@volter/twin-openai 0.1.1 → 2.0.0

package/dist/src/semantics/index.js

@@ -0,0 +1,46 @@
+import { assistants } from "./assistants.js";
+import { audio } from "./audio.js";
+import { batches } from "./batches.js";
+import { chatCompletions } from "./chat-completions.js";
+import { containers } from "./containers.js";
+import { embeddings } from "./embeddings.js";
+import { evals } from "./evals.js";
+import { files } from "./files.js";
+import { fineTuning } from "./fine-tuning.js";
+import { images } from "./images.js";
+import { models } from "./models.js";
+import { moderations } from "./moderations.js";
+import { organization } from "./organization.js";
+import { live, modelOf, removedAt } from "../openai-models.js";
+import { READ_ONLY } from "./progress.js";
+import { epoch } from "./shared.js";
+import { responses } from "./responses.js";
+import { uploads } from "./uploads.js";
+import { vectorStores } from "./vector-stores.js";
+export function openaiSemantics(options) {
+    const all = { ...chatCompletions(options.scenarioEngine), ...responses(options.scenarioEngine), ...models, ...files, ...uploads, ...batches, ...fineTuning, ...vectorStores, ...embeddings, ...moderations, ...images, ...audio, ...assistants, ...organization, ...evals, ...containers };
+    // OpenAI's timeline (../openai-models.ts), at the World's instant: an operation of a removed API family answers as
+    // removed; a request naming a model that is not live (not in the catalog, not yet released, or shut down) answers
+    // OpenAI's model_not_found, as for any model that does not exist. A fine-tuned model is live while the job that made
+    // it holds it and it is not deleted. An operation that names no model runs on its default (DEFAULT_MODEL). The models'
+    // own operations list and read the catalog as it stands (./models.ts).
+    for (const [id, h] of Object.entries(all)) {
+        all[id] = (async (ctx) => {
+            const now = epoch(ctx);
+            const removed = removedAt(id, now);
+            if (removed)
+                return ctx.refuse({ status: removed.status, message: removed.message });
+            if (id in models)
+                return h(ctx);
+            const p = ctx.params;
+            const named = typeof p.data_source?.model === 'string' && typeof p.model !== 'string' ? p.data_source.model : modelOf(id, p);
+            if (!named)
+                return h(ctx);
+            const tuned = named.startsWith('ft:') && ctx.rowsRaw('FineTuningJob', { withDeleted: true }).some((j) => j.fine_tuned_model === named) && !ctx.rowsRaw('Model', { withDeleted: true }).some((m) => m.id === named && m.deleted);
+            return tuned || live(named, now) ? h(ctx) : ctx.notFound('Model', named);
+        });
+    }
+    if (!options.readOnly)
+        return all;
+    return Object.fromEntries(Object.entries(all).map(([id, h]) => [id, ((ctx) => h(Object.assign(ctx, { [READ_ONLY]: true })))]));
+}

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

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

package/dist/src/semantics/models.js

@@ -0,0 +1,34 @@
+import { findModel, live, OPENAI_MODELS } from "../openai-models.js";
+import { epoch, invalid } from "./shared.js";
+/** The models succeeded fine-tuning jobs minted, less those deleted (a deletion is a Model tombstone). */
+function fineTunedModels(ctx) {
+    const deleted = new Set(ctx.rowsRaw('Model', { withDeleted: true }).filter((r) => r.deleted).map((r) => String(r.id)));
+    const out = [];
+    for (const job of ctx.rowsRaw('FineTuningJob', { withDeleted: true })) {
+        const id = job.fine_tuned_model;
+        if (typeof id === 'string' && id && !deleted.has(id))
+            out.push({ id, object: 'model', created: Number(job.created_at ?? 0), owned_by: 'org-twin', shutdown_date: null });
+    }
+    return out;
+}
+// the catalog as it stands at the World's instant: a model not yet released, or shut down, is not there
+const list = async (ctx) => ctx.reply({ object: 'list', data: [...OPENAI_MODELS.filter((m) => live(m.id, epoch(ctx))), ...fineTunedModels(ctx)] });
+const retrieve = async (ctx) => {
+    const id = String(ctx.id);
+    const model = (live(id, epoch(ctx)) ? findModel(id) : undefined) ?? fineTunedModels(ctx).find((m) => m.id === id);
+    return model ? ctx.reply(model) : ctx.notFound('Model', id);
+};
+const remove = async (ctx) => {
+    const id = String(ctx.id);
+    if (findModel(id))
+        return invalid(ctx, `The model '${id}' cannot be deleted`, 'model', 'model_not_deletable');
+    if (!fineTunedModels(ctx).some((m) => m.id === id))
+        return ctx.notFound('Model', id);
+    await ctx.write('Model', id, { deleted: true, object: 'model' }, 'model.delete');
+    return ctx.reply({ id, object: 'model', deleted: true });
+};
+export const models = {
+    listModels: list,
+    retrieveModel: retrieve,
+    deleteModel: remove,
+};

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

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

