luv-ai 0.1.0

package/dist/morphisms/openai_chat.js

@@ -0,0 +1,247 @@
+// luv_conversation_to_openai_request
+// Maps a luv Conversation (walked linearly in array order) plus per-call
+// options into an OpenAI Chat Completions request body.
+export function luv_conversation_to_openai_request(conv, opts) {
+    const messages = [];
+    for (const node of conv.nodes) {
+        const m = node.message;
+        if (m.role === "system") {
+            const text = concatTextBlocks(m.content);
+            messages.push({ role: "system", content: text });
+        }
+        else if (m.role === "user") {
+            const onlyToolResults = m.content.every((b) => b.kind === "tool_result");
+            const onlyText = m.content.every((b) => b.kind === "text");
+            if (onlyText) {
+                messages.push({ role: "user", content: concatTextBlocks(m.content) });
+            }
+            else if (onlyToolResults) {
+                for (const b of m.content) {
+                    if (b.kind === "tool_result") {
+                        messages.push({
+                            role: "tool",
+                            tool_call_id: b.call_id,
+                            content: b.text,
+                        });
+                    }
+                }
+            }
+            else {
+                // Mixed: emit in block order, one OpenAI message per block.
+                for (const b of m.content) {
+                    if (b.kind === "text") {
+                        messages.push({ role: "user", content: b.text });
+                    }
+                    else if (b.kind === "tool_result") {
+                        messages.push({
+                            role: "tool",
+                            tool_call_id: b.call_id,
+                            content: b.text,
+                        });
+                    }
+                }
+            }
+        }
+        else if (m.role === "assistant") {
+            const textPieces = [];
+            const toolCalls = [];
+            for (const b of m.content) {
+                if (b.kind === "text")
+                    textPieces.push(b.text);
+                else if (b.kind === "tool_call") {
+                    toolCalls.push({
+                        id: b.id,
+                        type: "function",
+                        function: { name: b.name, arguments: b.args },
+                    });
+                }
+            }
+            // Canonical key order: role, content, [tool_calls].
+            // content is null only when tool_calls are present (OpenAI's
+            // convention). If both text and tool_calls are empty (e.g., the
+            // assistant message contained only error blocks that the morphism
+            // dropped), emit content: "" rather than null to satisfy OpenAI's
+            // request validation.
+            const out = {
+                role: "assistant",
+                content: textPieces.length > 0
+                    ? textPieces.join("")
+                    : toolCalls.length > 0
+                        ? null
+                        : "",
+            };
+            if (toolCalls.length > 0)
+                out.tool_calls = toolCalls;
+            messages.push(out);
+        }
+    }
+    // Canonical key order for Request: model, messages, [stream], [tools].
+    const req = {
+        model: opts.model,
+        messages,
+    };
+    if (opts.stream !== undefined)
+        req.stream = opts.stream;
+    if (opts.stream === true)
+        req.stream_options = { include_usage: true };
+    if (opts.tools !== undefined)
+        req.tools = opts.tools;
+    return req;
+}
+function concatTextBlocks(content) {
+    return content
+        .filter((b) => b.kind === "text")
+        .map((b) => b.text)
+        .join("");
+}
+// Build the luv usage envelope from an OpenAI usage object + model.
+// Token counts are preserved faithfully (not normalized); see SPEC §2.5.
+export function openaiUsageEnvelope(model, usage) {
+    if (usage === null || typeof usage !== "object")
+        return null;
+    // Pass the provider's usage object through verbatim — every field, in the
+    // provider's key order. Nothing is dropped or normalized (SPEC §2.5);
+    // `raw` is opaque to the core.
+    return {
+        provider: "openai_chat",
+        model: typeof model === "string" ? model : "",
+        raw: usage,
+    };
+}
+// openai_response_to_luv_reply
+export function openai_response_to_luv_reply(resp) {
+    const r = resp;
+    const choice = r.choices[0];
+    const msg = choice.message;
+    const blocks = [];
+    if (typeof msg.content === "string") {
+        blocks.push({ kind: "text", text: msg.content });
+    }
+    if (Array.isArray(msg.tool_calls)) {
+        for (const tc of msg.tool_calls) {
+            blocks.push({
+                kind: "tool_call",
+                id: tc.id,
+                name: tc.function.name,
+                args: tc.function.arguments,
+            });
+        }
+    }
+    return {
+        message: { role: "assistant", content: blocks },
+        finish_reason: mapFinishReason(choice.finish_reason),
+        usage: openaiUsageEnvelope(r.model, r.usage),
+    };
+}
+function mapFinishReason(r) {
+    switch (r) {
+        case "stop":
+            return "end_turn";
+        case "length":
+            return "max_tokens";
+        case "content_filter":
+            return "content_filter";
+        case "tool_calls":
+        case "function_call":
+            return "end_turn";
+        default:
+            return "end_turn";
+    }
+}
+// openai_stream_to_luv_stream
+// Consumes a sequence of OpenAI streaming chunks and emits luv stream
+// events. Stateful: tracks which kind of block (if any) is currently
+// open so deltas are tagged correctly and block boundaries fire.
+export function openai_stream_to_luv_stream(chunks) {
+    const events = [];
+    let blockOpen = null;
+    let messageStartEmitted = false;
+    let model = null;
+    let usageEnvelope = null;
+    for (const chunk of chunks) {
+        const c = chunk;
+        if (typeof c.model === "string")
+            model = c.model;
+        // Trailing usage chunk (stream_options.include_usage) carries usage and
+        // an empty choices array.
+        if (c.usage !== undefined && c.usage !== null) {
+            usageEnvelope = openaiUsageEnvelope(c.model ?? model, c.usage);
+        }
+        const choice = c.choices[0];
+        if (choice === undefined)
+            continue;
+        const delta = choice.delta;
+        const finishReason = choice.finish_reason;
+        if (delta.role === "assistant" && !messageStartEmitted) {
+            events.push({ kind: "message_start" });
+            messageStartEmitted = true;
+        }
+        // Tool call openings/continuations.
+        if (Array.isArray(delta.tool_calls)) {
+            for (const tcDelta of delta.tool_calls) {
+                if (tcDelta.id !== undefined) {
+                    // First chunk for this tool_call slot: close any text block
+                    // and open a new tool_call block.
+                    if (blockOpen === "text") {
+                        events.push({ kind: "block_end" });
+                        blockOpen = null;
+                    }
+                    events.push({
+                        kind: "block_start",
+                        block: {
+                            kind: "tool_call",
+                            id: tcDelta.id,
+                            name: tcDelta.function?.name ?? "",
+                            args: "",
+                        },
+                    });
+                    blockOpen = "tool_call";
+                    // Emit initial args_delta only if the first chunk carried any.
+                    const initialArgs = tcDelta.function?.arguments;
+                    if (typeof initialArgs === "string" && initialArgs.length > 0) {
+                        events.push({ kind: "args_delta", args: initialArgs });
+                    }
+                }
+                else if (tcDelta.function?.arguments !== undefined &&
+                    tcDelta.function.arguments !== "") {
+                    events.push({ kind: "args_delta", args: tcDelta.function.arguments });
+                }
+            }
+        }
+        // Text content deltas.
+        if (typeof delta.content === "string" && delta.content.length > 0) {
+            if (blockOpen !== "text") {
+                if (blockOpen === "tool_call") {
+                    events.push({ kind: "block_end" });
+                }
+                events.push({
+                    kind: "block_start",
+                    block: { kind: "text", text: "" },
+                });
+                blockOpen = "text";
+            }
+            events.push({ kind: "text_delta", text: delta.content });
+        }
+        // Finish marker chunk.
+        if (finishReason !== null && finishReason !== undefined) {
+            if (blockOpen !== null) {
+                events.push({ kind: "block_end" });
+                blockOpen = null;
+            }
+            events.push({
+                kind: "message_end",
+                finish_reason: mapFinishReason(finishReason),
+                usage: null,
+            });
+        }
+    }
+    // OpenAI sends usage in a trailing chunk (after the finish chunk) when
+    // stream_options.include_usage is set; attach it to message_end.
+    if (usageEnvelope !== null) {
+        const last = events[events.length - 1];
+        if (last && last.kind === "message_end") {
+            last.usage = usageEnvelope;
+        }
+    }
+    return events;
+}

