@volter/twin-openai 0.1.1 → 2.0.0

package/dist/src/semantics/assistants.js

@@ -0,0 +1,331 @@
+import { estimateTokens, stubToolCall } from "../openai-stub.js";
+import { coreAnswer, progress } from "./progress.js";
+import { at, epoch, invalid, missing, objectOr, pick } from "./shared.js";
+const ASSISTANT = 'AssistantObject';
+const THREAD = 'ThreadObject';
+const MESSAGE = 'MessageObject';
+const RUN = 'RunObject';
+// ── assistants ──────────────────────────────────────────────────────────────────────────────
+/** An assistant's tool resources: as sent, with the empty store list a file_search tool searches when none is named
+ *  (the reference's modify example answers `"tool_resources": {"file_search": {"vector_store_ids": []}}` for an
+ *  assistant given the file_search tool and no stores: https://platform.openai.com/docs/api-reference/assistants/modifyAssistant). */
+function toolResources(tools, sent) {
+    const out = { ...(sent && typeof sent === 'object' ? sent : {}) };
+    if (Array.isArray(tools) && tools.some((t) => t?.type === 'file_search') && !out.file_search)
+        out.file_search = { vector_store_ids: [] };
+    // and the empty file list a code interpreter works on (the reference's listRuns and getThread examples answer
+    // `"code_interpreter": {"file_ids": []}`)
+    if (Array.isArray(tools) && tools.some((t) => t?.type === 'code_interpreter') && !out.code_interpreter)
+        out.code_interpreter = { file_ids: [] };
+    return out;
+}
+const createAssistant = async (ctx) => {
+    const p = ctx.params;
+    if (p.model === undefined || p.model === '')
+        return invalid(ctx, 'you must provide a model parameter', 'model');
+    const tools = Array.isArray(p.tools) ? p.tools : [];
+    const fields = {
+        object: 'assistant', created_at: epoch(ctx),
+        name: p.name ?? null, description: p.description ?? null,
+        model: String(p.model), instructions: p.instructions ?? null,
+        tools,
+        tool_resources: toolResources(tools, p.tool_resources),
+        metadata: objectOr(p.metadata, {}),
+        // sampling "Defaults to 1" (https://platform.openai.com/docs/api-reference/assistants/object, `temperature`, `top_p`)
+        temperature: p.temperature ?? 1, top_p: p.top_p ?? 1,
+        response_format: p.response_format ?? 'auto',
+    };
+    return ctx.reply(await ctx.write(ASSISTANT, ctx.mint(ASSISTANT), fields, 'assistant.create'));
+};
+// modify replaces only the fields the request names
+const modifyAssistant = async (ctx) => {
+    const id = String(ctx.id);
+    const current = ctx.get(ASSISTANT, id);
+    if (!current)
+        return ctx.notFound(ASSISTANT, id);
+    const fields = pick(ctx.params, ['name', 'description', 'model', 'instructions', 'tools', 'tool_resources', 'metadata', 'temperature', 'top_p', 'response_format']);
+    if (fields.tools !== undefined || fields.tool_resources !== undefined)
+        fields.tool_resources = toolResources(fields.tools ?? current.tools, fields.tool_resources ?? current.tool_resources);
+    return ctx.reply(await ctx.write(ASSISTANT, id, fields, 'assistant.update'));
+};
+// ── threads and messages ────────────────────────────────────────────────────────────────────
+/** The id of the next message appended to a thread: the thread's next sequence number. */
+const nextMessage = (ctx, threadId) => {
+    const seq = ctx.rowsRaw(MESSAGE, { withDeleted: true }).filter((r) => r.thread_id === threadId).length + 1;
+    return { seq, id: `msg-twin-${threadId}-${seq}` };
+};
+/** A message appended to a thread, named by the thread's next sequence number (or the id a run
+ *  reserved for its reply). */
+async function append(ctx, threadId, p, reserved) {
+    const next = nextMessage(ctx, threadId);
+    const id = reserved ?? next.id;
+    const seq = reserved ? Number(reserved.split('-').at(-1)) : next.seq;
+    const text = typeof p.content === 'string'
+        ? p.content
+        : Array.isArray(p.content) ? p.content.map((part) => String(part.text?.value ?? part.text ?? '')).join('') : '';
+    const fields = {
+        object: 'thread.message', created_at: epoch(ctx), thread_id: threadId, role: typeof p.role === 'string' ? p.role : 'user',
+        // a message added to a thread is whole when it is added
+        status: 'completed', completed_at: epoch(ctx), incomplete_at: null, incomplete_details: null,
+        content: [{ type: 'text', text: { value: text, annotations: [] } }],
+        assistant_id: p.assistant_id ?? null, run_id: p.run_id ?? null,
+        attachments: Array.isArray(p.attachments) ? p.attachments : [],
+        metadata: objectOr(p.metadata, {}),
+        _seq: seq,
+    };
+    return ctx.write(MESSAGE, id, fields, 'message.create');
+}
+/** The thread the path names (a deleted one still holds its messages and runs), or OpenAI's answer. */
+function thread(ctx) {
+    const id = at(ctx, 'thread_id');
+    return ctx.row(THREAD, id, { withDeleted: true }) ? { id } : { answer: ctx.notFound(THREAD, id) };
+}
+const createThread = async (ctx) => {
+    const p = ctx.params;
+    const id = ctx.mint(THREAD);
+    // a thread made with no tool resources has none: `{}` (the reference's createThread examples)
+    const body = await ctx.write(THREAD, id, { object: 'thread', created_at: epoch(ctx), metadata: objectOr(p.metadata, {}), tool_resources: objectOr(p.tool_resources, {}) }, 'thread.create');
+    // messages given at creation are the thread's first
+    if (Array.isArray(p.messages))
+        for (const m of p.messages)
+            await append(ctx, id, m);
+    return ctx.reply(body);
+};
+const modifyThread = async (ctx) => {
+    const id = String(ctx.id);
+    if (!ctx.get(THREAD, id))
+        return ctx.notFound(THREAD, id);
+    return ctx.reply(await ctx.write(THREAD, id, pick(ctx.params, ['metadata', 'tool_resources']), 'thread.update'));
+};
+const createMessage = async (ctx) => {
+    const found = thread(ctx);
+    if ('answer' in found)
+        return found.answer;
+    if (ctx.params.content === undefined)
+        return invalid(ctx, 'you must provide a content parameter', 'content');
+    return ctx.reply(await append(ctx, found.id, ctx.params));
+};
+// ── runs and steps ──────────────────────────────────────────────────────────────────────────
+/** The run the path names under its thread, raw (its reply message is bookkeeping), or OpenAI's answer. */
+function run(ctx) {
+    const id = at(ctx, 'run_id');
+    const found = ctx.row(RUN, id);
+    return found && found.thread_id === at(ctx, 'thread_id') ? { run: found } : { answer: ctx.notFound(RUN, id) };
+}
+const replyText = (model) => `[twin-stub:${model}] deterministic assistant run output (no model weights are run)`;
+/** What a completed run carries: its reply message and usage; a run that waited on its tools keeps when it started. */
+function finishRun(ctx) {
+    return (row, end) => {
+        if (end !== 'completed')
+            return {};
+        const text = replyText(String(row.model));
+        return { _reply_msg: nextMessage(ctx, String(row.thread_id)).id, expires_at: null, ...(row.started_at ? { started_at: row.started_at } : {}), usage: { prompt_tokens: 0, completion_tokens: estimateTokens(text), total_tokens: estimateTokens(text) } };
+    };
+}
+/** The function tools a run's model calls: its placeholder decision is to call them (each one, or the one
+ *  `tool_choice` names, or the first when calls are not parallel), unless `tool_choice` is `none` or their outputs
+ *  were already submitted. */
+function toolCalls(r, userText = '') {
+    const functions = (Array.isArray(r.tools) ? r.tools : []).filter((t) => t.type === 'function');
+    if (!functions.length || r.tool_choice === 'none' || r._tools_answered)
+        return [];
+    const named = r.tool_choice && typeof r.tool_choice === 'object' ? String(r.tool_choice.function?.name ?? '') : '';
+    const chosen = named ? functions.filter((t) => t.function?.name === named) : r.parallel_tool_calls === false ? functions.slice(0, 1) : functions;
+    const run = String(r.id).replace(/[^A-Za-z0-9]+/g, '_');
+    return chosen.map((tool, i) => {
+        const call = stubToolCall([tool], i + 1, undefined, userText);
+        return { id: `call_${run}_${i + 1}`, type: 'function', function: call.function };
+    });
+}
+/** A run whose model calls its function tools stops at `requires_action`, naming the calls it waits on
+ *  (https://platform.openai.com/docs/assistants/tools/function-calling: "the Run will enter a requires_action
+ *  status"); the vendor's moves, decided and written at once. */
+async function waitOnTools(ctx, id) {
+    return ctx.atomically((rows) => {
+        const current = rows(RUN).find((r) => r.id === id);
+        if (!current || current.status !== 'queued')
+            return { value: false };
+        // the thread's last user message is what the model answers, and what its calls take their values from
+        const asked = rows(MESSAGE).filter((m) => m.thread_id === current.thread_id && m.role === 'user').sort((a, b) => Number(a._seq ?? 0) - Number(b._seq ?? 0)).at(-1);
+        const calls = toolCalls(current, String(asked?.content?.[0]?.text?.value ?? ''));
+        if (!calls.length)
+            return { value: false };
+        if (ctx.legal(RUN, 'status', ctx.call.operation.id, 'queued', 'in_progress', id, 'vendor') || ctx.legal(RUN, 'status', ctx.call.operation.id, 'in_progress', 'requires_action', id, 'vendor'))
+            return { value: false };
+        const fields = { status: 'requires_action', started_at: epoch(ctx), required_action: { type: 'submit_tool_outputs', submit_tool_outputs: { tool_calls: calls } }, _tool_calls: calls };
+        return { value: true, write: { resource: RUN, id, fields, operation: 'run.update' } };
+    });
+}
+/** Observe the vendor's work on a run: it stops for its function tools, else the read that completes it appends
+ *  the reply to its thread. */
+async function work(ctx, id) {
+    if (await waitOnTools(ctx, id))
+        return;
+    const moved = await progress(ctx, RUN, id, finishRun(ctx));
+    if (moved?.to !== 'completed')
+        return;
+    const r = moved.row;
+    await append(ctx, String(r.thread_id), { role: 'assistant', content: replyText(String(r.model)), assistant_id: r.assistant_id, run_id: r.id }, String(r._reply_msg));
+}
+/** A run's steps, newest first: the call of its function tools (done once their outputs are in, each call with its
+ *  output), and, once it completed, the creation of its reply message. */
+function steps(r) {
+    const base = { object: 'thread.run.step', run_id: String(r.id), assistant_id: String(r.assistant_id), thread_id: String(r.thread_id), cancelled_at: null, expired_at: null, failed_at: null, last_error: null, metadata: {} };
+    const out = [];
+    const calls = (r._tool_calls ?? []);
+    if (calls.length) {
+        const outputs = (r._tool_outputs ?? {});
+        const done = r._tools_answered === true;
+        const cancelled = !done && (r.status === 'cancelled' || r.status === 'cancelling');
+        out.push({
+            ...base, id: `step-${r.id}-1`, created_at: Number(r.started_at ?? r.created_at ?? 0), type: 'tool_calls',
+            status: done ? 'completed' : cancelled ? 'cancelled' : 'in_progress', completed_at: done ? Number(r._tools_answered_at ?? r.started_at ?? 0) : null,
+            ...(cancelled ? { cancelled_at: Number(r.cancelled_at ?? r.started_at ?? 0) } : {}),
+            step_details: { type: 'tool_calls', tool_calls: calls.map((c) => ({ ...c, function: { ...c.function, output: done ? (outputs[String(c.id)] ?? null) : null } })) },
+            usage: null,
+        });
+    }
+    if (r.status === 'completed') {
+        const created = Number(r.completed_at ?? r.created_at ?? 0);
+        out.unshift({
+            ...base, id: `step-${r.id}-${out.length + 1}`, created_at: created,
+            type: 'message_creation', status: 'completed', completed_at: created,
+            step_details: { type: 'message_creation', message_creation: { message_id: String(r._reply_msg ?? '') } },
+            usage: r.usage ?? null,
+        });
+    }
+    return out;
+}
+const createRun = async (ctx) => {
+    const found = thread(ctx);
+    if ('answer' in found)
+        return found.answer;
+    const p = ctx.params;
+    if (p.assistant_id === undefined || p.assistant_id === '')
+        return invalid(ctx, 'you must provide an assistant_id parameter', 'assistant_id');
+    const assistantId = String(p.assistant_id);
+    const assistant = ctx.get(ASSISTANT, assistantId);
+    if (!assistant)
+        return ctx.notFound(ASSISTANT, assistantId);
+    const id = ctx.mint(RUN);
+    const created = epoch(ctx);
+    const model = typeof p.model === 'string' && p.model ? p.model : String(assistant.model);
+    const fields = {
+        object: 'thread.run', created_at: created, thread_id: found.id, assistant_id: assistantId,
+        status: 'queued', model, instructions: p.instructions ?? assistant.instructions ?? null,
+        tools: Array.isArray(p.tools) ? p.tools : (assistant.tools ?? []),
+        // the tool resources it runs with, its assistant's (the reference's cancelRun example; spec/patches.json)
+        tool_resources: assistant.tool_resources ?? {},
+        // a run in flight expires ten minutes after it was created; a completed one no longer does (the reference's
+        // streamed run: `expires_at` 600 seconds past `created_at` until `thread.run.completed` answers it null)
+        started_at: null, completed_at: null, expires_at: created + 600, cancelled_at: null, failed_at: null,
+        required_action: null, last_error: null, usage: null, incomplete_details: null,
+        // the request's sampling, else the assistant's (https://platform.openai.com/docs/api-reference/runs/object)
+        temperature: p.temperature ?? assistant.temperature ?? 1, top_p: p.top_p ?? assistant.top_p ?? 1,
+        // the request's settings as sent, or OpenAI's defaults for a run
+        max_prompt_tokens: p.max_prompt_tokens ?? null, max_completion_tokens: p.max_completion_tokens ?? null,
+        parallel_tool_calls: p.parallel_tool_calls ?? true, tool_choice: p.tool_choice ?? 'auto',
+        response_format: p.response_format ?? assistant.response_format ?? 'auto', truncation_strategy: p.truncation_strategy ?? { type: 'auto', last_messages: null },
+        metadata: objectOr(p.metadata, {}),
+    };
+    const created_ = await ctx.write(RUN, id, fields, 'run.create');
+    return p.stream === true ? streamRun(ctx, created_) : ctx.reply(created_);
+};
+/** A run created with `stream: true` answers its events as it runs (https://platform.openai.com/docs/api-reference/assistants-streaming/events):
+ *  created, queued and in progress, then either its tool-call step and `thread.run.requires_action` (a run that waits on
+ *  its function tools), or its message-creation step, the reply message with its text as deltas, and the run completed;
+ *  then `done`. Submitted tool outputs stream the same way from the finished tool-call step. The twin works the run in
+ *  the stream as a read would; each event is a server-sent `event:` with its object as `data`. */
+async function streamRun(ctx, queued, submitted = false) {
+    const id = String(queued.id);
+    await work(ctx, id);
+    const done = ctx.get(RUN, id);
+    const all = steps(ctx.row(RUN, id));
+    const toolStep = all.find((x) => x.type === 'tool_calls');
+    const step = all.find((x) => x.type === 'message_creation');
+    const message = step ? ctx.get(MESSAGE, String(step.step_details.message_creation.message_id)) : undefined;
+    const started = { ...done, status: 'in_progress', completed_at: null, required_action: null, usage: null };
+    const events = submitted
+        ? [['thread.run.step.completed', toolStep], ['thread.run.queued', queued], ['thread.run.in_progress', started]]
+        : [['thread.run.created', queued], ['thread.run.queued', queued], ['thread.run.in_progress', started]];
+    if (done.status === 'requires_action' && toolStep) {
+        events.push(['thread.run.step.created', toolStep], ['thread.run.step.in_progress', toolStep], ['thread.run.requires_action', done]);
+    }
+    else {
+        if (step && message) {
+            const text = String(message.content[0]?.text?.value ?? '');
+            const stepRunning = { ...step, status: 'in_progress', completed_at: null, usage: null };
+            const messageRunning = { ...message, status: 'in_progress', completed_at: null, content: [] };
+            events.push(['thread.run.step.created', stepRunning], ['thread.run.step.in_progress', stepRunning], ['thread.message.created', messageRunning], ['thread.message.in_progress', messageRunning]);
+            for (let i = 0; i < text.length; i += 20)
+                events.push(['thread.message.delta', { id: message.id, object: 'thread.message.delta', delta: { content: [{ index: 0, type: 'text', text: { value: text.slice(i, i + 20), annotations: [] } }] } }]);
+            events.push(['thread.message.completed', message], ['thread.run.step.completed', step]);
+        }
+        events.push(['thread.run.completed', done]);
+    }
+    const body = events.map(([event, data]) => `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`).join('') + 'event: done\ndata: [DONE]\n\n';
+    return ctx.raw(body, { headers: { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-cache' } });
+}
+/** Submitting a waiting run's tool outputs queues it again to finish (https://platform.openai.com/docs/api-reference/runs/submitToolOutputs):
+ *  only a run at `requires_action` takes them, and they must answer every call it waits on, and only those. */
+const submitToolOutputs = async (ctx) => {
+    const found = run(ctx);
+    if ('answer' in found)
+        return found.answer;
+    const r = found.run;
+    const refusal = ctx.legal(RUN, 'status', 'submitToolOuputsToRun', r.status, 'queued');
+    if (refusal)
+        return ctx.refuse(refusal);
+    const outputs = Array.isArray(ctx.params.tool_outputs) ? ctx.params.tool_outputs : undefined;
+    if (!outputs)
+        return invalid(ctx, 'you must provide a tool_outputs array', 'tool_outputs');
+    const waiting = (r._tool_calls ?? []).map((c) => String(c.id));
+    const given = outputs.map((o) => String(o.tool_call_id ?? ''));
+    const unknown = given.find((g) => !waiting.includes(g));
+    if (unknown !== undefined)
+        return invalid(ctx, `Invalid tool_call_id: ${unknown}. No tool call with that id is waiting on this run.`, 'tool_outputs');
+    const missingIds = waiting.filter((w) => !given.includes(w));
+    if (missingIds.length)
+        return invalid(ctx, `Expected tool outputs for call_ids ${JSON.stringify(waiting)}, got ${JSON.stringify(given)}`, 'tool_outputs');
+    const fields = { status: 'queued', required_action: null, _tools_answered: true, _tools_answered_at: epoch(ctx), _tool_outputs: Object.fromEntries(outputs.map((o) => [String(o.tool_call_id), String(o.output ?? '')])) };
+    const queued = await ctx.write(RUN, String(r.id), fields, 'run.update');
+    return ctx.params.stream === true ? streamRun(ctx, queued, true) : ctx.reply(queued);
+};
+const listRunSteps = async (ctx) => {
+    await work(ctx, at(ctx, 'run_id'));
+    const found = run(ctx);
+    if ('answer' in found)
+        return found.answer;
+    const data = steps(found.run);
+    return ctx.reply({ object: 'list', data, has_more: false, first_id: data[0]?.id ?? null, last_id: data.at(-1)?.id ?? null });
+};
+const getRunStep = async (ctx) => {
+    await work(ctx, at(ctx, 'run_id'));
+    const found = run(ctx);
+    if ('answer' in found)
+        return found.answer;
+    const id = at(ctx, 'step_id');
+    const step = steps(found.run).find((s) => s.id === id);
+    return step ? ctx.reply(step) : missing(ctx, `No run step found with id '${id}'.`);
+};
+export const assistants = {
+    createAssistant,
+    modifyAssistant,
+    createThread,
+    modifyThread,
+    createMessage,
+    createRun,
+    submitToolOuputsToRun: submitToolOutputs,
+    listRunSteps,
+    getRunStep,
+    getRun: async (ctx) => {
+        await work(ctx, at(ctx, 'run_id'));
+        return coreAnswer(ctx);
+    },
+    listRuns: async (ctx) => {
+        const threadId = at(ctx, 'thread_id');
+        for (const r of ctx.rowsRaw(RUN).filter((x) => x.thread_id === threadId))
+            await work(ctx, String(r.id));
+        return coreAnswer(ctx);
+    },
+};

package/dist/src/semantics/audio.d.ts

@@ -0,0 +1,2 @@
+import type { Semantics } from '@volter/world-core';
+export declare const audio: Record<string, Semantics>;

package/dist/src/semantics/audio.js

@@ -0,0 +1,27 @@
+import { handleSpeech, handleTranscription } from "../openai-twin.js";
+import { recordUsage, send } from "./shared.js";
+/** A transcription or translation is billed by the seconds of audio heard (the usage report's `seconds`). */
+async function recordSeconds(ctx, r) {
+    if (r.status === 200 && 'seconds' in r && typeof r.seconds === 'number')
+        await recordUsage(ctx, 'audio_transcriptions', String(ctx.params.model), 0, 0, { seconds: Math.ceil(r.seconds) });
+}
+export const audio = {
+    createTranscription: async (ctx) => {
+        const r = handleTranscription(ctx.params, false);
+        await recordSeconds(ctx, r);
+        return 'events' in r && r.events ? ctx.sse(r.events) : send(ctx, r);
+    },
+    createTranslation: async (ctx) => {
+        const r = handleTranscription(ctx.params, true);
+        await recordSeconds(ctx, r);
+        return send(ctx, r);
+    },
+    // the audio file itself, not JSON
+    createSpeech: async (ctx) => {
+        const r = handleSpeech(ctx.params);
+        // speech is billed by the characters it speaks (the usage report's `characters`)
+        if ('audio' in r)
+            await recordUsage(ctx, 'audio_speeches', String(ctx.params.model), 0, 0, { characters: String(ctx.params.input ?? '').length });
+        return 'audio' in r ? ctx.raw(r.audio, { headers: { 'content-type': r.type } }) : send(ctx, r);
+    },
+};

package/dist/src/semantics/batches.d.ts

@@ -0,0 +1,4 @@
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+export declare const batches: Record<string, Semantics>;
+/** Every batch OpenAI is still working on, observed (a read observes all the vendor's work before it answers). */
+export declare function observeBatches(ctx: SemanticsContext): Promise<void>;

package/dist/src/semantics/batches.js

@@ -0,0 +1,86 @@
+import { coreAnswer, inFlight, progress } from "./progress.js";
+import { epoch, invalid, objectOr } from "./shared.js";
+/** The request lines of a batch's input file. */
+const requestLines = (ctx, row) => String(ctx.row('OpenAIFile', String(row.input_file_id), { withDeleted: true })?._content ?? '').split('\n').filter((l) => l.trim());
+/** What a finished batch carries: its output file and its request counts, every request answered
+ *  (https://platform.openai.com/docs/api-reference/batch/object, `request_counts`). */
+const finish = (ctx) => (row, end) => {
+    if (end !== 'completed')
+        return {};
+    const total = requestLines(ctx, row).length;
+    return { output_file_id: `file-twin-batchout-${String(row.id)}`, request_counts: { total, completed: total, failed: 0 } };
+};
+const create = async (ctx) => {
+    const p = ctx.params;
+    if (p.input_file_id === undefined || p.input_file_id === '')
+        return invalid(ctx, 'you must provide an input_file_id parameter', 'input_file_id');
+    if (p.endpoint === undefined || p.endpoint === '')
+        return invalid(ctx, 'you must provide an endpoint parameter', 'endpoint');
+    if (p.completion_window === undefined)
+        return invalid(ctx, 'you must provide a completion_window parameter', 'completion_window');
+    const id = ctx.mint('Batch');
+    const created = epoch(ctx);
+    const fields = {
+        object: 'batch',
+        endpoint: String(p.endpoint),
+        input_file_id: String(p.input_file_id),
+        completion_window: String(p.completion_window),
+        status: 'validating',
+        output_file_id: null,
+        error_file_id: null,
+        created_at: created,
+        // the batch object's timestamps, each null until the batch gets there; it expires at the end of its completion
+        // window (https://platform.openai.com/docs/api-reference/batch/object)
+        in_progress_at: null,
+        expires_at: created + 24 * 3600,
+        finalizing_at: null,
+        completed_at: null,
+        failed_at: null,
+        expired_at: null,
+        cancelling_at: null,
+        cancelled_at: null,
+        errors: null,
+        request_counts: { total: 0, completed: 0, failed: 0 },
+        metadata: objectOr(p.metadata, null),
+    };
+    return ctx.reply(await ctx.write('Batch', id, fields, 'batch.create'));
+};
+/** Work a batch on; the read that completes it writes its output file, a result for each request line of its input. */
+async function work(ctx, id) {
+    const moved = await progress(ctx, 'Batch', id, finish(ctx));
+    if (moved?.to !== 'completed')
+        return;
+    const lines = requestLines(ctx, moved.row);
+    const results = lines.map((line, i) => {
+        let req = {};
+        try {
+            req = JSON.parse(line);
+        }
+        catch { /* a line that is not JSON answers an error for it */ }
+        return JSON.stringify({ id: `batch_req_twin_${i + 1}`, custom_id: req.custom_id ?? null, response: { status_code: 200, request_id: `req_twin_${i + 1}`, body: { object: 'chat.completion', model: req.body?.model ?? null, choices: [{ index: 0, message: { role: 'assistant', content: '[twin-stub] deterministic batch result' }, finish_reason: 'stop' }] } }, error: null });
+    });
+    const content = results.length ? `${results.join('\n')}\n` : '';
+    // the output is deleted thirty days after the batch completes (developers.openai.com/api/docs/guides/batch)
+    await ctx.write('OpenAIFile', String(moved.row.output_file_id), { object: 'file', bytes: new TextEncoder().encode(content).length, created_at: epoch(ctx), expires_at: Number(moved.row.completed_at ?? epoch(ctx)) + 30 * 24 * 3600, filename: 'batch_output.jsonl', purpose: 'batch_output', status: 'processed', _content: content }, 'file.create');
+}
+// the organization's batches, each one's work observed first
+const listBatches = async (ctx) => {
+    for (const row of ctx.rowsRaw('Batch'))
+        if (inFlight('Batch', row))
+            await work(ctx, String(row.id));
+    return coreAnswer(ctx);
+};
+export const batches = {
+    createBatch: create,
+    retrieveBatch: async (ctx) => {
+        await work(ctx, String(ctx.id));
+        return coreAnswer(ctx);
+    },
+    listBatches,
+};
+/** Every batch OpenAI is still working on, observed (a read observes all the vendor's work before it answers). */
+export async function observeBatches(ctx) {
+    for (const row of ctx.rowsRaw('Batch'))
+        if (inFlight('Batch', row))
+            await work(ctx, String(row.id));
+}

package/dist/src/semantics/chat-completions.d.ts

@@ -0,0 +1,3 @@
+import type { Semantics } from '@volter/world-core';
+import { type OpenAIScenarioEngine } from '../openai-scenario.js';
+export declare function chatCompletions(engine: OpenAIScenarioEngine | undefined): Record<string, Semantics>;

package/dist/src/semantics/chat-completions.js

@@ -0,0 +1,58 @@
+import { serveScenario } from "../openai-scenario.js";
+import { buildChatCompletion, streamChat, validateChat } from "../openai-twin.js";
+import { page, recordUsage, send } from "./shared.js";
+const COMPLETION = 'CreateChatCompletionResponse';
+const create = (engine) => async (ctx) => {
+    const validated = validateChat(ctx.params);
+    if ('error' in validated)
+        return send(ctx, validated.error);
+    const args = validated.args;
+    // the scenario decides the turn and honors a fault before any completion exists: a status fault
+    // is this vendor's own refusal envelope, decided before a stream would start
+    const decision = engine ? await serveScenario(engine, { model: args.model, messages: args.messages, tools: args.tools, maxTokens: args.maxTokens }, new URL(ctx.call.request.url).pathname) : undefined;
+    if (decision?.kind === 'fault')
+        return send(ctx, decision.result);
+    const events = [];
+    const result = args.stream ? streamChat(args, (e) => { if (e.data)
+        events.push({ data: e.data }); }, ctx.occurredAt, decision) : buildChatCompletion(args, ctx.occurredAt, decision);
+    // the request's messages are kept for the stored completion's /messages
+    // as the messages list shows them (https://platform.openai.com/docs/api-reference/chat/getMessages): the text, the
+    // author's name or null, and the parts when the content was sent as parts, else null
+    const inputMessages = args.messages.map((m, i) => {
+        const parts = Array.isArray(m.content) ? m.content : null;
+        const content = parts ? parts.filter((c) => c.type === 'text').map((c) => String(c.text ?? '')).join('') : (m.content ?? null);
+        return { id: `${result.id}-msg-${i}`, role: m.role, content, name: m.name ?? null, content_parts: parts };
+    });
+    // a stored completion keeps its metadata, `{}` when none was sent (https://platform.openai.com/docs/api-reference/chat/object)
+    // and reads back each reply message with its tool calls and legacy function call, null when it made none (the
+    // reference's getChatCompletion and listChatCompletions examples)
+    // A stored completion also keeps the request that made it: its id, and the settings it was sampled with, as sent or
+    // their defaults (the reference's getChatCompletion example: request_id, seed, temperature, top_p, presence_penalty,
+    // frequency_penalty, input_user, tools, tool_choice, response_format; spec/patches.json adds them to the object)
+    const p = ctx.params;
+    const settings = {
+        request_id: `req_twin_${result.id.replace(/^chatcmpl-twin-/, '')}`,
+        seed: typeof p.seed === 'number' ? p.seed : parseInt(result.id.replace(/^chatcmpl-twin-/, ''), 36),
+        temperature: p.temperature ?? 1, top_p: p.top_p ?? 1, presence_penalty: p.presence_penalty ?? 0, frequency_penalty: p.frequency_penalty ?? 0,
+        input_user: p.user ?? null, tools: p.tools ?? null, tool_choice: p.tool_choice ?? null, response_format: p.response_format ?? null,
+    };
+    const stored = args.store === true ? { metadata: result.metadata ?? {}, ...settings, choices: result.choices.map((c) => ({ ...c, message: { ...c.message, tool_calls: c.message.tool_calls ?? null, function_call: null } })) } : {};
+    const { vendorData } = await ctx.writeDetailed(COMPLETION, result.id, { ...result, ...stored, _stored: args.store === true, _input_messages: inputMessages }, 'chat.completions.create');
+    // live use: the head performed the call, and the model's own words are the answer
+    const live = vendorData;
+    const answer = live && typeof live === 'object' && Array.isArray(live.choices) ? live : result;
+    await recordUsage(ctx, 'completions', answer.model, answer.usage?.prompt_tokens ?? result.usage.prompt_tokens, answer.usage?.completion_tokens ?? result.usage.completion_tokens);
+    return args.stream ? ctx.sse(events) : ctx.reply(answer);
+};
+// the request's messages, kept when the completion was stored
+const messages = async (ctx) => {
+    const id = String(ctx.id);
+    const row = ctx.row(COMPLETION, id);
+    return row ? page(ctx, row._input_messages ?? []) : ctx.notFound(COMPLETION, id);
+};
+export function chatCompletions(engine) {
+    return {
+        createChatCompletion: create(engine),
+        getChatCompletionMessages: messages,
+    };
+}

package/dist/src/semantics/containers.d.ts

@@ -0,0 +1,2 @@
+import type { Semantics } from '@volter/world-core';
+export declare const containers: Record<string, Semantics>;