gavio 0.1.0 → 0.3.0

package/dist/esm/types.js

@@ -54,3 +54,53 @@ export class TokenUsage {
         };
     }
 }
+/**
+ * A single retrieved source that contributed to a prompt. Carries a *reference*
+ * to the source — never the retrieved text — so prompt lineage stays within the
+ * audit record's metadata-only contract.
+ */
+export class RagChunk {
+    source;
+    chunkId;
+    score;
+    constructor(init) {
+        this.source = init.source;
+        this.chunkId = init.chunkId ?? null;
+        this.score = init.score ?? null;
+    }
+    toJSON() {
+        return { source: this.source, chunkId: this.chunkId, score: this.score };
+    }
+}
+/**
+ * Provenance for a rendered prompt (F-OBS-04): the template, the variable
+ * bindings interpolated into it, and the RAG chunk sources retrieved for it.
+ *
+ * Attached to a GavioRequest by the caller and copied into the AuditRecord so
+ * any prompt can be reconstructed and debugged. RAG chunk text is never stored
+ * — only source references (see {@link RagChunk}).
+ */
+export class PromptLineage {
+    templateId;
+    templateVersion;
+    variables;
+    ragChunks;
+    constructor(init = {}) {
+        this.templateId = init.templateId ?? null;
+        this.templateVersion = init.templateVersion ?? null;
+        this.variables = init.variables ?? {};
+        this.ragChunks = (init.ragChunks ?? []).map((c) => c instanceof RagChunk ? c : new RagChunk(c));
+    }
+    /** Coerce a PromptLineage instance or plain init object into a PromptLineage. */
+    static from(value) {
+        return value instanceof PromptLineage ? value : new PromptLineage(value);
+    }
+    toJSON() {
+        return {
+            templateId: this.templateId,
+            templateVersion: this.templateVersion,
+            variables: this.variables,
+            ragChunks: this.ragChunks.map((c) => c.toJSON()),
+        };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gavio",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "The open standard AI gateway for production systems — PII guarding, audit, reliability, and cost tracking.",
   "license": "MIT",
   "repository": {
@@ -65,6 +65,36 @@
       "import": "./dist/esm/interceptors/reliability/index.js",
       "require": "./dist/cjs/interceptors/reliability/index.js"
     },
+    "./interceptors/governance": {
+      "types": "./dist/esm/interceptors/governance/index.d.ts",
+      "import": "./dist/esm/interceptors/governance/index.js",
+      "require": "./dist/cjs/interceptors/governance/index.js"
+    },
+    "./interceptors/guardrails": {
+      "types": "./dist/esm/interceptors/guardrails/index.d.ts",
+      "import": "./dist/esm/interceptors/guardrails/index.js",
+      "require": "./dist/cjs/interceptors/guardrails/index.js"
+    },
+    "./interceptors/injection": {
+      "types": "./dist/esm/interceptors/injection.d.ts",
+      "import": "./dist/esm/interceptors/injection.js",
+      "require": "./dist/cjs/interceptors/injection.js"
+    },
+    "./interceptors/metrics": {
+      "types": "./dist/esm/interceptors/metrics/index.d.ts",
+      "import": "./dist/esm/interceptors/metrics/index.js",
+      "require": "./dist/cjs/interceptors/metrics/index.js"
+    },
+    "./interceptors/quality": {
+      "types": "./dist/esm/interceptors/quality/index.d.ts",
+      "import": "./dist/esm/interceptors/quality/index.js",
+      "require": "./dist/cjs/interceptors/quality/index.js"
+    },
+    "./shim/openai": {
+      "types": "./dist/esm/shim/openai.d.ts",
+      "import": "./dist/esm/shim/openai.js",
+      "require": "./dist/cjs/shim/openai.js"
+    },
     "./providers": {
       "types": "./dist/esm/providers/index.d.ts",
       "import": "./dist/esm/providers/index.js",
@@ -99,11 +129,20 @@
   },
   "keywords": [
     "ai",
-    "gateway",
+    "ai-gateway",
     "llm",
+    "llm-gateway",
+    "llmops",
+    "gateway",
     "pii",
+    "pii-redaction",
     "audit",
+    "observability",
     "reliability",
+    "retry",
+    "fallback",
+    "cost-tracking",
+    "interceptor",
     "openai",
     "anthropic"
   ],

package/src/config.ts

@@ -0,0 +1,125 @@
+/**
+ * Config loader (F-DX-05) — build a Gateway from an object or a JSON file.
+ *
+ *   const gw = await Gateway.fromConfig('gateway.json')
+ *
+ * JSON is supported out of the box; string values expand ${ENV_VAR}.
+ */
+
+import { readFileSync } from 'node:fs'
+import { ConfigurationError } from './errors.js'
+import { Gateway } from './gateway.js'
+import { auditInterceptor } from './interceptors/audit/index.js'
+import { hashingEmbedder, semanticCache } from './interceptors/cache/index.js'
+import { costControl, modelPolicy, rateLimiter } from './interceptors/governance/index.js'
+import { promptInjectionGuard } from './interceptors/injection.js'
+import { piiGuard } from './interceptors/pii/index.js'
+import { retryInterceptor, timeoutPolicy } from './interceptors/reliability/index.js'
+
+type Cfg = Record<string, unknown>
+
+export function loadConfig(path: string): Cfg {
+  const text = readFileSync(path, 'utf8')
+  if (!path.endsWith('.json')) {
+    throw new ConfigurationError('JS config loader supports JSON only (use .json)')
+  }
+  return expand(JSON.parse(text)) as Cfg
+}
+
+function expand(obj: unknown): unknown {
+  if (Array.isArray(obj)) return obj.map(expand)
+  if (obj && typeof obj === 'object') {
+    return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, expand(v)]))
+  }
+  if (typeof obj === 'string') {
+    return obj.replace(/\$\{(\w+)\}/g, (_, v: string) => process.env[v] ?? '')
+  }
+  return obj
+}
+
+export function buildFromConfig(config: Cfg): Gateway {
+  const gatewayOptions: Cfg = {}
+  if (config['provider']) gatewayOptions['provider'] = config['provider']
+  if (config['model']) gatewayOptions['model'] = config['model']
+  if (config['devMode'] ?? config['dev_mode']) gatewayOptions['devMode'] = true
+  if (config['dryRun'] ?? config['dry_run']) gatewayOptions['dryRun'] = true
+
+  let gw = new Gateway(gatewayOptions)
+  const ic = (config['interceptors'] as Record<string, Cfg> | undefined) ?? {}
+
+  const cfg = (name: string): Cfg | null => {
+    const entry = ic[name]
+    return entry && entry['enabled'] !== false ? entry : null
+  }
+
+  let c: Cfg | null
+  if ((c = cfg('audit'))) {
+    gw = gw.use(
+      auditInterceptor({
+        sink: (c['sink'] as 'stdout') ?? 'stdout',
+        hashChain: Boolean(c['hashChain'] ?? c['hash_chain']),
+      }),
+    )
+  }
+  if ((c = cfg('prompt_injection'))) {
+    gw = gw.use(promptInjectionGuard({ action: (c['action'] as 'block' | 'flag') ?? 'block' }))
+  }
+  if ((c = cfg('pii_guard'))) {
+    gw = gw.use(
+      piiGuard({
+        sensitivity: (c['sensitivity'] as never) ?? 'strict',
+        mode: (c['mode'] as never) ?? 'redact',
+      }),
+    )
+  }
+  if ((c = cfg('cost_control'))) {
+    gw = gw.use(
+      costControl({
+        hardCapUsd: Number(c['hardCapUsd'] ?? c['hard_cap_usd']),
+        softCapUsd: (c['softCapUsd'] ?? c['soft_cap_usd']) as number | undefined,
+        scope: (c['scope'] as never) ?? 'global',
+        window: (c['window'] as never) ?? 'day',
+      }),
+    )
+  }
+  if ((c = cfg('rate_limiter'))) {
+    gw = gw.use(
+      rateLimiter({
+        maxRequestsPerMinute: (c['maxRequestsPerMinute'] ?? c['max_requests_per_minute']) as
+          | number
+          | undefined,
+        maxTokensPerMinute: (c['maxTokensPerMinute'] ?? c['max_tokens_per_minute']) as
+          | number
+          | undefined,
+        scope: (c['scope'] as never) ?? 'global',
+      }),
+    )
+  }
+  if ((c = cfg('model_policy'))) {
+    gw = gw.use(modelPolicy({ roles: (c['roles'] as Record<string, string[]>) ?? {} }))
+  }
+  if ((c = cfg('semantic_cache'))) {
+    const embedder = (c['enableSemantic'] ?? c['enable_semantic']) ? hashingEmbedder() : undefined
+    gw = gw.use(
+      semanticCache({
+        embedder,
+        similarityThreshold: Number(c['similarityThreshold'] ?? c['similarity_threshold'] ?? 0.95),
+      }),
+    )
+  }
+  if ((c = cfg('timeout'))) {
+    gw = gw.use(
+      timeoutPolicy({ timeoutSeconds: Number(c['timeoutSeconds'] ?? c['timeout_seconds'] ?? 30) }),
+    )
+  }
+  if ((c = cfg('retry'))) {
+    gw = gw.use(
+      retryInterceptor({
+        maxAttempts: Number(c['maxAttempts'] ?? c['max_attempts'] ?? 3),
+        baseDelayMs: Number(c['baseDelayMs'] ?? c['base_delay_ms'] ?? 500),
+      }),
+    )
+  }
+
+  return gw
+}

