@galdor/provider-openai 0.3.0

package/dist/convert.d.ts

@@ -0,0 +1,165 @@
+/**
+ * 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 { type Request, type Response } from "@galdor/core/provider";
+import { type StopReason } from "@galdor/core/schema";
+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;
+}
+/**
+ * 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 declare function buildRequest(req: Request, stream: boolean): ChatRequest;
+/**
+ * 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 declare function usageFromWire(u: WireUsage | undefined): {
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationTokens: number;
+    cacheReadTokens: number;
+};
+/**
+ * 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 declare function normalizeFinishReason(s: string | undefined): 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 declare function responseFromWire(r: ChatResponse, raw?: Uint8Array): Response;
+export {};
+//# sourceMappingURL=convert.d.ts.map

package/dist/convert.d.ts.map

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

package/dist/convert.js

@@ -0,0 +1,302 @@
+/**
+ * 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 } from "@galdor/core/provider";
+import { ContentType, messageText, Role, textPart, thinkingPart, } from "@galdor/core/schema";
+/** Build a typed invalid-request error for a request that cannot be lowered to the wire. */
+function invalidRequest(message) {
+    return new InvalidRequestError({ kind: "invalid_request", provider: "openai", statusCode: 0, message });
+}
+// ── Request building ─────────────────────────────────────────────────────────
+function toBase64(data) {
+    return Buffer.from(data).toString("base64");
+}
+/** Render an image part as OpenAI's image_url.url (direct URL or data: URL). */
+function imageToURL(img) {
+    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) {
+    const out = [];
+    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) {
+    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) {
+    const wm = { 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 = [];
+    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) {
+    if (args === undefined || args === null)
+        return "{}";
+    if (typeof args === "string")
+        return args;
+    return JSON.stringify(args);
+}
+function toolChoiceToWire(c) {
+    switch (c) {
+        case "auto":
+            return "auto";
+        case "none":
+            return "none";
+        case "required":
+            return "required";
+        default:
+            return undefined;
+    }
+}
+function responseFormatToWire(rf) {
+    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, stream) {
+    if (req.model === "")
+        throw invalidRequest("openai: model is required");
+    const out = { 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) {
+    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) {
+    if (!raw || raw === "")
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    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) {
+    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) {
+    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);
+    }
+}
+/**
+ * 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, raw) {
+    const message = { role: Role.Assistant, content: [] };
+    let 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 = [];
+        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 } : {}),
+    };
+}
+//# sourceMappingURL=convert.js.map

package/dist/convert.js.map

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

package/dist/embed.d.ts

@@ -0,0 +1,72 @@
+/**
+ * OpenAI embeddings — a galdor {@link Embedder} over the `/embeddings` endpoint.
+ *
+ * Works against the OpenAI API and any OpenAI-compatible endpoint (Mistral,
+ * Together, MiniMax, vLLM, Ollama, …) by pointing {@link EmbedderConfig.baseURL}
+ * at it. Construct one with {@link newEmbedder}.
+ */
+import type { Embedder } from "@galdor/core/memory";
+/** Configuration for an {@link OpenAIEmbedder}. */
+export interface EmbedderConfig {
+    /** Authenticates against the API. Required. */
+    apiKey: string;
+    /** Embedding model id. Defaults to `"text-embedding-3-small"`. */
+    model?: string;
+    /**
+     * Vector size. Defaults to the model's native size (1536 for
+     * `text-embedding-3-small`). When set and the model supports it (the
+     * `text-embedding-3-*` family), it is sent as `dimensions` to truncate output.
+     */
+    dimensions?: number;
+    /** Overrides the API endpoint. Default `https://api.openai.com/v1`; the `/v1` segment is part of it. */
+    baseURL?: string;
+    /** Sent as `openai-organization` when non-empty. */
+    organization?: string;
+    /** Sent as `openai-project` when non-empty. */
+    project?: string;
+    /** Sent as the `User-Agent` header when non-empty. */
+    userAgent?: string;
+    /** Per-request timeout in milliseconds. Defaults to 60000; `0` disables it. */
+    timeoutMs?: number;
+}
+/**
+ * A galdor {@link Embedder} backed by the OpenAI embeddings API.
+ *
+ * @example
+ * ```ts
+ * const embedder = newEmbedder({ apiKey: process.env.OPENAI_API_KEY! });
+ * const [vec] = await embedder.embed(["quito ecuador capital"]);
+ * ```
+ */
+export declare class OpenAIEmbedder implements Embedder {
+    #private;
+    /**
+     * @param cfg - Embedder configuration; `apiKey` is required.
+     * @throws {Error} When `apiKey` is missing or blank.
+     */
+    constructor(cfg: EmbedderConfig);
+    /** @returns The embedding model id. */
+    model(): string;
+    /**
+     * @returns The embedding vector size: the configured/learned size when known,
+     *   otherwise the model's native default until the first response sets it.
+     */
+    dimensions(): number;
+    /**
+     * Embed each input text, preserving order: `out[i]` is the vector for `texts[i]`.
+     *
+     * @param texts - Inputs to embed; an empty array returns `[]`.
+     * @returns One vector per input, ordered to match `texts`.
+     * @throws {Error} On a non-2xx response, or when the API returns the wrong number of vectors.
+     */
+    embed(texts: string[], signal?: AbortSignal): Promise<number[][]>;
+}
+/**
+ * Construct an {@link OpenAIEmbedder}.
+ *
+ * @param cfg - Embedder configuration; `apiKey` is required.
+ * @returns A ready embedder.
+ * @throws {Error} When `apiKey` is missing or blank.
+ */
+export declare function newEmbedder(cfg: EmbedderConfig): OpenAIEmbedder;
+//# sourceMappingURL=embed.d.ts.map

package/dist/embed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed.d.ts","sourceRoot":"","sources":["../src/embed.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAYpD,mDAAmD;AACnD,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wGAAwG;IACxG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAQD;;;;;;;;GAQG;AACH,qBAAa,cAAe,YAAW,QAAQ;;IAY7C;;;OAGG;gBACS,GAAG,EAAE,cAAc;IAc/B,uCAAuC;IACvC,KAAK,IAAI,MAAM;IAIf;;;OAGG;IACH,UAAU,IAAI,MAAM;IAIpB;;;;;;OAMG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;CAyCxE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,cAAc,GAAG,cAAc,CAE/D"}