@builddai/ai-kit weekly downloads statistics

@builddai/ai-kit

Shared chat contract, tool permissions, model plans and Jev decisions for apps that use buildd's model economy.

buildd decides which model a call uses and whether it may spend. Your app makes the call with its own provider key and reports a content-free usage record. buildd never sees prompts, tool results or replies.

npm i -E @builddai/ai-kit@0.16.0

Pin exact versions: a Jev model bump or a contract change is a new kit release, and you should re-run your evals before taking it. Releases publish on merge: a version bump landing on buildd's dev branch goes to npm with provenance and is tagged ai-kit-v<version>. See CHANGELOG.md.

Entry points

Import	What	Status
@builddai/ai-kit/chat/contract	Wire types: parts, object refs, data parts, approval previews, tool-permission rows. No deps, isomorphic	Ready
@builddai/ai-kit/chat/server	createChatTurn (the turn runner), defineToolGroups + server-side Allow enforcement, the ChatStore persistence adapter. Peer ai@^7, loaded lazily on the first turn	Ready
@builddai/ai-kit/chat/react	Thread, composer, tools / scope / tier pickers, thinking panel, approval / hand-off / setup cards, empty state, useKitChat. Peers react@^19, @ai-sdk/react@^4, ai@^7 (all required by this entry)	Ready
@builddai/ai-kit/chat/theme.css	--kit-* CSS custom properties. No Tailwind	Ready
@builddai/ai-kit/chat/styles.css	The components' layout, reading only --kit-*. No Tailwind	Ready
@builddai/ai-kit/chat/schema.sql	Reference Postgres tables for a ChatStore (never run by the kit)	Reference
@builddai/ai-kit/models	Model-plan client + usage sink. No deps; Node, Bun, edge	Ready
@builddai/ai-kit/policy	Standalone model policy: surface + tier → provider, model, effort. Local-first, optional remote service with fallback. No deps; Node, Bun, edge	Ready
@builddai/ai-kit/decide	Jev decisions: typed questions, gating, versioning, eval. Optional peer @typesafe-ai/sdk@0.6.0: install it to call decide; without it the module still loads and decide returns sdk_missing	Ready
@builddai/ai-kit/surfaces	Jev picks the app's own chips and card: defineSurface (rank and choice slots in one call, shadow first, a slot gated only after an eval of at least 700 held-out rows) and the single-slot defineRankSurface	Ready (shadow)

Model plans

Ask buildd which model to call and whether it may spend; make the call with your own key; record a content-free receipt.

import { createModelsClient, toCallConfig, isPlanDeniedError } from '@builddai/ai-kit/models';

const models = createModelsClient({
  apiKey: env.BUILDD_AI_KEY,                // a bld_ key for the app's service account
  providers: ['openrouter'],                // provider keys the app holds
  defaults: {                               // used only when buildd is unreachable; every tier
    'premium-plus': { provider: 'openrouter', model: '<pinned id>' },
    premium:        { provider: 'openrouter', model: '<pinned id>' },
    standard:       { provider: 'openrouter', model: '<pinned id>' },
    budget:         { provider: 'openrouter', model: '<pinned id>' },
  },
  // storage: kvPlanStore,                  // optional: survive cold starts (get/set of JSON)
});

try {
  const plan = await models.plan({ tier: 'standard', kind: 'chat_turn', budget: { maxUsdPerCall: 0.02 } });
  const cfg = toCallConfig(plan, { apiKeys: { openrouter: env.OPENROUTER_API_KEY }, appName: 'cue' });
  // ... call cfg.model at cfg.baseURL ...
  models.recordUsage({ plan, tokens: { input, output }, costUsd, latencyMs, outcome: 'ok' });
} catch (e) {
  if (isPlanDeniedError(e)) { /* show e.reason: daily_cap_reached, per_call_limit, ... */ }
}
await models.flush(); // before a serverless function returns (e.g. in waitUntil / after)

• Caching. Plans are cached per (tier, surface, workspace, budget) until buildd's expiresAt (60s). Concurrent callers share one request.
• Bounded fallback. buildd slower than 800ms, a 5xx, a network error or an unusable answer: the last good plan is served for up to maxStaleSeconds (24h) past expiry with planSource: 'cached', then your defaults with planSource: 'fallback' and planId: null. plan() never blocks longer than the deadline and throws only PlanDeniedError.
• Budget. deny throws PlanDeniedError; downgrade returns the cheaper model as buildd sent it (plan.tier ≠ plan.requestedTier).
• Receipts. recordUsage never throws. It rebuilds each record from the server's allowlist (plan id, model, provider, tier, kind, planSource, tokens, cost, latency, outcome, feedback), so nothing else you pass can reach buildd, and refuses locally what buildd would reject. Batches of ≤100, one retry on a network error / timeout / 5xx / 429, then dropped and counted in stats(). Optional kind (chat | inference | decision) lets buildd report spend by kind; a decision receipt needs no tier.
• Storage. PlanStore is { get(key), set(key, value) }, sync or async. A failing store is treated as a miss. Default: in memory.
• onError receives every absorbed failure, for logs.

Through a LiteLLM gateway (0.7.0). buildd's plan still names the real provider and model; pass gateway and the call goes to your proxy instead, on its OpenAI-compatible API. cfg.via is litellm, so build an OpenAI-compatible client whatever cfg.provider says:

const cfg = toCallConfig(plan, { gateway: { kind: 'litellm', baseURL: env.LITELLM_URL, apiKey: env.LITELLM_KEY } });
const litellm = createOpenAICompatible({ name: 'litellm', apiKey: cfg.apiKey, baseURL: cfg.baseURL });
streamText({ model: litellm(cfg.model), ... }); // cfg.model === 'anthropic/claude-…'
```…