okengine 0.1.4

package/src/drivers/ai-anthropic.ts

@@ -0,0 +1,128 @@
+/**
+ * `anthropic` AI driver — thin HTTP client for the Anthropic Messages API.
+ *
+ * Injectable `fetch` (same DI shape as postgres/redis/s3 `client`) so tests
+ * substitute a fake. Never a production default — prod must declare.
+ */
+
+import type {
+  AiCompleteOptions,
+  AiCompleteResult,
+  AiDriver,
+  AiModelClient,
+  AiOpenOptions,
+} from "./ai-types.ts";
+
+const DEFAULT_BASE = "https://api.anthropic.com";
+const ANTHROPIC_VERSION = "2023-06-01";
+
+/**
+ * Open an Anthropic Messages API client.
+ *
+ * @param options - API key / model / base URL / injectable fetch
+ */
+export async function openAnthropic(
+  options: AiOpenOptions = {},
+): Promise<AiModelClient> {
+  const apiKey = options.apiKey ?? process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) {
+    throw new Error("anthropic: apiKey is required (or ANTHROPIC_API_KEY)");
+  }
+  const model = options.model ?? "claude-sonnet-4-20250514";
+  const baseUrl = (options.baseUrl ?? DEFAULT_BASE).replace(/\/$/, "");
+  const fetchFn = options.fetch ?? globalThis.fetch;
+
+  return {
+    driverId: "anthropic",
+    model,
+    async complete(opts: AiCompleteOptions): Promise<AiCompleteResult> {
+      const resolvedModel = opts.model ?? model;
+      const { system, messages } = splitSystem(opts.messages);
+      const res = await fetchFn(`${baseUrl}/v1/messages`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "x-api-key": apiKey,
+          "anthropic-version": ANTHROPIC_VERSION,
+        },
+        body: JSON.stringify({
+          model: resolvedModel,
+          max_tokens: opts.maxTokens ?? 1024,
+          ...(opts.temperature !== undefined
+            ? { temperature: opts.temperature }
+            : {}),
+          ...(system !== undefined ? { system } : {}),
+          messages,
+        }),
+      });
+      const raw = (await res.json().catch(() => ({}))) as AnthropicMessagesResponse;
+      if (!res.ok) {
+        const msg =
+          raw.error?.message ?? `anthropic HTTP ${res.status}`;
+        throw new Error(`anthropic: ${msg}`);
+      }
+      const text = textFromContent(raw.content);
+      return {
+        text,
+        raw,
+        model: raw.model ?? resolvedModel,
+        driverId: "anthropic",
+        usage: {
+          inputTokens: raw.usage?.input_tokens,
+          outputTokens: raw.usage?.output_tokens,
+        },
+      };
+    },
+  };
+}
+
+/** Protocol-named anthropic driver. */
+export const anthropicAiDriver: AiDriver = {
+  id: "anthropic",
+  open: openAnthropic,
+};
+
+interface AnthropicMessagesResponse {
+  readonly model?: string;
+  readonly content?: readonly { readonly type?: string; readonly text?: string }[];
+  readonly usage?: {
+    readonly input_tokens?: number;
+    readonly output_tokens?: number;
+  };
+  readonly error?: { readonly message?: string };
+}
+
+function splitSystem(
+  messages: AiCompleteOptions["messages"],
+): {
+  system?: string;
+  messages: Array<{ role: "user" | "assistant"; content: string }>;
+} {
+  const systemParts: string[] = [];
+  const out: Array<{ role: "user" | "assistant"; content: string }> = [];
+  for (const m of messages) {
+    if (m.role === "system") {
+      systemParts.push(m.content);
+      continue;
+    }
+    if (m.role === "tool") {
+      out.push({ role: "user", content: m.content });
+      continue;
+    }
+    out.push({ role: m.role, content: m.content });
+  }
+  return {
+    ...(systemParts.length > 0 ? { system: systemParts.join("\n\n") } : {}),
+    messages: out,
+  };
+}
+
+function textFromContent(
+  content: AnthropicMessagesResponse["content"],
+): string {
+  if (!content?.length) return "";
+  return content
+    .filter((b) => b.type === "text" && typeof b.text === "string")
+    .map((b) => b.text!)
+    .join("");
+}

