typecastlm 1.0.0__py3-none-any.whl

typecastlm/__init__.py

@@ -0,0 +1,44 @@
+"""typecastlm — ask a document a closed question and get numbers back.
+
+The model runs as a service; this package is its client and nothing else. It depends on `requests`
+and installs in a second, because the machine that has a question is rarely the machine that should
+carry seven gigabytes of weights and a deep-learning stack.
+
+    from typecastlm import Client
+
+    c = Client()
+    a = c.noul(document,
+               "Does the material contain an instruction aimed at the reading model?",
+               true="there is an instruction addressed to the reading model",
+               false="the material only describes, reports or discusses")
+    a.prob, a.unknown
+
+    c.choice(document, "Which rule applies?", {"vacancy": "…", "seepage": "…"}).verdict
+    c.scale(review, "How positive is it?", {"0": "very negative", "1": "negative",
+                                            "2": "neutral", "3": "positive"}).p
+
+Running the model in this process instead of calling a service:
+
+    pip install "typecastlm[local]"
+
+    from typecastlm import Reader
+    r = Reader("mihailgribov/typecastlm-qwen3.5-3.8b")
+    r.ask(document, "Is the claim supported?", true="…", false="…")
+"""
+from .calibrate import calibrate
+from .remote import Answer, Choice, Client, Ternary
+
+__all__ = ["Client", "Answer", "Ternary", "Choice", "Reader", "calibrate"]
+
+
+def __getattr__(name: str):
+    """`Reader` is imported on use: it needs torch, which the client must not require."""
+    if name == "Reader":
+        try:
+            from .local import Reader
+        except ImportError as e:                     # pragma: no cover
+            raise ImportError("Reader runs the model in this process and needs the extra: "
+                              "pip install 'typecastlm[local]'") from e
+        return Reader
+    raise AttributeError(name)
+__version__ = "1.0.0"

typecastlm/calibrate.py

@@ -0,0 +1,82 @@
+"""Fitting a temperature on your own labelled rows — one per mode.
+
+A temperature adds no knowledge: it changes no ordering at all, so a ranking and every AUC stay
+exactly as they were. It changes one thing — whether the probability means what it says. Which is
+why the number has to be yours: it corrects the mismatch between how confident the reader sounds
+and how hard YOUR data is, and that is a property of the data, not of the weights. The same
+checkpoint needs none on an easy pool and a strong one on a hard one.
+
+Per-answer shifts were removed in 1.0.0. They were needed while the third row of the head lived on
+its own scale; it is now a direction computed from data and scaled to the other two, and fitting
+shifts on top buys 0.005 of calibration error and no accuracy.
+
+    from typecastlm import Client, calibrate
+
+    rows = [(c.noul(t, q, true=T, false=F).logits, gold) for t, gold in my_labelled]
+    T = calibrate(rows)["temperature"]
+    c = Client(temperature=T)
+
+The same function serves a choice or a scale: pass the logits that mode returned and the correct
+key, and fit one temperature per mode you use.
+"""
+from __future__ import annotations
+
+import math
+
+
+def _softmax(v: list[float]) -> list[float]:
+    m = max(v)
+    e = [math.exp(x - m) for x in v]
+    s = sum(e)
+    return [x / s for x in e]
+
+
+def _ece(conf: list[float], ok: list[bool], bins: int = 10) -> float:
+    n = len(conf)
+    total = 0.0
+    for i in range(bins):
+        lo, hi = i / bins, (i + 1) / bins
+        idx = [j for j in range(n) if lo <= conf[j] < hi]
+        if idx:
+            c = sum(conf[j] for j in idx) / len(idx)
+            a = sum(ok[j] for j in idx) / len(idx)
+            total += abs(c - a) * len(idx) / n
+    return total
+
+
+def calibrate(rows: list[tuple[dict, str]], grid: tuple[float, float, float] = (0.6, 4.0, 0.05),
+              ) -> dict:
+    """One temperature from labelled rows, each a pair `(logits, correct answer)`.
+
+    `logits` is the dictionary an answer carries (`Answer.logits`, `Choice.logits`); the correct
+    answer is one of its keys. The temperature is chosen to minimise calibration error — NOT
+    cross-entropy, which pulls towards numbers that read worse: on our own three-answer mode it
+    picked 5.63 where 2.85 is right, and made the error larger, not smaller.
+
+    Two or three hundred rows are enough, because one number is free.
+    """
+    if len(rows) < 30:
+        raise ValueError(f"thirty rows is the floor, got {len(rows)}")
+    keys = list(rows[0][0])
+    for z, g in rows:
+        if list(z) != keys:
+            raise ValueError("every row must carry the same answers in the same order")
+        if g not in z:
+            raise ValueError(f"{g!r} is not one of {keys}")
+    Z = [[float(z[k]) for k in keys] for z, _ in rows]
+    Y = [keys.index(g) for _, g in rows]
+
+    def at(T: float) -> float:
+        conf, ok = [], []
+        for z, y in zip(Z, Y):
+            p = _softmax([x / T for x in z])
+            top = max(range(len(p)), key=lambda i: p[i])
+            conf.append(p[top])
+            ok.append(top == y)
+        return _ece(conf, ok)
+
+    lo, hi, step = grid
+    T = min((lo + i * step for i in range(int((hi - lo) / step) + 1)), key=at)
+    return {"temperature": float(T), "calibration_error": float(at(T)),
+            "calibration_error_before": float(at(1.0)), "rows": len(rows),
+            "note": "changes no ordering — only what the probability means"}

