@volter/twin-openai 0.1.2 → 2.0.1

package/src/semantics/assistants.ts

@@ -0,0 +1,336 @@
+// Assistants API (beta) semantics: assistants, threads, their messages, and runs with their steps.
+// Reads and deletes are the derived core's: an assistant, a thread, and a thread's messages (each
+// under its thread), and cancelling a run (the machine in ../manifest.ts moves its `status`). A run
+// is created `queued`, as OpenAI creates it; it cannot invoke a model, so when a read of it first
+// looks (./progress.ts) a run with function tools stops at `requires_action` for them (the placeholder
+// model calls them) and, once their outputs are submitted, completes, appending a labeled stub reply to
+// its thread; its steps (a tool-call step, a message-creation step) are read off the run, never stored;
+// a cancelled run ends `cancelled`.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { estimateTokens, stubToolCall } from '../openai-stub.ts';
+import { coreAnswer, progress } from './progress.ts';
+import { at, epoch, invalid, missing, objectOr, pick, type Row } from './shared.ts';
+
+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: unknown, sent: unknown): Row {
+  const out = { ...((sent && typeof sent === 'object' ? sent : {}) as Row) };
+  if (Array.isArray(tools) && tools.some((t) => (t as { type?: unknown })?.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 as { type?: unknown })?.type === 'code_interpreter') && !out.code_interpreter) out.code_interpreter = { file_ids: [] };
+  return out;
+}
+
+const createAssistant: Semantics = 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: Semantics = 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: SemanticsContext, threadId: string): { seq: number; id: string } => {
+  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: SemanticsContext, threadId: string, p: Row, reserved?: string): Promise<Row> {
+  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 as Row[]).map((part) => String((part as { text?: { value?: unknown } }).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: SemanticsContext): { id: string } | { answer: Response } {
+  const id = at(ctx, 'thread_id');
+  return ctx.row(THREAD, id, { withDeleted: true }) ? { id } : { answer: ctx.notFound(THREAD, id) };
+}
+
+const createThread: Semantics = 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 as Row[]) await append(ctx, id, m);
+  return ctx.reply(body);
+};
+
+const modifyThread: Semantics = 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: Semantics = 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: SemanticsContext): { run: Row } | { answer: Response } {
+  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: string): string => `[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: SemanticsContext): (row: Row, end: string) => Row {
+  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: Row, userText = ''): Row[] {
+  const functions = (Array.isArray(r.tools) ? r.tools : []).filter((t) => (t as { type?: unknown }).type === 'function') as Row[];
+  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 as Row).function as Row | undefined)?.name ?? '') : '';
+  const chosen = named ? functions.filter((t) => (t.function as Row | undefined)?.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: SemanticsContext, id: string): Promise<boolean> {
+  return ctx.atomically<boolean>((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 as Row[] | undefined)?.[0]?.text as { value?: unknown } | undefined)?.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: SemanticsContext, id: string): Promise<void> {
+  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: Row): Row[] {
+  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: Row[] = [];
+  const calls = (r._tool_calls ?? []) as Row[];
+  if (calls.length) {
+    const outputs = (r._tool_outputs ?? {}) as Record<string, string>;
+    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 as Row), 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: Semantics = 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: SemanticsContext, queued: Row, submitted = false): Promise<Response> {
+  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 as { message_creation: { message_id: string } }).message_creation.message_id)) : undefined;
+  const started = { ...done, status: 'in_progress', completed_at: null, required_action: null, usage: null };
+  const events: Array<[string, unknown]> = 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 as Row[])[0]?.text as { value?: unknown } | undefined)?.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: Semantics = 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 as Row[]) : undefined;
+  if (!outputs) return invalid(ctx, 'you must provide a tool_outputs array', 'tool_outputs');
+  const waiting = ((r._tool_calls ?? []) as Row[]).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: Semantics = 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: Semantics = 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: Record<string, Semantics> = {
+  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/src/semantics/audio.ts

@@ -0,0 +1,31 @@
+// Audio: labeled deterministic transcripts, and speech as a real audio file of silence; the twin runs no
+// speech model. Transcription and translation take the audio as a multipart file (the SDK's shape),
+// refuse anything that is not an audio file OpenAI transcribes, and name the file in the transcript.
+import type { Semantics } from '@volter/world-core';
+import { handleSpeech, handleTranscription, type OpenAIResponseEnvelope } from '../openai-twin.ts';
+import { recordUsage, send } from './shared.ts';
+
+/** A transcription or translation is billed by the seconds of audio heard (the usage report's `seconds`). */
+async function recordSeconds(ctx: Parameters<Semantics>[0], r: ReturnType<typeof handleTranscription>): Promise<void> {
+  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: Record<string, Semantics> = {
+  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 as OpenAIResponseEnvelope);
+  },
+  createTranslation: async (ctx) => {
+    const r = handleTranscription(ctx.params, true);
+    await recordSeconds(ctx, r);
+    return send(ctx, r as OpenAIResponseEnvelope);
+  },
+  // 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 as Uint8Array<ArrayBuffer>, { headers: { 'content-type': r.type } }) : send(ctx, r);
+  },
+};

package/src/semantics/batches.ts

@@ -0,0 +1,88 @@
+// Batch semantics. A batch is created `validating`, as OpenAI creates it, and cancel is the derived
+// core's (the machine in ../manifest.ts moves `status`: an in-flight batch goes to `cancelling`).
+// OpenAI works a batch on its own; the twin works it when a read first looks (./progress.ts): it
+// ends `completed` with its output file written (one result line per request line of its input file, answered
+// by the pack's stub), or `cancelled` if it was being cancelled.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { coreAnswer, inFlight, progress } from './progress.ts';
+import { epoch, invalid, objectOr, type Row } from './shared.ts';
+
+/** The request lines of a batch's input file. */
+const requestLines = (ctx: SemanticsContext, row: Row): string[] =>
+  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: SemanticsContext) => (row: Row, end: string): Row => {
+  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: Semantics = 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: SemanticsContext, id: string): Promise<void> {
+  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: Row = {};
+    try { req = JSON.parse(line) as Row; } 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 as Row | undefined)?.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: Semantics = 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: Record<string, Semantics> = {
+  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: SemanticsContext): Promise<void> {
+  for (const row of ctx.rowsRaw('Batch')) if (inFlight('Batch', row)) await work(ctx, String(row.id));
+}

package/src/semantics/chat-completions.ts

@@ -0,0 +1,66 @@
+// Chat completion semantics. A completion is the pack's behaviour, never a model: a scripted
+// scenario's turn when one is loaded and a handler matches, else the labeled deterministic stub.
+// Every completion is recorded (the call is the change); one made with `store: true` is also
+// readable, with its request messages, until deleted. List, retrieve and delete of stored
+// completions are the derived core's (the manifest makes only `_stored` ones readable).
+import type { Semantics } from '@volter/world-core';
+import { type OpenAIScenarioEngine, serveScenario } from '../openai-scenario.ts';
+import { buildChatCompletion, streamChat, validateChat } from '../openai-twin.ts';
+import type { ChatCompletion } from '../openai-types.ts';
+import { page, recordUsage, send, type Row } from './shared.ts';
+
+const COMPLETION = 'CreateChatCompletionResponse';
+
+const create = (engine: OpenAIScenarioEngine | undefined): Semantics => 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: Array<{ data: unknown }> = [];
+  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 as Array<{ type?: unknown; text?: unknown }>) : 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 as { name?: unknown }).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 as Partial<ChatCompletion> | undefined;
+  const answer = live && typeof live === 'object' && Array.isArray(live.choices) ? (live as ChatCompletion) : 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: Semantics = async (ctx) => {
+  const id = String(ctx.id);
+  const row = ctx.row(COMPLETION, id);
+  return row ? page(ctx, (row._input_messages as Row[] | undefined) ?? []) : ctx.notFound(COMPLETION, id);
+};
+
+export function chatCompletions(engine: OpenAIScenarioEngine | undefined): Record<string, Semantics> {
+  return {
+    createChatCompletion: create(engine),
+    getChatCompletionMessages: messages,
+  };
+}