simthinkd 0.3.0

English | 한국어 | 日本語

Network down. Decisions stay local.

SimThink D is a small CPU model for offline backup decisions. It has 265,665 parameters and takes about 2 ms per decision on one CPU core.

In the factory simulation, the internet was cut for 15 seconds. The local backup got 59 of 63 parts right, with no late decisions.

Project page · Try in your browser · Watch the video (72 s) · Factory code · Paper

pip install simthinkd

What makes the next decision when your network goes down?

Words used here

• Tick: one step of a game or control loop. Doom runs at 35 ticks per second, so one tick is 28.6 ms.
• Decider: the small model. It gets a short sentence about the situation and returns one action.
• Teacher: your own rules, written as a normal function. The decider learns by copying the teacher.
• Perception: your code that turns the raw game state into the short sentence.

Install

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):

pip install "simthinkd[train]"

Quickstart

from simthinkd import Decider

d = Decider("doom-defend")
print(d.decide("seen: Demon left a30 d5 | enemies 1 | sway left | gun ready | ammo25"))
# TURN_LEFT (100%, 1.1 ms)

One call is one decision. A short sentence goes in. One action comes out, with its probability and the time it took. The first call also loads the model, so it is slower. After that, a call takes about 1 ms.

Two deciders come with the package: doom-defend (stand in the middle and fight) and doom-corridor (fight your way down a corridor).

Many decisions at once

One call can carry several questions about the same situation, and one batch can carry many situations. The answers are the same as asking one by one.

from simthinkd import Decider

d = Decider("doom-defend")
states = ["seen: Demon left a30 d5 | enemies 1 | sway left | gun ready | ammo25",
          "seen: Demon right a30 d5 | enemies 1 | sway right | gun ready | ammo25"]
answers = d.predict_batch([d.request(s) for s in states])   # many situations in one pass
print([a["operation"]["choice"] for a in answers])
# ['TURN_LEFT', 'TURN_RIGHT']

simthinkd bench --batch shows where the time goes on your machine. Details and limits: docs/PARALLEL.md.

Train your own in seconds

A new task needs two things: a perception step and a teacher. The toy module below is a small made-up task, an inspection station on a factory belt. Swap its examples and actions for your own.

import simthinkd
from simthinkd import toy

d = simthinkd.fit(toy.examples(3000), toy.ACTIONS, goal=toy.GOAL, out="inspection")
print(d.decide("part: defect dent | severity severe | image clear | belt normal | rework queue long"))
# REJECT (100%, 1.2 ms)

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.

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. 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 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:

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.

simthinkd bench
simthinkd bench --url http://127.0.0.1:8000/v1/systemone --name my-model --tick-hz 35

The second line measures any server that accepts the decision request.

Same CPU, same states

_{Same game, same seed, same 6-core CPU. Left: SimThink D, 1.9 ms per decision, 1 of 420 ticks missed. Right: Laya, a 421M-parameter open decision model, used as published without training on this game. It takes about 360 ms per decision and misses 390 of 420 ticks. A dark frame means the game moved on before the decider answered.}

Read this first. Laya is a general model and was not trained on this game. Its published speed, about 33 ms per question, is on a GPU. We only had a CPU. So this table compares time inside a real-time loop. It does not compare overall quality.

We used one workstation CPU (6 threads) and 1,050 Doom states, then 10 live games on the same seeds. "Missed ticks" are ticks that passed before the decider answered.

SimThink D only knows what its teacher knows. It does not reason, read long text or handle new actions without training. To run this comparison yourself, see benchmarks/.

Use it from your stack

How it works

• Input: the situation sentence, the goal and each action's description become hashed features: words, word pairs and three-letter pieces. There is no pretrained language model inside.
• Model: a small two-layer network scores every offered action. It sees all actions at once and gives calibrated probabilities.
• Training: it starts from random weights and learns from the teacher's choices. The best checkpoint is picked on held-out data.
• Why it matters: in a 35 Hz game, a decision that takes longer than 28.6 ms is a missed tick. Our paper separates the cost of decision time from the quality of the decision (docs/PAPER.md).

Limits

• At most 8 actions per decision.
• 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.

More

• Figures from the paper
• What you can reproduce
• Decision request format
• The factory video on LinkedIn

Citation

If you use SimThink D, please cite it with CITATION.cff. GitHub shows a "Cite this repository" button for it.

• Software: doi: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

The two bundled deciders are the exact deciders evaluated in the paper (same SHA-256). 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.

Credits

The comparison uses Laya by Convai Innovations (Apache 2.0), run unchanged through a small adapter. Doom scenes come from ViZDoom. See NOTICE.

License

Apache 2.0. See LICENSE.