gavio 0.1.0

package/dist/cjs/providers/mock.js

@@ -0,0 +1,54 @@
+"use strict";
+/** mockProvider — deterministic, offline provider for dev mode and tests. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mockProvider = mockProvider;
+const pricing_js_1 = require("../pricing.js");
+const types_js_1 = require("../types.js");
+const base_js_1 = require("./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 base_js_1.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 types_js_1.TokenUsage((0, pricing_js_1.estimateTokens)(request.promptText()), (0, pricing_js_1.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. */
+function mockProvider(options = {}) {
+    return new MockProvider(options);
+}

package/dist/cjs/providers/openai.js

@@ -0,0 +1,63 @@
+"use strict";
+/** openaiAdapter — Chat Completions API (GPT-4o, o1, ...). */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openaiAdapter = openaiAdapter;
+const errors_js_1 = require("../errors.js");
+const types_js_1 = require("../types.js");
+const base_js_1 = require("./base.js");
+const http_js_1 = require("./http.js");
+const DEFAULT_BASE_URL = 'https://api.openai.com/v1';
+class OpenAIAdapter extends base_js_1.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 errors_js_1.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 (0, http_js_1.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 types_js_1.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. */
+function openaiAdapter(options = {}) {
+    return new OpenAIAdapter(options);
+}

package/dist/cjs/request.js

@@ -0,0 +1,60 @@
+"use strict";
+/** GavioRequest — the canonical, provider-agnostic request model. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GavioRequest = void 0;
+const ids_js_1 = require("./ids.js");
+const types_js_1 = require("./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.
+ */
+class GavioRequest {
+    messages;
+    model;
+    provider;
+    traceId;
+    agentId;
+    parentTraceId;
+    sessionId;
+    options;
+    metadata;
+    constructor(init) {
+        this.messages = init.messages;
+        this.model = init.model;
+        this.provider = (0, types_js_1.coerceProvider)(init.provider);
+        this.traceId = init.traceId ?? (0, ids_js_1.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 },
+        });
+    }
+}
+exports.GavioRequest = GavioRequest;

package/dist/cjs/response.js

@@ -0,0 +1,55 @@
+"use strict";
+/** GavioResponse — the canonical response returned to the caller. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GavioResponse = void 0;
+const types_js_1 = require("./types.js");
+/** Result of a gateway call, enriched by the post-interceptor pipeline. */
+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 types_js_1.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 },
+        });
+    }
+}
+exports.GavioResponse = GavioResponse;

package/dist/cjs/testing/harness.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GavioTestKit = void 0;
+const context_js_1 = require("../context.js");
+const base_js_1 = require("../interceptors/base.js");
+const chain_js_1 = require("../interceptors/chain.js");
+const mock_js_1 = require("../providers/mock.js");
+const request_js_1 = require("../request.js");
+const types_js_1 = require("../types.js");
+/** Records the request as it reaches the provider (post-redaction). */
+class CaptureInterceptor {
+    name = '_capture';
+    captured = null;
+    before(request) {
+        this.captured = request;
+        return request;
+    }
+}
+class GavioTestKit {
+    interceptors;
+    provider;
+    model;
+    constructor(options = {}) {
+        this.interceptors = [...(options.interceptors ?? [])];
+        this.provider = options.provider ?? (0, mock_js_1.mockProvider)();
+        this.model = options.model ?? 'mock';
+    }
+    async run(input) {
+        const request = new request_js_1.GavioRequest({
+            messages: input.messages,
+            model: this.model,
+            provider: (0, types_js_1.coerceProvider)(this.provider.providerName),
+            options: input.options ?? {},
+        });
+        const ctx = new context_js_1.InterceptorContext({ traceId: request.traceId });
+        const capture = new CaptureInterceptor();
+        const all = [...this.interceptors, capture];
+        const policies = all.filter(base_js_1.isExecutorPolicy);
+        const regular = all.filter((i) => !(0, base_js_1.isExecutorPolicy)(i));
+        const chain = new chain_js_1.InterceptorChain(regular);
+        let executor = (req) => this.provider.complete(req);
+        for (let i = policies.length - 1; i >= 0; i--) {
+            executor = wrap(policies[i], executor, ctx);
+        }
+        const response = await chain.execute(request, ctx, executor);
+        return {
+            response,
+            ctx,
+            preRequestText: () => capture.captured?.promptText() ?? '',
+            piiDetected: (entityType) => {
+                if (entityType === undefined)
+                    return ctx.piiEntityTypes.length > 0;
+                return ctx.piiEntityTypes.includes(entityType);
+            },
+            get auditRecord() {
+                return response.audit;
+            },
+        };
+    }
+}
+exports.GavioTestKit = GavioTestKit;
+function wrap(policy, inner, ctx) {
+    return (req) => policy.around(req, ctx, inner);
+}

