gavio 0.1.0 → 0.2.0

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gavio",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The open standard AI gateway for production systems — PII guarding, audit, reliability, and cost tracking.",
   "license": "MIT",
   "repository": {
@@ -65,6 +65,26 @@
       "import": "./dist/esm/interceptors/reliability/index.js",
       "require": "./dist/cjs/interceptors/reliability/index.js"
     },
+    "./interceptors/governance": {
+      "types": "./dist/esm/interceptors/governance/index.d.ts",
+      "import": "./dist/esm/interceptors/governance/index.js",
+      "require": "./dist/cjs/interceptors/governance/index.js"
+    },
+    "./interceptors/guardrails": {
+      "types": "./dist/esm/interceptors/guardrails/index.d.ts",
+      "import": "./dist/esm/interceptors/guardrails/index.js",
+      "require": "./dist/cjs/interceptors/guardrails/index.js"
+    },
+    "./interceptors/injection": {
+      "types": "./dist/esm/interceptors/injection.d.ts",
+      "import": "./dist/esm/interceptors/injection.js",
+      "require": "./dist/cjs/interceptors/injection.js"
+    },
+    "./shim/openai": {
+      "types": "./dist/esm/shim/openai.d.ts",
+      "import": "./dist/esm/shim/openai.js",
+      "require": "./dist/cjs/shim/openai.js"
+    },
     "./providers": {
       "types": "./dist/esm/providers/index.d.ts",
       "import": "./dist/esm/providers/index.js",
@@ -99,11 +119,20 @@
   },
   "keywords": [
     "ai",
-    "gateway",
+    "ai-gateway",
     "llm",
+    "llm-gateway",
+    "llmops",
+    "gateway",
     "pii",
+    "pii-redaction",
     "audit",
+    "observability",
     "reliability",
+    "retry",
+    "fallback",
+    "cost-tracking",
+    "interceptor",
     "openai",
     "anthropic"
   ],

package/src/config.ts

@@ -0,0 +1,125 @@
+/**
+ * Config loader (F-DX-05) — build a Gateway from an object or a JSON file.
+ *
+ *   const gw = await Gateway.fromConfig('gateway.json')
+ *
+ * JSON is supported out of the box; string values expand ${ENV_VAR}.
+ */
+
+import { readFileSync } from 'node:fs'
+import { ConfigurationError } from './errors.js'
+import { Gateway } from './gateway.js'
+import { auditInterceptor } from './interceptors/audit/index.js'
+import { hashingEmbedder, semanticCache } from './interceptors/cache/index.js'
+import { costControl, modelPolicy, rateLimiter } from './interceptors/governance/index.js'
+import { promptInjectionGuard } from './interceptors/injection.js'
+import { piiGuard } from './interceptors/pii/index.js'
+import { retryInterceptor, timeoutPolicy } from './interceptors/reliability/index.js'
+
+type Cfg = Record<string, unknown>
+
+export function loadConfig(path: string): Cfg {
+  const text = readFileSync(path, 'utf8')
+  if (!path.endsWith('.json')) {
+    throw new ConfigurationError('JS config loader supports JSON only (use .json)')
+  }
+  return expand(JSON.parse(text)) as Cfg
+}
+
+function expand(obj: unknown): unknown {
+  if (Array.isArray(obj)) return obj.map(expand)
+  if (obj && typeof obj === 'object') {
+    return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, expand(v)]))
+  }
+  if (typeof obj === 'string') {
+    return obj.replace(/\$\{(\w+)\}/g, (_, v: string) => process.env[v] ?? '')
+  }
+  return obj
+}
+
+export function buildFromConfig(config: Cfg): Gateway {
+  const gatewayOptions: Cfg = {}
+  if (config['provider']) gatewayOptions['provider'] = config['provider']
+  if (config['model']) gatewayOptions['model'] = config['model']
+  if (config['devMode'] ?? config['dev_mode']) gatewayOptions['devMode'] = true
+  if (config['dryRun'] ?? config['dry_run']) gatewayOptions['dryRun'] = true
+
+  let gw = new Gateway(gatewayOptions)
+  const ic = (config['interceptors'] as Record<string, Cfg> | undefined) ?? {}
+
+  const cfg = (name: string): Cfg | null => {
+    const entry = ic[name]
+    return entry && entry['enabled'] !== false ? entry : null
+  }
+
+  let c: Cfg | null
+  if ((c = cfg('audit'))) {
+    gw = gw.use(
+      auditInterceptor({
+        sink: (c['sink'] as 'stdout') ?? 'stdout',
+        hashChain: Boolean(c['hashChain'] ?? c['hash_chain']),
+      }),
+    )
+  }
+  if ((c = cfg('prompt_injection'))) {
+    gw = gw.use(promptInjectionGuard({ action: (c['action'] as 'block' | 'flag') ?? 'block' }))
+  }
+  if ((c = cfg('pii_guard'))) {
+    gw = gw.use(
+      piiGuard({
+        sensitivity: (c['sensitivity'] as never) ?? 'strict',
+        mode: (c['mode'] as never) ?? 'redact',
+      }),
+    )
+  }
+  if ((c = cfg('cost_control'))) {
+    gw = gw.use(
+      costControl({
+        hardCapUsd: Number(c['hardCapUsd'] ?? c['hard_cap_usd']),
+        softCapUsd: (c['softCapUsd'] ?? c['soft_cap_usd']) as number | undefined,
+        scope: (c['scope'] as never) ?? 'global',
+        window: (c['window'] as never) ?? 'day',
+      }),
+    )
+  }
+  if ((c = cfg('rate_limiter'))) {
+    gw = gw.use(
+      rateLimiter({
+        maxRequestsPerMinute: (c['maxRequestsPerMinute'] ?? c['max_requests_per_minute']) as
+          | number
+          | undefined,
+        maxTokensPerMinute: (c['maxTokensPerMinute'] ?? c['max_tokens_per_minute']) as
+          | number
+          | undefined,
+        scope: (c['scope'] as never) ?? 'global',
+      }),
+    )
+  }
+  if ((c = cfg('model_policy'))) {
+    gw = gw.use(modelPolicy({ roles: (c['roles'] as Record<string, string[]>) ?? {} }))
+  }
+  if ((c = cfg('semantic_cache'))) {
+    const embedder = (c['enableSemantic'] ?? c['enable_semantic']) ? hashingEmbedder() : undefined
+    gw = gw.use(
+      semanticCache({
+        embedder,
+        similarityThreshold: Number(c['similarityThreshold'] ?? c['similarity_threshold'] ?? 0.95),
+      }),
+    )
+  }
+  if ((c = cfg('timeout'))) {
+    gw = gw.use(
+      timeoutPolicy({ timeoutSeconds: Number(c['timeoutSeconds'] ?? c['timeout_seconds'] ?? 30) }),
+    )
+  }
+  if ((c = cfg('retry'))) {
+    gw = gw.use(
+      retryInterceptor({
+        maxAttempts: Number(c['maxAttempts'] ?? c['max_attempts'] ?? 3),
+        baseDelayMs: Number(c['baseDelayMs'] ?? c['base_delay_ms'] ?? 500),
+      }),
+    )
+  }
+
+  return gw
+}