package/src/errors.ts

@@ -43,5 +43,33 @@ export class PiiBlockedError extends GavioError {
 /** A hard budget cap was exceeded. Never swallow this — surface to user. */
 export class BudgetExceededError extends GavioError {}
 
+/** The circuit breaker is open; the call was rejected without hitting the provider. */
+export class CircuitOpenError extends ProviderUnavailableError {}
+
+/** A local rate limit (requests/tokens per minute) was exceeded. */
+export class RateLimitExceededError extends GavioError {}
+
+/** The caller's role is not permitted to use the requested model (RBAC). */
+export class ModelNotAllowedError extends GavioError {
+  readonly role: string
+  readonly model: string
+
+  constructor(role: string, model: string) {
+    super(`role ${JSON.stringify(role)} may not use model ${JSON.stringify(model)}`)
+    this.role = role
+    this.model = model
+  }
+}
+
 /** Output failed a guardrail validator with onFailure='error'. */
 export class GuardrailViolationError extends GavioError {}
+
+/** A prompt-injection attempt was detected and the guard is in block mode. */
+export class PromptInjectionError extends GavioError {
+  readonly patterns: string[]
+
+  constructor(patterns: string[]) {
+    super(`prompt injection detected: ${patterns.join(', ')}`)
+    this.patterns = patterns
+  }
+}

package/src/gateway.ts

@@ -6,6 +6,7 @@ import { auditInterceptor, isAuditInterceptor } from './interceptors/audit/index
 import { isExecutorPolicy } from './interceptors/base.js'
 import type { Executor, ExecutorPolicy, Interceptor } from './interceptors/base.js'
 import { InterceptorChain } from './interceptors/chain.js'
+import { StreamBuffer } from './interceptors/reliability/stream-buffer.js'
 import { PricingProvider } from './pricing.js'
 import { buildAdapter } from './providers/index.js'
 import type { ProviderAdapter } from './providers/base.js'
@@ -13,7 +14,7 @@ import { mockProvider } from './providers/mock.js'
 import { GavioRequest } from './request.js'
 import type { GavioResponse } from './response.js'
 import { Provider, coerceProvider } from './types.js'
-import type { Message } from './types.js'
+import type { Message, PromptLineage, PromptLineageInit } from './types.js'
 
 export interface GatewayOptions {
   provider?: Provider | string
@@ -33,6 +34,8 @@ export interface CompleteOptions {
   metadata?: Record<string, unknown>
   /** Provider sampling options (temperature, maxTokens, etc.). */
   options?: Record<string, unknown>
+  /** Prompt provenance (F-OBS-04): template, variables, and RAG chunk sources. */
+  lineage?: PromptLineage | PromptLineageInit | null
 }
 
 const DEFAULT_MODELS: Record<string, string> = {
@@ -66,6 +69,16 @@ export class Gateway {
     this.pricing = options.pricing ?? new PricingProvider()
   }
 
+  /**
+   * Build a Gateway from a config object or a JSON file path (F-DX-05).
+   * Async so the config module loads lazily (avoids a circular import).
+   */
+  static async fromConfig(config: string | Record<string, unknown>): Promise<Gateway> {
+    const mod = await import('./config.js')
+    const data = typeof config === 'string' ? mod.loadConfig(config) : config
+    return mod.buildFromConfig(data)
+  }
+
   /** Register an interceptor or executor policy. First-registered = outermost. */
   use(interceptor: Interceptor): this {
     this.interceptors.push(interceptor)
@@ -99,6 +112,7 @@ export class Gateway {
       sessionId: opts.sessionId ?? null,
       options: opts.options ?? {},
       metadata: opts.metadata ?? {},
+      lineage: opts.lineage ?? null,
     })
     const ctx = new InterceptorContext({
       traceId: request.traceId,
@@ -112,6 +126,53 @@ export class Gateway {
     return chain.execute(request, ctx, executor)
   }
 
+  /**
+   * Stream a completion, buffering the provider stream (F-REL-06).
+   *
+   * The provider stream is buffered in full so the post-interceptor pipeline
+   * (guardrails, PII restore, audit) runs on the complete response before any
+   * chunk reaches the caller. Pre/post interceptors run via the chain; executor
+   * policies (retry, circuit breaker, cache) are not applied to the streaming
+   * path.
+   */
+  async *stream(opts: CompleteOptions): AsyncGenerator<string> {
+    const adapter = this.resolveAdapter()
+    if (adapter.stream === undefined || adapter.buildStreamResponse === undefined) {
+      throw new ConfigurationError(`${adapter.providerName} does not support streaming`)
+    }
+    const model = opts.model ?? this.modelHint ?? this.resolveModel(adapter)
+
+    const request = new GavioRequest({
+      messages: opts.messages,
+      model,
+      provider: coerceProvider(adapter.providerName),
+      agentId: opts.agentId ?? null,
+      parentTraceId: opts.parentTraceId ?? null,
+      sessionId: opts.sessionId ?? null,
+      options: opts.options ?? {},
+      metadata: opts.metadata ?? {},
+    })
+    const ctx = new InterceptorContext({
+      traceId: request.traceId,
+      agentId: request.agentId,
+      parentTraceId: request.parentTraceId,
+      sessionId: request.sessionId,
+      dryRun: this.dryRunMode,
+    })
+
+    const startedAt = performance.now()
+    const buffer = new StreamBuffer()
+    const { chain } = this.buildPipeline(adapter, ctx)
+    const bufferingExecutor: Executor = async (req) => {
+      for await (const chunk of adapter.stream!(req)) buffer.append(chunk)
+      return adapter.buildStreamResponse!(req, buffer.text(), startedAt)
+    }
+
+    const response = await chain.execute(request, ctx, bufferingExecutor)
+    // Post-interceptors have run on the fully buffered response; emit it now.
+    yield response.content
+  }
+
   async healthCheck(): Promise<boolean> {
     return this.resolveAdapter().healthCheck()
   }

package/src/index.ts

@@ -8,7 +8,7 @@
  * See https://gavio.io for documentation. MIT licensed.
  */
 
-export const VERSION = '0.1.0'
+export const VERSION = '0.3.0'
 
 export { Gateway } from './gateway.js'
 export type { GatewayOptions, CompleteOptions } from './gateway.js'
@@ -30,9 +30,11 @@ export {
   Sensitivity,
   GuardrailOutcome,
   TokenUsage,
+  PromptLineage,
+  RagChunk,
   coerceProvider,
 } from './types.js'
-export type { Message } from './types.js'
+export type { Message, PromptLineageInit, RagChunkInit } from './types.js'
 
 export type { Interceptor, Executor, ExecutorPolicy } from './interceptors/base.js'
 export { InterceptorChain } from './interceptors/chain.js'

package/src/interceptors/audit/index.ts

@@ -5,3 +5,5 @@ 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'
+export { verifyChain, buildCallGraph } from './trace.js'
+export type { TraceNode } from './trace.js'

package/src/interceptors/audit/interceptor.ts

@@ -3,17 +3,21 @@
 import type { InterceptorContext } from '../../context.js'
 import type { GavioRequest } from '../../request.js'
 import type { GavioResponse } from '../../response.js'
+import type { PromptLineage } from '../../types.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'
+const LINEAGE_KEY = 'audit_lineage'
 
 export const AUDIT_NAME = 'audit'
 
 export interface AuditInterceptorOptions {
   sink?: AuditSink | 'stdout'
+  /** F-OBS-02: link each record via previousHash into a tamper-evident chain. */
+  hashChain?: boolean
 }
 
 /**
@@ -29,13 +33,17 @@ class AuditInterceptor implements Interceptor {
   readonly dryRunSafe = true // auditing is observation-only, so it always runs
 
   private readonly sink: AuditSink
+  private readonly hashChain: boolean
+  private lastHash = ''
 
   constructor(options: AuditInterceptorOptions = {}) {
     this.sink = resolveSink(options.sink)
+    this.hashChain = options.hashChain ?? false
   }
 
   async before(request: GavioRequest, ctx: InterceptorContext): Promise<GavioRequest> {
     ctx.state[PROMPT_HASH_KEY] = AuditRecord.hashText(request.promptText())
+    if (request.lineage != null) ctx.state[LINEAGE_KEY] = request.lineage
     return request
   }
 
@@ -64,7 +72,12 @@ class AuditInterceptor implements Interceptor {
       cacheType: response.cacheType,
       guardrailOutcome: ctx.guardrailOutcome,
       riskScore: ctx.riskScore,
+      lineage: (ctx.state[LINEAGE_KEY] as PromptLineage | undefined) ?? null,
     })
+    if (this.hashChain) {
+      record.previousHash = this.lastHash
+      this.lastHash = record.contentHash()
+    }
     response.audit = record
     try {
       await this.sink.write(record)

package/src/interceptors/audit/record.ts

@@ -1,7 +1,7 @@
 /** AuditRecord — the immutable, per-request audit entry. */
 
 import { createHash } from 'node:crypto'
-import { TokenUsage } from '../../types.js'
+import { PromptLineage, TokenUsage } from '../../types.js'
 
 export const SCHEMA_VERSION = '1.0'
 
@@ -9,6 +9,17 @@ function sha256(text: string): string {
   return createHash('sha256').update(text, 'utf-8').digest('hex')
 }
 
+/** Deterministic JSON with keys sorted at every nesting level. */
+function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null'
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`
+  const obj = value as Record<string, unknown>
+  const parts = Object.keys(obj)
+    .sort()
+    .map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`)
+  return `{${parts.join(',')}}`
+}
+
 export interface AuditRecordInit {
   traceId: string
   provider: string
@@ -30,6 +41,7 @@ export interface AuditRecordInit {
   cacheType?: string | null
   guardrailOutcome?: string | null
   riskScore?: number | null
+  lineage?: PromptLineage | null
   previousHash?: string
   schemaVersion?: string
 }
@@ -62,6 +74,7 @@ export class AuditRecord {
   cacheType: string | null
   guardrailOutcome: string | null
   riskScore: number | null
+  lineage: PromptLineage | null
   previousHash: string
   schemaVersion: string
 
@@ -86,6 +99,7 @@ export class AuditRecord {
     this.cacheType = init.cacheType ?? null
     this.guardrailOutcome = init.guardrailOutcome ?? null
     this.riskScore = init.riskScore ?? null
+    this.lineage = init.lineage ?? null
     this.previousHash = init.previousHash ?? ''
     this.schemaVersion = init.schemaVersion ?? SCHEMA_VERSION
   }
@@ -120,15 +134,15 @@ export class AuditRecord {
       cacheType: this.cacheType,
       guardrailOutcome: this.guardrailOutcome,
       riskScore: this.riskScore,
+      lineage: this.lineage ? this.lineage.toJSON() : null,
       previousHash: this.previousHash,
       schemaVersion: this.schemaVersion,
     }
   }
 
-  /** Stable JSON with sorted keys — used for the v0.2.0 hash chain. */
+  /** Stable JSON with recursively sorted keys — used for the v0.2.0 hash chain. */
   toCanonicalJson(): string {
-    const data = this.toJSON()
-    return JSON.stringify(data, Object.keys(data).sort())
+    return stableStringify(this.toJSON())
   }
 
   /** Hash of this record's content — used to build the v0.2.0 chain. */

package/src/interceptors/audit/trace.ts

@@ -0,0 +1,47 @@
+/** Audit-chain verification (F-OBS-02) and multi-agent DAG trace (F-OBS-03). */
+
+import type { AuditRecord } from './record.js'
+
+/**
+ * Return true if the records form an intact hash chain. Each record's
+ * previousHash must equal the content hash of the record before it; the first
+ * must be empty. Any edit, reorder, or deletion breaks the chain.
+ */
+export function verifyChain(records: AuditRecord[]): boolean {
+  let prevHash = ''
+  for (const rec of records) {
+    if (rec.previousHash !== prevHash) return false
+    prevHash = rec.contentHash()
+  }
+  return true
+}
+
+export interface TraceNode {
+  traceId: string
+  agentId: string | null
+  parentTraceId: string | null
+  children: TraceNode[]
+}
+
+/**
+ * Reconstruct the multi-agent DAG from audit records using parentTraceId +
+ * traceId. Returns the root nodes (those with no known parent).
+ */
+export function buildCallGraph(records: AuditRecord[]): TraceNode[] {
+  const nodes = new Map<string, TraceNode>()
+  for (const rec of records) {
+    nodes.set(rec.traceId, {
+      traceId: rec.traceId,
+      agentId: rec.agentId,
+      parentTraceId: rec.parentTraceId,
+      children: [],
+    })
+  }
+  const roots: TraceNode[] = []
+  for (const node of nodes.values()) {
+    const parent = node.parentTraceId ? nodes.get(node.parentTraceId) : undefined
+    if (parent) parent.children.push(node)
+    else roots.push(node)
+  }
+  return roots
+}

package/src/interceptors/cache/embedding.ts

@@ -0,0 +1,53 @@
+/**
+ * Embeddings for the semantic cache (F-CACHE-02).
+ *
+ * Zero-dependency hashed bag-of-words embedder (L2-normalised) — good enough to
+ * dedup near-identical prompts. Plug in a real embedder implementing `Embedder`
+ * for production semantic matching.
+ */
+
+import { createHash } from 'node:crypto'
+
+export interface Embedder {
+  embed(text: string): number[]
+}
+
+const TOKEN = /[a-z0-9]+/g
+
+/** Deterministic hashed bag-of-words embedder. */
+export function hashingEmbedder(dim = 256): Embedder {
+  return {
+    embed(text: string): number[] {
+      const vec = new Array<number>(dim).fill(0)
+      const tokens = text.toLowerCase().match(TOKEN) ?? []
+      for (const token of tokens) {
+        // Parity note: Python uses blake2b(digest_size=8); here we take the
+        // first 8 bytes of blake2b512. Both are deterministic; the JS cache is
+        // per-process so cross-language byte-parity is not required.
+        const digest = createHash('blake2b512').update(token).digest()
+        let n = 0n
+        for (let i = 0; i < 8; i++) n = (n << 8n) | BigInt(digest[i]!)
+        const bucket = Number(n % BigInt(dim))
+        vec[bucket]! += 1
+      }
+      const norm = Math.sqrt(vec.reduce((s, x) => s + x * x, 0))
+      if (norm === 0) return vec
+      return vec.map((x) => x / norm)
+    },
+  }
+}
+
+/** Cosine similarity; safe for zero vectors. */
+export function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length !== b.length) throw new Error('vectors must have equal length')
+  let dot = 0
+  let na = 0
+  let nb = 0
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i]! * b[i]!
+    na += a[i]! * a[i]!
+    nb += b[i]! * b[i]!
+  }
+  if (na === 0 || nb === 0) return 0
+  return dot / (Math.sqrt(na) * Math.sqrt(nb))
+}

package/src/interceptors/cache/index.ts

@@ -1,8 +1,11 @@
-/**
- * Caching substrate. The SemanticCache interceptor ships in v0.2.0; v0.1.0
- * exposes the CacheBackend interface and the in-memory backend only.
- */
+/** Caching (F-CACHE-01 exact, F-CACHE-02 semantic, F-CACHE-03 in-memory). */
 
 export type { CacheBackend } from './backend.js'
 export { memoryCacheBackend } from './backends/memory.js'
 export type { MemoryCacheBackendOptions } from './backends/memory.js'
+export { semanticCache } from './interceptor.js'
+export type { SemanticCacheOptions } from './interceptor.js'
+export { hashingEmbedder, cosineSimilarity } from './embedding.js'
+export type { Embedder } from './embedding.js'
+export { inMemoryVectorBackend } from './vector.js'
+export type { VectorBackend } from './vector.js'