@zerotal/ai 1.6.2 → 1.7.0

package/api-surface.md

@@ -0,0 +1,620 @@
+# @zerotal/ai — public API surface
+
+<!-- AUTO-GENERATED by scripts/api-surface.ts. Do not edit by hand.
+     Run `bun run api:surface` to regenerate after an intentional API change. -->
+
+## .  `(./src/index.ts)`
+
+class AiAgentLimitError = {
+  new (message: string, context?: Record<string, unknown>): AiAgentLimitError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class AiCancelledError = {
+  new (message?: string): AiCancelledError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class AiConfigError = {
+  new (message: string, context?: Record<string, unknown>): AiConfigError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class AiDriverUnavailableError = {
+  new (driver: string, packageName: string): AiDriverUnavailableError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class AiError = {
+  new (message: string, code?: string, status?: number, context?: Record<string, unknown>): AiError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class AiFake = {
+  new (_app: Application, _original: Binding): AiFake
+  static install: () => AiFake
+  agent: (request: AiAgentRequest) => Promise<AiAgentResult>
+  assertNotPrompted: (expected: string | RegExp | ((prompt: string) => boolean)) => void
+  assertNothingPrompted: () => void
+  assertPromptCount: (count: number) => void
+  assertPrompted: (expected: string | RegExp | ((prompt: string) => boolean)) => void
+  assertSystemPrompted: (expected: string | RegExp | ((prompt: string) => boolean)) => void
+  calls: CapturedGeneration[]
+  countTokens: (request: AiRequest | string) => Promise<number>
+  drivers: () => string[]
+  embed: (input: string | string[], _options?: Omit<AiEmbedRequest, 'input'>) => Promise<AiEmbedResponse>
+  generate: (request: AiRequest | string) => Promise<AiResponse>
+  handlerFor: (name: string) => AiQueueHandler | undefined
+  object: <T = Record<string, unknown>>(request: AiRequest | string) => Promise<T>
+  onGenerated: (name: string, handler: AiQueueHandler) => AiFake
+  prompts: string[]
+  queue: (request: AiRequest, options: AiQueueOptions) => Promise<void>
+  refuse: (category?: string | null, explanation?: string | null) => AiFake
+  respondWith: (...texts: string[]) => AiFake
+  respondWithObject: (...objects: unknown[]) => AiFake
+  restore: () => void
+  stream: (request: AiRequest | string) => AsyncIterable<AiStreamChunk>
+  text: (request: AiRequest | string) => Promise<string>
+  verify: () => Promise<DriverStatus>
+}
+
+class AiGenerated = {
+  new (driver: string, model: string, operation: string, inputTokens: number, outputTokens: number, cacheReadTokens: number, durationMs: number, costUsd: number, ok: boolean, preview: string, error?: string | undefined): AiGenerated
+  readonly cacheReadTokens: number
+  readonly costUsd: number
+  readonly driver: string
+  readonly durationMs: number
+  readonly error?: string | undefined
+  readonly inputTokens: number
+  readonly model: string
+  readonly ok: boolean
+  readonly operation: string
+  readonly outputTokens: number
+  readonly preview: string
+}
+
+class AiGenerationJob = {
+  new (request: AiRequest, options: AiQueueOptions): AiGenerationJob
+  static fromPayload: (data: Record<string, unknown>) => AiGenerationJob
+  _chain: SerializedJob[] | undefined
+  batchId: string | undefined
+  className: string
+  debounceKey: () => string
+  handle: () => Promise<void>
+  payload: () => Record<string, unknown>
+  readonly debounce?: number
+  readonly maxAttempts: number
+  readonly queue: string
+  readonly retryDelay: number
+}
+
+class AiManager = {
+  new (config: AiConfigShape): AiManager
+  agent: (request: AiAgentRequest) => Promise<AiAgentResult>
+  countTokens: (request: AiRequest | string) => Promise<number>
+  driver: (name?: string) => AiDriver
+  drivers: () => string[]
+  embed: (input: string | string[], options?: Omit<AiEmbedRequest, 'input'>) => Promise<AiEmbedResponse>
+  embeddingsDriver: (name?: string) => EmbeddingsDriver
+  extend: (name: string, factory: DriverResolver) => AiManager
+  extendEmbeddings: (name: string, factory: EmbeddingsResolver) => AiManager
+  generate: (request: AiRequest | string) => Promise<AiResponse>
+  handlerFor: (name: string) => AiQueueHandler | undefined
+  object: <T = Record<string, unknown>>(request: AiRequest | string, schema: SchemaInput | ((rule: RuleBuilder) => SchemaInput)) => Promise<T>
+  onGenerated: (name: string, handler: AiQueueHandler) => AiManager
+  queue: (request: AiRequest, options: AiQueueOptions) => Promise<void>
+  readonly config: AiConfigShape
+  stream: (request: AiRequest | string) => AsyncIterable<AiStreamChunk>
+  text: (request: AiRequest | string) => Promise<string>
+  verify: (name?: string) => Promise<DriverStatus>
+}
+
+class AiProvider = {
+  new (app: Application): AiProvider
+  static dependsOn?: (new (app: Application) => ServiceProvider)[]
+  static environments: AppEnvironment[]
+  static priority?: number
+  static provides: readonly ['ai']
+  devProcesses: () => DevProcessDefinition[]
+  doctorChecks: () => DoctorCheck[]
+  onBooted: () => Promise<void>
+  onBooting: () => Promise<void>
+  onRegister: () => void
+  onRequestProcessed: (_ctx: HttpContext) => Promise<void>
+  onRequestReceived: (_ctx: HttpContext) => Promise<void>
+  onResponseSent: (_ctx: HttpContext) => Promise<void>
+  onStarted: () => Promise<void>
+  onStarting: () => Promise<void>
+  onStopped: () => Promise<void>
+  onStopping: () => Promise<void>
+  replContext: () => Record<string, unknown>
+}
+
+class AiRateLimitError = {
+  new (message: string, retryAfterSeconds?: number | undefined): AiRateLimitError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly retryAfterSeconds?: number | undefined
+  readonly status: number
+}
+
+class AiRefused = {
+  new (driver: string, model: string, category: string | null, preview: string): AiRefused
+  readonly category: string | null
+  readonly driver: string
+  readonly model: string
+  readonly preview: string
+}
+
+class AiRefusedError = {
+  new (category: string | null, explanation: string | null, partialText?: string): AiRefusedError
+  readonly category: string | null
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly explanation: string | null
+  readonly partialText: string
+  readonly status: number
+}
+
+class AiRequestError = {
+  new (message: string, providerStatus: number, context?: Record<string, unknown>): AiRequestError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly providerStatus: number
+  readonly status: number
+}
+
+class AiSchemaError = {
+  new (message: string, context?: Record<string, unknown>): AiSchemaError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class AiSpendCommand = {
+  new (): AiSpendCommand
+  static args: ArgDef[]
+  static commandName: string
+  static description: string
+  static flags: FlagDef[]
+  static needsApp: boolean
+  _readLine: () => Promise<string>
+  _writer: OutputWriter
+  app: unknown
+  args: Record<string, string>
+  ask: (question: string, defaultValue?: string) => Promise<string>
+  choice: (question: string, options: string[]) => Promise<string>
+  confirm: (question: string, defaultValue?: boolean) => Promise<boolean>
+  dim: (msg: string) => void
+  error: (msg: string) => void
+  flags: Record<string, string | number | boolean>
+  info: (msg: string) => void
+  line: (msg: string) => void
+  newLine: () => void
+  run: () => Promise<void>
+  secret: (question: string) => Promise<string>
+  section: (title: string) => void
+  table: (rows: [string, string][], indent?: number) => void
+  warn: (msg: string) => void
+  write: (msg: string) => void
+}
+
+class AiSpendLimitError = {
+  new (message: string, context?: Record<string, unknown>): AiSpendLimitError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class AiTestCommand = {
+  new (): AiTestCommand
+  static args: ArgDef[]
+  static commandName: string
+  static description: string
+  static flags: FlagDef[]
+  static needsApp: boolean
+  _readLine: () => Promise<string>
+  _writer: OutputWriter
+  app: unknown
+  args: Record<string, string>
+  ask: (question: string, defaultValue?: string) => Promise<string>
+  choice: (question: string, options: string[]) => Promise<string>
+  confirm: (question: string, defaultValue?: boolean) => Promise<boolean>
+  dim: (msg: string) => void
+  error: (msg: string) => void
+  flags: Record<string, string | number | boolean>
+  info: (msg: string) => void
+  line: (msg: string) => void
+  newLine: () => void
+  run: () => Promise<void>
+  secret: (question: string) => Promise<string>
+  section: (title: string) => void
+  table: (rows: [string, string][], indent?: number) => void
+  warn: (msg: string) => void
+  write: (msg: string) => void
+}
+
+class AiToolCalled = {
+  new (driver: string, tool: string, step: number, durationMs: number, ok: boolean, error?: string | undefined): AiToolCalled
+  readonly driver: string
+  readonly durationMs: number
+  readonly error?: string | undefined
+  readonly ok: boolean
+  readonly step: number
+  readonly tool: string
+}
+
+class AnthropicDriver = {
+  new (config: AnthropicConfigShape, inject?: LoadedAnthropic): AnthropicDriver
+  countTokens: (request: AiRequest) => Promise<number>
+  model: string
+  object: <T>(request: AiRequest, schema: SchemaInput) => Promise<AiObjectResponse<T>>
+  readonly name: 'anthropic'
+  stream: (request: AiRequest) => AsyncIterable<AiStreamChunk>
+  text: (request: AiRequest) => Promise<AiResponse>
+  verify: () => Promise<DriverStatus>
+}
+
+class OllamaDriver = {
+  new (config: OllamaConfigShape, fetchImpl?: typeof fetch): OllamaDriver
+  countTokens: (_request: AiRequest) => Promise<number>
+  model: string
+  object: <T>(request: AiRequest, schema: SchemaInput) => Promise<AiObjectResponse<T>>
+  readonly name: 'ollama'
+  stream: (request: AiRequest) => AsyncIterable<AiStreamChunk>
+  text: (request: AiRequest) => Promise<AiResponse>
+  verify: () => Promise<DriverStatus>
+}
+
+class OllamaEmbeddingsDriver = {
+  new (config: { model: string; baseUrl: string; timeout: number; }, fetchImpl?: typeof fetch): OllamaEmbeddingsDriver
+  embed: (request: AiEmbedRequest) => Promise<AiEmbedResponse>
+  model: string
+  readonly name: 'ollama'
+}
+
+class OpenAiDriver = {
+  new (config: OpenAiConfigShape, fetchImpl?: typeof fetch): OpenAiDriver
+  countTokens: (_request: AiRequest) => Promise<number>
+  model: string
+  object: <T>(request: AiRequest, schema: SchemaInput) => Promise<AiObjectResponse<T>>
+  readonly name: 'openai'
+  stream: (request: AiRequest) => AsyncIterable<AiStreamChunk>
+  text: (request: AiRequest) => Promise<AiResponse>
+  verify: () => Promise<DriverStatus>
+}
+
+class OpenAiEmbeddingsDriver = {
+  new (config: { apiKey: string; model: string; baseUrl: string; timeout: number; }, fetchImpl?: typeof fetch): OpenAiEmbeddingsDriver
+  embed: (request: AiEmbedRequest) => Promise<AiEmbedResponse>
+  model: string
+  readonly name: 'openai'
+}
+
+class UnknownAiDriverError = {
+  new (driver: string, known?: string[]): UnknownAiDriverError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+const Ai = AiManager
+
+function AiConfig = (options?: DeepPartial<AiConfigShape>) => AiConfigShape
+
+function AiConfigFromEnv = () => AiConfigShape
+
+function estimateCost = (model: string, usage: AiUsage) => number
+
+function modelPrice = (model: string) => ModelPrice | undefined
+
+function modelRejectsSampling = (model: string) => boolean
+
+function modelStats = () => ModelStat[]
+
+function recentGenerations = (limit?: number) => AiDelivery[]
+
+function refusalRate = () => number
+
+function registerModelPrice = (model: string, price: ModelPrice) => void
+
+function resetSpend = () => void
+
+function resetStats = () => void
+
+function spentToday = () => number
+
+function strippedConstraints = (input: SchemaInput) => string[]
+
+function tool = <I extends Record<string, unknown> = Record<string, unknown>>(options: {    name: string;    description: string;    input: ((rule: RuleBuilder) => Record<string, FieldRule>) | SchemaInput;    handle: (input: I, ctx: AiToolContext) => Promise<unknown> | unknown;}) => AiTool
+
+function toSchema = (input: SchemaInput) => Schema
+
+function translateSchema = (input: SchemaInput) => JsonSchema
+
+function validateAiConfig = (config: AiConfigShape) => void
+
+interface AgentOptions = {
+  maxResumes: number
+  maxSteps: number
+  signal: AbortSignal
+}
+
+interface AiAgentConfigShape = {
+  lock: boolean
+  lockTtl: number
+  maxResumes: number
+  maxSteps: number
+}
+
+interface AiAgentRequest = {
+  cache?: boolean
+  driver?: string
+  effort?: AiEffort
+  lock?: string
+  maxResumes?: number
+  maxSteps?: number
+  maxTokens?: number
+  messages?: AiMessage[]
+  model?: string
+  prompt?: string
+  providerOptions?: AiProviderOptions
+  signal?: AbortSignal
+  system?: string
+  temperature?: number
+  tools?: AiTool<Record<string, unknown>>[]
+}
+
+interface AiAgentResult = {
+  model: string
+  steps: AiAgentStep[]
+  stopReason: AiStopReason
+  text: string
+  usage: AiUsage
+}
+
+interface AiAgentStep = {
+  call: AiToolCall
+  durationMs: number
+  isError: boolean
+  result: string
+  step: number
+}
+
+interface AiConfigShape = {
+  agent: AiAgentConfigShape
+  default: string
+  drivers: {    anthropic?: AnthropicConfigShape;    openai?: OpenAiConfigShape;    ollama?: OllamaConfigShape;}
+  embeddings: EmbeddingsConfigShape
+  limits: AiLimitsConfigShape
+  redact: boolean
+}
+
+interface AiDelivery = {
+  at: number
+  cacheReadTokens: number
+  costUsd: number
+  driver: string
+  durationMs: number
+  error?: string
+  inputTokens: number
+  model: string
+  ok: boolean
+  operation: string
+  outputTokens: number
+  preview: string
+  refused: boolean
+}
+
+interface AiDriver = {
+  agent?: (request: AiRequest, options: AgentOptions) => Promise<AiAgentResult>
+  countTokens: (request: AiRequest) => Promise<number>
+  object: <T>(request: AiRequest, schema: SchemaInput) => Promise<AiObjectResponse<T>>
+  readonly model: string
+  readonly name: string
+  stream: (request: AiRequest) => AsyncIterable<AiStreamChunk>
+  text: (request: AiRequest) => Promise<AiResponse>
+  verify: () => Promise<DriverStatus>
+}
+
+interface AiEmbedRequest = {
+  driver?: string
+  input: string | string[]
+  model?: string
+  signal?: AbortSignal
+}
+
+interface AiEmbedResponse = {
+  embeddings: number[][]
+  model: string
+  usage: Pick<AiUsage, 'inputTokens'>
+}
+
+interface AiLimitsConfigShape = {
+  perDayUsd: number
+  perRequestUsd: number
+}
+
+interface AiMessage = {
+  content: string
+  raw?: unknown
+  role: AiRole
+  toolCalls?: AiToolCall[]
+  toolResults?: AiToolResult[]
+}
+
+interface AiObjectResponse = {
+  model: string
+  object: T
+  raw?: unknown
+  usage: AiUsage
+}
+
+interface AiQueueOptions = {
+  handler: string
+  meta?: Record<string, unknown>
+  queue?: string
+}
+
+interface AiRequest = {
+  cache?: boolean
+  driver?: string
+  effort?: AiEffort
+  maxTokens?: number
+  messages?: AiMessage[]
+  model?: string
+  prompt?: string
+  providerOptions?: AiProviderOptions
+  signal?: AbortSignal
+  system?: string
+  temperature?: number
+  tools?: AiTool<Record<string, unknown>>[]
+}
+
+interface AiResponse = {
+  assistantTurn: AiMessage
+  model: string
+  raw?: unknown
+  stopReason: AiStopReason
+  text: string
+  toolCalls: AiToolCall[]
+  usage: AiUsage
+}
+
+interface AiTool = {
+  description: string
+  handler: (input: I, ctx: AiToolContext) => Promise<unknown> | unknown
+  inputSchema: JsonSchema
+  name: string
+}
+
+interface AiToolCall = {
+  id: string
+  input: Record<string, unknown>
+  name: string
+}
+
+interface AiToolContext = {
+  signal: AbortSignal
+  step: number
+}
+
+interface AiToolResult = {
+  content: string
+  id: string
+  isError?: boolean
+}
+
+interface AiUsage = {
+  cacheReadTokens: number
+  cacheWriteTokens: number
+  inputTokens: number
+  outputTokens: number
+}
+
+interface AnthropicConfigShape = {
+  apiKey: string
+  baseUrl?: string
+  cacheSystem: boolean
+  effort: AiEffort
+  fallbacks: boolean
+  maxTokens: number
+  model: string
+  streamMaxTokens: number
+  temperature?: number
+  timeout: number
+}
+
+interface CapturedGeneration = {
+  operation: string
+  prompt: string
+  request: AiRequest
+  system: string | undefined
+}
+
+interface DriverStatus = {
+  detail: string
+  model: string
+  ok: boolean
+}
+
+interface EmbeddingsConfigShape = {
+  default: string
+  drivers: {    openai?: {        apiKey: string;        model: string;        baseUrl: string;        timeout: number;    };    ollama?: {        model: string;        baseUrl: string;        timeout: number;    };}
+}
+
+interface EmbeddingsDriver = {
+  embed: (request: AiEmbedRequest) => Promise<AiEmbedResponse>
+  readonly model: string
+  readonly name: string
+}
+
+interface JsonSchema = {
+  additionalProperties?: false
+  anyOf?: JsonSchema[]
+  description?: string
+  enum?: (string | number)[]
+  format?: string
+  items?: JsonSchema
+  properties?: Record<string, JsonSchema>
+  required?: string[]
+  type?: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'integer' | 'null'
+}
+
+interface ModelPrice = {
+  input: number
+  output: number
+}
+
+interface ModelStat = {
+  cacheReadTokens: number
+  calls: number
+  costUsd: number
+  failures: number
+  inputTokens: number
+  model: string
+  outputTokens: number
+  p50: number
+  p95: number
+  refusals: number
+}
+
+interface OllamaConfigShape = {
+  baseUrl: string
+  model: string
+  timeout: number
+}
+
+interface OpenAiConfigShape = {
+  apiKey: string
+  baseUrl: string
+  maxTokens: number
+  model: string
+  timeout: number
+}
+
+type AiConfigInput = {    default?: string | undefined;    drivers?: DeepPartial<{        anthropic?: AnthropicConfigShape;        openai?: OpenAiConfigShape;        ollama?: OllamaConfigShape;    }> | undefined;    embeddings?: DeepPartial<EmbeddingsConfigShape> | undefined;    limits?: DeepPartial<AiLimitsConfigShape> | undefined;    redact?: boolean | undefined;    agent?: DeepPartial<AiAgentConfigShape> | undefined;}
+
+type AiEffort = 'max' | 'medium' | 'low' | 'high' | 'xhigh'
+
+type AiProviderOptions = {    [x: string]: Record<string, unknown>;}
+
+type AiQueueHandler = (response: AiResponse, meta: Record<string, unknown>) => Promise<void> | void
+
+type AiRole = 'user' | 'assistant'
+
+type AiStopReason = 'end_turn' | 'max_tokens' | 'tool_use' | 'pause_turn' | 'refusal' | 'stop_sequence' | 'unknown'
+
+type AiStreamChunk = {    type: 'text';    text: string;} | {    type: 'thinking';    text: string;} | {    type: 'tool_call';    call: AiToolCall;} | {    type: 'done';    response: AiResponse;}
+
+type SchemaInput = {    [x: string]: FieldRuleDefinition | FieldRule;}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/ai",
-  "version": "1.6.2",
+  "version": "1.7.0",
   "license": "MIT",
   "maturity": "experimental",
   "private": false,
@@ -12,6 +12,7 @@
   },
   "files": [
     "CHANGELOG.md",
+    "api-surface.md",
     "src",
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
@@ -29,9 +30,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.6.2",
-    "@zerotal/validator": "1.6.2",
-    "@zerotal/queue": "1.6.2"
+    "@zerotal/core": "1.7.0",
+    "@zerotal/validator": "1.7.0",
+    "@zerotal/queue": "1.7.0"
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": ">=0.70.0"

package/src/config.ts

@@ -1,4 +1,5 @@
 import { deepMerge } from "@zerotal/core";
+import type { DeepPartial } from "@zerotal/core";
 import { AiConfigError } from "./errors.ts";
 import type {
   AiConfigShape,
@@ -9,20 +10,6 @@ import type {
 } from "./types.ts";
 import { modelRejectsSampling } from "./pricing.ts";
 
-/**
- * Recursively-optional view of the config, so callers override only what they
- * care about.
- *
- * `NonNullable` before the `extends object` test is load-bearing: every driver
- * block is already optional, so `AnthropicConfigShape | undefined` does not
- * extend `object` and the recursion would stop one level too early — leaving
- * `{ drivers: { anthropic: { apiKey } } }`, the single most common thing anyone
- * writes in `config/ai.ts`, a type error.
- */
-type DeepPartial<T> = {
-  [K in keyof T]?: NonNullable<T[K]> extends object ? DeepPartial<NonNullable<T[K]>> : T[K];
-};
-
 /**
  * What {@link AiConfig} accepts — every key optional, all the way down. The
  * same type the factory's parameter is written as, exported under a name