gavio 0.1.0

package/src/interceptors/pii/scanners/ssn.ts

@@ -0,0 +1,33 @@
+/** US Social Security Number scanner. */
+
+import type { ScanContext } from '../context.js'
+import { makeMatch } from '../match.js'
+import type { PiiMatch } from '../match.js'
+import type { PiiScanner } from '../scanner.js'
+
+// AAA-GG-SSSS with hyphens or spaces. Requires a separator to avoid colliding
+// with bare 9-digit numbers (handled by the BSN scanner / others).
+const SSN = /\b(?!000|666|9\d\d)\d{3}[ -](?!00)\d{2}[ -](?!0000)\d{4}\b/g
+
+export function ssnScanner(): PiiScanner {
+  return {
+    entityType: 'SSN',
+    tier: 1,
+    scan(text: string, ctx: ScanContext): PiiMatch[] {
+      const out: PiiMatch[] = []
+      for (const m of text.matchAll(SSN)) {
+        const idx = ctx.nextIndex('SSN')
+        out.push(
+          makeMatch({
+            entityType: 'SSN',
+            start: m.index,
+            end: m.index + m[0].length,
+            value: m[0],
+            replacement: `[SSN_${idx}]`,
+          }),
+        )
+      }
+      return out
+    },
+  }
+}

package/src/interceptors/reliability/fallback.ts

@@ -0,0 +1,66 @@
+/** fallbackChain (F-REL-02) — route to a secondary provider on failure. */
+
+import type { InterceptorContext } from '../../context.js'
+import { ProviderError } from '../../errors.js'
+import type { ProviderAdapter } from '../../providers/base.js'
+import type { GavioRequest } from '../../request.js'
+import type { GavioResponse } from '../../response.js'
+import { coerceProvider } from '../../types.js'
+import type { Executor, ExecutorPolicy } from '../base.js'
+
+export interface FallbackChainOptions {
+  /** Provider adapters to try, in order, when the primary call fails. */
+  fallbacks: ProviderAdapter[]
+}
+
+/**
+ * Try the primary executor; on a provider error, try fallback adapters.
+ *
+ * Each fallback is a provider adapter (anything with an async `complete`). The
+ * request's provider/model are rewritten per fallback so the audit record
+ * reflects which provider actually answered.
+ */
+class FallbackChain implements ExecutorPolicy {
+  readonly name = 'fallback'
+  readonly isExecutorPolicy = true as const
+  readonly dryRunSafe = true
+
+  private readonly fallbacks: ProviderAdapter[]
+
+  constructor(options: FallbackChainOptions) {
+    if (!options.fallbacks || options.fallbacks.length === 0) {
+      throw new Error('fallbackChain requires at least one fallback adapter')
+    }
+    this.fallbacks = options.fallbacks
+  }
+
+  async around(
+    request: GavioRequest,
+    ctx: InterceptorContext,
+    callNext: Executor,
+  ): Promise<GavioResponse> {
+    ctx.markFired(this.name)
+    try {
+      return await callNext(request)
+    } catch (primaryError) {
+      if (!(primaryError instanceof ProviderError)) throw primaryError
+      let lastError: unknown = primaryError
+      for (const adapter of this.fallbacks) {
+        try {
+          const rerouted = request.copyWithMessages(request.messages)
+          rerouted.provider = coerceProvider(adapter.providerName)
+          return await adapter.complete(rerouted)
+        } catch (error) {
+          if (!(error instanceof ProviderError)) throw error
+          lastError = error
+        }
+      }
+      throw lastError
+    }
+  }
+}
+
+/** Factory: build a fallback policy. */
+export function fallbackChain(options: FallbackChainOptions): ExecutorPolicy {
+  return new FallbackChain(options)
+}

package/src/interceptors/reliability/index.ts