package/dist/src/semantics/moderations.js

@@ -0,0 +1,12 @@
+import { handleModerations } from "../openai-twin.js";
+import { estimateTokens } from "../openai-stub.js";
+import { recordUsage, send } from "./shared.js";
+export const moderations = {
+    // a moderation is metered by the tokens of its text (the usage report's `input_tokens`)
+    createModeration: async (ctx) => {
+        const r = handleModerations(ctx.params, ctx.occurredAt);
+        if (r.status === 200)
+            await recordUsage(ctx, 'moderations', String(r.body.model), estimateTokens(JSON.stringify(ctx.params.input ?? '')), 0);
+        return send(ctx, r);
+    },
+};

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

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

package/dist/src/semantics/organization.js

@@ -0,0 +1,67 @@
+import { bucketed, costsReport, reportQuery, usageReport } from "../openai-twin.js";
+import { readOnly } from "./progress.js";
+import { epoch, invalid, newest, page, pick } from "./shared.js";
+const PROJECT = 'Project';
+/** Every organization has a Default project, where the keys made before any other project live and to
+ *  which the Admin API's own acts are attributed (https://platform.openai.com/docs/api-reference/audit-logs/object:
+ *  "any admin actions taken via Admin API keys are associated with the default project"). The twin makes
+ *  it when the organization's projects are first looked at, dated by the organization's first billed call
+ *  when there was one (the twin keeps no signup date); a read-only twin holds the vendor's own. */
+async function defaultProject(ctx) {
+    if (readOnly(ctx) || ctx.rowsRaw(PROJECT, { withDeleted: true }).some((p) => p._default === true))
+        return;
+    await ctx.write(PROJECT, ctx.mint(PROJECT), { object: 'organization.project', name: 'Default project', created_at: Math.min(epoch(ctx), ...ctx.rowsRaw('_usage_record').map((r) => Number(r.created_at))), archived_at: null, status: 'active', _default: true }, 'project.create');
+}
+// one report per kind the spec publishes; the operation's path names the kind
+const usage = async (ctx) => {
+    if (ctx.params.start_time === undefined)
+        return invalid(ctx, 'you must provide a start_time parameter', 'start_time');
+    const kind = new URL(ctx.call.request.url).pathname.replace(/\/+$/, '').split('/').at(-1);
+    const q = reportQuery(ctx.params, epoch(ctx), false);
+    // vector store usage is storage, not calls: the bytes the organization's stores held over each bucket, for a bucket in
+    // which any store existed (https://platform.openai.com/docs/api-reference/usage/vector_stores_object)
+    if (kind === 'vector_stores') {
+        const stores = ctx.rowsRaw('VectorStoreObject', { withDeleted: true }).map((r) => ({ from: Number(r.created_at), until: r.deleted ? Date.parse(String(r.updatedAt)) / 1000 : Infinity, bytes: Number(r.usage_bytes ?? 0) }));
+        return ctx.reply(bucketed([], q, (_rows, at, until) => {
+            const held = stores.filter((v) => v.from < until && v.until >= at);
+            return held.length ? [{ object: 'organization.usage.vector_stores.result', usage_bytes: held.reduce((n, v) => n + v.bytes, 0), project_id: null }] : [];
+        }));
+    }
+    return ctx.reply(usageReport(ctx.rowsRaw('_usage_record'), kind, q));
+};
+const costs = async (ctx) => ctx.params.start_time === undefined ? invalid(ctx, 'you must provide a start_time parameter', 'start_time') : ctx.reply(costsReport(ctx.rowsRaw('_usage_record'), reportQuery(ctx.params, epoch(ctx), true)));
+// archived projects are left out unless asked for
+const listProjects = async (ctx) => {
+    await defaultProject(ctx);
+    const all = ctx.params.include_archived === 'true';
+    return page(ctx, newest(ctx.rows(PROJECT).filter((p) => all || p.status !== 'archived')));
+};
+const createProject = async (ctx) => {
+    await defaultProject(ctx);
+    if (ctx.params.name === undefined || ctx.params.name === '')
+        return invalid(ctx, 'you must provide a name parameter', 'name');
+    const fields = { object: 'organization.project', name: String(ctx.params.name), created_at: epoch(ctx), archived_at: null, status: 'active' };
+    return ctx.reply(await ctx.write(PROJECT, ctx.mint(PROJECT), fields, 'project.create'));
+};
+const modifyProject = async (ctx) => {
+    const id = String(ctx.id);
+    if (!ctx.get(PROJECT, id))
+        return ctx.notFound(PROJECT, id);
+    return ctx.reply(await ctx.write(PROJECT, id, pick(ctx.params, ['name']), 'project.update'));
+};
+export const organization = {
+    'usage-audio-speeches': usage,
+    'usage-audio-transcriptions': usage,
+    'usage-code-interpreter-sessions': usage,
+    'usage-completions': usage,
+    'usage-embeddings': usage,
+    'usage-file-search-calls': usage,
+    'usage-images': usage,
+    'usage-moderations': usage,
+    'usage-vector-stores': usage,
+    'usage-web-search-calls': usage,
+    'usage-costs': costs,
+    'list-projects': listProjects,
+    'create-project': createProject,
+    'modify-project': modifyProject,
+};

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

