@volter/twin-openai 0.1.2 → 2.0.1

package/dist/src/semantics/containers.js

@@ -0,0 +1,147 @@
+import { coreAnswer, readOnly } from "./progress.js";
+import { at, epoch, invalid, objectOr, recordUsage } from "./shared.js";
+const CONTAINER = 'ContainerResource';
+const FILE = 'ContainerFileResource';
+/** Whether a running container has sat idle past its expiry window at this instant. */
+function idle(row, now) {
+    const after = (row.expires_after ?? {});
+    const minutes = Number(after.minutes ?? 20);
+    const anchor = Number((after.anchor === 'created_at' ? row.created_at : row.last_active_at) ?? row.created_at ?? 0);
+    return row.status === 'running' && Number.isFinite(minutes) && now > anchor + minutes * 60;
+}
+/** Observe a container's expiry (the time move), deciding and writing at once. */
+async function observe(ctx, id) {
+    if (readOnly(ctx))
+        return;
+    const now = epoch(ctx);
+    await ctx.atomically((rows) => {
+        const current = rows(CONTAINER).find((r) => r.id === id);
+        if (!current || !idle(current, now))
+            return { value: undefined };
+        if (ctx.legal(CONTAINER, 'status', ctx.call.operation.id, current.status, 'expired', id, 'time'))
+            return { value: undefined };
+        return { value: undefined, write: { resource: CONTAINER, id, fields: { status: 'expired' }, operation: 'container.update' } };
+    });
+}
+/** The container a file operation names, observed and allowed to be used, or OpenAI's answer. */
+async function usable(ctx) {
+    const id = at(ctx, 'container_id');
+    await observe(ctx, id);
+    const row = ctx.get(CONTAINER, id);
+    if (!row)
+        return { answer: ctx.notFound(CONTAINER, id) };
+    const refusal = ctx.legal(CONTAINER, 'status', ctx.call.operation.id, row.status, undefined, id);
+    return refusal ? { answer: ctx.refuse(refusal) } : { id };
+}
+/** Using a container (a file added or removed) is activity: it restarts the idle window. */
+const touch = (ctx, id) => ctx.write(CONTAINER, id, { last_active_at: epoch(ctx) }, 'container.update');
+const create = async (ctx) => {
+    const p = ctx.params;
+    if (p.name === undefined || p.name === '')
+        return invalid(ctx, 'you must provide a name parameter', 'name');
+    const created = epoch(ctx);
+    const fields = {
+        object: 'container',
+        name: String(p.name),
+        created_at: created,
+        status: 'running',
+        last_active_at: created,
+        expires_after: objectOr(p.expires_after, { anchor: 'last_active_at', minutes: 20 }),
+        // its memory, "Defaults to \"1g\"", and the network policy it was given (the spec's CreateContainerBody;
+        // https://platform.openai.com/docs/api-reference/containers/createContainers)
+        memory_limit: typeof p.memory_limit === 'string' && p.memory_limit ? p.memory_limit : '1g',
+        ...(p.network_policy && typeof p.network_policy === 'object' ? { network_policy: p.network_policy } : {}),
+    };
+    const written = await ctx.write(CONTAINER, ctx.mint(CONTAINER), fields, 'container.create');
+    // a container is a code interpreter session, billed as one (the usage report's `num_sessions`)
+    await recordUsage(ctx, 'code_interpreter_sessions', 'code-interpreter', 0, 0, { num_sessions: 1 });
+    return ctx.reply(written);
+};
+// A file comes from a stored File (a JSON `file_id`) or a multipart upload (the part `file`), the two
+// forms OpenAI takes (https://platform.openai.com/docs/api-reference/container-files/createContainerFile:
+// "either a multipart/form-data request with the raw file content, or a JSON request with a file ID");
+// its id is the container's next.
+const createFile = async (ctx) => {
+    const found = await usable(ctx);
+    if ('answer' in found)
+        return found.answer;
+    const containerId = found.id;
+    const p = ctx.params;
+    const seq = ctx.rowsRaw(FILE, { withDeleted: true }).filter((r) => r.container_id === containerId).length + 1;
+    const id = `cfile-twin-${containerId}-${seq}`;
+    let content = '';
+    let source = 'user';
+    let name = '';
+    if (typeof p.file_id === 'string' && p.file_id) {
+        const file = ctx.row('OpenAIFile', p.file_id);
+        if (!file)
+            return ctx.notFound('OpenAIFile', p.file_id);
+        content = String(file._content ?? '');
+        source = 'file_id';
+    }
+    else if (p.file && typeof p.file === 'object') {
+        const upload = p.file;
+        content = String(upload.content ?? '');
+        name = typeof upload.name === 'string' && upload.name ? upload.name : '';
+    }
+    const fields = {
+        object: 'container.file',
+        container_id: containerId,
+        created_at: epoch(ctx),
+        bytes: content.length,
+        path: name ? `/mnt/data/${name}` : `/mnt/data/${id}`,
+        source,
+        _content: content,
+    };
+    const written = await ctx.write(FILE, id, fields, 'container_file.create');
+    await touch(ctx, containerId);
+    return ctx.reply(written);
+};
+// the file's bytes as kept
+const content = async (ctx) => {
+    const found = await usable(ctx);
+    if ('answer' in found)
+        return found.answer;
+    const id = at(ctx, 'file_id');
+    const file = ctx.row(FILE, id);
+    if (!file || file.container_id !== at(ctx, 'container_id'))
+        return ctx.notFound(FILE, id);
+    return ctx.raw(String(file._content ?? ''), { headers: { 'content-type': 'application/octet-stream' } });
+};
+export const containers = {
+    CreateContainer: create,
+    CreateContainerFile: createFile,
+    RetrieveContainerFileContent: content,
+    // a container's reads observe its expiry first
+    RetrieveContainer: async (ctx) => {
+        await observe(ctx, at(ctx, 'container_id'));
+        return coreAnswer(ctx);
+    },
+    ListContainers: async (ctx) => {
+        for (const r of ctx.rowsRaw(CONTAINER))
+            await observe(ctx, String(r.id));
+        return coreAnswer(ctx);
+    },
+    // its files' reads, only while it can be used
+    ListContainerFiles: async (ctx) => {
+        const found = await usable(ctx);
+        return 'answer' in found ? found.answer : coreAnswer(ctx);
+    },
+    RetrieveContainerFile: async (ctx) => {
+        const found = await usable(ctx);
+        return 'answer' in found ? found.answer : coreAnswer(ctx);
+    },
+    // removing a file is activity too
+    DeleteContainerFile: async (ctx) => {
+        const found = await usable(ctx);
+        if ('answer' in found)
+            return found.answer;
+        const id = at(ctx, 'file_id');
+        const file = ctx.get(FILE, id);
+        if (!file || file.container_id !== found.id)
+            return ctx.notFound(FILE, id);
+        await ctx.write(FILE, id, { deleted: true }, 'container_file.delete');
+        await touch(ctx, found.id);
+        return ctx.reply({ id, object: 'container.file.deleted', deleted: true });
+    },
+};

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

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

