@connextar/house 0.8.1 → 0.9.0

package/README.md

@@ -634,6 +634,89 @@ ten results and two for eleven to a hundred; VALUE SERP charges per request.
 There is no caching here — what may be stored, and for how long, is each app's
 decision and each provider's terms.
 
+### `@connextar/house/ai`
+
+One harness for **Anthropic and OpenAI**, so which company answers is a
+deployment setting and never a feature's decision. Extracted from AltEd and
+PharmaLine, which had each written it — and Quickie was about to write it a
+third time. It is the union of the two: AltEd's call layer (prose, structured
+output from a Zod schema, PDFs and pictures, time limits, cache-aware usage) and
+the configuration rules both apps had arrived at independently.
+
+The app names its jobs; each job has a model per provider, read from a variable
+the operator sets, with a working default:
+
+```ts
+// lib/ai/index.ts — the app's binding, server-only because it reads keys
+import "server-only";
+import { createAiHarness } from "@connextar/house/ai";
+
+export const ai = createAiHarness({
+  tasks: {
+    categorise: {
+      ANTHROPIC: { modelVar: "ANTHROPIC_MODEL", defaultModel: "claude-haiku-4-5-20251001" },
+      OPENAI: { modelVar: "OPENAI_MODEL", defaultModel: "gpt-5-mini" },
+    },
+    insights: {
+      ANTHROPIC: { modelVar: "ANTHROPIC_INSIGHTS_MODEL", defaultModel: "claude-sonnet-5" },
+      OPENAI: { modelVar: "OPENAI_INSIGHTS_MODEL", defaultModel: "gpt-5" },
+      thinking: true,
+    },
+  },
+});
+
+const { parsed, provider, model, inputTokens, outputTokens } = await ai.generateStructured({
+  task: "categorise",
+  system: "…",
+  prompt: "…",
+  schema: answerSchema, // a Zod schema
+  schemaName: "categories",
+  maxTokens: 2000,
+  timeoutMs: 25_000,
+});
+```
+
+`ANTHROPIC_API_KEY` and `OPENAI_API_KEY` turn a provider on. `AI_PROVIDER`
+(`anthropic` or `openai`) chooses when both are set; unset, Anthropic is
+preferred — a stable order, so adding a second key never moves an instance to a
+different processor.
+
+Rules the module holds so no app has to rediscover them:
+
+- **Naming a provider is a decision.** `AI_PROVIDER=openai` with no OpenAI key
+  turns the feature _off_ with a reason (`status().problem`); it never falls
+  back to the other company, which would break a privacy policy that names its
+  processor. Nothing configured at all is simply off, not a problem.
+- **A person is told less than an operator.** `publicStatus()` drops `problem`,
+  which names environment variables. Neither status ever carries a key.
+- **Thinking belongs to the job.** Adaptive thinking is sent to Anthropic only
+  for a job declared `thinking: true` (or a call that asks) — the small fast
+  models reject it with a 400, and the job's default model is where that is
+  known. Effort is Anthropic-only; OpenAI's reasoning is the model's own.
+- **OpenAI output budgets get a floor** (`OPENAI_MIN_OUTPUT_TOKENS`, 4,000): a
+  reasoning model spends the budget thinking before it writes a word.
+- **Structured calls stream**, because both SDKs refuse a non-streaming call that
+  could outlive their timeout. A `timeoutMs` call makes one attempt, no retries.
+- **Failures are three classes.** `AiUnavailableError` — off, nothing was sent.
+  `AiServiceError` — the provider said no, in its own words, with its status.
+  `AiUnusableAnswerError` — a refusal, a cut-off or the wrong shape; the tokens
+  were spent anyway, so `error.usage` carries them for the caller to record.
+- **Usage is cache-aware.** Every result carries input, output, cache-read and
+  cache-write tokens. OpenAI counts cached tokens inside `input_tokens`; they are
+  moved out, not added, so nothing is billed twice.
+
+Pricing is arithmetic only — `costUsd(tokens, rates)`, `modelFamily` (a dated
+snapshot is priced at its family's row) and `findPrice(list, provider, model)`
+over `DEFAULT_PRICES`, the union of both apps' seeded tables with the date each
+rate was checked. **Where rates are kept is the app's decision**: AltEd and
+PharmaLine keep a dated table an operator can correct; a smaller app can price
+straight from the defaults. An unknown model is unpriced (`null`), never free.
+
+`@anthropic-ai/sdk`, `openai` and `zod` are optional peer dependencies — only an
+app that imports `/ai` needs them. The SDKs refuse to run in a browser-like
+environment, so a Vitest suite that calls the harness needs
+`// @vitest-environment node` on the file.
+
 ### Styles — `@connextar/house/house.css`
 
 What the components need that utility classes cannot say: rich text, the editor's

package/dist/ai/config.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Which model provider an instance uses, and which model it uses for which job.
+ *
+ * Extracted from AltEd and PharmaLine, which had each written this file and were
+ * about to be joined by a third. Two rules shape it, and both are why it is
+ * shared rather than copied.
+ *
+ * **Naming a provider is a decision, not a preference.** If `AI_PROVIDER` names
+ * a provider whose key is missing, the feature is *off* and says why — it does
+ * not quietly send a person's records to the other one. Silently switching
+ * processors would break the promise a privacy policy makes by name.
+ *
+ * **Jobs, not one model.** Sorting a bank line wants a small fast model; writing
+ * a report wants a capable one. The app names its jobs and, for each, the
+ * environment variable an operator sets per provider and a working default.
+ * The model name is provider-specific, so pointing `AI_PROVIDER` at OpenAI can
+ * never send a Claude model name to OpenAI.
+ *
+ * Deliberately free of `server-only` and of anything Next-specific: PharmaLine
+ * reads it from a plain Node service. An app binds it from a server-only
+ * module of its own, because the provider half reads API keys.
+ */
+export declare const AI_PROVIDERS: readonly ["ANTHROPIC", "OPENAI"];
+export type AiProviderName = (typeof AI_PROVIDERS)[number];
+/** How each provider is named to a person — in a privacy policy, in settings, in logs. */
+export declare const PROVIDER_LABELS: Record<AiProviderName, string>;
+/** The environment variable holding each provider's key. */
+export declare const PROVIDER_KEY_VARS: Record<AiProviderName, string>;
+/** One provider's model for one job: the variable an operator sets, and the default when they don't. */
+export interface AiModelSpec {
+    modelVar: string;
+    /** A working starting point. Every one is overridable; none is load-bearing. */
+    defaultModel: string;
+}
+/** One job the app gives a model. */
+export interface AiTaskSpec {
+    ANTHROPIC: AiModelSpec;
+    OPENAI: AiModelSpec;
+    /**
+     * Whether structured calls for this job ask Anthropic for adaptive thinking.
+     * Off unless the job says so: the small fast models (Haiku 4.5) reject the
+     * setting outright with a 400, and a job's default model is exactly where
+     * that knowledge belongs. A call can still override it.
+     */
+    thinking?: boolean;
+}
+/** The app's jobs, by name. */
+export type AiTaskTable<Task extends string> = Record<Task, AiTaskSpec>;
+/** Just the parts of the environment this module reads — so tests need no globals. */
+export type AiEnv = Record<string, string | undefined>;
+/** Providers with a key set, in preference order. */
+export declare function configuredProviders(env: AiEnv): AiProviderName[];
+export interface ProviderChoice {
+    provider: AiProviderName | null;
+    apiKey: string;
+    /** Set when the configuration is contradictory, for an operator to read. */
+    problem: string | null;
+}
+/**
+ * The provider this instance will use.
+ *
+ * `AI_PROVIDER` unset means "whichever is configured", preferring Anthropic when
+ * both are — an arbitrary but stable order, so adding a second key never silently
+ * moves an instance to a different processor. Nothing configured at all is not a
+ * problem, just a feature that is off.
+ */
+export declare function chooseProvider(env: AiEnv): ProviderChoice;
+/** The model this provider uses for this job — the operator's, or the default. */
+export declare function modelFor<Task extends string>(tasks: AiTaskTable<Task>, provider: AiProviderName, task: Task, env: AiEnv): string;
+export interface ResolvedAi {
+    provider: AiProviderName;
+    apiKey: string;
+    model: string;
+}
+/** Everything one call needs, or null when the feature is off. */
+export declare function resolveAi<Task extends string>(tasks: AiTaskTable<Task>, task: Task, env: AiEnv): ResolvedAi | null;
+export interface AiStatus<Task extends string = string> {
+    enabled: boolean;
+    provider: AiProviderName | null;
+    /** "Anthropic" / "OpenAI" — the name to show a person, and to name in a policy. */
+    providerLabel: string | null;
+    /** The model per job, when enabled. */
+    models: Record<Task, string> | null;
+    /** A misconfiguration worth telling an operator about, when there is one. */
+    problem: string | null;
+}
+/** What the settings and operator screens show. */
+export declare function aiStatus<Task extends string>(tasks: AiTaskTable<Task>, env: AiEnv): AiStatus<Task>;
+/**
+ * What a *person* may be told: everything but the misconfiguration.
+ *
+ * `problem` names environment variables and echoes the operator's configured
+ * provider — deployment detail, never a secret, but it has no business in a
+ * payload sent to every signed-in account (AltEd audit round 6). The operator
+ * screen, which is where somebody would act on it, still gets the full shape.
+ */
+export type PublicAiStatus<Task extends string = string> = Omit<AiStatus<Task>, "problem">;
+export declare function publicAiStatus<Task extends string>(tasks: AiTaskTable<Task>, env: AiEnv): PublicAiStatus<Task>;
+//# sourceMappingURL=config.d.ts.map

package/dist/ai/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/ai/config.ts"],"names":[],"mappings":"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"}

package/dist/ai/config.js

@@ -0,0 +1,99 @@
+/**
+ * Which model provider an instance uses, and which model it uses for which job.
+ *
+ * Extracted from AltEd and PharmaLine, which had each written this file and were
+ * about to be joined by a third. Two rules shape it, and both are why it is
+ * shared rather than copied.
+ *
+ * **Naming a provider is a decision, not a preference.** If `AI_PROVIDER` names
+ * a provider whose key is missing, the feature is *off* and says why — it does
+ * not quietly send a person's records to the other one. Silently switching
+ * processors would break the promise a privacy policy makes by name.
+ *
+ * **Jobs, not one model.** Sorting a bank line wants a small fast model; writing
+ * a report wants a capable one. The app names its jobs and, for each, the
+ * environment variable an operator sets per provider and a working default.
+ * The model name is provider-specific, so pointing `AI_PROVIDER` at OpenAI can
+ * never send a Claude model name to OpenAI.
+ *
+ * Deliberately free of `server-only` and of anything Next-specific: PharmaLine
+ * reads it from a plain Node service. An app binds it from a server-only
+ * module of its own, because the provider half reads API keys.
+ */
+export const AI_PROVIDERS = ["ANTHROPIC", "OPENAI"];
+/** How each provider is named to a person — in a privacy policy, in settings, in logs. */
+export const PROVIDER_LABELS = {
+    ANTHROPIC: "Anthropic",
+    OPENAI: "OpenAI",
+};
+/** The environment variable holding each provider's key. */
+export const PROVIDER_KEY_VARS = {
+    ANTHROPIC: "ANTHROPIC_API_KEY",
+    OPENAI: "OPENAI_API_KEY",
+};
+const read = (env, name) => (env[name] ?? "").trim();
+/** Providers with a key set, in preference order. */
+export function configuredProviders(env) {
+    return AI_PROVIDERS.filter((provider) => read(env, PROVIDER_KEY_VARS[provider]).length > 0);
+}
+/**
+ * The provider this instance will use.
+ *
+ * `AI_PROVIDER` unset means "whichever is configured", preferring Anthropic when
+ * both are — an arbitrary but stable order, so adding a second key never silently
+ * moves an instance to a different processor. Nothing configured at all is not a
+ * problem, just a feature that is off.
+ */
+export function chooseProvider(env) {
+    const requested = read(env, "AI_PROVIDER").toUpperCase();
+    if (requested) {
+        const named = AI_PROVIDERS.find((provider) => provider === requested);
+        if (!named) {
+            return {
+                provider: null,
+                apiKey: "",
+                problem: `AI_PROVIDER is set to “${read(env, "AI_PROVIDER")}” — expected ${AI_PROVIDERS.map((p) => p.toLowerCase()).join(" or ")}.`,
+            };
+        }
+        const apiKey = read(env, PROVIDER_KEY_VARS[named]);
+        if (!apiKey) {
+            return {
+                provider: null,
+                apiKey: "",
+                problem: `AI_PROVIDER names ${PROVIDER_LABELS[named]}, but ${PROVIDER_KEY_VARS[named]} is empty.`,
+            };
+        }
+        return { provider: named, apiKey, problem: null };
+    }
+    const [first] = configuredProviders(env);
+    if (!first)
+        return { provider: null, apiKey: "", problem: null };
+    return { provider: first, apiKey: read(env, PROVIDER_KEY_VARS[first]), problem: null };
+}
+/** The model this provider uses for this job — the operator's, or the default. */
+export function modelFor(tasks, provider, task, env) {
+    const spec = tasks[task][provider];
+    return read(env, spec.modelVar) || spec.defaultModel;
+}
+/** Everything one call needs, or null when the feature is off. */
+export function resolveAi(tasks, task, env) {
+    const choice = chooseProvider(env);
+    if (!choice.provider)
+        return null;
+    return { provider: choice.provider, apiKey: choice.apiKey, model: modelFor(tasks, choice.provider, task, env) };
+}
+/** What the settings and operator screens show. */
+export function aiStatus(tasks, env) {
+    const choice = chooseProvider(env);
+    if (!choice.provider) {
+        return { enabled: false, provider: null, providerLabel: null, models: null, problem: choice.problem };
+    }
+    const provider = choice.provider;
+    const models = Object.fromEntries(Object.keys(tasks).map((task) => [task, modelFor(tasks, provider, task, env)]));
+    return { enabled: true, provider, providerLabel: PROVIDER_LABELS[provider], models, problem: null };
+}
+export function publicAiStatus(tasks, env) {
+    const { enabled, provider, providerLabel, models } = aiStatus(tasks, env);
+    return { enabled, provider, providerLabel, models };
+}
+//# sourceMappingURL=config.js.map

package/dist/ai/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/ai/config.ts"],"names":[],"mappings":"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"}

package/dist/ai/index.d.ts

@@ -0,0 +1,4 @@
+export { AI_PROVIDERS, PROVIDER_KEY_VARS, PROVIDER_LABELS, aiStatus, chooseProvider, configuredProviders, modelFor, publicAiStatus, resolveAi, type AiEnv, type AiModelSpec, type AiProviderName, type AiStatus, type AiTaskSpec, type AiTaskTable, type ProviderChoice, type PublicAiStatus, type ResolvedAi, } from "./config.js";
+export { AI_IMAGE_TYPES, AiServiceError, AiUnavailableError, AiUnusableAnswerError, OPENAI_MIN_OUTPUT_TOKENS, createAiHarness, isAiImageType, type AiCallResult, type AiHarness, type AiHarnessOptions, type AiImage, type AiImageType, type AiStructuredCall, type AiTextCall, } from "./provider.js";
+export { DEFAULT_PRICES, costUsd, findPrice, modelFamily, type ModelPrice, type PriceRates, type TokenCounts, } from "./pricing.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/ai/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ai/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,QAAQ,EACR,cAAc,EACd,mBAAmB,EACnB,QAAQ,EACR,cAAc,EACd,SAAS,EACT,KAAK,KAAK,EACV,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,UAAU,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,qBAAqB,EACrB,wBAAwB,EACxB,eAAe,EACf,aAAa,EACb,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,UAAU,GAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,cAAc,EACd,OAAO,EACP,SAAS,EACT,WAAW,EACX,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,WAAW,GACjB,MAAM,cAAc,CAAC"}

