feat: Add comprehensive schema definitions for catalog system

- Introduced common types and validation utilities in common.types.ts
- Unified export of all schemas in index.ts for easier access
- Defined model configuration schemas including capabilities, pricing, and reasoning in model.schema.ts
- Created provider model override schemas to manage provider-specific configurations in override.schema.ts
- Established provider configuration schemas detailing metadata, capabilities, and behaviors in provider.schema.ts

packages/catalog/schemas/common.types.ts

@@ -0,0 +1,69 @@
+/**
+ * Common type definitions for the catalog system
+ * Shared across model, provider, and override schemas
+ */
+
+import * as z from 'zod'
+
+// Common string types for reuse
+export const ModelIdSchema = z.string()
+export const ProviderIdSchema = z.string()
+export const VersionSchema = z.string()
+
+// Currency codes
+export const CurrencySchema = z.enum(['USD', 'EUR', 'CNY', 'JPY', 'GBP'])
+
+// Common file size units
+export const FileSizeUnitSchema = z.enum(['B', 'KB', 'MB', 'GB'])
+
+// Common status types
+export const StatusSchema = z.enum(['active', 'inactive', 'deprecated', 'maintenance'])
+
+// Timestamp schema for date fields
+export const TimestampSchema = z.iso.datetime()
+
+// Range helper schemas
+export const NumericRangeSchema = z.object({
+  min: z.number(),
+  max: z.number()
+})
+
+export const StringRangeSchema = z.object({
+  min: z.string(),
+  max: z.string()
+})
+
+// Price per token schema
+export const PricePerTokenSchema = z.object({
+  perMillionTokens: z.number().nonnegative(),
+  currency: CurrencySchema.default('USD')
+})
+
+// Generic metadata schema
+export const MetadataSchema = z.record(z.string(), z.any()).optional()
+
+// Type exports
+export type ModelId = z.infer<typeof ModelIdSchema>
+export type ProviderId = z.infer<typeof ProviderIdSchema>
+export type Version = z.infer<typeof VersionSchema>
+export type Currency = z.infer<typeof CurrencySchema>
+export type FileSizeUnit = z.infer<typeof FileSizeUnitSchema>
+export type Status = z.infer<typeof StatusSchema>
+export type Timestamp = z.infer<typeof TimestampSchema>
+export type NumericRange = z.infer<typeof NumericRangeSchema>
+export type StringRange = z.infer<typeof StringRangeSchema>
+export type PricePerToken = z.infer<typeof PricePerTokenSchema>
+export type Metadata = z.infer<typeof MetadataSchema>
+
+// Common validation utilities
+export const validateRange = (min: number, max: number): boolean => {
+  return min <= max
+}
+
+export const validatePositiveNumber = (value: number): boolean => {
+  return value >= 0
+}
+
+export const validateNonEmptyString = (value: string): boolean => {
+  return value.trim().length > 0
+}

packages/catalog/schemas/index.ts

@@ -0,0 +1,49 @@
+/**
+ * Unified export of all catalog schemas and types
+ * This file provides a single entry point for all schema definitions
+ */
+
+// Export all schemas from common types
+export * from './common.types'
+
+// Export model schemas
+export * from './model.schema'
+
+// Export provider schemas
+export * from './provider.schema'
+
+// Export override schemas
+export * from './override.schema'
+
+// Re-export commonly used combined types for convenience
+export type {
+  Modality,
+  ModelCapabilityType,
+  ModelConfig,
+  ModelPricing,
+  ParameterSupport,
+  Reasoning
+} from './model.schema'
+export type {
+  OverrideResult,
+  OverrideValidation,
+  ProviderModelOverride
+} from './override.schema'
+export type {
+  Authentication,
+  EndpointType,
+  McpSupport,
+  PricingModel,
+  ProviderBehaviors,
+  ProviderConfig
+} from './provider.schema'
+
+// Export common types
+export type {
+  Currency,
+  Metadata,
+  ModelId,
+  ProviderId,
+  Timestamp,
+  Version
+} from './common.types'

packages/catalog/schemas/model.schema.ts