package/src/drivers/ai-mock.ts

@@ -0,0 +1,82 @@
+/**
+ * `mock` AI driver — deterministic responses for tests / `oke test`.
+ *
+ * Dev default. Never a production default.
+ */
+
+import type {
+  AiCompleteOptions,
+  AiCompleteResult,
+  AiDriver,
+  AiEmbedOptions,
+  AiEmbedResult,
+  AiModelClient,
+  AiOpenOptions,
+} from "./ai-types.ts";
+
+/**
+ * Create a mock AI driver.
+ */
+export const mockAiDriver: AiDriver = {
+  id: "mock",
+  async open(options: AiOpenOptions = {}): Promise<AiModelClient> {
+    const model = options.model ?? "mock";
+    const canned = options.mockResponses ?? {};
+
+    return {
+      driverId: "mock",
+      model,
+      async complete(opts: AiCompleteOptions): Promise<AiCompleteResult> {
+        const last = opts.messages[opts.messages.length - 1]?.content ?? "";
+        let payload: unknown | undefined;
+        for (const [key, value] of Object.entries(canned)) {
+          if (key === "*") continue;
+          if (last.includes(key) || opts.model === key) {
+            payload = value;
+            break;
+          }
+        }
+        if (payload === undefined) {
+          payload = canned["*"] ?? { ok: true, echo: last };
+        }
+        const text =
+          typeof payload === "string" ? payload : JSON.stringify(payload);
+        return {
+          text,
+          raw: payload,
+          model: opts.model ?? model,
+          driverId: "mock",
+          usage: { inputTokens: last.length, outputTokens: text.length, cost: 0 },
+        };
+      },
+      async embed(opts: AiEmbedOptions): Promise<AiEmbedResult> {
+        const inputs = Array.isArray(opts.input) ? opts.input : [opts.input];
+        const vectors = inputs.map((text) => {
+          // Tiny deterministic bag-of-chars embedding for tests
+          const v = new Array<number>(8).fill(0);
+          for (let i = 0; i < text.length; i++) {
+            v[i % 8]! += text.charCodeAt(i) / 255;
+          }
+          return v;
+        });
+        return { vectors, model: opts.model ?? model, driverId: "mock" };
+      },
+    };
+  },
+};
+
+/**
+ * Register a mock response helper for tests.
+ *
+ * @param responses - Key → JSON payload
+ */
+export function createMockAiDriver(
+  responses: Readonly<Record<string, unknown>>,
+): AiDriver {
+  return {
+    id: "mock",
+    open(options = {}) {
+      return mockAiDriver.open({ ...options, mockResponses: responses });
+    },
+  };
+}

package/src/drivers/ai-openai-compatible.ts

