@volter/twin-deepseek 0.1.0

package/dist/src/deepseek-stub.js

@@ -0,0 +1,191 @@
+// THE GENERATIVE-STUB CORE — the deterministic labeled answer this twin gives where the vendor
+// runs a model.
+//
+// The twin CANNOT run the model — there are no weights here. So `POST /chat/completions` returns a
+// DETERMINISTIC STUB completion that is CLEARLY a twin stub, NEVER pretending to be real model
+// output, and the same is true of `reasoning_content` and the beta FIM endpoint. What IS faithful
+// is the ENTIRE PROTOCOL ENVELOPE: the response shape, the SSE chunk sequence, the `tool_calls`
+// shape, `finish_reason`, and DeepSeek's KV-cache-bearing `usage`.
+//
+// SERVE-PATH DETERMINISM (CLAUDE.md): every number below is a pure function of (request, stored
+// state). Note what is NOT here: DeepSeek's cache-hit accounting is NOT a random split and NOT a
+// clock reading — it is computed from the twin's own observed cache-prefix ledger
+// (deepseek-cache.ts), so a replay is byte-identical and a genuine prefix reuse is genuinely
+// reported as a hit.
+//
+// The stub IS the twin's answer: the manifest's chat, reasoning and FIM capabilities are claimed
+// on the envelope and the determinism. See the README ## Coverage.
+/** 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 one message (the unit the cache ledger also counts in, so
+ *  a prefix's hit tokens and the request's prompt tokens are measured the same way). */
+export function messageTokens(m) {
+    let total = estimateTokens(contentToText(m.content));
+    if (m.name)
+        total += estimateTokens(m.name);
+    if (typeof m.reasoning_content === 'string')
+        total += estimateTokens(m.reasoning_content);
+    for (const tc of m.tool_calls ?? [])
+        total += estimateTokens(JSON.stringify(tc));
+    return total;
+}
+/** Deterministic prompt-token count for the full set of messages. */
+export function countPromptTokens(messages) {
+    let total = 0;
+    for (const m of messages)
+        total += messageTokens(m);
+    return total;
+}
+/** The last user turn's text — the thing the stub echoes (deterministic, clearly labeled). */
+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) : '';
+}
+/**
+ * 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 DeepSeek twin (no model weights are run). Echoing your last message: ${echo || '(empty)'}`;
+}
+/**
+ * The `reasoning_content` DeepSeek returns while thinking mode is enabled (the default for every
+ * V4 model). A labeled stub, like the content — never a real chain of thought.
+ */
+export function stubReasoningText(messages, model, effort) {
+    return `[twin-stub:${model}] deterministic stub reasoning_content (no model weights are run, reasoning_effort=${effort}) for: ${lastUserText(messages).trim().slice(0, 120) || '(empty)'}`;
+}
+/** The deterministic FIM continuation for `POST /beta/completions`. Labeled, and it names the
+ *  suffix it was asked to bridge to so the caller can see the twin honoured the parameter. */
+export function stubFimText(model, prompt, suffix) {
+    const bridge = suffix ? ` bridging to suffix "${suffix.slice(0, 60)}"` : '';
+    return `[twin-stub:${model}] deterministic fill-in-the-middle stub (no model weights are run)${bridge} after: ${prompt.trim().slice(0, 120) || '(empty)'}`;
+}
+/**
+ * Assemble DeepSeek's `usage`. The cache split is supplied by the caller (from the cache-prefix
+ * ledger) and the invariant DeepSeek's own docs state is enforced here rather than assumed:
+ * `prompt_cache_hit_tokens + prompt_cache_miss_tokens === prompt_tokens`
+ * (api-docs.deepseek.com/guides/kv_cache). `prompt_tokens_details.cached_tokens` mirrors the hit
+ * count — `@ai-sdk/deepseek`'s usage schema declares it and reads `prompt_cache_hit_tokens` for
+ * `cacheRead`, so the two must agree.
+ */
+export function buildUsage(promptTokens, completionTokens, cacheHitTokens, reasoningTokens = 0) {
+    const hit = Math.max(0, Math.min(cacheHitTokens, promptTokens));
+    return {
+        prompt_tokens: promptTokens,
+        completion_tokens: completionTokens,
+        total_tokens: promptTokens + completionTokens,
+        prompt_cache_hit_tokens: hit,
+        prompt_cache_miss_tokens: promptTokens - hit,
+        prompt_tokens_details: { cached_tokens: hit },
+        ...(reasoningTokens > 0 ? { completion_tokens_details: { reasoning_tokens: reasoningTokens } } : {}),
+    };
+}
+/** Extract a tool's function name from a DeepSeek/OpenAI-shaped tool
+ *  (`{ type:'function', function:{ name } }`). */
+function toolName(t) {
+    const o = t;
+    if (o?.function && typeof o.function.name === 'string')
+        return o.function.name;
+    return '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 '';
+    }
+}
+/**
+ * Build a deterministic stub argument string for a tool. When the tool declares a JSON-schema
+ * `parameters` object, 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.
+ */
+export function stubToolArguments(tool) {
+    const o = tool;
+    const schema = o?.function?.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, 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. Returns null when no tools.
+ */
+export function stubToolCall(tools, seq, forcedName) {
+    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) } };
+}
+/**
+ * A deterministic JSON-object stub for `response_format: { type: 'json_object' }`. DeepSeek's JSON
+ * output mode guarantees only that the content parses as JSON — there is no schema on this vendor
+ * (`json_schema` is rejected, see deepseek-twin.ts), so the twin returns a clearly-labeled
+ * deterministic object rather than fabricating schema conformance it was never given.
+ */
+export function stubJsonObject(messages, model) {
+    return JSON.stringify({ _twin_stub: true, model, echo: lastUserText(messages).slice(0, 200) });
+}
+// ── Deterministic hashing ───────────────────────────────────────────────────────────────
+/** A small deterministic 32-bit hash (FNV-1a) of a string. */
+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;
+}
+/**
+ * DeepSeek's `system_fingerprint` is a backend-configuration string like
+ * `fp_eaab8d114b_prod0820_fp8_kvcache` (`@ai-sdk/deepseek` docs/30-deepseek.mdx, "Provider
+ * Metadata"). The twin serves a value in that SHAPE that is unmistakably a twin fingerprint and is
+ * derived from the request, so a replay is byte-identical.
+ */
+export function stubFingerprint(seed) {
+    return `fp_${fnv1a(seed).toString(16).padStart(8, '0')}_twin_stub_kvcache`;
+}

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