@@ -0,0 +1,8 @@
+/** Reliability policies (F-REL-01, F-REL-02, F-REL-07). */
+
+export { retryInterceptor } from './retry.js'
+export type { RetryInterceptorOptions } from './retry.js'
+export { timeoutPolicy, timeout } from './timeout.js'
+export type { TimeoutPolicyOptions } from './timeout.js'
+export { fallbackChain } from './fallback.js'
+export type { FallbackChainOptions } from './fallback.js'

package/src/interceptors/reliability/retry.ts

@@ -0,0 +1,97 @@
+/** retryInterceptor (F-REL-01) — exponential backoff with jitter. */
+
+import { randomBytes } from 'node:crypto'
+import type { InterceptorContext } from '../../context.js'
+import {
+  ProviderUnavailableError,
+  RateLimitError,
+  ServerError,
+  TimeoutError,
+} from '../../errors.js'
+import type { GavioRequest } from '../../request.js'
+import type { GavioResponse } from '../../response.js'
+import type { Executor, ExecutorPolicy } from '../base.js'
+
+/** Default predicate: retry transient provider errors. */
+function defaultRetryable(error: unknown): boolean {
+  return (
+    error instanceof RateLimitError ||
+    error instanceof TimeoutError ||
+    error instanceof ServerError ||
+    error instanceof ProviderUnavailableError
+  )
+}
+
+export interface RetryInterceptorOptions {
+  maxAttempts?: number
+  baseDelayMs?: number
+  maxDelayMs?: number
+  jitter?: boolean
+  retryOn?: (error: unknown) => boolean
+  /** Override the sleep implementation (used in tests). */
+  sleep?: (ms: number) => Promise<void>
+}
+
+const defaultSleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms))
+
+class RetryInterceptor implements ExecutorPolicy {
+  readonly name = 'retry'
+  readonly isExecutorPolicy = true as const
+  readonly dryRunSafe = true
+
+  private readonly maxAttempts: number
+  private readonly baseDelayMs: number
+  private readonly maxDelayMs: number
+  private readonly jitter: boolean
+  private readonly retryOn: (error: unknown) => boolean
+  private readonly sleep: (ms: number) => Promise<void>
+
+  constructor(options: RetryInterceptorOptions = {}) {
+    const maxAttempts = options.maxAttempts ?? 3
+    if (maxAttempts < 1) throw new Error('maxAttempts must be >= 1')
+    this.maxAttempts = maxAttempts
+    this.baseDelayMs = options.baseDelayMs ?? 500
+    this.maxDelayMs = options.maxDelayMs ?? 10_000
+    this.jitter = options.jitter ?? true
+    this.retryOn = options.retryOn ?? defaultRetryable
+    this.sleep = options.sleep ?? defaultSleep
+  }
+
+  async around(
+    request: GavioRequest,
+    ctx: InterceptorContext,
+    callNext: Executor,
+  ): Promise<GavioResponse> {
+    ctx.markFired(this.name)
+    let lastError: unknown
+    for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
+      try {
+        return await callNext(request)
+      } catch (error) {
+        if (!this.retryOn(error)) throw error
+        lastError = error
+        if (attempt >= this.maxAttempts) break
+        await this.sleep(this.delayMs(attempt))
+      }
+    }
+    throw lastError
+  }
+
+  private delayMs(attempt: number): number {
+    // Exponential: base * 2^(attempt-1), capped, with optional full jitter.
+    const raw = this.baseDelayMs * 2 ** (attempt - 1)
+    let capped = Math.min(raw, this.maxDelayMs)
+    if (this.jitter) {
+      // full jitter in [0, capped] using crypto bytes (no global RNG state)
+      const frac = randomBytes(2).readUInt16BE(0) / 0xffff
+      capped *= frac
+    }
+    return capped
+  }
+}
+
+/** Factory: build a retry policy. */
+export function retryInterceptor(options: RetryInterceptorOptions = {}): ExecutorPolicy {
+  return new RetryInterceptor(options)
+}

package/src/interceptors/reliability/timeout.ts

