gavio 0.1.0 → 0.3.0

package/dist/esm/interceptors/reliability/load-balancer.js

@@ -0,0 +1,35 @@
+/** loadBalancer (F-REL-04) — weighted round-robin across provider adapters. */
+import { coerceProvider } from '../../types.js';
+class LoadBalancer {
+    name = 'load_balancer';
+    isExecutorPolicy = true;
+    pool;
+    index = 0;
+    constructor(adapters, options = {}) {
+        if (adapters.length === 0) {
+            throw new Error('loadBalancer requires at least one adapter');
+        }
+        const weights = options.weights ?? adapters.map(() => 1);
+        if (weights.length !== adapters.length) {
+            throw new Error('weights must match adapters length');
+        }
+        // Expand by weight, then cycle for round-robin.
+        this.pool = [];
+        adapters.forEach((adapter, i) => {
+            for (let k = 0; k < Math.max(1, weights[i]); k++)
+                this.pool.push(adapter);
+        });
+    }
+    async around(request, ctx, _callNext) {
+        ctx.markFired(this.name);
+        const adapter = this.pool[this.index % this.pool.length];
+        this.index += 1;
+        const rerouted = request.copyWithMessages(request.messages);
+        rerouted.provider = coerceProvider(adapter.providerName);
+        return adapter.complete(rerouted);
+    }
+}
+/** Factory: build a load balancer over a pool of adapters. */
+export function loadBalancer(adapters, options = {}) {
+    return new LoadBalancer(adapters, options);
+}

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/pricing.js

@@ -17,7 +17,11 @@ const DEFAULT_PRICES = {
     '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.
+    // Gemini (approximate public pricing; override via config)
+    'gemini-2.0-flash': [0.0001, 0.0004],
+    'gemini-1.5-flash': [0.000075, 0.0003],
+    'gemini-1.5-pro': [0.00125, 0.005],
+    // Local (Ollama) / mock are free.
     mock: [0.0, 0.0],
 };
 /** Estimates request cost from token usage and a model price table. */

package/dist/esm/providers/azure-openai.d.ts

@@ -0,0 +1,28 @@
+/** azureOpenaiAdapter — Azure OpenAI deployment-based chat completions. */
+import type { PricingProvider } from '../pricing.js';
+import type { GavioRequest } from '../request.js';
+import type { GavioResponse } from '../response.js';
+import { BaseProviderAdapter } from './base.js';
+export interface AzureOpenAIAdapterOptions {
+    apiKey?: string;
+    endpoint?: string;
+    deployment?: string;
+    apiVersion?: string;
+    timeoutMs?: number;
+    pricing?: PricingProvider;
+}
+declare class AzureOpenAIAdapter extends BaseProviderAdapter {
+    private readonly apiKey;
+    readonly endpoint: string;
+    private readonly deployment;
+    private readonly apiVersion;
+    private readonly timeoutSeconds;
+    constructor(options?: AzureOpenAIAdapterOptions);
+    get providerName(): string;
+    url(request: GavioRequest): string;
+    complete(request: GavioRequest): Promise<GavioResponse>;
+    healthCheck(): Promise<boolean>;
+}
+/** Factory: build an Azure OpenAI provider adapter. */
+export declare function azureOpenaiAdapter(options?: AzureOpenAIAdapterOptions): AzureOpenAIAdapter;
+export {};

package/dist/esm/providers/azure-openai.js

