@sahan-sac/ai-core 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @sahan-sac/ai-core
 
+## 0.3.1
+
+### Patch Changes
+
+- 5e7f3cb: The build shares modules between subpaths (code splitting) instead of copying them into each one. Before, a class imported from two subpaths was two different classes, so `instanceof` failed (for example `EmailGuardError` from `@sahan-sac/email-kit/guards` against an error thrown through `./layout`), and module-level state such as caches existed once per subpath.
+
+## 0.3.0
+
+### Minor Changes
+
+- b9d2dd6: `createAiService().generate()` takes an optional `signal`. Aborting it stops the chain at once: running attempts are aborted, no further provider starts, and the result is `errorClass: "aborted"`. Aborted attempts are not logged and do not put a provider into cooldown.
+- 4fa21e3: Provider registry and more providers. New `@sahan-sac/ai-core/adapters`: each provider is an adapter with its own env guard and paid flag (`BUILTIN_ADAPTERS`), and `realProviders` builds the chain from it. Added OpenAI, Anthropic (Messages API over REST), DeepSeek, xAI, Perplexity and one custom OpenAI-compatible endpoint (`AI_CUSTOM_*`), all paid and gated by `AI_ALLOW_PAID` (the custom one unless `AI_CUSTOM_FREE`). `AI_PROVIDER_ORDER`, `AI_PROVIDER_ORDER_BLOG` and `AI_PROVIDER_ORDER_CHAT` choose which providers run and in what order; an explicit order is kept as given (`AiProvider.priority`), while cooling providers still drop behind healthy ones. `providerStatuses` explains each adapter's place for health screens, `textAiConfigured(env, purpose?)` checks one purpose's chain, and apps can pass their own adapters to `realProviders`. New factories `openAiCompatibleProvider` and `anthropicProvider`. Existing variables and `realProviders(env, purpose, fetch?)` work as before.
+- f465908: Owner guidance and on-demand checks. `@sahan-sac/ai-core/guard` adds `guidanceSection(text)`, which appends the site owner's standing guidance after a prompt's fixed rules (it steers, never overrides them, and never changes how fenced data is treated), `mergeGuidance(...parts)` to join global and per-feature guidance, and an optional `maxLength` on `wrapUserData`. `@sahan-sac/ai-core/adapters` adds `checkProvider(env, id)` and `checkChain(env, purpose)`: each sends a one-line prompt (a few tokens) through one adapter or a whole chain and reports who answered, how long it took and every fall-through, for a health screen's manual Check button. Neither runs on its own, and neither cools a provider down for real traffic.
+
 ## 0.2.0
 
 No changes in this release.

package/README.md

@@ -1,23 +1,41 @@
 # @sahan-sac/ai-core
 
-The AI layer shared by `@sahan-sac/blog-kit` and `@sahan-sac/chat-kit`: a free-by-default provider chain (Gemini, OpenRouter, NVIDIA, then paid Vertex), model resolution from environment variables, image generation (NVIDIA FLUX, then paid Gemini/Vertex), and prompt-injection guards.
+The AI layer shared by `@sahan-sac/blog-kit` and `@sahan-sac/chat-kit`: a free-by-default provider chain with automatic fallback, a provider registry you can configure and extend from the environment, model resolution, image generation (NVIDIA FLUX, then paid Gemini/Vertex), and prompt-injection guards.
 
 Headless and framework-agnostic: no Prisma, no Next.js APIs, no React. Everything takes a parsed env or config object; only `aiEnvFromProcess()` reads `process.env`.
 
+## How a request is answered
+
+Two patterns, kept separate:
+
+- **Adapters.** Every provider is wrapped as an `AiProvider` with one `generate(prompt, options)` that returns `{ ok: true, text }` or a classified failure (`http_429`, `timeout`, `truncated`, `invalid_output`, ...). It never throws. Built in: Gemini, OpenRouter (two keys), NVIDIA, OpenAI, Anthropic (Claude), DeepSeek, xAI (Grok), Perplexity, one custom OpenAI-compatible endpoint (vLLM, Ollama, LiteLLM, a gateway), and Vertex AI.
+- **Chain of responsibility.** `createAiService({ providers })` hands the prompt to the first provider. On any retryable failure it passes the prompt to the next one, until one answers, a non-retryable failure stops it, the deadline passes, or the caller aborts. On top of that:
+  - a provider that timed out or was rate limited cools down and moves behind the healthy ones;
+  - optional hedging starts the next provider while a slow one is still running, and the first valid answer wins;
+  - an `accept` check turns a malformed reply into a failure, so the chain moves on.
+
+The registry (`@sahan-sac/ai-core/adapters`) decides which adapters form a chain and in what order:
+
+1. `AI_PROVIDER_ORDER_BLOG` or `AI_PROVIDER_ORDER_CHAT` for that purpose, else `AI_PROVIDER_ORDER`, else the default order: `gemini, openrouter, openrouter-2, nvidia, openai, anthropic, deepseek, xai, perplexity, custom, vertex`.
+2. An adapter runs only when its variables are set. A paid adapter also needs `AI_ALLOW_PAID=true`, even when it is listed.
+3. **Explicit order:** only the listed ids run, in that order. Speed never reorders them; cooling still does.
+4. **Default order:** paid adapters are last resorts, and the free ones are reordered by observed speed.
+
 ## Subpaths
 
 | Import | What |
 | --- | --- |
 | `@sahan-sac/ai-core/env` | `aiEnvSchema` (zod), `parseAiEnv(source)`, `aiEnvFromProcess()`, `AiEnv` |
