@nhtio/adk/batteries/llm/transformers_js/helpers

Translation helpers for the transformers.js LLM adapter.

Remarks

Two layers, like the other LLM batteries:

1. Re-exported format-agnostic helpers from chat_common (string/trust-envelope renderers, the joi→JSON-Schema converter, thought rendering/filtering) — reused verbatim.
2. transformers.js-native mappers defined here — building the {role,content}[] message array
   • the tools definitions, and a stream accumulator that collects decoded text (parsing of tool calls / reasoning happens once after the stream drains, via the shared parser layer).

Interfaces

Interface	Description
BatteryLifecycleHooks	The opt-in lifecycle option block mixed into each battery's options interface. Every phase transition fires onLifecycle (the firehose) AND the matching per-phase hook; subscribe to either or both. All optional — omitting them leaves behavior byte-for-byte unchanged.
BatteryLifecycleReport	A single normalized lifecycle report.
ChatGenerationOptions	The canonical generation options both on-device batteries accept. Every field optional + defaulted.
GpuBudget	A snapshot of the WebGPU device's memory budget, as reported by the adapter/device limits.
GpuBufferInstrument	A handle returned by instrumentGpuBuffers: read live samples, then uninstall() to restore.
GpuBufferSample	A live GPU-memory sample taken by a GpuBufferInstrument.
ParsedToolCall	A single tool call extracted from model output. arguments is a parsed object, never a string.
ReasoningParseResult	The result of running a ReasoningParserFn over assistant text.
ReasoningParserOptions	Options shared by the bundled reasoning parsers.
ResolvedGenerationOptions	The resolved, fully-defaulted generation config the adapters consume.
ToolCallParserContext	Context passed to a parser: the names of the tools actually offered this turn.
ToolCallParseResult	The result of running a ToolCallParserFn over assistant text.
TransformersJsStreamAccumulator	A streaming accumulator over transformers.js TextStreamer decoded-text deltas.
TransformersJsTool	A tool definition in the transformers.js tools array (OpenAI-function-shaped).

Type Aliases

Type Alias	Description
BatteryLifecycleBattery	Which battery emitted a lifecycle report.
BatteryLifecycleCallback	A lifecycle report consumer.
BatteryLifecyclePhase	The coarse lifecycle phases a battery transitions through.
ChatSampler	The portable sampler strategy. Maps to each battery's native mechanism: - 'greedy' — deterministic argmax. transformers.js do_sample:false; LiteRT SamplerType.GREEDY (which is top-1, so k is forced to 1). - 'top-k' — sample from the top-k logits. transformers.js do_sample:true+top_k; LiteRT SamplerType.TOP_K+k. - 'top-p' — nucleus sampling. transformers.js do_sample:true+top_p; LiteRT SamplerType.TOP_P+p.
JsonValue	A JSON-serialisable value — the shape of parsed tool-call arguments.
ReasoningParserFn	A synchronous reasoning text parser.
ReasoningParserName	The bundled reasoning parser names, plus 'auto' (try-all) and 'none' (disable).
ToolCallParserFn	A synchronous tool-call text parser.
ToolCallParserName	The bundled family parser names, plus 'auto' (try-all) and 'none' (disable).

Variables

