@sahan-sac/ai-core 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @sahan-sac/ai-core
 
+## 0.4.0
+
+### Minor Changes
+
+- 396e692: Three more free-tier adapters:
+  - `groq`: Groq free plan, keyed by `GROQ_API_KEY`. Default models `openai/gpt-oss-120b` for the blog and `openai/gpt-oss-20b` for chat.
+  - `mistral`: Mistral free Experiment plan, keyed by `MISTRAL_API_KEY`. This plan may train on prompts, so the adapter runs in the blog chain only unless `AI_PROVIDER_ORDER_CHAT` lists it.
+  - `cloudflare`: Cloudflare Workers AI, with 10,000 free neurons a day. Needs `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_AI_API_TOKEN`.
+  
+  None of them is paid, so none needs `AI_ALLOW_PAID`. Each model can be overridden per purpose. Adapters gain an optional `defaultPurposes`.
+
+### Patch Changes
+
+- 1570cf6: A provider that answers 402 (no credits, or an empty prepaid wallet) now cools down for 30 minutes instead of being retried on every request, so an unfunded account costs one probe per window rather than a failed round trip each time. `cooldownFor` is exported.
+
+## 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

package/README.md

@@ -1,120 +1,123 @@
-# @sahan-sac/ai-core
-
-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/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(text, maxLength?)`, `guidanceSection`, `mergeGuidance`, `looksLikeLeak`, `ModelPrompt` |
-| `@sahan-sac/ai-core/log` | `AiLogger`, `consoleAiLogger` |
-
-`providers`, `adapters`, `image` and `vertex` reach `server-only` code: use them from server code only.
-
-## Environment
-
-Spread the schema into your own env module so the names never drift:
-
-```ts
-import { aiEnvSchema } from "@sahan-sac/ai-core/env";
-
-const schema = z.object({ ...aiEnvSchema.shape, DATABASE_URL: z.string() });
-```
-
-| Variable | Default | Meaning |
-| --- | --- | --- |
-| `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_<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
-
-```ts
-import { chatbotEnabled } from "@sahan-sac/ai-core/availability";
-import { aiEnvFromProcess } from "@sahan-sac/ai-core/env";
-import { createAiService, realProviders, sharedAiHealth } from "@sahan-sac/ai-core/providers";
-
-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, 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.
+# @sahan-sac/ai-core
+
+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/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(text, maxLength?)`, `guidanceSection`, `mergeGuidance`, `looksLikeLeak`, `ModelPrompt` |
+| `@sahan-sac/ai-core/log` | `AiLogger`, `consoleAiLogger` |
+
+`providers`, `adapters`, `image` and `vertex` reach `server-only` code: use them from server code only.
+
+## Environment
+
+Spread the schema into your own env module so the names never drift:
+
+```ts
+import { aiEnvSchema } from "@sahan-sac/ai-core/env";
+
+const schema = z.object({ ...aiEnvSchema.shape, DATABASE_URL: z.string() });
+```
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `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) |
+| `GROQ_API_KEY` | unset | Groq free plan (no card). Models `openai/gpt-oss-120b` (blog) and `openai/gpt-oss-20b` (chat); override with `GROQ_MODEL` or `BLOG_`/`CHAT_` variants |
+| `MISTRAL_API_KEY` | unset | Mistral free (Experiment) plan, which may train on prompts. Blog chain only, unless `AI_PROVIDER_ORDER_CHAT` lists `mistral` |
+| `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_AI_API_TOKEN` | unset | Cloudflare Workers AI, 10,000 free neurons a day. Models `@cf/openai/gpt-oss-120b` / `-20b`; override with `CLOUDFLARE_AI_MODEL` |
+| `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_<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
+
+```ts
+import { chatbotEnabled } from "@sahan-sac/ai-core/availability";
+import { aiEnvFromProcess } from "@sahan-sac/ai-core/env";
+import { createAiService, realProviders, sharedAiHealth } from "@sahan-sac/ai-core/providers";
+
+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, 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

@@ -1,6 +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';
+export { A as AdapterContext, a as AdapterState, b as AdapterStatus, B as BUILTIN_ADAPTERS, C as CHECK_PROMPT, D as DEFAULT_ORDER, F as FREE_TEXT_MODELS, 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';