luv-ai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Monarch Wadia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,196 @@
+# luv — TypeScript reference implementation
+
+Hydration of the luv spec (`spec/SPEC.md`) in TypeScript. Runs in Bun
+during development; the published package is a plain ESM library that
+works in browsers, Node (≥18), Bun, and Deno. Zero runtime dependencies.
+
+## Install
+
+```
+npm install luv
+# or
+bun add luv
+# or
+pnpm add luv
+```
+
+## Quickstart
+
+```ts
+import { openaiClient, anthropicClient } from "luv";
+
+const openai = openaiClient({ api_key: process.env.OPENAI_API_KEY! });
+const anthropic = anthropicClient({ api_key: process.env.ANTHROPIC_API_KEY! });
+
+const conv = {
+  spec_version: "1.0",
+  nodes: [
+    {
+      id: "n1",
+      parent_id: null,
+      message: {
+        role: "user",
+        content: [{ kind: "text", text: "Hello!" }],
+      },
+    },
+  ],
+};
+
+// Same conversation, either provider, identical Reply shape.
+const r1 = await openai.send(conv, { model: "gpt-4o-mini" });
+const r2 = await anthropic.send(conv, {
+  model: "claude-haiku-4-5",
+  max_tokens: 1024,
+});
+```
+
+Streaming:
+
+```ts
+for await (const event of client.stream(conv, { model: "gpt-4o-mini" })) {
+  if (event.kind === "text_delta") process.stdout.write(event.text);
+}
+```
+
+Errors:
+
+```ts
+import { LuvError } from "luv";
+
+try {
+  await client.send(conv, { model: "gpt-4o-mini" });
+} catch (e) {
+  if (e instanceof LuvError) {
+    console.log(e.data.category);  // "auth" | "rate_limit" | ...
+    console.log(e.data.message);
+    console.log(e.data.details);   // canonical JSON string
+  }
+}
+```
+
+Configure per-error policy:
+
+```ts
+const client = openaiClient({
+  api_key,
+  on_error: {
+    rate_limit: "as_block",  // surface as data instead of throwing
+    content_filter: "as_block",
+  },
+});
+```
+
+## Layout
+
+```
+impl/typescript/
+  package.json
+  tsconfig.json
+  src/
+    index.ts                       — public exports
+    types.ts                       — canonical types + LuvError + ErrorCategory
+    encode.ts                      — canonical JSON encoders + stringify
+    stream.ts                      — consume_luv_stream_reply, produce_luv_stream_reply
+    validate.ts                    — five validators
+    morphisms/
+      openai_chat.ts               — three morphism arrows
+    transport/
+      openai_chat.ts               — three transport arrows + openaiClient
+  test/
+    bench.test.ts                  — walks spec/{cases,morphisms/*/cases}, byte-compares
+  scripts/
+    record.ts                      — refresh recorded fixtures against live API
+    smoke.ts                       — end-to-end live API smoke test
+```
+
+## Scripts
+
+| Command | What it does |
+|---|---|
+| `bun test` | Run the bench against on-disk fixtures (no network). |
+| `bun run build` | Compile `src/` to `dist/` with type declarations (uses `tsc`). |
+| `bun run verify` | Verify request-shape cases (luv→provider) against the live API; no file writes. |
+| `bun run record` | Refresh recorded fixtures (input.json + regenerated expected.json) by hitting the live API. Reviewable via `git diff`. |
+| `bun run smoke` | Live end-to-end smoke test of `client.send` + `client.stream`. |
+
+All scripts that hit the live API expect `OPENAI_API_KEY` and/or
+`ANTHROPIC_API_KEY` in either the environment or `<repo-root>/.env`.
+Providers without a configured key are skipped.
+
+## Universal use
+
+The `src/` code uses only standard JavaScript and Web APIs (`fetch`,
+`ReadableStream`, `TextDecoder`). It can be imported directly in a
+browser, in Node, in Bun, or in any modern JS runtime. The bench runner
+(`test/`) is Bun-specific because it walks the filesystem; everything
+under `src/` is universal.
+
+## Arrows registered with the bench
+
+Universal (spec-level) arrows — `spec/cases/`:
+- `consume_luv_stream_reply`
+- `produce_luv_stream_reply`
+- `validate_luv_conversation`
+
+OpenAI morphism arrows — `spec/morphisms/openai_chat/cases/`:
+- `luv_conversation_to_openai_request`
+- `openai_response_to_luv_reply`
+- `openai_stream_to_luv_stream`
+
+OpenAI transport arrows — `spec/morphisms/openai_chat/cases/`:
+- `luv_send_to_openai_http_request`
+- `openai_http_response_to_luv_reply`
+- `openai_http_stream_to_luv_stream`
+
+Anthropic morphism arrows — `spec/morphisms/anthropic_messages/cases/`:
+- `luv_conversation_to_anthropic_request`
+- `anthropic_response_to_luv_reply`
+- `anthropic_stream_to_luv_stream`
+
+Anthropic transport arrows — `spec/morphisms/anthropic_messages/cases/`:
+- `luv_send_to_anthropic_http_request`
+- `anthropic_http_response_to_luv_reply`
+- `anthropic_http_stream_to_luv_stream`
+
+Also exported but not (yet) exercised by bench cases:
+`validate_luv_message`, `validate_luv_block`, `validate_luv_reply`,
+`validate_luv_stream_reply`.
+
+## OpenAI-compatible providers
+
+`openaiClient` works with any provider that mirrors OpenAI's Chat
+Completions wire format. Pass a `base_url`:
+
+```ts
+const togetherClient = openaiClient({
+  api_key: process.env.TOGETHER_API_KEY!,
+  base_url: "https://api.together.xyz/v1",
+});
+```
+
+See `spec/morphisms/openai_chat/transport.md` for the full list of
+known-compatible providers.
+
+## Design notes
+
+- **Canonical JSON.** Encoders construct plain objects with property
+  insertion in canonical key order; `JSON.stringify` preserves that
+  order in ES2015+. `stringify()` walks the value tree to reject lone
+  surrogates before serializing (Section 3 rule 3).
+- **Validators.** Single-pass walk, stable sort by JSON Pointer path at
+  the end. Path format matches the spec exactly (`/nodes/<i>/...`).
+- **Streaming.** `openaiClient.stream()` returns `AsyncIterable<StreamEventReply>` —
+  the natural shape for TS (`for await`). Internally it reads the
+  Response body via `ReadableStream` and emits luv events as bytes
+  arrive; no buffering of the full response.
+- **Recording.** `bun run record` refreshes `input.json` from the live
+  API and regenerates `expected.json` from the current arrow. Diffs
+  surface in `git diff` for human review before commit. Standard
+  snapshot-test workflow.
+- **Zero runtime dependencies.** All shipped code is hand-written. The
+  transport layer uses `fetch`, `ReadableStream`, and `TextDecoder` —
+  all Web Standard APIs available in every modern runtime. The only
+  dev dependency is `typescript` (for type-declaration emission during
+  publish; see `DECISIONS.md`).
+- **Bun for development.** `bun test`, `bun build`, `bun:test`, and
+  hand-rolled scripts. No bundlers, linters, or other tooling.

