simthinkd 0.3.0__tar.gz → 0.5.0__tar.gz

{simthinkd-0.3.0/src/simthinkd.egg-info → simthinkd-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simthinkd
-Version: 0.3.0
+Version: 0.5.0
 Summary: A 265k-parameter decision model that picks one action in about 2 ms on one CPU core, inside real-time loops.
 Author: Myeongseongsimjae AX Institute
 License: Apache-2.0
@@ -38,7 +38,7 @@ Dynamic: license-file
   <img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+">
   <a href="https://github.com/MSSJ-AI-ORG/simthinkd/actions/workflows/test.yml"><img src="https://github.com/MSSJ-AI-ORG/simthinkd/actions/workflows/test.yml/badge.svg" alt="Tests"></a>
   <a href="https://colab.research.google.com/github/MSSJ-AI-ORG/simthinkd/blob/main/notebooks/quickstart.ipynb"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open in Colab"></a>
-  <a href="https://doi.org/10.5281/zenodo.23111615"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.23111615.svg" alt="DOI"></a>
+  <a href="https://arxiv.org/abs/2610.04810"><img src="https://img.shields.io/badge/arXiv-2610.04810-b31b1b.svg" alt="arXiv:2610.04810"></a>
 </p>
 
 <p align="center"><b>Network down. Decisions stay local.</b></p>
@@ -183,6 +183,83 @@ It is not a good fit for:
 - **Answers that are not in the line you give it.** If the answer depends on history the line does not contain, add that history to the line or use a different tool.
 - **Open-ended answers.** It picks from a list or returns one number. It does not write.
 
+## Route between a fast path and a large model
+
+New in 0.4.0 (router kit). A `Router` puts SimThink D in front of a large model. The decider names the current state, a
+skill table gives the scripted action for that state, and the router either does that action or hands the case over.
+
+```python
+from simthinkd import Decider, Router, SkillTable, ScreenAdapter
+
+skills = SkillTable({"LOGIN":   ("FILL_LOGIN", ["PROFILE"]),        # state: (action, expected next states)
+                     "PROFILE": ("SUBMIT", ["ERROR", "DONE"]),
+                     "ERROR":   ("CLOSE", ["PROFILE"]),
+                     "DONE":    ("STOP", None, True)})               # final: the task ends here
+router = Router(Decider("models/screen"), skills, tau=0.9, adapter=ScreenAdapter())
+router.reset(expect=["LOGIN"])
+route = router.route({"pixels": screenshot, "title": "Sign in", "prev": None})
+if route.handoff:
+    action = ask_large_model(screenshot)     # route.reason says why
+else:
+    action = route.action                    # about 2 ms
+```
+
+A route is a hand-over for one of three reasons:
+
+| Reason | When |
+|---|---|
+| `low_confidence` | the decider's confidence is below `tau` |
+| `unknown_state` | the state has no skill in this table |
+| `no_progress` | the state is not one the last fast action was expected to lead to |
+
+The third check matters most. A small model can be sure and wrong on a screen it has never seen. If its action then
+leads somewhere unexpected, or changes nothing, the very next route hands the case over. `SkillTable.from_transitions`
+learns the expected next states from runs of your teacher.
+
+- `HandoffMonitor()` watches the last 10 routes. It fires when half of them were hand-overs, or when 3 were no-progress.
+- `relearn(router, teacher, observations, base_examples)` asks your teacher (a large model or a person) about those
+  cases. It then retrains the decider, swaps it into the running router and appends one line to a log.
+- Adapters turn different inputs into the decider's sentence: `ScreenAdapter` (a colour grid of a screenshot, the window
+  title and the previous action), `PipelineAdapter` (request fields and a gate verdict) and `VectorAdapter` (part of a
+  robot's observation vector). The decider stays the same; only the input changes.
+
+[examples/router_screen](examples/router_screen/) runs all of this on a small synthetic screen task, with no network.
+It includes a sealed preregistration and a template for your own experiments. In our sealed run, 12 of 12 deliberately
+wrong actions were caught at the next screen. After a redesign, 101 teacher labels and 3.7 s of training brought the
+hand-over rate from 41 of 58 routes back to 0 of 96. Details: [docs/ROUTER.md](docs/ROUTER.md).
+
+## Drive a screen
+
+New in 0.5.0 (screen kit). Guards for putting the router on a real screen, where a wrong click costs time or cannot be
+undone.
+
+```python
+from simthinkd import NoClickBands, open_or_press, ExpectAfter, RuleFirst, PageTextCheck
+
+bands = NoClickBands(top=96, bottom_from=700)            # fixed header and footer of the site
+kind, where = open_or_press(element, allow=lambda href: "/item/" in href)
+if kind == "open":
+    browser.goto(where)                                    # a link: open it, do not wait for a click
+elif bands.allows(where):
+    browser.click(*where)
+ok, state, ms = ExpectAfter(read_state, timeout=5.0).wait({"CART"})
+if not ok:
+    action = ask_large_model(screenshot)                   # the step went nowhere: hand over
+```
+
+- `NoClickBands` keeps clicks off fixed headers and footers that cover the page.
+- `open_or_press` opens a link by its address instead of clicking a card and waiting for a new tab.
+- `ExpectAfter` checks that the expected screen appears in time after an action.
+- `RuleFirst` uses a rule where one is certain and asks the decider only where it is not.
+- `PageTextCheck` decides success from the page text, not from a screenshot.
+- `DomVerifier` and `PopupGuard` (also in this release) check the page structure before a confident fast action, and
+  never close a popup that asks for a decision.
+
+On our synthetic HR ERP, a large model alone took 118.3 s per mission on average (14 large-model calls each); with
+SimThink D in front it took 7.2 s with 0 calls (3 of 3 runs each, local headless Chrome). On a synthetic image studio, a large model alone took 126.6 s (14 calls each); with SimThink D in front it took 18.7 s with 1 call, for the credits popup, which asks for a decision and always goes to the large model (3 of 3 runs each, after the review fixes). An earlier sealed run took 24.3 s with 1 or 2 calls: a screen caught halfway through a change was sometimes handed over as well. In our first sealed run one of these missions failed; the cause was in the benchmark runner and is fixed (see CHANGELOG).
+`benchmarks/screen` reruns both apps; a large model is plugged in through one command. Manual:
+[docs/SCREEN.md](docs/SCREEN.md).
+
 ## Measure your own model
 
 Does your model fit inside one tick? `simthinkd bench` replays 1,050 recorded Doom states that ship with the package. It times every decision, one request at a time.
@@ -252,8 +329,7 @@ SimThink D only knows what its teacher knows. It does not reason, read long text
 
 If you use SimThink D, please cite it with [CITATION.cff](CITATION.cff). GitHub shows a "Cite this repository" button for it.
 
-- Software: [doi:10.5281/zenodo.23111615](https://doi.org/10.5281/zenodo.23111615)
-- Paper (preprint): Shin, Lee, Jeong and Kwon, "Separating Decision Time from Decision Quality in the Real-Time Gap of Distilled Deciders: Evidence from a Game and a Conveyor Simulator", [doi:10.5281/zenodo.23111659](https://doi.org/10.5281/zenodo.23111659)
+- Paper: Shin, Lee, Jeong and Kwon, "Separating Decision Time from Decision Quality in the Real-Time Gap of Distilled Deciders: Evidence from a Game and a Conveyor Simulator", [arXiv:2610.04810](https://arxiv.org/abs/2610.04810)
 
 The two bundled deciders are the exact deciders evaluated in the paper (same SHA-256). [docs/REPRODUCE.md](docs/REPRODUCE.md) lists what you can rerun from this repository and what is not released yet.
 

{simthinkd-0.3.0 → simthinkd-0.5.0}/README.md

@@ -8,7 +8,7 @@
   <img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+">
   <a href="https://github.com/MSSJ-AI-ORG/simthinkd/actions/workflows/test.yml"><img src="https://github.com/MSSJ-AI-ORG/simthinkd/actions/workflows/test.yml/badge.svg" alt="Tests"></a>
   <a href="https://colab.research.google.com/github/MSSJ-AI-ORG/simthinkd/blob/main/notebooks/quickstart.ipynb"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open in Colab"></a>
-  <a href="https://doi.org/10.5281/zenodo.23111615"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.23111615.svg" alt="DOI"></a>
+  <a href="https://arxiv.org/abs/2610.04810"><img src="https://img.shields.io/badge/arXiv-2610.04810-b31b1b.svg" alt="arXiv:2610.04810"></a>
 </p>
 
 <p align="center"><b>Network down. Decisions stay local.</b></p>
@@ -153,6 +153,83 @@ It is not a good fit for:
 - **Answers that are not in the line you give it.** If the answer depends on history the line does not contain, add that history to the line or use a different tool.
 - **Open-ended answers.** It picks from a list or returns one number. It does not write.
 
+## Route between a fast path and a large model
+
+New in 0.4.0 (router kit). A `Router` puts SimThink D in front of a large model. The decider names the current state, a
+skill table gives the scripted action for that state, and the router either does that action or hands the case over.
+
+```python
+from simthinkd import Decider, Router, SkillTable, ScreenAdapter
+
+skills = SkillTable({"LOGIN":   ("FILL_LOGIN", ["PROFILE"]),        # state: (action, expected next states)
+                     "PROFILE": ("SUBMIT", ["ERROR", "DONE"]),
+                     "ERROR":   ("CLOSE", ["PROFILE"]),
+                     "DONE":    ("STOP", None, True)})               # final: the task ends here
+router = Router(Decider("models/screen"), skills, tau=0.9, adapter=ScreenAdapter())
+router.reset(expect=["LOGIN"])
+route = router.route({"pixels": screenshot, "title": "Sign in", "prev": None})
+if route.handoff:
+    action = ask_large_model(screenshot)     # route.reason says why
+else:
+    action = route.action                    # about 2 ms
+```
+
+A route is a hand-over for one of three reasons:
+
+| Reason | When |
+|---|---|
+| `low_confidence` | the decider's confidence is below `tau` |
+| `unknown_state` | the state has no skill in this table |
+| `no_progress` | the state is not one the last fast action was expected to lead to |
+
+The third check matters most. A small model can be sure and wrong on a screen it has never seen. If its action then
+leads somewhere unexpected, or changes nothing, the very next route hands the case over. `SkillTable.from_transitions`
+learns the expected next states from runs of your teacher.
+
+- `HandoffMonitor()` watches the last 10 routes. It fires when half of them were hand-overs, or when 3 were no-progress.
+- `relearn(router, teacher, observations, base_examples)` asks your teacher (a large model or a person) about those
+  cases. It then retrains the decider, swaps it into the running router and appends one line to a log.
+- Adapters turn different inputs into the decider's sentence: `ScreenAdapter` (a colour grid of a screenshot, the window
+  title and the previous action), `PipelineAdapter` (request fields and a gate verdict) and `VectorAdapter` (part of a
+  robot's observation vector). The decider stays the same; only the input changes.
+
+[examples/router_screen](examples/router_screen/) runs all of this on a small synthetic screen task, with no network.
+It includes a sealed preregistration and a template for your own experiments. In our sealed run, 12 of 12 deliberately
+wrong actions were caught at the next screen. After a redesign, 101 teacher labels and 3.7 s of training brought the
+hand-over rate from 41 of 58 routes back to 0 of 96. Details: [docs/ROUTER.md](docs/ROUTER.md).
+
+## Drive a screen
+
+New in 0.5.0 (screen kit). Guards for putting the router on a real screen, where a wrong click costs time or cannot be
+undone.
+
+```python
+from simthinkd import NoClickBands, open_or_press, ExpectAfter, RuleFirst, PageTextCheck
+
+bands = NoClickBands(top=96, bottom_from=700)            # fixed header and footer of the site
+kind, where = open_or_press(element, allow=lambda href: "/item/" in href)
+if kind == "open":
+    browser.goto(where)                                    # a link: open it, do not wait for a click
+elif bands.allows(where):
+    browser.click(*where)
+ok, state, ms = ExpectAfter(read_state, timeout=5.0).wait({"CART"})
+if not ok:
+    action = ask_large_model(screenshot)                   # the step went nowhere: hand over
+```
+
+- `NoClickBands` keeps clicks off fixed headers and footers that cover the page.
+- `open_or_press` opens a link by its address instead of clicking a card and waiting for a new tab.
+- `ExpectAfter` checks that the expected screen appears in time after an action.
+- `RuleFirst` uses a rule where one is certain and asks the decider only where it is not.
+- `PageTextCheck` decides success from the page text, not from a screenshot.
+- `DomVerifier` and `PopupGuard` (also in this release) check the page structure before a confident fast action, and
+  never close a popup that asks for a decision.
+
+On our synthetic HR ERP, a large model alone took 118.3 s per mission on average (14 large-model calls each); with
+SimThink D in front it took 7.2 s with 0 calls (3 of 3 runs each, local headless Chrome). On a synthetic image studio, a large model alone took 126.6 s (14 calls each); with SimThink D in front it took 18.7 s with 1 call, for the credits popup, which asks for a decision and always goes to the large model (3 of 3 runs each, after the review fixes). An earlier sealed run took 24.3 s with 1 or 2 calls: a screen caught halfway through a change was sometimes handed over as well. In our first sealed run one of these missions failed; the cause was in the benchmark runner and is fixed (see CHANGELOG).
+`benchmarks/screen` reruns both apps; a large model is plugged in through one command. Manual:
+[docs/SCREEN.md](docs/SCREEN.md).
+
 ## Measure your own model
 
 Does your model fit inside one tick? `simthinkd bench` replays 1,050 recorded Doom states that ship with the package. It times every decision, one request at a time.
@@ -222,8 +299,7 @@ SimThink D only knows what its teacher knows. It does not reason, read long text
 
 If you use SimThink D, please cite it with [CITATION.cff](CITATION.cff). GitHub shows a "Cite this repository" button for it.
 
-- Software: [doi:10.5281/zenodo.23111615](https://doi.org/10.5281/zenodo.23111615)
-- Paper (preprint): Shin, Lee, Jeong and Kwon, "Separating Decision Time from Decision Quality in the Real-Time Gap of Distilled Deciders: Evidence from a Game and a Conveyor Simulator", [doi:10.5281/zenodo.23111659](https://doi.org/10.5281/zenodo.23111659)
+- Paper: Shin, Lee, Jeong and Kwon, "Separating Decision Time from Decision Quality in the Real-Time Gap of Distilled Deciders: Evidence from a Game and a Conveyor Simulator", [arXiv:2610.04810](https://arxiv.org/abs/2610.04810)
 
 The two bundled deciders are the exact deciders evaluated in the paper (same SHA-256). [docs/REPRODUCE.md](docs/REPRODUCE.md) lists what you can rerun from this repository and what is not released yet.
 

{simthinkd-0.3.0 → simthinkd-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simthinkd"
-version = "0.3.0"
+version = "0.5.0"
 description = "A 265k-parameter decision model that picks one action in about 2 ms on one CPU core, inside real-time loops."
 readme = "README.md"
 requires-python = ">=3.10"

simthinkd-0.5.0/src/simthinkd/__init__.py

@@ -0,0 +1,36 @@
+"""SimThink D: a small decision model that picks one action in about 2 ms on one CPU core.
+
+    from simthinkd import Decider
+    print(Decider("doom-defend").decide("seen: Demon left a30 d5 | enemies 1 | sway left | gun ready | ammo25"))
+
+Router kit (0.4.0): Router + SkillTable hand a case over to a large model when the decider is unsure, the state is
+unknown, or the last fast action did not lead to an expected next state; relearn() retrains and hot-swaps.
+DOM input: DomAdapter, CombinedAdapter, DomVerifier + VerifiedRouter (capture decides, DOM verifies), PopupGuard.
+Screen actions (0.5.0): NoClickBands, ExpectAfter, open_or_press, RuleFirst, PageTextCheck. See docs/SCREEN.md.
+"""
+from .adapters import PipelineAdapter, ScreenAdapter, VectorAdapter
+from .dom_adapter import CombinedAdapter, DomAdapter, DomVerifier, PopupGuard, VerifiedRouter
+from .screen_actions import ExpectAfter, NoClickBands, PageTextCheck, RuleFirst, RuleRoute, open_or_press
+from .core import Decider, Decision, available, build_request
+from .relearn import RelearnReport, relearn
+from .router import HandoffMonitor, Route, Router, Skill, SkillTable
+from .score import Score, Scorer
+
+__version__ = '0.5.0'
+__all__ = ['Decider', 'Decision', 'Score', 'Scorer', 'available', 'build_request', 'fit', 'fit_score', '__version__',
+           'Router', 'Route', 'Skill', 'SkillTable', 'HandoffMonitor', 'relearn', 'RelearnReport',
+           'ScreenAdapter', 'PipelineAdapter', 'VectorAdapter',
+           'DomAdapter', 'CombinedAdapter', 'DomVerifier', 'VerifiedRouter', 'PopupGuard',
+           'NoClickBands', 'ExpectAfter', 'open_or_press', 'RuleFirst', 'RuleRoute', 'PageTextCheck']
+
+
+def fit(*args, **kwargs):
+    """Train a decider from (situation, action) pairs. See simthinkd.train.fit. Needs simthinkd[train]."""
+    from .train import fit as _fit
+    return _fit(*args, **kwargs)
+
+
+def fit_score(*args, **kwargs):
+    """Train a score model from (situation, number) pairs. See simthinkd.score.fit_score. Needs simthinkd[train]."""
+    from .score import fit_score as _fit_score
+    return _fit_score(*args, **kwargs)

simthinkd-0.5.0/src/simthinkd/adapters.py

@@ -0,0 +1,178 @@
+"""Feature adapters: turn one kind of observation into the short sentence a decider reads. Same decider, different input.
+
+    ScreenAdapter()      screenshot pixels (+ window title, previous action) -> 'title: Sign in | prev: START | screen: g00w ...'
+    PipelineAdapter()    pipeline step (request meta, gate verdict)          -> 'step: draft | request: kind proposal ; pages 12 | gate: lint FAIL | reasons: ...'
+    VectorAdapter([...]) part of a robot observation vector                  -> 'obs: base_vx q5 | yaw_rate q3'
+
+Each adapter is a plain callable, so `Router(decider, skills, adapter=ScreenAdapter())` routes screenshots directly.
+Adapters are deterministic and need only NumPy; train the decider on sentences made by the same adapter.
+"""
+import json
+import math
+
+import numpy as np
+
+SATURATED = 'yorgbn'
+
+
+def color_class(r, g, b):
+    """One colour letter for an RGB value: w l m d (white to dark grey), y o r g b n (yellow orange red green blue other)."""
+    mx, mn = max(r, g, b), min(r, g, b)
+    if mx - mn < 28:
+        return 'w' if mx > 235 else 'l' if mx > 200 else 'm' if mx > 110 else 'd'
+    if r > 150 and g > 150 and b < 120:
+        return 'y'
+    if r >= g and r >= b:
+        return 'o' if g > 90 else 'r'
+    if g >= r and g >= b:
+        return 'g'
+    return 'b' if b - r > 40 else 'n'
+
+
+def _box(pixels, height, width):
+    """Area-average resize to (height, width), rounded to whole values. Exact block means when the sizes divide evenly."""
+    h, w = pixels.shape[:2]
+    if h < height or w < width:
+        raise ValueError(f'the screenshot ({w}x{h}) is smaller than the grid needs ({width}x{height})')
+    if h % height == 0 and w % width == 0:
+        out = pixels.reshape(height, h // height, width, w // width, 3).mean(axis=(1, 3))
+    else:
+        rows = np.linspace(0, h, height + 1).round().astype(int)
+        cols = np.linspace(0, w, width + 1).round().astype(int)
+        out = np.array([[pixels[rows[i]:rows[i + 1], cols[j]:cols[j + 1]].reshape(-1, 3).mean(0)
+                         for j in range(width)] for i in range(height)])
+    return np.floor(out + 0.5).astype(np.int64)
+
+
+def screen_tokens(pixels, cols=8, rows=6):
+    """Colour-grid tokens of a screenshot (the feature of experiment v2.1).
+
+    The image is box-resized to (8*cols) x (8*rows); each 8x8 cell gives a token g<row><col><mean colour class>, plus
+    a<row><col><colour> when at least 4 of its 64 pixels have a saturated colour (the most frequent one; a tie goes to the
+    colour seen first in the cell). pixels: an H x W x 3 array of 0-255 values (RGB), at least that many pixels."""
+    if not (1 <= cols <= 10 and 1 <= rows <= 10):
+        raise ValueError('cols and rows must be between 1 and 10')
+    px = np.asarray(pixels)
+    if px.ndim != 3 or px.shape[2] < 3:
+        raise ValueError('pixels must be an H x W x 3 RGB array')
+    small = _box(px[:, :, :3].astype(np.float64), rows * 8, cols * 8)
+    tokens = []
+    for cy in range(rows):
+        for cx in range(cols):
+            cell = small[cy * 8:cy * 8 + 8, cx * 8:cx * 8 + 8].reshape(-1, 3)
+            mean = cell.sum(0) // 64
+            tokens.append(f'g{cy}{cx}{color_class(*(int(v) for v in mean))}')
+            sat = [c for c in (color_class(*(int(v) for v in p)) for p in cell) if c in SATURATED]
+            if len(sat) >= 4:
+                top = max(dict.fromkeys(sat), key=sat.count)  # dict keeps first-seen order: deterministic ties
+                tokens.append(f'a{cy}{cx}{top}')
+    return ' '.join(tokens)
+
+
+class ScreenAdapter:
+    """Screen observation -> sentence. An observation is a dict {'pixels', 'title', 'prev'} or the pixel array alone.
+
+    with_title / with_prev False gives the pixel-only sentence 'screen: ...' (the router_visual model of v2.1)."""
+
+    def __init__(self, cols=8, rows=6, with_title=True, with_prev=True):
+        if not (1 <= cols <= 10 and 1 <= rows <= 10):
+            raise ValueError('cols and rows must be between 1 and 10')
+        self.cols, self.rows, self.with_title, self.with_prev = cols, rows, with_title, with_prev
+
+    def __call__(self, observation):
+        if isinstance(observation, dict):
+            if 'pixels' not in observation:
+                raise ValueError("a screen observation needs 'pixels'")
+            pixels, title, prev = observation['pixels'], observation.get('title', ''), observation.get('prev')
+        else:
+            pixels, title, prev = observation, '', None
+        parts = []
+        if self.with_title:
+            parts.append(f'title: {title or ""}')
+        if self.with_prev:
+            parts.append(f'prev: {prev or "START"}')
+        parts.append('screen: ' + screen_tokens(pixels, self.cols, self.rows))
+        return ' | '.join(parts)
+
+
+def _value(v):
+    if isinstance(v, bool):
+        return 'yes' if v else 'no'
+    if isinstance(v, (dict, list, tuple)):
+        return json.dumps(v, ensure_ascii=False, sort_keys=True, separators=(',', ':'))
+    return ' '.join(str(v).split()) or '-'
+
+
+class PipelineAdapter:
+    """Pipeline step -> sentence, for routing inside a fixed pipeline (which step next, which gate failure, which model).
+
+    An observation is a dict {'step': name, 'request': {meta}, 'gate': {'name', 'verdict', 'reasons'}}; every part is
+    optional but the observation must be a dict. fields: the request keys to keep, in this order (None: all, sorted)."""
+
+    def __init__(self, fields=None, max_reasons=5):
+        if fields is not None and (isinstance(fields, str) or not all(isinstance(f, str) and f for f in fields)):
+            raise ValueError('fields must be a list of request keys')
+        if not isinstance(max_reasons, int) or max_reasons < 0:
+            raise ValueError('max_reasons must be a whole number >= 0')
+        self.fields, self.max_reasons = (list(fields) if fields is not None else None), max_reasons
+
+    def __call__(self, observation):
+        if not isinstance(observation, dict):
+            raise ValueError('a pipeline observation is a dict with step, request and gate')
+        request = observation.get('request') or {}
+        if not isinstance(request, dict):
+            raise ValueError('request must be a dict of meta fields')
+        keys = self.fields if self.fields is not None else sorted(request)
+        meta = ' ; '.join(f'{k} {_value(request[k])}' for k in keys if k in request) or 'none'
+        parts = [f'step: {_value(observation.get("step") or "-")}', f'request: {meta}']
+        gate = observation.get('gate')
+        if gate is None:
+            parts.append('gate: none')
+        else:
+            if not isinstance(gate, dict):
+                raise ValueError('gate must be a dict with name, verdict and reasons')
+            parts.append(f'gate: {_value(gate.get("name") or "-")} {_value(gate.get("verdict") or "-").upper()}')
+            reasons = [_value(r) for r in (gate.get('reasons') or [])][:self.max_reasons]
+            if reasons:
+                parts.append('reasons: ' + ' ; '.join(reasons))
+        return ' | '.join(parts)
+
+
+class VectorAdapter:
+    """Part of a numeric observation vector (e.g. a robot's 61 observations) -> sentence of quantised levels.
+
+    indices: which entries to use; names: one word per entry (default x<index>); low/high: the range per entry (a number
+    or one per entry), clipped; levels: how many bins (2-64). Entry 0.42 in [-1, 1] with 8 levels becomes 'q5'."""
+
+    def __init__(self, indices, names=None, low=-1.0, high=1.0, levels=8, prefix='obs'):
+        self.indices = [int(i) for i in indices]
+        if not self.indices:
+            raise ValueError('choose at least one index')
+        if any(i < 0 for i in self.indices) or len(set(self.indices)) != len(self.indices):
+            raise ValueError('indices must be distinct and >= 0')
+        self.names = list(names) if names is not None else [f'x{i}' for i in self.indices]
+        if len(self.names) != len(self.indices) or not all(isinstance(n, str) and n and ' ' not in n for n in self.names):
+            raise ValueError('give one name (one word) per index')
+        n = len(self.indices)
+        self.low = np.broadcast_to(np.asarray(low, np.float64), (n,)).copy()
+        self.high = np.broadcast_to(np.asarray(high, np.float64), (n,)).copy()
+        if not np.all(np.isfinite(self.low)) or not np.all(np.isfinite(self.high)) or np.any(self.high <= self.low):
+            raise ValueError('every range needs finite low < high')
+        if not isinstance(levels, int) or not 2 <= levels <= 64:
+            raise ValueError('levels must be a whole number from 2 to 64')
+        self.levels, self.prefix = levels, prefix
+
+    def level(self, k, value):
+        """Bin of one value for entry k (0 .. levels-1)."""
+        span = (min(max(value, self.low[k]), self.high[k]) - self.low[k]) / (self.high[k] - self.low[k])
+        return min(int(math.floor(span * self.levels)), self.levels - 1)
+
+    def __call__(self, observation):
+        vector = np.asarray(observation, np.float64).reshape(-1)
+        if max(self.indices) >= len(vector):
+            raise ValueError(f'the observation has {len(vector)} entries; index {max(self.indices)} is out of range')
+        values = vector[self.indices]
+        if not np.all(np.isfinite(values)):
+            raise ValueError('the observation has a missing or infinite value in the chosen entries')
+        body = ' | '.join(f'{name} q{self.level(k, v)}' for k, (name, v) in enumerate(zip(self.names, values)))
+        return f'{self.prefix}: {body}'