@mlx-node/core 0.0.6 → 0.0.8

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,168 @@ 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 {
+  /**
+   * Create an uninitialized `Gemma4Model` stub from a config.
+   *
+   * **Prefer [`Gemma4Model::load`]** for any real usage — `new(config)`
+   * is a config-only stub that matches the OCR-model pattern
+   * (`VLModel::new(config)`, `QianfanOCRModel::new(config)`) and is
+   * intentionally NOT runnable. It was introduced in the cache-limit
+   * coordinator work so that the coordinator's per-model delta is
+   * registered exclusively on the `load()` path, eliminating a
+   * baseline-registration gap where a no-op `new(config)` would have
+   * leaked an empty guard into the coordinator.
+   *
+   * This path does NOT spawn a model thread, NOT materialize any
+   * weights, and NOT register with the cache-limit coordinator. The
+   * returned instance is only useful for config inspection — every
+   * session method (`chatSessionStart` / `chatSessionContinue` /
+   * `chatSessionContinueTool` and their streaming variants) rejects
+   * with a `napi::Error` whose message is exactly
+   * `"Model not initialized. Call Gemma4Model.load() first."` until
+   * `load()` runs and installs the underlying model thread. The
+   * synchronous `resetCaches()` call is a silent no-op on the stub
+   * to keep `ChatSession.reset()` idempotent across both runnable
+   * and stub instances.
+   *
+   * A runnable model requires `await Gemma4Model.load(path)`. The
+   * constructor signature is fixed by NAPI-RS; the stub-only behavior is
+   * covered by the regression tests in
+   * `__test__/models/model-loader-gemma4.test.ts`.
+   */
+  constructor(config: Gemma4Config);
+  /** Returns true if weights have been loaded via `load()`. */
+  get isInitialized(): boolean;
+  /**
+   * Whether the block-paged KV cache adapter is active on this model
+   * instance.
+   *
+   * `true` iff `Gemma4Inner::paged_adapter` was successfully
+   * constructed at load time (driven by
+   * `Gemma4Config::use_block_paged_cache`). The
+   * `gemma4_paged_vs_flat_parity` integration test pins greedy
+   * byte-equal at BF16 against real Gemma-4-E2B-IT weights. Stubs
+   * constructed via `new(config)` always return `false`. Surfaced
+   * through this NAPI method so server endpoints can branch on it
+   * without a model-thread roundtrip.
+   */
+  hasBlockPagedCache(): boolean;
+  /**
+   * Whether this loaded instance can execute image-bearing chat turns.
+   * Config-only stubs and incomplete/non-paged physical paths return false.
+   */
+  supportsImages(): boolean;
+  modelId(): number;
+  /**
+   * Whether a draft model — DSpark or Google assistant — is loaded on
+   * this instance (via `Gemma4LoadOptions::draft_model_path`), enabling
+   * the speculative-decode whole-turn path.
+   *
+   * Note: this only reports draft availability. Whether speculative
+   * decoding actually runs on a given call also requires the per-request
+   * `enableMtp` flag. Named `hasMtpWeights` for parity with the Qwen3.5
+   * surface, but it reports an external draft model (either variant),
+   * not in-checkpoint MTP heads. Stubs from `new(config)` always return
+   * `false`.
+   */
+  hasMtpWeights(): boolean;
+  /** Load a Gemma4 model from a directory. */
+  static load(modelPath: string, options?: Gemma4LoadOptions | undefined | null): 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.
+   */
+  resetCaches(): void;
+  /**
+   * Start a new chat session.
+   *
+   * Runs the full jinja chat template once, decodes until the
+   * family's session stop token, 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 user/assistant delta to the session's cached
+   * KV state, then decodes the assistant reply, stopping on the
+   * family's session boundary token.
+   *
+   * `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 route image-changes back through a
+   * fresh `chatSessionStart`.
+   */
+  chatSessionContinue(
+    userMessage: string,
+    images: Uint8Array[] | null | undefined,
+    audio: Uint8Array[] | null | undefined,
+    config: ChatConfig | null | undefined,
+  ): Promise<ChatResult>;
+  /**
+   * Continue an existing chat session with a tool-result turn.
+   *
+   * Builds the family's tool-result delta from `content` and
+   * prefills it on top of the live session caches, then decodes
+   * the assistant reply.
+   *
+   * `is_error` is the structured tool-error signal. When
+   * `Some(true)`, the renderer prepends the shared
+   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the
+   * rendered tool block.
+   */
+  chatSessionContinueTool(
+    toolCallId: string,
+    content: string,
+    config?: ChatConfig | undefined | null,
+    isError?: boolean | 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,
+    audio: Uint8Array[] | null | undefined,
+    config: ChatConfig | null | undefined,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+  /**
+   * Streaming variant of `chatSessionContinueTool`.
+   *
+   * `is_error` mirrors the non-streaming entry point — when
+   * `Some(true)`, the renderer prepends the shared
+   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the rendered
+   * tool block.
+   */
+  chatStreamSessionContinueTool(
+    toolCallId: string,
+    content: string,
+    config: ChatConfig | null | undefined,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+    isError?: boolean | null | undefined,
+  ): Promise<ChatStreamHandle>;
+}
+
 /** Result from text generation with detailed metadata */
 export declare class GenerationResult {
   /** Get the decoded text */
@@ -120,14 +287,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 +311,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 +339,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 +359,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 +391,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 +420,214 @@ 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>;
+  /**
+   * Whether the block-paged KV cache adapter is active on this model
+   * instance.
+   *
+   * `true` iff `Lfm2Inner::paged_adapter` was successfully constructed
+   * at load time (driven by `Lfm2Config::use_block_paged_cache`,
+   * defaulting to `true` after paged-vs-flat parity verification).
+   * LFM2 is hybrid (10 conv + 6 full-attention layers); only the
+   * full-attention layers route through the adapter, conv layers stay
+   * on flat `Lfm2LayerCache::Conv` regardless. When `true`, the native
+   * cache reuses SYS blocks across `chatSessionStart` calls via
+   * content-addressing, so the JS-side warm slot in
+   * `SessionRegistry.getOrCreateWarmAny` is redundant and the
+   * `/v1/messages` server endpoint allocates a fresh `ChatSession` per
+   * request.
+   */
+  hasBlockPagedCache(): boolean;
+  /** Get the model configuration. */
+  getConfig(): Lfm2Config;
+  /** Estimated number of model parameters. */
+  numParameters(): number;
+  /**
+   * 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 the
+   * family's session stop token, 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 user/assistant delta to the session's cached
+   * KV state, then decodes the assistant reply, stopping on the
+   * family's session boundary token.
+   *
+   * `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 route image-changes back through a
+   * fresh `chatSessionStart`.
+   */
+  chatSessionContinue(
+    userMessage: string,
+    images: Uint8Array[] | null | undefined,
+    audio: Uint8Array[] | null | undefined,
+    config: ChatConfig | null | undefined,
+  ): Promise<ChatResult>;
+  /**
+   * Continue an existing chat session with a tool-result turn.
+   *
+   * Builds the family's tool-result delta from `content` and
+   * prefills it on top of the live session caches, then decodes
+   * the assistant reply.
+   *
+   * `is_error` is the structured tool-error signal. When
+   * `Some(true)`, the renderer prepends the shared
+   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the
+   * rendered tool block.
+   */
+  chatSessionContinueTool(
+    toolCallId: string,
+    content: string,
+    config?: ChatConfig | undefined | null,
+    isError?: boolean | 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,
+    audio: Uint8Array[] | null | undefined,
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+  /**
+   * Streaming variant of `chatSessionContinueTool`.
+   *
+   * `is_error` mirrors the non-streaming entry point — when
+   * `Some(true)`, the renderer prepends the shared
+   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the rendered
+   * tool block.
+   */
+  chatStreamSessionContinueTool(
+    toolCallId: string,
+    content: string,
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+    isError?: boolean | null | undefined,
+  ): Promise<ChatStreamHandle>;
+}
+
 export declare class MxArray {
   equal(other: MxArray): MxArray;
   notEqual(other: MxArray): MxArray;
@@ -382,9 +749,20 @@ export declare class MxArray {
   divScalar(value: number): MxArray;
   matmul(other: MxArray): MxArray;
   /**
-   * Fused matrix multiply-add: D = beta * C + alpha * (self @ B)
-   * where self is A. More efficient than separate matmul and add operations.
-   * Default: alpha=1.0, beta=1.0, giving D = C + (self @ B)
+   * Matrix multiply-add: D = beta * C + alpha * (self @ B), where self is A.
+   * Default: alpha=1.0, beta=1.0, giving D = C + (self @ B).
+   *
+   * Computed explicitly (matmul, optional alpha scale, then add beta*C)
+   * rather than via the fused `mlx::core::addmm` primitive. The fused
+   * primitive is correct on a well-formed metallib, but this project's local
+   * release build is known to non-deterministically miscompile fused GEMM
+   * kernels (see the metallib-corruption notes), which manifested as the
+   * fused addmm dropping `beta*C` and corrupting every biased linear — most
+   * visibly the vision tower (`qkv`, `proj`, `fc1`, `fc2`, merger all carry a
+   * bias; bias-free LM/MoE linears pass a zero `C` and were unaffected). The
+   * explicit form keeps the `C` term robust to that build hazard; the
+   * `nn::linear` unit tests assert it applies a non-zero `C`, so they double
+   * as a canary if a future build corrupts the matmul kernel too.
    */
   addmm(c: MxArray, b: MxArray, alpha?: number | undefined | null, beta?: number | undefined | null): MxArray;
   abs(): MxArray;
@@ -399,6 +777,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,522 +1020,542 @@ export declare class OutputStore {
 }
 
 /**
- * Opaque handle to KV cache state from a previous chat() call.
- *
- * 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.
+ * NAPI-exported view of [`PrivacyFilterModel`].
  *
- * Created internally by the model when `reuseCache: true` (default).
- * Extract via `model.takeCache()`, restore via `model.setCache(cache)`.
+ * Construct via [`PrivacyFilterModelJs::load`] and run end-to-end
+ * classification via [`PrivacyFilterModelJs::classify`].
  */
-export declare class PromptCache {
-  /** Number of tokens stored in this cache. */
-  get tokenCount(): number;
-  /** Whether this cache has been consumed (caches moved out). */
-  get isEmpty(): boolean;
-  /** Release GPU memory held by this cache. */
-  dispose(): void;
+export declare class PrivacyFilterModel {
+  /**
+   * Load a privacy-filter checkpoint from a directory.
+   *
+   * The directory must contain `config.json`, `model.safetensors`,
+   * `tokenizer.json`, and optionally `viterbi_calibration.json` and
+   * `tokenizer_config.json`. Synchronous to match the loader pattern
+   * used by every other model in this crate (e.g. `TextDetModel`).
+   */
+  static load(modelPath: string): PrivacyFilterModel;
+  /**
+   * Classify `text` and return detected PII entities (and optionally
+   * per-token tags).
+   *
+   * Pipeline:
+   * 1. Tokenize the text with byte offsets, no special tokens.
+   * 2. Run the forward pass to get `[1, T, 33]` logits.
+   * 3. Compute softmax (for per-tag confidences) and log-softmax (for
+   *    Viterbi emissions) over the class axis.
+   * 4. Build the transition matrix from the default calibration
+   *    merged with any per-call overrides.
+   * 5. Viterbi-decode using log-softmax emissions to get the BIOES
+   *    tag sequence.
+   * 6. For each token, take the softmax probability of the
+   *    Viterbi-emitted tag (so per-token `tag` and `score` share
+   *    decoders), then walk the tags + offsets + those probabilities
+   *    to extract coherent spans whose mean probability clears
+   *    `threshold`.
+   */
+  classify(text: string, opts?: PrivacyClassifyOptions | undefined | null): PrivacyClassifyResult;
 }
+export type PrivacyFilterModelJs = PrivacyFilterModel;
 
 /**
- * Qwen3.5 Model -- hybrid linear/full attention with optional MoE.
+ * 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.
  *
- * 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 state lives on a dedicated OS thread. NAPI methods
+ * dispatch commands via channels and await responses.
  */
-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. */
-  resetCaches(): void;
-  /**
-   * Take the KV cache from the model, returning a `PromptCache` handle.
-   *
-   * 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.
-   */
-  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.
-   */
-  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;
+export declare class QianfanOCRModel {
   /**
-   * Load a pretrained model from a directory.
+   * Create a new QianfanOCRModel from config (uninitialized, no weights).
    *
-   * Expects the directory to contain:
-   * - config.json
-   * - model.safetensors (or model-*.safetensors)
-   * - tokenizer.json + tokenizer_config.json
+   * This constructor path does not spawn a model thread — the returned
+   * instance is only useful for `is_initialized` queries until
+   * [`QianfanOCRModel::load`] is called to actually run inference. The
+   * `config` argument is accepted to preserve the `new
+   * QianfanOCRModel(config)` JS surface; the value is discarded because
+   * nothing on the uninitialized path consults it (any future config
+   * getter would forward to the inner thread state populated by
+   * `load()`).
    */
-  static load(path: string): Promise<Qwen35Model>;
+  constructor(config: QianfanOcrConfig);
+  /** Returns true if weights have been loaded via `load()`. */
+  get isInitialized(): boolean;
   /**
-   * Generate text from a prompt token sequence.
+   * Load a QianfanOCRModel from a directory.
    *
-   * Runs generation on a worker thread via spawn_blocking to avoid
-   * blocking the Node.js event loop.
+   * 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.
    */
-  generate(promptTokens: MxArray, config: Qwen35GenerationConfig): Promise<Qwen35GenerationResult>;
+  static load(modelPath: string): Promise<QianfanOCRModel>;
   /**
-   * Chat API with tool calling support.
+   * Generate text tokens given pre-tokenized input.
    *
-   * Runs tokenization + generation on a worker thread via spawn_blocking
-   * to avoid blocking the Node.js event loop.
+   * Lower-level API — prefer the session chat methods
+   * (`chatSessionStart` / `chatSessionContinue` and their streaming
+   * variants) for typical usage.
    */
-  chat(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
+  generate(
+    inputIds: MxArray,
+    maxNewTokens?: number | undefined | null,
+    temperature?: number | undefined | null,
+  ): Promise<Array<number>>;
+  /** Reset KV caches and token history. */
+  resetCaches(): void;
   /**
-   * Streaming chat API with tool calling support.
-   *
-   * 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.
-   */
-  chatStream(
+   * 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.
+   *
+   * `audio` exists only to keep this method's positional ABI aligned
+   * with the shared chat surface every other family exposes (the
+   * `chat_napi_surface!` macro inserts `audio` between `images` and
+   * `config`). Qianfan-OCR has no audio support, so a non-empty
+   * `audio` is rejected at the boundary with the shared no-audio
+   * error; `None` / empty is a complete no-op and audio is never
+   * threaded into the model thread.
+   */
+  chatSessionContinue(
+    userMessage: string,
+    images: Uint8Array[] | null | undefined,
+    audio: 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.
+   *
+   * `is_error` is the structured tool-error signal. When `Some(true)`,
+   * the renderer prepends the shared
+   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the
+   * `<tool_response>` wrapper so the model receives a clear text-level
+   * cue. `None` / `Some(false)` keep the wire bytes byte-equal to the
+   * pre-feature output.
+   *
+   * Requires a live session started via `chatSessionStart`.
+   */
+  chatSessionContinueTool(
+    toolCallId: string,
+    content: string,
+    config?: ChatConfig | undefined | null,
+    isError?: boolean | undefined | null,
+  ): Promise<ChatResult>;
+  /** Streaming variant of `chatSessionStart`. */
+  chatStreamSessionStart(
     messages: ChatMessage[],
-    config: ChatConfig | null,
+    config: ChatConfig | null | undefined,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
-  /** Get the number of parameters in the model. */
-  numParameters(): number;
   /**
-   * Save the model weights and configuration to a directory.
+   * Streaming variant of `chatSessionContinue`.
    *
-   * 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
-   */
-  saveModel(savePath: string): Promise<undefined>;
-}
-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.
- */
-export declare class Qwen35MoeModel {
-  constructor(config: Qwen35MoeConfig);
-  /**
-   * Take the KV cache from the model, returning a `PromptCache` handle.
-   *
-   * 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.
+   * `audio` mirrors the non-streaming entry point: it exists only to
+   * keep the positional ABI aligned with the shared chat surface, and
+   * a non-empty value is rejected at the boundary with the shared
+   * no-audio error. `None` / empty is a complete no-op.
    */
-  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.
-   */
-  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>;
-  /**
-   * Streaming chat API with tool calling support.
-   *
-   * 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.
-   */
-  chatStream(
-    messages: ChatMessage[],
-    config: ChatConfig | null,
+  chatStreamSessionContinue(
+    userMessage: string,
+    images: Uint8Array[] | null | undefined,
+    audio: Uint8Array[] | null | undefined,
+    config: ChatConfig | null | undefined,
     callback: (err: Error | null, chunk: ChatStreamChunk) => void,
   ): Promise<ChatStreamHandle>;
-  numParameters(): number;
   /**
-   * Save the model weights and configuration to a directory.
+   * Streaming variant of `chatSessionContinueTool`.
    *
-   * 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
+   * `is_error` mirrors the non-streaming entry point — when
+   * `Some(true)`, the renderer prepends the shared
+   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the
+   * `<tool_response>` wrapper.
    */
-  saveModel(savePath: string): Promise<undefined>;
+  chatStreamSessionContinueTool(
+    toolCallId: string,
+    content: string,
+    config: ChatConfig | null | undefined,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+    isError?: boolean | null | undefined,
+  ): Promise<ChatStreamHandle>;
 }
-export type Qwen3_5MoeModel = Qwen35MoeModel;
 
 /**
- * Qwen3 Model with automatic differentiation support
+ * Qwen3.5 Model -- hybrid linear/full attention with optional MoE.
  *
- * 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().
+ * 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 Qwen3Model {
-  /** Create a new Qwen3 model with the given configuration */
-  constructor(config: Qwen3Config);
-  /**
-   * Reset the KV cache used for cache reuse across chat() calls.
-   * 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
-   *
-   * Creates one KV cache per transformer layer. Call this before starting generation.
-   */
-  initKvCaches(): void;
+export declare class Qwen35Model {
   /**
-   * Reset all KV caches
+   * Whether the block-paged KV cache adapter is active on this model
+   * instance.
    *
-   * Clears cached key-value states. Call this between different generation sequences.
+   * `true` iff `Qwen35Inner::paged_adapter` was successfully
+   * constructed at load time (driven by
+   * `Qwen3_5Config::use_block_paged_cache`, default-OFF for text-only
+   * checkpoints because parity is pending real-weights validation, and
+   * default-ON for VLM checkpoints). On VLM checkpoints dense image turns
+   * ONLY run on the paged-vision core; a vision turn that reaches a None
+   * adapter errors at dispatch. Surfaced through this NAPI method so
+   * server endpoints can branch on it without round-tripping through
+   * the model thread.
    */
-  resetKvCaches(): void;
-  /** Check if paged attention is enabled for this model */
-  hasPagedAttention(): boolean;
+  hasBlockPagedCache(): boolean;
   /**
-   * Get paged attention memory statistics (if enabled)
+   * Whether this checkpoint shipped an MTP head (module loaded by
+   * `persistence::apply_weights_inner`). Snapshotted at load time from
+   * `Qwen35Inner::has_mtp_weights()` so the TS `ChatSession` can
+   * auto-default `enableMtp = true` for MTP-capable checkpoints without
+   * dispatching a command into the model thread.
    *
-   * Returns memory usage statistics for the paged KV cache.
+   * Note: this only reports weight availability. Whether the
+   * speculative-decode path actually runs on a given call also requires the
+   * per-request `enableMtp` flag.
    */
-  pagedCacheStats(): PagedCacheStats | null;
+  hasMtpWeights(): boolean;
   /**
-   * Get scheduler statistics (if paged attention is enabled)
+   * Whether this loaded model instance can execute image-bearing turns.
    *
-   * Returns the number of waiting, running, and completed sequences.
+   * This is an authoritative load-time snapshot, not a `config.json`
+   * family guess: it requires a loaded vision encoder, image processor,
+   * and the block-paged KV adapter used by the dense vision path.
    */
-  schedulerStats(): SchedulerStatsNapi | null;
+  supportsImages(): boolean;
   /**
-   * 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]
+   * Synchronous snapshot used by higher layers to preflight rendered
+   * prompts and clamp output before native cache allocation.
    */
-  forwardWithCache(inputIds: MxArray, useCache: boolean): MxArray;
+  contextLimits(): Qwen35ContextLimits;
   /**
-   * Forward pass with paged attention for memory-efficient inference.
+   * Compute the exact prompt length after Qwen image-placeholder expansion
+   * without running the vision encoder or touching inference caches.
    *
-   * This method uses block-based KV cache management via Metal kernels for:
-   * - Variable-length sequences with efficient memory usage
-   * - Continuous batching with dynamic batch composition
-   * - Long context support beyond GPU memory limits
-   *
-   * # Arguments
-   * * `input_ids` - Token IDs, shape: [num_seqs, 1] for decode
-   * * `slot_mapping` - Slot indices for cache updates, shape: [num_seqs]
-   * * `seq_ids` - Sequence IDs in the batch (for looking up block tables/context lens)
-   * * `positions` - Token positions for RoPE, shape: [num_seqs] (per-sequence positions)
-   *
-   * # Returns
-   * * Logits, shape: [num_seqs, 1, vocab_size] for decode
-   */
-  forwardPaged(inputIds: MxArray, slotMapping: MxArray, seqIds: Array<number>, positions: MxArray): MxArray;
-  /**
-   * Prefill a sequence using standard attention and write K/V to paged cache.
-   *
-   * This method should be called before `step_paged_generation()` for each
-   * new prompt. It runs the full forward pass using standard attention
-   * (which is faster for long sequences), then writes the K/V cache to
-   * the paged cache for subsequent decode steps.
-   *
-   * # Arguments
-   * * `prompt_tokens` - Token IDs for the prompt (as u32 array)
-   * * `seq_id` - Sequence ID (obtained from scheduler)
-   *
-   * # Returns
-   * * Logits for the last token, shape: [1, vocab_size]
+   * `prompt_tokens` is the already-rendered chat-template output. `messages`
+   * supplies the complete image history so both fresh and leased-session
+   * preflights account for every image in template order.
    */
-  prefillPaged(promptTokens: Array<number>, seqId: number): MxArray;
+  expandedPromptTokenCount(promptTokens: Uint32Array, messages: Array<ChatMessage>): Promise<number>;
   /**
-   * Add a request to the paged attention scheduler.
-   *
-   * The scheduler queues requests and allocates blocks for KV cache.
-   * Use `step_paged_generation()` to process the scheduled batch.
-   *
-   * Note: The actual sequence ID is assigned during scheduling, not when the
-   * request is added. Use the `request_id` to track your requests through
-   * the generation process.
-   *
-   * # Arguments
-   * * `request_id` - Unique identifier for the request (returned in outputs)
-   * * `prompt_tokens` - Token IDs for the prompt
-   * * `max_new_tokens` - Maximum new tokens to generate
-   * * `priority` - Optional priority (higher = scheduled first)
-   *
-   * # Returns
-   * * Number of pending requests in the queue
-   */
-  addPagedRequest(
-    requestId: string,
-    promptTokens: Array<number>,
-    maxNewTokens: number,
-    priority?: number | undefined | null,
-  ): number;
-  /**
-   * Schedule and execute one step of paged generation.
-   *
-   * This method:
-   * 1. Schedules the next batch of sequences
-   * 2. Runs forward pass with paged attention
-   * 3. Samples next tokens
-   * 4. Returns the generated tokens for each sequence
-   *
-   * # Arguments
-   * * `config` - Generation configuration (temperature, top_k, etc.)
-   *
-   * # Returns
-   * * `PagedGenerationStep` with token outputs for each sequence
-   */
-  stepPagedGeneration(config?: GenerationConfig | undefined | null): PagedGenerationStep | null;
-  /**
-   * Get completed sequences from the scheduler.
+   * Load a pretrained model from a directory.
    *
-   * Call this after `step_paged_generation()` returns outputs with `is_finished: true`.
+   * Expects the directory to contain:
+   * - config.json
+   * - model.safetensors (or model-*.safetensors)
+   * - tokenizer.json + tokenizer_config.json
    */
-  getCompletedSequences(): Array<PagedCompletedSequence>;
-  /** Check if the scheduler has pending work. */
-  hasPagedWork(): boolean;
-  /** Get model configuration */
-  getConfig(): Qwen3Config;
+  static load(path: string): Promise<Qwen35Model>;
+  /** Generate text from a prompt token sequence. */
+  generate(promptTokens: MxArray, config: Qwen35GenerationConfig): Promise<Qwen35GenerationResult>;
   /**
-   * 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)
+   * Get the number of parameters in the model.
    *
-   * # 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,
-   * });
-   * ```
+   * Pure config computation — no model-thread dispatch needed.
    */
-  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
+   * Save the model weights and configuration to a directory.
    *
-   * This matches the TypeScript API for compatibility
+   * Dispatches to model thread.
    */
-  getParameters(): Record<string, MxArray>;
-  /** Load parameters from a dictionary */
-  loadParameters(params: Record<string, MxArray>): void;
+  saveModel(savePath: string): Promise<undefined>;
   /**
-   * 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
+   * Reset all caches and clear cached token history. Exposed
+   * so tests and session-management code can start from a
+   * known clean state between turns.
    */
-  computeLoss(inputIds: MxArray, labels: MxArray): MxArray;
+  resetCaches(): void;
   /**
-   * 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
+   * Start a new chat session.
+   *
+   * Runs the full jinja chat template once, decodes until the
+   * family's session stop token, 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 user/assistant delta to the session's cached
+   * KV state, then decodes the assistant reply, stopping on the
+   * family's session boundary token.
+   *
+   * `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 route image-changes back through a
+   * fresh `chatSessionStart`.
+   */
+  chatSessionContinue(
+    userMessage: string,
+    images: Uint8Array[] | null | undefined,
+    audio: Uint8Array[] | null | undefined,
+    config: ChatConfig | null | undefined,
+  ): Promise<ChatResult>;
+  /**
+   * Continue an existing chat session with a tool-result turn.
+   *
+   * Builds the family's tool-result delta from `content` and
+   * prefills it on top of the live session caches, then decodes
+   * the assistant reply.
+   *
+   * `is_error` is the structured tool-error signal. When
+   * `Some(true)`, the renderer prepends the shared
+   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the
+   * rendered tool block.
+   */
+  chatSessionContinueTool(
+    toolCallId: string,
+    content: string,
+    config?: ChatConfig | undefined | null,
+    isError?: boolean | 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,
+    audio: Uint8Array[] | null | undefined,
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+  /**
+   * Streaming variant of `chatSessionContinueTool`.
    *
-   * Future: Full MLX autograd will compute exact gradients for all 250+ parameters
+   * `is_error` mirrors the non-streaming entry point — when
+   * `Some(true)`, the renderer prepends the shared
+   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the rendered
+   * tool block.
    */
-  computeLossAndGradients(inputIds: MxArray, labels: MxArray): [MxArray, Record<string, MxArray>];
+  chatStreamSessionContinueTool(
+    toolCallId: string,
+    content: string,
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+    isError?: boolean | null | undefined,
+  ): Promise<ChatStreamHandle>;
+}
+export type Qwen3_5Model = Qwen35Model;
+
+/**
+ * Qwen3.5 MoE Model -- hybrid linear/full attention with Mixture-of-Experts.
+ *
+ * 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 {
   /**
-   * 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.
+   * Whether the block-paged KV cache adapter is active on this model
+   * instance.
    *
-   * # 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)
+   * `true` iff `Qwen35MoeInner::paged_adapter` was successfully
+   * constructed at load time (driven by
+   * `Qwen3_5MoeConfig::use_block_paged_cache`, currently default-OFF
+   * because parity is pending real-weights validation). On VLM
+   * checkpoints the adapter can still be active for text-only
+   * inference; image-bearing chat turns are rejected at runtime by
+   * the chat-entry sites. Surfaced through this NAPI method so
+   * server endpoints can branch on it without round-tripping through
+   * the model thread.
    */
-  trainStepGrpoAutograd(
-    promptTokens: Array<MxArray>,
-    completionTokens: Array<MxArray>,
-    completionLogprobs: Array<MxArray>,
-    rewards: Float64Array,
-    groupSize: number,
-    config: GrpoLossConfig,
-    learningRate: number,
-  ): [number, Record<string, number>];
+  hasBlockPagedCache(): boolean;
   /**
-   * Compute gradients only without applying them (for gradient accumulation)
+   * Whether this checkpoint shipped an MTP head (module loaded by
+   * `persistence::apply_weights_moe_inner`). Snapshotted at load time from
+   * `Qwen35MoeInner::has_mtp_weights()` so the TS `ChatSession` can
+   * auto-default `enableMtp = true` for MTP-capable checkpoints without
+   * dispatching a command into the model thread. Mirrors
+   * `Qwen3_5Model::has_mtp_weights`.
    *
-   * 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)
+   * Note: this only reports weight availability. Whether the
+   * speculative-decode path actually runs on a given call also requires
+   * the per-request `enableMtp` flag.
    */
-  computeGradientsOnlyGrpoAutograd(
-    promptTokens: Array<MxArray>,
-    completionTokens: Array<MxArray>,
-    completionLogprobs: Array<MxArray>,
-    rewards: Float64Array,
-    groupSize: number,
-    config: GrpoLossConfig,
-  ): [number, Record<string, MxArray>, Record<string, number>];
+  hasMtpWeights(): boolean;
   /**
-   * Accumulate gradients into existing gradient dictionary
+   * Whether this loaded model instance can execute image-bearing turns.
    *
-   * 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
+   * This is an authoritative load-time snapshot, not a model-family guess:
+   * it requires the loaded vision encoder, image processor, and block-paged
+   * KV adapter used by the MoE vision path.
    */
-  static accumulateGradients(
-    accumulatedGradients: Record<string, MxArray>,
-    newGradients: Record<string, MxArray>,
-  ): Record<string, MxArray>;
+  supportsImages(): boolean;
+  /** Synchronous active-context snapshot shared with the dense wrapper. */
+  contextLimits(): Qwen35ContextLimits;
   /**
-   * 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)
+   * Exact, non-mutating Qwen image-placeholder expansion count for a fully
+   * rendered prompt and complete message history.
    */
-  trainStepGrpo(
-    promptTokens: Array<MxArray>,
-    completionTokens: Array<MxArray>,
-    completionLogprobs: Array<MxArray>,
-    rewards: Float64Array,
-    groupSize: number,
-    config: GrpoLossConfig,
-    learningRate: number,
-  ): [number, Record<string, number>];
+  expandedPromptTokenCount(promptTokens: Uint32Array, messages: Array<ChatMessage>): Promise<number>;
+  /** 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>;
   /**
-   * Apply gradients to model parameters
+   * Get the number of parameters in the model.
    *
-   * # Arguments
-   * * `gradients` - Dictionary mapping parameter names to gradient arrays
-   * * `learning_rate` - Learning rate for gradient descent
+   * Pure config computation -- no model-thread dispatch needed.
+   */
+  numParameters(): number;
+  /**
+   * Save the model weights and configuration to a directory.
    *
-   * This performs a simple SGD update: param = param - lr * grad
-   * Only updates parameters that have gradients; others remain unchanged.
+   * Dispatches to model thread.
+   */
+  saveModel(savePath: string): Promise<undefined>;
+  /**
+   * 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 the
+   * family's session stop token, 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 user/assistant delta to the session's cached
+   * KV state, then decodes the assistant reply, stopping on the
+   * family's session boundary token.
+   *
+   * `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 route image-changes back through a
+   * fresh `chatSessionStart`.
+   */
+  chatSessionContinue(
+    userMessage: string,
+    images: Uint8Array[] | null | undefined,
+    audio: Uint8Array[] | null | undefined,
+    config: ChatConfig | null | undefined,
+  ): Promise<ChatResult>;
+  /**
+   * Continue an existing chat session with a tool-result turn.
+   *
+   * Builds the family's tool-result delta from `content` and
+   * prefills it on top of the live session caches, then decodes
+   * the assistant reply.
+   *
+   * `is_error` is the structured tool-error signal. When
+   * `Some(true)`, the renderer prepends the shared
+   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the
+   * rendered tool block.
+   */
+  chatSessionContinueTool(
+    toolCallId: string,
+    content: string,
+    config?: ChatConfig | undefined | null,
+    isError?: boolean | 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,
+    audio: Uint8Array[] | null | undefined,
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+  /**
+   * Streaming variant of `chatSessionContinueTool`.
    *
-   * 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.
+   * `is_error` mirrors the non-streaming entry point — when
+   * `Some(true)`, the renderer prepends the shared
+   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the rendered
+   * tool block.
    */
-  applyGradients(gradients: Record<string, MxArray>, learningRate: number): void;
+  chatStreamSessionContinueTool(
+    toolCallId: string,
+    content: string,
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+    isError?: boolean | null | undefined,
+  ): Promise<ChatStreamHandle>;
+}
+export type Qwen3_5MoeModel = Qwen35MoeModel;
+
+/**
+ * Qwen3 Model with automatic differentiation support
+ *
+ * Uses a dedicated model thread for inference and training commands.
+ * Training commands are routed via `TrainingDispatch`.
+ */
+export declare class Qwen3Model {
+  /**
+   * Whether the block-paged KV cache adapter is active on this model
+   * instance.
+   *
+   * `true` iff `Qwen3Inner::paged_adapter` was successfully constructed
+   * at load time (driven by `Qwen3Config::use_block_paged_cache`,
+   * defaulting to `true` for Qwen3 since paged-vs-flat parity has been
+   * verified). When `true`, the native cache reuses SYS blocks across
+   * `chatSessionStart` calls via content-addressing in
+   * `BlockAllocator`'s prefix-hash table — the JS-side warm slot in
+   * `SessionRegistry.getOrCreateWarmAny` becomes redundant and the
+   * `/v1/messages` server endpoint allocates a fresh `ChatSession` per
+   * request. See `packages/server/src/endpoints/messages.ts` for the
+   * runtime-routing decision.
+   */
+  hasBlockPagedCache(): boolean;
+  /** Get model configuration */
+  getConfig(): Qwen3Config;
   /**
    * Text-to-text generation with integrated tokenization
    *
@@ -1187,77 +1587,6 @@ 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
-   *
-   * # Arguments
-   * * `messages` - Array of chat messages (user/assistant/system roles)
-   * * `config` - Chat configuration including optional tools and generation params
-   *
-   * # 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)
-   *
-   * # Example
-   * ```typescript
-   * // Simple chat
-   * const result = await model.chat(messages);
-   * console.log(result.text);
-   *
-   * // With tools
-   * const result = await model.chat(messages, {
-   *   tools: [{ type: 'function', function: { name: 'get_weather' } }],
-   *   maxNewTokens: 2048,
-   *   temperature: 0.7,
-   * });
-   *
-   * // 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);
-   * }
-   * ```
-   */
-  chat(messages: Array<ChatMessage>, config?: ChatConfig | undefined | null): Promise<ChatResult>;
   /**
    * Generate multiple completions for multiple prompts in batch
    *
@@ -1297,20 +1626,6 @@ export declare class Qwen3Model {
     groupSize: number,
     config?: GenerationConfig | undefined | null,
   ): Promise<BatchGenerationResult>;
-  /**
-   * Decode token IDs to text using the internal tokenizer
-   *
-   * Helper method for decoding generated tokens. The model must have been loaded
-   * via load() to have a tokenizer available.
-   *
-   * # Arguments
-   * * `token_ids` - Token IDs to decode as Uint32Array
-   * * `skip_special_tokens` - Whether to skip special tokens (default: true)
-   *
-   * # Returns
-   * * Decoded text string
-   */
-  decode(tokenIds: Uint32Array, skipSpecialTokens?: boolean | undefined | null): Promise<string>;
   /**
    * Apply chat template and encode to token IDs
    *
@@ -1332,6 +1647,88 @@ export declare class Qwen3Model {
     tools?: Array<ToolDefinition> | undefined | null,
     enableThinking?: boolean | undefined | null,
   ): Promise<Uint32Array>;
+  /**
+   * 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 the
+   * family's session stop token, 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 user/assistant delta to the session's cached
+   * KV state, then decodes the assistant reply, stopping on the
+   * family's session boundary token.
+   *
+   * `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 route image-changes back through a
+   * fresh `chatSessionStart`.
+   */
+  chatSessionContinue(
+    userMessage: string,
+    images: Uint8Array[] | null | undefined,
+    audio: Uint8Array[] | null | undefined,
+    config: ChatConfig | null | undefined,
+  ): Promise<ChatResult>;
+  /**
+   * Continue an existing chat session with a tool-result turn.
+   *
+   * Builds the family's tool-result delta from `content` and
+   * prefills it on top of the live session caches, then decodes
+   * the assistant reply.
+   *
+   * `is_error` is the structured tool-error signal. When
+   * `Some(true)`, the renderer prepends the shared
+   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the
+   * rendered tool block.
+   */
+  chatSessionContinueTool(
+    toolCallId: string,
+    content: string,
+    config?: ChatConfig | undefined | null,
+    isError?: boolean | 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,
+    audio: Uint8Array[] | null | undefined,
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+  ): Promise<ChatStreamHandle>;
+  /**
+   * Streaming variant of `chatSessionContinueTool`.
+   *
+   * `is_error` mirrors the non-streaming entry point — when
+   * `Some(true)`, the renderer prepends the shared
+   * [`crate::tokenizer::TOOL_ERROR_MARKER`] inside the rendered
+   * tool block.
+   */
+  chatStreamSessionContinueTool(
+    toolCallId: string,
+    content: string,
+    config: ChatConfig | null,
+    callback: (err: Error | null, chunk: ChatStreamChunk) => void,
+    isError?: boolean | null | undefined,
+  ): Promise<ChatStreamHandle>;
   /**
    * Load a pretrained model from disk
    *
@@ -1355,6 +1752,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 +1908,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 +1951,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 +1977,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,14 +2189,18 @@ 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;
-  /** Check if tokenizer is available */
-  get hasTokenizer(): boolean;
   /**
    * Chat with the VLM model
    *
@@ -1778,82 +2241,6 @@ export declare class VLModel {
    * ```
    */
   ocr(imageData: Buffer, prompt?: string | undefined | null): Promise<string>;
-  /**
-   * Get input embeddings with vision features merged
-   *
-   * # Arguments
-   * * `input_ids` - Token IDs [batch, seq_len]
-   * * `pixel_values` - Optional image patches [batch, seq, channels, patch_h, patch_w]
-   * * `image_grid_thw` - Optional grid dimensions [num_images, 3]
-   *
-   * # Returns
-   * * Input embeddings with vision features inserted at image token positions
-   */
-  getInputEmbeddings(
-    inputIds: MxArray,
-    pixelValues?: MxArray | undefined | null,
-    imageGridThw?: MxArray | undefined | null,
-  ): MxArray;
-  /**
-   * Forward pass
-   *
-   * # Arguments
-   * * `input_ids` - Token IDs [batch, seq_len]
-   * * `pixel_values` - Optional image patches
-   * * `image_grid_thw` - Optional grid dimensions
-   * * `mask` - Optional attention mask
-   *
-   * # Returns
-   * * Logits [batch, seq_len, vocab_size]
-   */
-  forward(
-    inputIds: MxArray,
-    pixelValues?: MxArray | undefined | null,
-    imageGridThw?: MxArray | undefined | null,
-    mask?: MxArray | undefined | null,
-  ): MxArray;
-  /**
-   * 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.
-   *
-   * # Arguments
-   * * `input_ids` - Input token IDs [1, seq_len]
-   * * `pixel_values` - Optional image patches [1, num_patches, C, H, W]
-   * * `image_grid_thw` - Optional grid dimensions [1, 3]
-   * * `config` - Generation configuration
-   *
-   * # Returns
-   * * GenerationResult with tokens, logprobs, and finish reason
-   */
-  generate(
-    inputIds: MxArray,
-    pixelValues?: MxArray | undefined | null,
-    imageGridThw?: MxArray | undefined | null,
-    config?: GenerationConfig | undefined | null,
-  ): Promise<GenerationResult>;
-  /**
-   * Batch OCR: extract text from multiple images simultaneously
-   *
-   * Processes N images with sequential prefill + batched decode for ~N× decode throughput.
-   *
-   * # Arguments
-   * * `images` - Encoded image buffers
-   * * `config` - Optional chat configuration (shared across all items)
-   *
-   * # Returns
-   * * Vec of extracted text strings, one per image
-   *
-   * # Example
-   * ```typescript
-   * import { readFileSync } from 'fs';
-   * const images = ['page1.jpg', 'page2.jpg'].map(p => readFileSync(p));
-   * const texts = await model.ocrBatch(images);
-   * ```
-   */
-  ocrBatch(images: Array<Buffer>, config?: VlmChatConfig | undefined | null): Promise<Array<string>>;
   /**
    * Batch chat: process multiple items simultaneously
    *
@@ -1892,25 +2279,6 @@ export declare class VLModel {
    * ```
    */
   static load(modelPath: string): Promise<VLModel>;
-  /**
-   * Load model configuration from disk without loading weights
-   *
-   * This is useful for inspecting model configuration before loading the full model.
-   *
-   * # Arguments
-   * * `model_path` - Path to the model directory containing config.json
-   *
-   * # Returns
-   * * ModelConfig with vision and text configuration
-   *
-   * # Example
-   * ```typescript
-   * import { VLModel } from '@mlx-node/vlm';
-   * const config = await VLModel.loadConfig('./models/paddleocr-vl');
-   * console.log(config.visionConfig.hiddenSize);
-   * ```
-   */
-  static loadConfig(modelPath: string): Promise<ModelConfig>;
 }
 
 /**
@@ -1961,8 +2329,68 @@ export declare const enum BuiltinRewardType {
   JsonSchema = 'JsonSchema',
 }
 
+/**
+ * Data-free static FP8 activation-amax calibration over RAW-text PREFILL
+ * (NVIDIA modelopt `MaxCalibrator` parity), end to end in native code.
+ *
+ * The nvidia recipe covers BOTH `qwen3_5` (dense) and `qwen3_5_moe` (MoE), so
+ * this reads `<model_path>/config.json`'s `model_type` and dispatches to the
+ * matching loader + `CalibratePrefillRaw` command (any other `model_type` is a
+ * clear error). Both loaders are the SAME ones the inference session uses
+ * ([`persistence::load_with_thread`]) — the model is only usable on its
+ * dedicated model thread. Then:
+ *   1. dispatches `{Qwen35Cmd,Qwen35MoeCmd}::CalibratePrefillRaw`, which on the
+ *      model thread SELF-ARMS that thread's thread-local
+ *      [`ActivationAmaxCollector`] flag (RAII, AFTER load so no load-time eval
+ *      is recorded), tokenizes each `text` WITHOUT the chat template, truncates
+ *      to `calib_seq` tokens, and runs PREFILL ONLY (no generation) so every
+ *      mxfp8 attn/GDN projection's activation tap fires over realistic raw-text
+ *      activations, resetting caches between rows, then disarms on exit;
+ *   2. ONLY if the full loop succeeded — drains the per-tensor amax and
+ *      ATOMICALLY writes it into `<model_path>/config.json` (temp file +
+ *      `rename`).
+ *
+ * CONCURRENCY: the whole clear→prefill→take→write section is serialized by
+ * [`calib_guard`] (a process-wide `try_lock`); a second concurrent calibration
+ * fails fast with "another calibration is in progress". The arm flag is
+ * thread-local (so a concurrent inference model can't contaminate the run), but
+ * the running-max MAP is process-global, so serializing RUNS keeps two
+ * calibrations from interleaving `record`/`take` on it. The map is CLEARED at
+ * the very start so stale amax from a prior PANICKED run cannot leak into this
+ * write.
+ *
+ * On ANY error before the final write, the partial amax is discarded and
+ * `config.json` is left UNTOUCHED (a failed calibration must not mutate the
+ * live model in place). A run that prefilled ZERO rows (empty dataset, or every
+ * row tokenized to nothing) is likewise an ERROR that leaves `config.json`
+ * untouched — a no-op calibration must not report a silent success. Returns the
+ * number of projections calibrated (the count of collected amax entries); 0
+ * means a real prefill ran but the model exercised no activation-fp8 sites (not
+ * an nvidia-recipe checkpoint), and in that case `config.json` is left
+ * UNCHANGED (no rewrite).
+ */
+export declare function calibrateActivationAmaxRaw(
+  modelPath: string,
+  texts: Array<string>,
+  calibSeq: number,
+): Promise<number>;
+
 /** Unified chat configuration shared by all model variants (Qwen3, Qwen3.5, Qwen3.5 MoE). */
 export interface ChatConfig {
+  /**
+   * Internal logical cache owner. The agent provider forwards Pi's stable
+   * session id so model-global GDN sidecars can retain parent and child
+   * branches independently. This does not namespace the physical paged KV
+   * cache; exact token/extra-key hashes remain shareable across owners.
+   */
+  cacheOwnerId?: string | undefined;
+  /**
+   * Internal top-level owner for the bounded Qwen3.5 GDN sidecar store.
+   * `cache_owner_id` may identify a child Pi session; this separately
+   * identifies the current interactive root so /new and /resume can rotate
+   * the protected branch without changing PagedAttention cache identity.
+   */
+  cacheRootOwnerId?: string | undefined;
   maxNewTokens?: number | undefined;
   temperature?: number | undefined;
   topK?: number | undefined;
@@ -1972,28 +2400,107 @@ export interface ChatConfig {
   repetitionPenalty?: number | undefined;
   /** Size of the context window for repetition penalty (default: 256) */
   repetitionContextSize?: number | undefined;
-  /** Max consecutive identical tokens before stopping (default: 16, 0 = disabled) */
+  /**
+   * 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: 0 = disabled; opt in with a positive value) */
   maxConsecutiveTokens?: number | undefined;
-  /** Max n-gram repetitions before stopping (default: 3, 0 = disabled) */
+  /** Max n-gram repetitions before stopping (default: 0 = disabled; opt in with a positive value) */
   maxNgramRepeats?: number | undefined;
-  /** Max pattern size for n-gram repetition detection (default: 64) */
+  /** Max pattern size for n-gram repetition detection (default: 0 = disabled; opt in with a positive value) */
   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).
+   */
+  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").
    */
-  enableThinking?: boolean | undefined;
+  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;
+  /**
+   * MTP: opt-in flag enabling the Multi-Token Prediction speculative decode
+   * loop (pure-Rust eager; qwen3.5 dense and MoE). Requires the model
+   * checkpoint to carry an MTP head (otherwise silently ignored). Default:
+   * `false`.
+   */
+  enableMtp?: boolean | undefined;
+  /**
+   * MTP: number of draft tokens per speculative cycle.
+   *
+   * On Qwen3.5 native MTP heads it is clamped to `[1, 5]` by the verify
+   * FFI contract, and when unset native code currently pins depth 1.
+   * When `mtpAdaptiveDepth` is `true`, this value is used as the
+   * throughput-policy seed and the expected-value policy's max depth.
+   * Adaptive depth is opt-in; set `mtpAdaptiveDepth: true` explicitly to
+   * enable it.
+   *
+   * Gemma4 external drafts (`draftModelPath`) resolve the field per draft
+   * variant instead (`gemma4/model.rs` `resolve_params`, always from the
+   * RAW config value — the engine's central `[1, 5]` clamp is an MTP-head
+   * contract that does not apply to external drafts):
+   * - DSpark: with both knobs unset, full draft blocks (the checkpoint's
+   *   block size — 7 tokens on `dspark_gemma4_12b_block7`) run behind a
+   *   short target-AR/DSpark break-even calibration. A short generation
+   *   budget that cannot finish calibration retains the fixed-block
+   *   schedule. An explicit
+   *   `mtpDepth` caps and pins the block unless `mtpAdaptiveDepth: true`
+   *   opts the guard back in; explicit `false` disables it.
+   * - Assistant (Google `gemma-4-*-it-assistant`): an unset `mtpDepth`
+   *   drafts 3 tokens per cycle (`ASSISTANT_DEFAULT_DEPTH`), and an
+   *   explicit `mtpDepth` clamps to `[1, 8]` (`ASSISTANT_MAX_DEPTH`).
+   *
+   * `mtpAdaptiveDepth` is ignored for the Gemma4 assistant variant.
+   */
+  mtpDepth?: number | undefined;
+  /**
+   * MTP: when true, the decode loop runs the adaptive
+   * depth policy. Default mode is a per-depth EMA hill-climb plus
+   * DFlash-style 3-state machine `full | reduced | probe`.
+   * `MLX_MTP_ADAPTIVE_DEPTH_MODE=expected-value` instead uses the
+   * MTPLX-style intra-cycle expected-value gate, which deepens toward
+   * `mtpDepth` by default (T=0 byte-parity verified); set
+   * `MLX_MTP_EV_ALLOW_DEEPEN=0` to pin the base depth.
+   * When false, the loop pins `mtpDepth` for every cycle.
+   *
+   * Default: false, except Gemma4 DSpark enables its measured break-even
+   * guard when both this field and `mtpDepth` are unset. An explicit value
+   * always wins over the family default.
+   */
+  mtpAdaptiveDepth?: boolean | undefined;
 }
 
 /** Chat message with tool calling support */
@@ -2006,10 +2513,40 @@ export interface ChatMessage {
   toolCalls?: Array<ToolCall>;
   /** Tool call ID this message is responding to (for tool messages) */
   toolCallId?: string;
+  /**
+   * Whether this tool-role message represents an errored tool result.
+   *
+   * Authoritative, structured signal of tool-call failure. Set to
+   * `Some(true)` when the caller (e.g. the Anthropic
+   * `tool_result.is_error === true` translator) wants the model to
+   * treat the tool output as an error. The renderer prepends a short
+   * `[tool error]` prefix to `content` when emitting the wire-format
+   * tool response so the model receives a clear text-level cue, but
+   * the original `content` stays byte-for-byte intact in the
+   * structured form — no JSON wrapping, no in-band marker that could
+   * collide with a successful tool result whose literal content
+   * happens to start with the same prefix.
+   *
+   * `None` / `Some(false)` produce the unmarked wire format.
+   */
+  isError?: boolean;
   /** Reasoning content for thinking mode (used with <think> tags) */
   reasoningContent?: string;
+  /**
+   * Thinking mode used when this assistant message was generated.
+   *
+   * This is replay provenance, not a request override. Gemma4's disabled-
+   * thinking generation prefix contains an explicit empty thought channel,
+   * while an enabled-thinking turn that emitted no reasoning contains no
+   * such channel. Keeping the historical mode on the message lets the chat
+   * template reproduce either byte sequence even when a later request
+   * changes its current thinking setting.
+   */
+  thinkingEnabled?: boolean;
   /** Image data for VLM models (encoded image bytes: PNG/JPEG, passed as Uint8Array/Buffer) */
   images?: Array<Uint8Array> | undefined;
+  /** Audio data for unified Gemma 4 (encoded audio bytes: WAV, passed as Uint8Array/Buffer) */
+  audio?: Array<Uint8Array> | undefined;
 }
 
 /** Unified chat result shared by all model variants (Qwen3, Qwen3.5, Qwen3.5 MoE). */
@@ -2018,8 +2555,21 @@ export interface ChatResult {
   toolCalls: Array<ToolCallResult>;
   thinking?: string;
   numTokens: number;
+  promptTokens: number;
+  reasoningTokens: number;
   finishReason: string;
   rawText: string;
+  /**
+   * Number of prompt tokens served from the reused KV-cache prefix.
+   *
+   * When the native prefix-cache machinery successfully matches the new
+   * prompt against the cached conversation history (via
+   * `verify_cache_prefix_direct`), only the trailing delta is re-prefilled
+   * and this field reports the length of the reused prefix. `0` when
+   * the cache was missed or disabled and the full prompt had to be
+   * re-prefilled.
+   */
+  cachedTokens: number;
   /** Performance metrics (present when `reportPerformance: true` in config) */
   performance?: PerformanceMetrics;
 }
@@ -2044,9 +2594,30 @@ export interface ChatStreamChunk {
   toolCalls?: Array<ToolCallResult>;
   thinking?: string;
   numTokens?: number;
+  promptTokens?: number;
+  reasoningTokens?: number;
   rawText?: string;
+  /**
+   * Number of prompt tokens served from the reused KV-cache prefix on
+   * this turn. Populated on the terminal chunk (`done == true`) only;
+   * `None` on mid-stream delta chunks.
+   *
+   * Zero on a cache miss or disabled reuse; equal to the matched
+   * prefix length on a hit. Mirrors `ChatResult.cached_tokens`
+   * verbatim so session-aware streaming consumers can observe
+   * prefix-cache reuse without round-tripping to the non-streaming
+   * path. Non-terminal chunks always carry `None` — only the
+   * terminal chunk is authoritative.
+   */
+  cachedTokens?: number | undefined;
   /** 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. */
@@ -2109,7 +2680,11 @@ export interface ConversionOptions {
   quantBits?: number;
   /** Quantization group size (default: 64 for affine, 32 for mxfp8) */
   quantGroupSize?: number;
-  /** Quantization mode: "affine" (default) or "mxfp8" */
+  /**
+   * Quantization mode: "affine" (default), "mxfp4", "mxfp8", "nvfp4", or
+   * "sym8" (per-output-channel symmetric int8; qwen3_5 + qwen3_5_moe + lfm2/lfm2_moe + gemma4,
+   * implies bits=8, no group_size — consciously NOT mlx-lm-loadable)
+   */
   quantMode?: string;
   /**
    * Quantization recipe for per-layer mixed-bit quantization.
@@ -2121,6 +2696,35 @@ export interface ConversionOptions {
    * Improves quantization quality by amplifying important weight channels.
    */
   imatrixPath?: string;
+  /**
+   * Upgrade quantization to micro-scaling FP (mxfp4 / mxfp8).
+   * When true, applies after the recipe predicate: eligible 8-bit affine
+   * decisions become mxfp8 and 4-bit become mxfp4. Kept affine (not upgraded):
+   * affine-only loaders (lm_head, embed_tokens, router.proj,
+   * embedding_projection) at their recipe bits, MoE router gates (8-bit affine),
+   * and the recipe-pinned attention/GDN projections (o_proj / out_proj /
+   * in_proj_a / in_proj_b, 8-bit affine). Requires `quant_mode = "affine"`.
+   * Forces `group_size = 32` for upgraded layers.
+   */
+  quantMxfp?: boolean;
+  /**
+   * Optional Qwen MTP quantization policy: "off" (default), "cyankiwi", "all",
+   * or "split" (alias "drafter").
+   * "cyankiwi" keeps mtp.fc dense and quantizes only the MTP layer linears as
+   * 4-bit affine group_size=32. For dense `qwen3_5` the quantized linears are
+   * emitted into an MTPLX-compatible mtp.safetensors sidecar; for MoE
+   * (`qwen3_5_moe`) there is no sidecar — they are quantized in place and stored
+   * inline in the main safetensors shards.
+   * "all" additionally quantizes mtp.fc. For dense `qwen3_5` the quantized MTP
+   * linears land in the mtp.safetensors sidecar; for MoE (`qwen3_5_moe`) there
+   * is no sidecar — they are quantized in place and stored inline in the main
+   * safetensors shards.
+   * "split"/"drafter" emits a body checkpoint with NO mtp.* tensors plus a
+   * separate `mtp-drafter/` directory in mlx-vlm's `qwen3_5_mtp` format
+   * (bare-keyed MTP head, format:mlx). It does NOT require --quantize/--q-recipe;
+   * the body may be bf16 or already-quantized and the MTP head stays bf16.
+   */
+  quantMtp?: string;
 }
 
 export interface ConversionResult {
@@ -2174,6 +2778,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 model thread whose init runs
+ * [`create_random_qwen35_moe_checkpoint_sync`] (random-init inner + save);
+ * the thread holds no state and is dropped once the promise resolves, so
+ * the in-memory model is released as soon as 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;
@@ -2208,6 +2851,8 @@ export declare const enum DType {
   BFloat16 = 3,
   Uint32 = 4,
   Uint8 = 5,
+  /** Signed int8 — sym8 per-output-channel symmetric quantized weights. */
+  Int8 = 6,
 }
 
 /** Document element type */
@@ -2290,14 +2935,186 @@ export interface FunctionDefinition {
   parameters?: FunctionParameters;
 }
 
-/** Function parameters schema (JSON Schema subset) */
-export interface FunctionParameters {
-  /** Type (usually "object") */
-  type: string;
-  /** JSON string of property definitions */
-  properties?: string;
-  /** List of required parameter names */
-  required?: Array<string>;
+/** Function parameters schema (JSON Schema subset) */
+export interface FunctionParameters {
+  /** Type (usually "object") */
+  type: string;
+  /** JSON string of property definitions */
+  properties?: string;
+  /** List of required parameter names */
+  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;
+  /**
+   * True for the unified multimodal Gemma 4 checkpoint
+   * (`model_type == "gemma4_unified"` or
+   * `architectures[0] == "Gemma4UnifiedForConditionalGeneration"`).
+   * The text decoder is shared, but the unified checkpoint carries
+   * vision/audio embedder weights that must be dropped in a text-only load.
+   */
+  isUnified: boolean;
+  /**
+   * `text_config.use_bidirectional_attention` from the unified checkpoint
+   * (e.g. `"vision"`). Parsed for a stable struct surface; the text-only
+   * decode path does not consume it.
+   */
+  useBidirectionalAttention?: string;
+  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;
+  /**
+   * Encoder-free vision config for the unified multimodal checkpoint.
+   * `Some` only when `is_unified` and the checkpoint carries a
+   * `vision_config` sub-dict. Disjoint from `vision_config` (the SigLIP
+   * path) — the unified vision embedder is built from this instead.
+   */
+  unifiedVisionConfig?: UnifiedVisionConfig;
+  imageTokenId?: number;
+  boiTokenId?: number;
+  eoiTokenId?: number;
+  visionSoftTokensPerImage?: number;
+  /**
+   * True when the checkpoint declares an `audio_config` sub-dict. Parallels
+   * `unified_vision_config.is_some()`; gates the un-drop + load of
+   * `embed_audio` weights and the audio merge path.
+   */
+  hasAudio: boolean;
+  /**
+   * Audio placeholder token id (258881). Each `<audio>` placeholder expands to
+   * `boa + audio_token × n_frames + eoa`.
+   */
+  audioTokenId?: number;
+  /** Begin-of-audio token id (256000), emitted before the audio token run. */
+  boaTokenId?: number;
+  /**
+   * End-of-audio token id, parsed from the config's `eoa_token_index` (258883).
+   * A real appended token (like `eoi`), despite the "index" name.
+   */
+  eoaTokenId?: number;
+  /**
+   * Raw audio samples per audio token (640 = 40 ms @ 16 kHz), from
+   * `audio_config.audio_samples_per_token`. Frame size for the encoder-free
+   * pad+reshape feature extractor.
+   */
+  audioSamplesPerToken?: number;
+  /**
+   * GPU memory budget for paged KV cache in megabytes.
+   * Only used when `use_block_paged_cache` is true.
+   * Default: auto-sized to cover `max_position_embeddings` for the
+   * physical full-attention layers.
+   */
+  pagedCacheMemoryMb?: number | undefined;
+  /**
+   * Block size for paged attention (tokens per block).
+   * Only used when `use_block_paged_cache` is true.
+   * Default: 16.
+   */
+  pagedBlockSize?: number | undefined;
+  /**
+   * Use the new block-paged KV cache adapter (`PagedKVCacheAdapter`).
+   *
+   * When `Some(true)` or unset (the default), `Gemma4Inner` builds
+   * model-independent KV-cache specs, groups them, and allocates a
+   * `BlockAllocator` + `LayerKVPool` pair for physical full-attention
+   * layers. Sliding-window layers still use `RotatingKVCache` until
+   * true paged sliding-window groups are wired. KV-shared layers are
+   * aliases: they reuse their anchor's cache slot and do not allocate
+   * separate physical storage.
+   *
+   * Default: `true` (paged adapter on; opt-out via
+   * `use_block_paged_cache: false` in `config.json` to use the flat
+   * (non-paged) all-`Gemma4LayerCache` path instead). Parity between
+   * the two paths is verified by
+   * `crates/mlx-core/tests/gemma4_paged_vs_flat_parity.rs` against
+   * real Gemma-4-E2B weights.
+   */
+  useBlockPagedCache?: boolean | undefined;
+}
+
+/** Optional load-time settings for [`Gemma4Model::load`]. */
+export interface Gemma4LoadOptions {
+  /**
+   * Directory of a draft checkpoint (config.json + safetensors) to load
+   * alongside the target model for speculative decoding — either a
+   * DSpark draft or a Google assistant draft; the kind is probed from
+   * the draft config.json. When omitted, `<model_path>/draft/` is loaded
+   * automatically when present. Draft decoding runs only on the flat
+   * KV-cache path: setting this while the model config explicitly enables
+   * `use_block_paged_cache` is a hard load error, and an unset
+   * `use_block_paged_cache` is forced to `false`.
+   */
+  draftModelPath?: string;
+}
+
+/**
+ * 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 */
@@ -2334,19 +3151,33 @@ export interface GenerationConfig {
    */
   repetitionContextSize?: number;
   /**
-   * Stop if same token repeats this many times consecutively (default: 16)
-   * Set to 0 to disable. Prevents OOM from degenerate repetitive generation.
+   * 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: 0 = disabled).
+   * Opt in by setting a positive value to guard against degenerate repetitive generation.
    */
   maxConsecutiveTokens?: number;
   /**
-   * Stop if a pattern repeats this many times consecutively (default: 3)
-   * Set to 0 to disable. Detects patterns like "A B A B A B".
+   * Stop if a pattern repeats this many times consecutively (default: 0 = disabled).
+   * Opt in with a positive value to detect patterns like "A B A B A B".
    * Uses range-based detection: checks all pattern sizes from 2 to ngram_size.
    */
   maxNgramRepeats?: number;
   /**
-   * Maximum pattern size for repetition detection (default: 64)
-   * All pattern sizes from 2 up to this value are checked each decode step.
+   * Maximum pattern size for repetition detection (default: 0 = disabled).
+   * When enabled, all pattern sizes from 2 up to this value are checked each decode step.
    * Larger values catch long phrase-level repetition common in small models.
    */
   ngramSize?: number;
@@ -2361,29 +3192,6 @@ export interface GenerationConfig {
    * Set to 0 to disable chunking and process the entire prompt at once.
    */
   prefillStepSize?: number;
-  /**
-   * KV cache quantization bits (default: 16 = no quantization)
-   * - 16: Full precision (bfloat16/float16), no quantization
-   * - 8: 8-bit quantization, ~2x memory savings, minimal quality loss
-   * - 4: 4-bit quantization, ~4x memory savings, some quality degradation
-   *
-   * Quantized KV cache is useful for long sequences where memory becomes a bottleneck.
-   * Note: Adds dequantization overhead per forward pass.
-   */
-  kvCacheBits?: number;
-  /**
-   * KV cache quantization group size (default: 64)
-   * Number of elements per quantization group. Smaller groups = better accuracy
-   * but more overhead from storing scales/biases.
-   * Only used when kv_cache_bits is 4 or 8.
-   */
-  kvCacheGroupSize?: number;
-  /**
-   * Number of draft tokens to generate speculatively (default: 5)
-   * Only used when a draft model is provided for speculative decoding.
-   * Higher values can increase throughput but may reduce acceptance rate.
-   */
-  numDraftTokens?: number;
 }
 
 export interface GenerationProfile {
@@ -2407,6 +3215,24 @@ export interface GenerationProfile {
   timeToFirstTokenMs: number;
   /** Per-phase breakdown. */
   phases: Array<PhaseProfile>;
+  /**
+   * MTP speculative decode: mean accepted *draft* tokens per cycle
+   * (excludes the always-verified token). Historical drafts-only metric.
+   */
+  mtpMeanAcceptedTokens?: number;
+  /**
+   * MTP speculative decode: mean *committed* tokens per cycle, INCLUDING
+   * the always-verified token (`mtp_accepted_drafts_total / mtp_cycles
+   * + 1.0`). mlx-vlm-comparable headline; equals mlx-vlm's
+   * `(accepted_drafts + rounds) / rounds` (`common.py:247`).
+   */
+  mtpMeanAcceptedTokensTotal?: number;
+  /** MTP speculative decode: per-draft-position acceptance rate. */
+  mtpAcceptanceByPosition?: Array<number>;
+  /** MTP speculative decode: number of draft+verify cycles executed. */
+  mtpCycles?: number;
+  /** MTP speculative decode: mean attempted draft depth per cycle. */
+  mtpMeanDepth?: number;
   /** Memory snapshot before generation. */
   memoryBefore?: MemorySnapshot;
   /** Memory snapshot after generation. */
@@ -2433,8 +3259,8 @@ export interface GenerationWithToolCalls {
   toolCalls: Array<ToolCallRecord>;
 }
 
-/** Get expected weight keys for PaddleOCR-VL model */
-export declare function getExpectedWeightKeys(): Array<string>;
+/** Sample MLX's GPU memory counters. See [`GpuMemorySnapshot`]. */
+export declare function getMemorySnapshot(): GpuMemorySnapshot;
 
 /** Retrieve all collected profiling data as a `ProfilingSession`. */
 export declare function getProfilingData(): ProfilingSession;
@@ -2444,6 +3270,13 @@ export interface GgufConversionOptions {
   inputPath: string;
   /** Output directory for converted SafeTensors model */
   outputDir: string;
+  /**
+   * Optional directory containing the authoritative HuggingFace config and
+   * tokenizer/processor assets. GGUF metadata is not rich enough to recreate
+   * unified Gemma4 config fields such as head_dim, layer_types, vision, and
+   * audio configuration exactly.
+   */
+  configSourceDir?: string;
   /** Target dtype: "float32", "float16", "bfloat16" (default: keep original) */
   dtype?: string;
   /** Enable verbose logging */
@@ -2477,6 +3310,17 @@ export interface GgufConversionOptions {
    * This makes the safetensors compatible with mlx-vlm.
    */
   vlmKeyPrefix?: boolean;
+  /**
+   * Upgrade quantization to micro-scaling FP (mxfp4 / mxfp8).
+   * When true, applies after the recipe predicate: eligible 8-bit affine
+   * decisions become mxfp8 and 4-bit become mxfp4. Kept affine (not upgraded):
+   * affine-only loaders (lm_head, embed_tokens, router.proj,
+   * embedding_projection) at their recipe bits, MoE router gates (8-bit affine),
+   * and the recipe-pinned attention/GDN projections (o_proj / out_proj /
+   * in_proj_a / in_proj_b, 8-bit affine). Requires `quant_mode = "affine"`.
+   * Forces `group_size = 32` for upgraded layers.
+   */
+  quantMxfp?: boolean;
 }
 
 export interface GgufConversionResult {
@@ -2492,6 +3336,33 @@ export interface GpuInfo {
   architectureGen: number;
 }
 
+/**
+ * Snapshot of MLX's GPU memory counters at this instant. All values
+ * are in bytes. On Apple Silicon, GPU and CPU share unified memory,
+ * so these are NOT a separate "VRAM" pool — they reflect MLX's own
+ * tracking of `StorageModePrivate` Metal buffers (model weights,
+ * `LayerKVPool`, transient intermediate tensors) attributed to the
+ * MLX runtime in this process.
+ *
+ * Useful for live observability during long-running sessions:
+ *
+ * ```js
+ * const { getMemorySnapshot } = require('@mlx-node/core');
+ * setInterval(() => {
+ *   const m = getMemorySnapshot();
+ *   console.log(`active=${(m.activeBytes/1e9).toFixed(2)}GB peak=${(m.peakBytes/1e9).toFixed(2)}GB cache=${(m.cacheBytes/1e9).toFixed(2)}GB`);
+ * }, 1000);
+ * ```
+ */
+export interface GpuMemorySnapshot {
+  /** Current actively-used GPU buffer bytes (excludes cache pool). */
+  activeBytes: number;
+  /** Peak GPU buffer bytes since the last `resetPeakMemory()` call. */
+  peakBytes: number;
+  /** Bytes held in MLX's caching allocator (released by `clearCache`). */
+  cacheBytes: number;
+}
+
 /** Configuration for the GRPO training engine */
 export interface GrpoEngineConfig {
   /** Learning rate (default: 1e-6) */
@@ -2526,6 +3397,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 +3540,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 +3597,98 @@ 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;
+  /**
+   * GPU memory budget for paged KV cache in megabytes.
+   * Only used when `use_block_paged_cache` is true.
+   * Default: 2048 (2GB).
+   */
+  pagedCacheMemoryMb?: number | undefined;
+  /**
+   * Block size for paged attention (tokens per block).
+   * Only used when `use_block_paged_cache` is true.
+   * Default: 16.
+   */
+  pagedBlockSize?: number | undefined;
+  /**
+   * Use the new block-paged KV cache adapter (`PagedKVCacheAdapter`).
+   *
+   * Default: `true` since 2026-04-28 (parity-verified via
+   * `crates/mlx-core/tests/lfm2_paged_vs_flat_parity.rs` against real
+   * LFM2.5-1.2B weights: byte-equal greedy decode + prefix-reuse
+   * byte-equal at BF16). Wired through
+   * `Lfm2DecoderLayer::forward_paged_or_flat`.
+   *
+   * Per-layer routing: LFM2's hybrid architecture means only
+   * `full_attention` layers go through the paged adapter; conv layers
+   * stay on the existing flat `Lfm2LayerCache::Conv(ArraysCache)`
+   * storage regardless of this flag. The `LayerKVPool` is sized to
+   * the count of `full_attention` layers and indexed by
+   * attention-ordinal (via `config.full_attn_idxs()`), not by absolute
+   * layer index.
+   *
+   * Opt out with `use_block_paged_cache: Some(false)` to revert to the
+   * fully flat `Lfm2LayerCache` path on all layers.
+   */
+  useBlockPagedCache?: boolean | undefined;
+  /**
+   * MLP intermediate size for the DENSE-in-MoE layers (`layer_idx <
+   * num_dense_layers`). Used DIRECTLY (no 2/3 `computed_ff_dim()` shrink).
+   * Only present on MoE checkpoints.
+   */
+  intermediateSize?: number | undefined;
+  /** Per-expert MLP intermediate size for the sparse MoE layers. */
+  moeIntermediateSize?: number | undefined;
+  /** Total number of routed experts. */
+  numExperts?: number | undefined;
+  /** Top-k experts selected per token. */
+  numExpertsPerTok?: number | undefined;
+  /** Number of leading DENSE layers before MoE layers begin. */
+  numDenseLayers?: number | undefined;
+  /**
+   * Renormalize the top-k routing weights to sum to 1 (`/(sum+1e-20)`).
+   *
+   * `Option<bool>` so TS callers may omit it (napi renders bare `bool` as
+   * required). Absent (None) is read as `true` everywhere via
+   * `.unwrap_or(true)`, matching the prior `default = "default_true"`.
+   */
+  normTopkProb?: boolean | undefined;
+  /**
+   * Add the learned per-expert bias to the post-softmax gates BEFORE top-k.
+   *
+   * `Option<bool>` so TS callers may omit it (napi renders bare `bool` as
+   * required). Absent (None) is read as `true` everywhere via
+   * `.unwrap_or(true)`, matching the prior `default = "default_true"`.
+   */
+  useExpertBias?: boolean | undefined;
+}
+
 export interface MemorySnapshot {
   /** Active (non-cached) memory in bytes. */
   activeBytes: number;
@@ -2685,6 +3698,28 @@ export interface MemorySnapshot {
   cacheBytes: number;
 }
 
+/**
+ * Return a snapshot of the MLX allocator's memory counters. Primarily
+ * useful for dashboards and for debugging the `MLX_CACHE_LIMIT_GB`
+ * override. Read-only — does not mutate allocator state.
+ */
+export declare function memoryStats(): MemoryStats;
+
+/**
+ * Snapshot of the MLX Metal allocator's memory state. All values are in
+ * bytes and returned as `f64` to avoid forcing BigInt round-trips in JS.
+ */
+export interface MemoryStats {
+  /** Actively-used memory (excludes the cached free-pool). */
+  active: number;
+  /** Peak memory usage since load / the last `resetPeakMemory`. */
+  peak: number;
+  /** Cache / free-pool memory currently held by the allocator. */
+  cache: number;
+  /** Metal `max_recommended_working_set_size` snapshot (0 on non-Metal). */
+  wiredLimit: number;
+}
+
 /** Full model configuration */
 export interface ModelConfig {
   visionConfig: VisionConfig;
@@ -2728,56 +3763,6 @@ export interface OutputStoreConfig {
   localPath: string;
 }
 
-/** Paged attention memory statistics (NAPI-compatible) */
-export interface PagedCacheStats {
-  /** Total number of blocks in the pool */
-  totalBlocks: number;
-  /** Number of free blocks */
-  freeBlocks: number;
-  /** Number of allocated blocks */
-  allocatedBlocks: number;
-  /** Total memory in MB */
-  totalMemoryMb: number;
-  /** Used memory in MB */
-  usedMemoryMb: number;
-  /** Utilization percentage */
-  utilizationPercent: number;
-}
-
-/** A completed sequence from paged generation */
-export interface PagedCompletedSequence {
-  /** Original request ID */
-  requestId: string;
-  /** All generated tokens (excluding prompt) */
-  tokens: Array<number>;
-  /** Reason for completion ("stop", "length", "repetition", "tool_calls") */
-  finishReason: string;
-}
-
-/** Result of a paged generation step */
-export interface PagedGenerationStep {
-  /** Token outputs for each sequence in the batch */
-  outputs: Array<PagedTokenOutput>;
-  /** Number of sequences that were in prefill phase */
-  numPrefill: number;
-  /** Number of sequences that were in decode phase */
-  numDecode: number;
-}
-
-/** Output from a single token generation step in paged attention */
-export interface PagedTokenOutput {
-  /** Sequence ID in the scheduler */
-  seqId: number;
-  /** Request ID for this sequence */
-  requestId: string;
-  /** Generated token ID */
-  token: number;
-  /** Log probability of the token (f64 for NAPI compatibility) */
-  logprob: number;
-  /** Whether this sequence has finished */
-  isFinished: boolean;
-}
-
 /** A text paragraph */
 export interface Paragraph {
   content: string;
@@ -2859,6 +3844,52 @@ export interface PerformanceMetrics {
    * Excludes the first token (counted as prefill).
    */
   decodeTokensPerSecond: number;
+  /**
+   * MTP speculative decode: mean accepted *draft* tokens per cycle
+   * (range `[0, depth]`). EXCLUDES the always-verified token each cycle
+   * commits. `None` on plain autoregressive runs where no MTP cycle
+   * executed. This is the historical drafts-only metric; for the
+   * mlx-vlm-comparable headline see [`Self::mtp_mean_accepted_tokens_total`].
+   */
+  mtpMeanAcceptedTokens?: number;
+  /**
+   * MTP speculative decode: mean *committed* tokens per cycle, INCLUDING
+   * the single always-verified token each cycle emits — i.e.
+   * `mtp_accepted_drafts_total / mtp_cycles + 1.0`. This is the
+   * mlx-vlm-comparable headline accept rate: it equals mlx-vlm's
+   * `mean_accepted_tokens = (accepted_drafts + rounds) / rounds`
+   * (`mlx-vlm/mlx_vlm/speculative/common.py:247`), where our
+   * `mtp_cycles` is the 1:1 analog of mlx-vlm's `rounds` (one
+   * draft+verify iteration; `record_mtp_cycle` is called exactly once
+   * per cycle). The per-cycle `+1.0` matches mlx-vlm's `+rounds`
+   * assumption — every round commits exactly one verified token
+   * (the residual on partial-accept, the bonus on full-accept), even
+   * when the final cycle's tail is EOS/length-truncated downstream
+   * (mlx-vlm makes the same assumption: it appends to `accept_lens`
+   * once per round regardless of truncation). `None` on plain
+   * autoregressive runs.
+   */
+  mtpMeanAcceptedTokensTotal?: number;
+  /**
+   * MTP speculative decode: per-draft-position acceptance rate
+   * (index = draft position). `None` on plain autoregressive runs.
+   */
+  mtpAcceptanceByPosition?: Array<number>;
+  /**
+   * MTP speculative decode: number of draft+verify cycles executed.
+   * `None` on plain autoregressive runs.
+   */
+  mtpCycles?: number;
+  /**
+   * MTP speculative decode: mean attempted draft depth per cycle.
+   * `None` on plain autoregressive runs.
+   */
+  mtpMeanDepth?: number;
+  /**
+   * Optional decode phase breakdown. Present when decode profiling
+   * is enabled via `MLX_PROFILE_DECODE=1` or `setProfilingEnabled(true)`.
+   */
+  profilePhases?: Array<PhaseProfile>;
 }
 
 export interface PhaseProfile {
@@ -2872,6 +3903,76 @@ export interface PhaseProfile {
   count: number;
 }
 
+/**
+ * Per-call Viterbi calibration overrides.
+ *
+ * Any field set to `Some(_)` overrides the corresponding bias from the
+ * model's default calibration (loaded from `viterbi_calibration.json`
+ * at load time). Missing fields fall back to the default.
+ */
+export interface PrivacyCalibration {
+  transitionBiasBackgroundStay?: number;
+  transitionBiasBackgroundToStart?: number;
+  transitionBiasEndToBackground?: number;
+  transitionBiasEndToStart?: number;
+  transitionBiasInsideToContinue?: number;
+  transitionBiasInsideToEnd?: number;
+}
+
+/**
+ * Options for [`PrivacyFilterModelJs::classify`].
+ *
+ * - `threshold` (default `0.5`): minimum mean per-token probability for
+ *   an extracted span to be returned.
+ * - `calibration`: per-call overrides on top of the checkpoint default.
+ * - `return_tokens` (default `false`): when `true`, the result includes
+ *   a `tokens` array with one entry per input token.
+ */
+export interface PrivacyClassifyOptions {
+  threshold?: number;
+  calibration?: PrivacyCalibration;
+  returnTokens?: boolean;
+}
+
+/** Result of [`PrivacyFilterModelJs::classify`]. */
+export interface PrivacyClassifyResult {
+  entities: Array<PrivacyEntity>;
+  tokens?: Array<PrivacyToken>;
+}
+
+/**
+ * A privacy entity detected by [`PrivacyFilterModelJs::classify`].
+ *
+ * `start`/`end` are byte offsets into the input string (Hugging Face
+ * `tokenizers` convention). `label` is the privacy class without the
+ * BIOES prefix (e.g. `"private_email"`). `score` is the mean — across
+ * the span's tokens — of the softmax probability of the Viterbi-emitted
+ * tag at each token.
+ */
+export interface PrivacyEntity {
+  label: string;
+  start: number;
+  end: number;
+  score: number;
+  text: string;
+}
+
+/**
+ * Per-token output emitted when [`PrivacyClassifyOptions::return_tokens`]
+ * is `true`. `tag` is the full BIOES tag (`"O"` or `"B-..."`/`"I-..."`/
+ * `"E-..."`/`"S-..."`) chosen by the Viterbi decoder. `score` is the
+ * softmax probability of that emitted tag at this token, so `tag` and
+ * `score` always share decoders (at boundary tokens the Viterbi tag can
+ * differ from the local argmax).
+ */
+export interface PrivacyToken {
+  text: string;
+  tag: string;
+  score: number;
+  start: number;
+  end: number;
+}
+
 export interface ProfilingSession {
   /** GPU hardware info. */
   gpuInfo: GpuInfo;
@@ -2896,6 +3997,55 @@ 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;
+}
+
+/** Microbench result for the production quantized qmv dispatch path. */
+export interface QmvQuantizedMicrobenchResult {
+  /** Median `quantized_matmul` wall-clock per call, in nanoseconds. */
+  medianNs: number;
+  /** A tiny materialized checksum of the final output, used to keep the call live. */
+  checksum: number;
+}
+
+/**
+ * Run the production quantized-qmv microbench in the current process.
+ *
+ * To compare `MLX_MTP_SMALL_M_QMV=0` versus `1`, call this from separate
+ * processes. MLX caches the env-backed dispatch predicate statically.
+ */
+export declare function quantizedQmvMicrobench(
+  k: number,
+  n: number,
+  m: number,
+  groupSize: number,
+  bits: number,
+  mode: string,
+  dtype: DType,
+  warmup?: number | undefined | null,
+  iters?: number | undefined | null,
+): QmvQuantizedMicrobenchResult;
+
 /**
  * Qwen3.5 model configuration (dense variant).
  *
@@ -2924,6 +4074,72 @@ export interface Qwen35Config {
   fullAttentionInterval: number;
   partialRotaryFactor: number;
   ropeTheta: number;
+  /**
+   * GPU memory budget for paged KV cache in megabytes.
+   * Only used when `use_block_paged_cache` is true.
+   * Default: automatically sized for one full-context sequence.
+   */
+  pagedCacheMemoryMb?: number | undefined;
+  /**
+   * Block size for paged attention (tokens per block).
+   * Only used when `use_block_paged_cache` is true.
+   * Default: 16.
+   */
+  pagedBlockSize?: number | undefined;
+  /**
+   * Use the block-paged KV cache adapter (`PagedKVCacheAdapter`) for
+   * full-attention layers.
+   *
+   * **OPT-IN — experimental.** When `Some(true)`, `Qwen35Inner`
+   * allocates a `BlockAllocator` + `LayerKVPool` pair sized for the
+   * model's full-attention layer count and constructs a
+   * `PagedKVCacheAdapter`. The chat-session forward dispatch routes
+   * full-attention layers through this adapter while linear-attention
+   * (GatedDeltaNet / GDN) layers continue to use the existing
+   * `Qwen3_5LayerCache::Linear(ArraysCache)` path with no
+   * cross-request prefix reuse — vLLM's `MambaManager`-style "no
+   * prefix reuse for recurrent layers" stance.
+   *
+   * **Paged vs flat eager**: this flag selects the eager paged decode
+   * over the eager flat decode. When `Some(true)`, full-attention
+   * layers run through the paged adapter (cross-request prefix reuse);
+   * when unset, they run the eager flat decode. Either way the forward
+   * is pure-Rust eager.
+   *
+   * **VLM under paged**: a VLM checkpoint defaults this flag ON at load, so
+   * dense image turns ONLY run on the paged-vision core. A fresh single-turn
+   * image-bearing prompt prefills through the paged adapter (M-RoPE positions
+   * feed the rotary; the merged vision embeddings feed the forward) and
+   * decodes plain AR — MTP weights are ignored on image turns. Warm
+   * image-bearing session continues / cache-hit reuse are still rejected at
+   * runtime (the GDN two-pass warm prefix is not byte-exact). A vision turn
+   * that reaches a None adapter (explicit `Some(false)`, non-Metal build, or
+   * a sym8 checkpoint) errors at dispatch.
+   *
+   * Default: `None` for text-only checkpoints (eager flat decode);
+   * `Some(true)` for VLM checkpoints (block-paged, set in `parse_config`).
+   */
+  useBlockPagedCache?: boolean | undefined;
+  /**
+   * Number of MTP (Multi-Token Prediction) head layers shipped with the
+   * checkpoint. Populated from `mtp_num_hidden_layers` /
+   * `num_nextn_predict_layers` in `config.json`. `0` means the
+   * checkpoint has no MTP heads and the speculative-decode path is
+   * unavailable.
+   */
+  nMtpLayers: number;
+}
+
+/**
+ * Trained and physically available active-context limits for one loaded
+ * Qwen3.5 model. Values are snapshots because the physical pool is fixed for
+ * the lifetime of the resident model.
+ */
+export interface Qwen35ContextLimits {
+  trainedWindowTokens: number;
+  effectiveWindowTokens: number;
+  pagedBlockCapacity: number;
+  pagedBlockSize: number;
 }
 
 /** Generation configuration for Qwen3.5 */
@@ -2978,6 +4194,47 @@ export interface Qwen35MoeConfig {
   moeIntermediateSize?: number | undefined;
   normTopkProb: boolean;
   mlpOnlyLayers?: number[] | undefined;
+  /**
+   * GPU memory budget for paged KV cache in megabytes.
+   * Only used when `use_block_paged_cache` is true.
+   * Default: automatically sized for one full-context sequence.
+   */
+  pagedCacheMemoryMb?: number | undefined;
+  /**
+   * Block size for paged attention (tokens per block).
+   * Only used when `use_block_paged_cache` is true.
+   * Default: 16.
+   */
+  pagedBlockSize?: number | undefined;
+  /**
+   * Use the block-paged KV cache adapter for full-attention layers.
+   *
+   * **OPT-IN — experimental.** Same semantics as the dense
+   * `Qwen3_5Config::use_block_paged_cache` field. Selects the eager
+   * paged decode over the eager flat decode: routes full-attention
+   * layers through `PagedKVCacheAdapter` (cross-request prefix reuse);
+   * GDN linear-attention layers stay on `Qwen3_5LayerCache::Linear`
+   * either way. When disabled, full-attention layers run the eager flat
+   * decode instead.
+   *
+   * **VLM under paged**: a VLM checkpoint loads with this flag set, and a
+   * fresh single-turn image-bearing prompt prefills through the paged
+   * adapter (M-RoPE positions feed the rotary; the merged vision embeddings
+   * feed the forward). Image-bearing MTP turns are still rejected at
+   * runtime; warm image-bearing session continues / cache-hit reuse are
+   * cold-started (no warm GDN two-pass prefix).
+   *
+   * Default: `None` / `false`.
+   */
+  useBlockPagedCache?: boolean | undefined;
+  /**
+   * Number of MTP (Multi-Token Prediction) head layers shipped with
+   * the checkpoint. Populated from `mtp_num_hidden_layers` /
+   * `num_nextn_predict_layers` in `config.json`. `0` means the
+   * checkpoint has no MTP heads and the speculative-decode path is
+   * unavailable.
+   */
+  nMtpLayers: number;
 }
 
 /** Generation configuration for Qwen3.5 MoE */
@@ -3014,29 +4271,45 @@ export interface Qwen3Config {
   padTokenId: number;
   eosTokenId: number;
   bosTokenId: number;
-  /**
-   * Enable paged attention for memory-efficient inference.
-   * Default: false (use standard KVCache)
-   */
-  usePagedAttention?: boolean | undefined;
   /**
    * GPU memory budget for paged KV cache in megabytes.
-   * Only used when use_paged_attention is true.
    * Default: 2048 (2GB)
    */
   pagedCacheMemoryMb?: number | undefined;
   /**
    * Block size for paged attention (tokens per block).
-   * Only used when use_paged_attention is true.
    * Default: 16
    */
   pagedBlockSize?: number | undefined;
   /**
-   * Use FP8 cache for 2x memory reduction (experimental).
-   * Only used when use_paged_attention is true.
-   * Default: false
+   * Use the block-paged KV cache adapter (`PagedKVCacheAdapter`).
+   *
+   * When `Some(true)` (the default for Qwen3), `Qwen3Inner` allocates a
+   * `BlockAllocator` + `LayerKVPool` pair and constructs a
+   * `PagedKVCacheAdapter` for cross-request KV prefix reuse (vLLM-style
+   * block-paged storage with refcounted prefix caching). When
+   * `Some(false)`, the flat (non-paged) `Vec<KVCache>` cache path is
+   * used instead.
+   *
+   * Default: true.
    */
-  useFp8Cache?: boolean | undefined;
+  useBlockPagedCache?: 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. */
@@ -3047,6 +4320,14 @@ export interface RecResult {
   score: number;
 }
 
+/**
+ * Reset MLX's peak-memory counter to the current active level.
+ * Useful for measuring per-request peak memory in a long-running
+ * process — call before a request, sample
+ * `getMemorySnapshot().peakBytes` after.
+ */
+export declare function resetPeakMemory(): void;
+
 /** Clear all collected profiling data and reset session timer. */
 export declare function resetProfilingData(): void;
 
@@ -3136,22 +4417,6 @@ export interface SamplingConfig {
  */
 export declare function saveToXlsx(text: string, filePath: string): void;
 
-/** Scheduler statistics (NAPI-compatible) */
-export interface SchedulerStatsNapi {
-  /** Number of requests waiting to be scheduled */
-  numWaiting: number;
-  /** Number of sequences currently running */
-  numRunning: number;
-  /** Number of completed sequences */
-  numCompleted: number;
-  /** Number of sequences in prefill phase */
-  numPrefill: number;
-  /** Number of sequences in decode phase */
-  numDecode: number;
-  /** Total tokens across all running sequences */
-  totalRunningTokens: number;
-}
-
 /** Enable or disable profiling globally. */
 export declare function setProfilingEnabled(enabled: boolean): void;
 
@@ -3272,6 +4537,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>;
@@ -3418,6 +4699,35 @@ export interface TrainStepResultWithOutputs {
   completionLengths: Array<number>;
 }
 
+/**
+ * Encoder-free vision configuration for the Gemma 4 unified multimodal model.
+ *
+ * Parsed from the `vision_config` sub-dict of a `gemma4_unified` checkpoint
+ * (`model_type == "gemma4_unified_vision"`). This is a different shape from the
+ * SigLIP-style [`super::vision_config::Gemma4VisionConfig`] used by the dense
+ * gemma4 family: the unified vision path has no transformer encoder, only a
+ * patch embedder (LayerNorm + Linear + 2D positional embedding) feeding the
+ * multimodal projection.
+ */
+export interface UnifiedVisionConfig {
+  /** Pixel side length of a single image patch (48 = patch_size 16 × pooling 3). */
+  modelPatchSize: number;
+  /** Embedding width inside the vision embedder (3840, == text hidden_size). */
+  mmEmbedDim: number;
+  /** Number of rows in the 2D positional-embedding table (1120). */
+  mmPosembSize: number;
+  /** Maximum soft tokens (patches) per image after resize (280). */
+  numSoftTokens: number;
+  /** Output projection width of `embed_vision` (3840, == text hidden_size). */
+  outputProjDims: number;
+  /** Pixel-grid patch size used by the resize math (16). */
+  patchSize: number;
+  /** Pooling kernel size used by the resize math (3). */
+  poolingKernelSize: number;
+  /** Epsilon for the embedder LayerNorms and the projection RMSNorm. */
+  rmsNormEps: number;
+}
+
 /** Result from document unwarping. */
 export interface UnwarpResult {
   /** Unwarped image as PNG bytes */
@@ -3462,6 +4772,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;
 }
@@ -3473,3 +4797,27 @@ export interface VlmChatMessage {
   /** Text content of the message */
   content: string;
 }
+
+export declare namespace __internal__ {
+  /**
+   * Drain the MLX allocator's free-pool.
+   *
+   * @internal
+   *
+   * This is a process-wide drain routed through MLX's default-stream
+   * `mlx_synchronize()`, which does NOT wait on the custom generation
+   * streams that the per-model threads run on. Calling this from user
+   * code while a decode is in flight can race live Metal command buffers
+   * and risk use-after-free. The only safe caller today is
+   * `@mlx-node/server`'s idle sweeper, which only triggers after the
+   * in-flight request counter has returned to zero.
+   *
+   * Exposed under the `__internal__` NAPI namespace — reachable as
+   * `require('@mlx-node/core').__internal__.clearCache()` and NOT on
+   * the root `require('@mlx-node/core')` object. The namespace prefix
+   * is a deliberate speed-bump that forces any caller to acknowledge
+   * this is a private drain with custom-stream caveats; the root
+   * surface stays clean of the footgun.
+   */
+  export function clearCache(): void;
+}