@@ -0,0 +1,254 @@
+/**
+ * Model configuration schema definitions
+ * Defines the structure for model metadata, capabilities, and configurations
+ */
+
+import * as z from 'zod'
+
+import {
+  CurrencySchema,
+  MetadataSchema,
+  ModelIdSchema,
+  PricePerTokenSchema,
+  TimestampSchema,
+  VersionSchema
+} from './common.types'
+
+// Modality types - supported input/output modalities
+export const ModalitySchema = z.enum(['TEXT', 'VISION', 'AUDIO', 'VIDEO', 'VECTOR'])
+
+// Model capability types
+export const ModelCapabilityTypeSchema = z.enum([
+  'FUNCTION_CALL', // Function calling
+  'REASONING', // Reasoning/thinking
+  'IMAGE_RECOGNITION', // Image recognition
+  'IMAGE_GENERATION', // Image generation
+  'AUDIO_RECOGNITION', // Audio recognition
+  'AUDIO_GENERATION', // Audio generation
+  'EMBEDDING', // Embedding vector generation
+  'RERANK', // Text reranking
+  'AUDIO_TRANSCRIPT', // Audio transcription
+  'VIDEO_RECOGNITION', // Video recognition
+  'VIDEO_GENERATION', // Video generation
+  'STRUCTURED_OUTPUT', // Structured output
+  'FILE_INPUT', // File input support
+  'WEB_SEARCH', // Built-in web search
+  'CODE_EXECUTION', // Code execution
+  'FILE_SEARCH', // File search
+  'COMPUTER_USE' // Computer use
+])
+
+// Reasoning configuration
+export const ReasoningSchema = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('openai-chat'),
+    params: z.object({
+      reasoning_effort: z.enum(['none', 'minimal', 'low', 'medium', 'high']).optional()
+    })
+  }),
+  z.object({
+    type: z.literal('openai-responses'),
+    params: z.object({
+      reasoning: z.object({
+        effort: z.enum(['none', 'minimal', 'low', 'medium', 'high']).optional(),
+        summary: z.enum(['auto', 'concise', 'detailed']).optional()
+      })
+    })
+  }),
+  z.object({
+    type: z.literal('anthropic'),
+    params: z.object({
+      type: z.union([z.literal('enabled'), z.literal('disabled')]),
+      budgetTokens: z.number().optional()
+    })
+  }),
+  z.object({
+    type: z.literal('gemini'),
+    params: z.union([
+      z
+        .object({
+          thinking_config: z.object({
+            include_thoughts: z.boolean().optional(),
+            thinking_budget: z.number().optional()
+          })
+        })
+        .optional(),
+      z
+        .object({
+          thinking_level: z.enum(['low', 'medium', 'high']).optional()
+        })
+        .optional()
+    ])
+  }),
+  z.object({
+    type: z.literal('openrouter'),
+    params: z.object({
+      reasoning: z
+        .object({
+          effort: z
+            .union([z.literal('none'), z.literal('minimal'), z.literal('low'), z.literal('medium'), z.literal('high')])
+            .optional(),
+          max_tokens: z.number().optional(),
+          exclude: z.boolean().optional()
+        })
+        .refine((v) => {
+          v.effort == null || v.max_tokens == null
+        }, 'One of the following (not both)')
+    })
+  }),
+  z.object({
+    type: z.literal('qwen'),
+    params: z.object({
+      enable_thinking: z.boolean(),
+      thinking_budget: z.number().optional()
+    })
+  }),
+  z.object({
+    type: z.literal('doubao'),
+    params: z.object({
+      thinking: z.object({
+        type: z.union([z.literal('enabled'), z.literal('disabled'), z.literal('auto')])
+      })
+    })
+  }),
+  z.object({
+    type: z.literal('dashscope'),
+    params: z.object({
+      enable_thinking: z.boolean(),
+      incremental_output: z.boolean().optional()
+    })
+  }),
+  z.object({
+    type: z.literal('self-hosted'),
+    params: z.object({
+      chat_template_kwargs: z.object({
+        enable_thinking: z.boolean().optional(),
+        thinking: z.boolean().optional()
+      })
+    })
+  })
+])
+
+// Parameter support configuration
+export const ParameterSupportSchema = z.object({
+  temperature: z
+    .object({
+      supported: z.boolean(),
+      min: z.number().min(0).max(2).optional(),
+      max: z.number().min(0).max(2).optional(),
+      default: z.number().min(0).max(2).optional()
+    })
+    .optional(),
+
+  topP: z
+    .object({
+      supported: z.boolean(),
+      min: z.number().min(0).max(1).optional(),
+      max: z.number().min(0).max(1).optional(),
+      default: z.number().min(0).max(1).optional()
+    })
+    .optional(),
+
+  topK: z
+    .object({
+      supported: z.boolean(),
+      min: z.number().positive().optional(),
+      max: z.number().positive().optional()
+    })
+    .optional(),
+
+  frequencyPenalty: z.boolean().optional(),
+  presencePenalty: z.boolean().optional(),
+  maxTokens: z.boolean().optional(),
+  stopSequences: z.boolean().optional(),
+  systemMessage: z.boolean().optional(),
+  developerRole: z.boolean().optional()
+})
+
+// Model pricing configuration
+export const ModelPricingSchema = z.object({
+  input: PricePerTokenSchema,
+  output: PricePerTokenSchema,
+
+  // Image pricing (optional)
+  perImage: z
+    .object({
+      price: z.number(),
+      currency: CurrencySchema.default('USD'),
+      unit: z.enum(['image', 'pixel']).optional()
+    })
+    .optional(),
+
+  // Audio/video pricing (optional)
+  perMinute: z
+    .object({
+      price: z.number(),
+      currency: CurrencySchema.default('USD')
+    })
+    .optional()
+})
+
+// Model configuration schema
+export const ModelConfigSchema = z.object({
+  // Basic information
+  id: ModelIdSchema,
+  name: z.string().optional(),
+  ownedBy: z.string().optional(),
+  description: z.string().optional(),
+
+  // Capabilities (core)
+  capabilities: z.array(ModelCapabilityTypeSchema),
+
+  // Modalities
+  inputModalities: z.array(ModalitySchema),
+  outputModalities: z.array(ModalitySchema),
+
+  // Limits
+  contextWindow: z.number(),
+  maxOutputTokens: z.number(),
+  maxInputTokens: z.number().optional(),
+
+  // Pricing
+  pricing: ModelPricingSchema.optional(),
+
+  // Reasoning configuration
+  reasoning: ReasoningSchema.optional(),
+
+  // Parameter support
+  parameters: ParameterSupportSchema.optional(),
+
+  // Endpoint types (will reference provider schema)
+  endpointTypes: z.array(z.string()).optional(),
+
+  // Metadata
+  releaseDate: TimestampSchema.optional(),
+  deprecationDate: TimestampSchema.optional(),
+  replacedBy: ModelIdSchema.optional(),
+
+  // Version control
+  version: VersionSchema.optional(),
+  compatibility: z
+    .object({
+      minVersion: VersionSchema.optional(),
+      maxVersion: VersionSchema.optional()
+    })
+    .optional(),
+
+  // Additional metadata
+  metadata: MetadataSchema
+})
+
+// Model list container schema for JSON files
+export const ModelListSchema = z.object({
+  version: VersionSchema,
+  models: z.array(ModelConfigSchema)
+})
+
+// Type exports
+export type Modality = z.infer<typeof ModalitySchema>
+export type ModelCapabilityType = z.infer<typeof ModelCapabilityTypeSchema>
+export type Reasoning = z.infer<typeof ReasoningSchema>
+export type ParameterSupport = z.infer<typeof ParameterSupportSchema>
+export type ModelPricing = z.infer<typeof ModelPricingSchema>
+export type ModelConfig = z.infer<typeof ModelConfigSchema>
+export type ModelList = z.infer<typeof ModelListSchema>

