plugin-ai-api 1.0.3 → 1.0.6

package/src/server/routes/embeddings.ts

@@ -0,0 +1,191 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { Context } from '@nocobase/actions';
+import { toOpenAIError, toOpenAIEmbeddingsResponse } from '../utils/openai-format';
+import { resolveModelString } from '../utils/resolve-service';
+import type PluginAiApiServer from '../plugin';
+
+/**
+ * POST /api/ai-llm/v1/embeddings
+ *
+ * OpenAI-compatible embeddings endpoint.
+ *
+ * Supported providers (those with an `embedding` field in LLMProviderMeta):
+ *   - openai            → OpenAiEmbeddingProvider
+ *   - openai-completions → OpenAiEmbeddingProvider
+ *   - dashscope         → DashscopeEmbeddingProvider
+ *   - google-genai      → GoogleGenAIEmbeddingProvider
+ *   - ollama            → OllamaEmbeddingProvider
+ *
+ * Not supported: anthropic, deepseek, kimi (no embedding provider registered).
+ *
+ * Limitations:
+ * - encoding_format 'base64' is not supported (always returns float arrays)
+ * - Token counts always return 0 (LangChain embeddings API doesn't expose this)
+ * - Token array input (integer[]) is not supported, only string input
+ */
+export async function handleEmbeddings(ctx: Context, plugin: PluginAiApiServer) {
+  const body = ctx.request.body as any;
+
+  // ─── Validate ────────────────────────────────────────────────────────────
+  if (!body?.model) {
+    ctx.status = 400;
+    ctx.body = toOpenAIError(400, "'model' is required", 'invalid_request_error', 'missing_model');
+    return;
+  }
+
+  if (body.input === undefined || body.input === null) {
+    ctx.status = 400;
+    ctx.body = toOpenAIError(400, "'input' is required", 'invalid_request_error', 'missing_input');
+    return;
+  }
+
+  if (body.encoding_format === 'base64') {
+    ctx.status = 400;
+    ctx.body = toOpenAIError(
+      400,
+      "encoding_format 'base64' is not supported. Use 'float' (default) or omit the parameter.",
+      'invalid_request_error',
+      'unsupported_encoding_format',
+    );
+    return;
+  }
+
+  // ─── Normalize input to string[] ─────────────────────────────────────────
+  let inputs: string[];
+  if (typeof body.input === 'string') {
+    inputs = [body.input];
+  } else if (Array.isArray(body.input)) {
+    if (body.input.length === 0) {
+      ctx.status = 400;
+      ctx.body = toOpenAIError(400, "'input' array must not be empty", 'invalid_request_error');
+      return;
+    }
+    if (typeof body.input[0] === 'number') {
+      ctx.status = 400;
+      ctx.body = toOpenAIError(
+        400,
+        'Token array input is not supported. Please provide string input.',
+        'invalid_request_error',
+        'unsupported_input_type',
+      );
+      return;
+    }
+    inputs = body.input as string[];
+  } else {
+    ctx.status = 400;
+    ctx.body = toOpenAIError(400, "'input' must be a string or array of strings", 'invalid_request_error');
+    return;
+  }
+
+  // ─── Resolve model ────────────────────────────────────────────────────────
+  const resolved = await resolveModelString(ctx, body.model);
+  if (!resolved) {
+    ctx.status = 404;
+    ctx.body = toOpenAIError(
+      404,
+      `Could not resolve model '${body.model}'. Use GET /v1/models to list available models.`,
+      'invalid_request_error',
+      'model_not_found',
+    );
+    return;
+  }
+
+  const { service, modelId } = resolved;
+
+  if (service.enabled === false) {
+    ctx.status = 404;
+    ctx.body = toOpenAIError(
+      404,
+      `LLM service '${service.title || service.name}' is disabled`,
+      'invalid_request_error',
+      'model_not_found',
+    );
+    return;
+  }
+
+  // ─── Check service whitelist ──────────────────────────────────────────────
+  try {
+    const config = await ctx.db.getRepository('aiApiConfig').findOne();
+    if (config?.enabledLlmServices?.length) {
+      const allowed = config.enabledLlmServices.some((s: string) => s === service.name || s === service.title);
+      if (!allowed) {
+        ctx.status = 403;
+        ctx.body = toOpenAIError(
+          403,
+          `LLM service '${service.title || service.name}' is not enabled for API access`,
+          'invalid_request_error',
+          'model_not_available',
+        );
+        return;
+      }
+    }
+  } catch {
+    // Config read failure: fail open
+  }
+
+  // ─── Get embedding provider ───────────────────────────────────────────────
+  const aiPlugin = ctx.app.pm.get('ai') as any;
+  if (!aiPlugin) {
+    ctx.status = 500;
+    ctx.body = toOpenAIError(500, 'AI plugin not available', 'server_error');
+    return;
+  }
+
+  const providerMeta = aiPlugin.aiManager.llmProviders.get(service.provider);
+  if (!providerMeta) {
+    ctx.status = 500;
+    ctx.body = toOpenAIError(500, `Provider '${service.provider}' not registered`, 'server_error');
+    return;
+  }
+
+  // providerMeta.embedding is the EmbeddingProvider constructor (if supported by this provider)
+  if (!providerMeta.embedding) {
+    ctx.status = 400;
+    ctx.body = toOpenAIError(
+      400,
+      `Provider '${providerMeta.title || service.provider}' does not support embeddings. ` +
+        `Embedding-capable providers: openai, openai-completions, dashscope, google-genai, ollama.`,
+      'invalid_request_error',
+      'model_not_supported',
+    );
+    return;
+  }
+
+  try {
+    // ─── Instantiate and call the embedding provider ──────────────────────
+    const EmbeddingClass = providerMeta.embedding;
+    const embeddingProvider = new EmbeddingClass({
+      app: ctx.app,
+      serviceOptions: service.options, // Contains apiKey, baseURL, etc.
+      modelOptions: { model: modelId }, // The specific embedding model
+    });
+
+    // createEmbedding() returns a LangChain EmbeddingsInterface.
+    // embedDocuments() accepts string[] and returns number[][] (one vector per input).
+    const embeddingModel = embeddingProvider.createEmbedding();
+    const vectors: number[][] = await embeddingModel.embedDocuments(inputs);
+
+    ctx.status = 200;
+    ctx.set('Content-Type', 'application/json');
+    ctx.body = toOpenAIEmbeddingsResponse({
+      model: body.model,
+      embeddings: vectors,
+      // LangChain's EmbeddingsInterface does not expose token counts.
+      promptTokens: 0,
+    });
+  } catch (err) {
+    ctx.log.error('AI API embeddings error:', err);
+    if (!ctx.res.headersSent) {
+      ctx.status = 500;
+      ctx.body = toOpenAIError(500, err.message || 'Failed to generate embeddings', 'server_error');
+    }
+  }
+}