@@ -0,0 +1,77 @@
+import { type DeepSeekScenarioEngine } from './deepseek-scenario.js';
+import type { DeepSeekChatCompletion, DeepSeekMessageParam, SseSink } from './deepseek-types.js';
+/** DeepSeek's beta base URL suffix. `@ai-sdk/deepseek` turns prefix-completion and strict tool
+ *  calls on iff `baseURL.endsWith('/beta')` (src/deepseek-provider.ts), so the twin gates the same
+ *  two features on the same path segment. */
+export declare const DEEPSEEK_BETA_PREFIX = "/beta";
+/** DeepSeek's Anthropic-compatible surface lives here (api-docs.deepseek.com/guides/anthropic_api).
+ *  It is real vendor surface this twin does not model yet — filed as `deepseek.anthropic.messages`
+ *  and answered like any other unmodeled operation, never faked. */
+export declare const DEEPSEEK_ANTHROPIC_PREFIX = "/anthropic";
+export type DeepSeekRequest = {
+    /** The scenario engine (kernel grammar + this pack's vocabulary) — scripts chat turns. */
+    scenarioEngine?: DeepSeekScenarioEngine;
+    method: string;
+    path: string;
+    body?: string;
+    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. */
+    apiKey?: string;
+    /** Lower-cased request headers the HTTP server passes through so the handler can model auth
+     *  (401) and the deterministic 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. */
+export type DeepSeekResponseEnvelope = {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+};
+type ToolChoice = 'auto' | 'none' | 'required' | {
+    name: string;
+};
+type ResponseFormat = 'text' | 'json_object';
+type ReasoningEffort = 'low' | 'high' | 'max';
+type ChatArgs = {
+    model: string;
+    messages: DeepSeekMessageParam[];
+    tools?: unknown[];
+    maxTokens?: number;
+    stop?: string[];
+    stream: boolean;
+    includeUsage: boolean;
+    toolChoice?: ToolChoice;
+    responseFormat: ResponseFormat;
+    thinkingEnabled: boolean;
+    reasoningEffort: ReasoningEffort;
+    logprobs: boolean;
+    topLogprobs?: number;
+    userId?: string;
+    /** True when the request arrived under the `/beta` base URL. */
+    beta: boolean;
+};
+export declare function buildChatCompletion(args: ChatArgs, occurredAt?: string, scenarioEngine?: DeepSeekScenarioEngine, root?: string): DeepSeekChatCompletion | DeepSeekResponseEnvelope;
+/**
+ * Emit the vendor-faithful DeepSeek streaming sequence into the injected sink (NO sockets, NO
+ * setTimeout). The order: a first chunk with `delta:{role:'assistant', content:''}`, then
+ * `reasoning_content` deltas, then `content` deltas (or `tool_calls` deltas), then a chunk carrying
+ * `finish_reason`, and — when `stream_options.include_usage` was set — a FINAL chunk with an EMPTY
+ * `choices` array whose `usage` holds the completion's usage. `@ai-sdk/deepseek`'s `doStream`
+ * always sends `stream_options: { include_usage: true }`, so that tail chunk is what makes its
+ * `finish` part carry real token counts.
+ *
+ * REASONING BEFORE TEXT is not cosmetic: the SDK's transform closes its `reasoning-0` part the
+ * moment the first `content` delta arrives, so emitting them interleaved would produce a different
+ * part sequence than the vendor's.
+ */
+export declare function streamChat(args: ChatArgs, sink: SseSink, occurredAt?: string, scenarioEngine?: DeepSeekScenarioEngine, root?: string): DeepSeekChatCompletion | DeepSeekResponseEnvelope;
+export declare function handleDeepSeekTwinRequest(req: DeepSeekRequest): Promise<DeepSeekResponseEnvelope>;
+export {};