@sahan-sac/ai-core 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @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

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';

package/dist/adapters.js

@@ -2,6 +2,7 @@ import {
   BUILTIN_ADAPTERS,
   CHECK_PROMPT,
   DEFAULT_ORDER,
+  FREE_TEXT_MODELS,
   PAID_TEXT_MODELS,
   chainPlan,
   checkChain,
@@ -9,7 +10,7 @@ import {
   configuredOrder,
   providerStatuses,
   realProviders
-} from "./chunk-R3YY2Y7S.js";
+} from "./chunk-BK4B76LD.js";
 import "./chunk-BL4J2JNX.js";
 import "./chunk-PMC3UWQ2.js";
 import "./chunk-RBSLNDFW.js";
@@ -17,6 +18,7 @@ export {
   BUILTIN_ADAPTERS,
   CHECK_PROMPT,
   DEFAULT_ORDER,
+  FREE_TEXT_MODELS,
   PAID_TEXT_MODELS,
   chainPlan,
   checkChain,

package/dist/availability.js

@@ -1,6 +1,6 @@
 import {
   chainPlan
-} from "./chunk-R3YY2Y7S.js";
+} from "./chunk-BK4B76LD.js";
 import {
   imageConfigFromEnv
 } from "./chunk-MRNQPHWI.js";

package/dist/{chunk-R3YY2Y7S.js → chunk-BK4B76LD.js}

@@ -23,6 +23,11 @@ function modelFor(env, provider, purpose, fallback) {
   return record[`${purpose.toUpperCase()}_${provider}_MODEL`] || record[`${provider}_MODEL`] || fallback[purpose];
 }
 var need = (env, ...names) => names.filter((name) => !env[name]);
+var FREE_TEXT_MODELS = {
+  groq: { blog: "openai/gpt-oss-120b", chat: "openai/gpt-oss-20b" },
+  mistral: { blog: "mistral-medium-latest", chat: "mistral-small-latest" },
+  cloudflare: { blog: "@cf/openai/gpt-oss-120b", chat: "@cf/openai/gpt-oss-20b" }
+};
 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" },
@@ -68,6 +73,19 @@ var BUILTIN_ADAPTERS = [
     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 })
   },
+  {
+    id: "groq",
+    label: "Groq",
+    paid: () => false,
+    missing: (env) => need(env, "GROQ_API_KEY"),
+    create: ({ env, purpose, fetch: fetch2 }) => openAiCompatibleProvider({
+      name: "groq",
+      apiKey: env.GROQ_API_KEY,
+      baseUrl: "https://api.groq.com/openai/v1",
+      model: modelFor(env, "GROQ", purpose, FREE_TEXT_MODELS.groq),
+      fetch: fetch2
+    })
+  },
   openRouterAdapter("openrouter", "OPENROUTER_API_KEY"),
   openRouterAdapter("openrouter-2", "OPENROUTER_API_KEY_2"),
   {
@@ -83,6 +101,35 @@ var BUILTIN_ADAPTERS = [
       fetch: fetch2
     })
   },
