@geenius/ai 0.1.0

package/packages/shared/src/__tests__/ai.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from 'vitest'
+import {
+  BUILT_IN_TEMPLATES, buildContentPrompt, buildActionSystemPrompt,
+  DEFAULT_MEMORY_CONFIG, buildMemoryContext, extractPreferenceHints,
+  BUILT_IN_SKILLS, createSkillRegistry, buildSkillPrompt,
+} from '../index'
+
+describe('AI Templates', () => {
+  it('BUILT_IN_TEMPLATES is a non-empty array', () => {
+    expect(Array.isArray(BUILT_IN_TEMPLATES)).toBe(true)
+    expect(BUILT_IN_TEMPLATES.length).toBeGreaterThan(0)
+  })
+
+  it('buildContentPrompt returns system and user prompt', () => {
+    const template = BUILT_IN_TEMPLATES[0]
+    const result = buildContentPrompt(template, { text: 'Hello world' })
+    expect(typeof result).toBe('object')
+    expect(typeof result.systemPrompt).toBe('string')
+    expect(typeof result.userPrompt).toBe('string')
+  })
+
+  it('buildActionSystemPrompt returns a system prompt', () => {
+    const prompt = buildActionSystemPrompt('summarize')
+    expect(typeof prompt).toBe('string')
+    expect(prompt.length).toBeGreaterThan(0)
+  })
+})
+
+describe('AI Memory', () => {
+  it('DEFAULT_MEMORY_CONFIG is defined', () => {
+    expect(DEFAULT_MEMORY_CONFIG).toBeDefined()
+    expect(typeof DEFAULT_MEMORY_CONFIG).toBe('object')
+  })
+
+  it('buildMemoryContext returns string from entries', () => {
+    const ctx = buildMemoryContext([])
+    expect(typeof ctx).toBe('string')
+  })
+
+  it('extractPreferenceHints extracts from text', () => {
+    const hints = extractPreferenceHints('I prefer dark mode and concise responses.')
+    expect(typeof hints).toBe('object')
+  })
+})
+
+describe('AI Skills', () => {
+  it('BUILT_IN_SKILLS is a non-empty array', () => {
+    expect(Array.isArray(BUILT_IN_SKILLS)).toBe(true)
+    expect(BUILT_IN_SKILLS.length).toBeGreaterThan(0)
+  })
+
+  it('createSkillRegistry returns a registry', () => {
+    const registry = createSkillRegistry()
+    expect(registry).toBeDefined()
+    expect(typeof registry.register).toBe('function')
+    expect(typeof registry.get).toBe('function')
+    expect(typeof registry.list).toBe('function')
+  })
+
+  it('buildSkillPrompt produces system and user prompts', () => {
+    const skill = Object.values(BUILT_IN_SKILLS)[0]
+    const result = buildSkillPrompt(skill, {})
+    expect(typeof result).toBe('object')
+    expect(typeof result.systemPrompt).toBe('string')
+    expect(typeof result.userPrompt).toBe('string')
+  })
+})

package/packages/shared/src/ai-client.ts

