@volter/twin-cohere 0.1.0

package/dist/src/cohere-stub.js

@@ -0,0 +1,321 @@
+// ── hashing ─────────────────────────────────────────────────────────────────────────────
+/** A small deterministic 32-bit hash (FNV-1a) of a string — the seed for every stub below. */
+export 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 lowercase-hex id of `length` chars, seeded from `seed`. Cohere's response ids
+ *  are UUID-shaped; `cohereId` below assembles one from this. */
+function hexFrom(seed, length) {
+    let h = fnv1a(seed) || 1;
+    let out = '';
+    while (out.length < length) {
+        h ^= h << 13;
+        h >>>= 0;
+        h ^= h >> 17;
+        h ^= h << 5;
+        h >>>= 0;
+        out += h.toString(16).padStart(8, '0');
+    }
+    return out.slice(0, length);
+}
+/**
+ * A deterministic UUID-v4-SHAPED id. Cohere returns UUIDs for `id` / `generation_id` /
+ * `response_id`, so the twin returns something a caller parsing a UUID accepts — derived from the
+ * request rather than from `crypto.randomUUID`, because a random id would make the served response
+ * non-deterministic and break replay (CLAUDE.md, serve-path determinism).
+ */
+export function cohereId(seed) {
+    const h = hexFrom(seed, 32);
+    // Set the version nibble to 4 and the variant nibble to 8 so the string is a well-formed UUIDv4.
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-8${h.slice(17, 20)}-${h.slice(20, 32)}`;
+}
+// ── token accounting ────────────────────────────────────────────────────────────────────
+/** Deterministic token estimate: ~1 token per 4 chars. 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 v2 message's content (string OR content-part array) to its text. Cohere's parts are
+ *  `{type:'text',text}`, `{type:'image_url',image_url}` and `{type:'document',document}`; only the
+ *  first contributes literal text, the rest contribute their JSON length so the count stays
+ *  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 input-token count for a full v2 message list. */
+export function countInputTokens(messages) {
+    let total = 0;
+    for (const m of messages) {
+        total += estimateTokens(contentToText(m.content));
+        if (typeof m.tool_plan === 'string')
+            total += estimateTokens(m.tool_plan);
+        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. */
+export function lastUserText(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i].role === 'user')
+            return contentToText(messages[i].content);
+    }
+    return messages.length ? contentToText(messages[messages.length - 1].content) : '';
+}
+// ── chat stubs ──────────────────────────────────────────────────────────────────────────
+/**
+ * The deterministic stub ASSISTANT text. 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 Cohere twin (no model weights are run). Echoing your last message: ${echo || '(empty)'}`;
+}
+/** The v1 chat stub — v1 takes a single `message` string rather than a message list. */
+export function stubV1Text(message, model) {
+    const echo = message.length > 200 ? `${message.slice(0, 200)}…` : message;
+    return `[twin-stub:${model}] This is a deterministic stub from the Cohere twin (no model weights are run). Echoing your message: ${echo || '(empty)'}`;
+}
+/** The `tool_plan` a real Cohere model emits alongside tool calls — a chain-of-thought style
+ *  reflection. Stubbed deterministically and labeled. */
+export function stubToolPlan(toolNames) {
+    return `[twin-stub] I will call ${toolNames.length === 1 ? 'the tool' : 'the tools'} ${toolNames.join(', ')} to answer this.`;
+}
+function toolName(t) {
+    const o = t;
+    if (o?.function && typeof o.function.name === 'string')
+        return o.function.name;
+    if (typeof o?.name === 'string')
+        return o.name;
+    return 'unknown_function';
+}
+/** Every declared tool's name, in declaration order. */
+export function toolNames(tools) {
+    if (!Array.isArray(tools))
+        return [];
+    return tools.map(toolName);
+}
+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 '';
+    }
+}
+/**
+ * A deterministic stub argument STRING for a tool. Real models emit arguments that validate
+ * against the tool's declared JSON schema, so the twin synthesizes a deterministic object
+ * containing every declared property with a type-appropriate placeholder. Cohere's `arguments` is
+ * a STRING on the wire (`ToolCallV2Function.arguments`), like OpenAI's.
+ */
+export function stubToolArguments(tool) {
+    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 out = {};
+    for (const [key, def] of Object.entries(props))
+        out[key] = placeholderForSchema(def);
+    return JSON.stringify(out);
+}
+/**
+ * When tools are provided, a real Cohere model may answer with `tool_calls` and
+ * `finish_reason: 'TOOL_CALL'`. The stub deterministically "calls" the tool selected by
+ * `forcedName` (a named `tool_choice`) or the FIRST provided tool.
+ *
+ * The id is SEEDED FROM THE REQUEST, never from a module-level counter: a counter makes the id
+ * depend on how many completions the process happened to serve, which is not a property a replay
+ * can rely on, and hands two different turns the same id inside one process. Hashing the
+ * conversation keeps replay byte-identical while making ids differ between turns.
+ */
+export function stubToolCall(tools, seed, index, forcedName) {
+    if (!Array.isArray(tools) || tools.length === 0)
+        return null;
+    const chosen = forcedName ? (tools.find((t) => toolName(t) === forcedName) ?? tools[0]) : tools[0];
+    const name = toolName(chosen);
+    return { id: toolCallId(`${seed}|${name}|${index}`), type: 'function', function: { name, arguments: stubToolArguments(chosen) } };
+}
+/** Cohere's tool-call ids are UUID-shaped, like its response ids. */
+export function toolCallId(seed) {
+    return cohereId(`cohere-tool-${seed}`);
+}
+// ── embeddings: deterministic pseudo-vectors ────────────────────────────────────────────
+/**
+ * A deterministic, reproducible L2-normalized pseudo-embedding for `text`. NOT a real embedding —
+ * the values carry no semantic meaning; only the SHAPE, the dimensionality and the DETERMINISM are
+ * faithful. Same text → same vector, in every process
+ * and every state root.
+ */
+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++) {
+        state ^= state << 13;
+        state >>>= 0;
+        state ^= state >> 17;
+        state ^= state << 5;
+        state >>>= 0;
+        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;
+}
+/**
+ * Quantize a float vector into one of Cohere's non-float `embedding_types`. The vendor returns the
+ * SAME vector under every requested type, quantized — so the twin derives all of them from the one
+ * pseudo-vector rather than hashing separately per type, which is what makes the types agree the
+ * way a real response's do.
+ *   • int8   — signed 8-bit, [-128, 127]
+ *   • uint8  — unsigned 8-bit, [0, 255]
+ *   • binary/ubinary — one BIT per dimension, packed 8 to a byte (so the array is dim/8 long),
+ *     signed and unsigned respectively; this packing is why a binary embedding is 1/32 the size.
+ */
+export function quantizeEmbedding(floats, type) {
+    if (type === 'int8')
+        return floats.map((v) => clamp(Math.round(v * 127), -128, 127));
+    if (type === 'uint8')
+        return floats.map((v) => clamp(Math.round((v + 1) * 127.5), 0, 255));
+    // binary / ubinary: pack the SIGN of each dimension, 8 bits to a byte, most-significant first.
+    const bytes = [];
+    for (let i = 0; i < floats.length; i += 8) {
+        let b = 0;
+        for (let bit = 0; bit < 8; bit++) {
+            const v = floats[i + bit];
+            if (v !== undefined && v > 0)
+                b |= 1 << (7 - bit);
+        }
+        bytes.push(type === 'binary' ? (b > 127 ? b - 256 : b) : b);
+    }
+    return bytes;
+}
+/** Base64 of the float vector's little-endian float32 bytes — Cohere's `base64` embedding type. */
+export function base64Embedding(floats) {
+    const buf = new ArrayBuffer(floats.length * 4);
+    const view = new DataView(buf);
+    for (let i = 0; i < floats.length; i++)
+        view.setFloat32(i * 4, floats[i], true);
+    const bytes = new Uint8Array(buf);
+    let binary = '';
+    for (const b of bytes)
+        binary += String.fromCharCode(b);
+    // btoa is available in Bun and in every runtime this pack targets.
+    return btoa(binary);
+}
+function clamp(n, lo, hi) {
+    return n < lo ? lo : n > hi ? hi : n;
+}
+/** The output dimensionality Cohere's embed models produce, by model id. `embed-v4.0` accepts an
+ *  explicit `output_dimension` from the closed set {256, 512, 1024, 1536}; the v3 models are fixed
+ *  (1024 for the full models, 384 for the `light` ones). */
+export function embedDimensions(model) {
+    if (model.includes('light'))
+        return 384;
+    if (model === 'embed-v4.0')
+        return 1536;
+    return 1024;
+}
+/** `embed-v4.0`'s documented closed `output_dimension` set. A literal here, so the handler's
+ *  rejection of anything outside it is checkable against the vendor's documented set. */
+export const COHERE_OUTPUT_DIMENSIONS = [256, 512, 1024, 1536];
+// ── rerank: a deterministic lexical heuristic ───────────────────────────────────────────
+/**
+ * Score one document against a query. NOT the real cross-encoder — a deterministic
+ * token-overlap ratio, so the ORDERING is explainable and reproducible while carrying no learned
+ * relevance. Always in [0, 1], the range the vendor's `relevance_score` occupies.
+ *
+ * A tiny hash term breaks ties deterministically, so two documents with identical overlap still
+ * get a stable, total order rather than an order that depends on sort stability.
+ */
+export function rerankScore(query, document) {
+    const q = new Set(tokens(query));
+    const d = tokens(document);
+    if (q.size === 0 || d.length === 0)
+        return 0;
+    let hits = 0;
+    for (const t of d)
+        if (q.has(t))
+            hits++;
+    const overlap = hits / Math.max(q.size, d.length);
+    const tiebreak = (fnv1a(`${query}|${document}`) % 1000) / 1_000_000; // < 0.001
+    return Math.min(1, Number((overlap + tiebreak).toFixed(6)));
+}
+function tokens(text) {
+    return text.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+}
+// ── classify: a deterministic label heuristic ───────────────────────────────────────────
+/**
+ * Deterministically score `input` across `labels`. NOT the real classifier — the confidence is a
+ * hash-derived value per (input, label), normalized so the confidences SUM TO 1 the way a real
+ * single-label classification's do. The prediction is the argmax.
+ */
+export function classifyText(input, labels) {
+    const raw = labels.map((l) => (fnv1a(`${input}::${l}`) % 10_000) + 1);
+    const total = raw.reduce((a, b) => a + b, 0);
+    const confidences = raw.map((r) => Number((r / total).toFixed(6)));
+    let best = 0;
+    for (let i = 1; i < confidences.length; i++)
+        if (confidences[i] > confidences[best])
+            best = i;
+    return { prediction: labels[best], confidences };
+}
+// ── tokenize / detokenize: a deterministic, LEARNED vocabulary ──────────────────────────
+/**
+ * Segment text the way the twin's tokenizer does. NOT Cohere's BPE (vendoring the published
+ * tokenizer JSON is `cohere.tokenize.bpe_vocabulary`, a todo) — a deterministic word-with-trailing-whitespace
+ * split, chosen so that JOINING the segments restores the input EXACTLY, including runs of spaces
+ * and newlines. That exact-join property is what lets `detokenize(tokenize(t)) === t` hold, which
+ * is the property a caller actually depends on.
+ */
+export function segmentText(text) {
+    if (text === '')
+        return [];
+    return text.match(/\S+\s*|\s+/g) ?? [text];
+}
+/**
+ * The PREFERRED token id for a segment — a pure function of the segment, so the same text
+ * tokenizes to the same ids in every process and every state root.
+ *
+ * This is only a preference, not the answer: two different segments can hash to the same value,
+ * and a vocabulary that silently let the second one overwrite the first would make `detokenize`
+ * return the WRONG text for the earlier one. The handler resolves that by probing upward over the
+ * vocabulary it has already observed (`cohere-twin.ts`, `assignToken`) — deterministic given the
+ * stored state, which is what a twin's determinism means. Ids start at 1: Cohere's token ids are
+ * positive, and 0 is reserved so an unset field can never read as a valid token.
+ */
+export function preferredTokenId(segment) {
+    return (fnv1a(`cohere-tok:${segment}`) % 250_000) + 1;
+}

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