package/dist/cjs/testing/index.js

@@ -0,0 +1,8 @@
+"use strict";
+/** Gavio test utilities. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mockProvider = exports.GavioTestKit = void 0;
+var harness_js_1 = require("./harness.js");
+Object.defineProperty(exports, "GavioTestKit", { enumerable: true, get: function () { return harness_js_1.GavioTestKit; } });
+var mock_js_1 = require("../providers/mock.js");
+Object.defineProperty(exports, "mockProvider", { enumerable: true, get: function () { return mock_js_1.mockProvider; } });

package/dist/cjs/types.js

@@ -0,0 +1,61 @@
+"use strict";
+/** Shared enums (as string unions / const objects) and utility types. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenUsage = exports.GuardrailOutcome = exports.Sensitivity = exports.PiiMode = exports.CacheType = exports.Provider = void 0;
+exports.coerceProvider = coerceProvider;
+/** Supported LLM providers. String-valued for easy config + logging. */
+exports.Provider = {
+    OPENAI: 'openai',
+    ANTHROPIC: 'anthropic',
+    GEMINI: 'gemini',
+    AZURE_OPENAI: 'azure_openai',
+    OLLAMA: 'ollama',
+    BEDROCK: 'bedrock',
+    COHERE: 'cohere',
+    MOCK: 'mock',
+};
+/** Accept either a known provider value or any string and normalise to lowercase. */
+function coerceProvider(value) {
+    return value.toLowerCase();
+}
+exports.CacheType = {
+    EXACT: 'exact',
+    SEMANTIC: 'semantic',
+};
+/** What PiiGuard does with a detected entity. */
+exports.PiiMode = {
+    REDACT: 'redact', // replace with a typed placeholder token
+    MASK: 'mask', // replace characters with asterisks
+    TAG: 'tag', // annotate inline but keep the value
+    BLOCK: 'block', // raise and refuse the request
+};
+exports.Sensitivity = {
+    STRICT: 'strict',
+    BALANCED: 'balanced',
+    PERMISSIVE: 'permissive',
+};
+exports.GuardrailOutcome = {
+    PASS: 'PASS',
+    FAIL: 'FAIL',
+    HITL: 'HITL',
+};
+/** Token accounting for a single completion. */
+class TokenUsage {
+    promptTokens;
+    completionTokens;
+    constructor(promptTokens = 0, completionTokens = 0) {
+        this.promptTokens = promptTokens;
+        this.completionTokens = completionTokens;
+    }
+    get totalTokens() {
+        return this.promptTokens + this.completionTokens;
+    }
+    toJSON() {
+        return {
+            promptTokens: this.promptTokens,
+            completionTokens: this.completionTokens,
+            totalTokens: this.totalTokens,
+        };
+    }
+}
+exports.TokenUsage = TokenUsage;

package/dist/esm/context.d.ts