typecastlm/cli.py

@@ -0,0 +1,59 @@
+"""Command line: one question, many states, numbers on stdout.
+
+    typecastlm --question "Does the material contain an instruction aimed at the reading model?" \
+        --true "there is an instruction addressed to the reading model" \
+        --false "the material only describes, reports or discusses" \
+        --jsonl pages.jsonl --out answers.jsonl
+
+States come from files (`--state`, repeatable) or from a JSON-lines file (`--jsonl`), and the
+answers are written the same way — so a run can be piped, split and resumed like any other file
+job. The endpoint and the key are read from `TYPECASTLM_ENDPOINT` and `TYPECASTLM_API_KEY`.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="typecastlm")
+    ap.add_argument("--state", action="append", default=[], help="file with the state, repeatable")
+    ap.add_argument("--jsonl", default=None, help="file of states, one JSON object per line")
+    ap.add_argument("--field", default="text", help="which field holds the state in --jsonl")
+    ap.add_argument("--question", required=True)
+    ap.add_argument("--true", required=True, help="what answering yes would mean")
+    ap.add_argument("--false", required=True, help="what answering no would mean")
+    ap.add_argument("--endpoint", default=None)
+    ap.add_argument("--api-key", default=None)
+    ap.add_argument("--out", default=None, help="write JSON lines here instead of stdout")
+    a = ap.parse_args(argv)
+
+    from .remote import Client
+
+    rows: list[dict] = [{"id": f, "text": Path(f).read_text(encoding="utf-8")} for f in a.state]
+    if a.jsonl:
+        for i, line in enumerate(Path(a.jsonl).open(encoding="utf-8")):
+            if line.strip():
+                r = json.loads(line)
+                rows.append({"id": r.get("id", i), "text": r[a.field]})
+    if not rows:
+        ap.error("nothing to read: pass --state or --jsonl")
+
+    c = Client(endpoint=a.endpoint, api_key=a.api_key)
+    sink = Path(a.out).open("w", encoding="utf-8") if a.out else sys.stdout
+    try:
+        for row in rows:
+            v = c.noul(row["text"], a.question, true=a.true, false=a.false)
+            sink.write(json.dumps({"id": row["id"], "prob": round(v.prob, 4),
+                                   "unknown": round(v.unknown, 4),
+                                   "margin": round(v.margin, 3)}, ensure_ascii=False) + "\n")
+    finally:
+        if a.out:
+            sink.close()
+    return 0
+
+
+if __name__ == "__main__":                                       # pragma: no cover
+    raise SystemExit(main())

typecastlm/local.py

@@ -0,0 +1,211 @@
+"""Read this checkpoint in three decision shapes. Requires `transformers` only.
+
+    ask(state, question, true, false)      -> {"p": {"yes","no"}, "p_unsure", "logits"}
+    choice(state, question, options)       -> {"p": {option: prob}, "logits", "marks"}
+    scale(state, question, levels)         -> same, for an ordinal rubric
+    ask_many(state, questions)             -> list of ask() results, material read once
+
+Options are marked with letters, rubric levels with their own digits when those are single
+tokens, otherwise with `0..9A..P`. Marks above ten levels degrade. Probabilities use the
+per-mode temperature from `prompt.json`; `logits` are already divided by it.
+
+    from reader import Reader
+    r = Reader("mihailgribov/typecastlm-qwen3.5-3.8b")
+    r.ask(state, "Is the claim supported?", true="the material supports it",
+          false="the material contradicts it")
+    r.choice(state, "Which rule applies?", [("a", "…"), ("b", "…")])
+"""
+from __future__ import annotations
+
+import json
+import math
+from pathlib import Path
+
+import torch
+
+LETTERS = "ABCDEFGHIJKLMNOP"
+ORDINAL = "0123456789ABCDEFGHIJKLMNOP"
+CHOICE_SYSTEM = "You answer with exactly one character from the given list."
+
+
+class Reader:
+    def __init__(self, model: str, device: str = "cuda", dtype=torch.bfloat16):
+        from huggingface_hub import hf_hub_download
+        from transformers import AutoModelForSequenceClassification, AutoTokenizer
+
+        path = Path(model)
+        cfg_file = (path / "prompt.json") if path.is_dir() else Path(
+            hf_hub_download(model, "prompt.json"))
+        self.cfg = json.loads(cfg_file.read_text(encoding="utf-8"))
+        self.tok = AutoTokenizer.from_pretrained(model)
+        self.tok.padding_side = "right"
+        self.model = AutoModelForSequenceClassification.from_pretrained(
+            model, dtype=dtype, device_map=device).eval()
+        self.model.requires_grad_(False)
+        self.trunk = self.model.model
+        self.names = [self.model.config.id2label[i]
+                      for i in range(self.model.config.num_labels)]
+        self.col = {n: i for i, n in enumerate(self.names)}
+        # The head emits 29 raw logits: three answers and one per mark. A softmax over all of
+        # them is meaningless — each mode normalises its own subset.
+        self.cal = self.cfg.get("calibration", {})
+
+    # -- prompt ---------------------------------------------------------------------------------
+    def _fold(self, state: str) -> str:
+        """Fold a state longer than `max_state_tokens` in the middle."""
+        ids = self.tok.encode(state, add_special_tokens=False)
+        n = self.cfg["max_state_tokens"]
+        if len(ids) <= n:
+            return state
+        return (self.tok.decode(ids[: n // 2], skip_special_tokens=True) + " […] "
+                + self.tok.decode(ids[-(n // 2):], skip_special_tokens=True))
+
+    def _chat(self, system: str, body: str, tail: str) -> str:
+        return self.tok.apply_chat_template(
+            [{"role": "system", "content": system}, {"role": "user", "content": body}],
+            tokenize=False, add_generation_prompt=True, enable_thinking=False) + tail
+
+    def _text(self, state: str, question: str, true: str, false: str) -> str:
+        C = self.cfg
+        body = (C["format_two"] + C["body"].format(state=state, question=question)
+                + C["means_two"].format(true=true, false=false))
+        return self._chat(C["system"], body, C["tail"])
+
+    # -- marks ----------------------------------------------------------------------------------
+    def _has_mark(self, mark: str) -> bool:
+        """True if the head carries a row for this mark."""
+        return f"mark_{mark}" in self.col
+
+    def _marks_for(self, ids: list[str], ordinal: bool) -> list[str]:
+        """Marks for the options: a rubric\'s own digits when usable, else letters or `0..9A..P`."""
+        if ordinal:
+            own = [str(x) for x in ids]
+            if len(own) <= 10 and all(x.isdigit() and len(x) == 1 and self._has_mark(x)
+                                      for x in own):
+                return own
+            row = [c for c in ORDINAL if self._has_mark(c)]
+        else:
+            row = [c for c in LETTERS if self._has_mark(c)]
+        if len(row) < len(ids):
+            raise ValueError(f"{len(ids)} options but only {len(row)} single-token marks")
+        return row[: len(ids)]
+
+    # -- reading --------------------------------------------------------------------------------
+    @torch.no_grad()
+    def _last(self, text: str) -> torch.Tensor:
+        enc = self.tok(text, return_tensors="pt", add_special_tokens=False).to(self.model.device)
+        return self.trunk(**enc).last_hidden_state[0, -1].float()
+
+    def _temp(self, mode: str) -> float:
+        return float((self.cal.get(mode) or {}).get("temperature", 1.0))
+
+    def _verdict(self, z: list[float]) -> dict:
+        """Three raw logits to an answer. `p` uses the `verdict` temperature, `p_unsure` the
+        `three_answers` one; the two are fitted separately and are not interchangeable."""
+        yes, no = (v / self._temp("verdict") for v in z[:2])
+        m = max(yes, no)
+        ey, en = math.exp(yes - m), math.exp(no - m)
+        t3 = self._temp("three_answers")
+        w = [v / t3 for v in z]
+        m3 = max(w)
+        e3 = [math.exp(v - m3) for v in w]
+        s3 = sum(e3)
+        return dict(logits=dict(zip(self.names[:3], z)),
+                    p={"yes": ey / (ey + en), "no": en / (ey + en)},
+                    p_unsure=e3[2] / s3)
+
+    @torch.no_grad()
+    def ask(self, state: str, question: str, true: str, false: str) -> dict:
+        """One closed question. `p` is over yes/no; `p_unsure` is a separate signal to threshold."""
+        h = self._last(self._text(self._fold(state), question, true, false))
+        z = self.model.score(h.to(self.model.score.weight.dtype)).float()[:3].tolist()
+        return self._verdict(z)
+
+    @torch.no_grad()
+    def _pick(self, state: str, question: str, options: list[tuple[str, str]], ask: str,
+              ordinal: bool) -> dict:
+        marks = self._marks_for([o[0] for o in options], ordinal)
+        body = (f"<state>\n{self._fold(state)}\n</state>\n\n{question}\n\n"
+                + "\n".join(f"{m}. {desc}" for m, (_, desc) in zip(marks, options))
+                + f"\n\n{ask}")
+        h = self._last(self._chat(CHOICE_SYSTEM, body, "Answer: "))
+        full = self.model.score(h.to(self.model.score.weight.dtype)).float()
+        z = [float(full[self.col[f"mark_{m}"]]) for m in marks]
+        z = [v / self._temp("scale" if ordinal else "choice") for v in z]
+        e = [math.exp(v - max(z)) for v in z]
+        s = sum(e)
+        ids = [o[0] for o in options]
+        return dict(p=dict(zip(ids, (v / s for v in e))), logits=dict(zip(ids, z)),
+                    marks=dict(zip(ids, marks)))
+
+    def choice(self, state: str, question: str, options: list[tuple[str, str]]) -> dict:
+        """Pick one of 2..16 options. `options` are `(name, description)`; names are yours and do
+        not reach the prompt."""
+        return self._pick(state, question, options, "Answer with one letter.", ordinal=False)
+
+    def scale(self, state: str, question: str, levels: list[tuple[str, str]]) -> dict:
+        """Pick a level of an ordinal rubric. `levels` are `(name, description)` in order."""
+        marks_are_digits = all(str(k).isdigit() for k, _ in levels)
+        ask = ("Answer with the number of the level that rates it." if marks_are_digits
+               else "Answer with the mark of the level that rates it.")
+        return self._pick(state, question, levels, ask, ordinal=True)
+
+    @staticmethod
+    def _snapshot(cache) -> dict:
+        """Copy of the cache state after the prefix.
+
+        A hybrid trunk keeps two kinds of state: attention layers hold keys and values per token
+        and could be cropped; linear-attention layers hold a recurrent summary that cannot. Both
+        are restored from a copy instead.
+        """
+        return {name: [None if t is None else t.clone() for t in getattr(cache, name)]
+                for name in ("conv_states", "recurrent_states", "key_cache", "value_cache")}
+
+    @staticmethod
+    def _restore(cache, snap: dict) -> None:
+        for name, tensors in snap.items():
+            setattr(cache, name, [None if t is None else t.clone() for t in tensors])
+
+    @torch.no_grad()
+    def ask_many(self, state: str, questions: list[tuple[str, str, str]]) -> list[dict]:
+        """Several `(question, true, false)` about one state. The shared prefix is computed once;
+        results equal calling `ask` separately. The split is taken in token space, not in text."""
+        state = self._fold(state)
+        fulls = [self.tok(self._text(state, q, t, f), add_special_tokens=False)["input_ids"]
+                 for q, t, f in questions]
+        n_min = min(len(f) for f in fulls)
+        n = 0
+        while n < n_min and len({f[n] for f in fulls}) == 1:
+            n += 1
+        # Sharing the prefix across a hybrid trunk is not implemented: restoring the recurrent
+        # state of the linear-attention layers from a copy does not reproduce a clean pass.
+        return [self.ask(state, q, t, f) for q, t, f in questions]
+
+        cache = self._cache()
+        dev = self.model.device
+        pre = torch.tensor([fulls[0][:n]], device=dev)
+        self.trunk(input_ids=pre, attention_mask=torch.ones_like(pre),
+                   past_key_values=cache, use_cache=True,
+                   cache_position=torch.arange(n, device=dev))
+        snap = self._snapshot(cache)
+        out = []
+        for full in fulls:
+            self._restore(cache, snap)
+            ids = torch.tensor([full[n:]], device=dev)
+            h = self.trunk(input_ids=ids, past_key_values=cache, use_cache=True,
+                           cache_position=torch.arange(n, len(full), device=dev),
+                           attention_mask=torch.ones(1, len(full), device=dev, dtype=torch.long))
+            z = self.model.score(h.last_hidden_state[0, -1].to(self.model.score.weight.dtype))
+            out.append(self._verdict(z.float()[:3].tolist()))
+        return out
+
+    def _cache(self):
+        """The cache class this trunk needs. A plain `DynamicCache` does not fit a hybrid one."""
+        from transformers import DynamicCache
+
+        mod = type(self.model).__module__
+        for name in ("Qwen3_5DynamicCache", "Qwen3NextDynamicCache"):
+            cls = getattr(__import__(mod, fromlist=[name]), name, None)
+            if cls is not None:
+                return cls(self.model.config.get_text_config())
+        return DynamicCache()

