gavio 0.1.0

package/src/index.ts

@@ -0,0 +1,52 @@
+/**
+ * Gavio — the open standard AI gateway for production systems.
+ *
+ * Public API surface (v0.1.0):
+ *
+ *     import { Gateway, GavioRequest, GavioResponse, Provider } from 'gavio'
+ *
+ * See https://gavio.io for documentation. MIT licensed.
+ */
+
+export const VERSION = '0.1.0'
+
+export { Gateway } from './gateway.js'
+export type { GatewayOptions, CompleteOptions } from './gateway.js'
+
+export { GavioRequest } from './request.js'
+export type { GavioRequestInit } from './request.js'
+export { GavioResponse } from './response.js'
+export type { GavioResponseInit } from './response.js'
+export { InterceptorContext } from './context.js'
+export type { InterceptorContextInit } from './context.js'
+
+export { uuid7, newTraceId } from './ids.js'
+export { PricingProvider, estimateTokens } from './pricing.js'
+
+export {
+  Provider,
+  CacheType,
+  PiiMode,
+  Sensitivity,
+  GuardrailOutcome,
+  TokenUsage,
+  coerceProvider,
+} from './types.js'
+export type { Message } from './types.js'
+
+export type { Interceptor, Executor, ExecutorPolicy } from './interceptors/base.js'
+export { InterceptorChain } from './interceptors/chain.js'
+
+// errors
+export {
+  GavioError,
+  ConfigurationError,
+  ProviderError,
+  ProviderUnavailableError,
+  RateLimitError,
+  ServerError,
+  TimeoutError,
+  PiiBlockedError,
+  BudgetExceededError,
+  GuardrailViolationError,
+} from './errors.js'

package/src/interceptors/audit/index.ts

@@ -0,0 +1,7 @@
+export { auditInterceptor, isAuditInterceptor, AUDIT_NAME } from './interceptor.js'
+export type { AuditInterceptorOptions } from './interceptor.js'
+export { AuditRecord, SCHEMA_VERSION } from './record.js'
+export type { AuditRecordInit } from './record.js'
+export type { AuditSink } from './sink.js'
+export { stdoutSink } from './sinks/stdout.js'
+export type { StdoutSinkOptions } from './sinks/stdout.js'

package/src/interceptors/audit/interceptor.ts

@@ -0,0 +1,93 @@
+/** auditInterceptor (F-OBS-01) — captures a full record of every call. */
+
+import type { InterceptorContext } from '../../context.js'
+import type { GavioRequest } from '../../request.js'
+import type { GavioResponse } from '../../response.js'
+import type { Interceptor } from '../base.js'
+import { AuditRecord } from './record.js'
+import type { AuditSink } from './sink.js'
+import { stdoutSink } from './sinks/stdout.js'
+
+const PROMPT_HASH_KEY = 'audit_prompt_hash'
+
+export const AUDIT_NAME = 'audit'
+
+export interface AuditInterceptorOptions {
+  sink?: AuditSink | 'stdout'
+}
+
+/**
+ * Build an AuditRecord per request and write it to a sink.
+ *
+ * Register this as the outermost interceptor so its `after` runs last and sees
+ * the final, fully-processed response. It hashes the (already PII-redacted)
+ * prompt in `before` and the response in `after` — content is never stored,
+ * only digests and metadata.
+ */
+class AuditInterceptor implements Interceptor {
+  readonly name = AUDIT_NAME
+  readonly dryRunSafe = true // auditing is observation-only, so it always runs
+
+  private readonly sink: AuditSink
+
+  constructor(options: AuditInterceptorOptions = {}) {
+    this.sink = resolveSink(options.sink)
+  }
+
+  async before(request: GavioRequest, ctx: InterceptorContext): Promise<GavioRequest> {
+    ctx.state[PROMPT_HASH_KEY] = AuditRecord.hashText(request.promptText())
+    return request
+  }
+
+  async after(
+    response: GavioResponse,
+    ctx: InterceptorContext,
+  ): Promise<GavioResponse> {
+    const record = new AuditRecord({
+      traceId: response.traceId,
+      parentTraceId: ctx.parentTraceId,
+      agentId: ctx.agentId,
+      sessionId: ctx.sessionId,
+      timestampUtc: AuditRecord.nowUtc(),
+      provider: response.provider,
+      model: response.model,
+      modelVersion: response.modelVersion,
+      promptHash: (ctx.state[PROMPT_HASH_KEY] as string | undefined) ?? '',
+      responseHash: AuditRecord.hashText(response.content),
+      tokenUsage: response.usage,
+      costUsd: response.costUsd,
+      latencyMs: response.latencyMs,
+      piiEntityTypes: [...ctx.piiEntityTypes],
+      piiEntityCounts: { ...ctx.piiEntityCounts },
+      interceptorsFired: [...ctx.interceptorsFired],
+      cacheHit: response.cacheHit,
+      cacheType: response.cacheType,
+      guardrailOutcome: ctx.guardrailOutcome,
+      riskScore: ctx.riskScore,
+    })
+    response.audit = record
+    try {
+      await this.sink.write(record)
+    } catch {
+      // Auditing must never break the call.
+      // eslint-disable-next-line no-console
+      console.error(`[gavio:audit] sink write failed for trace ${record.traceId}`)
+    }
+    return response
+  }
+}
+
+function resolveSink(sink: AuditSink | 'stdout' | undefined): AuditSink {
+  if (sink === undefined || sink === 'stdout') return stdoutSink()
+  return sink
+}
+
+/** Factory: build an audit interceptor. */
+export function auditInterceptor(options: AuditInterceptorOptions = {}): Interceptor {
+  return new AuditInterceptor(options)
+}
+
+/** True if an interceptor is the audit interceptor (used by dev-mode auto-wiring). */
+export function isAuditInterceptor(i: Interceptor): boolean {
+  return i.name === AUDIT_NAME
+}