@@ -0,0 +1,53 @@
+/** timeoutPolicy (F-REL-07) — per-request timeout enforcement. */
+
+import type { InterceptorContext } from '../../context.js'
+import { TimeoutError } from '../../errors.js'
+import type { GavioRequest } from '../../request.js'
+import type { GavioResponse } from '../../response.js'
+import type { Executor, ExecutorPolicy } from '../base.js'
+
+export interface TimeoutPolicyOptions {
+  timeoutSeconds?: number
+}
+
+class TimeoutPolicy implements ExecutorPolicy {
+  readonly name = 'timeout'
+  readonly isExecutorPolicy = true as const
+  readonly dryRunSafe = true
+
+  private readonly timeoutSeconds: number
+
+  constructor(options: TimeoutPolicyOptions = {}) {
+    const timeoutSeconds = options.timeoutSeconds ?? 30.0
+    if (timeoutSeconds <= 0) throw new Error('timeoutSeconds must be > 0')
+    this.timeoutSeconds = timeoutSeconds
+  }
+
+  async around(
+    request: GavioRequest,
+    ctx: InterceptorContext,
+    callNext: Executor,
+  ): Promise<GavioResponse> {
+    ctx.markFired(this.name)
+    const ms = this.timeoutSeconds * 1000
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const timeout = new Promise<never>((_, reject) => {
+      timer = setTimeout(() => {
+        reject(new TimeoutError(`Request exceeded ${this.timeoutSeconds}s timeout`))
+      }, ms)
+    })
+    try {
+      return await Promise.race([callNext(request), timeout])
+    } finally {
+      if (timer !== undefined) clearTimeout(timer)
+    }
+  }
+}
+
+/** Factory: build a timeout policy. */
+export function timeoutPolicy(options: TimeoutPolicyOptions = {}): ExecutorPolicy {
+  return new TimeoutPolicy(options)
+}
+
+/** Alias matching the SDK plan naming (`timeout`). */
+export const timeout = timeoutPolicy

package/src/pricing.ts

@@ -0,0 +1,72 @@
+/**
+ * Token cost tracking (F-GOV-01).
+ *
+ * Prices are USD per 1,000 tokens, sourced from public provider pricing and
+ * overridable. Unknown models price at zero (warned once) rather than guessing.
+ * Prices are intentionally data, not code — update the table, not the estimator.
+ */
+
+import type { TokenUsage } from './types.js'
+
+/** model -> [inputPer1kUsd, outputPer1kUsd] */
+const DEFAULT_PRICES: Record<string, [number, number]> = {
+  // OpenAI
+  'gpt-4o': [0.0025, 0.01],
+  'gpt-4o-mini': [0.00015, 0.0006],
+  o1: [0.015, 0.06],
+  'o1-mini': [0.0011, 0.0044],
+  // Anthropic
+  'claude-sonnet-4-6': [0.003, 0.015],
+  'claude-sonnet-4-20250514': [0.003, 0.015],
+  'claude-haiku-4-5': [0.0008, 0.004],
+  'claude-opus-4-1': [0.015, 0.075],
+  // Local / mock are free.
+  mock: [0.0, 0.0],
+}
+
+/** Estimates request cost from token usage and a model price table. */
+export class PricingProvider {
+  private prices: Record<string, [number, number]>
+  private warned = new Set<string>()
+
+  constructor(prices?: Record<string, [number, number]>) {
+    this.prices = { ...DEFAULT_PRICES, ...(prices ?? {}) }
+  }
+
+  setPrice(model: string, inputPer1k: number, outputPer1k: number): void {
+    this.prices[model] = [inputPer1k, outputPer1k]
+  }
+
+  rates(model: string): [number, number] {
+    const rate = this.prices[model]
+    if (rate !== undefined) return rate
+    // try a prefix match (e.g. "gpt-4o-2024-..." -> "gpt-4o")
+    for (const [known, value] of Object.entries(this.prices)) {
+      if (model.startsWith(known)) return value
+    }
+    if (!this.warned.has(model)) {
+      // eslint-disable-next-line no-console
+      console.warn(`[gavio:pricing] no pricing for model '${model}'; treating as free`)
+      this.warned.add(model)
+    }
+    return [0.0, 0.0]
+  }
+
+  estimate(model: string, usage: TokenUsage): number {
+    const [inRate, outRate] = this.rates(model)
+    let cost = (usage.promptTokens / 1000.0) * inRate
+    cost += (usage.completionTokens / 1000.0) * outRate
+    return roundTo(cost, 8)
+  }
+}
+
+function roundTo(value: number, decimals: number): number {
+  const factor = 10 ** decimals
+  return Math.round(value * factor) / factor
+}
+
+/** Rough token estimate (~4 chars/token) for providers without a tokenizer. */
+export function estimateTokens(text: string): number {
+  if (!text) return 0
+  return Math.max(1, Math.floor(text.length / 4))
+}

