@profullstack/ai-providers 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 Profullstack, Inc.

package/README.md

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# @profullstack/ai-providers
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+One way for every Profullstack app to call a text model.
+
+1. **c0mpute first, always.** Jobs go to the peer network through Infernet's chat API, peer nodes only (`p2p_only`), never Infernet's billed hosted fallback.
+2. **OpenAI and Anthropic only as fallbacks, alternating.** Call 1 falls back to OpenAI then Anthropic, call 2 to Anthropic then OpenAI. Neither bill takes all the overflow.
+3. **Dead keys are parked, not retried.** No credits or a bad key parks that provider for an hour. A 429, a 5xx or no free node parks it for 30 seconds, doubling up to 10 minutes. A success clears it.
+
+No dependencies. Node 20+, Bun, Workers: anything with `fetch`.
+
+```sh
+npm i @profullstack/ai-providers
+```
+
+## Use
+
+```js
+import { generateText, generateObject } from '@profullstack/ai-providers';
+
+const { text, provider, model } = await generateText({
+  system: 'You write short product copy.',
+  user: 'One line for a coffee grinder.',
+  maxTokens: 200,
+});
+
+// JSON: pulled out of whatever the model wrapped it in, validated, and
+// repaired once on the same provider before moving to the next one.
+import { z } from 'zod';
+const Ad = z.object({ headline: z.string(), body: z.string() });
+const { object } = await generateObject({
+  name: 'Ad',
+  schema: Ad,
+  jsonSchema: z.toJSONSchema(Ad),
+  user: 'Ad copy for crawlproof.com',
+});
+```
+
+`generateText` and `generateObject` share one router per process (`getAi()`), so rotation and parking see every call. Build your own with `createAiProviders({ env, c0mpute, openai, anthropic, router })`.
+
+### Keep your own provider code
+
+An app with tuned SDK calls (structured outputs, prompt caching, spend tracking) keeps them and uses the router only for order, rotation and parking:
+
+```js
+import { getAi, generateObjectOn } from '@profullstack/ai-providers';
+
+const { provider, value } = await getAi().run(async (p) => {
+  if (p.name === 'anthropic') return myAnthropicCall();
+  if (p.name === 'openai') return myOpenAICall();
+  return (await generateObjectOn(p, req)).object; // c0mpute
+});
+```
+
+A thrown error with `status` 401/402/403, or a 429 or 400 that mentions credits or billing, parks that provider as `billing`.
+
+## Environment
+
+| Variable | Default | |
+|---|---|---|
+| `C0MPUTE_API_KEY` | none | Infernet trusted-client key (`ifc_...`), one per app. Without it the public limit is 20 requests an hour per IP. |
+| `C0MPUTE_URL` | `https://infernetprotocol.com` | |
+| `C0MPUTE_MODELS` | `huihui_ai/qwen3.5-abliterated:9b,qwen2.5:7b,qwen3:4b,gemma3:4b,huihui_ai/qwen3.5-abliterated:4b` | Tried in order. The first is an Infernet house model every node pulls. |
+| `C0MPUTE_ANY_MODEL` | off | Let any free node answer as a last resort. Small models write junk JSON. |
+| `C0MPUTE_CONCURRENCY` | 2 | c0mpute jobs in flight per process. |
+| `C0MPUTE_STALL_MS` | 90000 | A job that streams nothing this long is dropped and the next model tried. |
+| `C0MPUTE_TIMEOUT_MS` | 300000 | Whole call. |
+| `C0MPUTE_DISABLED` | off | `1` skips c0mpute. |
+| `OPENAI_API_KEY`, `AI_OPENAI_MODEL` | `gpt-5-mini` | Fallback. |
+| `ANTHROPIC_API_KEY`, `AI_ANTHROPIC_MODEL` | `claude-haiku-5-5` | Fallback. |
+| `AI_PAID_FALLBACK` | on | `off` never calls a paid provider (OutreachGraph's rule). |
+
+## CLI
+
+```sh
+npx @profullstack/ai-providers status
+npx @profullstack/ai-providers ask "one line about c0mpute"
+npx @profullstack/ai-providers ask --json 'Return {"ok": true}'
+```
+
+## What c0mpute does not do
+
+Images and embeddings. Apps that generate images keep their image provider and must already cope with it failing.
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,195 @@
+export type ProviderName = 'c0mpute' | 'openai' | 'anthropic' | (string & {});
+export type FailureKind = 'billing' | 'capacity' | 'invalid' | 'output';
+
+export interface ChatMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+
+export interface TextRequest {
+  system?: string;
+  /** Single user turn. Ignored when `messages` is set. */
+  user?: string;
+  messages?: ChatMessage[];
+  maxTokens?: number;
+  temperature?: number;
+  /** Ask for a JSON object (OpenAI json_object mode; the others are told so). */
+  json?: boolean;
+  /** Per-provider model override for this call. */
+  models?: { c0mpute?: string; openai?: string; anthropic?: string };
+  /** Label passed to onAttempt, for spend and failure logs. */
+  feature?: string;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+export interface Usage {
+  inputTokens: number;
+  outputTokens: number;
+  /** true when counted as characters / 4 (c0mpute reports no token counts). */
+  estimated: boolean;
+}
+
+export interface ProviderOutput {
+  text: string;
+  model: string;
+  usage: Usage;
+}
+
+export interface TextProvider {
+  readonly name: ProviderName;
+  generate(req: TextRequest): Promise<ProviderOutput>;
+}
+
+export interface Attempt {
+  provider: string;
+  error: ProviderError;
+}
+
+export interface TextResult extends ProviderOutput {
+  provider: ProviderName;
+  attempts: Attempt[];
+}
+
+/** Anything with safeParse (zod), parse, or a plain function. */
+export type SchemaLike<T> =
+  | { safeParse(v: unknown): { success: true; data: T } | { success: false; error: any } }
+  | { parse(v: unknown): T }
+  | ((v: unknown) => T);
+
+export interface ObjectRequest<T = unknown> extends TextRequest {
+  schema?: SchemaLike<T>;
+  /** Shown to the model. With zod 4: z.toJSONSchema(schema). */
+  jsonSchema?: Record<string, unknown>;
+  name?: string;
+  /** Repair attempts per provider after an unusable answer. Default 1. */
+  repairs?: number;
+}
+
+export interface ObjectResult<T> {
+  object: T;
+  text: string;
+  model: string;
+  usage: Usage;
+  provider: ProviderName;
+  attempts: Attempt[];
+}
+
+export interface AttemptEvent {
+  provider: string;
+  feature?: string;
+  ok: boolean;
+  ms: number;
+  kind?: FailureKind;
+  error?: string;
+}
+
+export interface RouterOptions {
+  primary?: TextProvider[];
+  fallback?: TextProvider[];
+  /** Alternate the fallback order every call. Default true. */
+  rotate?: boolean;
+  billingMs?: number;
+  capacityMs?: number;
+  capacityMaxMs?: number;
+  onAttempt?: (e: AttemptEvent) => void;
+  now?: () => number;
+}
+
+export interface ProviderStatus {
+  name: string;
+  tier: 'primary' | 'fallback';
+  available: boolean;
+  parkedForMs?: number;
+  reason?: FailureKind;
+}
+
+export declare class AiRouter {
+  constructor(opts?: RouterOptions);
+  readonly primary: TextProvider[];
+  readonly fallback: TextProvider[];
+  readonly providers: TextProvider[];
+  plan(): { order: TextProvider[]; skipped: { name: string; waitMs: number; reason: string }[] };
+  status(): ProviderStatus[];
+  run<T, P extends { name: string } = TextProvider>(
+    task: (provider: P) => Promise<T>,
+    opts?: { feature?: string; only?: string[] },
+  ): Promise<{ provider: ProviderName; value: T; attempts: Attempt[] }>;
+  generateText(req: TextRequest): Promise<TextResult>;
+  generateObject<T = unknown>(req: ObjectRequest<T>): Promise<ObjectResult<T>>;
+}
+
+export declare function generateObjectOn<T = unknown>(
+  provider: TextProvider,
+  req: ObjectRequest<T>,
+): Promise<{ object: T; text: string; model: string; usage: Usage }>;
+
+export declare class ProviderError extends Error {
+  constructor(provider: string, message: string, opts?: { status?: number; kind?: FailureKind });
+  readonly provider: string;
+  readonly status: number;
+  readonly kind: FailureKind;
+}
+export declare class AllProvidersFailedError extends Error {
+  readonly attempts: Attempt[];
+  readonly skipped: { name: string; waitMs: number; reason: string }[];
+}
+export declare function classify(status: number, message?: string): FailureKind;
+export declare function toProviderError(provider: string, err: unknown): ProviderError;
+
+export interface C0mputeOptions {
+  apiKey?: string;
+  baseUrl?: string;
+  models?: string[];
+  anyModel?: boolean;
+  p2pOnly?: boolean;
+  timeoutMs?: number;
+  concurrency?: number;
+  /** No stream event for this long: try the next model. Default 90000. */
+  stallMs?: number;
+  fetch?: typeof fetch;
+}
+export declare const DEFAULT_C0MPUTE_URL: string;
+export declare const DEFAULT_C0MPUTE_MODELS: string[];
+export declare class C0mputeProvider implements TextProvider {
+  constructor(opts?: C0mputeOptions);
+  readonly name: 'c0mpute';
+  generate(req: TextRequest): Promise<ProviderOutput>;
+}
+
+export interface PaidOptions {
+  apiKey?: string;
+  baseUrl?: string;
+  model?: string;
+  timeoutMs?: number;
+  fetch?: typeof fetch;
+}
+export declare const DEFAULT_OPENAI_MODEL: string;
+export declare const DEFAULT_ANTHROPIC_MODEL: string;
+export declare class OpenAIProvider implements TextProvider {
+  constructor(opts?: PaidOptions);
+  readonly name: 'openai';
+  generate(req: TextRequest): Promise<ProviderOutput>;
+}
+export declare class AnthropicProvider implements TextProvider {
+  constructor(opts?: PaidOptions);
+  readonly name: 'anthropic';
+  generate(req: TextRequest): Promise<ProviderOutput>;
+}
+
+export declare function extractJson(text: string): unknown;
+export declare function validate<T>(schema: SchemaLike<T> | undefined, value: unknown): T;
+export declare function jsonInstructions(name?: string, jsonSchema?: Record<string, unknown>): string;
+
+export interface CreateOptions {
+  env?: Record<string, string | undefined>;
+  c0mpute?: C0mputeOptions;
+  openai?: PaidOptions;
+  anthropic?: PaidOptions;
+  paidFallback?: boolean;
+  router?: Omit<RouterOptions, 'primary' | 'fallback'>;
+}
+export declare function createAiProviders(opts?: CreateOptions): AiRouter;
+export declare function getAi(): AiRouter;
+export declare function generateText(req: TextRequest): Promise<TextResult>;
+export declare function generateObject<T = unknown>(req: ObjectRequest<T>): Promise<ObjectResult<T>>;

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@profullstack/ai-providers",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "One text-model call for every Profullstack app: c0mpute first, OpenAI and Anthropic as alternating fallbacks, dead keys parked. Zero dependencies.",
+  "keywords": [
+    "ai",
+    "llm",
+    "c0mpute",
+    "infernet",
+    "openai",
+    "anthropic",
+    "fallback",
+    "router"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/profullstack/ai-providers.git"
+  },
+  "homepage": "https://github.com/profullstack/ai-providers#readme",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "ai-providers": "./src/cli.js"
+  },
+  "files": [
+    "src",
+    "index.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/c0mpute.js

@@ -0,0 +1,251 @@
+/**
+ * c0mpute: inference on the peer network, through Infernet's chat API.
+ *
+ *   POST /api/chat {messages, maxTokens, temperature, modelName?, p2p_only}
+ *     -> {jobId, source, model}
+ *   GET  /api/chat/stream/<jobId>   server-sent events: meta, token..., done | error
+ *
+ * Without a key the public playground allows 20 requests an hour per IP. A
+ * trusted-client key (`ifc_...`, one per app) has its own budget.
+ *
+ * `p2p_only` (default on) stops Infernet handing the job to its billed hosted
+ * fallback; an answer from anything but a peer node is refused.
+ *
+ * Models are tried in order. A small model on a free node writes junk JSON,
+ * so "any node" is off unless `anyModel` is set.
+ */
+import { ProviderError, toProviderError } from './errors.js';
+
+export const DEFAULT_C0MPUTE_URL = 'https://infernetprotocol.com';
+export const DEFAULT_C0MPUTE_MODELS = [
+  // House models: every Infernet node pulls these (infernetprotocol.com/house-models.json).
+  'huihui_ai/qwen3.5-abliterated:9b',
+  'qwen2.5:7b',
+  'qwen3:4b',
+  'gemma3:4b',
+  'huihui_ai/qwen3.5-abliterated:4b',
+];
+
+export class C0mputeProvider {
+  /**
+   * @param {object} [opts]
+   * @param {string} [opts.apiKey]
+   * @param {string} [opts.baseUrl]
+   * @param {string[]} [opts.models]
+   * @param {boolean} [opts.anyModel]
+   * @param {boolean} [opts.p2pOnly]
+   * @param {number} [opts.timeoutMs]
+   * @param {number} [opts.concurrency]
+   * @param {number} [opts.stallMs]
+   * @param {typeof fetch} [opts.fetch]
+   */
+  constructor(opts = {}) {
+    this.name = 'c0mpute';
+    this.apiKey = opts.apiKey?.trim() || undefined;
+    this.baseUrl = (opts.baseUrl || DEFAULT_C0MPUTE_URL).replace(/\/+$/, '');
+    this.models = opts.models?.length ? [...opts.models] : [...DEFAULT_C0MPUTE_MODELS];
+    this.anyModel = opts.anyModel ?? false;
+    this.p2pOnly = opts.p2pOnly ?? true;
+    this.timeoutMs = opts.timeoutMs ?? 300_000;
+    // A job a node accepted but never answers: give up on that model after
+    // this long with no stream event and try the next one.
+    this.stallMs = opts.stallMs ?? 90_000;
+    this.fetch = opts.fetch ?? globalThis.fetch;
+    this.slots = new Semaphore(opts.concurrency ?? 2);
+  }
+
+  /** @param {import('../index.js').TextRequest} req */
+  async generate(req) {
+    const release = await this.slots.acquire();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), req.timeoutMs ?? this.timeoutMs);
+    const onAbort = () => controller.abort();
+    req.signal?.addEventListener('abort', onAbort, { once: true });
+    try {
+      const messages = toMessages(req);
+      const candidates = [...(req.models?.c0mpute ? [req.models.c0mpute] : []), ...this.models];
+      const order = [...new Set(candidates)];
+      if (this.anyModel) order.push(undefined);
+
+      let last;
+      for (const model of order) {
+        const res = await this.fetch(`${this.baseUrl}/api/chat`, {
+          method: 'POST',
+          headers: {
+            'content-type': 'application/json',
+            accept: 'application/json',
+            ...(this.apiKey ? { authorization: `Bearer ${this.apiKey}` } : {}),
+          },
+          body: JSON.stringify({
+            messages,
+            maxTokens: req.maxTokens ?? 1024,
+            temperature: req.temperature ?? 0.4,
+            ...(this.p2pOnly ? { p2p_only: true } : {}),
+            ...(model ? { modelName: model } : {}),
+          }),
+          signal: controller.signal,
+        });
+        const job = await res.json().catch(() => ({}));
+        if (res.status === 503) {
+          // No live node serves this model right now: next model.
+          last = new ProviderError('c0mpute', `${model ?? 'any'}: ${job.error ?? 'no node'}`, {
+            status: 503,
+            kind: 'capacity',
+          });
+          continue;
+        }
+        if (!res.ok || !job.jobId) {
+          throw new ProviderError('c0mpute', job.error ?? `no job was created (${res.status})`, {
+            status: res.status,
+          });
+        }
+        if (this.p2pOnly && job.source && job.source !== 'p2p') {
+          throw new ProviderError('c0mpute', `no peer node took the job (source ${job.source})`, {
+            status: 503,
+            kind: 'capacity',
+          });
+        }
+        const attempt = new AbortController();
+        const stop = () => attempt.abort();
+        controller.signal.addEventListener('abort', stop, { once: true });
+        let stalled = false;
+        let stall;
+        const arm = () => {
+          clearTimeout(stall);
+          stall = setTimeout(() => {
+            stalled = true;
+            attempt.abort();
+          }, this.stallMs);
+        };
+        let out;
+        try {
+          arm();
+          const stream = await this.fetch(`${this.baseUrl}/api/chat/stream/${job.jobId}`, {
+            headers: {
+              accept: 'text/event-stream',
+              ...(this.apiKey ? { authorization: `Bearer ${this.apiKey}` } : {}),
+            },
+            signal: attempt.signal,
+          });
+          if (!stream.ok || !stream.body) {
+            throw new ProviderError('c0mpute', `could not read the job stream (${stream.status})`, {
+              status: stream.status || 502,
+              kind: 'capacity',
+            });
+          }
+          out = await readStream(stream.body, arm);
+        } catch (err) {
+          if (!stalled) throw err;
+          last = new ProviderError(
+            'c0mpute',
+            `${model ?? 'any'}: no answer for ${Math.round(this.stallMs / 1000)}s (job ${job.jobId})`,
+            { status: 504, kind: 'capacity' },
+          );
+          continue;
+        } finally {
+          clearTimeout(stall);
+          controller.signal.removeEventListener('abort', stop);
+        }
+        const prompt = messages.reduce((n, m) => n + m.content.length, 0);
+        return {
+          text: out.text,
+          model: out.model ?? job.model ?? model ?? 'p2p',
+          usage: {
+            inputTokens: Math.ceil(prompt / 4),
+            outputTokens: Math.ceil(out.text.length / 4),
+            estimated: true,
+          },
+        };
+      }
+      throw last ?? new ProviderError('c0mpute', 'no model configured', { kind: 'invalid' });
+    } catch (err) {
+      throw toProviderError('c0mpute', err);
+    } finally {
+      clearTimeout(timer);
+      req.signal?.removeEventListener('abort', onAbort);
+      release();
+    }
+  }
+}
+
+export function toMessages(req) {
+  if (req.messages?.length) {
+    const sys = req.system ? [{ role: 'system', content: req.system }] : [];
+    return [...sys, ...req.messages];
+  }
+  return [
+    ...(req.system ? [{ role: 'system', content: req.system }] : []),
+    { role: 'user', content: req.user ?? '' },
+  ];
+}
+
+/** Reads `meta`, `token` and `done` events until `done` or `error`. */
+export async function readStream(body, onEvent) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  let text = '';
+  let model;
+  for (;;) {
+    const { value, done } = await reader.read();
+    if (value?.length) onEvent?.();
+    if (value) buffer += decoder.decode(value, { stream: true });
+    buffer = buffer.replace(/\r\n/g, '\n');
+    let cut;
+    while ((cut = buffer.indexOf('\n\n')) >= 0) {
+      const block = buffer.slice(0, cut);
+      buffer = buffer.slice(cut + 2);
+      const event = /^event:\s*(.+)$/m.exec(block)?.[1]?.trim();
+      const raw = block
+        .split('\n')
+        .filter((l) => l.startsWith('data:'))
+        .map((l) => l.slice(5).trimStart())
+        .join('\n');
+      if (!event || !raw) continue;
+      let data;
+      try {
+        data = JSON.parse(raw);
+      } catch {
+        continue;
+      }
+      if (event === 'meta' && typeof data.model === 'string') model = data.model;
+      else if (event === 'token' && typeof data.text === 'string') text += data.text;
+      else if (event === 'done') {
+        await reader.cancel().catch(() => {});
+        return { text: typeof data.text === 'string' && data.text ? data.text : text, model };
+      } else if (event === 'error') {
+        await reader.cancel().catch(() => {});
+        throw new ProviderError('c0mpute', String(data.message ?? data.error ?? 'job failed'), {
+          status: 502,
+          kind: 'capacity',
+        });
+      }
+    }
+    if (done) break;
+  }
+  // No done event: the node or the connection died mid-answer.
+  throw new ProviderError(
+    'c0mpute',
+    text ? 'the stream ended before the answer finished' : 'the stream ended without an answer',
+    { status: 502, kind: 'capacity' },
+  );
+}
+
+class Semaphore {
+  constructor(n) {
+    this.free = Math.max(1, n);
+    this.waiting = [];
+  }
+  acquire() {
+    if (this.free > 0) {
+      this.free--;
+      return Promise.resolve(() => this.#release());
+    }
+    return new Promise((resolve) => this.waiting.push(() => resolve(() => this.#release())));
+  }
+  #release() {
+    const next = this.waiting.shift();
+    if (next) next();
+    else this.free++;
+  }
+}

package/src/cli.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * ai-providers status            which providers are configured, in call order
+ * ai-providers ask "prompt"      one call through the router; prints who answered
+ * ai-providers ask --json "..."  same, asking for a JSON object
+ */
+import { createAiProviders } from './index.js';
+
+const [cmd, ...rest] = process.argv.slice(2);
+const ai = createAiProviders();
+
+if (cmd === 'status' || !cmd) {
+  const { order } = ai.plan();
+  console.log(JSON.stringify({ order: order.map((p) => p.name), providers: ai.status() }, null, 2));
+} else if (cmd === 'ask') {
+  const json = rest[0] === '--json';
+  const prompt = (json ? rest.slice(1) : rest).join(' ');
+  if (!prompt) {
+    console.error('usage: ai-providers ask [--json] "prompt"');
+    process.exit(2);
+  }
+  try {
+    const r = json
+      ? await ai.generateObject({ user: prompt, maxTokens: 800 })
+      : await ai.generateText({ user: prompt, maxTokens: 800 });
+    console.error(`# ${r.provider} ${r.model} in=${r.usage.inputTokens} out=${r.usage.outputTokens}`);
+    for (const a of r.attempts) console.error(`# skipped: ${a.error.message}`);
+    console.log(json ? JSON.stringify(r.object, null, 2) : r.text);
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+} else {
+  console.error('usage: ai-providers status | ask [--json] "prompt"');
+  process.exit(2);
+}

package/src/errors.js

@@ -0,0 +1,51 @@
+/**
+ * One error type for every provider, carrying what the router needs to decide
+ * how long to leave a provider alone.
+ *
+ * kind:
+ *   billing   - out of credits, bad or revoked key. Nothing fixes it but a
+ *               person, so the provider is parked for a long time.
+ *   capacity  - rate limit, no node free, 5xx, timeout. Try again soon.
+ *   invalid   - the request itself was wrong (400). Another provider might
+ *               accept it, but this one should not be parked for it.
+ *   output    - the provider answered but the answer was unusable (empty,
+ *               not JSON, failed the schema).
+ */
+export class ProviderError extends Error {
+  /**
+   * @param {string} provider
+   * @param {string} message
+   * @param {{ status?: number, kind?: 'billing'|'capacity'|'invalid'|'output' }} [opts]
+   */
+  constructor(provider, message, opts = {}) {
+    super(`${provider}: ${message}`);
+    this.name = 'ProviderError';
+    this.provider = provider;
+    this.status = opts.status ?? 0;
+    this.kind = opts.kind ?? classify(this.status, message);
+  }
+}
+
+const BILLING_TEXT =
+  /credit|billing|quota|insufficient|balance|payment|exceeded your current|no credits|plan/i;
+
+/** Maps an HTTP status and message to a failure kind. */
+export function classify(status, message = '') {
+  if (status === 401 || status === 402 || status === 403) return 'billing';
+  if (status === 429) return BILLING_TEXT.test(message) ? 'billing' : 'capacity';
+  if (status === 400 && BILLING_TEXT.test(message) && /credit|balance|billing/i.test(message)) {
+    // Anthropic reports an empty balance as a 400 invalid_request_error.
+    return 'billing';
+  }
+  if (status >= 400 && status < 500) return 'invalid';
+  return 'capacity';
+}
+
+/** Wraps anything thrown by a provider call into a ProviderError. */
+export function toProviderError(provider, err) {
+  if (err instanceof ProviderError) return err;
+  const status = Number(err?.status ?? err?.statusCode ?? 0) || 0;
+  const message = err instanceof Error ? err.message : String(err);
+  const kind = err?.name === 'AbortError' || err?.name === 'TimeoutError' ? 'capacity' : undefined;
+  return new ProviderError(provider, message, { status, ...(kind ? { kind } : {}) });
+}

package/src/index.js

@@ -0,0 +1,100 @@
+/**
+ * @profullstack/ai-providers
+ *
+ * One way for every Profullstack app to call a text model:
+ * c0mpute first, always; OpenAI and Anthropic only as fallbacks, alternating
+ * so neither bill takes all the overflow; dead keys parked instead of retried.
+ */
+import { C0mputeProvider } from './c0mpute.js';
+import { OpenAIProvider, AnthropicProvider } from './paid.js';
+import { AiRouter } from './router.js';
+
+export * from './errors.js';
+export * from './c0mpute.js';
+export * from './paid.js';
+export * from './router.js';
+export * from './json.js';
+
+const OFF = /^(0|off|false|no|none|disabled?)$/i;
+const list = (v) =>
+  String(v ?? '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+const num = (v) => (v == null || v === '' || Number.isNaN(Number(v)) ? undefined : Number(v));
+
+/**
+ * Builds the router from the environment.
+ *
+ *   C0MPUTE_API_KEY      Infernet trusted-client key (ifc_...). Without it the
+ *                        public limit of 20 requests an hour per IP applies.
+ *   C0MPUTE_URL          default https://infernetprotocol.com
+ *   C0MPUTE_MODELS       comma list, tried in order (C0MPUTE_MODEL also read)
+ *   C0MPUTE_ANY_MODEL    1 to let any free node answer as a last resort
+ *   C0MPUTE_CONCURRENCY  jobs in flight per process, default 2
+ *   C0MPUTE_TIMEOUT_MS   whole job, default 300000
+ *   C0MPUTE_STALL_MS     give up on a model whose job streams nothing this long, default 90000
+ *   C0MPUTE_DISABLED     1 to skip c0mpute
+ *   OPENAI_API_KEY, AI_OPENAI_MODEL
+ *   ANTHROPIC_API_KEY, AI_ANTHROPIC_MODEL
+ *   AI_PAID_FALLBACK     0/off to never fall back to a paid provider
+ *
+ * @param {object} [opts]
+ * @param {Record<string, string|undefined>} [opts.env]
+ * @param {object} [opts.c0mpute]   overrides for C0mputeProvider
+ * @param {object} [opts.openai]    overrides for OpenAIProvider
+ * @param {object} [opts.anthropic] overrides for AnthropicProvider
+ * @param {boolean} [opts.paidFallback]
+ * @param {object} [opts.router]    overrides for AiRouter
+ */
+export function createAiProviders(opts = {}) {
+  const env = opts.env ?? (typeof process !== 'undefined' ? process.env : {});
+  const primary = [];
+  const fallback = [];
+
+  if (!/^(1|true|yes|on)$/i.test(env.C0MPUTE_DISABLED ?? '')) {
+    const models = list(env.C0MPUTE_MODELS || env.C0MPUTE_MODEL);
+    primary.push(
+      new C0mputeProvider({
+        apiKey: env.C0MPUTE_API_KEY || env.INFERNET_API_KEY,
+        baseUrl: env.C0MPUTE_URL,
+        ...(models.length ? { models } : {}),
+        anyModel: /^(1|true|yes)$/i.test(env.C0MPUTE_ANY_MODEL ?? ''),
+        concurrency: num(env.C0MPUTE_CONCURRENCY),
+        timeoutMs: num(env.C0MPUTE_TIMEOUT_MS),
+        stallMs: num(env.C0MPUTE_STALL_MS),
+        ...opts.c0mpute,
+      }),
+    );
+  }
+
+  const paid = opts.paidFallback ?? !OFF.test(env.AI_PAID_FALLBACK ?? '');
+  if (paid) {
+    const openaiKey = opts.openai?.apiKey ?? env.OPENAI_API_KEY;
+    if (openaiKey) {
+      fallback.push(
+        new OpenAIProvider({ model: env.AI_OPENAI_MODEL, ...opts.openai, apiKey: openaiKey }),
+      );
+    }
+    const anthropicKey = opts.anthropic?.apiKey ?? env.ANTHROPIC_API_KEY;
+    if (anthropicKey) {
+      fallback.push(
+        new AnthropicProvider({ model: env.AI_ANTHROPIC_MODEL, ...opts.anthropic, apiKey: anthropicKey }),
+      );
+    }
+  }
+
+  return new AiRouter({ ...opts.router, primary, fallback });
+}
+
+let shared;
+/** One router per process, so the breaker and rotation see every call. */
+export function getAi() {
+  shared ??= createAiProviders();
+  return shared;
+}
+
+/** Shorthand for getAi().generateText(req). */
+export const generateText = (req) => getAi().generateText(req);
+/** Shorthand for getAi().generateObject(req). */
+export const generateObject = (req) => getAi().generateObject(req);

package/src/json.js

@@ -0,0 +1,65 @@
+/**
+ * Getting JSON out of a model that was asked for JSON.
+ *
+ * Small open models wrap it in fences, add a sentence before it, or think out
+ * loud in <think> tags first. This takes the first complete top-level JSON
+ * object or array in the text.
+ */
+export function extractJson(text) {
+  if (typeof text !== 'string') throw new Error('no text');
+  let s = text.replace(/<think>[\s\S]*?<\/think>/gi, '').trim();
+  const fence = /```(?:json)?\s*([\s\S]*?)```/i.exec(s);
+  if (fence) s = fence[1].trim();
+  try {
+    return JSON.parse(s);
+  } catch {}
+  const start = s.search(/[[{]/);
+  if (start < 0) throw new Error('no JSON in the answer');
+  const open = s[start];
+  const close = open === '{' ? '}' : ']';
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let i = start; i < s.length; i++) {
+    const c = s[i];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (c === '\\') escaped = true;
+      else if (c === '"') inString = false;
+      continue;
+    }
+    if (c === '"') inString = true;
+    else if (c === open) depth++;
+    else if (c === close && --depth === 0) {
+      return JSON.parse(s.slice(start, i + 1));
+    }
+  }
+  throw new Error('the JSON in the answer is incomplete');
+}
+
+/**
+ * Validates with whatever the caller passed: a zod schema (safeParse/parse),
+ * a plain function that returns the value or throws, or nothing.
+ */
+export function validate(schema, value) {
+  if (!schema) return value;
+  if (typeof schema.safeParse === 'function') {
+    const r = schema.safeParse(value);
+    if (r.success) return r.data;
+    const issues = (r.error?.issues ?? [])
+      .slice(0, 8)
+      .map((i) => `${(i.path ?? []).join('.') || '(root)'}: ${i.message}`)
+      .join('; ');
+    throw new Error(`does not match the schema: ${issues || r.error?.message || 'invalid'}`);
+  }
+  if (typeof schema.parse === 'function') return schema.parse(value);
+  if (typeof schema === 'function') return schema(value);
+  return value;
+}
+
+export function jsonInstructions(name, jsonSchema) {
+  return [
+    `Return only one JSON object${name ? ` (${name})` : ''}. No Markdown, no code fences, no commentary.`,
+    ...(jsonSchema ? ['It must match this JSON schema:', JSON.stringify(jsonSchema)] : []),
+  ].join('\n');
+}

package/src/paid.js

@@ -0,0 +1,133 @@
+/**
+ * The paid fallbacks, over plain fetch so the package has no SDK dependency.
+ *
+ * OpenAI: Chat Completions. Anthropic: Messages. Both return real token counts.
+ */
+import { ProviderError, toProviderError } from './errors.js';
+import { toMessages } from './c0mpute.js';
+
+export const DEFAULT_OPENAI_MODEL = 'gpt-5-mini';
+export const DEFAULT_ANTHROPIC_MODEL = 'claude-haiku-5-5';
+
+async function failure(provider, res) {
+  const body = await res.text().catch(() => '');
+  let message = body.slice(0, 500);
+  try {
+    const j = JSON.parse(body);
+    message = j?.error?.message ?? j?.message ?? message;
+  } catch {}
+  return new ProviderError(provider, `${res.status} ${message}`.trim(), { status: res.status });
+}
+
+function withTimeout(req, ms) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), req.timeoutMs ?? ms);
+  const onAbort = () => controller.abort();
+  req.signal?.addEventListener('abort', onAbort, { once: true });
+  return {
+    signal: controller.signal,
+    done() {
+      clearTimeout(timer);
+      req.signal?.removeEventListener('abort', onAbort);
+    },
+  };
+}
+
+export class OpenAIProvider {
+  constructor(opts = {}) {
+    this.name = 'openai';
+    this.apiKey = opts.apiKey;
+    this.baseUrl = (opts.baseUrl || 'https://api.openai.com/v1').replace(/\/+$/, '');
+    this.model = opts.model || DEFAULT_OPENAI_MODEL;
+    this.timeoutMs = opts.timeoutMs ?? 120_000;
+    this.fetch = opts.fetch ?? globalThis.fetch;
+  }
+
+  async generate(req) {
+    const t = withTimeout(req, this.timeoutMs);
+    try {
+      const model = req.models?.openai || this.model;
+      const res = await this.fetch(`${this.baseUrl}/chat/completions`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', authorization: `Bearer ${this.apiKey}` },
+        body: JSON.stringify({
+          model,
+          messages: toMessages(req),
+          max_completion_tokens: req.maxTokens ?? 1024,
+          ...(req.json ? { response_format: { type: 'json_object' } } : {}),
+        }),
+        signal: t.signal,
+      });
+      if (!res.ok) throw await failure('openai', res);
+      const j = await res.json();
+      return {
+        text: j.choices?.[0]?.message?.content ?? '',
+        model: j.model ?? model,
+        usage: {
+          inputTokens: j.usage?.prompt_tokens ?? 0,
+          outputTokens: j.usage?.completion_tokens ?? 0,
+          estimated: false,
+        },
+      };
+    } catch (err) {
+      throw toProviderError('openai', err);
+    } finally {
+      t.done();
+    }
+  }
+}
+
+export class AnthropicProvider {
+  constructor(opts = {}) {
+    this.name = 'anthropic';
+    this.apiKey = opts.apiKey;
+    this.baseUrl = (opts.baseUrl || 'https://api.anthropic.com/v1').replace(/\/+$/, '');
+    this.model = opts.model || DEFAULT_ANTHROPIC_MODEL;
+    this.timeoutMs = opts.timeoutMs ?? 120_000;
+    this.fetch = opts.fetch ?? globalThis.fetch;
+  }
+
+  async generate(req) {
+    const t = withTimeout(req, this.timeoutMs);
+    try {
+      const model = req.models?.anthropic || this.model;
+      const all = toMessages(req);
+      const system = all.filter((m) => m.role === 'system').map((m) => m.content).join('\n\n');
+      const messages = all.filter((m) => m.role !== 'system');
+      const res = await this.fetch(`${this.baseUrl}/messages`, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          'x-api-key': this.apiKey,
+          'anthropic-version': '2023-06-01',
+        },
+        body: JSON.stringify({
+          model,
+          max_tokens: req.maxTokens ?? 1024,
+          ...(system ? { system } : {}),
+          messages,
+        }),
+        signal: t.signal,
+      });
+      if (!res.ok) throw await failure('anthropic', res);
+      const j = await res.json();
+      const text = (j.content ?? [])
+        .filter((b) => b.type === 'text')
+        .map((b) => b.text)
+        .join('');
+      return {
+        text,
+        model: j.model ?? model,
+        usage: {
+          inputTokens: j.usage?.input_tokens ?? 0,
+          outputTokens: j.usage?.output_tokens ?? 0,
+          estimated: false,
+        },
+      };
+    } catch (err) {
+      throw toProviderError('anthropic', err);
+    } finally {
+      t.done();
+    }
+  }
+}

