README.md

---
pipeline_tag: zero-shot-classification
license: apache-2.0
base_model: Qwen/Qwen3.5-2B
library_name: transformers
tags:
- decision-model
- classification
- system-one
- multimodal
- vision
- maincode
- matilda
---

# Matilda Decision v1 Nano

**Matilda Decision v1 Nano** is a 2.2B multimodal decision model from Maincode: a small decision model for high-throughput use. You give it an
input (text or JSON, optionally with images) and the questions you need answered: pick one of several options, say
yes or no, or rate on a scale. It answers them all in one call and returns a probability for every answer, without
generating text. It takes the same requests, and returns answers in the same format, as
[Matilda Decision v1](https://huggingface.co/Maincode/matilda-decision-v1) (27B).

| | |
| --- | --- |
| **Parameters** | 2.2B, including the vision encoder |
| **Inputs** | Text or JSON, plus images (several per request, up to 0.26 MP each) |
| **Decision types** | Choice (up to 255 options) · Yes / No · Score |
| **License** | Apache-2.0 |

## Quickstart

```bash
pip install "transformers==5.17.0" torch torchvision pillow safetensors
pip install flash-linear-attention  # optional: fast GPU kernels for the linear-attention layers
```

```python
import json

from transformers import AutoModel

model = AutoModel.from_pretrained("Maincode/Matilda-Decision-v1-Nano", trust_remote_code=True)

# Text
result = model.system_one(
    state="The order arrived damaged yesterday. The customer has a receipt and asks for a replacement today.",
    questions={
        "route": {
            "type": "choice",
            "instructions": "Which team should handle this request?",
            "criteria": {
                "returns": "Refunds, replacements and damaged deliveries",
                "billing": "Payments, invoices and charges",
                "technical": "Product setup and faults",
            },
        },
        "receipt": {"type": "noul", "instructions": "Does the customer have a receipt?"},
        "urgency": {
            "type": "score",
            "instructions": "How urgent is this request?",
            "criteria": ["Routine", "Soon", "Today"],
        },
    },
)
print(json.dumps(result["answers"], indent=2))

# Text and images
result = model.system_one(
    state="The customer says the blender arrived cracked and attached the receipt.",
    images=["receipt.png"],  # local paths, http(s) URLs, PIL images or base64 data URLs
    questions={
        "on_receipt": {"type": "noul", "instructions": "Does the receipt list the blender?"},
        "payment": {
            "type": "choice",
            "instructions": "How was the order paid?",
            "criteria": {"card": None, "cash": None, "gift card": None},
        },
    },
)
print(json.dumps(result["answers"], indent=2))
```

`from_pretrained` takes `device` (default `cuda:0` when a GPU is visible) and `max_image_pixels` (see
[Images](#images)).

## Requests and answers

`system_one(state=..., questions={id: question, ...}, images=[...])` returns
`{"model", "answers": {id: answer}, "usage"}`. Every question sees the same state and images.

| `type` | `criteria` | answer |
| --- | --- | --- |
| `choice` | `{option: description or None}`, 1–255 options | `choice`, `probabilities` per option, `confidence` |
| `noul` | optional `{"true": ..., "false": ...}` descriptions | `noul`: the probability of yes / true |
| `score` | level descriptions, lowest first | `score` (expected level), `probabilities`, `legend`, `confidence` |

`instructions` is the question text. `state` can be a string or any JSON value. It is read as data, not as
instructions. Inputs are never truncated: a request over 131,072 tokens raises an error.

## Images

- **Size:** each image is resized, keeping its aspect ratio, to at most **262,144 pixels (0.26 MP, about
  512 × 512)** and at least 65,536. The model was trained at this setting, which is the default in the runtime
  and in `processor_config.json`.
- **Tokens:** one input token per 32 × 32 pixel patch, so about 256 for a 512 × 512 image.
- **Order:** images go before the text, in the order given.
- **Other caps:** `AutoModel.from_pretrained(..., max_image_pixels=...)` changes the cap. Lower caps are faster
  but lose fine detail such as charts, documents and small text. Caps above 0.26 MP are not validated.

## Architecture

Qwen3.5-2B vision-language backbone with a 255-option decision readout. Each question takes one forward pass, and
its answer is read from the final prompt position.

**Training:** post-trained from Qwen3.5-2B on decisions across text and images.

The model was trained with **bidirectional attention**: its full-attention layers see the whole prompt at once,
rather than only the tokens before each position. **It must be served the same way.** `trust_remote_code=True`
loads the bundled runtime (`matilda_decision_runtime.py`), which sets this up. Loading the weights as a plain
causal backbone, or serving them in a causal engine, gives different and worse answers.

## License

Apache-2.0 ([LICENSE](LICENSE)). Built on [Qwen/Qwen3.5-2B](https://huggingface.co/Qwen/Qwen3.5-2B) (Apache-2.0).