@theoremjs/react 0.0.0-stage → 0.3.1

package/client/decision-transport.js

@@ -0,0 +1,175 @@
+/**
+ * The browser side of a decision profile: what the host lets the page see of
+ * it, and the one call that asks its questions about some state.
+ *
+ * @module
+ */
+import { resolveObservabilityPolicy, TheoremError, traceRecordSchema, z, } from '@theoremjs/agents';
+import { fetchJson } from "./transport.js";
+import { checkWire } from "./wire-line.js";
+/** A score level's name: its text, or the first text inside a structured entry. */
+function entryLabel(entry, fallback) {
+    if (typeof entry === 'string')
+        return entry;
+    const entries = Array.isArray(entry) ? entry : Object.keys(entry);
+    return entries.length ? entryLabel(entries[0], fallback) : fallback;
+}
+function withField(field) {
+    return field === undefined ? {} : { field };
+}
+/** The first field an entry names in backticks, as in "the mug in `photo`". */
+function namedField(entry) {
+    if (typeof entry === 'string')
+        return /\x60([^\x60\s]+)\x60/.exec(entry)?.[1];
+    const entries = Array.isArray(entry) ? entry : Object.values(entry);
+    for (const each of entries) {
+        const field = namedField(each);
+        if (field !== undefined)
+            return field;
+    }
+    return undefined;
+}
+/** The page's view of a decision profile, the questions its host asks, and the host's own images. */
+export function decisionInterface(profile, questions, images) {
+    return {
+        type: 'decision',
+        identity: { handle: profile.identity.handle },
+        contract: profile.decision.contract,
+        ...(profile.inputs.maxStateBytes === undefined
+            ? {}
+            : { maxStateBytes: profile.inputs.maxStateBytes }),
+        questions: Object.entries(questions).map(([id, question]) => ({
+            id,
+            type: question.type,
+            labels: question.type === 'choice'
+                ? Object.keys(question.criteria)
+                : question.type === 'score'
+                    ? question.criteria.map((entry, level) => entryLabel(entry, String(level)))
+                    : [],
+            ...(question.type === 'box'
+                ? withField(question.image ?? namedField(question.instructions))
+                : {}),
+        })),
+        ...(images && Object.keys(images).length > 0 ? { images } : {}),
+        ...(profile.observability
+            ? { observability: { record: resolveObservabilityPolicy(profile.observability).record } }
+            : {}),
+    };
+}
+/**
+ * The images a decision sends: the host's own and the page's. A page image may not take a name
+ * the host's use, so the questions always read the host's picture.
+ */
+export function decisionAssets(host, page) {
+    const clash = Object.keys(page ?? {}).find((name) => host && Object.hasOwn(host, name));
+    if (clash !== undefined)
+        // labels-exempt: internal diagnostic; the user reads error.request
+        throw new TheoremError('request', `the image ${clash} is the host's, so the page's needs another name`);
+    const all = { ...host, ...page };
+    return Object.keys(all).length > 0 ? all : undefined;
+}
+const probability = z.number().min(0).max(1);
+const probabilities = z
+    .record(z.string(), probability)
+    .refine((record) => Math.abs(Object.values(record).reduce((sum, value) => sum + value, 0) - 1) <= 0.001);
+const answerSchema = z.discriminatedUnion('type', [
+    z.object({
+        type: z.literal('choice'),
+        choice: z.string(),
+        confidence: probability,
+        probabilities,
+    }),
+    z.object({ type: z.literal('noul'), noul: probability }),
+    z.object({
+        type: z.literal('box'),
+        box: z.object({ top: probability, bottom: probability, left: probability, right: probability }),
+        confidence: probability,
+    }),
+    z.object({
+        type: z.literal('score'),
+        score: z.number().nonnegative(),
+        confidence: probability,
+        legend: z.record(z.string(), z.string().min(1)),
+        probabilities,
+    }),
+]);
+const replySchema = z.object({
+    result: z.object({
+        model: z.string().min(1),
+        answers: z.record(z.string(), answerSchema),
+        usage: z
+            .object({
+            inputTokens: z.number().int().nonnegative(),
+            outputTokens: z.number().int().nonnegative(),
+            costUsd: z.number().nonnegative().optional(),
+        })
+            .optional(),
+    }),
+    traces: z.array(traceRecordSchema).optional(),
+});
+/** The trace records a failed decision left, by the failure thrown for it. */
+const traceFailures = new WeakMap();
+/** Marks a decision's failure with the trace records it left, for the page's inspector. */
+export function withFailedTraces(err, traces) {
+    if (traces.length > 0 && typeof err === 'object' && err !== null)
+        traceFailures.set(err, traces);
+    return err;
+}
+/** The trace records a failed decision left; none when its host sent none. */
+export function failedTraces(err) {
+    return (typeof err === 'object' && err !== null && traceFailures.get(err)) || [];
+}
+export const failedDecisionTraces = failedTraces;
+const failedBody = z.object({ traces: z.array(traceRecordSchema) });
+/** POSTs `body` and reads its reply with `read`; a failure keeps the trace records its body carried. */
+export async function postWithTraces(url, body, signal, options, read) {
+    let traces = [];
+    const failed = (raw) => {
+        const parsed = failedBody.safeParse(raw);
+        if (parsed.success)
+            traces = parsed.data.traces;
+    };
+    try {
+        return read(await fetchJson(url, { body, signal, failed }, options));
+    }
+    catch (err) {
+        throw withFailedTraces(err, traces);
+    }
+}
+/** POSTs a decision and reads its reply; a failure keeps the trace records its body carried. */
+export function postDecision(url, body, signal, options = {}) {
+    return postWithTraces(url, body, signal, options, readDecisionReply);
+}
+/** A host's decide reply, checked: the answers, and any trace records it delivers. */
+export function readDecisionReply(raw) {
+    // labels-exempt: internal diagnostic; the user reads error.bad_response
+    return checkWire(replySchema, raw, 'the decision');
+}
+const describedSchema = z.object({
+    interface: z.object({
+        type: z.literal('decision'),
+        identity: z.object({ handle: z.string() }),
+        contract: z.string(),
+        maxStateBytes: z.number().optional(),
+        questions: z.array(z.object({
+            id: z.string(),
+            type: z.enum(['choice', 'noul', 'score', 'box']),
+            labels: z.array(z.string()),
+            field: z.string().optional(),
+        })),
+        images: z
+            .record(z.string(), z.object({ mimeType: z.enum(['image/png', 'image/jpeg']), data: z.string() }))
+            .optional(),
+        observability: z.object({ record: z.boolean() }).optional(),
+    }),
+});
+/** Transport for a host mounted with `createTheoremDecisionHandler`. Default endpoint `/api/decision`. */
+export function createDecisionTransport(options = {}) {
+    const base = (options.endpoint ?? '/api/decision').replace(/\/$/, '');
+    return {
+        async describe(signal) {
+            return checkWire(describedSchema, await fetchJson(base, { signal }, options), 'the decision description').interface;
+        },
+        decide: (state, signal, assets) => postDecision(`${base}/decide`, { state, ...(assets ? { assets } : {}) }, signal, options),
+    };
+}

