Release Phillnet Mini Text-Vision v1.1.0

Text-and-still-image model release with adaptive reasoning defaults, complete model card, examples, integrity manifest, and production deployment materials.

.dockerignore

@@ -0,0 +1,15 @@
+.git
+.gitignore
+__pycache__
+*.py[cod]
+.env
+.env.*
+!.env.example
+*.log
+*.pid
+*.zip
+*.tar
+*.tar.gz
+.pytest_cache
+.mypy_cache
+.cache

.env.example

@@ -0,0 +1,14 @@
+# Copy this file to .env and replace the placeholder before exposing the API.
+# Leave empty only for isolated local development.
+PHILLNET_API_KEY=replace-with-a-long-random-secret
+
+# Comma-separated browser origins allowed to call the API. Do not use * in production.
+PHILLNET_CORS_ORIGINS=https://your-app.example.com
+
+# The container's model directory. Keep the bundled default unless mounting a different model path.
+MODEL_DIR=/app/model
+
+# Request limits for base64 image input and JSON bodies.
+PHILLNET_MAX_IMAGE_BYTES=10485760
+PHILLNET_MAX_IMAGE_PIXELS=24000000
+PHILLNET_MAX_REQUEST_BYTES=12582912

.gitattributes

@@ -1,35 +1,8 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
+# Hugging Face Git LFS artifacts
 *.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+tokenizer.json filter=lfs diff=lfs merge=lfs -text
+
+# Keep Markdown, JSON configuration, HTML, and PNG examples as regular Git files
+# for direct review in the repository viewer.
+examples/direct-horizon-tasks.png filter=lfs diff=lfs merge=lfs -text
+examples/medium-solara-dashboard.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,29 @@
+# Python bytecode and caches
+__pycache__/
+*.py[cod]
+*.so
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Local environments and secrets
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+
+# Local runtime data and logs
+*.log
+*.pid
+.cache/
+.tmp/
+
+# Release archives are created outside the upload repository
+*.zip
+*.tar
+*.tar.gz
+
+# Operating-system files
+.DS_Store
+Thumbs.db

ADAPTIVE_DEFAULTS_REPORT.md

@@ -0,0 +1,79 @@
+# Adaptive Reasoning and 8K Output Configuration
+
+**Status:** Corrected and validated on 21 August 2026.
+
+## What was wrong with the prior HTML test
+
+The model checkpoint already contained adaptive-reasoning features, but the evaluation caller overrode them. The prior benchmark explicitly passed `reasoning_effort="direct"`, a small manual recurrent budget, and `max_new_tokens=180`. Those three caller arguments bypassed the model's normal default reasoning profile and stopped every HTML response inside its opening CSS.
+
+The issue was therefore not a missing SDXL removal or a tokenizer issue. It was a **generation-policy bottleneck in the testing and serving layer**.
+
+## Persisted defaults now enabled
+
+The package configuration now uses the following defaults:
+
+| Configuration field | Value | Effect |
+|---|---|---|
+| `adaptive_reasoning` | `true` | Enables adaptive recurrent reasoning behavior. |
+| `default_adaptive_capsule_budget` | `true` | Allows adaptive reasoning capsules. |
+| `default_adaptive_reasoning_trace` | `true` | Enables the private adaptive reasoning trace policy. |
+| `default_private_reasoning_generation` | `true` | Makes `model.generate()` enter private reasoning when the caller does not override it. |
+| `reasoning_token_budget_policy` | `adaptive_context` | Lets the private reasoning phase expand up to the real active-context boundary and stop naturally on `</think>`. |
+| `default_reasoning_effort` | **`max`** | Makes maximum adaptive reasoning the package default. |
+| `reasoning_effort_token_budgets.max` | `8192` | Retains the model's maximum reasoning profile. |
+| `answer_token_budget_policy` | **`fixed`** | Prevents the visible-answer phase from expanding to the 1,048,576-token logical context. |
+| `generation_default_max_answer_tokens` | **`8192`** | Gives visible responses an 8,192-token maximum by default. |
+
+> “Infinite” reasoning is not physically literal: the model uses an adaptive policy bounded by the active 32,768-token cache window, the reserved answer allocation, and its end-of-thinking token. This is the correct safety and memory boundary. The model decides when to close its private reasoning phase; it is no longer artificially restricted by the former 180-token benchmark cap.
+
+## Serving defaults
+
+`server.py` now defaults to:
+
+```python
+max_tokens = 8192
+reasoning_effort = "max"
+```
+
+Callers can still request a lower `max_tokens` or reasoning effort when latency is more important than depth. The default path prioritizes the user-requested deep adaptive behavior.
+
+## Full uncapped adaptive HTML validation
+
+The validation runner deliberately omitted `max_new_tokens`, `max_answer_tokens`, `max_reasoning_tokens`, and `reasoning_budget`. Consequently, the model used only persisted configuration defaults.
+
+| Metric | Result |
+|---|---:|
+| Prompt tokens | 107 |
+| Private-reasoning ceiling calculated from active context | 22,356 tokens |
+| Private reasoning actually used before natural close | 2,944 tokens |
+| Visible-answer ceiling | 8,192 tokens |
+| Visible answer actually generated | 2,991 tokens |
+| Total runtime on sandbox CPU | 921.415 seconds |
+| Complete HTML document detected | Yes |
+| HTML character count | 10,472 |
+
+The output contains one complete document with balanced CSS braces, closing `style`, `head`, `body`, `script`, and `html` tags, a responsive mobile-toggle element, the `toggleMenu()` handler, a navigation container, two calls to action, and three feature cards. It was rendered locally in Chromium as a usable Orbit Notes landing page.
+
+## Important policy distinction
+
+The first attempted configuration retained `answer_token_budget_policy: "adaptive_context"`. With a 1,048,576-token logical context, an omitted answer cap caused the private generator to allocate over one million visible-answer tokens after its reasoning phase. That was not an 8K maximum and exhausted the constrained evaluation process. The configuration was corrected to `answer_token_budget_policy: "fixed"` while preserving adaptive private reasoning. This gives the intended combination:
+
+1. **Adaptive deep private reasoning** that can self-terminate naturally before the active context boundary.
+2. **A bounded 8,192-token visible response** appropriate for practical serving and one-shot code generation.
+
+## Reproduction
+
+Run the full adaptive validation with:
+
+```bash
+python3 /home/ubuntu/phillnet_work/run_uncapped_adaptive_html_oneshot.py
+```
+
+The artifacts are in `uncapped_adaptive_html_result/`:
+
+| File | Description |
+|---|---|
+| `oneshot.html` | Complete generated Orbit Notes page. |
+| `raw.txt` | Exact decoded model completion. |
+| `summary.json` | Loaded defaults, completion totals, and progress events. |
+| `progress.jsonl` | Privacy-safe phase/count/budget progress trail. |

COHERENCE_REPAIR_REPORT.md

@@ -0,0 +1,71 @@
+# Coherence and Spatial-Input Repair Report
+
+**Status:** Corrected and validated on 21 August 2026.
+
+## Root cause
+
+The initial lean build retained the correct language-and-vision checkpoint but introduced a **tokenizer contract error** in the new image processor. It instantiated `DendroByteTokenizer`, a 259-token byte tokenizer, while the retained checkpoint declares a 248,320-token Qwen-derived vocabulary and includes a native `Qwen2Tokenizer` artifact. The mismatch sent byte-token IDs to embeddings trained for Qwen token IDs, causing malformed decoded output such as `�` even though the model could load and complete numerical forward passes.
+
+A second prompt-framing issue caused the initial service to construct literal `\\n` character pairs rather than newline separators. That altered the chat token sequence and made the HTTP endpoint differ from the native Qwen chat template. A third serving issue passed a near-zero `temperature` to the custom generation loop even with sampling disabled, which altered its deterministic behavior.
+
+## Corrections
+
+| Area | Previous behavior | Corrected behavior |
+|---|---|---|
+| Language tokenizer | Custom 259-token byte tokenizer | Native `Qwen2Tokenizer` loaded locally from `tokenizer.json` with remote code disabled for tokenizer loading |
+| Chat framing | Literal backslash-n characters in the processor prompt | Native Qwen-compatible `<|im_start|>`, real newline, `<|im_end|>` sequence |
+| Image placement | Image features appended after the assembled text | Image placeholder sequence inserted exactly where each image content item occurs |
+| Spatial metadata | Not independently tested | `image_grid_thw`, image placeholder count, and assistant-prefix ordering tested |
+| Deterministic service decoding | Passed `temperature=1e-5` while `do_sample=False` | Omits temperature during deterministic decoding, preserving native argmax behavior |
+| Service process | Older detached process remained bound to port 8000 | Stale process removed and the corrected service bound cleanly to port 8000 |
+
+## Coherence validation
+
+All text completions below use deterministic direct-mode generation and are taken from the corrected processor path. The wrapped processor now produces the same token count and token IDs as the native Qwen chat template.
+
+| Prompt | Corrected completion | Result |
+|---|---|---|
+| `Complete this phrase with one word: The capital of France is` | `Paris` | Correct |
+| `What is 2 plus 2? Answer with only the number.` | `4` | Correct |
+| `Reply with exactly one word: blue` | `blue` | Correct |
+| Same last prompt through live `/v1/chat/completions` | `blue` | Correct |
+
+## Vision and spatial validation
+
+The processor prepares a still image as two temporal frames, 16×16 patches, and a Qwen-compatible `image_grid_thw`. It inserts one `<|image_pad|>` token per spatially merged vision feature and places the vision tokens before the assistant generation prefix.
+
+| Test | Input | Output | Result |
+|---|---|---|---|
+| Color grounding | Solid red image | `red` | Correct |
+| Color grounding | Solid lime image | `green` | Correct |
+| Color grounding | Solid blue image | `blue` | Correct |
+| Color grounding | Solid white image | `white` | Correct |
+| Color grounding | Solid black image | `black` | Correct |
+| Spatial grounding | 128×64 scene: red left half, blue right half; ask left color | `red` | Correct |
+| Spatial grounding | Same scene; ask right color | `blue` | Correct |
+
+For the two-region spatial scene, the processor emitted `image_grid_thw = [[1, 4, 8]]` and eight visual placeholder tokens, matching the vision tower’s spatial merge factor of two. The direct test verified that the rightmost image placeholder precedes the assistant prefix, so vision embeddings are injected into the intended context position.
+
+## Live API status
+
+The temporary endpoint remains:
+
+```text
+https://8000-iq1jte46c8ls1hzprn1yn-9c029be5.us5.manus.computer/health
+```
+
+The live service now uses the corrected processor and deterministic generation path. For a dark navy image, it answered `black`; the dedicated visual probe shows correct output for pure blue (`blue`) and for five high-contrast solid colors. The navy result should be interpreted as a dark-color ambiguity rather than a failure of image-token placement.
+
+## Reproduction tests
+
+The parent workspace contains these scripts:
+
+| Script | Purpose |
+|---|---|
+| `diagnose_tokenizer_alignment.py` | Demonstrates the original byte-vocabulary mismatch and the native tokenizer path. |
+| `test_text_coherence.py` | Compares native Qwen chat formatting against the corrected processor on three deterministic prompts. |
+| `test_vision_coherence.py` | Verifies the still-image processor contract and a decoded response. |
+| `test_vision_color_grounding.py` | Verifies that five distinct solid-color images produce distinct correct answers. |
+| `test_vision_spatial_grounding.py` | Verifies left/right spatial grounding on a two-region image. |
+
+The model has now been demonstrated to provide coherent text completion, still-image color grounding, and basic left/right spatial grounding. These are smoke tests, not a comprehensive capability benchmark.

Dockerfile

@@ -0,0 +1,22 @@
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    MODEL_DIR=/app/model
+
+WORKDIR /app/model
+
+COPY requirements.txt requirements-server.txt ./
+RUN pip install --no-cache-dir -r requirements.txt -r requirements-server.txt \
+    && useradd --create-home --uid 10001 --shell /usr/sbin/nologin modeluser
+
+COPY --chown=modeluser:modeluser . ./
+
+USER modeluser
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=120s --retries=3 \
+  CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/ready', timeout=3)"
+
+CMD ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "1", "--proxy-headers", "--forwarded-allow-ips", "*"]

HF_UPLOAD.md

@@ -0,0 +1,61 @@
+# Upload Phillnet Mini Text-Vision to Hugging Face
+
+This directory is the **complete upload root**. Upload the directory itself, not a nested archive, so the model card, `config.json`, custom model code, tokenizer, checkpoint, examples, and deployment materials remain at repository root.
+
+## Recommended CLI workflow
+
+Install the current Hub client, authenticate with a token that has write access, create the model repository, then upload this directory. The official `hf upload` workflow streams folders, resumes interrupted uploads, and honours the root `.gitignore` file. [1]
+
+```bash
+python -m pip install --upgrade huggingface_hub
+hf auth login
+
+# Choose your own account or organization namespace.
+hf repo create YOUR_NAMESPACE/Phillnet-Mini-Text-Vision --type model
+
+# Run from the parent directory that contains Phillnet-Mini-Text-Vision/.
+export HF_XET_HIGH_PERFORMANCE=1
+hf upload YOUR_NAMESPACE/Phillnet-Mini-Text-Vision \
+  ./Phillnet-Mini-Text-Vision \
+  . \
+  --commit-message "Release Phillnet Mini Text-Vision v1.1.0"
+```
+
+The upload command can be rerun safely if a network interruption occurs; committed files are skipped and existing content is deduplicated by the Hub upload pipeline. [1]
+
+## Pre-upload checklist
+
+| Item | Expected state |
+|---|---|
+| `README.md` | Model card with Hugging Face metadata and embedded local example gallery. |
+| `model.safetensors` | Full retained language-and-vision checkpoint, tracked through Git LFS policy. |
+| `config.json`, tokenizer files, and custom Python modules | Present at repository root for `trust_remote_code=True` loading. |
+| `examples/` | Three complete HTML outputs and PNG previews. |
+| `LICENSE` | Apache License 2.0 text. |
+| `.gitattributes` | Tracks `*.safetensors` and `tokenizer.json` as large artifacts. |
+| `.gitignore` | Excludes caches, secrets, local logs, and archives. |
+| `Dockerfile`, `docker-compose.yml`, `.env.example` | Included for controlled self-hosted API deployment. |
+| `RELEASE_MANIFEST.json` | Integrity and inventory record. |
+
+## Verify after upload
+
+Open `https://huggingface.co/YOUR_NAMESPACE/Phillnet-Mini-Text-Vision` and verify that the README renders its three images, the Files tab contains the checkpoint and configuration, and the model card identifies this as a custom-code model requiring `trust_remote_code=True`.
+
+Then test from a clean environment:
+
+```python
+from transformers import AutoModelForCausalLM, AutoProcessor
+
+repo = "YOUR_NAMESPACE/Phillnet-Mini-Text-Vision"
+processor = AutoProcessor.from_pretrained(repo, trust_remote_code=True)
+model = AutoModelForCausalLM.from_pretrained(repo, trust_remote_code=True)
+```
+
+## Git alternative
+
+The Hub also supports Git-based model repositories. The included `.gitattributes` provides the necessary large-file rules, but the CLI workflow above is recommended for this full folder because it handles resumed large-file transfers automatically. [1] [2]
+
+## References
+
+[1]: https://huggingface.co/docs/huggingface_hub/en/guides/upload "Hugging Face Hub: Upload files to the Hub"
+[2]: https://huggingface.co/docs/hub/en/models-uploading "Hugging Face Hub: Uploading models"

IMPLEMENTATION_REPORT.md

@@ -0,0 +1,240 @@
+# Phillnet Mini Text-Vision
+
+**Build status:** Complete and validated on 21 August 2026.
+
+This package is a deliberately lean derivative of `ayjays132/Phillnet-Mini-Omni-Max`. It retains **text generation** and **still-image understanding** only. The upstream model card identifies the checkpoint as a custom-code Transformers model and describes a separate SDXL image-generation route; this build removes that route completely rather than merely disabling it at runtime. [1]
+
+> **Scope lock:** This package supports only language generation and visual question answering over still images. It contains no SDXL U-Net, VAE, SDXL text encoders, diffusion scheduler, text-to-image API, text-to-video API, tool runtime, agent runtime, audio endpoint, or video endpoint.
+
+## What was downloaded and what was removed
+
+The full original Hugging Face snapshot was mirrored before transformation. Its source inventory contained 99 files, including 18 files in the `phillnet3_sdxl/` subtree. The final lean package contains 48 files and is 1,785,035,602 bytes on disk, compared with 10,403,517,915 bytes for the complete downloaded snapshot.
+
+| Artifact | Original snapshot | Final text-vision package | Result |
+|---|---:|---:|---|
+| Total package size | 10,403,517,915 bytes | 1,785,035,602 bytes | **82.84% reduction** |
+| SDXL subtree | 8,608,200,761 bytes across 18 files | 0 bytes | **Removed** |
+| Core `model.safetensors` | 1,763,655,304 bytes | 1,763,655,304 bytes | **Retained byte-for-byte** |
+| Package files | 300 files in downloaded snapshot | 48 files | Runtime surface reduced |
+
+The retained core checkpoint has SHA-256:
+
+```text
+f1a913f99f8ce921c1aa79982a09eaee6744448766f09a4756751e2d4b9342fc
+```
+
+That hash is identical before and after the stripping process. Therefore, the language and visual-encoder weights that reside in `model.safetensors` were not rewritten or quantized.
+
+## Exact removal policy
+
+The SDXL assets were not left as optional downloads. They were physically excluded from the final package together with the loading paths that referenced them. This prevents the deployment from downloading, initializing, or accidentally exposing a diffusion backend.
+
+| Removed area | Files or behavior removed | Why it is absent |
+|---|---|---|
+| SDXL checkpoint | `phillnet3_sdxl/`, including two `phillnet-image-*.safetensors` shards | These shards contain the diffusion donor banks and were the primary storage cost. |
+| SDXL runtime | `phillnet3_sdxl.py`, `synthesis.py`, `phillnet3_bridge.py`, `generation_acceleration.py` | They create or accelerate the SDXL U-Net, VAE, CLIP encoders, scheduler, and image/video synthesis routes. |
+| Generation APIs | `generate_image`, `generate_image_prompt`, `generate_video`, `generate_video_prompt`, `synthesis_losses` | These methods were removed from `DendroForCausalLM`, not merely hidden. |
+| Diffusion configuration | SDXL/diffusion-specific fields and validation from `config.json` and `configuration_dendro_omni.py` | A lean model should not advertise, validate, or accept inactive synthesis configuration. |
+| Non-core runtimes | Agent, tool, orchestration, Smolagents, legacy showcase, cache, and image-generation files | They are outside the requested text-and-vision serving surface. |
+| External processor declaration | Stale `Qwen3VLProcessor` declaration | Replaced by the bundled `DendroVisionProcessor` to make image input local and self-contained. |
+
+The remaining configuration declares `model_capabilities: ["text-generation", "image-understanding"]` and `text_vision_only: true`.
+
+## What remains and why it works
+
+The central retained checkpoint uses a packed single-source SafeTensors layout. It has one top-level tensor rather than many separately named tensors, while `transplant_manifest.json` maps portions of that source to language and visual components. The manifest contains **153 retained `model.visual.*` mappings**. This is distinct from the deleted SDXL subtree: those mappings implement visual encoding for image understanding, whereas SDXL supplied image synthesis.
+
+The new `processing_dendro_omni.py` is the key compatibility layer. It loads text and still images locally, normalizes an image, duplicates a still frame to satisfy the visual tower’s temporal patch dimension, constructs visual patches, inserts exactly the matching number of image placeholder tokens, and emits the `pixel_values`, `image_grid_thw`, and `mm_token_type_ids` tensors needed by the retained visual transformer. The processor is registered in both `config.json` and `preprocessor_config.json`, so `AutoProcessor.from_pretrained(..., trust_remote_code=True)` resolves to `DendroVisionProcessor`.
+
+| Supported path | Status | Implementation |
+|---|---|---|
+| Text completion | Enabled | `model.generate(...)` with `reasoning_effort="direct"` for low-latency serving. |
+| Text forward pass | Enabled | Standard `DendroForCausalLM.forward(...)`. |
+| Still-image understanding | Enabled | `DendroVisionProcessor` plus `model.answer_image(...)` or direct multimodal model calls. |
+| SDXL image generation | Removed | No weights, no module, no API, no dependency. |
+| Video generation | Removed | No API, no diffusion route, no endpoint. |
+| Audio / tools / agents | Not exposed | Excluded from the lean HTTP service and removed where they were optional runtime layers. |
+
+## Verification evidence
+
+Verification was intentionally separated into structural, load, forward, and serving checks. The checks prove that the package can load and execute the retained text and visual-input paths. They do **not** constitute a semantic-quality benchmark; output quality must be evaluated separately on representative user tasks.
+
+| Check | Result | Evidence |
+|---|---|---|
+| Python syntax compilation | Passed | Lean runtime modules, processor, configuration, model, and service compiled. |
+| SDXL filesystem scan | Passed | No SDXL-named source or weight artifact remains in the final package. |
+| Synthesis-code scan | Passed | No `diffusers`, `StableDiffusion`, `DendroSharedDiffusion`, image/video-generation method, or SDXL adapter reference remains in Python runtime code. |
+| Configuration deserialization | Passed | `DendroOmniConfig.from_pretrained(...)` loaded from the stripped directory. |
+| Processor discovery | Passed | `AutoProcessor` resolves to `DendroVisionProcessor`. |
+| Model loading | Passed | `AutoModelForCausalLM` instantiated `DendroForCausalLM` in BF16 on CPU. |
+| Text forward pass | Passed | Finite logits with shape `[1, 27, 248320]`. |
+| Image forward pass | Passed | Finite logits with shape `[1, 61, 248320]`. |
+| Visual-input contract | Passed | One 32×32 test image produced one visual placeholder and four visual patches. |
+| Direct text generation | Passed | Two output tokens completed in 2.224 seconds in the sandbox CPU test. |
+| Local deployment health | Passed | `/health` returns exactly the two enabled capabilities and the disabled set. |
+| Local text endpoint | Passed | `/v1/chat/completions` completed a direct-mode text request. |
+| Local image endpoint | Passed | `/v1/chat/completions` accepted a valid base64 still image plus text question. |
+| Public temporary health check | Passed | Temporary proxied endpoint returned the expected health payload. |
+
+## Local use
+
+Install the model dependencies from this directory, then load it using the local custom-code implementation:
+
+```bash
+cd Phillnet-Mini-Text-Vision
+pip install -r requirements.txt
+```
+
+```python
+import torch
+from transformers import AutoModelForCausalLM, AutoProcessor
+
+model_dir = "./Phillnet-Mini-Text-Vision"
+processor = AutoProcessor.from_pretrained(model_dir, trust_remote_code=True)
+model = AutoModelForCausalLM.from_pretrained(
+    model_dir,
+    trust_remote_code=True,
+    dtype=torch.bfloat16,
+    low_cpu_mem_usage=True,
+).eval()
+
+encoded = processor("Reply with one word: blue", return_tensors="pt")
+output = model.generate(
+    **encoded,
+    max_new_tokens=32,
+    reasoning_effort="direct",
+    do_sample=False,
+)
+print(processor.tokenizer.decode(output[0], skip_special_tokens=True))
+```
+
+For still-image questions, pass OpenAI-style multimodal message content to the processor:
+
+```python
+from PIL import Image
+
+encoded = processor.apply_chat_template(
+    [{
+        "role": "user",
+        "content": [
+            {"type": "image", "image": Image.open("example.png").convert("RGB")},
+            {"type": "text", "text": "Describe the visible objects."},
+        ],
+    }],
+    tokenize=True,
+    add_generation_prompt=True,
+    return_dict=True,
+    return_tensors="pt",
+)
+
+answer = model.generate(
+    **encoded,
+    max_new_tokens=128,
+    reasoning_effort="direct",
+    do_sample=False,
+)
+print(processor.tokenizer.decode(answer[0], skip_special_tokens=True))
+```
+
+## Deployment
+
+The package contains a minimal FastAPI service in `server.py` and a `Dockerfile`. The service exposes only `/health` and `/v1/chat/completions`.
+
+### Run directly
+
+```bash
+cd Phillnet-Mini-Text-Vision
+pip install -r requirements.txt -r requirements-server.txt
+uvicorn server:app --host 0.0.0.0 --port 8000
+```
+
+### Run in a container
+
+```bash
+docker build -t phillnet-mini-text-vision .
+docker run --rm -p 8000:8000 phillnet-mini-text-vision
+```
+
+The package was verified on CPU using BF16 weights. Production capacity must account for the 1.76 GB checkpoint plus framework and request-memory overhead; test the target hardware under representative image sizes and concurrent-request volume before enabling unrestricted traffic.
+
+### Health check
+
+```bash
+curl http://localhost:8000/health
+```
+
+Expected response:
+
+```json
+{
+  "status": "ok",
+  "capabilities": ["text-generation", "image-understanding"],
+  "disabled": ["image-generation", "video-generation", "audio", "tools", "agents"]
+}
+```
+
+### Text request
+
+```bash
+curl http://localhost:8000/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  --data '{
+    "messages": [{"role": "user", "content": "Give a one-sentence summary of caching."}],
+    "max_tokens": 96,
+    "reasoning_effort": "direct"
+  }'
+```
+
+### Still-image question
+
+The endpoint accepts `image_base64`; remote image URLs are intentionally not fetched, avoiding a server-side request-forgery surface.
+
+```bash
+IMAGE_B64=$(base64 -w0 example.png)
+curl http://localhost:8000/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  --data "{
+    \"messages\": [{
+      \"role\": \"user\",
+      \"content\": [
+        {\"type\": \"image\", \"image_base64\": \"${IMAGE_B64}\"},
+        {\"type\": \"text\", \"text\": \"What is visible in this image?\"}
+      ]
+    }],
+    \"max_tokens\": 128,
+    \"reasoning_effort\": \"direct\"
+  }"
+```
+
+## Temporary deployment
+
+A verified **temporary** endpoint is currently available at:
+
+```text
+https://8000-iq1jte46c8ls1hzprn1yn-9c029be5.us5.manus.computer
+```
+
+Its health endpoint is:
+
+```text
+https://8000-iq1jte46c8ls1hzprn1yn-9c029be5.us5.manus.computer/health
+```
+
+This URL is for validation only. It is backed by the session sandbox and will not provide durable production hosting. For a persistent deployment, use the included container definition on a host with enough RAM for the retained BF16 checkpoint and configure authentication, TLS termination, logging, rate limits, and request-size limits at the deployment boundary.
+
+## Reproducibility artifacts
+
+The parent workspace contains the following non-runtime artifacts:
+
+| File | Purpose |
+|---|---|
+| `build_text_vision_only.py` | Rebuilds the lean package from the fully downloaded original snapshot without executing remote model code. |
+| `validate_text_vision_package.py` | Structural, configuration, processor, and checkpoint-inventory validation. |
+| `load_text_vision_model.py` | Controlled model-load verification. |
+| `run_text_vision_forward.py` | Text, image, and direct-generation forward smoke test. |
+| `original_weight_sha256.txt` | Checksums captured from the complete original snapshot. |
+| `SOURCE_INVENTORY.md` | Source repository inventory. |
+
+## References
+
+[1]: https://huggingface.co/ayjays132/Phillnet-Mini-Omni-Max "ayjays132/Phillnet-Mini-Omni-Max model card"

PRODUCTION.md

@@ -0,0 +1,108 @@
+# Production Operations Guide
+
+Phillnet Mini Text-Vision is a **single-process, text-and-still-image inference service**. The included stack is designed for a controlled deployment boundary: one model process, one serialized generation at a time, local base64 image inputs only, optional API-key authentication, and explicit CORS origins.
+
+## Deployment topology
+
+```text
+Trusted clients
+    │ HTTPS + API key
+    ▼
+TLS reverse proxy / edge rate limiter
+    │ localhost HTTP
+    ▼
+Docker Compose: Phillnet Mini Text-Vision
+    │ one Uvicorn worker + one loaded model
+    ▼
+Text generation and still-image understanding
+```
+
+Keep the model container bound to loopback by default. Terminate TLS, rate limit, and log access at a reverse proxy or managed ingress. The model container itself is intentionally not a public multi-tenant gateway.
+
+## First deployment
+
+```bash
+cp .env.example .env
+# Set PHILLNET_API_KEY to a long random secret.
+# Set PHILLNET_CORS_ORIGINS to the exact browser application origin.
+docker compose up --build -d
+
+docker compose ps
+curl http://127.0.0.1:8000/ready
+```
+
+The service reports `ready: true` only after the processor and checkpoint are loaded.
+
+## Reverse-proxy example
+
+The following Nginx location keeps the container private, applies a request body limit, and forwards the authorization header. Configure a valid TLS server block around it.
+
+```nginx
+location / {
+    proxy_pass http://127.0.0.1:8000;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header Authorization $http_authorization;
+    proxy_set_header X-API-Key $http_x_api_key;
+    client_max_body_size 12m;
+    proxy_read_timeout 1800s;
+    proxy_send_timeout 1800s;
+}
+```
+
+Apply an edge rate limit appropriate to available RAM and latency. One model worker is deliberate: a concurrent long-context generation can overcommit local memory. Scale by adding isolated model replicas behind a router, not by increasing Uvicorn workers inside one model container.
+
+## Authentication and CORS
+
+Set `PHILLNET_API_KEY` in `.env`. The protected completion route accepts either of these headers:
+
+```http
+Authorization: Bearer YOUR_SECRET
+```
+
+```http
+X-API-Key: YOUR_SECRET
+```
+
+Set `PHILLNET_CORS_ORIGINS` to a comma-separated list of known origins such as `https://app.example.com`. Leave it empty for server-to-server callers. Never use a wildcard origin together with a browser-facing credential policy.
+
+## Inference and input limits
+
+| Guardrail | Default | Reason |
+|---|---:|---|
+| Concurrent generations | 1 | Avoids contention and memory overcommit on one local checkpoint. |
+| Maximum visible answer | 8,192 tokens | Matches the model’s persisted response policy. |
+| Maximum images per request | 4 | Bounds multimodal preprocessing work. |
+| Maximum decoded image size | 10 MiB | Prevents oversized inline payloads. |
+| Maximum image pixels | 24,000,000 | Mitigates decompression-bomb and preprocessing risks. |
+| Maximum request body | 12 MiB | Rejects oversized JSON before inference. |
+
+## Health and observability
+
+Use these endpoints in the surrounding platform:
+
+| Endpoint | Purpose | Authentication |
+|---|---|---|
+| `GET /health` | Basic liveness and advertised capability surface. | No |
+| `GET /ready` | Readiness after checkpoint and processor load. | No |
+| `POST /v1/chat/completions` | Text and optional still-image inference. | Required when `PHILLNET_API_KEY` is set. |
+
+The completion response includes `usage` counts and `elapsed_seconds`, which are sufficient for basic application-side request telemetry. Do not log request images or full user prompts unless your data-retention policy explicitly allows it.
+
+## Upgrade and rollback
+
+Build tagged images rather than relying on mutable local source.
+
+```bash
+docker compose build
+docker image tag phillnet-mini-text-vision:1.1.0 registry.example.com/phillnet-mini-text-vision:1.1.0
+# Push to your trusted registry, then deploy that immutable tag.
+```
+
+Retain the preceding image tag and the matching `RELEASE_MANIFEST.json`. Verify the checkpoint hash before switching traffic. Roll back by returning the compose image reference to the prior known-good tag and running `docker compose up -d`.
+
+## Scope boundary
+
+This service supports only **text generation** and **still-image understanding**. It does not expose image generation, video generation, audio, tools, agents, browsing, remote URL fetching, or arbitrary local file access.

README.md