package/src/interceptors/audit/record.ts

@@ -0,0 +1,138 @@
+/** AuditRecord — the immutable, per-request audit entry. */
+
+import { createHash } from 'node:crypto'
+import { TokenUsage } from '../../types.js'
+
+export const SCHEMA_VERSION = '1.0'
+
+function sha256(text: string): string {
+  return createHash('sha256').update(text, 'utf-8').digest('hex')
+}
+
+export interface AuditRecordInit {
+  traceId: string
+  provider: string
+  model: string
+  timestampUtc: string
+  parentTraceId?: string | null
+  agentId?: string | null
+  sessionId?: string | null
+  modelVersion?: string
+  promptHash?: string
+  responseHash?: string
+  tokenUsage?: TokenUsage
+  costUsd?: number
+  latencyMs?: number
+  piiEntityTypes?: string[]
+  piiEntityCounts?: Record<string, number>
+  interceptorsFired?: string[]
+  cacheHit?: boolean
+  cacheType?: string | null
+  guardrailOutcome?: string | null
+  riskScore?: number | null
+  previousHash?: string
+  schemaVersion?: string
+}
+
+/**
+ * One append-only audit entry. Carries metadata only — never raw content.
+ *
+ * `promptHash` / `responseHash` are SHA-256 digests so the entry is verifiable
+ * without storing sensitive text. `previousHash` is reserved for the v0.2.0
+ * hash-chain (F-OBS-02); empty in v0.1.0.
+ */
+export class AuditRecord {
+  traceId: string
+  provider: string
+  model: string
+  timestampUtc: string
+  parentTraceId: string | null
+  agentId: string | null
+  sessionId: string | null
+  modelVersion: string
+  promptHash: string
+  responseHash: string
+  tokenUsage: TokenUsage
+  costUsd: number
+  latencyMs: number
+  piiEntityTypes: string[]
+  piiEntityCounts: Record<string, number>
+  interceptorsFired: string[]
+  cacheHit: boolean
+  cacheType: string | null
+  guardrailOutcome: string | null
+  riskScore: number | null
+  previousHash: string
+  schemaVersion: string
+
+  constructor(init: AuditRecordInit) {
+    this.traceId = init.traceId
+    this.provider = init.provider
+    this.model = init.model
+    this.timestampUtc = init.timestampUtc
+    this.parentTraceId = init.parentTraceId ?? null
+    this.agentId = init.agentId ?? null
+    this.sessionId = init.sessionId ?? null
+    this.modelVersion = init.modelVersion ?? ''
+    this.promptHash = init.promptHash ?? ''
+    this.responseHash = init.responseHash ?? ''
+    this.tokenUsage = init.tokenUsage ?? new TokenUsage()
+    this.costUsd = init.costUsd ?? 0.0
+    this.latencyMs = init.latencyMs ?? 0
+    this.piiEntityTypes = init.piiEntityTypes ?? []
+    this.piiEntityCounts = init.piiEntityCounts ?? {}
+    this.interceptorsFired = init.interceptorsFired ?? []
+    this.cacheHit = init.cacheHit ?? false
+    this.cacheType = init.cacheType ?? null
+    this.guardrailOutcome = init.guardrailOutcome ?? null
+    this.riskScore = init.riskScore ?? null
+    this.previousHash = init.previousHash ?? ''
+    this.schemaVersion = init.schemaVersion ?? SCHEMA_VERSION
+  }
+
+  static nowUtc(): string {
+    return new Date().toISOString()
+  }
+
+  static hashText(text: string): string {
+    return sha256(text)
+  }
+
+  toJSON(): Record<string, unknown> {
+    return {
+      traceId: this.traceId,
+      parentTraceId: this.parentTraceId,
+      agentId: this.agentId,
+      sessionId: this.sessionId,
+      provider: this.provider,
+      model: this.model,
+      modelVersion: this.modelVersion,
+      timestampUtc: this.timestampUtc,
+      promptHash: this.promptHash,
+      responseHash: this.responseHash,
+      tokenUsage: this.tokenUsage.toJSON(),
+      costUsd: this.costUsd,
+      latencyMs: this.latencyMs,
+      piiEntityTypes: this.piiEntityTypes,
+      piiEntityCounts: this.piiEntityCounts,
+      interceptorsFired: this.interceptorsFired,
+      cacheHit: this.cacheHit,
+      cacheType: this.cacheType,
+      guardrailOutcome: this.guardrailOutcome,
+      riskScore: this.riskScore,
+      previousHash: this.previousHash,
+      schemaVersion: this.schemaVersion,
+    }
+  }
+
+  /** Stable JSON with sorted keys — used for the v0.2.0 hash chain. */
+  toCanonicalJson(): string {
+    const data = this.toJSON()
+    return JSON.stringify(data, Object.keys(data).sort())
+  }
+
+  /** Hash of this record's content — used to build the v0.2.0 chain. */
+  contentHash(): string {
+    return sha256(this.toCanonicalJson())
+  }
+}