package/client/decode-composer-draft.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Restore composer fields from a serializable pending `UserTurnDraft`.
+ */
+import type { UserTurnDraft } from '@theoremjs/agents/interface';
+export type ComposerDraftFields = {
+    text: string;
+    files: File[];
+    voice: File[];
+};
+/** Map an encoded pending draft back into live composer file fields. */
+export declare function composerFieldsFromDraft(draft: UserTurnDraft): ComposerDraftFields;

package/client/decode-composer-draft.js

@@ -0,0 +1,12 @@
+/**
+ * Restore composer fields from a serializable pending `UserTurnDraft`.
+ */
+import { pendingAttachmentsToFiles } from "./encode-files.js";
+/** Map an encoded pending draft back into live composer file fields. */
+export function composerFieldsFromDraft(draft) {
+    return {
+        text: draft.text ?? '',
+        files: pendingAttachmentsToFiles(draft.attachments ?? []),
+        voice: pendingAttachmentsToFiles(draft.voice ?? []),
+    };
+}

package/client/embedding-input.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The rules behind an embedding console: the inputs as the JSON a request
+ * sends, text split into documents, documents packed into the requests the
+ * profile allows, all checked the way the kernel checks them, and documents
+ * ranked by how alike they point to a query.
+ *
+ * @module
+ */
+import { type EmbeddingInput, type EmbeddingPart, type EmbeddingUsage } from '@theoremjs/agents';
+import type { AttachmentValidationIssue } from '@theoremjs/agents/interface';
+import type { EmbeddingInterface } from './embedding-transport.ts';
+/** A part that is not text: a file sent inline, or one the provider already holds. */
+export type EmbeddingMediaPart = Exclude<EmbeddingPart, {
+    type: 'text';
+}>;
+export type EmbeddingInputCheck = {
+    ok: true;
+    inputs: EmbeddingInput[];
+} | {
+    ok: false;
+    reason: 'invalid_json' | 'no_inputs';
+} | {
+    ok: false;
+    reason: 'too_many_inputs';
+    max: number;
+    inputs: EmbeddingInput[];
+} | {
+    ok: false;
+    reason: 'empty_input' | 'text_off';
+    index: number;
+    inputs: EmbeddingInput[];
+} | {
+    ok: false;
+    reason: 'attachments';
+    issues: AttachmentValidationIssue[];
+    inputs: EmbeddingInput[];
+};
+/** The request's inputs, read from its JSON; `undefined` when it is not a list of inputs. */
+export declare function readEmbeddingInputs(text: string): EmbeddingInput[] | undefined;
+/** One input, read from its JSON; `undefined` when it is not one. */
+export declare function readEmbeddingInput(text: string): EmbeddingInput | undefined;
+/** One input as fields edit it: its words, and the files beside them. */
+export type EmbeddingFields = {
+    text: string;
+    media: EmbeddingMediaPart[];
+};
+/** The input as fields, or `null` when it holds more than one text part and fields would lose it. */
+export declare function inputFields(input: EmbeddingInput): EmbeddingFields | null;
+/** Fields as the input they send: plain text alone, else its parts with the text first. */
+export declare function fieldsInput(fields: EmbeddingFields): EmbeddingInput;
+/** The inputs, held to the profile's rules and its model's limits as the kernel holds them in one request. */
+export declare function checkInputs(inputs: readonly EmbeddingInput[], rules: EmbeddingInterface['inputs']): EmbeddingInputCheck;
+/** The request's JSON as the inputs it sends, held to the profile's rules. */
+export declare function checkEmbeddingInputs(text: string, rules: EmbeddingInterface['inputs']): EmbeddingInputCheck;
+/** Where text is cut into documents: not at all, at each line, at blank lines, at commas, or at a separator of your own. */
+export type EmbeddingSplit = 'whole' | 'lines' | 'paragraphs' | 'commas' | {
+    separator: string;
+};
+/** The text as documents, each trimmed, none empty. */
+export declare function splitText(text: string, split: EmbeddingSplit): string[];
+/** A file read as words and split, not sent as media: plain text, Markdown, CSV, and JSON. */
+export declare function readsAsText(file: {
+    name: string;
+    type: string;
+}): boolean;
+/** The most inputs the console sends in one request when the model sets no cap. */
+export declare const MAX_BATCH_INPUTS = 100;
+/**
+ * The inputs, in order, as the fewest requests the profile and its model
+ * allow: each holds at most `most` inputs and passes {@linkcode checkInputs}.
+ * An input refused on its own goes alone, for the kernel to refuse.
+ */
+export declare function embeddingBatches(inputs: readonly EmbeddingInput[], rules: EmbeddingInterface['inputs'], most?: number): EmbeddingInput[][];
+/** Two calls' usage as one: token counts and costs added, estimated when either was. */
+export declare function addUsage(a: EmbeddingUsage | undefined, b: EmbeddingUsage | undefined): EmbeddingUsage | undefined;
+/** How alike two vectors point, from -1 to 1. */
+export declare function cosineSimilarity(a: readonly number[], b: readonly number[]): number;
+/** A document and how alike it points to the query, from -1 to 1. */
+export type EmbeddingMatch = {
+    index: number;
+    score: number;
+};
+/** The documents, most alike to the query first; a vector of another width is left out. */
+export declare function rankMatches(query: readonly number[], documents: readonly (readonly number[])[]): EmbeddingMatch[];