@@ -0,0 +1,243 @@
+// @geenius/ai — TanStack AI Evaluation Wrapper
+// Multi-provider AI hook for React with streaming support.
+
+/**
+ * Unified AI provider abstraction.
+ * When TanStack AI reaches beta, this can wrap @tanstack/react-ai.
+ * Until then, provides a consistent interface across providers.
+ */
+
+export type AIProvider = 'openai' | 'anthropic' | 'gemini' | 'ollama' | 'custom'
+
+/** Lightweight per-request client config. For the full SDK config object, see AIConfig in types.ts. */
+export interface AIClientConfig {
+  provider: AIProvider
+  apiKey?: string
+  baseUrl?: string
+  model?: string
+  defaultTemperature?: number
+  defaultMaxTokens?: number
+}
+/** @deprecated Use AIClientConfig — renamed to avoid collision with types.ts AIConfig */
+export type AIConfig = AIClientConfig
+
+export interface AIClientMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool'
+  content: string
+  toolCalls?: ToolCall[]
+  toolCallId?: string
+}
+
+export interface ToolCall {
+  id: string
+  name: string
+  arguments: Record<string, unknown>
+}
+
+export interface ToolDefinition {
+  name: string
+  description: string
+  parameters: Record<string, unknown>
+  handler?: (args: Record<string, unknown>) => Promise<unknown>
+}
+
+export interface StreamCallbacks {
+  onToken?: (token: string) => void
+  onThinking?: (thinking: string) => void
+  onToolCall?: (toolCall: ToolCall) => Promise<unknown>
+  onComplete?: (response: AIResponse) => void
+  onError?: (error: Error) => void
+}
+
+export interface AIResponse {
+  content: string
+  model: string
+  provider: AIProvider
+  usage?: { promptTokens: number; completionTokens: number; totalTokens: number }
+  toolCalls?: ToolCall[]
+  thinking?: string
+  finishReason: 'stop' | 'length' | 'tool_calls' | 'error'
+}
+
+// ─── Provider Resolution ──────────────────────────────────────
+
+const PROVIDER_ENDPOINTS: Record<AIProvider, string> = {
+  openai: 'https://api.openai.com/v1/chat/completions',
+  anthropic: 'https://api.anthropic.com/v1/messages',
+  gemini: 'https://generativelanguage.googleapis.com/v1beta/models',
+  ollama: 'http://localhost:11434/api/chat',
+  custom: '',
+}
+
+const DEFAULT_MODELS: Record<AIProvider, string> = {
+  openai: 'gpt-4o',
+  anthropic: 'claude-sonnet-4-20250514',
+  gemini: 'gemini-2.0-flash',
+  ollama: 'llama3.1',
+  custom: '',
+}
+
+/**
+ * Resolve the provider from environment variables.
+ */
+export function resolveAIProvider(): AIClientConfig {
+  let provider: AIProvider = 'openai'
+  let apiKey = ''
+
+  try {
+    // @ts-expect-error — Vite env
+    const envProvider = import.meta?.env?.VITE_AI_PROVIDER ?? process?.env?.AI_PROVIDER ?? 'openai'
+    provider = envProvider as AIProvider
+    // @ts-expect-error — Vite env
+    apiKey = import.meta?.env?.VITE_AI_API_KEY ?? process?.env?.AI_API_KEY ?? ''
+  } catch {
+    // Fallback
+  }
+
+  return {
+    provider,
+    apiKey,
+    model: DEFAULT_MODELS[provider],
+    defaultTemperature: 0.7,
+    defaultMaxTokens: 4096,
+  }
+}
+
+// ─── Chat Client ──────────────────────────────────────────────
+
+export class AIClient {
+  private config: AIClientConfig
+
+  constructor(config?: Partial<AIClientConfig>) {
+    this.config = { ...resolveAIProvider(), ...config }
+  }
+
+  /**
+   * Send a chat completion request.
+   */
+  async chat(
+    messages: AIClientMessage[],
+    opts?: {
+      model?: string
+      temperature?: number
+      maxTokens?: number
+      tools?: ToolDefinition[]
+      stream?: boolean
+      callbacks?: StreamCallbacks
+    }
+  ): Promise<AIResponse> {
+    const model = opts?.model ?? this.config.model ?? DEFAULT_MODELS[this.config.provider]
+    const endpoint = this.config.baseUrl ?? PROVIDER_ENDPOINTS[this.config.provider]
+
+    try {
+      // Format request based on provider
+      const body = this.formatRequest(messages, model, opts)
+
+      const response = await fetch(endpoint, {
+        method: 'POST',
+        headers: this.getHeaders(),
+        body: JSON.stringify(body),
+      })
+
+      if (!response.ok) {
+        const err = await response.json().catch(() => ({ error: response.statusText }))
+        throw new Error(`AI request failed: ${err.error?.message ?? err.error ?? response.statusText}`)
+      }
+
+      const data = await response.json()
+      const result = this.parseResponse(data)
+
+      // Handle tool calls
+      if (result.toolCalls?.length && opts?.callbacks?.onToolCall) {
+        for (const tc of result.toolCalls) {
+          const toolResult = await opts.callbacks.onToolCall(tc)
+          // Could recursively call with tool results
+          opts.callbacks.onComplete?.(result)
+        }
+      }
+
+      opts?.callbacks?.onComplete?.(result)
+      return result
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err))
+      opts?.callbacks?.onError?.(error)
+      throw error
+    }
+  }
+
+  private formatRequest(messages: AIClientMessage[], model: string, opts?: { temperature?: number; maxTokens?: number; tools?: ToolDefinition[] }) {
+    // OpenAI / Gemini compatible format
+    return {
+      model,
+      messages: messages.map(m => ({ role: m.role, content: m.content })),
+      temperature: opts?.temperature ?? this.config.defaultTemperature,
+      max_tokens: opts?.maxTokens ?? this.config.defaultMaxTokens,
+      ...(opts?.tools?.length ? {
+        tools: opts.tools.map(t => ({
+          type: 'function',
+          function: { name: t.name, description: t.description, parameters: t.parameters },
+        })),
+      } : {}),
+    }
+  }
+
+  private getHeaders(): Record<string, string> {
+    const headers: Record<string, string> = { 'Content-Type': 'application/json' }
+    if (this.config.apiKey) {
+      if (this.config.provider === 'anthropic') {
+        headers['x-api-key'] = this.config.apiKey
+        headers['anthropic-version'] = '2023-06-01'
+      } else {
+        headers['Authorization'] = `Bearer ${this.config.apiKey}`
+      }
+    }
+    return headers
+  }
+
+  private parseResponse(data: any): AIResponse {
+    // OpenAI format
+    if (data.choices) {
+      const choice = data.choices[0]
+      return {
+        content: choice.message?.content ?? '',
+        model: data.model,
+        provider: this.config.provider,
+        usage: data.usage ? {
+          promptTokens: data.usage.prompt_tokens,
+          completionTokens: data.usage.completion_tokens,
+          totalTokens: data.usage.total_tokens,
+        } : undefined,
+        toolCalls: choice.message?.tool_calls?.map((tc: any) => ({
+          id: tc.id, name: tc.function.name, arguments: JSON.parse(tc.function.arguments),
+        })),
+        finishReason: choice.finish_reason === 'tool_calls' ? 'tool_calls' : choice.finish_reason === 'length' ? 'length' : 'stop',
+      }
+    }
+    // Anthropic format
+    if (data.content) {
+      const text = data.content.filter((c: any) => c.type === 'text').map((c: any) => c.text).join('')
+      return {
+        content: text,
+        model: data.model,
+        provider: this.config.provider,
+        usage: data.usage ? {
+          promptTokens: data.usage.input_tokens,
+          completionTokens: data.usage.output_tokens,
+          totalTokens: data.usage.input_tokens + data.usage.output_tokens,
+        } : undefined,
+        finishReason: data.stop_reason === 'tool_use' ? 'tool_calls' : 'stop',
+      }
+    }
+    return { content: JSON.stringify(data), model: '', provider: this.config.provider, finishReason: 'stop' }
+  }
+}
+
+// ─── Provider Switching ───────────────────────────────────────
+
+/**
+ * Create an AI client from environment configuration.
+ * Supports switching providers without code changes.
+ */
+export function createAI(overrides?: Partial<AIClientConfig>): AIClient {
+  return new AIClient(overrides)
+}

