Parameter Validation & Transformation System - Implementation Summary

Different AI models/providers have incompatible parameter requirements, causing a "whack-a-mole" issue where:

• Qwen3-32B: Requires reasoning_effort to be 'none' or 'default'
• OpenAI o1/o3: Accepts 'low', 'medium', 'high'
• GPT-OSS models: Don't support image_detail at all
• Vision models: Support image_detail parameter
• Other models: Don't support reasoning_effort at all

This caused API errors like:

`reasoning_effort` must be one of `none` or `default`
property 'image_detail' is unsupported

Added apiMapping to SelectParameter type for value translation:

export interface SelectParameter extends BaseParameter {
  type: 'select';
  options: Array<{ value: string; label: string }>;
  default?: string;
  apiMapping?: Record<string, string>; // NEW: Maps UI → API values
}

Added transformParameters function to ModelConfig:

export interface ModelConfig {
  // ... existing fields ...
  transformParameters?: (params: Record<string, unknown>) => Record<string, unknown>;
}

Created transformParametersForAPI() that:

• Applies apiMapping for select parameters
• Runs model-specific transformation functions
• Preserves unknown/unsupported parameters

transformParametersForAPI('qwen/qwen3-32b', {
  reasoningEffort: 'medium',  // UI value
  temperature: 0.7
});
// Returns: { reasoningEffort: 'default', temperature: 0.7 }

Created validateParameters() that:

• Checks required parameters
• Validates number ranges (min/max)
• Validates select options (with apiMapping support)
• Validates string/textarea lengths
• Validates boolean types

Returns array of human-readable error messages.

Updated groq.ts provider:

• Imports transformParametersForAPI
• Transforms parameters before building request body
• Applied to both complete() and stream() methods

const transformedParams = transformParametersForAPI(model, {
  reasoningEffort: options?.reasoningEffort,
  imageDetail: options?.imageDetail,
  webSearch: options?.webSearch,
  codeExecution: options?.codeExecution,
});

if (transformedParams.reasoningEffort && modelSupportsParameter(model, 'reasoningEffort')) {
  requestBody.reasoning_effort = transformedParams.reasoningEffort;
}

Updated jobs.ts to validate and transform parameters:

• Validates parameters before starting job
• Transforms parameters for model-specific requirements
• Returns clear error messages on validation failure

// Validate parameters
const validationErrors = validateParameters(model, paramsToValidate);
if (validationErrors.length > 0) {
  failJob(job, "Invalid parameters: " + validationErrors.join(", "));
  return;
}

// Transform parameters
const transformedParams = transformParametersForAPI(model, paramsToValidate);

Updated qwen/qwen3-32b model config with proper parameter mapping:

{
  id: 'qwen/qwen3-32b',
  name: 'Qwen3-32B',
  provider: 'groq',
  parameters: [
    // ... base parameters ...
    {
      key: 'reasoningEffort',
      label: 'Reasoning Effort',
      type: 'select',
      options: [
        { value: 'none', label: 'None' },
        { value: 'default', label: 'Default' }
      ],
      default: 'default',
      apiMapping: {
        'none': 'none',
        'default': 'default',
        // Backwards compatibility
        'low': 'none',
        'medium': 'default',
        'high': 'default'
      }
    },
    // ... other parameters ...
  ],
  capabilities: { thinking: true, streaming: true }
}

1. backend/providers/model-configs.ts

   • Added apiMapping to SelectParameter
   • Added transformParameters to ModelConfig
   • Added transformParametersForAPI() function
   • Added validateParameters() function
   • Updated Qwen model config with proper parameters

2. backend/providers/groq.ts

   • Import transformParametersForAPI
   • Apply transformation in complete() method
   • Apply transformation in stream() method

3. backend/routes/jobs.ts

   • Import validation and transformation functions
   • Validate parameters before job execution
   • Transform parameters before passing to provider
   • Return validation errors to client

1. backend/providers/PARAMETER-VALIDATION.md

   • Complete documentation of the system
   • Usage examples
   • Migration guide
   • Common patterns

2. backend/providers/test-parameter-validation.ts

   • Test suite demonstrating all features
   • Validation examples
   • Transformation examples
   • Run with: deno run backend/providers/test-parameter-validation.ts

Run the test suite:

cd /Users/janzheng/localhost/smallweb/design/v2/frontend/apps/chat-app
deno run backend/providers/test-parameter-validation.ts

Expected output:

• ✅ Parameter transformation works (medium → default)
• ✅ Validation catches invalid values
• ✅ Backwards compatibility maintained
• ✅ Range validation works
• ✅ All valid parameters pass validation

1. Single Source of Truth: Model requirements defined once in config
2. Backwards Compatible: Old parameter values automatically mapped
3. Type Safe: TypeScript validates at compile time
4. Clear Errors: Meaningful error messages for invalid parameters
5. Extensible: Easy to add new models with custom requirements
6. No Code Changes: Providers automatically use transformations
7. No Whack-a-Mole: Model-specific quirks handled declaratively

To add parameter mapping for other models:

1. Identify models with parameter requirements (check API docs)
2. Add apiMapping to relevant parameters in model-configs.ts
3. Test with test-parameter-validation.ts
4. Deploy - existing code automatically uses mappings

{
  id: 'new-model',
  name: 'New Model',
  provider: 'custom',
  parameters: [
    {
      key: 'creativityLevel',
      label: 'Creativity',
      type: 'select',
      options: [
        { value: 'conservative', label: 'Conservative' },
        { value: 'balanced', label: 'Balanced' },
        { value: 'experimental', label: 'Experimental' }
      ],
      default: 'balanced',
      // Map UI values to what API expects
      apiMapping: {
        'conservative': '1',
        'balanced': '2',
        'experimental': '3'
      }
    }
  ]
}

No other code changes needed - transformation happens automatically!