okengine 0.5.1 → 0.6.0

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;
+}

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

@@ -1,8 +1,10 @@
 /**
  * `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
+ * One protocol driver for OpenAI, Groq, Together, OpenRouter, vLLM, LM Studio,
+ * Ollama `/v1`, and other chat/completions endpoints. Configure via
+ * `baseUrl` + `apiKey` + `model` (+ optional `headers`). Native Ollama stays
+ * on the separate `ollama` driver. Injectable `fetch` for tests. Never a
  * production default — prod must declare.
  */
 
@@ -14,23 +16,67 @@ import type {
   AiEmbedResult,
   AiModelClient,
   AiOpenOptions,
+  AiStreamChunk,
+  AiToolCall,
 } from "./ai-types.ts";
 
-const DEFAULT_BASE = "https://api.openai.com/v1";
+/** Default OpenAI cloud base — apiKey is required for this origin. */
+export const OPENAI_COMPAT_DEFAULT_BASE = "https://api.openai.com/v1";
+
+/**
+ * Normalize a chat/embeddings base URL (strip trailing slash).
+ *
+ * @param raw - Base URL
+ */
+export function normalizeOpenaiCompatibleBaseUrl(raw: string): string {
+  return raw.trim().replace(/\/$/, "");
+}
+
+/**
+ * Whether this base is the OpenAI cloud default (key required).
+ *
+ * @param baseUrl - Normalized base
+ */
+export function isOpenaiCloudBase(baseUrl: string): boolean {
+  return normalizeOpenaiCompatibleBaseUrl(baseUrl) === OPENAI_COMPAT_DEFAULT_BASE;
+}
+
+/**
+ * Build request headers: content-type, optional Bearer, optional extras.
+ *
+ * @param apiKey - Bearer token when present
+ * @param extra - Caller headers
+ */
+export function openaiCompatibleHeaders(
+  apiKey: string | undefined,
+  extra?: Readonly<Record<string, string>>,
+): Record<string, string> {
+  const headers: Record<string, string> = {
+    "content-type": "application/json",
+    ...(extra ?? {}),
+  };
+  if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+  return headers;
+}
 
 /**
  * Open an OpenAI-compatible chat / embeddings client.
  *
- * @param options - API key / model / base URL / injectable fetch
+ * apiKey is required for the default OpenAI cloud base. Custom `baseUrl`
+ * (LM Studio, Ollama `/v1`, Groq, …) may omit the key — Authorization is
+ * then omitted. HTTP failures always throw (never silent mock fallback).
+ *
+ * @param options - API key / model / base URL / headers / injectable fetch
  */
 export async function openOpenaiCompatible(options: AiOpenOptions = {}): Promise<AiModelClient> {
+  const baseUrl = normalizeOpenaiCompatibleBaseUrl(options.baseUrl ?? OPENAI_COMPAT_DEFAULT_BASE);
   const apiKey = options.apiKey ?? process.env.OPENAI_API_KEY;
-  if (!apiKey) {
+  if (isOpenaiCloudBase(baseUrl) && !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;
+  const extraHeaders = options.headers;
 
   return {
     driverId: "openai-compatible",
@@ -39,52 +85,82 @@ export async function openOpenaiCompatible(options: AiOpenOptions = {}): Promise
       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 } : {}),
-        })),
+        messages: opts.messages.map(serializeMessage),
       };
       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;
       }
+      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 } : {}),
+          },
+        }));
+      }
 
       const res = await fetchFn(`${baseUrl}/chat/completions`, {
         method: "POST",
-        headers: {
-          "content-type": "application/json",
-          Authorization: `Bearer ${apiKey}`,
-        },
+        headers: openaiCompatibleHeaders(apiKey, extraHeaders),
         body: JSON.stringify(body),
+        ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
       });
       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 ?? "";
+      const message = raw.choices?.[0]?.message;
+      const text = message?.content ?? "";
+      const toolCalls = parseToolCalls(message?.tool_calls);
       return {
         text,
         raw,
         model: raw.model ?? resolvedModel,
         driverId: "openai-compatible",
+        ...(toolCalls !== undefined ? { toolCalls } : {}),
         usage: {
           inputTokens: raw.usage?.prompt_tokens,
           outputTokens: raw.usage?.completion_tokens,
         },
       };
     },
