gavio 0.1.0 → 0.3.0

package/src/shim/openai.ts

@@ -0,0 +1,76 @@
+/**
+ * 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 { GavioResponse } from '../response.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
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  max_tokens?: number
+}
+
+function toCompletion(resp: GavioResponse): ChatCompletion {
+  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 {
+  constructor(private readonly gw: Gateway) {}
+
+  async create(params: CreateParams): Promise<ChatCompletion> {
+    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 {
+  readonly chat: { completions: Completions }
+
+  constructor(gateway: Gateway) {
+    this.chat = { completions: new Completions(gateway) }
+  }
+}

package/src/types.ts

@@ -81,3 +81,80 @@ export class TokenUsage {
     }
   }
 }
+
+export interface RagChunkInit {
+  source: string
+  chunkId?: string | null
+  score?: number | null
+}
+
+/**
+ * A single retrieved source that contributed to a prompt. Carries a *reference*
+ * to the source — never the retrieved text — so prompt lineage stays within the
+ * audit record's metadata-only contract.
+ */
+export class RagChunk {
+  readonly source: string
+  readonly chunkId: string | null
+  readonly score: number | null
+
+  constructor(init: RagChunkInit) {
+    this.source = init.source
+    this.chunkId = init.chunkId ?? null
+    this.score = init.score ?? null
+  }
+
+  toJSON(): { source: string; chunkId: string | null; score: number | null } {
+    return { source: this.source, chunkId: this.chunkId, score: this.score }
+  }
+}
+
+export interface PromptLineageInit {
+  templateId?: string | null
+  templateVersion?: string | null
+  variables?: Record<string, unknown>
+  ragChunks?: Array<RagChunk | RagChunkInit>
+}
+
+/**
+ * Provenance for a rendered prompt (F-OBS-04): the template, the variable
+ * bindings interpolated into it, and the RAG chunk sources retrieved for it.
+ *
+ * Attached to a GavioRequest by the caller and copied into the AuditRecord so
+ * any prompt can be reconstructed and debugged. RAG chunk text is never stored
+ * — only source references (see {@link RagChunk}).
+ */
+export class PromptLineage {
+  readonly templateId: string | null
+  readonly templateVersion: string | null
+  readonly variables: Record<string, unknown>
+  readonly ragChunks: RagChunk[]
+
+  constructor(init: PromptLineageInit = {}) {
+    this.templateId = init.templateId ?? null
+    this.templateVersion = init.templateVersion ?? null
+    this.variables = init.variables ?? {}
+    this.ragChunks = (init.ragChunks ?? []).map((c) =>
+      c instanceof RagChunk ? c : new RagChunk(c),
+    )
+  }
+
+  /** Coerce a PromptLineage instance or plain init object into a PromptLineage. */
+  static from(value: PromptLineage | PromptLineageInit): PromptLineage {
+    return value instanceof PromptLineage ? value : new PromptLineage(value)
+  }
+
+  toJSON(): {
+    templateId: string | null
+    templateVersion: string | null
+    variables: Record<string, unknown>
+    ragChunks: Array<{ source: string; chunkId: string | null; score: number | null }>
+  } {
+    return {
+      templateId: this.templateId,
+      templateVersion: this.templateVersion,
+      variables: this.variables,
+      ragChunks: this.ragChunks.map((c) => c.toJSON()),
+    }
+  }
+}