@@ -0,0 +1,53 @@
+/** azureOpenaiAdapter — Azure OpenAI deployment-based chat completions. */
+import { ConfigurationError } from '../errors.js';
+import { TokenUsage } from '../types.js';
+import { BaseProviderAdapter } from './base.js';
+import { postJson } from './http.js';
+const DEFAULT_API_VERSION = '2024-06-01';
+class AzureOpenAIAdapter extends BaseProviderAdapter {
+    apiKey;
+    endpoint;
+    deployment;
+    apiVersion;
+    timeoutSeconds;
+    constructor(options = {}) {
+        super(options.pricing);
+        this.apiKey = options.apiKey ?? process.env['AZURE_OPENAI_API_KEY'];
+        this.endpoint = (options.endpoint ?? process.env['AZURE_OPENAI_ENDPOINT'] ?? '').replace(/\/+$/, '');
+        this.deployment = options.deployment ?? process.env['AZURE_OPENAI_DEPLOYMENT'];
+        this.apiVersion = options.apiVersion ?? DEFAULT_API_VERSION;
+        this.timeoutSeconds = (options.timeoutMs ?? 30_000) / 1000;
+    }
+    get providerName() {
+        return 'azure_openai';
+    }
+    url(request) {
+        const deployment = this.deployment ?? request.model;
+        return `${this.endpoint}/openai/deployments/${deployment}/chat/completions?api-version=${this.apiVersion}`;
+    }
+    async complete(request) {
+        if (!this.apiKey || !this.endpoint) {
+            throw new ConfigurationError('AZURE_OPENAI_API_KEY and AZURE_OPENAI_ENDPOINT must be set');
+        }
+        const started = performance.now();
+        const payload = {
+            messages: request.messages,
+            temperature: request.temperature,
+            max_tokens: request.maxTokens,
+        };
+        const data = await postJson(this.url(request), payload, { 'api-key': this.apiKey }, this.timeoutSeconds);
+        const choices = data['choices'] ?? [];
+        const message = choices[0]?.['message'] ?? {};
+        const content = message['content'] ?? '';
+        const usageData = data['usage'] ?? {};
+        const usage = new TokenUsage(usageData['prompt_tokens'] ?? 0, usageData['completion_tokens'] ?? 0);
+        return this.buildResponse(request, content, usage, data['model'] ?? request.model, started);
+    }
+    async healthCheck() {
+        return !!(this.apiKey && this.endpoint);
+    }
+}
+/** Factory: build an Azure OpenAI provider adapter. */
+export function azureOpenaiAdapter(options = {}) {
+    return new AzureOpenAIAdapter(options);
+}

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/providers/gemini.d.ts

@@ -0,0 +1,36 @@
+/** geminiAdapter — Google Generative Language API (generateContent). */
+import type { PricingProvider } from '../pricing.js';
+import type { GavioRequest } from '../request.js';
+import type { GavioResponse } from '../response.js';
+import { type Message } from '../types.js';
+import { BaseProviderAdapter } from './base.js';
+export interface GeminiAdapterOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    pricing?: PricingProvider;
+}
+interface GeminiContent {
+    role: string;
+    parts: {
+        text: string;
+    }[];
+}
+/** Map Gavio messages to Gemini contents + a system instruction. */
+export declare function geminiToContents(messages: Message[]): {
+    system: string | null;
+    contents: GeminiContent[];
+};
+declare class GeminiAdapter extends BaseProviderAdapter {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutSeconds;
+    constructor(options?: GeminiAdapterOptions);
+    get providerName(): string;
+    private payload;
+    complete(request: GavioRequest): Promise<GavioResponse>;
+    healthCheck(): Promise<boolean>;
+}
+/** Factory: build a Gemini provider adapter. */
+export declare function geminiAdapter(options?: GeminiAdapterOptions): GeminiAdapter;
+export {};

package/dist/esm/providers/gemini.js

