gavio 0.1.0

package/src/providers/openai.ts

@@ -0,0 +1,94 @@
+/** openaiAdapter — Chat Completions API (GPT-4o, o1, ...). */
+
+import { ConfigurationError } from '../errors.js'
+import type { PricingProvider } from '../pricing.js'
+import type { GavioRequest } from '../request.js'
+import type { GavioResponse } from '../response.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'
+
+export interface OpenAIAdapterOptions {
+  apiKey?: string
+  baseUrl?: string
+  timeoutMs?: number
+  organization?: string
+  pricing?: PricingProvider
+}
+
+class OpenAIAdapter extends BaseProviderAdapter {
+  private readonly apiKey: string | undefined
+  private readonly baseUrl: string
+  private readonly timeoutSeconds: number
+  private readonly organization: string | undefined
+
+  constructor(options: OpenAIAdapterOptions = {}) {
+    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(): string {
+    return 'openai'
+  }
+
+  private headers(): Record<string, string> {
+    if (!this.apiKey) {
+      throw new ConfigurationError(
+        'OPENAI_API_KEY not set (pass apiKey or set the env var)',
+      )
+    }
+    const headers: Record<string, string> = { Authorization: `Bearer ${this.apiKey}` }
+    if (this.organization) headers['OpenAI-Organization'] = this.organization
+    return headers
+  }
+
+  async complete(request: GavioRequest): Promise<GavioResponse> {
+    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'] as Array<Record<string, unknown>>) ?? []
+    const message = (choices[0]?.['message'] as Record<string, unknown>) ?? {}
+    const content = (message['content'] as string) ?? ''
+    const usageData = (data['usage'] as Record<string, number>) ?? {}
+    const usage = new TokenUsage(
+      usageData['prompt_tokens'] ?? 0,
+      usageData['completion_tokens'] ?? 0,
+    )
+    return this.buildResponse(
+      request,
+      content,
+      usage,
+      (data['model'] as string) ?? request.model,
+      started,
+    )
+  }
+
+  async healthCheck(): Promise<boolean> {
+    try {
+      this.headers()
+      return true
+    } catch {
+      return false
+    }
+  }
+}
+
+/** Factory: build an OpenAI provider adapter. */
+export function openaiAdapter(options: OpenAIAdapterOptions = {}): OpenAIAdapter {
+  return new OpenAIAdapter(options)
+}

package/src/request.ts

@@ -0,0 +1,76 @@
+/** GavioRequest — the canonical, provider-agnostic request model. */
+
+import { newTraceId } from './ids.js'
+import { coerceProvider } from './types.js'
+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 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) {
+    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(): number {
+    const t = this.options['temperature']
+    return typeof t === 'number' ? t : 0.7
+  }
+
+  get maxTokens(): number {
+    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(): string {
+    return this.messages.map((m) => m.content ?? '').join('\n')
+  }
+
+  /** Return a shallow copy with replaced messages (interceptors mutate via this). */
+  copyWithMessages(messages: Message[]): GavioRequest {
+    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/src/response.ts

@@ -0,0 +1,73 @@
+/** 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 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) {
+    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: string): GavioResponse {
+    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/src/testing/harness.ts

@@ -0,0 +1,98 @@
+/**
+ * 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 type { Executor, ExecutorPolicy, Interceptor } from '../interceptors/base.js'
+import { InterceptorChain } from '../interceptors/chain.js'
+import type { AuditRecord } from '../interceptors/audit/record.js'
+import { mockProvider } from '../providers/mock.js'
+import type { ProviderAdapter } from '../providers/base.js'
+import { GavioRequest } from '../request.js'
+import type { GavioResponse } from '../response.js'
+import { coerceProvider } from '../types.js'
+import type { Message } from '../types.js'
+
+/** Records the request as it reaches the provider (post-redaction). */
+class CaptureInterceptor implements Interceptor {
+  readonly name = '_capture'
+  captured: GavioRequest | null = null
+
+  before(request: GavioRequest): GavioRequest {
+    this.captured = request
+    return request
+  }
+}
+
+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 class GavioTestKit {
+  private readonly interceptors: Interceptor[]
+  private readonly provider: ProviderAdapter
+  private readonly model: string
+
+  constructor(options: GavioTestKitOptions = {}) {
+    this.interceptors = [...(options.interceptors ?? [])]
+    this.provider = options.provider ?? mockProvider()
+    this.model = options.model ?? 'mock'
+  }
+
+  async run(input: { messages: Message[]; options?: Record<string, unknown> }): Promise<RunResult> {
+    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: 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?: string): boolean => {
+        if (entityType === undefined) return ctx.piiEntityTypes.length > 0
+        return ctx.piiEntityTypes.includes(entityType)
+      },
+      get auditRecord(): AuditRecord | null {
+        return response.audit
+      },
+    }
+  }
+}
+
+function wrap(policy: ExecutorPolicy, inner: Executor, ctx: InterceptorContext): Executor {
+  return (req: GavioRequest) => policy.around(req, ctx, inner)
+}

package/src/testing/index.ts

@@ -0,0 +1,6 @@
+/** 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/src/types.ts

@@ -0,0 +1,83 @@
+/** 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 const Provider = {
+  OPENAI: 'openai',
+  ANTHROPIC: 'anthropic',
+  GEMINI: 'gemini',
+  AZURE_OPENAI: 'azure_openai',
+  OLLAMA: 'ollama',
+  BEDROCK: 'bedrock',
+  COHERE: 'cohere',
+  MOCK: 'mock',
+} as const
+
+export type Provider = (typeof Provider)[keyof typeof Provider]
+
+/** Accept either a known provider value or any string and normalise to lowercase. */
+export function coerceProvider(value: Provider | string): Provider {
+  return value.toLowerCase() as Provider
+}
+
+export const CacheType = {
+  EXACT: 'exact',
+  SEMANTIC: 'semantic',
+} as const
+
+export type CacheType = (typeof CacheType)[keyof typeof CacheType]
+
+/** 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
+} as const
+
+export type PiiMode = (typeof PiiMode)[keyof typeof PiiMode]
+
+export const Sensitivity = {
+  STRICT: 'strict',
+  BALANCED: 'balanced',
+  PERMISSIVE: 'permissive',
+} as const
+
+export type Sensitivity = (typeof Sensitivity)[keyof typeof Sensitivity]
+
+export const GuardrailOutcome = {
+  PASS: 'PASS',
+  FAIL: 'FAIL',
+  HITL: 'HITL',
+} as const
+
+export type GuardrailOutcome = (typeof GuardrailOutcome)[keyof typeof GuardrailOutcome]
+
+/** Token accounting for a single completion. */
+export class TokenUsage {
+  readonly promptTokens: number
+  readonly completionTokens: number
+
+  constructor(promptTokens = 0, completionTokens = 0) {
+    this.promptTokens = promptTokens
+    this.completionTokens = completionTokens
+  }
+
+  get totalTokens(): number {
+    return this.promptTokens + this.completionTokens
+  }
+
+  toJSON(): { promptTokens: number; completionTokens: number; totalTokens: number } {
+    return {
+      promptTokens: this.promptTokens,
+      completionTokens: this.completionTokens,
+      totalTokens: this.totalTokens,
+    }
+  }
+}