@playstack/ai

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

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

Install and compose

import { createAi } from '@playstack/ai'
import { streamText } 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,
})

const call = await ai.beginCall('anthropic:claude-sonnet-4-6', { accountId, actorId })
const result = await streamText({ model: call.model, prompt })
await ai.completeCall(call, {
  promptTokens: result.usage.inputTokens,
  completionTokens: result.usage.outputTokens,
})

call.model is the provider’s exact model object. Streaming, tools, structured output, and UI hooks remain native SDK APIs.

Core configuration

Provider and policy bridges

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

completeCall records by callId; a duplicate with identical usage is safe, while conflicting billable usage fails. Provider prices are captured into the receipt and event so billing consumers do not own the price table.

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

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.

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.