-| `@sahan-sac/ai-core/availability` | `textAiConfigured`, `blogAiEnabled`, `blogAiImagesEnabled`, `chatbotEnabled` |
-| `@sahan-sac/ai-core/providers` | `createAiService` (ordered chain, hedging, cooldowns, deadlines, output validation), `realProviders(env, "blog" \| "chat")`, `sharedAiHealth`, provider factories |
+| `@sahan-sac/ai-core/adapters` | `BUILTIN_ADAPTERS`, `ProviderAdapter`, `realProviders(env, purpose, fetch?, adapters?)`, `chainPlan`, `providerStatuses` (why each adapter is in or out, for health screens), `checkProvider` / `checkChain` (manual checks), `configuredOrder`, `PAID_TEXT_MODELS` |
+| `@sahan-sac/ai-core/providers` | `createAiService` (the chain), `sharedAiHealth`, `realProviders` (re-exported), the provider factories: `geminiProvider`, `openRouterProvider`, `nvidiaProvider`, `openAiCompatibleProvider`, `anthropicProvider`, `vertexProvider` |
+| `@sahan-sac/ai-core/availability` | `textAiConfigured(env, purpose?)`, `blogAiEnabled`, `blogAiImagesEnabled`, `chatbotEnabled` |
 | `@sahan-sac/ai-core/models` | `textModels`, `imageModels`, verified free defaults, `paidAllowed`, `vertexConfigured` |
 | `@sahan-sac/ai-core/image` | `imageConfigFromEnv`, `generateImage` |
 | `@sahan-sac/ai-core/vertex` | `getVertexAccessToken` (service-account JWT exchange, cached) |
-| `@sahan-sac/ai-core/guard` | `wrapUserData`, `looksLikeLeak`, `ModelPrompt` |
+| `@sahan-sac/ai-core/guard` | `wrapUserData(text, maxLength?)`, `guidanceSection`, `mergeGuidance`, `looksLikeLeak`, `ModelPrompt` |
 | `@sahan-sac/ai-core/log` | `AiLogger`, `consoleAiLogger` |
 
-`providers`, `image` and `vertex` import `server-only`: use them from server code only.
+`providers`, `adapters`, `image` and `vertex` reach `server-only` code: use them from server code only.
 
 ## Environment
 
@@ -31,14 +49,20 @@ const schema = z.object({ ...aiEnvSchema.shape, DATABASE_URL: z.string() });
 
 | Variable | Default | Meaning |
 | --- | --- | --- |
-| `ENABLE_BLOG_AI` | `false` | Blog AI assistant (also needs a text provider key) |
-| `ENABLE_CHATBOT` | `true` | Chatbot (also needs a text provider key); `false`/`0`/`no`/`off` turns it off |
-| `AI_ALLOW_PAID` | `false` | Lets paid providers (Vertex text and images, Gemini images) join the chains |
+| `ENABLE_BLOG_AI` | `false` | Blog AI assistant (also needs a blog text provider) |
+| `ENABLE_CHATBOT` | `true` | Chatbot (also needs a chat text provider); `false`/`0`/`no`/`off` turns it off |
+| `AI_ALLOW_PAID` | `false` | Lets paid providers join the chains: OpenAI, Anthropic, DeepSeek, xAI, Perplexity, the custom endpoint (unless `AI_CUSTOM_FREE`), Vertex text and images, Gemini images |
+| `AI_PROVIDER_ORDER`, `AI_PROVIDER_ORDER_BLOG`, `AI_PROVIDER_ORDER_CHAT` | built-in order | Comma-separated adapter ids; only the listed ones run, in that order |
 | `GEMINI_API_KEY`, `OPENROUTER_API_KEY`, `OPENROUTER_API_KEY_2`, `NVIDIA_API_KEY` | unset | Free text providers; `NVIDIA_API_KEY` is also the free image provider |
 | `OPENROUTER_BASE_URL`, `OPENROUTER_ALLOW_PAID_MODELS` | OpenRouter API, `false` | OpenRouter settings |