@@ -0,0 +1,22 @@
+import type { SemanticsContext } from '@volter/world-core';
+import type { Row } from './shared.js';
+/** Marks a context served by a read-only (mirror) twin: its subjects come from the real vendor, so it
+ *  has no vendor progress to simulate and a read never writes. */
+export declare const READ_ONLY: unique symbol;
+/** Whether this request is served by a read-only twin. */
+export declare const readOnly: (ctx: SemanticsContext) => boolean;
+/** Where the vendor takes each in-flight state next, per resource. */
+export declare const PROGRESS: Record<string, Record<string, string>>;
+/** Whether the vendor still has work to do on a stored subject. */
+export declare const inFlight: (resource: string, row: Row) => boolean;
+/** Walk one subject to where the vendor leaves it. `finish` adds what its end state carries (an
+ *  output file, a fine-tuned model). Answers the end state when this read is the one that moved it. */
+export declare function progress(ctx: SemanticsContext, resource: string, id: string, finish?: (row: Row, end: string) => Row): Promise<{
+    from: string;
+    to: string;
+    row: Row;
+} | undefined>;
+/** Every in-flight subject a read is about to show, walked on (a list observes as a get does). */
+export declare function progressAll(ctx: SemanticsContext, resource: string, finish?: (row: Row, end: string) => Row, only?: (row: Row) => boolean): Promise<void>;
+/** The derived core's answer for this read, once the vendor's work is observed. */
+export declare function coreAnswer(ctx: SemanticsContext): Promise<Response>;

package/dist/src/semantics/progress.js

