README.md

---
license: apache-2.0
library_name: peft
base_model: Qwen/Qwen3-VL-4B-Instruct
base_model_relation: adapter
pipeline_tag: image-text-to-text
language:
- en
tags:
- decision-model
- system-one
- calibration
- typesafe
- decision-circuits
- lora
- vision
---

# circuit-vl-4b

**v1.2** (2026-09-22). The options of a choice question are encoded side by side, so the answer cannot depend on the order they are listed in: 0.0% of answers change under reordering on its grid (v1.1: 3.6%); grid .967 / ECE .021, POPE .907 / .069. `config.json` carries `"parallel_options": true`; serve it with the circuit repo's scorer, which applies the mask. See [Versions](#versions).

**v1.1.** Same base, head and recipe as v1.0, with real photographs (Open Images V7, human-verified labels) added to the training data. "Vision grid v2" below names the dataset, not the model. See [Versions](#versions).

A **System One** decision model for images: a state that carries one or
more images (video as sampled frames) plus optional text, typed questions
in, calibrated probability distributions out, one forward pass, no text
generation. It is the vision member of the circuit family behind
[decision-circuits](https://decisioncircuits.com); the text members are
[circuit-1.7b](https://huggingface.co/jbarney/circuit-1.7b) and
[circuit-8b](https://huggingface.co/jbarney/circuit-8b).

`circuit-vl-4b` is a LoRA adapter on the language model of
`Qwen/Qwen3-VL-4B-Instruct` (vision encoder frozen and untouched) plus the
same pointer readout head as the text models. Each option is wrapped in
delimiter tokens and the sequence ends with a decide token; the head scores
every option's closing delimiter against the decide token and applies
softmax. Trained with cross-entropy against outcome labels, so calibration
is learned. No cap on the number of options, unlike letter-logit prompting.

## Results

Vision generalization grid v2: rendered receipts, bar charts, tables,
forms, and shape scenes with every label computed by the code that drew
the image, plus real photographs from Open Images V7 validation (images
CC BY 2.0 by their Flickr authors, labels CC BY 4.0) with questions
labeled by the human-verified image labels: is there a dog, which of these
is in the photo, is there no horse anywhere. 16 cells. 390 held-out items,
accuracy / ECE (15 bins).

| model | all 390 | real photos (86) | ms per item, M-series laptop |
|---|---|---|---|
| Qwen3-VL-4B-Instruct, raw, letter logits | 92.6% / 0.079 | 81.4% / 0.192 | 760 |
| **circuit-vl-4b** | **96.4% / 0.036** | **89.5% / 0.105** | 1,000 |

Rendered documents are at or near 100% in every cell (counting rows in a
table 93%, counting shapes 90%). Photos are the hard part: 97% on "which
of these is in the photo", 86% on presence and on negated presence, where
the base sits at 76% to 89%. Open Images' verified labels are not
exhaustive, so some of the remaining error is label noise on small or
partly hidden objects.

Caveats. The grid is ours, so this is held-out items, not held-out
structure; on the items made undecidable (a blurred or mostly blacked-out
image) the model answers with mean confidence 0.88 where it should be near
0.5. As with the text models, calibration on ambiguity is the open problem,
and it is why decision circuits put an uncertainty band around every
threshold.

## Training

- Base: `Qwen/Qwen3-VL-4B-Instruct` (Apache 2.0), frozen. LoRA rank 16,
  alpha 32, on the language model's attention and MLP projections only
  (33M params). Pointer head: two 2560 x 256 linear maps.
- Data: the vision grid v2 (`python -m s1proto.data.vision_grid` in the
  [circuit](https://github.com/Barneyjm/circuit) repo), 1,408 train and
  152 validation items across 16 cells: rendered documents labeled at
  render time, and 700 Open Images validation photos with human-verified
  labels (per-image attribution in the data manifest). About 8% made
  ambiguous with soft labels. No teacher-model outputs.
- 2 epochs, batch 2, max 1,536 tokens, lr 1e-4 (LoRA) / 1e-3 (head), bf16,
  soft-target cross-entropy, early stopping on validation ECE (best at step
  600: ECE 0.035, accuracy 96.7%). 85 minutes on an Apple laptop GPU.

## Versions

| tag | date | what changed |
|---|---|---|
| `v1.2` | 2026-09-22 | Options encoded side by side: order-stable answers. Same data and recipe as v1.1 otherwise. |
| `v1.1` | 2026-09 | Trains on vision grid v2: the rendered cells plus three cells of real photographs. |
| `v1.0` | 2026-09 | First release, rendered or scripted data only. |

Pin one with `revision="v1.0"` in `huggingface_hub`.

## Use

Score a JSONL of `{"state": {"image": path, "text": ...}, "question": ...}`
items with the circuit repo's evaluator:

```bash
uv run python scripts/eval_vision.py data/vision/grid/eval.jsonl --lora runs/circuit-vl-4b --out results/vgrid.json
```

Files: `adapter/` (PEFT LoRA, language-model targets), `head.pt` (pointer
head, keys `q.weight`, `k.weight`), `config.json` (base, hidden size, head
type, layout, modality, training args). It is served at
`api.decisioncircuits.com`: send `state` as `{"image": "<data URI or https URL>", "text": "<optional>"}`
with `"model": "circuit-vl-4b"`.

## Intended use and limits

Research and evaluation of calibrated decision models over documents,
charts, forms, and photos. Not a production system for decisions that affect
people. Documents in training are rendered, not photographed; expect a drop
on photographs of real paperwork until those are in the mix. English only.

## License

Adapter and head: Apache 2.0. Base model: Apache 2.0 (Qwen3-VL).