package/dist/src/semantics/embeddings.js

@@ -0,0 +1,13 @@
+import { handleEmbeddings } from "../openai-twin.js";
+import { recordUsage, send } from "./shared.js";
+const create = async (ctx) => {
+    const answer = handleEmbeddings(ctx.params);
+    if (answer.status === 200) {
+        const body = answer.body;
+        await recordUsage(ctx, 'embeddings', body.model, body.usage.prompt_tokens, 0);
+    }
+    return send(ctx, answer);
+};
+export const embeddings = {
+    createEmbedding: create,
+};

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

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

package/dist/src/semantics/evals.js

@@ -0,0 +1,173 @@
+import { coreAnswer, progress, progressAll } from "./progress.js";
+import { at, epoch, invalid, objectOr, page } from "./shared.js";
+const EVAL = 'Eval';
+const RUN = 'EvalRun';
+/** The items a run grades: those its data source holds inline (`file_content`), else one the twin stands in for (it
+ *  fetches no dataset and reads no stored completions). */
+function items(run) {
+    const source = (run.data_source ?? {}).source;
+    const inline = source?.type === 'file_content' && Array.isArray(source.content) ? source.content.map((c) => (c?.item ?? {})) : [];
+    return inline.length ? inline : [{ input: '[twin-stub] datasource item' }];
+}
+/** The names the eval's testing criteria are graded under: each criterion's id. */
+const criteria = (ctx, run) => {
+    const list = (ctx.get(EVAL, String(run.eval_id))?.testing_criteria ?? []);
+    return list.length ? list.map((c) => String(c.id)) : ['twin-stub-grader'];
+};
+/** What a graded run carries: each of its items passed by the stub grader, under each criterion. */
+const graded = (ctx) => (row, end) => {
+    if (end !== 'completed')
+        return {};
+    const n = items(row).length;
+    return {
+        result_counts: { total: n, errored: 0, failed: 0, passed: n },
+        per_model_usage: row.model == null ? [] : [{ model_name: String(row.model), invocation_count: n, prompt_tokens: 0, completion_tokens: 0, total_tokens: 0, cached_tokens: 0 }],
+        per_testing_criteria_results: criteria(ctx, row).map((testing_criteria) => ({ testing_criteria, passed: n, failed: 0 })),
+    };
+};
+/** A chat message as an eval answers it: a typed message whose text content is an `input_text` part (the reference's
+ *  createEval and createEvalRun examples answer the messages they were sent so). */
+function message(m) {
+    const x = m;
+    if (!x || typeof x !== 'object' || x.type !== undefined && x.type !== 'message')
+        return m;
+    return { type: 'message', ...x, content: typeof x.content === 'string' ? { type: 'input_text', text: x.content } : x.content };
+}
+/** The schema of the items (and samples) an eval reads: a stored-completions eval's item and sample objects, a custom
+ *  eval's item schema as sent (the reference's createEval and getEval examples;
+ *  https://platform.openai.com/docs/api-reference/evals/object, `data_source_config.schema`). */
+function dataSourceConfig(config) {
+    if (config.type === 'stored_completions')
+        return { type: 'stored_completions', metadata: config.metadata ?? {}, schema: { type: 'object', properties: { item: { type: 'object' }, sample: { type: 'object' } }, required: ['item', 'sample'] } };
+    // a custom eval's item schema (and the sample's, when asked for); any other source's configuration as sent
+    const sample = config.include_sample_schema === true;
+    return config.type === 'custom' && config.item_schema
+        ? { type: 'custom', schema: { type: 'object', properties: { item: config.item_schema, ...(sample ? { sample: { type: 'object' } } : {}) }, required: sample ? ['item', 'sample'] : ['item'] } }
+        : config;
+}
+const createEval = async (ctx) => {
+    const p = ctx.params;
+    if (p.data_source_config === undefined)
+        return invalid(ctx, 'you must provide a data_source_config parameter', 'data_source_config');
+    if (p.testing_criteria === undefined || !Array.isArray(p.testing_criteria))
+        return invalid(ctx, 'you must provide a testing_criteria parameter (array)', 'testing_criteria');
+    const id = ctx.mint(EVAL);
+    // each criterion is named and given an id of its own (its name and the eval's), its model's messages typed
+    // a label model grader samples as its model does unless told: `sampling_params: null` (the reference's listEvals
+    // example; spec/patches.json)
+    const testing = p.testing_criteria.map((c, i) => ({ ...c, id: `${String(c.name ?? c.type)}-${id}-${i + 1}`, ...(Array.isArray(c.input) ? { input: c.input.map(message) } : {}), ...(c.type === 'label_model' ? { sampling_params: c.sampling_params ?? null } : {}) }));
+    const fields = {
+        object: 'eval',
+        name: typeof p.name === 'string' ? p.name : `eval-${id}`,
+        created_at: epoch(ctx),
+        data_source_config: dataSourceConfig((p.data_source_config ?? {})),
+        testing_criteria: testing,
+        metadata: objectOr(p.metadata, {}),
+    };
+    return ctx.reply(await ctx.write(EVAL, id, fields, 'eval.create'));
+};
+// the twin grades a single datasource item (it fetches no dataset): one item, passed
+const createRun = async (ctx) => {
+    const evalId = at(ctx, 'eval_id');
+    if (!ctx.get(EVAL, evalId))
+        return ctx.notFound(EVAL, evalId);
+    const p = ctx.params;
+    if (p.data_source === undefined)
+        return invalid(ctx, 'you must provide a data_source parameter', 'data_source');
+    const id = ctx.mint(RUN);
+    const source = p.data_source;
+    // a data source that names no model samples none: the run's `model` is "The model that is evaluated, if applicable"
+    // (EvalRun), and the spec gives the sources no default; with none, nothing is sampled and nothing billed (the twin's
+    // reading of "if applicable")
+    const model = typeof source?.model === 'string' ? source.model : null;
+    const template = source?.input_messages?.template;
+    const dataSource = Array.isArray(template) ? { ...source, input_messages: { ...source.input_messages, template: template.map(message) } } : source;
+    const fields = {
+        object: 'eval.run',
+        eval_id: evalId,
+        name: typeof p.name === 'string' ? p.name : `run-${id}`,
+        created_at: epoch(ctx),
+        status: 'queued',
+        model,
+        data_source: dataSource,
+        // nothing graded yet: no usage and no criterion's results (the reference's createEvalRun example)
+        result_counts: { total: 0, errored: 0, failed: 0, passed: 0 },
+        per_model_usage: null,
+        per_testing_criteria_results: null,
+        report_url: `https://twin.invalid/evals/${evalId}/runs/${id}`,
+        metadata: objectOr(p.metadata, {}),
+        error: null,
+    };
+    return ctx.reply(await ctx.write(RUN, id, fields, 'eval_run.create'));
+};
+/** The messages the model was sent for an item: the run's template, each `{{item.x}}` filled from the item. */
+function rendered(run, item) {
+    const template = ((run.data_source ?? {}).input_messages ?? {}).template;
+    const fill = (t) => t.replace(/\{\{\s*item\.([A-Za-z0-9_]+)\s*\}\}/g, (_m, k) => String(item[k] ?? ''));
+    return (Array.isArray(template) ? template : []).map((m) => {
+        const x = m;
+        const text = typeof x.content === 'string' ? x.content : String(x.content?.text ?? '');
+        return { role: x.role, content: fill(text), tool_call_id: null, tool_calls: null, function_call: null };
+    });
+}
+/** A completed run's output: an item for each datasource item it graded, passed by the stub grader under each
+ *  criterion, with the sample the model answered (https://platform.openai.com/docs/api-reference/evals/run-output-item-object);
+ *  others have none yet. */
+function outputItems(ctx, run) {
+    if (run.status !== 'completed')
+        return [];
+    const sampling = ((run.data_source ?? {}).sampling_params ?? {});
+    const names = criteria(ctx, run);
+    return items(run).map((item, i) => ({
+        id: `evalitem-${run.id}-${i + 1}`,
+        object: 'eval.run.output_item',
+        created_at: Number(run.created_at ?? 0),
+        run_id: String(run.id),
+        eval_id: String(run.eval_id),
+        status: 'pass',
+        datasource_item_id: i,
+        datasource_item: item,
+        results: names.map((name) => ({ name, sample: null, passed: true, score: 1.0 })),
+        sample: run.model == null ? null : {
+            input: rendered(run, item), output: [{ role: 'assistant', content: '[twin-stub] eval sample output (no real model run)', tool_call_id: null, tool_calls: null, function_call: null }],
+            finish_reason: 'stop', model: String(run.model), usage: { total_tokens: 0, completion_tokens: 0, prompt_tokens: 0, cached_tokens: 0 }, error: null,
+            temperature: sampling.temperature ?? 1, max_completion_tokens: sampling.max_completions_tokens ?? null, top_p: sampling.top_p ?? 1, seed: sampling.seed ?? 0,
+        },
+    }));
+}
+const listOutputItems = async (ctx) => {
+    const id = at(ctx, 'run_id');
+    await progress(ctx, RUN, id, graded(ctx));
+    const run = ctx.get(RUN, id);
+    if (!run || run.eval_id !== at(ctx, 'eval_id'))
+        return ctx.notFound(RUN, id);
+    return page(ctx, outputItems(ctx, run));
+};
+// cancelling stops a run still being graded
+const cancelRun = async (ctx) => {
+    const id = at(ctx, 'run_id');
+    const run = ctx.row(RUN, id);
+    if (!run || run.eval_id !== at(ctx, 'eval_id'))
+        return ctx.notFound(RUN, id);
+    const refusal = ctx.legal(RUN, 'status', 'cancelEvalRun', run.status, 'canceled');
+    if (refusal)
+        return ctx.refuse(refusal);
+    return ctx.reply(await ctx.write(RUN, id, { status: 'canceled' }, 'eval_run.cancel'));
+};
+// an eval's runs, each one's grading observed first
+const listRuns = async (ctx) => {
+    const evalId = at(ctx, 'eval_id');
+    await progressAll(ctx, RUN, graded(ctx), (r) => r.eval_id === evalId);
+    return coreAnswer(ctx);
+};
+export const evals = {
+    createEval,
+    createEvalRun: createRun,
+    getEvalRunOutputItems: listOutputItems,
+    cancelEvalRun: cancelRun,
+    getEvalRun: async (ctx) => {
+        await progress(ctx, RUN, at(ctx, 'run_id'), graded(ctx));
+        return coreAnswer(ctx);
+    },
+    getEvalRuns: listRuns,
+};

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