@@ -0,0 +1,63 @@
+import { manifest } from "../manifest.js";
+/** Marks a context served by a read-only (mirror) twin: its subjects come from the real vendor, so it
+ *  has no vendor progress to simulate and a read never writes. */
+export const READ_ONLY = Symbol('openai.readOnly');
+/** Whether this request is served by a read-only twin. */
+export const readOnly = (ctx) => ctx[READ_ONLY] === true;
+/** Where the vendor takes each in-flight state next, per resource. */
+export const PROGRESS = {
+    Batch: { validating: 'in_progress', in_progress: 'finalizing', finalizing: 'completed', cancelling: 'cancelled' },
+    FineTuningJob: { validating_files: 'queued', queued: 'running', running: 'succeeded' },
+    RunObject: { queued: 'in_progress', in_progress: 'completed', cancelling: 'cancelled' },
+    EvalRun: { queued: 'in_progress', in_progress: 'completed' },
+    VectorStoreFileObject: { in_progress: 'completed' },
+    VectorStoreFileBatchObject: { in_progress: 'completed' },
+};
+/** Whether the vendor still has work to do on a stored subject. */
+export const inFlight = (resource, row) => String(row.status) in (PROGRESS[resource] ?? {});
+/** The effects the manifest declares on the vendor's move `from` → `to`, as values. */
+function effects(ctx, resource, from, to) {
+    const t = manifest.resources[resource]?.state?.status?.transitions.find((x) => x.actor === 'vendor' && x.to === to && x.from !== '*' && x.from.includes(from));
+    const out = {};
+    for (const [k, rule] of Object.entries(t?.effects ?? {}))
+        out[k] = 'now' in rule ? ctx.now() : 'value' in rule ? rule.value : null;
+    return out;
+}
+/** Walk one subject to where the vendor leaves it. `finish` adds what its end state carries (an
+ *  output file, a fine-tuned model). Answers the end state when this read is the one that moved it. */
+export async function progress(ctx, resource, id, finish) {
+    if (readOnly(ctx))
+        return undefined;
+    const storedAs = manifest.resources[resource]?.storedAs ?? resource;
+    return ctx.atomically((rows) => {
+        const current = rows(resource).find((r) => r.id === id);
+        if (!current || !inFlight(resource, current))
+            return { value: undefined };
+        const path = PROGRESS[resource];
+        const from = String(current.status);
+        let state = from;
+        const fields = {};
+        while (state in path) {
+            const to = path[state];
+            // the vendor's move, never the caller's: the machine must declare it
+            if (ctx.legal(resource, 'status', ctx.call.operation.id, state, to, id, 'vendor'))
+                break;
+            Object.assign(fields, effects(ctx, resource, state, to));
+            state = to;
+        }
+        Object.assign(fields, { status: state }, finish?.(current, state) ?? {});
+        return { value: { from, to: state, row: { ...current, ...fields } }, write: { resource, id, fields, operation: `${storedAs}.update` } };
+    });
+}
+/** Every in-flight subject a read is about to show, walked on (a list observes as a get does). */
+export async function progressAll(ctx, resource, finish, only = () => true) {
+    if (readOnly(ctx))
+        return;
+    for (const row of ctx.rowsRaw(resource))
+        if (only(row) && inFlight(resource, row))
+            await progress(ctx, resource, String(row.id), finish);
+}
+/** The derived core's answer for this read, once the vendor's work is observed. */
+export async function coreAnswer(ctx) {
+    return (await ctx.core()) ?? ctx.refuse({ status: 404, message: `Unknown request URL: ${ctx.call.request.method} ${new URL(ctx.call.request.url).pathname}. Please check the URL for typos.` });
+}

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

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

package/dist/src/semantics/responses.js

