@volter/twin-openai 0.1.1 → 2.0.0

package/dist/src/openai-scenario.js

@@ -0,0 +1,166 @@
+// The openai pack's scenario system on the kernel's ONE engine (@volter/world-core scenario.ts):
+// chat-completions vocabulary + the scripted-turn respond shape. New with the
+// TWIN-PROGRAMMING-MODEL consolidation — this pack previously had no scripting at all. The
+// handler FILE (handlers/openai.json in a world dir) is the only write surface.
+import { getActiveWorldStore, parseScenarioDocument, ScenarioError, ScenarioEngine } from '@volter/world-core';
+import { contentToText, estimateTokens, lastUserText } from "./openai-stub.js";
+const RESPOND_KEYS = new Set(['text', 'toolCalls', 'finishReason']);
+const FINISH_REASONS = new Set(['stop', 'length', 'tool_calls', 'content_filter']);
+const nonEmptyString = (cond) => typeof cond === 'string' && cond.length > 0;
+const positiveNumber = (cond) => typeof cond === 'number' && Number.isFinite(cond) && cond > 0;
+function lastToolResultNames(messages) {
+    const names = new Set();
+    const last = messages[messages.length - 1];
+    if (!last || last.role !== 'tool' || typeof last.tool_call_id !== 'string')
+        return names;
+    for (const m of messages) {
+        const am = m;
+        if (am.role !== 'assistant' || !Array.isArray(am.tool_calls))
+            continue;
+        for (const tc of am.tool_calls) {
+            if (tc?.id === last.tool_call_id && typeof tc?.function?.name === 'string')
+                names.add(tc.function.name);
+        }
+    }
+    return names;
+}
+function toolNames(tools) {
+    if (!Array.isArray(tools))
+        return [];
+    return tools.map((t) => typeof t?.function?.name === 'string' ? t.function.name : typeof t?.name === 'string' ? t.name : null).filter((n) => n !== null);
+}
+export const openaiScenarioAdapter = {
+    // R15 — a status fault in THIS vendor's envelope: the same {error:{message,type,param,code}}
+    // openai-twin.ts serves for its own refusals (its 429 is `type: 'rate_limit_exceeded'`).
+    renderFault: (f) => ({
+        body: {
+            error: {
+                message: f.message ?? (f.status === 429 ? 'Rate limit reached for requests. Limit your request rate or retry after the indicated delay.' : f.status >= 500 ? 'The server had an error while processing your request. Sorry about that!' : 'The request was refused by a scripted fault.'),
+                type: f.status === 429 ? 'rate_limit_exceeded' : f.status >= 500 ? 'server_error' : 'invalid_request_error',
+                param: null,
+                code: f.status === 429 ? 'rate_limit_exceeded' : null,
+            },
+        },
+    }),
+    vendor: 'openai',
+    features: (req) => ({
+        model: req.model,
+        lastUserText: lastUserText(req.messages).slice(0, 300),
+        tools: toolNames(req.tools),
+        lastMessageIsToolResult: req.messages[req.messages.length - 1]?.role === 'tool',
+        toolResultFor: [...lastToolResultNames(req.messages)],
+        // The output cap the caller asked for (max_tokens / max_completion_tokens), or 0 when it sent none. A
+        // proxy between the agent and this twin may clamp it; a handler keyed on it makes that clamp visible.
+        maxTokens: req.maxTokens ?? 0,
+    }),
+    matchers: {
+        modelEquals: (req, cond) => nonEmptyString(cond) && req.model === cond,
+        userTextIncludes: (req, cond) => nonEmptyString(cond) && lastUserText(req.messages).toLowerCase().includes(cond.toLowerCase()),
+        anyTextIncludes: (req, cond) => nonEmptyString(cond) && req.messages.map((m) => contentToText(m.content)).join('\n').toLowerCase().includes(cond.toLowerCase()),
+        lastMessageIsToolResult: (req, cond) => typeof cond === 'boolean' && (req.messages[req.messages.length - 1]?.role === 'tool') === cond,
+        toolResultFor: (req, cond) => nonEmptyString(cond) && lastToolResultNames(req.messages).has(cond),
+        hasTool: (req, cond) => nonEmptyString(cond) && toolNames(req.tools).includes(cond),
+        // A request whose output cap is below N (a cap it did not send counts as below every N).
+        maxTokensBelow: (req, cond) => positiveNumber(cond) && (req.maxTokens ?? 0) < cond,
+        maxTokensAtLeast: (req, cond) => positiveNumber(cond) && (req.maxTokens ?? 0) >= cond,
+    },
+    text: (req) => req.messages.map((m) => contentToText(m.content)).join('\n'),
+    validateOn: (on) => {
+        for (const k of ['modelEquals', 'userTextIncludes', 'anyTextIncludes', 'toolResultFor', 'hasTool'])
+            if (on[k] !== undefined && (typeof on[k] !== 'string' || !on[k]))
+                return `on.${k} is a non-empty string`;
+        if (on.lastMessageIsToolResult !== undefined && typeof on.lastMessageIsToolResult !== 'boolean')
+            return 'on.lastMessageIsToolResult is a boolean';
+        for (const k of ['maxTokensBelow', 'maxTokensAtLeast'])
+            if (on[k] !== undefined && !positiveNumber(on[k]))
+                return `on.${k} is a positive number`;
+        return null;
+    },
+    validateRespond: (respond) => {
+        if (typeof respond !== 'object' || respond === null || Array.isArray(respond))
+            return 'respond is an object { text?, toolCalls?, finishReason? }';
+        const r = respond;
+        for (const k of Object.keys(r))
+            if (!RESPOND_KEYS.has(k))
+                return `respond: unknown key "${k}" (valid: ${[...RESPOND_KEYS].join(', ')})`;
+        if (r.text !== undefined && typeof r.text !== 'string')
+            return 'respond.text is a string';
+        if (r.finishReason !== undefined && (typeof r.finishReason !== 'string' || !FINISH_REASONS.has(r.finishReason)))
+            return `respond.finishReason is one of ${[...FINISH_REASONS].join(', ')}`;
+        if (r.toolCalls !== undefined) {
+            for (const tc of Array.isArray(r.toolCalls) ? r.toolCalls : [r.toolCalls]) {
+                const t = tc;
+                if (!t || typeof t !== 'object' || Array.isArray(t))
+                    return 'respond.toolCalls entries are objects';
+                if (typeof t.name !== 'string' || !t.name)
+                    return 'respond.toolCalls[].name is a non-empty string';
+                if (!t.arguments || typeof t.arguments !== 'object' || Array.isArray(t.arguments))
+                    return 'respond.toolCalls[].arguments is an object';
+                if (t.id !== undefined && typeof t.id !== 'string')
+                    return 'respond.toolCalls[].id is a string';
+            }
+        }
+        if (r.text === undefined && r.toolCalls === undefined)
+            return 'respond needs text or toolCalls';
+        return null;
+    },
+};
+export function loadOpenAIScenarioDocument(path) {
+    let parsed;
+    try {
+        // Read through the ACTIVE WorldStore, never the filesystem directly (runtime contract
+        // R12b): the handlers document is WORLD STATE, so a MemoryWorldStore / DO-backed world
+        // serves ITS OWN scenario instead of whatever happens to sit on the host disk — and the
+        // serve path stays workerd-clean. A missing document keeps the historical ENOENT wording,
+        // so the loud load-time failure reads byte-identically to the read it replaces.
+        const raw = getActiveWorldStore().read(path);
+        if (raw === null)
+            throw new Error(`ENOENT: no such file or directory, open '${path}'`);
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new ScenarioError(`openai scenario: cannot read/parse ${path}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    return parseScenarioDocument(parsed, openaiScenarioAdapter);
+}
+/** What the scenario makes of one request: the decision a builder realizes, or a fault answered at once
+ *  (a status the script names; the script's own authoring failure is a 500 before any stream starts). */
+export async function serveScenario(engine, req, path) {
+    try {
+        return await engine.serve(req);
+    }
+    catch (error) {
+        if (!(error instanceof ScenarioError))
+            throw error;
+        console.error(`[openai twin] scenario error on ${path}: ${error.message}`);
+        return { kind: 'fault', result: { status: 500, body: { error: { message: error.message, type: 'twin_scenario_error', param: null, code: 'scenario_error' } }, headers: { 'x-request-id': 'req_twin' } } };
+    }
+}
+/** A decision as a turn: the scripted result, or, on a miss, the note that teaches where to script it. */
+export function scenarioTurn(decision, callIdPrefix) {
+    if (decision.kind === 'handler')
+        return { scripted: realizeOpenAIRespond(decision.respond, callIdPrefix) };
+    return { missTeach: `\n[twin-scenario miss — no handler matched. Author one in the world dir's handlers/openai.json (GET /twin explains; GET /twin/scenario lists handlers + misses). Features seen: ${JSON.stringify(decision.miss.features)}]` };
+}
+/** A scripted turn as a chat completion's choice. */
+export function scriptedChoice(scripted, index) {
+    const message = scripted.toolCalls.length
+        ? { role: 'assistant', content: scripted.text, tool_calls: scripted.toolCalls, refusal: null }
+        : { role: 'assistant', content: scripted.text ?? '', refusal: null };
+    return { choice: { index, message, logprobs: null, finish_reason: scripted.finishReason }, completionTokens: estimateTokens(JSON.stringify(scripted.toolCalls.length ? scripted.toolCalls : scripted.text ?? '')) };
+}
+export function createOpenAIScenarioEngine(document) {
+    return new ScenarioEngine(openaiScenarioAdapter, document);
+}
+export function realizeOpenAIRespond(respond, callIdPrefix = 'call_scripted') {
+    const toolCalls = [];
+    // Responses supplies a response-specific prefix so chained calls keep distinct identities.
+    for (const [i, tc] of (respond.toolCalls ? (Array.isArray(respond.toolCalls) ? respond.toolCalls : [respond.toolCalls]) : []).entries()) {
+        toolCalls.push({ id: tc.id ?? `${callIdPrefix}_${i + 1}`, type: 'function', function: { name: tc.name, arguments: JSON.stringify(tc.arguments) } });
+    }
+    return {
+        text: respond.text ?? (toolCalls.length ? null : ''),
+        toolCalls,
+        finishReason: respond.finishReason ?? (toolCalls.length ? 'tool_calls' : 'stop'),
+    };
+}

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

@@ -0,0 +1,40 @@
+import { type OpenAIScenarioEngine } from './openai-scenario.js';
+/** Options every OpenAI-twin HTTP surface needs, independent of who owns the socket. */
+export interface OpenAITwinFetchOptions {
+    root?: string;
+    readOnly?: boolean;
+    scenarioPath?: string;
+    /** a scenario engine already built (an in-process caller's), in place of `scenarioPath` */
+    scenarioEngine?: OpenAIScenarioEngine;
+    /** the World instant, when a caller pins it */
+    clock?: () => string;
+}
+/**
+ * The pack's whole HTTP surface as a plain `fetch` — Request in, Response out, no listener.
+ *
+ * This is the composable form (runtime contract R12's Cloudflare consequence): a Worker /
+ * Durable Object entry has NO loopback ports, so it must mount a pack's handler IN-PROCESS.
+ * `createOpenAITwinServer` is nothing but `Bun.serve` wrapped around this closure, so the
+ * standalone (R1) and hosted surfaces are the SAME code — there is no second HTTP adaptation
+ * to drift.
+ *
+ * WHAT IT SERVES IS UNCHANGED (R9): openai is a GENERATIVE pack, so chat/responses/embeddings
+ * answer a labeled deterministic stub or a scripted scenario — never a model, here or anywhere.
+ * The only wall-clock-shaped call on this path is `worldNow()`, the world's frozen instant.
+ *
+ * The scenario document is read ONCE, when the factory is called — the per-request path never
+ * touches storage at all. That one read goes through the ACTIVE WorldStore (runtime contract
+ * R12b), so a serverless entry MAY pass a `scenarioPath`: the handlers document is hydrated
+ * world state like any other, and a memory-backed namespace serves its own scripted answers
+ * with no filesystem in the picture (openai-serverless.test.ts pins exactly that).
+ */
+export declare function createOpenAITwinFetch(options: OpenAITwinFetchOptions): (request: Request) => Promise<Response>;
+export declare function createOpenAITwinServer(options: {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+    scenarioPath?: string;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;

package/dist/src/openai-server.js

@@ -0,0 +1,126 @@
+// OpenAI twin HTTP server — serve the full OpenAI twin handler over HTTP so the real `openai`
+// SDK (constructed with `baseURL: http://127.0.0.1:<port>/v1`) works unmodified. JSON bodies
+// (what the SDK sends for most calls) pass straight through. Writable by default; pass readOnly
+// to reject mutations (D3).
+//
+// Streaming: a chat completion or response with `"stream": true` is answered by its semantics
+// handler as server-sent events in OpenAI's `data: <json>\n\n` framing, ending `data: [DONE]`
+// (the manifest's framing); a failure decided before the stream answers JSON with its status.
+//
+// The surface is a plain `fetch` (`createOpenAITwinFetch`) and the SERVER is one line of
+// `Bun.serve` around it — see that factory's docstring for why (a serverless entry has no
+// port to bind, so it mounts the fetch in-process).
+import { bindSemantics, coreFor, createDerivedFetch, crossCutting, semanticsContext, serveHttp, vendorError } from '@volter/world-core';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { manifest } from "./manifest.js";
+import { openaiSemantics } from "./semantics/index.js";
+import { answerVendorErrors, RefusedWriteError } from '@volter/world-core';
+import { twinManifest } from '@volter/world-core';
+import { createOpenAIScenarioEngine, loadOpenAIScenarioDocument } from "./openai-scenario.js";
+import { openaiApiKeysScreen, projectKeyUse } from "./screens/api-keys.js";
+import { openaiSessionFlow } from "./screens/session.js";
+import { expireFiles } from "./semantics/files.js";
+import { observeBatches } from "./semantics/batches.js";
+import { observeJobs } from "./semantics/fine-tuning.js";
+/**
+ * The pack's whole HTTP surface as a plain `fetch` — Request in, Response out, no listener.
+ *
+ * This is the composable form (runtime contract R12's Cloudflare consequence): a Worker /
+ * Durable Object entry has NO loopback ports, so it must mount a pack's handler IN-PROCESS.
+ * `createOpenAITwinServer` is nothing but `Bun.serve` wrapped around this closure, so the
+ * standalone (R1) and hosted surfaces are the SAME code — there is no second HTTP adaptation
+ * to drift.
+ *
+ * WHAT IT SERVES IS UNCHANGED (R9): openai is a GENERATIVE pack, so chat/responses/embeddings
+ * answer a labeled deterministic stub or a scripted scenario — never a model, here or anywhere.
+ * The only wall-clock-shaped call on this path is `worldNow()`, the world's frozen instant.
+ *
+ * The scenario document is read ONCE, when the factory is called — the per-request path never
+ * touches storage at all. That one read goes through the ACTIVE WorldStore (runtime contract
+ * R12b), so a serverless entry MAY pass a `scenarioPath`: the handlers document is hydrated
+ * world state like any other, and a memory-backed namespace serves its own scripted answers
+ * with no filesystem in the picture (openai-serverless.test.ts pins exactly that).
+ */
+export function createOpenAITwinFetch(options) {
+    const readOnly = options.readOnly ?? false;
+    const scenarioPath = options.scenarioPath ?? process.env.TWIN_OPENAI_SCENARIO;
+    const scenarioEngine = options.scenarioEngine ?? (scenarioPath ? createOpenAIScenarioEngine(loadOpenAIScenarioDocument(scenarioPath)) : undefined);
+    const scope = { ...(options.root !== undefined ? { root: options.root } : {}), ...(options.clock ? { clock: options.clock } : {}) };
+    // THE READ DOORS (TWIN-PROGRAMMING-MODEL): discovery + inspection, read-only.
+    const door = (request) => {
+        const url = new URL(request.url);
+        if (request.method !== 'GET')
+            return undefined;
+        const path = url.pathname.replace(/\/+$/, '');
+        if (path === '/twin') {
+            return Response.json(twinManifest({
+                vendor: 'openai',
+                twinOf: 'OpenAI API (chat completions)',
+                stateSentence: 'Seed stored completions/files through the ordinary API with any key.',
+                behaviorSentence: 'Chat completions are scripted by MSW-shaped handlers in the world dir (handlers/openai.json): {on:{userTextIncludes|anyTextIncludes|modelEquals|hasTool|toolResultFor|lastMessageIsToolResult|nthCall}, respond:{text|toolCalls, finishReason?}, once?, phase?}. Unmatched requests answer a labeled stub naming this door.',
+                exampleHandler: { on: { userTextIncludes: 'summarize', hasTool: 'file_search' }, respond: { text: 'Scripted summary.' }, once: true },
+                engine: scenarioEngine,
+            }));
+        }
+        if (path === '/twin/scenario')
+            return Response.json(scenarioEngine ? scenarioEngine.status() : { vendor: 'openai', handlers: [], misses: 0, recentMisses: [] });
+        return undefined;
+    };
+    // a refused or failed write at the head (kernel head.ts) answers in the vendor's own error shape
+    // The derived dispatch owns the wire: semantics handlers, then the derived core for resources the
+    // manifest declares; an operation neither models answers OpenAI's unknown-URL 404.
+    const inner = createDerivedFetch({
+        surface,
+        handlers: bindSemantics(manifest, openaiSemantics({ ...(scenarioEngine ? { scenarioEngine } : {}), readOnly }), scope),
+        core: coreFor(manifest, scope),
+        around: crossCutting(manifest, { readOnly, ...scope }),
+        gap: (request) => vendorError(manifest, { status: 404, message: `Unknown request URL: ${request.method} ${new URL(request.url).pathname}. Please check the URL for typos.` }),
+    });
+    const handle = answerVendorErrors(inner, (error) => Response.json({ error: { message: error.message, type: error instanceof RefusedWriteError ? 'invalid_request_error' : 'server_error', param: null, code: error instanceof RefusedWriteError ? 'refused' : 'vendor_failed' } }, { status: error instanceof RefusedWriteError ? 400 : 502 }));
+    // OpenAI's own pages sit beside the API: the log-in (and the World's account door), and the dashboard's API keys page,
+    // where a project's keys are made
+    const screens = [openaiSessionFlow(scope), openaiApiKeysScreen(scope)];
+    // which part serves each spec operation (the derived dispatch's owners), for the pack's report
+    // (a scenario's authoring failure is answered where the scenario is served: openai-scenario.ts)
+    // time's moves OpenAI makes on its own (a file expiring: semantics/files.ts) are caught up to the World's clock
+    // before anything is answered, so every door reads the organization as it stands now
+    const filesClock = surface.operations.find((o) => o.id === 'listFiles');
+    // a project key presented to the API is used: its last use is recorded, and a revoked one refused (screens/api-keys.tsx)
+    const useKey = projectKeyUse(scope);
+    // and a read of the files observes the work whose outputs are files (a batch's output, a fine-tuning job's results)
+    // first, as a read of that batch or job does: the files a read lists never depend on which other read came before it
+    const catchUp = async (request) => {
+        const ctx = await semanticsContext(manifest, new Request(request.url), filesClock, scope);
+        await expireFiles(ctx);
+        if (request.method === 'GET' && /^\/v1\/files(\/|$)/.test(new URL(request.url).pathname))
+            for (const observe of [observeBatches, observeJobs])
+                await observe(ctx);
+    };
+    return Object.assign(async (request) => {
+        const opened = door(request);
+        if (opened)
+            return opened;
+        if (!readOnly)
+            await catchUp(request);
+        if (!readOnly) {
+            const refused = await useKey(request);
+            if (refused)
+                return refused;
+        }
+        if (!readOnly)
+            for (const screen of screens) {
+                const page = await screen(request);
+                if (page)
+                    return page;
+            }
+        return handle(request);
+    }, { owners: inner.owners });
+}
+export async function createOpenAITwinServer(options) {
+    const server = await serveHttp({
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        fetch: createOpenAITwinFetch(options),
+    });
+    return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}

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

@@ -0,0 +1,82 @@
+import type { ChatMessageParam, ChatToolCall } from './openai-types.js';
+/** 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 declare function estimateTokens(text: string): number;
+/** 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 declare function contentToText(content: ChatMessageParam['content']): string;
+/** Deterministic prompt-token count for the full set of messages. */
+export declare function countPromptTokens(messages: ChatMessageParam[]): number;
+/** The last user turn's text — the thing the stub echoes (deterministic, clearly labeled). */
+export declare function lastUserText(messages: ChatMessageParam[]): string;
+/**
+ * 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 declare function stubAssistantText(messages: ChatMessageParam[], model: string): string;
+/**
+ * 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 declare function stubToolArguments(tool: unknown, userText?: string): string;
+/**
+ * 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 declare function stubToolCall(tools: unknown, seq: number, forcedName?: string, userText?: string): ChatToolCall | null;
+/**
+ * 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 declare function stubJsonObject(messages: ChatMessageParam[], model: string, jsonSchema?: unknown): string;
+/** The per-token logprob shape OpenAI returns in `choices[].logprobs.content[]`. */
+export type LogprobToken = {
+    token: string;
+    logprob: number;
+    bytes: number[];
+    top_logprobs: Array<{
+        token: string;
+        logprob: number;
+        bytes: number[];
+    }>;
+};
+/**
+ * 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 declare function buildLogprobs(text: string, topN: number): {
+    content: LogprobToken[];
+};
+/** 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 declare function pseudoEmbedding(text: string, dimensions: number): number[];
+/** The moderation categories the twin reports (faithful key set). */
+export declare const MODERATION_CATEGORIES: readonly ["hate", "hate/threatening", "harassment", "harassment/threatening", "illicit", "illicit/violent", "self-harm", "self-harm/intent", "self-harm/instructions", "sexual", "sexual/minors", "violence", "violence/graphic"];
+export type ModerationResult = {
+    flagged: boolean;
+    categories: Record<string, boolean>;
+    category_scores: Record<string, number>;
+    category_applied_input_types?: Record<string, string[]>;
+};
+/** 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 declare function moderateText(text: string, image?: boolean): ModerationResult;