gavio 0.1.0

package/dist/esm/testing/harness.js

@@ -0,0 +1,66 @@
+/**
+ * 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 { isExecutorPolicy } from '../interceptors/base.js';
+import { InterceptorChain } from '../interceptors/chain.js';
+import { mockProvider } from '../providers/mock.js';
+import { GavioRequest } from '../request.js';
+import { coerceProvider } from '../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;
+    }
+}
+export class GavioTestKit {
+    interceptors;
+    provider;
+    model;
+    constructor(options = {}) {
+        this.interceptors = [...(options.interceptors ?? [])];
+        this.provider = options.provider ?? mockProvider();
+        this.model = options.model ?? 'mock';
+    }
+    async run(input) {
+        const request = new GavioRequest({
+            messages: input.messages,
+            model: this.model,
+            provider: coerceProvider(this.provider.providerName),
+            options: input.options ?? {},
+        });
+        const ctx = new InterceptorContext({ traceId: request.traceId });
+        const capture = new CaptureInterceptor();
+        const all = [...this.interceptors, capture];
+        const policies = all.filter(isExecutorPolicy);
+        const regular = all.filter((i) => !isExecutorPolicy(i));
+        const chain = new 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;
+            },
+        };
+    }
+}
+function wrap(policy, inner, ctx) {
+    return (req) => policy.around(req, ctx, inner);
+}

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

@@ -0,0 +1,5 @@
+/** Gavio test utilities. */
+export { GavioTestKit } from './harness.js';
+export type { GavioTestKitOptions, RunResult } from './harness.js';
+export { mockProvider } from '../providers/mock.js';
+export type { MockProviderOptions } from '../providers/mock.js';

package/dist/esm/testing/index.js

@@ -0,0 +1,3 @@
+/** Gavio test utilities. */
+export { GavioTestKit } from './harness.js';
+export { mockProvider } from '../providers/mock.js';

package/dist/esm/types.d.ts

@@ -0,0 +1,58 @@
+/** Shared enums (as string unions / const objects) and utility types. */
+/** A provider-agnostic chat message. */
+export interface Message {
+    role: string;
+    content: string;
+    [key: string]: unknown;
+}
+/** Supported LLM providers. String-valued for easy config + logging. */
+export declare const Provider: {
+    readonly OPENAI: "openai";
+    readonly ANTHROPIC: "anthropic";
+    readonly GEMINI: "gemini";
+    readonly AZURE_OPENAI: "azure_openai";
+    readonly OLLAMA: "ollama";
+    readonly BEDROCK: "bedrock";
+    readonly COHERE: "cohere";
+    readonly MOCK: "mock";
+};
+export type Provider = (typeof Provider)[keyof typeof Provider];
+/** Accept either a known provider value or any string and normalise to lowercase. */
+export declare function coerceProvider(value: Provider | string): Provider;
+export declare const CacheType: {
+    readonly EXACT: "exact";
+    readonly SEMANTIC: "semantic";
+};
+export type CacheType = (typeof CacheType)[keyof typeof CacheType];
+/** What PiiGuard does with a detected entity. */
+export declare const PiiMode: {
+    readonly REDACT: "redact";
+    readonly MASK: "mask";
+    readonly TAG: "tag";
+    readonly BLOCK: "block";
+};
+export type PiiMode = (typeof PiiMode)[keyof typeof PiiMode];
+export declare const Sensitivity: {
+    readonly STRICT: "strict";
+    readonly BALANCED: "balanced";
+    readonly PERMISSIVE: "permissive";
+};
+export type Sensitivity = (typeof Sensitivity)[keyof typeof Sensitivity];
+export declare const GuardrailOutcome: {
+    readonly PASS: "PASS";
+    readonly FAIL: "FAIL";
+    readonly HITL: "HITL";
+};
+export type GuardrailOutcome = (typeof GuardrailOutcome)[keyof typeof GuardrailOutcome];
+/** Token accounting for a single completion. */
+export declare class TokenUsage {
+    readonly promptTokens: number;
+    readonly completionTokens: number;
+    constructor(promptTokens?: number, completionTokens?: number);
+    get totalTokens(): number;
+    toJSON(): {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}

package/dist/esm/types.js

@@ -0,0 +1,56 @@
+/** Shared enums (as string unions / const objects) and utility types. */
+/** Supported LLM providers. String-valued for easy config + logging. */
+export const 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. */
+export function coerceProvider(value) {
+    return value.toLowerCase();
+}
+export const CacheType = {
+    EXACT: 'exact',
+    SEMANTIC: 'semantic',
+};
+/** What PiiGuard does with a detected entity. */
+export const 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
+};
+export const Sensitivity = {
+    STRICT: 'strict',
+    BALANCED: 'balanced',
+    PERMISSIVE: 'permissive',
+};
+export const GuardrailOutcome = {
+    PASS: 'PASS',
+    FAIL: 'FAIL',
+    HITL: 'HITL',
+};
+/** Token accounting for a single completion. */
+export 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,
+        };
+    }
+}

