@volter/twin-openai 0.1.2 → 2.0.1

package/dist/src/openai-stub.js

@@ -0,0 +1,256 @@
+// THE GENERATIVE-STUB CORE (the twin's answer to generation).
+//
+// The twin CANNOT run the model — there are no weights here. So `POST /v1/chat/completions`
+// and `POST /v1/responses` return a DETERMINISTIC STUB completion that is CLEARLY a twin stub,
+// NEVER pretending to be real model output. `POST /v1/embeddings` returns DETERMINISTIC
+// pseudo-vectors (seeded from the input hash) — never real embedding values. What IS faithful
+// is the ENTIRE PROTOCOL ENVELOPE: the response shape, streaming chunk sequence, tool_calls
+// shape, finish_reason, and deterministic token counts.
+//
+// Pinned by `openai.chat.stub_labeled` and `openai.embeddings.deterministic` in the manifest.
+// capability manifest and the README ## Coverage: the protocol is real; the generation is a stub.
+/** Deterministic token estimate for a string: ~1 token per 4 chars (faithful order of
+ *  magnitude; deterministic so usage counts are assertable, like the vendor's tokenizer on a
+ *  fixed input). Never zero for non-empty text. */
+export function estimateTokens(text) {
+    if (!text)
+        return 0;
+    return Math.max(1, Math.ceil(text.length / 4));
+}
+/** Flatten a chat message's content (string OR content-part array) to its text for token
+ *  counting / echo. Non-text parts contribute their JSON length so the count is deterministic
+ *  and reflects payload size. */
+export function contentToText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (content === null || content === undefined)
+        return '';
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .map((part) => {
+        if (part && typeof part === 'object' && part.type === 'text') {
+            return String(part.text ?? '');
+        }
+        return JSON.stringify(part);
+    })
+        .join('\n');
+}
+/** Deterministic prompt-token count for the full set of messages. */
+export function countPromptTokens(messages) {
+    let total = 0;
+    for (const m of messages) {
+        total += estimateTokens(contentToText(m.content));
+        if (m.name)
+            total += estimateTokens(m.name);
+        for (const tc of m.tool_calls ?? [])
+            total += estimateTokens(JSON.stringify(tc));
+    }
+    return total;
+}
+/** The last user turn's text — the thing the stub echoes (deterministic, clearly labeled). */
+export function lastUserText(messages) {
+    // No user turn (e.g. only system) → fall back to the last message's text.
+    const turn = [...messages].reverse().find((m) => m.role === 'user') ?? messages.at(-1);
+    return turn ? contentToText(turn.content) : '';
+}
+/**
+ * Build the deterministic stub ASSISTANT text. It is unmistakably a twin stub: it carries the
+ * `[twin-stub:<model>]` marker and echoes the prompt, so no caller can mistake it for real
+ * model output. Deterministic for a given prompt → assertable in tests.
+ */
+export function stubAssistantText(messages, model) {
+    const prompt = lastUserText(messages).trim();
+    const echo = prompt.length > 200 ? `${prompt.slice(0, 200)}…` : prompt;
+    return `[twin-stub:${model}] This is a deterministic stub from the OpenAI twin (no model weights are run). Echoing your last message: ${echo || '(empty)'}`;
+}
+/** Extract a tool's function name from either a Chat Completions tool
+ *  (`{ type:'function', function:{ name } }`) or a legacy `functions` entry (`{ name }`). */
+function toolName(t) {
+    const o = t;
+    return o?.function && typeof o.function.name === 'string' ? o.function.name : typeof o?.name === 'string' ? o.name : 'unknown_function';
+}
+function placeholderForSchema(def) {
+    const d = def;
+    if (Array.isArray(d?.enum) && d.enum.length)
+        return d.enum[0];
+    switch (d?.type) {
+        case 'number':
+        case 'integer': return 0;
+        case 'boolean': return false;
+        case 'array': return [];
+        case 'object': return {};
+        default: return '';
+    }
+}
+// Words that name nothing a tool could take as a value.
+const STOPWORDS = new Set(['a', 'an', 'the', 'do', 'does', 'you', 'your', 'have', 'has', 'is', 'are', 'for', 'me', 'my', 'please', 'this', 'that', 'one', 'like', 'with', 'what', 'which', 'how', 'can', 'could', 'would', 'and', 'or', 'of', 'to', 'in', 'on', 'it', 'its', 'small', 'large', 'big', 'some', 'any']);
+/** The value the user's message names for a string parameter: its longest content word (the thing asked about: "Do you
+ *  have a small monstera?" names `monstera`), or none. */
+function namedIn(userText) {
+    // a link the message carries (an image's URL) is not what it asks about
+    const words = (userText.replace(/\S+:\/\/\S+/g, ' ').toLowerCase().match(/[a-z][a-z0-9-]*/g) ?? []).filter((w) => !STOPWORDS.has(w));
+    return words.reduce((best, w) => (!best || w.length > best.length ? w : best), undefined);
+}
+/**
+ * Build a deterministic stub argument string for a tool. When the tool declares a JSON-schema
+ * `parameters` object (especially with `strict:true`), real models emit arguments that validate
+ * against the schema; the twin synthesizes a deterministic object containing every declared
+ * property with a type-appropriate placeholder so `strict` callers parse it cleanly. A required
+ * string is never left empty: an empty value is schema-valid in type but names nothing, so an
+ * application's tool could not act on it and a story could not follow the call. It takes what the
+ * user's message names (`namedIn`), else a deterministic value of the parameter's own name; an enum
+ * takes the value the message names, else its first.
+ */
+export function stubToolArguments(tool, userText = '') {
+    const o = tool;
+    const schema = (o?.function?.parameters ?? o?.parameters);
+    const props = schema && typeof schema === 'object' ? schema.properties : undefined;
+    if (!props || typeof props !== 'object')
+        return '{}';
+    const required = new Set(Array.isArray(schema.required) ? schema.required.map(String) : []);
+    const words = new Set(userText.toLowerCase().match(/[a-z0-9-]+/g) ?? []);
+    const out = {};
+    for (const [key, def] of Object.entries(props)) {
+        const d = def;
+        const named = Array.isArray(d?.enum) ? d.enum.find((e) => typeof e === 'string' && words.has(e.toLowerCase())) : undefined;
+        out[key] = named ?? (required.has(key) && d?.type === 'string' && !Array.isArray(d?.enum) ? namedIn(userText) ?? `twin-${key}` : placeholderForSchema(def));
+    }
+    return JSON.stringify(out);
+}
+/**
+ * When tools/functions are provided, real models may respond with `tool_calls` and
+ * `finish_reason:'tool_calls'`. The stub deterministically "calls" the tool selected by
+ * `forcedName` (a named tool_choice) or the FIRST provided tool. Arguments are synthesized
+ * from the tool's JSON schema so strict callers parse them — clearly a stub, but a
+ * vendor-faithful tool_calls envelope. Returns the tool_call, or null when no tools provided.
+ */
+export function stubToolCall(tools, seq, forcedName, userText = '') {
+    if (!Array.isArray(tools) || tools.length === 0)
+        return null;
+    const chosen = forcedName ? (tools.find((t) => toolName(t) === forcedName) ?? tools[0]) : tools[0];
+    return { id: `call_twin_${seq}`, type: 'function', function: { name: toolName(chosen), arguments: stubToolArguments(chosen, userText) } };
+}
+/**
+ * Build a deterministic JSON-object stub for `response_format` json_object / json_schema. The
+ * model's job is to emit parseable JSON; the twin returns a clearly-labeled deterministic object
+ * (and, for json_schema, fills every declared property with a schema-typed placeholder so the
+ * caller's strict parse succeeds). Always valid JSON.
+ */
+export function stubJsonObject(messages, model, jsonSchema) {
+    const schema = jsonSchema;
+    const props = schema?.schema?.properties ?? schema?.properties;
+    if (!props || typeof props !== 'object')
+        return freeformJson(messages, model);
+    const out = {};
+    for (const [key, def] of Object.entries(props))
+        out[key] = placeholderForSchema(def);
+    return JSON.stringify(out);
+}
+/** JSON mode with no schema (`json_object`): a labeled object echoing the request. */
+function freeformJson(messages, model) {
+    return JSON.stringify({ _twin_stub: true, model, echo: lastUserText(messages).slice(0, 200) });
+}
+/** A whitespace-preserving token split: deterministic chunks of the stub text whose `token`
+ *  fields re-join into the exact text. NOT a real BPE tokenizer. */
+function splitForLogprobs(text) {
+    if (!text)
+        return [];
+    return text.match(/\s+|\S+/g) ?? [];
+}
+/**
+ * Build deterministic pseudo-logprobs for the stub completion text. Real models return a per-token
+ * logprob (a negative number) plus `top_logprobs` alternatives; the twin synthesizes a deterministic
+ * negative logprob per token (seeded from the token text) and `topN` alternatives. NOT real
+ * probabilities — the SHAPE and DETERMINISM are faithful, the values carry no model meaning.
+ * Re-joining `content[].token` reconstructs the full text exactly.
+ */
+export function buildLogprobs(text, topN) {
+    const tokens = splitForLogprobs(text);
+    const content = tokens.map((tok) => {
+        const seed = fnv1a(tok);
+        const lp = -((seed % 5000) / 1000); // deterministic logprob in (-5, 0]
+        const bytes = Array.from(new TextEncoder().encode(tok));
+        // the token itself, then `topN` labeled alternatives, each less likely
+        const top = [{ token: tok, logprob: lp, bytes }, ...Array.from({ length: topN }, (_, i) => ({ token: `«alt${i}»`, logprob: lp - 1 - (fnv1a(`${tok}#${i}`) % 3000) / 1000, bytes: [] }))];
+        return { token: tok, logprob: lp, bytes, top_logprobs: top.slice(0, Math.max(1, topN)) };
+    });
+    return { content };
+}
+// ── Embeddings: deterministic pseudo-vectors ────────────────────────────────────────────
+/** A small deterministic 32-bit hash (FNV-1a) of a string — the seed for a pseudo-vector. */
+function fnv1a(text) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return h >>> 0;
+}
+/** A deterministic, reproducible L2-normalized pseudo-embedding vector for `text`. NOT a real
+ *  embedding — the values carry no semantic meaning; only the SHAPE and DETERMINISM are
+ *  faithful (`openai.embeddings.deterministic`). Same text → same vector. */
+export function pseudoEmbedding(text, dimensions) {
+    const dim = Math.max(1, Math.floor(dimensions));
+    let state = fnv1a(text) || 1;
+    const raw = new Array(dim);
+    let norm = 0;
+    for (let i = 0; i < dim; i++) {
+        // xorshift32 PRNG seeded from the text hash → deterministic per (text, index).
+        state ^= state << 13;
+        state >>>= 0;
+        state ^= state >> 17;
+        state ^= state << 5;
+        state >>>= 0;
+        // map to [-1, 1)
+        const v = (state / 0xffffffff) * 2 - 1;
+        raw[i] = v;
+        norm += v * v;
+    }
+    norm = Math.sqrt(norm) || 1;
+    for (let i = 0; i < dim; i++)
+        raw[i] = raw[i] / norm;
+    return raw;
+}
+// ── Moderations: deterministic classifier ───────────────────────────────────────────────
+/** The moderation categories the twin reports (faithful key set). */
+export const MODERATION_CATEGORIES = [
+    'hate', 'hate/threatening', 'harassment', 'harassment/threatening', 'illicit', 'illicit/violent',
+    'self-harm', 'self-harm/intent', 'self-harm/instructions',
+    'sexual', 'sexual/minors', 'violence', 'violence/graphic',
+];
+/** The categories an image is classified in besides text (the spec's `category_applied_input_types`; the moderation
+ *  guide, https://platform.openai.com/docs/guides/moderation). */
+const IMAGE_CATEGORIES = new Set(['self-harm', 'self-harm/intent', 'self-harm/instructions', 'sexual', 'violence', 'violence/graphic']);
+// Deterministic keyword → category map. The twin can't run the real classifier, so it flags
+// on a fixed keyword list (clearly a heuristic). Shape is faithful; the decision is a stub.
+const MODERATION_KEYWORDS = {
+    kill: 'violence', murder: 'violence', attack: 'violence',
+    hate: 'hate', hateful: 'hate',
+    harass: 'harassment',
+    suicide: 'self-harm', 'self-harm': 'self-harm',
+};
+/** Deterministically moderate one input (its text, and whether it held an image) into the faithful result shape: each
+ *  category with the input types its score applies to, as every result carries them
+ *  (https://platform.openai.com/docs/api-reference/moderations/object). */
+export function moderateText(text, image = false) {
+    const lower = text.toLowerCase();
+    const categories = {};
+    const scores = {};
+    for (const c of MODERATION_CATEGORIES) {
+        categories[c] = false;
+        scores[c] = 0;
+    }
+    let flagged = false;
+    for (const [kw, cat] of Object.entries(MODERATION_KEYWORDS)) {
+        if (lower.includes(kw)) {
+            categories[cat] = true;
+            scores[cat] = 0.99;
+            flagged = true;
+        }
+    }
+    const applied = {};
+    for (const c of MODERATION_CATEGORIES)
+        applied[c] = image && IMAGE_CATEGORIES.has(c) ? ['text', 'image'] : ['text'];
+    return { flagged, categories, category_scores: scores, category_applied_input_types: applied };
+}