@@ -0,0 +1,153 @@
+import { serveScenario } from "../openai-scenario.js";
+import { buildResponse, createStoredResponse, emitResponse, responseMessages, responseSuffix, validateResponses } from "../openai-twin.js";
+import { readOnly } from "./progress.js";
+import { epoch, recordUsage, req, send, vendorView } from "./shared.js";
+const GA = { resource: 'Response', get: 'getResponse', cancel: 'cancelResponse' };
+const BETA = { resource: 'BetaResponse', get: 'beta_getResponse', cancel: 'beta_cancelResponse' };
+/** Each built-in tool call a response made is billed as one (the usage reports' web search and file search calls). */
+async function recordToolCalls(ctx, resp) {
+    for (const item of resp.output) {
+        if (item.type === 'web_search_call')
+            await recordUsage(ctx, 'web_search_calls', resp.model, 0, 0);
+        if (item.type === 'file_search_call')
+            await recordUsage(ctx, 'file_search_calls', resp.model, 0, 0);
+    }
+}
+const create = (engine, ops) => async (ctx) => {
+    const validated = validateResponses(ctx.params);
+    if ('error' in validated)
+        return send(ctx, validated.error);
+    const args = validated.args;
+    // each stored input already holds its ancestry: continuing appends the prior output once
+    if (args.previousResponseId) {
+        const prior = ctx.row(ops.resource, args.previousResponseId);
+        if (!prior)
+            return ctx.notFound(ops.resource, args.previousResponseId);
+        args.inputItems = [...(prior._input_items ?? []), ...(prior.output ?? []), ...args.inputItems];
+        args.messages = responseMessages(args.inputItems, args.instructions);
+    }
+    // the scenario decides the turn and honors a fault before any response exists, as on chat
+    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);
+    // a background response keeps its decision until its first poll, and streams nothing now
+    if (args.background) {
+        const queued = await createStoredResponse(args, req(ctx), decision);
+        return args.stream ? ctx.sse([]) : ctx.reply(queued);
+    }
+    const resp = args.store ? (await createStoredResponse(args, req(ctx), decision)) : buildResponse(args, ctx.occurredAt, responseSuffix(args), decision);
+    const events = [];
+    if (args.stream)
+        emitResponse(resp, (e) => { if (e.data)
+            events.push({ event: String(e.data.type ?? ''), data: e.data }); });
+    await recordUsage(ctx, 'responses', resp.model, resp.usage.input_tokens, resp.usage.output_tokens);
+    await recordToolCalls(ctx, resp);
+    return args.stream ? ctx.sse(events) : ctx.reply(resp);
+};
+// A background response is OpenAI's work, done over time: it is `queued`, then `in_progress` as its output is written,
+// then `completed` (https://platform.openai.com/docs/guides/background: "you can poll the response object... while the
+// status is `queued` or `in_progress`"). Extrapolation, the twin's own timing: a response waits a second in the queue, then
+// writes its output at 50 tokens a second; a poll in between sees the text written so far in a message still in progress.
+const QUEUED_SECONDS = 1;
+const TOKENS_PER_SECOND = 50;
+/** Where a background response has got to at `now`: its status and, in progress, the output written so far. */
+function backgroundAt(current, now, occurredAt) {
+    const created = Number(current.created_at);
+    const start = created + QUEUED_SECONDS;
+    if (now < start)
+        return { status: 'queued' };
+    const args = JSON.parse(String(current._bg_args ?? '{}'));
+    const decision = current._bg_decision ? JSON.parse(String(current._bg_decision)) : undefined;
+    const resp = buildResponse(args, occurredAt, String(current._bg_suffix ?? responseSuffix(args)), decision);
+    const finish = start + Math.max(1, Math.ceil(resp.usage.output_tokens / TOKENS_PER_SECOND));
+    if (now >= finish)
+        return { status: 'completed', resp: { ...resp, created_at: created, completed_at: finish }, at: finish };
+    const share = (now - start) / (finish - start);
+    const output = resp.output.flatMap((item) => {
+        if (item.type !== 'message')
+            return item.type === 'reasoning' ? [item] : [];
+        const whole = item.content[0]?.text ?? '';
+        return [{ ...item, status: 'in_progress', content: [{ ...item.content[0], text: whole.slice(0, Math.floor(whole.length * share)) }] }];
+    });
+    return { status: 'in_progress', output };
+}
+/** Observe OpenAI's work on a background response up to now, deciding and writing at once so concurrent reads move it
+ *  once (and record its usage once, when it completes). */
+async function observe(ctx, ops, id) {
+    const now = epoch(ctx);
+    const polled = await ctx.atomically((rows) => {
+        const current = rows(ops.resource).find((r) => r.id === id);
+        if (!current)
+            return { value: {} };
+        if (current.status !== 'queued' && current.status !== 'in_progress')
+            return { value: { row: current } };
+        const at = backgroundAt(current, now, ctx.occurredAt);
+        if (at.status === current.status && at.status === 'queued')
+            return { value: { row: current } };
+        // the vendor's move, not the caller's: a poll finds it moved on
+        // (further text in a response already in progress is no move of its status)
+        const refusal = at.status === current.status ? undefined : ctx.legal(ops.resource, 'status', ops.get, current.status, at.status, id, 'vendor');
+        if (refusal)
+            return { value: { row: current } };
+        const fields = at.status === 'completed'
+            ? { ...at.resp, background: true, _bg_args: null, _bg_suffix: null, _bg_decision: null }
+            : { status: 'in_progress', output: at.output };
+        return { value: { row: { ...current, ...fields }, ...(at.status === 'completed' ? { completed: at.resp } : {}) }, write: { resource: ops.resource, id, fields, operation: 'response.update' } };
+    });
+    if (polled.completed) {
+        await recordUsage(ctx, 'responses', polled.completed.model, polled.completed.usage.input_tokens, polled.completed.usage.output_tokens);
+        await recordToolCalls(ctx, polled.completed);
+    }
+    return polled.row;
+}
+const retrieve = (ops) => async (ctx) => {
+    const id = String(ctx.id);
+    const row = ctx.row(ops.resource, id);
+    if (!row)
+        return ctx.notFound(ops.resource, id);
+    // a read-only (mirror) twin holds the vendor's own state: it answers it as stored
+    if ((row.status !== 'queued' && row.status !== 'in_progress') || readOnly(ctx))
+        return ctx.reply(vendorView(row));
+    const seen = await observe(ctx, ops, id);
+    return seen ? ctx.reply(vendorView(seen)) : ctx.notFound(ops.resource, id);
+};
+// cancelling stops the response where OpenAI's work has got to: a queued one with no output, one in progress with the
+// output written so far, its message still `in_progress` (the reference's cancel example); a finished one is refused
+const cancel = (ops) => async (ctx) => {
+    const id = String(ctx.id);
+    let row = ctx.row(ops.resource, id);
+    if (!row)
+        return ctx.notFound(ops.resource, id);
+    if ((row.status === 'queued' || row.status === 'in_progress') && !readOnly(ctx))
+        row = (await observe(ctx, ops, id)) ?? row;
+    const refusal = ctx.legal(ops.resource, 'status', ops.cancel, row.status, 'cancelled');
+    if (refusal)
+        return ctx.refuse(refusal);
+    // cancelling a cancelled response again answers it as it is
+    if (row.status === 'cancelled')
+        return ctx.reply(vendorView(row));
+    return ctx.reply(await ctx.write(ops.resource, id, { status: 'cancelled', _bg_args: null, _bg_suffix: null, _bg_decision: null }, 'response.cancel'));
+};
+// the input items folded into a stored response (its ancestry included)
+const inputItems = (ops) => async (ctx) => {
+    const id = String(ctx.id);
+    const row = ctx.row(ops.resource, id);
+    if (!row)
+        return ctx.notFound(ops.resource, id);
+    // the list page names its first and last items, as every OpenAI list does
+    // (https://platform.openai.com/docs/api-reference/responses/input-items)
+    const data = row._input_items ?? [];
+    return ctx.reply({ object: 'list', data, first_id: data[0]?.id ?? null, last_id: data.at(-1)?.id ?? null, has_more: false });
+};
+export function responses(engine) {
+    return {
+        createResponse: create(engine, GA),
+        getResponse: retrieve(GA),
+        cancelResponse: cancel(GA),
+        listInputItems: inputItems(GA),
+        beta_createResponse: create(engine, BETA),
+        beta_getResponse: retrieve(BETA),
+        beta_cancelResponse: cancel(BETA),
+        beta_listInputItems: inputItems(BETA),
+    };
+}

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

