Interface: WebLLMChatCompletionsAdapterOptions

Defined in: src/batteries/llm/webllm_chat_completions/types.ts:75

Configuration options for the in-browser WebLLM Chat Completions adapter — the OpenAI options minus the network-transport fields (no HTTP is involved), plus WebLLM-specific engine controls.

Extends

• Omit<OpenAIChatCompletionsAdapterOptions, "apiKey" | "baseURL" | "headers" | "fetch" | "retry" | "requestTimeoutMs">.BatteryLifecycleHooks

Properties

Property	Type	Default value	Description	Inherited from	Defined in
audio?	{ format: "wav" | "mp3" | "flac" | "opus" | "pcm16"; voice: string; }	undefined	Parameters for audio output if requested.	OpenAIChatCompletionsAdapterOptions.audio	src/batteries/llm/openai_chat_completions/types.ts:611
audio.format	"wav" | "mp3" | "flac" | "opus" | "pcm16"	undefined	-	-	src/batteries/llm/openai_chat_completions/types.ts:611
audio.voice	string	undefined	-	-	src/batteries/llm/openai_chat_completions/types.ts:611
autoAck?	boolean	false	Whether the executor should call ctx.ack() itself when a generation completes with no tool calls (a terminal text answer). Remarks ack() is terminal and one-shot: once called, the dispatch loop exits after the current iteration. When the executor acks automatically, it seizes turn-completion control from the implementor — a dispatchOutputPipeline quality gate can never run, because the signal is already set before the output pipeline executes. This option therefore defaults to false (opt-in). With autoAck: false, a tool-call-free response leaves the context unsignalled and the executor returns; the implementor's output pipeline (or a later iteration) is responsible for calling ctx.ack() / ctx.nack(). This is the seam that makes output-side quality gates (citation enforcement, schema validation, regenerate-on-reject) possible. Set autoAck: true to restore single-shot behavior: the executor acks the moment a tool-call-free answer finishes, terminating the turn without giving the output pipeline a vote. The tool-call path is unaffected by this flag — it always withholds ack so the runner can iterate and execute the calls. Error paths always nack regardless of this flag.	OpenAIChatCompletionsAdapterOptions.autoAck	src/batteries/llm/openai_chat_completions/types.ts:605
bucketOrder?	ChatCompletionsBucketOrder	undefined	Determines order of memory and retrievable buckets in history assembly.	OpenAIChatCompletionsAdapterOptions.bucketOrder	src/batteries/llm/openai_chat_completions/types.ts:502
chatOptions?	ChatOptions | ChatOptions[]	undefined	MLC chat option(s) applied to the loaded model.	-	src/batteries/llm/webllm_chat_completions/types.ts:93
contextWindow?	number	undefined	Size of the model's token context window.	OpenAIChatCompletionsAdapterOptions.contextWindow	src/batteries/llm/openai_chat_completions/types.ts:504
createEngine?	(input: { chatOptions?: ChatOptions | ChatOptions[]; engineConfig?: MLCEngineConfig; model: string; onInitProgress?: (report: InitProgressReport) => void; }) => Promise<MLCEngineInterface>	undefined	Custom engine factory; overrides the default WebLLM engine loader.	-	src/batteries/llm/webllm_chat_completions/types.ts:95
enableThinking?	boolean	undefined	Whether to enable the model's "thinking"/reasoning mode, threaded EXPLICITLY into the request as extra_body.enable_thinking. Defaults to false — many reasoning chat templates (Qwen3, DeepSeek-R1) default thinking ON, which silently burns the token budget inside <think>. Pinned off unless you opt in. (Independent of reasoningFieldPrecedence/parsing, which only handle thinking that IS emitted.)	-	src/batteries/llm/webllm_chat_completions/types.ts:112
engine?	MLCEngineInterface	undefined	A pre-constructed engine to drive; mutually exclusive with WebLLMChatCompletionsAdapterOptions.createEngine.	-	src/batteries/llm/webllm_chat_completions/types.ts:89
engineConfig?	MLCEngineConfig	undefined	MLC engine configuration used when the adapter creates the engine itself.	-	src/batteries/llm/webllm_chat_completions/types.ts:91
extra_body?	Record<string, unknown>	undefined	Additional WebLLM/MLC request fields passed through verbatim.	-	src/batteries/llm/webllm_chat_completions/types.ts:87
forgeToolsFilter?	(forged: ToolRegistry, ctx: DispatchContext) => ToolRegistry	undefined	OPTIONAL hook to SHAPE the artifact-query tools forged from prior-turn SpooledArtifact results, before they merge into the visible tool set. Receives the merged forged registry + dispatch context; returns a (possibly narrowed) registry, applied BEFORE the merge with ctx.tools. Lets the assembler keep only the core readers on a tight window (the rest reachable via tool_catalog/call_a_tool). Default absent = identity (all forged tools) = backward-compatible. The battery stays budget-agnostic (per the CONTRIBUTING size-threshold rule) — it applies the supplied filter without measuring context; budget logic lives in the caller's filter.	OpenAIChatCompletionsAdapterOptions.forgeToolsFilter	src/batteries/llm/openai_chat_completions/types.ts:758
frequency_penalty?	number	undefined	Frequency penalty wire field to discourage repeating words.	OpenAIChatCompletionsAdapterOptions.frequency_penalty	src/batteries/llm/openai_chat_completions/types.ts:613
function_call?	| "auto" | "none" | { name: string; }	undefined	Deprecated wire field to control which function is called.	OpenAIChatCompletionsAdapterOptions.function_call	src/batteries/llm/openai_chat_completions/types.ts:615
functions?	{ description?: string; name: string; parameters?: JsonSchema; }[]	undefined	Deprecated list of functions available to the model.	OpenAIChatCompletionsAdapterOptions.functions	src/batteries/llm/openai_chat_completions/types.ts:617
helpers?	Partial<ChatCompletionsHelpers>	undefined	Optional overrides for OpenAI chat completions helpers.	OpenAIChatCompletionsAdapterOptions.helpers	src/batteries/llm/openai_chat_completions/types.ts:533
ignore_eos?	boolean	undefined	When true, the model ignores end-of-sequence tokens and keeps generating.	-	src/batteries/llm/webllm_chat_completions/types.ts:85
isWebGPUAvailable?	() => boolean	undefined	Override for the WebGPU-availability probe (defaults to a real navigator.gpu check).	-	src/batteries/llm/webllm_chat_completions/types.ts:104
localToolCallParser?	| ToolCallParserName | ToolCallParserFn	undefined	OPTIONAL fallback parser for tool calls the provider did NOT return structurally. Remarks The Chat Completions message.tool_calls array is authoritative: when the provider returns tool calls, those are used and this option is never consulted. But some models — especially small local ones served through an OpenAI-compatible endpoint — emit a tool call in a surface form the endpoint does not lift into tool_calls: <call:name{…}, a fenced ```json ```` block, <tool_code…>, or bare name\nkey: value. Those land as plain assistant contentwithtool_callsempty, silently dropping the call. This is a cross-model, cross-weight reality, not a single-endpoint quirk. Set this to a parser family name (e.g.'gemma'), 'auto'(try every bundled parser in priority order), or a custom ToolCallParserFn to recover such calls fromcontentONLY when the provider returned none. Recovered calls execute exactly like native ones. Default absent = disabled = today's native-only behaviour (fully backward-compatible). Mirrors the on-device batteries'toolCallParser, which parse from text unconditionally because those runtimes never return structured calls.	OpenAIChatCompletionsAdapterOptions.localToolCallParser	src/batteries/llm/openai_chat_completions/types.ts:748
logit_bias?	Record<string, number>	undefined	Bias logits to control token generation likelihood.	OpenAIChatCompletionsAdapterOptions.logit_bias	src/batteries/llm/openai_chat_completions/types.ts:619
logprobs?	boolean	undefined	Request log probabilities for generated tokens.	OpenAIChatCompletionsAdapterOptions.logprobs	src/batteries/llm/openai_chat_completions/types.ts:621
max_completion_tokens?	number	undefined	Hard limit on token count for model reasoning/completion.	OpenAIChatCompletionsAdapterOptions.max_completion_tokens	src/batteries/llm/openai_chat_completions/types.ts:623
max_tokens?	number	undefined	Maximum number of generated tokens.	OpenAIChatCompletionsAdapterOptions.max_tokens	src/batteries/llm/openai_chat_completions/types.ts:625
metadata?	Record<string, string>	undefined	Metadata key-value pairs forwarded to the provider.	OpenAIChatCompletionsAdapterOptions.metadata	src/batteries/llm/openai_chat_completions/types.ts:627
modalities?	("text" | "audio")[]	undefined	Desired modalities for model output, such as text and audio.	OpenAIChatCompletionsAdapterOptions.modalities	src/batteries/llm/openai_chat_completions/types.ts:629
model	string	undefined	Name of the model to use for completion.	OpenAIChatCompletionsAdapterOptions.model	src/batteries/llm/openai_chat_completions/types.ts:609
n?	number	undefined	Number of completions to generate for each request.	OpenAIChatCompletionsAdapterOptions.n	src/batteries/llm/openai_chat_completions/types.ts:631
onCompiling?	BatteryLifecycleCallback	undefined	Engine/graph/shader compilation after download, before the first token. A COARSE marker: the on-device runtimes (LiteRT Engine.create, transformers.js from_pretrained) expose the boundary — download done, opaque WebGPU/WASM graph build about to run — but NOT a progress stream, so progress is usually absent. Often the slowest part of a cold start; without this it was invisible.	BatteryLifecycleHooks.onCompiling	src/batteries/llm/chat_common/lifecycle.ts:89
onComplete?	BatteryLifecycleCallback	undefined	After the turn's output is parsed + persisted, before ack (fires per turn).	BatteryLifecycleHooks.onComplete	src/batteries/llm/chat_common/lifecycle.ts:95
onError?	BatteryLifecycleCallback	undefined	A load or generation failure (paired with nack).	BatteryLifecycleHooks.onError	src/batteries/llm/chat_common/lifecycle.ts:97
onGenerating?	BatteryLifecycleCallback	undefined	Immediately before the provider generate call (fires per turn).	BatteryLifecycleHooks.onGenerating	src/batteries/llm/chat_common/lifecycle.ts:93
onInitProgress?	(report: InitProgressReport) => void	undefined	Callback invoked with model-load progress reports.	-	src/batteries/llm/webllm_chat_completions/types.ts:102
onLifecycle?	BatteryLifecycleCallback	undefined	Fires on EVERY phase transition (the firehose).	BatteryLifecycleHooks.onLifecycle	src/batteries/llm/chat_common/lifecycle.ts:80
onLoading?	BatteryLifecycleCallback	undefined	Weights/runtime loading — may fire repeatedly with progress as the provider reports it.	BatteryLifecycleHooks.onLoading	src/batteries/llm/chat_common/lifecycle.ts:82
onPromptAssembled?	PromptAssembledObserverFn	undefined	Observe the fully-assembled request this battery is about to POST TO the provider — fired once per terminal generation, the instant the body is built and BEFORE the fetch, with the wire messages, tools, and the complete requestBody. The mirror of onRawGeneration. Purely observational (return value ignored, errors swallowed). Default absent. An ADK-control key — stripped from the wire request body, never sent to the provider. The request is handed back AS-IS — no redaction — so treat it as potentially sensitive (it may contain auth material that rode the body) if you persist it. See PromptAssembledObserverFn.	OpenAIChatCompletionsAdapterOptions.onPromptAssembled	src/batteries/llm/openai_chat_completions/types.ts:729
onRawGeneration?	RawGenerationObserverFn	undefined	Observe the model's RAW response for each completed generation — fired once per terminal generation, after the provider's reply is parsed but before the result is persisted, with the returned assistant content (rawText), the residual cleanedText, and the extracted reasoning / toolCalls. Purely observational (return value ignored, errors swallowed). Default absent. An ADK-control key — stripped from the wire request body, never sent to the provider. See RawGenerationObserverFn.	OpenAIChatCompletionsAdapterOptions.onRawGeneration	src/batteries/llm/openai_chat_completions/types.ts:719
onReady?	BatteryLifecycleCallback	undefined	Engine/pipeline resolved and cached, before the first generation.	BatteryLifecycleHooks.onReady	src/batteries/llm/chat_common/lifecycle.ts:91
parallel_tool_calls?	boolean	undefined	Allow the model to emit multiple tool calls in one turn.	OpenAIChatCompletionsAdapterOptions.parallel_tool_calls	src/batteries/llm/openai_chat_completions/types.ts:633
prediction?	{ content: | string | { text: string; type: "text"; }[]; type: "content"; }	undefined	Prediction helper to accelerate latency of known content.	OpenAIChatCompletionsAdapterOptions.prediction	src/batteries/llm/openai_chat_completions/types.ts:635
prediction.content	| string | { text: string; type: "text"; }[]	undefined	-	-	src/batteries/llm/openai_chat_completions/types.ts:637
prediction.type	"content"	undefined	-	-	src/batteries/llm/openai_chat_completions/types.ts:636
presence_penalty?	number	undefined	Presence penalty wire field to encourage new topics.	OpenAIChatCompletionsAdapterOptions.presence_penalty	src/batteries/llm/openai_chat_completions/types.ts:640
prompt_cache_key?	string	undefined	Vendor cache key for caching system prompts.	OpenAIChatCompletionsAdapterOptions.prompt_cache_key	src/batteries/llm/openai_chat_completions/types.ts:642
prompt_cache_retention?	"in_memory" | "24h"	undefined	Cache retention strategy for cached system prompts.	OpenAIChatCompletionsAdapterOptions.prompt_cache_retention	src/batteries/llm/openai_chat_completions/types.ts:644
reasoning_effort?	"none" | "low" | "high" | "minimal" | "medium"	undefined	Target reasoning depth/effort for reasoning models.	OpenAIChatCompletionsAdapterOptions.reasoning_effort	src/batteries/llm/openai_chat_completions/types.ts:646
reasoningFieldPrecedence?	ReasoningFieldPrecedence	['reasoning', 'reasoning_content']	Ordered precedence of the wire fields the adapter reads for model reasoning/thinking output. Remarks Reasoning is not part of OpenAI's official Chat Completions spec, so OpenAI-compatible providers disagree on the field name: Ollama's /v1 and current vLLM emit reasoning, while legacy vLLM (≤0.8) and the DeepSeek API emit reasoning_content. The adapter reads every field in this list that is present on the response. Precedence governs two things. When more than one listed field is present with identical content (or only one is present), the adapter emits a single thought attributed to the highest-precedence field. When listed fields are present with divergent content, each surfaces as its own thought (ordered by precedence) rather than silently dropping one — a thought stream is the wrong place to lose data.	OpenAIChatCompletionsAdapterOptions.reasoningFieldPrecedence	src/batteries/llm/openai_chat_completions/types.ts:531
repetition_penalty?	number	undefined	Penalty applied to repeated tokens (WebLLM/MLC sampling parameter).	-	src/batteries/llm/webllm_chat_completions/types.ts:83
replayCompatibility?	readonly string[]	undefined	List of replay labels supported by the assistant.	OpenAIChatCompletionsAdapterOptions.replayCompatibility	src/batteries/llm/openai_chat_completions/types.ts:512
response_format?	| { type: "text"; } | { type: "json_object"; } | { json_schema: { description?: string; name: string; schema: JsonSchema; strict?: boolean; }; type: "json_schema"; }	undefined	Enforces a specific output format, e.g. JSON schema.	OpenAIChatCompletionsAdapterOptions.response_format	src/batteries/llm/openai_chat_completions/types.ts:648
safety_identifier?	string	undefined	Unique safety system identifier or configuration ID.	OpenAIChatCompletionsAdapterOptions.safety_identifier	src/batteries/llm/openai_chat_completions/types.ts:661
seed?	number	undefined	Deterministic random seed for generation.	OpenAIChatCompletionsAdapterOptions.seed	src/batteries/llm/openai_chat_completions/types.ts:663
selfIdentity?	string	undefined	Unique identity label for the assistant instance.	OpenAIChatCompletionsAdapterOptions.selfIdentity	src/batteries/llm/openai_chat_completions/types.ts:506
service_tier?	"default" | "auto" | "flex" | "priority" | "scale"	undefined	Service reliability tier for processing the request.	OpenAIChatCompletionsAdapterOptions.service_tier	src/batteries/llm/openai_chat_completions/types.ts:665
spoolStore?	SpoolStore	a new InMemorySpoolStore per dispatch	Backing store for string / Uint8Array tool returns. Tool output bytes are written under the tool call's id; the resulting @nhtio/adk!SpooledArtifact (or the tool's configured subclass) is the model-visible handle for the rest of the turn. Remarks Defaults to a fresh, ephemeral per-dispatch @nhtio/adk/batteries/storage/in_memory!InMemorySpoolStore. Inject an @nhtio/adk/batteries/storage/opfs!OpfsSpoolStore or a Flydrive-backed store to persist artifacts to durable storage (and to stream large/binary tool output to disk rather than buffering it in memory). Lifetime / namespacing: the default store is per-dispatch, so tool-call ids only need to be unique within a dispatch. An injected durable store persists across turns and dispatches, so the tool-call ids used as keys must be globally unique for that store (or the store must apply its own keyPrefix); the adapter does not namespace keys for you, and it does not delete entries — lifetime and cleanup of an injected store are the consumer's responsibility.	OpenAIChatCompletionsAdapterOptions.spoolStore	src/batteries/llm/openai_chat_completions/types.ts:554
stop?	string | string[]	undefined	Custom stop sequence strings.	OpenAIChatCompletionsAdapterOptions.stop	src/batteries/llm/openai_chat_completions/types.ts:667
store?	boolean	undefined	Request the provider to store the completed trace.	OpenAIChatCompletionsAdapterOptions.store	src/batteries/llm/openai_chat_completions/types.ts:669
stream?	boolean	undefined	Whether to stream the completion response chunk by chunk.	OpenAIChatCompletionsAdapterOptions.stream	src/batteries/llm/openai_chat_completions/types.ts:492
stream_options?	{ include_obfuscation?: boolean; include_usage?: boolean; }	undefined	Configuration options for response streaming.	OpenAIChatCompletionsAdapterOptions.stream_options	src/batteries/llm/openai_chat_completions/types.ts:671
stream_options.include_obfuscation?	boolean	undefined	-	-	src/batteries/llm/openai_chat_completions/types.ts:671
stream_options.include_usage?	boolean	undefined	-	-	src/batteries/llm/openai_chat_completions/types.ts:671
streamIdleTimeoutMs?	number	undefined	Idle timeout in milliseconds for the stream before aborting.	OpenAIChatCompletionsAdapterOptions.streamIdleTimeoutMs	src/batteries/llm/openai_chat_completions/types.ts:494
strictToolChoice?	boolean	false	When tool_choice (or the allowed_tools variant) forces the model onto a specific tool name, and that name resolves to an ephemeral, forged artifact-query tool (one produced by <Subclass>.forgeTools(ctx) — i.e. tool.ephemeral === true), this flag controls how the adapter reacts: - false (default): emit a single helpers.log.warn({ kind: 'tool-choice-forged-artifact', ... }) record and continue. Forging an artifact-query tool by name is almost always a misconfiguration — the tool may not exist in the next iteration once the artifact ages out — but the call still goes through. - true: hard-fail with E_INVALID_OPENAI_CHAT_COMPLETIONS_OPTIONS. Use this in production deployments where forcing a forged tool indicates a real bug.	OpenAIChatCompletionsAdapterOptions.strictToolChoice	src/batteries/llm/openai_chat_completions/types.ts:570
temperature?	number	undefined	Sampling temperature control.	OpenAIChatCompletionsAdapterOptions.temperature	src/batteries/llm/openai_chat_completions/types.ts:673
thoughtSurfacing?	"all-self" | "latest-self" | "all"	undefined	Determines which thoughts are surfaced back to the model.	OpenAIChatCompletionsAdapterOptions.thoughtSurfacing	src/batteries/llm/openai_chat_completions/types.ts:508
tokenEncoding?	| "gpt2" | "r50k_base" | "p50k_base" | "p50k_edit" | "cl100k_base" | "o200k_base" | "gemini" | "gemma" | "llama2" | "claude" | null	undefined	Tokenizer encoding configuration for token counting.	OpenAIChatCompletionsAdapterOptions.tokenEncoding	src/batteries/llm/openai_chat_completions/types.ts:510
tool_choice?	| "required" | "auto" | "none" | { function: { name: string; }; type: "function"; } | { custom: { name: string; }; type: "custom"; } | { allowed_tools: { mode: "required" | "auto"; tools: ( | { function: { name: string; }; type: "function"; } | { custom: { name: string; }; type: "custom"; })[]; }; type: "allowed_tools"; }	undefined	Enforce or disable tool execution selection.	OpenAIChatCompletionsAdapterOptions.tool_choice	src/batteries/llm/openai_chat_completions/types.ts:675
top_logprobs?	number	undefined	Top log probability tokens limit.	OpenAIChatCompletionsAdapterOptions.top_logprobs	src/batteries/llm/openai_chat_completions/types.ts:692
top_p?	number	undefined	Nucleus sampling probability threshold.	OpenAIChatCompletionsAdapterOptions.top_p	src/batteries/llm/openai_chat_completions/types.ts:694
unsupportedMediaPolicy?	UnsupportedMediaPolicy	'throw'	Policy for how the adapter handles a @nhtio/adk!Media instance whose modality the OpenAI Chat Completions wire format does not natively support (today: video). See UnsupportedMediaPolicy.	OpenAIChatCompletionsAdapterOptions.unsupportedMediaPolicy	src/batteries/llm/openai_chat_completions/types.ts:579
user?	string	undefined	End-user identifier for abuse monitoring.	OpenAIChatCompletionsAdapterOptions.user	src/batteries/llm/openai_chat_completions/types.ts:696
verbosity?	"low" | "high" | "medium"	undefined	Diagnostics verbosity level.	OpenAIChatCompletionsAdapterOptions.verbosity	src/batteries/llm/openai_chat_completions/types.ts:698
web_search_options?	{ search_context_size?: "low" | "high" | "medium"; user_location?: { approximate: { city?: string; country?: string; region?: string; timezone?: string; }; type: "approximate"; }; }	undefined	Configuration for built-in web search.	OpenAIChatCompletionsAdapterOptions.web_search_options	src/batteries/llm/openai_chat_completions/types.ts:700
web_search_options.search_context_size?	"low" | "high" | "medium"	undefined	-	-	src/batteries/llm/openai_chat_completions/types.ts:701
web_search_options.user_location?	{ approximate: { city?: string; country?: string; region?: string; timezone?: string; }; type: "approximate"; }	undefined	-	-	src/batteries/llm/openai_chat_completions/types.ts:702
web_search_options.user_location.approximate	{ city?: string; country?: string; region?: string; timezone?: string; }	undefined	-	-	src/batteries/llm/openai_chat_completions/types.ts:704
web_search_options.user_location.approximate.city?	string	undefined	-	-	src/batteries/llm/openai_chat_completions/types.ts:705
web_search_options.user_location.approximate.country?	string	undefined	-	-	src/batteries/llm/openai_chat_completions/types.ts:706
web_search_options.user_location.approximate.region?	string	undefined	-	-	src/batteries/llm/openai_chat_completions/types.ts:707
web_search_options.user_location.approximate.timezone?	string	undefined	-	-	src/batteries/llm/openai_chat_completions/types.ts:708
web_search_options.user_location.type	"approximate"	undefined	-	-	src/batteries/llm/openai_chat_completions/types.ts:703