| Variable | Description | | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ------------------------------- | --------- | ------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | ---------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---- | ----------------------------------------------------------------------------------- | | barePythonicToolCallParser | Parse a BARE pythonic call — provide_answer(answer=“…”, sources=[“/x”]) — i.e. the pythonic NAME(kwargs) form WITHOUT the surrounding [ … ] list wrapper that pythonicToolCallParser requires. Small models (observed: Gemma-4 E2B via transformers.js) emit this for a single call, sometimes with a leading /, a call: prefix, or smart quotes in the args. | | BUNDLED_REASONING_PARSERS | The bundled reasoning parsers keyed by name (excluding 'auto'/'none'), orphan recovery ON. | | BUNDLED_TOOL_CALL_PARSERS | The bundled family parsers keyed by name (excluding 'auto'/'none'). | | DEFAULT_REASONING_PARSER_ORDER | The default 'auto' precedence. All three are literal-marker-anchored, so order is collision-free. | | DEFAULT_TOOL_CALL_PARSER_ORDER | The default 'auto' precedence. Marker-anchored families first (collision-free); the weak-signal pythonic/llama3_json forms run last and are gated on callee∈toolNames. | | defaultBarePythonicToolCallParser | Default barePythonicToolCallParser. | | defaultBuildTransformersJsMessages | Default buildTransformersJsMessages. | | defaultCreateAutoReasoningParser | Default createAutoReasoningParser. | | defaultCreateAutoToolCallParser | Default createAutoToolCallParser. | | defaultCreateTransformersJsStreamAccumulator | Default createTransformersJsStreamAccumulator. | | defaultEmitLifecycle | Default emitLifecycle. | | defaultGemmaChannelReasoningParser | Default gemmaChannelReasoningParser. | | defaultGemmaToolCallParser | Default gemmaToolCallParser. | | defaultGptOssToolCallParser | Default gptOssToolCallParser. | | defaultHarmonyAnalysisReasoningParser | Default harmonyAnalysisReasoningParser. | | defaultHermesToolCallParser | Default hermesToolCallParser. | | defaultLlama3JsonToolCallParser | Default llama3JsonToolCallParser. | | defaultLooseKeyedToolCallParser | Default looseKeyedToolCallParser. | | defaultMediaToTransformersInput | Default mediaToTransformersInput. | | defaultMistralToolCallParser | Default mistralToolCallParser. | | defaultNoneReasoningParser | Default noneReasoningParser. | | defaultNoneToolCallParser | Default noneToolCallParser. | | defaultPhiToolCallParser | Default phiToolCallParser. | | defaultPythonicToolCallParser | Default pythonicToolCallParser. | | defaultQwen3CoderToolCallParser | Default qwen3CoderToolCallParser. | | defaultRenderArtifactHandleBody | Default renderArtifactHandleBody. | | defaultRenderTransformersJsToolResult | Default renderTransformersJsToolResult. | | defaultResolveGenerationOptions | Default resolveGenerationOptions. | | defaultResolveReasoningParser | Default resolveReasoningParser. | | defaultResolveToolCallParser | Default resolveToolCallParser. | | defaultThinkTagReasoningParser | Default thinkTagReasoningParser. | | defaultToolsToTransformersJsTools | Default toolsToTransformersJsTools. | | gemmaChannelReasoningParser | Default makeGemmaChannelReasoningParser (orphan recovery on). | | gemmaToolCallParser | Parse Gemma E2B/E4B tool calls. Accepts the wrapped template form (< | tool_call>call:NAME{k:< | " | >v< | " | >}<tool_call | >) AND the decoder-stripped runtime form (call:NAME{k:v}, special tokens removed, scalars unquoted — the shape a real ONNX run emits), including NESTED argument blocks with curly smart quotes (the form a real E4B provide_answeremits:{answer:< | “ | >…< | ” | >,sources:[{path:…}]}), AND the PREFIX-LESS bare form NAME{…}with nocall:lead (e.g.say_i_dont_know{reason: "…"}— a real E2B/E4B runtime shape), gated onctx.toolNames. Targets the E2B/E4B form only — Gemma 3 (tool_code fences) and FunctionGemma (<start_function_call>) are out of scope (use a custom ToolCallParserFn). | | GENERATION_DEFAULTS | Deterministic-friendly defaults, identical across batteries. | | gptOssToolCallParser | Parse gpt-oss Harmony tool calls on the commentary channel: < | channel | >commentary to=functions.NAME < | constrain | >json< | message | >{…}< | call | >. The arguments payload after < | message | >is JSON, located by a string-aware balanced-brace scan so an embedded< | call | > / brace inside a string value survives. Anchored on the literal Harmony markers. | | harmonyAnalysisReasoningParser | Default makeHarmonyAnalysisReasoningParser (orphan recovery on). | | hermesToolCallParser | Parse Hermes-style <tool_call>{"name":…,"arguments":{…}}</tool_call> tags. The de-facto standard, reused by Qwen2.5/Qwen3-Instruct. Anchored on the literal tags — zero collision with bare JSON. | | llama3JsonToolCallParser | Parse bare top-level JSON tool call(s) — {"name":"x","parameters":{…}} (or "arguments"), optionally wrapped in a json … fence (a common small-model emission — verified via the real-model matrix on Qwen2.5-Coder-0.5B). The weakest signal, so it is gated hard: after un-fencing, the output must be ONLY top-level JSON object(s) AND every callee must be a real tool (ctx.toolNames). Runs after every marker-anchored family in 'auto'. | | looseKeyedToolCallParser | Parse the DEGENERATE keyed form a small instruct model emits when it ignores every structured tool-call grammar: the bare tool NAME on its own line, then one or more argname: value lines. | | mistralToolCallParser | Parse Mistral tool calls — the [TOOL_CALLS] token followed by a JSON array of { name, arguments }. Anchored on the literal [TOOL_CALLS] token. | | noneReasoningParser | A parser that never extracts anything — disables reasoning parsing entirely. | | noneToolCallParser | A parser that never extracts anything — disables tool-call parsing entirely. | | phiToolCallParser | Parse Phi-4-mini tool calls: the literal functools token followed by a JSON array of { name, arguments } objects (e.g. functools[{"name":"get_weather","arguments":{"city":"SF"}}]). | | pythonicToolCallParser | Parse pythonic tool calls — [get_weather(city='SF'), get_time()]. Requires the whole trimmed output to be the bracketed call list, so it cannot false-positive on incidental prose. Parallel calls are inherent to the format. | | qwen3CoderToolCallParser | Parse Qwen3-Coder's custom per-parameter XML — <tool_call><function=NAME><parameter=k>v</parameter> …</function></tool_call>. Values are taken as trimmed strings (the format is untyped). Anchored on the literal <function= tag, distinct from Hermes's JSON-in-<tool_call>. | | thinkTagReasoningParser | Default makeThinkTagReasoningParser (orphan recovery on). |