package/package.json

@@ -0,0 +1,115 @@
+{
+  "name": "gavio",
+  "version": "0.1.0",
+  "description": "The open standard AI gateway for production systems — PII guarding, audit, reliability, and cost tracking.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/manojmallick/gavio.git",
+    "directory": "packages/gavio-js"
+  },
+  "bugs": {
+    "url": "https://github.com/manojmallick/gavio/issues"
+  },
+  "homepage": "https://github.com/manojmallick/gavio#readme",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    },
+    "./interceptors/pii": {
+      "types": "./dist/esm/interceptors/pii/index.d.ts",
+      "import": "./dist/esm/interceptors/pii/index.js",
+      "require": "./dist/cjs/interceptors/pii/index.js"
+    },
+    "./interceptors/pii/scanners": {
+      "types": "./dist/esm/interceptors/pii/scanners/index.d.ts",
+      "import": "./dist/esm/interceptors/pii/scanners/index.js",
+      "require": "./dist/cjs/interceptors/pii/scanners/index.js"
+    },
+    "./interceptors/audit": {
+      "types": "./dist/esm/interceptors/audit/index.d.ts",
+      "import": "./dist/esm/interceptors/audit/index.js",
+      "require": "./dist/cjs/interceptors/audit/index.js"
+    },
+    "./interceptors/audit/sinks": {
+      "types": "./dist/esm/interceptors/audit/sinks/index.d.ts",
+      "import": "./dist/esm/interceptors/audit/sinks/index.js",
+      "require": "./dist/cjs/interceptors/audit/sinks/index.js"
+    },
+    "./interceptors/cache": {
+      "types": "./dist/esm/interceptors/cache/index.d.ts",
+      "import": "./dist/esm/interceptors/cache/index.js",
+      "require": "./dist/cjs/interceptors/cache/index.js"
+    },
+    "./interceptors/cache/backends": {
+      "types": "./dist/esm/interceptors/cache/backends/index.d.ts",
+      "import": "./dist/esm/interceptors/cache/backends/index.js",
+      "require": "./dist/cjs/interceptors/cache/backends/index.js"
+    },
+    "./interceptors/reliability": {
+      "types": "./dist/esm/interceptors/reliability/index.d.ts",
+      "import": "./dist/esm/interceptors/reliability/index.js",
+      "require": "./dist/cjs/interceptors/reliability/index.js"
+    },
+    "./providers": {
+      "types": "./dist/esm/providers/index.d.ts",
+      "import": "./dist/esm/providers/index.js",
+      "require": "./dist/cjs/providers/index.js"
+    },
+    "./providers/openai": {
+      "types": "./dist/esm/providers/openai.d.ts",
+      "import": "./dist/esm/providers/openai.js",
+      "require": "./dist/cjs/providers/openai.js"
+    },
+    "./providers/anthropic": {
+      "types": "./dist/esm/providers/anthropic.d.ts",
+      "import": "./dist/esm/providers/anthropic.js",
+      "require": "./dist/cjs/providers/anthropic.js"
+    },
+    "./testing": {
+      "types": "./dist/esm/testing/index.d.ts",
+      "import": "./dist/esm/testing/index.js",
+      "require": "./dist/cjs/testing/index.js"
+    }
+  },
+  "scripts": {
+    "build": "npm run build:esm && npm run build:cjs && node scripts/finalize-build.mjs",
+    "build:esm": "tsc -p tsconfig.build.esm.json",
+    "build:cjs": "tsc -p tsconfig.build.cjs.json",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "smoke": "npm run build && node scripts/smoke.mjs",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "ai",
+    "gateway",
+    "llm",
+    "pii",
+    "audit",
+    "reliability",
+    "openai",
+    "anthropic"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  }
+}