@@ -0,0 +1,33 @@
+/** Per-request context passed through the interceptor pipeline. */
+export interface InterceptorContextInit {
+    traceId: string;
+    agentId?: string | null;
+    parentTraceId?: string | null;
+    sessionId?: string | null;
+    dryRun?: boolean;
+}
+/**
+ * Mutable scratch space shared by all interceptors within one request. One
+ * instance per request — never shared across requests. Interceptors stash
+ * signals here (PII findings, cache decisions, risk scores) for the audit
+ * interceptor to collect at the end of the chain.
+ */
+export declare class InterceptorContext {
+    traceId: string;
+    agentId: string | null;
+    parentTraceId: string | null;
+    sessionId: string | null;
+    dryRun: boolean;
+    interceptorsFired: string[];
+    piiEntityTypes: string[];
+    piiEntityCounts: Record<string, number>;
+    cacheHit: boolean;
+    cacheType: string | null;
+    riskScore: number | null;
+    guardrailOutcome: string | null;
+    /** Arbitrary inter-interceptor state (e.g. PII replacement map for restore). */
+    state: Record<string, unknown>;
+    constructor(init: InterceptorContextInit);
+    markFired(name: string): void;
+    recordPii(entityTypes: string[]): void;
+}

package/dist/esm/context.js

@@ -0,0 +1,43 @@
+/** Per-request context passed through the interceptor pipeline. */
+/**
+ * Mutable scratch space shared by all interceptors within one request. One
+ * instance per request — never shared across requests. Interceptors stash
+ * signals here (PII findings, cache decisions, risk scores) for the audit
+ * interceptor to collect at the end of the chain.
+ */
+export class InterceptorContext {
+    traceId;
+    agentId;
+    parentTraceId;
+    sessionId;
+    dryRun;
+    interceptorsFired = [];
+    piiEntityTypes = [];
+    piiEntityCounts = {};
+    cacheHit = false;
+    cacheType = null;
+    riskScore = null;
+    guardrailOutcome = null;
+    /** Arbitrary inter-interceptor state (e.g. PII replacement map for restore). */
+    state = {};
+    constructor(init) {
+        this.traceId = init.traceId;
+        this.agentId = init.agentId ?? null;
+        this.parentTraceId = init.parentTraceId ?? null;
+        this.sessionId = init.sessionId ?? null;
+        this.dryRun = init.dryRun ?? false;
+    }
+    markFired(name) {
+        if (!this.interceptorsFired.includes(name)) {
+            this.interceptorsFired.push(name);
+        }
+    }
+    recordPii(entityTypes) {
+        for (const et of entityTypes) {
+            this.piiEntityCounts[et] = (this.piiEntityCounts[et] ?? 0) + 1;
+            if (!this.piiEntityTypes.includes(et)) {
+                this.piiEntityTypes.push(et);
+            }
+        }
+    }
+}

package/dist/esm/errors.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Gavio error hierarchy. All Gavio errors derive from {@link GavioError} so
+ * callers can catch the whole family with a single check.
+ */
+export declare class GavioError extends Error {
+    constructor(message?: string);
+}
+/** Raised when the gateway is misconfigured (e.g. no provider set). */
+export declare class ConfigurationError extends GavioError {
+}
+/** Base class for provider-adapter failures. */
+export declare class ProviderError extends GavioError {
+}
+/** The provider could not be reached (network / health-check failure). */
+export declare class ProviderUnavailableError extends ProviderError {
+}
+/** The provider returned a rate-limit (HTTP 429) signal. */
+export declare class RateLimitError extends ProviderError {
+}
+/** The provider returned a 5xx server error. */
+export declare class ServerError extends ProviderError {
+}
+/** A request exceeded its configured timeout. */
+export declare class TimeoutError extends ProviderError {
+}
+/** PiiGuard is in BLOCK mode and detected PII in the request. */
+export declare class PiiBlockedError extends GavioError {
+    readonly entityTypes: string[];
+    constructor(entityTypes: string[]);
+}
+/** A hard budget cap was exceeded. Never swallow this — surface to user. */
+export declare class BudgetExceededError extends GavioError {
+}
+/** Output failed a guardrail validator with onFailure='error'. */
+export declare class GuardrailViolationError extends GavioError {
+}

