circuit-vl-4b: LoRA + pointer head on Qwen3-VL-4B-Instruct, best step 500

README.md

@@ -0,0 +1,98 @@
+---
+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
+
+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: rendered receipts, bar charts, tables, forms,
+and shape scenes, with every label computed by the code that drew the
+image. Operations: extract, read, classify, compare, count, consistency,
+negation. 300 held-out items, accuracy / ECE (15 bins).
+
+| model | vision grid | ms per item, RTX A6000 |
+|---|---|---|
+| Qwen3-VL-4B-Instruct, raw, letter logits | 96.0% / 0.041 | 61 |
+| **circuit-vl-4b** | **98.3% / 0.018** | 90 |
+
+Per cell the fine-tune is at 100% on every receipt, form, and chart family,
+93% on counting rows in tables, and 97% on negated questions about scenes.
+
+Caveats. The grid is ours, so this is held-out items, not held-out
+structure; the training set is small (1,083 items); and on the handful of
+items rendered to be undecidable (a blurred field under a comparison
+question) the model answers with mean confidence 0.93 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 (`python -m s1proto.data.vision_grid` in the
+  [circuit](https://github.com/Barneyjm/circuit) repo), 1,083 train and
+  117 validation items, labels computed at render time, about 5% rendered
+  ambiguous with soft 0.5 labels. No teacher-model outputs.
+- 2 epochs, batch 4, max 1,536 tokens, lr 1e-4 (LoRA) / 1e-3 (head), bf16
+  with gradient checkpointing, soft-target cross-entropy, early stopping on
+  validation ECE (best at step 500: ECE 0.016, accuracy 98.3%). 7 minutes on
+  one RTX A6000.
+
+## 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). The HTTP service in the repo serves
+the text models today; image states over `POST /v1/systemone` are the next
+step for this one.
+
+## 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. Trained on rendered synthetic documents; expect a drop on
+photographs of real paperwork until real data is in the mix. English only.
+
+## License
+
+Adapter and head: Apache 2.0. Base model: Apache 2.0 (Qwen3-VL).

adapter/README.md

@@ -0,0 +1,206 @@
+---
+base_model: Qwen/Qwen3-VL-4B-Instruct
+library_name: peft
+tags:
+- base_model:adapter:Qwen/Qwen3-VL-4B-Instruct
+- lora
+- transformers
+---
+
+# Model Card for Model ID
+
+<!-- Provide a quick summary of what the model is/does. -->
+
+
+
+## Model Details
+
+### Model Description
+
+<!-- Provide a longer summary of what this model is. -->
+
+
+
+- **Developed by:** [More Information Needed]
+- **Funded by [optional]:** [More Information Needed]
+- **Shared by [optional]:** [More Information Needed]
+- **Model type:** [More Information Needed]
+- **Language(s) (NLP):** [More Information Needed]
+- **License:** [More Information Needed]
+- **Finetuned from model [optional]:** [More Information Needed]
+
+### Model Sources [optional]
+
+<!-- Provide the basic links for the model. -->
+
+- **Repository:** [More Information Needed]
+- **Paper [optional]:** [More Information Needed]
+- **Demo [optional]:** [More Information Needed]
+
+## Uses
+
+<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
+
+### Direct Use
+
+<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
+
+[More Information Needed]
+
+### Downstream Use [optional]
+
+<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
+
+[More Information Needed]
+
+### Out-of-Scope Use
+
+<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
+
+[More Information Needed]
+
+## Bias, Risks, and Limitations
+
+<!-- This section is meant to convey both technical and sociotechnical limitations. -->
+
+[More Information Needed]
+
+### Recommendations
+
+<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
+
+Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
+
+## How to Get Started with the Model
+
+Use the code below to get started with the model.
+
+[More Information Needed]
+
+## Training Details
+
+### Training Data
+
+<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
+
+[More Information Needed]
+
+### Training Procedure
+
+<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
+
+#### Preprocessing [optional]
+
+[More Information Needed]
+
+
+#### Training Hyperparameters
+
+- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
+
+#### Speeds, Sizes, Times [optional]
+
+<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
+
+[More Information Needed]
+
+## Evaluation
+
+<!-- This section describes the evaluation protocols and provides the results. -->
+
+### Testing Data, Factors & Metrics
+
+#### Testing Data
+
+<!-- This should link to a Dataset Card if possible. -->
+
+[More Information Needed]
+
+#### Factors
+
+<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
+
+[More Information Needed]
+
+#### Metrics
+
+<!-- These are the evaluation metrics being used, ideally with a description of why. -->
+
+[More Information Needed]
+
+### Results
+
+[More Information Needed]
+
+#### Summary
+
+
+
+## Model Examination [optional]
+
+<!-- Relevant interpretability work for the model goes here -->
+
+[More Information Needed]
+
+## Environmental Impact
+
+<!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly -->
+
+Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://arxiv.org/abs/1910.09700).
+
+- **Hardware Type:** [More Information Needed]
+- **Hours used:** [More Information Needed]
+- **Cloud Provider:** [More Information Needed]
+- **Compute Region:** [More Information Needed]
+- **Carbon Emitted:** [More Information Needed]
+
+## Technical Specifications [optional]
+
+### Model Architecture and Objective
+
+[More Information Needed]
+
+### Compute Infrastructure
+
+[More Information Needed]
+
+#### Hardware
+
+[More Information Needed]
+
+#### Software
+
+[More Information Needed]
+
+## Citation [optional]
+
+<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
+
+**BibTeX:**
+
+[More Information Needed]
+
+**APA:**
+
+[More Information Needed]
+
+## Glossary [optional]
+
+<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
+
+[More Information Needed]
+
+## More Information [optional]
+
+[More Information Needed]
+
+## Model Card Authors [optional]
+
+[More Information Needed]
+
+## Model Card Contact
+
+[More Information Needed]
+### Framework versions
+
+- PEFT 0.21.0

adapter/adapter_config.json

@@ -0,0 +1,46 @@
+{
+  "alora_invocation_tokens": null,
+  "alpha_pattern": {},
+  "arrow_config": null,
+  "auto_mapping": {
+    "base_model_class": "Qwen3VLForConditionalGeneration",
+    "parent_library": "transformers.models.qwen3_vl.modeling_qwen3_vl"
+  },
+  "base_model_name_or_path": "Qwen/Qwen3-VL-4B-Instruct",
+  "bias": "none",
+  "corda_config": null,
+  "ensure_weight_tying": false,
+  "eva_config": null,
+  "exclude_modules": null,
+  "fan_in_fan_out": false,
+  "inference_mode": true,
+  "init_lora_weights": true,
+  "kasa_config": null,
+  "layer_replication": null,
+  "layers_pattern": null,
+  "layers_to_transform": null,
+  "loftq_config": {},
+  "lora_alpha": 32,
+  "lora_bias": false,
+  "lora_dropout": 0.05,
+  "lora_ga_config": null,
+  "megatron_config": null,
+  "megatron_core": "megatron.core",
+  "modules_to_save": null,
+  "monteclora_config": null,
+  "peft_type": "LORA",
+  "peft_version": "0.21.0",
+  "qalora_group_size": 16,
+  "r": 16,
+  "rank_pattern": {},
+  "revision": null,
+  "target_modules": ".*language_model.*\\.(q_proj|k_proj|v_proj|o_proj|gate_proj|up_proj|down_proj)",
+  "target_parameters": null,
+  "task_type": null,
+  "trainable_token_indices": null,
+  "use_bdlora": null,
+  "use_dora": false,
+  "use_qalora": false,
+  "use_rslora": false,
+  "velora_config": null
+}

adapter/adapter_model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:68245b4578a66fe3bd273dd3c1f4a44b9f1c584b4446dc343b47f011f1d47324
+size 132195448

config.json

@@ -0,0 +1,40 @@
+{
+ "base": "Qwen/Qwen3-VL-4B-Instruct",
+ "hidden": 2560,
+ "head": "pointer",
+ "head_size": 256,
+ "head_dim": 256,
+ "layout": "pointer",
+ "load_4bit": false,
+ "modality": "vision",
+ "best": {
+  "ece": 0.015816945805508867,
+  "accuracy": 0.9829059829059829,
+  "kl": 0.027667189338858887,
+  "step": 500
+ },
+ "args": {
+  "model": "Qwen/Qwen3-VL-4B-Instruct",
+  "data": "data/vision/grid/train.jsonl",
+  "out": "runs/circuit-vl-4b",
+  "epochs": 2,
+  "batch": 4,
+  "lr": 0.0001,
+  "head_lr": 0.001,
+  "rank": 16,
+  "max_length": 1536,
+  "val_frac": 0.1,
+  "eval_every": 100,
+  "limit": null,
+  "seed": 0,
+  "dtype": "bfloat16",
+  "grad_checkpoint": true,
+  "wandb": "s1proto",
+  "run_name": "circuit-vl-4b",
+  "resume": false,
+  "head": "pointer",
+  "load_4bit": false,
+  "modality": "vision",
+  "exclude_family": null
+ }
+}

head.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:da12c989d8e688b22cb3a69618ba54324e5a469c61d7028538fd211bd8dfa604
+size 5244685