@@ -0,0 +1,139 @@
+/**
+ * `openai-compatible` AI driver — thin HTTP client for OpenAI-shaped APIs.
+ *
+ * Covers OpenAI, vLLM, Groq, Together, LM Studio, and most self-hosted
+ * servers (unified-theory §16). Injectable `fetch` for tests. Never a
+ * production default — prod must declare.
+ */
+
+import type {
+  AiCompleteOptions,
+  AiCompleteResult,
+  AiDriver,
+  AiEmbedOptions,
+  AiEmbedResult,
+  AiModelClient,
+  AiOpenOptions,
+} from "./ai-types.ts";
+
+const DEFAULT_BASE = "https://api.openai.com/v1";
+
+/**
+ * Open an OpenAI-compatible chat / embeddings client.
+ *
+ * @param options - API key / model / base URL / injectable fetch
+ */
+export async function openOpenaiCompatible(
+  options: AiOpenOptions = {},
+): Promise<AiModelClient> {
+  const apiKey = options.apiKey ?? process.env.OPENAI_API_KEY;
+  if (!apiKey) {
+    throw new Error(
+      "openai-compatible: apiKey is required (or OPENAI_API_KEY)",
+    );
+  }
+  const model = options.model ?? "gpt-4o-mini";
+  const baseUrl = (options.baseUrl ?? DEFAULT_BASE).replace(/\/$/, "");
+  const fetchFn = options.fetch ?? globalThis.fetch;
+
+  return {
+    driverId: "openai-compatible",
+    model,
+    async complete(opts: AiCompleteOptions): Promise<AiCompleteResult> {
+      const resolvedModel = opts.model ?? model;
+      const body: Record<string, unknown> = {
+        model: resolvedModel,
+        messages: opts.messages.map((m) => ({
+          role: m.role,
+          content: m.content,
+          ...(m.name !== undefined ? { name: m.name } : {}),
+        })),
+      };
+      if (opts.temperature !== undefined) body.temperature = opts.temperature;
+      if (opts.maxTokens !== undefined) body.max_tokens = opts.maxTokens;
+      if (opts.responseFormat !== undefined) {
+        body.response_format = opts.responseFormat;
+      }
+
+      const res = await fetchFn(`${baseUrl}/chat/completions`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify(body),
+      });
+      const raw = (await res.json().catch(() => ({}))) as OpenAiChatResponse;
+      if (!res.ok) {
+        const msg =
+          raw.error?.message ?? `openai-compatible HTTP ${res.status}`;
+        throw new Error(`openai-compatible: ${msg}`);
+      }
+      const text = raw.choices?.[0]?.message?.content ?? "";
+      return {
+        text,
+        raw,
+        model: raw.model ?? resolvedModel,
+        driverId: "openai-compatible",
+        usage: {
+          inputTokens: raw.usage?.prompt_tokens,
+          outputTokens: raw.usage?.completion_tokens,
+        },
+      };
+    },
+    async embed(opts: AiEmbedOptions): Promise<AiEmbedResult> {
+      const resolvedModel = opts.model ?? model;
+      const input = opts.input;
+      const res = await fetchFn(`${baseUrl}/embeddings`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({ model: resolvedModel, input }),
+      });
+      const raw = (await res.json().catch(() => ({}))) as OpenAiEmbedResponse;
+      if (!res.ok) {
+        const msg =
+          raw.error?.message ?? `openai-compatible embed HTTP ${res.status}`;
+        throw new Error(`openai-compatible: ${msg}`);
+      }
+      const vectors = (raw.data ?? [])
+        .slice()
+        .sort((a, b) => (a.index ?? 0) - (b.index ?? 0))
+        .map((d) => d.embedding ?? []);
+      return {
+        vectors,
+        model: raw.model ?? resolvedModel,
+        driverId: "openai-compatible",
+      };
+    },
+  };
+}
+
+/** Protocol-named openai-compatible driver. */
+export const openaiCompatibleAiDriver: AiDriver = {
+  id: "openai-compatible",
+  open: openOpenaiCompatible,
+};
+
+interface OpenAiChatResponse {
+  readonly model?: string;
+  readonly choices?: readonly {
+    readonly message?: { readonly content?: string | null };
+  }[];
+  readonly usage?: {
+    readonly prompt_tokens?: number;
+    readonly completion_tokens?: number;
+  };
+  readonly error?: { readonly message?: string };
+}
+
+interface OpenAiEmbedResponse {
+  readonly model?: string;
+  readonly data?: readonly {
+    readonly embedding?: readonly number[];
+    readonly index?: number;
+  }[];
+  readonly error?: { readonly message?: string };
+}

package/src/drivers/ai-providers.test.ts