@@ -0,0 +1,82 @@
+import { fnv1a } from './cohere-stub.js';
+import { type CohereScenarioEngine, type ScriptedResult } from './cohere-scenario.js';
+import { type CohereChatV2Response, type CohereMessageV2, type SseSink } from './cohere-types.js';
+export type CohereRequest = {
+    /** The scenario engine (kernel grammar + this pack's vocabulary) — scripts chat turns. */
+    scenarioEngine?: CohereScenarioEngine;
+    method: string;
+    path: string;
+    body?: string;
+    occurredAt?: string;
+    root?: string;
+    readOnly?: boolean;
+    /** Lower-cased request headers (e.g. `authorization`) the HTTP server passes through so the
+     *  handler can model auth (401). In-process trusted calls (capability verifies, the connector)
+     *  omit them and are not auth-gated — the twin cannot validate against real keys, so the
+     *  modeled failure is the CHECKABLE missing/sentinel-invalid case. */
+    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` on a scripted 429. */
+export type CohereResponseEnvelope = {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+};
+export type ChatV2Args = {
+    model: string;
+    messages: CohereMessageV2[];
+    tools?: unknown;
+    toolChoice?: 'REQUIRED' | 'NONE';
+    maxTokens?: number;
+    stream: boolean;
+    thinking: boolean;
+};
+/** The outcome of ONE engine advance. `missTeach` is appended to the stub so an in-world agent
+ *  that never matched a handler is told what features it would have to match on. */
+type ScenarioOutcome = {
+    scripted?: ScriptedResult;
+    error?: CohereResponseEnvelope;
+    missTeach?: string;
+};
+/** Build the unary `POST /v2/chat` envelope. */
+export declare function buildChatV2(args: ChatV2Args, outcome?: ScenarioOutcome): CohereChatV2Response;
+/**
+ * Stream `POST /v2/chat` into the injected sink and return the same body the unary path would.
+ *
+ * The event sequence is Cohere's own, and it is asserted key-for-key against
+ * @ai-sdk/cohere's `cohereChatChunkSchema` — a `z.discriminatedUnion('type', …)`, so a wrong
+ * `type` or a missing `delta.message.content` is a hard parse failure in the real provider, not a
+ * soft mismatch. Note the shapes differ between `content-start` (a full content BLOCK under
+ * `delta.message.content`) and `content-delta` (just `{ text }`), which is exactly the sort of
+ * detail a hand-written stream gets wrong.
+ */
+export declare function streamChatV2(args: ChatV2Args, sink: SseSink, outcome?: ScenarioOutcome): CohereChatV2Response;
+/**
+ * Every method/path pair the dispatch below branches on. HAND-AUTHORED (the honest limit): a
+ * branch added to the handler and to neither this list nor the conformance snapshot is invisible
+ * to the conformance check's third direction. The mechanical backstop for that lives in
+ * `cohere-twin.test.ts` ("covers every literal path the handler dispatches on"), which reads this
+ * module's own source; segment-matched sub-routes still rest on review.
+ *
+ * `{id}` stands for one path segment.
+ */
+export declare const COHERE_ROUTER_SURFACE: ReadonlyArray<{
+    method: string;
+    path: string;
+}>;
+export declare function handleCohereTwinRequest(req: CohereRequest): Promise<CohereResponseEnvelope>;
+/** Re-exported so tests can assert the twin's closed sets against the vendor's without importing
+ *  the private constants by name. */
+export declare const COHERE_CLOSED_SETS: {
+    readonly datasetTypes: readonly string[];
+    readonly validationStatuses: readonly string[];
+    readonly embedJobStatuses: readonly string[];
+    readonly toolChoices: readonly string[];
+    readonly safetyModes: readonly string[];
+    readonly v2Roles: readonly string[];
+};
+/** Exported for the connector's shared FNV seed and for tests that need the twin's id derivation. */
+export { fnv1a };