@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.

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. 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.

• 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:

• The model is sent as provider/model (LiteLLM's convention). models maps a provider/model or bare model to your proxy's alias; prefix: false sends the bare id. • Receipts keep plan.provider and plan.model, so buildd prices the call as the model it is. List in providers what the gateway can reach. • Chat: modelFromPlan({ models, gateway, create }). The gateway's apiKey pays for the turn (none ⇒ 409 no_key); a gateway function returning null takes the direct key path, so one app can serve both.

Model policy (standalone)

/policy answers "which model?" from two things the app knows structurally: its surface (chat | coding) and the tier it wants. It works with no service and no buildd account; a policy service is optional.

• No intent field. What kind of request it is gets inferred behind the policy, later, when useful; a request carrying intent is refused. • Precedence: app/workspace (+ surface) override → surfaces[surface][tier] → tiers[tier] → fallback. source on the decision says which answered; cached / fallback mean the service did not. • Credentials are separate. The policy token authorises policy calls only; it is never a provider key (one is refused) and the service never returns one (an answer carrying anything credential-shaped is refused). • Experiments: pinned, split (sticky per workspace/app), shadow (the route never changes; experiment.shadow names the challenger for an out-of-band run), adaptive only with a trustworthy signal for its surface (coding: tests, goal criteria, review, merge, rework; chat: none yet). • Outcomes are typed observations keyed by planId, never one score.

The service is apps/model-policy in the buildd repo (a Cloudflare Worker).

Chat

A streamed chat turn on AI SDK v7, with the writes it proposes gated on the server, and the React components that render it. The kit owns the turn and the permission rules; your app owns the tools, the model key, the storage and the look.

Peers

| Entry | Needs |…

Description from the npm listing.