packages/catalog/schemas/override.schema.ts

@@ -0,0 +1,147 @@
+/**
+ * Provider model override schema definitions
+ * Defines how providers can override specific model configurations
+ */
+
+import * as z from 'zod'
+
+import { MetadataSchema, ModelIdSchema, ProviderIdSchema, VersionSchema } from './common.types'
+import { ModelCapabilityTypeSchema, ModelPricingSchema, ParameterSupportSchema, ReasoningSchema } from './model.schema'
+import { EndpointTypeSchema } from './provider.schema'
+
+// Capability override operations
+export const CapabilityOverrideSchema = z.object({
+  add: z.array(ModelCapabilityTypeSchema).optional(), // Add capabilities
+  remove: z.array(ModelCapabilityTypeSchema).optional(), // Remove capabilities
+  force: z.array(ModelCapabilityTypeSchema).optional() // Force set capabilities (ignore base config)
+})
+
+// Limits override configuration
+export const LimitsOverrideSchema = z.object({
+  contextWindow: z.number().optional(),
+  maxOutputTokens: z.number().optional(),
+  maxInputTokens: z.number().optional()
+})
+
+// Pricing override configuration
+export const PricingOverrideSchema = ModelPricingSchema.partial().optional()
+
+// Endpoint types override
+export const EndpointTypesOverrideSchema = z.array(EndpointTypeSchema).optional()
+
+// Reasoning configuration override - allows partial override of reasoning configs
+export const ReasoningOverrideSchema = ReasoningSchema.optional()
+
+// Parameter support override
+export const ParameterSupportOverrideSchema = ParameterSupportSchema.partial().optional()
+
+// Model metadata override
+export const MetadataOverrideSchema = z
+  .object({
+    name: z.string().optional(),
+    description: z.string().optional(),
+    deprecationDate: z.iso.datetime().optional(),
+    replacedBy: ModelIdSchema.optional(),
+    metadata: MetadataSchema
+  })
+  .optional()
+
+// Main provider model override schema
+export const ProviderModelOverrideSchema = z.object({
+  // Identification
+  providerId: ProviderIdSchema,
+  modelId: ModelIdSchema,
+
+  // Capability overrides
+  capabilities: CapabilityOverrideSchema.optional(),
+
+  // Limits overrides
+  limits: LimitsOverrideSchema.optional(),
+
+  // Pricing overrides
+  pricing: PricingOverrideSchema,
+
+  // Reasoning configuration overrides
+  reasoning: ReasoningOverrideSchema.optional(),
+
+  // Parameter support overrides
+  parameters: ParameterSupportOverrideSchema.optional(),
+
+  // Endpoint type overrides
+  endpointTypes: EndpointTypesOverrideSchema.optional(),
+
+  // Model metadata overrides
+  metadata: MetadataOverrideSchema.optional(),
+
+  // Status overrides
+  disabled: z.boolean().optional(), // Disable this model for this provider
+  replaceWith: ModelIdSchema.optional(), // Replace with alternative model
+
+  // Override tracking
+  reason: z.string().optional(), // Reason for override
+  lastUpdated: z.iso.datetime().optional(),
+  updatedBy: z.string().optional(), // Who made the override
+
+  // Override priority (higher number = higher priority)
+  priority: z.number().default(0),
+
+  // Override conditions
+  conditions: z
+    .object({
+      // Apply override only for specific regions
+      regions: z.array(z.string()).optional(),
+
+      // Apply override only for specific user tiers
+      userTiers: z.array(z.string()).optional(),
+
+      // Apply override only in specific environments
+      environments: z.array(z.enum(['development', 'staging', 'production'])).optional(),
+
+      // Time-based conditions
+      validFrom: z.iso.datetime().optional(),
+      validUntil: z.iso.datetime().optional()
+    })
+    .optional(),
+
+  // Additional override metadata
+  overrideMetadata: MetadataSchema.optional()
+})
+
+// Override container schema for JSON files
+export const OverrideListSchema = z.object({
+  version: VersionSchema,
+  overrides: z.array(ProviderModelOverrideSchema)
+})
+
+// Override application result schema
+export const OverrideResultSchema = z.object({
+  modelId: ModelIdSchema,
+  providerId: ProviderIdSchema,
+  applied: z.boolean(),
+  appliedOverrides: z.array(z.string()), // List of applied override fields
+  originalValues: z.record(z.string(), z.unknown()), // Original values before override
+  newValues: z.record(z.string(), z.unknown()), // New values after override
+  overrideReason: z.string().optional(),
+  appliedAt: z.iso.datetime().optional()
+})
+
+// Override validation result
+export const OverrideValidationSchema = z.object({
+  valid: z.boolean(),
+  errors: z.array(z.string()),
+  warnings: z.array(z.string()),
+  recommendations: z.array(z.string())
+})
+
+// Type exports
+export type CapabilityOverride = z.infer<typeof CapabilityOverrideSchema>
+export type LimitsOverride = z.infer<typeof LimitsOverrideSchema>
+export type PricingOverride = z.infer<typeof PricingOverrideSchema>
+export type EndpointTypesOverride = z.infer<typeof EndpointTypesOverrideSchema>
+export type ReasoningOverride = z.infer<typeof ReasoningOverrideSchema>
+export type ParameterSupportOverride = z.infer<typeof ParameterSupportOverrideSchema>
+export type MetadataOverride = z.infer<typeof MetadataOverrideSchema>
+export type ProviderModelOverride = z.infer<typeof ProviderModelOverrideSchema>
+export type OverrideList = z.infer<typeof OverrideListSchema>
+export type OverrideResult = z.infer<typeof OverrideResultSchema>
+export type OverrideValidation = z.infer<typeof OverrideValidationSchema>

