@open-mercato/ai-assistant 0.4.11-develop.2226.2963a4b52d → 0.4.11-develop.2229.54cd746c6e

package/src/modules/ai_assistant/lib/llm-adapters/openai.ts

@@ -0,0 +1,145 @@
+/**
+ * OpenAIAdapter — implements the LlmProvider port for the OpenAI
+ * chat-completions protocol.
+ *
+ * This single adapter serves OpenAI itself and every OpenAI-compatible
+ * backend (DeepInfra, Groq, Together, Fireworks, Azure OpenAI, LiteLLM,
+ * Ollama, LocalAI, vLLM, …). Vendor-specific configuration — endpoint
+ * URL, available models, env var conventions — lives in
+ * `./openai-compatible-presets.ts` as plain data, not code.
+ *
+ * The factory {@link createOpenAICompatibleProvider} takes a preset and
+ * returns a fully-configured `LlmProvider` that internally calls
+ * `createOpenAI({ apiKey, baseURL })` from `@ai-sdk/openai`.
+ *
+ * @see packages/shared/src/lib/ai/llm-provider.ts
+ * @see ./openai-compatible-presets.ts
+ * @see .ai/specs/2026-04-14-llm-provider-ports-and-adapters.md
+ */
+
+import { createOpenAI } from '@ai-sdk/openai'
+import type {
+  EnvLookup,
+  LlmCreateModelOptions,
+  LlmModelInfo,
+  LlmProvider,
+} from '@open-mercato/shared/lib/ai/llm-provider'
+
+/**
+ * Configuration for a single OpenAI-compatible provider instance.
+ *
+ * Built-in presets live in {@link ./openai-compatible-presets.ts}.
+ * Downstream applications may construct custom presets at bootstrap time
+ * and register them with `llmProviderRegistry.register(
+ *   createOpenAICompatibleProvider(customPreset),
+ * )`.
+ */
+export interface OpenAICompatiblePreset {
+  /** Stable id (e.g. `openai`, `deepinfra`, `groq`, `together`). */
+  id: string
+  /** Human-readable display name. */
+  name: string
+  /**
+   * Upstream base URL. Leave `undefined` to use the AI SDK default
+   * (`https://api.openai.com/v1`). Required for DeepInfra, Groq, etc.
+   */
+  baseURL?: string
+  /**
+   * Env var names where the adapter looks for the API key, in priority
+   * order. Each preset declares its own keys so unrelated presets never
+   * accidentally share credentials (e.g. DeepInfra uses
+   * `DEEPINFRA_API_KEY`, not `OPENAI_API_KEY`).
+   */
+  envKeys: readonly string[]
+  /** Default model id used when the caller does not specify one. */
+  defaultModel: string
+  /** Curated model catalog shown in the UI dropdown. */
+  defaultModels: readonly LlmModelInfo[]
+  /**
+   * Optional env var names for overriding the base URL at runtime.
+   * Primarily used by presets that rely on a user-supplied URL
+   * (Azure deployment, self-hosted LiteLLM, Ollama on a custom port).
+   * The first non-empty value wins and overrides {@link baseURL}.
+   */
+  baseURLEnvKeys?: readonly string[]
+}
+
+function readFirstNonEmpty(
+  env: EnvLookup,
+  keys: readonly string[],
+): string | null {
+  for (const key of keys) {
+    const value = env[key]
+    if (typeof value === 'string') {
+      const trimmed = value.trim()
+      if (trimmed.length > 0) return trimmed
+    }
+  }
+  return null
+}
+
+/**
+ * Builds a `LlmProvider` instance bound to a specific OpenAI-compatible
+ * preset. The returned object is stateless and can be registered directly
+ * with `llmProviderRegistry.register(...)`.
+ */
+export function createOpenAICompatibleProvider(
+  preset: OpenAICompatiblePreset,
+): LlmProvider {
+  if (!preset.id || preset.id.length === 0) {
+    throw new Error('[OpenAIAdapter] Preset must have a non-empty id')
+  }
+  if (!preset.envKeys || preset.envKeys.length === 0) {
+    throw new Error(
+      `[OpenAIAdapter] Preset "${preset.id}" must declare at least one env key`,
+    )
+  }
+
+  function resolveApiKey(env?: EnvLookup): string | null {
+    return readFirstNonEmpty(env ?? process.env, preset.envKeys)
+  }
+
+  function resolveBaseURL(env?: EnvLookup): string | undefined {
+    const lookup = env ?? process.env
+    if (preset.baseURLEnvKeys && preset.baseURLEnvKeys.length > 0) {
+      const override = readFirstNonEmpty(lookup, preset.baseURLEnvKeys)
+      if (override) return override
+    }
+    return preset.baseURL
+  }
+
+  return {
+    id: preset.id,
+    name: preset.name,
+    envKeys: preset.envKeys,
+    defaultModel: preset.defaultModel,
+    defaultModels: preset.defaultModels,
+
+    isConfigured(env?: EnvLookup): boolean {
+      return resolveApiKey(env) !== null
+    },
+
+    resolveApiKey,
+
+    getConfiguredEnvKey(env?: EnvLookup): string {
+      const lookup = env ?? process.env
+      for (const key of preset.envKeys) {
+        const value = lookup[key]
+        if (typeof value === 'string' && value.trim().length > 0) {
+          return key
+        }
+      }
+      return preset.envKeys[0]
+    },
+
+    createModel(options: LlmCreateModelOptions): unknown {
+      // Per-request baseURL override wins over preset/env defaults.
+      const baseURL = options.baseURL ?? resolveBaseURL()
+      const openai = createOpenAI({
+        apiKey: options.apiKey,
+        ...(baseURL ? { baseURL } : {}),
+      })
+      return openai(options.modelId)
+    },
+  }
+}