@@ -0,0 +1,13 @@
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+/** When a file expires (its `expires_at`): `expires_after.seconds` past its creation when the upload set one, else
+ *  thirty days for a batch file, else never. "By default, files with `purpose=batch` expire after 30 days and all
+ *  other files are persisted until they are manually deleted"; `seconds` "must be between 3600 (1 hour) and 2592000
+ *  (30 days)" (developers.openai.com/api/reference/resources/files/methods/create, `expires_after`). Undefined for a
+ *  policy OpenAI refuses. */
+export declare function expiresAt(purpose: string, created: number, after: unknown): number | null | undefined;
+/** Files whose time is up are gone, each deleted at the moment it expired, not when a later request looks: a batch
+ *  input thirty days after its upload (above), a batch's output "automatically deleted 30 days after the batch is
+ *  complete" (developers.openai.com/api/docs/guides/batch). A get, download or delete of one then answers OpenAI's
+ *  404 for a file that does not exist. */
+export declare function expireFiles(ctx: SemanticsContext): Promise<void>;
+export declare const files: Record<string, Semantics>;

package/dist/src/semantics/files.js

@@ -0,0 +1,59 @@
+import { epoch, invalid } from "./shared.js";
+const THIRTY_DAYS = 30 * 24 * 3600;
+/** When a file expires (its `expires_at`): `expires_after.seconds` past its creation when the upload set one, else
+ *  thirty days for a batch file, else never. "By default, files with `purpose=batch` expire after 30 days and all
+ *  other files are persisted until they are manually deleted"; `seconds` "must be between 3600 (1 hour) and 2592000
+ *  (30 days)" (developers.openai.com/api/reference/resources/files/methods/create, `expires_after`). Undefined for a
+ *  policy OpenAI refuses. */
+export function expiresAt(purpose, created, after) {
+    return after !== undefined ? expiresAfter(created, after) : purpose === 'batch' ? created + THIRTY_DAYS : null;
+}
+/** The expiry an upload's own `expires_after` sets, or undefined for one out of range. */
+function expiresAfter(created, after) {
+    const a = (after && typeof after === 'object' ? after : {});
+    const seconds = Number(a.seconds);
+    return a.anchor === 'created_at' && Number.isInteger(seconds) && seconds >= 3600 && seconds <= THIRTY_DAYS ? created + seconds : undefined;
+}
+/** Files whose time is up are gone, each deleted at the moment it expired, not when a later request looks: a batch
+ *  input thirty days after its upload (above), a batch's output "automatically deleted 30 days after the batch is
+ *  complete" (developers.openai.com/api/docs/guides/batch). A get, download or delete of one then answers OpenAI's
+ *  404 for a file that does not exist. */
+export async function expireFiles(ctx) {
+    const now = epoch(ctx);
+    const due = ctx.rowsRaw('OpenAIFile').filter((f) => typeof f.expires_at === 'number' && f.expires_at <= now);
+    for (const f of due.sort((a, b) => Number(a.expires_at) - Number(b.expires_at))) {
+        const at = await ctx.at(new Date(Number(f.expires_at) * 1000).toISOString());
+        await at.write('OpenAIFile', String(f.id), { deleted: true }, 'file.delete');
+    }
+}
+// The SDK sends multipart/form-data (the part `file`); an in-process caller may send JSON
+// { purpose, filename, content, bytes } instead.
+const create = async (ctx) => {
+    const p = ctx.params;
+    if (p.purpose === undefined || p.purpose === '')
+        return invalid(ctx, 'you must provide a purpose parameter', 'purpose');
+    const upload = p.file && typeof p.file === 'object' ? p.file : undefined;
+    const content = upload ? String(upload.content ?? '') : typeof p.content === 'string' ? p.content : '';
+    const filename = upload ? upload.name || 'upload' : typeof p.filename === 'string' && p.filename ? p.filename : 'upload.jsonl';
+    const bytes = upload ? upload.size || content.length : Number(p.bytes ?? (typeof p.content === 'string' ? p.content.length : 0));
+    // the SDK sends the policy as the form fields expires_after[anchor] and expires_after[seconds]
+    const after = p.expires_after ?? (p['expires_after[anchor]'] === undefined ? undefined : { anchor: p['expires_after[anchor]'], seconds: p['expires_after[seconds]'] });
+    const expires = expiresAt(String(p.purpose), epoch(ctx), after);
+    if (expires === undefined)
+        return invalid(ctx, "'expires_after' must have anchor 'created_at' and seconds between 3600 and 2592000", 'expires_after');
+    const id = ctx.mint('OpenAIFile');
+    const fields = { object: 'file', bytes: Number.isFinite(bytes) ? bytes : 0, created_at: epoch(ctx), expires_at: expires, filename, purpose: String(p.purpose), status: 'processed', _content: content };
+    return ctx.reply(await ctx.write('OpenAIFile', id, fields, 'file.create'));
+};
+// the file's bytes as uploaded, not JSON
+const download = async (ctx) => {
+    const id = String(ctx.id);
+    const row = ctx.row('OpenAIFile', id);
+    if (!row)
+        return ctx.notFound('OpenAIFile', id);
+    return ctx.raw(String(row._content ?? ''), { headers: { 'content-type': 'application/octet-stream' } });
+};
+export const files = {
+    createFile: create,
+    downloadFile: download,
+};