packages/catalog/schemas/provider.schema.ts

@@ -0,0 +1,171 @@
+/**
+ * Provider configuration schema definitions
+ * Defines the structure for AI service provider metadata and capabilities
+ */
+
+import * as z from 'zod'
+
+import { MetadataSchema, ProviderIdSchema, VersionSchema } from './common.types'
+
+// Endpoint types supported by providers
+export const EndpointTypeSchema = z.enum([
+  'CHAT_COMPLETIONS', // /chat/completions
+  'COMPLETIONS', // /completions
+  'EMBEDDINGS', // /embeddings
+  'IMAGE_GENERATION', // /images/generations
+  'IMAGE_EDIT', // /images/edits
+  'AUDIO_SPEECH', // /audio/speech (TTS)
+  'AUDIO_TRANSCRIPTIONS', // /audio/transcriptions (STT)
+  'MESSAGES', // /messages
+  'RESPONSES', // /responses
+  'GENERATE_CONTENT', // :generateContent
+  'STREAM_GENERATE_CONTENT', // :streamGenerateContent
+  'RERANK', // /rerank
+  'MODERATIONS' // /moderations
+])
+
+// Authentication methods
+export const AuthenticationSchema = z.enum([
+  'API_KEY', // Standard API Key authentication
+  'OAUTH', // OAuth 2.0 authentication
+  'CLOUD_CREDENTIALS' // Cloud service credentials (AWS, GCP, Azure)
+])
+
+// Pricing models that affect UI and behavior
+export const PricingModelSchema = z.enum([
+  'UNIFIED', // Unified pricing (like OpenRouter)
+  'PER_MODEL', // Per-model independent pricing (like OpenAI official)
+  'TRANSPARENT', // Transparent pricing (like New-API)
+  'USAGE_BASED', // Dynamic usage-based pricing
+  'SUBSCRIPTION' // Subscription-based pricing
+])
+
+// Model routing strategies affecting performance and reliability
+export const ModelRoutingSchema = z.enum([
+  'INTELLIGENT', // Intelligent routing, auto-select optimal instance
+  'DIRECT', // Direct routing to specified model
+  'LOAD_BALANCED', // Load balanced across multiple instances
+  'GEO_ROUTED', // Geographic location routing
+  'COST_OPTIMIZED' // Cost-optimized routing
+])
+
+// Server-side MCP support configuration
+export const McpSupportSchema = z.object({
+  supported: z.boolean().default(false),
+  configuration: z
+    .object({
+      supportsUrlPassThrough: z.boolean().default(false),
+      supportedServers: z.array(z.string()).optional(),
+      maxConcurrentServers: z.number().optional()
+    })
+    .optional()
+})
+
+// API compatibility configuration
+export const ApiCompatibilitySchema = z.object({
+  supportsArrayContent: z.boolean().default(true),
+  supportsStreamOptions: z.boolean().default(true),
+  supportsDeveloperRole: z.boolean().default(false),
+  supportsServiceTier: z.boolean().default(false),
+  supportsThinkingControl: z.boolean().default(false),
+  supportsApiVersion: z.boolean().default(false),
+  supportsParallelTools: z.boolean().default(false),
+  supportsMultimodal: z.boolean().default(false),
+  maxFileUploadSize: z.number().optional(), // bytes
+  supportedFileTypes: z.array(z.string()).optional()
+})
+
+// Behavior characteristics configuration - replaces categorization, describes actual behavior
+export const ProviderBehaviorsSchema = z.object({
+  // Model management
+  supportsCustomModels: z.boolean().default(false), // Supports user custom models
+  providesModelMapping: z.boolean().default(false), // Provides model name mapping
+  supportsModelVersioning: z.boolean().default(false), // Supports model version control
+
+  // Reliability and fault tolerance
+  providesFallbackRouting: z.boolean().default(false), // Provides fallback routing
+  hasAutoRetry: z.boolean().default(false), // Has automatic retry mechanism
+  supportsHealthCheck: z.boolean().default(false), // Supports health checks
+
+  // Monitoring and metrics
+  hasRealTimeMetrics: z.boolean().default(false), // Has real-time metrics
+  providesUsageAnalytics: z.boolean().default(false), // Provides usage analytics
+  supportsWebhookEvents: z.boolean().default(false), // Supports webhook events
+
+  // Configuration and management
+  requiresApiKeyValidation: z.boolean().default(true), // Requires API key validation
+  supportsRateLimiting: z.boolean().default(false), // Supports rate limiting
+  providesUsageLimits: z.boolean().default(false), // Provides usage limit configuration
+
+  // Advanced features
+  supportsStreaming: z.boolean().default(true), // Supports streaming responses
+  supportsBatchProcessing: z.boolean().default(false), // Supports batch processing
+  providesModelFineTuning: z.boolean().default(false) // Provides model fine-tuning
+})
+
+// Provider configuration schema
+export const ProviderConfigSchema = z.object({
+  // Basic information
+  id: ProviderIdSchema,
+  name: z.string(),
+  description: z.string().optional(),
+
+  // Behavior-related configuration
+  authentication: AuthenticationSchema,
+  pricingModel: PricingModelSchema,
+  modelRouting: ModelRoutingSchema,
+  behaviors: ProviderBehaviorsSchema,
+
+  // Feature support
+  supportedEndpoints: z.array(EndpointTypeSchema),
+  mcpSupport: McpSupportSchema.optional(),
+  apiCompatibility: ApiCompatibilitySchema.optional(),
+
+  // Default configuration
+  defaultApiHost: z.string().optional(),
+  defaultRateLimit: z.number().optional(), // requests per minute
+
+  // Model matching assistance
+  modelIdPatterns: z.array(z.string()).optional(),
+  aliasModelIds: z.record(z.string(), z.string()).optional(), // Model alias mapping
+
+  // Special configuration
+  specialConfig: MetadataSchema,
+
+  // Metadata and links
+  documentation: z.string().url().optional(),
+  statusPage: z.string().url().optional(),
+  pricingPage: z.string().url().optional(),
+  supportEmail: z.string().email().optional(),
+  website: z.string().url().optional(),
+
+  // Status management
+  deprecated: z.boolean().default(false),
+  deprecationDate: z.iso.datetime().optional(),
+  maintenanceMode: z.boolean().default(false),
+
+  // Version and compatibility
+  minAppVersion: VersionSchema.optional(), // Minimum supported app version
+  maxAppVersion: VersionSchema.optional(), // Maximum supported app version
+  configVersion: VersionSchema.default('1.0.0'), // Configuration file version
+
+  // Additional metadata
+  metadata: MetadataSchema
+})
+
+// Provider list container schema for JSON files
+export const ProviderListSchema = z.object({
+  version: VersionSchema,
+  providers: z.array(ProviderConfigSchema)
+})
+
+// Type exports
+export type EndpointType = z.infer<typeof EndpointTypeSchema>
+export type Authentication = z.infer<typeof AuthenticationSchema>
+export type PricingModel = z.infer<typeof PricingModelSchema>
+export type ModelRouting = z.infer<typeof ModelRoutingSchema>
+export type McpSupport = z.infer<typeof McpSupportSchema>
+export type ApiCompatibility = z.infer<typeof ApiCompatibilitySchema>
+export type ProviderBehaviors = z.infer<typeof ProviderBehaviorsSchema>
+export type ProviderConfig = z.infer<typeof ProviderConfigSchema>
+export type ProviderList = z.infer<typeof ProviderListSchema>