@@ -0,0 +1,32 @@
+import type { SemanticsContext } from '@volter/world-core';
+import { type OpenAIRequest, type OpenAIResponseEnvelope } from '../openai-twin.js';
+export type Row = Record<string, unknown>;
+/** The request shape the pack's shared helpers take. */
+export declare function req(ctx: SemanticsContext): OpenAIRequest;
+/** An answer a pack helper built, with the headers it carries (a scripted fault's rate-limit family). */
+export declare function send(ctx: SemanticsContext, r: OpenAIResponseEnvelope): Response;
+/** OpenAI's invalid_request_error: 400 with the parameter it names and the code when there is one. */
+export declare const invalid: (ctx: SemanticsContext, message: string, param?: string, code?: string) => Response;
+/** A 404 in OpenAI's error shape, with the message the family uses. */
+export declare const missing: (ctx: SemanticsContext, message: string, code?: string) => Response;
+/** The world clock as OpenAI's unix seconds. */
+export declare const epoch: (ctx: SemanticsContext) => number;
+/** A path parameter, by the name the spec gives it. */
+export declare const at: (ctx: SemanticsContext, name: string) => string;
+/** An object parameter, or the fallback when the caller sent none. */
+export declare const objectOr: (v: unknown, fallback: unknown) => unknown;
+/** Only the updatable fields present in the request (OpenAI's modify-by-POST). */
+export declare function pick(params: Row, keys: string[]): Row;
+/** OpenAI's cursor page over items already in list order: `after` starts past that id (an unknown
+ *  one past the end), `limit` defaults to 20 and caps at 100. */
+export declare function page(ctx: SemanticsContext, items: Row[]): Response;
+/** A stored row as OpenAI shows it, from the raw row a handler read for its bookkeeping: its id
+ *  first, the kernel's fields and the twin's own (`_`-prefixed) left out. */
+export declare function vendorView(r: Row): Row;
+/** Newest first by `created_at`, rows of one instant by mint order (`proj-twin-10` newer than `proj-twin-9`), as the
+ *  derived core lists. */
+export declare const newest: (items: Row[], field?: string) => Row[];
+/** A billable call's usage, priced per model: what the organization usage and costs reports read. `extra` is what the
+ *  call's own report counts besides tokens (a speech's characters, a transcription's seconds, an image call's images,
+ *  size and source, a container's session). */
+export declare function recordUsage(ctx: SemanticsContext, kind: string, model: string, inputTokens: number, outputTokens: number, extra?: Row): Promise<void>;

package/dist/src/semantics/shared.js