+| `OPENAI_API_KEY`, `OPENAI_BASE_URL` | unset, OpenAI API | OpenAI (paid); the base URL also points it at any OpenAI-compatible gateway |
+| `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL` | unset, Anthropic API | Anthropic Messages API over REST (paid) |
+| `DEEPSEEK_API_KEY`, `XAI_API_KEY`, `PERPLEXITY_API_KEY` | unset | Paid OpenAI-compatible providers |
+| `AI_CUSTOM_BASE_URL`, `AI_CUSTOM_MODEL`, `AI_CUSTOM_API_KEY`, `AI_CUSTOM_NAME`, `AI_CUSTOM_FREE` | unset, `false` | One custom OpenAI-compatible endpoint. The key is optional for a local server. Paid unless `AI_CUSTOM_FREE=true` |
 | `GOOGLE_CLIENT_EMAIL`, `GOOGLE_PRIVATE_KEY`, `GOOGLE_CLOUD_PROJECT` | unset | Vertex service account (paid). Keep the key on one line with literal `\n` |
 | `GOOGLE_TOKEN_URI` | Google's token endpoint | Override only for testing |
-| `BLOG_*_MODEL`, `CHAT_*_MODEL`, `IMAGE_*_MODEL`, `*_MODEL`, `IMAGEN_MODEL` | verified free defaults | Model overrides: purpose variable, then provider-wide, then default |
+| `BLOG_<P>_MODEL`, `CHAT_<P>_MODEL`, `<P>_MODEL` | built-in defaults | Model per provider `<P>` (`GEMINI`, `OPENROUTER`, `NVIDIA`, `VERTEX`, `OPENAI`, `ANTHROPIC`, `DEEPSEEK`, `XAI`, `PERPLEXITY`): purpose variable, then provider-wide, then default. Paid-provider names change often, so set them |
+| `IMAGE_*_MODEL`, `IMAGEN_MODEL` | verified free defaults | Image models |
 
 ## Example
 