Functions

| Function | Description | | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | buildBundledReasoningParsers | Build the bundled family parsers honouring ReasoningParserOptions (e.g. orphan recovery). | | buildTransformersJsMessages | Build the transformers.js messages array + tools from the ADK dispatch context buckets. | | createAutoReasoningParser | Compose an 'auto' reasoning parser: run each parser in order until one returns a non-empty reasoning array; that result wins. Returns no-match if none claim the text. | | createAutoToolCallParser | Compose an 'auto' parser: run each family parser in order until one returns a non-empty calls array; that result wins. Returns no-match if none claim the text. | | createTransformersJsStreamAccumulator | Create a TransformersJsStreamAccumulator. | | emitLifecycle | Build a BatteryLifecycleReport (stamping at) and dispatch it to the firehose (BatteryLifecycleHooks.onLifecycle) AND the per-phase hook for phase. A no-op when hooks is undefined or carries no relevant callbacks. Defensive: each callback is invoked through safeInvoke, so a throwing consumer never disrupts the battery. | | instrumentGpuBuffers | Install an OPT-IN live GPU-buffer instrument by wrapping GPUDevice.prototype.createBuffer. | | isGpuOutOfMemoryError | Detect the WebGPU "out of memory / failed to allocate" family of errors from a message string. | | looksLikeSpooledArtifact | Structural (cross-realm-safe) check that a tool result is a @nhtio/adk!SpooledArtifact: it exposes the reader surface the handle pattern needs (asString + byteLength/lineCount) and a constructor carrying the toolMethods descriptor list the model is told to call. Used instead of a bare instanceof so a SpooledArtifact from another realm (worker, bundle copy) still matches. | | makeGemmaChannelReasoningParser | Parse Gemma E2B/E4B reasoning emitted on the thought channel: < | channel>thought\n…<channel | >. Targets the E2B/E4B delimited form (the transformers.js-runnable one). Reasoning is only emitted when < | think | > is injected into the system prompt. Unpaired markers are recovered by default — see ReasoningParserOptions. | | makeHarmonyAnalysisReasoningParser | Parse gpt-oss Harmony chain-of-thought on the analysis channel: < | channel | >analysis< | message | >…< | end | >. (The user-visible answer is the separate finalchannel; tool calls arecommentary — handled by the tool-call parser.) Unpaired markers are recovered by default — see ReasoningParserOptions. | | makeThinkTagReasoningParser | Parse <think>…</think> (and the <thinking>…</thinking> variant) reasoning blocks — the dominant convention, used by Qwen3, DeepSeek-R1, and most distilled reasoning models. Unpaired markers (a lone </think> or a truncated <think>) are recovered by default — see ReasoningParserOptions. | | mediaToTransformersInput | Decode an ADK @nhtio/adk!Media into a transformers.js multimodal input. | | probeGpuBudget | Probe the host WebGPU device for its memory budget (per-allocation ceilings + adapter info). | | renderArtifactHandleBody | Render the "handle" body for a spooled-artifact tool result that the producer marked inline: false: a directions-bearing text block telling the model the result was NOT inlined (to preserve context budget) and exactly which forged artifact_* tools to call — with this callId — to read it incrementally. | | renderTransformersJsToolResult | Render a @nhtio/adk!ToolCall's results into a plain-text tool message body. | | resolveGenerationOptions | Resolve the canonical ChatGenerationOptions (already merged across option layers) into a fully-defaulted ResolvedGenerationOptions. Native per-battery fallbacks are passed via nativeFallbacks and consulted ONLY when the canonical field is absent (canonical wins). The adapter then maps the resolved shape onto its runtime API. | | resolveReasoningParser | Resolve a reasoningParser option (a name, 'auto', 'none', or a custom fn) to a concrete ReasoningParserFn. | | resolveToolCallParser | Resolve a toolCallParser option (a name, 'auto', 'none', or a custom fn) to a concrete ToolCallParserFn. | | toolsToTransformersJsTools | Convert ADK @nhtio/adk!Tool / @nhtio/adk!ArtifactTool instances into the transformers.js tools array shape (OpenAI-function-shaped — what apply_chat_template expects). |