package/src/providers/anthropic.ts

@@ -0,0 +1,113 @@
+/** anthropicAdapter — Messages API (Claude Sonnet, Haiku, Opus). */
+
+import { ConfigurationError } from '../errors.js'
+import type { PricingProvider } from '../pricing.js'
+import type { GavioRequest } from '../request.js'
+import type { GavioResponse } from '../response.js'
+import { TokenUsage } from '../types.js'
+import type { Message } from '../types.js'
+import { BaseProviderAdapter } from './base.js'
+import { postJson } from './http.js'
+
+const DEFAULT_BASE_URL = 'https://api.anthropic.com/v1'
+const API_VERSION = '2023-06-01'
+
+export interface AnthropicAdapterOptions {
+  apiKey?: string
+  baseUrl?: string
+  timeoutMs?: number
+  pricing?: PricingProvider
+}
+
+/**
+ * Talks to the Anthropic Messages endpoint. Anthropic splits the system prompt
+ * from the message list, so any `role === "system"` messages are extracted into
+ * the `system` field.
+ */
+class AnthropicAdapter extends BaseProviderAdapter {
+  private readonly apiKey: string | undefined
+  private readonly baseUrl: string
+  private readonly timeoutSeconds: number
+
+  constructor(options: AnthropicAdapterOptions = {}) {
+    super(options.pricing)
+    this.apiKey = options.apiKey ?? process.env['ANTHROPIC_API_KEY']
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '')
+    this.timeoutSeconds = (options.timeoutMs ?? 30_000) / 1000
+  }
+
+  get providerName(): string {
+    return 'anthropic'
+  }
+
+  private headers(): Record<string, string> {
+    if (!this.apiKey) {
+      throw new ConfigurationError(
+        'ANTHROPIC_API_KEY not set (pass apiKey or set the env var)',
+      )
+    }
+    return {
+      'x-api-key': this.apiKey,
+      'anthropic-version': API_VERSION,
+    }
+  }
+
+  private static splitSystem(messages: Message[]): [string | null, Message[]] {
+    const systemParts = messages
+      .filter((m) => m.role === 'system')
+      .map((m) => m.content)
+    const chat = messages.filter((m) => m.role !== 'system')
+    const system = systemParts.length > 0 ? systemParts.join('\n') : null
+    return [system, chat]
+  }
+
+  async complete(request: GavioRequest): Promise<GavioResponse> {
+    const started = performance.now()
+    const [system, chat] = AnthropicAdapter.splitSystem(request.messages)
+    const payload: Record<string, unknown> = {
+      model: request.model,
+      messages: chat,
+      max_tokens: request.maxTokens,
+      temperature: request.temperature,
+    }
+    if (system) payload['system'] = system
+
+    const data = await postJson(
+      `${this.baseUrl}/messages`,
+      payload,
+      this.headers(),
+      this.timeoutSeconds,
+    )
+    const blocks = (data['content'] as Array<Record<string, unknown>>) ?? []
+    const content = blocks
+      .filter((b) => b['type'] === 'text')
+      .map((b) => (b['text'] as string) ?? '')
+      .join('')
+    const usageData = (data['usage'] as Record<string, number>) ?? {}
+    const usage = new TokenUsage(
+      usageData['input_tokens'] ?? 0,
+      usageData['output_tokens'] ?? 0,
+    )
+    return this.buildResponse(
+      request,
+      content,
+      usage,
+      (data['model'] as string) ?? request.model,
+      started,
+    )
+  }
+
+  async healthCheck(): Promise<boolean> {
+    try {
+      this.headers()
+      return true
+    } catch {
+      return false
+    }
+  }
+}
+
+/** Factory: build an Anthropic provider adapter. */
+export function anthropicAdapter(options: AnthropicAdapterOptions = {}): AnthropicAdapter {
+  return new AnthropicAdapter(options)
+}