package/dist/stream.d.ts

@@ -0,0 +1,3 @@
+import type { Reply, StreamReply } from "./types.js";
+export declare function consume_luv_stream_reply(stream: StreamReply): Reply;
+export declare function produce_luv_stream_reply(reply: Reply): StreamReply;

package/dist/stream.js

@@ -0,0 +1,100 @@
+// consume_luv_stream_reply : Stream<Reply> -> Reply
+// Collapses a well-formed Stream<Reply> into the Reply it represents.
+export function consume_luv_stream_reply(stream) {
+    let finishReason = "end_turn";
+    let usage = null;
+    const blocks = [];
+    let current = null;
+    for (const evt of stream) {
+        switch (evt.kind) {
+            case "message_start":
+                break;
+            case "block_start": {
+                // Append a fresh copy of the initial block to content.
+                const b = evt.block;
+                if (b.kind === "text") {
+                    current = { kind: "text", text: b.text };
+                }
+                else if (b.kind === "tool_call") {
+                    current = { kind: "tool_call", id: b.id, name: b.name, args: b.args };
+                }
+                else if (b.kind === "tool_result") {
+                    current = { kind: "tool_result", call_id: b.call_id, text: b.text };
+                }
+                else {
+                    current = {
+                        kind: "error",
+                        category: b.category,
+                        message: b.message,
+                        details: b.details,
+                    };
+                }
+                blocks.push(current);
+                break;
+            }
+            case "text_delta":
+                if (current && current.kind === "text") {
+                    current.text += evt.text;
+                }
+                break;
+            case "args_delta":
+                if (current && current.kind === "tool_call") {
+                    current.args += evt.args;
+                }
+                break;
+            case "block_end":
+                current = null;
+                break;
+            case "message_end":
+                finishReason = evt.finish_reason;
+                usage = evt.usage ?? null;
+                break;
+        }
+    }
+    return {
+        message: { role: "assistant", content: blocks },
+        finish_reason: finishReason,
+        usage,
+    };
+}
+// produce_luv_stream_reply : Reply -> Stream<Reply>
+// Lifts a Reply into the canonical singleton stream that consumes back
+// to it. Always emits exactly one delta per block (even if empty).
+export function produce_luv_stream_reply(reply) {
+    const events = [];
+    events.push({ kind: "message_start" });
+    for (const block of reply.message.content) {
+        if (block.kind === "text") {
+            events.push({
+                kind: "block_start",
+                block: { kind: "text", text: "" },
+            });
+            events.push({ kind: "text_delta", text: block.text });
+            events.push({ kind: "block_end" });
+        }
+        else if (block.kind === "tool_call") {
+            events.push({
+                kind: "block_start",
+                block: {
+                    kind: "tool_call",
+                    id: block.id,
+                    name: block.name,
+                    args: "",
+                },
+            });
+            events.push({ kind: "args_delta", args: block.args });
+            events.push({ kind: "block_end" });
+        }
+        else if (block.kind === "error") {
+            events.push({ kind: "block_start", block });
+            events.push({ kind: "block_end" });
+        }
+        // tool_result blocks don't appear in Stream<Reply> (assistant-only).
+    }
+    events.push({
+        kind: "message_end",
+        finish_reason: reply.finish_reason,
+        usage: reply.usage ?? null,
+    });
+    return events;
+}

