@sahan-sac/ai-core 0.1.0

package/dist/image.js

@@ -0,0 +1,246 @@
+// src/image.ts
+import "server-only";
+
+// src/models.ts
+var DEFAULT_IMAGE_MODELS = {
+  nvidia: "black-forest-labs/flux.1-dev",
+  gemini: "gemini-3.1-flash-image",
+  vertex: "gemini-3.1-flash-image"
+};
+var pick = (...values) => values.find((value) => value && value.trim()).trim();
+function imageModels(env) {
+  return {
+    nvidia: pick(env.IMAGE_NVIDIA_MODEL, DEFAULT_IMAGE_MODELS.nvidia),
+    gemini: pick(env.IMAGE_GEMINI_MODEL, DEFAULT_IMAGE_MODELS.gemini),
+    vertex: pick(env.IMAGE_VERTEX_MODEL, env.IMAGEN_MODEL, DEFAULT_IMAGE_MODELS.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);
+}
+
+// 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/image.ts
+var DEFAULT_IMAGE_MODELS2 = [
+  { model: "gemini-3.1-flash-image", location: "global" },
+  { model: "gemini-2.5-flash-image", location: "us-central1" }
+];
+function defaultLocation(model) {
+  return /^gemini-3/.test(model) ? "global" : "us-central1";
+}
+function imageModelChain(config) {
+  const chain = config.model ? [{ model: config.model, location: config.location ?? defaultLocation(config.model) }] : [];
+  for (const candidate of DEFAULT_IMAGE_MODELS2) {
+    if (!chain.some((entry) => entry.model === candidate.model)) chain.push(candidate);
+  }
+  return chain;
+}
+function endpoint(project, target, method) {
+  const host = target.location === "global" ? "aiplatform.googleapis.com" : `${target.location}-aiplatform.googleapis.com`;
+  return `https://${host}/v1/projects/${project}/locations/${target.location}/publishers/google/models/${target.model}:${method}`;
+}
+function requestFor(target, prompt, aspectRatio) {
+  if (target.model.startsWith("imagen-")) {
+    return {
+      method: "predict",
+      body: {
+        instances: [{ prompt }],
+        parameters: { sampleCount: 1, aspectRatio, safetySetting: "block_medium_and_above", personGeneration: "allow_adult" }
+      }
+    };
+  }
+  return {
+    method: "generateContent",
+    body: {
+      contents: [{ role: "user", parts: [{ text: prompt }] }],
+      generationConfig: { responseModalities: ["IMAGE"], imageConfig: { aspectRatio } }
+    }
+  };
+}
+function extractImage(data) {
+  const prediction = data?.predictions?.[0];
+  if (prediction?.bytesBase64Encoded) return { base64: prediction.bytesBase64Encoded, mimeType: prediction.mimeType || "image/png" };
+  const parts = data?.candidates?.[0]?.content?.parts;
+  const inline = parts?.find((part) => part.inlineData?.data)?.inlineData;
+  return inline?.data ? { base64: inline.data, mimeType: inline.mimeType || "image/png" } : null;
+}
+async function generateImageVertex(prompt, config, options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const aspectRatio = options.aspectRatio ?? "16:9";
+  let accessToken;
+  try {
+    accessToken = await getVertexAccessToken(
+      { clientEmail: config.clientEmail, privateKey: config.privateKey, tokenUri: config.tokenUri },
+      fetchImpl
+    );
+  } catch (error) {
+    return { ok: false, error: `Image generation failed: ${error instanceof Error ? error.message : "authentication error"}` };
+  }
+  const failures = [];
+  for (const target of imageModelChain(config)) {
+    if (options.signal?.aborted) return { ok: false, error: "Image generation timed out." };
+    const { method, body } = requestFor(target, prompt, aspectRatio);
+    try {
+      const response = await fetchImpl(endpoint(config.project, target, method), {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${accessToken}` },
+        signal: options.signal,
+        body: JSON.stringify(body)
+      });
+      if (!response.ok) {
+        failures.push(`${target.model}: HTTP ${response.status}`);
+        continue;
+      }
+      const image = extractImage(await response.json());
+      if (image) return { ok: true, ...image };
+      failures.push(`${target.model}: no image data`);
+    } catch (error) {
+      if (options.signal?.aborted) return { ok: false, error: "Image generation timed out." };
+      failures.push(`${target.model}: ${error instanceof Error ? error.message : "transport error"}`);
+    }
+  }
+  return { ok: false, error: `Image generation failed (${failures.join("; ")}).` };
+}
+function vertexImageAvailable(env) {
+  return vertexConfigured(env);
+}
+var FLUX_SIZE = {
+  "16:9": { width: 1344, height: 768 },
+  "4:3": { width: 1024, height: 768 },
+  "1:1": { width: 1024, height: 1024 }
+};
+function nvidiaImageRequest(model, prompt, aspectRatio, seed) {
+  const size = FLUX_SIZE[aspectRatio];
+  if (/schnell/.test(model)) return { prompt, ...size, steps: 4, seed };
+  return { prompt, ...size, steps: 30, cfg_scale: 3.5, mode: "base", seed };
+}
+function extractNvidiaImage(data) {
+  const artifact = data?.artifacts?.[0];
+  if (!artifact?.base64 || artifact.finishReason && artifact.finishReason !== "SUCCESS") return null;
+  const mimeType = artifact.base64.startsWith("/9j/") ? "image/jpeg" : artifact.base64.startsWith("UklG") ? "image/webp" : "image/png";
+  return { base64: artifact.base64, mimeType };
+}
+async function postForImage(model, url, init, extract, options) {
+  try {
+    const response = await (options.fetchImpl ?? fetch)(url, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...init.headers },
+      signal: options.signal,
+      body: JSON.stringify(init.body)
+    });
+    if (!response.ok) return { ok: false, error: `${model}: HTTP ${response.status}` };
+    const image = extract(await response.json());
+    return image ? { ok: true, ...image } : { ok: false, error: `${model}: no image (filtered or empty)` };
+  } catch (error) {
+    if (options.signal?.aborted) return { ok: false, error: "Image generation timed out." };
+    return { ok: false, error: `${model}: ${error instanceof Error ? error.message : "transport error"}` };
+  }
+}
+function generateImageNvidia(prompt, config, aspectRatio, options) {
+  return postForImage(
+    config.model,
+    `https://ai.api.nvidia.com/v1/genai/${config.model}`,
+    {
+      headers: { authorization: `Bearer ${config.apiKey}`, accept: "application/json" },
+      body: nvidiaImageRequest(config.model, prompt, aspectRatio, Math.floor(Math.random() * 2 ** 31))
+    },
+    extractNvidiaImage,
+    options
+  );
+}
+function generateImageGemini(prompt, config, aspectRatio, options) {
+  return postForImage(
+    config.model,
+    `https://generativelanguage.googleapis.com/v1beta/models/${config.model}:generateContent`,
+    {
+      headers: { "x-goog-api-key": config.apiKey },
+      body: { contents: [{ role: "user", parts: [{ text: prompt }] }], generationConfig: { responseModalities: ["IMAGE"], imageConfig: { aspectRatio } } }
+    },
+    extractImage,
+    options
+  );
+}
+function imageConfigFromEnv(env) {
+  const models = imageModels(env);
+  const paid = paidAllowed(env);
+  const config = {};
+  if (env.NVIDIA_API_KEY) config.nvidia = { apiKey: env.NVIDIA_API_KEY, model: models.nvidia };
+  if (paid && env.GEMINI_API_KEY) config.gemini = { apiKey: env.GEMINI_API_KEY, model: models.gemini };
+  if (paid && vertexImageAvailable(env)) {
+    config.vertex = {
+      clientEmail: env.GOOGLE_CLIENT_EMAIL,
+      privateKey: env.GOOGLE_PRIVATE_KEY,
+      tokenUri: env.GOOGLE_TOKEN_URI,
+      project: env.GOOGLE_CLOUD_PROJECT,
+      model: models.vertex
+    };
+  }
+  return config.nvidia || config.gemini || config.vertex ? config : null;
+}
+async function generateImage(prompt, config, options = {}) {
+  const aspectRatio = options.aspectRatio ?? "16:9";
+  const attempts = [];
+  if (config.nvidia) attempts.push(() => generateImageNvidia(prompt, config.nvidia, aspectRatio, options));
+  if (config.gemini) attempts.push(() => generateImageGemini(prompt, config.gemini, aspectRatio, options));
+  if (config.vertex) attempts.push(() => generateImageVertex(prompt, config.vertex, options));
+  const failures = [];
+  for (const run of attempts) {
+    if (options.signal?.aborted) return { ok: false, error: "Image generation timed out." };
+    const outcome = await run();
+    if (outcome.ok) return outcome;
+    failures.push(outcome.error);
+  }
+  return { ok: false, error: failures.length ? `Image generation failed (${failures.join("; ")}).` : "No image provider is configured." };
+}
+export {
+  DEFAULT_IMAGE_MODELS2 as DEFAULT_IMAGE_MODELS,
+  extractImage,
+  extractNvidiaImage,
+  generateImage,
+  generateImageVertex,
+  imageConfigFromEnv,
+  imageModelChain,
+  nvidiaImageRequest,
+  vertexImageAvailable
+};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { AiEnv, aiEnvFromProcess, aiEnvSchema, parseAiEnv } from './env.js';
+export { ImageModels, TextModels, TextPurpose } from './models.js';
+export { AiHealth, AiProvider, AiResult } from './providers.js';
+export { ModelPrompt } from './guard.js';
+export { AiLogger } from './log.js';
+import 'zod';

package/dist/index.js

@@ -0,0 +1,68 @@
+// src/env.ts
+import { z } from "zod";
+var text = z.string().optional().transform((value) => {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : void 0;
+});
+var ON = ["1", "true", "yes", "on"];
+var flag = z.string().optional().transform((value) => ON.includes((value ?? "").trim().toLowerCase()));
+var flagDefaultOn = z.string().optional().transform((value) => {
+  const normalized = (value ?? "").trim().toLowerCase();
+  return normalized === "" || ON.includes(normalized);
+});
+var privateKey = text.transform((value) => value?.replace(/\\n/g, "\n"));
+var DEFAULT_GOOGLE_TOKEN_URI = "https://oauth2.googleapis.com/token";
+var aiEnvSchema = z.object({
+  // Paid providers (Vertex text and images, Gemini images) join the chains
+  // only with AI_ALLOW_PAID; off by default, so AI costs $0.
+  AI_ALLOW_PAID: flag,
+  // Feature switches. The blog assistant is off until turned on; the chatbot
+  // is on unless turned off. Each also needs a text provider key.
+  ENABLE_BLOG_AI: flag,
+  ENABLE_CHATBOT: flagDefaultOn,
+  OPENROUTER_BASE_URL: text,
+  OPENROUTER_API_KEY: text,
+  OPENROUTER_API_KEY_2: text,
+  OPENROUTER_ALLOW_PAID_MODELS: flag,
+  GEMINI_API_KEY: text,
+  NVIDIA_API_KEY: text,
+  // Model overrides, all optional (models.ts): purpose variable, then the
+  // provider-wide *_MODEL, then a verified free default.
+  OPENROUTER_MODEL: text,
+  GEMINI_MODEL: text,
+  NVIDIA_MODEL: text,
+  VERTEX_MODEL: text,
+  IMAGEN_MODEL: text,
+  BLOG_GEMINI_MODEL: text,
+  BLOG_OPENROUTER_MODEL: text,
+  BLOG_NVIDIA_MODEL: text,
+  BLOG_VERTEX_MODEL: text,
+  CHAT_GEMINI_MODEL: text,
+  CHAT_OPENROUTER_MODEL: text,
+  CHAT_NVIDIA_MODEL: text,
+  CHAT_VERTEX_MODEL: text,
+  IMAGE_NVIDIA_MODEL: text,
+  IMAGE_GEMINI_MODEL: text,
+  IMAGE_VERTEX_MODEL: text,
+  // Google Vertex service account (paid).
+  GOOGLE_CLIENT_EMAIL: text,
+  GOOGLE_PRIVATE_KEY: privateKey,
+  GOOGLE_CLOUD_PROJECT: text,
+  GOOGLE_TOKEN_URI: text.transform((value) => value ?? DEFAULT_GOOGLE_TOKEN_URI)
+});
+function parseAiEnv(source) {
+  const result = aiEnvSchema.safeParse(source);
+  if (!result.success) {
+    const names = [...new Set(result.error.issues.map((issue) => String(issue.path[0] ?? "?")))];
+    throw new Error(`Invalid AI environment variables: ${names.join(", ")}`);
+  }
+  return result.data;
+}
+function aiEnvFromProcess() {
+  return parseAiEnv(process.env);
+}
+export {
+  aiEnvFromProcess,
+  aiEnvSchema,
+  parseAiEnv
+};

package/dist/log.d.ts

@@ -0,0 +1,6 @@
+interface AiLogger {
+    warn(message: string, meta?: Record<string, unknown>): void;
+}
+declare const consoleAiLogger: AiLogger;
+
+export { type AiLogger, consoleAiLogger };

package/dist/log.js

@@ -0,0 +1,9 @@
+// src/log.ts
+var consoleAiLogger = {
+  warn(message, meta) {
+    console.warn(JSON.stringify({ level: "warn", message, ...meta }));
+  }
+};
+export {
+  consoleAiLogger
+};

package/dist/models.d.ts

@@ -0,0 +1,59 @@
+type TextPurpose = "blog" | "chat";
+interface TextModels {
+    gemini: string;
+    openrouter: string;
+    nvidia: string;
+    vertex: string;
+}
+interface ImageModels {
+    nvidia: string;
+    gemini: string;
+    vertex: string;
+}
+/**
+ * Verified 2026-09-26 on free keys: gemini-2.5-flash 1.8 s valid JSON,
+ * gemini-3.1-flash-lite 1.6 s, nemotron-3-super-120b 5-7 s on both OpenRouter
+ * (":free") and NVIDIA; the older defaults (deepseek-v4.1-flash on NVIDIA,
+ * nemotron-3.5-lightning on OpenRouter) timed out or took 8 s+.
+ */
+declare const DEFAULT_TEXT_MODELS: Record<TextPurpose, TextModels>;
+/** FLUX.1-dev on NVIDIA's free API: 1344x768 in about 6 s (verified 2026-09-26). The Gemini ones are paid-only. */
+declare const DEFAULT_IMAGE_MODELS: ImageModels;
+/** The subset of the parsed env this module reads. */
+interface ModelEnv {
+    AI_ALLOW_PAID?: boolean;
+    GOOGLE_CLIENT_EMAIL?: string;
+    GOOGLE_PRIVATE_KEY?: string;
+    GOOGLE_CLOUD_PROJECT?: string;
+    GEMINI_MODEL?: string;
+    OPENROUTER_MODEL?: string;
+    NVIDIA_MODEL?: string;
+    VERTEX_MODEL?: string;
+    IMAGEN_MODEL?: string;
+    BLOG_GEMINI_MODEL?: string;
+    BLOG_OPENROUTER_MODEL?: string;
+    BLOG_NVIDIA_MODEL?: string;
+    BLOG_VERTEX_MODEL?: string;
+    CHAT_GEMINI_MODEL?: string;
+    CHAT_OPENROUTER_MODEL?: string;
+    CHAT_NVIDIA_MODEL?: string;
+    CHAT_VERTEX_MODEL?: string;
+    IMAGE_NVIDIA_MODEL?: string;
+    IMAGE_GEMINI_MODEL?: string;
+    IMAGE_VERTEX_MODEL?: string;
+}
+declare function textModels(env: ModelEnv, purpose: TextPurpose): TextModels;
+declare function imageModels(env: ModelEnv): ImageModels;
+/** Paid providers (Vertex, Gemini image) join a chain only when this is true. */
+declare const paidAllowed: (env: ModelEnv) => boolean;
+/** The Vertex service account is complete. Vertex still only runs with AI_ALLOW_PAID. */
+declare function vertexConfigured(env: ModelEnv): boolean;
+/**
+ * Gemini's thinking control differs by generation: 2.x takes a token budget
+ * (0 = off), 3.x rejects `thinkingBudget` with HTTP 400 and takes a level.
+ * Short replies get no thinking at all (it would eat a small output cap and
+ * return empty text); long structured output gets a little.
+ */
+declare function thinkingConfigFor(model: string, maxOutputTokens: number): Record<string, unknown>;
+
+export { DEFAULT_IMAGE_MODELS, DEFAULT_TEXT_MODELS, type ImageModels, type ModelEnv, type TextModels, type TextPurpose, imageModels, paidAllowed, textModels, thinkingConfigFor, vertexConfigured };

package/dist/models.js

@@ -0,0 +1,60 @@
+// 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 DEFAULT_IMAGE_MODELS = {
+  nvidia: "black-forest-labs/flux.1-dev",
+  gemini: "gemini-3.1-flash-image",
+  vertex: "gemini-3.1-flash-image"
+};
+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)
+  };
+}
+function imageModels(env) {
+  return {
+    nvidia: pick(env.IMAGE_NVIDIA_MODEL, DEFAULT_IMAGE_MODELS.nvidia),
+    gemini: pick(env.IMAGE_GEMINI_MODEL, DEFAULT_IMAGE_MODELS.gemini),
+    vertex: pick(env.IMAGE_VERTEX_MODEL, env.IMAGEN_MODEL, DEFAULT_IMAGE_MODELS.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 };
+}
+export {
+  DEFAULT_IMAGE_MODELS,
+  DEFAULT_TEXT_MODELS,
+  imageModels,
+  paidAllowed,
+  textModels,
+  thinkingConfigFor,
+  vertexConfigured
+};

package/dist/providers.d.ts

@@ -0,0 +1,157 @@
+import { AiEnv } from './env.js';
+import { TextPurpose } from './models.js';
+import { ModelPrompt } from './guard.js';
+import { AiLogger } from './log.js';
+import 'zod';
+
+type AiOutcome = {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    errorClass: string;
+    retryable: boolean;
+    status?: number;
+};
+interface AiGenerateOptions {
+    maxTokens?: number;
+    /** Aborted when the attempt times out, so a slow provider stops consuming a socket. */
+    signal?: AbortSignal;
+    /**
+     * JSON output. `true` asks for JSON (Gemini/Vertex responseMimeType); an
+     * object also passes a response schema, which Gemini/Vertex enforce while
+     * decoding, so the reply is always syntactically valid, correctly escaped
+     * JSON of that shape. Providers without the feature ignore it.
+     */
+    jsonMode?: JsonMode;
+}
+type JsonMode = boolean | {
+    schema: Record<string, unknown>;
+};
+interface AiProvider {
+    readonly name: string;
+    /** Paid or otherwise costly: tried only after every other provider, whatever its speed or health. */
+    readonly lastResort?: boolean;
+    generate(prompt: ModelPrompt, options?: AiGenerateOptions): Promise<AiOutcome>;
+}
+interface AiAttempt {
+    provider: string;
+    ok: boolean;
+    errorClass?: string;
+    ms: number;
+}
+interface AiResult {
+    ok: boolean;
+    provider: string | null;
+    text?: string;
+    errorClass?: string;
+    attempts: AiAttempt[];
+    /** The last reply `accept` turned down, kept so a caller can ask a model to repair it. */
+    rejected?: {
+        provider: string;
+        text: string;
+        reason: string;
+    };
+}
+declare const AI_TIMEOUT_MS = 25000;
+/** A provider that timed out or was rate limited goes to the back of the line for this long. */
+declare const AI_COOLDOWN_MS = 60000;
+/** What the chain has learned about each provider: when it may lead again, and how fast it answers. */
+interface AiHealth {
+    cooldownUntil: Map<string, number>;
+    latencyMs: Map<string, number>;
+}
+declare const createAiHealth: () => AiHealth;
+/** One per server instance, for request handlers; tests and scripts get a fresh one by default. */
+declare const sharedAiHealth: AiHealth;
+interface AiServiceDeps {
+    providers: readonly AiProvider[];
+    /** Per-provider attempt budget. */
+    timeoutMs?: number;
+    /** Whole-chain budget; the remaining time caps each later attempt. */
+    deadlineMs?: number;
+    /**
+     * Hedged requests: when the running attempt has not answered after this
+     * long, the next provider starts too and the first success wins (the
+     * others are aborted). Off by default, so attempts run one at a time.
+     */
+    hedgeAfterMs?: number;
+    health?: AiHealth;
+    now?: () => number;
+    /** Where provider failures are reported; defaults to one JSON line on stderr. */
+    logger?: AiLogger;
+}
+type AiAttemptStatus = {
+    provider: string;
+    stage: "start" | "failure" | "fallback" | "success";
+    errorClass?: string;
+    fallbackTo?: string;
+};
+declare const HEDGE: unique symbol;
+/**
+ * Tries providers until one succeeds, a non-retryable failure stops the chain,
+ * or the deadline passes. Healthy providers lead, fastest observed first;
+ * cooling ones go last instead of being dropped, so a request always gets a
+ * real attempt even when every provider is cooling.
+ */
+declare function createAiService(deps: AiServiceDeps): {
+    generate: (prompt: ModelPrompt, options?: {
+        maxTokens?: number;
+        jsonMode?: JsonMode;
+        onAttempt?: (status: AiAttemptStatus) => void;
+        /**
+         * Output check run on each reply before it counts as a success: return
+         * null to accept, or a reason to treat the reply as that provider's
+         * failure. With hedging on, this is what stops a fast but broken reply
+         * (malformed JSON from a weak model) from beating a slower valid one.
+         */
+        accept?: (text: string) => string | null;
+    }) => Promise<AiResult>;
+};
+/** OpenRouter, OpenAI-compatible. Refuses a paid model id unless the owner opted in. */
+declare function openRouterProvider(config: {
+    apiKey: string;
+    model?: string;
+    baseUrl?: string;
+    allowPaidModels: boolean;
+    fetch?: typeof fetch;
+    name?: string;
+}): AiProvider;
+/** NVIDIA NIM, OpenAI-compatible. */
+declare function nvidiaProvider(config: {
+    apiKey: string;
+    model?: string;
+    fetch?: typeof fetch;
+}): AiProvider;
+/** Text of a Gemini/Vertex generateContent reply; a reply stopped at the token cap is "truncated", not a success. */
+declare function geminiOutcome(data: unknown): AiOutcome;
+/** Gemini's own REST API (not OpenAI-compatible), called directly so no extra SDK is added for one provider. */
+declare function geminiProvider(config: {
+    apiKey: string;
+    model?: string;
+    fetchImpl?: typeof fetch;
+}): AiProvider;
+/** Google Vertex AI's Gemini endpoint, authenticated with a service-account JWT
+ * (lib/ai/vertex.ts) instead of an API key. Last resort in the chain: it is the
+ * slowest to authenticate (a token exchange before every cold call) and the
+ * most involved to configure correctly, so faster, simpler providers go first. */
+declare function vertexProvider(config: {
+    clientEmail: string;
+    privateKey: string;
+    tokenUri: string;
+    project: string;
+    location?: string;
+    model?: string;
+    fetchImpl?: typeof fetch;
+}): AiProvider;
+/**
+ * The chain from decision D15, free tiers first and paid last:
+ * 1. Gemini (free API key, fast)
+ * 2. OpenRouter (free-tier models, heavily rate-limited)
+ * 3. NVIDIA (free developer API; key may be dead or model retired)
+ * 4. Vertex (pay-as-you-go): only with AI_ALLOW_PAID, and only after the free ones
+ * Models per purpose come from lib/ai/models.ts (env override, else a verified free default).
+ */
+declare function realProviders(env: AiEnv, purpose: TextPurpose, fetchImpl?: typeof fetch): AiProvider[];
+
+export { AI_COOLDOWN_MS, AI_TIMEOUT_MS, type AiAttempt, type AiAttemptStatus, type AiGenerateOptions, type AiHealth, type AiOutcome, type AiProvider, type AiResult, type AiServiceDeps, HEDGE, type JsonMode, createAiHealth, createAiService, geminiOutcome, geminiProvider, nvidiaProvider, openRouterProvider, realProviders, sharedAiHealth, vertexProvider };