package/src/errors.ts

@@ -43,5 +43,33 @@ export class PiiBlockedError extends GavioError {
 /** A hard budget cap was exceeded. Never swallow this — surface to user. */
 export class BudgetExceededError extends GavioError {}
 
+/** The circuit breaker is open; the call was rejected without hitting the provider. */
+export class CircuitOpenError extends ProviderUnavailableError {}
+
+/** A local rate limit (requests/tokens per minute) was exceeded. */
+export class RateLimitExceededError extends GavioError {}
+
+/** The caller's role is not permitted to use the requested model (RBAC). */
+export class ModelNotAllowedError extends GavioError {
+  readonly role: string
+  readonly model: string
+
+  constructor(role: string, model: string) {
+    super(`role ${JSON.stringify(role)} may not use model ${JSON.stringify(model)}`)
+    this.role = role
+    this.model = model
+  }
+}
+
 /** Output failed a guardrail validator with onFailure='error'. */
 export class GuardrailViolationError extends GavioError {}
+
+/** A prompt-injection attempt was detected and the guard is in block mode. */
+export class PromptInjectionError extends GavioError {
+  readonly patterns: string[]
+
+  constructor(patterns: string[]) {
+    super(`prompt injection detected: ${patterns.join(', ')}`)
+    this.patterns = patterns
+  }
+}

package/src/gateway.ts

@@ -66,6 +66,16 @@ export class Gateway {
     this.pricing = options.pricing ?? new PricingProvider()
   }
 
+  /**
+   * Build a Gateway from a config object or a JSON file path (F-DX-05).
+   * Async so the config module loads lazily (avoids a circular import).
+   */
+  static async fromConfig(config: string | Record<string, unknown>): Promise<Gateway> {
+    const mod = await import('./config.js')
+    const data = typeof config === 'string' ? mod.loadConfig(config) : config
+    return mod.buildFromConfig(data)
+  }
+
   /** Register an interceptor or executor policy. First-registered = outermost. */
   use(interceptor: Interceptor): this {
     this.interceptors.push(interceptor)

package/src/interceptors/audit/index.ts

@@ -5,3 +5,5 @@ export type { AuditRecordInit } from './record.js'
 export type { AuditSink } from './sink.js'
 export { stdoutSink } from './sinks/stdout.js'
 export type { StdoutSinkOptions } from './sinks/stdout.js'
+export { verifyChain, buildCallGraph } from './trace.js'
+export type { TraceNode } from './trace.js'

package/src/interceptors/audit/interceptor.ts

@@ -14,6 +14,8 @@ export const AUDIT_NAME = 'audit'
 
 export interface AuditInterceptorOptions {
   sink?: AuditSink | 'stdout'
+  /** F-OBS-02: link each record via previousHash into a tamper-evident chain. */
+  hashChain?: boolean
 }
 
 /**
@@ -29,9 +31,12 @@ class AuditInterceptor implements Interceptor {
   readonly dryRunSafe = true // auditing is observation-only, so it always runs
 
   private readonly sink: AuditSink
+  private readonly hashChain: boolean
+  private lastHash = ''
 
   constructor(options: AuditInterceptorOptions = {}) {
     this.sink = resolveSink(options.sink)
+    this.hashChain = options.hashChain ?? false
   }
 
   async before(request: GavioRequest, ctx: InterceptorContext): Promise<GavioRequest> {
@@ -65,6 +70,10 @@ class AuditInterceptor implements Interceptor {
       guardrailOutcome: ctx.guardrailOutcome,
       riskScore: ctx.riskScore,
     })
+    if (this.hashChain) {
+      record.previousHash = this.lastHash
+      this.lastHash = record.contentHash()
+    }
     response.audit = record
     try {
       await this.sink.write(record)

package/src/interceptors/audit/trace.ts

@@ -0,0 +1,47 @@
+/** Audit-chain verification (F-OBS-02) and multi-agent DAG trace (F-OBS-03). */
+
+import type { AuditRecord } from './record.js'
+
+/**
+ * Return true if the records form an intact hash chain. Each record's
+ * previousHash must equal the content hash of the record before it; the first
+ * must be empty. Any edit, reorder, or deletion breaks the chain.
+ */
+export function verifyChain(records: AuditRecord[]): boolean {
+  let prevHash = ''
+  for (const rec of records) {
+    if (rec.previousHash !== prevHash) return false
+    prevHash = rec.contentHash()
+  }
+  return true
+}
+
+export interface TraceNode {
+  traceId: string
+  agentId: string | null
+  parentTraceId: string | null
+  children: TraceNode[]
+}
+
+/**
+ * Reconstruct the multi-agent DAG from audit records using parentTraceId +
+ * traceId. Returns the root nodes (those with no known parent).
+ */
+export function buildCallGraph(records: AuditRecord[]): TraceNode[] {
+  const nodes = new Map<string, TraceNode>()
+  for (const rec of records) {
+    nodes.set(rec.traceId, {
+      traceId: rec.traceId,
+      agentId: rec.agentId,
+      parentTraceId: rec.parentTraceId,
+      children: [],
+    })
+  }
+  const roots: TraceNode[] = []
+  for (const node of nodes.values()) {
+    const parent = node.parentTraceId ? nodes.get(node.parentTraceId) : undefined
+    if (parent) parent.children.push(node)
+    else roots.push(node)
+  }
+  return roots
+}

package/src/interceptors/cache/embedding.ts

@@ -0,0 +1,53 @@
+/**
+ * Embeddings for the semantic cache (F-CACHE-02).
+ *
+ * Zero-dependency hashed bag-of-words embedder (L2-normalised) — good enough to
+ * dedup near-identical prompts. Plug in a real embedder implementing `Embedder`
+ * for production semantic matching.
+ */
+
+import { createHash } from 'node:crypto'
+
+export interface Embedder {
+  embed(text: string): number[]
+}
+
+const TOKEN = /[a-z0-9]+/g
+
+/** Deterministic hashed bag-of-words embedder. */
+export function hashingEmbedder(dim = 256): Embedder {
+  return {
+    embed(text: string): number[] {
+      const vec = new Array<number>(dim).fill(0)
+      const tokens = text.toLowerCase().match(TOKEN) ?? []
+      for (const token of tokens) {
+        // Parity note: Python uses blake2b(digest_size=8); here we take the
+        // first 8 bytes of blake2b512. Both are deterministic; the JS cache is
+        // per-process so cross-language byte-parity is not required.
+        const digest = createHash('blake2b512').update(token).digest()
+        let n = 0n
+        for (let i = 0; i < 8; i++) n = (n << 8n) | BigInt(digest[i]!)
+        const bucket = Number(n % BigInt(dim))
+        vec[bucket]! += 1
+      }
+      const norm = Math.sqrt(vec.reduce((s, x) => s + x * x, 0))
+      if (norm === 0) return vec
+      return vec.map((x) => x / norm)
+    },
+  }
+}
+
+/** Cosine similarity; safe for zero vectors. */
+export function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length !== b.length) throw new Error('vectors must have equal length')
+  let dot = 0
+  let na = 0
+  let nb = 0
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i]! * b[i]!
+    na += a[i]! * a[i]!
+    nb += b[i]! * b[i]!
+  }
+  if (na === 0 || nb === 0) return 0
+  return dot / (Math.sqrt(na) * Math.sqrt(nb))
+}