@volter/twin-openai 0.1.1 → 2.0.0

package/src/semantics/containers.ts

@@ -0,0 +1,151 @@
+// Containers API semantics: code-interpreter sandboxes and the files in them. Delete of a container is
+// the derived core's, and so are the reads once expiry is observed. The twin runs no sandbox, so a
+// container is created running; it expires once idle past its `expires_after` (by default 20 minutes
+// after `last_active_at`), which a read or a use observes by the World clock (the machine's time
+// move in ../manifest.ts; a read-only twin never writes it). Adding or removing a file is activity and
+// moves `last_active_at`; an expired container's files cannot be used. A file keeps its text
+// (`_content`) as the Files API does, from an upload or a stored File.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { coreAnswer, readOnly } from './progress.ts';
+import { at, epoch, invalid, objectOr, recordUsage, type Row } from './shared.ts';
+
+const CONTAINER = 'ContainerResource';
+const FILE = 'ContainerFileResource';
+
+/** Whether a running container has sat idle past its expiry window at this instant. */
+function idle(row: Row, now: number): boolean {
+  const after = (row.expires_after ?? {}) as { anchor?: unknown; minutes?: unknown };
+  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: SemanticsContext, id: string): Promise<void> {
+  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: SemanticsContext): Promise<{ id: string } | { answer: Response }> {
+  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: SemanticsContext, id: string): Promise<Row> => ctx.write(CONTAINER, id, { last_active_at: epoch(ctx) }, 'container.update');
+
+const create: Semantics = 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: Semantics = 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 as { name?: unknown; content?: unknown };
+    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: Semantics = 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: Record<string, Semantics> = {
+  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/src/semantics/embeddings.ts

@@ -0,0 +1,19 @@
+// Embeddings: deterministic pseudo-vectors from the pack's stub, never a model's. Each call records
+// its usage.
+import type { Semantics } from '@volter/world-core';
+import { handleEmbeddings } from '../openai-twin.ts';
+import type { EmbeddingResponse } from '../openai-types.ts';
+import { recordUsage, send } from './shared.ts';
+
+const create: Semantics = async (ctx) => {
+  const answer = handleEmbeddings(ctx.params);
+  if (answer.status === 200) {
+    const body = answer.body as EmbeddingResponse;
+    await recordUsage(ctx, 'embeddings', body.model, body.usage.prompt_tokens, 0);
+  }
+  return send(ctx, answer);
+};
+
+export const embeddings: Record<string, Semantics> = {
+  createEmbedding: create,
+};

package/src/semantics/evals.ts

@@ -0,0 +1,182 @@
+// Evals API semantics: an eval's configuration, its runs, and a run's output items. List and
+// retrieve of evals are the derived core's, and so are an eval's runs (a run lives under its eval)
+// once the vendor's work is observed. A run is created `queued`, as OpenAI creates it; the twin runs
+// no grader, so when a read first looks (./progress.ts) it completes with one passed item graded by
+// a deterministic stub grader; the output items are read off the run, never stored.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { coreAnswer, progress, progressAll } from './progress.ts';
+import { at, epoch, invalid, objectOr, page, type Row } from './shared.ts';
+
+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: Row): Row[] {
+  const source = ((run.data_source ?? {}) as { source?: { type?: unknown; content?: unknown } }).source;
+  const inline = source?.type === 'file_content' && Array.isArray(source.content) ? (source.content as Array<{ item?: unknown }>).map((c) => (c?.item ?? {}) as Row) : [];
+  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: SemanticsContext, run: Row): string[] => {
+  const list = (ctx.get(EVAL, String(run.eval_id))?.testing_criteria ?? []) as Array<{ id?: unknown }>;
+  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: SemanticsContext) => (row: Row, end: string): Row => {
+  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: unknown): unknown {
+  const x = m as { type?: unknown; role?: unknown; content?: unknown };
+  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: Row): Row {
+  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: Semantics = 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 as Row[]).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 ?? {}) as Row),
+    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: Semantics = 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 as { model?: unknown; input_messages?: { template?: unknown } };
+  // 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: Row, item: Row): Row[] {
+  const template = ((((run.data_source ?? {}) as Row).input_messages ?? {}) as { template?: unknown }).template;
+  const fill = (t: string): string => t.replace(/\{\{\s*item\.([A-Za-z0-9_]+)\s*\}\}/g, (_m, k: string) => String(item[k] ?? ''));
+  return (Array.isArray(template) ? template : []).map((m) => {
+    const x = m as { role?: unknown; content?: unknown };
+    const text = typeof x.content === 'string' ? x.content : String((x.content as { text?: unknown } | undefined)?.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: SemanticsContext, run: Row): Row[] {
+  if (run.status !== 'completed') return [];
+  const sampling = (((run.data_source ?? {}) as Row).sampling_params ?? {}) as { max_completions_tokens?: unknown; temperature?: unknown; top_p?: unknown; seed?: unknown };
+  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: Semantics = 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: Semantics = 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: Semantics = 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: Record<string, Semantics> = {
+  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/src/semantics/files.ts

@@ -0,0 +1,67 @@
+// File semantics. List, retrieve and delete are the derived core's; upload and download are here, with
+// a file's expiry. The twin keeps an uploaded file's text (`_content`) so a download returns what was uploaded.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { epoch, invalid, type Row } from './shared.ts';
+
+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: string, created: number, after: unknown): number | null | undefined {
+  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: number, after: unknown): number | undefined {
+  const a = (after && typeof after === 'object' ? after : {}) as Row;
+  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: SemanticsContext): Promise<void> {
+  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');
+  }
+}
+
+type Upload = { name?: string; size?: number; content?: string };
+
+// The SDK sends multipart/form-data (the part `file`); an in-process caller may send JSON
+// { purpose, filename, content, bytes } instead.
+const create: Semantics = 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 as Upload) : 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: Semantics = 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: Record<string, Semantics> = {
+  createFile: create,
+  downloadFile: download,
+};

package/src/semantics/fine-tuning.ts

@@ -0,0 +1,185 @@
+// Fine-tuning semantics. Cancel, pause and resume are the derived core's: the machine in
+// ../manifest.ts moves `status` and refuses what OpenAI refuses. A job is created
+// `validating_files`, as OpenAI creates it; the twin cannot train, so when a read first looks it
+// finishes the job (./progress.ts) with a synthetic fine-tuned model id, unless it is paused or
+// cancelled. Its events and checkpoints are read off the job.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { fineTuningClosed } from '../openai-models.ts';
+import { estimateTokens } from '../openai-stub.ts';
+import { coreAnswer, inFlight, progress } from './progress.ts';
+import { epoch, invalid, page, type Row } from './shared.ts';
+
+const JOB = 'FineTuningJob';
+
+/** The text of a file the job names, or '' when there is none. */
+const fileText = (ctx: SemanticsContext, id: unknown): string => 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: Row): number {
+  const m = (row.method ?? {}) as Record<string, { hyperparameters?: { n_epochs?: unknown } } | undefined>;
+  const n = Number(m[String((row.method as { type?: unknown } | undefined)?.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: SemanticsContext) => (row: Row, end: string): Row => (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: Row): Row {
+  const method = row.method as Row | undefined;
+  const type = String(method?.type);
+  const body = method?.[type] as Row | undefined;
+  if (!method || !body || (type !== 'supervised' && type !== 'dpo')) return {};
+  const h = (body.hyperparameters ?? {}) as Row;
+  const auto = (v: unknown, n: number): unknown => (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: SemanticsContext, id: string): Promise<void> {
+  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: SemanticsContext): Promise<{ job: Row } | { answer: Response }> {
+  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: Row): Row {
+  const type = String(method.type);
+  if (type !== 'supervised' && type !== 'dpo' && type !== 'reinforcement') return method;
+  const body = (method[type] && typeof method[type] === 'object' ? method[type] : {}) as Row;
+  const sent = (body.hyperparameters && typeof body.hyperparameters === 'object' ? body.hyperparameters : {}) as Row;
+  // 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: Semantics = 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 as Row) : { type: 'supervised', supervised: { hyperparameters: p.hyperparameters ?? {} } });
+  const hyperparameters = method.type === 'supervised' ? ((method.supervised as Row).hyperparameters as Row) : 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 as Row[]).map((i) => (i && i.type === 'wandb' ? { ...i, wandb: { entity: null, ...(i.wandb as Row), 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: Semantics = 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: Semantics = 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: Semantics = 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)] as const] : []; });
+  const nested = ctx.params.metadata && typeof ctx.params.metadata === 'object' ? Object.entries(ctx.params.metadata as Row).map(([k, v]) => [k, String(v)] as const) : [];
+  const pairs = [...wanted, ...nested];
+  if (!pairs.length) return coreAnswer(ctx);
+  const jobs = ctx.rows(JOB).filter((r) => pairs.every(([k, v]) => (r.metadata as Row | null)?.[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: Record<string, Semantics> = {
+  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: SemanticsContext): Promise<void> {
+  for (const row of ctx.rowsRaw(JOB)) if (inFlight(JOB, row)) await train(ctx, String(row.id));
+}

package/src/semantics/images.ts

@@ -0,0 +1,23 @@
+// Images: a real placeholder image (base64 for the GPT image models, a URL for DALL·E); the twin renders no
+// pixels. An edit or a variation takes its image as a multipart file of a format the endpoint takes.
+import type { Semantics } from '@volter/world-core';
+import { handleImageEdit, handleImages, handleImageVariation, type ImageAnswer } from '../openai-twin.ts';
+import { modelOf } from '../openai-models.ts';
+import { recordUsage, send } from './shared.ts';
+
+/** 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: Parameters<Semantics>[0], r: ImageAnswer, source: string): Promise<Response> {
+  if (r.status === 200) {
+    const n = ((r.body as { data?: unknown[] }).data ?? []).length;
+    const model = modelOf(ctx.call.operation.id, ctx.params as { model?: unknown })!;
+    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: Record<string, Semantics> = {
+  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'),
+};