README.md

---
license: apache-2.0
model_name: Phillnet Mini Max
base_model: Qwen/Qwen3.5-0.8B
library_name: transformers
pipeline_tag: image-text-to-text
language:
  - en
tags:
  - phillnet
  - phillnet-mini
  - dendro
  - text-generation
  - image-text-to-text
  - visual-question-answering
  - multimodal
  - adaptive-reasoning
  - code-generation
  - long-context
  - custom-code
  - safetensors
  - text-vision-only
widget:
  - text: "Write a concise launch announcement for a focused productivity application."
    example_title: Text Writing — Direct
  - text: "Create a complete single-file HTML landing page for a premium notes application."
    example_title: Text-to-HTML — Adaptive Max
  - text: "Explain the difference between a mutex and a semaphore with one practical example."
    example_title: Technical Explanation — Medium
---

<div align="center">

# ◈ Phillnet Mini Max
### *Focused Text + Vision Reasoning with Deep Adaptive Generation*

[![Transformers](https://img.shields.io/badge/Transformers-Custom_Code-ffcc4d?style=for-the-badge&logo=huggingface&logoColor=black)](https://huggingface.co/docs/transformers)
[![Weights](https://img.shields.io/badge/Weights-1.76_GB_SafeTensors-7c3aed?style=for-the-badge&logo=pypi&logoColor=white)](model.safetensors)
[![Modalities](https://img.shields.io/badge/Modalities-Text_%2B_Still_Vision-0284c7?style=for-the-badge)](#capability-surface)
[![Reasoning](https://img.shields.io/badge/Adaptive_Reasoning-Max_by_Default-f59e0b?style=for-the-badge)](#adaptive-reasoning)
[![Output](https://img.shields.io/badge/Visible_Output-Up_to_8K_Tokens-10b981?style=for-the-badge)](#adaptive-reasoning)
[![License](https://img.shields.io/badge/License-Apache--2.0-2563eb?style=for-the-badge)](LICENSE)

<p align="center">
  <b>A deliberately lean multimodal model for strong text work and still-image understanding.</b><br/>
  Write, reason, explain, transform, code, generate complete HTML, and answer image-grounded questions—without carrying an image or video synthesis stack.
</p>

</div>

---

## ◇ The Mini Max proposition

**Phillnet Mini Max** is the focused text-and-vision edition of [Phillnet Mini Omni Max][1]. It retains the language backbone, the visual-understanding route, the native Qwen tokenizer contract, and adaptive reasoning controls while intentionally excluding diffusion and synthesis subsystems. The result is a smaller operational surface for applications that need **high-quality language work plus image understanding**, not image or video generation.

> **Best fit:** conversational AI, writing assistants, technical explanation, code and single-file HTML generation, text transformation, visual question answering, image-grounded reasoning, and self-hosted multimodal APIs.

<div align="center">

**Text Intelligence** &nbsp;·&nbsp; **Still-Image Understanding** &nbsp;·&nbsp; **Adaptive Reasoning** &nbsp;·&nbsp; **Production-Ready Local API**

</div>

---

## ✦ Capability surface

| Capability | Phillnet Mini Max behavior | Practical use |
|:---|:---|:---|
| **Text generation** | Enabled through `DendroForCausalLM.generate(...)`. | Conversation, drafting, rewriting, summaries, structured text, and instruction following. |
| **Reasoned text work** | Five selectable effort modes with `max` as the persisted default. | Short direct answers through long-form planning, technical analysis, and code generation. |
| **Code and HTML** | Generates ordinary text tokens, including self-contained code and HTML documents. | Landing pages, dashboards, UI prototypes, scripts, documentation, and configuration templates. |
| **Still-image understanding** | Enabled through the local `DendroVisionProcessor` and retained visual encoder. | Image description, visual Q&A, color and spatial questions, and image-grounded chat. |
| **OpenAI-style service** | Included FastAPI endpoint accepts text and optional inline base64 images. | Controlled self-hosted product integration. |
| **Image / video synthesis** | **Not included.** SDXL weights, U-Net, VAE, diffusion schedulers, and synthesis APIs are absent. | Keeps deployment focused on language and visual understanding. |
| **Audio, tools, agents, remote URL fetch** | **Not exposed** by the lean service. | Reduces the deployed attack and dependency surface. |

---

## ✦ Text capabilities, in depth

The language path is first-class in this release. Use it for direct chat, long-form writing, editing, code generation, schema-oriented output, and reasoning-heavy tasks. The model processes the same chat format for text-only and multimodal turns, so an application can begin in text mode and introduce images only when a task requires visual evidence.

| Text workflow | Suggested mode | Why it fits |
|:---|:---:|:---|
| Classification, short formatting, lightweight extraction | `direct` | Minimizes deliberation for fast, bounded responses. |
| Summaries, rewrites, concise explanations, ordinary Q&A | `low` | Adds modest reasoning without the maximum latency profile. |
| Technical explanations, multi-step planning, nontrivial coding | `medium` | Balanced answer depth and deliberation. |
| Architecture reviews, complicated debugging, detailed specifications | `high` | Allocates deeper internal reasoning. |
| Long-form HTML, substantial code, complex written deliverables | `max` | Uses the release default: adaptive private reasoning plus an 8,192-token visible-answer ceiling. |

### Text-only quick start

```bash
pip install -r requirements.txt
```

```python
import torch
from transformers import AutoModelForCausalLM, AutoProcessor

model_id = "ayjays132/Phillnet-Mini-Max"

processor = AutoProcessor.from_pretrained(
    model_id,
    trust_remote_code=True,
)
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    trust_remote_code=True,
    dtype=torch.bfloat16,
    low_cpu_mem_usage=True,
).eval()

messages = [
    {
        "role": "system",
        "content": "You are a precise writing and technical reasoning assistant.",
    },
    {
        "role": "user",
        "content": "Write a concise product brief for a privacy-first research workspace.",
    },
]

inputs = processor.apply_chat_template(
    messages,
    tokenize=True,
    add_generation_prompt=True,
    return_dict=True,
    return_tensors="pt",
)

with torch.inference_mode():
    output = model.generate(
        **inputs,
        reasoning_effort="medium",
        max_new_tokens=700,
        do_sample=False,
        use_cache=True,
    )

prompt_tokens = inputs["input_ids"].shape[1]
answer = processor.tokenizer.decode(
    output[0, prompt_tokens:],
    skip_special_tokens=True,
)
print(answer)
```

### One-shot HTML and code generation

For full-page HTML, use `max` and allow enough answer tokens for the entire document. The included gallery contains three standalone outputs—two application interfaces and one landing page—created as self-contained HTML with inline CSS and JavaScript.

```python
html_request = [
    {
        "role": "user",
        "content": (
            "Create a complete, responsive, single-file HTML dashboard for a solar-energy "
            "operations team. Use inline CSS and JavaScript. Include a metrics row, a small chart, "
            "status alerts, and a working theme toggle. Return only the HTML document."
        ),
    }
]

inputs = processor.apply_chat_template(
    html_request,
    tokenize=True,
    add_generation_prompt=True,
    return_dict=True,
    return_tensors="pt",
)

with torch.inference_mode():
    output = model.generate(
        **inputs,
        reasoning_effort="max",
        max_new_tokens=8192,
        do_sample=False,
        use_cache=True,
    )

html = processor.tokenizer.decode(
    output[0, inputs["input_ids"].shape[1]:],
    skip_special_tokens=True,
)
open("solara-dashboard.html", "w", encoding="utf-8").write(html)
```

---

## ◇ Adaptive reasoning

Adaptive reasoning is **enabled by default**. The model separates internal deliberation from the final answer: its private phase can use the active context budget and end naturally, while the returned answer is bounded independently.

| Persisted default | Value | Operational meaning |
|:---|:---:|:---|
| Default effort | `max` | The model uses its highest configured effort profile when a caller does not override it. |
| Adaptive private reasoning | `true` | Private deliberation can expand within the active context boundary. |
| Private-reasoning policy | `adaptive_context` | Reasoning is governed by real context/cache capacity rather than a short hidden caller cap. |
| Visible answer ceiling | **8,192 tokens** | Supports substantial documents and code while retaining a predictable returned-output bound. |
| Active context/cache window | 32,768 tokens | Shared physical budget for prompt, private deliberation, and answer allocation. |

> **Use the right budget.** For short interactive work, explicitly select `direct` or `low`. For whole pages, multi-section documents, or more demanding code, preserve `max` and permit a correspondingly larger visible-answer budget.

---

## ◇ Visual understanding

The bundled `DendroVisionProcessor` is local to this repository and uses the checkpoint’s native Qwen tokenizer contract. It creates visual patches, inserts image placeholders at the correct point in the conversation, and routes visual features into the retained model path.

```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 objects in this image and explain their relative positions.",
            },
        ],
    }
]

inputs = processor.apply_chat_template(
    messages,
    tokenize=True,
    add_generation_prompt=True,
    return_dict=True,
    return_tensors="pt",
)

with torch.inference_mode():
    output = model.generate(
        **inputs,
        reasoning_effort="medium",
        max_new_tokens=512,
        do_sample=False,
        use_cache=True,
    )

answer = processor.tokenizer.decode(
    output[0, inputs["input_ids"].shape[1]:],
    skip_special_tokens=True,
)
print(answer)
```

The visual path is intended for **still-image understanding**. It does not provide image creation, image editing, video generation, audio understanding, browser tools, or remote image URL fetching.

---

## ✦ Release gallery

<div align="center">
  <a href="examples/direct-horizon-tasks.html"><img src="examples/direct-horizon-tasks.png" alt="Horizon Tasks landing-page preview" width="31%" /></a>
  <a href="examples/medium-solara-dashboard.html"><img src="examples/medium-solara-dashboard.png" alt="Solara Grid dashboard preview" width="31%" /></a>
  <a href="examples/max-orbit-notes.html"><img src="examples/max-orbit-notes.png" alt="Orbit Notes landing-page preview" width="31%" /></a>
</div>

<div align="center">
  <sub><b>Horizon Tasks — Direct</b> &nbsp;·&nbsp; <b>Solara Grid — Medium</b> &nbsp;·&nbsp; <b>Orbit Notes — Adaptive Max</b></sub>
</div>

| Example | Focus | Source |
|:---|:---|:---|
| **Horizon Tasks** | Dark productivity landing-page composition. | [Open HTML](examples/direct-horizon-tasks.html) |
| **Solara Grid** | Responsive operational dashboard with metrics, CSS chart, alerts, and a theme control. | [Open HTML](examples/medium-solara-dashboard.html) |
| **Orbit Notes** | Long-form adaptive one-shot landing page. | [Open HTML](examples/max-orbit-notes.html) |

---

## ◇ Verification snapshot

The release was checked at the model, processor, reasoning, visual-input, API, and package levels. The validation evidence is retained in `RELEASE_VALIDATION.md`, `ADAPTIVE_DEFAULTS_REPORT.md`, and `COHERENCE_REPAIR_REPORT.md`.

| Area | Verified result |
|:---|:---|
| Core checkpoint | `DendroForCausalLM` loads in BF16. |
| Native tokenizer | Local Qwen tokenizer matches the checkpoint’s 248,320-token vocabulary. |
| Text coherence | Deterministic text probes returned `Paris`, `4`, and `blue`. |
| Local processor | `AutoProcessor` resolves to `DendroVisionProcessor`. |
| Image grounding | Controlled solid-color probes produced the corresponding colors. |
| Spatial grounding | A red-left / blue-right probe returned `red` for left and `blue` for right. |
| Long text / HTML | A complete 2,991-token Orbit Notes HTML page was produced after 2,944 private-reasoning tokens. |
| Lean scope | SDXL weights, code, dependencies, and synthesis APIs are absent. |

<details>
<summary><b>Open the retained-checkpoint integrity record</b></summary>

```text
model.safetensors
SHA-256: f1a913f99f8ce921c1aa79982a09eaee6744448766f09a4756751e2d4b9342fc
Size:    1,763,655,304 bytes
```

The repository’s `CHECKSUMS.sha256` and `RELEASE_MANIFEST.json` provide the corresponding reproducibility records.
</details>

---

## ◇ Architecture and package layout

```text
PHILLNET MINI MAX — TEXT + VISION EDITION
│
├── Language path       Dendro causal language model
├── Vision path         Retained visual encoder + local DendroVisionProcessor
├── Token vocabulary    248,320 native Qwen-compatible tokens
├── Reasoning policy    Adaptive private deliberation; max by default
├── Answer policy       Up to 8,192 visible answer tokens
├── Checkpoint          1.76 GB SafeTensors, BF16-capable load path
└── Excluded systems    SDXL, U-Net, VAE, diffusion, image/video synthesis,
                        audio, agents, tools, and remote image fetching
```

| Repository path | Purpose |
|:---|:---|
| `model.safetensors` | Retained language and visual-understanding checkpoint. |
| `config.json` | Model configuration, adaptive defaults, and custom auto mappings. |
| `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 OpenAI-style FastAPI service. |
| `examples/` | Complete HTML examples and visual previews. |
| `PRODUCTION.md` | Deployment topology, security controls, and operations guide. |
| `HF_UPLOAD.md` | Hugging Face upload and verification workflow. |
| `RELEASE_MANIFEST.json` | Release identity, artifact hashes, capability boundary, and defaults. |

---

## ◇ Local API and production deployment

The included service exposes only `POST /v1/chat/completions`, with text and optional inline base64 still images.

```bash
pip install -r requirements.txt -r requirements-server.txt
uvicorn server:app --host 127.0.0.1 --port 8000
```

```bash
curl http://127.0.0.1:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  --data '{
    "messages": [
      {
        "role": "user",
        "content": "Draft a concise engineering handoff for a feature-flag rollout."
      }
    ],
    "reasoning_effort": "medium",
    "max_tokens": 700
  }'
```

For deployment, the repository includes a non-root `Dockerfile`, loopback-bound `docker-compose.yml`, readiness checks, optional API-key protection, explicit CORS configuration, image/request limits, and a single-generation lock. Start with:

```bash
cp .env.example .env
# Set PHILLNET_API_KEY and PHILLNET_CORS_ORIGINS before public exposure.
docker compose up --build -d
```

Read [PRODUCTION.md](PRODUCTION.md) before placing the service behind a public endpoint.

---

## ◇ License and provenance

This derivative retains the upstream Apache-2.0 designation. It is based on the Phillnet Mini Omni Max release and preserves only its text and still-image-understanding routes. See the upstream model card for the source release context. [1]

| Attribute | Value |
|:---|:---|
| License | Apache-2.0 |
| Upstream reference | [ayjays132/Phillnet-Mini-Omni-Max][1] |
| Release repository | [ayjays132/Phillnet-Mini-Max](https://huggingface.co/ayjays132/Phillnet-Mini-Max) |
| Loading requirement | `trust_remote_code=True` |

[1]: https://huggingface.co/ayjays132/Phillnet-Mini-Omni-Max "Phillnet Mini Omni Max"