@bitbaum/ai-kit 0.6.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mao Nakamoto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,216 @@
+# ai-kit
+
+**The AI layer of an app, in one install.** Which model to call, what to do when
+the vendor deletes it, how to walk the fallback and know when none of it worked,
+what to do when you're going too fast, how to share a free tier fairly between
+users, and how to fill a form from plain language.
+
+```bash
+npm install ai-kit
+```
+
+---
+
+## Why this is one package and not four
+
+Adding an AI feature looks like one decision and is actually four. Get any of
+them wrong and the app fails **identically** from the outside: the assistant is
+broken, and the error usually blames the wrong thing.
+
+On 2026-08-26 that stopped being hypothetical. Groq retired its entire
+`llama-3.x` family. Every app in this fleet that had picked a model by hand went
+down at the same moment — five repos, three of them serving live traffic — and
+the one app that had adopted the fallback chain was unaffected. One of the broken
+ones reported *"AI assistant not configured, please set GROQ_API_KEY"* on a
+deployment whose key was perfectly valid, so the first hour of the investigation
+went into checking a credential that was never the problem.
+
+That app had already adopted the form-filling half. It hand-rolled the other
+half, because that was a second decision and nobody made it.
+
+So the four decisions ship together now. Adding AI is one install.
+
+> **Renamed from `ai-ration` in v0.3.0.** The old name described one of its five
+> modules and hid the other four, and the person deciding whether to install it
+> could not tell what it did. An unreadable name is a cost paid at every install
+> decision — and this package had a single adopter while five repos that skipped
+> it were taken down together by exactly the failure it prevents.
+
+---
+
+## What's in it
+
+### Which model — a list, never a pin
+
+```ts
+import { freeChain, usableChain, chainFrom } from '@bitbaum/ai-kit';
+
+const providers = freeChain('MYAPP');               // groq → openrouter
+const links = usableChain(providers, process.env);   // drops vendors with no key
+const chain = chainFrom(process.env.MYAPP_MODEL, links);
+```
+
+Falling back to a **smaller model at the same vendor buys nothing**: it draws on
+the same org-wide daily budget, so when the day runs dry every link in that
+"fallback" is already dead. Only a different vendor has a different meter.
+
+**Probe before you pin.** Of nine free models probed live, **five** answered only
+via a text tool protocol, not native `tool_calls`. A native-only client would
+have silently lost most of the chain.
+
+### Is it up? — walk the chain, and know when none of it worked
+
+A chain nobody walks is a list, not a fallback. This was found sitting unused
+next to a single-shot caller in an app this package's `freeChain` had already
+saved from a retired model — the list existed, and nothing tried link two.
+
+```ts
+import { tryChain, createHealthTracker } from '@bitbaum/ai-kit';
+
+const llmHealth = createHealthTracker(); // one per process; see below
+
+const { text } = await tryChain(chain, {
+  health: llmHealth,
+  attempt: async ({ provider, model }) => {
+    // POST `${provider.baseUrl}/chat/completions` with `model` — your own
+    // fetch, your own retries. Throw to demote to the next link.
+    return callVendor(provider, model);
+  },
+});
+```
+
+No HTTP client here either — `attempt` makes the real request; `tryChain` only
+decides which link goes next and throws `ChainExhaustedError` (naming every
+link's failure, not just the last) when none of them work.
+
+`createHealthTracker()` is a factory, not a global: a single-process app gets
+the old "shared state everywhere" behaviour for free by making exactly one and
+exporting it —
+
+```ts
+// lib/llm-health.ts
+export const llmHealth = createHealthTracker();
+```
+
+— and a health route reports `llmHealth.getHealth()` instead of only ever
+checking the database. That gap is not hypothetical: an app's `/health` reported
+"healthy" while its only configured key was returning 401 and every chat route
+was answering a friendly, silent, hardcoded apology. HTTP 200 is not evidence.
+
+### Still there? — catch a retirement before a user does
+
+```ts
+import { freeChain, checkCatalog, hasRot, catalogReport } from '@bitbaum/ai-kit';
+
+const verdicts = await checkCatalog(freeChain('MYAPP'));
+if (hasRot(verdicts)) console.warn(catalogReport(verdicts));
+```
+
+One `GET /models` per vendor. **Zero tokens**, which is what makes it
+schedulable — and "somebody is supposed to remember" is precisely what failed.
+
+Three states, not two: a catalogue that could not be read reports **unchecked**,
+never *gone*. Treating "I could not look" as "nothing is there" marks every model
+retired and invents an outage someone then acts on.
+
+> This fleet runs it daily across every repo from
+> [`fleet/scripts/ci/model-pin-audit.mjs`](https://github.com/bitbaum/fleet).
+
+### Too fast? — the three kinds of 429
+
+```ts
+import { classifyRateLimit, rateLimitMessage } from '@bitbaum/ai-kit';
+
+classifyRateLimit(body); // 'capacity' | 'size' | 'daily'
+```
+
+They share a status code, a `type` and a `code`. Only the body tells them apart,
+and they need **opposite** responses: retry shortly, shrink the request, or give
+up on this vendor until tomorrow.
+
+`retryAfterSeconds` is present only for the refusal a wait actually fixes.
+Telling someone whose daily quota is gone to try again in 20 minutes is a lie.
+
+### Who gets it — fair shares of a free tier
+
+```ts
+import { fairShare, utcDayElapsed } from '@bitbaum/ai-kit';
+```
+
+A free tier grants roughly 100k tokens **per day for an entire org**, and one
+measured tool-calling turn cost ~16k — about six turns a day. Divided badly, the
+first enthusiastic user spends it before lunch and everyone after them meets a
+wall, including the person trying the product for the first time, who concludes
+it is broken and never comes back.
+
+Shares are `capacity / active users`, recomputed per request, where *active*
+means users who actually drew today — one user on a quiet day correctly gets
+everything. The allowance unlocks gradually through the day, with a **one-turn
+floor** so nobody's first question of the morning is refused.
+
+Whatever you pass as `costTokens` must err **high**: under-estimating admits
+turns the pool cannot cover, draining the day while the gate still believes there
+is room.
+
+### Filling forms — from prose, then by talking to it
+
+```ts
+import { runFormAssist } from '@bitbaum/ai-kit/forms';
+import { useAiForm } from '@bitbaum/ai-kit/react';
+import { createFormAssistHandler } from '@bitbaum/ai-kit/server';
+```
+
+Re-exported from [`ai-forms`](https://github.com/bitbaum/ai-forms), which
+stays its own package — it works, four apps run it, and it is useful well outside
+this fleet. Swallowing it would have broken those four for the sake of a filing
+system.
+
+**Note the subpath.** Form filling is at `ai-kit/forms`, not at the root. For one
+release it was both, and the first app to adopt the merged package paid for it:
+`ai-forms` is ESM-only, so importing the *chain* from the root dragged the forms
+package in behind it and the app's Jest run — which executes CJS — died inside a
+module it never asked for. One install is still the whole promise; the exports
+map is what keeps it, while letting a server that only wants a provider chain
+stop paying for a form library.
+
+React lives on its own subpath and is an **optional** peer, so importing `ai-kit`
+on a server never pulls in a UI library.
+
+---
+
+## What it deliberately does not ship
+
+**An HTTP client.** Every app has its own calling conventions, retries and
+logging, and replacing those is a rewrite rather than an adoption. This supplies
+the decisions; you keep the fetch.
+
+That rule is under review, and honestly. `ai-forms` is the most-adopted package
+in this fleet and it is the one that broke the rule, by shipping a route factory
+and a React hook. A package that hands you a working route gets installed; one
+that hands you advice about routes does not.
+
+**Model values.** Which ids are free, which are billed, and which your account
+may use are properties of *your* deployment. Centralise the rule, assert it
+locally.
+
+---
+
+## Related
+
+| Package | For |
+|---|---|
+| [`ai-forms`](https://github.com/bitbaum/ai-forms) | Form filling on its own, without the model layer |
+| [`threadkit`](https://github.com/bitbaum/threadkit) | Messages between people, and who may see them |
+| [`limitkit`](https://github.com/bitbaum/limitkit) | Stopping someone doing something too often |
+
+`threadkit` and `limitkit` are **not** merged in here, on purpose: neither has
+anything to do with AI. An app that throttles its login form should not install a
+model catalogue to do it.
+
+## Development
+
+```bash
+npm run verify   # lint + typecheck + build + test
+```
+
+MIT.

package/dist/attempt.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Walk a chain, never own the fetch.
+ *
+ * `usableChain`/`chainFrom` (chain.ts) already answer WHICH links exist and in
+ * what order. What was still missing — in every app that hand-rolled it, and
+ * inconsistently — is the loop that tries link one, and on failure tries link
+ * two, rather than picking the first link and calling it once. A chain nobody
+ * walks is a list, not a fallback: it was found sitting unused next to a
+ * single-shot caller in the same app that this package's `freeChain` already
+ * protected from a retired model but not from a dead key, because ordering the
+ * links and walking them were still two different jobs and only one had a
+ * home.
+ *
+ * This still ships no HTTP client. `attempt` is supplied by the caller and
+ * does the actual request; this only decides which link goes next, and
+ * records the outcome if a `HealthTracker` is given.
+ */
+import type { Link } from "./chain.js";
+import type { HealthTracker } from "./health.js";
+export interface ChainAttemptFailure {
+    link: Link;
+    message: string;
+}
+/** Every link in the chain was tried and failed (or the chain was empty). */
+export declare class ChainExhaustedError extends Error {
+    readonly failures: ChainAttemptFailure[];
+    constructor(failures: ChainAttemptFailure[]);
+}
+export interface TryChainOptions<T> {
+    /** Makes the actual call for one link. Throw to demote to the next link. */
+    attempt: (link: Link) => Promise<T>;
+    /** Records one success or one failure for the WHOLE walk, not per link. */
+    health?: HealthTracker;
+    /** Called on each link's failure, before moving to the next — e.g. to log it. */
+    onLinkFailure?: (link: Link, error: unknown) => void;
+}
+/**
+ * Try each link in order; return the first success.
+ *
+ * Health is recorded once per call — a success on link two is still a success
+ * for the app, and a health check that flagged it "degraded" because the FIRST
+ * link failed would be reporting its own fallback working as a problem.
+ *
+ * Throws `ChainExhaustedError` (carrying every link's failure) when none
+ * succeed, so a caller can log exactly what was tried rather than only the
+ * last error — the failure that matters is often not the last one.
+ */
+export declare function tryChain<T>(chain: Link[], options: TryChainOptions<T>): Promise<T>;

package/dist/attempt.js

@@ -0,0 +1,59 @@
+/**
+ * Walk a chain, never own the fetch.
+ *
+ * `usableChain`/`chainFrom` (chain.ts) already answer WHICH links exist and in
+ * what order. What was still missing — in every app that hand-rolled it, and
+ * inconsistently — is the loop that tries link one, and on failure tries link
+ * two, rather than picking the first link and calling it once. A chain nobody
+ * walks is a list, not a fallback: it was found sitting unused next to a
+ * single-shot caller in the same app that this package's `freeChain` already
+ * protected from a retired model but not from a dead key, because ordering the
+ * links and walking them were still two different jobs and only one had a
+ * home.
+ *
+ * This still ships no HTTP client. `attempt` is supplied by the caller and
+ * does the actual request; this only decides which link goes next, and
+ * records the outcome if a `HealthTracker` is given.
+ */
+/** Every link in the chain was tried and failed (or the chain was empty). */
+export class ChainExhaustedError extends Error {
+    failures;
+    constructor(failures) {
+        super(failures.length === 0
+            ? "No usable link in the chain — every provider is missing its key, or has no models configured."
+            : `All ${failures.length} link(s) failed — ${failures
+                .map((f) => `${f.link.provider.id}/${f.link.model}: ${f.message}`)
+                .join("; ")}`);
+        this.name = "ChainExhaustedError";
+        this.failures = failures;
+    }
+}
+/**
+ * Try each link in order; return the first success.
+ *
+ * Health is recorded once per call — a success on link two is still a success
+ * for the app, and a health check that flagged it "degraded" because the FIRST
+ * link failed would be reporting its own fallback working as a problem.
+ *
+ * Throws `ChainExhaustedError` (carrying every link's failure) when none
+ * succeed, so a caller can log exactly what was tried rather than only the
+ * last error — the failure that matters is often not the last one.
+ */
+export async function tryChain(chain, options) {
+    const failures = [];
+    for (const link of chain) {
+        try {
+            const result = await options.attempt(link);
+            options.health?.recordSuccess();
+            return result;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            failures.push({ link, message });
+            options.onLinkFailure?.(link, error);
+        }
+    }
+    const exhausted = new ChainExhaustedError(failures);
+    options.health?.recordFailure(exhausted);
+    throw exhausted;
+}

package/dist/catalog.d.ts

@@ -0,0 +1,65 @@
+/**
+ * catalog — has the vendor retired a model this chain still asks for?
+ *
+ * The chain exists because a single pinned free model is a scheduled outage.
+ * That reasoning has a hole: the chain itself is a list of pinned ids, so it
+ * rots too, and a chain whose first vendor is entirely dead is a slower version
+ * of the failure it was built to prevent.
+ *
+ * Not hypothetical. On 2026-08-25 `freeChain()` was checked against the live
+ * catalogues and FOUR of its nine ids were gone — both Groq models (the whole
+ * first vendor) and two OpenRouter ids, one of them the preferred fallback. The
+ * consumer that also used the Groq id for direct, unchained calls had been
+ * silently failing for eight days.
+ *
+ * Why this lives in the package rather than in each app: the check is the same
+ * everywhere, and the app that wrote its own first wrote it slightly
+ * differently. One implementation, shared by name and by value.
+ *
+ * Cheap on purpose — one GET /models per provider and ZERO tokens. That is what
+ * makes it schedulable, which is the whole difference between a check that runs
+ * nightly and a command someone is supposed to remember. A tool-call probe
+ * costs real tokens and cannot run on a timer; existence can.
+ */
+import { type Env, type Provider } from "./chain.js";
+export type CatalogVerdict = {
+    provider: string;
+    /**
+     * Ids the vendor currently lists, or NULL when the catalogue could not be
+     * read (no key, network failure, non-200, unparseable body).
+     *
+     * Null is not an empty list. Treating "I could not look" as "nothing is
+     * there" reports every model as retired and invents an outage; treating it
+     * as "all fine" hides a real one. Callers must handle three states.
+     */
+    live: string[] | null;
+    /** Pinned ids confirmed present. Empty when `live` is null. */
+    present: string[];
+    /** Pinned ids the vendor no longer lists. Empty when `live` is null. */
+    missing: string[];
+    /** Pinned ids whose status is unknown because `live` is null. */
+    unchecked: string[];
+};
+export type CheckCatalogOptions = {
+    env?: Env;
+    /** Injectable for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+};
+/**
+ * Check every model a chain would try against what its vendor still lists.
+ *
+ * Honours the same env overrides `usableChain` does, so it checks the ids this
+ * deployment would ACTUALLY call — not the library defaults an operator has
+ * already routed around.
+ */
+export declare function checkCatalog(chain: Provider[], opts?: CheckCatalogOptions): Promise<CatalogVerdict[]>;
+/** True when any pinned id is confirmed gone. Unchecked providers do NOT count
+ *  — an unreadable catalogue is not evidence of rot. */
+export declare function hasRot(verdicts: CatalogVerdict[]): boolean;
+/** True when a whole vendor's models are gone, i.e. the chain has lost a link
+ *  entirely. Worth separating: a chain that still has vendors is degraded, a
+ *  chain that has lost one is back to being a single point of failure. */
+export declare function deadProviders(verdicts: CatalogVerdict[]): string[];
+/** Human-readable report. Keeps could-not-look visibly distinct from a pass. */
+export declare function catalogReport(verdicts: CatalogVerdict[]): string;

package/dist/catalog.js

@@ -0,0 +1,115 @@
+/**
+ * catalog — has the vendor retired a model this chain still asks for?
+ *
+ * The chain exists because a single pinned free model is a scheduled outage.
+ * That reasoning has a hole: the chain itself is a list of pinned ids, so it
+ * rots too, and a chain whose first vendor is entirely dead is a slower version
+ * of the failure it was built to prevent.
+ *
+ * Not hypothetical. On 2026-08-25 `freeChain()` was checked against the live
+ * catalogues and FOUR of its nine ids were gone — both Groq models (the whole
+ * first vendor) and two OpenRouter ids, one of them the preferred fallback. The
+ * consumer that also used the Groq id for direct, unchained calls had been
+ * silently failing for eight days.
+ *
+ * Why this lives in the package rather than in each app: the check is the same
+ * everywhere, and the app that wrote its own first wrote it slightly
+ * differently. One implementation, shared by name and by value.
+ *
+ * Cheap on purpose — one GET /models per provider and ZERO tokens. That is what
+ * makes it schedulable, which is the whole difference between a check that runs
+ * nightly and a command someone is supposed to remember. A tool-call probe
+ * costs real tokens and cannot run on a timer; existence can.
+ */
+import { providerModels } from "./chain.js";
+/** Ids listed by one provider, or null when the catalogue could not be read. */
+async function liveIds(provider, key, fetchImpl, timeoutMs) {
+    try {
+        const res = await fetchImpl(`${provider.baseUrl.replace(/\/$/, "")}/models`, {
+            headers: { Authorization: `Bearer ${key}` },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        if (!Array.isArray(body?.data))
+            return null;
+        const ids = body.data
+            .map((m) => (typeof m?.id === "string" ? m.id : ""))
+            .filter((id) => id.length > 0);
+        // A catalogue that parses but lists nothing is a malformed answer, not a
+        // vendor with no models. Refusing it keeps a bad response from reading as
+        // total rot.
+        return ids.length > 0 ? ids : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check every model a chain would try against what its vendor still lists.
+ *
+ * Honours the same env overrides `usableChain` does, so it checks the ids this
+ * deployment would ACTUALLY call — not the library defaults an operator has
+ * already routed around.
+ */
+export async function checkCatalog(chain, opts = {}) {
+    const env = opts.env ?? process.env;
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const timeoutMs = opts.timeoutMs ?? 20_000;
+    const out = [];
+    for (const provider of chain) {
+        const pinned = providerModels(provider, env);
+        const key = env[provider.keyEnv]?.trim();
+        const live = key ? await liveIds(provider, key, fetchImpl, timeoutMs) : null;
+        if (!live) {
+            out.push({ provider: provider.id, live: null, present: [], missing: [], unchecked: pinned });
+            continue;
+        }
+        const set = new Set(live);
+        out.push({
+            provider: provider.id,
+            live,
+            present: pinned.filter((m) => set.has(m)),
+            missing: pinned.filter((m) => !set.has(m)),
+            unchecked: [],
+        });
+    }
+    return out;
+}
+/** True when any pinned id is confirmed gone. Unchecked providers do NOT count
+ *  — an unreadable catalogue is not evidence of rot. */
+export function hasRot(verdicts) {
+    return verdicts.some((v) => v.missing.length > 0);
+}
+/** True when a whole vendor's models are gone, i.e. the chain has lost a link
+ *  entirely. Worth separating: a chain that still has vendors is degraded, a
+ *  chain that has lost one is back to being a single point of failure. */
+export function deadProviders(verdicts) {
+    return verdicts
+        .filter((v) => v.live !== null && v.present.length === 0 && v.missing.length > 0)
+        .map((v) => v.provider);
+}
+/** Human-readable report. Keeps could-not-look visibly distinct from a pass. */
+export function catalogReport(verdicts) {
+    const lines = [];
+    for (const v of verdicts) {
+        if (v.live === null) {
+            lines.push(`? ${v.provider}: catalogue unreadable (no key, or the request failed) — ${v.unchecked.length} id(s) UNCHECKED`);
+            for (const m of v.unchecked)
+                lines.push(`    ? ${m}`);
+            continue;
+        }
+        for (const m of v.present)
+            lines.push(`  ok   ${v.provider}/${m}`);
+        for (const m of v.missing)
+            lines.push(`  GONE ${v.provider}/${m}`);
+    }
+    const dead = deadProviders(verdicts);
+    if (dead.length)
+        lines.push(`\nEVERY model is gone at: ${dead.join(", ")} — the chain has lost that vendor entirely.`);
+    const unchecked = verdicts.reduce((n, v) => n + v.unchecked.length, 0);
+    if (unchecked)
+        lines.push(`\n${unchecked} id(s) could not be checked. That is not a pass for them.`);
+    return lines.join("\n");
+}