References

ChatCompletionsTool

Re-exports ChatCompletionsTool

---

defaultDescriptionToChatCompletionsJsonSchema

Re-exports defaultDescriptionToChatCompletionsJsonSchema

---

defaultFilterThoughts

Re-exports defaultFilterThoughts

---

defaultRenderChatCompletionsSystemPrompt

Re-exports defaultRenderChatCompletionsSystemPrompt

---

defaultRenderFirstPartyRetrievables

Re-exports defaultRenderFirstPartyRetrievables

---

defaultRenderMemories

Re-exports defaultRenderMemories

---

defaultRenderRetrievables

Re-exports defaultRenderRetrievables

---

defaultRenderRetrievableSafetyDirective

Re-exports defaultRenderRetrievableSafetyDirective

---

defaultRenderStandingInstructions

Re-exports defaultRenderStandingInstructions

---

defaultRenderThirdPartyPrivateRetrievables

Re-exports defaultRenderThirdPartyPrivateRetrievables

---

defaultRenderThirdPartyPublicRetrievables

Re-exports defaultRenderThirdPartyPublicRetrievables

---

defaultRenderThought

Re-exports defaultRenderThought

---

defaultRenderTrustedContent

Re-exports defaultRenderTrustedContent

---

defaultRenderUntrustedContent

Re-exports defaultRenderUntrustedContent

---

descriptionToChatCompletionsJsonSchema

Re-exports descriptionToChatCompletionsJsonSchema

---

extractReasoningFields

Re-exports extractReasoningFields

---

filterThoughts

Re-exports filterThoughts

---

renderChatCompletionsSystemPrompt

Re-exports renderChatCompletionsSystemPrompt

---

renderFirstPartyRetrievables

Re-exports renderFirstPartyRetrievables

---

renderMemories

Re-exports renderMemories

---

renderRetrievables

Re-exports renderRetrievables

---

renderRetrievableSafetyDirective

Re-exports renderRetrievableSafetyDirective

---

renderStandingInstructions

Re-exports renderStandingInstructions

---

renderThirdPartyPrivateRetrievables

Re-exports renderThirdPartyPrivateRetrievables

---

renderThirdPartyPublicRetrievables

Re-exports renderThirdPartyPublicRetrievables

---

renderThought

Re-exports renderThought

---

renderTrustedContent

Re-exports renderTrustedContent

---

renderUntrustedContent

Re-exports renderUntrustedContent