package/dist/ai/index.js

@@ -0,0 +1,4 @@
+export { AI_PROVIDERS, PROVIDER_KEY_VARS, PROVIDER_LABELS, aiStatus, chooseProvider, configuredProviders, modelFor, publicAiStatus, resolveAi, } from "./config.js";
+export { AI_IMAGE_TYPES, AiServiceError, AiUnavailableError, AiUnusableAnswerError, OPENAI_MIN_OUTPUT_TOKENS, createAiHarness, isAiImageType, } from "./provider.js";
+export { DEFAULT_PRICES, costUsd, findPrice, modelFamily, } from "./pricing.js";
+//# sourceMappingURL=index.js.map

package/dist/ai/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ai/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,QAAQ,EACR,cAAc,EACd,mBAAmB,EACnB,QAAQ,EACR,cAAc,EACd,SAAS,GAUV,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,qBAAqB,EACrB,wBAAwB,EACxB,eAAe,EACf,aAAa,GAQd,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,cAAc,EACd,OAAO,EACP,SAAS,EACT,WAAW,GAIZ,MAAM,cAAc,CAAC"}

package/dist/ai/pricing.d.ts

@@ -0,0 +1,51 @@
+import type { AiProviderName } from "./config.js";
+/**
+ * What a model call costs, at the provider's published rates.
+ *
+ * The arithmetic and the starting rates only. Where the rates are *kept* is each
+ * app's decision — AltEd and PharmaLine keep a dated price table an operator can
+ * correct; a smaller app can price straight from `DEFAULT_PRICES` — so nothing
+ * here touches a database. Nothing here is the source of truth for a price
+ * either: the provider's pricing page is, which is why every row records where
+ * it came from and when.
+ */
+export interface PriceRates {
+    inputPerMillionUsd: number;
+    outputPerMillionUsd: number;
+    cacheReadPerMillionUsd: number;
+    cacheWritePerMillionUsd: number;
+}
+export interface ModelPrice extends PriceRates {
+    provider: AiProviderName;
+    model: string;
+    source: string;
+}
+/**
+ * The rates the portfolio's apps start from — the union of AltEd's and
+ * PharmaLine's seeded tables. A model missing from here is unpriced, not free:
+ * `findPrice` returns null and the caller records the tokens without a cost.
+ */
+export declare const DEFAULT_PRICES: readonly ModelPrice[];
+/**
+ * The family a reported model id belongs to.
+ *
+ * Providers report dated snapshots (`claude-haiku-4-5-20251001`) and priced
+ * variants (`gpt-5-2026-03-01`) of a family that is priced once. The date
+ * suffix is dropped for the lookup, so a row for the family covers them all —
+ * and an exact row, when one exists, still wins.
+ */
+export declare function modelFamily(model: string): string;
+/** The rate for a model from a list: an exact row first, then its family's. Null when none is known. */
+export declare function findPrice<P extends {
+    provider: AiProviderName;
+    model: string;
+}>(prices: readonly P[], provider: AiProviderName, model: string): P | null;
+export interface TokenCounts {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+}
+/** The cost of a call at a rate, in USD. Six decimals: a Haiku call is fractions of a cent. */
+export declare function costUsd(tokens: TokenCounts, rates: PriceRates): number;
+//# sourceMappingURL=pricing.d.ts.map

