@sahan-sac/ai-core 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @sahan-sac/ai-core
 
+## 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';