thx02 1.0.0__py3-none-any.whl

thx02/__init__.py

@@ -0,0 +1,38 @@
+"""THX-02: a decision model. Typed questions in, calibrated probabilities out, optional short thinking.
+
+    pip install thx02                  # API client and the `thx02` command (no dependencies, works in Termux)
+    pip install "thx02[local]"         # also run the model on your own GPU or CPU
+
+    from thx02 import Client
+    thx = Client()                     # reads HALX_API_KEY
+    thx.decide("I was charged twice", {"team": thx.choice("Which team?", billing="Charges", shipping="Deliveries")})
+
+    from thx02 import THX02            # local model (needs the [local] extra)
+    m = THX02.load("HAL-X-AI/THX-02")
+"""
+from .client import APIError, Client, choice, image, noul, score
+
+__version__ = "1.0.0"
+
+_LOCAL = {
+    "THX02": "runtime", "Decider": "model", "FastOptions": "model", "THXDecisionModel": "model",
+    "DEFAULT_MAX_LENGTH": "model", "MAX_OPTIONS": "protocol", "LengthError": "protocol", "RequestError": "protocol",
+    "answer": "protocol", "options": "protocol", "Answer": "types", "Question": "types", "Request": "types",
+    "Response": "types", "Usage": "types",
+}
+
+
+def __getattr__(name):
+    """The local model classes import torch, so they load only when first used."""
+    module = _LOCAL.get(name)
+    if module is None:
+        raise AttributeError(f"module 'thx02' has no attribute {name!r}")
+    try:
+        from . import _local  # noqa: F401
+    except ImportError as e:
+        raise ImportError(f"thx02.{name} runs the model locally and needs the extra: pip install \"thx02[local]\" ({e})") from e
+    import importlib
+    return getattr(importlib.import_module(f".{module}", __name__), name)
+
+
+__all__ = ["APIError", "Client", "choice", "image", "noul", "score", "__version__", *_LOCAL]

thx02/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

thx02/_local.py

@@ -0,0 +1,17 @@
+"""Imported on first use of the local model classes: torch setup that the API client never needs."""
+import logging
+import os
+import sys
+
+import torch
+
+if os.environ.get("THX02_DEVICE") == "cpu" or not torch.cuda.is_available():
+    sys.modules.setdefault("fla", None)  # GPU-only Triton kernels: use the PyTorch linear-attention path
+
+
+class _QuietTypeCheck(logging.Filter):  # config.json is THX-02's own; the backbone config sits inside it
+    def filter(self, record):
+        return "model of type `thx02`" not in record.getMessage()
+
+
+logging.getLogger("transformers.configuration_utils").addFilter(_QuietTypeCheck())

thx02/build_thinker.py

@@ -0,0 +1,50 @@
+"""Build the THX-02 thinker for vLLM: decision weights + think LoRA merged, plus the MTP head for speculative decoding.
+
+  python -m thx02.build_thinker --model . --out thinker-merged
+  vllm serve thinker-merged --served-model-name thx02-thinker --max-model-len 8192 \\
+      --speculative-config '{"method":"mtp","num_speculative_tokens":3}'   # add --quantization fp8 on 24 GB GPUs
+
+The thinker writes the short reasoning notes; decisions are always read by THX-02 itself.
+"""
+import argparse
+import json
+import shutil
+from pathlib import Path
+
+
+def main(argv=None):
+    from safetensors import safe_open
+    from safetensors.torch import load_file, save_file
+    ap = argparse.ArgumentParser(prog="thx02-build-thinker")
+    ap.add_argument("--model", default=".")
+    ap.add_argument("--out", default="thinker-merged")
+    a = ap.parse_args(argv)
+    root, out = Path(a.model), Path(a.out)
+    th = root / "thinker"
+    out.mkdir(parents=True, exist_ok=True)
+    sd = {}
+    with safe_open(str(root / "model.safetensors"), "pt") as fh:
+        for k in fh.keys():
+            sd[k] = fh.get_tensor(k)
+    acfg = json.loads((th / "adapter_config.json").read_text())
+    scale = acfg["lora_alpha"] / acfg["r"]
+    lw = load_file(str(th / "adapter_model.safetensors"))
+    merged = 0
+    for k, A in lw.items():
+        if ".lora_A." not in k:
+            continue
+        B = lw[k.replace(".lora_A.", ".lora_B.")]
+        name = k.replace("base_model.model.", "").replace(".lora_A.weight", ".weight")
+        W = sd[name]
+        sd[name] = (W.float() + scale * (B.float() @ A.float())).to(W.dtype)
+        merged += 1
+    out_sd = {"model." + k: v.contiguous() for k, v in sd.items()}
+    out_sd.update(load_file(str(th / "mtp.safetensors")))
+    save_file(out_sd, str(out / "model.safetensors"), metadata={"format": "pt"})
+    for f in (th / "lm_config").iterdir():
+        shutil.copy(f, out / f.name)
+    print(f"merged {merged} LoRA modules; thinker written to {out}")
+
+
+if __name__ == "__main__":
+    main()