package/src/interceptors/audit/sink.ts

@@ -0,0 +1,10 @@
+/** AuditSink — the extensible destination for audit records. */
+
+import type { AuditRecord } from './record.js'
+
+/** Where audit records go. Implement `write` to add a backend. */
+export interface AuditSink {
+  write(record: AuditRecord): Promise<void>
+  /** Flush/close any resources. Optional. */
+  close?(): Promise<void>
+}

package/src/interceptors/audit/sinks/index.ts

@@ -0,0 +1,2 @@
+export { stdoutSink } from './stdout.js'
+export type { StdoutSinkOptions } from './stdout.js'

package/src/interceptors/audit/sinks/stdout.ts

@@ -0,0 +1,42 @@
+/** stdoutSink — human-readable audit output for development (F-OBS-05). */
+
+import type { AuditRecord } from '../record.js'
+import type { AuditSink } from '../sink.js'
+
+export interface StdoutSinkOptions {
+  pretty?: boolean
+  write?: (line: string) => void
+}
+
+/** Print each audit record to stdout. Zero dependencies. */
+export function stdoutSink(options: StdoutSinkOptions = {}): AuditSink {
+  const pretty = options.pretty ?? true
+  // eslint-disable-next-line no-console
+  const emit = options.write ?? ((line: string) => console.log(line))
+  return {
+    async write(record: AuditRecord): Promise<void> {
+      const data = record.toJSON()
+      emit(pretty ? formatPretty(data) : JSON.stringify(data))
+    },
+  }
+}
+
+function formatPretty(data: Record<string, unknown>): string {
+  const usage = data['tokenUsage'] as { totalTokens: number }
+  const piiTypes = data['piiEntityTypes'] as string[]
+  const pii = piiTypes.length > 0 ? piiTypes : ['none']
+  const interceptors = data['interceptorsFired'] as string[]
+  const traceId = String(data['traceId'])
+  const cost = Number(data['costUsd'])
+  return (
+    '[gavio:audit] ' +
+    `trace=${traceId.slice(0, 18)}… ` +
+    `${String(data['provider'])}/${String(data['model'])} ` +
+    `tokens=${usage.totalTokens} ` +
+    `cost=$${cost.toFixed(6)} ` +
+    `latency=${String(data['latencyMs'])}ms ` +
+    `cache=${data['cacheHit'] ? 'HIT' : 'miss'} ` +
+    `pii=${pii.join(',')} ` +
+    `interceptors=[${interceptors.join(',')}]`
+  )
+}

package/src/interceptors/base.ts