package/dist/transport/anthropic_messages.d.ts

@@ -0,0 +1,31 @@
+import type { Conversation, ErrorCategory, Reply, StreamEventReply, StreamReply } from "../types.js";
+import { type AnthropicRequestOptions } from "../morphisms/anthropic_messages.js";
+export interface HTTPRequest {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body: string;
+}
+export interface HTTPResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+export type ErrorPolicy = "throw" | "as_block";
+export type ErrorPolicyMap = Partial<Record<ErrorCategory, ErrorPolicy>>;
+export interface AnthropicClientConfig {
+    api_key: string;
+    base_url?: string;
+    anthropic_version?: string;
+    default_max_tokens?: number;
+    timeout_ms?: number;
+    on_error?: ErrorPolicyMap;
+}
+export declare function luv_send_to_anthropic_http_request(conv: Conversation, opts: AnthropicRequestOptions, config: AnthropicClientConfig): HTTPRequest;
+export declare function anthropic_http_response_to_luv_reply(response: HTTPResponse): Reply;
+export declare function anthropic_http_stream_to_luv_stream(response: HTTPResponse): StreamReply;
+export interface AnthropicClient {
+    send(conv: Conversation, opts: AnthropicRequestOptions): Promise<Reply>;
+    stream(conv: Conversation, opts: AnthropicRequestOptions): AsyncIterable<StreamEventReply>;
+}
+export declare function anthropicClient(config: AnthropicClientConfig): AnthropicClient;