package/src/modules/ai_assistant/lib/llm-bootstrap.ts

@@ -0,0 +1,80 @@
+/**
+ * LLM provider bootstrap — registers built-in adapters and OpenAI-compatible
+ * presets with the shared `llmProviderRegistry` singleton.
+ *
+ * This runs at module load via the side-effect import in `./ai-sdk.ts`.
+ * Safe to call multiple times — each registration is idempotent (replaces
+ * existing by id), so Next.js hot-reload does not duplicate providers.
+ *
+ * Adapter registration is wrapped in individual try/catch blocks. A
+ * failing import (e.g. missing peer dependency) skips that adapter with a
+ * `console.warn` but leaves the rest of the registry working.
+ *
+ * @see packages/shared/src/lib/ai/llm-provider-registry.ts
+ * @see .ai/specs/2026-04-14-llm-provider-ports-and-adapters.md
+ */
+
+import { llmProviderRegistry } from '@open-mercato/shared/lib/ai/llm-provider-registry'
+import { createAnthropicAdapter } from './llm-adapters/anthropic'
+import { createGoogleAdapter } from './llm-adapters/google'
+import { createOpenAICompatibleProvider } from './llm-adapters/openai'
+import { OPENAI_COMPATIBLE_PRESETS } from './openai-compatible-presets'
+
+let bootstrapped = false
+
+/**
+ * Registers all built-in LLM providers with the shared singleton.
+ * Idempotent — the second and subsequent calls are no-ops (unless the
+ * registry was reset by a test, in which case registration runs again).
+ */
+export function registerBuiltInLlmProviders(): void {
+  if (bootstrapped && llmProviderRegistry.list().length > 0) {
+    return
+  }
+
+  // Native protocol adapters.
+  try {
+    llmProviderRegistry.register(createAnthropicAdapter())
+  } catch (error) {
+    console.warn(
+      '[LlmBootstrap] Failed to register Anthropic adapter:',
+      error instanceof Error ? error.message : error,
+    )
+  }
+
+  try {
+    llmProviderRegistry.register(createGoogleAdapter())
+  } catch (error) {
+    console.warn(
+      '[LlmBootstrap] Failed to register Google adapter:',
+      error instanceof Error ? error.message : error,
+    )
+  }
+
+  // OpenAI-compatible presets — all share one protocol adapter under the
+  // hood but appear as separate providers in the registry.
+  for (const preset of OPENAI_COMPATIBLE_PRESETS) {
+    try {
+      llmProviderRegistry.register(createOpenAICompatibleProvider(preset))
+    } catch (error) {
+      console.warn(
+        `[LlmBootstrap] Failed to register OpenAI-compatible preset "${preset.id}":`,
+        error instanceof Error ? error.message : error,
+      )
+    }
+  }
+
+  bootstrapped = true
+}
+
+/**
+ * Resets the bootstrap state. Intended for tests that call
+ * `llmProviderRegistry.reset()` and then want a fresh bootstrap run.
+ */
+export function resetLlmBootstrapState(): void {
+  bootstrapped = false
+}
+
+// Auto-bootstrap on module load so any consumer importing from
+// `@open-mercato/ai-assistant/lib/llm-bootstrap` triggers registration.
+registerBuiltInLlmProviders()

package/src/modules/ai_assistant/lib/openai-compatible-presets.ts