package/dist/ai/pricing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.d.ts","sourceRoot":"","sources":["../../src/ai/pricing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;;;GASG;AAEH,MAAM,WAAW,UAAU;IACzB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,uBAAuB,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,UAAW,SAAQ,UAAU;IAC5C,QAAQ,EAAE,cAAc,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AA0BD;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,UAAU,EAQ9C,CAAC;AAEH;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,wGAAwG;AACxG,wBAAgB,SAAS,CAAC,CAAC,SAAS;IAAE,QAAQ,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAC7E,MAAM,EAAE,SAAS,CAAC,EAAE,EACpB,QAAQ,EAAE,cAAc,EACxB,KAAK,EAAE,MAAM,GACZ,CAAC,GAAG,IAAI,CAMV;AAED,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,+FAA+F;AAC/F,wBAAgB,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAQtE"}

package/dist/ai/pricing.js

@@ -0,0 +1,65 @@
+const ANTHROPIC_SOURCE = "Anthropic API pricing, checked 2026-06-24 — cache reads 10% of input, cache writes 125%";
+const OPENAI_SOURCE = "OpenAI API pricing, checked 2026-09-07 — cached input 10% of input, no write premium";
+/** Per million tokens, USD. Cache multipliers are each provider's published rule. */
+const anthropic = (model, input, output) => ({
+    provider: "ANTHROPIC",
+    model,
+    inputPerMillionUsd: input,
+    outputPerMillionUsd: output,
+    cacheReadPerMillionUsd: input * 0.1,
+    cacheWritePerMillionUsd: input * 1.25,
+    source: ANTHROPIC_SOURCE,
+});
+const openai = (model, input, output) => ({
+    provider: "OPENAI",
+    model,
+    inputPerMillionUsd: input,
+    outputPerMillionUsd: output,
+    cacheReadPerMillionUsd: input * 0.1,
+    cacheWritePerMillionUsd: input,
+    source: OPENAI_SOURCE,
+});
+/**
+ * The rates the portfolio's apps start from — the union of AltEd's and
+ * PharmaLine's seeded tables. A model missing from here is unpriced, not free:
+ * `findPrice` returns null and the caller records the tokens without a cost.
+ */
+export const DEFAULT_PRICES = Object.freeze([
+    anthropic("claude-opus-5", 5, 25),
+    anthropic("claude-sonnet-5", 2, 10),
+    anthropic("claude-haiku-4-5", 1, 5),
+    anthropic("claude-opus-4-8", 5, 25),
+    anthropic("claude-sonnet-4-6", 3, 15),
+    openai("gpt-5", 1.25, 10),
+    openai("gpt-5-mini", 0.25, 2),
+]);
+/**
+ * The family a reported model id belongs to.
+ *
+ * Providers report dated snapshots (`claude-haiku-4-5-20251001`) and priced
+ * variants (`gpt-5-2026-03-01`) of a family that is priced once. The date
+ * suffix is dropped for the lookup, so a row for the family covers them all —
+ * and an exact row, when one exists, still wins.
+ */
+export function modelFamily(model) {
+    return model.replace(/[-_]?\d{4}-?\d{2}-?\d{2}$/, "");
+}
+/** The rate for a model from a list: an exact row first, then its family's. Null when none is known. */
+export function findPrice(prices, provider, model) {
+    for (const candidate of [...new Set([model, modelFamily(model)])]) {
+        const row = prices.find((price) => price.provider === provider && price.model === candidate);
+        if (row)
+            return row;
+    }
+    return null;
+}
+/** The cost of a call at a rate, in USD. Six decimals: a Haiku call is fractions of a cent. */
+export function costUsd(tokens, rates) {
+    const per = (count, rate) => (count / 1_000_000) * rate;
+    const total = per(tokens.inputTokens, rates.inputPerMillionUsd) +
+        per(tokens.outputTokens, rates.outputPerMillionUsd) +
+        per(tokens.cacheReadTokens ?? 0, rates.cacheReadPerMillionUsd) +
+        per(tokens.cacheWriteTokens ?? 0, rates.cacheWritePerMillionUsd);
+    return Math.round(total * 1_000_000) / 1_000_000;
+}
+//# sourceMappingURL=pricing.js.map

