@galdor/provider-openai 0.3.0

package/dist/stream.js

@@ -0,0 +1,178 @@
+/**
+ * OpenAI streaming over Server-Sent Events.
+ *
+ * Decodes each `data: {...}` chunk of the /chat/completions stream into galdor
+ * provider {@link Event}s (MessageStart / ContentDelta / ToolCallDelta /
+ * MessageStop). The OpenAI stream carries no dedicated opening frame, so
+ * MessageStart is synthesized from the first chunk, and MessageStop is deferred
+ * to the end: with `stream_options.include_usage = true` the final usage chunk
+ * arrives after the `finish_reason` chunk. Some OpenAI-compatible backends close
+ * the connection rather than emitting `data: [DONE]`, so the terminal
+ * MessageStop is always synthesized from accumulated state, regardless of how
+ * the stream ends. Consume the generator with `for await`, or fold it into a
+ * single {@link Response} via `collectStream`.
+ */
+import { APIError, EventType, fetchWithHeaderTimeout } from "@galdor/core/provider";
+import { Role, thinkingPart } from "@galdor/core/schema";
+import { normalizeFinishReason, usageFromWire } from "./convert.js";
+import { kindForType, normalizeHTTPError } from "./errors.js";
+const PROVIDER_NAME = "openai";
+function emptyUsage() {
+    return { inputTokens: 0, outputTokens: 0, cacheCreationTokens: 0, cacheReadTokens: 0 };
+}
+/**
+ * POST a streaming /chat/completions request and yield galdor provider events.
+ *
+ * Synthesizes a MessageStart from the first chunk, forwards content and tool-call
+ * deltas as they arrive, accumulates reasoning and usage, and emits a terminal
+ * MessageStop once the upstream stream ends.
+ *
+ * @param url - The fully-qualified /chat/completions endpoint to POST to.
+ * @param headers - Request headers (auth, content-type, etc.); an SSE `Accept`
+ * header is added automatically.
+ * @param body - The request payload, serialized to JSON.
+ * @param signal - Optional abort signal to cancel the in-flight request.
+ * @returns An async generator of provider {@link Event}s ending in MessageStop.
+ * @throws {APIError} When the HTTP response is non-2xx, or when an in-stream
+ * error frame is received.
+ * @throws {Error} When a 2xx response unexpectedly carries no body.
+ * @example
+ * ```ts
+ * for await (const ev of streamChat(url, headers, wire, signal)) {
+ *   if (ev.type === EventType.ContentDelta) process.stdout.write(ev.contentDelta);
+ * }
+ * ```
+ */
+export async function* streamChat(url, headers, body, signal, timeoutMs = 0) {
+    const res = await fetchWithHeaderTimeout(url, { method: "POST", headers: { ...headers, accept: "text/event-stream" }, body: JSON.stringify(body) }, timeoutMs, signal);
+    if (Math.floor(res.status / 100) !== 2)
+        throw await normalizeHTTPError(res);
+    if (!res.body)
+        throw new Error("openai: streaming response had no body");
+    const state = {
+        started: false,
+        model: "",
+        usage: emptyUsage(),
+        stopReason: "end_turn",
+        reasoning: "",
+        toolByIdx: new Map(),
+    };
+    const decoder = new TextDecoder();
+    let buffer = "";
+    for await (const chunk of res.body) {
+        buffer += decoder.decode(chunk, { stream: true });
+        // SSE events are separated by a blank line. Accept both LF and CRLF framing
+        // so OpenAI-compatible backends that emit \r\n boundaries parse cleanly.
+        let m;
+        while ((m = FRAME_BOUNDARY.exec(buffer)) !== null) {
+            const rawEvent = buffer.slice(0, m.index);
+            buffer = buffer.slice(m.index + m[0].length);
+            FRAME_BOUNDARY.lastIndex = 0;
+            const payload = parseDataLine(rawEvent);
+            if (payload === undefined)
+                continue;
+            yield* handleChunk(payload, state);
+        }
+    }
+    // Some backends close the connection without a blank-line-terminated final
+    // frame; if the leftover buffer still holds a data line, process it so the
+    // closing usage/finish chunk is not dropped.
+    const tail = parseDataLine(buffer);
+    if (tail !== undefined)
+        yield* handleChunk(tail, state);
+    yield terminalStop(state);
+}
+/** Matches an SSE blank-line frame boundary under either LF or CRLF framing. */
+const FRAME_BOUNDARY = /\r?\n\r?\n/g;
+/** Extract and JSON-parse the `data:` payload of one SSE event block. */
+function parseDataLine(rawEvent) {
+    const dataParts = [];
+    for (const raw of rawEvent.split("\n")) {
+        const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw; // strip CR under CRLF framing
+        if (line.startsWith(":"))
+            continue; // comment
+        if (line.startsWith("data:"))
+            dataParts.push(line.slice(5).trimStart());
+    }
+    if (dataParts.length === 0)
+        return undefined;
+    const payload = dataParts.join("\n");
+    if (payload === "" || payload === "[DONE]")
+        return undefined;
+    try {
+        return JSON.parse(payload);
+    }
+    catch {
+        // Skip lines that fail to parse — be permissive about transport hiccups.
+        return undefined;
+    }
+}
+function terminalStop(state) {
+    const msg = state.reasoning !== ""
+        ? { role: Role.Assistant, content: [thinkingPart(state.reasoning)] }
+        : undefined;
+    return {
+        type: EventType.MessageStop,
+        stopReason: state.stopReason,
+        usage: state.usage,
+        model: state.model,
+        ...(msg ? { message: msg } : {}),
+    };
+}
+function* handleChunk(c, state) {
+    // Surface an in-stream error frame instead of silently ending the stream.
+    if (c.error) {
+        const kind = kindForType(c.error.type, c.error.code) ?? "server";
+        throw new APIError({ kind, provider: PROVIDER_NAME, statusCode: 0, message: c.error.message ?? "stream error" });
+    }
+    if (c.model)
+        state.model = c.model;
+    if (c.usage)
+        state.usage = usageFromWire(c.usage);
+    // First chunk: synthesize MessageStart, since the stream has no start frame.
+    if (!state.started && (state.model !== "" || (c.choices?.length ?? 0) > 0)) {
+        state.started = true;
+        yield { type: EventType.MessageStart, model: state.model };
+    }
+    const ch = c.choices?.[0];
+    if (!ch)
+        return;
+    if (ch.delta?.reasoning_content) {
+        // Accumulate reasoning; do not forward it on the live stream.
+        state.reasoning += ch.delta.reasoning_content;
+    }
+    if (ch.delta?.content) {
+        yield { type: EventType.ContentDelta, contentDelta: ch.delta.content };
+    }
+    for (const td of ch.delta?.tool_calls ?? []) {
+        const ts = touchToolState(td, state);
+        yield {
+            type: EventType.ToolCallDelta,
+            toolCallDelta: { id: ts.id, name: td.function?.name ?? "", argumentsDelta: td.function?.arguments ?? "" },
+        };
+    }
+    if (ch.finish_reason)
+        state.stopReason = normalizeFinishReason(ch.finish_reason);
+}
+/**
+ * Ensure a ToolState exists for `td.index` (defaulting to 0) and fold any new
+ * id or name from this delta into it. Some OpenAI-compatible backends omit
+ * `tool_call` ids, so a stable id is synthesized from the index to keep the call
+ * from being dropped downstream (collectStream discards id-less tool deltas).
+ */
+function touchToolState(td, state) {
+    const idx = td.index ?? 0;
+    let ts = state.toolByIdx.get(idx);
+    if (!ts) {
+        ts = { id: "", name: "" };
+        state.toolByIdx.set(idx, ts);
+    }
+    if (td.id)
+        ts.id = td.id;
+    if (td.function?.name)
+        ts.name = td.function.name;
+    if (ts.id === "")
+        ts.id = `call_${idx}`;
+    return ts;
+}
+//# sourceMappingURL=stream.js.map