@@ -50,6 +74,47 @@ import { createAiService, realProviders, sharedAiHealth } from "@sahan-sac/ai-co
 const env = aiEnvFromProcess();
 if (chatbotEnabled(env)) {
   const ai = createAiService({ providers: realProviders(env, "chat"), health: sharedAiHealth, timeoutMs: 12_000, deadlineMs: 20_000 });
-  const result = await ai.generate({ system: "You are helpful.", user: "Hello" }, { maxTokens: 200 });
+  const result = await ai.generate({ system: "You are helpful.", user: "Hello" }, { maxTokens: 200, signal: request.signal });
+  // result.provider: who answered; result.attempts: every provider tried, with its error class.
 }
 ```
+
+Pass the request's `signal` so a client that disconnects stops the chain: every running attempt is aborted, no further provider starts, and the result is `{ ok: false, errorClass: "aborted" }`. An aborted attempt is not logged or cooled down.
+
+## Your own adapter
+
+```ts
+import { BUILTIN_ADAPTERS, realProviders, type ProviderAdapter } from "@sahan-sac/ai-core/adapters";
+import { openAiCompatibleProvider } from "@sahan-sac/ai-core/providers";
+
+const groq: ProviderAdapter = {
+  id: "groq",
+  label: "Groq",
+  paid: () => false,
+  missing: () => (process.env.GROQ_API_KEY ? [] : ["GROQ_API_KEY"]),
+  create: ({ fetch }) =>
+    openAiCompatibleProvider({ name: "groq", apiKey: process.env.GROQ_API_KEY!, baseUrl: "https://api.groq.com/openai/v1", model: "llama-3.3-70b-versatile", fetch }),
+};
+
+const providers = realProviders(env, "chat", undefined, [...BUILTIN_ADAPTERS, groq]);
+// Default order: the built-ins, then groq. Or list it: AI_PROVIDER_ORDER=groq,gemini
+```
+
+For a settings screen, `providerStatuses(env, purpose)` reports each adapter's state: `active` (with its position), `not_configured` (with the missing variable names, never values), `needs_paid`, `not_in_order` or `unknown`.
+
+## Manual checks
+
+Reachability for an AI provider means a real prompt, which spends tokens, so run it only when an operator asks:
+
+```ts
+import { checkChain, checkProvider } from "@sahan-sac/ai-core/adapters";
+
+await checkProvider(env, "anthropic"); // { id, ok, provider, ms } or { ok: false, errorClass: "http_401", ... }
+await checkChain(env, "blog"); // the whole chain once: who answered, and `attempts` for every fall-through
+```
+
+`checkProvider` ignores the order and `AI_ALLOW_PAID` (the operator asked for that provider) and answers `not_configured` without a call when a variable is missing. `checkChain` uses a fresh health record, so a failed check never cools a provider down for real traffic.
+
+## Owner guidance
+
+`guidanceSection(text)` appends the site owner's standing guidance (voice, facts, do and don't) after a prompt's fixed rules; it returns `""` for empty text and caps the length. `mergeGuidance(global, perFeature)` joins the layers. Guidance steers the model but never overrides the rules above it or how fenced data is treated.

package/dist/adapters.d.ts

@@ -0,0 +1,6 @@
+import './env.js';
+import './models.js';
+export { A as AdapterContext, a as AdapterState, b as AdapterStatus, B as BUILTIN_ADAPTERS, C as CHECK_PROMPT, D as DEFAULT_ORDER, P as PAID_TEXT_MODELS, c as ProviderAdapter, d as ProviderCheck, e as chainPlan, f as checkChain, g as checkProvider, h as configuredOrder, p as providerStatuses, realProviders } from './providers.js';
+import 'zod';
+import './guard.js';
+import './log.js';

package/dist/adapters.js

@@ -0,0 +1,27 @@
+import {
+  BUILTIN_ADAPTERS,
+  CHECK_PROMPT,
+  DEFAULT_ORDER,
+  PAID_TEXT_MODELS,
+  chainPlan,
+  checkChain,
+  checkProvider,
+  configuredOrder,
+  providerStatuses,
+  realProviders
+} from "./chunk-R3YY2Y7S.js";
+import "./chunk-BL4J2JNX.js";
+import "./chunk-PMC3UWQ2.js";
+import "./chunk-RBSLNDFW.js";
+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;

package/dist/availability.js

@@ -1,60 +1,26 @@
-// 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/image.ts
-function vertexImageAvailable(env) {
-  return vertexConfigured(env);
-}
-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;
-}
+import {
+  chainPlan
+} from "./chunk-R3YY2Y7S.js";
+import {
+  imageConfigFromEnv
+} from "./chunk-MRNQPHWI.js";
+import "./chunk-BL4J2JNX.js";
+import "./chunk-PMC3UWQ2.js";
+import "./chunk-RBSLNDFW.js";
 
 // src/availability.ts
-function textAiConfigured(env) {
-  if (env.GEMINI_API_KEY || env.OPENROUTER_API_KEY || env.OPENROUTER_API_KEY_2 || env.NVIDIA_API_KEY) return true;
-  return paidAllowed(env) && vertexConfigured(env);
+function textAiConfigured(env, purpose) {
+  if (purpose) return chainPlan(env, purpose).length > 0;
+  return chainPlan(env, "blog").length > 0 || chainPlan(env, "chat").length > 0;
 }
 function blogAiEnabled(env) {
-  return env.ENABLE_BLOG_AI && textAiConfigured(env);
+  return env.ENABLE_BLOG_AI && textAiConfigured(env, "blog");
 }
 function blogAiImagesEnabled(env) {
   return blogAiEnabled(env) && imageConfigFromEnv(env) !== null;
 }
 function chatbotEnabled(env) {
-  return env.ENABLE_CHATBOT && textAiConfigured(env);
+  return env.ENABLE_CHATBOT && textAiConfigured(env, "chat");
 }
 export {
   blogAiEnabled,

package/dist/chunk-BL4J2JNX.js

@@ -0,0 +1,48 @@
+// 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;
+}
+function resetVertexTokenCache() {
+  cachedToken = null;
+}
+
+export {
+  getVertexAccessToken,
+  resetVertexTokenCache
+};

package/dist/chunk-MRNQPHWI.js

@@ -0,0 +1,194 @@
+import {
+  getVertexAccessToken
+} from "./chunk-BL4J2JNX.js";
+import {
+  imageModels,
+  paidAllowed,
+  vertexConfigured
+} from "./chunk-RBSLNDFW.js";
+
+// src/image.ts
+import "server-only";
+var DEFAULT_IMAGE_MODELS = [
+  { 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_MODELS) {
+    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_MODELS,
+  imageModelChain,
+  extractImage,
+  generateImageVertex,
+  vertexImageAvailable,
+  nvidiaImageRequest,
+  extractNvidiaImage,
+  imageConfigFromEnv,
+  generateImage
+};

package/dist/chunk-PMC3UWQ2.js

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