package/dist/encode.d.ts

@@ -0,0 +1,12 @@
+import type { Block, Message, Node, Conversation, Reply, Usage, StreamEventReply, StreamReply, ValidationError, ValidationResult } from "./types.js";
+export declare function encodeBlock(b: Block): unknown;
+export declare function encodeMessage(m: Message): unknown;
+export declare function encodeNode(n: Node): unknown;
+export declare function encodeConversation(c: Conversation): unknown;
+export declare function encodeUsage(u: Usage | null): unknown;
+export declare function encodeReply(r: Reply): unknown;
+export declare function encodeStreamEventReply(e: StreamEventReply): unknown;
+export declare function encodeStreamReply(s: StreamReply): unknown;
+export declare function encodeValidationError(e: ValidationError): unknown;
+export declare function encodeValidationResult(v: ValidationResult): unknown;
+export declare function stringify(v: unknown): string;

package/dist/encode.js

@@ -0,0 +1,115 @@
+// Each encoder produces a plain JS object whose property insertion order
+// matches the canonical key order for its type (Section 3 rule 1).
+// JSON.stringify preserves insertion order in ES2015+, so stringifying
+// the result yields canonical bytes.
+export function encodeBlock(b) {
+    switch (b.kind) {
+        case "text":
+            return { kind: b.kind, text: b.text };
+        case "tool_call":
+            return { kind: b.kind, id: b.id, name: b.name, args: b.args };
+        case "tool_result":
+            return { kind: b.kind, call_id: b.call_id, text: b.text };
+        case "error":
+            return {
+                kind: b.kind,
+                category: b.category,
+                message: b.message,
+                details: b.details,
+            };
+    }
+}
+export function encodeMessage(m) {
+    return { role: m.role, content: m.content.map(encodeBlock) };
+}
+export function encodeNode(n) {
+    return { id: n.id, parent_id: n.parent_id, message: encodeMessage(n.message) };
+}
+export function encodeConversation(c) {
+    return {
+        spec_version: c.spec_version,
+        nodes: c.nodes.map(encodeNode),
+    };
+}
+export function encodeUsage(u) {
+    if (u === null)
+        return null;
+    // Envelope key order: provider, model, raw. `raw` is morphism-defined and
+    // already in canonical key order by construction; passed through unchanged.
+    return { provider: u.provider, model: u.model, raw: u.raw };
+}
+export function encodeReply(r) {
+    return {
+        message: encodeMessage(r.message),
+        finish_reason: r.finish_reason,
+        usage: encodeUsage(r.usage),
+    };
+}
+export function encodeStreamEventReply(e) {
+    switch (e.kind) {
+        case "message_start":
+            return { kind: e.kind };
+        case "block_start":
+            return { kind: e.kind, block: encodeBlock(e.block) };
+        case "text_delta":
+            return { kind: e.kind, text: e.text };
+        case "args_delta":
+            return { kind: e.kind, args: e.args };
+        case "block_end":
+            return { kind: e.kind };
+        case "message_end":
+            return {
+                kind: e.kind,
+                finish_reason: e.finish_reason,
+                usage: encodeUsage(e.usage),
+            };
+    }
+}
+export function encodeStreamReply(s) {
+    return s.map(encodeStreamEventReply);
+}
+export function encodeValidationError(e) {
+    return { path: e.path, rule: e.rule, message: e.message };
+}
+export function encodeValidationResult(v) {
+    if (v.valid)
+        return { valid: true };
+    return { valid: false, errors: v.errors.map(encodeValidationError) };
+}
+// Final canonical serialization. JSON.stringify with no replacer/spacer
+// produces no insignificant whitespace and preserves the property
+// insertion order set up by the encoders above.
+export function stringify(v) {
+    // Reject lone surrogates anywhere in the value tree (Section 3 rule 3).
+    checkStrings(v);
+    return JSON.stringify(v);
+}
+function checkStrings(v) {
+    if (typeof v === "string") {
+        for (let i = 0; i < v.length; i++) {
+            const code = v.charCodeAt(i);
+            if (code >= 0xd800 && code <= 0xdbff) {
+                if (i + 1 >= v.length) {
+                    throw new Error(`Lone high surrogate at position ${i}`);
+                }
+                const next = v.charCodeAt(i + 1);
+                if (next < 0xdc00 || next > 0xdfff) {
+                    throw new Error(`Lone high surrogate at position ${i}`);
+                }
+                i++;
+            }
+            else if (code >= 0xdc00 && code <= 0xdfff) {
+                throw new Error(`Lone low surrogate at position ${i}`);
+            }
+        }
+    }
+    else if (Array.isArray(v)) {
+        for (const item of v)
+            checkStrings(item);
+    }
+    else if (v !== null && typeof v === "object") {
+        for (const k of Object.keys(v)) {
+            checkStrings(v[k]);
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { Role, Block, ErrorCategory, Message, Node, Conversation, FinishReason, Reply, Usage, StreamEventReply, StreamReply, ValidationError, ValidationResult, } from "./types.js";
+export { LUV_SPEC_VERSION, ERROR_CATEGORIES, LuvError } from "./types.js";
+export { encodeBlock, encodeMessage, encodeNode, encodeConversation, encodeReply, encodeUsage, encodeStreamEventReply, encodeStreamReply, encodeValidationError, encodeValidationResult, stringify, } from "./encode.js";
+export { consume_luv_stream_reply, produce_luv_stream_reply, } from "./stream.js";
+export { validate_luv_conversation, validate_luv_message, validate_luv_block, validate_luv_reply, validate_luv_stream_reply, } from "./validate.js";
+export { luv_send_to_openai_http_request, openai_http_response_to_luv_reply, openai_http_stream_to_luv_stream, openaiClient, type HTTPRequest, type HTTPResponse, type OpenAIClient, type OpenAIClientConfig, type ErrorPolicy, type ErrorPolicyMap, } from "./transport/openai_chat.js";
+export { luv_send_to_anthropic_http_request, anthropic_http_response_to_luv_reply, anthropic_http_stream_to_luv_stream, anthropicClient, type AnthropicClient, type AnthropicClientConfig, } from "./transport/anthropic_messages.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { LUV_SPEC_VERSION, ERROR_CATEGORIES, LuvError } from "./types.js";
+export { encodeBlock, encodeMessage, encodeNode, encodeConversation, encodeReply, encodeUsage, encodeStreamEventReply, encodeStreamReply, encodeValidationError, encodeValidationResult, stringify, } from "./encode.js";
+export { consume_luv_stream_reply, produce_luv_stream_reply, } from "./stream.js";
+export { validate_luv_conversation, validate_luv_message, validate_luv_block, validate_luv_reply, validate_luv_stream_reply, } from "./validate.js";
+export { luv_send_to_openai_http_request, openai_http_response_to_luv_reply, openai_http_stream_to_luv_stream, openaiClient, } from "./transport/openai_chat.js";
+export { luv_send_to_anthropic_http_request, anthropic_http_response_to_luv_reply, anthropic_http_stream_to_luv_stream, anthropicClient, } from "./transport/anthropic_messages.js";

package/dist/morphisms/anthropic_messages.d.ts

@@ -0,0 +1,14 @@
+import type { Conversation, Reply, Usage, StreamReply } from "../types.js";
+export interface AnthropicRequestOptions {
+    model: string;
+    max_tokens: number;
+    stream?: boolean;
+    tools?: unknown[];
+    tool_choice?: unknown;
+    temperature?: number;
+    stop_sequences?: string[];
+}
+export declare function luv_conversation_to_anthropic_request(conv: Conversation, opts: AnthropicRequestOptions): unknown;
+export declare function anthropicUsageEnvelope(model: unknown, usage: unknown): Usage | null;
+export declare function anthropic_response_to_luv_reply(resp: unknown): Reply;
+export declare function anthropic_stream_to_luv_stream(events: unknown[]): StreamReply;

package/dist/morphisms/anthropic_messages.js

@@ -0,0 +1,238 @@
+// luv_conversation_to_anthropic_request
+// Builds an Anthropic Messages request body from a luv Conversation
+// (walked linearly in array order) plus per-call options.
+export function luv_conversation_to_anthropic_request(conv, opts) {
+    const systemTexts = [];
+    // First pass: per-node emission into a flat messages list.
+    const initial = [];
+    for (const node of conv.nodes) {
+        const m = node.message;
+        if (m.role === "system") {
+            const txt = m.content
+                .filter((b) => b.kind === "text")
+                .map((b) => b.text)
+                .join("");
+            systemTexts.push(txt);
+            continue;
+        }
+        if (m.role !== "user" && m.role !== "assistant")
+            continue;
+        const allText = m.content.every((b) => b.kind === "text");
+        let content;
+        if (allText) {
+            content = m.content
+                .map((b) => b.text)
+                .join("");
+        }
+        else {
+            const arr = [];
+            for (const b of m.content) {
+                const cb = blockToAnthropic(b);
+                if (cb !== null)
+                    arr.push(cb);
+            }
+            // If every block dropped (e.g., only error blocks), Anthropic
+            // rejects content: []. Fall back to empty string.
+            content = arr.length > 0 ? arr : "";
+        }
+        initial.push({ role: m.role, content });
+    }
+    // Second pass: merge consecutive same-role messages.
+    const merged = [];
+    for (const msg of initial) {
+        const prev = merged[merged.length - 1];
+        if (!prev || prev.role !== msg.role) {
+            merged.push({ role: msg.role, content: msg.content });
+            continue;
+        }
+        if (typeof prev.content === "string" && typeof msg.content === "string") {
+            prev.content = prev.content + msg.content;
+        }
+        else {
+            const prevArr = typeof prev.content === "string"
+                ? prev.content.length > 0
+                    ? [{ type: "text", text: prev.content }]
+                    : []
+                : prev.content;
+            const newArr = typeof msg.content === "string"
+                ? msg.content.length > 0
+                    ? [{ type: "text", text: msg.content }]
+                    : []
+                : msg.content;
+            prev.content = [...prevArr, ...newArr];
+        }
+    }
+    // Canonical key order: model, max_tokens, messages, [system], [stream],
+    // [tools], [tool_choice], [temperature], [stop_sequences].
+    const req = {
+        model: opts.model,
+        max_tokens: opts.max_tokens,
+        messages: merged,
+    };
+    if (systemTexts.length > 0)
+        req.system = systemTexts.join("\n\n");
+    if (opts.stream !== undefined)
+        req.stream = opts.stream;
+    if (opts.tools !== undefined)
+        req.tools = opts.tools;
+    if (opts.tool_choice !== undefined)
+        req.tool_choice = opts.tool_choice;
+    if (opts.temperature !== undefined)
+        req.temperature = opts.temperature;
+    if (opts.stop_sequences !== undefined)
+        req.stop_sequences = opts.stop_sequences;
+    return req;
+}
+function blockToAnthropic(b) {
+    if (b.kind === "text") {
+        return { type: "text", text: b.text };
+    }
+    if (b.kind === "tool_call") {
+        let input = {};
+        try {
+            input = JSON.parse(b.args);
+        }
+        catch {
+            // Malformed args: pass empty object. Documented in homomorphism_exceptions.
+        }
+        return { type: "tool_use", id: b.id, name: b.name, input };
+    }
+    if (b.kind === "tool_result") {
+        return { type: "tool_result", tool_use_id: b.call_id, content: b.text };
+    }
+    // error blocks not representable; drop (documented in homomorphism_exceptions).
+    return null;
+}
+// Build the luv usage envelope from an Anthropic usage object + model.
+// Token counts are preserved faithfully (not normalized); see SPEC §2.5.
+export function anthropicUsageEnvelope(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). For
+    // streams this is the merged message_start + message_delta usage. `raw` is
+    // opaque to the core.
+    return {
+        provider: "anthropic_messages",
+        model: typeof model === "string" ? model : "",
+        raw: usage,
+    };
+}
+// anthropic_response_to_luv_reply
+export function anthropic_response_to_luv_reply(resp) {
+    const r = resp;
+    const blocks = [];
+    for (const cb of r.content) {
+        if (cb.type === "text") {
+            blocks.push({ kind: "text", text: cb.text });
+        }
+        else if (cb.type === "tool_use") {
+            blocks.push({
+                kind: "tool_call",
+                id: cb.id,
+                name: cb.name,
+                args: JSON.stringify(cb.input),
+            });
+        }
+    }
+    return {
+        message: { role: "assistant", content: blocks },
+        finish_reason: mapStopReason(r.stop_reason),
+        usage: anthropicUsageEnvelope(r.model, r.usage),
+    };
+}
+function mapStopReason(r) {
+    switch (r) {
+        case "end_turn":
+            return "end_turn";
+        case "max_tokens":
+            return "max_tokens";
+        case "stop_sequence":
+            return "end_turn";
+        case "tool_use":
+            return "end_turn";
+        default:
+            return "end_turn";
+    }
+}
+// anthropic_stream_to_luv_stream
+export function anthropic_stream_to_luv_stream(events) {
+    const out = [];
+    let storedStopReason = null;
+    let model = null;
+    let usageObj = null;
+    for (const evt of events) {
+        const e = evt;
+        switch (e.type) {
+            case "message_start":
+                out.push({ kind: "message_start" });
+                if (e.message) {
+                    if (typeof e.message.model === "string")
+                        model = e.message.model;
+                    if (e.message.usage)
+                        usageObj = { ...e.message.usage };
+                }
+                break;
+            case "content_block_start": {
+                const cb = e.content_block;
+                if (!cb)
+                    break;
+                if (cb.type === "text") {
+                    out.push({
+                        kind: "block_start",
+                        block: { kind: "text", text: "" },
+                    });
+                }
+                else if (cb.type === "tool_use") {
+                    out.push({
+                        kind: "block_start",
+                        block: {
+                            kind: "tool_call",
+                            id: cb.id ?? "",
+                            name: cb.name ?? "",
+                            args: "",
+                        },
+                    });
+                }
+                break;
+            }
+            case "content_block_delta": {
+                const d = e.delta;
+                if (!d)
+                    break;
+                if (d.type === "text_delta" && typeof d.text === "string") {
+                    out.push({ kind: "text_delta", text: d.text });
+                }
+                else if (d.type === "input_json_delta" &&
+                    typeof d.partial_json === "string") {
+                    out.push({ kind: "args_delta", args: d.partial_json });
+                }
+                break;
+            }
+            case "content_block_stop":
+                out.push({ kind: "block_end" });
+                break;
+            case "message_delta":
+                if (e.delta && typeof e.delta.stop_reason === "string") {
+                    storedStopReason = e.delta.stop_reason;
+                }
+                // Anthropic reports final output_tokens (and running fields) here;
+                // merge over the message_start usage.
+                if (e.usage) {
+                    usageObj = { ...(usageObj ?? {}), ...e.usage };
+                }
+                break;
+            case "message_stop":
+                out.push({
+                    kind: "message_end",
+                    finish_reason: mapStopReason(storedStopReason),
+                    usage: anthropicUsageEnvelope(model, usageObj),
+                });
+                break;
+            case "ping":
+            default:
+                break;
+        }
+    }
+    return out;
+}

package/dist/morphisms/openai_chat.d.ts

@@ -0,0 +1,10 @@
+import type { Conversation, Reply, Usage, StreamReply } from "../types.js";
+export interface OpenAIRequestOptions {
+    model: string;
+    stream?: boolean;
+    tools?: unknown[];
+}
+export declare function luv_conversation_to_openai_request(conv: Conversation, opts: OpenAIRequestOptions): unknown;
+export declare function openaiUsageEnvelope(model: unknown, usage: unknown): Usage | null;
+export declare function openai_response_to_luv_reply(resp: unknown): Reply;
+export declare function openai_stream_to_luv_stream(chunks: unknown[]): StreamReply;