package/packages/shared/src/config.ts

@@ -0,0 +1,235 @@
+// @geenius-ai/shared — src/config.ts
+
+import type { AIConfig, AIProviderType, AIProviderConfig, AIModel } from './types'
+
+// ============================================================================
+// Default Provider Configs
+// ============================================================================
+
+const OPENAI_PROVIDER: AIProviderConfig = {
+    name: 'OpenAI',
+    type: 'openai',
+    baseUrl: 'https://api.openai.com/v1',
+    apiKeyEnvVar: 'OPENAI_API_KEY',
+    isActive: true,
+    models: ['gpt-4o', 'gpt-4o-mini', 'gpt-4-turbo', 'gpt-3.5-turbo', 'dall-e-3', 'tts-1', 'tts-1-hd', 'whisper-1', 'text-embedding-3-small', 'text-embedding-3-large'],
+    defaultModel: 'gpt-4o',
+}
+
+const ANTHROPIC_PROVIDER: AIProviderConfig = {
+    name: 'Anthropic',
+    type: 'anthropic',
+    baseUrl: 'https://api.anthropic.com/v1',
+    apiKeyEnvVar: 'ANTHROPIC_API_KEY',
+    isActive: true,
+    models: ['claude-3.5-sonnet', 'claude-3-haiku', 'claude-3-opus'],
+    defaultModel: 'claude-3.5-sonnet',
+}
+
+const NVIDIA_PROVIDER: AIProviderConfig = {
+    name: 'NVIDIA NIM',
+    type: 'nvidia',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    apiKeyEnvVar: 'NVIDIA_API_KEY',
+    isActive: true,
+    models: ['meta/llama-3.1-70b-instruct', 'meta/llama-3.1-8b-instruct', 'nvidia/llama-3.1-nemotron-70b-instruct', 'stabilityai/stable-diffusion-xl-base-1.0'],
+    defaultModel: 'meta/llama-3.1-70b-instruct',
+}
+
+const GOOGLE_PROVIDER: AIProviderConfig = {
+    name: 'Google AI',
+    type: 'google',
+    baseUrl: 'https://generativelanguage.googleapis.com/v1beta',
+    apiKeyEnvVar: 'GOOGLE_AI_API_KEY',
+    isActive: true,
+    models: ['gemini-pro', 'gemini-flash', 'gemini-1.5-pro', 'text-embedding-004'],
+    defaultModel: 'gemini-pro',
+}
+
+const OLLAMA_PROVIDER: AIProviderConfig = {
+    name: 'Ollama',
+    type: 'ollama',
+    baseUrl: 'http://localhost:11434/v1',
+    apiKeyEnvVar: 'OLLAMA_API_KEY',
+    isActive: false,
+    models: ['llama3.2:3b', 'qwen2.5:7b', 'mistral:7b'],
+    defaultModel: 'llama3.2:3b',
+}
+
+const GROQ_PROVIDER: AIProviderConfig = {
+    name: 'Groq',
+    type: 'groq',
+    baseUrl: 'https://api.groq.com/openai/v1',
+    apiKeyEnvVar: 'GROQ_API_KEY',
+    isActive: true,
+    models: ['llama-3.1-70b-versatile', 'mixtral-8x7b-32768', 'whisper-large-v3'],
+    defaultModel: 'llama-3.1-70b-versatile',
+}
+
+const ELEVENLABS_PROVIDER: AIProviderConfig = {
+    name: 'ElevenLabs',
+    type: 'elevenlabs',
+    baseUrl: 'https://api.elevenlabs.io',
+    apiKeyEnvVar: 'ELEVENLABS_API_KEY',
+    isActive: true,
+    models: ['eleven_multilingual_v2', 'eleven_turbo_v2_5', 'eleven_english_sts_v2'],
+    defaultModel: 'eleven_multilingual_v2',
+}
+
+const REPLICATE_PROVIDER: AIProviderConfig = {
+    name: 'Replicate',
+    type: 'replicate',
+    baseUrl: 'https://api.replicate.com',
+    apiKeyEnvVar: 'REPLICATE_API_KEY',
+    isActive: true,
+    models: ['stability-ai/sdxl', 'minimax/video-01', 'meta/musicgen', 'black-forest-labs/flux-1.1-pro'],
+    defaultModel: 'stability-ai/sdxl',
+}
+
+const FAL_PROVIDER: AIProviderConfig = {
+    name: 'Fal.ai',
+    type: 'fal',
+    baseUrl: 'https://queue.fal.run',
+    apiKeyEnvVar: 'FAL_API_KEY',
+    isActive: true,
+    models: ['fal-ai/flux/dev', 'fal-ai/kling-video/v2/master', 'fal-ai/stable-audio'],
+    defaultModel: 'fal-ai/flux/dev',
+}
+
+export const DEFAULT_PROVIDERS: AIProviderConfig[] = [
+    OPENAI_PROVIDER,
+    ANTHROPIC_PROVIDER,
+    NVIDIA_PROVIDER,
+    GOOGLE_PROVIDER,
+    GROQ_PROVIDER,
+    ELEVENLABS_PROVIDER,
+    REPLICATE_PROVIDER,
+    FAL_PROVIDER,
+    OLLAMA_PROVIDER,
+]
+
+// ============================================================================
+// Default Model Cost Registry
+// ============================================================================
+
+export const DEFAULT_MODELS: AIModel[] = [
+    // --- Text models ---
+    { id: 'gpt-4o', provider: 'openai', name: 'GPT-4o', capabilities: ['text', 'vision', 'function-calling', 'streaming', 'structured-output'], inputCostPer1k: 0.005, outputCostPer1k: 0.015, contextWindow: 128000, isActive: true },
+    { id: 'gpt-4o-mini', provider: 'openai', name: 'GPT-4o Mini', capabilities: ['text', 'vision', 'function-calling', 'streaming', 'structured-output'], inputCostPer1k: 0.00015, outputCostPer1k: 0.0006, contextWindow: 128000, isActive: true },
+    { id: 'claude-3.5-sonnet', provider: 'anthropic', name: 'Claude 3.5 Sonnet', capabilities: ['text', 'vision', 'function-calling', 'streaming'], inputCostPer1k: 0.003, outputCostPer1k: 0.015, contextWindow: 200000, isActive: true },
+    { id: 'claude-3-haiku', provider: 'anthropic', name: 'Claude 3 Haiku', capabilities: ['text', 'vision', 'streaming'], inputCostPer1k: 0.00025, outputCostPer1k: 0.00125, contextWindow: 200000, isActive: true },
+    { id: 'gemini-pro', provider: 'google', name: 'Gemini Pro', capabilities: ['text', 'vision', 'streaming'], inputCostPer1k: 0.00125, outputCostPer1k: 0.005, contextWindow: 2000000, isActive: true },
+    { id: 'gemini-flash', provider: 'google', name: 'Gemini Flash', capabilities: ['text', 'vision', 'streaming'], inputCostPer1k: 0.000075, outputCostPer1k: 0.0003, contextWindow: 1000000, isActive: true },
+    { id: 'meta/llama-3.1-70b-instruct', provider: 'nvidia', name: 'Llama 3.1 70B', capabilities: ['text', 'streaming'], inputCostPer1k: 0.00035, outputCostPer1k: 0.0004, contextWindow: 128000, isActive: true },
+    { id: 'llama-3.1-70b-versatile', provider: 'groq', name: 'Llama 3.1 70B (Groq)', capabilities: ['text', 'streaming'], inputCostPer1k: 0.00059, outputCostPer1k: 0.00079, contextWindow: 128000, isActive: true },
+
+    // --- Image models ---
+    { id: 'dall-e-3', provider: 'openai', name: 'DALL-E 3', capabilities: ['image-generation'], inputCostPer1k: 0, outputCostPer1k: 0, costPerCall: 0.04, isActive: true },
+    { id: 'stabilityai/stable-diffusion-xl-base-1.0', provider: 'nvidia', name: 'SDXL (NVIDIA)', capabilities: ['image-generation'], inputCostPer1k: 0, outputCostPer1k: 0, costPerCall: 0.002, isActive: true },
+    { id: 'stability-ai/sdxl', provider: 'replicate', name: 'SDXL (Replicate)', capabilities: ['image-generation'], inputCostPer1k: 0, outputCostPer1k: 0, costPerCall: 0.003, isActive: true },
+    { id: 'black-forest-labs/flux-1.1-pro', provider: 'replicate', name: 'Flux 1.1 Pro', capabilities: ['image-generation'], inputCostPer1k: 0, outputCostPer1k: 0, costPerCall: 0.04, isActive: true },
+    { id: 'fal-ai/flux/dev', provider: 'fal', name: 'Flux Dev (Fal)', capabilities: ['image-generation'], inputCostPer1k: 0, outputCostPer1k: 0, costPerCall: 0.025, isActive: true },
+
+    // --- Audio / TTS models ---
+    { id: 'tts-1', provider: 'openai', name: 'OpenAI TTS', capabilities: ['text-to-speech'], inputCostPer1k: 0.015, outputCostPer1k: 0, isActive: true },
+    { id: 'tts-1-hd', provider: 'openai', name: 'OpenAI TTS HD', capabilities: ['text-to-speech'], inputCostPer1k: 0.030, outputCostPer1k: 0, isActive: true },
+    { id: 'eleven_multilingual_v2', provider: 'elevenlabs', name: 'ElevenLabs Multilingual v2', capabilities: ['text-to-speech', 'voice-cloning'], inputCostPer1k: 0, outputCostPer1k: 0, costPerCall: 0.0003, isActive: true },
+    { id: 'eleven_turbo_v2_5', provider: 'elevenlabs', name: 'ElevenLabs Turbo v2.5', capabilities: ['text-to-speech'], inputCostPer1k: 0, outputCostPer1k: 0, costPerCall: 0.0002, isActive: true },
+
+    // --- Transcription / ASR models ---
+    { id: 'whisper-1', provider: 'openai', name: 'Whisper', capabilities: ['speech-to-text'], inputCostPer1k: 0.006, outputCostPer1k: 0, isActive: true },
+    { id: 'whisper-large-v3', provider: 'groq', name: 'Whisper v3 (Groq)', capabilities: ['speech-to-text'], inputCostPer1k: 0.001, outputCostPer1k: 0, isActive: true },
+
+    // --- Video models ---
+    { id: 'minimax/video-01', provider: 'replicate', name: 'MiniMax Video', capabilities: ['video-generation'], inputCostPer1k: 0, outputCostPer1k: 0, costPerCall: 0.25, isActive: true },
+    { id: 'fal-ai/kling-video/v2/master', provider: 'fal', name: 'Kling Video v2', capabilities: ['video-generation'], inputCostPer1k: 0, outputCostPer1k: 0, costPerCall: 0.10, isActive: true },
+
+    // --- Embedding models ---
+    { id: 'text-embedding-3-small', provider: 'openai', name: 'Embedding Small', capabilities: ['embedding'], inputCostPer1k: 0.00002, outputCostPer1k: 0, isActive: true },
+    { id: 'text-embedding-3-large', provider: 'openai', name: 'Embedding Large', capabilities: ['embedding'], inputCostPer1k: 0.00013, outputCostPer1k: 0, isActive: true },
+
+    // --- Music models ---
+    { id: 'meta/musicgen', provider: 'replicate', name: 'MusicGen', capabilities: ['music-generation'], inputCostPer1k: 0, outputCostPer1k: 0, costPerCall: 0.02, isActive: true },
+    { id: 'fal-ai/stable-audio', provider: 'fal', name: 'Stable Audio', capabilities: ['music-generation', 'sound-effects'], inputCostPer1k: 0, outputCostPer1k: 0, costPerCall: 0.015, isActive: true },
+]
+
+// ============================================================================
+// Default Voices
+// ============================================================================
+
+export const DEFAULT_VOICES = [
+    // OpenAI voices
+    { id: 'alloy', name: 'Alloy', provider: 'openai' as const, gender: 'neutral' as const },
+    { id: 'echo', name: 'Echo', provider: 'openai' as const, gender: 'male' as const },
+    { id: 'fable', name: 'Fable', provider: 'openai' as const, gender: 'male' as const },
+    { id: 'onyx', name: 'Onyx', provider: 'openai' as const, gender: 'male' as const },
+    { id: 'nova', name: 'Nova', provider: 'openai' as const, gender: 'female' as const },
+    { id: 'shimmer', name: 'Shimmer', provider: 'openai' as const, gender: 'female' as const },
+]
+
+// ============================================================================
+// defineAIConfig
+// ============================================================================
+
+export function defineAIConfig(overrides: Partial<AIConfig> = {}): AIConfig {
+    return {
+        defaultProvider: overrides.defaultProvider ?? 'openai',
+        defaultModel: overrides.defaultModel ?? 'gpt-4o',
+        providers: overrides.providers ?? DEFAULT_PROVIDERS,
+        models: overrides.models ?? DEFAULT_MODELS,
+        logging: {
+            enabled: true,
+            maxPromptLength: 2000,
+            maxResponseLength: 8000,
+            ...overrides.logging,
+        },
+        retries: {
+            maxAttempts: 3,
+            retryableStatusCodes: [429, 500, 502, 503, 504],
+            backoffMultiplierMs: 1000,
+            ...overrides.retries,
+        },
+        generationDefaults: {
+            image: 'dall-e-3',
+            audio: 'tts-1',
+            video: 'minimax/video-01',
+            embedding: 'text-embedding-3-small',
+            transcription: 'whisper-1',
+            music: 'meta/musicgen',
+            ...overrides.generationDefaults,
+        },
+    }
+}
+
+export function mergeAIConfig(base: AIConfig, overrides: Partial<AIConfig>): AIConfig {
+    return {
+        ...base,
+        ...overrides,
+        providers: overrides.providers ?? base.providers,
+        models: overrides.models ?? base.models,
+        logging: { ...base.logging, ...overrides.logging },
+        retries: { ...base.retries, ...overrides.retries },
+        generationDefaults: { ...base.generationDefaults, ...overrides.generationDefaults },
+    }
+}
+
+export function findProviderConfig(config: AIConfig, type: AIProviderType): AIProviderConfig | undefined {
+    return config.providers.find(p => p.type === type)
+}
+
+export function findModelConfig(config: AIConfig, modelId: string): AIModel | undefined {
+    return config.models.find(m => m.id === modelId)
+}
+
+export function getProviderForModel(config: AIConfig, modelId: string): AIProviderConfig | undefined {
+    const model = findModelConfig(config, modelId)
+    if (!model) return undefined
+    return findProviderConfig(config, model.provider)
+}
+
+/**
+ * Get all models that support a given capability.
+ */
+export function getModelsByCapability(config: AIConfig, capability: string): AIModel[] {
+    return config.models.filter(m => m.isActive && m.capabilities.includes(capability as any))
+}