@@ -0,0 +1,163 @@
+/**
+ * Real AI provider drivers — injectable fetch (CI) · live key skip (optional).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { anthropicAiDriver, openAnthropic } from "./ai-anthropic.ts";
+import {
+  openaiCompatibleAiDriver,
+  openOpenaiCompatible,
+} from "./ai-openai-compatible.ts";
+import { mockAiDriver } from "./ai-mock.ts";
+
+describe("anthropic driver", () => {
+  test("id is anthropic; mock remains the only default elsewhere", () => {
+    expect(anthropicAiDriver.id).toBe("anthropic");
+    expect(mockAiDriver.id).toBe("mock");
+  });
+
+  test("complete via injectable fetch (no network)", async () => {
+    const calls: Array<{ url: string; init?: RequestInit }> = [];
+    const fetchFn: typeof fetch = Object.assign(
+      async (input: string | URL | Request, init?: RequestInit) => {
+        calls.push({ url: String(input), init });
+        return new Response(
+          JSON.stringify({
+            model: "claude-test",
+            content: [{ type: "text", text: '{"ok":true}' }],
+            usage: { input_tokens: 3, output_tokens: 5 },
+          }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        );
+      },
+      { preconnect: () => {} },
+    ) as typeof fetch;
+
+    const client = await openAnthropic({
+      apiKey: "sk-test",
+      model: "claude-test",
+      fetch: fetchFn,
+    });
+    const result = await client.complete({
+      messages: [
+        { role: "system", content: "be brief" },
+        { role: "user", content: "hi" },
+      ],
+      maxTokens: 64,
+    });
+
+    expect(result.driverId).toBe("anthropic");
+    expect(result.text).toBe('{"ok":true}');
+    expect(result.usage?.inputTokens).toBe(3);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]!.url).toContain("/v1/messages");
+    const body = JSON.parse(String(calls[0]!.init?.body)) as {
+      system?: string;
+      messages: Array<{ role: string }>;
+    };
+    expect(body.system).toBe("be brief");
+    expect(body.messages).toEqual([
+      { role: "user", content: "hi" } as { role: string },
+    ]);
+  });
+
+  test("HTTP error surfaces provider message", async () => {
+    const fetchFn = Object.assign(
+      async () =>
+        new Response(JSON.stringify({ error: { message: "rate limited" } }), {
+          status: 429,
+        }),
+      { preconnect: () => {} },
+    ) as typeof fetch;
+    const client = await openAnthropic({
+      apiKey: "sk-test",
+      fetch: fetchFn,
+    });
+    await expect(
+      client.complete({ messages: [{ role: "user", content: "x" }] }),
+    ).rejects.toThrow("rate limited");
+  });
+
+  test("live Anthropic ask when ANTHROPIC_API_KEY is set", async () => {
+    const key = process.env.ANTHROPIC_API_KEY;
+    if (!key) {
+      // Clearly-marked skip — never fail CI for lack of credentials.
+      console.log(
+        "skip: live anthropic ask (ANTHROPIC_API_KEY not set)",
+      );
+      return;
+    }
+    const client = await anthropicAiDriver.open({
+      apiKey: key,
+      model: process.env.ANTHROPIC_MODEL ?? "claude-haiku-4-5-20251001",
+    });
+    const result = await client.complete({
+      messages: [{ role: "user", content: 'Reply with exactly: {"pong":true}' }],
+      maxTokens: 32,
+    });
+    expect(result.driverId).toBe("anthropic");
+    expect(result.text.length).toBeGreaterThan(0);
+  });
+});
+
+describe("openai-compatible driver", () => {
+  test("id is openai-compatible", () => {
+    expect(openaiCompatibleAiDriver.id).toBe("openai-compatible");
+  });
+
+  test("complete + embed via injectable fetch", async () => {
+    const paths: string[] = [];
+    const fetchFn: typeof fetch = Object.assign(
+      async (input: string | URL | Request) => {
+        const url = String(input);
+        paths.push(url);
+        if (url.includes("/embeddings")) {
+          return new Response(
+            JSON.stringify({
+              model: "text-embedding-3-small",
+              data: [{ index: 0, embedding: [0.1, 0.2] }],
+            }),
+            { status: 200 },
+          );
+        }
+        return new Response(
+          JSON.stringify({
+            model: "gpt-test",
+            choices: [{ message: { content: "hello" } }],
+            usage: { prompt_tokens: 1, completion_tokens: 2 },
+          }),
+          { status: 200 },
+        );
+      },
+      { preconnect: () => {} },
+    ) as typeof fetch;
+
+    const client = await openOpenaiCompatible({
+      apiKey: "sk-test",
+      model: "gpt-test",
+      baseUrl: "https://example.test/v1",
+      fetch: fetchFn,
+    });
+
+    const chat = await client.complete({
+      messages: [{ role: "user", content: "hi" }],
+    });
+    expect(chat.text).toBe("hello");
+    expect(chat.driverId).toBe("openai-compatible");
+
+    const emb = await client.embed!({ input: "hi" });
+    expect(emb.vectors[0]).toEqual([0.1, 0.2]);
+    expect(paths.some((p) => p.endsWith("/chat/completions"))).toBe(true);
+    expect(paths.some((p) => p.endsWith("/embeddings"))).toBe(true);
+  });
+
+  test("requires apiKey", async () => {
+    const prev = process.env.OPENAI_API_KEY;
+    delete process.env.OPENAI_API_KEY;
+    try {
+      await expect(openOpenaiCompatible({})).rejects.toThrow("apiKey");
+    } finally {
+      if (prev !== undefined) process.env.OPENAI_API_KEY = prev;
+    }
+  });
+});

package/src/drivers/ai-types.ts

@@ -0,0 +1,83 @@
+/**
+ * Protocol-named AI model driver contracts.
+ *
+ * Driver ids: `mock` · `anthropic` · `openai-compatible` · `bedrock` · `vertex` · `ollama`.
+ * Dev default is `mock`. There is **no** production default — prod must declare.
+ */
+
+/** Protocol ids for AI model drivers. */
+export type AiDriverId =
+  | "mock"
+  | "anthropic"
+  | "openai-compatible"
+  | "bedrock"
+  | "vertex"
+  | "ollama";
+
+/** One chat / completion turn. */
+export interface AiMessage {
+  readonly role: "system" | "user" | "assistant" | "tool";
+  readonly content: string;
+  readonly name?: string;
+}
+
+/** Options for a model completion. */
+export interface AiCompleteOptions {
+  readonly messages: readonly AiMessage[];
+  readonly model?: string;
+  readonly temperature?: number;
+  readonly maxTokens?: number;
+  /** Structured output hint (JSON schema or name). */
+  readonly responseFormat?: unknown;
+}
+
+/** Result of a model completion. */
+export interface AiCompleteResult {
+  readonly text: string;
+  readonly raw?: unknown;
+  readonly model: string;
+  readonly driverId: AiDriverId;
+  readonly usage?: {
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly cost?: number;
+  };
+}
+
+/** Embedding request. */
+export interface AiEmbedOptions {
+  readonly input: string | readonly string[];
+  readonly model?: string;
+}
+
+/** Embedding result. */
+export interface AiEmbedResult {
+  readonly vectors: readonly (readonly number[])[];
+  readonly model: string;
+  readonly driverId: AiDriverId;
+}
+
+/** Opened model client. */
+export interface AiModelClient {
+  readonly driverId: AiDriverId;
+  readonly model: string;
+  complete(options: AiCompleteOptions): Promise<AiCompleteResult>;
+  embed?(options: AiEmbedOptions): Promise<AiEmbedResult>;
+  close?(): Promise<void>;
+}
+
+/** Options when opening a model driver. */
+export interface AiOpenOptions {
+  readonly model?: string;
+  readonly apiKey?: string;
+  readonly baseUrl?: string;
+  /** Mock canned responses keyed by prompt name or substring. */
+  readonly mockResponses?: Readonly<Record<string, unknown>>;
+  readonly fetch?: typeof globalThis.fetch;
+}
+
+/** AI model driver factory. */
+export interface AiDriver {
+  readonly id: AiDriverId;
+  open(options?: AiOpenOptions): Promise<AiModelClient>;
+}