@mlx-node/core 0.0.5 → 0.0.7

package/index.d.cts

@@ -26,7 +26,12 @@ export declare class BatchGenerationResult {
   get groupSize(): number;
 }
 
-/** Handle returned by `chat_stream()` to control an in-progress streaming generation. */
+/**
+ * Handle returned by the streaming chat-session entry points
+ * (`chat_stream_session_start`, `chat_stream_session_continue`,
+ * `chat_stream_session_continue_tool`) to control an in-progress
+ * streaming generation.
+ */
 export declare class ChatStreamHandle {
   cancel(): void;
 }
@@ -103,6 +108,115 @@ export declare class DocUnwarpModel {
   unwarp(imageData: Uint8Array): UnwarpResult;
 }
 
+/**
+ * Gemma 4 dense language model.
+ *
+ * Supports E2B (2.3B), E4B (4.5B), and 31B variants.
+ * Features: hybrid attention (sliding + global), GeGLU MLP, logit softcapping,
+ * embedding scaling, and optional per-layer embeddings.
+ *
+ * All model state lives on a dedicated OS thread. NAPI methods dispatch
+ * commands via channels and await responses.
+ */
+export declare class Gemma4Model {
+  constructor(config: Gemma4Config);
+  modelId(): number;
+  /** Load a Gemma4 model from a directory. */
+  static load(modelPath: string): Promise<Gemma4Model>;
+  /**
+   * Reset all caches and clear cached token history. Exposed so
+   * tests and session-management code can start from a known clean
+   * state between turns.
+   *
+   * Synchronous on the NAPI boundary — every other `SessionCapableModel`
+   * exposes `resetCaches(): void` and the `ChatSession<M>` cross-model
+   * wrapper calls this inline during the image-change restart and
+   * `reset()` flows. Running it as an async NAPI method would break
+   * that contract and silently drop reset failures because
+   * `ChatSession.reset()` and the session-start restart path invoke
+   * `model.resetCaches()` without awaiting.
+   */
+  resetCaches(): void;
+  /**
+   * Start a new chat session.
+   *
+   * Runs the full jinja chat template once, decodes until Gemma4's
+   * `<turn|>` delimiter, and leaves the KV caches on a clean turn
+   * boundary so subsequent `chatSessionContinue` /
+   * `chatSessionContinueTool` calls can append a raw delta on top
+   * without re-rendering the chat template.
+   */
+  chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Continue an existing chat session with a new user message.
+   *
+   * Appends a raw Gemma4 user/model delta to the session's cached KV
+   * state, then decodes the model reply. Stops on `<turn|>` so the
+   * cache remains on a clean turn boundary for the next turn.
+   *
+   * Requires a live session started via `chatSessionStart`. Errors
+   * if the session is empty, carries image state, or if
+   * `config.reuse_cache` is explicitly set to `false`.
+   *
+   * `images` is an opt-in guard parameter: when non-empty the native
+   * side returns an error whose message begins with
+   * `IMAGE_CHANGE_REQUIRES_SESSION_RESTART:` so the TypeScript
+   * `ChatSession` layer can catch the prefix and route image-changes
+   * back through a fresh `chatSessionStart` uniformly across all
+   * model backends.
+   */
+  chatSessionContinue(
+    userMessage: string,
+    images: Uint8Array[] | null | undefined,
+    config: ChatConfig | null | undefined,
+  ): Promise<ChatResult>;
+  /**
+   * Continue an existing chat session with a tool-result turn.
+   *
+   * Builds a Gemma4-format tool delta
+   * (`
+  <|turn>tool
+  {content}<turn|>
+  <|turn>model
+  `) from
+   * `content` and prefills it on top of the live session caches,
+   * then decodes the model reply. Stops on `<turn|>` so the cache
+   * stays on a clean turn boundary for the next turn.
+   *
+   * The `tool_call_id` is currently dropped by the wire format —
+   * Gemma4's chat template identifies tool responses positionally,
+   * not via an explicit id. Callers may still log it for their own
+   * bookkeeping.
+   *
+   * Requires a live session started via `chatSessionStart`.
+   */
+  chatSessionContinueTool(
+    toolCallId: string,
+    content: string,
+    config?: ChatConfig | undefined | null,
+  ): Promise<ChatResult>;
+  /** Streaming variant of `chatSessionStart`. */
+  chatStreamSessionStart(
+    messages: ChatMessage[],
+    config: ChatConfig | null | undefined,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+  /** Streaming variant of `chatSessionContinue`. */
+  chatStreamSessionContinue(
+    userMessage: string,
+    images: Uint8Array[] | null | undefined,
+    config: ChatConfig | null | undefined,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+  /** Streaming variant of `chatSessionContinueTool`. */
+  chatStreamSessionContinueTool(
+    toolCallId: string,
+    content: string,
+    config: ChatConfig | null | undefined,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+}
+
 /** Result from text generation with detailed metadata */
 export declare class GenerationResult {
   /** Get the decoded text */
@@ -120,14 +234,15 @@ export declare class GenerationResult {
 /**
  * GRPO Training Engine
  *
- * Complete training engine that runs entirely in Rust.
+ * Thin coordinator that routes all MLX operations through the model thread.
+ * No MxArrays or model state live here — only plain data crosses the boundary.
  */
 export declare class GrpoTrainingEngine {
   /**
    * Create a new training engine from a Qwen3 model
    *
    * # Arguments
-   * * `model` - The Qwen3 model to train (will be cloned internally)
+   * * `model` - The Qwen3 model (must be loaded via load())
    * * `config` - Engine configuration
    */
   constructor(model: Qwen3Model, config: GrpoEngineConfig);
@@ -143,8 +258,8 @@ export declare class GrpoTrainingEngine {
    * This method performs the complete training cycle:
    * 1. Generate completions for each prompt (G times per prompt)
    * 2. Use provided rewards to compute advantages
-   * 3. Compute GRPO loss and gradients
-   * 4. Apply gradients (respecting accumulation steps)
+   * 3. Compute GRPO loss and gradients (on model thread)
+   * 4. Apply gradients (respecting accumulation steps, on model thread)
    *
    * # Arguments
    * * `prompts` - Array of chat conversations to use as prompts
@@ -171,13 +286,14 @@ export declare class GrpoTrainingEngine {
   /**
    * Run a training step with pre-generated completions
    *
-   * This method performs training using pre-generated completions,
-   * eliminating the double-generation issue.
+   * Uses the cached MxArrays from the most recent generate_batch_for_training
+   * call on the model thread. The generation_result parameter is used only for
+   * validation (the actual MxArrays are cached on the model thread).
    *
    * # Arguments
    * * `prompts` - Array of chat conversations to use as prompts
    * * `rewards` - Reward values for each completion (num_prompts * group_size)
-   * * `generation_result` - Pre-generated completion data from generate_batch_for_training
+   * * `generation_result` - Pre-generated completion data (used for validation)
    *
    * # Returns
    * * Training step metrics
@@ -190,8 +306,8 @@ export declare class GrpoTrainingEngine {
   /**
    * Unified training step with JS reward callback and optional output recording
    *
-   * Same as `train_step_auto` but optionally captures the full RewardOutput data
-   * for persistence to an output store database.
+   * Generates completions via the model thread, calls the JS reward function
+   * with plain data, then dispatches the training step to the model thread.
    *
    * # Arguments
    * * `prompts` - Array of chat conversations to use as prompts
@@ -222,7 +338,16 @@ export declare class GrpoTrainingEngine {
   startEpoch(): void;
   /** End the current epoch and get metrics */
   endEpoch(epochTimeSecs: number): EngineEpochMetrics;
-  /** Reset the engine for a fresh training run */
+  /**
+   * Reset the engine for a fresh training run.
+   *
+   * This is a TERMINAL operation on this handle. It drops the training
+   * state (optimizer, step counter) on the model thread so a fresh
+   * `GRPOTrainingEngine` can be constructed on the same model, and marks
+   * THIS handle as invalidated. Any subsequent dispatch-requiring method
+   * on this handle returns an error — callers must construct a new
+   * engine to continue training.
+   */
   reset(): void;
   /** Check if reward registry has any rewards registered */
   get hasBuiltinRewards(): boolean;
@@ -242,25 +367,199 @@ export declare class GrpoTrainingEngine {
   /**
    * Save optimizer state (moment tensors + step) to a SafeTensors file.
    *
-   * The step counter is stored in the `__metadata__` field.
-   * Each parameter's first moment (m) and second moment (v) are stored as
-   * `{param_name}.m` and `{param_name}.v` tensors.
-   *
-   * No-op if the engine uses SGD (no optimizer state to save).
+   * Routes through the model thread so AdamW moments and step counter
+   * survive across checkpoint/resume. No-op if the engine uses SGD
+   * (no optimizer to save) or before the first optimizer update has
+   * populated any moment tensors.
    */
-  saveOptimizerState(path: string): void;
+  saveOptimizerState(path: string): Promise<void>;
   /**
    * Load optimizer state (moment tensors + step) from a SafeTensors file.
    *
-   * Restores the step counter from metadata and sets first/second moment
-   * tensors for each parameter found in the file.
-   *
-   * No-op if the engine uses SGD (no optimizer to restore).
+   * Routes through the model thread. No-op if the engine uses SGD.
    */
-  loadOptimizerState(path: string): void;
+  loadOptimizerState(path: string): Promise<void>;
 }
 export type GRPOTrainingEngine = GrpoTrainingEngine;
 
+/**
+ * Harrier embedding model (Qwen3 backbone for text embeddings).
+ *
+ * Uses last-token pooling and L2 normalization to produce fixed-size
+ * embedding vectors from variable-length text inputs.
+ */
+export declare class HarrierModel {
+  constructor(config: HarrierConfig);
+  /**
+   * Forward pass returning hidden states (no lm_head projection).
+   *
+   * # Arguments
+   * * `input_ids` - Token IDs, shape: [batch_size, seq_len]
+   *
+   * # Returns
+   * * Hidden states, shape: [batch_size, seq_len, hidden_size]
+   */
+  forward(inputIds: MxArray): MxArray;
+  /**
+   * Encode a single text into a normalized embedding vector.
+   *
+   * Tokenizes the text, runs the forward pass, applies last-token pooling,
+   * and L2-normalizes the result. Truncates to `max_position_embeddings`.
+   *
+   * # Arguments
+   * * `text` - Input text to encode
+   * * `instruction` - Optional task instruction prefix or preset name
+   *   (e.g. `"web_search_query"` resolves to the full Harrier prompt).
+   *   Pass `null` for documents/passages that need no instruction.
+   *
+   * # Returns
+   * * Embedding vector, shape: [hidden_size]
+   */
+  encode(text: string, instruction?: string | undefined | null): Promise<MxArray>;
+  /**
+   * Encode a batch of texts into normalized embedding vectors.
+   *
+   * Each text is independently tokenized and encoded (no padding needed
+   * since each goes through its own forward pass). Truncates each text
+   * to `max_position_embeddings`.
+   *
+   * # Arguments
+   * * `texts` - Input texts to encode
+   * * `instruction` - Optional task instruction prefix or preset name
+   *   (e.g. `"web_search_query"` resolves to the full Harrier prompt).
+   *   Pass `null` for documents/passages that need no instruction.
+   *
+   * # Returns
+   * * Embedding matrix, shape: [batch_size, hidden_size]
+   */
+  encodeBatch(texts: Array<string>, instruction?: string | undefined | null): Promise<MxArray>;
+  /** Get the model configuration. */
+  getConfig(): HarrierConfig;
+  /**
+   * Get available prompt presets loaded from config_sentence_transformers.json.
+   *
+   * Returns a map of task name -> full instruction prefix.
+   * Pass a task name to `encode()`/`encodeBatch()` as the `instruction` parameter
+   * to use a preset instead of a raw prefix string.
+   */
+  getPrompts(): Record<string, string>;
+  /** Get the total number of model parameters. */
+  numParameters(): number;
+  /**
+   * Load a Harrier embedding model from a directory.
+   *
+   * Expects the standard HuggingFace layout:
+   * - config.json (model configuration)
+   * - model.safetensors or weights.safetensors (weights)
+   * - tokenizer.json (tokenizer)
+   * - config_sentence_transformers.json (optional, prompt presets)
+   */
+  static load(modelPath: string): Promise<HarrierModel>;
+}
+
+/**
+ * LFM2 language model (LFM2.5-1.2B-Thinking).
+ *
+ * Hybrid conv+attention architecture from Liquid AI. 16 layers total:
+ * 10 conv layers + 6 full_attention layers. Features gated short
+ * convolutions for local processing and standard attention for global context.
+ *
+ * All model state lives on a dedicated OS thread. NAPI methods dispatch
+ * commands via channels and await responses.
+ */
+export declare class Lfm2Model {
+  /** Load an LFM2 model from a directory containing safetensors and config.json. */
+  static load(modelPath: string): Promise<Lfm2Model>;
+  /**
+   * Reset all caches and clear cached token history. Exposed so
+   * tests and session-management code can start from a known clean
+   * state between turns.
+   */
+  resetCaches(): void;
+  /**
+   * Start a new chat session.
+   *
+   * Runs the full jinja chat template once, decodes until
+   * `<|im_end|>`, and leaves the KV/conv caches on a clean ChatML
+   * boundary so subsequent `chatSessionContinue` /
+   * `chatSessionContinueTool` calls can append a raw delta on top
+   * without re-rendering the chat template.
+   *
+   * Requires `config.reuse_cache` to be enabled (the default).
+   */
+  chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Continue an existing chat session with a new user message.
+   *
+   * Appends a raw ChatML user/assistant delta to the session's
+   * cached KV/conv state, then decodes the assistant reply. Stops
+   * on `<|im_end|>` so the cache remains on a clean boundary for
+   * the next turn.
+   *
+   * Requires a live session started via `chatSessionStart`. Errors
+   * if the session is empty, carries image state, or if
+   * `config.reuse_cache` is explicitly set to `false`.
+   *
+   * LFM2 is text-only; `images` is an opt-in guard parameter: when
+   * non-empty the native side returns an error whose message begins
+   * with `IMAGE_CHANGE_REQUIRES_SESSION_RESTART:` so the TypeScript
+   * `ChatSession` layer can catch the prefix and route
+   * image-changes back through a fresh `chatSessionStart`
+   * uniformly across all model backends.
+   */
+  chatSessionContinue(
+    userMessage: string,
+    images: Uint8Array[] | null | undefined,
+    config: ChatConfig | null | undefined,
+  ): Promise<ChatResult>;
+  /**
+   * Continue an existing chat session with a tool-result turn.
+   *
+   * Builds an LFM2-format tool delta (`<|im_start|>tool
+{content}
+ * <|im_end|>`) from `content` and prefills it on top of the live
+ * session caches, then decodes the assistant reply. Stops on
+ * `<|im_end|>` so the cache stays on a clean boundary for the
+ * next turn.
+ *
+ * The `tool_call_id` is currently dropped by the wire format —
+ * LFM2's chat template identifies tool responses positionally,
+ * not via an explicit id. Callers may still log it for their own
+ * bookkeeping.
+ *
+ * Requires a live session started via `chatSessionStart`.
+ */
+  chatSessionContinueTool(
+    toolCallId: string,
+    content: string,
+    config?: ChatConfig | undefined | null,
+  ): Promise<ChatResult>;
+  /** Streaming variant of `chatSessionStart`. */
+  chatStreamSessionStart(
+    messages: ChatMessage[],
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+  /** Streaming variant of `chatSessionContinue`. */
+  chatStreamSessionContinue(
+    userMessage: string,
+    images: Uint8Array[] | null | undefined,
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+  /** Streaming variant of `chatSessionContinueTool`. */
+  chatStreamSessionContinueTool(
+    toolCallId: string,
+    content: string,
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+  /** Get the model configuration. */
+  getConfig(): Lfm2Config;
+  /** Estimated number of model parameters. */
+  numParameters(): number;
+}
+
 export declare class MxArray {
   equal(other: MxArray): MxArray;
   notEqual(other: MxArray): MxArray;
@@ -399,6 +698,8 @@ export declare class MxArray {
   sinh(): MxArray;
   cosh(): MxArray;
   tanh(): MxArray;
+  /** Error function: erf(x) = (2/sqrt(pi)) * integral(0..x, exp(-t^2) dt) */
+  erf(): MxArray;
   floor(): MxArray;
   ceil(): MxArray;
   round(): MxArray;
@@ -640,13 +941,13 @@ export declare class OutputStore {
 }
 
 /**
- * Opaque handle to KV cache state from a previous chat() call.
+ * Opaque handle to KV cache state from a chat-session turn.
  *
- * Pass this back to the next chat() call via `model.setCache(cache)`
- * to enable incremental prefill — only new tokens since the last turn
- * are processed, avoiding redundant computation.
+ * Pass this back via `model.setCache(cache)` before the next
+ * chat-session call to enable incremental prefill — only new tokens
+ * since the last turn are processed, avoiding redundant computation.
  *
- * Created internally by the model when `reuseCache: true` (default).
+ * Created internally by the model during chat-session turns.
  * Extract via `model.takeCache()`, restore via `model.setCache(cache)`.
  */
 export declare class PromptCache {
@@ -658,16 +959,132 @@ export declare class PromptCache {
   dispose(): void;
 }
 
+/**
+ * Qianfan-OCR Vision-Language Model (InternVL architecture).
+ *
+ * Combines InternViT vision encoder, MLP bridge with pixel shuffle,
+ * and Qwen3 language model for OCR and document understanding.
+ *
+ * All inference state lives on a dedicated OS thread. NAPI methods
+ * dispatch commands via channels and await responses.
+ */
+export declare class QianfanOCRModel {
+  /**
+   * Create a new QianfanOCRModel from config (uninitialized, no weights).
+   *
+   * This constructor path does not spawn a model thread — the returned
+   * instance is only useful for config inspection. Call
+   * [`QianfanOCRModel::load`] to actually run inference.
+   */
+  constructor(config: QianfanOcrConfig);
+  /** Returns true if weights have been loaded via `load()`. */
+  get isInitialized(): boolean;
+  /**
+   * Load a QianfanOCRModel from a directory.
+   *
+   * Reads config.json, loads SafeTensors weights (single or sharded),
+   * builds vision encoder, bridge, and language model, and loads tokenizer.
+   * All heavy work runs on the dedicated model thread.
+   */
+  static load(modelPath: string): Promise<QianfanOCRModel>;
+  /**
+   * Generate text tokens given pre-tokenized input.
+   *
+   * Lower-level API — prefer the session chat methods
+   * (`chatSessionStart` / `chatSessionContinue` and their streaming
+   * variants) for typical usage.
+   */
+  generate(
+    inputIds: MxArray,
+    maxNewTokens?: number | undefined | null,
+    temperature?: number | undefined | null,
+  ): Promise<Array<number>>;
+  /** Reset KV caches and token history. */
+  resetCaches(): void;
+  /**
+   * Start a new chat session.
+   *
+   * Runs the full chat template once, decodes until `<|im_end|>`,
+   * and leaves the KV caches on a clean turn boundary so subsequent
+   * `chatSessionContinue` / `chatSessionContinueTool` calls can
+   * append a raw ChatML delta on top without re-rendering the chat
+   * template.
+   *
+   * Qianfan-OCR is always a VLM (InternViT + Qwen3 language model), so
+   * this entry point accepts images in `messages` without the text-only
+   * fast-fail used by plain language models.
+   */
+  chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Continue an existing chat session with a new user message.
+   *
+   * Appends a raw ChatML user/assistant delta to the session's cached
+   * KV state, then decodes the model reply. Stops on `<|im_end|>` so
+   * the cache remains on a clean turn boundary for the next turn.
+   *
+   * Requires a live session started via `chatSessionStart`. Errors
+   * if the session is empty or if `config.reuse_cache` is
+   * explicitly set to `false`.
+   *
+   * `images` is an opt-in guard parameter: when non-empty the native
+   * side returns an error whose message begins with
+   * `IMAGE_CHANGE_REQUIRES_SESSION_RESTART:` so the TypeScript
+   * `ChatSession` layer can catch the prefix and route image-changes
+   * back through a fresh `chatSessionStart` uniformly across all
+   * model backends. Qianfan-OCR is a VLM but the continue path cannot
+   * splice new vision features into a live KV cache — image changes
+   * always require a fresh session start.
+   */
+  chatSessionContinue(
+    userMessage: string,
+    images: Uint8Array[] | null | undefined,
+    config: ChatConfig | null | undefined,
+  ): Promise<ChatResult>;
+  /**
+   * Continue an existing chat session with a tool-result turn.
+   *
+   * Builds a ChatML `<tool_response>` delta from `tool_call_id` and
+   * `content` and prefills it on top of the live session caches, then
+   * decodes the model reply. Stops on `<|im_end|>` so the cache stays
+   * on a clean turn boundary for the next turn.
+   *
+   * Requires a live session started via `chatSessionStart`.
+   */
+  chatSessionContinueTool(
+    toolCallId: string,
+    content: string,
+    config?: ChatConfig | undefined | null,
+  ): Promise<ChatResult>;
+  /** Streaming variant of `chatSessionStart`. */
+  chatStreamSessionStart(
+    messages: ChatMessage[],
+    config: ChatConfig | null | undefined,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+  /** Streaming variant of `chatSessionContinue`. */
+  chatStreamSessionContinue(
+    userMessage: string,
+    images: Uint8Array[] | null | undefined,
+    config: ChatConfig | null | undefined,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+  /** Streaming variant of `chatSessionContinueTool`. */
+  chatStreamSessionContinueTool(
+    toolCallId: string,
+    content: string,
+    config: ChatConfig | null | undefined,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+}
+
 /**
  * Qwen3.5 Model -- hybrid linear/full attention with optional MoE.
  *
- * Uses interior mutability (RwLock) for layers, final_norm, lm_head, and caches
- * to allow async generation via spawn_blocking without blocking the Node.js event loop.
- * This matches the pattern used by Qwen3Model.
+ * All inference and training state lives on a dedicated OS thread. NAPI methods
+ * dispatch commands via channels and await responses. Training commands are
+ * routed through `TrainingDispatch` to the model thread.
  */
 export declare class Qwen35Model {
-  /** Create a new Qwen3.5 model with the given configuration. */
-  constructor(config: Qwen35Config);
   /** Initialize caches for incremental generation. */
   initCaches(): void;
   /** Reset all caches. */
@@ -677,28 +1094,18 @@ export declare class Qwen35Model {
    *
    * The cache is moved out of the model — calling `takeCache()` twice
    * returns `null` the second time. Pass the cache back via `setCache()`
-   * before the next `chat()` call for incremental prefill.
+   * before the next `chatSessionStart` / `chatSessionContinue` call for
+   * incremental prefill.
    */
   takeCache(): PromptCache | null;
   /**
    * Restore a previously taken `PromptCache` into the model.
    *
-   * On the next `chat()` call with `reuseCache: true`, the model will
-   * prefix-match the new tokens against the cache and only prefill the delta.
+   * On the next `chatSessionStart` / `chatSessionContinue` call with
+   * `reuseCache: true`, the model will prefix-match the new tokens against
+   * the cache and only prefill the delta.
    */
   setCache(cache: PromptCache): void;
-  /**
-   * Forward pass through the model.
-   *
-   * # Arguments
-   * * `input_ids` - Token IDs [B, T]
-   *
-   * # Returns
-   * Logits [B, T, vocab_size]
-   */
-  forward(inputIds: MxArray): MxArray;
-  /** Forward pass with cache for incremental generation. */
-  forwardWithCache(inputIds: MxArray): MxArray;
   /**
    * Load a pretrained model from a directory.
    *
@@ -708,44 +1115,131 @@ export declare class Qwen35Model {
    * - tokenizer.json + tokenizer_config.json
    */
   static load(path: string): Promise<Qwen35Model>;
-  /**
-   * Generate text from a prompt token sequence.
-   *
-   * Runs generation on a worker thread via spawn_blocking to avoid
-   * blocking the Node.js event loop.
-   */
+  /** Generate text from a prompt token sequence. */
   generate(promptTokens: MxArray, config: Qwen35GenerationConfig): Promise<Qwen35GenerationResult>;
   /**
-   * Chat API with tool calling support.
+   * Start a new chat session.
+   *
+   * Runs the full jinja chat template once and uses `<|im_end|>` as
+   * its stop token so the cached KV state ends on a clean ChatML
+   * boundary. Image support is conditional on the loaded
+   * checkpoint: a Qwen3.5-VL dense model loaded with vision weights
+   * accepts images in `messages` (the vision encoder handles
+   * prefill), while a plain text Qwen3.5 checkpoint rejects them
+   * with a runtime error. Subsequent turns in the same session MUST
+   * go through `chatSessionContinue` so the caller appends raw
+   * ChatML deltas on top of the live caches without rerunning the
+   * jinja template; a mid-session image change requires a fresh
+   * `chatSessionStart` call. The session is owned end-to-end by
+   * the `chatSession*` surface.
+   *
+   * This method is the production entry point used by the TypeScript
+   * `ChatSession` wrapper for turn 1 of a multi-round conversation.
+   */
+  chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Continue an existing chat session with a new user message.
+   *
+   * Appends a raw ChatML user/assistant delta to the session's cached
+   * KV state, then decodes the assistant reply. Stops on `<|im_end|>`
+   * so the cache remains on a clean boundary for the next turn.
+   *
+   * Requires a live session started via `chatSessionStart`. Errors
+   * if the session is empty, carries image state, or if
+   * `config.reuse_cache` is explicitly set to `false`.
+   *
+   * `images` is an opt-in guard parameter: when non-empty, the native
+   * side returns an error whose message begins with
+   * `IMAGE_CHANGE_REQUIRES_SESSION_RESTART:` so the TypeScript
+   * `ChatSession` layer can catch the prefix and route image-changes
+   * back through a fresh `chatSessionStart`.
+   */
+  chatSessionContinue(
+    userMessage: string,
+    images: Uint8Array[] | null | undefined,
+    config: ChatConfig | null | undefined,
+  ): Promise<ChatResult>;
+  /**
+   * Continue an existing chat session with a tool-result turn.
+   *
+   * Builds a ChatML `<tool_response>`-wrapped delta from `content` and
+   * prefills it on top of the live session caches, then decodes the
+   * assistant reply. Stops on `<|im_end|>` so the cache stays on a
+   * clean boundary for the next turn.
+   *
+   * The `tool_call_id` is currently dropped by the wire format —
+   * Qwen3.5's chat template identifies tool responses by position +
+   * wrapper tags, not an explicit id. Callers may still log it for
+   * their own bookkeeping.
+   *
+   * Requires a live session started via `chatSessionStart`.
+   */
+  chatSessionContinueTool(
+    toolCallId: string,
+    content: string,
+    config?: ChatConfig | undefined | null,
+  ): Promise<ChatResult>;
+  /**
+   * Streaming variant of `chatSessionStart`.
+   *
+   * Dispatches to the dedicated model thread. Behaviourally identical
+   * to `chatSessionStart` (resets caches, uses `<|im_end|>` as
+   * eos, inherits the same VLM-vs-text image-support contract) but
+   * streams token deltas through the JS callback instead of
+   * returning a `ChatResult`. Used by the TypeScript
+   * `ChatSession.sendStream()` for turn 1 of a multi-round streaming
+   * conversation.
+   */
+  chatStreamSessionStart(
+    messages: ChatMessage[],
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+  /**
+   * Streaming variant of `chatSessionContinue`.
+   *
+   * Appends a ChatML user/assistant delta on top of the live session
+   * caches and streams the decoded reply. Requires a live session
+   * started via `chatStreamSessionStart` (or the non-streaming
+   * `chatSessionStart`). Used by the TypeScript
+   * `ChatSession.sendStream()` for turns 2..N of a multi-round
+   * streaming conversation.
    *
-   * Runs tokenization + generation on a worker thread via spawn_blocking
-   * to avoid blocking the Node.js event loop.
+   * `images` is an opt-in guard parameter: when non-empty, the
+   * streaming path emits an error chunk whose message begins with
+   * `IMAGE_CHANGE_REQUIRES_SESSION_RESTART:` so the TypeScript
+   * `ChatSession` layer can route image-changes through a fresh
+   * session start.
    */
-  chat(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  chatStreamSessionContinue(
+    userMessage: string,
+    images: Uint8Array[] | null | undefined,
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
   /**
-   * Streaming chat API with tool calling support.
+   * Streaming variant of `chatSessionContinueTool`.
    *
-   * Same as `chat()` but streams tokens one-by-one via the callback.
-   * Returns a `ChatStreamHandle` immediately; generation runs in background.
-   * Call `handle.cancel()` to abort generation early.
+   * Builds a ChatML tool-response delta on top of the live session
+   * caches and streams the decoded reply. Requires a live session
+   * started via `chatSessionStart` / `chatStreamSessionStart`.
    */
-  chatStream(
-    messages: ChatMessage[],
+  chatStreamSessionContinueTool(
+    toolCallId: string,
+    content: string,
     config: ChatConfig | null,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
-  /** Get the number of parameters in the model. */
+  /**
+   * Get the number of parameters in the model.
+   *
+   * Pure config computation — no model-thread dispatch needed.
+   */
   numParameters(): number;
   /**
    * Save the model weights and configuration to a directory.
    *
-   * This saves:
-   * - config.json: Model configuration (with model_type for detectModelType)
-   * - weights.safetensors: Full model weights in SafeTensors format
-   * - weights.mlx: Parameter metadata (for reference)
-   *
-   * # Arguments
-   * * `save_path` - Directory to save the model
+   * Dispatches to model thread.
    */
   saveModel(savePath: string): Promise<undefined>;
 }
@@ -754,57 +1248,145 @@ export type Qwen3_5Model = Qwen35Model;
 /**
  * Qwen3.5 MoE Model -- hybrid linear/full attention with Mixture-of-Experts.
  *
- * Supports C++ MoE forward path (non-compiled, builds fresh graph per step)
- * when weights are registered via `register_moe_weights_with_cpp`.
- * Falls back to Rust forward_inner path for test models without stored weights.
+ * All inference and training state lives on a dedicated OS thread. NAPI methods
+ * dispatch commands via channels and await responses. Training commands are
+ * routed through `TrainingDispatch` to the model thread.
  */
 export declare class Qwen35MoeModel {
-  constructor(config: Qwen35MoeConfig);
+  /** Initialize caches for incremental generation. */
+  initCaches(): void;
+  /** Reset all caches. */
+  resetCaches(): void;
+  /** Take the KV cache from the model, returning a `PromptCache` handle. */
+  takeCache(): PromptCache | null;
+  /** Restore a previously taken `PromptCache` into the model. */
+  setCache(cache: PromptCache): void;
+  /** Load a pretrained model from a directory. */
+  static load(path: string): Promise<Qwen35MoeModel>;
+  /** Generate text from a prompt token sequence. */
+  generate(promptTokens: MxArray, config: Qwen35MoeGenerationConfig): Promise<Qwen35MoeGenerationResult>;
   /**
-   * Take the KV cache from the model, returning a `PromptCache` handle.
+   * Start a new chat session.
    *
-   * The cache is moved out of the model — calling `takeCache()` twice
-   * returns `null` the second time. Pass the cache back via `setCache()`
-   * before the next `chat()` call for incremental prefill.
+   * Runs the full jinja chat template once, decodes until `<|im_end|>`,
+   * and leaves the KV caches on a clean ChatML boundary so subsequent
+   * `chatSessionContinue` / `chatSessionContinueTool` calls can
+   * append a raw delta on top without re-rendering the chat
+   * template.
+   *
+   * Image support is conditional on the loaded checkpoint: a
+   * Qwen3.5-VL MoE model loaded with vision weights accepts images
+   * in `messages` (the vision encoder handles prefill), while a
+   * plain text Qwen3.5 MoE checkpoint rejects them with a runtime
+   * error. A mid-session image change requires a fresh
+   * `chatSessionStart` call.
+   *
+   * Requires `config.reuse_cache` to be enabled (the default).
    */
-  takeCache(): PromptCache | null;
+  chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
   /**
-   * Restore a previously taken `PromptCache` into the model.
+   * Continue an existing chat session with a new user message.
+   *
+   * Appends a raw ChatML user/assistant delta to the session's cached
+   * KV state, then decodes the assistant reply. Stops on `<|im_end|>`
+   * so the cache remains on a clean boundary for the next turn.
+   *
+   * Requires a live session started via `chatSessionStart`.
+   * Errors if the session is empty, carries image state, or if
+   * `config.reuse_cache` is explicitly set to `false`.
    *
-   * On the next `chat()` call with `reuseCache: true`, the model will
-   * prefix-match the new tokens against the cache and only prefill the delta.
+   * `images` is an opt-in guard parameter: when non-empty, the native
+   * side returns an error whose message begins with
+   * `IMAGE_CHANGE_REQUIRES_SESSION_RESTART:` so the TypeScript
+   * `ChatSession` layer can catch the prefix and route image-changes
+   * back through a fresh `chatSessionStart`.
    */
-  setCache(cache: PromptCache): void;
-  initCaches(): void;
-  resetCaches(): void;
-  forward(inputIds: MxArray): MxArray;
-  forwardWithCache(inputIds: MxArray): MxArray;
-  static load(path: string): Promise<Qwen35MoeModel>;
-  generate(promptTokens: MxArray, config: Qwen35MoeGenerationConfig): Promise<Qwen35MoeGenerationResult>;
-  chat(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  chatSessionContinue(
+    userMessage: string,
+    images: Uint8Array[] | null | undefined,
+    config: ChatConfig | null | undefined,
+  ): Promise<ChatResult>;
   /**
-   * Streaming chat API with tool calling support.
+   * Continue an existing chat session with a tool-result turn.
+   *
+   * Builds a ChatML `<tool_response>`-wrapped delta from `content` and
+   * prefills it on top of the live session caches, then decodes the
+   * assistant reply. Stops on `<|im_end|>` so the cache stays on a
+   * clean boundary for the next turn.
+   *
+   * The `tool_call_id` is currently dropped by the wire format —
+   * Qwen3.5's chat template identifies tool responses by position +
+   * wrapper tags, not an explicit id. Callers may still log it for
+   * their own bookkeeping.
    *
-   * Same as `chat()` but streams tokens one-by-one via the callback.
-   * Returns a `ChatStreamHandle` immediately; generation runs in background.
-   * Call `handle.cancel()` to abort generation early.
+   * Requires a live session started via `chatSessionStart`.
    */
-  chatStream(
+  chatSessionContinueTool(
+    toolCallId: string,
+    content: string,
+    config?: ChatConfig | undefined | null,
+  ): Promise<ChatResult>;
+  /**
+   * Streaming variant of `chatSessionStart`.
+   *
+   * Dispatches to the dedicated model thread. Behaviourally identical
+   * to `chatSessionStart` (resets caches, uses `<|im_end|>` as
+   * eos, inherits the same VLM-vs-text image-support contract) but
+   * streams token deltas through the JS callback instead of
+   * returning a `ChatResult`. Used by the TypeScript
+   * `ChatSession.sendStream()` for turn 1 of a multi-round streaming
+   * conversation.
+   */
+  chatStreamSessionStart(
     messages: ChatMessage[],
     config: ChatConfig | null,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
+  /**
+   * Streaming variant of `chatSessionContinue`.
+   *
+   * Appends a ChatML user/assistant delta on top of the live session
+   * caches and streams the decoded reply. Requires a live session
+   * started via `chatStreamSessionStart` (or the non-streaming
+   * `chatSessionStart`). Used by the TypeScript
+   * `ChatSession.sendStream()` for turns 2..N of a multi-round
+   * streaming conversation.
+   *
+   * `images` is an opt-in guard parameter: when non-empty, the
+   * streaming path emits an error chunk whose message begins with
+   * `IMAGE_CHANGE_REQUIRES_SESSION_RESTART:` so the TypeScript
+   * `ChatSession` layer can route image-changes through a fresh
+   * session start.
+   */
+  chatStreamSessionContinue(
+    userMessage: string,
+    images: Uint8Array[] | null | undefined,
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+  /**
+   * Streaming variant of `chatSessionContinueTool`.
+   *
+   * Builds a ChatML tool-response delta on top of the live session
+   * caches and streams the decoded reply. Requires a live session
+   * started via `chatSessionStart` / `chatStreamSessionStart`.
+   */
+  chatStreamSessionContinueTool(
+    toolCallId: string,
+    content: string,
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+  /**
+   * Get the number of parameters in the model.
+   *
+   * Pure config computation -- no model-thread dispatch needed.
+   */
   numParameters(): number;
   /**
    * Save the model weights and configuration to a directory.
    *
-   * This saves:
-   * - config.json: Model configuration (with model_type for detectModelType)
-   * - weights.safetensors: Full model weights in SafeTensors format
-   * - weights.mlx: Parameter metadata (for reference)
-   *
-   * # Arguments
-   * * `save_path` - Directory to save the model
+   * Dispatches to model thread.
    */
   saveModel(savePath: string): Promise<undefined>;
 }
@@ -813,28 +1395,15 @@ export type Qwen3_5MoeModel = Qwen35MoeModel;
 /**
  * Qwen3 Model with automatic differentiation support
  *
- * Uses interior mutability (RwLock) for layers, final_norm, and lm_head
- * to allow gradient application without deep cloning the model.
- * This eliminates the previous ~4GB memory overhead from clone_for_session().
+ * Uses a dedicated model thread for inference and training commands.
+ * Training commands are routed via `TrainingDispatch`.
  */
 export declare class Qwen3Model {
-  /** Create a new Qwen3 model with the given configuration */
-  constructor(config: Qwen3Config);
   /**
-   * Reset the KV cache used for cache reuse across chat() calls.
+   * Reset the KV cache used for cache reuse across chat-session turns.
    * Call this when starting a new conversation to ensure a full prefill.
    */
   resetCache(): void;
-  /**
-   * Forward pass through the model
-   *
-   * # Arguments
-   * * `input_ids` - Token IDs, shape: [batch_size, seq_len]
-   *
-   * # Returns
-   * * Logits, shape: [batch_size, seq_len, vocab_size]
-   */
-  forward(inputIds: MxArray): MxArray;
   /**
    * Initialize KV caches for incremental generation
    *
@@ -847,8 +1416,6 @@ export declare class Qwen3Model {
    * Clears cached key-value states. Call this between different generation sequences.
    */
   resetKvCaches(): void;
-  /** Check if paged attention is enabled for this model */
-  hasPagedAttention(): boolean;
   /**
    * Get paged attention memory statistics (if enabled)
    *
@@ -861,17 +1428,6 @@ export declare class Qwen3Model {
    * Returns the number of waiting, running, and completed sequences.
    */
   schedulerStats(): SchedulerStatsNapi | null;
-  /**
-   * Forward pass with KV caching for incremental generation
-   *
-   * # Arguments
-   * * `input_ids` - Token IDs, shape: [batch_size, seq_len]
-   * * `use_cache` - Whether to use KV caching (must call init_kv_caches() first)
-   *
-   * # Returns
-   * * Logits, shape: [batch_size, seq_len, vocab_size]
-   */
-  forwardWithCache(inputIds: MxArray, useCache: boolean): MxArray;
   /**
    * Forward pass with paged attention for memory-efficient inference.
    *
@@ -957,205 +1513,6 @@ export declare class Qwen3Model {
   hasPagedWork(): boolean;
   /** Get model configuration */
   getConfig(): Qwen3Config;
-  /**
-   * Generate tokens using speculative decoding with a draft model.
-   *
-   * Speculative decoding uses a smaller draft model to generate tokens speculatively,
-   * then verifies them with the target model in a single forward pass. This can achieve
-   * 2-3x speedup when the draft model has high acceptance rate.
-   *
-   * # Algorithm
-   * 1. Draft model generates N tokens speculatively (cheap forward passes)
-   * 2. Target model (self) verifies all N tokens in one forward pass
-   * 3. Accept/reject using rejection sampling
-   * 4. On rejection, resample from adjusted distribution
-   * 5. Rewind caches and continue
-   *
-   * # Arguments
-   * * `draft_model` - Smaller model for speculative generation (should share tokenizer)
-   * * `input_ids` - Input token IDs [1, seq_len]
-   * * `config` - Generation configuration (includes num_draft_tokens)
-   *
-   * # Returns
-   * GenerationResult with tokens, logprobs, and speculative stats in finish_reason
-   *
-   * # Example (TypeScript)
-   * ```typescript
-   * const targetModel = await loadModel('qwen3-7b');
-   * const draftModel = await loadModel('qwen3-0.5b');
-   *
-   * const result = targetModel.generateSpeculativeSync(draftModel, inputIds, {
-   *   numDraftTokens: 5,
-   *   maxNewTokens: 100,
-   *   temperature: 0.7,
-   * });
-   * ```
-   */
-  generateSpeculativeSync(
-    draftModel: Qwen3Model,
-    inputIds: MxArray,
-    config?: GenerationConfig | undefined | null,
-  ): GenerationResult;
-  /** Count total number of parameters in the model */
-  numParameters(): number;
-  /**
-   * Get all model parameters as a dictionary mapping names to arrays
-   *
-   * This matches the TypeScript API for compatibility
-   */
-  getParameters(): Record<string, MxArray>;
-  /** Load parameters from a dictionary */
-  loadParameters(params: Record<string, MxArray>): void;
-  /**
-   * Compute forward pass and loss (for evaluation)
-   *
-   * # Arguments
-   * * `input_ids` - Input token IDs, shape: [batch_size, seq_len]
-   * * `labels` - Target token IDs, shape: [batch_size, seq_len]
-   *
-   * # Returns
-   * * Scalar loss value
-   */
-  computeLoss(inputIds: MxArray, labels: MxArray): MxArray;
-  /**
-   * Compute loss and gradients using a hybrid approach
-   *
-   * This implementation computes gradients for the output layers and uses
-   * numerical approximations for other parameters. This is sufficient to
-   * demonstrate that training works while we build out full MLX autograd integration.
-   *
-   * # Arguments
-   * * `input_ids` - Input token IDs, shape: [batch_size, seq_len]
-   * * `labels` - Target token IDs, shape: [batch_size, seq_len]
-   *
-   * # Returns
-   * * A tuple of (loss, gradients_dict) where gradients_dict maps parameter names to gradient arrays
-   *
-   * # Phase 6A Status
-   * Current implementation computes:
-   * - ✅ Exact gradients for LM head (output layer)
-   * - ⚠吅 Numerical approximations for other layers
-   *
-   * Future: Full MLX autograd will compute exact gradients for all 250+ parameters
-   */
-  computeLossAndGradients(inputIds: MxArray, labels: MxArray): [MxArray, Record<string, MxArray>];
-  /**
-   * Complete GRPO training step using MLX Autograd (RECOMMENDED)
-   *
-   * This method uses automatic differentiation to compute gradients, eliminating
-   * the need for manual backward pass implementation. This is the preferred approach.
-   *
-   * # Arguments
-   * * `prompt_tokens` - Prompt token sequences [batch_size, seq_len] (1D arrays)
-   * * `completion_tokens` - Completion sequences [batch*G, completion_len] (1D arrays)
-   * * `completion_logprobs` - Logprobs from generation [batch*G, completion_len] (1D arrays)
-   * * `rewards` - Reward scores for each completion [batch*G]
-   * * `group_size` - Number of completions per prompt (G)
-   * * `config` - GRPO loss configuration
-   * * `learning_rate` - Learning rate for parameter updates
-   *
-   * # Returns
-   * * Tuple of (loss_value, metrics_dict)
-   */
-  trainStepGrpoAutograd(
-    promptTokens: Array<MxArray>,
-    completionTokens: Array<MxArray>,
-    completionLogprobs: Array<MxArray>,
-    rewards: Float64Array,
-    groupSize: number,
-    config: GrpoLossConfig,
-    learningRate: number,
-  ): [number, Record<string, number>];
-  /**
-   * Compute gradients only without applying them (for gradient accumulation)
-   *
-   * This method computes GRPO loss and gradients but does NOT update parameters.
-   * Used for gradient accumulation where gradients are summed across multiple
-   * micro-batches before applying them.
-   *
-   * # Arguments
-   * * `prompt_tokens` - Prompt token sequences [batch_size, seq_len] (1D arrays)
-   * * `completion_tokens` - Completion sequences [batch*G, completion_len] (1D arrays)
-   * * `completion_logprobs` - Logprobs from generation [batch*G, completion_len] (1D arrays)
-   * * `rewards` - Reward scores for each completion [batch*G]
-   * * `group_size` - Number of completions per prompt (G)
-   * * `config` - GRPO loss configuration
-   *
-   * # Returns
-   * * Tuple of (loss_value, gradients_dict, metrics_dict)
-   */
-  computeGradientsOnlyGrpoAutograd(
-    promptTokens: Array<MxArray>,
-    completionTokens: Array<MxArray>,
-    completionLogprobs: Array<MxArray>,
-    rewards: Float64Array,
-    groupSize: number,
-    config: GrpoLossConfig,
-  ): [number, Record<string, MxArray>, Record<string, number>];
-  /**
-   * Accumulate gradients into existing gradient dictionary
-   *
-   * This is a helper method for gradient accumulation. It adds new_gradients
-   * to accumulated_gradients element-wise.
-   *
-   * # Arguments
-   * * `accumulated_gradients` - Existing accumulated gradients (will be modified in-place conceptually, but returns new dict)
-   * * `new_gradients` - New gradients to add
-   *
-   * # Returns
-   * * Updated gradient dictionary with accumulated values
-   */
-  static accumulateGradients(
-    accumulatedGradients: Record<string, MxArray>,
-    newGradients: Record<string, MxArray>,
-  ): Record<string, MxArray>;
-  /**
-   * Complete GRPO training step using manual gradients (Legacy)
-   *
-   * This method performs a full GRPO training iteration:
-   * 1. Takes completions (already generated) with their logprobs and rewards
-   * 2. Computes advantages
-   * 3. Computes GRPO loss and gradients
-   * 4. Updates model parameters
-   *
-   * NOTE: Use train_step_grpo_autograd instead for automatic differentiation.
-   *
-   * # Arguments
-   * * `prompt_tokens` - Prompt token sequences [batch_size, seq_len] (1D arrays)
-   * * `completion_tokens` - Completion sequences [batch*G, completion_len] (1D arrays)
-   * * `completion_logprobs` - Logprobs from generation [batch*G, completion_len] (1D arrays)
-   * * `rewards` - Reward scores for each completion [batch*G]
-   * * `group_size` - Number of completions per prompt (G)
-   * * `config` - GRPO loss configuration
-   * * `learning_rate` - Learning rate for parameter updates
-   *
-   * # Returns
-   * * Tuple of (loss_value, metrics_dict)
-   */
-  trainStepGrpo(
-    promptTokens: Array<MxArray>,
-    completionTokens: Array<MxArray>,
-    completionLogprobs: Array<MxArray>,
-    rewards: Float64Array,
-    groupSize: number,
-    config: GrpoLossConfig,
-    learningRate: number,
-  ): [number, Record<string, number>];
-  /**
-   * Apply gradients to model parameters
-   *
-   * # Arguments
-   * * `gradients` - Dictionary mapping parameter names to gradient arrays
-   * * `learning_rate` - Learning rate for gradient descent
-   *
-   * This performs a simple SGD update: param = param - lr * grad
-   * Only updates parameters that have gradients; others remain unchanged.
-   *
-   * IMPORTANT: This function preserves the original dtype of parameters.
-   * The learning rate scalar is cast to match param dtype to prevent
-   * promotion to float32 during arithmetic operations.
-   */
-  applyGradients(gradients: Record<string, MxArray>, learningRate: number): void;
   /**
    * Text-to-text generation with integrated tokenization
    *
@@ -1188,76 +1545,82 @@ export declare class Qwen3Model {
    */
   generate(messages: Array<ChatMessage>, config?: GenerationConfig | undefined | null): Promise<GenerationResult>;
   /**
-   * High-level chat API with structured response parsing
-   *
-   * The primary API for conversational AI. Handles:
-   * - Chat message formatting with Jinja2 templates
-   * - Tool/function calling with structured output
-   * - Thinking extraction from `<think>` tags
-   * - Clean response text with all special tags stripped
-   *
-   * ## `chat()` vs `generate()`
-   *
-   * | Feature | `chat()` | `generate()` |
-   * |---------|----------|--------------|
-   * | **Purpose** | Conversational AI with tools | Raw text generation |
-   * | **Input** | Chat messages | Token IDs (MxArray) |
-   * | **Tool Support** | Built-in parsing | None |
-   * | **Thinking** | Extracts `<think>` content | Raw text only |
-   * | **Output** | Structured `ChatResult` | Basic `GenerationResult` |
-   * | **Use Case** | Chat apps, agents, assistants | Training, low-level control |
-   *
-   * ## When to use `chat()`
-   * - Building conversational applications
-   * - Need tool/function calling
-   * - Want structured responses with thinking separated
-   * - Working with chat message format
-   *
-   * ## When to use `generate()`
-   * - Training and fine-tuning (need raw logprobs)
-   * - Custom tokenization pipeline
-   * - Low-level generation control
-   * - Non-chat use cases
+   * Reset all caches and clear cached token history. Exposed so
+   * tests and session-management code can start from a known clean
+   * state between turns.
+   */
+  resetCaches(): void;
+  /**
+   * Start a new chat session.
    *
-   * # Arguments
-   * * `messages` - Array of chat messages (user/assistant/system roles)
-   * * `config` - Chat configuration including optional tools and generation params
+   * Runs the full jinja chat template once, decodes until `<|im_end|>`,
+   * and leaves the KV caches on a clean ChatML boundary so subsequent
+   * `chatSessionContinue` / `chatSessionContinueTool` calls can
+   * append a raw delta on top without re-rendering the chat
+   * template.
    *
-   * # Returns
-   * * `ChatResult` containing:
-   *   - `text`: Clean response (tool_call and think tags stripped)
-   *   - `thinking`: Extracted chain-of-thought reasoning (or null)
-   *   - `toolCalls`: Parsed tool calls with native JS object arguments
-   *   - `finishReason`: "stop" | "length" | "tool_calls"
-   *   - `rawText`: Original text before processing (for debugging)
+   * Requires `config.reuse_cache` to be enabled (the default).
+   */
+  chatSessionStart(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  /**
+   * Continue an existing chat session with a new user message.
    *
-   * # Example
-   * ```typescript
-   * // Simple chat
-   * const result = await model.chat(messages);
-   * console.log(result.text);
+   * Appends a raw ChatML user/assistant delta to the session's
+   * cached KV state, then decodes the assistant reply. Stops on
+   * `<|im_end|>` so the cache remains on a clean boundary for the
+   * next turn.
    *
-   * // With tools
-   * const result = await model.chat(messages, {
-   *   tools: [{ type: 'function', function: { name: 'get_weather' } }],
-   *   maxNewTokens: 2048,
-   *   temperature: 0.7,
-   * });
+   * Requires a live session started via `chatSessionStart`. Errors
+   * if the session is empty, carries image state, or if
+   * `config.reuse_cache` is explicitly set to `false`.
    *
-   * // Handle tool calls
-   * for (const call of result.toolCalls) {
-   *   if (call.status === 'ok') {
-   *     console.log(call.name, call.arguments);  // Arguments is a JS object!
-   *   }
-   * }
-   *
-   * // Access thinking (chain-of-thought)
-   * if (result.thinking) {
-   *   console.log('Model reasoning:', result.thinking);
-   * }
-   * ```
+   * Qwen3 legacy is text-only; `images` is an opt-in guard parameter:
+   * when non-empty the native side returns an error whose message
+   * begins with `IMAGE_CHANGE_REQUIRES_SESSION_RESTART:` so the
+   * TypeScript `ChatSession` layer can catch the prefix and route
+   * image-changes back through a fresh `chatSessionStart` uniformly
+   * across all model backends.
    */
-  chat(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  chatSessionContinue(
+    userMessage: string,
+    images: Uint8Array[] | null | undefined,
+    config: ChatConfig | null | undefined,
+  ): Promise<ChatResult>;
+  /**
+   * Continue an existing chat session with a tool-result turn.
+   *
+   * Builds a Qwen3.5-style `<tool_response>`-wrapped user-role delta
+   * from `content` and prefills it on top of the live session
+   * caches, then decodes the assistant reply. Stops on `<|im_end|>`
+   * so the cache stays on a clean boundary for the next turn.
+   *
+   * Requires a live session started via `chatSessionStart`.
+   */
+  chatSessionContinueTool(
+    toolCallId: string,
+    content: string,
+    config?: ChatConfig | undefined | null,
+  ): Promise<ChatResult>;
+  /** Streaming variant of `chatSessionStart`. */
+  chatStreamSessionStart(
+    messages: ChatMessage[],
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+  /** Streaming variant of `chatSessionContinue`. */
+  chatStreamSessionContinue(
+    userMessage: string,
+    images: Uint8Array[] | null | undefined,
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+  /** Streaming variant of `chatSessionContinueTool`. */
+  chatStreamSessionContinueTool(
+    toolCallId: string,
+    content: string,
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
   /**
    * Generate multiple completions for multiple prompts in batch
    *
@@ -1355,6 +1718,10 @@ export declare class Qwen3Model {
    * - weights.safetensors: Full model weights in SafeTensors format
    * - weights.mlx: Parameter metadata (for reference)
    *
+   * Dispatches to the dedicated model thread — all MxArray reads must
+   * happen on the thread that owns them to avoid the MLX cross-thread
+   * `CommandEncoder` crash.
+   *
    * # Arguments
    * * `save_path` - Directory to save the model
    */
@@ -1507,7 +1874,33 @@ export declare class Qwen3Tokenizer {
   getEndoftextToken(): string;
 }
 
-/** SFT Training Engine */
+/**
+ * Response store for OpenAI Responses API persistence.
+ *
+ * Stores responses in SQLite to support `previous_response_id`
+ * for multi-turn conversation state.
+ */
+export declare class ResponseStore {
+  /** Open (or create) a response store at the given path. */
+  static open(path: string): Promise<ResponseStore>;
+  /** Store a response. */
+  store(response: StoredResponseRecord): Promise<void>;
+  /** Get a single response by ID. */
+  get(id: string): Promise<StoredResponseRecord | null>;
+  /** Get the full conversation chain for a response (oldest first). */
+  getChain(id: string): Promise<Array<StoredResponseRecord>>;
+  /** Delete a response by ID. Returns true if a row was deleted. */
+  delete(id: string): Promise<boolean>;
+  /** Delete expired responses. Returns the number of rows deleted. */
+  cleanupExpired(): Promise<number>;
+}
+
+/**
+ * SFT Training Engine
+ *
+ * Thin coordinator that routes all MLX operations through the model thread.
+ * No MxArrays or model state live here - only plain data crosses the boundary.
+ */
 export declare class SftTrainingEngine {
   /** Create a new SFT training engine from a Qwen3 model */
   constructor(model: Qwen3Model, config: SftEngineConfig);
@@ -1524,9 +1917,10 @@ export declare class SftTrainingEngine {
   /**
    * Flush any accumulated gradients at epoch end
    *
-   * When stepsPerEpoch % gradient_accumulation_steps != 0, there may be
-   * leftover gradients from the final micro-batches. This method applies
-   * them with proper averaging, matching TRL behavior.
+   * With the model thread architecture, gradient accumulation is handled
+   * on the model thread. This method is kept for API compatibility but
+   * currently logs a warning. Partial accumulation at epoch boundaries
+   * will be handled in a future update.
    */
   flushGradients(): boolean;
   /**
@@ -1549,15 +1943,46 @@ export declare class SftTrainingEngine {
   startEpoch(epoch: number): void;
   /** End current epoch and return metrics */
   endEpoch(epochTimeSecs: number): SftEpochMetrics;
-  /** Reset training state (for new training run) */
+  /**
+   * Reset training state (for new training run)
+   *
+   * This is a TERMINAL operation on this handle. It drops the training
+   * state (optimizer, step counter) on the model thread so a fresh
+   * `SftTrainingEngine` can be constructed on the same model, and marks
+   * THIS handle as invalidated. Any subsequent dispatch-requiring method
+   * on this handle returns an error — callers must construct a new
+   * engine to continue training.
+   */
   reset(): void;
-  /** Restore training state (for resuming from checkpoint) */
+  /**
+   * Restore training state (for resuming from checkpoint)
+   *
+   * Updates both the engine's read-through cache and the model thread's
+   * authoritative `ts.step`. Does NOT touch optimizer state — that is
+   * loaded via `loadOptimizerState`, which restores the AdamW bias-
+   * correction step separately.
+   */
   restoreState(step: number, epoch: number): void;
-  /** Get the underlying Qwen3 model for checkpointing */
+  /**
+   * Get the underlying Qwen3 model for checkpointing
+   *
+   * NOTE: With the model thread architecture, direct model access is no longer
+   * supported. Use save_checkpoint() on the model directly instead.
+   */
   getModel(): Qwen3Model;
-  /** Get the underlying Qwen3.5 dense model for checkpointing */
+  /**
+   * Get the underlying Qwen3.5 dense model for checkpointing
+   *
+   * NOTE: With the model thread architecture, direct model access is no longer
+   * supported. Use save_checkpoint() on the model directly instead.
+   */
   getQwen35Model(): Qwen35Model;
-  /** Get the underlying Qwen3.5 MoE model for checkpointing */
+  /**
+   * Get the underlying Qwen3.5 MoE model for checkpointing
+   *
+   * NOTE: With the model thread architecture, direct model access is no longer
+   * supported. Use save_checkpoint() on the model directly instead.
+   */
   getQwen35MoeModel(): Qwen35MoeModel;
 }
 
@@ -1730,9 +2155,17 @@ export type VLMChatResult = VlmChatResult;
  *
  * A generic VLM for OCR and document understanding tasks.
  * Currently supports PaddleOCR-VL architecture (vision encoder + ERNIE language model).
+ *
+ * All model state lives on a dedicated OS thread. NAPI methods dispatch
+ * commands via channels and await responses.
  */
 export declare class VLModel {
-  /** Create a new PaddleOCR-VL model */
+  /**
+   * Create a new PaddleOCR-VL model (empty, not loaded).
+   *
+   * Creates a model thread with an empty inner. Use `VLModel.load()` instead
+   * for loading a model from disk.
+   */
   constructor(config: ModelConfig);
   /** Set the tokenizer */
   setTokenizer(tokenizer: Qwen3Tokenizer): void;
@@ -1815,9 +2248,7 @@ export declare class VLModel {
   /**
    * Generate text tokens given input tokens and optional image
    *
-   * Uses KV caching for efficient generation - each step only processes the
-   * new token(s) while reusing cached key-value states from previous tokens.
-   * Vision features are computed once at the start and cached.
+   * Uses KV caching for efficient generation.
    *
    * # Arguments
    * * `input_ids` - Input token IDs [1, seq_len]
@@ -1972,6 +2403,20 @@ export interface ChatConfig {
   repetitionPenalty?: number | undefined;
   /** Size of the context window for repetition penalty (default: 256) */
   repetitionContextSize?: number | undefined;
+  /**
+   * Presence penalty (0.0 = disabled). Subtracts a flat penalty from logits of any
+   * token that appeared at least once in context. Matches OpenAI API semantics.
+   */
+  presencePenalty?: number | undefined;
+  /** Number of recent tokens to consider for presence penalty (default: 20) */
+  presenceContextSize?: number | undefined;
+  /**
+   * Frequency penalty (0.0 = disabled). Subtracts penalty * occurrence_count from
+   * logits of each token in context. Matches OpenAI API semantics.
+   */
+  frequencyPenalty?: number | undefined;
+  /** Number of recent tokens to consider for frequency penalty (default: 20) */
+  frequencyContextSize?: number | undefined;
   /** Max consecutive identical tokens before stopping (default: 16, 0 = disabled) */
   maxConsecutiveTokens?: number | undefined;
   /** Max n-gram repetitions before stopping (default: 3, 0 = disabled) */
@@ -1980,18 +2425,33 @@ export interface ChatConfig {
   ngramSize?: number | undefined;
   tools?: Array<ToolDefinition>;
   /**
-   * Enable thinking mode (Qwen3's <think> tags). Default: true (model thinks naturally).
-   * Set to false to suppress thinking by injecting empty <think></think> tags.
+   * Reasoning effort level. Controls whether the model thinks before answering.
+   * - "none" / "low": thinking disabled (template injects closed think block).
+   *   "none" also sets includeReasoning to false by default.
+   * - "medium" / "high": thinking enabled (default behavior).
+   * - Not set: thinking enabled (model thinks naturally).
    */
-  enableThinking?: boolean | undefined;
+  reasoningEffort?: string | undefined;
+  /**
+   * Maximum number of thinking tokens before forcing </think>.
+   * When the model has generated this many tokens while in thinking mode,
+   * the next token is forced to be the think_end token. None = unlimited.
+   */
+  thinkingTokenBudget?: number | undefined;
+  /**
+   * Whether to include reasoning/thinking content in the output.
+   * When false, the `thinking` field of ChatResult/ChatStreamChunk will always be None.
+   * Default: true (false when reasoningEffort is "none").
+   */
+  includeReasoning?: boolean | undefined;
   /** When true, include performance metrics (TTFT, prefill tok/s, decode tok/s) in the result */
   reportPerformance?: boolean | undefined;
   /**
-   * Reuse KV cache across chat() calls for incremental prefill. Default: true.
+   * Reuse KV cache across chat-session turns for incremental prefill. Default: true.
    * When true, the model preserves its KV cache after generation. On the next
-   * chat() call, it prefix-matches the new token sequence against the cached
-   * tokens and only prefills the delta — avoiding redundant computation for
-   * multi-turn conversations.
+   * `chatSessionStart` / `chatSessionContinue` call, it prefix-matches the new
+   * token sequence against the cached tokens and only prefills the delta —
+   * avoiding redundant computation for multi-turn conversations.
    */
   reuseCache?: boolean | undefined;
 }
@@ -2018,6 +2478,8 @@ export interface ChatResult {
   toolCalls: Array<ToolCallResult>;
   thinking?: string;
   numTokens: number;
+  promptTokens: number;
+  reasoningTokens: number;
   finishReason: string;
   rawText: string;
   /** Performance metrics (present when `reportPerformance: true` in config) */
@@ -2044,9 +2506,17 @@ export interface ChatStreamChunk {
   toolCalls?: Array<ToolCallResult>;
   thinking?: string;
   numTokens?: number;
+  promptTokens?: number;
+  reasoningTokens?: number;
   rawText?: string;
   /** Performance metrics (only present in the final chunk when `reportPerformance: true`) */
   performance?: PerformanceMetrics;
+  /**
+   * Whether this delta chunk contains reasoning/thinking content.
+   * true = reasoning (inside <think>...</think>), false = content (after </think>).
+   * Only present on intermediate (non-final) chunks.
+   */
+  isReasoning?: boolean | undefined;
 }
 
 /** Result from classify_and_rotate: orientation info + corrected image bytes. */
@@ -2174,6 +2644,45 @@ export declare function convertParquetToJsonl(inputPath: string, outputPath: str
 /** Create a default PaddleOCR-VL 1.5 configuration (JS factory function) */
 export declare function createPaddleocrVlConfig(): ModelConfig;
 
+/** Create a default Qianfan-OCR configuration (JS factory function) */
+export declare function createQianfanOcrConfig(): QianfanOcrConfig;
+
+/**
+ * Create a random-init Qwen3.5 model and save it to disk.
+ *
+ * Spawns a dedicated `ModelThread<Qwen35Cmd>` whose init builds a fresh
+ * random-weight `Qwen35Inner` directly, then dispatches `Qwen35Cmd::SaveModel`
+ * on that thread. The thread is dropped at the end of the promise, so the
+ * in-memory model is released once the checkpoint has been written. Used by
+ * TypeScript test fixtures that need an on-disk checkpoint without keeping a
+ * NAPI model instance alive.
+ */
+export declare function createRandomQwen35Checkpoint(config: Qwen35Config, savePath: string): Promise<undefined>;
+
+/**
+ * Create a random-init Qwen3.5 MoE model and save it to disk.
+ *
+ * Spawns a dedicated `ModelThread<Qwen35MoeCmd>` whose init builds a fresh
+ * random-weight `Qwen35MoeInner` directly, then dispatches
+ * `Qwen35MoeCmd::SaveModel` on that thread. The thread is dropped at the end
+ * of the promise, so the in-memory model is released once the checkpoint has
+ * been written. Used by TypeScript test fixtures that need an on-disk
+ * checkpoint without keeping a NAPI model instance alive.
+ */
+export declare function createRandomQwen35MoeCheckpoint(config: Qwen35MoeConfig, savePath: string): Promise<undefined>;
+
+/**
+ * Create a random-init Qwen3 model and save it to disk.
+ *
+ * Spawns a dedicated `ModelThread<Qwen3Cmd>` whose init builds a fresh
+ * random-weight `Qwen3Inner` directly, then dispatches `Qwen3Cmd::SaveModel`
+ * on that thread. The thread is dropped at the end of the promise, so the
+ * in-memory model is released once the checkpoint has been written. Used by
+ * TypeScript test fixtures that need an on-disk checkpoint without keeping a
+ * NAPI model instance alive.
+ */
+export declare function createRandomQwen3Checkpoint(config: Qwen3Config, savePath: string): Promise<undefined>;
+
 /** Document element - either a table or paragraph */
 export interface DocumentElement {
   elementType: ElementType;
@@ -2300,6 +2809,86 @@ export interface FunctionParameters {
   required?: Array<string>;
 }
 
+/**
+ * Gemma 4 model configuration (dense variant).
+ *
+ * Supports E2B (2.3B), E4B (4.5B), and 31B dense models.
+ * For MoE models (26B-A4B), use `Gemma4MoeConfig` from `gemma4_moe`.
+ */
+export interface Gemma4Config {
+  vocabSize: number;
+  hiddenSize: number;
+  numHiddenLayers: number;
+  numAttentionHeads: number;
+  numKeyValueHeads: number;
+  headDim: number;
+  intermediateSize: number;
+  rmsNormEps: number;
+  tieWordEmbeddings: boolean;
+  maxPositionEmbeddings: number;
+  slidingWindow: number;
+  /**
+   * Explicit per-layer attention type: "sliding_attention" or "full_attention".
+   * Parsed from `text_config.layer_types` in the HuggingFace config.
+   */
+  layerTypes: Array<string>;
+  /** RoPE theta for global (full) attention layers. */
+  ropeTheta: number;
+  /** RoPE theta for sliding (local) attention layers. */
+  ropeLocalBaseFreq: number;
+  /** Fraction of head_dim to rotate for global attention (0.25 = 25%). */
+  partialRotaryFactor: number;
+  /** KV heads for global layers. If None, uses num_key_value_heads. */
+  globalNumKeyValueHeads?: number;
+  /** Head dimension for global layers. If None, uses head_dim. */
+  globalHeadDim?: number;
+  attentionKEqV: boolean;
+  finalLogitSoftcapping?: number;
+  perLayerInputEmbeds: boolean;
+  hiddenSizePerLayerInput?: number;
+  vocabSizePerLayerInput?: number;
+  padTokenId: number;
+  eosTokenIds: Array<number>;
+  bosTokenId: number;
+  attentionBias: boolean;
+  useDoubleWideMlp: boolean;
+  numKvSharedLayers?: number;
+  defaultTemperature?: number;
+  defaultTopK?: number;
+  defaultTopP?: number;
+  enableMoeBlock: boolean;
+  numExperts?: number;
+  topKExperts?: number;
+  moeIntermediateSize?: number;
+  visionConfig?: Gemma4VisionConfig;
+  imageTokenId?: number;
+  boiTokenId?: number;
+  eoiTokenId?: number;
+  visionSoftTokensPerImage?: number;
+}
+
+/**
+ * Vision encoder configuration for Gemma4 multimodal models.
+ *
+ * Parsed from the `vision_config` sub-dict in config.json.
+ */
+export interface Gemma4VisionConfig {
+  hiddenSize: number;
+  intermediateSize: number;
+  numHiddenLayers: number;
+  numAttentionHeads: number;
+  numKeyValueHeads: number;
+  headDim: number;
+  rmsNormEps: number;
+  patchSize: number;
+  positionEmbeddingSize: number;
+  defaultOutputLength: number;
+  poolingKernelSize: number;
+  useClippedLinears: boolean;
+  ropeTheta: number;
+  standardize: boolean;
+}
+
 /** Result from generate_batch_for_training with all data needed for training */
 export interface GenerateBatchResult {
   /** Generated completion texts */
@@ -2333,6 +2922,20 @@ export interface GenerationConfig {
    * Matches mlx-lm default. Larger values catch longer patterns but use more memory
    */
   repetitionContextSize?: number;
+  /**
+   * Presence penalty (0.0 = disabled). Subtracts a flat penalty from logits of any
+   * token that appeared at least once in context. Matches OpenAI API semantics.
+   */
+  presencePenalty?: number;
+  /** Number of recent tokens to consider for presence penalty (default: 20) */
+  presenceContextSize?: number;
+  /**
+   * Frequency penalty (0.0 = disabled). Subtracts penalty * occurrence_count from
+   * logits of each token in context. Matches OpenAI API semantics.
+   */
+  frequencyPenalty?: number;
+  /** Number of recent tokens to consider for frequency penalty (default: 20) */
+  frequencyContextSize?: number;
   /**
    * Stop if same token repeats this many times consecutively (default: 16)
    * Set to 0 to disable. Prevents OOM from degenerate repetitive generation.
@@ -2526,6 +3129,16 @@ export interface GrpoEngineConfig {
   topK?: number;
   /** Repetition penalty (default: 1.1) */
   repetitionPenalty?: number;
+  /**
+   * Presence penalty (0.0 = disabled). Subtracts a flat penalty from logits of any
+   * token that appeared at least once in context.
+   */
+  presencePenalty?: number;
+  /**
+   * Frequency penalty (0.0 = disabled). Subtracts penalty * occurrence_count from
+   * logits of each token in context.
+   */
+  frequencyPenalty?: number;
   /**
    * Maximum allowed NaN gradient occurrences before stopping training (default: 100)
    * When exceeded, training will stop with an error to prevent model corruption.
@@ -2659,6 +3272,46 @@ export interface GrpoLossConfig {
   vocabChunkSize?: number;
 }
 
+/**
+ * Configuration for Harrier embedding model (Qwen3 backbone).
+ *
+ * Only includes backbone dimensions needed for encoding.
+ * No generation fields (token IDs, paged attention, etc.).
+ */
+export interface HarrierConfig {
+  hiddenSize: number;
+  numLayers: number;
+  numHeads: number;
+  numKeyValueHeads: number;
+  intermediateSize: number;
+  rmsNormEps: number;
+  ropeTheta: number;
+  maxPositionEmbeddings: number;
+  headDim: number;
+  /**
+   * Qwen3 always uses QK normalization. Omit to use the default (true).
+   * Explicitly passing false is allowed but produces a model incompatible
+   * with published Harrier weights.
+   */
+  useQkNorm?: boolean;
+  vocabSize: number;
+}
+
+/** InternViT vision encoder configuration */
+export interface InternVisionConfig {
+  hiddenSize: number;
+  intermediateSize: number;
+  numHiddenLayers: number;
+  numAttentionHeads: number;
+  numChannels: number;
+  imageSize: number;
+  patchSize: number;
+  layerNormEps: number;
+  qkvBias: boolean;
+  /** Drop path rate (inference only, always 0) */
+  dropPathRate: number;
+}
+
 /** Check whether profiling is currently enabled. */
 export declare function isProfilingEnabled(): boolean;
 
@@ -2676,6 +3329,35 @@ export interface LayoutElement {
   order: number;
 }
 
+/**
+ * LFM2 model configuration.
+ *
+ * Supports LiquidAI's LFM2.5 hybrid conv+attention architecture.
+ * 16 layers total: 10 conv + 6 full_attention, defined by `layer_types` array.
+ */
+export interface Lfm2Config {
+  vocabSize: number;
+  hiddenSize: number;
+  numHiddenLayers: number;
+  numAttentionHeads: number;
+  numKeyValueHeads: number;
+  maxPositionEmbeddings: number;
+  normEps: number;
+  convBias: boolean;
+  convLCache: number;
+  blockDim: number;
+  blockFfDim: number;
+  blockMultipleOf: number;
+  blockFfnDimMultiplier: number;
+  blockAutoAdjustFfDim: boolean;
+  ropeTheta: number;
+  layerTypes: Array<string>;
+  tieEmbedding: boolean;
+  eosTokenId: number;
+  bosTokenId: number;
+  padTokenId: number;
+}
+
 export interface MemorySnapshot {
   /** Active (non-cached) memory in bytes. */
   activeBytes: number;
@@ -2896,6 +3578,29 @@ export interface ProfilingSummary {
   avgPrefillMs: number;
 }
 
+/** Full Qianfan-OCR model configuration */
+export interface QianfanOcrConfig {
+  visionConfig: InternVisionConfig;
+  llmConfig: Qwen3LmConfig;
+  modelType: string;
+  imgContextTokenId: number;
+  /** `<img>` token ID */
+  imgStartTokenId: number;
+  /** `</img>` token ID */
+  imgEndTokenId: number;
+  /** `<|im_end|>` token ID */
+  eosTokenId: number;
+  /** Which vision encoder layer to extract features from */
+  selectLayer: number;
+  /** Pixel shuffle version */
+  psVersion: string;
+  downsampleRatio: number;
+  dynamicImageSize: boolean;
+  useThumbnail: boolean;
+  maxDynamicPatch: number;
+  minDynamicPatch: number;
+}
+
 /**
  * Qwen3.5 model configuration (dense variant).
  *
@@ -3039,6 +3744,22 @@ export interface Qwen3Config {
   useFp8Cache?: boolean | undefined;
 }
 
+/** Qwen3 language model configuration */
+export interface Qwen3LmConfig {
+  hiddenSize: number;
+  numHiddenLayers: number;
+  intermediateSize: number;
+  numAttentionHeads: number;
+  numKeyValueHeads: number;
+  headDim: number;
+  rmsNormEps: number;
+  vocabSize: number;
+  maxPositionEmbeddings: number;
+  ropeTheta: number;
+  useQkNorm: boolean;
+  tieWordEmbeddings: boolean;
+}
+
 /** Result of text recognition. */
 export interface RecResult {
   /** Recognized text */
@@ -3272,6 +3993,22 @@ export interface StepSummary {
   lengthCount: number;
 }
 
+/** A stored response record exposed to JavaScript. */
+export interface StoredResponseRecord {
+  id: string;
+  createdAt: number;
+  model: string;
+  status: string;
+  instructions?: string;
+  inputJson: string;
+  outputJson: string;
+  outputText: string;
+  usageJson: string;
+  previousResponseId?: string;
+  configJson?: string;
+  expiresAt?: number;
+}
+
 /** A table structure */
 export interface Table {
   rows: Array<TableRow>;
@@ -3462,6 +4199,20 @@ export interface VlmChatConfig {
   topP?: number;
   /** Repetition penalty (default: 1.5) */
   repetitionPenalty?: number;
+  /**
+   * Presence penalty (0.0 = disabled). Subtracts a flat penalty from logits of any
+   * token that appeared at least once in context. Matches OpenAI API semantics.
+   */
+  presencePenalty?: number;
+  /** Number of recent tokens to consider for presence penalty (default: 20) */
+  presenceContextSize?: number;
+  /**
+   * Frequency penalty (0.0 = disabled). Subtracts penalty * occurrence_count from
+   * logits of each token in context. Matches OpenAI API semantics.
+   */
+  frequencyPenalty?: number;
+  /** Number of recent tokens to consider for frequency penalty (default: 20) */
+  frequencyContextSize?: number;
   /** Whether to return log probabilities (default: false) */
   returnLogprobs?: boolean;
 }