+  {
+    id: "mistral",
+    label: "Mistral",
+    paid: () => false,
+    // The free plan may train on prompts: keep visitors' chat text out unless
+    // the operator lists it in AI_PROVIDER_ORDER_CHAT.
+    defaultPurposes: ["blog"],
+    missing: (env) => need(env, "MISTRAL_API_KEY"),
+    create: ({ env, purpose, fetch: fetch2 }) => openAiCompatibleProvider({
+      name: "mistral",
+      apiKey: env.MISTRAL_API_KEY,
+      baseUrl: "https://api.mistral.ai/v1",
+      model: modelFor(env, "MISTRAL", purpose, FREE_TEXT_MODELS.mistral),
+      fetch: fetch2
+    })
+  },
+  {
+    id: "cloudflare",
+    label: "Cloudflare Workers AI",
+    paid: () => false,
+    missing: (env) => need(env, "CLOUDFLARE_ACCOUNT_ID", "CLOUDFLARE_AI_API_TOKEN"),
+    create: ({ env, purpose, fetch: fetch2 }) => openAiCompatibleProvider({
+      name: "cloudflare",
+      apiKey: env.CLOUDFLARE_AI_API_TOKEN,
+      baseUrl: `https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(env.CLOUDFLARE_ACCOUNT_ID)}/ai/v1`,
+      model: modelFor(env, "CLOUDFLARE_AI", purpose, FREE_TEXT_MODELS.cloudflare),
+      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",
@@ -137,7 +184,7 @@ function configuredOrder(env, purpose) {
 }
 function providerStatuses(env, purpose, adapters = BUILTIN_ADAPTERS) {
   const order = configuredOrder(env, purpose);
-  const ids = order ?? adapters.map((adapter) => adapter.id);
+  const ids = order ?? adapters.filter((adapter) => !adapter.defaultPurposes || adapter.defaultPurposes.includes(purpose)).map((adapter) => adapter.id);
   const byId = new Map(adapters.map((adapter) => [adapter.id, adapter]));
   let position = 0;
   const statuses = [];
@@ -239,6 +286,7 @@ 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 === 402) return AI_COOLDOWN_MS * 30;
   if (outcome.status === 401 || outcome.status === 403 || outcome.status === 404) return AI_COOLDOWN_MS * 10;
   return 0;
 }
@@ -548,6 +596,7 @@ export {
   AI_COOLDOWN_MS,
   createAiHealth,
   sharedAiHealth,
+  cooldownFor,
   HEDGE,
   createAiService,
   openRouterProvider,
@@ -558,6 +607,7 @@ export {
   geminiOutcome,
   geminiProvider,
   vertexProvider,
+  FREE_TEXT_MODELS,
   PAID_TEXT_MODELS,
   BUILTIN_ADAPTERS,
   DEFAULT_ORDER,

package/dist/{chunk-ZIHRZXPE.js → chunk-SI7JE5BG.js}

@@ -26,6 +26,23 @@ var aiEnvSchema = z.object({
   OPENROUTER_ALLOW_PAID_MODELS: flag,
   GEMINI_API_KEY: text,
   NVIDIA_API_KEY: text,
+  // More free tiers (./adapters). Groq: free plan, no card. Mistral: free
+  // Experiment plan, which may train on prompts, so it joins the chat chain
+  // only when AI_PROVIDER_ORDER_CHAT lists it. Cloudflare Workers AI: 10,000
+  // free neurons a day; needs the account id and a Workers AI token.
+  GROQ_API_KEY: text,
+  GROQ_MODEL: text,
+  BLOG_GROQ_MODEL: text,
+  CHAT_GROQ_MODEL: text,
+  MISTRAL_API_KEY: text,
+  MISTRAL_MODEL: text,
+  BLOG_MISTRAL_MODEL: text,
+  CHAT_MISTRAL_MODEL: text,
+  CLOUDFLARE_ACCOUNT_ID: text,
+  CLOUDFLARE_AI_API_TOKEN: text,
+  CLOUDFLARE_AI_MODEL: text,
+  BLOG_CLOUDFLARE_AI_MODEL: text,
+  CHAT_CLOUDFLARE_AI_MODEL: text,
   // Model overrides, all optional (models.ts): purpose variable, then the
   // provider-wide *_MODEL, then a verified free default.
   OPENROUTER_MODEL: text,

package/dist/env.d.ts

@@ -11,6 +11,19 @@ declare const aiEnvSchema: z.ZodObject<{
     OPENROUTER_ALLOW_PAID_MODELS: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<boolean, string | undefined>>;
     GEMINI_API_KEY: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
     NVIDIA_API_KEY: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
+    GROQ_API_KEY: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
+    GROQ_MODEL: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
+    BLOG_GROQ_MODEL: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
+    CHAT_GROQ_MODEL: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
+    MISTRAL_API_KEY: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
+    MISTRAL_MODEL: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
+    BLOG_MISTRAL_MODEL: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
+    CHAT_MISTRAL_MODEL: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
+    CLOUDFLARE_ACCOUNT_ID: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
+    CLOUDFLARE_AI_API_TOKEN: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
+    CLOUDFLARE_AI_MODEL: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
+    BLOG_CLOUDFLARE_AI_MODEL: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
+    CHAT_CLOUDFLARE_AI_MODEL: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
     OPENROUTER_MODEL: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
     GEMINI_MODEL: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;
     NVIDIA_MODEL: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string | undefined, string | undefined>>;

package/dist/env.js

@@ -3,7 +3,7 @@ import {
   aiEnvFromProcess,
   aiEnvSchema,
   parseAiEnv
-} from "./chunk-ZIHRZXPE.js";
+} from "./chunk-SI7JE5BG.js";
 export {
   DEFAULT_GOOGLE_TOKEN_URI,
   aiEnvFromProcess,

package/dist/index.js

@@ -2,7 +2,7 @@ import {
   aiEnvFromProcess,
   aiEnvSchema,
   parseAiEnv
-} from "./chunk-ZIHRZXPE.js";
+} from "./chunk-SI7JE5BG.js";
 export {
   aiEnvFromProcess,
   aiEnvSchema,

package/dist/providers.d.ts

@@ -70,6 +70,13 @@ interface AiHealth {
 declare const createAiHealth: () => AiHealth;
 /** One per server instance, for request handlers; tests and scripts get a fresh one by default. */
 declare const sharedAiHealth: AiHealth;
+/**
+ * Quota and slowness pass quickly; a wrong key or a retired model needs an
+ * operator, so it cools longer; an empty prepaid wallet (402) needs someone to
+ * add funds, so it cools longest and costs one probe per half hour instead of
+ * a failed round trip on every request.
+ */
+declare function cooldownFor(outcome: AiOutcome): number;
 interface AiServiceDeps {
     providers: readonly AiProvider[];
     /** Per-provider attempt budget. */
@@ -188,12 +195,35 @@ interface ProviderAdapter {
     /** Lowercase id used in AI_PROVIDER_ORDER. */
     readonly id: string;
     readonly label: string;
+    /**
+     * Purposes it joins under the default order; unset means all. An explicit
+     * AI_PROVIDER_ORDER(_BLOG|_CHAT) still adds it anywhere it is listed.
+     */
+    readonly defaultPurposes?: readonly TextPurpose[];
     /** Costs money: runs only with AI_ALLOW_PAID. */
     paid(env: AiEnv): boolean;
     /** Env variable names still missing; empty means configured. Never values. */
     missing(env: AiEnv): string[];
     create(context: AdapterContext): AiProvider;
 }
+/**
+ * Defaults for the free-tier adapters that take an id per purpose. The blog
+ * writes long JSON, so it gets the larger model; chat gets the faster one.
+ */
+declare const FREE_TEXT_MODELS: {
+    readonly groq: {
+        readonly blog: "openai/gpt-oss-120b";
+        readonly chat: "openai/gpt-oss-20b";
+    };
+    readonly mistral: {
+        readonly blog: "mistral-medium-latest";
+        readonly chat: "mistral-small-latest";
+    };
+    readonly cloudflare: {
+        readonly blog: "@cf/openai/gpt-oss-120b";
+        readonly chat: "@cf/openai/gpt-oss-20b";
+    };
+};
 /**
  * Defaults for the paid adapters. Model names change often: set the
  * provider's *_MODEL variable rather than relying on these.
@@ -290,4 +320,4 @@ declare function checkChain(env: AiEnv, purpose: TextPurpose, options?: {
  */
 declare function realProviders(env: AiEnv, purpose: TextPurpose, fetchImpl?: typeof fetch, adapters?: readonly ProviderAdapter[]): AiProvider[];
 
-export { type AdapterContext as A, AI_COOLDOWN_MS, AI_TIMEOUT_MS, type AiAttempt, type AiAttemptStatus, type AiGenerateOptions, type AiHealth, type AiOutcome, type AiProvider, type AiResult, type AiServiceDeps, BUILTIN_ADAPTERS as B, CHECK_PROMPT as C, DEFAULT_ORDER as D, HEDGE, type JsonMode, PAID_TEXT_MODELS as P, type AdapterState as a, anthropicOutcome, anthropicProvider, type AdapterStatus as b, type ProviderAdapter as c, createAiHealth, createAiService, type ProviderCheck as d, chainPlan as e, checkChain as f, checkProvider as g, geminiOutcome, geminiProvider, configuredOrder as h, nvidiaProvider, openAiCompatibleProvider, openRouterProvider, providerStatuses as p, realProviders, sharedAiHealth, vertexProvider };
+export { type AdapterContext as A, AI_COOLDOWN_MS, AI_TIMEOUT_MS, type AiAttempt, type AiAttemptStatus, type AiGenerateOptions, type AiHealth, type AiOutcome, type AiProvider, type AiResult, type AiServiceDeps, BUILTIN_ADAPTERS as B, CHECK_PROMPT as C, DEFAULT_ORDER as D, FREE_TEXT_MODELS as F, HEDGE, type JsonMode, PAID_TEXT_MODELS as P, type AdapterState as a, anthropicOutcome, anthropicProvider, type AdapterStatus as b, type ProviderAdapter as c, cooldownFor, createAiHealth, createAiService, type ProviderCheck as d, chainPlan as e, checkChain as f, checkProvider as g, geminiOutcome, geminiProvider, configuredOrder as h, nvidiaProvider, openAiCompatibleProvider, openRouterProvider, providerStatuses as p, realProviders, sharedAiHealth, vertexProvider };

package/dist/providers.js

@@ -4,6 +4,7 @@ import {
   HEDGE,
   anthropicOutcome,
   anthropicProvider,
+  cooldownFor,
   createAiHealth,
   createAiService,
   geminiOutcome,
@@ -14,7 +15,7 @@ import {
   realProviders,
   sharedAiHealth,
   vertexProvider
-} from "./chunk-R3YY2Y7S.js";
+} from "./chunk-BK4B76LD.js";
 import "./chunk-BL4J2JNX.js";
 import "./chunk-PMC3UWQ2.js";
 import "./chunk-RBSLNDFW.js";
@@ -24,6 +25,7 @@ export {
   HEDGE,
   anthropicOutcome,
   anthropicProvider,
+  cooldownFor,
   createAiHealth,
   createAiService,
   geminiOutcome,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sahan-sac/ai-core",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Free-by-default AI provider chain with fallback (chain of responsibility over provider adapters: Gemini, OpenRouter, NVIDIA, OpenAI, Anthropic, DeepSeek, xAI, Perplexity, any OpenAI-compatible endpoint, Vertex), env-configurable order, hedging, cooldowns and deadlines, image generation and prompt-injection guards. Shared by @sahan-sac/blog-kit and @sahan-sac/chat-kit.",
   "license": "Apache-2.0",
   "repository": {
@@ -92,6 +92,6 @@
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.build.json",
-    "test": "node --conditions=react-server --import tsx --test \"src/**/*.test.ts\""
+    "test": "node ../../scripts/test-package.mjs --conditions=react-server"
   }
 }