package/src/providers/base.ts

@@ -0,0 +1,52 @@
+/** ProviderAdapter interface and shared response-building helpers. */
+
+import { PricingProvider } from '../pricing.js'
+import { GavioRequest } from '../request.js'
+import { GavioResponse } from '../response.js'
+import { TokenUsage } from '../types.js'
+
+/** Adapter to one LLM provider. */
+export interface ProviderAdapter {
+  readonly providerName: string
+  complete(request: GavioRequest): Promise<GavioResponse>
+  stream?(request: GavioRequest): AsyncIterable<string>
+  healthCheck(): Promise<boolean>
+  readonly reportedModelVersion?: string | null
+}
+
+/** Base class with a shared pricing provider and response builder. */
+export abstract class BaseProviderAdapter implements ProviderAdapter {
+  protected readonly pricing: PricingProvider
+
+  constructor(pricing?: PricingProvider) {
+    this.pricing = pricing ?? new PricingProvider()
+  }
+
+  abstract get providerName(): string
+  abstract complete(request: GavioRequest): Promise<GavioResponse>
+  abstract healthCheck(): Promise<boolean>
+
+  get reportedModelVersion(): string | null {
+    return null
+  }
+
+  protected buildResponse(
+    request: GavioRequest,
+    content: string,
+    usage: TokenUsage,
+    modelVersion: string,
+    startedAt: number,
+  ): GavioResponse {
+    const latencyMs = Math.floor(performance.now() - startedAt)
+    return new GavioResponse({
+      traceId: request.traceId,
+      content,
+      model: request.model,
+      provider: this.providerName,
+      modelVersion: modelVersion || request.model,
+      usage,
+      costUsd: this.pricing.estimate(request.model, usage),
+      latencyMs,
+    })
+  }
+}

package/src/providers/http.ts

@@ -0,0 +1,50 @@
+/** Tiny JSON-over-HTTP helper built on native fetch (keeps core dependency-free). */
+
+import {
+  ProviderUnavailableError,
+  RateLimitError,
+  ServerError,
+} from '../errors.js'
+
+/**
+ * POST `payload` as JSON and return the parsed response.
+ *
+ * Maps HTTP status families onto Gavio's transient error types so the
+ * retry/fallback policies can react.
+ */
+export async function postJson(
+  url: string,
+  payload: unknown,
+  headers: Record<string, string>,
+  timeoutSeconds = 30.0,
+): Promise<Record<string, unknown>> {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutSeconds * 1000)
+  let resp: Response
+  try {
+    resp = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...headers },
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+    })
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error)
+    throw new ProviderUnavailableError(`network error: ${reason}`)
+  } finally {
+    clearTimeout(timer)
+  }
+
+  if (!resp.ok) {
+    const body = (await resp.text().catch(() => '')).slice(0, 200)
+    if (resp.status === 429) {
+      throw new RateLimitError(`429 from provider: ${body}`)
+    }
+    if (resp.status >= 500) {
+      throw new ServerError(`${resp.status} from provider: ${body}`)
+    }
+    throw new ProviderUnavailableError(`${resp.status} from provider: ${body}`)
+  }
+
+  return (await resp.json()) as Record<string, unknown>
+}

package/src/providers/index.ts

