luv-ai 0.1.0

package/dist/transport/openai_chat.js

@@ -0,0 +1,373 @@
+import { LuvError } from "../types.js";
+import { stringify } from "../encode.js";
+import { luv_conversation_to_openai_request, openai_response_to_luv_reply, openai_stream_to_luv_stream, openaiUsageEnvelope, } from "../morphisms/openai_chat.js";
+const DEFAULT_BASE_URL = "https://api.openai.com/v1";
+const DEFAULT_ON_ERROR = {
+    auth: "throw",
+    rate_limit: "throw",
+    bad_request: "throw",
+    content_filter: "as_block",
+    server_error: "throw",
+    network: "throw",
+    tool_execution: "throw",
+    local_validation: "throw",
+    unknown: "throw",
+};
+function policyFor(config, category) {
+    return config.on_error?.[category] ?? DEFAULT_ON_ERROR[category];
+}
+// ---------- Status -> ErrorCategory ----------
+function mapStatusToCategory(status) {
+    if (status === 401 || status === 403)
+        return "auth";
+    if (status === 408 || status === 504)
+        return "network";
+    if (status === 429)
+        return "rate_limit";
+    if (status === 0)
+        return "network";
+    if (status >= 500 && status < 600)
+        return "server_error";
+    if (status >= 400 && status < 500)
+        return "bad_request";
+    return "unknown";
+}
+function shortMessageFor(status, category) {
+    return `HTTP ${status}: ${category}`;
+}
+// ---------- Arrow: luv_send_to_openai_http_request ----------
+export function luv_send_to_openai_http_request(conv, opts, config) {
+    const baseUrl = config.base_url ?? DEFAULT_BASE_URL;
+    const url = `${baseUrl}/chat/completions`;
+    // Build headers in canonical order: required first (authorization,
+    // content-type), then optional alphabetically.
+    const headers = {};
+    headers["authorization"] = `Bearer ${config.api_key}`;
+    headers["content-type"] = "application/json";
+    const optionals = [];
+    if (config.organization) {
+        optionals.push(["openai-organization", config.organization]);
+    }
+    if (config.project) {
+        optionals.push(["openai-project", config.project]);
+    }
+    optionals.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+    for (const [k, v] of optionals)
+        headers[k] = v;
+    const body = stringify(luv_conversation_to_openai_request(conv, opts));
+    return { method: "POST", url, headers, body };
+}
+// ---------- Arrow: openai_http_response_to_luv_reply ----------
+export function openai_http_response_to_luv_reply(response) {
+    if (response.status >= 200 && response.status < 300) {
+        let parsed;
+        try {
+            parsed = JSON.parse(response.body);
+        }
+        catch {
+            return makeErrorReply("unknown", `HTTP ${response.status}: failed to parse response body as JSON`, { status: response.status, body: response.body });
+        }
+        return openai_response_to_luv_reply(parsed);
+    }
+    const category = mapStatusToCategory(response.status);
+    return makeErrorReply(category, shortMessageFor(response.status, category), { status: response.status, body: response.body });
+}
+function makeErrorReply(category, message, detailsObj) {
+    return {
+        message: {
+            role: "assistant",
+            content: [
+                {
+                    kind: "error",
+                    category,
+                    message,
+                    details: stringify(detailsObj),
+                },
+            ],
+        },
+        finish_reason: "error",
+        usage: null,
+    };
+}
+// ---------- Arrow: openai_http_stream_to_luv_stream ----------
+export function openai_http_stream_to_luv_stream(response) {
+    if (response.status < 200 || response.status >= 300) {
+        const category = mapStatusToCategory(response.status);
+        return [
+            { kind: "message_start" },
+            {
+                kind: "block_start",
+                block: {
+                    kind: "error",
+                    category,
+                    message: shortMessageFor(response.status, category),
+                    details: stringify({ status: response.status, body: response.body }),
+                },
+            },
+            { kind: "block_end" },
+            { kind: "message_end", finish_reason: "error", usage: null },
+        ];
+    }
+    const chunks = parseSSE(response.body);
+    return openai_stream_to_luv_stream(chunks);
+}
+function parseSSE(body) {
+    const chunks = [];
+    const events = body.split("\n\n");
+    for (const event of events) {
+        for (const line of event.split("\n")) {
+            if (!line.startsWith("data: "))
+                continue;
+            const payload = line.slice(6);
+            if (payload === "[DONE]")
+                return chunks;
+            try {
+                chunks.push(JSON.parse(payload));
+            }
+            catch {
+                // Skip unparseable data lines silently. A more aggressive
+                // implementation might surface a parse-error event here.
+            }
+        }
+    }
+    return chunks;
+}
+export function openaiClient(config) {
+    return {
+        async send(conv, opts) {
+            const req = luv_send_to_openai_http_request(conv, opts, config);
+            const fetchRes = await fetch(req.url, {
+                method: req.method,
+                headers: req.headers,
+                body: req.body,
+            });
+            const httpRes = {
+                status: fetchRes.status,
+                headers: headersToRecord(fetchRes.headers),
+                body: await fetchRes.text(),
+            };
+            const reply = openai_http_response_to_luv_reply(httpRes);
+            applyErrorPolicyOrThrow(reply, config);
+            return reply;
+        },
+        async *stream(conv, opts) {
+            const req = luv_send_to_openai_http_request(conv, { ...opts, stream: true }, config);
+            const fetchRes = await fetch(req.url, {
+                method: req.method,
+                headers: req.headers,
+                body: req.body,
+            });
+            if (fetchRes.status < 200 || fetchRes.status >= 300) {
+                const httpRes = {
+                    status: fetchRes.status,
+                    headers: headersToRecord(fetchRes.headers),
+                    body: await fetchRes.text(),
+                };
+                const events = openai_http_stream_to_luv_stream(httpRes);
+                const errBlock = findErrorBlock(events);
+                if (errBlock && policyFor(config, errBlock.category) === "throw") {
+                    throw new LuvError({
+                        category: errBlock.category,
+                        message: errBlock.message,
+                        details: errBlock.details,
+                    });
+                }
+                for (const e of events)
+                    yield e;
+                return;
+            }
+            // 2xx — stream chunks as they arrive.
+            yield* streamSSE(fetchRes);
+        },
+    };
+}
+function headersToRecord(h) {
+    const out = {};
+    h.forEach((v, k) => {
+        out[k.toLowerCase()] = v;
+    });
+    return out;
+}
+function findErrorBlock(events) {
+    for (const e of events) {
+        if (e.kind === "block_start" && e.block.kind === "error") {
+            return {
+                category: e.block.category,
+                message: e.block.message,
+                details: e.block.details,
+            };
+        }
+    }
+    return null;
+}
+function applyErrorPolicyOrThrow(reply, config) {
+    for (const block of reply.message.content) {
+        if (block.kind === "error") {
+            const policy = policyFor(config, block.category);
+            if (policy === "throw") {
+                throw new LuvError({
+                    category: block.category,
+                    message: block.message,
+                    details: block.details,
+                });
+            }
+        }
+    }
+}
+// Real-time SSE streaming from a fetch Response. Decodes bytes as
+// they arrive, scans for complete event blocks (separated by "\n\n"),
+// parses each data: line, and yields luv events incrementally.
+async function* streamSSE(res) {
+    if (!res.body)
+        return;
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder("utf-8");
+    let buffer = "";
+    // Stateful chunk-to-luv processor mirrors the morphism, but operates
+    // chunk-at-a-time so we can yield events as bytes arrive.
+    const state = createStreamState();
+    let doneSignal = false;
+    while (!doneSignal) {
+        const { value, done } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        let sep;
+        while ((sep = buffer.indexOf("\n\n")) !== -1) {
+            const event = buffer.slice(0, sep);
+            buffer = buffer.slice(sep + 2);
+            for (const line of event.split("\n")) {
+                if (!line.startsWith("data: "))
+                    continue;
+                const payload = line.slice(6);
+                if (payload === "[DONE]") {
+                    doneSignal = true;
+                    break;
+                }
+                let chunk;
+                try {
+                    chunk = JSON.parse(payload);
+                }
+                catch {
+                    continue;
+                }
+                for (const ev of processChunk(state, chunk))
+                    yield ev;
+            }
+            if (doneSignal)
+                break;
+        }
+    }
+    // Emit the deferred message_end (with usage if a trailing usage chunk
+    // arrived before [DONE]).
+    for (const ev of finishStream(state))
+        yield ev;
+}
+function createStreamState() {
+    return {
+        blockOpen: null,
+        messageStartEmitted: false,
+        model: null,
+        usage: null,
+        finishReason: null,
+    };
+}
+function processChunk(state, chunk) {
+    const out = [];
+    const c = chunk;
+    if (typeof c.model === "string")
+        state.model = c.model;
+    // Trailing usage chunk (stream_options.include_usage): empty choices + usage.
+    if (c.usage !== undefined && c.usage !== null) {
+        state.usage = openaiUsageEnvelope(c.model ?? state.model, c.usage);
+    }
+    const choice = c.choices[0];
+    if (choice === undefined)
+        return out;
+    const delta = choice.delta;
+    const finishReason = choice.finish_reason;
+    if (delta.role === "assistant" && !state.messageStartEmitted) {
+        out.push({ kind: "message_start" });
+        state.messageStartEmitted = true;
+    }
+    if (Array.isArray(delta.tool_calls)) {
+        for (const tcDelta of delta.tool_calls) {
+            if (tcDelta.id !== undefined) {
+                if (state.blockOpen === "text") {
+                    out.push({ kind: "block_end" });
+                    state.blockOpen = null;
+                }
+                out.push({
+                    kind: "block_start",
+                    block: {
+                        kind: "tool_call",
+                        id: tcDelta.id,
+                        name: tcDelta.function?.name ?? "",
+                        args: "",
+                    },
+                });
+                state.blockOpen = "tool_call";
+                const initialArgs = tcDelta.function?.arguments;
+                if (typeof initialArgs === "string" && initialArgs.length > 0) {
+                    out.push({ kind: "args_delta", args: initialArgs });
+                }
+            }
+            else if (tcDelta.function?.arguments !== undefined &&
+                tcDelta.function.arguments !== "") {
+                out.push({ kind: "args_delta", args: tcDelta.function.arguments });
+            }
+        }
+    }
+    if (typeof delta.content === "string" && delta.content.length > 0) {
+        if (state.blockOpen !== "text") {
+            if (state.blockOpen === "tool_call") {
+                out.push({ kind: "block_end" });
+            }
+            out.push({ kind: "block_start", block: { kind: "text", text: "" } });
+            state.blockOpen = "text";
+        }
+        out.push({ kind: "text_delta", text: delta.content });
+    }
+    if (finishReason !== null && finishReason !== undefined) {
+        if (state.blockOpen !== null) {
+            out.push({ kind: "block_end" });
+            state.blockOpen = null;
+        }
+        // Defer message_end to finishStream: OpenAI sends usage in a trailing
+        // chunk AFTER this finish chunk, so message_end is emitted at stream end.
+        state.finishReason = finishReason;
+    }
+    return out;
+}
+// Emit the deferred message_end once the SSE stream ends, carrying usage if a
+// trailing usage chunk was seen.
+function finishStream(state) {
+    const out = [];
+    if (!state.messageStartEmitted)
+        return out;
+    if (state.blockOpen !== null) {
+        out.push({ kind: "block_end" });
+        state.blockOpen = null;
+    }
+    out.push({
+        kind: "message_end",
+        finish_reason: state.finishReason !== null ? mapFinishReason(state.finishReason) : "end_turn",
+        usage: state.usage,
+    });
+    return out;
+}
+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";
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,101 @@
+export type Role = "system" | "user" | "assistant";
+export type ErrorCategory = "auth" | "rate_limit" | "bad_request" | "content_filter" | "server_error" | "network" | "tool_execution" | "local_validation" | "unknown";
+export declare const ERROR_CATEGORIES: readonly ErrorCategory[];
+export type Block = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "tool_call";
+    id: string;
+    name: string;
+    args: string;
+} | {
+    kind: "tool_result";
+    call_id: string;
+    text: string;
+} | {
+    kind: "error";
+    category: ErrorCategory;
+    message: string;
+    details: string;
+};
+export interface Message {
+    role: Role;
+    content: Block[];
+}
+export interface Node {
+    id: string;
+    parent_id: string | null;
+    message: Message;
+}
+export interface Conversation {
+    spec_version: string;
+    nodes: Node[];
+}
+export declare const LUV_SPEC_VERSION = "1.0";
+export type FinishReason = "end_turn" | "max_tokens" | "content_filter" | "error";
+/**
+ * Single throwable class paired with the canonical error Block shape.
+ * Switching from "throw" to "as_block" is conversion between this
+ * exception form and a Block with kind: "error".
+ */
+export declare class LuvError extends Error {
+    readonly data: {
+        category: ErrorCategory;
+        message: string;
+        details: string;
+    };
+    constructor(data: {
+        category: ErrorCategory;
+        message: string;
+        details: string;
+    });
+}
+/**
+ * Provider-tagged usage envelope. Token accounting is NOT normalized across
+ * providers (token counts are not commensurable and billing differs); instead
+ * the provider's own usage object is preserved verbatim in `raw`, tagged with
+ * the morphism `provider` id and the `model` that produced the reply. The
+ * shape of `raw` is defined by each morphism spec and is opaque to the
+ * universal core.
+ */
+export interface Usage {
+    provider: string;
+    model: string;
+    raw: unknown;
+}
+export interface Reply {
+    message: Message;
+    finish_reason: FinishReason;
+    usage: Usage | null;
+}
+export type StreamEventReply = {
+    kind: "message_start";
+} | {
+    kind: "block_start";
+    block: Block;
+} | {
+    kind: "text_delta";
+    text: string;
+} | {
+    kind: "args_delta";
+    args: string;
+} | {
+    kind: "block_end";
+} | {
+    kind: "message_end";
+    finish_reason: FinishReason;
+    usage: Usage | null;
+};
+export type StreamReply = StreamEventReply[];
+export interface ValidationError {
+    path: string;
+    rule: string;
+    message: string;
+}
+export type ValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    errors: ValidationError[];
+};

package/dist/types.js

@@ -0,0 +1,25 @@
+export const ERROR_CATEGORIES = [
+    "auth",
+    "rate_limit",
+    "bad_request",
+    "content_filter",
+    "server_error",
+    "network",
+    "tool_execution",
+    "local_validation",
+    "unknown",
+];
+export const LUV_SPEC_VERSION = "1.0";
+/**
+ * Single throwable class paired with the canonical error Block shape.
+ * Switching from "throw" to "as_block" is conversion between this
+ * exception form and a Block with kind: "error".
+ */
+export class LuvError extends Error {
+    data;
+    constructor(data) {
+        super(data.message);
+        this.name = "LuvError";
+        this.data = data;
+    }
+}

package/dist/validate.d.ts

@@ -0,0 +1,6 @@
+import type { ValidationResult } from "./types.js";
+export declare function validate_luv_block(input: unknown, basePath?: string): ValidationResult;
+export declare function validate_luv_message(input: unknown, basePath?: string): ValidationResult;
+export declare function validate_luv_reply(input: unknown, basePath?: string): ValidationResult;
+export declare function validate_luv_stream_reply(input: unknown, basePath?: string): ValidationResult;
+export declare function validate_luv_conversation(input: unknown): ValidationResult;