package/src/server/routes/models.ts

@@ -0,0 +1,195 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { Context } from '@nocobase/actions';
+import { toOpenAIError } from '../utils/openai-format';
+import type PluginAiApiServer from '../plugin';
+
+/**
+ * GET /api/ai-llm/v1/models
+ *
+ * Lists all available models from enabled LLM services.
+ * Model IDs use the "serviceName/modelId" format (e.g. "my-openai/gpt-4o")
+ * so clients can copy-paste the ID directly into POST /v1/chat/completions
+ * without needing to configure a defaultLlmService.
+ *
+ * Backward compatibility: resolveModelString() in resolve-service.ts still
+ * accepts bare model IDs via its 3-tier fallback (defaultLlmService / single service).
+ */
+export async function handleListModels(ctx: Context, plugin: PluginAiApiServer) {
+  try {
+    const aiPlugin = ctx.app.pm.get('ai') as any;
+    if (!aiPlugin) {
+      ctx.status = 500;
+      ctx.body = toOpenAIError(500, 'AI plugin not available', 'server_error');
+      return;
+    }
+
+    const config = await getPluginConfig(ctx);
+    const filter: any = {};
+
+    // If whitelist is set, apply it (match by name OR title)
+    if (config?.enabledLlmServices?.length) {
+      filter.$or = [{ name: { $in: config.enabledLlmServices } }, { title: { $in: config.enabledLlmServices } }];
+    }
+
+    const services = await ctx.db.getRepository('llmServices').find({
+      filter,
+      sort: 'sort',
+    });
+
+    const now = Math.floor(Date.now() / 1000);
+    const models: any[] = [];
+
+    for (const service of services) {
+      if (service.enabled === false) continue;
+
+      const enabledModels = resolveEnabledModels(service);
+      const serviceLabel = service.title || service.name;
+
+      for (const model of enabledModels) {
+        models.push({
+          // Use "serviceName/modelId" format so the ID can be used directly in
+          // POST /v1/chat/completions without ambiguity in multi-service setups.
+          id: `${service.name}/${model.value}`,
+          object: 'model',
+          created: now,
+          owned_by: serviceLabel,
+        });
+      }
+    }
+
+    ctx.status = 200;
+    ctx.body = {
+      object: 'list',
+      data: models,
+    };
+  } catch (err) {
+    ctx.log.error('AI API list models error:', err);
+    ctx.status = 500;
+    ctx.body = toOpenAIError(500, 'Failed to list models', 'server_error');
+  }
+}
+
+/**
+ * GET /api/ai-llm/v1/models/:model
+ *
+ * Retrieve a single model by ID.
+ * Accepts both "serviceName/modelId" format (new) and bare "modelId" (backward compat).
+ */
+export async function handleGetModel(ctx: Context, modelId: string, plugin: PluginAiApiServer) {
+  try {
+    const config = await getPluginConfig(ctx);
+    const filter: any = {};
+
+    if (config?.enabledLlmServices?.length) {
+      filter.$or = [{ name: { $in: config.enabledLlmServices } }, { title: { $in: config.enabledLlmServices } }];
+    }
+
+    const services = await ctx.db.getRepository('llmServices').find({
+      filter,
+      sort: 'sort',
+    });
+
+    const now = Math.floor(Date.now() / 1000);
+    let found: any = null;
+
+    for (const service of services) {
+      if (service.enabled === false) continue;
+      const enabledModels = resolveEnabledModels(service);
+      const serviceLabel = service.title || service.name;
+
+      for (const model of enabledModels) {
+        const fullId = `${service.name}/${model.value}`;
+        // Accept both new "serviceName/modelId" format AND bare model ID (backward compat)
+        if (fullId === modelId || model.value === modelId) {
+          found = {
+            id: fullId,
+            object: 'model',
+            created: now,
+            owned_by: serviceLabel,
+          };
+          break;
+        }
+      }
+      if (found) break;
+    }
+
+    if (!found) {
+      ctx.status = 404;
+      ctx.body = toOpenAIError(404, `Model '${modelId}' not found`, 'invalid_request_error', 'model_not_found');
+      return;
+    }
+
+    ctx.status = 200;
+    ctx.body = found;
+  } catch (err) {
+    ctx.log.error('AI API get model error:', err);
+    ctx.status = 500;
+    ctx.body = toOpenAIError(500, 'Failed to retrieve model', 'server_error');
+  }
+}
+
+// ─── Helpers ───
+
+async function getPluginConfig(ctx: Context) {
+  return ctx.db.getRepository('aiApiConfig').findOne();
+}
+
+/**
+ * Resolve enabled models for a service.
+ * Mirrors the logic from plugin-ai's ai.ts listAllEnabledModels.
+ *
+ * For 'recommended' mode, we now correctly fetch the official model list
+ * from plugin-ai's shared recommended-models module.
+ */
+function resolveEnabledModels(service: any): { label: string; value: string }[] {
+  const raw = service.enabledModels;
+
+  // Handle new { mode, models } format
+  if (raw && typeof raw === 'object' && !Array.isArray(raw) && raw.mode) {
+    if (raw.mode === 'recommended') {
+      return getRecommendedModelsForProvider(service.provider);
+    }
+    // 'provider' or 'custom' mode with explicitly listed models
+    return (raw.models || [])
+      .filter((m: any) => m.value)
+      .map((m: any) => ({ label: m.label || m.value, value: m.value }));
+  }
+
+  // Backward compat: old string[] format
+  if (Array.isArray(raw)) {
+    if (raw.length === 0) {
+      // Empty array means no explicit models — fall back to recommended
+      return getRecommendedModelsForProvider(service.provider);
+    }
+    return raw.map((id: string) => ({ label: id, value: id }));
+  }
+
+  // null/undefined — no explicit models set, fall back to recommended
+  return getRecommendedModelsForProvider(service.provider);
+}
+
+/**
+ * Get recommended models for a provider from plugin-ai's shared module.
+ *
+ * Uses dynamic require() to avoid a hard compile-time import path dependency.
+ * plugin-ai is always available at runtime (it's a peerDependency).
+ * Falls back to [] if the module is unavailable or the provider has no recommendations.
+ */
+function getRecommendedModelsForProvider(provider: string): { label: string; value: string }[] {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { getRecommendedModels } = require('@nocobase/plugin-ai/src/common/recommended-models');
+    const models = getRecommendedModels(provider);
+    return Array.isArray(models) ? models : [];
+  } catch {
+    return [];
+  }
+}

