@playstack/ai
Tenant-aware keys, preflight, metering, telemetry, and cache context around the Vercel AI SDK.
Reference: @playstack/ai@0.1.0-beta.5 · TypeScript · MIT licence
Free. MIT licensed. Check preview availability before installing. See package access.
@playstack/ai supplies tenant-aware keys, entitlement and rate-limit preflight, idempotent usage metering, safe telemetry, and deterministic cache context around native Vercel AI SDK calls.
Install
After confirming preview access, install the package at your application's shared Playstack version:
npm install --save-exact @playstack/ai@0.1.0-beta.5Check the peer requirements below before choosing a runtime or provider.
Install and compose
import { createAi, type AiTokenUsage } from '@playstack/ai'
import { generateText } from 'ai'
const ai = createAi({
persistence,
events,
connections,
rateLimiter,
entitlements,
connectionScope: 'account',
allowPlatformFallback: false,
providers: [{
id: 'anthropic',
createModel: (modelId, { apiKey }) => anthropic(modelId, { apiKey }),
}],
prices: {
'anthropic:claude-sonnet-4-6': {
inputMicrosPerMillionTokens: configuredInputPrice,
outputMicrosPerMillionTokens: configuredOutputPrice,
currency: 'USD',
},
},
clock,
ids,
})
function usageEvidence(value: { inputTokens?: number; outputTokens?: number; totalTokens?: number }): AiTokenUsage {
const { inputTokens, outputTokens, totalTokens } = value;
const details = totalTokens === undefined ? undefined : { providerReportedTotalTokens: totalTokens };
if (inputTokens !== undefined && outputTokens !== undefined)
return { state: 'known', promptTokens: inputTokens, completionTokens: outputTokens, ...(details ? { details } : {}) };
if (inputTokens !== undefined) return { state: 'partial', promptTokens: inputTokens, ...(details ? { details } : {}) };
if (outputTokens !== undefined) return { state: 'partial', completionTokens: outputTokens, ...(details ? { details } : {}) };
if (details) return { state: 'partial', details };
return { state: 'unknown' };
}
const call = await ai.beginCall('anthropic:claude-sonnet-4-6', { accountId, actor: { type: 'user', id: actorId } })
const result = await generateText({ model: call.model, prompt })
await ai.completeCall(call, {
usage: usageEvidence(result.totalUsage),
})call.model is the provider’s exact model object. Streaming, tools, structured output, and UI hooks remain native SDK APIs.
The model can retain credentials internally: never serialize or log calls/models.
Only validated accounting projections exclude those opaque objects.
Core configuration
AiOptions property | Required | Purpose |
|---|---|---|
persistence | Yes | Transactional idempotent usage records and summaries. |
events | Yes | Emits ai.call.completed or ai.call.failed atomically with accounting; qualify audit consumers for both. |
connections | Yes | Lists scoped BYO connections and decrypts selected access tokens. |
rateLimiter | Yes | Fail-closed ai.generate account/user or ai.generate.system account/custom policy. |
entitlements | Yes | Authorizes provider/model and may supply rate-limit overrides. |
providers | Yes | Provider ID, native model factory, and optional platform key resolver. |
prices | Yes | Model-ref input/output micros per million tokens and currency. |
connectionScope | Yes | user, accountMember, or account. |
allowPlatformFallback | No | Enables platform keys only when a provider supplies one. |
telemetry, errorReporter, scrubber | No | Application-owned operational bridges. |
recordContent | No | Includes scrubbed prompt/completion telemetry; defaults false. |
cache | No | Explicit { enabled, hasher }; disabled when absent. |
clock, ids | Yes | Call timing and identifiers. |
Provider and policy bridges
| Contract | Responsibility |
|---|---|
AiProvider | createModel(modelId, { apiKey }) and optional platformApiKey(). |
AiConnections | Scoped list plus decrypted accessToken(connectionId). |
AiEntitlements | Authorize account/actor/provider/model and return optional bucket overrides. |
AiRateLimiter | Consume the matching user/system named policy with account and user/custom subjects. |
AiUsagePersistence | Transactional record with created/duplicate result and account/time summary. |
AiTelemetry | Isolated started/completed/failed observations. |
AiErrorReporter | Receives scrubbed failure reports. |
AiCacheHasher | SHA-256 digest for normalized deterministic inputs. |
A present but unusable BYO connection never falls back. Platform fallback requires both the global opt-in and a provider resolver. Bypassed/open rate-limit decisions are rejected so inference stays fail-closed.
Metering, telemetry, and caching
Attribution is actor: { type: 'user' | 'system', id }. System actors require
account-scoped keys and cannot supply accountMemberId; they use an independently
configured ai.generate.system policy with tagged custom subject
JSON.stringify(['ai-system', actor.id]). No synthetic user is created. The two
named policies have separate account buckets; shared budgets and actor/account
authorization remain explicit product composition.
completeCall(call, { usage }) records success. failCall(call, cause, { usage }?)
records failure (unknown usage by default) and returns { error, usage } after
commit. Model-construction failures also record failed/unknown receipts. Provider
errors are generic/nonretryable; no raw diagnostic code/message/stack is retained.
Observers run only after the first commit. Reporting failure must not be caught
as provider failure or used to rerun inference.
Usage is known with both base counts, partial with one base count or only
numeric details, or unknown with none. Details preserve cached/cache-write prompt,
reasoning and independent provider-reported total tokens. Subcategories are not
charged again. The receipt total is normalized prompt-plus-completion; preserve a
different provider total explicitly. Known usage uses the call's captured flat
price; incomplete total/cost remains null. This configured estimate is not a
provider invoice or a product billing decision.
Exact replay preserves the first receipt/timing and emits once. Changed attribution,
outcome, measurements, details or price under the same call ID refuses. Summaries
return outcome/coverage counts and per-metric
{ observedTotal, reportedCalls, missingCalls, total }; total is null when any
measurement is missing. Observed subtotals are not complete bills. Empty histories
are zero. There is no durable in-flight admission or automatic crash recovery;
unreported calls remain host reconciliation work.
Prompt/completion recording is off by default. When enabled, content is scrubbed before telemetry and credentials never enter receipts, errors, events, or traces. cacheKey() returns a key only when caching is enabled and temperature is zero; storage remains an application-selected concern.
Persistence and boundary
@playstack/ai/prisma supplies structural PostgreSQL persistence and a managed, non-ejectable schema fragment. Applications own clients and migrations. The package does not wrap the AI SDK, store cache results, load keys, define subscription plans, or hide provider-native behavior.
API entry points and requirements
Reference snapshot: @playstack/ai@0.1.0-beta.5. Import only the entry point your runtime needs. Paths below are relative to the installed package; use Go to Definition in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.
| Public entry point | Declaration file |
|---|---|
@playstack/ai | ./dist/index.d.ts |
@playstack/ai/errors | ./dist/errors.d.ts |
@playstack/ai/prisma | ./dist/prisma.d.ts |
@playstack/ai/testing | ./dist/testing.d.ts |
@playstack/ai/playstack.artifacts.json | No TypeScript declaration (asset or metadata export). |
@playstack/ai/package.json | No TypeScript declaration (asset or metadata export). |
Node.js engine requirement: >=20. This is not a claim that every entry point works in browsers or Workers.
Peer dependencies
Keep existing framework versions that satisfy these ranges. Install optional peers only when using the corresponding adapter. The package manager resolves ordinary dependencies separately.
| Peer | Compatible range | When needed |
|---|---|---|
@playstack/connections | 0.1.0-beta.5 | Required by the package. |
@playstack/rate-limit | 0.1.0-beta.5 | Required by the package. |
For a complete first program, start with Getting started. For API lookup and partial-example conventions, see Reading the reference. Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.