package/src/router.js

@@ -0,0 +1,196 @@
+/**
+ * The order every call takes:
+ *
+ *   1. primary providers in order (c0mpute)
+ *   2. fallback providers, rotated one step per call so the paid ones share
+ *      the load evenly: call 1 tries openai then anthropic, call 2 tries
+ *      anthropic then openai, and so on
+ *
+ * A provider that fails is parked so the next calls do not pay its latency:
+ *   billing  (no credits, bad key)      parked `billingMs`, default 1 hour
+ *   capacity (429, 5xx, no node, timeout) parked 30 s, doubling to 10 min
+ *   invalid / output                     not parked
+ * A success clears it.
+ */
+import { ProviderError, toProviderError } from './errors.js';
+import { extractJson, validate, jsonInstructions } from './json.js';
+
+export class AllProvidersFailedError extends Error {
+  constructor(attempts, skipped = []) {
+    const parts = attempts.map((a) => a.error.message);
+    for (const s of skipped) parts.push(`${s.name}: parked ${Math.ceil(s.waitMs / 1000)}s after ${s.reason}`);
+    super(`AI generation failed (${parts.join('; ') || 'no provider configured'})`);
+    this.name = 'AllProvidersFailedError';
+    this.attempts = attempts;
+    this.skipped = skipped;
+  }
+}
+
+export class AiRouter {
+  /**
+   * @param {object} opts
+   * @param {Array<{name:string, generate?:Function}>} [opts.primary]
+   * @param {Array<{name:string, generate?:Function}>} [opts.fallback]
+   * @param {boolean} [opts.rotate]
+   * @param {number} [opts.billingMs]
+   * @param {number} [opts.capacityMs]
+   * @param {number} [opts.capacityMaxMs]
+   * @param {(e: object) => void} [opts.onAttempt]
+   * @param {() => number} [opts.now]
+   */
+  constructor(opts = {}) {
+    this.primary = opts.primary ?? [];
+    this.fallback = opts.fallback ?? [];
+    this.rotate = opts.rotate ?? true;
+    this.billingMs = opts.billingMs ?? 60 * 60_000;
+    this.capacityMs = opts.capacityMs ?? 30_000;
+    this.capacityMaxMs = opts.capacityMaxMs ?? 10 * 60_000;
+    this.onAttempt = opts.onAttempt;
+    this.now = opts.now ?? Date.now;
+    this.turn = 0;
+    /** @type {Map<string, {until:number, strikes:number, reason:string}>} */
+    this.parked = new Map();
+  }
+
+  get providers() {
+    return [...this.primary, ...this.fallback];
+  }
+
+  /** The providers the next call would try, in order, and the ones skipped. */
+  plan() {
+    const n = this.fallback.length;
+    const shift = this.rotate && n > 1 ? this.turn % n : 0;
+    const rotated = [...this.fallback.slice(shift), ...this.fallback.slice(0, shift)];
+    const now = this.now();
+    const order = [];
+    const skipped = [];
+    for (const p of [...this.primary, ...rotated]) {
+      const park = this.parked.get(p.name);
+      if (park && park.until > now) skipped.push({ name: p.name, waitMs: park.until - now, reason: park.reason });
+      else order.push(p);
+    }
+    return { order, skipped };
+  }
+
+  status() {
+    const now = this.now();
+    return this.providers.map((p) => {
+      const park = this.parked.get(p.name);
+      const active = park && park.until > now;
+      return {
+        name: p.name,
+        tier: this.primary.includes(p) ? 'primary' : 'fallback',
+        available: !active,
+        ...(active ? { parkedForMs: park.until - now, reason: park.reason } : {}),
+      };
+    });
+  }
+
+  #fail(name, err) {
+    if (err.kind !== 'billing' && err.kind !== 'capacity') return;
+    const prev = this.parked.get(name);
+    const strikes = (prev?.strikes ?? 0) + 1;
+    const ms =
+      err.kind === 'billing'
+        ? this.billingMs
+        : Math.min(this.capacityMaxMs, this.capacityMs * 2 ** (strikes - 1));
+    this.parked.set(name, { until: this.now() + ms, strikes, reason: err.kind });
+  }
+
+  /**
+   * Runs `task(provider)` on each provider in order until one returns.
+   * The building block: generateText/generateObject use it, and an app with
+   * its own provider code (structured outputs, prompt caching) can too.
+   *
+   * @template T
+   * @param {(provider: any) => Promise<T>} task
+   * @param {{ feature?: string, only?: string[] }} [opts]
+   * @returns {Promise<{ provider: string, value: T, attempts: object[] }>}
+   */
+  async run(task, opts = {}) {
+    const { order, skipped } = this.plan();
+    this.turn++;
+    const attempts = [];
+    for (const provider of order) {
+      if (opts.only && !opts.only.includes(provider.name)) continue;
+      const started = this.now();
+      try {
+        const value = await task(provider);
+        this.parked.delete(provider.name);
+        this.onAttempt?.({ provider: provider.name, feature: opts.feature, ok: true, ms: this.now() - started });
+        return { provider: provider.name, value, attempts };
+      } catch (raw) {
+        const error = toProviderError(provider.name, raw);
+        this.#fail(provider.name, error);
+        attempts.push({ provider: provider.name, error });
+        this.onAttempt?.({
+          provider: provider.name,
+          feature: opts.feature,
+          ok: false,
+          ms: this.now() - started,
+          kind: error.kind,
+          error: error.message,
+        });
+      }
+    }
+    throw new AllProvidersFailedError(attempts, skipped);
+  }
+
+  /**
+   * @param {import('../index.js').TextRequest} req
+   */
+  async generateText(req) {
+    const { provider, value, attempts } = await this.run(async (p) => {
+      const out = await p.generate(req);
+      if (!out.text?.trim()) throw new ProviderError(p.name, 'empty answer', { kind: 'output' });
+      return out;
+    }, req);
+    return { ...value, provider, attempts };
+  }
+
+  /**
+   * Asks for JSON, extracts it, validates it against `schema`. An unusable
+   * answer gets one repair attempt on the same provider before moving on.
+   *
+   * @param {import('../index.js').ObjectRequest} req
+   */
+  async generateObject(req) {
+    const { provider, value, attempts } = await this.run((p) => generateObjectOn(p, req), req);
+    return { ...value, provider, attempts };
+  }
+}
+
+export async function generateObjectOn(provider, req) {
+  const system = [req.system, jsonInstructions(req.name, req.jsonSchema)].filter(Boolean).join('\n\n');
+  const base = { ...req, system, json: true };
+  let out = await provider.generate(base);
+  let object;
+  try {
+    object = validate(req.schema, extractJson(out.text));
+  } catch (first) {
+    const repairs = req.repairs ?? 1;
+    if (repairs < 1) throw new ProviderError(provider.name, first.message, { kind: 'output' });
+    const user = req.user ?? req.messages?.at(-1)?.content ?? '';
+    out = await provider.generate({
+      ...base,
+      messages: undefined,
+      user: [
+        user,
+        '',
+        'Your previous answer could not be used:',
+        first.message,
+        '',
+        'Previous answer:',
+        String(out.text).slice(0, 4000),
+        '',
+        'Answer again with only the corrected JSON object.',
+      ].join('\n'),
+    });
+    try {
+      object = validate(req.schema, extractJson(out.text));
+    } catch (second) {
+      throw new ProviderError(provider.name, second.message, { kind: 'output' });
+    }
+  }
+  return { object, text: out.text, model: out.model, usage: out.usage };
+}