@@ -0,0 +1,69 @@
+/** geminiAdapter — Google Generative Language API (generateContent). */
+import { ConfigurationError } from '../errors.js';
+import { TokenUsage } from '../types.js';
+import { BaseProviderAdapter } from './base.js';
+import { postJson } from './http.js';
+const DEFAULT_BASE_URL = 'https://generativelanguage.googleapis.com/v1beta';
+/** Map Gavio messages to Gemini contents + a system instruction. */
+export function geminiToContents(messages) {
+    let system = null;
+    const contents = [];
+    for (const m of messages) {
+        const text = m.content;
+        if (m.role === 'system') {
+            system = system ? `${system}\n${text}` : text;
+            continue;
+        }
+        contents.push({ role: m.role === 'assistant' ? 'model' : 'user', parts: [{ text }] });
+    }
+    return { system, contents };
+}
+class GeminiAdapter extends BaseProviderAdapter {
+    apiKey;
+    baseUrl;
+    timeoutSeconds;
+    constructor(options = {}) {
+        super(options.pricing);
+        this.apiKey =
+            options.apiKey ?? process.env['GEMINI_API_KEY'] ?? process.env['GOOGLE_API_KEY'];
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.timeoutSeconds = (options.timeoutMs ?? 30_000) / 1000;
+    }
+    get providerName() {
+        return 'gemini';
+    }
+    payload(request) {
+        const { system, contents } = geminiToContents(request.messages);
+        const payload = {
+            contents,
+            generationConfig: {
+                temperature: request.temperature,
+                maxOutputTokens: request.maxTokens,
+            },
+        };
+        if (system)
+            payload['systemInstruction'] = { parts: [{ text: system }] };
+        return payload;
+    }
+    async complete(request) {
+        if (!this.apiKey)
+            throw new ConfigurationError('GEMINI_API_KEY not set');
+        const started = performance.now();
+        const url = `${this.baseUrl}/models/${request.model}:generateContent?key=${this.apiKey}`;
+        const data = await postJson(url, this.payload(request), {}, this.timeoutSeconds);
+        const candidates = data['candidates'] ?? [{}];
+        const contentObj = candidates[0]?.['content'] ?? {};
+        const parts = contentObj['parts'] ?? [];
+        const content = parts.map((p) => p.text ?? '').join('');
+        const um = data['usageMetadata'] ?? {};
+        const usage = new TokenUsage(um['promptTokenCount'] ?? 0, um['candidatesTokenCount'] ?? 0);
+        return this.buildResponse(request, content, usage, request.model, started);
+    }
+    async healthCheck() {
+        return !!this.apiKey;
+    }
+}
+/** Factory: build a Gemini provider adapter. */
+export function geminiAdapter(options = {}) {
+    return new GeminiAdapter(options);
+}

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

@@ -10,6 +10,12 @@ export { openaiAdapter } from './openai.js';
 export type { OpenAIAdapterOptions } from './openai.js';
 export { anthropicAdapter } from './anthropic.js';
 export type { AnthropicAdapterOptions } from './anthropic.js';
+export { geminiAdapter } from './gemini.js';
+export type { GeminiAdapterOptions } from './gemini.js';
+export { azureOpenaiAdapter } from './azure-openai.js';
+export type { AzureOpenAIAdapterOptions } from './azure-openai.js';
+export { ollamaAdapter } from './ollama.js';
+export type { OllamaAdapterOptions } from './ollama.js';
 export { Provider } from '../types.js';
-/** Instantiate the default adapter for a provider id. v0.1.0: OpenAI, Anthropic, Mock. */
+/** Instantiate the default adapter for a provider id. */
 export declare function buildAdapter(provider: Provider | string, pricing?: PricingProvider): ProviderAdapter;

package/dist/esm/providers/index.js

@@ -2,24 +2,37 @@
 import { ConfigurationError } from '../errors.js';
 import { Provider, coerceProvider } from '../types.js';
 import { anthropicAdapter } from './anthropic.js';
+import { azureOpenaiAdapter } from './azure-openai.js';
+import { geminiAdapter } from './gemini.js';
 import { mockProvider } from './mock.js';
+import { ollamaAdapter } from './ollama.js';
 import { openaiAdapter } from './openai.js';
 export { BaseProviderAdapter } from './base.js';
 export { mockProvider } from './mock.js';
 export { openaiAdapter } from './openai.js';
 export { anthropicAdapter } from './anthropic.js';
