okengine 0.5.0 → 0.6.0

package/src/drivers/ai-ollama.integration.test.ts

@@ -0,0 +1,197 @@
+/**
+ * Live Ollama round-trip — real prompt, real response, documented default model.
+ *
+ * Opt-in (never auto-pull a multi-GB model in ordinary `bun test`):
+ * 1. `OKE_TEST_OLLAMA_URL` — point at any reachable Ollama
+ * 2. Ollama already listening on `http://127.0.0.1:11434`
+ * 3. `OKE_TEST_OLLAMA_DOCKER=1` — start `ollama/ollama` via the recipe and pull
+ *    `qwen3.5:9b` (slow first run)
+ *
+ * Without one of those, the suite skips with a visible reason (never an empty pass).
+ */
+
+import { afterAll, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { deriveInfrastructure, writeDerivedFiles } from "../docker/index.ts";
+import { ai } from "../elements/ai.ts";
+import { bindAi } from "../kernel/boot-bind/ai.ts";
+import { OLLAMA_DEFAULT_MODEL, openOllama } from "./ai-ollama.ts";
+
+const OLLAMA_IMAGE = "ollama/ollama:latest";
+const DEFAULT_LOCAL = "http://127.0.0.1:11434";
+const ENV_URL = process.env.OKE_TEST_OLLAMA_URL?.trim();
+const WANT_DOCKER = process.env.OKE_TEST_OLLAMA_DOCKER === "1";
+
+function dockerAvailable(): boolean {
+  try {
+    return Bun.spawnSync(["docker", "info"], { stdout: "pipe", stderr: "pipe" }).exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+async function probeOllama(url: string): Promise<boolean> {
+  try {
+    const res = await fetch(`${url}/api/tags`, { signal: AbortSignal.timeout(1_500) });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+const DOCKER = dockerAvailable();
+const localUp = ENV_URL ? false : await probeOllama(DEFAULT_LOCAL);
+const canLive = Boolean(ENV_URL) || localUp || (WANT_DOCKER && DOCKER);
+
+if (!canLive) {
+  const reasons: string[] = [];
+  if (!ENV_URL) reasons.push("OKE_TEST_OLLAMA_URL not set");
+  if (!localUp) reasons.push("no Ollama on :11434");
+  if (!WANT_DOCKER) reasons.push("OKE_TEST_OLLAMA_DOCKER≠1");
+  else if (!DOCKER) reasons.push("docker daemon not available");
+  console.log(`skip: live ollama e2e (${reasons.join("; ")})`);
+}
+const live = canLive ? test : test.skip;
+
+let cleanup: (() => Promise<void>) | undefined;
+
+afterAll(async () => {
+  if (cleanup) await cleanup();
+});
+
+async function waitForOllama(url: string, timeoutMs: number, requireModel: boolean): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`${url}/api/tags`);
+      if (res.ok) {
+        if (!requireModel) return;
+        const body = (await res.json()) as { models?: readonly { name?: string }[] };
+        const names = (body.models ?? []).map((m) => m.name ?? "");
+        if (
+          names.some((n) => n === OLLAMA_DEFAULT_MODEL || n.startsWith(`${OLLAMA_DEFAULT_MODEL}`))
+        ) {
+          return;
+        }
+      }
+    } catch {
+      // still starting
+    }
+    await Bun.sleep(1_000);
+  }
+  throw new Error(
+    `ollama not ready at ${url} within ${timeoutMs}ms${
+      requireModel ? ` (need model ${OLLAMA_DEFAULT_MODEL})` : ""
+    }`,
+  );
+}
+
+async function resolveLiveUrl(): Promise<{ url: string; model: string }> {
+  if (ENV_URL) {
+    await waitForOllama(ENV_URL, 30_000, false);
+    return { url: ENV_URL, model: process.env.OKE_AI_MODEL?.trim() || OLLAMA_DEFAULT_MODEL };
+  }
+
+  if (localUp) {
+    return { url: DEFAULT_LOCAL, model: process.env.OKE_AI_MODEL?.trim() || OLLAMA_DEFAULT_MODEL };
+  }
+
+  const dir = await mkdtemp(join(tmpdir(), "oke-ollama-"));
+  const dockerDir = join(dir, "docker");
+  const project = `oke-ollama-${Date.now()}`;
+  const instanceId = crypto.randomUUID().replace(/-/g, "").slice(0, 6);
+  const derived = deriveInfrastructure({
+    images: { ai: OLLAMA_IMAGE },
+    app: "ollama-e2e",
+    host: "127.0.0.1",
+    includeApp: false,
+    composeDir: "docker",
+    instanceId,
+    controls: { OKE_AI_MODEL: OLLAMA_DEFAULT_MODEL },
+  });
+  await writeDerivedFiles(derived, dockerDir, { writeStackEnv: true });
+
+  const composeFiles = ["compose.yml", "compose.ai.yml"];
+  const up = Bun.spawn(
+    ["docker", "compose", "-p", project, ...composeFiles.flatMap((f) => ["-f", f]), "up", "-d"],
+    {
+      cwd: dockerDir,
+      stdout: "pipe",
+      stderr: "pipe",
+      env: { ...process.env, ...derived.stackEnv, OKE_AI_MODEL: OLLAMA_DEFAULT_MODEL },
+    },
+  );
+  const [upErr, upCode] = await Promise.all([new Response(up.stderr).text(), up.exited]);
+  if (upCode !== 0) {
+    await rm(dir, { recursive: true, force: true });
+    throw new Error(`docker compose up failed: ${upErr}`);
+  }
+
+  const url = derived.stackEnv.OKE_AI_URL!;
+  cleanup = async () => {
+    const down = Bun.spawn(
+      ["docker", "compose", "-p", project, ...composeFiles.flatMap((f) => ["-f", f]), "down", "-v"],
+      { cwd: dockerDir, stdout: "pipe", stderr: "pipe" },
+    );
+    await down.exited;
+    await rm(dir, { recursive: true, force: true });
+  };
+
+  // Model pull can take a long time on first run.
+  await waitForOllama(url, 20 * 60_000, true);
+  return { url, model: OLLAMA_DEFAULT_MODEL };
+}
+
+describe("ollama live — real completion", () => {
+  live(
+    "boots against a real Ollama, completes with a real model, returns a real response",
+    async () => {
+      const { url, model } = await resolveLiveUrl();
+      const prevUrl = process.env.OKE_AI_URL;
+      const prevModel = process.env.OKE_AI_MODEL;
+      process.env.OKE_AI_URL = url;
+      process.env.OKE_AI_MODEL = model;
+
+      try {
+        const smart = ai.model("smart", { provider: "ollama", model });
+        const ping = smart.prompt("ollama-ping", { version: 1 });
+
+        const runtime = bindAi(
+          {
+            config: { drivers: { ai: { local: "ollama", test: "ollama" } } },
+            ai: { models: [smart], prompts: [ping] },
+          },
+          undefined,
+          () => Date.now(),
+          "local",
+          false,
+        );
+        expect(runtime.prompts.has("ollama-ping")).toBe(true);
+
+        const client = await openOllama({ baseUrl: url, model });
+        const result = await client.complete({
+          messages: [
+            {
+              role: "user",
+              content: "Reply with exactly the single word: pong",
+            },
+          ],
+          temperature: 0,
+          maxTokens: 32,
+        });
+
+        expect(result.driverId).toBe("ollama");
+        expect(result.text.trim().length).toBeGreaterThan(0);
+        expect(result.text.toLowerCase()).toContain("pong");
+      } finally {
+        if (prevUrl === undefined) delete process.env.OKE_AI_URL;
+        else process.env.OKE_AI_URL = prevUrl;
+        if (prevModel === undefined) delete process.env.OKE_AI_MODEL;
+        else process.env.OKE_AI_MODEL = prevModel;
+      }
+    },
+    25 * 60_000,
+  );
+});

package/src/drivers/ai-ollama.ts

@@ -0,0 +1,327 @@
+/**
+ * `ollama` AI driver — thin fetch client for the native Ollama HTTP API.
+ *
+ * Any pulled model works via `model` / `OKE_AI_MODEL`. The documented local-dev
+ * default is `qwen3.5:9b` (balanced starting point — override freely; on Apple
+ * Silicon consider `qwen3.5:9b-mlx`). Fail-loud:
+ * configured but unreachable throws {@link OllamaUnavailableError} — never a
+ * silent mock fallback.
+ *
+ * Native API: `POST /api/chat` (not the OpenAI-compat shim). Default base URL
+ * `http://127.0.0.1:11434`. Supports `complete`, `stream` (NDJSON), and tools.
+ */
+
+import type {
+  AiCompleteOptions,
+  AiCompleteResult,
+  AiDriver,
+  AiModelClient,
+  AiOpenOptions,
+  AiStreamChunk,
+  AiToolCall,
+} from "./ai-types.ts";
+
+/** Documented local-dev default — override via `model` / `OKE_AI_MODEL`. */
+export const OLLAMA_DEFAULT_MODEL = "qwen3.5:9b";
+
+/** Default Ollama listen URL (host installs + compose host port). */
+export const OLLAMA_DEFAULT_BASE_URL = "http://127.0.0.1:11434";
+
+/** Error thrown when Ollama is unreachable / unhealthy / rejects a call. */
+export class OllamaUnavailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "OllamaUnavailableError";
+  }
+}
+
+/**
+ * Normalize a base URL or bare `host:port` (as in `OLLAMA_HOST`) to an origin.
+ *
+ * @param raw - URL or host:port
+ */
+export function normalizeOllamaBaseUrl(raw: string): string {
+  const trimmed = raw.trim().replace(/\/$/, "");
+  if (!trimmed) return OLLAMA_DEFAULT_BASE_URL;
+  if (/^https?:\/\//i.test(trimmed)) return trimmed.replace(/\/v1\/?$/i, "");
+  return `http://${trimmed}`;
+}
+
+/**
+ * Resolve the Ollama base URL from options / env (never invent a cloud endpoint).
+ *
+ * @param options - Open options
+ */
+export function resolveOllamaBaseUrl(options: AiOpenOptions = {}): string {
+  const raw =
+    options.baseUrl?.trim() ||
+    process.env.OKE_AI_URL?.trim() ||
+    process.env.OLLAMA_HOST?.trim() ||
+    OLLAMA_DEFAULT_BASE_URL;
+  return normalizeOllamaBaseUrl(raw);
+}
+
+/**
+ * Resolve the model name — fully configurable; documented default only.
+ *
+ * @param options - Open options
+ * @param override - Per-call model override
+ */
+export function resolveOllamaModel(options: AiOpenOptions = {}, override?: string): string {
+  return (
+    override?.trim() ||
+    options.model?.trim() ||
+    process.env.OKE_AI_MODEL?.trim() ||
+    OLLAMA_DEFAULT_MODEL
+  );
+}
+
+/**
+ * Open an Ollama chat client. Health-checks `/api/tags` before returning.
+ *
+ * @param options - model / baseUrl / injectable fetch
+ */
+export async function openOllama(options: AiOpenOptions = {}): Promise<AiModelClient> {
+  const baseUrl = resolveOllamaBaseUrl(options);
+  const model = resolveOllamaModel(options);
+  const fetchFn = options.fetch ?? globalThis.fetch;
+
+  await healthCheck(baseUrl, fetchFn);
+
+  return {
+    driverId: "ollama",
+    model,
+    async complete(opts: AiCompleteOptions): Promise<AiCompleteResult> {
+      const resolvedModel = resolveOllamaModel(options, opts.model);
+      const body = buildChatBody(resolvedModel, opts, false);
+
+      let res: Response;
+      try {
+        res = await fetchFn(`${baseUrl}/api/chat`, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify(body),
+          ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
+        });
+      } catch (err) {
+        if (isAbortError(err)) throw err;
+        throw new OllamaUnavailableError(
+          `ollama: unreachable at ${baseUrl} — ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+
+      const raw = (await res.json().catch(() => ({}))) as OllamaChatResponse;
+      if (!res.ok) {
+        const msg = raw.error ?? `ollama HTTP ${res.status}`;
+        throw new OllamaUnavailableError(`ollama: ${msg}`);
+      }
+
+      const text = raw.message?.content ?? "";
+      const toolCalls = parseOllamaToolCalls(raw.message?.tool_calls);
+      return {
+        text,
+        raw,
+        model: raw.model ?? resolvedModel,
+        driverId: "ollama",
+        ...(toolCalls !== undefined ? { toolCalls } : {}),
+        usage: {
+          inputTokens: raw.prompt_eval_count,
+          outputTokens: raw.eval_count,
+        },
+      };
+    },
+    async *stream(opts: AiCompleteOptions): AsyncIterable<AiStreamChunk> {
+      const resolvedModel = resolveOllamaModel(options, opts.model);
+      const body = buildChatBody(resolvedModel, opts, true);
+
+      let res: Response;
+      try {
+        res = await fetchFn(`${baseUrl}/api/chat`, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify(body),
+          ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
+        });
+      } catch (err) {
+        if (isAbortError(err)) throw err;
+        throw new OllamaUnavailableError(
+          `ollama: unreachable at ${baseUrl} — ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+      if (!res.ok) {
+        const raw = (await res.json().catch(() => ({}))) as OllamaChatResponse;
+        const msg = raw.error ?? `ollama HTTP ${res.status}`;
+        throw new OllamaUnavailableError(`ollama: ${msg}`);
+      }
+      if (!res.body) {
+        throw new OllamaUnavailableError("ollama: stream response has no body");
+      }
+      yield* readOllamaNdjson(res.body, opts.signal);
+    },
+  };
+}
+
+/** Protocol-named ollama driver. */
+export const ollamaAiDriver: AiDriver = {
+  id: "ollama",
+  open: openOllama,
+};
+
+function buildChatBody(
+  resolvedModel: string,
+  opts: AiCompleteOptions,
+  stream: boolean,
+): Record<string, unknown> {
+  const body: Record<string, unknown> = {
+    model: resolvedModel,
+    messages: opts.messages.map((m) => {
+      const msg: Record<string, unknown> = {
+        role: m.role,
+        content: m.content,
+      };
+      if (m.name !== undefined) msg.name = m.name;
+      if (m.toolCalls !== undefined && m.toolCalls.length > 0) {
+        msg.tool_calls = m.toolCalls.map((tc) => ({
+          type: "function",
+          function: {
+            name: tc.name,
+            arguments: tc.arguments,
+          },
+        }));
+      }
+      return msg;
+    }),
+    stream,
+    // Thinking models (e.g. qwen3 / qwen3.5) otherwise spend the token budget in
+    // `message.thinking` and leave `content` empty — baseline complete
+    // wants the answer text.
+    think: false,
+  };
+  const modelOptions: Record<string, unknown> = {};
+  if (opts.temperature !== undefined) modelOptions.temperature = opts.temperature;
+  if (opts.maxTokens !== undefined) modelOptions.num_predict = opts.maxTokens;
+  if (Object.keys(modelOptions).length > 0) body.options = modelOptions;
+  if (opts.responseFormat !== undefined) body.format = opts.responseFormat;
+  if (opts.tools !== undefined && opts.tools.length > 0) {
+    body.tools = opts.tools.map((t) => ({
+      type: "function",
+      function: {
+        name: t.name,
+        ...(t.description !== undefined ? { description: t.description } : {}),
+        ...(t.parameters !== undefined ? { parameters: t.parameters } : {}),
+      },
+    }));
+  }
+  return body;
+}
+
+function parseOllamaToolCalls(
+  raw: readonly OllamaToolCall[] | undefined,
+): readonly AiToolCall[] | undefined {
+  if (!raw || raw.length === 0) return undefined;
+  return raw.map((tc, i) => ({
+    id: `ollama_call_${i}`,
+    name: tc.function?.name ?? "",
+    arguments: tc.function?.arguments ?? {},
+  }));
+}
+
+/**
+ * Parse Ollama NDJSON stream lines.
+ *
+ * @param body - Response body
+ * @param signal - Optional abort
+ */
+async function* readOllamaNdjson(
+  body: ReadableStream<Uint8Array>,
+  signal?: AbortSignal,
+): AsyncGenerator<AiStreamChunk> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      if (signal?.aborted) {
+        throw abortAsError(signal.reason);
+      }
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        try {
+          const chunk = JSON.parse(trimmed) as OllamaChatResponse;
+          const delta = chunk.message?.content;
+          if (typeof delta === "string" && delta.length > 0) {
+            yield { text: delta };
+          }
+          if (chunk.done) {
+            yield { text: "", done: true };
+            return;
+          }
+        } catch {
+          // ignore malformed lines
+        }
+      }
+    }
+    yield { text: "", done: true };
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+/**
+ * Probe Ollama — fail loud before the first completion.
+ *
+ * @param baseUrl - Origin
+ * @param fetchFn - Injectable fetch
+ */
+async function healthCheck(baseUrl: string, fetchFn: typeof globalThis.fetch): Promise<void> {
+  let res: Response;
+  try {
+    res = await fetchFn(`${baseUrl}/api/tags`, { method: "GET" });
+  } catch (err) {
+    throw new OllamaUnavailableError(
+      `ollama: unreachable at ${baseUrl} — ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "");
+    throw new OllamaUnavailableError(
+      `ollama: health check failed at ${baseUrl}/api/tags (${res.status})${
+        detail ? ` — ${detail.slice(0, 200)}` : ""
+      }`,
+    );
+  }
+}
+
+function isAbortError(err: unknown): boolean {
+  return err instanceof Error && err.name === "AbortError";
+}
+
+function abortAsError(reason?: unknown): Error {
+  if (reason instanceof Error) return reason;
+  const err = new Error(reason !== undefined ? String(reason) : "This operation was aborted");
+  err.name = "AbortError";
+  return err;
+}
+
+interface OllamaToolCall {
+  readonly function?: { readonly name?: string; readonly arguments?: unknown };
+}
+
+interface OllamaChatResponse {
+  readonly model?: string;
+  readonly message?: {
+    readonly role?: string;
+    readonly content?: string;
+    readonly tool_calls?: readonly OllamaToolCall[];
+  };
+  readonly done?: boolean;
+  readonly prompt_eval_count?: number;
+  readonly eval_count?: number;
+  readonly error?: string;
+}