On this page
  1. Install
  2. Install and compose
  3. Core configuration
  4. Provider and policy bridges
  5. Metering, telemetry, and caching
  6. Persistence and boundary
  7. API entry points and requirements
  8. Peer dependencies

This guide describes upcoming source contracts, not a publication receipt. Check release availability and keep your complete Playstack graph on one verified version.

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

sh
npm install --save-exact @playstack/ai@0.1.0-beta.5

Check the peer requirements below before choosing a runtime or provider.

Install and compose

ts
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 propertyRequiredPurpose
persistenceYesTransactional idempotent usage records and summaries.
eventsYesEmits ai.call.completed or ai.call.failed atomically with accounting; qualify audit consumers for both.
connectionsYesLists scoped BYO connections and decrypts selected access tokens.
rateLimiterYesFail-closed ai.generate account/user or ai.generate.system account/custom policy.
entitlementsYesAuthorizes provider/model and may supply rate-limit overrides.
providersYesProvider ID, native model factory, and optional platform key resolver.
pricesYesModel-ref input/output micros per million tokens and currency.
connectionScopeYesuser, accountMember, or account.
allowPlatformFallbackNoEnables platform keys only when a provider supplies one.
telemetry, errorReporter, scrubberNoApplication-owned operational bridges.
recordContentNoIncludes scrubbed prompt/completion telemetry; defaults false.
cacheNoExplicit { enabled, hasher }; disabled when absent.
clock, idsYesCall timing and identifiers.

Provider and policy bridges

ContractResponsibility
AiProvidercreateModel(modelId, { apiKey }) and optional platformApiKey().
AiConnectionsScoped list plus decrypted accessToken(connectionId).
AiEntitlementsAuthorize account/actor/provider/model and return optional bucket overrides.
AiRateLimiterConsume the matching user/system named policy with account and user/custom subjects.
AiUsagePersistenceTransactional record with created/duplicate result and account/time summary.
AiTelemetryIsolated started/completed/failed observations.
AiErrorReporterReceives scrubbed failure reports.
AiCacheHasherSHA-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 pointDeclaration 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.jsonNo TypeScript declaration (asset or metadata export).
@playstack/ai/package.jsonNo 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.

PeerCompatible rangeWhen needed
@playstack/connections0.1.0-beta.5Required by the package.
@playstack/rate-limit0.1.0-beta.5Required 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.

Go

Playstack Pro tag
OriginsPricingBlogChangelogStatus

© 2026 Playstack. All rights reserved.

With OSS

By

Commune Software