@@ -0,0 +1,58 @@
+/** The Interceptor interface — the unit of composition in Gavio. */
+
+import type { InterceptorContext } from '../context.js'
+import type { GavioRequest } from '../request.js'
+import type { GavioResponse } from '../response.js'
+
+/**
+ * A pre/post hook around the provider call.
+ *
+ * `before` runs in registration order on the request; `after` runs in reverse
+ * order on the response (onion model). Either may be omitted. Throwing from
+ * `before` aborts the call.
+ */
+export interface Interceptor {
+  /** Unique name used in audit logs and metrics. */
+  readonly name: string
+
+  /** Pre-interceptor: runs before the provider call. */
+  before?(
+    request: GavioRequest,
+    ctx: InterceptorContext,
+  ): Promise<GavioRequest> | GavioRequest
+
+  /** Post-interceptor: runs after the provider call. */
+  after?(
+    response: GavioResponse,
+    ctx: InterceptorContext,
+  ): Promise<GavioResponse> | GavioResponse
+
+  /** Called if the provider call or a downstream interceptor throws. */
+  onError?(error: Error, ctx: InterceptorContext): void | Promise<void>
+
+  /** If true (default), participates in dry-run mode (logs only). */
+  readonly dryRunSafe?: boolean
+}
+
+/** A function that takes the final request and returns a response (the provider call). */
+export type Executor = (request: GavioRequest) => Promise<GavioResponse>
+
+/**
+ * Base class for executor-wrapping reliability policies.
+ *
+ * Retry, timeout, and fallback can't be expressed as plain before/after hooks:
+ * they need to re-invoke (or race) the executor. They implement `around` so the
+ * Gateway composes them *around* the provider call, innermost-last.
+ */
+export interface ExecutorPolicy extends Interceptor {
+  readonly isExecutorPolicy: true
+  around(
+    request: GavioRequest,
+    ctx: InterceptorContext,
+    callNext: Executor,
+  ): Promise<GavioResponse>
+}
+
+export function isExecutorPolicy(i: Interceptor): i is ExecutorPolicy {
+  return (i as Partial<ExecutorPolicy>).isExecutorPolicy === true
+}

package/src/interceptors/cache/backend.ts

@@ -0,0 +1,15 @@
+/**
+ * CacheBackend — the key/value contract behind the cache interceptors.
+ *
+ * The full SemanticCache interceptor lands in v0.2.0 (F-CACHE-01/02). v0.1.0
+ * ships the backend interface and the in-memory backend so dev mode has a
+ * working, dependency-free cache substrate.
+ */
+
+/** A minimal async key/value store. */
+export interface CacheBackend {
+  get(key: string): Promise<unknown | null>
+  set(key: string, value: unknown, ttlSeconds?: number | null): Promise<void>
+  delete(key: string): Promise<void>
+  clear(): Promise<void>
+}

package/src/interceptors/cache/backends/index.ts

@@ -0,0 +1,2 @@
+export { memoryCacheBackend } from './memory.js'
+export type { MemoryCacheBackendOptions } from './memory.js'

package/src/interceptors/cache/backends/memory.ts