package/dist/src/semantics/fine-tuning.d.ts

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

package/dist/src/semantics/fine-tuning.js

@@ -0,0 +1,178 @@
+import { fineTuningClosed } from "../openai-models.js";
+import { estimateTokens } from "../openai-stub.js";
+import { coreAnswer, inFlight, progress } from "./progress.js";
+import { epoch, invalid, page } from "./shared.js";
+const JOB = 'FineTuningJob';
+/** The text of a file the job names, or '' when there is none. */
+const fileText = (ctx, id) => String(ctx.row('OpenAIFile', String(id ?? ''), { withDeleted: true })?._content ?? '');
+/** The epochs a job trains: its method's n_epochs, one when left to OpenAI ("auto"). */
+function epochs(row) {
+    const m = (row.method ?? {});
+    const n = Number(m[String(row.method?.type)]?.hyperparameters?.n_epochs);
+    return Number.isInteger(n) && n > 0 ? n : 1;
+}
+/** What a finished job carries: the model it trained, the tokens it trained on (its training file's, once an epoch),
+ *  and its result file, the training metrics OpenAI writes for a succeeded job
+ *  (https://platform.openai.com/docs/api-reference/fine-tuning/object, `result_files`, `trained_tokens`). */
+const finish = (ctx) => (row, end) => (end === 'succeeded'
+    ? { fine_tuned_model: `ft:${String(row.model)}:twin::${String(row.id)}`, trained_tokens: estimateTokens(fileText(ctx, row.training_file)) * epochs(row), result_files: [`file-twin-ftresult-${String(row.id)}`], ...resolved(row) }
+    : {});
+/** A trained job's hyperparameters as it trained with them: each `auto` resolved to a value, as a finished job answers
+ *  them (the reference's retrieve example: `"hyperparameters": {"n_epochs": 4, "batch_size": 1, "learning_rate_multiplier": 1}`).
+ *  The twin trains one example a step at the base rate, for the epochs asked or one. */
+function resolved(row) {
+    const method = row.method;
+    const type = String(method?.type);
+    const body = method?.[type];
+    if (!method || !body || (type !== 'supervised' && type !== 'dpo'))
+        return {};
+    const h = (body.hyperparameters ?? {});
+    const auto = (v, n) => (v === 'auto' || v === undefined ? n : v);
+    const hyperparameters = { ...h, batch_size: auto(h.batch_size, 1), learning_rate_multiplier: auto(h.learning_rate_multiplier, 1), n_epochs: epochs(row) };
+    return { method: { ...method, [type]: { ...body, hyperparameters } }, ...(type === 'supervised' ? { hyperparameters } : {}) };
+}
+/** Observe OpenAI's training of a job; the read that finishes it writes its result file (step metrics, stubs). */
+async function train(ctx, id) {
+    const moved = await progress(ctx, JOB, id, finish(ctx));
+    if (moved?.to !== 'succeeded')
+        return;
+    const content = 'step,train_loss,train_accuracy,valid_loss,valid_mean_token_accuracy\n1,0,1,,\n';
+    await ctx.write('OpenAIFile', `file-twin-ftresult-${id}`, { object: 'file', bytes: content.length, created_at: epoch(ctx), expires_at: null, filename: 'step_metrics.csv', purpose: 'fine-tune-results', status: 'processed', _content: content }, 'file.create');
+}
+/** The job the path names, its training observed, or OpenAI's answer that there is none. */
+async function job(ctx) {
+    const id = String(ctx.id);
+    await train(ctx, id);
+    const found = ctx.get(JOB, id);
+    return found ? { job: found } : { answer: ctx.notFound(JOB, id) };
+}
+/** A method's hyperparameters with OpenAI's `auto` for each one not sent (the job object's `method`:
+ *  https://platform.openai.com/docs/api-reference/fine-tuning/object); a reinforcement method's are its own. */
+function withDefaults(method) {
+    const type = String(method.type);
+    if (type !== 'supervised' && type !== 'dpo' && type !== 'reinforcement')
+        return method;
+    const body = (method[type] && typeof method[type] === 'object' ? method[type] : {});
+    const sent = (body.hyperparameters && typeof body.hyperparameters === 'object' ? body.hyperparameters : {});
+    // a reinforcement job also evaluates on its own schedule and budget, and answers its response format, null unless
+    // set (the reference's Reinforcement example)
+    const own = type === 'dpo' ? { beta: 'auto' } : type === 'reinforcement' ? { eval_interval: 'auto', eval_samples: 'auto', compute_multiplier: 'auto', reasoning_effort: 'default' } : {};
+    const hyperparameters = { batch_size: 'auto', learning_rate_multiplier: 'auto', n_epochs: 'auto', ...own, ...sent };
+    return { ...method, [type]: { ...body, hyperparameters, ...(type === 'reinforcement' ? { response_format: body.response_format ?? null } : {}) } };
+}
+const create = async (ctx) => {
+    const p = ctx.params;
+    if (p.model === undefined || p.model === '')
+        return invalid(ctx, 'you must provide a model parameter', 'model');
+    if (p.training_file === undefined || p.training_file === '')
+        return invalid(ctx, 'you must provide a training_file parameter', 'training_file');
+    // fine-tuning's dated availability (../openai-models.ts): whether the organization has fine-tuned before, and when it
+    // last ran inference on a fine-tuned model
+    const inference = ctx.rowsRaw('_usage_record').filter((r) => String(r.model).startsWith('ft:')).map((r) => Number(r.created_at));
+    const closed = fineTuningClosed(epoch(ctx), { everFineTuned: ctx.rowsRaw(JOB, { withDeleted: true }).length > 0, ...(inference.length ? { lastFineTunedInference: Math.max(...inference) } : {}) });
+    if (closed)
+        return ctx.refuse({ status: 403, message: closed, code: 'fine_tuning_unavailable' });
+    const id = ctx.mint(JOB);
+    const created = epoch(ctx);
+    // the method trained with, supervised by default; the deprecated top-level hyperparameters are a supervised job's
+    // method's, and null for any other method (the reference's Epochs and DPO examples)
+    const method = withDefaults(p.method && typeof p.method === 'object' ? p.method : { type: 'supervised', supervised: { hyperparameters: p.hyperparameters ?? {} } });
+    const hyperparameters = method.type === 'supervised' ? method.supervised.hyperparameters : null;
+    // a Weights & Biases run is named by the job unless the request names it (the spec's FineTuningIntegration: "If not
+    // set, we will use the Job ID as the name"); its entity is the W&B default unless set
+    const integrations = Array.isArray(p.integrations)
+        ? p.integrations.map((i) => (i && i.type === 'wandb' ? { ...i, wandb: { entity: null, ...i.wandb, run_id: id } } : i))
+        : [];
+    const fields = {
+        object: 'fine_tuning.job',
+        model: String(p.model),
+        created_at: created,
+        finished_at: null,
+        fine_tuned_model: null,
+        organization_id: 'org-twin',
+        status: 'validating_files',
+        training_file: String(p.training_file),
+        validation_file: p.validation_file ?? null,
+        hyperparameters,
+        method,
+        integrations,
+        metadata: p.metadata && typeof p.metadata === 'object' ? p.metadata : null,
+        result_files: [],
+        trained_tokens: null,
+        // no failure, as the reference's create examples answer it
+        error: { code: null, message: null, param: null },
+        estimated_finish: null,
+        // the suffix it was given, its usage (none until it trains) and whether its data is shared with OpenAI, as the
+        // reference's create examples answer them (spec/patches.json adds them to the job object)
+        user_provided_suffix: typeof p.suffix === 'string' ? p.suffix : null,
+        usage_metrics: null,
+        shared_with_openai: false,
+        seed: Number(p.seed ?? 0),
+    };
+    return ctx.reply(await ctx.write(JOB, id, fields, 'fine_tuning_job.create'));
+};
+// the job's event stream: created, then completed once it has succeeded
+const events = async (ctx) => {
+    const found = await job(ctx);
+    if ('answer' in found)
+        return found.answer;
+    const j = found.job;
+    const created = Number(j.created_at ?? 0);
+    const data = [
+        // a message event carries no data (https://platform.openai.com/docs/api-reference/fine-tuning/event-object, `data`)
+        { object: 'fine_tuning.job.event', id: `ftevent-${j.id}-1`, created_at: created, level: 'info', message: 'Created fine-tuning job', data: null, type: 'message' },
+        ...(j.status === 'succeeded' ? [{ object: 'fine_tuning.job.event', id: `ftevent-${j.id}-2`, created_at: Number(j.finished_at ?? created), level: 'info', message: 'Fine-tuning job successfully completed (twin stub)', data: null, type: 'message' }] : []),
+    ];
+    return ctx.reply({ object: 'list', data, has_more: false });
+};
+// a succeeded job has one final checkpoint naming its fine-tuned model (metrics are stubs); any
+// other job has none
+const checkpoints = async (ctx) => {
+    const found = await job(ctx);
+    if ('answer' in found)
+        return found.answer;
+    const j = found.job;
+    const data = j.status === 'succeeded'
+        ? [{
+                object: 'fine_tuning.job.checkpoint',
+                id: `ftckpt-${j.id}-1`,
+                created_at: Number(j.created_at ?? 0),
+                fine_tuned_model_checkpoint: String(j.fine_tuned_model ?? `ft:twin::${j.id}:ckpt-step-1`),
+                fine_tuning_job_id: String(j.id),
+                metrics: { step: 1, train_loss: 0, train_mean_token_accuracy: 1, full_valid_loss: 0, full_valid_mean_token_accuracy: 1 },
+                step_number: 1,
+            }]
+        : [];
+    return ctx.reply({ object: 'list', data, has_more: false, first_id: data[0]?.id ?? null, last_id: data[0]?.id ?? null });
+};
+// the organization's jobs, each one's training observed first, newest first; `metadata[k]=v` keeps the jobs whose
+// metadata holds each pair (https://platform.openai.com/docs/api-reference/fine-tuning/list, `metadata`)
+const listJobs = async (ctx) => {
+    for (const r of ctx.rowsRaw(JOB))
+        if (inFlight(JOB, r))
+            await train(ctx, String(r.id));
+    const wanted = Object.entries(ctx.params).flatMap(([k, v]) => { const m = /^metadata\[(.+)\]$/.exec(k); return m ? [[m[1], String(v)]] : []; });
+    const nested = ctx.params.metadata && typeof ctx.params.metadata === 'object' ? Object.entries(ctx.params.metadata).map(([k, v]) => [k, String(v)]) : [];
+    const pairs = [...wanted, ...nested];
+    if (!pairs.length)
+        return coreAnswer(ctx);
+    const jobs = ctx.rows(JOB).filter((r) => pairs.every(([k, v]) => r.metadata?.[k] === v));
+    // newest first, ties by mint order as the derived core lists (a job minted later is newer)
+    return page(ctx, jobs.sort((a, b) => Number(b.created_at) - Number(a.created_at) || String(b.id).localeCompare(String(a.id), undefined, { numeric: true })));
+};
+export const fineTuning = {
+    createFineTuningJob: create,
+    listFineTuningEvents: events,
+    listFineTuningJobCheckpoints: checkpoints,
+    retrieveFineTuningJob: async (ctx) => {
+        await train(ctx, String(ctx.id));
+        return coreAnswer(ctx);
+    },
+    listPaginatedFineTuningJobs: listJobs,
+};
+/** Every job OpenAI is still training, observed (a read observes all the vendor's work before it answers). */
+export async function observeJobs(ctx) {
+    for (const row of ctx.rowsRaw(JOB))
+        if (inFlight(JOB, row))
+            await train(ctx, String(row.id));
+}

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

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