@@ -0,0 +1,285 @@
+---
+license: apache-2.0
+language:
+  - en
+pipeline_tag: image-text-to-text
+tags:
+  - text-generation
+  - visual-question-answering
+  - multimodal
+  - custom-code
+  - adaptive-reasoning
+  - text-vision-only
+library_name: transformers
+---
+
+# Phillnet Mini Text-Vision
+
+**Phillnet Mini Text-Vision** is a lean, self-contained derivative of [ayjays132/Phillnet-Mini-Omni-Max][1] for two focused capabilities: **language generation** and **still-image understanding**. It preserves the source checkpoint’s language and visual-encoder path while removing the SDXL synthesis stack and nonessential runtime surfaces.
+
+> **Designed for:** text completion, multimodal chat, visual question answering, image-grounded reasoning, and code or HTML generation.  
+> **Not included:** image generation, video generation, audio, agents, tools, SDXL, diffusion schedulers, U-Net, VAE, or SDXL text encoders.
+
+## Example gallery
+
+| Direct example: Horizon Tasks | Medium example: Solara Grid | Maximum adaptive example: Orbit Notes |
+|---|---|---|
+| [![Horizon Tasks landing page](https://private-us-east-1.manuscdn.com/sessionFile/BqAFZMqxyrtm3s5wdTv4jM/sandbox/HtU7EIGVyL1k8mG5rg24G6-images_1787379131756_na1fn_L2hvbWUvdWJ1bnR1L3BoaWxsbmV0X3dvcmsvUGhpbGxuZXQtTWluaS1UZXh0LVZpc2lvbi9leGFtcGxlcy9kaXJlY3QtaG9yaXpvbi10YXNrcw.png?Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiaHR0cHM6Ly9wcml2YXRlLXVzLWVhc3QtMS5tYW51c2Nkbi5jb20vc2Vzc2lvbkZpbGUvQnFBRlpNcXh5cnRtM3M1d2RUdjRqTS9zYW5kYm94L0h0VTdFSUdWeUwxazhtRzVyZzI0RzYtaW1hZ2VzXzE3ODczNzkxMzE3NTZfbmExZm5fTDJodmJXVXZkV0oxYm5SMUwzQm9hV3hzYm1WMFgzZHZjbXN2VUdocGJHeHVaWFF0VFdsdWFTMVVaWGgwTFZacGMybHZiaTlsZUdGdGNHeGxjeTlrYVhKbFkzUXRhRzl5YVhwdmJpMTBZWE5yY3cucG5nIiwiQ29uZGl0aW9uIjp7IkRhdGVMZXNzVGhhbiI6eyJBV1M6RXBvY2hUaW1lIjoxNzg5NDMwNDAwfX19XX0_&Key-Pair-Id=K2QY5QTL8JSY6C&Signature=MEYCIQD97wMIU0b2gCDDgui8twaZctOYKGp9qOHQvycgpDIv7AIhAN01ndIde03tb6BnOGz4sq0nDhhTXpu5IOnk-r9mrTxj)](examples/direct-horizon-tasks.html) | [![Solara Grid dashboard](https://private-us-east-1.manuscdn.com/sessionFile/BqAFZMqxyrtm3s5wdTv4jM/sandbox/HtU7EIGVyL1k8mG5rg24G6-images_1787379131756_na1fn_L2hvbWUvdWJ1bnR1L3BoaWxsbmV0X3dvcmsvUGhpbGxuZXQtTWluaS1UZXh0LVZpc2lvbi9leGFtcGxlcy9tZWRpdW0tc29sYXJhLWRhc2hib2FyZA.png?Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiaHR0cHM6Ly9wcml2YXRlLXVzLWVhc3QtMS5tYW51c2Nkbi5jb20vc2Vzc2lvbkZpbGUvQnFBRlpNcXh5cnRtM3M1d2RUdjRqTS9zYW5kYm94L0h0VTdFSUdWeUwxazhtRzVyZzI0RzYtaW1hZ2VzXzE3ODczNzkxMzE3NTZfbmExZm5fTDJodmJXVXZkV0oxYm5SMUwzQm9hV3hzYm1WMFgzZHZjbXN2VUdocGJHeHVaWFF0VFdsdWFTMVVaWGgwTFZacGMybHZiaTlsZUdGdGNHeGxjeTl0WldScGRXMHRjMjlzWVhKaExXUmhjMmhpYjJGeVpBLnBuZyIsIkNvbmRpdGlvbiI6eyJEYXRlTGVzc1RoYW4iOnsiQVdTOkVwb2NoVGltZSI6MTc4OTQzMDQwMH19fV19&Key-Pair-Id=K2QY5QTL8JSY6C&Signature=MEYCIQCIqMN-TCflATcFV0J0Zto7HWLe~wz0OyJgsWnEgqXCLAIhAIUdO7UE5MbCIw96dBisgVbq6~SMMwtlgfSPYdxXpxMt)](examples/medium-solara-dashboard.html) | [![Orbit Notes landing page](https://private-us-east-1.manuscdn.com/sessionFile/BqAFZMqxyrtm3s5wdTv4jM/sandbox/HtU7EIGVyL1k8mG5rg24G6-images_1787379131756_na1fn_L2hvbWUvdWJ1bnR1L3BoaWxsbmV0X3dvcmsvUGhpbGxuZXQtTWluaS1UZXh0LVZpc2lvbi9leGFtcGxlcy9tYXgtb3JiaXQtbm90ZXM.png?Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiaHR0cHM6Ly9wcml2YXRlLXVzLWVhc3QtMS5tYW51c2Nkbi5jb20vc2Vzc2lvbkZpbGUvQnFBRlpNcXh5cnRtM3M1d2RUdjRqTS9zYW5kYm94L0h0VTdFSUdWeUwxazhtRzVyZzI0RzYtaW1hZ2VzXzE3ODczNzkxMzE3NTZfbmExZm5fTDJodmJXVXZkV0oxYm5SMUwzQm9hV3hzYm1WMFgzZHZjbXN2VUdocGJHeHVaWFF0VFdsdWFTMVVaWGgwTFZacGMybHZiaTlsZUdGdGNHeGxjeTl0WVhndGIzSmlhWFF0Ym05MFpYTS5wbmciLCJDb25kaXRpb24iOnsiRGF0ZUxlc3NUaGFuIjp7IkFXUzpFcG9jaFRpbWUiOjE3ODk0MzA0MDB9fX1dfQ__&Key-Pair-Id=K2QY5QTL8JSY6C&Signature=MEQCIGoHLMxYVWPWicHZXdTNzYdrNk9LW4wr0vMsNzWp5yGcAiAbPbTwfQPNpkHRNTFvNLCC7bZRbjXRyG8uvjrr2q-uVQ__)](examples/max-orbit-notes.html) |
+| [Open HTML source](examples/direct-horizon-tasks.html) | [Open HTML source](examples/medium-solara-dashboard.html) | [Open HTML source](examples/max-orbit-notes.html) |
+
+The example pages are standalone HTML files with inline CSS and JavaScript. They are included as reproducible reference outputs for landing-page, dashboard, and long-form one-shot generation workflows.
+
+## What changed from the omni source
+
+The original source model includes an SDXL-backed synthesis route. This package excludes that route at the file, configuration, and runtime levels so the deployed capability surface remains intentionally narrow.
+
+| Area | Phillnet Mini Text-Vision behavior |
+|---|---|
+| Language generation | **Enabled** through `DendroForCausalLM.generate(...)`. |
+| Still-image understanding | **Enabled** through the local `DendroVisionProcessor`, the visual encoder, and multimodal chat inputs. |
+| SDXL image synthesis | **Removed**, including SDXL weights, U-Net, VAE, text encoders, scheduler, adapter, and public generation methods. |
+| Video synthesis | **Removed**. |
+| Audio, tools, agents, orchestration | **Not exposed** by the lean package or the included service. |
+| External processor requirement | **Removed**. The package includes a local processor that uses the checkpoint’s native Qwen tokenizer and vision-token contract. |
+
+The retained `model.safetensors` checkpoint is unchanged from the source core checkpoint:
+
+```text
+SHA-256: f1a913f99f8ce921c1aa79982a09eaee6744448766f09a4756751e2d4b9342fc
+```
+
+## Adaptive reasoning defaults
+
+The package is configured for deep adaptive inference by default. The model’s private reasoning stays private; only the final answer is returned from `model.generate(...)`.
+
+| Default | Value | Meaning |
+|---|---:|---|
+| Default reasoning effort | `max` | Uses the highest configured adaptive effort profile when the caller does not override it. |
+| Adaptive private reasoning | `true` | The private phase can expand and stop naturally at the model’s end-of-thinking token. |
+| Private-reasoning policy | `adaptive_context` | The private phase is bounded by the active physical context/cache boundary rather than a small caller cap. |
+| Visible answer ceiling | **8,192 tokens** | Keeps long-form answers and code generation practical and predictable. |
+| Active context/cache window | 32,768 tokens | Establishes the physical boundary for prompt, private reasoning, and answer allocation. |
+
+> “Adaptive” does not mean unbounded hardware usage. The model may reason for as long as the active context and cache allocation permit, then reserves a separately bounded visible answer. This package’s visible-answer ceiling is intentionally fixed at **8,192 tokens**.
+
+The included FastAPI service also defaults to `reasoning_effort="max"` and `max_tokens=8192`. Requests can explicitly select `direct`, `low`, `medium`, `high`, or `max` when latency or cost behavior needs to differ.
+
+## Installation
+
+```bash
+pip install -r requirements.txt
+```
+
+The package uses custom Transformers code, so load it from a local checkout or trusted repository with `trust_remote_code=True` for the model and processor.
+
+```python
+import torch
+from transformers import AutoModelForCausalLM, AutoProcessor
+
+model_dir = "./Phillnet-Mini-Text-Vision"
+
+processor = AutoProcessor.from_pretrained(
+    model_dir,
+    trust_remote_code=True,
+)
+model = AutoModelForCausalLM.from_pretrained(
+    model_dir,
+    trust_remote_code=True,
+    dtype=torch.bfloat16,
+    low_cpu_mem_usage=True,
+).eval()
+```
+
+## Text generation
+
+### Use the persisted maximum adaptive defaults
+
+The call below deliberately omits `max_new_tokens`, `max_reasoning_tokens`, and `reasoning_budget`. The model therefore uses its loaded maximum adaptive profile and 8,192-token visible-answer ceiling.
+
+```python
+messages = [{
+    "role": "user",
+    "content": "Write a concise release note for a focused note-taking application.",
+}]
+
+inputs = processor.apply_chat_template(
+    messages,
+    tokenize=True,
+    add_generation_prompt=True,
+    return_dict=True,
+    return_tensors="pt",
+)
+
+output = model.generate(
+    **inputs,
+    do_sample=False,
+    use_cache=True,
+)
+
+prompt_length = inputs["input_ids"].shape[1]
+answer = processor.tokenizer.decode(
+    output[0, prompt_length:],
+    skip_special_tokens=True,
+)
+print(answer)
+```
+
+### Choose a lower-latency profile
+
+```python
+output = model.generate(
+    **inputs,
+    reasoning_effort="direct",
+    max_new_tokens=256,
+    do_sample=False,
+    use_cache=True,
+)
+```
+
+## Still-image understanding
+
+The bundled `DendroVisionProcessor` accepts PIL images directly. It performs local visual patch preparation, emits the correct visual placeholder sequence, and injects visual features before the assistant response prefix.
+
+```python
+from PIL import Image
+
+image = Image.open("scene.png").convert("RGB")
+messages = [{
+    "role": "user",
+    "content": [
+        {"type": "image", "image": image},
+        {"type": "text", "text": "Describe the important objects and their relative positions."},
+    ],
+}]
+
+inputs = processor.apply_chat_template(
+    messages,
+    tokenize=True,
+    add_generation_prompt=True,
+    return_dict=True,
+    return_tensors="pt",
+)
+
+output = model.generate(
+    **inputs,
+    reasoning_effort="medium",
+    max_new_tokens=512,
+    do_sample=False,
+    use_cache=True,
+)
+
+prompt_length = inputs["input_ids"].shape[1]
+print(processor.tokenizer.decode(output[0, prompt_length:], skip_special_tokens=True))
+```
+
+## HTTP service
+
+The package includes a small OpenAI-style FastAPI service that intentionally exposes only text generation and still-image understanding.
+
+```bash
+pip install -r requirements.txt -r requirements-server.txt
+uvicorn server:app --host 0.0.0.0 --port 8000
+```
+
+Check availability:
+
+```bash
+curl http://localhost:8000/health
+```
+
+Submit a text request using the default maximum adaptive behavior:
+
+```bash
+curl http://localhost:8000/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  --data '{
+    "messages": [{"role": "user", "content": "Create a compact project brief for a solar dashboard."}]
+  }'
+```
+
+The endpoint accepts a base64-encoded still image through an `image_base64` content item. It deliberately does not fetch remote image URLs.
+
+```bash
+IMAGE_B64=$(base64 -w0 scene.png)
+curl http://localhost:8000/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  --data "{
+    \"messages\": [{
+      \"role\": \"user\",
+      \"content\": [
+        {\"type\": \"image\", \"image_base64\": \"${IMAGE_B64}\"},
+        {\"type\": \"text\", \"text\": \"What is visible in this image?\"}
+      ]
+    }]
+  }"
+```
+
+## Production deployment
+
+The repository includes a hardened single-worker container path for self-hosted inference. It runs as a non-root user, exposes readiness checks, serializes local generation to prevent memory overcommit, accepts only inline base64 still images, and supports optional bearer or `X-API-Key` authentication.
+
+```bash
+# On a server that has Docker and Docker Compose installed.
+cp .env.example .env
+# Edit .env: set a long PHILLNET_API_KEY and your exact browser origin.
+docker compose up --build -d
+
+docker compose ps
+curl http://127.0.0.1:8000/health
+```
+
+The compose file binds to `127.0.0.1:8000` by default. Place a TLS-terminating reverse proxy in front of it for public traffic, set `PHILLNET_CORS_ORIGINS` to the exact allowed application origin, and keep `PHILLNET_API_KEY` non-empty. Do not place the model API directly on the public internet without authentication and rate limiting at the edge.
+
+| Environment variable | Default | Deployment purpose |
+|---|---|---|
+| `PHILLNET_API_KEY` | Empty locally | Enforces bearer or `X-API-Key` authentication when set. |
+| `PHILLNET_CORS_ORIGINS` | Disabled | Allows only named browser origins. |
+| `PHILLNET_MAX_IMAGE_BYTES` | 10 MiB | Rejects oversized decoded image payloads. |
+| `PHILLNET_MAX_IMAGE_PIXELS` | 24,000,000 | Limits decoded image dimensions. |
+| `PHILLNET_MAX_REQUEST_BYTES` | 12 MiB | Rejects oversized request bodies before inference. |
+| `PHILLNET_BIND_ADDRESS` | `127.0.0.1` | Keeps the compose service loopback-bound by default. |
+| `PHILLNET_PORT` | `8000` | Changes the host listener port. |
+
+See [HF_UPLOAD.md](HF_UPLOAD.md) for the complete Hugging Face upload workflow and [`.env.example`](.env.example) for deployment values.
+
+## Validation snapshot
+
+The lean package was tested with structural checks, local model loading, text completion, visual patch preparation, visual grounding, basic spatial grounding, and service-level requests.
+
+| Validation | Verified result |
+|---|---|
+| Core checkpoint loading | `DendroForCausalLM` loaded in BF16. |
+| Tokenizer contract | Local `Qwen2Tokenizer` matches the checkpoint’s 248,320-token vocabulary. |
+| Processor contract | `AutoProcessor` resolves to `DendroVisionProcessor`. |
+| Text coherence | Deterministic chat probes returned `Paris`, `4`, and `blue`. |
+| Color grounding | Solid red, green, blue, white, and black probes returned the corresponding color. |
+| Spatial grounding | A red-left / blue-right scene returned `red` for left and `blue` for right. |
+| SDXL exclusion | SDXL weights, code, configuration, dependencies, and synthesis APIs are absent. |
+| Full adaptive HTML generation | A complete 2,991-token Orbit Notes page was generated after 2,944 private-reasoning tokens. |
+
+## Layout
+
+| Path | Purpose |
+|---|---|
+| `model.safetensors` | Retained language and visual-understanding checkpoint. |
+| `processing_dendro_omni.py` | Local native-tokenizer text-and-image processor. |
+| `modeling_dendro_omni.py` | Custom language and multimodal generation runtime. |
+| `server.py` | Text-and-vision-only HTTP service. |
+| `examples/` | Completed HTML examples and PNG previews. |
+| `ADAPTIVE_DEFAULTS_REPORT.md` | Deep configuration and long-form generation report. |
+| `PRODUCTION.md` | Deployment architecture, authentication, limits, reverse proxy, and operating guide. |
+| `HF_UPLOAD.md` | Current Hugging Face upload workflow and verification checklist. |
+| `COHERENCE_REPAIR_REPORT.md` | Tokenizer, chat-template, and spatial-input repair record. |
+| `IMPLEMENTATION_REPORT.md` | Original lean-package removal and validation report. |
+
+## Operational notes
+
+The core checkpoint is approximately 1.76 GB. Deep adaptive reasoning and long code generation can require substantially more memory and time than direct short-answer requests. For production use, evaluate target hardware, concurrency, request limits, observability, and authentication before exposing the API publicly.
+
+## License and attribution
+
+This derivative retains the upstream model’s Apache-2.0 license designation. Consult the source model card and included licensing files before redistribution or use in a product. [1]
+
+## References
+
+[1]: https://huggingface.co/ayjays132/Phillnet-Mini-Omni-Max "ayjays132/Phillnet-Mini-Omni-Max"

RELEASE_MANIFEST.json

@@ -0,0 +1,59 @@
+{
+  "schema_version": "1.0",
+  "release": {
+    "name": "Phillnet Mini Text-Vision",
+    "version": "1.1.0",
+    "release_date": "2026-08-21",
+    "license": "Apache-2.0",
+    "source_model": "https://huggingface.co/ayjays132/Phillnet-Mini-Omni-Max"
+  },
+  "repository": {
+    "upload_root": true,
+    "file_count_excluding_this_manifest": 48,
+    "size_bytes_excluding_this_manifest": 1785015195,
+    "lfs_artifacts": [
+      "model.safetensors",
+      "tokenizer.json"
+    ]
+  },
+  "artifacts": {
+    "model.safetensors": {
+      "bytes": 1763655304,
+      "sha256": "f1a913f99f8ce921c1aa79982a09eaee6744448766f09a4756751e2d4b9342fc"
+    },
+    "tokenizer.json": {
+      "bytes": 19989325,
+      "sha256": "06b9509352d2af50381ab2247e083b80d32d5c0aba91c272ca9ff729b6a0e523"
+    }
+  },
+  "capabilities": {
+    "enabled": [
+      "text-generation",
+      "still-image-understanding"
+    ],
+    "disabled": [
+      "sdxl-image-generation",
+      "video-generation",
+      "audio",
+      "tools",
+      "agents",
+      "remote-image-url-fetching"
+    ]
+  },
+  "inference_defaults": {
+    "reasoning_effort": "max",
+    "adaptive_private_reasoning": true,
+    "private_reasoning_policy": "adaptive_context",
+    "max_visible_answer_tokens": 8192,
+    "active_context_window_tokens": 32768
+  },
+  "deployment": {
+    "container": "Dockerfile",
+    "compose": "docker-compose.yml",
+    "service": "server.py",
+    "authentication": "PHILLNET_API_KEY (optional locally, required for public deployment)",
+    "api_route": "/v1/chat/completions",
+    "health_route": "/health",
+    "readiness_route": "/ready"
+  }
+}

RELEASE_VALIDATION.md

@@ -0,0 +1,27 @@
+# Release Validation
+
+**Release:** Phillnet Mini Text-Vision v1.1.0  
+**Date:** 21 August 2026
+
+## Completed checks
+
+| Check | Result |
+|---|---|
+| Custom model Python modules | All root Python modules compile successfully. |
+| `config.json` and `RELEASE_MANIFEST.json` | Valid JSON. |
+| Retained model checkpoint | SHA-256 matches the value in `RELEASE_MANIFEST.json`. |
+| Example gallery | All three HTML and PNG assets are present. |
+| Hugging Face large-file policy | `model.safetensors` and `tokenizer.json` are explicitly marked for LFS. |
+| Repository hygiene | `.gitignore` excludes bytecode caches, secrets, logs, and archives. |
+| Production files | `Dockerfile`, `docker-compose.yml`, `.env.example`, `PRODUCTION.md`, and `HF_UPLOAD.md` are present. |
+| API-key gate | Missing credentials are rejected when `PHILLNET_API_KEY` is set; bearer and `X-API-Key` forms are accepted. |
+| Request safeguards | Maximum image byte, pixel, and request-body limits were validated. |
+| Temporary deployment | Fresh `/health` and `/ready` checks returned a ready text-and-vision-only service. |
+
+## Validation boundary
+
+The available environment does not include Docker, so the container image and Compose runtime were inspected and validated statically rather than built locally. The Python service was compiled and loaded directly with the full model checkpoint, then checked through its HTTP health and readiness routes.
+
+## Upload status
+
+The repository is ready to upload as a complete Hugging Face model repository. Follow [HF_UPLOAD.md](HF_UPLOAD.md) from the parent directory and verify the checksum in [RELEASE_MANIFEST.json](RELEASE_MANIFEST.json) after transfer.

__init__.py

@@ -0,0 +1,33 @@
+"""Phillnet Mini Text-Vision: language generation and image understanding only."""
+
+from .cache import DendroKVCache, QuantizedCacheTensor
+from .configuration_dendro_omni import DendroOmniConfig
+from .modeling_dendro_omni import (
+    DendroAnswerGenerationOutput,
+    DendroBaseModelOutputWithPast,
+    DendroCausalLMOutput,
+    DendroForCausalLM,
+    DendroOmniModel,
+    register_dendro_auto_classes,
+)
+from .processing_dendro_omni import DendroVisionProcessor
+from .tokenization_dendro_omni import DendroByteTokenizer
+from .vision_routing import DendroVisionAnswer, build_vision_views
+
+__version__ = "1.0.0-text-vision"
+
+__all__ = [
+    "DendroAnswerGenerationOutput",
+    "DendroBaseModelOutputWithPast",
+    "DendroByteTokenizer",
+    "DendroCausalLMOutput",
+    "DendroForCausalLM",
+    "DendroKVCache",
+    "DendroOmniConfig",
+    "DendroOmniModel",
+    "DendroVisionAnswer",
+    "DendroVisionProcessor",
+    "QuantizedCacheTensor",
+    "build_vision_views",
+    "register_dendro_auto_classes",
+]

chat_template.jinja

@@ -0,0 +1,154 @@
+{%- set image_count = namespace(value=0) %}
+{%- set video_count = namespace(value=0) %}
+{%- macro render_content(content, do_vision_count, is_system_content=false) %}
+    {%- if content is string %}
+        {{- content }}
+    {%- elif content is iterable and content is not mapping %}
+        {%- for item in content %}
+            {%- if 'image' in item or 'image_url' in item or item.type == 'image' %}
+                {%- if is_system_content %}
+                    {{- raise_exception('System message cannot contain images.') }}
+                {%- endif %}
+                {%- if do_vision_count %}
+                    {%- set image_count.value = image_count.value + 1 %}
+                {%- endif %}
+                {%- if add_vision_id %}
+                    {{- 'Picture ' ~ image_count.value ~ ': ' }}
+                {%- endif %}
+                {{- '<|vision_start|><|image_pad|><|vision_end|>' }}
+            {%- elif 'video' in item or item.type == 'video' %}
+                {%- if is_system_content %}
+                    {{- raise_exception('System message cannot contain videos.') }}
+                {%- endif %}
+                {%- if do_vision_count %}
+                    {%- set video_count.value = video_count.value + 1 %}
+                {%- endif %}
+                {%- if add_vision_id %}
+                    {{- 'Video ' ~ video_count.value ~ ': ' }}
+                {%- endif %}
+                {{- '<|vision_start|><|video_pad|><|vision_end|>' }}
+            {%- elif 'text' in item %}
+                {{- item.text }}
+            {%- else %}
+                {{- raise_exception('Unexpected item type in content.') }}
+            {%- endif %}
+        {%- endfor %}
+    {%- elif content is none or content is undefined %}
+        {{- '' }}
+    {%- else %}
+        {{- raise_exception('Unexpected content type.') }}
+    {%- endif %}
+{%- endmacro %}
+{%- if not messages %}
+    {{- raise_exception('No messages provided.') }}
+{%- endif %}
+{%- if tools and tools is iterable and tools is not mapping %}
+    {{- '<|im_start|>system\n' }}
+    {{- "# Tools\n\nYou have access to the following functions:\n\n<tools>" }}
+    {%- for tool in tools %}
+        {{- "\n" }}
+        {{- tool | tojson }}
+    {%- endfor %}
+    {{- "\n</tools>" }}
+    {{- '\n\nIf you choose to call a function ONLY reply in the following format with NO suffix:\n\n<tool_call>\n<function=example_function_name>\n<parameter=example_parameter_1>\nvalue_1\n</parameter>\n<parameter=example_parameter_2>\nThis is the value for the second parameter\nthat can span\nmultiple lines\n</parameter>\n</function>\n</tool_call>\n\n<IMPORTANT>\nReminder:\n- Function calls MUST follow the specified format: an inner <function=...></function> block must be nested within <tool_call></tool_call> XML tags\n- Required parameters MUST be specified\n- You may provide optional reasoning for your function call in natural language BEFORE the function call, but NOT after\n- If there is no function call available, answer the question like normal with your current knowledge and do not tell the user about function calls\n</IMPORTANT>' }}
+    {%- if messages[0].role == 'system' %}
+        {%- set content = render_content(messages[0].content, false, true)|trim %}
+        {%- if content %}
+            {{- '\n\n' + content }}
+        {%- endif %}
+    {%- endif %}
+    {{- '<|im_end|>\n' }}
+{%- else %}
+    {%- if messages[0].role == 'system' %}
+        {%- set content = render_content(messages[0].content, false, true)|trim %}
+        {{- '<|im_start|>system\n' + content + '<|im_end|>\n' }}
+    {%- endif %}
+{%- endif %}
+{%- set ns = namespace(multi_step_tool=true, last_query_index=messages|length - 1) %}
+{%- for message in messages[::-1] %}
+    {%- set index = (messages|length - 1) - loop.index0 %}
+    {%- if ns.multi_step_tool and message.role == "user" %}
+        {%- set content = render_content(message.content, false)|trim %}
+        {%- if not(content.startswith('<tool_response>') and content.endswith('</tool_response>')) %}
+            {%- set ns.multi_step_tool = false %}
+            {%- set ns.last_query_index = index %}
+        {%- endif %}
+    {%- endif %}
+{%- endfor %}
+{%- if ns.multi_step_tool %}
+    {{- raise_exception('No user query found in messages.') }}
+{%- endif %}
+{%- for message in messages %}
+    {%- set content = render_content(message.content, true)|trim %}
+    {%- if message.role == "system" %}
+        {%- if not loop.first %}
+            {{- raise_exception('System message must be at the beginning.') }}
+        {%- endif %}
+    {%- elif message.role == "user" %}
+        {{- '<|im_start|>' + message.role + '\n' + content + '<|im_end|>' + '\n' }}
+    {%- elif message.role == "assistant" %}
+        {%- set reasoning_content = '' %}
+        {%- if message.reasoning_content is string %}
+            {%- set reasoning_content = message.reasoning_content %}
+        {%- else %}
+            {%- if '</think>' in content %}
+                {%- set reasoning_content = content.split('</think>')[0].rstrip('\n').split('<think>')[-1].lstrip('\n') %}
+                {%- set content = content.split('</think>')[-1].lstrip('\n') %}
+            {%- endif %}
+        {%- endif %}
+        {%- set reasoning_content = reasoning_content|trim %}
+        {%- if loop.index0 > ns.last_query_index %}
+            {{- '<|im_start|>' + message.role + '\n<think>\n' + reasoning_content + '\n</think>\n\n' + content }}
+        {%- else %}
+            {{- '<|im_start|>' + message.role + '\n' + content }}
+        {%- endif %}
+        {%- if message.tool_calls and message.tool_calls is iterable and message.tool_calls is not mapping %}
+            {%- for tool_call in message.tool_calls %}
+                {%- if tool_call.function is defined %}
+                    {%- set tool_call = tool_call.function %}
+                {%- endif %}
+                {%- if loop.first %}
+                    {%- if content|trim %}
+                        {{- '\n\n<tool_call>\n<function=' + tool_call.name + '>\n' }}
+                    {%- else %}
+                        {{- '<tool_call>\n<function=' + tool_call.name + '>\n' }}
+                    {%- endif %}
+                {%- else %}
+                    {{- '\n<tool_call>\n<function=' + tool_call.name + '>\n' }}
+                {%- endif %}
+                {%- if tool_call.arguments is defined %}
+                    {%- for args_name, args_value in tool_call.arguments|items %}
+                        {{- '<parameter=' + args_name + '>\n' }}
+                        {%- set args_value = args_value | tojson | safe if args_value is mapping or (args_value is sequence and args_value is not string) else args_value | string %}
+                        {{- args_value }}
+                        {{- '\n</parameter>\n' }}
+                    {%- endfor %}
+                {%- endif %}
+                {{- '</function>\n</tool_call>' }}
+            {%- endfor %}
+        {%- endif %}
+        {{- '<|im_end|>\n' }}
+    {%- elif message.role == "tool" %}
+        {%- if loop.previtem and loop.previtem.role != "tool" %}
+            {{- '<|im_start|>user' }}
+        {%- endif %}
+        {{- '\n<tool_response>\n' }}
+        {{- content }}
+        {{- '\n</tool_response>' }}
+        {%- if not loop.last and loop.nextitem.role != "tool" %}
+            {{- '<|im_end|>\n' }}
+        {%- elif loop.last %}
+            {{- '<|im_end|>\n' }}
+        {%- endif %}
+    {%- else %}
+        {{- raise_exception('Unexpected message role.') }}
+    {%- endif %}
+{%- endfor %}
+{%- if add_generation_prompt %}
+    {{- '<|im_start|>assistant\n' }}
+    {%- if enable_thinking is defined and enable_thinking is true %}
+        {{- '<think>\n' }}
+    {%- else %}
+        {{- '<think>\n\n</think>\n\n' }}
+    {%- endif %}
+{%- endif %}

docker-compose.yml

@@ -0,0 +1,23 @@
+services:
+  phillnet-mini-text-vision:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    image: phillnet-mini-text-vision:1.1.0
+    restart: unless-stopped
+    env_file:
+      - .env
+    ports:
+      - "${PHILLNET_BIND_ADDRESS:-127.0.0.1}:${PHILLNET_PORT:-8000}:8000"
+    init: true
+    read_only: true
+    tmpfs:
+      - /tmp:rw,noexec,nosuid,size=256m
+    security_opt:
+      - no-new-privileges:true
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/ready', timeout=3)"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 120s

modalities.py

@@ -0,0 +1,407 @@
+"""Real multimodal patchification and packing into one Dendro token space."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import torch
+from torch.nn import functional as F
+
+from ._source_bound import SourceBoundModule
+from .configuration_dendro_omni import DendroOmniConfig
+from .source import DendroSourceLayer
+from .spatial import (
+    MODALITY_AUDIO,
+    MODALITY_IMAGE,
+    MODALITY_POSITION_OFFSETS,
+    MODALITY_SENSOR,
+    MODALITY_TEXT,
+    MODALITY_VIDEO,
+    DendroSpatialEncoder,
+)
+
+
+@dataclass(slots=True)
+class ModalitySegment:
+    name: str
+    modality_id: int
+    start: int
+    end: int
+    shape: tuple[int, ...]
+
+    @property
+    def length(self) -> int:
+        return self.end - self.start
+
+
+@dataclass(slots=True)
+class DendroModalityLayout:
+    modality_ids: torch.Tensor
+    sequence_positions: torch.Tensor
+    logical_positions: torch.Tensor
+    coordinates: torch.Tensor
+    is_prefix: torch.Tensor
+    attention_mask: torch.Tensor
+    segments: tuple[ModalitySegment, ...]
+    text_start: int
+    text_length: int
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "segments": [
+                {
+                    "name": segment.name,
+                    "modality_id": segment.modality_id,
+                    "start": segment.start,
+                    "end": segment.end,
+                    "length": segment.length,
+                    "shape": segment.shape,
+                }
+                for segment in self.segments
+            ],
+            "text_start": self.text_start,
+            "text_length": self.text_length,
+            "total_length": int(self.modality_ids.shape[-1]),
+            "prefix_length": int(self.is_prefix[0].sum().item()) if self.is_prefix.numel() else 0,
+        }
+
+
+@dataclass(slots=True)
+class DendroPackedInput:
+    hidden_states: torch.Tensor
+    layout: DendroModalityLayout
+    aligned_labels: torch.Tensor | None = None
+
+
+class DendroOmniInputProjector(SourceBoundModule):
+    """Parameterless modality adapters backed entirely by ``DendroSourceLayer``."""
+
+    def __init__(self, config: DendroOmniConfig, source: DendroSourceLayer) -> None:
+        super().__init__(source)
+        self.config = config
+        self.spatial_encoder = DendroSpatialEncoder(config, source)
+
+    @staticmethod
+    def _batch_size(*values: torch.Tensor | None) -> int:
+        batches = [int(value.shape[0]) for value in values if value is not None]
+        if not batches:
+            raise ValueError("At least one text, image, audio, video, or sensor input is required")
+        if any(batch != batches[0] for batch in batches):
+            raise ValueError(f"All modalities must share a batch size, got {batches}")
+        return batches[0]
+
+    @staticmethod
+    def _normalize_coords(index: torch.Tensor, maximum: int) -> torch.Tensor:
+        if maximum <= 1:
+            return torch.zeros_like(index, dtype=torch.float32)
+        return index.float() / float(maximum - 1) * 2.0 - 1.0
+
+    def _token_features(self, input_ids: torch.Tensor, token_hidden: torch.Tensor) -> torch.Tensor:
+        source = self.source
+        offset = self.config.byte_offset
+        byte = input_ids - offset
+        atom_ids = torch.zeros_like(input_ids)
+        atom_ids = torch.where((byte >= ord("0")) & (byte <= ord("9")), 1, atom_ids)
+        atom_ids = torch.where(
+            ((byte >= ord("A")) & (byte <= ord("Z"))) | ((byte >= ord("a")) & (byte <= ord("z"))),
+            2,
+            atom_ids,
+        )
+        atom_ids = torch.where((byte == 9) | (byte == 10) | (byte == 13) | (byte == 32), 3, atom_ids)
+        atom_ids = torch.where((byte >= 128) & (byte <= 255), 4, atom_ids)
+        atom_ids = torch.where(input_ids < offset, 5, atom_ids)
+        atoms = source.embedding(atom_ids, "token/atoms", 6, self.config.hidden_size)
+
+        # Atom -> bond -> molecule composition is deliberately pointwise here. Any
+        # cross-token neighborhood operation belongs inside cache-aware attention;
+        # otherwise a one-token decode chunk would not match full-sequence training.
+        bond_input = token_hidden * torch.tanh(atoms)
+        bonds = source.project(bond_input, "token/bonds", self.config.hidden_size, low_bit=False)
+        molecule_input = F.silu(bonds) + 0.5 * token_hidden + 0.25 * atoms
+        molecules = source.project(molecule_input, "token/molecules", self.config.hidden_size, low_bit=False)
+        gate = source.gate(torch.cat([token_hidden, atoms], dim=-1), "token/compose_gate", self.config.hidden_size)
+        return token_hidden + 0.15 * atoms + 0.10 * gate * bonds + 0.10 * (1.0 - gate) * molecules
+
+    def _text(
+        self,
+        input_ids: torch.Tensor | None,
+        inputs_embeds: torch.Tensor | None,
+        attention_mask: torch.Tensor | None,
+        *,
+        position_start: int,
+        prefix_mask: torch.Tensor | None,
+    ) -> tuple[torch.Tensor, dict[str, torch.Tensor], tuple[int, ...]] | None:
+        if input_ids is None and inputs_embeds is None:
+            return None
+        if input_ids is not None and inputs_embeds is not None:
+            raise ValueError("Pass input_ids or inputs_embeds, not both")
+        if inputs_embeds is None:
+            assert input_ids is not None
+            hidden = self.source.embedding(
+                input_ids,
+                "token",
+                self.config.vocab_size,
+                self.config.hidden_size,
+            )
+            hidden = self._token_features(input_ids, hidden)
+        else:
+            if inputs_embeds.shape[-1] != self.config.hidden_size:
+                raise ValueError("inputs_embeds last dimension must equal hidden_size")
+            hidden = inputs_embeds
+        batch, length = hidden.shape[:2]
+        device = hidden.device
+        positions = torch.arange(position_start, position_start + length, device=device).expand(batch, -1)
+        logical = positions + MODALITY_POSITION_OFFSETS[MODALITY_TEXT]
+        coords = torch.zeros(batch, length, 4, device=device, dtype=hidden.dtype)
+        # Absolute coordinates must be invariant to chunking.  Normalizing by the
+        # current input length made a token receive different spatial features during
+        # full-sequence training and cached one-token decoding.
+        denominator = max(1, self.config.max_position_embeddings - 1)
+        coords[..., 0] = (positions.to(hidden.dtype) / denominator * 2.0 - 1.0).clamp(-1.0, 1.0)
+        modality = torch.full((batch, length), MODALITY_TEXT, device=device, dtype=torch.long)
+        is_prefix = (
+            prefix_mask.to(device=device, dtype=torch.bool)
+            if prefix_mask is not None
+            else torch.zeros(batch, length, device=device, dtype=torch.bool)
+        )
+        mask = (
+            attention_mask.to(device=device, dtype=torch.bool)
+            if attention_mask is not None
+            else torch.ones(batch, length, device=device, dtype=torch.bool)
+        )
+        return hidden, {
+            "modality": modality,
+            "positions": positions,
+            "logical": logical,
+            "coords": coords,
+            "prefix": is_prefix,
+            "mask": mask,
+        }, (length,)
+
+    def _image(self, pixel_values: torch.Tensor | None) -> tuple[torch.Tensor, dict[str, torch.Tensor], tuple[int, ...]] | None:
+        if pixel_values is None:
+            return None
+        if pixel_values.ndim != 4:
+            raise ValueError("pixel_values must be [batch, channels, height, width]")
+        batch, channels, height, width = pixel_values.shape
+        if channels != self.config.image_channels:
+            raise ValueError(f"Expected {self.config.image_channels} image channels, got {channels}")
+        patch = self.config.image_patch_size
+        pad_h, pad_w = (-height) % patch, (-width) % patch
+        values = F.pad(pixel_values, (0, pad_w, 0, pad_h))
+        grid_h, grid_w = values.shape[-2] // patch, values.shape[-1] // patch
+        patches = F.unfold(values, kernel_size=patch, stride=patch).transpose(1, 2)
+        hidden = self.source.project(patches, "modality/image_patch", self.config.hidden_size)
+        length = hidden.shape[1]
+        y = torch.arange(grid_h, device=hidden.device).repeat_interleave(grid_w)
+        x = torch.arange(grid_w, device=hidden.device).repeat(grid_h)
+        coords = torch.zeros(batch, length, 4, device=hidden.device, dtype=hidden.dtype)
+        coords[..., 1] = self._normalize_coords(y, grid_h)
+        coords[..., 2] = self._normalize_coords(x, grid_w)
+        local = torch.arange(length, device=hidden.device).expand(batch, -1)
+        return hidden, self._metadata(local, coords, MODALITY_IMAGE, prefix=True), (grid_h, grid_w)
+
+    def _audio(self, audio_values: torch.Tensor | None) -> tuple[torch.Tensor, dict[str, torch.Tensor], tuple[int, ...]] | None:
+        if audio_values is None:
+            return None
+        if audio_values.ndim == 3:
+            audio_values = audio_values.mean(dim=1)
+        if audio_values.ndim != 2:
+            raise ValueError("audio_values must be [batch, samples] or [batch, channels, samples]")
+        patch, stride = self.config.audio_patch_size, self.config.audio_patch_stride
+        if audio_values.shape[-1] < patch:
+            audio_values = F.pad(audio_values, (0, patch - audio_values.shape[-1]))
+        remainder = (audio_values.shape[-1] - patch) % stride
+        if remainder:
+            audio_values = F.pad(audio_values, (0, stride - remainder))
+        windows = audio_values.unfold(-1, patch, stride)
+        hidden = self.source.project(windows, "modality/audio_patch", self.config.hidden_size)
+        length = hidden.shape[1]
+        local = torch.arange(length, device=hidden.device).expand(hidden.shape[0], -1)
+        coords = torch.zeros(hidden.shape[0], length, 4, device=hidden.device, dtype=hidden.dtype)
+        coords[..., 0] = self._normalize_coords(torch.arange(length, device=hidden.device), length)
+        # Frequency-energy coordinate gives raw wave patches a useful second axis.
+        spectrum = torch.fft.rfft(windows.float(), dim=-1).abs().mean(dim=-1)
+        spectrum = spectrum / spectrum.amax(dim=-1, keepdim=True).clamp_min(1e-8)
+        coords[..., 3] = spectrum.to(hidden.dtype) * 2.0 - 1.0
+        return hidden, self._metadata(local, coords, MODALITY_AUDIO, prefix=True), (length, patch)
+
+    def _video(self, video_values: torch.Tensor | None) -> tuple[torch.Tensor, dict[str, torch.Tensor], tuple[int, ...]] | None:
+        if video_values is None:
+            return None
+        if video_values.ndim != 5:
+            raise ValueError("video_values must be [batch, frames, channels, height, width]")
+        batch, frames, channels, height, width = video_values.shape
+        if channels != self.config.image_channels:
+            raise ValueError(f"Expected {self.config.image_channels} video channels, got {channels}")
+        tube, patch = self.config.video_tubelet_size, self.config.video_patch_size
+        pad_t, pad_h, pad_w = (-frames) % tube, (-height) % patch, (-width) % patch
+        # F.pad follows reverse dimension order for [B,T,C,H,W].
+        values = F.pad(video_values, (0, pad_w, 0, pad_h, 0, 0, 0, pad_t))
+        tg, hg, wg = values.shape[1] // tube, values.shape[3] // patch, values.shape[4] // patch
+        blocks = values.reshape(batch, tg, tube, channels, hg, patch, wg, patch)
+        blocks = blocks.permute(0, 1, 4, 6, 2, 3, 5, 7).reshape(batch, tg * hg * wg, -1)
+        hidden = self.source.project(blocks, "modality/video_tubelet", self.config.hidden_size)
+        t = torch.arange(tg, device=hidden.device).repeat_interleave(hg * wg)
+        y = torch.arange(hg, device=hidden.device).repeat_interleave(wg).repeat(tg)
+        x = torch.arange(wg, device=hidden.device).repeat(hg * tg)
+        coords = torch.zeros(batch, hidden.shape[1], 4, device=hidden.device, dtype=hidden.dtype)
+        coords[..., 0] = self._normalize_coords(t, tg)
+        coords[..., 1] = self._normalize_coords(y, hg)
+        coords[..., 2] = self._normalize_coords(x, wg)
+        local = torch.arange(hidden.shape[1], device=hidden.device).expand(batch, -1)
+        return hidden, self._metadata(local, coords, MODALITY_VIDEO, prefix=True), (tg, hg, wg)
+
+    def _sensor(self, sensor_values: torch.Tensor | None) -> tuple[torch.Tensor, dict[str, torch.Tensor], tuple[int, ...]] | None:
+        if sensor_values is None:
+            return None
+        if sensor_values.ndim == 2:
+            sensor_values = sensor_values.unsqueeze(1)
+        if sensor_values.ndim != 3:
+            raise ValueError("sensor_values must be [batch, steps, features] or [batch, features]")
+        target = self.config.sensor_feature_size
+        if sensor_values.shape[-1] < target:
+            sensor_values = F.pad(sensor_values, (0, target - sensor_values.shape[-1]))
+        elif sensor_values.shape[-1] > target:
+            sensor_values = sensor_values[..., :target]
+        hidden = self.source.project(sensor_values, "modality/sensor", self.config.hidden_size)
+        length = hidden.shape[1]
+        local = torch.arange(length, device=hidden.device).expand(hidden.shape[0], -1)
+        coords = torch.zeros(hidden.shape[0], length, 4, device=hidden.device, dtype=hidden.dtype)
+        coords[..., 0] = self._normalize_coords(torch.arange(length, device=hidden.device), length)
+        coords[..., 3] = sensor_values.float().std(dim=-1).to(hidden.dtype).clamp(max=1.0) * 2.0 - 1.0
+        return hidden, self._metadata(local, coords, MODALITY_SENSOR, prefix=True), (length, target)
+
+    @staticmethod
+    def _metadata(
+        local: torch.Tensor,
+        coords: torch.Tensor,
+        modality_id: int,
+        *,
+        prefix: bool,
+    ) -> dict[str, torch.Tensor]:
+        batch, length = local.shape
+        device = local.device
+        return {
+            "modality": torch.full((batch, length), modality_id, device=device, dtype=torch.long),
+            "positions": local,
+            "logical": local + MODALITY_POSITION_OFFSETS[modality_id],
+            "coords": coords,
+            "prefix": torch.full((batch, length), prefix, device=device, dtype=torch.bool),
+            "mask": torch.ones(batch, length, device=device, dtype=torch.bool),
+        }
+
+    def forward(
+        self,
+        *,
+        input_ids: torch.Tensor | None = None,
+        inputs_embeds: torch.Tensor | None = None,
+        attention_mask: torch.Tensor | None = None,
+        pixel_values: torch.Tensor | None = None,
+        audio_values: torch.Tensor | None = None,
+        video_values: torch.Tensor | None = None,
+        sensor_values: torch.Tensor | None = None,
+        prefix_mask: torch.Tensor | None = None,
+        labels: torch.Tensor | None = None,
+        position_start: int = 0,
+    ) -> DendroPackedInput:
+        self._batch_size(input_ids, inputs_embeds, pixel_values, audio_values, video_values, sensor_values)
+        # Non-text modalities form a bidirectional perceptual prefix. Text remains
+        # last so causal decoding can append tokens without repacking old inputs.
+        parts = [
+            ("image", MODALITY_IMAGE, self._image(pixel_values)),
+            ("video", MODALITY_VIDEO, self._video(video_values)),
+            ("audio", MODALITY_AUDIO, self._audio(audio_values)),
+            ("sensor", MODALITY_SENSOR, self._sensor(sensor_values)),
+            (
+                "text",
+                MODALITY_TEXT,
+                self._text(
+                    input_ids,
+                    inputs_embeds,
+                    attention_mask,
+                    position_start=position_start,
+                    prefix_mask=prefix_mask,
+                ),
+            ),
+        ]
+        hidden_parts: list[torch.Tensor] = []
+        metadata: dict[str, list[torch.Tensor]] = {
+            "modality": [],
+            "positions": [],
+            "logical": [],
+            "coords": [],
+            "prefix": [],
+            "mask": [],
+        }
+        segments: list[ModalitySegment] = []
+        cursor = 0
+        text_start, text_length = 0, 0
+        for name, modality_id, result in parts:
+            if result is None:
+                continue
+            hidden, info, original_shape = result
+            length = int(hidden.shape[1])
+            # Physical sequence positions are contiguous across the packed sequence.
+            physical = torch.arange(cursor + position_start, cursor + position_start + length, device=hidden.device)
+            info["positions"] = physical.expand(hidden.shape[0], -1)
+            # Logical modality offsets are applied to the same absolute physical
+            # positions so a token keeps identical coordinates when a multimodal
+            # prefix is processed in one call or reused through KV cache.
+            info["logical"] = info["positions"] + MODALITY_POSITION_OFFSETS[modality_id]
+            if modality_id == MODALITY_TEXT:
+                denominator = max(1, self.config.max_position_embeddings - 1)
+                info["coords"][..., 0] = (
+                    info["positions"].to(hidden.dtype) / denominator * 2.0 - 1.0
+                ).clamp(-1.0, 1.0)
+            hidden_parts.append(hidden)
+            for key in metadata:
+                metadata[key].append(info[key])
+            segments.append(ModalitySegment(name, modality_id, cursor, cursor + length, original_shape))
+            if modality_id == MODALITY_TEXT:
+                text_start, text_length = cursor, length
+            cursor += length
+        if not hidden_parts:
+            raise RuntimeError("No modality generated tokens")
+
+        hidden = torch.cat(hidden_parts, dim=1)
+        combined = {key: torch.cat(values, dim=1) for key, values in metadata.items()}
+        hidden = self.spatial_encoder(
+            hidden,
+            modality_ids=combined["modality"],
+            sequence_positions=combined["positions"],
+            logical_positions=combined["logical"],
+            coordinates=combined["coords"],
+            is_prefix=combined["prefix"],
+        )
+        layout = DendroModalityLayout(
+            modality_ids=combined["modality"],
+            sequence_positions=combined["positions"],
+            logical_positions=combined["logical"],
+            coordinates=combined["coords"],
+            is_prefix=combined["prefix"],
+            attention_mask=combined["mask"],
+            segments=tuple(segments),
+            text_start=text_start,
+            text_length=text_length,
+        )
+
+        aligned_labels = labels
+        if labels is not None:
+            if labels.shape[0] != hidden.shape[0]:
+                raise ValueError("labels batch size does not match inputs")
+            if labels.shape[1] == text_length and text_start > 0:
+                prefix_labels = torch.full(
+                    (labels.shape[0], text_start),
+                    -100,
+                    device=labels.device,
+                    dtype=labels.dtype,
+                )
+                aligned_labels = torch.cat([prefix_labels, labels], dim=1)
+            elif labels.shape[1] != hidden.shape[1]:
+                raise ValueError(
+                    f"labels length {labels.shape[1]} must equal text length {text_length} "
+                    f"or packed length {hidden.shape[1]}"
+                )
+        return DendroPackedInput(hidden_states=hidden, layout=layout, aligned_labels=aligned_labels)

modeling_dendro_omni.py

@@ -0,0 +1,1929 @@
+"""Hugging Face compatible unified Dendro Omni model."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Mapping, Sequence
+
+import torch
+from torch import nn
+from torch.nn import functional as F
+from torch.utils.checkpoint import checkpoint as activation_checkpoint
+
+from ._source_bound import SourceBoundModule
+from .cache import DendroKVCache
+from .cell import DendroCellState, DendroRecurrentCell
+from .configuration_dendro_omni import DendroOmniConfig
+from .hf_compat import (
+    CausalLMOutputWithPast,
+    DendroGenerationConfig,
+    GenerationMixin,
+    ModelOutput,
+    PreTrainedModel,
+    TRANSFORMERS_AVAILABLE,
+)
+from .modalities import DendroModalityLayout, DendroOmniInputProjector
+from .source import DendroSourceLayer
+from .transplant import DendroExactTransplantCore, DendroTransplantCache
+
+
+@dataclass(slots=True)
+class DendroAwakeningCache:
+    """Incremental donor and native state without duplicate model weights."""
+
+    donor: DendroTransplantCache
+    native: DendroKVCache
+
+    @property
+    def total_tokens_seen(self) -> int:
+        return self.donor.total_tokens_seen
+
+    def get_seq_length(self, layer_idx: int = 0) -> int:
+        del layer_idx
+        return self.donor.get_seq_length()
+
+    def reorder_cache(self, indices: torch.Tensor) -> "DendroAwakeningCache":
+        self.donor.reorder_cache(indices)
+        self.native.reorder_cache(indices)
+        return self
+
+
+@dataclass
+class DendroBaseModelOutputWithPast(ModelOutput):
+    last_hidden_state: torch.Tensor | None = None
+    past_key_values: DendroKVCache | DendroTransplantCache | DendroAwakeningCache | tuple[tuple[torch.Tensor, torch.Tensor], ...] | None = None
+    hidden_states: tuple[torch.Tensor, ...] | None = None
+    attentions: tuple[torch.Tensor, ...] | None = None
+    reasoning_state: dict[str, Any] | None = None
+    modality_layout: dict[str, Any] | None = None
+    dendro_states: tuple[DendroCellState, ...] | None = None
+    aligned_labels: torch.Tensor | None = None
+
+
+@dataclass
+class DendroCausalLMOutput(CausalLMOutputWithPast):
+    reasoning_state: dict[str, Any] | None = None
+    modality_layout: dict[str, Any] | None = None
+    dendro_states: tuple[DendroCellState, ...] | None = None
+
+
+@dataclass(slots=True)
+class DendroAnswerGenerationOutput:
+    """Answer-only result from hidden deliberative generation.
+
+    Deliberation token IDs are intentionally absent.  The answer mask identifies
+    real tokens in the padded batch and is directly usable for tokenizer decoding.
+    """
+
+    answer_token_ids: torch.Tensor
+    answer_attention_mask: torch.Tensor
+    reasoning_token_counts: tuple[int, ...]
+    reasoning_minimum_tokens: tuple[int, ...]
+    reasoning_token_budgets: tuple[int, ...]
+    reasoning_completed: tuple[bool, ...]
+    reasoning_forced_close: tuple[bool, ...]
+    answer_token_counts: tuple[int, ...]
+    answer_eos_reached: tuple[bool, ...]
+    answer_reasoning_filtered: tuple[bool, ...]
+    finish_reasons: tuple[str, ...]
+
+    @property
+    def sequences(self) -> torch.Tensor:
+        """Answer-only tensor alias for generation consumers."""
+
+        return self.answer_token_ids
+
+    def batch_decode(
+        self,
+        tokenizer: Any,
+        *,
+        skip_special_tokens: bool = True,
+    ) -> list[str]:
+        rows = [
+            row[mask].detach().cpu().tolist()
+            for row, mask in zip(self.answer_token_ids, self.answer_attention_mask)
+        ]
+        if hasattr(tokenizer, "batch_decode"):
+            try:
+                return list(
+                    tokenizer.batch_decode(
+                        rows,
+                        skip_special_tokens=skip_special_tokens,
+                        clean_up_tokenization_spaces=False,
+                    )
+                )
+            except TypeError:
+                return list(
+                    tokenizer.batch_decode(
+                        rows, skip_special_tokens=skip_special_tokens
+                    )
+                )
+        return [
+            str(tokenizer.decode(row, skip_special_tokens=skip_special_tokens))
+            for row in rows
+        ]
+
+
+class DendroSourceEmbedding(SourceBoundModule):
+    """HF-facing embedding proxy with no private parameters."""
+
+    def __init__(self, config: DendroOmniConfig, source: DendroSourceLayer) -> None:
+        super().__init__(source)
+        self.num_embeddings = config.vocab_size
+        self.embedding_dim = config.hidden_size
+
+    @property
+    def weight(self) -> torch.Tensor:
+        return self.source.primitive("token/embedding", (self.num_embeddings, self.embedding_dim))
+
+    def forward(self, input_ids: torch.Tensor) -> torch.Tensor:
+        return F.embedding(input_ids, self.weight)
+
+
+class DendroSourceLMHead(SourceBoundModule):
+    """HF-facing tied output proxy over the same token source view."""
+
+    def __init__(self, config: DendroOmniConfig, source: DendroSourceLayer) -> None:
+        super().__init__(source)
+        self.in_features = config.hidden_size
+        self.out_features = config.vocab_size
+
+    @property
+    def weight(self) -> torch.Tensor:
+        return self.source.primitive("token/embedding", (self.out_features, self.in_features))
+
+    def forward(self, hidden_states: torch.Tensor) -> torch.Tensor:
+        return self.source.tied_logits(hidden_states, vocab_size=self.out_features)
+
+
+class DendroPreTrainedModel(PreTrainedModel):
+    config_class = DendroOmniConfig
+    generation_config_class = DendroGenerationConfig
+    base_model_prefix = "model"
+    main_input_name = "input_ids"
+    supports_gradient_checkpointing = False
+    _supports_sdpa = True
+    _supports_cache_class = True
+    _supports_static_cache = True
+    _no_split_modules = ["DendroRecurrentCell", "DendroSourceLayer"]
+    _skip_keys_device_placement = ["past_key_values"]
+
+    def _init_weights(self, module: nn.Module) -> None:
+        # The source tensor initializes itself exactly once. Parameterless views must
+        # not trigger Hugging Face's per-module initializer.
+        del module
+
+    @classmethod
+    def _supports_default_dynamic_cache(cls) -> bool:
+        """Prevent GenerationMixin from injecting a generic HF cache.
+
+        Dendro must instantiate :class:`DendroKVCache` itself because each virtual
+        recurrent depth owns an activation-only K/V stream plus workspace, memory,
+        plasticity and associative state.  Returning ``False`` is the current
+        Transformers extension point for architectures with a custom cache.
+        """
+
+        return False
+
+
+if issubclass(PreTrainedModel, GenerationMixin):
+    class _DendroGenerationBase(DendroPreTrainedModel):
+        pass
+else:
+    class _DendroGenerationBase(DendroPreTrainedModel, GenerationMixin):
+        pass
+
+
+class DendroOmniModel(DendroPreTrainedModel):
+    """The recurrent backbone: one source layer and one physical cell."""
+
+    def __init__(self, config: DendroOmniConfig) -> None:
+        super().__init__(config)
+        self.source_layer = DendroSourceLayer(
+            config.source_size,
+            low_bit=config.low_bit,
+            ternary_threshold=config.ternary_threshold,
+            init_std=config.init_std,
+            cache_derived_views=config.cache_derived_views,
+            cache_indices=config.cache_source_indices,
+            logical_region_start=config.source_logical_region_start,
+            logical_region_size=config.source_logical_region_size,
+            tensor_map=config.transplant_tensor_map,
+            aliases=config.transplant_aliases,
+            exact_tied_logits=config.transplant_exact_tied_logits,
+            freeze_named_tensors=config.transplant_freeze_donor_bank,
+        )
+        self.transplant_core = (
+            DendroExactTransplantCore(config, self.source_layer)
+            if config.transplant_mode in {"exact", "awakening"}
+            else None
+        )
+        if self.transplant_core is not None:
+            missing = self.transplant_core.validate_required_tensors()
+            if missing:
+                preview = ", ".join(missing[:8])
+                raise ValueError(
+                    f"transplant checkpoint is missing {len(missing)} required donor tensors: {preview}"
+                )
+        self.input_projector = DendroOmniInputProjector(config, self.source_layer)
+        self.cell = DendroRecurrentCell(config, self.source_layer)
+        self._input_embedding_proxy = DendroSourceEmbedding(config, self.source_layer)
+        self.post_init()
+
+    def get_input_embeddings(self) -> DendroSourceEmbedding:
+        return self._input_embedding_proxy
+
+    def set_input_embeddings(self, value: nn.Module) -> None:
+        weight = getattr(value, "weight", None)
+        if weight is None or tuple(weight.shape) != (self.config.vocab_size, self.config.hidden_size):
+            raise ValueError("input embedding must expose weight [vocab_size, hidden_size]")
+        self.source_layer.write_primitive("token/embedding", weight)
+
+    def _new_cache(self) -> DendroKVCache:
+        return DendroKVCache(
+            max_depth=self.config.max_total_recurrent_steps,
+            implementation=self.config.cache_implementation,
+            max_cache_length=self.config.max_cache_length,
+            sliding_window=self.config.sliding_window,
+            offload_device=self.config.cache_offload_device,
+            detach_runtime_state=self.config.detach_runtime_state,
+        )
+
+    @staticmethod
+    def _mean_metric(states: list[DendroCellState], name: str) -> float:
+        values = [getattr(state, name).detach().float().mean() for state in states]
+        return float(torch.stack(values).mean().cpu().item()) if values else 0.0
+
+    def forward(
+        self,
+        input_ids: torch.Tensor | None = None,
+        attention_mask: torch.Tensor | None = None,
+        position_ids: torch.Tensor | None = None,
+        past_key_values: DendroKVCache | DendroTransplantCache | DendroAwakeningCache | tuple[tuple[torch.Tensor, torch.Tensor], ...] | None = None,
+        inputs_embeds: torch.Tensor | None = None,
+        pixel_values: torch.Tensor | None = None,
+        pixel_values_videos: torch.Tensor | None = None,
+        image_grid_thw: torch.Tensor | None = None,
+        video_grid_thw: torch.Tensor | None = None,
+        mm_token_type_ids: torch.Tensor | None = None,
+        audio_values: torch.Tensor | None = None,
+        video_values: torch.Tensor | None = None,
+        sensor_values: torch.Tensor | None = None,
+        prefix_mask: torch.Tensor | None = None,
+        labels: torch.Tensor | None = None,
+        reasoning_effort: str | None = None,
+        reasoning_budget: int | None = None,
+        use_cache: bool | None = None,
+        output_attentions: bool | None = None,
+        output_hidden_states: bool | None = None,
+        return_dict: bool | None = None,
+        collect_reasoning_diagnostics: bool = True,
+        cache_position: torch.Tensor | None = None,
+        **extra_kwargs: Any,
+    ) -> DendroBaseModelOutputWithPast | tuple[Any, ...]:
+        native_training_only = bool(extra_kwargs.pop("native_training_only", False))
+        training_recurrent_depth = extra_kwargs.pop("training_recurrent_depth", None)
+        if extra_kwargs:
+            unknown = ", ".join(sorted(extra_kwargs))
+            raise TypeError(f"unexpected Dendro model arguments: {unknown}")
+        del cache_position  # Positions are represented directly in the packed layout.
+        use_cache = self.config.use_cache if use_cache is None else bool(use_cache)
+        output_attentions = self.config.output_attentions if output_attentions is None else bool(output_attentions)
+        output_hidden_states = (
+            self.config.output_hidden_states if output_hidden_states is None else bool(output_hidden_states)
+        )
+        return_dict = self.config.use_return_dict if return_dict is None else bool(return_dict)
+        collect_reasoning_diagnostics = bool(collect_reasoning_diagnostics)
+        self.source_layer.begin_forward_cache()
+
+        explicit_reasoning_budget = None
+        if reasoning_budget is not None:
+            explicit_reasoning_budget = self.config.resolve_reasoning_budget(
+                reasoning_effort, reasoning_budget
+            )
+
+        transplant_mode = self.config.transplant_mode
+        transplant_blend = self.config.transplant_blend_for_effort(reasoning_effort)
+        if self.transplant_core is not None and (transplant_mode == "exact" or transplant_blend <= 0.0):
+            explicit_reasoning_budget = 0
+            if past_key_values is not None and not isinstance(past_key_values, DendroTransplantCache):
+                raise ValueError(
+                    "exact transplant caching requires DendroTransplantCache"
+                )
+            if any(value is not None for value in (audio_values, video_values, sensor_values, prefix_mask)):
+                raise ValueError(
+                    "Qwen3.5 exact transplant mode accepts Qwen text/image/video processor tensors; "
+                    "Dendro-native audio/sensor inputs become available in awakening mode"
+                )
+            if input_ids is None and inputs_embeds is None:
+                raise ValueError("exact transplant mode requires input_ids or inputs_embeds")
+            if input_ids is not None:
+                transplant_output = self.transplant_core.multimodal_forward(
+                    input_ids=input_ids,
+                    attention_mask=attention_mask,
+                    position_ids=position_ids,
+                    pixel_values=pixel_values,
+                    pixel_values_videos=pixel_values_videos,
+                    image_grid_thw=image_grid_thw,
+                    video_grid_thw=video_grid_thw,
+                    mm_token_type_ids=mm_token_type_ids,
+                    cache=past_key_values,
+                    use_cache=use_cache,
+                )
+            else:
+                if any(value is not None for value in (pixel_values, pixel_values_videos)):
+                    raise ValueError("multimodal exact transplant mode requires input_ids for placeholder placement")
+                transplant_output = self.transplant_core.text_forward(
+                    inputs_embeds=inputs_embeds,
+                    attention_mask=attention_mask,
+                    position_ids=position_ids,
+                    cache=past_key_values,
+                    use_cache=use_cache,
+                )
+            reasoning_state = {
+                "transplant_mode": "exact",
+                "source_model": self.config.transplant_source_model,
+                "function_path": "dendro_native_exact_equivalence",
+                "dendro_extensions_active": False,
+                "cache": None,
+            }
+            result = DendroBaseModelOutputWithPast(
+                last_hidden_state=transplant_output.last_hidden_state,
+                past_key_values=transplant_output.cache if use_cache else None,
+                hidden_states=(transplant_output.last_hidden_state,) if output_hidden_states else None,
+                attentions=None,
+                reasoning_state=reasoning_state,
+                modality_layout={"mode": "qwen3.5_exact_transplant"},
+                dendro_states=tuple(),
+                aligned_labels=labels,
+            )
+            return result if return_dict else result.to_tuple()
+
+        if self.transplant_core is not None and transplant_mode == "awakening" and transplant_blend > 0.0:
+            # Preserve the donor function while admitting the original Dendro recurrent body.
+            # Qwen image/video features are first formed by the exact donor coordinate path,
+            # then the resulting fused embeddings are routed through Dendro's own cell.  Native
+            # audio/video/sensor prefixes can be added around the same text-aligned sequence.
+            if past_key_values is not None and not isinstance(past_key_values, DendroAwakeningCache):
+                raise ValueError("awakening transplant caching requires DendroAwakeningCache")
+            awakening_cache = past_key_values if isinstance(past_key_values, DendroAwakeningCache) else None
+            donor_cache = None if awakening_cache is None else awakening_cache.donor
+            native_cache = None if awakening_cache is None else awakening_cache.native
+            if native_training_only:
+                if not self.training:
+                    raise ValueError("native_training_only is restricted to model.train()")
+                if use_cache or past_key_values is not None:
+                    raise ValueError("native_training_only does not retain an inference cache")
+                if any(
+                    value is not None
+                    for value in (
+                        pixel_values,
+                        pixel_values_videos,
+                        image_grid_thw,
+                        video_grid_thw,
+                        mm_token_type_ids,
+                        audio_values,
+                        video_values,
+                        sensor_values,
+                    )
+                ):
+                    raise ValueError("native_training_only currently accepts text batches only")
+                if inputs_embeds is None:
+                    if input_ids is None:
+                        raise ValueError("native_training_only requires input_ids or inputs_embeds")
+                    inputs_embeds = self.transplant_core.token_embedding(input_ids)
+                original_mode = self.config.transplant_mode
+                self.config.transplant_mode = "off"
+                try:
+                    native_output = self.forward(
+                        input_ids=None,
+                        attention_mask=attention_mask,
+                        position_ids=position_ids,
+                        inputs_embeds=inputs_embeds,
+                        prefix_mask=prefix_mask,
+                        labels=labels,
+                        reasoning_effort=reasoning_effort,
+                        reasoning_budget=reasoning_budget,
+                        training_recurrent_depth=training_recurrent_depth,
+                        use_cache=False,
+                        output_attentions=output_attentions,
+                        output_hidden_states=output_hidden_states,
+                        return_dict=True,
+                        collect_reasoning_diagnostics=collect_reasoning_diagnostics,
+                    )
+                finally:
+                    self.config.transplant_mode = original_mode
+                native_output.reasoning_state = dict(native_output.reasoning_state or {})
+                native_output.reasoning_state.update(
+                    {
+                        "transplant_mode": "awakening_native_training",
+                        "final_inference_blend": transplant_blend,
+                        "donor_forward_skipped": True,
+                    }
+                )
+                return native_output if return_dict else native_output.to_tuple()
+            if input_ids is not None:
+                exact_output = self.transplant_core.multimodal_forward(
+                    input_ids=input_ids,
+                    attention_mask=attention_mask,
+                    position_ids=position_ids,
+                    pixel_values=pixel_values,
+                    pixel_values_videos=pixel_values_videos,
+                    image_grid_thw=image_grid_thw,
+                    video_grid_thw=video_grid_thw,
+                    mm_token_type_ids=mm_token_type_ids,
+                    cache=donor_cache,
+                    use_cache=use_cache,
+                )
+            else:
+                if inputs_embeds is None:
+                    raise ValueError("awakening transplant mode requires input_ids or inputs_embeds")
+                if pixel_values is not None or pixel_values_videos is not None:
+                    raise ValueError("Qwen image/video awakening requires input_ids for placeholder placement")
+                exact_output = self.transplant_core.text_forward(
+                    inputs_embeds=inputs_embeds,
+                    attention_mask=attention_mask,
+                    position_ids=position_ids,
+                    cache=donor_cache,
+                    use_cache=use_cache,
+                )
+
+            native_prefix_mask = prefix_mask
+            if native_prefix_mask is None and mm_token_type_ids is not None:
+                native_prefix_mask = mm_token_type_ids.to(dtype=torch.bool)
+
+            original_mode = self.config.transplant_mode
+            self.config.transplant_mode = "off"
+            try:
+                native_output = self.forward(
+                    input_ids=None,
+                    attention_mask=attention_mask,
+                    # The awakening branches must see the same absolute text
+                    # coordinates.  This is especially important for the
+                    # trainer's randomized high-position augmentation; using
+                    # donor offsets with native zero-based positions would blend
+                    # representations for different coordinates.
+                    position_ids=position_ids,
+                    past_key_values=native_cache,
+                    inputs_embeds=exact_output.input_embeddings,
+                    pixel_values=None,
+                    audio_values=audio_values,
+                    video_values=video_values,
+                    sensor_values=sensor_values,
+                    prefix_mask=native_prefix_mask,
+                    labels=labels,
+                    reasoning_effort=reasoning_effort,
+                    reasoning_budget=reasoning_budget,
+                    use_cache=use_cache,
+                    output_attentions=output_attentions,
+                    output_hidden_states=output_hidden_states,
+                    return_dict=True,
+                    collect_reasoning_diagnostics=collect_reasoning_diagnostics,
+                )
+            finally:
+                self.config.transplant_mode = original_mode
+
+            native_hidden = native_output.last_hidden_state
+            if native_hidden is None:
+                raise RuntimeError("Dendro awakening path produced no hidden state")
+            layout = native_output.modality_layout or {}
+            text_start = int(layout.get("text_start", 0))
+            text_length = int(layout.get("text_length", native_hidden.shape[1]))
+            if text_length != exact_output.last_hidden_state.shape[1]:
+                raise RuntimeError(
+                    "Dendro awakening text segment is not aligned with the exact donor sequence: "
+                    f"native={text_length}, exact={exact_output.last_hidden_state.shape[1]}"
+                )
+            blended = transplant_blend * native_hidden
+            blended[:, text_start : text_start + text_length] = (
+                blended[:, text_start : text_start + text_length]
+                + exact_output.last_hidden_state
+            )
+            native_output.last_hidden_state = blended
+            native_output.reasoning_state = dict(native_output.reasoning_state or {})
+            native_output.reasoning_state.update(
+                {
+                    "transplant_mode": "awakening",
+                    "transplant_native_blend": transplant_blend,
+                    "source_model": self.config.transplant_source_model,
+                }
+            )
+            if use_cache:
+                if exact_output.cache is None or not isinstance(native_output.past_key_values, DendroKVCache):
+                    raise RuntimeError("awakening cache initialization failed")
+                native_output.past_key_values = DendroAwakeningCache(
+                    donor=exact_output.cache,
+                    native=native_output.past_key_values,
+                )
+            return native_output if return_dict else native_output.to_tuple()
+
+        if past_key_values is not None and not isinstance(past_key_values, DendroKVCache):
+            past_key_values = DendroKVCache.from_legacy_cache(
+                past_key_values,
+                max_depth=self.config.max_total_recurrent_steps,
+                implementation=self.config.cache_implementation,
+            )
+        cache = past_key_values
+        if use_cache and cache is None:
+            cache = self._new_cache()
+        if cache is not None and cache.get_seq_length() > 0:
+            if any(value is not None for value in (pixel_values, audio_values, video_values, sensor_values)):
+                raise ValueError("Multimodal prefix tensors may only be supplied while the cache is empty")
+            position_start = cache.total_tokens_seen
+        else:
+            position_start = 0
+
+        packed = self.input_projector(
+            input_ids=input_ids,
+            inputs_embeds=inputs_embeds,
+            attention_mask=attention_mask,
+            pixel_values=pixel_values,
+            audio_values=audio_values,
+            video_values=video_values,
+            sensor_values=sensor_values,
+            prefix_mask=prefix_mask,
+            labels=labels,
+            position_start=position_start,
+        )
+        if position_ids is not None:
+            if len(packed.layout.segments) != 1 or packed.layout.segments[0].name != "text":
+                raise ValueError("Explicit position_ids are supported only for text-only inputs")
+            if position_ids.shape != packed.layout.sequence_positions.shape:
+                raise ValueError("position_ids shape must match input_ids")
+            packed.layout.sequence_positions = position_ids.to(packed.hidden_states.device)
+
+        effort_name, effort_id, effort_level = self.config.reasoning_effort_profile(
+            reasoning_effort
+        )
+        extra_requested = self.config.resolve_reasoning_budget(
+            effort_name, reasoning_budget
+        )
+        verifier_passes = self.config.reasoning_verifier_passes if extra_requested >= 3 else 0
+        base_depth = self.config.num_hidden_layers
+        if training_recurrent_depth is not None:
+            if not self.training:
+                raise ValueError("training_recurrent_depth is restricted to model.train()")
+            base_depth = int(training_recurrent_depth)
+            if not 1 <= base_depth <= self.config.num_hidden_layers:
+                raise ValueError("training_recurrent_depth must be within the configured recurrent depth")
+            # Legacy shallow training remains unchanged unless the caller opts in
+            # with an explicit reasoning budget.  This lets a future curriculum
+            # train reasoning/verification phases without requiring full base depth.
+            if reasoning_budget is None:
+                extra_requested = 0
+                verifier_passes = 0
+        requested_depth = base_depth + extra_requested + verifier_passes
+        reasoning_signature = (
+            effort_name,
+            effort_id,
+            round(effort_level, 8),
+            extra_requested,
+            verifier_passes,
+        )
+        if cache is not None:
+            cache.ensure_recurrent_depth(requested_depth)
+            previous_signature = cache.reasoning_state.get("reasoning_signature")
+            if (
+                cache.get_seq_length() > 0
+                and previous_signature is not None
+                and tuple(previous_signature) != reasoning_signature
+            ):
+                raise RuntimeError(
+                    "reasoning effort/budget changed while reusing a populated cache; "
+                    "start a fresh cache or keep the same reasoning controls"
+                )
+
+        hidden = packed.hidden_states
+        hidden_history: list[torch.Tensor] = [hidden] if output_hidden_states else []
+        attention_history: list[torch.Tensor] = []
+        states: list[DendroCellState] = []
+
+        checkpoint_recurrence = (
+            self.training
+            and torch.is_grad_enabled()
+            and bool(getattr(self.config, "training_recurrent_checkpointing", False))
+            and not use_cache
+        )
+
+        def apply_cell(
+            current_hidden: torch.Tensor,
+            *,
+            current_depth: int,
+            current_phase: str,
+            current_progress: float,
+            current_remaining: float,
+        ):
+            def cell_forward(value: torch.Tensor):
+                return self.cell(
+                    value,
+                    layout=packed.layout,
+                    depth_idx=current_depth,
+                    phase=current_phase,
+                    effort_id=effort_id,
+                    effort_level=effort_level,
+                    phase_progress=current_progress,
+                    remaining_budget_fraction=current_remaining,
+                    cache=cache,
+                    use_cache=use_cache,
+                    output_attentions=output_attentions,
+                )
+
+            if not checkpoint_recurrence:
+                return cell_forward(current_hidden)
+            return activation_checkpoint(
+                cell_forward,
+                current_hidden,
+                use_reentrant=False,
+                preserve_rng_state=True,
+            )
+
+        depth_idx = 0
+        for step in range(base_depth):
+            output = apply_cell(
+                hidden,
+                current_depth=depth_idx,
+                current_phase="base",
+                current_progress=(step + 1) / max(1, base_depth),
+                current_remaining=(requested_depth - depth_idx - 1)
+                / max(1, requested_depth),
+            )
+            hidden = output.hidden_states
+            states.append(output.state)
+            if output_hidden_states:
+                hidden_history.append(hidden)
+            if output_attentions and output.attention_weights is not None:
+                attention_history.append(output.attention_weights)
+            depth_idx += 1
+
+        extra_executed = 0
+        refinement_scale = float(self.config.reasoning_refinement_scale)
+        adaptive_allowed = (
+            self.config.adaptive_reasoning
+            and not use_cache
+            and reasoning_budget is None
+        )
+        for step in range(extra_requested):
+            output = apply_cell(
+                hidden,
+                current_depth=depth_idx,
+                current_phase="reasoning",
+                current_progress=(step + 1) / max(1, extra_requested),
+                current_remaining=(requested_depth - depth_idx - 1)
+                / max(1, requested_depth),
+            )
+            if refinement_scale >= 1.0:
+                hidden = output.hidden_states
+            elif refinement_scale > 0.0:
+                hidden = hidden + refinement_scale * (output.hidden_states - hidden)
+            states.append(output.state)
+            extra_executed += 1
+            if output_hidden_states:
+                hidden_history.append(hidden)
+            if output_attentions and output.attention_weights is not None:
+                attention_history.append(output.attention_weights)
+            depth_idx += 1
+            if adaptive_allowed and extra_executed >= self.config.reasoning_min_steps:
+                ready = float(output.state.readiness.detach().float().mean().cpu().item())
+                contradiction = float(output.state.contradiction.detach().float().mean().cpu().item())
+                if ready * (1.0 - contradiction) >= self.config.reasoning_stop_threshold:
+                    break
+
+        verifier_executed = 0
+        # Cached generation uses a fixed depth so every recurrent K/V stream remains
+        # complete. In non-cached analysis, verifier passes follow actual reasoning.
+        passes = verifier_passes if use_cache else (verifier_passes if extra_executed else 0)
+        for step in range(passes):
+            output = apply_cell(
+                hidden,
+                current_depth=depth_idx,
+                current_phase="verification",
+                current_progress=(step + 1) / max(1, passes),
+                current_remaining=(requested_depth - depth_idx - 1)
+                / max(1, requested_depth),
+            )
+            if refinement_scale >= 1.0:
+                hidden = output.hidden_states
+            elif refinement_scale > 0.0:
+                hidden = hidden + refinement_scale * (output.hidden_states - hidden)
+            states.append(output.state)
+            verifier_executed += 1
+            if output_hidden_states:
+                hidden_history.append(hidden)
+            if output_attentions and output.attention_weights is not None:
+                attention_history.append(output.attention_weights)
+            depth_idx += 1
+
+        hidden = self.source_layer.rms_norm(hidden, "model/final_norm", eps=self.config.layer_norm_eps)
+        if output_hidden_states:
+            hidden_history.append(hidden)
+
+        reasoning_state: dict[str, Any] = {
+            "effort": effort_name,
+            "effort_id": effort_id,
+            "effort_level": effort_level,
+            "reasoning_budget": extra_requested,
+            "reasoning_budget_override": reasoning_budget is not None,
+            "base_recurrent_steps": self.config.num_hidden_layers,
+            "reasoning_steps_requested": extra_requested,
+            "reasoning_steps_executed": extra_executed,
+            "verifier_steps_executed": verifier_executed,
+            "total_recurrent_steps": depth_idx,
+            "adaptive_early_stop": bool(adaptive_allowed and extra_executed < extra_requested),
+            "reasoning_route_prior_strength": float(
+                self.config.reasoning_route_prior_strength
+            ),
+            "reasoning_refinement_scale": refinement_scale,
+            "diagnostics_collected": collect_reasoning_diagnostics,
+            "reasoning_signature": list(reasoning_signature),
+        }
+        if collect_reasoning_diagnostics:
+            final_state = states[-1]
+            readiness = float(final_state.readiness.detach().float().mean().cpu().item())
+            contradiction = float(final_state.contradiction.detach().float().mean().cpu().item())
+            route_distribution = (
+                final_state.route_probs.detach().float().mean(dim=(0, 1)).cpu()
+            )
+            expert_distribution = (
+                final_state.expert_probs.detach().float().mean(dim=(0, 1)).cpu()
+            )
+            route_entropy = float(
+                (
+                    -route_distribution
+                    * route_distribution.clamp_min(1e-8).log()
+                ).sum().item()
+            )
+            reasoning_state.update(
+                {
+                    "readiness": readiness,
+                    "contradiction": contradiction,
+                    "confidence": readiness * (1.0 - contradiction),
+                    "mean_coherence": self._mean_metric(states, "coherence"),
+                    "mean_entropy_pressure": self._mean_metric(states, "entropy_pressure"),
+                    "mean_salience": self._mean_metric(states, "salience"),
+                    "route_distribution": route_distribution.tolist(),
+                    "route_entropy": route_entropy,
+                    "expert_distribution": expert_distribution.tolist(),
+                    "cache": cache.summary() if cache is not None else None,
+                }
+            )
+        if cache is not None:
+            cache.reasoning_state = reasoning_state
+
+        result = DendroBaseModelOutputWithPast(
+            last_hidden_state=hidden,
+            past_key_values=cache if use_cache else None,
+            hidden_states=tuple(hidden_history) if output_hidden_states else None,
+            attentions=tuple(attention_history) if output_attentions else None,
+            reasoning_state=reasoning_state,
+            modality_layout=packed.layout.to_dict(),
+            dendro_states=tuple(states),
+            aligned_labels=packed.aligned_labels,
+        )
+        if return_dict:
+            return result
+        return result.to_tuple()
+
+
+class DendroForCausalLM(_DendroGenerationBase):
+    """Causal LM with tied logits derived from the same single source tensor."""
+
+    _tied_weights_keys = {}
+
+    def __init__(self, config: DendroOmniConfig) -> None:
+        super().__init__(config)
+        self.model = DendroOmniModel(config)
+        self._output_embedding_proxy = DendroSourceLMHead(
+            config,
+            self.model.source_layer,
+        )
+        self.post_init()
+
+    @property
+    def source_layer(self) -> DendroSourceLayer:
+        return self.model.source_layer
+
+    def get_input_embeddings(self) -> DendroSourceEmbedding:
+        return self.model.get_input_embeddings()
+
+    def set_input_embeddings(self, value: nn.Module) -> None:
+        self.model.set_input_embeddings(value)
+
+    def get_output_embeddings(self) -> DendroSourceLMHead:
+        return self._output_embedding_proxy
+
+    def set_output_embeddings(self, new_embeddings: nn.Module) -> None:
+        weight = getattr(new_embeddings, "weight", None)
+        if weight is None or tuple(weight.shape) != (self.config.vocab_size, self.config.hidden_size):
+            raise ValueError("output embedding must expose weight [vocab_size, hidden_size]")
+        self.source_layer.write_primitive("token/embedding", weight)
+
+    def tie_weights(
+        self,
+        missing_keys: set[str] | None = None,
+        recompute_mapping: bool = True,
+    ) -> None:
+        del missing_keys, recompute_mapping
+        return None
+
+    def resize_token_embeddings(
+        self,
+        new_num_tokens: int | None = None,
+        pad_to_multiple_of: int | None = None,
+        mean_resizing: bool = True,
+    ) -> DendroSourceEmbedding:
+        del mean_resizing
+        if new_num_tokens is None:
+            return self.get_input_embeddings()
+        if pad_to_multiple_of:
+            new_num_tokens = math.ceil(new_num_tokens / pad_to_multiple_of) * pad_to_multiple_of
+        if new_num_tokens < self.config.byte_offset + 256:
+            raise ValueError("The byte tokenizer requires at least byte_offset + 256 tokens")
+        old_weight = self.get_input_embeddings().weight.detach().clone()
+        self.source_layer.forget_primitive_shape("token")
+        self.config.vocab_size = int(new_num_tokens)
+        self.model._input_embedding_proxy.num_embeddings = int(new_num_tokens)
+        self._output_embedding_proxy.out_features = int(new_num_tokens)
+        resized = torch.empty(
+            new_num_tokens,
+            self.config.hidden_size,
+            device=old_weight.device,
+            dtype=old_weight.dtype,
+        )
+        nn.init.normal_(resized, mean=0.0, std=self.config.init_std)
+        count = min(old_weight.shape[0], new_num_tokens)
+        resized[:count].copy_(old_weight[:count])
+        self.source_layer.write_primitive("token/embedding", resized)
+        return self.get_input_embeddings()
+
+    def forward(
+        self,
+        input_ids: torch.Tensor | None = None,
+        attention_mask: torch.Tensor | None = None,
+        position_ids: torch.Tensor | None = None,
+        past_key_values: DendroKVCache | DendroTransplantCache | DendroAwakeningCache | tuple[tuple[torch.Tensor, torch.Tensor], ...] | None = None,
+        inputs_embeds: torch.Tensor | None = None,
+        labels: torch.Tensor | None = None,
+        pixel_values: torch.Tensor | None = None,
+        pixel_values_videos: torch.Tensor | None = None,
+        image_grid_thw: torch.Tensor | None = None,
+        video_grid_thw: torch.Tensor | None = None,
+        mm_token_type_ids: torch.Tensor | None = None,
+        audio_values: torch.Tensor | None = None,
+        video_values: torch.Tensor | None = None,
+        sensor_values: torch.Tensor | None = None,
+        prefix_mask: torch.Tensor | None = None,
+        reasoning_effort: str | None = None,
+        reasoning_budget: int | None = None,
+        use_cache: bool | None = None,
+        output_attentions: bool | None = None,
+        output_hidden_states: bool | None = None,
+        return_dict: bool | None = None,
+        collect_reasoning_diagnostics: bool = True,
+        cache_position: torch.Tensor | None = None,
+        logits_to_keep: int | torch.Tensor = 0,
+        vocab_indices: torch.Tensor | None = None,
+        **kwargs: Any,
+    ) -> DendroCausalLMOutput | tuple[Any, ...]:
+        return_dict = self.config.use_return_dict if return_dict is None else bool(return_dict)
+        base = self.model(
+            input_ids=input_ids,
+            attention_mask=attention_mask,
+            position_ids=position_ids,
+            past_key_values=past_key_values,
+            inputs_embeds=inputs_embeds,
+            pixel_values=pixel_values,
+            pixel_values_videos=pixel_values_videos,
+            image_grid_thw=image_grid_thw,
+            video_grid_thw=video_grid_thw,
+            mm_token_type_ids=mm_token_type_ids,
+            audio_values=audio_values,
+            video_values=video_values,
+            sensor_values=sensor_values,
+            prefix_mask=prefix_mask,
+            labels=labels,
+            reasoning_effort=reasoning_effort,
+            reasoning_budget=reasoning_budget,
+            use_cache=use_cache,
+            output_attentions=output_attentions,
+            output_hidden_states=output_hidden_states,
+            return_dict=True,
+            collect_reasoning_diagnostics=collect_reasoning_diagnostics,
+            cache_position=cache_position,
+            **kwargs,
+        )
+        assert isinstance(base, DendroBaseModelOutputWithPast)
+        hidden = base.last_hidden_state
+        assert hidden is not None
+        if isinstance(logits_to_keep, int) and logits_to_keep > 0:
+            hidden_for_logits = hidden[:, -logits_to_keep:]
+        elif torch.is_tensor(logits_to_keep):
+            hidden_for_logits = hidden.index_select(1, logits_to_keep.to(hidden.device))
+        else:
+            hidden_for_logits = hidden
+        if vocab_indices is None:
+            logits = self.source_layer.tied_logits(
+                hidden_for_logits, vocab_size=self.config.vocab_size
+            ).float()
+        else:
+            logits = self.source_layer.tied_selected_logits(
+                hidden_for_logits,
+                vocab_indices=vocab_indices,
+                vocab_size=self.config.vocab_size,
+            ).float()
+
+        loss = None
+        aligned_labels = base.aligned_labels
+        if labels is not None:
+            if vocab_indices is not None:
+                raise ValueError("vocab_indices is a trainer-only projection and cannot be combined with model labels")
+            if aligned_labels is None:
+                raise RuntimeError("labels were supplied but not aligned by the input projector")
+            full_logits = logits
+            if full_logits.shape[1] != aligned_labels.shape[1]:
+                full_logits = self.source_layer.tied_logits(hidden, vocab_size=self.config.vocab_size).float()
+            shift_logits = full_logits[:, :-1, :].contiguous()
+            shift_labels = aligned_labels[:, 1:].to(shift_logits.device).contiguous()
+            loss = F.cross_entropy(
+                shift_logits.view(-1, self.config.vocab_size),
+                shift_labels.view(-1),
+                ignore_index=-100,
+            )
+
+        result = DendroCausalLMOutput(
+            loss=loss,
+            logits=logits,
+            past_key_values=base.past_key_values,
+            hidden_states=base.hidden_states,
+            attentions=base.attentions,
+            reasoning_state=base.reasoning_state,
+            modality_layout=base.modality_layout,
+            dendro_states=base.dendro_states,
+        )
+        if return_dict:
+            return result
+        return result.to_tuple()
+
+    @torch.no_grad()
+    def answer_image(
+        self,
+        processor: Any,
+        image: Any,
+        prompt: str,
+        *,
+        reasoning_effort: str = "high",
+        max_new_tokens: int | None = None,
+        do_sample: bool = False,
+        temperature: float = 0.7,
+    ) -> Any:
+        """Answer about an image with effort-scaled detail views.
+
+        The caller reuses this loaded model and its matching lightweight
+        processor.  High/max add deterministic local views but never load a
+        second language model or vision tower.
+        """
+
+        from .vision_routing import answer_image_with_effort
+
+        return answer_image_with_effort(
+            self,
+            processor,
+            image,
+            prompt,
+            reasoning_effort=reasoning_effort,
+            max_new_tokens=max_new_tokens,
+            do_sample=do_sample,
+            temperature=temperature,
+        )
+
+    def prepare_inputs_for_generation(
+        self,
+        input_ids: torch.Tensor,
+        past_key_values: DendroKVCache | DendroTransplantCache | DendroAwakeningCache | None = None,
+        attention_mask: torch.Tensor | None = None,
+        inputs_embeds: torch.Tensor | None = None,
+        cache_position: torch.Tensor | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        populated = past_key_values is not None and past_key_values.get_seq_length() > 0
+        if populated:
+            seen = past_key_values.total_tokens_seen
+            if input_ids.shape[1] > seen:
+                start = min(seen, input_ids.shape[1] - 1)
+                input_ids = input_ids[:, start:]
+                if attention_mask is not None:
+                    attention_mask = attention_mask[:, start:]
+            else:
+                input_ids = input_ids[:, -1:]
+                if attention_mask is not None:
+                    attention_mask = attention_mask[:, -1:]
+            inputs_embeds = None
+            for key in ("pixel_values", "pixel_values_videos", "image_grid_thw", "video_grid_thw", "mm_token_type_ids", "audio_values", "video_values", "sensor_values", "prefix_mask"):
+                kwargs[key] = None
+        model_inputs: dict[str, Any] = {
+            "input_ids": input_ids,
+            "attention_mask": attention_mask,
+            "past_key_values": past_key_values,
+            "use_cache": kwargs.pop("use_cache", True),
+            "cache_position": cache_position,
+        }
+        if inputs_embeds is not None and not populated:
+            model_inputs["inputs_embeds"] = inputs_embeds
+            model_inputs["input_ids"] = None
+        for key in (
+            "pixel_values",
+            "pixel_values_videos",
+            "image_grid_thw",
+            "video_grid_thw",
+            "mm_token_type_ids",
+            "audio_values",
+            "video_values",
+            "sensor_values",
+            "prefix_mask",
+            "reasoning_effort",
+            "reasoning_budget",
+            "logits_to_keep",
+        ):
+            if key in kwargs:
+                model_inputs[key] = kwargs[key]
+        return model_inputs
+
+    @staticmethod
+    def _reorder_cache(
+        past_key_values: DendroKVCache | DendroTransplantCache | DendroAwakeningCache,
+        beam_idx: torch.Tensor,
+    ) -> DendroKVCache | DendroTransplantCache | DendroAwakeningCache:
+        return past_key_values.reorder_cache(beam_idx)
+
+    @torch.no_grad()
+    def _local_generate(
+        self,
+        input_ids: torch.Tensor,
+        *,
+        # A soft practical allowance: generation still exits immediately on EOS,
+        # while normal structured answers are not silently clipped at 20 tokens.
+        max_new_tokens: int = 384,
+        completion_reserve_tokens: int | None = None,
+        min_new_tokens: int = 0,
+        attention_mask: torch.Tensor | None = None,
+        do_sample: bool = False,
+        temperature: float = 1.0,
+        top_k: int = 0,
+        top_p: float = 1.0,
+        repetition_penalty: float = 1.0,
+        eos_token_id: int | list[int] | tuple[int, ...] | None = None,
+        pad_token_id: int | None = None,
+        reasoning_effort: str | None = None,
+        reasoning_budget: int | None = None,
+        generator: torch.Generator | None = None,
+        use_cache: bool = True,
+        token_callback: Any | None = None,
+        **model_kwargs: Any,
+    ) -> torch.Tensor:
+        if not torch.is_tensor(input_ids):
+            raise TypeError("input_ids must be a torch.Tensor")
+        if input_ids.ndim != 2:
+            raise ValueError("input_ids must have shape (batch, sequence)")
+        if input_ids.shape[1] == 0:
+            raise ValueError("input_ids must contain at least one token")
+        if isinstance(max_new_tokens, bool) or not isinstance(max_new_tokens, int):
+            raise TypeError("max_new_tokens must be an integer")
+        if max_new_tokens < 0:
+            raise ValueError("max_new_tokens cannot be negative")
+        if completion_reserve_tokens is None:
+            completion_reserve_tokens = int(
+                getattr(self.config, "generation_completion_reserve_tokens", 0)
+            )
+        if (
+            isinstance(completion_reserve_tokens, bool)
+            or not isinstance(completion_reserve_tokens, int)
+        ):
+            raise TypeError("completion_reserve_tokens must be an integer")
+        if completion_reserve_tokens < 0:
+            raise ValueError("completion_reserve_tokens cannot be negative")
+        if isinstance(min_new_tokens, bool) or not isinstance(min_new_tokens, int):
+            raise TypeError("min_new_tokens must be an integer")
+        if min_new_tokens < 0:
+            raise ValueError("min_new_tokens cannot be negative")
+        if min_new_tokens > max_new_tokens:
+            raise ValueError("min_new_tokens cannot exceed max_new_tokens")
+        if isinstance(top_k, bool) or not isinstance(top_k, int):
+            raise TypeError("top_k must be an integer")
+        if top_k < 0:
+            raise ValueError("top_k cannot be negative")
+        try:
+            temperature = float(temperature)
+        except (TypeError, ValueError) as error:
+            raise TypeError("temperature must be a real number") from error
+        if not math.isfinite(temperature) or temperature <= 0.0:
+            raise ValueError("temperature must be finite and positive")
+        try:
+            top_p = float(top_p)
+        except (TypeError, ValueError) as error:
+            raise TypeError("top_p must be a real number") from error
+        if not math.isfinite(top_p) or not 0.0 < top_p <= 1.0:
+            raise ValueError("top_p must be finite and in (0, 1]")
+        try:
+            repetition_penalty = float(repetition_penalty)
+        except (TypeError, ValueError) as error:
+            raise TypeError("repetition_penalty must be a real number") from error
+        if not math.isfinite(repetition_penalty) or repetition_penalty <= 0.0:
+            raise ValueError("repetition_penalty must be finite and positive")
+
+        # These forward-only knobs cannot be honored by a tensor-returning local
+        # generation loop.  Consume them so callers that pass generic model
+        # kwargs cannot collide with the invariants below.
+        model_kwargs.pop("return_dict", None)
+        model_kwargs.pop("logits_to_keep", None)
+        supported_forward_kwargs = {
+            "audio_values",
+            "cache_position",
+            "image_grid_thw",
+            "mm_token_type_ids",
+            "output_attentions",
+            "output_hidden_states",
+            "pixel_values",
+            "pixel_values_videos",
+            "position_ids",
+            "prefix_mask",
+            "sensor_values",
+            "video_grid_thw",
+            "video_values",
+        }
+        unsupported = sorted(set(model_kwargs).difference(supported_forward_kwargs))
+        if unsupported:
+            names = ", ".join(unsupported)
+            raise TypeError(f"unsupported local generation argument(s): {names}")
+
+        def normalize_eos_ids(value: Any) -> tuple[int, ...]:
+            if value is None:
+                return ()
+            values = value if isinstance(value, (list, tuple)) else (value,)
+            normalized: list[int] = []
+            for token_id in values:
+                if isinstance(token_id, bool) or not isinstance(token_id, int):
+                    raise TypeError("eos_token_id must be an integer or a list of integers")
+                if token_id not in normalized:
+                    normalized.append(token_id)
+            return tuple(normalized)
+
+        configured_eos = self.config.eos_token_id if eos_token_id is None else eos_token_id
+        eos_ids = normalize_eos_ids(configured_eos)
+        configured_pad = self.config.pad_token_id if pad_token_id is None else pad_token_id
+        if configured_pad is None:
+            configured_pad = next(
+                (token_id for token_id in eos_ids if 0 <= token_id < self.config.vocab_size),
+                0,
+            )
+        if isinstance(configured_pad, bool) or not isinstance(configured_pad, int):
+            raise TypeError("pad_token_id must be an integer")
+        if not 0 <= configured_pad < self.config.vocab_size:
+            raise ValueError(
+                f"pad_token_id must be in [0, {self.config.vocab_size}), got {configured_pad}"
+            )
+        pad = configured_pad
+        valid_eos_ids = tuple(
+            token_id for token_id in eos_ids if 0 <= token_id < self.config.vocab_size
+        )
+        eos_tensor = torch.tensor(eos_ids, device=input_ids.device, dtype=input_ids.dtype)
+        valid_eos_tensor = torch.tensor(
+            valid_eos_ids, device=input_ids.device, dtype=torch.long
+        )
+
+        if attention_mask is None:
+            prompt_mask = torch.ones_like(input_ids, dtype=torch.bool)
+        else:
+            if not torch.is_tensor(attention_mask):
+                attention_mask = torch.as_tensor(attention_mask, device=input_ids.device)
+            else:
+                attention_mask = attention_mask.to(device=input_ids.device)
+            if attention_mask.ndim == 1 and input_ids.shape[0] == 1:
+                attention_mask = attention_mask.unsqueeze(0)
+            if attention_mask.shape != input_ids.shape:
+                raise ValueError(
+                    "attention_mask must have the same (batch, sequence) shape as input_ids"
+                )
+            prompt_mask = attention_mask.to(dtype=torch.bool)
+
+        batch_size, prompt_length = input_ids.shape
+        total_token_budget = max_new_tokens + completion_reserve_tokens
+        capacity = prompt_length + total_token_budget
+        token_buffer = input_ids.new_empty((batch_size, capacity))
+        mask_buffer = torch.empty(
+            (batch_size, capacity), device=input_ids.device, dtype=torch.bool
+        )
+        token_buffer[:, :prompt_length].copy_(input_ids)
+        mask_buffer[:, :prompt_length].copy_(prompt_mask)
+        generated_length = prompt_length
+        generated = token_buffer[:, :generated_length]
+        generated_mask = mask_buffer[:, :generated_length]
+        current = input_ids
+        current_mask = generated_mask
+        cache: DendroKVCache | DendroTransplantCache | DendroAwakeningCache | None = None
+        # ``use_cache`` is a public generation argument, not a model-forward
+        # kwarg.  Keeping it explicit prevents it from also arriving through
+        # ``model_kwargs`` and colliding with the value passed below.  The
+        # uncached path deliberately recomputes the complete prefix each step.
+        recompute_full_prefix = not use_cache
+        finished = torch.zeros(input_ids.shape[0], device=input_ids.device, dtype=torch.bool)
+        if hasattr(self.model, "transplant_core") and self.model.transplant_core is not None and hasattr(self.model.transplant_core, "prebind_weights"):
+            self.model.transplant_core.prebind_weights(device=input_ids.device)
+        prefix_kwargs = dict(model_kwargs)
+        for _step in range(total_token_budget):
+            if recompute_full_prefix:
+                current = generated
+                current_mask = generated_mask
+                cache = None
+            output = self(
+                input_ids=current,
+                attention_mask=current_mask,
+                past_key_values=cache,
+                reasoning_effort=reasoning_effort,
+                reasoning_budget=reasoning_budget,
+                use_cache=not recompute_full_prefix,
+                return_dict=True,
+                logits_to_keep=1,
+                collect_reasoning_diagnostics=False,
+                **prefix_kwargs,
+            )
+            assert isinstance(output, DendroCausalLMOutput)
+            cache = None if recompute_full_prefix else output.past_key_values
+            logits = output.logits[:, -1, :]
+            if repetition_penalty != 1.0:
+                previous_scores = logits.gather(1, generated)
+                penalized_scores = torch.where(
+                    previous_scores < 0,
+                    previous_scores * repetition_penalty,
+                    previous_scores / repetition_penalty,
+                )
+                logits = logits.scatter(1, generated, penalized_scores)
+            if _step < min_new_tokens and valid_eos_tensor.numel() > 0:
+                logits = logits.index_fill(1, valid_eos_tensor, -torch.inf)
+            if do_sample:
+                logits = logits / temperature
+                if top_k > 0:
+                    candidate_logits, candidate_indices = logits.topk(
+                        min(top_k, logits.shape[-1]), dim=-1
+                    )
+                    if top_p < 1.0:
+                        cumulative = torch.softmax(candidate_logits, dim=-1).cumsum(dim=-1)
+                        remove = cumulative > top_p
+                        remove[..., 1:] = remove[..., :-1].clone()
+                        remove[..., 0] = False
+                        candidate_logits = candidate_logits.masked_fill(remove, -torch.inf)
+                    candidate_position = torch.multinomial(
+                        torch.softmax(candidate_logits, dim=-1), 1, generator=generator
+                    )
+                    next_token = candidate_indices.gather(-1, candidate_position)
+                elif top_p < 1.0:
+                    sorted_logits, sorted_indices = logits.sort(descending=True)
+                    cumulative = torch.softmax(sorted_logits, dim=-1).cumsum(dim=-1)
+                    remove = cumulative > top_p
+                    remove[..., 1:] = remove[..., :-1].clone()
+                    remove[..., 0] = False
+                    sorted_logits = sorted_logits.masked_fill(remove, -torch.inf)
+                    sorted_position = torch.multinomial(
+                        torch.softmax(sorted_logits, dim=-1), 1, generator=generator
+                    )
+                    next_token = sorted_indices.gather(-1, sorted_position)
+                else:
+                    next_token = torch.multinomial(
+                        torch.softmax(logits, dim=-1), 1, generator=generator
+                    )
+            else:
+                next_token = logits.argmax(dim=-1, keepdim=True)
+            next_token = torch.where(finished.unsqueeze(-1), torch.full_like(next_token, pad), next_token)
+            active = ~finished
+            if token_callback is not None:
+                token_callback(next_token.detach(), _step + 1, active.detach())
+            token_buffer[:, generated_length].copy_(next_token.squeeze(-1))
+            mask_buffer[:, generated_length].copy_(active)
+            generated_length += 1
+            generated = token_buffer[:, :generated_length]
+            generated_mask = mask_buffer[:, :generated_length]
+            if eos_tensor.numel() > 0:
+                hit_eos = (
+                    next_token.squeeze(-1).unsqueeze(-1) == eos_tensor.unsqueeze(0)
+                ).any(dim=-1)
+                finished = finished | hit_eos
+            if bool(finished.all().item()):
+                break
+            if not recompute_full_prefix:
+                current = next_token
+                # Rows that finished on an earlier iteration must not add their
+                # padding tokens to the cache as valid context. ``active`` was
+                # captured before this step's EOS update, so a newly emitted EOS
+                # is still committed once while older finished rows stay masked.
+                current_mask = active.unsqueeze(-1)
+                prefix_kwargs = {}
+        return token_buffer[:, :generated_length].contiguous()
+
+    def _resolve_thinking_token_ids(
+        self,
+        start_token_id: int | None,
+        end_token_id: int | None,
+    ) -> tuple[int, int]:
+        """Resolve configured thinking boundaries or the transplanted Qwen IDs."""
+
+        start = self.config.thinking_start_token_id if start_token_id is None else start_token_id
+        end = self.config.thinking_end_token_id if end_token_id is None else end_token_id
+        # Qwen3.5's copied tokenizer stores these as ordinary added tokens rather
+        # than ``special`` tokens, so skip_special_tokens cannot be used as a
+        # privacy boundary.  They are inferred only when the vocabulary covers the
+        # known IDs; smaller/native vocabularies must configure boundaries.
+        if start is None and self.config.vocab_size > 248_068:
+            start = 248_068
+        if end is None and self.config.vocab_size > 248_069:
+            end = 248_069
+        if start is None or end is None:
+            raise ValueError(
+                "deliberative generation requires thinking_start_token_id and "
+                "thinking_end_token_id for this vocabulary"
+            )
+        for name, value in (("thinking_start_token_id", start), ("thinking_end_token_id", end)):
+            if isinstance(value, bool) or not isinstance(value, int):
+                raise TypeError(f"{name} must be an integer")
+            if not 0 <= value < self.config.vocab_size:
+                raise ValueError(f"{name} must be in [0, {self.config.vocab_size})")
+        if start == end:
+            raise ValueError("thinking start and end token IDs must be distinct")
+        return int(start), int(end)
+
+    @torch.no_grad()
+    def generate_answer(
+        self,
+        input_ids: torch.Tensor,
+        *,
+        attention_mask: torch.Tensor | None = None,
+        max_reasoning_tokens: int | None = None,
+        min_reasoning_tokens: int | None = None,
+        max_answer_tokens: int | None = None,
+        reasoning_effort: str | None = None,
+        reasoning_budget: int | None = None,
+        thinking_start_token_id: int | None = None,
+        thinking_end_token_id: int | None = None,
+        do_sample: bool = False,
+        temperature: float = 1.0,
+        top_k: int = 0,
+        top_p: float = 1.0,
+        repetition_penalty: float = 1.0,
+        answer_eos_token_id: int | list[int] | tuple[int, ...] | None = None,
+        pad_token_id: int | None = None,
+        generator: torch.Generator | None = None,
+        use_cache: bool = True,
+        progress_callback: Any | None = None,
+        answer_token_callback: Any | None = None,
+        **model_kwargs: Any,
+    ) -> DendroAnswerGenerationOutput:
+        """Deliberate privately, then return only independently budgeted answers.
+
+        The first phase ends at the configured ``</think>`` token.  An explicit
+        ``max_reasoning_tokens`` remains a hard caller limit.  With the packaged
+        ``adaptive_context`` policy and no explicit maximum, private reasoning may
+        expand past the effort profile up to the real context boundary while the
+        complete visible-answer allocation stays reserved.  If that physical
+        boundary is reached, ``</think>`` is injected before answer generation.
+
+        Rows are processed independently.  This avoids leaking one batch member's
+        early-close padding into another member's cache and permits variable hidden
+        reasoning lengths without exposing them in a rectangular result tensor.
+        ``progress_callback`` receives phase/count/budget metadata only; private
+        token IDs are never exposed. ``answer_token_callback`` receives visible
+        answer token IDs as they are generated, enabling privacy-safe streaming.
+        """
+
+        if not torch.is_tensor(input_ids) or input_ids.ndim != 2:
+            raise ValueError("input_ids must be a tensor with shape (batch, sequence)")
+        if input_ids.shape[0] == 0 or input_ids.shape[1] == 0:
+            raise ValueError("input_ids must contain at least one token per row")
+        for name, value in (("max_reasoning_tokens", max_reasoning_tokens),
+                            ("min_reasoning_tokens", min_reasoning_tokens)):
+            if value is None:
+                continue
+            if isinstance(value, bool) or not isinstance(value, int):
+                raise TypeError(f"{name} must be an integer")
+            if value < 0:
+                raise ValueError(f"{name} cannot be negative")
+        explicit_answer_max = max_answer_tokens is not None
+        if max_answer_tokens is not None:
+            if isinstance(max_answer_tokens, bool) or not isinstance(max_answer_tokens, int):
+                raise TypeError("max_answer_tokens must be an integer")
+            if max_answer_tokens < 0:
+                raise ValueError("max_answer_tokens cannot be negative")
+        configured_answer_reserve = int(
+            getattr(self.config, "generation_default_max_answer_tokens", 384)
+        )
+        if max_answer_tokens is None:
+            max_answer_tokens = configured_answer_reserve
+        # Validate even when both generation phases have a zero token allowance.
+        self.config.resolve_reasoning_budget(reasoning_effort, reasoning_budget)
+        resolved_reasoning_min, resolved_reasoning_max = self.config.reasoning_token_budget(
+            reasoning_effort,
+            maximum=max_reasoning_tokens,
+            minimum=min_reasoning_tokens,
+        )
+        answer_reasoning_budget = self.config.answer_commit_budget(
+            reasoning_effort, reasoning_budget
+        )
+        thinking_start, thinking_end = self._resolve_thinking_token_ids(
+            thinking_start_token_id, thinking_end_token_id
+        )
+        if any(key in model_kwargs for key in ("position_ids", "cache_position")):
+            raise TypeError(
+                "generate_answer derives private-phase positions and does not accept "
+                "position_ids or cache_position"
+            )
+
+        if attention_mask is None:
+            supplied_mask = torch.ones_like(input_ids, dtype=torch.bool)
+        else:
+            if not torch.is_tensor(attention_mask):
+                attention_mask = torch.as_tensor(attention_mask, device=input_ids.device)
+            supplied_mask = attention_mask.to(device=input_ids.device, dtype=torch.bool)
+            if supplied_mask.shape != input_ids.shape:
+                raise ValueError("attention_mask must have the same shape as input_ids")
+
+        configured_eos = (
+            self.config.eos_token_id
+            if answer_eos_token_id is None
+            else answer_eos_token_id
+        )
+        eos_values = configured_eos if isinstance(configured_eos, (list, tuple)) else (configured_eos,)
+        normalized_eos: tuple[int, ...] = tuple(
+            int(value)
+            for value in eos_values
+            if value is not None and not isinstance(value, bool) and isinstance(value, int)
+        )
+        resolved_pad = self.config.pad_token_id if pad_token_id is None else pad_token_id
+        if resolved_pad is None:
+            resolved_pad = next(
+                (value for value in normalized_eos if 0 <= value < self.config.vocab_size),
+                0,
+            )
+        if isinstance(resolved_pad, bool) or not isinstance(resolved_pad, int):
+            raise TypeError("pad_token_id must be an integer")
+        if not 0 <= resolved_pad < self.config.vocab_size:
+            raise ValueError("pad_token_id must be in [0, vocab_size)")
+
+        if input_ids.shape[0] > 1 and any(
+            model_kwargs.get(name) is not None
+            for name in (
+                "pixel_values",
+                "pixel_values_videos",
+                "audio_values",
+                "video_values",
+                "sensor_values",
+            )
+        ):
+            raise ValueError(
+                "batched deliberative multimodal generation is not yet supported; "
+                "generate each multimodal request separately"
+            )
+
+        answer_rows: list[torch.Tensor] = []
+        reasoning_counts: list[int] = []
+        reasoning_minimums: list[int] = []
+        reasoning_budgets: list[int] = []
+        reasoning_completed: list[bool] = []
+        forced_close: list[bool] = []
+        answer_counts: list[int] = []
+        answer_eos_reached: list[bool] = []
+        answer_reasoning_filtered: list[bool] = []
+        finish_reasons: list[str] = []
+        direct_final = self.config.reasoning_effort_profile(reasoning_effort)[0] == "direct"
+
+        batch_size = input_ids.shape[0]
+        for name, callback in (
+            ("progress_callback", progress_callback),
+            ("answer_token_callback", answer_token_callback),
+        ):
+            if callback is not None and not callable(callback):
+                raise TypeError(f"{name} must be callable")
+        sampling_kwargs = {
+            "do_sample": do_sample,
+            "temperature": temperature,
+            "top_k": top_k,
+            "top_p": top_p,
+            "repetition_penalty": repetition_penalty,
+            "generator": generator,
+            "use_cache": use_cache,
+        }
+        for row_index in range(batch_size):
+            valid = supplied_mask[row_index]
+            if not bool(valid.any().item()):
+                raise ValueError("each input row must contain at least one unmasked token")
+            row_prompt = input_ids[row_index, valid].unsqueeze(0)
+            row_mask = torch.ones_like(row_prompt, dtype=torch.bool)
+            row_kwargs: dict[str, Any] = {}
+            for key, value in model_kwargs.items():
+                if torch.is_tensor(value) and value.ndim > 0 and value.shape[0] == batch_size:
+                    sliced = value[row_index : row_index + 1]
+                    if (
+                        key in {"mm_token_type_ids", "prefix_mask"}
+                        and sliced.ndim == 2
+                        and sliced.shape[1] == input_ids.shape[1]
+                    ):
+                        sliced = sliced[:, valid.to(device=sliced.device)]
+                    row_kwargs[key] = sliced
+                else:
+                    row_kwargs[key] = value
+
+            def sequence_aligned_kwargs(length: int) -> dict[str, Any]:
+                aligned = dict(row_kwargs)
+                for key in ("mm_token_type_ids", "prefix_mask"):
+                    value = aligned.get(key)
+                    if value is None or not torch.is_tensor(value) or value.ndim != 2:
+                        continue
+                    if value.shape[1] > length:
+                        raise ValueError(f"{key} is longer than the deliberative sequence")
+                    if value.shape[1] < length:
+                        padding = value.new_zeros((value.shape[0], length - value.shape[1]))
+                        aligned[key] = torch.cat((value, padding), dim=1)
+                return aligned
+
+            prompt_values = row_prompt[0].detach().cpu().tolist()
+            last_start = max(
+                (index for index, token in enumerate(prompt_values) if token == thinking_start),
+                default=-1,
+            )
+            last_end = max(
+                (index for index, token in enumerate(prompt_values) if token == thinking_end),
+                default=-1,
+            )
+            row_reasoning_max = resolved_reasoning_max
+            if (
+                not direct_final
+                and
+                max_reasoning_tokens is None
+                and self.config.reasoning_token_budget_policy == "adaptive_context"
+                and self.config.private_deliberation_trained
+            ):
+                context_limits = [int(self.config.max_position_embeddings)]
+                if self.config.transplant_mode in {"exact", "awakening"}:
+                    context_limits.append(int(self.config.transplant_attention_window))
+                if self.config.max_cache_length is not None:
+                    context_limits.append(int(self.config.max_cache_length))
+                if self.config.sliding_window is not None:
+                    context_limits.append(int(self.config.sliding_window))
+                # Reasoning past the active attention/cache window is not deeper:
+                # early private tokens have already been evicted.  The minimum
+                # physical limit is therefore the honest adaptive boundary.
+                active_context_capacity = min(context_limits)
+                physical_allowance = (
+                    active_context_capacity
+                    - int(row_prompt.shape[1])
+                    - int(max_answer_tokens)
+                    - int(
+                        getattr(
+                            self.config,
+                            "generation_completion_reserve_tokens",
+                            0,
+                        )
+                    )
+                    - int(self.config.reasoning_context_guard_tokens)
+                    - 1
+                )
+                if physical_allowance < resolved_reasoning_min:
+                    raise ValueError(
+                        "prompt plus reserved answer leaves insufficient active context for "
+                        "the configured minimum private reasoning budget"
+                    )
+                # The active window is authoritative.  Effort profiles are the
+                # initial/minimum policy, never permission to consume the answer
+                # allocation or silently evict the user's goal before answering.
+                row_reasoning_max = physical_allowance
+            if row_reasoning_max > 0 and last_start <= last_end:
+                opener = row_prompt.new_tensor([[thinking_start]])
+                row_prompt = torch.cat((row_prompt, opener), dim=1)
+                row_mask = torch.cat((row_mask, torch.ones_like(opener, dtype=torch.bool)), dim=1)
+
+            reasoning_prefix_length = row_prompt.shape[1]
+            if progress_callback is not None:
+                progress_callback("reasoning_start", 0, row_reasoning_max)
+            if row_reasoning_max:
+                def private_progress(
+                    _tokens: torch.Tensor,
+                    count: int,
+                    _active: torch.Tensor,
+                ) -> None:
+                    if progress_callback is not None:
+                        progress_callback("reasoning", count, row_reasoning_max)
+
+                deliberated = self._local_generate(
+                    row_prompt,
+                    attention_mask=row_mask,
+                    max_new_tokens=row_reasoning_max,
+                    completion_reserve_tokens=0,
+                    min_new_tokens=resolved_reasoning_min,
+                    eos_token_id=thinking_end,
+                    pad_token_id=resolved_pad,
+                    reasoning_effort=reasoning_effort,
+                    reasoning_budget=reasoning_budget,
+                    token_callback=private_progress,
+                    **sampling_kwargs,
+                    **sequence_aligned_kwargs(row_prompt.shape[1]),
+                )
+            else:
+                deliberated = row_prompt
+            reasoning_suffix = deliberated[0, reasoning_prefix_length:]
+            close_positions = torch.nonzero(
+                reasoning_suffix.eq(thinking_end), as_tuple=False
+            ).flatten()
+            closed_naturally = close_positions.numel() > 0
+            if row_reasoning_max == 0:
+                # Low/direct effort does not manufacture a private phase.  Close
+                # only a caller-supplied dangling think span, then preserve the
+                # entire independently budgeted answer allowance.
+                if last_start > last_end:
+                    closer = deliberated.new_tensor([[thinking_end]])
+                    internal = torch.cat((deliberated, closer), dim=1)
+                else:
+                    internal = deliberated
+                closed_naturally = True
+                reasoning_count = 0
+            elif closed_naturally:
+                close_offset = int(close_positions[0].item())
+                reasoning_count = close_offset
+                internal = deliberated[:, : reasoning_prefix_length + close_offset + 1]
+            else:
+                reasoning_count = int(reasoning_suffix.numel())
+                closer = deliberated.new_tensor([[thinking_end]])
+                internal = torch.cat((deliberated, closer), dim=1)
+
+            internal_mask = torch.ones_like(internal, dtype=torch.bool)
+            row_answer_max = max_answer_tokens
+            adaptive_answer = (
+                not explicit_answer_max
+                and getattr(self.config, "answer_token_budget_policy", "fixed")
+                == "adaptive_context"
+            )
+            if adaptive_answer:
+                # Logical request/output capacity is distinct from the bounded
+                # physical KV attention window. Sliding caches cap memory while
+                # absolute positions and total generation may continue. Private
+                # reasoning remains physically guarded above so its answer-phase
+                # prefill cannot grow without bound.
+                active_capacity = min(
+                    int(self.config.max_position_embeddings),
+                    int(
+                        getattr(
+                            self.config,
+                            "generation_logical_context_tokens",
+                            self.config.max_position_embeddings,
+                        )
+                    ),
+                )
+                row_answer_max = max(
+                    0,
+                    active_capacity
+                    - int(internal.shape[1])
+                    - int(self.config.reasoning_context_guard_tokens),
+                )
+            if progress_callback is not None:
+                progress_callback("answer_start", 0, row_answer_max)
+            if row_answer_max:
+                streaming_inside_reasoning = False
+
+                def visible_progress(
+                    tokens: torch.Tensor,
+                    count: int,
+                    active: torch.Tensor,
+                ) -> None:
+                    nonlocal streaming_inside_reasoning
+                    if progress_callback is not None:
+                        progress_callback("answer", count, row_answer_max)
+                    token = int(tokens[0, 0].item())
+                    if token == thinking_start:
+                        streaming_inside_reasoning = True
+                    elif token == thinking_end:
+                        streaming_inside_reasoning = False
+                    elif answer_token_callback is not None and not streaming_inside_reasoning:
+                        answer_token_callback(tokens, active)
+
+                answered = self._local_generate(
+                    internal,
+                    attention_mask=internal_mask,
+                    max_new_tokens=row_answer_max,
+                    completion_reserve_tokens=(
+                        0
+                        if adaptive_answer or explicit_answer_max
+                        else int(
+                            getattr(
+                                self.config,
+                                "generation_completion_reserve_tokens",
+                                0,
+                            )
+                        )
+                    ),
+                    eos_token_id=configured_eos,
+                    pad_token_id=resolved_pad,
+                    reasoning_effort=reasoning_effort,
+                    reasoning_budget=answer_reasoning_budget,
+                    token_callback=visible_progress,
+                    **sampling_kwargs,
+                    **sequence_aligned_kwargs(internal.shape[1]),
+                )
+                raw_answer = answered[0, internal.shape[1]:].contiguous()
+            else:
+                raw_answer = internal.new_empty((0,), dtype=internal.dtype)
+            reached_eos = any(
+                bool(raw_answer.eq(value).any().item()) for value in normalized_eos
+            )
+            # The thinking delimiters are ordinary Qwen added tokens, not special
+            # tokens.  Filter any accidentally reopened think span before exposing
+            # answer IDs; an unclosed span is dropped through the end of the row.
+            visible_tokens: list[int] = []
+            inside_reasoning = False
+            filtered_reasoning = False
+            for token in raw_answer.detach().cpu().tolist():
+                if token == thinking_start:
+                    inside_reasoning = True
+                    filtered_reasoning = True
+                    continue
+                if token == thinking_end:
+                    inside_reasoning = False
+                    filtered_reasoning = True
+                    continue
+                if not inside_reasoning:
+                    visible_tokens.append(int(token))
+            answer = raw_answer.new_tensor(visible_tokens)
+
+            answer_rows.append(answer)
+            reasoning_counts.append(reasoning_count)
+            reasoning_minimums.append(resolved_reasoning_min)
+            reasoning_budgets.append(row_reasoning_max)
+            reasoning_completed.append(closed_naturally)
+            forced_close.append(not closed_naturally)
+            answer_counts.append(int(answer.numel()))
+            answer_eos_reached.append(reached_eos)
+            answer_reasoning_filtered.append(filtered_reasoning)
+            finish_reasons.append("eos" if reached_eos else "length")
+            if progress_callback is not None:
+                progress_callback("complete", int(answer.numel()), row_answer_max)
+
+        maximum_answer_length = max(answer_counts, default=0)
+        answer_token_ids = input_ids.new_full(
+            (batch_size, maximum_answer_length), resolved_pad
+        )
+        answer_attention_mask = torch.zeros(
+            (batch_size, maximum_answer_length),
+            device=input_ids.device,
+            dtype=torch.bool,
+        )
+        for row_index, answer in enumerate(answer_rows):
+            count = answer.numel()
+            if count:
+                answer_token_ids[row_index, :count].copy_(answer)
+                answer_attention_mask[row_index, :count] = True
+
+        return DendroAnswerGenerationOutput(
+            answer_token_ids=answer_token_ids,
+            answer_attention_mask=answer_attention_mask,
+            reasoning_token_counts=tuple(reasoning_counts),
+            reasoning_minimum_tokens=tuple(reasoning_minimums),
+            reasoning_token_budgets=tuple(reasoning_budgets),
+            reasoning_completed=tuple(reasoning_completed),
+            reasoning_forced_close=tuple(forced_close),
+            answer_token_counts=tuple(answer_counts),
+            answer_eos_reached=tuple(answer_eos_reached),
+            answer_reasoning_filtered=tuple(answer_reasoning_filtered),
+            finish_reasons=tuple(finish_reasons),
+        )
+
+    def generate(self, *args: Any, **kwargs: Any) -> torch.Tensor:
+        private_reasoning = kwargs.pop("private_reasoning", None)
+        if private_reasoning is None:
+            private_reasoning = bool(
+                getattr(self.config, "default_private_reasoning_generation", False)
+                and self.config.private_deliberation_trained
+            )
+        if not isinstance(private_reasoning, bool):
+            raise TypeError("private_reasoning must be a boolean")
+        if private_reasoning:
+            if args:
+                input_ids, *remaining = args
+                if remaining:
+                    raise TypeError(
+                        "Private generate accepts only input_ids as a positional argument"
+                    )
+            else:
+                input_ids = kwargs.pop("input_ids")
+            if "max_new_tokens" in kwargs:
+                max_answer_tokens = kwargs.pop("max_new_tokens")
+            elif getattr(self.config, "answer_token_budget_policy", "fixed") == "adaptive_context":
+                max_answer_tokens = None
+            else:
+                max_answer_tokens = int(
+                    getattr(self.config, "generation_default_max_answer_tokens", 384)
+                )
+            min_new_tokens = kwargs.pop("min_new_tokens", 0)
+            if min_new_tokens:
+                raise TypeError(
+                    "min_new_tokens is not supported by private generation; use "
+                    "generate_answer for explicit phase control"
+                )
+            answer_eos = kwargs.pop("eos_token_id", None)
+            answer = self.generate_answer(
+                input_ids,
+                max_answer_tokens=max_answer_tokens,
+                answer_eos_token_id=answer_eos,
+                **kwargs,
+            )
+            return torch.cat(
+                (input_ids, answer.answer_token_ids.to(device=input_ids.device)), dim=1
+            ).contiguous()
+        # The transplant path owns an exact hybrid cache that generic Transformers
+        # cannot construct. Use the local loop so donor full-attention, gated-delta,
+        # convolution, and Dendro recurrent states advance one token at a time.
+        if self.model.transplant_core is not None and self.config.transplant_mode in {"exact", "awakening"}:
+            if args:
+                input_ids, *remaining = args
+                if remaining:
+                    raise TypeError("Transplant generate accepts only input_ids as a positional argument")
+            else:
+                input_ids = kwargs.pop("input_ids")
+            return self._local_generate(input_ids, **kwargs)
+        if TRANSFORMERS_AVAILABLE:
+            return GenerationMixin.generate(self, *args, **kwargs)
+        if args:
+            input_ids, *remaining = args
+            if remaining:
+                raise TypeError("Local generate accepts only input_ids as a positional argument")
+        else:
+            input_ids = kwargs.pop("input_ids")
+        return self._local_generate(input_ids, **kwargs)
+
+    def architecture_audit(self, *, raise_on_error: bool = False) -> dict[str, Any]:
+        parameters = list(self.named_parameters())
+        private_layers = [
+            name
+            for name, module in self.named_modules()
+            if isinstance(module, (nn.Linear, nn.Embedding))
+        ]
+        cell_count = sum(isinstance(module, DendroRecurrentCell) for module in self.modules())
+        result = {
+            **self.source_layer.audit(),
+            "model_parameter_tensors": len(parameters),
+            "model_parameter_elements": sum(parameter.numel() for _name, parameter in parameters),
+            "parameter_names": [name for name, _parameter in parameters],
+            "private_linear_or_embedding_modules": private_layers,
+            "physical_recurrent_cells": cell_count,
+            "virtual_base_depth": self.config.num_hidden_layers,
+            "shared_input_output_token_view": True,
+            "passes": len(parameters) == 1 and not private_layers and cell_count == 1,
+        }
+        if raise_on_error and not result["passes"]:
+            raise RuntimeError(f"Dendro single-source audit failed: {result}")
+        return result
+
+    def compile_for_inference(
+        self,
+        *,
+        mode: str = "reduce-overhead",
+        fullgraph: bool = False,
+        dynamic: bool = True,
+    ) -> "DendroForCausalLM":
+        """Compile the recurrent cell with ``torch.compile`` when available."""
+
+        if not hasattr(torch, "compile"):
+            raise RuntimeError("This PyTorch build does not provide torch.compile")
+        self.model.cell = torch.compile(  # type: ignore[assignment]
+            self.model.cell,
+            mode=mode,
+            fullgraph=fullgraph,
+            dynamic=dynamic,
+        )
+        return self
+
+
+def register_dendro_auto_classes() -> bool:
+    """Register the model with local Hugging Face Auto classes."""
+
+    if not TRANSFORMERS_AVAILABLE:
+        return False
+    from transformers import AutoConfig, AutoModel, AutoModelForCausalLM, AutoTokenizer
+
+    from .tokenization_dendro_omni import DendroByteTokenizer
+
+    try:
+        AutoConfig.register(DendroOmniConfig.model_type, DendroOmniConfig)
+    except ValueError:
+        pass
+    try:
+        AutoModel.register(DendroOmniConfig, DendroOmniModel)
+    except ValueError:
+        pass
+    try:
+        AutoModelForCausalLM.register(DendroOmniConfig, DendroForCausalLM)
+    except ValueError:
+        pass
+    try:
+        AutoTokenizer.register(
+            DendroOmniConfig,
+            slow_tokenizer_class=DendroByteTokenizer,
+            fast_tokenizer_class=None,
+        )
+    except ValueError:
+        pass
+    return True

preprocessor_config.json

@@ -0,0 +1,15 @@
+{
+  "processor_class": "DendroVisionProcessor",
+  "auto_map": {
+    "AutoProcessor": "processing_dendro_omni.DendroVisionProcessor"
+  },
+  "image_processor_type": "DendroVisionProcessor",
+  "patch_size": 16,
+  "temporal_patch_size": 2,
+  "merge_size": 2,
+  "image_mean": [0.5, 0.5, 0.5],
+  "image_std": [0.5, 0.5, 0.5],
+  "max_side": 448,
+  "supported_modalities": ["text", "image"],
+  "unsupported_modalities": ["audio", "video", "image-generation", "video-generation"]
+}

processing_dendro_omni.py

@@ -0,0 +1,267 @@
+"""Image processor for Phillnet Mini Text-Vision.
+
+The processor produces Qwen-compatible visual patch tensors for the retained
+transplanted vision encoder and deliberately exposes no image or video synthesis
+functionality.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Sequence
+
+import torch
+from PIL import Image
+
+from transformers import AutoTokenizer
+
+try:
+    from transformers.feature_extraction_utils import BatchFeature
+except Exception:  # pragma: no cover
+    BatchFeature = dict  # type: ignore[misc,assignment]
+
+
+IMAGE_MARKER = "\ue000"
+
+
+class DendroVisionProcessor:
+    """Prepare text and still-image inputs for Phillnet Mini Text-Vision.
+
+    This class supports text generation and image understanding only.  It accepts
+    one conversation at a time, creates static two-frame visual patches required
+    by the retained vision tower, and expands one image placeholder per merged
+    visual token.
+    """
+
+    model_input_names = [
+        "input_ids",
+        "attention_mask",
+        "pixel_values",
+        "image_grid_thw",
+        "mm_token_type_ids",
+    ]
+
+    @classmethod
+    def register_for_auto_class(cls, auto_class: str = "AutoProcessor") -> None:
+        """Compatibility hook used by Transformers dynamic-module loading."""
+        cls._auto_class = str(auto_class)
+
+    def __init__(
+        self,
+        tokenizer: Any,
+        *,
+        image_token_id: int,
+        vision_start_token_id: int,
+        vision_end_token_id: int,
+        patch_size: int = 16,
+        temporal_patch_size: int = 2,
+        spatial_merge_size: int = 2,
+        image_mean: Sequence[float] = (0.5, 0.5, 0.5),
+        image_std: Sequence[float] = (0.5, 0.5, 0.5),
+        max_side: int = 448,
+    ) -> None:
+        self.tokenizer = tokenizer
+        self.image_token_id = int(image_token_id)
+        self.vision_start_token_id = int(vision_start_token_id)
+        self.vision_end_token_id = int(vision_end_token_id)
+        self.patch_size = int(patch_size)
+        self.temporal_patch_size = int(temporal_patch_size)
+        self.spatial_merge_size = int(spatial_merge_size)
+        self.image_mean = tuple(float(x) for x in image_mean)
+        self.image_std = tuple(float(x) for x in image_std)
+        self.max_side = int(max_side)
+        if self.patch_size < 1 or self.temporal_patch_size < 1 or self.spatial_merge_size < 1:
+            raise ValueError("Visual patch and merge dimensions must be positive")
+
+    @classmethod
+    def from_pretrained(cls, pretrained_model_name_or_path: str | Path, **kwargs: Any) -> "DendroVisionProcessor":
+        root = Path(pretrained_model_name_or_path)
+        config = json.loads((root / "config.json").read_text(encoding="utf-8"))
+        preprocessing = json.loads((root / "preprocessor_config.json").read_text(encoding="utf-8"))
+        tokenizer_kwargs = dict(kwargs)
+        max_side = int(tokenizer_kwargs.pop("max_side", preprocessing.get("max_side", 448)))
+        tokenizer_kwargs.pop("trust_remote_code", None)
+        tokenizer_kwargs.pop("_from_auto", None)
+        tokenizer = AutoTokenizer.from_pretrained(str(root), trust_remote_code=False, **tokenizer_kwargs)
+        return cls(
+            tokenizer,
+            image_token_id=int(config["image_token_id"]),
+            vision_start_token_id=int(config["vision_start_token_id"]),
+            vision_end_token_id=int(config["vision_end_token_id"]),
+            patch_size=int(preprocessing.get("patch_size", 16)),
+            temporal_patch_size=int(preprocessing.get("temporal_patch_size", 2)),
+            spatial_merge_size=int(preprocessing.get("merge_size", 2)),
+            image_mean=preprocessing.get("image_mean", (0.5, 0.5, 0.5)),
+            image_std=preprocessing.get("image_std", (0.5, 0.5, 0.5)),
+            max_side=max_side,
+        )
+
+    def _encode_text(self, value: str) -> list[int]:
+        return list(self.tokenizer.encode(str(value), add_special_tokens=False))
+
+    @staticmethod
+    def _to_pil(image: Any) -> Image.Image:
+        if isinstance(image, Image.Image):
+            return image.convert("RGB")
+        if isinstance(image, (str, Path)):
+            with Image.open(image) as opened:
+                return opened.convert("RGB")
+        if torch.is_tensor(image):
+            value = image.detach().cpu().float()
+            if value.ndim == 4 and value.shape[0] == 1:
+                value = value[0]
+            if value.ndim != 3:
+                raise TypeError("Image tensor must be [C,H,W] or [1,C,H,W]")
+            if value.shape[0] in {1, 3, 4}:
+                value = value[:3].permute(1, 2, 0)
+            value = value.clamp(0, 1).mul(255).byte().numpy()
+            return Image.fromarray(value).convert("RGB")
+        try:
+            import numpy as np
+            value = np.asarray(image)
+            if value.ndim == 3:
+                if value.dtype != np.uint8:
+                    value = (value.clip(0, 1) * 255 if float(value.max()) <= 1 else value.clip(0, 255)).astype(np.uint8)
+                return Image.fromarray(value).convert("RGB")
+        except Exception as error:  # pragma: no cover
+            raise TypeError("Unsupported image input") from error
+        raise TypeError("Unsupported image input")
+
+    def _resize(self, image: Image.Image) -> Image.Image:
+        unit = self.patch_size * self.spatial_merge_size
+        width, height = image.size
+        if max(width, height) > self.max_side:
+            scale = self.max_side / max(width, height)
+            width, height = round(width * scale), round(height * scale)
+        width = max(unit, round(width / unit) * unit)
+        height = max(unit, round(height / unit) * unit)
+        return image.resize((width, height), Image.Resampling.BICUBIC)
+
+    def _patchify(self, image: Any) -> tuple[torch.Tensor, torch.Tensor, int]:
+        prepared = self._resize(self._to_pil(image))
+        try:
+            import numpy as np
+            values = torch.from_numpy(np.asarray(prepared).copy()).permute(2, 0, 1).float().div_(255.0)
+        except Exception as error:  # pragma: no cover
+            raise RuntimeError("NumPy is required for image preprocessing") from error
+        mean = torch.tensor(self.image_mean).view(3, 1, 1)
+        std = torch.tensor(self.image_std).view(3, 1, 1)
+        values = (values - mean) / std
+        channels, height, width = values.shape
+        patch = self.patch_size
+        temporal = self.temporal_patch_size
+        grid_h, grid_w = height // patch, width // patch
+        frames = values.unsqueeze(0).repeat(temporal, 1, 1, 1)
+        blocks = frames.reshape(1, temporal, channels, grid_h, patch, grid_w, patch)
+        blocks = blocks.permute(0, 3, 5, 2, 1, 4, 6).reshape(-1, channels * temporal * patch * patch)
+        grid = torch.tensor([[1, grid_h, grid_w]], dtype=torch.long)
+        placeholder_count = grid_h // self.spatial_merge_size * (grid_w // self.spatial_merge_size)
+        return blocks, grid, int(placeholder_count)
+
+    def _build_single(self, text: str, images: Sequence[Any] | None) -> dict[str, torch.Tensor]:
+        image_list = list(images or [])
+        if IMAGE_MARKER not in text and image_list:
+            text = text + IMAGE_MARKER * len(image_list)
+        chunks = text.split(IMAGE_MARKER)
+        if len(chunks) != len(image_list) + 1:
+            raise ValueError("Image markers must match the number of supplied images")
+        ids: list[int] = []
+        types: list[int] = []
+        pixel_blocks: list[torch.Tensor] = []
+        grids: list[torch.Tensor] = []
+        for index, chunk in enumerate(chunks):
+            text_ids = self._encode_text(chunk)
+            ids.extend(text_ids)
+            types.extend([0] * len(text_ids))
+            if index == len(image_list):
+                continue
+            blocks, grid, count = self._patchify(image_list[index])
+            ids.append(self.vision_start_token_id)
+            types.append(0)
+            ids.extend([self.image_token_id] * count)
+            types.extend([1] * count)
+            ids.append(self.vision_end_token_id)
+            types.append(0)
+            pixel_blocks.append(blocks)
+            grids.append(grid)
+        output: dict[str, torch.Tensor] = {
+            "input_ids": torch.tensor([ids], dtype=torch.long),
+            "attention_mask": torch.ones((1, len(ids)), dtype=torch.long),
+        }
+        if pixel_blocks:
+            output["pixel_values"] = torch.cat(pixel_blocks, dim=0)
+            output["image_grid_thw"] = torch.cat(grids, dim=0)
+            output["mm_token_type_ids"] = torch.tensor([types], dtype=torch.long)
+        return output
+
+    def __call__(
+        self,
+        text: str | Sequence[str],
+        *,
+        images: Any | Sequence[Any] | None = None,
+        return_tensors: str | None = "pt",
+        **_: Any,
+    ) -> Any:
+        if isinstance(text, Sequence) and not isinstance(text, str):
+            if len(text) != 1:
+                raise ValueError("DendroVisionProcessor currently accepts a single conversation per call")
+            text = text[0]
+        if images is None:
+            image_list: list[Any] = []
+        elif isinstance(images, (str, Path, Image.Image)) or torch.is_tensor(images):
+            image_list = [images]
+        else:
+            image_list = list(images)
+        encoded = self._build_single(str(text), image_list)
+        if return_tensors not in {None, "pt"}:
+            raise ValueError("Only return_tensors='pt' is supported")
+        return BatchFeature(data=encoded, tensor_type="pt") if BatchFeature is not dict else encoded
+
+    def apply_chat_template(
+        self,
+        messages: Sequence[dict[str, Any]],
+        *,
+        tokenize: bool = True,
+        add_generation_prompt: bool = True,
+        enable_thinking: bool = False,
+        return_dict: bool = True,
+        return_tensors: str | None = "pt",
+        **_: Any,
+    ) -> Any:
+        parts: list[str] = []
+        images: list[Any] = []
+        for message in messages:
+            role = str(message.get("role", "user"))
+            parts.append(f"<|im_start|>{role}\n")
+            content = message.get("content", "")
+            if isinstance(content, str):
+                parts.append(content)
+            else:
+                for item in content:
+                    item_type = item.get("type") if isinstance(item, dict) else None
+                    if item_type == "text":
+                        parts.append(str(item.get("text", "")))
+                    elif item_type == "image":
+                        image = item.get("image", item.get("image_url"))
+                        if image is None:
+                            raise ValueError("Image content must provide an image object")
+                        images.append(image)
+                        parts.append(IMAGE_MARKER)
+                    else:
+                        raise ValueError(f"Unsupported chat content type: {item_type!r}")
+            parts.append("<|im_end|>\n")
+        if add_generation_prompt:
+            parts.append("<|im_start|>assistant\n")
+            parts.append("<think>\n" if enable_thinking else "<think>\n\n</think>\n\n")
+        prompt = "".join(parts)
+        if not tokenize:
+            return prompt
+        encoded = self(prompt, images=images, return_tensors=return_tensors)
+        return encoded if return_dict else encoded["input_ids"]
+
+    def save_pretrained(self, save_directory: str | Path, **_: Any) -> tuple[str]:
+        root = Path(save_directory)
+        root.mkdir(parents=True, exist_ok=True)
+        path = root / "preprocessor_config.json"
+        path.write_text(json.dumps({"processor_class": "DendroVisionProcessor"}, indent=2) + "\n", encoding="utf-8")
+        return (str(path),)

requirements-server.txt

@@ -0,0 +1,3 @@
+fastapi>=0.115
+uvicorn[standard]>=0.30
+pydantic>=2.0

server.py

@@ -0,0 +1,226 @@
+"""Production-oriented text-and-still-image API for Phillnet Mini Text-Vision.
+
+The service intentionally exposes only chat completion and visual-question-answering
+workflows. SDXL, image/video synthesis, audio, agents, tools, and remote image URL
+fetching are outside this deployment surface.
+"""
+from __future__ import annotations
+
+import base64
+import hmac
+import io
+import os
+import threading
+import time
+import uuid
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any
+
+import torch
+from fastapi import Depends, FastAPI, Header, HTTPException, Request, status
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from PIL import Image, UnidentifiedImageError
+from pydantic import BaseModel, Field
+from transformers import AutoModelForCausalLM, AutoProcessor
+
+MODEL_DIR = Path(os.getenv("MODEL_DIR", Path(__file__).resolve().parent))
+API_KEY = os.getenv("PHILLNET_API_KEY", "")
+MAX_IMAGE_BYTES = int(os.getenv("PHILLNET_MAX_IMAGE_BYTES", str(10 * 1024 * 1024)))
+MAX_IMAGE_PIXELS = int(os.getenv("PHILLNET_MAX_IMAGE_PIXELS", str(24_000_000)))
+MAX_REQUEST_BYTES = int(os.getenv("PHILLNET_MAX_REQUEST_BYTES", str(12 * 1024 * 1024)))
+CORS_ORIGINS = [origin.strip() for origin in os.getenv("PHILLNET_CORS_ORIGINS", "").split(",") if origin.strip()]
+
+Image.MAX_IMAGE_PIXELS = MAX_IMAGE_PIXELS
+MODEL: Any | None = None
+PROCESSOR: Any | None = None
+GENERATION_LOCK = threading.Lock()
+
+
+class ImageContent(BaseModel):
+    type: str
+    text: str | None = Field(default=None, max_length=32_000)
+    image_base64: str | None = None
+
+
+class Message(BaseModel):
+    role: str = Field(pattern="^(system|user|assistant)$")
+    content: str | list[ImageContent]
+
+
+class ChatRequest(BaseModel):
+    model: str = "phillnet-mini-text-vision"
+    messages: list[Message] = Field(min_length=1, max_length=32)
+    max_tokens: int = Field(default=8192, ge=1, le=8192)
+    temperature: float = Field(default=0.0, ge=0.0, le=2.0)
+    reasoning_effort: str = Field(default="max", pattern="^(direct|low|medium|high|max)$")
+
+
+def require_api_key(
+    authorization: str | None = Header(default=None),
+    x_api_key: str | None = Header(default=None),
+) -> None:
+    """Enforce an API key when PHILLNET_API_KEY is configured.
+
+    Local development remains frictionless when the environment variable is empty.
+    Production compose configuration supplies a non-empty secret by default.
+    """
+    if not API_KEY:
+        return
+    candidate = x_api_key or ""
+    if authorization and authorization.lower().startswith("bearer "):
+        candidate = authorization[7:].strip()
+    if not candidate or not hmac.compare_digest(candidate, API_KEY):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Valid API credentials are required.",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+
+def decode_image(encoded: str) -> Image.Image:
+    try:
+        raw = encoded.split(",", 1)[1] if encoded.startswith("data:") else encoded
+        # Base64 expands bytes by roughly 4/3. Guard before decoding a large body.
+        if len(raw) > ((MAX_IMAGE_BYTES * 4) // 3) + 8:
+            raise HTTPException(413, f"image_base64 exceeds the {MAX_IMAGE_BYTES}-byte limit")
+        payload = base64.b64decode(raw, validate=True)
+        if len(payload) > MAX_IMAGE_BYTES:
+            raise HTTPException(413, f"image_base64 exceeds the {MAX_IMAGE_BYTES}-byte limit")
+        image = Image.open(io.BytesIO(payload))
+        image.load()
+        return image.convert("RGB")
+    except HTTPException:
+        raise
+    except (ValueError, UnidentifiedImageError, OSError, Image.DecompressionBombError) as error:
+        raise HTTPException(400, "image_base64 must be a valid, safe base64-encoded image") from error
+
+
+def make_contents(messages: list[Message]) -> list[dict[str, Any]]:
+    result: list[dict[str, Any]] = []
+    image_count = 0
+    for message in messages:
+        if isinstance(message.content, str):
+            if len(message.content) > 32_000:
+                raise HTTPException(400, "A text message may not exceed 32,000 characters")
+            content: str | list[dict[str, Any]] = message.content
+        else:
+            content = []
+            for item in message.content:
+                if item.type == "text":
+                    content.append({"type": "text", "text": item.text or ""})
+                elif item.type == "image":
+                    image_count += 1
+                    if image_count > 4:
+                        raise HTTPException(400, "A request may contain at most four images")
+                    if not item.image_base64:
+                        raise HTTPException(400, "image content requires image_base64")
+                    content.append({"type": "image", "image": decode_image(item.image_base64)})
+                else:
+                    raise HTTPException(400, f"Unsupported content type: {item.type!r}. Only text and image are supported.")
+        result.append({"role": message.role, "content": content})
+    return result
+
+
+@asynccontextmanager
+async def lifespan(_app: FastAPI):
+    global MODEL, PROCESSOR
+    PROCESSOR = AutoProcessor.from_pretrained(str(MODEL_DIR), trust_remote_code=True)
+    MODEL = AutoModelForCausalLM.from_pretrained(
+        str(MODEL_DIR),
+        trust_remote_code=True,
+        dtype=torch.bfloat16,
+        low_cpu_mem_usage=True,
+    ).eval()
+    yield
+    MODEL = None
+    PROCESSOR = None
+
+
+app = FastAPI(
+    title="Phillnet Mini Text-Vision",
+    version="1.1.0",
+    description="Text generation and still-image understanding only. SDXL, image generation, video generation, audio, tools, and agent runtimes are disabled.",
+    lifespan=lifespan,
+)
+
+if CORS_ORIGINS:
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=CORS_ORIGINS,
+        allow_credentials=False,
+        allow_methods=["GET", "POST"],
+        allow_headers=["Authorization", "Content-Type", "X-API-Key"],
+        max_age=600,
+    )
+
+
+@app.middleware("http")
+async def enforce_request_limit(request: Request, call_next: Any) -> Any:
+    content_length = request.headers.get("content-length")
+    if content_length and int(content_length) > MAX_REQUEST_BYTES:
+        return JSONResponse(status_code=413, content={"detail": "Request body exceeds configured size limit"})
+    return await call_next(request)
+
+
+@app.get("/health")
+def health() -> dict[str, Any]:
+    ready = MODEL is not None and PROCESSOR is not None
+    return {
+        "status": "ok" if ready else "loading",
+        "ready": ready,
+        "service": "phillnet-mini-text-vision",
+        "version": app.version,
+        "capabilities": ["text-generation", "image-understanding"],
+        "disabled": ["image-generation", "video-generation", "audio", "tools", "agents"],
+    }
+
+
+@app.get("/ready")
+def ready() -> dict[str, bool]:
+    if MODEL is None or PROCESSOR is None:
+        raise HTTPException(503, "Model is still loading")
+    return {"ready": True}
+
+
+@app.post("/v1/chat/completions", dependencies=[Depends(require_api_key)])
+def chat_completions(request: ChatRequest) -> dict[str, Any]:
+    if MODEL is None or PROCESSOR is None:
+        raise HTTPException(503, "Model is still loading")
+    content = make_contents(request.messages)
+    encoded = PROCESSOR.apply_chat_template(
+        content,
+        tokenize=True,
+        add_generation_prompt=True,
+        return_dict=True,
+        return_tensors="pt",
+    )
+    device = next(MODEL.parameters()).device
+    encoded = {key: value.to(device) if torch.is_tensor(value) else value for key, value in dict(encoded).items()}
+    prompt_length = int(encoded["input_ids"].shape[1])
+    generation_kwargs: dict[str, Any] = {
+        "max_new_tokens": request.max_tokens,
+        "do_sample": request.temperature > 0.0,
+        "use_cache": True,
+        "reasoning_effort": request.reasoning_effort,
+    }
+    if request.temperature > 0.0:
+        generation_kwargs["temperature"] = request.temperature
+    started = time.perf_counter()
+    # A single local model instance should perform one generation at a time to
+    # prevent concurrent high-context calls from overcommitting model memory.
+    with GENERATION_LOCK, torch.inference_mode():
+        output = MODEL.generate(**encoded, **generation_kwargs)
+    completion_ids = output[0, prompt_length:].detach().cpu()
+    text = PROCESSOR.tokenizer.decode(completion_ids, skip_special_tokens=True)
+    completion_tokens = int(completion_ids.numel())
+    return {
+        "id": f"chatcmpl-{uuid.uuid4().hex}",
+        "object": "chat.completion",
+        "created": int(time.time()),
+        "model": "phillnet-mini-text-vision",
+        "choices": [{"index": 0, "message": {"role": "assistant", "content": text}, "finish_reason": "stop"}],
+        "usage": {"prompt_tokens": prompt_length, "completion_tokens": completion_tokens, "total_tokens": prompt_length + completion_tokens},
+        "elapsed_seconds": round(time.perf_counter() - started, 3),
+    }

tokenization_dendro_omni.py

@@ -0,0 +1,334 @@
+"""Deterministic UTF-8 byte tokenizer for Dendro Omni."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Iterable, Sequence
+
+import torch
+
+try:  # pragma: no cover - optional Hugging Face branch.
+    from transformers import PreTrainedTokenizer
+
+    _HF_TOKENIZER = True
+except Exception:  # pragma: no cover - fallback is covered.
+    PreTrainedTokenizer = object  # type: ignore[assignment,misc]
+    _HF_TOKENIZER = False
+
+
+PAD_TOKEN = "<pad>"
+BOS_TOKEN = "<bos>"
+EOS_TOKEN = "<eos>"
+BYTE_OFFSET = 3
+
+
+def _byte_token(value: int) -> str:
+    return f"<0x{value:02X}>"
+
+
+def _token_byte(token: str) -> int | None:
+    if len(token) == 6 and token.startswith("<0x") and token.endswith(">"):
+        try:
+            value = int(token[3:5], 16)
+        except ValueError:
+            return None
+        return value if 0 <= value <= 255 else None
+    return None
+
+
+class _ByteTokenizerLogic:
+    pad_token_id = 0
+    bos_token_id = 1
+    eos_token_id = 2
+    byte_offset = BYTE_OFFSET
+    model_input_names = ["input_ids", "attention_mask"]
+
+    @property
+    def vocab_size(self) -> int:
+        return self.byte_offset + 256
+
+    def raw_encode(self, text: str, *, add_bos: bool = False, add_eos: bool = False) -> list[int]:
+        ids: list[int] = []
+        if add_bos:
+            ids.append(self.bos_token_id)
+        ids.extend(byte + self.byte_offset for byte in text.encode("utf-8"))
+        if add_eos:
+            ids.append(self.eos_token_id)
+        return ids
+
+    def raw_decode(self, token_ids: Iterable[int], *, skip_special_tokens: bool = True) -> str:
+        data = bytearray()
+        literal: list[str] = []
+        for item in token_ids:
+            token_id = int(item)
+            if token_id in (self.pad_token_id, self.bos_token_id, self.eos_token_id):
+                if skip_special_tokens:
+                    continue
+                literal.append({0: PAD_TOKEN, 1: BOS_TOKEN, 2: EOS_TOKEN}[token_id])
+                continue
+            value = token_id - self.byte_offset
+            if 0 <= value <= 255:
+                if literal:
+                    data.extend("".join(literal).encode("utf-8"))
+                    literal.clear()
+                data.append(value)
+        if literal:
+            data.extend("".join(literal).encode("utf-8"))
+        return data.decode("utf-8", errors="replace")
+
+
+if _HF_TOKENIZER:
+    class DendroByteTokenizer(_ByteTokenizerLogic, PreTrainedTokenizer):
+        """Hugging Face tokenizer with lossless byte coverage and no learned files."""
+
+        vocab_files_names = {"vocab_file": "dendro_vocab.json"}
+        model_input_names = ["input_ids", "attention_mask"]
+
+        def __init__(
+            self,
+            vocab_file: str | None = None,
+            *,
+            model_max_length: int = 131_072,
+            **kwargs: Any,
+        ) -> None:
+            del vocab_file
+            # ``from_pretrained`` restores these values through ``kwargs``.  Use
+            # defaults instead of passing a second explicit copy so this remains
+            # compatible with both legacy tokenizers and the Transformers 5
+            # Python backend.
+            kwargs.setdefault("pad_token", PAD_TOKEN)
+            kwargs.setdefault("bos_token", BOS_TOKEN)
+            kwargs.setdefault("eos_token", EOS_TOKEN)
+            kwargs.setdefault("model_max_length", model_max_length)
+            kwargs.setdefault("clean_up_tokenization_spaces", False)
+            super().__init__(**kwargs)
+
+        def _tokenize(self, text: str, **kwargs: Any) -> list[str]:
+            del kwargs
+            return [_byte_token(byte) for byte in text.encode("utf-8")]
+
+        def _convert_token_to_id(self, token: str) -> int:
+            if token == PAD_TOKEN:
+                return self.pad_token_id
+            if token == BOS_TOKEN:
+                return self.bos_token_id
+            if token == EOS_TOKEN:
+                return self.eos_token_id
+            value = _token_byte(token)
+            return self.eos_token_id if value is None else value + self.byte_offset
+
+        def _convert_id_to_token(self, index: int) -> str:
+            index = int(index)
+            if index == self.pad_token_id:
+                return PAD_TOKEN
+            if index == self.bos_token_id:
+                return BOS_TOKEN
+            if index == self.eos_token_id:
+                return EOS_TOKEN
+            value = index - self.byte_offset
+            return _byte_token(value) if 0 <= value <= 255 else EOS_TOKEN
+
+        def convert_tokens_to_string(self, tokens: list[str]) -> str:
+            data = bytearray()
+            text_parts: list[str] = []
+            for token in tokens:
+                value = _token_byte(token)
+                if value is None:
+                    if data:
+                        text_parts.append(data.decode("utf-8", errors="replace"))
+                        data.clear()
+                    if token not in {PAD_TOKEN, BOS_TOKEN, EOS_TOKEN}:
+                        text_parts.append(token)
+                else:
+                    data.append(value)
+            if data:
+                text_parts.append(data.decode("utf-8", errors="replace"))
+            return "".join(text_parts)
+
+        def get_vocab(self) -> dict[str, int]:
+            vocab = {PAD_TOKEN: 0, BOS_TOKEN: 1, EOS_TOKEN: 2}
+            vocab.update({_byte_token(value): value + self.byte_offset for value in range(256)})
+            return vocab
+
+        def build_inputs_with_special_tokens(
+            self,
+            token_ids_0: list[int],
+            token_ids_1: list[int] | None = None,
+        ) -> list[int]:
+            result = [self.bos_token_id, *token_ids_0, self.eos_token_id]
+            if token_ids_1 is not None:
+                result.extend([*token_ids_1, self.eos_token_id])
+            return result
+
+        def get_special_tokens_mask(
+            self,
+            token_ids_0: list[int],
+            token_ids_1: list[int] | None = None,
+            already_has_special_tokens: bool = False,
+        ) -> list[int]:
+            if already_has_special_tokens:
+                return [int(token in {0, 1, 2}) for token in token_ids_0]
+            mask = [1] + [0] * len(token_ids_0) + [1]
+            if token_ids_1 is not None:
+                mask += [0] * len(token_ids_1) + [1]
+            return mask
+
+        def save_vocabulary(
+            self,
+            save_directory: str,
+            filename_prefix: str | None = None,
+        ) -> tuple[str]:
+            directory = Path(save_directory)
+            directory.mkdir(parents=True, exist_ok=True)
+            name = f"{filename_prefix + '-' if filename_prefix else ''}dendro_vocab.json"
+            path = directory / name
+            path.write_text(json.dumps(self.get_vocab(), indent=2, sort_keys=True), encoding="utf-8")
+            return (str(path),)
+
+        def encode_bytes(self, text: str, *, add_bos: bool = False, add_eos: bool = False) -> list[int]:
+            return self.raw_encode(text, add_bos=add_bos, add_eos=add_eos)
+
+        def decode_bytes(self, ids: Iterable[int], *, skip_special_tokens: bool = True) -> str:
+            return self.raw_decode(ids, skip_special_tokens=skip_special_tokens)
+
+else:
+    class DendroByteTokenizer(_ByteTokenizerLogic):
+        """PyTorch-only fallback implementing the common tokenizer call surface."""
+
+        def __init__(
+            self,
+            vocab_file: str | None = None,
+            *,
+            model_max_length: int = 131_072,
+            padding_side: str = "right",
+            **_: Any,
+        ) -> None:
+            del vocab_file
+            self.model_max_length = int(model_max_length)
+            self.padding_side = str(padding_side)
+            self.pad_token = PAD_TOKEN
+            self.bos_token = BOS_TOKEN
+            self.eos_token = EOS_TOKEN
+
+        def get_vocab(self) -> dict[str, int]:
+            vocab = {PAD_TOKEN: 0, BOS_TOKEN: 1, EOS_TOKEN: 2}
+            vocab.update({_byte_token(value): value + self.byte_offset for value in range(256)})
+            return vocab
+
+        def encode(
+            self,
+            text: str,
+            *,
+            add_special_tokens: bool = True,
+            add_bos: bool | None = None,
+            add_eos: bool | None = None,
+            **_: Any,
+        ) -> list[int]:
+            return self.raw_encode(
+                text,
+                add_bos=add_special_tokens if add_bos is None else add_bos,
+                add_eos=add_special_tokens if add_eos is None else add_eos,
+            )
+
+        def decode(
+            self,
+            token_ids: Iterable[int] | torch.Tensor,
+            *,
+            skip_special_tokens: bool = True,
+            **_: Any,
+        ) -> str:
+            if torch.is_tensor(token_ids):
+                token_ids = token_ids.detach().cpu().tolist()
+            return self.raw_decode(token_ids, skip_special_tokens=skip_special_tokens)
+
+        def batch_decode(
+            self,
+            sequences: Sequence[Sequence[int] | torch.Tensor],
+            *,
+            skip_special_tokens: bool = True,
+            **kwargs: Any,
+        ) -> list[str]:
+            return [self.decode(row, skip_special_tokens=skip_special_tokens, **kwargs) for row in sequences]
+
+        def __call__(
+            self,
+            text: str | Sequence[str],
+            *,
+            add_special_tokens: bool = True,
+            padding: bool | str = False,
+            truncation: bool = False,
+            max_length: int | None = None,
+            return_tensors: str | None = None,
+            **_: Any,
+        ) -> dict[str, Any]:
+            texts = [text] if isinstance(text, str) else list(text)
+            rows = [self.encode(item, add_special_tokens=add_special_tokens) for item in texts]
+            limit = self.model_max_length if max_length is None else int(max_length)
+            if truncation:
+                rows = [row[:limit] for row in rows]
+            target = max((len(row) for row in rows), default=0) if padding else None
+            if padding == "max_length":
+                target = limit
+            masks: list[list[int]] = []
+            if target is not None:
+                padded: list[list[int]] = []
+                for row in rows:
+                    amount = max(0, target - len(row))
+                    if self.padding_side == "left":
+                        padded.append([self.pad_token_id] * amount + row[:target])
+                        masks.append([0] * amount + [1] * min(len(row), target))
+                    else:
+                        padded.append(row[:target] + [self.pad_token_id] * amount)
+                        masks.append([1] * min(len(row), target) + [0] * amount)
+                rows = padded
+            else:
+                masks = [[1] * len(row) for row in rows]
+            result: dict[str, Any] = {"input_ids": rows, "attention_mask": masks}
+            if return_tensors is not None:
+                if return_tensors != "pt":
+                    raise ValueError("The local tokenizer supports return_tensors='pt' only")
+                if not padding and len({len(row) for row in rows}) > 1:
+                    raise ValueError("Batch tensor output requires padding")
+                result = {key: torch.tensor(value, dtype=torch.long) for key, value in result.items()}
+            if isinstance(text, str) and return_tensors is None:
+                result = {key: value[0] for key, value in result.items()}
+            return result
+
+        def save_pretrained(self, save_directory: str | Path, **_: Any) -> tuple[str, ...]:
+            directory = Path(save_directory)
+            directory.mkdir(parents=True, exist_ok=True)
+            vocab_path = directory / "dendro_vocab.json"
+            config_path = directory / "tokenizer_config.json"
+            special_path = directory / "special_tokens_map.json"
+            vocab_path.write_text(json.dumps(self.get_vocab(), indent=2, sort_keys=True), encoding="utf-8")
+            config_path.write_text(
+                json.dumps(
+                    {
+                        "tokenizer_class": "DendroByteTokenizer",
+                        "model_max_length": self.model_max_length,
+                        "padding_side": self.padding_side,
+                        "auto_map": {"AutoTokenizer": ["tokenization_dendro_omni.DendroByteTokenizer", None]},
+                    },
+                    indent=2,
+                ),
+                encoding="utf-8",
+            )
+            special_path.write_text(
+                json.dumps(
+                    {"pad_token": PAD_TOKEN, "bos_token": BOS_TOKEN, "eos_token": EOS_TOKEN},
+                    indent=2,
+                ),
+                encoding="utf-8",
+            )
+            return str(vocab_path), str(config_path), str(special_path)
+
+        @classmethod
+        def from_pretrained(cls, path: str | Path, **kwargs: Any) -> "DendroByteTokenizer":
+            directory = Path(path)
+            config_path = directory / "tokenizer_config.json"
+            if config_path.exists():
+                config = json.loads(config_path.read_text(encoding="utf-8"))
+                kwargs.setdefault("model_max_length", config.get("model_max_length", 131_072))
+                kwargs.setdefault("padding_side", config.get("padding_side", "right"))
+            return cls(vocab_file=str(directory / "dendro_vocab.json"), **kwargs)

tokenizer_config.json

@@ -0,0 +1,32 @@
+{
+  "add_prefix_space": false,
+  "audio_bos_token": "<|audio_start|>",
+  "audio_eos_token": "<|audio_end|>",
+  "audio_token": "<|audio_pad|>",
+  "backend": "tokenizers",
+  "bos_token": null,
+  "clean_up_tokenization_spaces": false,
+  "eos_token": "<|im_end|>",
+  "errors": "replace",
+  "image_token": "<|image_pad|>",
+  "is_local": true,
+  "local_files_only": true,
+  "model_max_length": 262144,
+  "model_specific_special_tokens": {
+    "audio_bos_token": "<|audio_start|>",
+    "audio_eos_token": "<|audio_end|>",
+    "audio_token": "<|audio_pad|>",
+    "image_token": "<|image_pad|>",
+    "video_token": "<|video_pad|>",
+    "vision_bos_token": "<|vision_start|>",
+    "vision_eos_token": "<|vision_end|>"
+  },
+  "pad_token": "<|endoftext|>",
+  "pretokenize_regex": "(?i:'s|'t|'re|'ve|'m|'ll|'d)|[^\\r\\n\\p{L}\\p{N}]?[\\p{L}\\p{M}]+|\\p{N}| ?[^\\s\\p{L}\\p{M}\\p{N}]+[\\r\\n]*|\\s*[\\r\\n]+|\\s+(?!\\S)|\\s+",
+  "split_special_tokens": false,
+  "tokenizer_class": "Qwen2Tokenizer",
+  "unk_token": null,
+  "video_token": "<|video_pad|>",
+  "vision_bos_token": "<|vision_start|>",
+  "vision_eos_token": "<|vision_end|>"
+}

transplant.py

@@ -0,0 +1,1410 @@
+"""Dendro-native exact-equivalence path for transplanted Qwen3.5 tensors.
+
+This module contains no Qwen modules and registers no parameters.  It evaluates
+source-model operators directly from named slices of the one Dendro source
+parameter.  Dendro remains the owning architecture; the donor checkpoint is only
+an initialization and exact-equivalence coordinate system.
+
+The operator equations follow the Apache-2.0 Hugging Face Qwen3.5 reference
+implementation, rewritten as parameterless Dendro functions so that transplant
+weights never become a second model object.
+"""
+
+from __future__ import annotations
+
+import itertools
+import math
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+import torch
+from torch.nn import functional as F
+from torch.utils.checkpoint import checkpoint
+
+from ._source_bound import SourceBoundModule
+from .accelerators import (
+    fla_causal_conv1d,
+    fla_causal_conv1d_update,
+    fla_chunk_gated_delta_rule,
+    fla_recurrent_gated_delta_rule,
+)
+from .source import DendroSourceLayer
+
+
+def _can_use_fused_sdpa(
+    query: torch.Tensor,
+    key: torch.Tensor,
+    value: torch.Tensor,
+    *,
+    is_causal: bool,
+    enable_gqa: bool,
+) -> bool:
+    """Return whether PyTorch can run attention without a quadratic score tensor.
+
+    ``scaled_dot_product_attention`` silently falls back to its math backend when
+    a fused CUDA kernel is unavailable.  That fallback still materializes the
+    complete attention matrix, so use PyTorch's backend probes before selecting
+    SDPA.  Every probe is optional to retain compatibility with older PyTorch
+    releases and CPU-only installations.
+    """
+
+    if query.device.type != "cuda" or not hasattr(F, "scaled_dot_product_attention"):
+        return False
+    cuda_backends = getattr(torch.backends, "cuda", None)
+    params_type = getattr(cuda_backends, "SDPAParams", None)
+    if params_type is None:
+        return False
+    try:
+        params = params_type(query, key, value, None, 0.0, is_causal, enable_gqa)
+    except (RuntimeError, TypeError):
+        return False
+    for name in (
+        "can_use_flash_attention",
+        "can_use_efficient_attention",
+        "can_use_cudnn_attention",
+    ):
+        probe = getattr(cuda_backends, name, None)
+        if probe is None:
+            continue
+        try:
+            if bool(probe(params, False)):
+                return True
+        except (RuntimeError, TypeError):
+            continue
+    return False
+
+
+def _run_fused_sdpa(
+    query: torch.Tensor,
+    key: torch.Tensor,
+    value: torch.Tensor,
+    *,
+    is_causal: bool,
+    enable_gqa: bool,
+) -> torch.Tensor | None:
+    """Run fused SDPA when supported, otherwise preserve the reference route."""
+
+    if not _can_use_fused_sdpa(
+        query,
+        key,
+        value,
+        is_causal=is_causal,
+        enable_gqa=enable_gqa,
+    ):
+        return None
+    try:
+        return F.scaled_dot_product_attention(
+            query,
+            key,
+            value,
+            dropout_p=0.0,
+            is_causal=is_causal,
+            enable_gqa=enable_gqa,
+        )
+    except (NotImplementedError, TypeError):
+        return None
+    except RuntimeError as error:
+        # Do not hide a real allocation failure behind a second, larger
+        # reference allocation.  Other backend launch failures safely fall back.
+        if "out of memory" in str(error).lower():
+            raise
+        return None
+
+
+def _torch_grouped_query_attention(
+    query: torch.Tensor,
+    key: torch.Tensor,
+    value: torch.Tensor,
+    *,
+    past_length: int,
+    attention_mask: torch.Tensor | None,
+) -> torch.Tensor:
+    """Reference GQA without physically repeating key and value heads.
+
+    Combining the repetition factor with the query-length dimension turns GQA
+    into one batched matrix multiplication per native KV head.  This retains the
+    donor equation while avoiding a persistent or transient ``repeat_kv`` copy.
+    """
+
+    batch, num_heads, length, head_dim = query.shape
+    kv_heads = key.shape[1]
+    repetitions = num_heads // kv_heads
+    key_length = key.shape[-2]
+    grouped_query = query.reshape(batch * kv_heads, repetitions * length, head_dim)
+    grouped_key = key.reshape(batch * kv_heads, key_length, head_dim)
+    grouped_value = value.reshape(batch * kv_heads, key_length, head_dim)
+    scores = torch.bmm(grouped_query, grouped_key.transpose(1, 2))
+    scores = scores.reshape(batch, kv_heads, repetitions, length, key_length)
+    scores = scores * (head_dim**-0.5)
+
+    query_positions = past_length + torch.arange(length, device=scores.device)
+    key_positions = torch.arange(key_length, device=scores.device)
+    causal = key_positions.unsqueeze(0) > query_positions.unsqueeze(1)
+    scores = scores.masked_fill(causal[None, None, None], torch.finfo(scores.dtype).min)
+    if attention_mask is not None:
+        key_mask = ~attention_mask.to(device=scores.device, dtype=torch.bool)
+        scores = scores.masked_fill(
+            key_mask[:, None, None, None, :],
+            torch.finfo(scores.dtype).min,
+        )
+    probabilities = F.softmax(scores.float(), dim=-1).to(query.dtype)
+    output = torch.bmm(
+        probabilities.reshape(batch * kv_heads, repetitions * length, key_length),
+        grouped_value,
+    )
+    return output.reshape(batch, num_heads, length, head_dim)
+
+
+@dataclass(slots=True)
+class DendroTransplantOutput:
+    last_hidden_state: torch.Tensor
+    input_embeddings: torch.Tensor
+    position_ids: torch.Tensor
+    rope_deltas: torch.Tensor | None = None
+    cache: "DendroTransplantCache | None" = None
+
+
+@dataclass(slots=True)
+class DendroTransplantCache:
+    """Parameterless incremental state for the exact donor operators."""
+
+    position: int = 0
+    attention_mask: torch.Tensor | None = None
+    full_attention: dict[int, tuple[torch.Tensor, torch.Tensor]] = field(default_factory=dict)
+    linear_convolution: dict[int, torch.Tensor] = field(default_factory=dict)
+    linear_recurrent: dict[int, torch.Tensor] = field(default_factory=dict)
+
+    @property
+    def total_tokens_seen(self) -> int:
+        return int(self.position)
+
+    def get_seq_length(self, layer_idx: int = 0) -> int:
+        del layer_idx
+        return int(self.position)
+
+    def reorder(self, indices: torch.Tensor) -> "DendroTransplantCache":
+        if self.attention_mask is not None:
+            self.attention_mask = self.attention_mask.index_select(0, indices.to(self.attention_mask.device))
+        self.full_attention = {
+            layer: (
+                key.index_select(0, indices.to(key.device)),
+                value.index_select(0, indices.to(value.device)),
+            )
+            for layer, (key, value) in self.full_attention.items()
+        }
+        self.linear_convolution = {
+            layer: value.index_select(0, indices.to(value.device))
+            for layer, value in self.linear_convolution.items()
+        }
+        self.linear_recurrent = {
+            layer: value.index_select(0, indices.to(value.device))
+            for layer, value in self.linear_recurrent.items()
+        }
+        return self
+
+    def reorder_cache(self, indices: torch.Tensor) -> "DendroTransplantCache":
+        return self.reorder(indices)
+
+
+def required_transplant_tensor_names(source_config: Mapping[str, Any]) -> set[str]:
+    """Return every donor tensor required by Dendro's exact text/vision path.
+
+    This is deliberately independent of a live model or source tensor so the root
+    transplant script can reject an incomplete checkpoint *before* allocating and
+    writing the packed one-source target.  MTP tensors are preserved in the donor
+    bank when present, but are not required for ordinary causal-LM equivalence.
+    """
+
+    text_config: Mapping[str, Any] = source_config.get("text_config", source_config)
+    vision_config: Mapping[str, Any] = source_config.get("vision_config", {})
+    language_prefix = "model.language_model"
+    required: set[str] = {
+        f"{language_prefix}.embed_tokens.weight",
+        f"{language_prefix}.norm.weight",
+    }
+
+    layer_types = list(text_config.get("layer_types", []))
+    num_layers = int(text_config.get("num_hidden_layers", len(layer_types)))
+    full_attention_interval = int(text_config.get("full_attention_interval", 4))
+    attention_bias = bool(text_config.get("attention_bias", False))
+    for index in range(num_layers):
+        prefix = f"{language_prefix}.layers.{index}"
+        required.update(
+            {
+                f"{prefix}.input_layernorm.weight",
+                f"{prefix}.post_attention_layernorm.weight",
+                f"{prefix}.mlp.gate_proj.weight",
+                f"{prefix}.mlp.up_proj.weight",
+                f"{prefix}.mlp.down_proj.weight",
+            }
+        )
+        layer_type = layer_types[index] if layer_types else (
+            "full_attention" if (index + 1) % full_attention_interval == 0 else "linear_attention"
+        )
+        if layer_type == "full_attention":
+            attention = f"{prefix}.self_attn"
+            required.update(
+                {
+                    f"{attention}.q_proj.weight",
+                    f"{attention}.k_proj.weight",
+                    f"{attention}.v_proj.weight",
+                    f"{attention}.o_proj.weight",
+                    f"{attention}.q_norm.weight",
+                    f"{attention}.k_norm.weight",
+                }
+            )
+            if attention_bias:
+                required.update(
+                    {
+                        f"{attention}.q_proj.bias",
+                        f"{attention}.k_proj.bias",
+                        f"{attention}.v_proj.bias",
+                        f"{attention}.o_proj.bias",
+                    }
+                )
+        elif layer_type == "linear_attention":
+            attention = f"{prefix}.linear_attn"
+            required.update(
+                {
+                    f"{attention}.in_proj_qkv.weight",
+                    f"{attention}.in_proj_z.weight",
+                    f"{attention}.in_proj_b.weight",
+                    f"{attention}.in_proj_a.weight",
+                    f"{attention}.conv1d.weight",
+                    f"{attention}.dt_bias",
+                    f"{attention}.A_log",
+                    f"{attention}.norm.weight",
+                    f"{attention}.out_proj.weight",
+                }
+            )
+        else:
+            raise ValueError(f"unsupported Qwen3.5 donor layer type at index {index}: {layer_type!r}")
+
+    if vision_config:
+        required.update(
+            {
+                "model.visual.patch_embed.proj.weight",
+                "model.visual.patch_embed.proj.bias",
+                "model.visual.pos_embed.weight",
+                "model.visual.merger.norm.weight",
+                "model.visual.merger.norm.bias",
+                "model.visual.merger.linear_fc1.weight",
+                "model.visual.merger.linear_fc1.bias",
+                "model.visual.merger.linear_fc2.weight",
+                "model.visual.merger.linear_fc2.bias",
+            }
+        )
+        for index in range(int(vision_config.get("depth", 0))):
+            prefix = f"model.visual.blocks.{index}"
+            required.update(
+                {
+                    f"{prefix}.norm1.weight",
+                    f"{prefix}.norm1.bias",
+                    f"{prefix}.norm2.weight",
+                    f"{prefix}.norm2.bias",
+                    f"{prefix}.attn.qkv.weight",
+                    f"{prefix}.attn.qkv.bias",
+                    f"{prefix}.attn.proj.weight",
+                    f"{prefix}.attn.proj.bias",
+                    f"{prefix}.mlp.linear_fc1.weight",
+                    f"{prefix}.mlp.linear_fc1.bias",
+                    f"{prefix}.mlp.linear_fc2.weight",
+                    f"{prefix}.mlp.linear_fc2.bias",
+                }
+            )
+    return required
+
+
+def _rotate_half(x: torch.Tensor) -> torch.Tensor:
+    first, second = x.chunk(2, dim=-1)
+    return torch.cat((-second, first), dim=-1)
+
+
+def _l2norm(x: torch.Tensor, *, eps: float = 1e-6) -> torch.Tensor:
+    return x * torch.rsqrt((x * x).sum(dim=-1, keepdim=True) + eps)
+
+
+def _torch_chunk_gated_delta_rule(
+    query: torch.Tensor,
+    key: torch.Tensor,
+    value: torch.Tensor,
+    g: torch.Tensor,
+    beta: torch.Tensor,
+    *,
+    chunk_size: int = 64,
+    return_state: bool = False,
+) -> torch.Tensor | tuple[torch.Tensor, torch.Tensor]:
+    """Reference chunked gated-delta recurrence used by the transplant path."""
+
+    initial_dtype = query.dtype
+    query = _l2norm(query, eps=1e-6)
+    key = _l2norm(key, eps=1e-6)
+    query, key, value, beta, g = [
+        tensor.transpose(1, 2).contiguous().float() for tensor in (query, key, value, beta, g)
+    ]
+
+    batch_size, num_heads, sequence_length, key_dim = key.shape
+    value_dim = value.shape[-1]
+    pad_size = (chunk_size - sequence_length % chunk_size) % chunk_size
+    query = F.pad(query, (0, 0, 0, pad_size))
+    key = F.pad(key, (0, 0, 0, pad_size))
+    value = F.pad(value, (0, 0, 0, pad_size))
+    beta = F.pad(beta, (0, pad_size))
+    g = F.pad(g, (0, pad_size))
+    total_length = sequence_length + pad_size
+    query = query * (key_dim**-0.5)
+
+    value_beta = value * beta.unsqueeze(-1)
+    key_beta = key * beta.unsqueeze(-1)
+    query, key, value, key_beta, value_beta = [
+        tensor.reshape(tensor.shape[0], tensor.shape[1], -1, chunk_size, tensor.shape[-1])
+        for tensor in (query, key, value, key_beta, value_beta)
+    ]
+    g = g.reshape(g.shape[0], g.shape[1], -1, chunk_size)
+
+    upper_including_diagonal = torch.triu(
+        torch.ones(chunk_size, chunk_size, dtype=torch.bool, device=query.device), diagonal=0
+    )
+    g = g.cumsum(dim=-1)
+    decay_mask = ((g.unsqueeze(-1) - g.unsqueeze(-2)).tril().exp().float()).tril()
+    correction = -((key_beta @ key.transpose(-1, -2)) * decay_mask).masked_fill(
+        upper_including_diagonal, 0
+    )
+    for row_index in range(1, chunk_size):
+        row = correction[..., row_index, :row_index].clone()
+        previous = correction[..., :row_index, :row_index].clone()
+        correction[..., row_index, :row_index] = row + (row.unsqueeze(-1) * previous).sum(-2)
+    correction = correction + torch.eye(chunk_size, dtype=correction.dtype, device=correction.device)
+    value = correction @ value_beta
+    cumulative_key = correction @ (key_beta * g.exp().unsqueeze(-1))
+
+    recurrent = torch.zeros(
+        batch_size,
+        num_heads,
+        key_dim,
+        value_dim,
+        dtype=value.dtype,
+        device=value.device,
+    )
+    output = torch.zeros_like(value)
+    for chunk_index in range(total_length // chunk_size):
+        query_chunk = query[:, :, chunk_index]
+        key_chunk = key[:, :, chunk_index]
+        value_chunk = value[:, :, chunk_index]
+        attention = query_chunk @ key_chunk.transpose(-1, -2) * decay_mask[:, :, chunk_index]
+        predicted = cumulative_key[:, :, chunk_index] @ recurrent
+        corrected_value = value_chunk - predicted
+        recurrent_read = (query_chunk * g[:, :, chunk_index, :, None].exp()) @ recurrent
+        output[:, :, chunk_index] = recurrent_read + attention @ corrected_value
+        recurrent = (
+            recurrent * g[:, :, chunk_index, -1, None, None].exp()
+            + (
+                key_chunk
+                * (g[:, :, chunk_index, -1, None] - g[:, :, chunk_index]).exp()[..., None]
+            ).transpose(-1, -2)
+            @ corrected_value
+        )
+
+    output = output.reshape(output.shape[0], output.shape[1], -1, output.shape[-1])
+    output = output[:, :, :sequence_length]
+    converted = output.transpose(1, 2).contiguous().to(initial_dtype)
+    if return_state:
+        return converted, recurrent
+    return converted
+
+
+def _torch_recurrent_gated_delta_rule(
+    query: torch.Tensor,
+    key: torch.Tensor,
+    value: torch.Tensor,
+    g: torch.Tensor,
+    beta: torch.Tensor,
+    state: torch.Tensor,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    """Incremental form numerically aligned with the chunked reference rule with vectorized batched matmuls."""
+
+    initial_dtype = query.dtype
+    query = _l2norm(query, eps=1e-6).float()
+    key = _l2norm(key, eps=1e-6).float()
+    value = value.float()
+    state = state.float()
+    key_dim = key.shape[-1]
+    scale = float(key_dim**-0.5)
+    seq_len = query.shape[1]
+
+    if seq_len == 1:
+        # Fast path for single-token autoregressive decoding (eliminates einsum parsing and dispatch overhead)
+        g_exp = g[:, 0, :, None, None].float().exp()
+        state = state * g_exp
+        k_vec = key[:, 0].unsqueeze(-2)
+        prediction = torch.matmul(k_vec, state)
+        v_vec = value[:, 0].unsqueeze(-2)
+        b_val = beta[:, 0, :, None, None].float()
+        delta = b_val * (v_vec - prediction)
+        state = state + torch.matmul(k_vec.transpose(-1, -2), delta)
+        q_vec = (query[:, 0] * scale).unsqueeze(-2)
+        read = torch.matmul(q_vec, state)
+        output = read.squeeze(-2).unsqueeze(1).to(initial_dtype)
+        return output, state
+
+    outputs: list[torch.Tensor] = []
+    for token_index in range(seq_len):
+        g_exp = g[:, token_index, :, None, None].float().exp()
+        state = state * g_exp
+        k_vec = key[:, token_index].unsqueeze(-2)
+        prediction = torch.matmul(k_vec, state)
+        v_vec = value[:, token_index].unsqueeze(-2)
+        b_val = beta[:, token_index, :, None, None].float()
+        delta = b_val * (v_vec - prediction)
+        state = state + torch.matmul(k_vec.transpose(-1, -2), delta)
+        q_vec = (query[:, token_index] * scale).unsqueeze(-2)
+        read = torch.matmul(q_vec, state).squeeze(-2)
+        outputs.append(read)
+    return torch.stack(outputs, dim=1).to(initial_dtype), state
+
+
+class DendroExactTransplantCore(SourceBoundModule):
+    """Parameterless exact-equivalence operator path inside Dendro Omni.
+
+    The class reads every tensor from :class:`DendroSourceLayer.named_tensor`.
+    Consequently the complete donor and every Dendro extension remain one
+    registered parameter tensor.
+    """
+
+    def __init__(self, config: Any, source: DendroSourceLayer) -> None:
+        super().__init__(source)
+        source_config = dict(config.transplant_source_config or {})
+        if not source_config:
+            raise ValueError("exact transplant mode requires transplant_source_config")
+        self.config = config
+        self.source_config = source_config
+        self.text_config: Mapping[str, Any] = source_config.get("text_config", source_config)
+        self.vision_config: Mapping[str, Any] = source_config.get("vision_config", {})
+        self.image_token_id = source_config.get("image_token_id", getattr(config, "image_token_id", None))
+        self.video_token_id = source_config.get("video_token_id", getattr(config, "video_token_id", None))
+        self._required_prefix = "model.language_model"
+        self._bound_weights: dict[tuple[str, torch.dtype | None], torch.Tensor] = {}
+        self._bound_source_version: int = -1
+
+    def _sync_bound_weights(self) -> None:
+        current_version = getattr(self.source.source, "_version", 0)
+        if self._bound_source_version != current_version:
+            self._bound_weights.clear()
+            self._bound_source_version = current_version
+
+    def prebind_weights(self, device: torch.device | str | None = None, dtype: torch.dtype | None = None) -> None:
+        """Pre-cache all named tensor slices into an in-memory direct lookup table."""
+        self._sync_bound_weights()
+        target_device = device or self.source.source.device
+        runtime_dtype = dtype or self.source.source.dtype
+        for name in self.source._tensor_map:
+            t = self.source.named_tensor(name, dtype=runtime_dtype).to(device=target_device)
+            self._bound_weights[(name, runtime_dtype)] = t
+            self._bound_weights[(name, None)] = t
+
+    @property
+    def _acceleration_backend(self) -> str:
+        return str(getattr(self.config, "acceleration_backend", "auto"))
+
+    def _tensor(self, name: str, *, dtype: torch.dtype | None = None) -> torch.Tensor:
+        # Match Hugging Face's ``dtype=...`` loading semantics.  The manifest's
+        # logical dtype records how each donor tensor was stored, but execution
+        # must follow the dtype of the owning single source parameter.  Otherwise
+        # an FP32 checkpoint silently runs its BF16 donor views in BF16, producing
+        # accumulating text drift and much larger vision drift.  Callers may still
+        # request FP32 explicitly for numerically sensitive state such as A_log.
+        self._sync_bound_weights()
+        runtime_dtype = self.source.source.dtype if dtype is None else dtype
+        key = (name, runtime_dtype)
+        cached = self._bound_weights.get(key)
+        if cached is not None:
+            return cached
+        tensor = self.source.named_tensor(name, dtype=runtime_dtype)
+        self._bound_weights[key] = tensor
+        return tensor
+
+    def _linear(
+        self,
+        x: torch.Tensor,
+        weight_name: str,
+        bias_name: str | None = None,
+    ) -> torch.Tensor:
+        weight = self._tensor(weight_name, dtype=x.dtype).to(device=x.device)
+        bias = None
+        if bias_name is not None and self.source.has_named_tensor(bias_name):
+            bias = self._tensor(bias_name, dtype=x.dtype).to(device=x.device)
+        return F.linear(x, weight, bias)
+
+    def _qwen_rms_norm(self, x: torch.Tensor, weight_name: str) -> torch.Tensor:
+        eps = float(self.text_config.get("rms_norm_eps", 1e-6))
+        weight = self._tensor(weight_name, dtype=torch.float32).to(x.device)
+        normalized = x.float() * torch.rsqrt(x.float().pow(2).mean(-1, keepdim=True) + eps)
+        return (normalized * (1.0 + weight.float())).to(x.dtype)
+
+    def _qwen_gated_rms_norm(
+        self,
+        x: torch.Tensor,
+        gate: torch.Tensor,
+        weight_name: str,
+    ) -> torch.Tensor:
+        eps = float(self.text_config.get("rms_norm_eps", 1e-6))
+        weight = self._tensor(weight_name).to(device=x.device, dtype=x.dtype)
+        normalized = x.float() * torch.rsqrt(x.float().pow(2).mean(-1, keepdim=True) + eps)
+        output = weight * normalized.to(x.dtype)
+        return (output.float() * F.silu(gate.float())).to(x.dtype)
+
+    @staticmethod
+    def _layer_norm(
+        x: torch.Tensor,
+        weight: torch.Tensor,
+        bias: torch.Tensor,
+        eps: float = 1e-6,
+    ) -> torch.Tensor:
+        return F.layer_norm(
+            x,
+            (x.shape[-1],),
+            weight.to(device=x.device, dtype=x.dtype),
+            bias.to(device=x.device, dtype=x.dtype),
+            eps,
+        )
+
+    def token_embedding(self, input_ids: torch.Tensor) -> torch.Tensor:
+        table = self._tensor(f"{self._required_prefix}.embed_tokens.weight")
+        return F.embedding(input_ids, table.to(input_ids.device))
+
+    def tied_logits(self, hidden_states: torch.Tensor) -> torch.Tensor:
+        table = self._tensor(f"{self._required_prefix}.embed_tokens.weight")
+        return F.linear(hidden_states, table.to(device=hidden_states.device, dtype=hidden_states.dtype))
+
+    def _text_position_embeddings(
+        self,
+        hidden_states: torch.Tensor,
+        position_ids: torch.Tensor,
+    ) -> tuple[torch.Tensor, torch.Tensor]:
+        if position_ids.ndim == 2:
+            position_ids = position_ids[None, ...].expand(3, position_ids.shape[0], -1)
+        elif position_ids.ndim == 3 and position_ids.shape[0] == 4:
+            position_ids = position_ids[1:]
+        if position_ids.ndim != 3 or position_ids.shape[0] != 3:
+            raise ValueError("transplant position_ids must be [batch, seq], [3,batch,seq], or [4,batch,seq]")
+
+        head_dim = int(self.text_config.get("head_dim", 256))
+        rope = dict(self.text_config.get("rope_parameters", {}))
+        rotary_dim = int(head_dim * float(rope.get("partial_rotary_factor", 1.0)))
+        theta = float(rope.get("rope_theta", 10_000.0))
+        inv_freq = 1.0 / (
+            theta
+            ** (
+                torch.arange(0, rotary_dim, 2, device=hidden_states.device, dtype=torch.float32)
+                / rotary_dim
+            )
+        )
+        frequencies = position_ids.to(device=hidden_states.device, dtype=torch.float32).unsqueeze(-1) * inv_freq
+        mixed = frequencies[0].clone()
+        sections = list(rope.get("mrope_section", [11, 11, 10]))
+        for axis, offset in ((1, 1), (2, 2)):
+            length = int(sections[axis]) * 3
+            mixed[..., slice(offset, length, 3)] = frequencies[axis, ..., slice(offset, length, 3)]
+        embedding = torch.cat((mixed, mixed), dim=-1)
+        return embedding.cos().to(hidden_states.dtype), embedding.sin().to(hidden_states.dtype)
+
+    @staticmethod
+    def _apply_text_rope(
+        query: torch.Tensor,
+        key: torch.Tensor,
+        cos: torch.Tensor,
+        sin: torch.Tensor,
+    ) -> tuple[torch.Tensor, torch.Tensor]:
+        cos = cos.unsqueeze(1)
+        sin = sin.unsqueeze(1)
+        rotary_dim = cos.shape[-1]
+        query_rotary, query_pass = query[..., :rotary_dim], query[..., rotary_dim:]
+        key_rotary, key_pass = key[..., :rotary_dim], key[..., rotary_dim:]
+        query_rotary = query_rotary * cos + _rotate_half(query_rotary) * sin
+        key_rotary = key_rotary * cos + _rotate_half(key_rotary) * sin
+        return torch.cat((query_rotary, query_pass), -1), torch.cat((key_rotary, key_pass), -1)
+
+    @staticmethod
+    def _repeat_kv(x: torch.Tensor, repetitions: int) -> torch.Tensor:
+        if repetitions == 1:
+            return x
+        batch, heads, length, dim = x.shape
+        return x[:, :, None, :, :].expand(batch, heads, repetitions, length, dim).reshape(
+            batch, heads * repetitions, length, dim
+        )
+
+    def _full_attention(
+        self,
+        hidden_states: torch.Tensor,
+        layer_index: int,
+        position_embeddings: tuple[torch.Tensor, torch.Tensor],
+        attention_mask: torch.Tensor | None,
+        cache: DendroTransplantCache | None = None,
+        use_cache: bool = False,
+    ) -> torch.Tensor:
+        prefix = f"{self._required_prefix}.layers.{layer_index}.self_attn"
+        batch, length, _ = hidden_states.shape
+        num_heads = int(self.text_config.get("num_attention_heads", 8))
+        kv_heads = int(self.text_config.get("num_key_value_heads", num_heads))
+        head_dim = int(self.text_config.get("head_dim", hidden_states.shape[-1] // num_heads))
+
+        mixed_query = self._linear(
+            hidden_states, f"{prefix}.q_proj.weight", f"{prefix}.q_proj.bias"
+        )
+        mixed_query = mixed_query.view(batch, length, num_heads, head_dim * 2)
+        query, gate = mixed_query.chunk(2, dim=-1)
+        query = self._qwen_rms_norm(query, f"{prefix}.q_norm.weight").transpose(1, 2)
+        key = self._linear(
+            hidden_states, f"{prefix}.k_proj.weight", f"{prefix}.k_proj.bias"
+        ).view(
+            batch, length, kv_heads, head_dim
+        )
+        key = self._qwen_rms_norm(key, f"{prefix}.k_norm.weight").transpose(1, 2)
+        value = self._linear(
+            hidden_states, f"{prefix}.v_proj.weight", f"{prefix}.v_proj.bias"
+        ).view(
+            batch, length, kv_heads, head_dim
+        ).transpose(1, 2)
+        query, key = self._apply_text_rope(query, key, *position_embeddings)
+        repetitions = num_heads // kv_heads
+
+        past_length = 0
+        if cache is not None and layer_index in cache.full_attention:
+            past_key, past_value = cache.full_attention[layer_index]
+            past_key = past_key.to(device=key.device, dtype=key.dtype)
+            past_value = past_value.to(device=value.device, dtype=value.dtype)
+            past_length = past_key.shape[-2]
+            key = torch.cat([past_key, key], dim=-2)
+            value = torch.cat([past_value, value], dim=-2)
+        if use_cache and cache is not None:
+            attention_window = int(getattr(self.config, "transplant_attention_window", 8192))
+            cache.full_attention[layer_index] = (
+                key[:, :, -attention_window:].detach(),
+                value[:, :, -attention_window:].detach(),
+            )
+
+        # Long prefills can use a fused CUDA kernel without an offset mask.  Tiny
+        # prefills and incremental decode remain faster on the grouped reference
+        # operation because kernel selection and transient expansion dominate at
+        # those sizes.  The persistent GQA cache always remains compact.
+        fused_output = None
+        # BF16/FP16 fused reductions can move logits enough to alter borderline
+        # greedy decisions.  Keep reduced-precision inference on the compact,
+        # donor-equivalent BMM path; FP32 stays within strict equivalence bounds.
+        can_use_exact_inference_fused_prefill = (
+            query.dtype == torch.float32
+            and attention_mask is None
+            and past_length == 0
+            and length >= 64
+        )
+        # Training explicitly opts into fused reduced-precision attention.  This
+        # is safe for optimization (where small reduction-order differences are
+        # expected) and avoids materializing B*H*T*T scores for long examples.
+        # Inference remains on the donor-equivalent BF16 reference path.  A mask
+        # containing padding falls back because combining padding and causality
+        # is backend/version sensitive; the audited batch-1 curriculum is fully
+        # visible and therefore qualifies.
+        training_all_visible = attention_mask is None
+        if (
+            self.training
+            and bool(getattr(self.config, "transplant_training_fused_attention", False))
+            and attention_mask is not None
+            and attention_mask.ndim == 2
+            and tuple(attention_mask.shape) == (batch, key.shape[-2])
+        ):
+            training_all_visible = bool(
+                attention_mask.to(device=query.device, dtype=torch.bool).all().item()
+            )
+        can_use_training_fused_prefill = (
+            self.training
+            and bool(getattr(self.config, "transplant_training_fused_attention", False))
+            and training_all_visible
+            and past_length == 0
+            and length >= 64
+        )
+        if (
+            (not self.training and can_use_exact_inference_fused_prefill)
+            or can_use_training_fused_prefill
+        ):
+            fused_output = _run_fused_sdpa(
+                query,
+                key,
+                value,
+                is_causal=True,
+                enable_gqa=repetitions > 1,
+            )
+            if fused_output is None and repetitions > 1:
+                expanded_key = self._repeat_kv(key, repetitions)
+                expanded_value = self._repeat_kv(value, repetitions)
+                fused_output = _run_fused_sdpa(
+                    query,
+                    expanded_key,
+                    expanded_value,
+                    is_causal=True,
+                    enable_gqa=False,
+                )
+        if fused_output is not None:
+            output = fused_output.transpose(1, 2).contiguous()
+            output = output.reshape(batch, length, num_heads * head_dim)
+            output = output * torch.sigmoid(gate.reshape(batch, length, num_heads * head_dim))
+            return self._linear(output, f"{prefix}.o_proj.weight", f"{prefix}.o_proj.bias")
+
+        # Preserve the donor's exact reduced-precision arithmetic order.  K/V
+        # stay compact in the persistent cache, but are expanded transiently for
+        # the reference matmuls.  A grouped BMM is faster in isolation yet can
+        # round borderline BF16 logits differently over long autoregressive runs.
+        attention_key = self._repeat_kv(key, repetitions)
+        attention_value = self._repeat_kv(value, repetitions)
+        scores = torch.matmul(query, attention_key.transpose(-1, -2)) * (head_dim**-0.5)
+        query_positions = past_length + torch.arange(length, device=scores.device)
+        key_positions = torch.arange(attention_key.shape[-2], device=scores.device)
+        causal = key_positions.unsqueeze(0) > query_positions.unsqueeze(1)
+        scores = scores.masked_fill(causal[None, None], torch.finfo(scores.dtype).min)
+        if attention_mask is not None:
+            key_mask = ~attention_mask.to(device=scores.device, dtype=torch.bool)
+            scores = scores.masked_fill(
+                key_mask[:, None, None, :],
+                torch.finfo(scores.dtype).min,
+            )
+        probabilities = F.softmax(scores.float(), dim=-1).to(query.dtype)
+        output = torch.matmul(probabilities, attention_value).transpose(1, 2).contiguous()
+        output = output.reshape(batch, length, num_heads * head_dim)
+        output = output * torch.sigmoid(gate.reshape(batch, length, num_heads * head_dim))
+        return self._linear(output, f"{prefix}.o_proj.weight", f"{prefix}.o_proj.bias")
+
+    def _linear_attention(
+        self,
+        hidden_states: torch.Tensor,
+        layer_index: int,
+        attention_mask: torch.Tensor | None,
+        cache: DendroTransplantCache | None = None,
+        use_cache: bool = False,
+    ) -> torch.Tensor:
+        prefix = f"{self._required_prefix}.layers.{layer_index}.linear_attn"
+        if attention_mask is not None and hidden_states.shape[0] > 1 and hidden_states.shape[1] > 1:
+            hidden_states = hidden_states * attention_mask[:, :, None].to(hidden_states.dtype)
+
+        batch, length, _ = hidden_states.shape
+        key_heads = int(self.text_config.get("linear_num_key_heads", 16))
+        value_heads = int(self.text_config.get("linear_num_value_heads", 16))
+        key_head_dim = int(self.text_config.get("linear_key_head_dim", 128))
+        value_head_dim = int(self.text_config.get("linear_value_head_dim", 128))
+        key_dim = key_heads * key_head_dim
+        value_dim = value_heads * value_head_dim
+
+        raw_mixed = self._linear(hidden_states, f"{prefix}.in_proj_qkv.weight").transpose(1, 2)
+        convolution_weight = self._tensor(f"{prefix}.conv1d.weight").to(
+            device=raw_mixed.device, dtype=raw_mixed.dtype
+        )
+        if convolution_weight.ndim == 2:
+            convolution_weight = convolution_weight.unsqueeze(1)
+        kernel = convolution_weight.shape[-1]
+        if cache is not None and layer_index in cache.linear_convolution:
+            history = cache.linear_convolution[layer_index].to(
+                device=raw_mixed.device, dtype=raw_mixed.dtype
+            )
+        else:
+            history = F.pad(raw_mixed[:, :, :0], (max(0, kernel - 1), 0))
+        update_state: torch.Tensor | None = None
+        accelerated_update = None
+        if length == 1 and cache is not None and layer_index in cache.linear_convolution:
+            update_state = history
+            if update_state.shape[-1] == kernel - 1:
+                update_state = F.pad(update_state, (1, 0))
+            accelerated_update = fla_causal_conv1d_update(
+                raw_mixed.transpose(1, 2).contiguous(),
+                update_state.contiguous(),
+                convolution_weight.squeeze(1),
+                activation="silu",
+                configured=self._acceleration_backend,
+            )
+        if accelerated_update is not None:
+            mixed, update_state = accelerated_update
+            convolution_input = update_state
+        else:
+            history_for_convolution = history[..., -(kernel - 1):]
+            convolution_input = torch.cat([history_for_convolution, raw_mixed], dim=-1)
+            accelerated_mixed = fla_causal_conv1d(
+                convolution_input.transpose(1, 2).contiguous(),
+                convolution_weight.squeeze(1),
+                activation="silu",
+                configured=self._acceleration_backend,
+            )
+            if accelerated_mixed is None:
+                mixed = F.silu(F.conv1d(
+                    convolution_input,
+                    convolution_weight,
+                    bias=None,
+                    padding=0,
+                    groups=convolution_weight.shape[0],
+                )[:, :, :length]).transpose(1, 2)
+            else:
+                mixed = accelerated_mixed[:, -length:]
+        if use_cache and cache is not None:
+            history_length = max(0, kernel)
+            cache.linear_convolution[layer_index] = (
+                convolution_input[:, :, -history_length:].detach()
+                if history_length
+                else convolution_input[:, :, :0].detach()
+            )
+        query, key, value = torch.split(mixed, [key_dim, key_dim, value_dim], dim=-1)
+        query = query.view(batch, length, key_heads, key_head_dim)
+        key = key.view(batch, length, key_heads, key_head_dim)
+        value = value.view(batch, length, value_heads, value_head_dim)
+
+        z = self._linear(hidden_states, f"{prefix}.in_proj_z.weight").view(
+            batch, length, value_heads, value_head_dim
+        )
+        beta = torch.sigmoid(self._linear(hidden_states, f"{prefix}.in_proj_b.weight"))
+        a = self._linear(hidden_states, f"{prefix}.in_proj_a.weight")
+        a_log = self._tensor(f"{prefix}.A_log", dtype=torch.float32).to(hidden_states.device)
+        dt_bias = self._tensor(f"{prefix}.dt_bias", dtype=torch.float32).to(hidden_states.device)
+        g = -a_log.float().exp() * F.softplus(a.float() + dt_bias)
+
+        if value_heads // key_heads > 1:
+            repetitions = value_heads // key_heads
+            query = query.repeat_interleave(repetitions, dim=2)
+            key = key.repeat_interleave(repetitions, dim=2)
+        recurrent = None if cache is None else cache.linear_recurrent.get(layer_index)
+        if recurrent is None:
+            result = fla_chunk_gated_delta_rule(
+                query,
+                key,
+                value,
+                g,
+                beta,
+                return_state=use_cache,
+                configured=self._acceleration_backend,
+            )
+            if result is None:
+                result = _torch_chunk_gated_delta_rule(
+                    query,
+                    key,
+                    value,
+                    g,
+                    beta,
+                    return_state=use_cache,
+                )
+            if use_cache:
+                assert isinstance(result, tuple)
+                output, recurrent = result
+            else:
+                assert torch.is_tensor(result)
+                output = result
+        else:
+            accelerated = fla_recurrent_gated_delta_rule(
+                query,
+                key,
+                value,
+                g,
+                beta,
+                recurrent.to(query.device),
+                configured=self._acceleration_backend,
+            )
+            if accelerated is None:
+                output, recurrent = _torch_recurrent_gated_delta_rule(
+                    query,
+                    key,
+                    value,
+                    g,
+                    beta,
+                    recurrent.to(query.device),
+                )
+            else:
+                output, recurrent = accelerated
+        if use_cache and cache is not None and recurrent is not None:
+            cache.linear_recurrent[layer_index] = recurrent.detach()
+        output = output.reshape(-1, value_head_dim)
+        z = z.reshape(-1, value_head_dim)
+        output = self._qwen_gated_rms_norm(output, z, f"{prefix}.norm.weight")
+        output = output.reshape(batch, length, value_dim)
+        return self._linear(output, f"{prefix}.out_proj.weight")
+
+    def _mlp(self, hidden_states: torch.Tensor, layer_index: int) -> torch.Tensor:
+        prefix = f"{self._required_prefix}.layers.{layer_index}.mlp"
+        gate = F.silu(self._linear(hidden_states, f"{prefix}.gate_proj.weight"))
+        value = self._linear(hidden_states, f"{prefix}.up_proj.weight")
+        return self._linear(gate * value, f"{prefix}.down_proj.weight")
+
+    def text_forward(
+        self,
+        *,
+        input_ids: torch.Tensor | None = None,
+        inputs_embeds: torch.Tensor | None = None,
+        attention_mask: torch.Tensor | None = None,
+        position_ids: torch.Tensor | None = None,
+        cache: DendroTransplantCache | None = None,
+        use_cache: bool = False,
+    ) -> DendroTransplantOutput:
+        if (input_ids is None) == (inputs_embeds is None):
+            raise ValueError("provide exactly one of input_ids or inputs_embeds")
+        if inputs_embeds is None:
+            assert input_ids is not None
+            inputs_embeds = self.token_embedding(input_ids)
+        batch, length, _ = inputs_embeds.shape
+        if use_cache and cache is None:
+            cache = DendroTransplantCache()
+        supplied_attention_mask = attention_mask
+        current_mask = (
+            torch.ones(batch, length, device=inputs_embeds.device, dtype=torch.long)
+            if attention_mask is None
+            else attention_mask.to(device=inputs_embeds.device)
+        )
+        if current_mask.shape[-1] != length:
+            current_mask = current_mask[:, -length:]
+        past_mask = None if cache is None else cache.attention_mask
+        # ``None`` is the compact representation of an all-visible mask.  During
+        # evaluation, collapse explicit all-one masks once per forward so every
+        # full-attention layer can use maskless fused SDPA.  Training stays on the
+        # established reference mask path and incurs no synchronization.
+        current_all_visible = supplied_attention_mask is None
+        if not self.training and not current_all_visible:
+            current_all_visible = bool(torch.all(current_mask).item())
+        if past_mask is None and current_all_visible:
+            attention_mask = None
+        else:
+            if past_mask is None:
+                attention_window = int(getattr(self.config, "transplant_attention_window", 8192))
+                past_length = 0 if cache is None else min(int(cache.position), attention_window)
+                past_mask = torch.ones(
+                    batch,
+                    past_length,
+                    device=current_mask.device,
+                    dtype=current_mask.dtype,
+                )
+            attention_mask = torch.cat([past_mask.to(current_mask.device), current_mask], dim=-1)
+        if position_ids is None:
+            start = 0 if cache is None else int(cache.position)
+            positions = torch.arange(start, start + length, device=inputs_embeds.device, dtype=torch.long)
+            position_ids = positions.view(1, 1, -1).expand(4, batch, -1)
+        elif position_ids.ndim == 2:
+            position_ids = position_ids[None].expand(4, -1, -1)
+        position_embeddings = self._text_position_embeddings(inputs_embeds, position_ids)
+
+        hidden_states = inputs_embeds
+        layer_types = list(self.text_config.get("layer_types", []))
+        num_layers = int(self.text_config.get("num_hidden_layers", len(layer_types)))
+        if not layer_types:
+            interval = int(self.text_config.get("full_attention_interval", 4))
+            layer_types = [
+                "full_attention" if (index + 1) % interval == 0 else "linear_attention"
+                for index in range(num_layers)
+            ]
+        for layer_index in range(num_layers):
+            prefix = f"{self._required_prefix}.layers.{layer_index}"
+            residual = hidden_states
+            normalized = self._qwen_rms_norm(hidden_states, f"{prefix}.input_layernorm.weight")
+            if layer_types[layer_index] == "full_attention":
+                mixed = self._full_attention(
+                    normalized,
+                    layer_index,
+                    position_embeddings,
+                    attention_mask,
+                    cache=cache,
+                    use_cache=use_cache,
+                )
+            else:
+                mixed = self._linear_attention(
+                    normalized,
+                    layer_index,
+                    current_mask,
+                    cache=cache,
+                    use_cache=use_cache,
+                )
+            hidden_states = residual + mixed
+            residual = hidden_states
+            normalized = self._qwen_rms_norm(hidden_states, f"{prefix}.post_attention_layernorm.weight")
+            hidden_states = residual + self._mlp(normalized, layer_index)
+        hidden_states = self._qwen_rms_norm(hidden_states, f"{self._required_prefix}.norm.weight")
+        if use_cache:
+            assert cache is not None
+            cache.position += length
+            attention_window = int(getattr(self.config, "transplant_attention_window", 8192))
+            cache.attention_mask = (
+                None
+                if attention_mask is None
+                else attention_mask[:, -attention_window:].detach()
+            )
+        return DendroTransplantOutput(
+            last_hidden_state=hidden_states,
+            input_embeddings=inputs_embeds,
+            position_ids=position_ids,
+            cache=cache,
+        )
+
+    # ------------------------------- Vision ---------------------------------
+    @staticmethod
+    def _vision_cu_seqlens(grid_thw: torch.Tensor) -> torch.Tensor:
+        lengths = torch.repeat_interleave(grid_thw[:, 1] * grid_thw[:, 2], grid_thw[:, 0])
+        return F.pad(lengths.cumsum(0, dtype=torch.int32), (1, 0), value=0)
+
+    @staticmethod
+    def _vision_position_ids(grid_thw: torch.Tensor, merge_size: int) -> torch.Tensor:
+        positions: list[torch.Tensor] = []
+        for temporal, height, width in grid_thw.tolist():
+            h_grid, w_grid = torch.meshgrid(
+                torch.arange(height, device=grid_thw.device),
+                torch.arange(width, device=grid_thw.device),
+                indexing="ij",
+            )
+            shape = (height // merge_size, merge_size, width // merge_size, merge_size)
+            h_grid = h_grid.reshape(shape).transpose(1, 2).flatten()
+            w_grid = w_grid.reshape(shape).transpose(1, 2).flatten()
+            positions.append(torch.stack((h_grid, w_grid), dim=-1).repeat(temporal, 1))
+        return torch.cat(positions, dim=0)
+
+    @staticmethod
+    def _vision_bilinear_indices(
+        grid_thw: torch.Tensor,
+        side: int,
+        merge_size: int,
+    ) -> tuple[torch.Tensor, torch.Tensor]:
+        index_parts: list[list[torch.Tensor]] = [[] for _ in range(4)]
+        weight_parts: list[list[torch.Tensor]] = [[] for _ in range(4)]
+        device = grid_thw.device
+        for temporal, height, width in grid_thw.tolist():
+            h_grid = torch.linspace(0, side - 1, height, device=device)
+            w_grid = torch.linspace(0, side - 1, width, device=device)
+            h_floor, w_floor = h_grid.int(), w_grid.int()
+            h_ceil = (h_floor + 1).clamp(max=side - 1)
+            w_ceil = (w_floor + 1).clamp(max=side - 1)
+            h_frac, w_frac = h_grid - h_floor, w_grid - w_floor
+            h_floor_offset, h_ceil_offset = h_floor * side, h_ceil * side
+            corners = [
+                (h_floor_offset[:, None] + w_floor[None, :]).flatten(),
+                (h_floor_offset[:, None] + w_ceil[None, :]).flatten(),
+                (h_ceil_offset[:, None] + w_floor[None, :]).flatten(),
+                (h_ceil_offset[:, None] + w_ceil[None, :]).flatten(),
+            ]
+            weights = [
+                ((1 - h_frac)[:, None] * (1 - w_frac)[None, :]).flatten(),
+                ((1 - h_frac)[:, None] * w_frac[None, :]).flatten(),
+                (h_frac[:, None] * (1 - w_frac)[None, :]).flatten(),
+                (h_frac[:, None] * w_frac[None, :]).flatten(),
+            ]
+            h_index = torch.arange(height, device=device).view(height // merge_size, merge_size)
+            w_index = torch.arange(width, device=device).view(width // merge_size, merge_size)
+            reorder = (
+                (h_index[:, :, None, None] * width + w_index[None, None, :, :])
+                .transpose(1, 2)
+                .flatten()
+                .repeat(temporal)
+            )
+            for corner in range(4):
+                index_parts[corner].append(corners[corner][reorder])
+                weight_parts[corner].append(weights[corner][reorder])
+        return (
+            torch.stack([torch.cat(part) for part in index_parts]),
+            torch.stack([torch.cat(part) for part in weight_parts]),
+        )
+
+    @staticmethod
+    def _vision_rope(
+        query: torch.Tensor,
+        key: torch.Tensor,
+        cos: torch.Tensor,
+        sin: torch.Tensor,
+    ) -> tuple[torch.Tensor, torch.Tensor]:
+        query_dtype, key_dtype = query.dtype, key.dtype
+        cos = cos.unsqueeze(-2).float()
+        sin = sin.unsqueeze(-2).float()
+        query = query.float() * cos + _rotate_half(query.float()) * sin
+        key = key.float() * cos + _rotate_half(key.float()) * sin
+        return query.to(query_dtype), key.to(key_dtype)
+
+    def _vision_attention(
+        self,
+        hidden_states: torch.Tensor,
+        layer_index: int,
+        cu_seqlens: torch.Tensor,
+        position_embeddings: tuple[torch.Tensor, torch.Tensor],
+    ) -> torch.Tensor:
+        prefix = f"model.visual.blocks.{layer_index}.attn"
+        sequence_length = hidden_states.shape[0]
+        num_heads = int(self.vision_config.get("num_heads", 12))
+        hidden_size = int(self.vision_config.get("hidden_size", hidden_states.shape[-1]))
+        head_dim = hidden_size // num_heads
+        qkv = self._linear(
+            hidden_states,
+            f"{prefix}.qkv.weight",
+            f"{prefix}.qkv.bias",
+        )
+        query, key, value = qkv.reshape(sequence_length, 3, num_heads, head_dim).permute(1, 0, 2, 3).unbind(0)
+        query, key = self._vision_rope(query, key, *position_embeddings)
+        outputs: list[torch.Tensor] = []
+        for start_tensor, end_tensor in zip(cu_seqlens[:-1], cu_seqlens[1:]):
+            start, end = int(start_tensor.item()), int(end_tensor.item())
+            q = query[start:end].transpose(0, 1)
+            k = key[start:end].transpose(0, 1)
+            v = value[start:end].transpose(0, 1)
+            scores = torch.matmul(q, k.transpose(-1, -2)) * (head_dim**-0.5)
+            probabilities = F.softmax(scores.float(), dim=-1).to(q.dtype)
+            outputs.append(torch.matmul(probabilities, v).transpose(0, 1))
+        output = torch.cat(outputs, dim=0).reshape(sequence_length, hidden_size)
+        return self._linear(output, f"{prefix}.proj.weight", f"{prefix}.proj.bias")
+
+    def vision_forward(
+        self,
+        pixel_values: torch.Tensor,
+        grid_thw: torch.Tensor,
+        *,
+        return_intermediates: bool = False,
+        checkpoint_layers: bool = False,
+    ) -> torch.Tensor | tuple[torch.Tensor, tuple[torch.Tensor, ...]]:
+        if not self.vision_config:
+            raise RuntimeError("transplant checkpoint has no vision configuration")
+        hidden_size = int(self.vision_config.get("hidden_size", 768))
+        patch_size = int(self.vision_config.get("patch_size", 16))
+        temporal_patch = int(self.vision_config.get("temporal_patch_size", 2))
+        channels = int(self.vision_config.get("in_channels", 3))
+        merge_size = int(self.vision_config.get("spatial_merge_size", 2))
+        depth = int(self.vision_config.get("depth", 12))
+
+        patch_weight = self._tensor("model.visual.patch_embed.proj.weight")
+        patch_bias = self._tensor("model.visual.patch_embed.proj.bias")
+        patches = pixel_values.view(-1, channels, temporal_patch, patch_size, patch_size)
+        hidden_states = F.conv3d(
+            patches.to(device=patch_weight.device, dtype=patch_weight.dtype),
+            patch_weight,
+            patch_bias,
+            stride=(temporal_patch, patch_size, patch_size),
+        ).view(-1, hidden_size)
+
+        num_positions = int(self.vision_config.get("num_position_embeddings", 2304))
+        side = int(math.sqrt(num_positions))
+        indices, weights = self._vision_bilinear_indices(grid_thw.to(hidden_states.device), side, merge_size)
+        position_table = self._tensor("model.visual.pos_embed.weight").to(hidden_states.device)
+        position_embedding = (position_table[indices] * weights[:, :, None].to(position_table.dtype)).sum(0)
+        hidden_states = hidden_states + position_embedding.to(hidden_states.dtype)
+
+        position_ids = self._vision_position_ids(grid_thw.to(hidden_states.device), merge_size)
+        head_dim = hidden_size // int(self.vision_config.get("num_heads", 12))
+        rotary_dim = head_dim // 2
+        inv_freq = 1.0 / (
+            10_000.0
+            ** (
+                torch.arange(0, rotary_dim, 2, device=hidden_states.device, dtype=torch.float32)
+                / rotary_dim
+            )
+        )
+        rotary = (position_ids.float().unsqueeze(-1) * inv_freq).flatten(1)
+        rotary = torch.cat((rotary, rotary), dim=-1)
+        position_embeddings = (rotary.cos().to(hidden_states.dtype), rotary.sin().to(hidden_states.dtype))
+        cu_seqlens = self._vision_cu_seqlens(grid_thw.to(hidden_states.device))
+
+        intermediates: list[torch.Tensor] = []
+        capture_layers = {max(0, round((depth - 1) * fraction)) for fraction in (0.25, 0.5, 0.75, 1.0)}
+        for layer_index in range(depth):
+            def vision_block(
+                states: torch.Tensor, current_layer: int = layer_index
+            ) -> torch.Tensor:
+                prefix = f"model.visual.blocks.{current_layer}"
+                norm1 = self._layer_norm(
+                    states,
+                    self._tensor(f"{prefix}.norm1.weight"),
+                    self._tensor(f"{prefix}.norm1.bias"),
+                )
+                states = states + self._vision_attention(
+                    norm1, current_layer, cu_seqlens, position_embeddings
+                )
+                norm2 = self._layer_norm(
+                    states,
+                    self._tensor(f"{prefix}.norm2.weight"),
+                    self._tensor(f"{prefix}.norm2.bias"),
+                )
+                mlp = self._linear(
+                    norm2,
+                    f"{prefix}.mlp.linear_fc1.weight",
+                    f"{prefix}.mlp.linear_fc1.bias",
+                )
+                activation_name = str(self.vision_config.get("hidden_act", "gelu")).lower()
+                if activation_name == "gelu_pytorch_tanh":
+                    mlp = F.gelu(mlp, approximate="tanh")
+                elif activation_name in {"gelu", "gelu_pytorch"}:
+                    mlp = F.gelu(mlp)
+                else:
+                    raise ValueError(
+                        f"unsupported Qwen3.5 vision activation for exact transplant: {activation_name!r}"
+                    )
+                mlp = self._linear(
+                    mlp,
+                    f"{prefix}.mlp.linear_fc2.weight",
+                    f"{prefix}.mlp.linear_fc2.bias",
+                )
+                return states + mlp
+
+            hidden_states = (
+                checkpoint(vision_block, hidden_states, use_reentrant=False)
+                if checkpoint_layers and torch.is_grad_enabled()
+                else vision_block(hidden_states)
+            )
+            if return_intermediates and layer_index in capture_layers:
+                intermediates.append(hidden_states)
+
+        merger_prefix = "model.visual.merger"
+        normalized = self._layer_norm(
+            hidden_states,
+            self._tensor(f"{merger_prefix}.norm.weight"),
+            self._tensor(f"{merger_prefix}.norm.bias"),
+        )
+        merger_hidden = hidden_size * merge_size * merge_size
+        normalized = normalized.view(-1, merger_hidden)
+        merged = self._linear(
+            normalized,
+            f"{merger_prefix}.linear_fc1.weight",
+            f"{merger_prefix}.linear_fc1.bias",
+        )
+        merged = F.gelu(merged)
+        output = self._linear(
+            merged,
+            f"{merger_prefix}.linear_fc2.weight",
+            f"{merger_prefix}.linear_fc2.bias",
+        )
+        if return_intermediates:
+            return output, tuple(intermediates)
+        return output
+
+    def _get_vision_position_ids(
+        self,
+        start_position: int,
+        grid_thw: torch.Tensor,
+        spatial_merge_size: int,
+        device: torch.device,
+    ) -> torch.Tensor:
+        temporal = int(grid_thw[0].item())
+        height = int(grid_thw[1].item()) // spatial_merge_size
+        width = int(grid_thw[2].item()) // spatial_merge_size
+        temporal_positions = torch.arange(temporal, device=device)
+        height_positions = torch.arange(height, device=device) + start_position
+        width_positions = torch.arange(width, device=device) + start_position
+        temporal_grid, height_grid, width_grid = torch.meshgrid(
+            temporal_positions, height_positions, width_positions, indexing="ij"
+        )
+        positions = torch.stack((temporal_grid, height_grid, width_grid), dim=0).reshape(3, -1)
+        positions[0] += start_position
+        return positions
+
+    def get_rope_index(
+        self,
+        input_ids: torch.Tensor,
+        mm_token_type_ids: torch.Tensor,
+        *,
+        image_grid_thw: torch.Tensor | None,
+        video_grid_thw: torch.Tensor | None,
+        attention_mask: torch.Tensor | None,
+    ) -> tuple[torch.Tensor, torch.Tensor]:
+        if video_grid_thw is not None:
+            video_grid_thw = torch.repeat_interleave(video_grid_thw, video_grid_thw[:, 0], dim=0).clone()
+            video_grid_thw[:, 0] = 1
+        merge_size = int(self.vision_config.get("spatial_merge_size", 2))
+        positions = torch.zeros(
+            3,
+            input_ids.shape[0],
+            input_ids.shape[1],
+            dtype=input_ids.dtype,
+            device=input_ids.device,
+        )
+        image_iterator = iter(image_grid_thw) if image_grid_thw is not None else None
+        video_iterator = iter(video_grid_thw) if video_grid_thw is not None else None
+        deltas: list[torch.Tensor] = []
+        for batch_index, current_ids in enumerate(input_ids):
+            token_types = mm_token_type_ids[batch_index]
+            active = None
+            if attention_mask is not None:
+                active = attention_mask[batch_index].bool()
+                current_ids = current_ids[active]
+                token_types = token_types[active]
+            groups: list[tuple[int, int, int]] = []
+            for modality, group in itertools.groupby(enumerate(token_types.tolist()), lambda item: item[1]):
+                values = list(group)
+                groups.append((int(modality), values[0][0], values[-1][0] + 1))
+            current_position = 0
+            parts: list[torch.Tensor] = []
+            for modality, start, end in groups:
+                if modality == 0:
+                    length = end - start
+                    parts.append(
+                        torch.arange(length, device=input_ids.device).view(1, -1).expand(3, -1)
+                        + current_position
+                    )
+                    current_position += length
+                else:
+                    iterator = image_iterator if modality == 1 else video_iterator
+                    if iterator is None:
+                        raise ValueError("multimodal token types require matching grid_thw metadata")
+                    grid = next(iterator)
+                    parts.append(
+                        self._get_vision_position_ids(
+                            current_position, grid, merge_size, input_ids.device
+                        )
+                    )
+                    current_position += int(max(grid[1], grid[2]).item()) // merge_size
+            current = torch.cat(parts, dim=1)
+            if active is None:
+                positions[:, batch_index] = current
+            else:
+                positions[:, batch_index, active] = current
+            deltas.append(current.max() + 1 - len(current_ids))
+        return positions, torch.stack(deltas).unsqueeze(1)
+
+    def multimodal_forward(
+        self,
+        *,
+        input_ids: torch.Tensor,
+        attention_mask: torch.Tensor | None = None,
+        position_ids: torch.Tensor | None = None,
+        pixel_values: torch.Tensor | None = None,
+        pixel_values_videos: torch.Tensor | None = None,
+        image_grid_thw: torch.Tensor | None = None,
+        video_grid_thw: torch.Tensor | None = None,
+        mm_token_type_ids: torch.Tensor | None = None,
+        cache: DendroTransplantCache | None = None,
+        use_cache: bool = False,
+    ) -> DendroTransplantOutput:
+        embeddings = self.token_embedding(input_ids)
+        if pixel_values is not None:
+            if image_grid_thw is None or self.image_token_id is None:
+                raise ValueError("pixel_values requires image_grid_thw and image_token_id")
+            features = self.vision_forward(pixel_values, image_grid_thw).to(
+                device=embeddings.device, dtype=embeddings.dtype
+            )
+            mask = (input_ids == int(self.image_token_id)).unsqueeze(-1)
+            if int(mask.sum().item()) * embeddings.shape[-1] != features.numel():
+                raise ValueError("image placeholder token count does not match transplanted vision features")
+            embeddings = embeddings.masked_scatter(mask, features)
+        if pixel_values_videos is not None:
+            if video_grid_thw is None or self.video_token_id is None:
+                raise ValueError("pixel_values_videos requires video_grid_thw and video_token_id")
+            features = self.vision_forward(pixel_values_videos, video_grid_thw).to(
+                device=embeddings.device, dtype=embeddings.dtype
+            )
+            mask = (input_ids == int(self.video_token_id)).unsqueeze(-1)
+            if int(mask.sum().item()) * embeddings.shape[-1] != features.numel():
+                raise ValueError("video placeholder token count does not match transplanted vision features")
+            embeddings = embeddings.masked_scatter(mask, features)
+
+        rope_deltas = None
+        if position_ids is None and (image_grid_thw is not None or video_grid_thw is not None):
+            if mm_token_type_ids is None:
+                raise ValueError("multimodal transplant inputs require mm_token_type_ids")
+            position_ids, rope_deltas = self.get_rope_index(
+                input_ids,
+                mm_token_type_ids,
+                image_grid_thw=image_grid_thw,
+                video_grid_thw=video_grid_thw,
+                attention_mask=attention_mask,
+            )
+        result = self.text_forward(
+            inputs_embeds=embeddings,
+            attention_mask=attention_mask,
+            position_ids=position_ids,
+            cache=cache,
+            use_cache=use_cache,
+        )
+        result.rope_deltas = rope_deltas
+        return result
+
+    def validate_required_tensors(self) -> list[str]:
+        """Return missing tensor names needed for the exact path."""
+        required = required_transplant_tensor_names(self.source_config)
+        return sorted(name for name in required if not self.source.has_named_tensor(name))