@@ -0,0 +1,68 @@
+/** In-memory cache backend (F-CACHE-03) — default zero-dependency dev backend. */
+
+import type { CacheBackend } from '../backend.js'
+
+interface Entry {
+  value: unknown
+  expiresAt: number | null
+}
+
+export interface MemoryCacheBackendOptions {
+  maxSize?: number
+}
+
+/** LRU-bounded, optionally TTL'd in-process cache. Not shared across processes. */
+class MemoryBackend implements CacheBackend {
+  readonly maxSize: number
+  // Map preserves insertion order, which we use for LRU eviction.
+  private store = new Map<string, Entry>()
+
+  constructor(maxSize = 1000) {
+    this.maxSize = maxSize
+  }
+
+  async get(key: string): Promise<unknown | null> {
+    const entry = this.store.get(key)
+    if (entry === undefined) return null
+    if (entry.expiresAt !== null && now() > entry.expiresAt) {
+      this.store.delete(key)
+      return null
+    }
+    // Move to end (most-recently-used).
+    this.store.delete(key)
+    this.store.set(key, entry)
+    return entry.value
+  }
+
+  async set(key: string, value: unknown, ttlSeconds?: number | null): Promise<void> {
+    const expiresAt = ttlSeconds ? now() + ttlSeconds * 1000 : null
+    this.store.delete(key)
+    this.store.set(key, { value, expiresAt })
+    while (this.store.size > this.maxSize) {
+      const oldest = this.store.keys().next().value
+      if (oldest === undefined) break
+      this.store.delete(oldest)
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    this.store.delete(key)
+  }
+
+  async clear(): Promise<void> {
+    this.store.clear()
+  }
+
+  get size(): number {
+    return this.store.size
+  }
+}
+
+function now(): number {
+  return Date.now()
+}
+
+/** Factory: build an in-memory cache backend. */
+export function memoryCacheBackend(options: MemoryCacheBackendOptions = {}): CacheBackend {
+  return new MemoryBackend(options.maxSize ?? 1000)
+}

package/src/interceptors/cache/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Caching substrate. The SemanticCache interceptor ships in v0.2.0; v0.1.0
+ * exposes the CacheBackend interface and the in-memory backend only.
+ */
+
+export type { CacheBackend } from './backend.js'
+export { memoryCacheBackend } from './backends/memory.js'
+export type { MemoryCacheBackendOptions } from './backends/memory.js'

package/src/interceptors/chain.ts

@@ -0,0 +1,65 @@
+/** InterceptorChain — runs the pre/post pipeline around the provider call. */
+
+import type { InterceptorContext } from '../context.js'
+import type { GavioRequest } from '../request.js'
+import type { GavioResponse } from '../response.js'
+import type { Executor, Interceptor } from './base.js'
+
+const dryRunSafe = (i: Interceptor): boolean => i.dryRunSafe !== false
+
+/**
+ * Ordered list of interceptors wrapping an executor.
+ *
+ * `before` hooks fire in order; the executor runs; `after` hooks fire in
+ * reverse order (onion model). If any stage throws, every interceptor's
+ * `onError` is invoked before the error propagates.
+ */
+export class InterceptorChain {
+  private readonly interceptors: Interceptor[]
+
+  constructor(interceptors: Interceptor[]) {
+    this.interceptors = [...interceptors]
+  }
+
+  async execute(
+    request: GavioRequest,
+    ctx: InterceptorContext,
+    executor: Executor,
+  ): Promise<GavioResponse> {
+    try {
+      let req = request
+      for (const interceptor of this.interceptors) {
+        if (ctx.dryRun && !dryRunSafe(interceptor)) continue
+        if (interceptor.before) {
+          req = await interceptor.before(req, ctx)
+        }
+        ctx.markFired(interceptor.name)
+      }
+
+      let response = await executor(req)
+
+      for (let i = this.interceptors.length - 1; i >= 0; i--) {
+        const interceptor = this.interceptors[i]!
+        if (ctx.dryRun && !dryRunSafe(interceptor)) continue
+        if (interceptor.after) {
+          response = await interceptor.after(response, ctx)
+        }
+      }
+
+      response.interceptorsFired = [...ctx.interceptorsFired]
+      return response
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error))
+      for (const interceptor of this.interceptors) {
+        if (interceptor.onError) {
+          try {
+            await interceptor.onError(err, ctx)
+          } catch {
+            // on_error must never break the propagation of the original error.
+          }
+        }
+      }
+      throw error
+    }
+  }
+}

package/src/interceptors/index.ts

@@ -0,0 +1,9 @@
+/** Interceptor barrel. */
+
+export type { Interceptor, Executor, ExecutorPolicy } from './base.js'
+export { isExecutorPolicy } from './base.js'
+export { InterceptorChain } from './chain.js'
+export { piiGuard } from './pii/index.js'
+export { auditInterceptor } from './audit/index.js'
+export { retryInterceptor, timeoutPolicy, fallbackChain } from './reliability/index.js'
+export { memoryCacheBackend } from './cache/index.js'

package/src/interceptors/pii/context.ts

@@ -0,0 +1,24 @@
+/** ScanContext — per-request state shared across PII scanners. */
+
+/**
+ * Context threaded through every scanner for one request.
+ *
+ * Tracks a monotonic per-entity-type index so repeated entities get stable,
+ * distinct placeholders (`[EMAIL_1]`, `[EMAIL_2]`).
+ */
+export class ScanContext {
+  readonly language: string
+  readonly locale: string
+  private counters: Record<string, number> = {}
+
+  constructor(language = 'en', locale = 'NL') {
+    this.language = language
+    this.locale = locale
+  }
+
+  /** Return the next 1-based index for an entity type. */
+  nextIndex(entityType: string): number {
+    this.counters[entityType] = (this.counters[entityType] ?? 0) + 1
+    return this.counters[entityType]
+  }
+}