+export { geminiAdapter } from './gemini.js';
+export { azureOpenaiAdapter } from './azure-openai.js';
+export { ollamaAdapter } from './ollama.js';
 export { Provider } from '../types.js';
-/** Instantiate the default adapter for a provider id. v0.1.0: OpenAI, Anthropic, Mock. */
+/** Instantiate the default adapter for a provider id. */
 export function buildAdapter(provider, pricing) {
     const p = coerceProvider(provider);
+    const opts = pricing ? { pricing } : {};
     switch (p) {
         case Provider.OPENAI:
-            return openaiAdapter(pricing ? { pricing } : {});
+            return openaiAdapter(opts);
         case Provider.ANTHROPIC:
-            return anthropicAdapter(pricing ? { pricing } : {});
+            return anthropicAdapter(opts);
+        case Provider.GEMINI:
+            return geminiAdapter(opts);
+        case Provider.AZURE_OPENAI:
+            return azureOpenaiAdapter(opts);
+        case Provider.OLLAMA:
+            return ollamaAdapter(opts);
         case Provider.MOCK:
-            return mockProvider(pricing ? { pricing } : {});
+            return mockProvider(opts);
         default:
-            throw new ConfigurationError(`Provider '${p}' is not available in v0.1.0 (available: openai, anthropic, mock)`);
+            throw new ConfigurationError(`Provider '${p}' is not available (v0.3.0 adds bedrock, cohere)`);
     }
 }

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

@@ -0,0 +1,21 @@
+/** ollamaAdapter — local models via the Ollama chat API. */
+import type { PricingProvider } from '../pricing.js';
+import type { GavioRequest } from '../request.js';
+import type { GavioResponse } from '../response.js';
+import { BaseProviderAdapter } from './base.js';
+export interface OllamaAdapterOptions {
+    baseUrl?: string;
+    timeoutMs?: number;
+    pricing?: PricingProvider;
+}
+declare class OllamaAdapter extends BaseProviderAdapter {
+    private readonly baseUrl;
+    private readonly timeoutSeconds;
+    constructor(options?: OllamaAdapterOptions);
+    get providerName(): string;
+    complete(request: GavioRequest): Promise<GavioResponse>;
+    healthCheck(): Promise<boolean>;
+}
+/** Factory: build an Ollama provider adapter. */
+export declare function ollamaAdapter(options?: OllamaAdapterOptions): OllamaAdapter;
+export {};

package/dist/esm/providers/ollama.js