@@ -0,0 +1,69 @@
+import { usageCost } from "../openai-twin.js";
+/** The request shape the pack's shared helpers take. */
+export function req(ctx) {
+    const url = new URL(ctx.call.request.url);
+    return { method: ctx.call.request.method, path: url.pathname + url.search, occurredAt: ctx.occurredAt, ...(ctx.root !== undefined ? { root: ctx.root } : {}) };
+}
+/** An answer a pack helper built, with the headers it carries (a scripted fault's rate-limit family). */
+export function send(ctx, r) {
+    if (!r.headers)
+        return ctx.reply(r.body, r.status);
+    return new Response(JSON.stringify(r.body), { status: r.status, headers: { 'content-type': 'application/json', ...r.headers } });
+}
+/** OpenAI's invalid_request_error: 400 with the parameter it names and the code when there is one. */
+export const invalid = (ctx, message, param, code) => ctx.refuse({ status: 400, message, ...(param ? { param } : {}), ...(code ? { code } : {}) });
+/** A 404 in OpenAI's error shape, with the message the family uses. */
+export const missing = (ctx, message, code) => ctx.refuse({ status: 404, message, ...(code ? { code } : {}) });
+/** The world clock as OpenAI's unix seconds. */
+export const epoch = (ctx) => Number(ctx.now());
+/** A path parameter, by the name the spec gives it. */
+export const at = (ctx, name) => ctx.call.params[name] ?? '';
+/** An object parameter, or the fallback when the caller sent none. */
+export const objectOr = (v, fallback) => (v && typeof v === 'object' ? v : fallback);
+/** Only the updatable fields present in the request (OpenAI's modify-by-POST). */
+export function pick(params, keys) {
+    const out = {};
+    for (const k of keys)
+        if (params[k] !== undefined)
+            out[k] = params[k];
+    return out;
+}
+/** Where a page starts after the cursor `after`: past that id, or past the end for an unknown one. */
+function startAfter(items, after) {
+    const i = items.findIndex((it) => it.id === after);
+    return i >= 0 ? i + 1 : items.length;
+}
+/** OpenAI's cursor page over items already in list order: `after` starts past that id (an unknown
+ *  one past the end), `limit` defaults to 20 and caps at 100. */
+export function page(ctx, items) {
+    const after = typeof ctx.params.after === 'string' ? ctx.params.after : '';
+    let limit = Number(ctx.params.limit);
+    if (!Number.isInteger(limit) || limit < 1)
+        limit = 20;
+    if (limit > 100)
+        limit = 100;
+    const start = after ? startAfter(items, after) : 0;
+    const data = items.slice(start, start + limit);
+    return ctx.reply({ object: 'list', data, has_more: start + limit < items.length, first_id: data[0]?.id ?? null, last_id: data[data.length - 1]?.id ?? null });
+}
+/** A stored row as OpenAI shows it, from the raw row a handler read for its bookkeeping: its id
+ *  first, the kernel's fields and the twin's own (`_`-prefixed) left out. */
+export function vendorView(r) {
+    const out = { id: r.id };
+    for (const [k, v] of Object.entries(r))
+        if (k !== 'type' && k !== 'updatedAt' && !k.startsWith('_'))
+            out[k] = v;
+    return out;
+}
+/** Newest first by `created_at`, rows of one instant by mint order (`proj-twin-10` newer than `proj-twin-9`), as the
+ *  derived core lists. */
+export const newest = (items, field = 'created_at') => [...items].sort((a, b) => Number(b[field]) - Number(a[field]) || String(b.id).localeCompare(String(a.id), undefined, { numeric: true }));
+/** A billable call's usage, priced per model: what the organization usage and costs reports read. `extra` is what the
+ *  call's own report counts besides tokens (a speech's characters, a transcription's seconds, an image call's images,
+ *  size and source, a container's session). */
+export async function recordUsage(ctx, kind, model, inputTokens, outputTokens, extra = {}) {
+    await ctx.record('_usage_record', {
+        object: '_usage_record', kind, model, input_tokens: inputTokens, output_tokens: outputTokens,
+        num_model_requests: 1, cost_usd: usageCost(model, inputTokens, outputTokens), created_at: epoch(ctx), ...extra,
+    });
+}

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

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

package/dist/src/semantics/uploads.js

