@sahan-sac/ai-core 0.1.0 → 0.3.0

package/dist/adapters.js

@@ -0,0 +1,621 @@
+// src/models.ts
+var DEFAULT_TEXT_MODELS = {
+  // Long structured JSON: a full flash model, not lite.
+  blog: {
+    gemini: "gemini-2.5-flash",
+    openrouter: "nvidia/nemotron-3-super-120b-a12b:free",
+    nvidia: "nvidia/nemotron-3-super-120b-a12b",
+    vertex: "gemini-2.5-flash"
+  },
+  // Short, latency-sensitive replies: the fastest free model first.
+  chat: {
+    gemini: "gemini-3.1-flash-lite",
+    openrouter: "nvidia/nemotron-3-super-120b-a12b:free",
+    nvidia: "nvidia/nemotron-3-super-120b-a12b",
+    vertex: "gemini-2.5-flash"
+  }
+};
+var pick = (...values) => values.find((value) => value && value.trim()).trim();
+function textModels(env, purpose) {
+  const defaults = DEFAULT_TEXT_MODELS[purpose];
+  const own = purpose === "blog" ? { gemini: env.BLOG_GEMINI_MODEL, openrouter: env.BLOG_OPENROUTER_MODEL, nvidia: env.BLOG_NVIDIA_MODEL, vertex: env.BLOG_VERTEX_MODEL } : { gemini: env.CHAT_GEMINI_MODEL, openrouter: env.CHAT_OPENROUTER_MODEL, nvidia: env.CHAT_NVIDIA_MODEL, vertex: env.CHAT_VERTEX_MODEL };
+  return {
+    gemini: pick(own.gemini, env.GEMINI_MODEL, defaults.gemini),
+    openrouter: pick(own.openrouter, env.OPENROUTER_MODEL, defaults.openrouter),
+    nvidia: pick(own.nvidia, env.NVIDIA_MODEL, defaults.nvidia),
+    vertex: pick(own.vertex, env.VERTEX_MODEL, defaults.vertex)
+  };
+}
+var paidAllowed = (env) => env.AI_ALLOW_PAID === true;
+function vertexConfigured(env) {
+  return Boolean(env.GOOGLE_CLIENT_EMAIL && env.GOOGLE_PRIVATE_KEY && env.GOOGLE_CLOUD_PROJECT);
+}
+function thinkingConfigFor(model, maxOutputTokens) {
+  const long = maxOutputTokens >= 2e3;
+  if (/^gemini-[3-9]/.test(model)) {
+    return { thinkingLevel: long ? "low" : /flash/.test(model) ? "minimal" : "low" };
+  }
+  return { thinkingBudget: long ? Math.min(800, Math.floor(maxOutputTokens / 5)) : 0 };
+}
+
+// src/providers.ts
+import "server-only";
+import { createOpenAI } from "@ai-sdk/openai";
+import { generateText } from "ai";
+
+// src/log.ts
+var consoleAiLogger = {
+  warn(message, meta) {
+    console.warn(JSON.stringify({ level: "warn", message, ...meta }));
+  }
+};
+
+// src/vertex.ts
+import "server-only";
+var cachedToken = null;
+function base64UrlEncode(input) {
+  return Buffer.from(input).toString("base64url");
+}
+async function getVertexAccessToken(account, fetchImpl = fetch) {
+  const now = Date.now();
+  if (cachedToken && cachedToken.expiresAt - 6e4 > now) return cachedToken.accessToken;
+  const { createSign } = await import("crypto");
+  const issuedAt = Math.floor(now / 1e3);
+  const expiresIn = 3600;
+  const header = base64UrlEncode(JSON.stringify({ alg: "RS256", typ: "JWT" }));
+  const claims = base64UrlEncode(
+    JSON.stringify({
+      iss: account.clientEmail,
+      scope: "https://www.googleapis.com/auth/cloud-platform",
+      aud: account.tokenUri,
+      iat: issuedAt,
+      exp: issuedAt + expiresIn
+    })
+  );
+  const signingInput = `${header}.${claims}`;
+  const signature = createSign("RSA-SHA256").update(signingInput).sign(account.privateKey);
+  const jwt = `${signingInput}.${base64UrlEncode(signature)}`;
+  const response = await fetchImpl(account.tokenUri, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+      assertion: jwt
+    })
+  });
+  if (!response.ok) {
+    throw new Error(`Vertex token exchange failed: HTTP ${response.status}`);
+  }
+  const data = await response.json();
+  cachedToken = { accessToken: data.access_token, expiresAt: now + data.expires_in * 1e3 };
+  return data.access_token;
+}
+
+// src/providers.ts
+function jsonConfig(jsonMode) {
+  if (!jsonMode) return {};
+  return typeof jsonMode === "object" ? { responseMimeType: "application/json", responseSchema: jsonMode.schema } : { responseMimeType: "application/json" };
+}
+var AI_TIMEOUT_MS = 25e3;
+var AI_COOLDOWN_MS = 6e4;
+async function attempt(provider, prompt, maxTokens, ms, cancel, jsonMode) {
+  const controller = new AbortController();
+  const onCancel = () => controller.abort();
+  cancel.addEventListener("abort", onCancel, { once: true });
+  let timer;
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      resolve({ ok: false, errorClass: "timeout", retryable: true });
+    }, ms);
+  });
+  try {
+    return await Promise.race([provider.generate(prompt, { maxTokens, signal: controller.signal, jsonMode }), timeout]);
+  } catch {
+    return { ok: false, errorClass: "transport", retryable: true };
+  } finally {
+    clearTimeout(timer);
+    cancel.removeEventListener("abort", onCancel);
+  }
+}
+var createAiHealth = () => ({ cooldownUntil: /* @__PURE__ */ new Map(), latencyMs: /* @__PURE__ */ new Map() });
+var sharedAiHealth = globalThis.sahanAiHealth ??= createAiHealth();
+function cooldownFor(outcome) {
+  if (outcome.ok) return 0;
+  if (outcome.errorClass === "timeout" || outcome.status === 429) return AI_COOLDOWN_MS;
+  if (outcome.status === 401 || outcome.status === 403 || outcome.status === 404) return AI_COOLDOWN_MS * 10;
+  return 0;
+}
+var HEDGE = /* @__PURE__ */ Symbol("hedge");
+function createAiService(deps) {
+  const timeoutMs = deps.timeoutMs ?? AI_TIMEOUT_MS;
+  const now = deps.now ?? Date.now;
+  const health = deps.health ?? createAiHealth();
+  const logger = deps.logger ?? consoleAiLogger;
+  function rank(at) {
+    const cooling = (p) => Number((health.cooldownUntil.get(p.name) ?? 0) > at);
+    const speed = (p) => health.latencyMs.get(p.name) ?? Number.POSITIVE_INFINITY;
+    const costly = (p) => Number(Boolean(p.lastResort));
+    const chosen = (a, b) => a.priority !== void 0 && b.priority !== void 0 ? a.priority - b.priority : speed(a) - speed(b);
+    return [...deps.providers].sort((a, b) => costly(a) - costly(b) || cooling(a) - cooling(b) || chosen(a, b));
+  }
+  async function generate(prompt, options) {
+    if (deps.providers.length === 0) {
+      return { ok: false, provider: null, errorClass: "no_provider", attempts: [] };
+    }
+    const external = options?.signal;
+    if (external?.aborted) return { ok: false, provider: null, errorClass: "aborted", attempts: [] };
+    const startedAll = now();
+    const ordered = rank(startedAll);
+    const attempts = [];
+    const cancelLosers = new AbortController();
+    const running = /* @__PURE__ */ new Set();
+    let next = 0;
+    let stopped = false;
+    let result = null;
+    let rejected;
+    let onAbort;
+    const aborted = new Promise((resolve) => {
+      onAbort = () => {
+        stopped = true;
+        cancelLosers.abort();
+        resolve();
+      };
+      external?.addEventListener("abort", onAbort, { once: true });
+    });
+    const launch = () => {
+      if (result || stopped || next >= ordered.length) return false;
+      const remaining = deps.deadlineMs === void 0 ? timeoutMs : deps.deadlineMs - (now() - startedAll);
+      if (remaining <= 250) return false;
+      const provider = ordered[next++];
+      options?.onAttempt?.({ provider: provider.name, stage: "start" });
+      const started = now();
+      const run = attempt(provider, prompt, options?.maxTokens, Math.min(timeoutMs, remaining), cancelLosers.signal, options?.jsonMode).then((raw) => {
+        if (result || external?.aborted) return;
+        const ms = now() - started;
+        let outcome = raw;
+        if (outcome.ok && options?.accept) {
+          const reason = options.accept(outcome.text);
+          if (reason) {
+            rejected = { provider: provider.name, text: outcome.text, reason };
+            outcome = { ok: false, errorClass: "invalid_output", retryable: true };
+          }
+        }
+        if (outcome.ok) {
+          health.cooldownUntil.delete(provider.name);
+          const previous = health.latencyMs.get(provider.name);
+          health.latencyMs.set(provider.name, previous === void 0 ? ms : Math.round(previous * 0.7 + ms * 0.3));
+          attempts.push({ provider: provider.name, ok: true, ms });
+          result = { ok: true, provider: provider.name, text: outcome.text, attempts };
+          options?.onAttempt?.({ provider: provider.name, stage: "success" });
+          cancelLosers.abort();
+          return;
+        }
+        attempts.push({ provider: provider.name, ok: false, errorClass: outcome.errorClass, ms });
+        const fallbackTo = next < ordered.length ? ordered[next].name : void 0;
+        options?.onAttempt?.({
+          provider: provider.name,
+          stage: fallbackTo ? "fallback" : "failure",
+          errorClass: outcome.errorClass,
+          fallbackTo
+        });
+        const cooldown = cooldownFor(outcome);
+        if (cooldown) health.cooldownUntil.set(provider.name, now() + cooldown);
+        logger.warn("ai provider failed", {
+          provider: provider.name,
+          errorClass: outcome.errorClass,
+          ms,
+          ...outcome.errorClass === "invalid_output" && rejected ? { reason: rejected.reason.slice(0, 160) } : {}
+        });
+        if (!outcome.retryable) stopped = true;
+      });
+      const tracked = run.finally(() => running.delete(tracked));
+      running.add(tracked);
+      return true;
+    };
+    try {
+      while (!result && !external?.aborted) {
+        if (running.size === 0 && !launch()) break;
+        let timer;
+        const racers = [...running, aborted];
+        if (deps.hedgeAfterMs !== void 0 && next < ordered.length) {
+          racers.push(new Promise((resolve) => timer = setTimeout(() => resolve(HEDGE), deps.hedgeAfterMs)));
+        }
+        const first = await Promise.race(racers);
+        clearTimeout(timer);
+        if (first === HEDGE) launch();
+      }
+    } finally {
+      if (onAbort) external?.removeEventListener("abort", onAbort);
+    }
+    if (result) return result;
+    if (external?.aborted) return { ok: false, provider: null, errorClass: "aborted", attempts, rejected };
+    return { ok: false, provider: null, errorClass: attempts[attempts.length - 1]?.errorClass ?? "deadline", attempts, rejected };
+  }
+  return { generate };
+}
+function httpOutcome(status) {
+  return { ok: false, errorClass: `http_${status}`, retryable: true, status };
+}
+var FREE_SUFFIX = ":free";
+function openRouterProvider(config) {
+  const model = config.model || DEFAULT_TEXT_MODELS.blog.openrouter;
+  const client = createOpenAI({
+    apiKey: config.apiKey,
+    baseURL: config.baseUrl || "https://openrouter.ai/api/v1",
+    fetch: config.fetch
+  });
+  return {
+    name: config.name ?? "openrouter",
+    async generate(prompt, options) {
+      if (!config.allowPaidModels && !model.endsWith(FREE_SUFFIX)) {
+        return { ok: false, errorClass: "paid_model_blocked", retryable: true };
+      }
+      return sdkGenerate(client.chat(model), prompt, options);
+    }
+  };
+}
+async function sdkGenerate(model, prompt, options) {
+  try {
+    const result = await generateText({
+      model,
+      system: prompt.system,
+      prompt: prompt.user,
+      maxOutputTokens: options?.maxTokens ?? 1200,
+      maxRetries: 0,
+      abortSignal: options?.signal
+    });
+    if (!result.text) return { ok: false, errorClass: "empty_response", retryable: true };
+    if (result.finishReason === "length") return { ok: false, errorClass: "truncated", retryable: true };
+    return { ok: true, text: result.text };
+  } catch (error) {
+    const status = error?.statusCode ?? error?.status;
+    if (status) return httpOutcome(status);
+    return { ok: false, errorClass: options?.signal?.aborted ? "timeout" : "provider_error", retryable: true };
+  }
+}
+function openAiCompatibleProvider(config) {
+  const client = createOpenAI({ apiKey: config.apiKey, baseURL: config.baseUrl, headers: config.headers, fetch: config.fetch });
+  return {
+    name: config.name,
+    generate: (prompt, options) => sdkGenerate(client.chat(config.model), prompt, options)
+  };
+}
+function anthropicOutcome(data) {
+  const reply = data;
+  if (reply.stop_reason === "max_tokens") return { ok: false, errorClass: "truncated", retryable: true };
+  if (reply.stop_reason === "refusal") return { ok: false, errorClass: "refused", retryable: true };
+  const text = reply.content?.filter((block) => block.type === "text").map((block) => block.text ?? "").join("") ?? "";
+  if (!text) return { ok: false, errorClass: "empty_response", retryable: true };
+  return { ok: true, text };
+}
+function anthropicProvider(config) {
+  const fetchImpl = config.fetchImpl ?? fetch;
+  const base = (config.baseUrl || "https://api.anthropic.com").replace(/\/+$/, "");
+  return {
+    name: "anthropic",
+    async generate(prompt, options) {
+      try {
+        const system = options?.jsonMode ? `${prompt.system}
+
+Reply with one JSON value only, no prose and no code fences.` : prompt.system;
+        const response = await fetchImpl(`${base}/v1/messages`, {
+          method: "POST",
+          headers: { "content-type": "application/json", "x-api-key": config.apiKey, "anthropic-version": "2023-06-01" },
+          signal: options?.signal,
+          body: JSON.stringify({
+            model: config.model,
+            max_tokens: options?.maxTokens ?? 1800,
+            system,
+            messages: [{ role: "user", content: prompt.user }]
+          })
+        });
+        if (!response.ok) return httpOutcome(response.status);
+        return anthropicOutcome(await response.json());
+      } catch {
+        return { ok: false, errorClass: options?.signal?.aborted ? "timeout" : "transport", retryable: true };
+      }
+    }
+  };
+}
+function geminiOutcome(data) {
+  const candidate = data.candidates?.[0];
+  const text = candidate?.content?.parts?.filter((part) => !part.thought).map((part) => part.text ?? "").join("") ?? "";
+  if (candidate?.finishReason === "MAX_TOKENS") return { ok: false, errorClass: "truncated", retryable: true };
+  if (!text) return { ok: false, errorClass: "empty_response", retryable: true };
+  return { ok: true, text };
+}
+function geminiProvider(config) {
+  const model = config.model || DEFAULT_TEXT_MODELS.blog.gemini;
+  const fetchImpl = config.fetchImpl ?? fetch;
+  return {
+    name: "gemini",
+    async generate(prompt, options) {
+      try {
+        const maxOutputTokens = options?.maxTokens ?? 2400;
+        const generationConfig = {
+          maxOutputTokens,
+          thinkingConfig: thinkingConfigFor(model, maxOutputTokens),
+          ...jsonConfig(options?.jsonMode)
+        };
+        let response = await fetchImpl(
+          `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent`,
+          {
+            method: "POST",
+            // Header, not ?key=: query strings end up in proxy and access logs.
+            headers: { "content-type": "application/json", "x-goog-api-key": config.apiKey },
+            signal: options?.signal,
+            body: JSON.stringify({
+              systemInstruction: { parts: [{ text: prompt.system }] },
+              contents: [{ role: "user", parts: [{ text: prompt.user }] }],
+              generationConfig
+            })
+          }
+        );
+        if (response.status === 503 && !options?.signal?.aborted) {
+          await new Promise((r) => setTimeout(r, 500));
+          if (!options?.signal?.aborted) {
+            response = await fetchImpl(
+              `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent`,
+              {
+                method: "POST",
+                headers: { "content-type": "application/json", "x-goog-api-key": config.apiKey },
+                signal: options?.signal,
+                body: JSON.stringify({
+                  systemInstruction: { parts: [{ text: prompt.system }] },
+                  contents: [{ role: "user", parts: [{ text: prompt.user }] }],
+                  generationConfig
+                })
+              }
+            );
+          }
+        }
+        if (!response.ok) return httpOutcome(response.status);
+        return geminiOutcome(await response.json());
+      } catch {
+        return { ok: false, errorClass: options?.signal?.aborted ? "timeout" : "transport", retryable: true };
+      }
+    }
+  };
+}
+function vertexProvider(config) {
+  const model = config.model || DEFAULT_TEXT_MODELS.blog.vertex;
+  const location = config.location ?? (/^gemini-[3-9]/.test(model) ? "global" : "us-central1");
+  const host = location === "global" ? "aiplatform.googleapis.com" : `${location}-aiplatform.googleapis.com`;
+  const fetchImpl = config.fetchImpl ?? fetch;
+  return {
+    name: "vertex",
+    lastResort: true,
+    async generate(prompt, options) {
+      try {
+        const accessToken = await getVertexAccessToken(
+          { clientEmail: config.clientEmail, privateKey: config.privateKey, tokenUri: config.tokenUri },
+          fetchImpl
+        );
+        const response = await fetchImpl(
+          `https://${host}/v1/projects/${config.project}/locations/${location}/publishers/google/models/${model}:generateContent`,
+          {
+            method: "POST",
+            headers: { "content-type": "application/json", authorization: `Bearer ${accessToken}` },
+            signal: options?.signal,
+            body: JSON.stringify({
+              systemInstruction: { parts: [{ text: prompt.system }] },
+              contents: [{ role: "user", parts: [{ text: prompt.user }] }],
+              generationConfig: {
+                maxOutputTokens: options?.maxTokens ?? 1800,
+                thinkingConfig: thinkingConfigFor(model, options?.maxTokens ?? 1800),
+                ...jsonConfig(options?.jsonMode)
+              }
+            })
+          }
+        );
+        if (!response.ok) return httpOutcome(response.status);
+        return geminiOutcome(await response.json());
+      } catch {
+        return { ok: false, errorClass: "transport", retryable: true };
+      }
+    }
+  };
+}
+
+// src/adapters.ts
+function modelFor(env, provider, purpose, fallback) {
+  const record = env;
+  return record[`${purpose.toUpperCase()}_${provider}_MODEL`] || record[`${provider}_MODEL`] || fallback[purpose];
+}
+var need = (env, ...names) => names.filter((name) => !env[name]);
+var PAID_TEXT_MODELS = {
+  openai: { blog: "gpt-5-mini", chat: "gpt-5-nano" },
+  anthropic: { blog: "claude-sonnet-5-5", chat: "claude-haiku-4-5-20251001" },
+  deepseek: { blog: "deepseek-chat", chat: "deepseek-chat" },
+  xai: { blog: "grok-3-mini", chat: "grok-3-mini" },
+  perplexity: { blog: "sonar", chat: "sonar" }
+};
+function compatibleAdapter(spec) {
+  return {
+    id: spec.id,
+    label: spec.label,
+    paid: () => true,
+    missing: (env) => need(env, spec.keyVar),
+    create: ({ env, purpose, fetch: fetch2 }) => openAiCompatibleProvider({
+      name: spec.id,
+      apiKey: env[spec.keyVar],
+      baseUrl: spec.baseUrlVar && env[spec.baseUrlVar] || spec.baseUrl,
+      model: modelFor(env, spec.envPrefix, purpose, PAID_TEXT_MODELS[spec.id]),
+      fetch: fetch2
+    })
+  };
+}
+var openRouterAdapter = (id, keyVar) => ({
+  id,
+  label: id === "openrouter" ? "OpenRouter" : "OpenRouter (second key)",
+  // Free models only, unless OPENROUTER_ALLOW_PAID_MODELS: the adapter itself refuses a paid model id.
+  paid: () => false,
+  missing: (env) => need(env, keyVar),
+  create: ({ env, purpose, fetch: fetch2 }) => openRouterProvider({
+    apiKey: env[keyVar],
+    model: textModels(env, purpose).openrouter,
+    baseUrl: env.OPENROUTER_BASE_URL,
+    allowPaidModels: env.OPENROUTER_ALLOW_PAID_MODELS,
+    fetch: fetch2,
+    name: id
+  })
+});
+var BUILTIN_ADAPTERS = [
+  {
+    id: "gemini",
+    label: "Gemini",
+    paid: () => false,
+    missing: (env) => need(env, "GEMINI_API_KEY"),
+    create: ({ env, purpose, fetch: fetch2 }) => geminiProvider({ apiKey: env.GEMINI_API_KEY, model: textModels(env, purpose).gemini, fetchImpl: fetch2 })
+  },
+  openRouterAdapter("openrouter", "OPENROUTER_API_KEY"),
+  openRouterAdapter("openrouter-2", "OPENROUTER_API_KEY_2"),
+  {
+    id: "nvidia",
+    label: "NVIDIA",
+    paid: () => false,
+    missing: (env) => need(env, "NVIDIA_API_KEY"),
+    create: ({ env, purpose, fetch: fetch2 }) => openAiCompatibleProvider({
+      name: "nvidia",
+      apiKey: env.NVIDIA_API_KEY,
+      baseUrl: "https://integrate.api.nvidia.com/v1",
+      model: textModels(env, purpose).nvidia,
+      fetch: fetch2
+    })
+  },
+  compatibleAdapter({ id: "openai", label: "OpenAI", envPrefix: "OPENAI", keyVar: "OPENAI_API_KEY", baseUrl: "https://api.openai.com/v1", baseUrlVar: "OPENAI_BASE_URL" }),
+  {
+    id: "anthropic",
+    label: "Anthropic (Claude)",
+    paid: () => true,
+    missing: (env) => need(env, "ANTHROPIC_API_KEY"),
+    create: ({ env, purpose, fetch: fetch2 }) => anthropicProvider({
+      apiKey: env.ANTHROPIC_API_KEY,
+      baseUrl: env.ANTHROPIC_BASE_URL,
+      model: modelFor(env, "ANTHROPIC", purpose, PAID_TEXT_MODELS.anthropic),
+      fetchImpl: fetch2
+    })
+  },
+  compatibleAdapter({ id: "deepseek", label: "DeepSeek", envPrefix: "DEEPSEEK", keyVar: "DEEPSEEK_API_KEY", baseUrl: "https://api.deepseek.com/v1" }),
+  compatibleAdapter({ id: "xai", label: "xAI (Grok)", envPrefix: "XAI", keyVar: "XAI_API_KEY", baseUrl: "https://api.x.ai/v1" }),
+  compatibleAdapter({ id: "perplexity", label: "Perplexity", envPrefix: "PERPLEXITY", keyVar: "PERPLEXITY_API_KEY", baseUrl: "https://api.perplexity.ai" }),
+  {
+    id: "custom",
+    label: "Custom OpenAI-compatible",
+    paid: (env) => !env.AI_CUSTOM_FREE,
+    missing: (env) => need(env, "AI_CUSTOM_BASE_URL", "AI_CUSTOM_MODEL"),
+    create: ({ env, fetch: fetch2 }) => openAiCompatibleProvider({
+      name: env.AI_CUSTOM_NAME ? `custom:${env.AI_CUSTOM_NAME}` : "custom",
+      // A local server may take no key; the header must still be well formed.
+      apiKey: env.AI_CUSTOM_API_KEY ?? "none",
+      baseUrl: env.AI_CUSTOM_BASE_URL,
+      model: env.AI_CUSTOM_MODEL,
+      fetch: fetch2
+    })
+  },
+  {
+    id: "vertex",
+    label: "Vertex AI",
+    paid: () => true,
+    missing: (env) => vertexConfigured(env) ? [] : need(env, "GOOGLE_CLIENT_EMAIL", "GOOGLE_PRIVATE_KEY", "GOOGLE_CLOUD_PROJECT"),
+    create: ({ env, purpose, fetch: fetch2 }) => vertexProvider({
+      clientEmail: env.GOOGLE_CLIENT_EMAIL,
+      privateKey: env.GOOGLE_PRIVATE_KEY,
+      tokenUri: env.GOOGLE_TOKEN_URI,
+      project: env.GOOGLE_CLOUD_PROJECT,
+      model: textModels(env, purpose).vertex,
+      fetchImpl: fetch2
+    })
+  }
+];
+var DEFAULT_ORDER = BUILTIN_ADAPTERS.map((adapter) => adapter.id);
+function configuredOrder(env, purpose) {
+  const raw = (purpose === "blog" ? env.AI_PROVIDER_ORDER_BLOG : env.AI_PROVIDER_ORDER_CHAT) ?? env.AI_PROVIDER_ORDER;
+  if (!raw) return null;
+  const ids = raw.split(",").map((id) => id.trim().toLowerCase()).filter(Boolean);
+  return ids.length ? [...new Set(ids)] : null;
+}
+function providerStatuses(env, purpose, adapters = BUILTIN_ADAPTERS) {
+  const order = configuredOrder(env, purpose);
+  const ids = order ?? adapters.map((adapter) => adapter.id);
+  const byId = new Map(adapters.map((adapter) => [adapter.id, adapter]));
+  let position = 0;
+  const statuses = [];
+  for (const id of ids) {
+    const adapter = byId.get(id);
+    if (!adapter) {
+      statuses.push({ id, label: id, paid: false, state: "unknown", missing: [] });
+      continue;
+    }
+    const missing = adapter.missing(env);
+    const paid = adapter.paid(env);
+    const state = missing.length ? "not_configured" : paid && !paidAllowed(env) ? "needs_paid" : "active";
+    statuses.push({ id, label: adapter.label, paid, state, missing, ...state === "active" ? { position: position++ } : {} });
+  }
+  for (const adapter of adapters) {
+    if (!ids.includes(adapter.id)) {
+      statuses.push({ id: adapter.id, label: adapter.label, paid: adapter.paid(env), state: "not_in_order", missing: adapter.missing(env) });
+    }
+  }
+  return statuses;
+}
+function chainPlan(env, purpose, adapters = BUILTIN_ADAPTERS) {
+  const byId = new Map(adapters.map((adapter) => [adapter.id, adapter]));
+  return providerStatuses(env, purpose, adapters).filter((status) => status.state === "active").map((status) => byId.get(status.id));
+}
+var CHECK_PROMPT = { system: "You are a connectivity check. Reply with the single word OK.", user: "Reply with OK." };
+async function checkProvider(env, id, options = {}) {
+  const now = options.now ?? Date.now;
+  const adapter = (options.adapters ?? BUILTIN_ADAPTERS).find((candidate) => candidate.id === id);
+  if (!adapter) return { id, ok: false, errorClass: "unknown_provider", ms: 0 };
+  if (adapter.missing(env).length) return { id, ok: false, errorClass: "not_configured", ms: 0 };
+  const started = now();
+  try {
+    const provider = adapter.create({ env, purpose: options.purpose ?? "chat", fetch: options.fetch });
+    const outcome = await provider.generate(CHECK_PROMPT, { maxTokens: 32, signal: AbortSignal.timeout(options.timeoutMs ?? 2e4) });
+    return outcome.ok ? { id, ok: true, provider: provider.name, ms: now() - started } : { id, ok: false, provider: provider.name, errorClass: outcome.errorClass, ms: now() - started };
+  } catch {
+    return { id, ok: false, errorClass: "transport", ms: now() - started };
+  }
+}
+async function checkChain(env, purpose, options = {}) {
+  const now = options.now ?? Date.now;
+  const id = `chain:${purpose}`;
+  const providers = realProviders(env, purpose, options.fetch, options.adapters);
+  if (providers.length === 0) return { id, ok: false, errorClass: "no_provider", ms: 0, attempts: [] };
+  const started = now();
+  const result = await createAiService({
+    providers,
+    timeoutMs: 15e3,
+    deadlineMs: options.deadlineMs ?? 4e4,
+    logger: { warn: () => void 0 }
+  }).generate(CHECK_PROMPT, { maxTokens: 32 });
+  return {
+    id,
+    ok: result.ok,
+    ...result.provider ? { provider: result.provider } : {},
+    ...result.ok ? {} : { errorClass: result.errorClass },
+    ms: now() - started,
+    attempts: result.attempts.map(({ provider, ok, errorClass }) => ({ provider, ok, ...errorClass ? { errorClass } : {} }))
+  };
+}
+function realProviders(env, purpose, fetchImpl, adapters = BUILTIN_ADAPTERS) {
+  const explicit = configuredOrder(env, purpose) !== null;
+  return chainPlan(env, purpose, adapters).map((adapter, index) => {
+    const provider = adapter.create({ env, purpose, fetch: fetchImpl });
+    return explicit ? { name: provider.name, generate: provider.generate, priority: index } : { name: provider.name, generate: provider.generate, lastResort: adapter.paid(env) || provider.lastResort };
+  });
+}
+export {
+  BUILTIN_ADAPTERS,
+  CHECK_PROMPT,
+  DEFAULT_ORDER,
+  PAID_TEXT_MODELS,
+  chainPlan,
+  checkChain,
+  checkProvider,
+  configuredOrder,
+  providerStatuses,
+  realProviders
+};

package/dist/availability.d.ts

@@ -1,9 +1,14 @@
 import { AiEnv } from './env.js';
+import { TextPurpose } from './models.js';
 import 'zod';
 
-/** At least one text provider can answer: a free key, or Vertex with AI_ALLOW_PAID. */
-declare function textAiConfigured(env: AiEnv): boolean;
-/** The blog AI assistant: ENABLE_BLOG_AI=true (off by default) and a text provider. */
+/**
+ * At least one text provider can answer for the purpose (both when omitted):
+ * configured, in AI_PROVIDER_ORDER when one is set, and paid ones only with
+ * AI_ALLOW_PAID (./adapters).
+ */
+declare function textAiConfigured(env: AiEnv, purpose?: TextPurpose): boolean;
+/** The blog AI assistant: ENABLE_BLOG_AI=true (off by default) and a blog text provider. */
 declare function blogAiEnabled(env: AiEnv): boolean;
 /** Blog AI images (featured and inline): blog AI plus at least one image provider. */
 declare function blogAiImagesEnabled(env: AiEnv): boolean;