package/client/embedding-input.js

@@ -0,0 +1,194 @@
+/**
+ * The rules behind an embedding console: the inputs as the JSON a request
+ * sends, text split into documents, documents packed into the requests the
+ * profile allows, all checked the way the kernel checks them, and documents
+ * ranked by how alike they point to a query.
+ *
+ * @module
+ */
+import { base64Bytes, embeddingMediaIssues, } from '@theoremjs/agents';
+function isPart(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const part = value;
+    if (part.type === 'text')
+        return typeof part.text === 'string';
+    if (typeof part.mimeType !== 'string')
+        return false;
+    if (part.type === 'media')
+        return typeof part.data === 'string';
+    return part.type === 'media-ref' && typeof part.uri === 'string';
+}
+function isInput(value) {
+    if (typeof value === 'string')
+        return true;
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const parts = value.parts;
+    return Array.isArray(parts) && parts.every(isPart);
+}
+/** The request's inputs, read from its JSON; `undefined` when it is not a list of inputs. */
+export function readEmbeddingInputs(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    return Array.isArray(value) && value.every(isInput) ? value : undefined;
+}
+function partsOf(input) {
+    return typeof input === 'string' ? [{ type: 'text', text: input }] : input.parts;
+}
+/** One input, read from its JSON; `undefined` when it is not one. */
+export function readEmbeddingInput(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    return isInput(value) ? value : undefined;
+}
+/** The input as fields, or `null` when it holds more than one text part and fields would lose it. */
+export function inputFields(input) {
+    const parts = partsOf(input);
+    const texts = parts.filter((part) => part.type === 'text');
+    if (texts.length > 1)
+        return null;
+    return {
+        text: texts[0]?.text ?? '',
+        media: parts.filter((part) => part.type !== 'text'),
+    };
+}
+/** Fields as the input they send: plain text alone, else its parts with the text first. */
+export function fieldsInput(fields) {
+    if (fields.media.length === 0)
+        return fields.text;
+    return {
+        parts: [
+            ...(fields.text ? [{ type: 'text', text: fields.text }] : []),
+            ...fields.media,
+        ],
+    };
+}
+function mediaFacts(part) {
+    return part.type === 'media'
+        ? { mimeType: part.mimeType, sizeBytes: base64Bytes(part.data) }
+        : { mimeType: part.mimeType };
+}
+/** The inputs, held to the profile's rules and its model's limits as the kernel holds them in one request. */
+export function checkInputs(inputs, rules) {
+    const list = [...inputs];
+    if (list.length === 0)
+        return { ok: false, reason: 'no_inputs' };
+    if (rules.maxInputs !== undefined && list.length > rules.maxInputs)
+        return { ok: false, reason: 'too_many_inputs', max: rules.maxInputs, inputs: list };
+    const media = [];
+    for (const [index, input] of list.entries()) {
+        const parts = partsOf(input);
+        if (parts.length === 0 || parts.every((part) => part.type === 'text' && !part.text.trim()))
+            return { ok: false, reason: 'empty_input', index, inputs: list };
+        if (!rules.text && parts.some((part) => part.type === 'text' && part.text.trim()))
+            return { ok: false, reason: 'text_off', index, inputs: list };
+        const files = [];
+        for (const part of parts) {
+            if (part.type === 'text')
+                continue;
+            try {
+                files.push(mediaFacts(part));
+            }
+            catch {
+                return { ok: false, reason: 'invalid_json' };
+            }
+        }
+        media.push(files);
+    }
+    const issues = embeddingMediaIssues(rules, media);
+    return issues.length > 0
+        ? { ok: false, reason: 'attachments', issues, inputs: list }
+        : { ok: true, inputs: list };
+}
+/** The request's JSON as the inputs it sends, held to the profile's rules. */
+export function checkEmbeddingInputs(text, rules) {
+    const inputs = readEmbeddingInputs(text);
+    return inputs === undefined ? { ok: false, reason: 'invalid_json' } : checkInputs(inputs, rules);
+}
+/** The text as documents, each trimmed, none empty. */
+export function splitText(text, split) {
+    const pieces = split === 'whole'
+        ? [text]
+        : split === 'lines'
+            ? text.split(/\r?\n/)
+            : split === 'paragraphs'
+                ? text.split(/\r?\n[^\S\r\n]*\r?\n/)
+                : split === 'commas'
+                    ? text.split(',')
+                    : split.separator
+                        ? text.split(split.separator)
+                        : [text];
+    return pieces.map((piece) => piece.trim()).filter((piece) => piece !== '');
+}
+/** A file read as words and split, not sent as media: plain text, Markdown, CSV, and JSON. */
+export function readsAsText(file) {
+    return (file.type.startsWith('text/') ||
+        file.type === 'application/json' ||
+        /\.(txt|md|markdown|csv|tsv|json)$/i.test(file.name));
+}
+// why: OpenRouter caps no batch (it took 101 inputs); 100 is Gemini's cap, a size every provider checked carries.
+/** The most inputs the console sends in one request when the model sets no cap. */
+export const MAX_BATCH_INPUTS = 100;
+/**
+ * The inputs, in order, as the fewest requests the profile and its model
+ * allow: each holds at most `most` inputs and passes {@linkcode checkInputs}.
+ * An input refused on its own goes alone, for the kernel to refuse.
+ */
+export function embeddingBatches(inputs, rules, most = MAX_BATCH_INPUTS) {
+    const batches = [];
+    let current = [];
+    for (const input of inputs) {
+        const next = [...current, input];
+        if (current.length > 0 && (next.length > most || !checkInputs(next, rules).ok)) {
+            batches.push(current);
+            current = [input];
+        }
+        else
+            current = next;
+    }
+    if (current.length > 0)
+        batches.push(current);
+    return batches;
+}
+/** Two calls' usage as one: token counts and costs added, estimated when either was. */
+export function addUsage(a, b) {
+    if (!a || !b)
+        return a ?? b;
+    const sum = (x, y) => x === undefined && y === undefined ? undefined : (x ?? 0) + (y ?? 0);
+    const inputTokens = sum(a.inputTokens, b.inputTokens);
+    const costUsd = sum(a.costUsd, b.costUsd);
+    return {
+        ...(inputTokens === undefined ? {} : { inputTokens }),
+        ...(costUsd === undefined ? {} : { costUsd }),
+        ...(a.estimated || b.estimated ? { estimated: true } : {}),
+    };
+}
+/** How alike two vectors point, from -1 to 1. */
+export function cosineSimilarity(a, b) {
+    let dot = 0;
+    let aa = 0;
+    let bb = 0;
+    for (let i = 0; i < Math.min(a.length, b.length); i += 1) {
+        dot += a[i] * b[i];
+        aa += a[i] * a[i];
+        bb += b[i] * b[i];
+    }
+    return aa === 0 || bb === 0 ? 0 : dot / Math.sqrt(aa * bb);
+}
+/** The documents, most alike to the query first; a vector of another width is left out. */
+export function rankMatches(query, documents) {
+    return documents
+        .flatMap((values, index) => values.length === query.length ? [{ index, score: cosineSimilarity(query, values) }] : [])
+        .sort((a, b) => b.score - a.score);
+}