@@ -0,0 +1,84 @@
+import { expiresAt } from "./files.js";
+import { epoch, invalid } from "./shared.js";
+const UPLOAD = 'Upload';
+/** The Upload the path names, when the machine in ../manifest.ts lets `operationId` act on it (only a
+ *  pending one takes parts, completes or cancels), or OpenAI's answer. */
+async function pending(ctx, operationId, to) {
+    const id = String(ctx.id);
+    let upload = ctx.row(UPLOAD, id, { withDeleted: true });
+    if (!upload)
+        return { answer: ctx.notFound(UPLOAD, id) };
+    // a pending Upload expires an hour after it was created (its expires_at): the clock's move, seen when a use looks
+    if (upload.status === 'pending' && Number(upload.expires_at) <= epoch(ctx) && !ctx.legal(UPLOAD, 'status', operationId, 'pending', 'expired', id, 'time')) {
+        upload = { ...upload, ...(await ctx.write(UPLOAD, id, { status: 'expired' }, 'upload.update')) };
+    }
+    const refusal = ctx.legal(UPLOAD, 'status', operationId, upload.status, to, id);
+    return refusal ? { answer: ctx.refuse(refusal) } : { upload };
+}
+const create = async (ctx) => {
+    const p = ctx.params;
+    for (const k of ['filename', 'purpose', 'bytes', 'mime_type']) {
+        if (p[k] === undefined || p[k] === '')
+            return invalid(ctx, `you must provide a ${k} parameter`, k);
+    }
+    const created = epoch(ctx);
+    const fields = {
+        object: 'upload', created_at: created, filename: String(p.filename), bytes: Number(p.bytes),
+        purpose: String(p.purpose), mime_type: String(p.mime_type), status: 'pending',
+        expires_at: created + 3600, file: null,
+    };
+    return ctx.reply(await ctx.write(UPLOAD, ctx.mint(UPLOAD), fields, 'upload.create'));
+};
+// A part's `data` is a multipart file from the SDK, or a string from an in-process caller.
+const addPart = async (ctx) => {
+    const found = await pending(ctx, 'addUploadPart');
+    if ('answer' in found)
+        return found.answer;
+    const data = ctx.params.data;
+    if (data === undefined)
+        return invalid(ctx, 'you must provide a data parameter', 'data');
+    const id = String(found.upload.id);
+    const parts = Array.isArray(found.upload._parts) ? [...found.upload._parts] : [];
+    const partId = `part-twin-${id}-${parts.length + 1}`;
+    parts.push({ id: partId, data: data && typeof data === 'object' ? String(data.content ?? '') : String(data) });
+    await ctx.write(UPLOAD, id, { _parts: parts }, 'upload.update');
+    return ctx.reply({ id: partId, object: 'upload.part', created_at: epoch(ctx), upload_id: id });
+};
+const complete = async (ctx) => {
+    const found = await pending(ctx, 'completeUpload', 'completed');
+    if ('answer' in found)
+        return found.answer;
+    const upload = found.upload;
+    const partIds = ctx.params.part_ids;
+    if (!Array.isArray(partIds) || partIds.length === 0)
+        return invalid(ctx, 'you must provide a part_ids array', 'part_ids');
+    const parts = Array.isArray(upload._parts) ? upload._parts : [];
+    const byId = new Map(parts.map((part) => [part.id, part.data]));
+    let content = '';
+    for (const pid of partIds) {
+        if (!byId.has(String(pid)))
+            return invalid(ctx, `unknown part_id '${pid}'`, 'part_ids');
+        content += byId.get(String(pid));
+    }
+    // OpenAI refuses to assemble a file whose parts do not add up to the bytes declared at creation
+    // (https://platform.openai.com/docs/api-reference/uploads/complete). Extrapolation: the wording is
+    // not sourced from a recording.
+    const sent = new TextEncoder().encode(content).length;
+    const declared = Number(upload.bytes);
+    if (sent !== declared)
+        return invalid(ctx, `The number of bytes uploaded (${sent}) does not match the number of bytes specified when the Upload was created (${declared}).`, 'bytes');
+    const file = await ctx.write('OpenAIFile', ctx.mint('OpenAIFile'), { object: 'file', bytes: Number(upload.bytes ?? content.length), created_at: epoch(ctx), expires_at: expiresAt(String(upload.purpose), epoch(ctx), undefined), filename: String(upload.filename), purpose: String(upload.purpose), status: 'processed', _content: content }, 'file.create');
+    return ctx.reply(await ctx.write(UPLOAD, String(upload.id), { status: 'completed', file }, 'upload.update'));
+};
+const cancel = async (ctx) => {
+    const found = await pending(ctx, 'cancelUpload', 'cancelled');
+    if ('answer' in found)
+        return found.answer;
+    return ctx.reply(await ctx.write(UPLOAD, String(found.upload.id), { status: 'cancelled' }, 'upload.cancel'));
+};
+export const uploads = {
+    createUpload: create,
+    addUploadPart: addPart,
+    completeUpload: complete,
+    cancelUpload: cancel,
+};

package/dist/src/semantics/vector-stores.d.ts

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