package/dist/ai/pricing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.js","sourceRoot":"","sources":["../../src/ai/pricing.ts"],"names":[],"mappings":"AA0BA,MAAM,gBAAgB,GAAG,yFAAyF,CAAC;AACnH,MAAM,aAAa,GAAG,sFAAsF,CAAC;AAE7G,qFAAqF;AACrF,MAAM,SAAS,GAAG,CAAC,KAAa,EAAE,KAAa,EAAE,MAAc,EAAc,EAAE,CAAC,CAAC;IAC/E,QAAQ,EAAE,WAAW;IACrB,KAAK;IACL,kBAAkB,EAAE,KAAK;IACzB,mBAAmB,EAAE,MAAM;IAC3B,sBAAsB,EAAE,KAAK,GAAG,GAAG;IACnC,uBAAuB,EAAE,KAAK,GAAG,IAAI;IACrC,MAAM,EAAE,gBAAgB;CACzB,CAAC,CAAC;AAEH,MAAM,MAAM,GAAG,CAAC,KAAa,EAAE,KAAa,EAAE,MAAc,EAAc,EAAE,CAAC,CAAC;IAC5E,QAAQ,EAAE,QAAQ;IAClB,KAAK;IACL,kBAAkB,EAAE,KAAK;IACzB,mBAAmB,EAAE,MAAM;IAC3B,sBAAsB,EAAE,KAAK,GAAG,GAAG;IACnC,uBAAuB,EAAE,KAAK;IAC9B,MAAM,EAAE,aAAa;CACtB,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAA0B,MAAM,CAAC,MAAM,CAAC;IACjE,SAAS,CAAC,eAAe,EAAE,CAAC,EAAE,EAAE,CAAC;IACjC,SAAS,CAAC,iBAAiB,EAAE,CAAC,EAAE,EAAE,CAAC;IACnC,SAAS,CAAC,kBAAkB,EAAE,CAAC,EAAE,CAAC,CAAC;IACnC,SAAS,CAAC,iBAAiB,EAAE,CAAC,EAAE,EAAE,CAAC;IACnC,SAAS,CAAC,mBAAmB,EAAE,CAAC,EAAE,EAAE,CAAC;IACrC,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC;IACzB,MAAM,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;CAC9B,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO,KAAK,CAAC,OAAO,CAAC,2BAA2B,EAAE,EAAE,CAAC,CAAC;AACxD,CAAC;AAED,wGAAwG;AACxG,MAAM,UAAU,SAAS,CACvB,MAAoB,EACpB,QAAwB,EACxB,KAAa;IAEb,KAAK,MAAM,SAAS,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAClE,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,KAAK,QAAQ,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC;QAC7F,IAAI,GAAG;YAAE,OAAO,GAAG,CAAC;IACtB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AASD,+FAA+F;AAC/F,MAAM,UAAU,OAAO,CAAC,MAAmB,EAAE,KAAiB;IAC5D,MAAM,GAAG,GAAG,CAAC,KAAa,EAAE,IAAY,EAAE,EAAE,CAAC,CAAC,KAAK,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC;IACxE,MAAM,KAAK,GACT,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,kBAAkB,CAAC;QACjD,GAAG,CAAC,MAAM,CAAC,YAAY,EAAE,KAAK,CAAC,mBAAmB,CAAC;QACnD,GAAG,CAAC,MAAM,CAAC,eAAe,IAAI,CAAC,EAAE,KAAK,CAAC,sBAAsB,CAAC;QAC9D,GAAG,CAAC,MAAM,CAAC,gBAAgB,IAAI,CAAC,EAAE,KAAK,CAAC,uBAAuB,CAAC,CAAC;IACnE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;AACnD,CAAC"}

