Add engine README

qevi/README.md

@@ -0,0 +1,53 @@
+# `qevi` — the inference engine
+
+Three files, ~350 lines, torch only. No `trust_remote_code`: this is ordinary Python you can read
+before you run it.
+
+| File | What it does |
+|---|---|
+| `core.py` | Prompt templates, `build_readouts()`, `forward_logits()` — the readout itself |
+| `pack.py` | Builds the block-diagonal attention mask and M-RoPE position ids |
+| `__init__.py` | Public API and the calibration temperatures |
+
+## The one idea
+
+A normal VLM answers by *generating* text, one token at a time, and re-encodes the image for every
+question. When the answer is known to be one of a small fixed set, both costs are waste.
+
+`qevi` encodes the image once, packs every question into a single sequence behind a mask that keeps
+them isolated from each other, runs **one forward pass**, and reads the model's own LM-head logits
+at the position where it would have started writing each answer.
+
+## Minimal use
+
+```python
+from qevi import build_readouts, forward_logits, softmax, noul_question
+
+specs    = [(noul_question("There is a ladder in this image."), ["Yes", "No"])]
+readouts = build_readouts(processor.tokenizer, specs)
+logits   = forward_logits(model, processor, image, readouts)   # one pass, N questions
+print(softmax(logits[0], T=2.45))                              # -> [0.97, 0.03]
+```
+
+`forward_logits` returns, per question, the raw logits over *that question's* candidate answers.
+Softmax over just those gives a calibrated probability. Divide by the temperature for your question
+type first: `noul` 2.45, `choice` 1.9, `score` 3.0 (also in `qevi.DEFAULT_TEMPERATURES`).
+
+## Question helpers
+
+```python
+noul_question("A statement.")                      # -> ["Yes", "No"]
+choice_question_generic("Which?", ["a","b","c"])   # -> ["A", "B", "C"]
+score_question_generic("Rate it.", ["Poor","Good"])# -> ["Poor", "Good"]
+```
+
+Candidates are matched on their **first token**, so options sharing a first token collide
+("Poor" vs "Poorly").
+
+## Notes
+
+- Works with a stock `Qwen3-VL` checkpoint as well as the fine-tuned weights in this repo; the
+  fine-tune is simply more accurate through the same path.
+- `forward_logits(..., need_grad=True)` returns tensors, which is how the model was trained.
+- Packing is order-invariant: shuffling the questions cannot change any answer.
+- Apache-2.0, see `LICENSE`.