gavio 0.2.0 → 0.3.0

package/src/interceptors/audit/interceptor.ts

@@ -3,12 +3,14 @@
 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'
 
@@ -41,6 +43,7 @@ class AuditInterceptor implements Interceptor {
 
   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
   }
 
@@ -69,6 +72,7 @@ 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

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/metrics/index.ts

@@ -0,0 +1,6 @@
+/** Prometheus metrics (F-OBS-08). */
+
+export { PrometheusMetrics } from './registry.js'
+export type { RecordSample } from './registry.js'
+export { metricsInterceptor, METRICS_NAME } from './interceptor.js'
+export type { MetricsInterceptor } from './interceptor.js'

package/src/interceptors/metrics/interceptor.ts

@@ -0,0 +1,46 @@
+/** metricsInterceptor (F-OBS-08) — records Prometheus metrics per request. */
+
+import type { InterceptorContext } from '../../context.js'
+import type { GavioResponse } from '../../response.js'
+import type { Interceptor } from '../base.js'
+import { PrometheusMetrics } from './registry.js'
+
+export const METRICS_NAME = 'metrics'
+
+/** An interceptor that also exposes the registry it records into. */
+export interface MetricsInterceptor extends Interceptor {
+  readonly metrics: PrometheusMetrics
+}
+
+/**
+ * Build a metrics interceptor. Pass a shared {@link PrometheusMetrics} registry
+ * (or let it create one) and scrape it via `.metrics.render()`:
+ *
+ * ```ts
+ * const m = metricsInterceptor()
+ * const gw = new Gateway({ devMode: true }).use(m)
+ * // ...
+ * console.log(m.metrics.render())
+ * ```
+ *
+ * Observation-only, so it always runs (including in dry-run).
+ */
+export function metricsInterceptor(
+  metrics: PrometheusMetrics = new PrometheusMetrics(),
+): MetricsInterceptor {
+  return {
+    name: METRICS_NAME,
+    dryRunSafe: true,
+    metrics,
+    async after(response: GavioResponse, _ctx: InterceptorContext): Promise<GavioResponse> {
+      metrics.record(response.provider, response.model, {
+        promptTokens: response.usage.promptTokens,
+        completionTokens: response.usage.completionTokens,
+        costUsd: response.costUsd,
+        latencyMs: response.latencyMs,
+        cacheHit: response.cacheHit,
+      })
+      return response
+    },
+  }
+}

package/src/interceptors/quality/index.ts

@@ -0,0 +1,4 @@
+/** Quality & compliance interceptors (F-QUA-06 risk scoring; F-QUA-03/04 to come). */
+
+export { RiskScorer, riskScorer } from './risk.js'
+export type { RiskWeights } from './risk.js'

package/src/interceptors/quality/risk.ts