package/src/context.ts

@@ -0,0 +1,57 @@
+/** 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 class InterceptorContext {
+  traceId: string
+  agentId: string | null
+  parentTraceId: string | null
+  sessionId: string | null
+  dryRun: boolean
+
+  interceptorsFired: string[] = []
+  piiEntityTypes: string[] = []
+  piiEntityCounts: Record<string, number> = {}
+  cacheHit = false
+  cacheType: string | null = null
+  riskScore: number | null = null
+  guardrailOutcome: string | null = null
+
+  /** Arbitrary inter-interceptor state (e.g. PII replacement map for restore). */
+  state: Record<string, unknown> = {}
+
+  constructor(init: InterceptorContextInit) {
+    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: string): void {
+    if (!this.interceptorsFired.includes(name)) {
+      this.interceptorsFired.push(name)
+    }
+  }
+
+  recordPii(entityTypes: string[]): void {
+    for (const et of entityTypes) {
+      this.piiEntityCounts[et] = (this.piiEntityCounts[et] ?? 0) + 1
+      if (!this.piiEntityTypes.includes(et)) {
+        this.piiEntityTypes.push(et)
+      }
+    }
+  }
+}

package/src/errors.ts

@@ -0,0 +1,47 @@
+/**
+ * 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?: string) {
+    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 {
+  readonly entityTypes: string[]
+
+  constructor(entityTypes: string[]) {
+    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/src/gateway.ts

@@ -0,0 +1,174 @@
+/** Gateway — the entry point. Wires interceptors around a provider adapter. */
+
+import { InterceptorContext } from './context.js'
+import { ConfigurationError } from './errors.js'
+import { auditInterceptor, isAuditInterceptor } from './interceptors/audit/index.js'
+import { isExecutorPolicy } from './interceptors/base.js'
+import type { Executor, ExecutorPolicy, Interceptor } from './interceptors/base.js'
+import { InterceptorChain } from './interceptors/chain.js'
+import { PricingProvider } from './pricing.js'
+import { buildAdapter } from './providers/index.js'
+import type { ProviderAdapter } from './providers/base.js'
+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'
+
+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>
+}
+
+const DEFAULT_MODELS: Record<string, string> = {
+  openai: 'gpt-4o',
+  anthropic: 'claude-sonnet-4-6',
+  mock: 'mock',
+}
+
+/**
+ * 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 class Gateway {
+  private readonly providerHint: Provider | undefined
+  private modelHint: string | undefined
+  private adapterOverride: ProviderAdapter | undefined
+  private readonly devMode: boolean
+  private readonly dryRunMode: boolean
+  private readonly pricing: PricingProvider
+  private readonly interceptors: Interceptor[] = []
+
+  constructor(options: GatewayOptions = {}) {
+    this.providerHint = options.provider ? coerceProvider(options.provider) : undefined
+    this.modelHint = options.model
+    this.adapterOverride = options.adapter
+    this.devMode = options.devMode ?? false
+    this.dryRunMode = options.dryRun ?? false
+    this.pricing = options.pricing ?? new PricingProvider()
+  }
+
+  /** Register an interceptor or executor policy. First-registered = outermost. */
+  use(interceptor: Interceptor): this {
+    this.interceptors.push(interceptor)
+    return this
+  }
+
+  /** Supply a provider adapter explicitly (overrides `provider`). */
+  withAdapter(adapter: ProviderAdapter): this {
+    this.adapterOverride = adapter
+    return this
+  }
+
+  get model(): string {
+    return this.modelHint ?? this.resolveModel(this.resolveAdapter())
+  }
+
+  get providerName(): string {
+    return this.resolveAdapter().providerName
+  }
+
+  async complete(opts: CompleteOptions): Promise<GavioResponse> {
+    const adapter = this.resolveAdapter()
+    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 { chain, executor } = this.buildPipeline(adapter, ctx)
+    return chain.execute(request, ctx, executor)
+  }
+
+  async healthCheck(): Promise<boolean> {
+    return this.resolveAdapter().healthCheck()
+  }
+
+  private buildPipeline(
+    adapter: ProviderAdapter,
+    ctx: InterceptorContext,
+  ): { chain: InterceptorChain; executor: Executor } {
+    let interceptors = [...this.interceptors]
+
+    // Dev mode auto-wires a stdout audit sink if none was added.
+    if (this.devMode && !interceptors.some(isAuditInterceptor)) {
+      interceptors = [auditInterceptor(), ...interceptors]
+    }
+
+    const policies = interceptors.filter(isExecutorPolicy)
+    const regular = interceptors.filter((i) => !isExecutorPolicy(i))
+    const chain = new InterceptorChain(regular)
+
+    let executor: Executor = (request) => adapter.complete(request)
+    // Wrap so the first-registered policy ends up outermost.
+    for (let i = policies.length - 1; i >= 0; i--) {
+      executor = this.wrapPolicy(policies[i]!, executor, ctx)
+    }
+    return { chain, executor }
+  }
+
+  private wrapPolicy(
+    policy: ExecutorPolicy,
+    inner: Executor,
+    ctx: InterceptorContext,
+  ): Executor {
+    return async (request: GavioRequest): Promise<GavioResponse> => {
+      if (ctx.dryRun && policy.dryRunSafe === false) {
+        return inner(request)
+      }
+      return policy.around(request, ctx, inner)
+    }
+  }
+
+  private resolveAdapter(): ProviderAdapter {
+    if (this.adapterOverride !== undefined) return this.adapterOverride
+    if (this.devMode) {
+      this.adapterOverride = mockProvider({ pricing: this.pricing })
+      return this.adapterOverride
+    }
+    if (this.providerHint === undefined) {
+      throw new ConfigurationError(
+        'No provider configured. Pass { provider }, { adapter }, call .withAdapter(...), ' +
+          'or set { devMode: true }.',
+      )
+    }
+    this.adapterOverride = buildAdapter(this.providerHint, this.pricing)
+    return this.adapterOverride
+  }
+
+  private resolveModel(adapter: ProviderAdapter): string {
+    return DEFAULT_MODELS[adapter.providerName] ?? 'mock'
+  }
+}