+    async *stream(opts: AiCompleteOptions): AsyncIterable<AiStreamChunk> {
+      const resolvedModel = opts.model ?? model;
+      const body: Record<string, unknown> = {
+        model: resolvedModel,
+        messages: opts.messages.map(serializeMessage),
+        stream: true,
+      };
+      if (opts.temperature !== undefined) body.temperature = opts.temperature;
+      if (opts.maxTokens !== undefined) body.max_tokens = opts.maxTokens;
+
+      const res = await fetchFn(`${baseUrl}/chat/completions`, {
+        method: "POST",
+        headers: openaiCompatibleHeaders(apiKey, extraHeaders),
+        body: JSON.stringify(body),
+        ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
+      });
+      if (!res.ok) {
+        const raw = (await res.json().catch(() => ({}))) as OpenAiChatResponse;
+        const msg = raw.error?.message ?? `openai-compatible HTTP ${res.status}`;
+        throw new Error(`openai-compatible: ${msg}`);
+      }
+      if (!res.body) {
+        throw new Error("openai-compatible: stream response has no body");
+      }
+      yield* readOpenaiSse(res.body, opts.signal);
+    },
     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}`,
-        },
+        headers: openaiCompatibleHeaders(apiKey, extraHeaders),
         body: JSON.stringify({ model: resolvedModel, input }),
       });
       const raw = (await res.json().catch(() => ({}))) as OpenAiEmbedResponse;
@@ -111,10 +187,124 @@ export const openaiCompatibleAiDriver: AiDriver = {
   open: openOpenaiCompatible,
 };
 
+function serializeMessage(m: AiCompleteOptions["messages"][number]): Record<string, unknown> {
+  const out: Record<string, unknown> = {
+    role: m.role,
+    content: m.content,
+  };
+  if (m.name !== undefined) out.name = m.name;
+  if (m.toolCallId !== undefined) out.tool_call_id = m.toolCallId;
+  if (m.toolCalls !== undefined && m.toolCalls.length > 0) {
+    out.tool_calls = m.toolCalls.map((tc) => ({
+      id: tc.id,
+      type: "function",
+      function: {
+        name: tc.name,
+        arguments:
+          typeof tc.arguments === "string" ? tc.arguments : JSON.stringify(tc.arguments ?? {}),
+      },
+    }));
+  }
+  return out;
+}
+
+function parseToolCalls(
+  raw: readonly OpenAiToolCall[] | undefined,
+): readonly AiToolCall[] | undefined {
+  if (!raw || raw.length === 0) return undefined;
+  return raw.map((tc, i) => {
+    const name = tc.function?.name ?? "";
+    const argStr = tc.function?.arguments ?? "{}";
+    let args: unknown = argStr;
+    try {
+      args = JSON.parse(argStr) as unknown;
+    } catch {
+      args = { _raw: argStr };
+    }
+    return {
+      id: tc.id ?? `call_${i}`,
+      name,
+      arguments: args,
+    };
+  });
+}
+
+/**
+ * Parse OpenAI SSE chat.completion.chunk stream.
+ *
+ * @param body - Response body
+ * @param signal - Optional abort
+ */
+async function* readOpenaiSse(
+  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.startsWith("data:")) continue;
+        const data = trimmed.slice(5).trim();
+        if (data === "[DONE]") {
+          yield { text: "", done: true };
+          return;
+        }
+        try {
+          const chunk = JSON.parse(data) as {
+            choices?: readonly {
+              delta?: { content?: string | null };
+              finish_reason?: string | null;
+            }[];
+          };
+          const delta = chunk.choices?.[0]?.delta?.content;
+          if (typeof delta === "string" && delta.length > 0) {
+            yield { text: delta };
+          }
+          if (chunk.choices?.[0]?.finish_reason) {
+            yield { text: "", done: true };
+            return;
+          }
+        } catch {
+          // ignore malformed SSE lines
+        }
+      }
+    }
+    yield { text: "", done: true };
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+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 OpenAiToolCall {
+  readonly id?: string;
+  readonly function?: { readonly name?: string; readonly arguments?: string };
+}
+
 interface OpenAiChatResponse {
   readonly model?: string;
   readonly choices?: readonly {
-    readonly message?: { readonly content?: string | null };
+    readonly message?: {
+      readonly content?: string | null;
+      readonly tool_calls?: readonly OpenAiToolCall[];
+    };
   }[];
   readonly usage?: {
     readonly prompt_tokens?: number;