gavio 0.1.0

package/dist/esm/providers/anthropic.js

@@ -0,0 +1,77 @@
+/** anthropicAdapter — Messages API (Claude Sonnet, Haiku, Opus). */
+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://api.anthropic.com/v1';
+const API_VERSION = '2023-06-01';
+/**
+ * Talks to the Anthropic Messages endpoint. Anthropic splits the system prompt
+ * from the message list, so any `role === "system"` messages are extracted into
+ * the `system` field.
+ */
+class AnthropicAdapter extends BaseProviderAdapter {
+    apiKey;
+    baseUrl;
+    timeoutSeconds;
+    constructor(options = {}) {
+        super(options.pricing);
+        this.apiKey = options.apiKey ?? process.env['ANTHROPIC_API_KEY'];
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.timeoutSeconds = (options.timeoutMs ?? 30_000) / 1000;
+    }
+    get providerName() {
+        return 'anthropic';
+    }
+    headers() {
+        if (!this.apiKey) {
+            throw new ConfigurationError('ANTHROPIC_API_KEY not set (pass apiKey or set the env var)');
+        }
+        return {
+            'x-api-key': this.apiKey,
+            'anthropic-version': API_VERSION,
+        };
+    }
+    static splitSystem(messages) {
+        const systemParts = messages
+            .filter((m) => m.role === 'system')
+            .map((m) => m.content);
+        const chat = messages.filter((m) => m.role !== 'system');
+        const system = systemParts.length > 0 ? systemParts.join('\n') : null;
+        return [system, chat];
+    }
+    async complete(request) {
+        const started = performance.now();
+        const [system, chat] = AnthropicAdapter.splitSystem(request.messages);
+        const payload = {
+            model: request.model,
+            messages: chat,
+            max_tokens: request.maxTokens,
+            temperature: request.temperature,
+        };
+        if (system)
+            payload['system'] = system;
+        const data = await postJson(`${this.baseUrl}/messages`, payload, this.headers(), this.timeoutSeconds);
+        const blocks = data['content'] ?? [];
+        const content = blocks
+            .filter((b) => b['type'] === 'text')
+            .map((b) => b['text'] ?? '')
+            .join('');
+        const usageData = data['usage'] ?? {};
+        const usage = new TokenUsage(usageData['input_tokens'] ?? 0, usageData['output_tokens'] ?? 0);
+        return this.buildResponse(request, content, usage, data['model'] ?? request.model, started);
+    }
+    async healthCheck() {
+        try {
+            this.headers();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+/** Factory: build an Anthropic provider adapter. */
+export function anthropicAdapter(options = {}) {
+    return new AnthropicAdapter(options);
+}

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

@@ -0,0 +1,23 @@
+/** ProviderAdapter interface and shared response-building helpers. */
+import { PricingProvider } from '../pricing.js';
+import { GavioRequest } from '../request.js';
+import { GavioResponse } from '../response.js';
+import { TokenUsage } from '../types.js';
+/** Adapter to one LLM provider. */
+export interface ProviderAdapter {
+    readonly providerName: string;
+    complete(request: GavioRequest): Promise<GavioResponse>;
+    stream?(request: GavioRequest): AsyncIterable<string>;
+    healthCheck(): Promise<boolean>;
+    readonly reportedModelVersion?: string | null;
+}
+/** Base class with a shared pricing provider and response builder. */
+export declare abstract class BaseProviderAdapter implements ProviderAdapter {
+    protected readonly pricing: PricingProvider;
+    constructor(pricing?: PricingProvider);
+    abstract get providerName(): string;
+    abstract complete(request: GavioRequest): Promise<GavioResponse>;
+    abstract healthCheck(): Promise<boolean>;
+    get reportedModelVersion(): string | null;
+    protected buildResponse(request: GavioRequest, content: string, usage: TokenUsage, modelVersion: string, startedAt: number): GavioResponse;
+}

package/dist/esm/providers/base.js

@@ -0,0 +1,28 @@
+/** ProviderAdapter interface and shared response-building helpers. */
+import { PricingProvider } from '../pricing.js';
+import { GavioRequest } from '../request.js';
+import { GavioResponse } from '../response.js';
+import { TokenUsage } from '../types.js';
+/** Base class with a shared pricing provider and response builder. */
+export class BaseProviderAdapter {
+    pricing;
+    constructor(pricing) {
+        this.pricing = pricing ?? new PricingProvider();
+    }
+    get reportedModelVersion() {
+        return null;
+    }
+    buildResponse(request, content, usage, modelVersion, startedAt) {
+        const latencyMs = Math.floor(performance.now() - startedAt);
+        return new GavioResponse({
+            traceId: request.traceId,
+            content,
+            model: request.model,
+            provider: this.providerName,
+            modelVersion: modelVersion || request.model,
+            usage,
+            costUsd: this.pricing.estimate(request.model, usage),
+            latencyMs,
+        });
+    }
+}

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

@@ -0,0 +1,8 @@
+/** Tiny JSON-over-HTTP helper built on native fetch (keeps core dependency-free). */
+/**
+ * POST `payload` as JSON and return the parsed response.
+ *
+ * Maps HTTP status families onto Gavio's transient error types so the
+ * retry/fallback policies can react.
+ */
+export declare function postJson(url: string, payload: unknown, headers: Record<string, string>, timeoutSeconds?: number): Promise<Record<string, unknown>>;

package/dist/esm/providers/http.js

@@ -0,0 +1,39 @@
+/** Tiny JSON-over-HTTP helper built on native fetch (keeps core dependency-free). */
+import { ProviderUnavailableError, RateLimitError, ServerError, } from '../errors.js';
+/**
+ * POST `payload` as JSON and return the parsed response.
+ *
+ * Maps HTTP status families onto Gavio's transient error types so the
+ * retry/fallback policies can react.
+ */
+export async function postJson(url, payload, headers, timeoutSeconds = 30.0) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutSeconds * 1000);
+    let resp;
+    try {
+        resp = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...headers },
+            body: JSON.stringify(payload),
+            signal: controller.signal,
+        });
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new ProviderUnavailableError(`network error: ${reason}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!resp.ok) {
+        const body = (await resp.text().catch(() => '')).slice(0, 200);
+        if (resp.status === 429) {
+            throw new RateLimitError(`429 from provider: ${body}`);
+        }
+        if (resp.status >= 500) {
+            throw new ServerError(`${resp.status} from provider: ${body}`);
+        }
+        throw new ProviderUnavailableError(`${resp.status} from provider: ${body}`);
+    }
+    return (await resp.json());
+}

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

@@ -0,0 +1,15 @@
+/** Provider adapters and the provider registry. */
+import type { PricingProvider } from '../pricing.js';
+import { Provider } from '../types.js';
+import type { ProviderAdapter } from './base.js';
+export type { ProviderAdapter } from './base.js';
+export { BaseProviderAdapter } from './base.js';
+export { mockProvider } from './mock.js';
+export type { MockProviderOptions } from './mock.js';
+export { openaiAdapter } from './openai.js';
+export type { OpenAIAdapterOptions } from './openai.js';
+export { anthropicAdapter } from './anthropic.js';
+export type { AnthropicAdapterOptions } from './anthropic.js';
+export { Provider } from '../types.js';
+/** Instantiate the default adapter for a provider id. v0.1.0: OpenAI, Anthropic, Mock. */
+export declare function buildAdapter(provider: Provider | string, pricing?: PricingProvider): ProviderAdapter;

package/dist/esm/providers/index.js

@@ -0,0 +1,25 @@
+/** Provider adapters and the provider registry. */
+import { ConfigurationError } from '../errors.js';
+import { Provider, coerceProvider } from '../types.js';
+import { anthropicAdapter } from './anthropic.js';
+import { mockProvider } from './mock.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 { Provider } from '../types.js';
+/** Instantiate the default adapter for a provider id. v0.1.0: OpenAI, Anthropic, Mock. */
+export function buildAdapter(provider, pricing) {
+    const p = coerceProvider(provider);
+    switch (p) {
+        case Provider.OPENAI:
+            return openaiAdapter(pricing ? { pricing } : {});
+        case Provider.ANTHROPIC:
+            return anthropicAdapter(pricing ? { pricing } : {});
+        case Provider.MOCK:
+            return mockProvider(pricing ? { pricing } : {});
+        default:
+            throw new ConfigurationError(`Provider '${p}' is not available in v0.1.0 (available: openai, anthropic, mock)`);
+    }
+}

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

@@ -0,0 +1,31 @@
+/** mockProvider — deterministic, offline provider for dev mode and tests. */
+import { PricingProvider } from '../pricing.js';
+import type { GavioRequest } from '../request.js';
+import type { GavioResponse } from '../response.js';
+import { BaseProviderAdapter } from './base.js';
+export interface MockProviderOptions {
+    response?: string | null;
+    modelVersion?: string;
+    pricing?: PricingProvider;
+}
+/**
+ * Returns a canned response without any network call.
+ *
+ * If `response` is null/undefined, it echoes the last user message so the
+ * pipeline (including PII restore) is observable end to end.
+ */
+declare class MockProvider extends BaseProviderAdapter {
+    private readonly response;
+    private readonly modelVersion;
+    constructor(options?: MockProviderOptions);
+    get providerName(): string;
+    get reportedModelVersion(): string | null;
+    private contentFor;
+    complete(request: GavioRequest): Promise<GavioResponse>;
+    stream(request: GavioRequest): AsyncIterable<string>;
+    healthCheck(): Promise<boolean>;
+}
+/** Factory: build a mock provider adapter. */
+export declare function mockProvider(options?: MockProviderOptions): ProviderAdapterMock;
+export type ProviderAdapterMock = MockProvider;
+export {};

package/dist/esm/providers/mock.js

@@ -0,0 +1,51 @@
+/** mockProvider — deterministic, offline provider for dev mode and tests. */
+import { PricingProvider, estimateTokens } from '../pricing.js';
+import { TokenUsage } from '../types.js';
+import { BaseProviderAdapter } from './base.js';
+/**
+ * Returns a canned response without any network call.
+ *
+ * If `response` is null/undefined, it echoes the last user message so the
+ * pipeline (including PII restore) is observable end to end.
+ */
+class MockProvider extends BaseProviderAdapter {
+    response;
+    modelVersion;
+    constructor(options = {}) {
+        super(options.pricing);
+        this.response = options.response ?? null;
+        this.modelVersion = options.modelVersion ?? 'mock-1';
+    }
+    get providerName() {
+        return 'mock';
+    }
+    get reportedModelVersion() {
+        return this.modelVersion;
+    }
+    contentFor(request) {
+        if (this.response !== null)
+            return this.response;
+        const lastUser = [...request.messages]
+            .reverse()
+            .find((m) => m.role === 'user');
+        return `[mock reply] ${lastUser?.content ?? ''}`;
+    }
+    async complete(request) {
+        const started = performance.now();
+        const content = this.contentFor(request);
+        const usage = new TokenUsage(estimateTokens(request.promptText()), estimateTokens(content));
+        return this.buildResponse(request, content, usage, this.modelVersion, started);
+    }
+    async *stream(request) {
+        for (const token of this.contentFor(request).split(' ')) {
+            yield token + ' ';
+        }
+    }
+    async healthCheck() {
+        return true;
+    }
+}
+/** Factory: build a mock provider adapter. */
+export function mockProvider(options = {}) {
+    return new MockProvider(options);
+}

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

@@ -0,0 +1,26 @@
+/** openaiAdapter — Chat Completions API (GPT-4o, o1, ...). */
+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 OpenAIAdapterOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    organization?: string;
+    pricing?: PricingProvider;
+}
+declare class OpenAIAdapter extends BaseProviderAdapter {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutSeconds;
+    private readonly organization;
+    constructor(options?: OpenAIAdapterOptions);
+    get providerName(): string;
+    private headers;
+    complete(request: GavioRequest): Promise<GavioResponse>;
+    healthCheck(): Promise<boolean>;
+}
+/** Factory: build an OpenAI provider adapter. */
+export declare function openaiAdapter(options?: OpenAIAdapterOptions): OpenAIAdapter;
+export {};

package/dist/esm/providers/openai.js

@@ -0,0 +1,60 @@
+/** openaiAdapter — Chat Completions API (GPT-4o, o1, ...). */
+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://api.openai.com/v1';
+class OpenAIAdapter extends BaseProviderAdapter {
+    apiKey;
+    baseUrl;
+    timeoutSeconds;
+    organization;
+    constructor(options = {}) {
+        super(options.pricing);
+        this.apiKey = options.apiKey ?? process.env['OPENAI_API_KEY'];
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.timeoutSeconds = (options.timeoutMs ?? 30_000) / 1000;
+        this.organization = options.organization;
+    }
+    get providerName() {
+        return 'openai';
+    }
+    headers() {
+        if (!this.apiKey) {
+            throw new ConfigurationError('OPENAI_API_KEY not set (pass apiKey or set the env var)');
+        }
+        const headers = { Authorization: `Bearer ${this.apiKey}` };
+        if (this.organization)
+            headers['OpenAI-Organization'] = this.organization;
+        return headers;
+    }
+    async complete(request) {
+        const started = performance.now();
+        const payload = {
+            model: request.model,
+            messages: request.messages,
+            temperature: request.temperature,
+            max_tokens: request.maxTokens,
+        };
+        const data = await postJson(`${this.baseUrl}/chat/completions`, payload, this.headers(), 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() {
+        try {
+            this.headers();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+/** Factory: build an OpenAI provider adapter. */
+export function openaiAdapter(options = {}) {
+    return new OpenAIAdapter(options);
+}

package/dist/esm/request.d.ts

@@ -0,0 +1,36 @@
+/** GavioRequest — the canonical, provider-agnostic request model. */
+import type { Message, Provider } from './types.js';
+export interface GavioRequestInit {
+    messages: Message[];
+    model: string;
+    provider: Provider | string;
+    traceId?: string;
+    agentId?: string | null;
+    parentTraceId?: string | null;
+    sessionId?: string | null;
+    options?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A single gateway call. A `traceId` (UUID v7, time-sortable) is assigned
+ * automatically if not supplied. `parentTraceId` links calls into a
+ * multi-agent DAG.
+ */
+export declare class GavioRequest {
+    messages: Message[];
+    model: string;
+    provider: Provider;
+    traceId: string;
+    agentId: string | null;
+    parentTraceId: string | null;
+    sessionId: string | null;
+    options: Record<string, unknown>;
+    metadata: Record<string, unknown>;
+    constructor(init: GavioRequestInit);
+    get temperature(): number;
+    get maxTokens(): number;
+    /** Concatenate message contents — used for hashing and token estimation. */
+    promptText(): string;
+    /** Return a shallow copy with replaced messages (interceptors mutate via this). */
+    copyWithMessages(messages: Message[]): GavioRequest;
+}

package/dist/esm/request.js

@@ -0,0 +1,56 @@
+/** GavioRequest — the canonical, provider-agnostic request model. */
+import { newTraceId } from './ids.js';
+import { coerceProvider } from './types.js';
+/**
+ * A single gateway call. A `traceId` (UUID v7, time-sortable) is assigned
+ * automatically if not supplied. `parentTraceId` links calls into a
+ * multi-agent DAG.
+ */
+export class GavioRequest {
+    messages;
+    model;
+    provider;
+    traceId;
+    agentId;
+    parentTraceId;
+    sessionId;
+    options;
+    metadata;
+    constructor(init) {
+        this.messages = init.messages;
+        this.model = init.model;
+        this.provider = coerceProvider(init.provider);
+        this.traceId = init.traceId ?? newTraceId();
+        this.agentId = init.agentId ?? null;
+        this.parentTraceId = init.parentTraceId ?? null;
+        this.sessionId = init.sessionId ?? null;
+        this.options = init.options ?? {};
+        this.metadata = init.metadata ?? {};
+    }
+    get temperature() {
+        const t = this.options['temperature'];
+        return typeof t === 'number' ? t : 0.7;
+    }
+    get maxTokens() {
+        const m = this.options['maxTokens'] ?? this.options['max_tokens'];
+        return typeof m === 'number' ? m : 1024;
+    }
+    /** Concatenate message contents — used for hashing and token estimation. */
+    promptText() {
+        return this.messages.map((m) => m.content ?? '').join('\n');
+    }
+    /** Return a shallow copy with replaced messages (interceptors mutate via this). */
+    copyWithMessages(messages) {
+        return new GavioRequest({
+            messages,
+            model: this.model,
+            provider: this.provider,
+            traceId: this.traceId,
+            agentId: this.agentId,
+            parentTraceId: this.parentTraceId,
+            sessionId: this.sessionId,
+            options: { ...this.options },
+            metadata: { ...this.metadata },
+        });
+    }
+}

package/dist/esm/response.d.ts

@@ -0,0 +1,38 @@
+/** GavioResponse — the canonical response returned to the caller. */
+import { TokenUsage } from './types.js';
+import type { CacheType } from './types.js';
+import type { AuditRecord } from './interceptors/audit/record.js';
+export interface GavioResponseInit {
+    traceId: string;
+    content: string;
+    model: string;
+    provider: string;
+    modelVersion?: string;
+    usage?: TokenUsage;
+    costUsd?: number;
+    latencyMs?: number;
+    cacheHit?: boolean;
+    cacheType?: CacheType | null;
+    interceptorsFired?: string[];
+    audit?: AuditRecord | null;
+    metadata?: Record<string, unknown>;
+}
+/** Result of a gateway call, enriched by the post-interceptor pipeline. */
+export declare class GavioResponse {
+    traceId: string;
+    content: string;
+    model: string;
+    provider: string;
+    modelVersion: string;
+    usage: TokenUsage;
+    costUsd: number;
+    latencyMs: number;
+    cacheHit: boolean;
+    cacheType: CacheType | null;
+    interceptorsFired: string[];
+    audit: AuditRecord | null;
+    metadata: Record<string, unknown>;
+    constructor(init: GavioResponseInit);
+    /** Return a copy with replaced content (used by PII restore, guardrails). */
+    copyWithContent(content: string): GavioResponse;
+}

package/dist/esm/response.js

@@ -0,0 +1,51 @@
+/** GavioResponse — the canonical response returned to the caller. */
+import { TokenUsage } from './types.js';
+/** Result of a gateway call, enriched by the post-interceptor pipeline. */
+export class GavioResponse {
+    traceId;
+    content;
+    model;
+    provider;
+    modelVersion;
+    usage;
+    costUsd;
+    latencyMs;
+    cacheHit;
+    cacheType;
+    interceptorsFired;
+    audit;
+    metadata;
+    constructor(init) {
+        this.traceId = init.traceId;
+        this.content = init.content;
+        this.model = init.model;
+        this.provider = init.provider;
+        this.modelVersion = init.modelVersion ?? '';
+        this.usage = init.usage ?? new TokenUsage();
+        this.costUsd = init.costUsd ?? 0.0;
+        this.latencyMs = init.latencyMs ?? 0;
+        this.cacheHit = init.cacheHit ?? false;
+        this.cacheType = init.cacheType ?? null;
+        this.interceptorsFired = init.interceptorsFired ?? [];
+        this.audit = init.audit ?? null;
+        this.metadata = init.metadata ?? {};
+    }
+    /** Return a copy with replaced content (used by PII restore, guardrails). */
+    copyWithContent(content) {
+        return new GavioResponse({
+            traceId: this.traceId,
+            content,
+            model: this.model,
+            provider: this.provider,
+            modelVersion: this.modelVersion,
+            usage: this.usage,
+            costUsd: this.costUsd,
+            latencyMs: this.latencyMs,
+            cacheHit: this.cacheHit,
+            cacheType: this.cacheType,
+            interceptorsFired: [...this.interceptorsFired],
+            audit: this.audit,
+            metadata: { ...this.metadata },
+        });
+    }
+}

package/dist/esm/testing/harness.d.ts

@@ -0,0 +1,37 @@
+/**
+ * GavioTestKit — run interceptor chains in isolation for unit tests.
+ *
+ * This v0.1.0 kit drives a chain against a {@link mockProvider} and lets you
+ * assert on PII detection, the redacted request, and the resulting audit record.
+ */
+import { InterceptorContext } from '../context.js';
+import type { Interceptor } from '../interceptors/base.js';
+import type { AuditRecord } from '../interceptors/audit/record.js';
+import type { ProviderAdapter } from '../providers/base.js';
+import type { GavioResponse } from '../response.js';
+import type { Message } from '../types.js';
+export interface GavioTestKitOptions {
+    interceptors?: Interceptor[];
+    provider?: ProviderAdapter;
+    model?: string;
+}
+export interface RunResult {
+    response: GavioResponse;
+    ctx: InterceptorContext;
+    /** The request text as it reached the provider (post-redaction). */
+    preRequestText(): string;
+    /** True if any (or a specific) PII entity type was detected. */
+    piiDetected(entityType?: string): boolean;
+    /** The audit record produced for this call, if an audit interceptor ran. */
+    readonly auditRecord: AuditRecord | null;
+}
+export declare class GavioTestKit {
+    private readonly interceptors;
+    private readonly provider;
+    private readonly model;
+    constructor(options?: GavioTestKitOptions);
+    run(input: {
+        messages: Message[];
+        options?: Record<string, unknown>;
+    }): Promise<RunResult>;
+}