package/src/ids.ts

@@ -0,0 +1,69 @@
+/**
+ * UUID v7 generation — time-sortable, unique identifiers for traces.
+ *
+ * UUID v7 layout (RFC 9562): 48-bit Unix millisecond timestamp, 4-bit version,
+ * 12 bits used here as a per-millisecond monotonic sequence (rand_a), 2-bit
+ * variant, 62 bits of randomness. Ported directly from the Python `_ids.py`.
+ */
+
+import { randomBytes } from 'node:crypto'
+
+let lastMs = -1
+let seq = 0 // 12-bit per-millisecond sequence in rand_a, for monotonicity
+
+/**
+ * Return a [unix_ms, sequence] pair that is monotonically non-decreasing.
+ *
+ * Within a single millisecond the 12-bit sequence increments so IDs stay
+ * strictly ordered (RFC 9562 method 1). If the sequence overflows, the
+ * timestamp is nudged forward. JavaScript is single-threaded per event loop,
+ * so no lock is required.
+ */
+function nextTimestampAndSeq(): [number, number] {
+  const nowMs = Date.now()
+  if (nowMs > lastMs) {
+    lastMs = nowMs
+    seq = randomBytes(2).readUInt16BE(0) & 0x0fff
+  } else {
+    seq += 1
+    if (seq > 0x0fff) {
+      lastMs += 1
+      seq = 0
+    }
+  }
+  return [lastMs, seq]
+}
+
+function toHex(value: bigint, width: number): string {
+  return value.toString(16).padStart(width, '0')
+}
+
+/** Return a new UUID version 7 (time-ordered, monotonic within a process). */
+export function uuid7(): string {
+  const [unixMs, randA] = nextTimestampAndSeq()
+
+  // 48-bit millisecond timestamp occupies bits 80..127. Use BigInt for the
+  // shift — JS bitwise ops are 32-bit and would truncate Date.now() (~1.75e12).
+  const ms = BigInt(unixMs) & 0xffffffffffffn
+
+  const randBuf = randomBytes(8)
+  const randB = randBuf.readBigUInt64BE(0) & 0x3fffffffffffffffn // 62 bits
+
+  const value =
+    (ms << 80n) |
+    (0x7n << 76n) | // version 7
+    (BigInt(randA) << 64n) |
+    (0b10n << 62n) | // variant
+    randB
+
+  const hex = toHex(value, 32)
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(
+    16,
+    20,
+  )}-${hex.slice(20)}`
+}
+
+/** Return a fresh trace id as a string. */
+export function newTraceId(): string {
+  return uuid7()
+}