@@ -0,0 +1,262 @@
+/**
+ * Curated registry of OpenAI-compatible LLM backends.
+ *
+ * Each preset is plain data — adding a new backend takes one entry in
+ * this array, zero new adapter files, and zero changes to route handlers.
+ * The {@link createOpenAICompatibleProvider} factory in `./llm-adapters/openai.ts`
+ * turns each preset into a concrete `LlmProvider` at bootstrap time.
+ *
+ * Preset model catalogs are curated snapshots as of 2026-04-14 and should
+ * be updated as upstream catalogs evolve. Users can always override the
+ * selected model via the `OPENCODE_MODEL` env var without editing this
+ * file.
+ *
+ * @see ./llm-adapters/openai.ts
+ * @see .ai/specs/2026-04-14-llm-provider-ports-and-adapters.md
+ */
+
+import type { OpenAICompatiblePreset } from './llm-adapters/openai'
+
+/**
+ * Standard OpenAI — default OpenAI API at api.openai.com.
+ */
+const OPENAI_PRESET: OpenAICompatiblePreset = {
+  id: 'openai',
+  name: 'OpenAI',
+  baseURL: undefined,
+  envKeys: ['OPENAI_API_KEY', 'OPENCODE_OPENAI_API_KEY'],
+  defaultModel: 'gpt-5-mini',
+  defaultModels: [
+    {
+      id: 'gpt-5-mini',
+      name: 'GPT-5 Mini',
+      contextWindow: 128000,
+      tags: ['budget'],
+    },
+    {
+      id: 'gpt-5',
+      name: 'GPT-5',
+      contextWindow: 128000,
+      tags: ['flagship'],
+    },
+    {
+      id: 'gpt-4o-mini',
+      name: 'GPT-4o Mini',
+      contextWindow: 128000,
+      tags: ['budget'],
+    },
+    {
+      id: 'gpt-4o',
+      name: 'GPT-4o',
+      contextWindow: 128000,
+    },
+  ],
+}
+
+/**
+ * DeepInfra — hosts open-weight flagship models at 3-12× lower cost than
+ * the native APIs. The curated catalog targets the AI Assistant use case
+ * (routing + tool use + conversational chat).
+ */
+const DEEPINFRA_PRESET: OpenAICompatiblePreset = {
+  id: 'deepinfra',
+  name: 'DeepInfra',
+  baseURL: 'https://api.deepinfra.com/v1/openai',
+  envKeys: ['DEEPINFRA_API_KEY'],
+  defaultModel: 'zai-org/GLM-5.1',
+  defaultModels: [
+    {
+      id: 'zai-org/GLM-5.1',
+      name: 'GLM-5.1 (Zhipu)',
+      contextWindow: 202752,
+      tags: ['flagship'],
+    },
+    {
+      id: 'zai-org/GLM-4.7-Flash',
+      name: 'GLM-4.7 Flash',
+      contextWindow: 202752,
+      tags: ['budget'],
+    },
+    {
+      id: 'Qwen/Qwen3-235B-A22B-Instruct-2507',
+      name: 'Qwen3 235B (MoE)',
+      contextWindow: 262144,
+      tags: ['flagship'],
+    },
+    {
+      id: 'meta-llama/Llama-4-Scout-17B-16E-Instruct',
+      name: 'Llama 4 Scout',
+      contextWindow: 327680,
+    },
+    {
+      id: 'deepseek-ai/DeepSeek-V3.2-Exp',
+      name: 'DeepSeek V3.2',
+      contextWindow: 163840,
+      tags: ['reasoning'],
+    },
+    {
+      id: 'Qwen/Qwen3-Coder-30B-A3B-Instruct',
+      name: 'Qwen3 Coder 30B',
+      contextWindow: 262144,
+      tags: ['coding'],
+    },
+  ],
+}
+
+/**
+ * Groq — specializes in low-latency inference on LPU hardware.
+ * Best suited for snappy tool-use and routing, less so for long reasoning.
+ */
+const GROQ_PRESET: OpenAICompatiblePreset = {
+  id: 'groq',
+  name: 'Groq',
+  baseURL: 'https://api.groq.com/openai/v1',
+  envKeys: ['GROQ_API_KEY'],
+  defaultModel: 'llama-3.3-70b-versatile',
+  defaultModels: [
+    {
+      id: 'llama-3.3-70b-versatile',
+      name: 'Llama 3.3 70B Versatile',
+      contextWindow: 131072,
+    },
+    {
+      id: 'llama-4-scout-17b',
+      name: 'Llama 4 Scout 17B',
+      contextWindow: 131072,
+    },
+    {
+      id: 'mixtral-8x22b-32768',
+      name: 'Mixtral 8x22B',
+      contextWindow: 32768,
+    },
+  ],
+}
+
+/**
+ * Together AI — broad catalog of open-weight models with per-model pricing.
+ */
+const TOGETHER_PRESET: OpenAICompatiblePreset = {
+  id: 'together',
+  name: 'Together AI',
+  baseURL: 'https://api.together.xyz/v1',
+  envKeys: ['TOGETHER_API_KEY'],
+  defaultModel: 'meta-llama/Llama-3.3-70B-Instruct-Turbo',
+  defaultModels: [
+    {
+      id: 'meta-llama/Llama-3.3-70B-Instruct-Turbo',
+      name: 'Llama 3.3 70B Turbo',
+      contextWindow: 131072,
+    },
+    {
+      id: 'Qwen/Qwen2.5-72B-Instruct-Turbo',
+      name: 'Qwen 2.5 72B Turbo',
+      contextWindow: 32768,
+    },
+  ],
+}
+
+/**
+ * Fireworks AI — fast inference with a curated catalog.
+ */
+const FIREWORKS_PRESET: OpenAICompatiblePreset = {
+  id: 'fireworks',
+  name: 'Fireworks AI',
+  baseURL: 'https://api.fireworks.ai/inference/v1',
+  envKeys: ['FIREWORKS_API_KEY'],
+  defaultModel: 'accounts/fireworks/models/llama-v3p3-70b-instruct',
+  defaultModels: [
+    {
+      id: 'accounts/fireworks/models/llama-v3p3-70b-instruct',
+      name: 'Llama 3.3 70B',
+      contextWindow: 131072,
+    },
+  ],
+}
+
+/**
+ * Azure OpenAI — enterprise Azure deployments. Base URL is deployment-
+ * specific and must be provided via `AZURE_OPENAI_BASE_URL`.
+ */
+const AZURE_PRESET: OpenAICompatiblePreset = {
+  id: 'azure',
+  name: 'Azure OpenAI',
+  baseURL: undefined,
+  baseURLEnvKeys: ['AZURE_OPENAI_BASE_URL'],
+  envKeys: ['AZURE_OPENAI_API_KEY'],
+  defaultModel: 'gpt-5-mini',
+  defaultModels: [
+    {
+      id: 'gpt-5-mini',
+      name: 'GPT-5 Mini',
+      contextWindow: 128000,
+    },
+    {
+      id: 'gpt-5',
+      name: 'GPT-5',
+      contextWindow: 128000,
+    },
+  ],
+}
+
+/**
+ * LiteLLM proxy — self-hosted router for arbitrary upstream providers.
+ * Base URL must be supplied via `LITELLM_BASE_URL`.
+ */
+const LITELLM_PRESET: OpenAICompatiblePreset = {
+  id: 'litellm',
+  name: 'LiteLLM',
+  baseURL: 'http://localhost:4000/v1',
+  baseURLEnvKeys: ['LITELLM_BASE_URL'],
+  envKeys: ['LITELLM_API_KEY'],
+  defaultModel: 'gpt-4o-mini',
+  defaultModels: [
+    {
+      id: 'gpt-4o-mini',
+      name: 'GPT-4o Mini (via LiteLLM)',
+      contextWindow: 128000,
+    },
+  ],
+}
+
+/**
+ * Ollama — local model runner for development and offline use.
+ * Default port 11434 can be overridden via `OLLAMA_BASE_URL`.
+ */
+const OLLAMA_PRESET: OpenAICompatiblePreset = {
+  id: 'ollama',
+  name: 'Ollama (local)',
+  baseURL: 'http://localhost:11434/v1',
+  baseURLEnvKeys: ['OLLAMA_BASE_URL'],
+  envKeys: ['OLLAMA_API_KEY'],
+  defaultModel: 'llama3.3',
+  defaultModels: [
+    {
+      id: 'llama3.3',
+      name: 'Llama 3.3 (local)',
+      contextWindow: 131072,
+    },
+    {
+      id: 'qwen2.5-coder',
+      name: 'Qwen 2.5 Coder (local)',
+      contextWindow: 131072,
+      tags: ['coding'],
+    },
+  ],
+}
+
+/**
+ * Built-in presets registered at bootstrap time. Order matters — it
+ * determines the default iteration order of
+ * `llmProviderRegistry.resolveFirstConfigured()` when no explicit order
+ * is supplied.
+ */
+export const OPENAI_COMPATIBLE_PRESETS: readonly OpenAICompatiblePreset[] = [
+  OPENAI_PRESET,
+  DEEPINFRA_PRESET,
+  GROQ_PRESET,
+  TOGETHER_PRESET,
+  FIREWORKS_PRESET,
+  AZURE_PRESET,
+  LITELLM_PRESET,
+  OLLAMA_PRESET,
+]