package/dist/src/semantics/images.js

@@ -0,0 +1,18 @@
+import { handleImageEdit, handleImages, handleImageVariation } from "../openai-twin.js";
+import { modelOf } from "../openai-models.js";
+import { recordUsage, send } from "./shared.js";
+/** The images, or their events when the request streamed them; each call made is billed by its images, of the size
+ *  asked, from its source (the usage report's `images`, `size`, `source`). */
+async function answer(ctx, r, source) {
+    if (r.status === 200) {
+        const n = (r.body.data ?? []).length;
+        const model = modelOf(ctx.call.operation.id, ctx.params);
+        await recordUsage(ctx, 'images', model, 0, 0, { images: n, size: typeof ctx.params.size === 'string' ? ctx.params.size : '1024x1024', source });
+    }
+    return r.events ? ctx.sse(r.events) : send(ctx, r);
+}
+export const images = {
+    createImage: async (ctx) => answer(ctx, handleImages(ctx.params, ctx.occurredAt), 'image.generation'),
+    createImageEdit: async (ctx) => answer(ctx, handleImageEdit(ctx.params, ctx.occurredAt), 'image.edit'),
+    createImageVariation: async (ctx) => answer(ctx, handleImageVariation(ctx.params, ctx.occurredAt), 'image.variation'),
+};

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

@@ -0,0 +1,8 @@
+import type { Semantics } from '@volter/world-core';
+import type { OpenAIScenarioEngine } from '../openai-scenario.js';
+/** `readOnly`: served by a read-only (mirror) twin, whose reads never write (./progress.ts). */
+export type OpenAISemanticsOptions = {
+    scenarioEngine?: OpenAIScenarioEngine;
+    readOnly?: boolean;
+};
+export declare function openaiSemantics(options: OpenAISemanticsOptions): Record<string, Semantics>;