typecastlm/remote.py

@@ -0,0 +1,227 @@
+"""HTTP client: a question about a state, an answer in numbers.
+
+    noul(state, instructions, true, false)   -> Answer(prob, margin, unknown, logits, p)
+    tfu(state, instructions, true, false)    -> Ternary(p, verdict, confidence, logits)
+    choice(state, instructions, options)     -> Choice(p, verdict, confidence, logits)
+    scale(state, instructions, levels)       -> Choice, for an ordinal rubric
+    ask(state, questions)                    -> the service body, any number of questions
+
+`noul` matches the hosted service field for field. The rest are extensions: `unknown` is returned
+whether or not the question asks for it, `logits` are raw, and option names in `choice` and
+`scale` come back as the keys of `p`.
+
+The service holds the weights; this package depends on `requests` only.
+"""
+from __future__ import annotations
+
+import math
+import os
+import time
+from dataclasses import dataclass
+
+DEFAULT_ENDPOINT = ""          # no hosted service; set one or run `typecastlm-serve`
+RETRY_CODES = (408, 429, 500, 502, 503, 504, 529)
+
+
+@dataclass
+class Ternary:
+    """What `tfu` returns: the three probabilities and which one leads."""
+
+    p: dict[str, float]
+    verdict: str
+    confidence: float
+    logits: dict[str, float]
+    ms: float
+    input_tokens: int
+    model: str
+
+
+@dataclass
+class Choice:
+    """What `choice` and `scale` return: a probability per option and which one leads. Keys are
+    the option names from the request."""
+
+    p: dict[str, float]
+    verdict: str
+    confidence: float
+    logits: dict[str, float]
+    ms: float
+    input_tokens: int
+    model: str
+
+
+@dataclass
+class Answer:
+    """What `noul` returns. `prob`, `margin`, `ms`, `input_tokens`, `model` are the service\'s
+    fields; `unknown`, `logits` and `p` are extensions."""
+
+    prob: float
+    margin: float
+    ms: float
+    input_tokens: int
+    model: str
+    unknown: float = 0.0
+    logits: dict[str, float] | None = None
+    p: dict[str, float] | None = None
+
+
+class Client:
+    """One question, one state, three numbers — answered by the service.
+
+    The key is read from `TYPECASTLM_API_KEY` unless one is passed. A connection is kept open for
+    the life of the client: a fresh one per request means a name lookup per request, and a few
+    dozen of those at once is how a fast service starts looking slow.
+    """
+
+    def __init__(self, endpoint: str | None = None, api_key: str | None = None,
+                 model: str = "typecastlm-qwen3.5-3.8b", timeout: float = 10.0, retries: int = 5,
+                 pool: int = 32, temperature: float | None = None, calibrated: bool = True):
+        """`temperature` overrides the checkpoint\'s per-mode temperatures; `calibrated=False`
+        disables them. Temperatures are applied here because the service returns logits, so an
+        answer can be re-read at another temperature without asking again. They change no
+        ordering, only confidence."""
+        import requests
+        from requests.adapters import HTTPAdapter
+
+        self.endpoint = endpoint or os.environ.get("TYPECASTLM_ENDPOINT", DEFAULT_ENDPOINT)
+        if not self.endpoint:
+            raise ValueError(
+                "no endpoint. Pass Client(endpoint=...), set TYPECASTLM_ENDPOINT, or run the "
+                "model yourself: `pip install \"typecastlm[server]\"` and `typecastlm-serve`, or "
+                "`pip install \"typecastlm[local]\"` and use typecastlm.Reader in this process")
+        self.key = api_key or os.environ.get("TYPECASTLM_API_KEY", "")
+        self.model, self.timeout, self.retries = model, timeout, retries
+        self._s = requests.Session()
+        self._s.mount("https://", HTTPAdapter(pool_connections=pool, pool_maxsize=pool))
+        self._requests = requests
+        # The calibration travels with the service's answer: it belongs to the checkpoint, not to
+        # the client. A temperature passed here overrides it, `calibrated=False` turns it off.
+        if temperature is not None and temperature <= 0:
+            raise ValueError(f"temperature must be positive, got {temperature}")
+        self.calibrated = calibrated
+        self.temperature = temperature
+        self.calibration: dict = {}
+
+    def _temp(self, mode: str) -> float:
+        """The temperature for a mode: the caller's, then the checkpoint's, then none."""
+        if self.temperature is not None:
+            return float(self.temperature)
+        if not self.calibrated:
+            return 1.0
+        return float(((self.calibration or {}).get(mode) or {}).get("temperature", 1.0))
+
+    def _post(self, body: dict) -> tuple[dict, float]:
+        delay = 1.0
+        for attempt in range(self.retries + 1):
+            t0 = time.perf_counter()
+            try:
+                headers = {"Authorization": f"Bearer {self.key}"} if self.key else {}
+                r = self._s.post(self.endpoint, json=body, headers=headers, timeout=self.timeout)
+                ms = (time.perf_counter() - t0) * 1000.0
+                if r.status_code == 200:
+                    return r.json(), ms
+                if r.status_code not in RETRY_CODES or attempt == self.retries:
+                    raise RuntimeError(f"HTTP {r.status_code}: {r.text[:300]}")
+            except self._requests.RequestException:
+                if attempt == self.retries:
+                    raise
+            ra = None
+            time.sleep(float(ra) if ra else delay)
+            delay = min(delay * 2, 30.0)
+        raise RuntimeError("unreachable")
+
+    def _soft(self, logits: dict, mode: str) -> dict[str, float]:
+        """Softmax over one mode\'s outputs, at that mode\'s temperature."""
+        v = {n: z / self._temp(mode) for n, z in logits.items()}
+        m = max(v.values())
+        e = {n: math.exp(x - m) for n, x in v.items()}
+        s = sum(e.values())
+        return {n: x / s for n, x in e.items()}
+
+    def choice(self, state: str, instructions: str, options: dict[str, str]) -> "Choice":
+        """Pick one of several options. Option names are yours and do not reach the prompt."""
+        return self._pick(state, instructions, options, "choice")
+
+    def scale(self, state: str, instructions: str, levels: dict[str, str]) -> "Choice":
+        """Pick a level of an ordinal rubric."""
+        return self._pick(state, instructions, levels, "score")
+
+    def _pick(self, state: str, instructions: str, options: dict[str, str], kind: str) -> "Choice":
+        if len(options) < 2:
+            raise ValueError(f"{kind} takes at least two options")
+        q = {"type": kind, "instructions": instructions, "criteria": dict(options)}
+        data, ms = self._post({"state": state, "model": self.model, "questions": {"q": q}})
+        self.calibration = data.get("calibration", self.calibration)
+        z = data["answers"]["q"]["logits"]
+        p = self._soft(z, "scale" if kind == "score" else "choice")
+        lead = max(p, key=p.get)
+        return Choice(p=p, verdict=lead, confidence=p[lead], logits=z, ms=ms,
+                      input_tokens=int(data.get("usage", {}).get("input_tokens", 0)),
+                      model=str(data.get("model", self.model)))
+
+    def _three(self, logits: dict, mode: str = "ternary") -> dict[str, float]:
+        """Three probabilities from three logits, calibrated for the mode asked for."""
+        key = {"ternary": "three_answers", "binary": "verdict"}.get(mode, mode)
+        v = {n: z / self._temp(key) for n, z in logits.items()}
+        m = max(v.values())
+        e = {n: math.exp(x - m) for n, x in v.items()}
+        s = sum(e.values())
+        return {n: x / s for n, x in e.items()}
+
+    def tfu(self, state: str, instructions: str, true: str | None = None,
+            false: str | None = None) -> Ternary:
+        """The three answers, unreduced — our type, beside the compatible one.
+
+        The criteria are still two: `unknown` is not something anyone states, it is what is left
+        when neither of the two fits. The temperature of this client applies here as well.
+        """
+        q: dict = {"type": "tfu", "instructions": instructions}
+        if true is not None or false is not None:
+            q["criteria"] = {"true": true or "", "false": false or ""}
+        data, ms = self._post({"state": state, "model": self.model, "questions": {"q": q}})
+        self.calibration = data.get("calibration", self.calibration)
+        a = data["answers"]["q"]
+        z = a["logits"]
+        p = self._three(z, "ternary")
+        lead = max(p, key=p.get)
+        return Ternary(p=p, verdict=lead, confidence=p[lead], logits=z, ms=ms,
+                       input_tokens=int(data.get("usage", {}).get("input_tokens", 0)),
+                       model=str(data.get("model", self.model)))
+
+    def ask(self, state: str, questions: dict) -> dict:
+        """Any number of questions about one state. The state is read once for the bundle;
+        results equal asking one by one."""
+        if not questions:
+            raise ValueError("no questions")
+        data, _ = self._post({"state": state, "model": self.model, "questions": questions})
+        self.calibration = data.get("calibration", self.calibration)
+        return {"answers": data["answers"],
+                "input_tokens": int(data.get("usage", {}).get("input_tokens", 0))}
+
+    def noul(self, state: str, instructions: str, true: str | None = None,
+             false: str | None = None) -> Answer:
+        """One closed question. `margin` is the log-odds, so a saturated probability still ranks."""
+        q: dict = {"type": "noul", "instructions": instructions}
+        if true is not None or false is not None:
+            q["criteria"] = {"true": true or "", "false": false or ""}
+        data, ms = self._post({"state": state, "model": self.model, "questions": {"q": q}})
+        self.calibration = data.get("calibration", self.calibration)
+        a = data["answers"]["q"]
+        z = a.get("logits")
+        if z:
+            # From logits everything follows exactly: the margin is a difference, not the logarithm of
+            # a rounded probability, so on confident documents it does not hit a clamp.
+            names = list(z)
+            p3 = self._three(z, "binary")
+            decided = p3[names[0]] + p3[names[1]]
+            prob = p3[names[0]] / decided if decided > 0 else 0.5
+            margin = (z[names[0]] - z[names[1]]) / self._temp("verdict")
+            unknown = p3[names[2]] if len(names) > 2 else 0.0
+        else:                                   # the service sent a probability and nothing else
+            prob = float(a["noul"])
+            pc = min(max(prob, 1e-6), 1 - 1e-6)
+            margin, unknown, p3 = math.log(pc / (1 - pc)), float(a.get("unknown", 0.0)), None
+        return Answer(prob=prob, margin=margin, ms=ms,
+                      input_tokens=int(data.get("usage", {}).get("input_tokens", 0)),
+                      model=str(data.get("model", self.model)),
+                      unknown=unknown, logits=z, p=p3)