package/dist/esm/errors.js

@@ -0,0 +1,44 @@
+/**
+ * Gavio error hierarchy. All Gavio errors derive from {@link GavioError} so
+ * callers can catch the whole family with a single check.
+ */
+export class GavioError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** Raised when the gateway is misconfigured (e.g. no provider set). */
+export class ConfigurationError extends GavioError {
+}
+/** Base class for provider-adapter failures. */
+export class ProviderError extends GavioError {
+}
+/** The provider could not be reached (network / health-check failure). */
+export class ProviderUnavailableError extends ProviderError {
+}
+/** The provider returned a rate-limit (HTTP 429) signal. */
+export class RateLimitError extends ProviderError {
+}
+/** The provider returned a 5xx server error. */
+export class ServerError extends ProviderError {
+}
+/** A request exceeded its configured timeout. */
+export class TimeoutError extends ProviderError {
+}
+/** PiiGuard is in BLOCK mode and detected PII in the request. */
+export class PiiBlockedError extends GavioError {
+    entityTypes;
+    constructor(entityTypes) {
+        const sorted = Array.from(new Set(entityTypes)).sort();
+        super(`Request blocked: PII detected (${sorted.join(', ')})`);
+        this.entityTypes = entityTypes;
+    }
+}
+/** A hard budget cap was exceeded. Never swallow this — surface to user. */
+export class BudgetExceededError extends GavioError {
+}
+/** Output failed a guardrail validator with onFailure='error'. */
+export class GuardrailViolationError extends GavioError {
+}

package/dist/esm/gateway.d.ts

@@ -0,0 +1,54 @@
+/** Gateway — the entry point. Wires interceptors around a provider adapter. */
+import type { Interceptor } from './interceptors/base.js';
+import { PricingProvider } from './pricing.js';
+import type { ProviderAdapter } from './providers/base.js';
+import type { GavioResponse } from './response.js';
+import { Provider } from './types.js';
+import type { Message } from './types.js';
+export interface GatewayOptions {
+    provider?: Provider | string;
+    model?: string;
+    adapter?: ProviderAdapter;
+    devMode?: boolean;
+    dryRun?: boolean;
+    pricing?: PricingProvider;
+}
+export interface CompleteOptions {
+    messages: Message[];
+    model?: string;
+    agentId?: string | null;
+    parentTraceId?: string | null;
+    sessionId?: string | null;
+    metadata?: Record<string, unknown>;
+    /** Provider sampling options (temperature, maxTokens, etc.). */
+    options?: Record<string, unknown>;
+}
+/**
+ * Routes a request through the interceptor pipeline to a provider.
+ *
+ * Construct with `new Gateway({ provider, model })` then chain `.use(...)` and
+ * `.withAdapter(...)`. A single instance is safe to reuse — per-request state
+ * lives in an {@link InterceptorContext} created fresh for every call.
+ */
+export declare class Gateway {
+    private readonly providerHint;
+    private modelHint;
+    private adapterOverride;
+    private readonly devMode;
+    private readonly dryRunMode;
+    private readonly pricing;
+    private readonly interceptors;
+    constructor(options?: GatewayOptions);
+    /** Register an interceptor or executor policy. First-registered = outermost. */
+    use(interceptor: Interceptor): this;
+    /** Supply a provider adapter explicitly (overrides `provider`). */
+    withAdapter(adapter: ProviderAdapter): this;
+    get model(): string;
+    get providerName(): string;
+    complete(opts: CompleteOptions): Promise<GavioResponse>;
+    healthCheck(): Promise<boolean>;
+    private buildPipeline;
+    private wrapPolicy;
+    private resolveAdapter;
+    private resolveModel;
+}