@@ -0,0 +1,38 @@
+/** ollamaAdapter — local models via the Ollama chat API. */
+import { TokenUsage } from '../types.js';
+import { BaseProviderAdapter } from './base.js';
+import { postJson } from './http.js';
+const DEFAULT_BASE_URL = 'http://localhost:11434';
+class OllamaAdapter extends BaseProviderAdapter {
+    baseUrl;
+    timeoutSeconds;
+    constructor(options = {}) {
+        super(options.pricing);
+        this.baseUrl = (options.baseUrl ?? process.env['OLLAMA_HOST'] ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.timeoutSeconds = (options.timeoutMs ?? 60_000) / 1000;
+    }
+    get providerName() {
+        return 'ollama';
+    }
+    async complete(request) {
+        const started = performance.now();
+        const payload = {
+            model: request.model,
+            messages: request.messages,
+            stream: false,
+            options: { temperature: request.temperature },
+        };
+        const data = await postJson(`${this.baseUrl}/api/chat`, payload, {}, this.timeoutSeconds);
+        const message = data['message'] ?? {};
+        const content = message['content'] ?? '';
+        const usage = new TokenUsage(data['prompt_eval_count'] ?? 0, data['eval_count'] ?? 0);
+        return this.buildResponse(request, content, usage, data['model'] ?? request.model, started);
+    }
+    async healthCheck() {
+        return true;
+    }
+}
+/** Factory: build an Ollama provider adapter. */
+export function ollamaAdapter(options = {}) {
+    return new OllamaAdapter(options);
+}

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/shim/openai.d.ts

@@ -0,0 +1,56 @@
+/**
+ * OpenAI drop-in shim (F-DX-04) — point existing OpenAI SDK code at Gavio.
+ *
+ *   import { Gateway } from 'gavio'
+ *   import { GavioOpenAI } from 'gavio/shim/openai'
+ *
+ *   const client = new GavioOpenAI(new Gateway({ provider: 'openai', model: 'gpt-4o' }))
+ *   const resp = await client.chat.completions.create({
+ *     model: 'gpt-4o', messages: [{ role: 'user', content: 'hi' }],
+ *   })
+ *   console.log(resp.choices[0].message.content)
+ */
+import type { Gateway } from '../gateway.js';
+import type { Message } from '../types.js';
+export interface ChatCompletion {
+    id: string;
+    object: 'chat.completion';
+    model: string;
+    choices: {
+        index: number;
+        message: {
+            role: string;
+            content: string;
+        };
+        finish_reason: string;
+    }[];
+    usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+    gavio: {
+        costUsd: number;
+        cacheHit: boolean;
+        interceptorsFired: string[];
+    };
+}
+export interface CreateParams {
+    messages: Message[];
+    model?: string;
+    temperature?: number;
+    max_tokens?: number;
+}
+declare class Completions {
+    private readonly gw;
+    constructor(gw: Gateway);
+    create(params: CreateParams): Promise<ChatCompletion>;
+}
+/** OpenAI-client-shaped facade over a Gavio Gateway. */
+export declare class GavioOpenAI {
+    readonly chat: {
+        completions: Completions;
+    };
+    constructor(gateway: Gateway);
+}
+export {};

package/dist/esm/shim/openai.js

@@ -0,0 +1,53 @@
+/**
+ * OpenAI drop-in shim (F-DX-04) — point existing OpenAI SDK code at Gavio.
+ *
+ *   import { Gateway } from 'gavio'
+ *   import { GavioOpenAI } from 'gavio/shim/openai'
+ *
+ *   const client = new GavioOpenAI(new Gateway({ provider: 'openai', model: 'gpt-4o' }))
+ *   const resp = await client.chat.completions.create({
+ *     model: 'gpt-4o', messages: [{ role: 'user', content: 'hi' }],
+ *   })
+ *   console.log(resp.choices[0].message.content)
+ */
+function toCompletion(resp) {
+    return {
+        id: resp.traceId,
+        object: 'chat.completion',
+        model: resp.modelVersion || resp.model,
+        choices: [
+            { index: 0, message: { role: 'assistant', content: resp.content }, finish_reason: 'stop' },
+        ],
+        usage: {
+            prompt_tokens: resp.usage.promptTokens,
+            completion_tokens: resp.usage.completionTokens,
+            total_tokens: resp.usage.totalTokens,
+        },
+        gavio: {
+            costUsd: resp.costUsd,
+            cacheHit: resp.cacheHit,
+            interceptorsFired: resp.interceptorsFired,
+        },
+    };
+}
+class Completions {
+    gw;
+    constructor(gw) {
+        this.gw = gw;
+    }
+    async create(params) {
+        const resp = await this.gw.complete({
+            messages: params.messages,
+            model: params.model,
+            options: { temperature: params.temperature ?? 0.7, maxTokens: params.max_tokens ?? 1024 },
+        });
+        return toCompletion(resp);
+    }
+}
+/** OpenAI-client-shaped facade over a Gavio Gateway. */
+export class GavioOpenAI {
+    chat;
+    constructor(gateway) {
+        this.chat = { completions: new Completions(gateway) };
+    }
+}

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;
+        }>;
+    };
+}