@@ -0,0 +1,64 @@
+/**
+ * RiskScorer (F-QUA-06) — a composite risk score from per-request signals.
+ *
+ * Folds the signals other interceptors leave on the {@link InterceptorContext}
+ * — PII entities found, guardrail outcome, and the prompt-injection risk — into
+ * a single score in `[0, 1]` written to `ctx.riskScore` (and thus the audit
+ * record). Register it *inside* the audit interceptor so audit sees the composite.
+ */
+
+import type { InterceptorContext } from '../../context.js'
+import type { GavioResponse } from '../../response.js'
+import type { Interceptor } from '../base.js'
+
+export interface RiskWeights {
+  pii?: number
+  guardrail?: number
+  injection?: number
+  /** PII entity count at which the PII signal saturates to 1.0 (<= 0 → any PII = 1.0). */
+  piiSaturation?: number
+}
+
+// Guardrail outcome → its contribution before weighting.
+const GUARDRAIL_SIGNAL: Record<string, number> = { FAIL: 1.0, HITL: 0.6 }
+
+export class RiskScorer implements Interceptor {
+  readonly name = 'risk_scorer'
+  readonly dryRunSafe = true
+
+  private readonly pii: number
+  private readonly guardrail: number
+  private readonly injection: number
+  private readonly piiSaturation: number
+
+  constructor(weights: RiskWeights = {}) {
+    this.pii = weights.pii ?? 0.3
+    this.guardrail = weights.guardrail ?? 0.4
+    this.injection = weights.injection ?? 0.3
+    this.piiSaturation = weights.piiSaturation ?? 4
+  }
+
+  /** Compute the composite risk score from the three raw signals. */
+  score(piiCount: number, guardrailOutcome: string | null, injectionScore: number | null): number {
+    let piiSignal = 0
+    if (piiCount > 0) {
+      piiSignal = this.piiSaturation <= 0 ? 1 : Math.min(1, piiCount / this.piiSaturation)
+    }
+    const guardrailSignal = GUARDRAIL_SIGNAL[guardrailOutcome ?? ''] ?? 0
+    const injectionSignal = injectionScore ?? 0
+    const composite =
+      this.pii * piiSignal + this.guardrail * guardrailSignal + this.injection * injectionSignal
+    return Math.max(0, Math.min(1, composite))
+  }
+
+  async after(response: GavioResponse, ctx: InterceptorContext): Promise<GavioResponse> {
+    const piiCount = Object.values(ctx.piiEntityCounts).reduce((a, b) => a + b, 0)
+    ctx.riskScore = this.score(piiCount, ctx.guardrailOutcome, ctx.riskScore)
+    return response
+  }
+}
+
+/** Build a risk scorer. */
+export function riskScorer(weights: RiskWeights = {}): RiskScorer {
+  return new RiskScorer(weights)
+}

package/src/interceptors/reliability/index.ts

@@ -10,3 +10,4 @@ export { circuitBreaker, CircuitState } from './circuit-breaker.js'
 export type { CircuitBreakerOptions } from './circuit-breaker.js'
 export { loadBalancer } from './load-balancer.js'
 export type { LoadBalancerOptions } from './load-balancer.js'
+export { StreamBuffer } from './stream-buffer.js'

package/src/interceptors/reliability/stream-buffer.ts

@@ -0,0 +1,27 @@
+/**
+ * StreamBuffer (F-REL-06) — accumulate a provider stream for post-interceptors.
+ *
+ * Post-interceptors (guardrails, PII restore, audit) need the *complete*
+ * response, so a streamed reply is buffered in full before the post pipeline
+ * runs and before any chunk reaches the caller. This trades first-token latency
+ * for the guarantee that every interceptor sees — and can rewrite or block — the
+ * whole response.
+ */
+export class StreamBuffer {
+  private readonly parts: string[] = []
+
+  /** Add one streamed chunk. */
+  append(chunk: string): void {
+    this.parts.push(chunk)
+  }
+
+  /** The full buffered response so far. */
+  text(): string {
+    return this.parts.join('')
+  }
+
+  /** Total buffered length in characters. */
+  get length(): number {
+    return this.parts.reduce((n, p) => n + p.length, 0)
+  }
+}

package/src/providers/base.ts

@@ -1,6 +1,6 @@
 /** ProviderAdapter interface and shared response-building helpers. */
 
-import { PricingProvider } from '../pricing.js'
+import { PricingProvider, estimateTokens } from '../pricing.js'
 import { GavioRequest } from '../request.js'
 import { GavioResponse } from '../response.js'
 import { TokenUsage } from '../types.js'
@@ -10,6 +10,8 @@ export interface ProviderAdapter {
   readonly providerName: string
   complete(request: GavioRequest): Promise<GavioResponse>
   stream?(request: GavioRequest): AsyncIterable<string>
+  /** Build a response from a fully buffered stream (F-REL-06). */
+  buildStreamResponse?(request: GavioRequest, content: string, startedAt: number): GavioResponse
   healthCheck(): Promise<boolean>
   readonly reportedModelVersion?: string | null
 }
@@ -30,6 +32,24 @@ export abstract class BaseProviderAdapter implements ProviderAdapter {
     return null
   }
 