package/dist/ai/provider.d.ts

@@ -0,0 +1,146 @@
+import type { z } from "zod";
+import { type AiEnv, type AiProviderName, type AiStatus, type AiTaskTable, type PublicAiStatus, type ResolvedAi } from "./config.js";
+/**
+ * The one place either provider's SDK is called.
+ *
+ * Everything above this file asks for a job — "sort these bank lines", "write
+ * this month's summary" — and gets back text or a parsed object plus what it
+ * cost. Which company answered is a deployment decision (`config.ts`), not a
+ * decision any feature makes.
+ *
+ * The harness hides three real differences between the providers, and
+ * deliberately hides nothing else:
+ *
+ * 1. **Long requests must stream.** Both SDKs refuse a non-streaming call that
+ *    could outlive their timeout, and transcribing a sixty-page document can.
+ *    Structured calls stream and read the final message; nothing consumes the
+ *    intermediate events.
+ * 2. **Output budgets mean different things.** An OpenAI reasoning model spends
+ *    `max_output_tokens` on its reasoning before it writes a word, so a budget
+ *    that is generous for Anthropic can return nothing at all. Hence the floor.
+ * 3. **Tuning parameters are model-specific.** Adaptive thinking and effort are
+ *    sent only where they are asked for, and a model that rejects them produces
+ *    a clear error naming the provider rather than a 500.
+ *
+ * Ported from AltEd's `lib/ai/provider.ts`, where it has run in production since
+ * tranche 113; the only change is that the jobs are the app's to name.
+ */
+/** The feature is off, or the request never reached a model. */
+export declare class AiUnavailableError extends Error {
+    constructor(message?: string);
+}
+/** The provider answered, and said no. Carries its words: an operator can act on them. */
+export declare class AiServiceError extends Error {
+    readonly status: number | undefined;
+    constructor(message: string, status?: number);
+}
+/**
+ * The provider answered, but not with something usable — a refusal, a cut-off
+ * or an answer in the wrong shape. The tokens were spent all the same, so the
+ * usage travels with the error for the caller to record (AltEd round 10: these
+ * were free, and a failed step could be tried again without limit).
+ */
+export declare class AiUnusableAnswerError extends AiUnavailableError {
+    readonly usage: AiCallResult;
+    constructor(message: string, usage: AiCallResult);
+}
+export interface AiCallResult {
+    provider: AiProviderName;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    /** Prompt tokens the provider served from its cache, and wrote to it. Billed apart. */
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+}
+export interface AiTextCall<Task extends string> {
+    task: Task;
+    system: string;
+    prompt: string;
+    /** Words the answer may run to. Raised automatically where reasoning shares the budget. */
+    maxTokens: number;
+    /**
+     * The longest the call may take, in milliseconds, with no retries — what is
+     * left of a serverless request, so a slow answer fails as an error rather than
+     * the function being killed mid-call.
+     */
+    timeoutMs?: number;
+}
+/** The image types both providers accept inline. */
+export declare const AI_IMAGE_TYPES: readonly ["image/jpeg", "image/png", "image/gif", "image/webp"];
+export type AiImageType = (typeof AI_IMAGE_TYPES)[number];
+export declare function isAiImageType(value: string): value is AiImageType;
+export interface AiImage {
+    mediaType: AiImageType;
+    /** Base64, no data-URL prefix. */
+    base64: string;
+}
+export interface AiStructuredCall<Task extends string, T> extends AiTextCall<Task> {
+    schema: z.ZodType<T>;
+    /** A name for the schema. OpenAI requires one; Anthropic ignores it. */
+    schemaName: string;
+    /** A PDF for the model to read. Both providers fetch it themselves. */
+    documentUrl?: string;
+    /**
+     * Pictures for the model to look at, sent inline and in order. Inline rather
+     * than a URL because most of what an app shows a model sits behind its own
+     * access check — there is no public URL for a provider to fetch, and there
+     * must not be one.
+     */
+    images?: AiImage[];
+    /**
+     * Whether to ask Anthropic for adaptive thinking. Defaults to the job's own
+     * `thinking` setting. OpenAI's reasoning is the model's own and is unaffected.
+     */
+    thinking?: boolean;
+    /**
+     * How hard to think, on providers and models that take the instruction.
+     * Anthropic-only: OpenAI's reasoning effort is left at the model's default so
+     * that a non-reasoning model an operator chooses still works.
+     */
+    effort?: "medium" | "high";
+}
+/**
+ * An OpenAI reasoning model bills its thinking against the same budget as its
+ * answer, so a 900-token ceiling can be spent entirely before the prose starts.
+ * Small requests get room; large ones already have it.
+ */
+export declare const OPENAI_MIN_OUTPUT_TOKENS = 4000;
+export interface AiHarnessOptions<Task extends string> {
+    /** The app's jobs, each with a model per provider. */
+    tasks: AiTaskTable<Task>;
+    /** Where configuration is read from, on every call. Defaults to `process.env`. */
+    env?: () => AiEnv;
+}
+export interface AiHarness<Task extends string> {
+    /** Everything one call would use, or null when the feature is off. Never logged: it holds the key. */
+    resolve(task: Task): ResolvedAi | null;
+    /** For an operator: includes a misconfiguration, when there is one. */
+    status(): AiStatus<Task>;
+    /** For a person: everything but the misconfiguration. */
+    publicStatus(): PublicAiStatus<Task>;
+    /** Prose, from a system prompt and one user message. */
+    generateText(call: AiTextCall<Task>): Promise<AiCallResult & {
+        text: string;
+    }>;
+    /** A parsed object in the shape of a Zod schema, optionally read from a PDF or pictures. */
+    generateStructured<T>(call: AiStructuredCall<Task, T>): Promise<AiCallResult & {
+        parsed: T;
+    }>;
+}
+/**
+ * Bind the harness to an app's jobs.
+ *
+ * ```ts
+ * export const ai = createAiHarness({
+ *   tasks: {
+ *     categorise: {
+ *       ANTHROPIC: { modelVar: "ANTHROPIC_MODEL", defaultModel: "claude-haiku-4-5-20251001" },
+ *       OPENAI: { modelVar: "OPENAI_MODEL", defaultModel: "gpt-5-mini" },
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare function createAiHarness<Task extends string>(options: AiHarnessOptions<Task>): AiHarness<Task>;
+//# sourceMappingURL=provider.d.ts.map

package/dist/ai/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/ai/provider.ts"],"names":[],"mappings":"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"}

package/dist/ai/provider.js

@@ -0,0 +1,234 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";
+import OpenAI from "openai";
+import { zodTextFormat } from "openai/helpers/zod";
+import { aiStatus, PROVIDER_LABELS, publicAiStatus, resolveAi, } from "./config.js";
+/**
+ * The one place either provider's SDK is called.
+ *
+ * Everything above this file asks for a job — "sort these bank lines", "write
+ * this month's summary" — and gets back text or a parsed object plus what it
+ * cost. Which company answered is a deployment decision (`config.ts`), not a
+ * decision any feature makes.
+ *
+ * The harness hides three real differences between the providers, and
+ * deliberately hides nothing else:
+ *
+ * 1. **Long requests must stream.** Both SDKs refuse a non-streaming call that
+ *    could outlive their timeout, and transcribing a sixty-page document can.
+ *    Structured calls stream and read the final message; nothing consumes the
+ *    intermediate events.
+ * 2. **Output budgets mean different things.** An OpenAI reasoning model spends
+ *    `max_output_tokens` on its reasoning before it writes a word, so a budget
+ *    that is generous for Anthropic can return nothing at all. Hence the floor.
+ * 3. **Tuning parameters are model-specific.** Adaptive thinking and effort are
+ *    sent only where they are asked for, and a model that rejects them produces
+ *    a clear error naming the provider rather than a 500.
+ *
+ * Ported from AltEd's `lib/ai/provider.ts`, where it has run in production since
+ * tranche 113; the only change is that the jobs are the app's to name.
+ */
+/** The feature is off, or the request never reached a model. */
+export class AiUnavailableError extends Error {
+    constructor(message = "AI isn't available on this instance — no model is configured.") {
+        super(message);
+        this.name = "AiUnavailableError";
+    }
+}
+/** The provider answered, and said no. Carries its words: an operator can act on them. */
+export class AiServiceError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = "AiServiceError";
+        this.status = status;
+    }
+}
+/**
+ * The provider answered, but not with something usable — a refusal, a cut-off
+ * or an answer in the wrong shape. The tokens were spent all the same, so the
+ * usage travels with the error for the caller to record (AltEd round 10: these
+ * were free, and a failed step could be tried again without limit).
+ */
+export class AiUnusableAnswerError extends AiUnavailableError {
+    usage;
+    constructor(message, usage) {
+        super(message);
+        this.name = "AiUnusableAnswerError";
+        this.usage = usage;
+    }
+}
+/** The image types both providers accept inline. */
+export const AI_IMAGE_TYPES = ["image/jpeg", "image/png", "image/gif", "image/webp"];
+export function isAiImageType(value) {
+    return AI_IMAGE_TYPES.includes(value);
+}
+/**
+ * An OpenAI reasoning model bills its thinking against the same budget as its
+ * answer, so a 900-token ceiling can be spent entirely before the prose starts.
+ * Small requests get room; large ones already have it.
+ */
+export const OPENAI_MIN_OUTPUT_TOKENS = 4000;
+/** Turn either SDK's error into one a route can report in the provider's own words. */
+function asServiceError(error, provider) {
+    if (error instanceof Anthropic.APIError || error instanceof OpenAI.APIError) {
+        // The two SDKs type `status` differently; narrow rather than trust either.
+        const status = typeof error.status === "number" ? error.status : undefined;
+        throw new AiServiceError(`${PROVIDER_LABELS[provider]} refused the request (${status ?? "no status"}): ${error.message}`, status);
+    }
+    throw error;
+}
+/** OpenAI counts cached prompt tokens inside `input_tokens`; move them out rather than bill them twice. */
+function openAiUsage(provider, model, usage) {
+    const cached = usage?.input_tokens_details?.cached_tokens ?? 0;
+    return {
+        provider,
+        model,
+        inputTokens: (usage?.input_tokens ?? 0) - cached,
+        outputTokens: usage?.output_tokens ?? 0,
+        cacheReadTokens: cached,
+        cacheWriteTokens: 0,
+    };
+}
+function anthropicUsage(provider, message) {
+    return {
+        provider,
+        model: message.model,
+        inputTokens: message.usage.input_tokens,
+        outputTokens: message.usage.output_tokens,
+        cacheReadTokens: message.usage.cache_read_input_tokens ?? 0,
+        cacheWriteTokens: message.usage.cache_creation_input_tokens ?? 0,
+    };
+}
+/**
+ * Bind the harness to an app's jobs.
+ *
+ * ```ts
+ * export const ai = createAiHarness({
+ *   tasks: {
+ *     categorise: {
+ *       ANTHROPIC: { modelVar: "ANTHROPIC_MODEL", defaultModel: "claude-haiku-4-5-20251001" },
+ *       OPENAI: { modelVar: "OPENAI_MODEL", defaultModel: "gpt-5-mini" },
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export function createAiHarness(options) {
+    const { tasks } = options;
+    const env = options.env ?? (() => process.env);
+    function resolve(task) {
+        const config = resolveAi(tasks, task, env());
+        if (!config)
+            throw new AiUnavailableError();
+        return config;
+    }
+    async function generateText(call) {
+        const { provider, apiKey, model } = resolve(call.task);
+        const requestOptions = call.timeoutMs ? { timeout: call.timeoutMs, maxRetries: 0 } : undefined;
+        try {
+            if (provider === "ANTHROPIC") {
+                const message = await new Anthropic({ apiKey }).messages.create({
+                    model,
+                    max_tokens: call.maxTokens,
+                    system: call.system,
+                    messages: [{ role: "user", content: call.prompt }],
+                }, requestOptions);
+                const text = message.content
+                    .filter((block) => block.type === "text")
+                    .map((block) => block.text)
+                    .join("\n")
+                    .trim();
+                return { text, ...anthropicUsage(provider, message) };
+            }
+            const response = await new OpenAI({ apiKey }).responses.create({
+                model,
+                instructions: call.system,
+                input: call.prompt,
+                max_output_tokens: Math.max(call.maxTokens, OPENAI_MIN_OUTPUT_TOKENS),
+            }, requestOptions);
+            return { text: response.output_text.trim(), ...openAiUsage(provider, response.model, response.usage) };
+        }
+        catch (error) {
+            asServiceError(error, provider);
+        }
+    }
+    async function generateStructured(call) {
+        const { provider, apiKey, model } = resolve(call.task);
+        const requestOptions = call.timeoutMs ? { timeout: call.timeoutMs, maxRetries: 0 } : undefined;
+        const thinking = call.thinking ?? tasks[call.task].thinking ?? false;
+        try {
+            if (provider === "ANTHROPIC") {
+                const content = [];
+                if (call.documentUrl)
+                    content.push({ type: "document", source: { type: "url", url: call.documentUrl } });
+                for (const image of call.images ?? []) {
+                    content.push({
+                        type: "image",
+                        source: { type: "base64", media_type: image.mediaType, data: image.base64 },
+                    });
+                }
+                content.push({ type: "text", text: call.prompt });
+                // Streamed, not because anything reads the stream, but because the SDK
+                // refuses a non-streaming call that could run past ten minutes.
+                const stream = new Anthropic({ apiKey }).messages.stream({
+                    model,
+                    max_tokens: call.maxTokens,
+                    system: call.system,
+                    ...(thinking ? { thinking: { type: "adaptive" } } : {}),
+                    output_config: { ...(call.effort ? { effort: call.effort } : {}), format: zodOutputFormat(call.schema) },
+                    messages: [{ role: "user", content }],
+                }, requestOptions);
+                const response = await stream.finalMessage();
+                const usage = anthropicUsage(provider, response);
+                if (response.stop_reason === "refusal") {
+                    throw new AiUnusableAnswerError("The model declined to process this request.", usage);
+                }
+                if (response.parsed_output === null || response.parsed_output === undefined) {
+                    throw new AiUnusableAnswerError("The model's answer did not match the expected shape.", usage);
+                }
+                return { parsed: response.parsed_output, ...usage };
+            }
+            const content = [];
+            if (call.documentUrl)
+                content.push({ type: "input_file", file_url: call.documentUrl });
+            for (const image of call.images ?? []) {
+                content.push({
+                    type: "input_image",
+                    image_url: `data:${image.mediaType};base64,${image.base64}`,
+                    detail: "auto",
+                });
+            }
+            content.push({ type: "input_text", text: call.prompt });
+            const stream = new OpenAI({ apiKey }).responses.stream({
+                model,
+                instructions: call.system,
+                input: [{ role: "user", content }],
+                max_output_tokens: Math.max(call.maxTokens, OPENAI_MIN_OUTPUT_TOKENS),
+                text: { format: zodTextFormat(call.schema, call.schemaName) },
+            }, requestOptions);
+            const response = await stream.finalResponse();
+            const usage = openAiUsage(provider, response.model, response.usage);
+            if (response.status === "incomplete") {
+                throw new AiUnusableAnswerError(`The answer was cut off before it was complete (${response.incomplete_details?.reason ?? "no reason given"}). Try a model with more room, or a shorter input.`, usage);
+            }
+            if (response.output_parsed === null || response.output_parsed === undefined) {
+                throw new AiUnusableAnswerError("The model's answer did not match the expected shape.", usage);
+            }
+            return { parsed: response.output_parsed, ...usage };
+        }
+        catch (error) {
+            if (error instanceof AiUnavailableError)
+                throw error;
+            asServiceError(error, provider);
+        }
+    }
+    return {
+        resolve: (task) => resolveAi(tasks, task, env()),
+        status: () => aiStatus(tasks, env()),
+        publicStatus: () => publicAiStatus(tasks, env()),
+        generateText,
+        generateStructured,
+    };
+}
+//# sourceMappingURL=provider.js.map

package/dist/ai/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/ai/provider.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@connextar/house",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "The pieces every app we build needs and none of them should own a copy of.",
   "license": "MIT",
   "repository": {
@@ -14,6 +14,10 @@
     "docs"
   ],
   "exports": {
+    "./ai": {
+      "types": "./dist/ai/index.d.ts",
+      "default": "./dist/ai/index.js"
+    },
     "./errors": {
       "types": "./dist/errors/index.d.ts",
       "default": "./dist/errors/index.js"
@@ -103,10 +107,13 @@
     "check:ci": "npm run lint:check && npm run format:check && npm run typecheck"
   },
   "peerDependencies": {
+    "@anthropic-ai/sdk": ">=0.122.0",
     "next": "^16.0.0",
+    "openai": ">=7.10.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "react-hook-form": "^7.60.0"
+    "react-hook-form": "^7.60.0",
+    "zod": "^3.25.0 || ^4.0.0"
   },
   "peerDependenciesMeta": {
     "next": {
@@ -114,9 +121,19 @@
     },
     "react-hook-form": {
       "optional": true
+    },
+    "@anthropic-ai/sdk": {
+      "optional": true
+    },
+    "openai": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@anthropic-ai/sdk": "^0.128.0",
     "@eslint/js": "^9.39.5",
     "@testing-library/react": "^16.3.3",
     "@types/node": "^26.4.1",
@@ -127,13 +144,15 @@
     "eslint": "^9.0.0",
     "jsdom": "^27.4.0",
     "next": "^16.3.3",
+    "openai": "^7.23.0",
     "prettier": "^3.0.0",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "react-hook-form": "^7.68.0",
     "typescript": "^5.7.0",
     "typescript-eslint": "^8.69.0",
-    "vitest": "^4.0.0"
+    "vitest": "^4.0.0",
+    "zod": "^4.6.5"
   },
   "publishConfig": {
     "access": "public"