thx02/cli.py

@@ -0,0 +1,213 @@
+"""`thx02`: THX decisions from any terminal, including Termux on Android.
+
+  thx02 "I was charged twice, refund please" --choice team=billing,support,sales --yesno "Refund request?"
+  thx02 "Income 4200, debts 2800, limit 50%. Pass?" --choice verdict=pass,fail --think on --thoughts
+  thx02 --image receipt.jpg --yesno "Is the receipt legible?"
+  thx02 --batch tickets.txt --choice team=billing,shipping > answers.jsonl
+  thx02                     interactive: type states, get decisions
+  thx02 models              models your key can use
+  thx02 serve ...           run your own THX-02 server (pip install "thx02[server]")
+
+The API key comes from --key or $HALX_API_KEY. --local runs the model on this machine (pip install "thx02[local]").
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+
+from . import __version__
+from .client import APIError, Client, image, top
+
+RUBY, DIM, BOLD, RESET = "\033[38;2;226;23;102m", "\033[2m", "\033[1m", "\033[0m"
+
+
+def _color() -> bool:
+    return sys.stdout.isatty() and not os.environ.get("NO_COLOR")
+
+
+def _options(spec: str, flag: str):
+    if "=" not in spec:
+        raise SystemExit(f"{flag} needs NAME=option1,option2 (got {spec!r})")
+    name, opts = spec.split("=", 1)
+    items = [o.strip() for o in opts.split(",") if o.strip()]
+    if len(items) < 2:
+        raise SystemExit(f"{flag} {name}: give at least two options")
+    return name.strip(), items
+
+
+def build_questions(a) -> dict:
+    qs = {}
+    for spec in a.choice or []:
+        name, items = _options(spec, "--choice")
+        crit = {}
+        for it in items:  # "key:description" or just "key"
+            k, _, d = it.partition(":")
+            crit[k.strip()] = (d or k).strip()
+        qs[name] = {"type": "choice", "instructions": a.instructions or f"Which {name} applies?", "criteria": crit}
+    for spec in a.score or []:
+        name, items = _options(spec, "--score")
+        qs[name] = {"type": "score", "instructions": a.instructions or f"How would you rate the {name}?", "criteria": items}
+    for i, text in enumerate(a.yesno or []):
+        name = text.strip().rstrip("?")[:60]  # the question itself labels its answer
+        qs[name if name not in qs else f"{name} ({i + 1})"] = {"type": "noul", "instructions": text}
+    if a.questions:
+        raw = open(a.questions, encoding="utf-8").read() if os.path.exists(a.questions) else a.questions
+        qs.update(json.loads(raw))
+    return qs or {"intent": {"type": "choice", "instructions": "What does the user want?", "criteria": {
+        "question": "Asks a question", "complaint": "Complains about something", "request": "Asks for an action",
+        "other": "Something else"}}}
+
+
+def show(out: dict, color: bool) -> None:
+    r, d, b, x = (RUBY, DIM, BOLD, RESET) if color else ("", "", "", "")
+    for name, a in out.get("answers", {}).items():
+        if a.get("type") == "noul":
+            dist = {"yes": a["noul"], "no": 1 - a["noul"]}
+        else:
+            legend = a.get("legend") or {}
+            dist = {legend.get(k, k): v for k, v in a.get("probabilities", {}).items()}
+        best, _ = top(a)
+        print(f"\n{b}{name}{x}")
+        for k, p in sorted(dist.items(), key=lambda kv: -kv[1]):
+            bar = "█" * round(p * 24)
+            mark = f"{r}›{x}" if k == best else " "
+            print(f"  {mark} {k[:24]:24s} {r if k == best else d}{bar:24s}{x} {p * 100:5.1f}%")
+        if a.get("thought"):
+            print(f"  {d}thought:{x} {a['thought']}")
+    usage = out.get("usage") or {}
+    extra = f" · {usage.get('thoughts')} thought(s)" if usage.get("thoughts") else ""
+    print(f"\n{d}{out.get('model', '')} · {out.get('latency_ms', '?')} ms{extra}{x}")
+
+
+def _local_runner(path: str):
+    os.environ.setdefault("THX02_DEVICE", "cpu")
+    try:
+        import torch
+        from . import THX02
+    except ImportError:
+        raise SystemExit('--local needs the model runtime: pip install "thx02[local]"') from None
+    device = "cuda" if torch.cuda.is_available() and os.environ.get("THX02_DEVICE") != "cpu" else "cpu"
+    print(f"loading THX-02 on {device} ...", file=sys.stderr)
+    m = THX02.load(path, device=device)
+    return lambda body: m.decide(body["state"], body["questions"], images=body.get("images"), think=False,
+                                 tta=body.get("tta"))
+
+
+def main(argv=None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv[:1] == ["serve"]:
+        try:
+            from .serve import main as serve_main
+        except ImportError:
+            raise SystemExit('thx02 serve needs the server extra: pip install "thx02[server]"') from None
+        sys.argv = ["thx02-serve", *argv[1:]]
+        return serve_main() or 0
+
+    ap = argparse.ArgumentParser(prog="thx02", description="THX decisions from the terminal (api.hal-x.ai or local).",
+                                 epilog="Docs: https://api.hal-x.ai/docs/thx-02/")
+    ap.add_argument("state", nargs="?", help='text to decide about, or "models"; omit for interactive mode')
+    ap.add_argument("--choice", action="append", metavar="NAME=a,b,c", help="pick one option (a:description works too)")
+    ap.add_argument("--yesno", action="append", metavar="QUESTION", help="yes / no question")
+    ap.add_argument("--score", action="append", metavar="NAME=low,mid,high", help="ordered scale, lowest first")
+    ap.add_argument("--instructions", "-i", help="question text for --choice / --score")
+    ap.add_argument("--questions", "-q", help="questions as JSON (a string or a file)")
+    ap.add_argument("--image", action="append", help="image file to include (up to 4)")
+    ap.add_argument("--think", choices=["off", "auto", "on"], default="off", help="thinking mode (default off)")
+    ap.add_argument("--thoughts", action="store_true", help="show the thoughts")
+    ap.add_argument("--tta", type=int, choices=[1, 4], help="read choice options in 4 orders and average")
+    ap.add_argument("--batch", metavar="FILE", help="one state per line (or JSONL with a state field); prints JSONL")
+    ap.add_argument("--model", default=os.environ.get("THX_MODEL", "thx-02"), help="thx-02 (default) or thx-01")
+    ap.add_argument("--key", help="API key (default $HALX_API_KEY)")
+    ap.add_argument("--server", default=os.environ.get("HALX_BASE_URL"), help="API base URL (default https://api.hal-x.ai)")
+    ap.add_argument("--local", metavar="MODEL", help="run on this machine: a THX-02 folder or HAL-X-AI/THX-02")
+    ap.add_argument("--json", action="store_true", help="print raw JSON")
+    ap.add_argument("--version", action="version", version=f"thx02 {__version__}")
+    a = ap.parse_args(argv)
+    color = _color() and not a.json
+
+    client = Client(api_key=a.key, base_url=a.server, model=a.model)
+    if a.state == "models" and not a.local:
+        try:
+            print("\n".join(client.models()))
+        except APIError as e:
+            print(f"error: {e}", file=sys.stderr)
+            return 1
+        return 0
+
+    qs = build_questions(a)
+    images = [image(f) for f in (a.image or [])][:4]
+    think = {"off": False, "auto": "auto", "on": True}[a.think]
+    run_local = _local_runner(a.local) if a.local else None
+
+    def body_for(state):
+        b = {"state": state, "questions": qs}
+        if images:
+            b["images"] = images
+        if think:
+            b["think"] = think
+        if a.thoughts:
+            b["return_thoughts"] = True
+        if a.tta:
+            b["tta"] = a.tta
+        return b
+
+    def ask(state) -> int:
+        t0 = time.time()
+        try:
+            if run_local:
+                out = run_local(body_for(state))
+            else:
+                b = body_for(state)
+                out = client.decide(b["state"], b["questions"], images=b.get("images"), think=think,
+                                    return_thoughts=a.thoughts, tta=a.tta)
+        except APIError as e:
+            print(f"error: {e}", file=sys.stderr)
+            if e.status == 401 and not client.api_key:
+                print("Set your key: export HALX_API_KEY=sk-...  (or --key). Docs: https://api.hal-x.ai/docs/thx-02/", file=sys.stderr)
+            return 1
+        out.setdefault("latency_ms", round((time.time() - t0) * 1000))
+        if a.json:
+            print(json.dumps(out, ensure_ascii=False, indent=2))
+        else:
+            show(out, color)
+        return 0
+
+    if a.batch:
+        lines = [ln.strip() for ln in open(a.batch, encoding="utf-8") if ln.strip()]
+        states = [json.loads(ln).get("state", "") if ln.startswith("{") else ln for ln in lines]
+        for i in range(0, len(states), 256):
+            chunk = states[i:i + 256]
+            try:
+                results = client.batch([body_for(s) for s in chunk])
+            except APIError as e:
+                print(f"error: {e}", file=sys.stderr)
+                return 1
+            for s, res in zip(chunk, results):
+                print(json.dumps({"state": s, **res}, ensure_ascii=False))
+        return 0
+
+    if a.state is not None:
+        return ask(a.state)
+    if images:
+        return ask("")
+    if not sys.stdin.isatty():
+        return ask(sys.stdin.read().strip())
+    r, d, x = (RUBY, DIM, RESET) if color else ("", "", "")
+    print(f"{r}THX-02{x} interactive · questions: {', '.join(qs)} · empty line to quit")
+    while True:
+        try:
+            s = input(f"\n{d}state>{x} ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            break
+        if not s:
+            break
+        ask(s)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

thx02/client.py

@@ -0,0 +1,193 @@
+"""THX-02 API client. Standard library only, so it installs anywhere Python runs (servers, laptops, Termux).
+
+    from thx02 import Client, choice, noul, score
+
+    thx = Client()                                   # API key from HALX_API_KEY
+    out = thx.decide(
+        "Salam, kartımdan iki dəfə pul çıxılıb, geri qaytarın zəhmət olmasa.",
+        {"team": choice("Which team should handle this?", billing="Charges and refunds", support="Technical problems"),
+         "refund": noul("Does the customer ask for a refund?"),
+         "anger": score("How frustrated is the customer?", ["calm", "annoyed", "angry"])},
+        think="auto",
+    )
+    out["answers"]["team"]["choice"]                 # "billing"
+"""
+from __future__ import annotations
+
+import base64
+import json
+import mimetypes
+import os
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Union
+
+DEFAULT_BASE_URL = "https://api.hal-x.ai"
+DEFAULT_MODEL = "thx-02"
+RETRY_STATUS = {429, 502, 503, 504}
+USER_AGENT = "thx02-python/1.0.0"
+
+
+class APIError(Exception):
+    """An error answer from the API (or the network). `status` is the HTTP status (0 for network errors)."""
+
+    def __init__(self, status: int, message: str, code: str = "", request_id: str = "", body: Any = None):
+        super().__init__(f"{status} {code}: {message}" if code else f"{status}: {message}")
+        self.status, self.message, self.code, self.request_id, self.body = status, message, code, request_id, body
+
+
+# ------------------------------------------------------------------ question builders
+
+def choice(instructions: str, options: Union[Dict[str, str], Sequence[str], None] = None, **described: str) -> dict:
+    """One option out of a list. Options as a dict {key: description}, a list of keys, or keyword arguments."""
+    if options is None:
+        options = {}
+    crit = {str(o): str(o) for o in options} if not isinstance(options, dict) else dict(options)
+    crit.update(described)
+    if len(crit) < 2:
+        raise ValueError("a choice question needs at least two options")
+    return {"type": "choice", "instructions": instructions, "criteria": crit}
+
+
+def noul(instructions: str) -> dict:
+    """A yes / no question; the answer is the probability of yes."""
+    return {"type": "noul", "instructions": instructions}
+
+
+def score(instructions: str, levels: Sequence[str]) -> dict:
+    """An ordered scale, lowest level first."""
+    if len(levels) < 2:
+        raise ValueError("a score question needs at least two levels")
+    return {"type": "score", "instructions": instructions, "criteria": [str(x) for x in levels]}
+
+
+def image(source: Union[str, Path, bytes], mime: Optional[str] = None) -> str:
+    """A data URI from a file path or raw bytes (PNG, JPEG, WebP). Data URIs and http(s) strings pass through."""
+    if isinstance(source, str) and source.startswith(("data:", "http://", "https://")):
+        return source
+    if isinstance(source, (str, Path)):
+        mime = mime or mimetypes.guess_type(str(source))[0] or "image/jpeg"
+        source = Path(source).expanduser().read_bytes()
+    return f"data:{mime or 'image/jpeg'};base64," + base64.b64encode(source).decode()
+
+
+def top(answer: dict):
+    """(label, probability) of the most likely option of one answer."""
+    if answer.get("type") == "noul":
+        p = float(answer["noul"])
+        return ("yes", p) if p >= 0.5 else ("no", 1 - p)
+    probs = answer.get("probabilities") or {}
+    best = max(probs, key=probs.get)
+    label = (answer.get("legend") or {}).get(best, best)
+    return label, float(probs[best])
+
+
+# ------------------------------------------------------------------ client
+
+class Client:
+    """Calls THX models on api.hal-x.ai (or any THX-02 server with base_url).
+
+    api_key   defaults to $HALX_API_KEY (or $THX_API_KEY). Without one, only the free tier answers (per-IP limits).
+    base_url  defaults to $HALX_BASE_URL or https://api.hal-x.ai. A self-hosted `thx02-serve` works too.
+    model     "thx-02" (default) or "thx-01".
+    """
+
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, model: str = DEFAULT_MODEL,
+                 timeout: float = 120.0, max_retries: int = 3):
+        self.api_key = api_key or os.environ.get("HALX_API_KEY") or os.environ.get("THX_API_KEY") or ""
+        self.base_url = (base_url or os.environ.get("HALX_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.model, self.timeout, self.max_retries = model, timeout, max_retries
+
+    # -- public API
+
+    def decide(self, state: Any, questions: Dict[str, dict], *, images: Optional[Iterable] = None,
+               think: Union[bool, str] = False, return_thoughts: bool = False, tta: Optional[int] = None,
+               model: Optional[str] = None) -> dict:
+        """One state, its questions. Returns {"model", "answers", "usage", "latency_ms"}.
+
+        think: False (direct), "auto" (think only when unsure and reasoning helps) or True (think on nearly every question).
+        images: up to 4 paths, bytes or data URIs. tta: 4 reads choice options in four orders and averages.
+        """
+        body = self._body(state, questions, images, think, return_thoughts, tta)
+        body["model"] = model or self.model
+        return self._post("/v1/decide", body)
+
+    def batch(self, items: Sequence[Union[dict, tuple]], *, model: Optional[str] = None, **defaults) -> List[dict]:
+        """Up to 1,024 states in one call. Items are dicts (state, questions, images, think, ...) or (state, questions)
+        pairs; keyword arguments (think=..., tta=...) apply to every item. Failed items come back as {"error": ...}."""
+        out_items = []
+        for it in items:
+            if isinstance(it, tuple):
+                it = {"state": it[0], "questions": it[1]}
+            merged = {**defaults, **it}
+            out_items.append(self._body(merged.get("state", ""), merged["questions"], merged.get("images"),
+                                        merged.get("think", False), merged.get("return_thoughts", False), merged.get("tta")))
+        return self._post("/v1/decide/batch", {"model": model or self.model, "items": out_items})["results"]
+
+    def models(self) -> List[str]:
+        """Model ids your key can use."""
+        return [m["id"] for m in self._request("GET", "/v1/models").get("data", [])]
+
+    choice, noul, score, image, top = staticmethod(choice), staticmethod(noul), staticmethod(score), staticmethod(image), staticmethod(top)
+
+    # -- internals
+
+    @staticmethod
+    def _body(state, questions, images, think, return_thoughts, tta) -> dict:
+        if not isinstance(questions, dict) or not questions:
+            raise ValueError("questions must be a non-empty dict of named questions")
+        body: Dict[str, Any] = {"state": state, "questions": questions}
+        imgs = [image(i) for i in (images or [])]
+        if imgs:
+            body["images"] = imgs
+        if think:
+            body["think"] = think
+        if return_thoughts:
+            body["return_thoughts"] = True
+        if tta:
+            body["tta"] = int(tta)
+        return body
+
+    def _post(self, path: str, body: dict) -> dict:
+        return self._request("POST", path, body)
+
+    def _request(self, method: str, path: str, body: Optional[dict] = None) -> dict:
+        data = json.dumps(body, ensure_ascii=False).encode() if body is not None else None
+        headers = {"Content-Type": "application/json", "Accept": "application/json", "User-Agent": USER_AGENT}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        delay = 0.5
+        for attempt in range(self.max_retries + 1):
+            req = urllib.request.Request(self.base_url + path, data=data, headers=headers, method=method)
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as r:
+                    return json.loads(r.read().decode("utf-8"))
+            except urllib.error.HTTPError as e:
+                raw = e.read().decode("utf-8", "replace")
+                if e.code in RETRY_STATUS and attempt < self.max_retries:
+                    retry_after = e.headers.get("Retry-After")
+                    time.sleep(min(float(retry_after), 30.0) if retry_after and retry_after.isdigit() else delay)
+                    delay *= 2
+                    continue
+                raise _api_error(e.code, raw, e.headers.get("X-Request-ID", "")) from None
+            except (urllib.error.URLError, TimeoutError, ConnectionError) as e:
+                if attempt < self.max_retries:
+                    time.sleep(delay)
+                    delay *= 2
+                    continue
+                raise APIError(0, f"cannot reach {self.base_url}: {getattr(e, 'reason', e)}") from None
+        raise APIError(0, "unreachable")  # pragma: no cover
+
+
+def _api_error(status: int, raw: str, request_id: str) -> APIError:
+    try:
+        body = json.loads(raw)
+    except ValueError:
+        return APIError(status, raw.strip()[:300] or "error", request_id=request_id)
+    err = body.get("error", body) if isinstance(body, dict) else body
+    if isinstance(err, dict):
+        return APIError(status, str(err.get("message") or err), str(err.get("code") or ""),
+                        str(body.get("request_id") or request_id), body)
+    return APIError(status, str(err), request_id=request_id, body=body)

thx02/engine.py

@@ -0,0 +1,77 @@
+"""Request planning shared by the local runtime and the server: option-order averaging, the joint-read rule and
+the pieces of self-gated thinking (gate question, think prompt, re-read with the thought)."""
+from __future__ import annotations
+
+import json
+import math
+
+from .protocol import DEFAULT_INSTRUCTIONS, describe, options
+
+THINK_SYSTEM = "You reason briefly about decisions. Think in at most 60 words, only what decides the answer."
+THOUGHT_NOTE = "\n\nReasoning notes (may contain mistakes): "
+GATE_QUESTION = ("Would a careful person need to work this out step by step (calculation, logic puzzle, code tracing, "
+                 "multi-hop reasoning) rather than just read, recognise or classify it?")
+
+# thinking presets: "auto" = Decision Index setting (thinks only when unsure and the question needs reasoning),
+# True = think on nearly every question
+AUTO = {"tau": 0.6, "gate": 0.2, "alpha": 0.7, "cap": 96}
+ALWAYS = {"tau": 0.97, "gate": 0.0, "alpha": 0.5, "cap": 320}
+
+
+def orders(n: int, k: int) -> list[list[int]]:
+    """Identity, reversed, then cyclic shifts of n options; the first k distinct orders."""
+    out = [list(range(n)), list(range(n))[::-1]] + [[(i + s) % n for i in range(n)] for s in range(1, n)]
+    seen, uniq = set(), []
+    for o in out:
+        if tuple(o) not in seen:
+            seen.add(tuple(o))
+            uniq.append(o)
+    return uniq[:k]
+
+
+def facet_joint(questions: dict) -> bool:
+    """Read jointly when several questions apply the same criteria to different items with plain-text instructions
+    (select-all candidates, aspect/sentiment pairs, per-entity labels); otherwise one question per request."""
+    v = list(questions.values())
+    return (len(v) > 1 and all(isinstance(q.get("instructions"), str) for q in v) and len({q.get("type") for q in v}) == 1
+            and len({json.dumps(q.get("criteria"), sort_keys=True) for q in v}) == 1)
+
+
+def permuted(q: dict, order: list[int]) -> dict:
+    crit = q["criteria"]
+    keys, vals = list(crit), list(crit.values())
+    return {**q, "criteria": {keys[i]: vals[i] for i in order}}
+
+
+def distribution(a: dict, keys: list[str]) -> list[float]:
+    if a["type"] == "noul":
+        return [a["noul"] if x == "true" else 1 - a["noul"] for x in keys]
+    return [a["probabilities"][x] for x in keys]
+
+
+def geo_mean(ps: list[list[float]]) -> list[float]:
+    m = [math.exp(sum(math.log(max(p[i], 1e-9)) for p in ps) / len(ps)) for i in range(len(ps[0]))]
+    z = sum(m)
+    return [x / z for x in m]
+
+
+def gate_request(state, q: dict) -> dict:
+    """Cheap yes/no request: does question q need step-by-step reasoning? Uses a short state excerpt."""
+    _, desc = options(q)
+    text = ("Question: " + describe(q.get("instructions") or "Choose the best matching option.") + "\nOptions:\n" +
+            "\n".join(str(x)[:200] for x in desc[:12]) + "\n\nContext excerpt:\n" + describe(state)[:1200])
+    return {"state": text, "questions": {"g": {"type": "noul", "instructions": GATE_QUESTION}}}
+
+
+def think_body(enc, request: dict) -> str:
+    """User text of the think pass (the format the think adapter was trained on): state, one question, coded options."""
+    (key, q), = request["questions"].items()
+    _, desc = options(q)
+    return ("State:\n" + enc._text(request["state"]) + "\n\nQuestion:\n" + enc._text(q.get("instructions") or DEFAULT_INSTRUCTIONS)
+            + "\nOptions:\n" + "\n".join(f"{c}: {enc._text(t)}" for c, t in zip(enc.codes, desc)))
+
+
+def with_thought(q: dict, thought: str) -> dict:
+    q = dict(q)
+    q["instructions"] = describe(q.get("instructions") or "Choose the best matching option.") + THOUGHT_NOTE + thought.strip()
+    return q