package/src/server/routes/router.ts

@@ -0,0 +1,283 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import crypto from 'crypto';
+import { Context, Next } from '@nocobase/actions';
+import { authenticateBearer } from './auth';
+import { handleListModels, handleGetModel } from './models';
+import { handleChatCompletions } from './chat-completions';
+import { handleCompletions } from './completions';
+import { handleAgentCompletions } from './agent-completions';
+import { handleEmbeddings } from './embeddings';
+import { toOpenAIError } from '../utils/openai-format';
+import { createRateLimitMiddleware } from '../middleware/rate-limit';
+import { checkRolePermission } from '../middleware/role-permission';
+import type PluginAiApiServer from '../plugin';
+
+const API_PREFIX = '/api/ai-llm/v1';
+
+/**
+ * Main Koa middleware router for OpenAI-compatible endpoints.
+ *
+ * Intercepts all requests to /api/ai-llm/v1/* and routes them
+ * to the appropriate handler. Runs before NocoBase's resourcer
+ * so the URL paths follow OpenAI convention.
+ *
+ * Features:
+ * - CORS support (Access-Control-Allow-Origin: *)
+ * - OPTIONS preflight handling (204)
+ * - X-Request-Id on every response
+ * - Bearer token authentication
+ * - Sliding window rate limiting (enforces rateLimitPerMinute from config)
+ * - Structured request logging via app.logger
+ *
+ * Supported endpoints:
+ *   POST /v1/chat/completions  — OpenAI chat completions (LLM or agent mode)
+ *   POST /v1/completions       — Legacy text completions (LiteLLM compat)
+ *   POST /v1/embeddings        — OpenAI embeddings
+ *   GET  /v1/models            — List available models
+ *   GET  /v1/models/:id        — Get a single model
+ *   DELETE /v1/models/:id      — Not implemented (501 stub)
+ */
+export function createAiLlmRouter(plugin: PluginAiApiServer) {
+  const checkRateLimit = createRateLimitMiddleware(plugin.rateLimiter);
+
+  return async (ctx: Context, next: Next) => {
+    const { path, method } = ctx;
+
+    // Only handle our prefix
+    if (!path.startsWith(API_PREFIX)) {
+      return next();
+    }
+
+    // Prevent NocoBase's dataWrapping middleware from wrapping OpenAI-format responses
+    // in an extra {"data": ...} envelope, which breaks OpenAI-compatible clients like n8n.
+    (ctx as any).withoutDataWrapping = true;
+
+    // Parse the sub-path after prefix
+    const subPath = path.substring(API_PREFIX.length);
+
+    // ─── CORS — applies to all requests, including preflight ──────────────
+    // '*' is safe here because all endpoints require Bearer token auth.
+    // Browsers cannot send cookies to '*' origins, but Authorization headers work fine.
+    ctx.set('Access-Control-Allow-Origin', '*');
+    ctx.set('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+    ctx.set('Access-Control-Allow-Headers', 'Authorization, Content-Type, X-AI-Mode, X-Timezone, X-Locale');
+    ctx.set('Access-Control-Expose-Headers', 'X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After');
+    ctx.set('Access-Control-Max-Age', '86400');
+
+    // ─── OPTIONS preflight — return immediately after CORS headers ────────
+    if (method === 'OPTIONS') {
+      ctx.status = 204;
+      return;
+    }
+
+    // ─── Request ID — set before any response ─────────────────────────────
+    const requestId = `req-${crypto.randomBytes(12).toString('hex')}`;
+    ctx.set('X-Request-Id', requestId);
+
+    // ─── Parse body for POST requests if not already parsed ───────────────
+    if (method === 'POST' && !ctx.request.body) {
+      try {
+        const rawBody = await getRawBody(ctx);
+        ctx.request.body = JSON.parse(rawBody);
+      } catch (bodyErr: any) {
+        const status = bodyErr?.statusCode === 413 ? 413 : 400;
+        const message = status === 413 ? 'Request body too large (max 10 MB)' : 'Invalid JSON in request body';
+        ctx.status = status;
+        ctx.body = toOpenAIError(status, message, 'invalid_request_error');
+        return;
+      }
+    }
+
+    // ─── Authenticate ─────────────────────────────────────────────────────
+    const isAuth = await authenticateBearer(ctx);
+    if (!isAuth) {
+      logRequest(ctx, requestId, '-', 'auth_failed', 0);
+      return;
+    }
+
+    // ─── Role permission check ────────────────────────────────────────────
+    const permitted = await checkRolePermission(ctx);
+    if (!permitted) {
+      logRequest(ctx, requestId, '-', 'forbidden', 0);
+      return;
+    }
+
+    // ─── Rate limiting ────────────────────────────────────────────────────
+    const allowed = await checkRateLimit(ctx);
+    if (!allowed) {
+      logRequest(ctx, requestId, '-', 'rate_limited', 0);
+      return;
+    }
+
+    // ─── Route matching ───────────────────────────────────────────────────
+    const model = (ctx.request.body as any)?.model ?? '-';
+    const t0 = Date.now();
+
+    try {
+      // POST /v1/chat/completions — route based on mode
+      if (method === 'POST' && subPath === '/chat/completions') {
+        const mode = await resolveMode(ctx);
+        await (mode === 'agent' ? handleAgentCompletions(ctx, plugin) : handleChatCompletions(ctx, plugin));
+        logRequest(ctx, requestId, model, 'ok', Date.now() - t0);
+        return;
+      }
+
+      // POST /v1/embeddings
+      if (method === 'POST' && subPath === '/embeddings') {
+        await handleEmbeddings(ctx, plugin);
+        logRequest(ctx, requestId, model, 'ok', Date.now() - t0);
+        return;
+      }
+
+      // POST /v1/completions (legacy text completions — used by LiteLLM)
+      if (method === 'POST' && subPath === '/completions') {
+        const completionsMode = await resolveMode(ctx);
+        if (completionsMode === 'agent') {
+          // Convert legacy prompt → messages format for agent handler
+          const reqBody = ctx.request.body as any;
+          if (reqBody?.prompt !== undefined) {
+            const prompt =
+              typeof reqBody.prompt === 'string'
+                ? reqBody.prompt
+                : Array.isArray(reqBody.prompt)
+                  ? reqBody.prompt.join('\n')
+                  : String(reqBody.prompt);
+            ctx.request.body = { ...reqBody, messages: [{ role: 'user', content: prompt }] };
+          }
+          await handleAgentCompletions(ctx, plugin);
+        } else {
+          await handleCompletions(ctx, plugin);
+        }
+        logRequest(ctx, requestId, model, 'ok', Date.now() - t0);
+        return;
+      }
+
+      // GET /v1/models
+      if (method === 'GET' && subPath === '/models') {
+        await handleListModels(ctx, plugin);
+        logRequest(ctx, requestId, '-', 'ok', Date.now() - t0);
+        return;
+      }
+
+      // GET /v1/models/:model (model can contain '/' for service/model format)
+      if (method === 'GET' && subPath.startsWith('/models/')) {
+        const modelId = subPath.substring('/models/'.length);
+        if (modelId) {
+          await handleGetModel(ctx, decodeURIComponent(modelId), plugin);
+          logRequest(ctx, requestId, modelId, 'ok', Date.now() - t0);
+          return;
+        }
+      }
+
+      // DELETE /v1/models/:model — stub (OpenAI fine-tune model deletion, not applicable here)
+      if (method === 'DELETE' && subPath.startsWith('/models/')) {
+        ctx.status = 501;
+        ctx.body = toOpenAIError(
+          501,
+          'Model deletion is not supported by this API gateway. ' +
+            'Use the NocoBase admin panel to manage LLM services.',
+          'invalid_request_error',
+          'not_implemented',
+        );
+        logRequest(ctx, requestId, '-', 'not_implemented', Date.now() - t0);
+        return;
+      }
+
+      // ─── Unsupported endpoint ──────────────────────────────────────────
+      ctx.status = 404;
+      ctx.body = toOpenAIError(
+        404,
+        `Unknown endpoint: ${method} ${path}. ` +
+          `Supported: POST /v1/chat/completions, POST /v1/completions, POST /v1/embeddings, GET /v1/models`,
+        'invalid_request_error',
+        'unknown_url',
+      );
+      logRequest(ctx, requestId, '-', 'not_found', Date.now() - t0);
+    } catch (err) {
+      ctx.log.error('AI API router error:', err);
+      logRequest(ctx, requestId, model, 'error', Date.now() - t0);
+      if (!ctx.res.headersSent) {
+        ctx.status = 500;
+        ctx.body = toOpenAIError(500, err.message || 'Internal server error', 'server_error');
+      }
+    }
+  };
+}
+
+/** Maximum allowed request body size (10 MB) to prevent OOM DoS attacks. */
+const MAX_BODY_BYTES = 10 * 1024 * 1024;
+
+/**
+ * Read raw body from request stream (fallback if bodyparser didn't handle it).
+ * Rejects with a 413-style error if the body exceeds MAX_BODY_BYTES.
+ */
+function getRawBody(ctx: Context): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let body = '';
+    let byteCount = 0;
+
+    ctx.req.on('data', (chunk: Buffer) => {
+      byteCount += chunk.length;
+      if (byteCount > MAX_BODY_BYTES) {
+        ctx.req.destroy();
+        reject(Object.assign(new Error('Request body too large (max 10 MB)'), { statusCode: 413 }));
+        return;
+      }
+      body += chunk.toString();
+    });
+    ctx.req.on('end', () => resolve(body));
+    ctx.req.on('error', reject);
+  });
+}
+
+/**
+ * Determine the API mode for a request.
+ *
+ * Priority:
+ * 1. X-AI-Mode request header ('llm' or 'agent')
+ * 2. Config `mode` field from aiApiConfig
+ * 3. Default: 'llm'
+ */
+async function resolveMode(ctx: Context): Promise<'llm' | 'agent'> {
+  const headerMode = ctx.get('X-AI-Mode')?.toLowerCase();
+  if (headerMode === 'agent' || headerMode === 'llm') {
+    ctx.app.logger?.info(`[ai-api] Mode resolved from header: ${headerMode}`);
+    return headerMode;
+  }
+
+  try {
+    const config = await ctx.db.getRepository('aiApiConfig').findOne();
+    if (config) {
+      const dbMode = config.get('mode') || config.mode;
+      if (dbMode === 'agent' || dbMode === 'llm') {
+        ctx.app.logger?.info(`[ai-api] Mode resolved from DB config: ${dbMode}`);
+        return dbMode as 'llm' | 'agent';
+      }
+    }
+  } catch (err) {
+    ctx.app.logger?.error('[ai-api] Failed to get mode from config:', err);
+    // Ignore config errors — default to llm
+  }
+
+  ctx.app.logger?.info(`[ai-api] Mode fallback to default: llm`);
+  return 'llm';
+}
+
+/**
+ * Write a structured log line for every handled request.
+ */
+function logRequest(ctx: Context, requestId: string, model: string, status: string, durationMs: number): void {
+  const userId = ctx.state.currentUser?.id ?? 'anon';
+  ctx.app.logger?.info(
+    `[ai-api] ${ctx.method} ${ctx.path} requestId=${requestId} userId=${userId} ` +
+      `model=${model} status=${status} duration=${durationMs}ms`,
+  );
+}