@@ -0,0 +1,39 @@
+/** Provider adapters and the provider registry. */
+
+import { ConfigurationError } from '../errors.js'
+import type { PricingProvider } from '../pricing.js'
+import { Provider, coerceProvider } from '../types.js'
+import { anthropicAdapter } from './anthropic.js'
+import type { ProviderAdapter } from './base.js'
+import { mockProvider } from './mock.js'
+import { openaiAdapter } from './openai.js'
+
+export type { ProviderAdapter } from './base.js'
+export { BaseProviderAdapter } from './base.js'
+export { mockProvider } from './mock.js'
+export type { MockProviderOptions } from './mock.js'
+export { openaiAdapter } from './openai.js'
+export type { OpenAIAdapterOptions } from './openai.js'
+export { anthropicAdapter } from './anthropic.js'
+export type { AnthropicAdapterOptions } from './anthropic.js'
+export { Provider } from '../types.js'
+
+/** Instantiate the default adapter for a provider id. v0.1.0: OpenAI, Anthropic, Mock. */
+export function buildAdapter(
+  provider: Provider | string,
+  pricing?: PricingProvider,
+): ProviderAdapter {
+  const p = coerceProvider(provider)
+  switch (p) {
+    case Provider.OPENAI:
+      return openaiAdapter(pricing ? { pricing } : {})
+    case Provider.ANTHROPIC:
+      return anthropicAdapter(pricing ? { pricing } : {})
+    case Provider.MOCK:
+      return mockProvider(pricing ? { pricing } : {})
+    default:
+      throw new ConfigurationError(
+        `Provider '${p}' is not available in v0.1.0 (available: openai, anthropic, mock)`,
+      )
+  }
+}

package/src/providers/mock.ts

@@ -0,0 +1,73 @@
+/** mockProvider — deterministic, offline provider for dev mode and tests. */
+
+import { PricingProvider, estimateTokens } from '../pricing.js'
+import type { GavioRequest } from '../request.js'
+import type { GavioResponse } from '../response.js'
+import { TokenUsage } from '../types.js'
+import { BaseProviderAdapter } from './base.js'
+
+export interface MockProviderOptions {
+  response?: string | null
+  modelVersion?: string
+  pricing?: PricingProvider
+}
+
+/**
+ * Returns a canned response without any network call.
+ *
+ * If `response` is null/undefined, it echoes the last user message so the
+ * pipeline (including PII restore) is observable end to end.
+ */
+class MockProvider extends BaseProviderAdapter {
+  private readonly response: string | null
+  private readonly modelVersion: string
+
+  constructor(options: MockProviderOptions = {}) {
+    super(options.pricing)
+    this.response = options.response ?? null
+    this.modelVersion = options.modelVersion ?? 'mock-1'
+  }
+
+  get providerName(): string {
+    return 'mock'
+  }
+
+  override get reportedModelVersion(): string | null {
+    return this.modelVersion
+  }
+
+  private contentFor(request: GavioRequest): string {
+    if (this.response !== null) return this.response
+    const lastUser = [...request.messages]
+      .reverse()
+      .find((m) => m.role === 'user')
+    return `[mock reply] ${lastUser?.content ?? ''}`
+  }
+
+  async complete(request: GavioRequest): Promise<GavioResponse> {
+    const started = performance.now()
+    const content = this.contentFor(request)
+    const usage = new TokenUsage(
+      estimateTokens(request.promptText()),
+      estimateTokens(content),
+    )
+    return this.buildResponse(request, content, usage, this.modelVersion, started)
+  }
+
+  async *stream(request: GavioRequest): AsyncIterable<string> {
+    for (const token of this.contentFor(request).split(' ')) {
+      yield token + ' '
+    }
+  }
+
+  async healthCheck(): Promise<boolean> {
+    return true
+  }
+}
+
+/** Factory: build a mock provider adapter. */
+export function mockProvider(options: MockProviderOptions = {}): ProviderAdapterMock {
+  return new MockProvider(options)
+}
+
+export type ProviderAdapterMock = MockProvider