simthinkd 0.1.0__tar.gz → 0.2.0__tar.gz

{simthinkd-0.1.0/src/simthinkd.egg-info → simthinkd-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simthinkd
-Version: 0.1.0
+Version: 0.2.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
@@ -28,9 +28,10 @@ Requires-Dist: onnx>=1.15; extra == "onnx"
 Requires-Dist: onnxruntime>=1.17; extra == "onnx"
 Dynamic: license-file
 
-<p align="center"><b>SimThink D</b></p>
+<p align="center"><img src="assets/banner.png" alt="SimThink D: a tiny decision model that runs on one CPU core" width="100%"></p>
 
 <p align="center">
+  <a href="https://pypi.org/project/simthinkd/"><img src="https://img.shields.io/pypi/v/simthinkd" alt="PyPI"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License: Apache 2.0"></a>
   <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>
@@ -38,6 +39,8 @@ Dynamic: license-file
   <a href="https://doi.org/10.5281/zenodo.23111615"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.23111615.svg" alt="DOI"></a>
 </p>
 
+<p align="center"><a href="https://mssj-ai-org.github.io/simthinkd/"><b>Project page, live demo and video →</b></a></p>
+
 **A tiny decision model that runs on one CPU core.** It has 265,665 parameters. It picks one action in about 2 ms. That is fast enough to decide inside every tick of a game or a control loop. No GPU is needed, not even for training.
 
 <p align="center">
@@ -48,11 +51,15 @@ Dynamic: license-file
 
 <div align="center">
 
-[Open in Colab](https://colab.research.google.com/github/MSSJ-AI-ORG/simthinkd/blob/main/notebooks/quickstart.ipynb) · [Try it in your browser](web/index.html) · [Gradio demo](space/) · [Paper](docs/PAPER.md) · [Protocol](docs/PROTOCOL.md)
+[Open in Colab](https://colab.research.google.com/github/MSSJ-AI-ORG/simthinkd/blob/main/notebooks/quickstart.ipynb) · [Try it in your browser](https://mssj-ai-org.github.io/simthinkd/#demo) · [Gradio demo](space/) · [Factory twin](examples/factory_twin/) · [Paper](docs/PAPER.md) · [Reproduce the paper](docs/REPRODUCE.md) · [Figures](docs/FIGURES.md) · [Protocol](docs/PROTOCOL.md)
 
 </div>
 
-Video: [a simulated factory line keeps running when the internet drops, with SimThink D deciding on the factory PC](https://www.linkedin.com/feed/update/urn:li:activity:7510142949981057024/) (LinkedIn).
+### Video: the internet goes down, the line keeps going
+
+<a href="assets/factory_fallback.mp4"><img src="assets/factory_fallback_poster.jpg" alt="Internet down. The line kept going." width="100%"></a>
+
+A cloud decision service runs a simulated inspection line, with SimThink D on the factory PC as its backup. When an answer does not come back in time, or the network is cut, SimThink D makes the decision. [Watch the video](assets/factory_fallback.mp4) (72 s) or see it [on LinkedIn](https://www.linkedin.com/feed/update/urn:li:activity:7510142949981057024/). The simulator is in [examples/factory_twin](examples/factory_twin/).
 
 ## Words used here
 
@@ -64,13 +71,13 @@ Video: [a simulated factory line keeps running when the internet drops, with Sim
 ## Install
 
 ```bash
-pip install "simthinkd @ git+https://github.com/MSSJ-AI-ORG/simthinkd"
+pip install simthinkd
 ```
 
 That is all you need to make decisions. It only needs NumPy. To train your own decider, add the `train` extra (it adds PyTorch, CPU build is fine):
 
 ```bash
-pip install "simthinkd[train] @ git+https://github.com/MSSJ-AI-ORG/simthinkd"
+pip install "simthinkd[train]"
 ```
 
 ## Quickstart
@@ -102,6 +109,65 @@ print(d.decide("part: defect dent | severity severe | image clear | belt normal
 
 On our test PC this trains on the CPU in about 8 seconds. The new decider then matched the teacher on 500 of 500 states it had not seen.
 
+## Score instead of choose
+
+Sometimes you need a number, not an action: a risk level, a priority, an expected wait. `fit_score` trains the same small network to return one number. Give it (situation sentence, number) pairs.
+
+```python
+import random
+import simthinkd
+from simthinkd import toy
+
+SEVERITY = {"minor": 20, "moderate": 45, "severe": 75}
+
+def risk(s):  # your own rule or records give the number
+    value = 0 if s["defect"] == "none" else SEVERITY[s["severity"]]
+    value += 10 if s["image"] == "blurry" else 0
+    value += 8 if s["belt"] == "fast" else 0
+    value += 5 if s["defect"] != "none" and s["queue"] == "long" else 0
+    return float(min(100, value))
+
+rng = random.Random(7)
+examples = [(text, risk(state)) for state, text in (toy.observe(rng) for _ in range(3000))]
+s = simthinkd.fit_score(examples, goal="Rate how risky this part is, 0 to 100.", out="risk", low=0, high=100, quiet=True)
+print(s.score("part: defect dent | severity severe | image clear | belt fast | rework queue long"))
+# 87.99 (0.22 ms)
+```
+
+The full script is [examples/risk_score.py](examples/risk_score.py). On our test PC, a risk score trained this way was off by 0.13 points on average (on a 0 to 100 scale) for 400 parts it had not seen. It put every pair of parts in the right order.
+
+## Where it fits
+
+SimThink D is a good fit when all three are true:
+
+1. **The situation fits in one short line.** A few fields, like "seen: Demon left a30 d5 | enemies 1". Not a long text.
+2. **The answer is small.** One of up to 8 actions, or one number.
+3. **The answer must be fast, cheap or offline.** Every game tick, every part on a line, every control step, or when the network is down.
+
+| Use | Why it fits | Try it here |
+|---|---|---|
+| Game characters | One decision every tick, 35 ticks a second | The two Doom deciders, `simthinkd bench` |
+| Backup decider on a factory PC | Decides when a cloud service is late or offline | [examples/factory_twin](examples/factory_twin/) |
+| Risk or priority score | One number per item, in well under a millisecond | [examples/risk_score.py](examples/risk_score.py) |
+| A rule you already have | Learns your rule from examples, then runs it in about 2 ms | [Train your own](#train-your-own-in-seconds) |
+
+### Use it together with a large model
+
+Most of the time SimThink D works best as one part of a bigger system, not alone. Two patterns:
+
+| Pattern | How it works | Try it here |
+|---|---|---|
+| **First filter** | SimThink D answers every case first. When it is not sure (its confidence is below a threshold you set), the case goes to a large model or a person. Easy cases stay cheap and fast; hard cases still get the big model. | `python examples/factory_twin/run.py --arm CASCADE --tau 0.9` |
+| **Local backup** | A large model or cloud service answers first. When its answer is late or the network fails, SimThink D on the local machine answers instead. | The factory video above and [examples/factory_twin](examples/factory_twin/) |
+
+A game character (NPC) is a natural first-filter case: SimThink D handles the moment-to-moment moves on every tick, and a large model is asked only for rare, slower choices such as planning or dialogue.
+
+It is not a good fit for:
+
+- **Judging long text** such as essays or reports. In our own test on essay sections, a simple word-count model did better.
+- **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.
+
 ## 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.
@@ -133,7 +199,8 @@ SimThink D only knows what its teacher knows. It does not reason, read long text
 | Any language, any engine | `simthinkd serve doom-defend --port 11890`, then POST the [decision request](docs/PROTOCOL.md) to `/v1/systemone` |
 | Unity / C# | [docs/INTEGRATION_UNITY.md](docs/INTEGRATION_UNITY.md): a client loop that keeps the game running while it waits |
 | Browser | [web/](web/): the same model in plain JavaScript, no server |
-| MCP (Claude Desktop, Cursor and others) | `pip install "simthinkd[mcp] @ git+https://github.com/MSSJ-AI-ORG/simthinkd"`, then `python -m simthinkd.integrations.mcp_server` |
+| A factory line (simulator) | [examples/factory_twin/](examples/factory_twin/): an inspection conveyor with a 400 ms deadline per part |
+| MCP (Claude Desktop, Cursor and others) | `pip install "simthinkd[mcp]"`, then `python -m simthinkd.integrations.mcp_server` |
 | LangChain / LangGraph | `from simthinkd.integrations.langchain_tool import simthinkd_tool` |
 
 ## How it works
@@ -149,6 +216,7 @@ SimThink D only knows what its teacher knows. It does not reason, read long text
 - Text input only. Turn numbers into short words or bins, like "d5" or "ammo25".
 - A decider copies its teacher. It is only as good as the teacher's rules.
 - Probabilities are calibrated for the decider's own task only.
+- A score model returns one number. It gives no probability or error bar with it.
 
 ## Citation
 
@@ -157,6 +225,8 @@ If you use SimThink D, please cite it with [CITATION.cff](CITATION.cff). GitHub
 - 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)
 
+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.
+
 ## Contributing
 
 Bug reports and small pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).

{simthinkd-0.1.0 → simthinkd-0.2.0}/README.md

@@ -1,6 +1,7 @@
-<p align="center"><b>SimThink D</b></p>
+<p align="center"><img src="assets/banner.png" alt="SimThink D: a tiny decision model that runs on one CPU core" width="100%"></p>
 
 <p align="center">
+  <a href="https://pypi.org/project/simthinkd/"><img src="https://img.shields.io/pypi/v/simthinkd" alt="PyPI"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License: Apache 2.0"></a>
   <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>
@@ -8,6 +9,8 @@
   <a href="https://doi.org/10.5281/zenodo.23111615"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.23111615.svg" alt="DOI"></a>
 </p>
 
+<p align="center"><a href="https://mssj-ai-org.github.io/simthinkd/"><b>Project page, live demo and video →</b></a></p>
+
 **A tiny decision model that runs on one CPU core.** It has 265,665 parameters. It picks one action in about 2 ms. That is fast enough to decide inside every tick of a game or a control loop. No GPU is needed, not even for training.
 
 <p align="center">
@@ -18,11 +21,15 @@
 
 <div align="center">
 
-[Open in Colab](https://colab.research.google.com/github/MSSJ-AI-ORG/simthinkd/blob/main/notebooks/quickstart.ipynb) · [Try it in your browser](web/index.html) · [Gradio demo](space/) · [Paper](docs/PAPER.md) · [Protocol](docs/PROTOCOL.md)
+[Open in Colab](https://colab.research.google.com/github/MSSJ-AI-ORG/simthinkd/blob/main/notebooks/quickstart.ipynb) · [Try it in your browser](https://mssj-ai-org.github.io/simthinkd/#demo) · [Gradio demo](space/) · [Factory twin](examples/factory_twin/) · [Paper](docs/PAPER.md) · [Reproduce the paper](docs/REPRODUCE.md) · [Figures](docs/FIGURES.md) · [Protocol](docs/PROTOCOL.md)
 
 </div>
 
-Video: [a simulated factory line keeps running when the internet drops, with SimThink D deciding on the factory PC](https://www.linkedin.com/feed/update/urn:li:activity:7510142949981057024/) (LinkedIn).
+### Video: the internet goes down, the line keeps going
+
+<a href="assets/factory_fallback.mp4"><img src="assets/factory_fallback_poster.jpg" alt="Internet down. The line kept going." width="100%"></a>
+
+A cloud decision service runs a simulated inspection line, with SimThink D on the factory PC as its backup. When an answer does not come back in time, or the network is cut, SimThink D makes the decision. [Watch the video](assets/factory_fallback.mp4) (72 s) or see it [on LinkedIn](https://www.linkedin.com/feed/update/urn:li:activity:7510142949981057024/). The simulator is in [examples/factory_twin](examples/factory_twin/).
 
 ## Words used here
 
@@ -34,13 +41,13 @@ Video: [a simulated factory line keeps running when the internet drops, with Sim
 ## Install
 
 ```bash
-pip install "simthinkd @ git+https://github.com/MSSJ-AI-ORG/simthinkd"
+pip install simthinkd
 ```
 
 That is all you need to make decisions. It only needs NumPy. To train your own decider, add the `train` extra (it adds PyTorch, CPU build is fine):
 
 ```bash
-pip install "simthinkd[train] @ git+https://github.com/MSSJ-AI-ORG/simthinkd"
+pip install "simthinkd[train]"
 ```
 
 ## Quickstart
@@ -72,6 +79,65 @@ print(d.decide("part: defect dent | severity severe | image clear | belt normal
 
 On our test PC this trains on the CPU in about 8 seconds. The new decider then matched the teacher on 500 of 500 states it had not seen.
 
+## Score instead of choose
+
+Sometimes you need a number, not an action: a risk level, a priority, an expected wait. `fit_score` trains the same small network to return one number. Give it (situation sentence, number) pairs.
+
+```python
+import random
+import simthinkd
+from simthinkd import toy
+
+SEVERITY = {"minor": 20, "moderate": 45, "severe": 75}
+
+def risk(s):  # your own rule or records give the number
+    value = 0 if s["defect"] == "none" else SEVERITY[s["severity"]]
+    value += 10 if s["image"] == "blurry" else 0
+    value += 8 if s["belt"] == "fast" else 0
+    value += 5 if s["defect"] != "none" and s["queue"] == "long" else 0
+    return float(min(100, value))
+
+rng = random.Random(7)
+examples = [(text, risk(state)) for state, text in (toy.observe(rng) for _ in range(3000))]
+s = simthinkd.fit_score(examples, goal="Rate how risky this part is, 0 to 100.", out="risk", low=0, high=100, quiet=True)
+print(s.score("part: defect dent | severity severe | image clear | belt fast | rework queue long"))
+# 87.99 (0.22 ms)
+```
+
+The full script is [examples/risk_score.py](examples/risk_score.py). On our test PC, a risk score trained this way was off by 0.13 points on average (on a 0 to 100 scale) for 400 parts it had not seen. It put every pair of parts in the right order.
+
+## Where it fits
+
+SimThink D is a good fit when all three are true:
+
+1. **The situation fits in one short line.** A few fields, like "seen: Demon left a30 d5 | enemies 1". Not a long text.
+2. **The answer is small.** One of up to 8 actions, or one number.
+3. **The answer must be fast, cheap or offline.** Every game tick, every part on a line, every control step, or when the network is down.
+
+| Use | Why it fits | Try it here |
+|---|---|---|
+| Game characters | One decision every tick, 35 ticks a second | The two Doom deciders, `simthinkd bench` |
+| Backup decider on a factory PC | Decides when a cloud service is late or offline | [examples/factory_twin](examples/factory_twin/) |
+| Risk or priority score | One number per item, in well under a millisecond | [examples/risk_score.py](examples/risk_score.py) |
+| A rule you already have | Learns your rule from examples, then runs it in about 2 ms | [Train your own](#train-your-own-in-seconds) |
+
+### Use it together with a large model
+
+Most of the time SimThink D works best as one part of a bigger system, not alone. Two patterns:
+
+| Pattern | How it works | Try it here |
+|---|---|---|
+| **First filter** | SimThink D answers every case first. When it is not sure (its confidence is below a threshold you set), the case goes to a large model or a person. Easy cases stay cheap and fast; hard cases still get the big model. | `python examples/factory_twin/run.py --arm CASCADE --tau 0.9` |
+| **Local backup** | A large model or cloud service answers first. When its answer is late or the network fails, SimThink D on the local machine answers instead. | The factory video above and [examples/factory_twin](examples/factory_twin/) |
+
+A game character (NPC) is a natural first-filter case: SimThink D handles the moment-to-moment moves on every tick, and a large model is asked only for rare, slower choices such as planning or dialogue.
+
+It is not a good fit for:
+
+- **Judging long text** such as essays or reports. In our own test on essay sections, a simple word-count model did better.
+- **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.
+
 ## 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.
@@ -103,7 +169,8 @@ SimThink D only knows what its teacher knows. It does not reason, read long text
 | Any language, any engine | `simthinkd serve doom-defend --port 11890`, then POST the [decision request](docs/PROTOCOL.md) to `/v1/systemone` |
 | Unity / C# | [docs/INTEGRATION_UNITY.md](docs/INTEGRATION_UNITY.md): a client loop that keeps the game running while it waits |
 | Browser | [web/](web/): the same model in plain JavaScript, no server |
-| MCP (Claude Desktop, Cursor and others) | `pip install "simthinkd[mcp] @ git+https://github.com/MSSJ-AI-ORG/simthinkd"`, then `python -m simthinkd.integrations.mcp_server` |
+| A factory line (simulator) | [examples/factory_twin/](examples/factory_twin/): an inspection conveyor with a 400 ms deadline per part |
+| MCP (Claude Desktop, Cursor and others) | `pip install "simthinkd[mcp]"`, then `python -m simthinkd.integrations.mcp_server` |
 | LangChain / LangGraph | `from simthinkd.integrations.langchain_tool import simthinkd_tool` |
 
 ## How it works
@@ -119,6 +186,7 @@ SimThink D only knows what its teacher knows. It does not reason, read long text
 - Text input only. Turn numbers into short words or bins, like "d5" or "ammo25".
 - A decider copies its teacher. It is only as good as the teacher's rules.
 - Probabilities are calibrated for the decider's own task only.
+- A score model returns one number. It gives no probability or error bar with it.
 
 ## Citation
 
@@ -127,6 +195,8 @@ If you use SimThink D, please cite it with [CITATION.cff](CITATION.cff). GitHub
 - 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)
 
+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.
+
 ## Contributing
 
 Bug reports and small pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).

{simthinkd-0.1.0 → simthinkd-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simthinkd"
-version = "0.1.0"
+version = "0.2.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.1.0 → simthinkd-0.2.0}/src/simthinkd/__init__.py

@@ -4,12 +4,19 @@
     print(Decider("doom-defend").decide("seen: Demon left a30 d5 | enemies 1 | sway left | gun ready | ammo25"))
 """
 from .core import Decider, Decision, available, build_request
+from .score import Score, Scorer
 
-__version__ = '0.1.0'
-__all__ = ['Decider', 'Decision', 'available', 'build_request', 'fit', '__version__']
+__version__ = '0.2.0'
+__all__ = ['Decider', 'Decision', 'Score', 'Scorer', 'available', 'build_request', 'fit', 'fit_score', '__version__']
 
 
 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.2.0/src/simthinkd/score.py

@@ -0,0 +1,137 @@
+"""Score models: the same small network as a decider, but it returns one number instead of picking an action.
+
+    import simthinkd
+    s = simthinkd.fit_score(examples, goal="Rate the risk of this part.", out="risk", low=0, high=100)
+    s.score("part: defect dent | severity severe | image clear | belt normal | rework queue long")
+    # Score(value=87.3, ms=1.1)
+
+`examples` is a list of (situation sentence, number) pairs. Training needs PyTorch; scoring needs only NumPy.
+Targets are standardised, the network is trained with a squared-error loss, and the checkpoint with the lowest
+validation mean absolute error is kept. Splits are made by a hash of each example, as in `fit`.
+"""
+import copy
+import hashlib
+import json
+import os
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+import numpy as np
+
+from .core import build_request
+from .policy import Policy, encode
+from .train import _encode_rows, _ranker, _torch, sha, split_for
+
+ACTION = {'SCORE': 'Return one number for this situation.'}
+
+
+@dataclass
+class Score:
+    value: float
+    ms: float = 0.0
+
+    def __str__(self):
+        return f'{self.value:.2f} ({self.ms:.2f} ms)'
+
+
+class Scorer:
+    """A trained score model. `Scorer("path/to/folder")`."""
+
+    def __init__(self, path):
+        path = Path(path)
+        self.card = json.loads((path / 'decider.json').read_text(encoding='utf8'))
+        if self.card.get('kind') != 'score':
+            raise ValueError(f'{path} is not a score model (use Decider for action models)')
+        self.policy = Policy(path / self.card['weights'])
+        self.sha256 = self.policy.digest
+
+    def score(self, state):
+        body = build_request(state, ACTION, self.card.get('goal', ''))
+        start = time.perf_counter()
+        x, _, _, _ = encode(body)
+        raw = float(self.policy.scores(x)[0])
+        value = raw * self.card['std'] + self.card['mean']
+        low, high = self.card.get('low'), self.card.get('high')
+        if low is not None:
+            value = max(low, value)
+        if high is not None:
+            value = min(high, value)
+        return Score(value, (time.perf_counter() - start) * 1000)
+
+    def __repr__(self):
+        return f'Scorer({self.card.get("name")!r}, sha256={self.sha256[:12]})'
+
+
+def _mae(torch, model, part, mean, std):
+    x, _, m, y = part
+    with torch.inference_mode():
+        pred = torch.cat([model(x[i:i + 256], m[i:i + 256])[:, 0] for i in range(0, len(x), 256)])
+    return float((pred * std + mean - y).abs().mean())
+
+
+def fit_score(examples, goal='', out='my_scorer', steps=1500, seed=31, low=None, high=None, name=None, quiet=False):
+    """Train a score model from (situation sentence, number) pairs. Returns a ready Scorer."""
+    torch = _torch()
+    out = Path(out)
+    out.mkdir(parents=True, exist_ok=True)
+    log = (lambda record: None) if quiet else (lambda record: print(json.dumps(record), flush=True))
+    torch.set_num_threads(min(4, os.cpu_count() or 1))
+    torch.use_deterministic_algorithms(True)
+    device = 'cpu'
+    splits = {'train': [], 'validation': [], 'calibration': []}
+    for i, item in enumerate(examples):
+        state, value = (item['state'], item['value']) if isinstance(item, dict) else item
+        row_id = f'sc{i:07d}:' + hashlib.sha256(state.encode()).hexdigest()[:8]
+        splits[split_for(row_id)].append({'id': row_id, 'request': build_request(state, ACTION, goal),
+                                          'expected': {'operation': 'SCORE'}, 'value': float(value)})
+    splits['validation'] += splits.pop('calibration')
+    if min(len(v) for v in splits.values()) == 0:
+        raise ValueError('need enough examples for train/validation splits (about 100 or more)')
+    values = np.array([r['value'] for r in splits['train']], np.float32)
+    mean, std = float(values.mean()), float(values.std() or 1.)
+    parts = {}
+    for name_, items in splits.items():
+        (x, g, m, _), width = _encode_rows(torch, items, device)
+        parts[name_] = (x, g, m, torch.tensor([r['value'] for r in items], dtype=torch.float32))
+    torch.manual_seed(seed)
+    model = _ranker(torch, width).to(device)
+    optimizer = torch.optim.AdamW(model.parameters(), lr=.002, weight_decay=.0001)
+    rng = torch.Generator().manual_seed(seed + 2121)
+    x, _, m, y = parts['train']
+    target = (y - mean) / std
+    best, weights, best_step, events = float('inf'), copy.deepcopy(model.state_dict()), 0, []
+    started = time.perf_counter()
+    for step in range(steps + 1):
+        if step % 100 == 0 or step == steps:
+            model.eval()
+            val = _mae(torch, model, parts['validation'], mean, std)
+            model.train()
+            events.append({'step': step, 'validation_mae': val})
+            if val < best:
+                best, weights, best_step = val, copy.deepcopy(model.state_dict()), step
+            log({'seed': seed, 'step': step, 'validation_mae': round(val, 6)})
+        if step == steps:
+            break
+        batch = torch.randint(len(x), (min(96, len(x)),), generator=rng)
+        pred = model(x[batch], m[batch])[:, 0]
+        loss = ((pred - target[batch]) ** 2).mean()
+        optimizer.zero_grad(set_to_none=True)
+        loss.backward()
+        optimizer.step()
+    model.load_state_dict(weights)
+    model.eval()
+    arrays = {k: v.detach().cpu().numpy() for k, v in model.state_dict().items()}
+    path = out / 'weights.npz'
+    np.savez_compressed(path, **arrays, temperature=np.array(1.0))
+    card = {'kind': 'score', 'name': name or out.name, 'goal': goal, 'weights': path.name, 'sha256': sha(path),
+            'mean': mean, 'std': std, 'low': low, 'high': high,
+            'parameters': sum(p.numel() for p in model.parameters()),
+            'examples': {k: len(v) for k, v in splits.items()},
+            'training': {'seed': seed, 'steps_run': steps, 'selected_step': best_step, 'validation_mae': best,
+                         'seconds': time.perf_counter() - started, 'events': events},
+            'torch': torch.__version__, 'created_at': datetime.now(timezone.utc).isoformat(),
+            'initialization': 'random (no pretrained weights)'}
+    (out / 'decider.json').write_text(json.dumps(card, ensure_ascii=False, indent=1), encoding='utf8')
+    return Scorer(out)

{simthinkd-0.1.0 → simthinkd-0.2.0/src/simthinkd.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simthinkd
-Version: 0.1.0
+Version: 0.2.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
@@ -28,9 +28,10 @@ Requires-Dist: onnx>=1.15; extra == "onnx"
 Requires-Dist: onnxruntime>=1.17; extra == "onnx"
 Dynamic: license-file
 
-<p align="center"><b>SimThink D</b></p>
+<p align="center"><img src="assets/banner.png" alt="SimThink D: a tiny decision model that runs on one CPU core" width="100%"></p>
 
 <p align="center">
+  <a href="https://pypi.org/project/simthinkd/"><img src="https://img.shields.io/pypi/v/simthinkd" alt="PyPI"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License: Apache 2.0"></a>
   <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>
@@ -38,6 +39,8 @@ Dynamic: license-file
   <a href="https://doi.org/10.5281/zenodo.23111615"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.23111615.svg" alt="DOI"></a>
 </p>
 
+<p align="center"><a href="https://mssj-ai-org.github.io/simthinkd/"><b>Project page, live demo and video →</b></a></p>
+
 **A tiny decision model that runs on one CPU core.** It has 265,665 parameters. It picks one action in about 2 ms. That is fast enough to decide inside every tick of a game or a control loop. No GPU is needed, not even for training.
 
 <p align="center">
@@ -48,11 +51,15 @@ Dynamic: license-file
 
 <div align="center">
 
-[Open in Colab](https://colab.research.google.com/github/MSSJ-AI-ORG/simthinkd/blob/main/notebooks/quickstart.ipynb) · [Try it in your browser](web/index.html) · [Gradio demo](space/) · [Paper](docs/PAPER.md) · [Protocol](docs/PROTOCOL.md)
+[Open in Colab](https://colab.research.google.com/github/MSSJ-AI-ORG/simthinkd/blob/main/notebooks/quickstart.ipynb) · [Try it in your browser](https://mssj-ai-org.github.io/simthinkd/#demo) · [Gradio demo](space/) · [Factory twin](examples/factory_twin/) · [Paper](docs/PAPER.md) · [Reproduce the paper](docs/REPRODUCE.md) · [Figures](docs/FIGURES.md) · [Protocol](docs/PROTOCOL.md)
 
 </div>
 
-Video: [a simulated factory line keeps running when the internet drops, with SimThink D deciding on the factory PC](https://www.linkedin.com/feed/update/urn:li:activity:7510142949981057024/) (LinkedIn).
+### Video: the internet goes down, the line keeps going
+
+<a href="assets/factory_fallback.mp4"><img src="assets/factory_fallback_poster.jpg" alt="Internet down. The line kept going." width="100%"></a>
+
+A cloud decision service runs a simulated inspection line, with SimThink D on the factory PC as its backup. When an answer does not come back in time, or the network is cut, SimThink D makes the decision. [Watch the video](assets/factory_fallback.mp4) (72 s) or see it [on LinkedIn](https://www.linkedin.com/feed/update/urn:li:activity:7510142949981057024/). The simulator is in [examples/factory_twin](examples/factory_twin/).
 
 ## Words used here
 
@@ -64,13 +71,13 @@ Video: [a simulated factory line keeps running when the internet drops, with Sim
 ## Install
 
 ```bash
-pip install "simthinkd @ git+https://github.com/MSSJ-AI-ORG/simthinkd"
+pip install simthinkd
 ```
 
 That is all you need to make decisions. It only needs NumPy. To train your own decider, add the `train` extra (it adds PyTorch, CPU build is fine):
 
 ```bash
-pip install "simthinkd[train] @ git+https://github.com/MSSJ-AI-ORG/simthinkd"
+pip install "simthinkd[train]"
 ```
 
 ## Quickstart
@@ -102,6 +109,65 @@ print(d.decide("part: defect dent | severity severe | image clear | belt normal
 
 On our test PC this trains on the CPU in about 8 seconds. The new decider then matched the teacher on 500 of 500 states it had not seen.
 
+## Score instead of choose
+
+Sometimes you need a number, not an action: a risk level, a priority, an expected wait. `fit_score` trains the same small network to return one number. Give it (situation sentence, number) pairs.
+
+```python
+import random
+import simthinkd
+from simthinkd import toy
+
+SEVERITY = {"minor": 20, "moderate": 45, "severe": 75}
+
+def risk(s):  # your own rule or records give the number
+    value = 0 if s["defect"] == "none" else SEVERITY[s["severity"]]
+    value += 10 if s["image"] == "blurry" else 0
+    value += 8 if s["belt"] == "fast" else 0
+    value += 5 if s["defect"] != "none" and s["queue"] == "long" else 0
+    return float(min(100, value))
+
+rng = random.Random(7)
+examples = [(text, risk(state)) for state, text in (toy.observe(rng) for _ in range(3000))]
+s = simthinkd.fit_score(examples, goal="Rate how risky this part is, 0 to 100.", out="risk", low=0, high=100, quiet=True)
+print(s.score("part: defect dent | severity severe | image clear | belt fast | rework queue long"))
+# 87.99 (0.22 ms)
+```
+
+The full script is [examples/risk_score.py](examples/risk_score.py). On our test PC, a risk score trained this way was off by 0.13 points on average (on a 0 to 100 scale) for 400 parts it had not seen. It put every pair of parts in the right order.
+
+## Where it fits
+
+SimThink D is a good fit when all three are true:
+
+1. **The situation fits in one short line.** A few fields, like "seen: Demon left a30 d5 | enemies 1". Not a long text.
+2. **The answer is small.** One of up to 8 actions, or one number.
+3. **The answer must be fast, cheap or offline.** Every game tick, every part on a line, every control step, or when the network is down.
+
+| Use | Why it fits | Try it here |
+|---|---|---|
+| Game characters | One decision every tick, 35 ticks a second | The two Doom deciders, `simthinkd bench` |
+| Backup decider on a factory PC | Decides when a cloud service is late or offline | [examples/factory_twin](examples/factory_twin/) |
+| Risk or priority score | One number per item, in well under a millisecond | [examples/risk_score.py](examples/risk_score.py) |
+| A rule you already have | Learns your rule from examples, then runs it in about 2 ms | [Train your own](#train-your-own-in-seconds) |
+
+### Use it together with a large model
+
+Most of the time SimThink D works best as one part of a bigger system, not alone. Two patterns:
+
+| Pattern | How it works | Try it here |
+|---|---|---|
+| **First filter** | SimThink D answers every case first. When it is not sure (its confidence is below a threshold you set), the case goes to a large model or a person. Easy cases stay cheap and fast; hard cases still get the big model. | `python examples/factory_twin/run.py --arm CASCADE --tau 0.9` |
+| **Local backup** | A large model or cloud service answers first. When its answer is late or the network fails, SimThink D on the local machine answers instead. | The factory video above and [examples/factory_twin](examples/factory_twin/) |
+
+A game character (NPC) is a natural first-filter case: SimThink D handles the moment-to-moment moves on every tick, and a large model is asked only for rare, slower choices such as planning or dialogue.
+
+It is not a good fit for:
+
+- **Judging long text** such as essays or reports. In our own test on essay sections, a simple word-count model did better.
+- **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.
+
 ## 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.
@@ -133,7 +199,8 @@ SimThink D only knows what its teacher knows. It does not reason, read long text
 | Any language, any engine | `simthinkd serve doom-defend --port 11890`, then POST the [decision request](docs/PROTOCOL.md) to `/v1/systemone` |
 | Unity / C# | [docs/INTEGRATION_UNITY.md](docs/INTEGRATION_UNITY.md): a client loop that keeps the game running while it waits |
 | Browser | [web/](web/): the same model in plain JavaScript, no server |
-| MCP (Claude Desktop, Cursor and others) | `pip install "simthinkd[mcp] @ git+https://github.com/MSSJ-AI-ORG/simthinkd"`, then `python -m simthinkd.integrations.mcp_server` |
+| A factory line (simulator) | [examples/factory_twin/](examples/factory_twin/): an inspection conveyor with a 400 ms deadline per part |
+| MCP (Claude Desktop, Cursor and others) | `pip install "simthinkd[mcp]"`, then `python -m simthinkd.integrations.mcp_server` |
 | LangChain / LangGraph | `from simthinkd.integrations.langchain_tool import simthinkd_tool` |
 
 ## How it works
@@ -149,6 +216,7 @@ SimThink D only knows what its teacher knows. It does not reason, read long text
 - Text input only. Turn numbers into short words or bins, like "d5" or "ammo25".
 - A decider copies its teacher. It is only as good as the teacher's rules.
 - Probabilities are calibrated for the decider's own task only.
+- A score model returns one number. It gives no probability or error bar with it.
 
 ## Citation
 
@@ -157,6 +225,8 @@ If you use SimThink D, please cite it with [CITATION.cff](CITATION.cff). GitHub
 - 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)
 
+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.
+
 ## Contributing
 
 Bug reports and small pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).

{simthinkd-0.1.0 → simthinkd-0.2.0}/src/simthinkd.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ src/simthinkd/bench.py
 src/simthinkd/cli.py
 src/simthinkd/core.py
 src/simthinkd/policy.py
+src/simthinkd/score.py
 src/simthinkd/server.py
 src/simthinkd/toy.py
 src/simthinkd/train.py
@@ -23,8 +24,10 @@ src/simthinkd/integrations/mcp_server.py
 src/simthinkd/weights/SHA256SUMS
 src/simthinkd/weights/doom-corridor.npz
 src/simthinkd/weights/doom-defend.npz
+tests/test_factory_twin.py
 tests/test_notebook.py
 tests/test_package.py
+tests/test_score.py
 tests/test_space.py
 tests/test_web_page.py
 tests/test_web_parity.py

simthinkd-0.2.0/tests/test_factory_twin.py

@@ -0,0 +1,65 @@
+"""Factory twin end-to-end test: train a decider, serve it, run the twin against it, check the results.
+
+    python -X utf8 tests/test_factory_twin.py        (needs simthinkd[train])
+
+Exit 0 = all pass. This runs the same three commands as examples/factory_twin/README.md.
+"""
+import json
+import socket
+import subprocess
+import sys
+import tempfile
+import time
+import urllib.request
+from pathlib import Path
+
+TWIN = Path(__file__).resolve().parents[1] / "examples" / "factory_twin"
+PY = sys.executable
+
+
+def free_port():
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+def main():
+    results = []
+    with tempfile.TemporaryDirectory() as t:
+        t = Path(t)
+        r = subprocess.run([PY, "-X", "utf8", str(TWIN / "train_inspection_decider.py"), "--out", str(t / "decider")],
+                           capture_output=True, text=True, cwd=TWIN)
+        results.append(("train", r.returncode == 0 and (t / "decider" / "weights.npz").exists(), r.stderr[-300:]))
+        port = free_port()
+        server = subprocess.Popen([PY, "-m", "simthinkd.cli", "serve", str(t / "decider"), "--port", str(port)],
+                                  stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)
+        try:
+            health = None
+            for _ in range(60):
+                try:
+                    with urllib.request.urlopen(f"http://127.0.0.1:{port}/health", timeout=1) as h:
+                        health = json.loads(h.read())
+                        break
+                except OSError:
+                    time.sleep(0.5)
+            results.append(("serve", bool(health and health.get("weights_sha256")), str(health)))
+            out = t / "result.json"
+            r = subprocess.run([PY, "-X", "utf8", str(TWIN / "run.py"), "--arm", "D", "--parts", "50", "--timing", "live",
+                                "--url", f"http://127.0.0.1:{port}", "--out", str(out)], capture_output=True, text=True, cwd=TWIN)
+            ok = r.returncode == 0 and out.exists()
+            results.append(("run arm D", ok, (r.stdout + r.stderr)[-400:]))
+            if ok:
+                m = json.loads(out.read_text(encoding="utf-8"))["metrics"]
+                results.append(("50 parts done", m["parts"] == 50, m))
+                results.append(("decisions on time (late < 10%)", m["late_rate"] < 0.10, m["late_rate"]))
+                results.append(("decider mostly right (>= 70%)", m["correct_rate"] >= 0.70, m["correct_rate"]))
+        finally:
+            server.terminate()
+            server.wait(timeout=10)
+    for name, ok, info in results:
+        print(("PASS " if ok else "FAIL ") + name + ("" if ok else f" | {info}"))
+    return 0 if results and all(ok for _, ok, _ in results) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

simthinkd-0.2.0/tests/test_score.py

@@ -0,0 +1,67 @@
+"""Score models end to end: train a risk score (0-100) from the toy inspection task on a CPU, then check it.
+
+    python -X utf8 tests/test_score.py        (needs: pip install "simthinkd[train]")
+The teacher is a fixed formula over the toy part, so the right answer is known for every state. Checks: training finishes,
+held-out mean absolute error is small and far better than predicting the training mean, the ranking of parts is
+preserved, values stay inside [low, high], the saved model reloads with the same hash, scoring needs no PyTorch path.
+"""
+import random
+import sys
+import tempfile
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / 'src'))
+
+import simthinkd  # noqa: E402
+from simthinkd import toy  # noqa: E402
+
+SEVERITY = {'minor': 20, 'moderate': 45, 'severe': 75}
+
+
+def risk(s):
+    base = 0 if s['defect'] == 'none' else SEVERITY[s['severity']]
+    base += 10 if s['image'] == 'blurry' else 0
+    base += 8 if s['belt'] == 'fast' else 0
+    base += 5 if s['defect'] != 'none' and s['queue'] == 'long' else 0
+    return float(min(100, base))
+
+
+def data(n, seed):
+    rng = random.Random(seed)
+    out = []
+    for _ in range(n):
+        s, text = toy.observe(rng)
+        out.append((text, risk(s)))
+    return out
+
+
+def main():
+    train, test = data(3000, 7), data(400, 99)
+    with tempfile.TemporaryDirectory() as tmp:
+        s = simthinkd.fit_score(train, goal='Rate how risky this part is, 0 to 100.', out=str(Path(tmp) / 'risk'),
+                                low=0, high=100, quiet=True)
+        preds = [s.score(t).value for t, _ in test]
+        gold = [v for _, v in test]
+        mae = sum(abs(p - g) for p, g in zip(preds, gold)) / len(gold)
+        mean = sum(v for _, v in train) / len(train)
+        base = sum(abs(mean - g) for g in gold) / len(gold)
+        pairs = [(i, j) for i in range(0, len(test), 7) for j in range(3, len(test), 11) if gold[i] != gold[j]]
+        concord = sum((preds[i] - preds[j]) * (gold[i] - gold[j]) > 0 for i, j in pairs) / len(pairs)
+        again = simthinkd.Scorer(str(Path(tmp) / 'risk'))
+        checks = [
+            (f'held-out MAE {mae:.2f} below 3 points', mae < 3),
+            (f'much better than predicting the mean (MAE {base:.2f})', mae < base / 4),
+            (f'ranking preserved ({concord:.0%} of pairs in the right order)', concord > 0.9),
+            ('values stay in [0, 100]', all(0 <= p <= 100 for p in preds)),
+            ('reloaded model has the same hash', again.sha256 == s.sha256),
+            ('same value after reload', abs(again.score(test[0][0]).value - preds[0]) < 1e-6),
+            (f'scoring time {s.score(test[1][0]).ms:.2f} ms under 10 ms', s.score(test[1][0]).ms < 10),
+        ]
+    for name, ok in checks:
+        print(('PASS ' if ok else 'FAIL ') + name)
+    sys.exit(0 if all(ok for _, ok in checks) else 1)
+
+
+if __name__ == '__main__':
+    main()

{simthinkd-0.1.0 → simthinkd-0.2.0}/tests/test_web_page.py

@@ -1,4 +1,4 @@
-"""Browser demo end to end: serve web/, open index.html in headless Chromium, make a decision, read the time.
+"""Browser demo end to end: serve web/, open demo/index.html in headless Chromium, make a decision, read the time.
 
     python -X utf8 tests/test_web_page.py          (needs: pip install playwright; playwright install chromium)
 Checks: page loads without console errors, the example decision is TURN_LEFT, a time and the one-tick verdict
@@ -20,7 +20,7 @@ def main():
     handler = functools.partial(http.server.SimpleHTTPRequestHandler, directory=str(ROOT / 'web'))
     server = http.server.ThreadingHTTPServer(('127.0.0.1', 0), handler)
     threading.Thread(target=server.serve_forever, daemon=True).start()
-    url = f'http://127.0.0.1:{server.server_address[1]}/index.html'
+    url = f'http://127.0.0.1:{server.server_address[1]}/demo/index.html'
     checks, errors = [], []
     with sync_playwright() as p:
         browser = p.chromium.launch()