+  /**
+   * Build a response from a fully buffered stream (F-REL-06). Streamed chunks
+   * carry text only, so token usage is estimated from prompt + content.
+   */
+  buildStreamResponse(request: GavioRequest, content: string, startedAt: number): GavioResponse {
+    const usage = new TokenUsage(
+      estimateTokens(request.promptText()),
+      estimateTokens(content),
+    )
+    return this.buildResponse(
+      request,
+      content,
+      usage,
+      this.reportedModelVersion ?? request.model,
+      startedAt,
+    )
+  }
+
   protected buildResponse(
     request: GavioRequest,
     content: string,

package/src/request.ts

@@ -1,8 +1,8 @@
 /** GavioRequest — the canonical, provider-agnostic request model. */
 
 import { newTraceId } from './ids.js'
-import { coerceProvider } from './types.js'
-import type { Message, Provider } from './types.js'
+import { coerceProvider, PromptLineage } from './types.js'
+import type { Message, PromptLineageInit, Provider } from './types.js'
 
 export interface GavioRequestInit {
   messages: Message[]
@@ -14,6 +14,7 @@ export interface GavioRequestInit {
   sessionId?: string | null
   options?: Record<string, unknown>
   metadata?: Record<string, unknown>
+  lineage?: PromptLineage | PromptLineageInit | null
 }
 
 /**
@@ -31,6 +32,7 @@ export class GavioRequest {
   sessionId: string | null
   options: Record<string, unknown>
   metadata: Record<string, unknown>
+  lineage: PromptLineage | null
 
   constructor(init: GavioRequestInit) {
     this.messages = init.messages
@@ -42,6 +44,7 @@ export class GavioRequest {
     this.sessionId = init.sessionId ?? null
     this.options = init.options ?? {}
     this.metadata = init.metadata ?? {}
+    this.lineage = init.lineage != null ? PromptLineage.from(init.lineage) : null
   }
 
   get temperature(): number {
@@ -71,6 +74,7 @@ export class GavioRequest {
       sessionId: this.sessionId,
       options: { ...this.options },
       metadata: { ...this.metadata },
+      lineage: this.lineage,
     })
   }
 }

package/src/types.ts

@@ -81,3 +81,80 @@ export class TokenUsage {
     }
   }
 }
+
+export interface RagChunkInit {
+  source: string
+  chunkId?: string | null
+  score?: number | null
+}
+
+/**
+ * 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 {
+  readonly source: string
+  readonly chunkId: string | null
+  readonly score: number | null
+
+  constructor(init: RagChunkInit) {
+    this.source = init.source
+    this.chunkId = init.chunkId ?? null
+    this.score = init.score ?? null
+  }
+
+  toJSON(): { source: string; chunkId: string | null; score: number | null } {
+    return { source: this.source, chunkId: this.chunkId, score: this.score }
+  }
+}
+
+export interface PromptLineageInit {
+  templateId?: string | null
+  templateVersion?: string | null
+  variables?: Record<string, unknown>
+  ragChunks?: Array<RagChunk | RagChunkInit>
+}
+
+/**
+ * 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 {
+  readonly templateId: string | null
+  readonly templateVersion: string | null
+  readonly variables: Record<string, unknown>
+  readonly ragChunks: RagChunk[]
+
+  constructor(init: PromptLineageInit = {}) {
+    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: PromptLineage | PromptLineageInit): PromptLineage {
+    return value instanceof PromptLineage ? value : new PromptLineage(value)
+  }
+
+  toJSON(): {
+    templateId: string | null
+    templateVersion: string | null
+    variables: Record<string, unknown>
+    ragChunks: Array<{ source: string; chunkId: string | null; score: number | null }>
+  } {
+    return {
+      templateId: this.templateId,
+      templateVersion: this.templateVersion,
+      variables: this.variables,
+      ragChunks: this.ragChunks.map((c) => c.toJSON()),
+    }
+  }
+}