package/dist/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../src/stream.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@galdor/provider-openai",
+  "version": "0.3.0",
+  "type": "module",
+  "description": "OpenAI (Chat Completions API) provider adapter for galdor-bun. Also targets OpenAI-compatible endpoints (Groq, Together, MiniMax, Mistral, DeepSeek, vLLM, Ollama, ...) via baseURL.",
+  "author": {
+    "name": "Yasser Rosas",
+    "email": "yassros16@gmail.com"
+  },
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "engines": {
+    "node": ">=22.5",
+    "bun": ">=1.3"
+  },
+  "dependencies": {
+    "@galdor/core": "0.3.0"
+  }
+}

package/src/convert.ts

@@ -0,0 +1,429 @@
+/**
+ * Conversion between galdor's shared schema and the OpenAI Chat Completions API
+ * wire shape.
+ *
+ * On the wire OpenAI carries the system prompt as a `role: system` message and
+ * tool results as `role: tool` messages keyed by `tool_call_id`. The wire types
+ * declared below model OpenAI's snake_case JSON exactly. The two entry points are
+ * {@link buildRequest} (galdor request to wire request) and
+ * {@link responseFromWire} (wire response to galdor response).
+ */
+
+import { InvalidRequestError, type Request, type Response } from "@galdor/core/provider";
+import {
+  ContentType,
+  type ContentPart,
+  type ImageContent,
+  type JSONValue,
+  type Message,
+  messageText,
+  Role,
+  type StopReason,
+  textPart,
+  thinkingPart,
+  type ToolCall,
+} from "@galdor/core/schema";
+
+/** Build a typed invalid-request error for a request that cannot be lowered to the wire. */
+function invalidRequest(message: string): InvalidRequestError {
+  return new InvalidRequestError({ kind: "invalid_request", provider: "openai", statusCode: 0, message });
+}
+
+// ── Wire types (OpenAI JSON, snake_case) ─────────────────────────────────────
+
+interface WireImageURL {
+  url: string;
+  detail?: string;
+}
+
+interface WireContentPart {
+  type: string;
+  text?: string;
+  image_url?: WireImageURL;
+}
+
+interface WireFuncCall {
+  name?: string;
+  arguments?: string;
+}
+
+interface WireToolCall {
+  id?: string;
+  type?: string;
+  function: WireFuncCall;
+  /** Only set on streaming deltas. */
+  index?: number;
+}
+
+interface WireMessage {
+  role: string;
+  content?: string | WireContentPart[];
+  name?: string;
+  tool_calls?: WireToolCall[];
+  tool_call_id?: string;
+  /** Reasoning from OpenAI-compatible models (e.g. DeepSeek-R1). Inbound only. */
+  reasoning_content?: string;
+}
+
+interface WireFuncDecl {
+  name: string;
+  description?: string;
+  parameters: unknown;
+}
+
+interface WireTool {
+  type: string;
+  function: WireFuncDecl;
+}
+
+interface WireJSONSchema {
+  name?: string;
+  strict?: boolean;
+  schema: unknown;
+}
+
+interface WireRespFormat {
+  type: string;
+  json_schema?: WireJSONSchema;
+}
+
+/** Serialized request body for the OpenAI /chat/completions endpoint. */
+export interface ChatRequest {
+  model: string;
+  messages: WireMessage[];
+  max_tokens?: number;
+  max_completion_tokens?: number;
+  temperature?: number;
+  top_p?: number;
+  stop?: string[];
+  stream?: boolean;
+  stream_options?: { include_usage: boolean };
+  tools?: WireTool[];
+  tool_choice?: string;
+  response_format?: WireRespFormat;
+  reasoning_effort?: string;
+  user?: string;
+}
+
+interface WireTokenDetails {
+  cached_tokens?: number;
+}
+
+/** Token accounting block as returned by OpenAI, in its snake_case form. */
+export interface WireUsage {
+  prompt_tokens?: number;
+  completion_tokens?: number;
+  total_tokens?: number;
+  prompt_tokens_details?: WireTokenDetails;
+}
+
+interface WireResponseMessage {
+  role?: string;
+  content?: string | WireContentPart[];
+  tool_calls?: WireToolCall[];
+  reasoning_content?: string;
+}
+
+interface WireChoice {
+  index?: number;
+  message: WireResponseMessage;
+  finish_reason?: string;
+}
+
+/** Decoded body of a non-streaming OpenAI /chat/completions response. */
+export interface ChatResponse {
+  id?: string;
+  object?: string;
+  created?: number;
+  model?: string;
+  choices?: WireChoice[];
+  usage?: WireUsage;
+}
+
+// ── Request building ─────────────────────────────────────────────────────────
+
+function toBase64(data: Uint8Array): string {
+  return Buffer.from(data).toString("base64");
+}
+
+/** Render an image part as OpenAI's image_url.url (direct URL or data: URL). */
+function imageToURL(img: ImageContent): string {
+  if (img.url && img.url !== "") return img.url;
+  if (img.data && img.data.length > 0) {
+    if (!img.media) throw invalidRequest("openai: inline image missing media (MIME type)");
+    return `data:${img.media};base64,${toBase64(img.data)}`;
+  }
+  throw invalidRequest("openai: image part with no url or data");
+}
+
+function partsToWire(parts: ContentPart[]): WireContentPart[] {
+  const out: WireContentPart[] = [];
+  for (const p of parts) {
+    switch (p.type) {
+      case ContentType.Text:
+        out.push({ type: "text", text: p.text ?? "" });
+        break;
+      case ContentType.Image:
+        if (!p.image) throw invalidRequest("openai: image part with nil image");
+        out.push({ type: "image_url", image_url: { url: imageToURL(p.image) } });
+        break;
+      case ContentType.Thinking:
+      case ContentType.RedactedThinking:
+        // Reasoning is model output, not input: never echo it back.
+        continue;
+      default:
+        throw invalidRequest(`openai: unsupported content type ${p.type}`);
+    }
+  }
+  return out;
+}
+
+function roleToWire(r: Role): string {
+  switch (r) {
+    case Role.System:
+      return "system";
+    case Role.User:
+      return "user";
+    case Role.Assistant:
+      return "assistant";
+    case Role.Tool:
+      return "tool";
+    default:
+      throw invalidRequest(`openai: unknown role ${r}`);
+  }
+}
+
+function messageToWire(m: Message): WireMessage {
+  const wm: WireMessage = { role: roleToWire(m.role) };
+  if (m.name) wm.name = m.name;
+  if (m.toolCallId) wm.tool_call_id = m.toolCallId;
+
+  // Assistant tool calls.
+  const toolCalls: WireToolCall[] = [];
+  for (const tc of m.toolCalls ?? []) {
+    toolCalls.push({
+      id: tc.id,
+      type: "function",
+      function: { name: tc.name, arguments: stringifyArguments(tc.arguments) },
+    });
+  }
+  if (toolCalls.length > 0) wm.tool_calls = toolCalls;
+
+  // Content. Prefer the plain-string form when all parts are text; use the
+  // array form when any non-text part is present.
+  const allText = m.content.every((p) => p.type === ContentType.Text);
+  if (m.content.length === 0 && toolCalls.length > 0) {
+    // Assistant tool-call-only messages omit content.
+  } else if (allText) {
+    wm.content = messageText(m);
+  } else {
+    wm.content = partsToWire(m.content);
+  }
+
+  return wm;
+}
+
+function stringifyArguments(args: JSONValue): string {
+  if (args === undefined || args === null) return "{}";
+  if (typeof args === "string") return args;
+  return JSON.stringify(args);
+}
+
+function toolChoiceToWire(c: Request["toolChoice"]): string | undefined {
+  switch (c) {
+    case "auto":
+      return "auto";
+    case "none":
+      return "none";
+    case "required":
+      return "required";
+    default:
+      return undefined;
+  }
+}
+
+function responseFormatToWire(rf: Request["responseFormat"]): WireRespFormat | undefined {
+  if (!rf) return undefined;
+  switch (rf.type) {
+    case "json_object":
+      return { type: "json_object" };
+    case "json_schema":
+      return {
+        type: "json_schema",
+        json_schema: { ...(rf.name ? { name: rf.name } : {}), strict: true, schema: rf.schema },
+      };
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Translate a galdor {@link Request} into an OpenAI Chat Completions wire
+ * request.
+ *
+ * Maps messages, tools, tool choice and response format; toggles
+ * `stream`/`stream_options` for streaming; and applies o-series reasoning rules,
+ * where the effort level is set and `max_tokens` is moved to
+ * `max_completion_tokens` while `temperature` and `top_p` are dropped (those
+ * models reject them).
+ *
+ * @param req - The provider-neutral galdor request to translate.
+ * @param stream - When true, request a streamed response with usage included.
+ * @returns The wire-ready {@link ChatRequest}.
+ * @throws {Error} When `req.model` is empty, or a message contains an unknown
+ * role or unsupported content type.
+ * @example
+ * ```ts
+ * const wire = buildRequest({ model: "gpt-4o-mini", messages }, false);
+ * ```
+ */
+export function buildRequest(req: Request, stream: boolean): ChatRequest {
+  if (req.model === "") throw invalidRequest("openai: model is required");
+
+  const out: ChatRequest = { model: req.model, messages: req.messages.map(messageToWire) };
+  if (req.maxTokens !== undefined) out.max_tokens = req.maxTokens;
+  if (req.temperature !== undefined) out.temperature = req.temperature;
+  if (req.topP !== undefined) out.top_p = req.topP;
+  // Only emit `stop` when non-empty; an empty array is a no-op some backends reject.
+  if (req.stopSequences && req.stopSequences.length > 0) out.stop = req.stopSequences;
+  if (stream) {
+    out.stream = true;
+    out.stream_options = { include_usage: true };
+  }
+
+  if (req.tools && req.tools.length > 0) {
+    out.tools = req.tools.map((t) => ({
+      type: "function",
+      function: { name: t.name, ...(t.description ? { description: t.description } : {}), parameters: t.schema },
+    }));
+  }
+
+  const tc = toolChoiceToWire(req.toolChoice);
+  if (tc) out.tool_choice = tc;
+
+  const rf = responseFormatToWire(req.responseFormat);
+  if (rf) out.response_format = rf;
+
+  if (req.reasoning?.enabled) {
+    // OpenAI is effort-based (o-series): map the effort level, defaulting to
+    // medium. Budget is ignored.
+    out.reasoning_effort = req.reasoning.effort ?? "medium";
+    // o-series reasoning models reject max_tokens (use max_completion_tokens)
+    // and reject temperature / top_p. Move and drop them so the request is
+    // accepted.
+    if (out.max_tokens !== undefined) out.max_completion_tokens = out.max_tokens;
+    delete out.max_tokens;
+    delete out.temperature;
+    delete out.top_p;
+  }
+
+  const uid = req.metadata?.user_id;
+  if (uid) out.user = uid;
+
+  return out;
+}
+
+// ── Response decoding ────────────────────────────────────────────────────────
+
+/** Concatenate text from either content form (plain string or part array). */
+function decodeContent(content: string | WireContentPart[] | undefined): string {
+  if (content === undefined) return "";
+  if (typeof content === "string") return content;
+  let out = "";
+  for (const p of content) {
+    if (p.type === "text" && p.text) out += p.text;
+  }
+  return out;
+}
+
+function parseArguments(raw: string | undefined): JSONValue {
+  if (!raw || raw === "") return {};
+  try {
+    return JSON.parse(raw) as JSONValue;
+  } catch {
+    return raw;
+  }
+}
+
+/**
+ * Convert OpenAI's wire usage block into galdor's {@link Usage} shape.
+ *
+ * @param u - The wire usage object, or `undefined` when absent.
+ * @returns A usage record; missing fields default to 0. Cached prompt tokens are
+ * reported as cache reads; cache-creation tokens are always 0.
+ */
+export function usageFromWire(u: WireUsage | undefined) {
+  return {
+    inputTokens: u?.prompt_tokens ?? 0,
+    outputTokens: u?.completion_tokens ?? 0,
+    cacheCreationTokens: 0,
+    cacheReadTokens: u?.prompt_tokens_details?.cached_tokens ?? 0,
+  };
+}
+
+/**
+ * Map an OpenAI `finish_reason` string to a galdor {@link StopReason}.
+ *
+ * @param s - The wire finish reason (e.g. `"stop"`, `"length"`, `"tool_calls"`).
+ * @returns The corresponding {@link StopReason}; an empty or absent value
+ * becomes `"end_turn"`, and an unrecognized value is passed through unchanged.
+ */
+export function normalizeFinishReason(s: string | undefined): StopReason {
+  switch (s) {
+    case "stop":
+      return "end_turn";
+    case "length":
+      return "max_tokens";
+    case "tool_calls":
+    case "function_call":
+      return "tool_use";
+    case "content_filter":
+      return "refusal";
+    default:
+      return (s === undefined || s === "" ? "end_turn" : s) as StopReason;
+  }
+}
+
+/**
+ * Collapse a non-streaming Chat Completions response into a galdor
+ * {@link Response}.
+ *
+ * Reads the first choice: surfaces any reasoning content as a thinking part,
+ * appends decoded text, and collects tool calls (parsing their JSON arguments).
+ *
+ * @param r - The decoded wire response.
+ * @param raw - Optional raw response bytes, attached as `providerRaw` when given.
+ * @returns The assembled galdor {@link Response} with message, stop reason,
+ * usage and model.
+ */
+export function responseFromWire(r: ChatResponse, raw?: Uint8Array): Response {
+  const message: Message = { role: Role.Assistant, content: [] };
+  let stopReason: StopReason = "end_turn";
+
+  const choice = r.choices?.[0];
+  if (choice) {
+    stopReason = normalizeFinishReason(choice.finish_reason);
+
+    if (choice.message.reasoning_content) {
+      // Reasoning from an OpenAI-compatible model (e.g. DeepSeek). messageText
+      // skips it, so the answer stays clean.
+      message.content.push(thinkingPart(choice.message.reasoning_content));
+    }
+    const text = decodeContent(choice.message.content);
+    if (text !== "") message.content.push(textPart(text));
+
+    const toolCalls: ToolCall[] = [];
+    for (const t of choice.message.tool_calls ?? []) {
+      toolCalls.push({ id: t.id ?? "", name: t.function.name ?? "", arguments: parseArguments(t.function.arguments) });
+    }
+    if (toolCalls.length > 0) message.toolCalls = toolCalls;
+  }
+
+  return {
+    message,
+    stopReason,
+    usage: usageFromWire(r.usage),
+    model: r.model ?? "",
+    ...(raw ? { providerRaw: raw } : {}),
+  };
+}