gavio 0.2.0 → 0.3.0

package/dist/esm/interceptors/audit/record.js

@@ -1,10 +1,22 @@
 /** 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';
 function sha256(text) {
     return createHash('sha256').update(text, 'utf-8').digest('hex');
 }
+/** Deterministic JSON with keys sorted at every nesting level. */
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    const obj = value;
+    const parts = Object.keys(obj)
+        .sort()
+        .map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`);
+    return `{${parts.join(',')}}`;
+}
 /**
  * One append-only audit entry. Carries metadata only — never raw content.
  *
@@ -33,6 +45,7 @@ export class AuditRecord {
     cacheType;
     guardrailOutcome;
     riskScore;
+    lineage;
     previousHash;
     schemaVersion;
     constructor(init) {
@@ -56,6 +69,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;
     }
@@ -87,14 +101,14 @@ 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() {
-        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. */
     contentHash() {

package/dist/esm/interceptors/metrics/index.d.ts

@@ -0,0 +1,5 @@
+/** 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/dist/esm/interceptors/metrics/index.js

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

package/dist/esm/interceptors/metrics/interceptor.d.ts

@@ -0,0 +1,22 @@
+/** metricsInterceptor (F-OBS-08) — records Prometheus metrics per request. */
+import type { Interceptor } from '../base.js';
+import { PrometheusMetrics } from './registry.js';
+export declare 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 declare function metricsInterceptor(metrics?: PrometheusMetrics): MetricsInterceptor;

package/dist/esm/interceptors/metrics/interceptor.js

@@ -0,0 +1,33 @@
+/** metricsInterceptor (F-OBS-08) — records Prometheus metrics per request. */
+import { PrometheusMetrics } from './registry.js';
+export const METRICS_NAME = 'metrics';
+/**
+ * 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 = new PrometheusMetrics()) {
+    return {
+        name: METRICS_NAME,
+        dryRunSafe: true,
+        metrics,
+        async after(response, _ctx) {
+            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/dist/esm/interceptors/metrics/registry.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Prometheus metrics registry (F-OBS-08) — zero-dependency exposition.
+ *
+ * Holds counters and a latency histogram keyed by `provider|model` and renders
+ * them in the Prometheus text exposition format. No client library — the format
+ * is hand-rolled so the core stays dependency-free.
+ */
+export interface RecordSample {
+    promptTokens?: number;
+    completionTokens?: number;
+    costUsd?: number;
+    latencyMs?: number;
+    cacheHit?: boolean;
+}
+/**
+ * Thread-free, in-process metrics rendered as Prometheus exposition text. All
+ * series are labelled by `provider` and `model`.
+ */
+export declare class PrometheusMetrics {
+    private readonly ns;
+    private readonly requests;
+    private readonly tokens;
+    private readonly cost;
+    private readonly cacheHits;
+    private readonly latency;
+    private readonly keyLabels;
+    constructor(namespace?: string);
+    record(provider: string, model: string, sample?: RecordSample): void;
+    /** Return the Prometheus text exposition of all metrics. */
+    render(): string;
+}

package/dist/esm/interceptors/quality/index.d.ts

@@ -0,0 +1,3 @@
+/** 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/dist/esm/interceptors/quality/index.js

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

package/dist/esm/interceptors/quality/risk.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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;
+}
+export declare class RiskScorer implements Interceptor {
+    readonly name = "risk_scorer";
+    readonly dryRunSafe = true;
+    private readonly pii;
+    private readonly guardrail;
+    private readonly injection;
+    private readonly piiSaturation;
+    constructor(weights?: RiskWeights);
+    /** Compute the composite risk score from the three raw signals. */
+    score(piiCount: number, guardrailOutcome: string | null, injectionScore: number | null): number;
+    after(response: GavioResponse, ctx: InterceptorContext): Promise<GavioResponse>;
+}
+/** Build a risk scorer. */
+export declare function riskScorer(weights?: RiskWeights): RiskScorer;

package/dist/esm/interceptors/quality/risk.js

@@ -0,0 +1,44 @@
+/**
+ * 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.
+ */
+// Guardrail outcome → its contribution before weighting.
+const GUARDRAIL_SIGNAL = { FAIL: 1.0, HITL: 0.6 };
+export class RiskScorer {
+    name = 'risk_scorer';
+    dryRunSafe = true;
+    pii;
+    guardrail;
+    injection;
+    piiSaturation;
+    constructor(weights = {}) {
+        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, guardrailOutcome, injectionScore) {
+        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, ctx) {
+        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 = {}) {
+    return new RiskScorer(weights);
+}

package/dist/esm/interceptors/reliability/index.d.ts

@@ -9,3 +9,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/dist/esm/interceptors/reliability/index.js

@@ -4,3 +4,4 @@ export { timeoutPolicy, timeout } from './timeout.js';
 export { fallbackChain } from './fallback.js';
 export { circuitBreaker, CircuitState } from './circuit-breaker.js';
 export { loadBalancer } from './load-balancer.js';
+export { StreamBuffer } from './stream-buffer.js';

package/dist/esm/interceptors/reliability/stream-buffer.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 declare class StreamBuffer {
+    private readonly parts;
+    /** Add one streamed chunk. */
+    append(chunk: string): void;
+    /** The full buffered response so far. */
+    text(): string;
+    /** Total buffered length in characters. */
+    get length(): number;
+}

package/dist/esm/interceptors/reliability/stream-buffer.js

@@ -0,0 +1,24 @@
+/**
+ * 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 {
+    parts = [];
+    /** Add one streamed chunk. */
+    append(chunk) {
+        this.parts.push(chunk);
+    }
+    /** The full buffered response so far. */
+    text() {
+        return this.parts.join('');
+    }
+    /** Total buffered length in characters. */
+    get length() {
+        return this.parts.reduce((n, p) => n + p.length, 0);
+    }
+}

package/dist/esm/providers/base.d.ts

@@ -8,6 +8,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;
 }
@@ -19,5 +21,10 @@ export declare abstract class BaseProviderAdapter implements ProviderAdapter {
     abstract complete(request: GavioRequest): Promise<GavioResponse>;
     abstract healthCheck(): Promise<boolean>;
     get reportedModelVersion(): string | 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;
     protected buildResponse(request: GavioRequest, content: string, usage: TokenUsage, modelVersion: string, startedAt: number): GavioResponse;
 }

package/dist/esm/providers/base.js

@@ -1,5 +1,5 @@
 /** 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';
@@ -12,6 +12,14 @@ export class BaseProviderAdapter {
     get reportedModelVersion() {
         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, content, startedAt) {
+        const usage = new TokenUsage(estimateTokens(request.promptText()), estimateTokens(content));
+        return this.buildResponse(request, content, usage, this.reportedModelVersion ?? request.model, startedAt);
+    }
     buildResponse(request, content, usage, modelVersion, startedAt) {
         const latencyMs = Math.floor(performance.now() - startedAt);
         return new GavioResponse({

package/dist/esm/request.d.ts

@@ -1,5 +1,6 @@
 /** GavioRequest — the canonical, provider-agnostic request model. */
-import type { Message, Provider } from './types.js';
+import { PromptLineage } from './types.js';
+import type { Message, PromptLineageInit, Provider } from './types.js';
 export interface GavioRequestInit {
     messages: Message[];
     model: string;
@@ -10,6 +11,7 @@ export interface GavioRequestInit {
     sessionId?: string | null;
     options?: Record<string, unknown>;
     metadata?: Record<string, unknown>;
+    lineage?: PromptLineage | PromptLineageInit | null;
 }
 /**
  * A single gateway call. A `traceId` (UUID v7, time-sortable) is assigned
@@ -26,6 +28,7 @@ export declare class GavioRequest {
     sessionId: string | null;
     options: Record<string, unknown>;
     metadata: Record<string, unknown>;
+    lineage: PromptLineage | null;
     constructor(init: GavioRequestInit);
     get temperature(): number;
     get maxTokens(): number;

package/dist/esm/request.js

@@ -1,6 +1,6 @@
 /** GavioRequest — the canonical, provider-agnostic request model. */
 import { newTraceId } from './ids.js';
-import { coerceProvider } from './types.js';
+import { coerceProvider, PromptLineage } from './types.js';
 /**
  * A single gateway call. A `traceId` (UUID v7, time-sortable) is assigned
  * automatically if not supplied. `parentTraceId` links calls into a
@@ -16,6 +16,7 @@ export class GavioRequest {
     sessionId;
     options;
     metadata;
+    lineage;
     constructor(init) {
         this.messages = init.messages;
         this.model = init.model;
@@ -26,6 +27,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() {
         const t = this.options['temperature'];
@@ -51,6 +53,7 @@ export class GavioRequest {
             sessionId: this.sessionId,
             options: { ...this.options },
             metadata: { ...this.metadata },
+            lineage: this.lineage,
         });
     }
 }

package/dist/esm/types.d.ts

@@ -56,3 +56,57 @@ export declare class TokenUsage {
         totalTokens: number;
     };
 }
+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 declare class RagChunk {
+    readonly source: string;
+    readonly chunkId: string | null;
+    readonly score: number | null;
+    constructor(init: RagChunkInit);
+    toJSON(): {
+        source: string;
+        chunkId: string | null;
+        score: number | null;
+    };
+}
+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 declare class PromptLineage {
+    readonly templateId: string | null;
+    readonly templateVersion: string | null;
+    readonly variables: Record<string, unknown>;
+    readonly ragChunks: RagChunk[];
+    constructor(init?: PromptLineageInit);
+    /** Coerce a PromptLineage instance or plain init object into a PromptLineage. */
+    static from(value: PromptLineage | PromptLineageInit): PromptLineage;
+    toJSON(): {
+        templateId: string | null;
+        templateVersion: string | null;
+        variables: Record<string, unknown>;
+        ragChunks: Array<{
+            source: string;
+            chunkId: string | null;
+            score: number | null;
+        }>;
+    };
+}

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.2.0",
+  "version": "0.3.0",
   "description": "The open standard AI gateway for production systems — PII guarding, audit, reliability, and cost tracking.",
   "license": "MIT",
   "repository": {
@@ -80,6 +80,16 @@
       "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",

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> = {
@@ -109,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,
@@ -122,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'