package/dist/src/openai-twin.d.ts

@@ -0,0 +1,182 @@
+import { type ScenarioDecision } from '@volter/world-core';
+import { type OpenAIScenarioEngine } from './openai-scenario.js';
+import type { ChatCompletion, ChatMessageParam, OpenAIResponse, SseSink } from './openai-types.js';
+export type OpenAIRequest = {
+    /** The scenario engine (kernel grammar + this pack's vocabulary) — scripts chat turns. */
+    scenarioEngine?: OpenAIScenarioEngine;
+    method: string;
+    path: string;
+    /** JSON text, or a multipart form (an upload) */
+    body?: string | FormData;
+    occurredAt?: string;
+    root?: string;
+    readOnly?: boolean;
+    /** The credential the caller presents (the SDK's bearer `Authorization` header). When a request
+     *  carries an auth SURFACE (this field set, or `headers` present), the twin holds it to the real
+     *  vendor rule: a credential is required → 401 on missing/invalid. In-process trusted calls
+     *  (capability verify, connector) omit BOTH and are not auth-gated — the twin can't validate
+     *  against real keys, so the modeled failure is the CHECKABLE missing/sentinel-invalid case. */
+    apiKey?: string;
+    /** Lower-cased request headers (e.g. `authorization`) the HTTP server passes through so the
+     *  handler can model auth (401) and the rate-limit trigger (429). */
+    headers?: Record<string, string>;
+    /** When set on a streaming POST, chunks are written here (no sockets). */
+    sseSink?: SseSink;
+};
+/** The handler response. `headers` (when present) are response headers the HTTP server should set
+ *  — e.g. `Retry-After` + the `x-ratelimit-*` family on a modeled 429. */
+export type OpenAIResponseEnvelope = {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+};
+export declare function usageCost(model: string, inputTokens: number, outputTokens: number): number;
+/** The query a report answers: its window, bucket width, page size, where the page starts, and its groups. */
+export type ReportQuery = {
+    start: number;
+    end: number;
+    width: number;
+    limit: number;
+    from: number;
+    groupBy: string[];
+};
+/** A report's query from its parameters; Costs buckets by day only and pages up to 180 of them. */
+export declare function reportQuery(params: Record<string, unknown>, now: number, costs: boolean): ReportQuery;
+/** Buckets of one page of the query, each holding `results(rows in its window)`. */
+export declare function bucketed(records: Array<Record<string, unknown>>, q: ReportQuery, results: (rows: Array<Record<string, unknown>>, at: number, until: number) => unknown[]): Record<string, unknown>;
+/** The usage report over the recorded usage rows, for one kind ('completions', 'embeddings', …). */
+export declare function usageReport(records: Array<Record<string, unknown>>, kind: string | undefined, q: ReportQuery): Record<string, unknown>;
+/** The costs report: the recorded usage priced per model, per bucket, by line item (usage kind) when grouped so. */
+export declare function costsReport(records: Array<Record<string, unknown>>, q: ReportQuery): Record<string, unknown>;
+type ToolChoice = 'auto' | 'none' | 'required' | {
+    name: string;
+};
+type ResponseFormat = {
+    kind: 'text';
+} | {
+    kind: 'json_object';
+} | {
+    kind: 'json_schema';
+    schema: unknown;
+};
+type ChatArgs = {
+    model: string;
+    messages: ChatMessageParam[];
+    tools?: unknown;
+    functions?: unknown;
+    n: number;
+    maxTokens?: number;
+    stop?: string[];
+    stream: boolean;
+    toolChoice?: ToolChoice;
+    parallelToolCalls: boolean;
+    responseFormat: ResponseFormat;
+    includeUsage: boolean;
+    logprobs: boolean;
+    topLogprobs?: number;
+    seed?: number;
+    logitBias?: Record<string, number>;
+    prediction?: string;
+    /** the reasoning effort a reasoning model spends (the request's `reasoning_effort`, else the default) */
+    reasoningEffort?: string;
+    store: boolean;
+    metadata?: Record<string, unknown>;
+    /** modalities: ['text'] (default) or ['text','audio'] — audio asks for a spoken output. */
+    audioOutput?: {
+        voice: string;
+        format: string;
+    };
+};
+export declare function validateChat(params: Record<string, unknown>): {
+    args: ChatArgs;
+} | {
+    error: OpenAIResponseEnvelope;
+};
+export declare function buildChatCompletion(args: ChatArgs, occurredAt?: string, decision?: ScenarioDecision): ChatCompletion;
+/**
+ * Emit the vendor-faithful Chat Completions streaming sequence into the injected sink (NO
+ * sockets, NO setTimeout). Real order: a first chunk with `delta:{role:'assistant'}`, then
+ * `delta:{content}` chunks (or tool_calls deltas), then a final chunk with `finish_reason`,
+ * then `[DONE]`. Deterministic + synchronous so a collector can assert the full sequence.
+ */
+export declare function streamChat(args: ChatArgs, sink: SseSink, occurredAt?: string, decision?: ScenarioDecision): ChatCompletion;
+export type ResponsesArgs = {
+    inputItems: Record<string, unknown>[];
+    instructions?: string;
+    model: string;
+    inputText: string;
+    messages: ChatMessageParam[];
+    stream: boolean;
+    store: boolean;
+    previousResponseId?: string;
+    /** reasoning.effort ('minimal'|'low'|'medium'|'high') → emit a reasoning item + reasoning_tokens. */
+    reasoningEffort?: string;
+    /** background:true → the response is created `queued` and processed asynchronously (poll + cancel). */
+    background: boolean;
+    /** The caller's tools, as sent (Responses shape `{type:'function', name, parameters}`); the scenario reads their names. */
+    tools?: unknown;
+    /** max_output_tokens, when sent — the output cap a scenario handler may key on. */
+    maxTokens?: number;
+    /** the request's settings a response answers back as sent, or OpenAI's defaults */
+    echo: {
+        metadata: unknown;
+        temperature: unknown;
+        top_p: unknown;
+        parallel_tool_calls: unknown;
+        tool_choice: unknown;
+        text: unknown;
+        truncation: unknown;
+        user: unknown;
+        max_tool_calls: unknown;
+        top_logprobs: unknown;
+        service_tier: unknown;
+    };
+    /** reasoning.summary, when sent: a reasoning item carries a summary only when one is asked for */
+    reasoningSummary?: string;
+};
+export declare function responseMessages(items: Record<string, unknown>[], instructions?: string): ChatMessageParam[];
+export declare function validateResponses(params: Record<string, unknown>): {
+    args: ResponsesArgs;
+} | {
+    error: OpenAIResponseEnvelope;
+};
+export declare function buildResponse(args: ResponsesArgs, occurredAt?: string, idSuffix?: string, decision?: ScenarioDecision): OpenAIResponse;
+export declare function responseSuffix(args: ResponsesArgs): string;
+export declare function createStoredResponse(args: ResponsesArgs, req: OpenAIRequest, decision?: ScenarioDecision): Promise<OpenAIResponse | Record<string, unknown>>;
+export declare function emitResponse(resp: OpenAIResponse, sink: SseSink): OpenAIResponse;
+export declare function handleEmbeddings(params: Record<string, unknown>): OpenAIResponseEnvelope;
+export declare function handleModerations(params: Record<string, unknown>, occurredAt?: string): OpenAIResponseEnvelope;
+/** An image answer, and its events when streamed. */
+export type ImageAnswer = OpenAIResponseEnvelope & {
+    events?: Array<{
+        event: string;
+        data: unknown;
+    }>;
+};
+export declare function handleImages(params: Record<string, unknown>, occurredAt?: string): ImageAnswer;
+export declare function handleImageEdit(params: Record<string, unknown>, occurredAt?: string): ImageAnswer;
+export declare function handleImageVariation(params: Record<string, unknown>, occurredAt?: string): OpenAIResponseEnvelope;
+export type Transcription = {
+    status: 200;
+    body: unknown;
+    seconds: number;
+    events?: Array<{
+        data: unknown;
+    }>;
+} | OpenAIResponseEnvelope;
+/** A transcription (or translation) of the uploaded audio: a labeled transcript naming the file, in the response
+ *  format asked (json, text, verbose_json with the word or segment timestamps asked, or diarized_json), with the
+ *  token log probabilities when `include[]=logprobs`, and as `transcript.text.delta` events then
+ *  `transcript.text.done` when `stream=true` on a model that streams (https://platform.openai.com/docs/api-reference/audio/createTranscription). */
+export declare function handleTranscription(params: Record<string, unknown>, translate: boolean): Transcription;
+export declare function handleSpeech(params: Record<string, unknown>): OpenAIResponseEnvelope | {
+    status: 200;
+    audio: Uint8Array;
+    type: string;
+};
+/** OpenAI's API as one call: the request goes through the pack's own dispatch (the derived dispatch over its
+ *  semantics, its derived core and the hand-written routes below), so a caller that holds no HTTP
+ *  server reaches exactly what an SDK does. A caller that presents no credential is a trusted
+ *  in-process caller and is not held to the auth rule; `sseSink` receives a stream's events. */
+export declare function handleOpenAITwinRequest(req: OpenAIRequest): Promise<OpenAIResponseEnvelope>;
+export {};