package/client/embedding-space.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The index as a space: each document a point in a ball, placed by the
+ * three directions its vectors differ most along, each measured in its own
+ * spread so the space is as deep as it is wide. Its direction from the
+ * centre is its direction along those three; its distance is how far it sits
+ * from the index's mean along them, as `r / (r + median)`, scaled so the
+ * farthest document is on the rim: the order of distances is kept, and no
+ * one far document squeezes the rest into the centre. A pair is alike when
+ * its cosine similarity stands out against every other pair in the index:
+ * more than {@link OUTLIER} robust deviations above the median pair. Most
+ * pairs in an index are unrelated, so the median and its deviation say what
+ * unrelated looks like for this model and these documents. Each document is
+ * linked to its nearest neighbour, the one its cosine similarity is highest
+ * with, when that pair is alike. A cluster is documents alike pairs connect,
+ * directly or through each other. Positions are a projection and only
+ * approximate; links and clusters are the vectors' own cosine similarity.
+ *
+ * @module
+ */
+/** A point in the space, inside the unit ball. */
+export type SpacePoint = readonly [number, number, number];
+/** One document in the space. */
+export type SpaceDocument = {
+    /** Its index among the documents. */
+    readonly index: number;
+    /** Where it sits in the unit ball. */
+    readonly position: SpacePoint;
+    /** The cluster it belongs to. */
+    readonly cluster: number;
+};
+/** Documents alike pairs connect, directly or through each other. */
+export type SpaceCluster = {
+    /** Its documents' indexes, in order. */
+    readonly members: readonly number[];
+    /** Its hue, from 0 to 1 around the colour wheel: where its members' mean vector lands, as an angle around the space's two widest directions, so neighbouring clusters share a family. */
+    readonly tone: number;
+};
+/** A document and its nearest neighbour, whose cosine similarity is above the space's threshold. */
+export type SpaceLink = {
+    readonly a: number;
+    readonly b: number;
+    /** Their cosine similarity. */
+    readonly similarity: number;
+};
+/** The three directions the space is drawn along, kept so a query lands consistently. */
+export type SpaceBasis = {
+    readonly mean: Float64Array;
+    /** Each a unit direction in the vectors' own space; fewer than three when the documents span fewer. */
+    readonly axes: readonly Float64Array[];
+    /** Each axis's spread over the documents; a point is measured along each in its own spread, so the space is as deep as it is wide. */
+    readonly spreads: readonly number[];
+    /** The documents' median distance from the mean, so measured. */
+    readonly scale: number;
+    /** The farthest document's `r / (r + scale)`; dividing by it puts that document on the rim. */
+    readonly reach: number;
+};
+export type EmbeddingSpace = {
+    readonly documents: readonly SpaceDocument[];
+    readonly clusters: readonly SpaceCluster[];
+    /** Each document's nearest neighbour, where that pair is above the threshold; a pair that is each other's nearest appears once. */
+    readonly links: readonly SpaceLink[];
+    /** The cosine similarity a pair must pass to be linked; `Infinity` when the index has too few pairs, or too alike, to say what unrelated looks like. */
+    readonly threshold: number;
+    readonly basis: SpaceBasis;
+    /** How wide the vectors are. */
+    readonly dimensions: number;
+};
+/**
+ * The similarity one must pass to stand out among `similarities`: their
+ * median plus {@link OUTLIER} robust deviations. `Infinity` when they have no
+ * spread, since then nothing stands out.
+ */
+export declare function outlierThreshold(similarities: ArrayLike<number>): number;
+/** The space for a set of document vectors, all at once. */
+export declare function layoutSpace(vectors: readonly (readonly number[])[]): EmbeddingSpace;
+/**
+ * The same space, laid out in slices between which the page goes on, so a
+ * large index never freezes it. Rejects with the signal's reason once aborted.
+ */
+export declare function layoutSpaceSoon(vectors: readonly (readonly number[])[], signal?: AbortSignal): Promise<EmbeddingSpace>;
+/** Where a query lands in the space: projected along the same directions as the documents. `null` when its width differs. */
+export declare function placeQuery(space: EmbeddingSpace, query: readonly number[]): SpacePoint | null;