simthinkd 0.1.0__py3-none-any.whl

simthinkd/__init__.py

@@ -0,0 +1,15 @@
+"""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"))
+"""
+from .core import Decider, Decision, available, build_request
+
+__version__ = '0.1.0'
+__all__ = ['Decider', 'Decision', 'available', 'build_request', 'fit', '__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)

simthinkd/bench.py

@@ -0,0 +1,55 @@
+"""Does your decider fit inside one game tick? Measures decision time and teacher agreement on recorded states.
+
+    simthinkd bench                                   # the bundled decider, in-process, bundled Doom states
+    simthinkd bench --url http://127.0.0.1:8000/v1/systemone --name my-model
+    simthinkd bench --states my_states.json --tick-hz 60
+
+Any server that accepts the decision request (PROTOCOL.md) and answers {"answers": {"operation": {"choice": ...}}}
+can be measured. States file: {"rows": [{"body": <request>, "teacher": <action>}, ...]}.
+One request at a time; the time is the full round trip seen by the caller.
+"""
+import json
+import statistics
+import time
+import urllib.request
+from pathlib import Path
+
+from .core import Decider
+
+BUNDLED = Path(__file__).resolve().parent / 'data' / 'doom_defend_states.json'
+
+
+def _post(url, body):
+    req = urllib.request.Request(url, data=json.dumps(body).encode(), headers={'Content-Type': 'application/json'})
+    with urllib.request.urlopen(req, timeout=300) as reply:
+        return json.load(reply)['answers']['operation']['choice']
+
+
+def run(states=None, url=None, decider='doom-defend', name=None, tick_hz=35.0, warmup=20, limit=0):
+    rows = json.loads(Path(states or BUNDLED).read_text(encoding='utf8'))['rows']
+    rows = rows[:limit] if limit else rows
+    if url:
+        call, label = (lambda body: _post(url, body)), name or url
+    else:
+        d = decider if isinstance(decider, Decider) else Decider(decider)
+        call, label = (lambda body: d.predict(body)['operation']['choice']), name or f'simthink-d:{d.preset["name"]}'
+    for row in rows[:warmup]:
+        call(row['body'])
+    times, agree = [], 0
+    for row in rows:
+        start = time.perf_counter()
+        choice = call(row['body'])
+        times.append((time.perf_counter() - start) * 1000)
+        agree += choice == row['teacher']
+    q = sorted(times)
+    tick_ms = 1000.0 / tick_hz
+    return {'name': label, 'states': len(rows), 'tick_ms': round(tick_ms, 2),
+            'p50_ms': round(statistics.median(q), 3), 'p95_ms': round(q[max(0, int(0.95 * len(q)) - 1)], 3),
+            'within_one_tick': round(sum(t <= tick_ms for t in times) / len(times), 4),
+            'teacher_agreement': round(agree / len(rows), 4)}
+
+
+def report(result):
+    return (f"{result['name']}: median {result['p50_ms']} ms, p95 {result['p95_ms']} ms, "
+            f"{result['within_one_tick']:.1%} of decisions within one {result['tick_ms']} ms tick, "
+            f"teacher agreement {result['teacher_agreement']:.1%} on {result['states']} states")

simthinkd/cli.py

@@ -0,0 +1,62 @@
+"""simthinkd command line: decide · serve · bench · train · list."""
+import argparse
+import json
+import sys
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog='simthinkd', description='SimThink D: a 2 ms decision model for real-time loops.')
+    sub = ap.add_subparsers(dest='cmd', required=True)
+    s = sub.add_parser('decide', help='one decision for one situation sentence')
+    s.add_argument('state', nargs='?', help='situation sentence (default: the preset example)')
+    s.add_argument('--decider', default='doom-defend')
+    s.add_argument('--json', action='store_true')
+    s = sub.add_parser('serve', help='HTTP server (POST /v1/systemone)')
+    s.add_argument('decider', nargs='?', default='doom-defend')
+    s.add_argument('--host', default='127.0.0.1')
+    s.add_argument('--port', type=int, default=11890)
+    s.add_argument('--delay-ms', type=float, default=0.0)
+    s = sub.add_parser('bench', help='decision time and teacher agreement on recorded states')
+    s.add_argument('--url')
+    s.add_argument('--name')
+    s.add_argument('--decider', default='doom-defend')
+    s.add_argument('--states')
+    s.add_argument('--tick-hz', type=float, default=35.0)
+    s.add_argument('--limit', type=int, default=0)
+    s.add_argument('--json', action='store_true')
+    s = sub.add_parser('train', help='train from a folder of protocol rows (needs simthinkd[train])')
+    s.add_argument('--data', required=True)
+    s.add_argument('--out', required=True)
+    s.add_argument('--steps', type=int, default=600)
+    s.add_argument('--seed', type=int, default=31)
+    sub.add_parser('list', help='bundled deciders')
+    a = ap.parse_args(argv)
+
+    if a.cmd == 'decide':
+        from .core import Decider
+        d = Decider(a.decider)
+        state = a.state or d.preset.get('example')
+        if not state:
+            sys.exit('give a situation sentence')
+        r = d.decide(state)
+        print(json.dumps({'choice': r.choice, 'confidence': r.confidence, 'ms': r.ms, 'probabilities': r.probabilities})
+              if a.json else r)
+    elif a.cmd == 'serve':
+        from .server import serve
+        serve(a.decider, a.host, a.port, a.delay_ms)
+    elif a.cmd == 'bench':
+        from . import bench
+        result = bench.run(a.states, a.url, a.decider, a.name, a.tick_hz, limit=a.limit)
+        print(json.dumps(result) if a.json else bench.report(result))
+    elif a.cmd == 'train':
+        from .train import fit_dir
+        d = fit_dir(a.data, a.out, a.steps, a.seed)
+        print(json.dumps({'decider': a.out, 'sha256': d.sha256}))
+    elif a.cmd == 'list':
+        from .core import available
+        for name, about in available().items():
+            print(f'{name:15s} {about}')
+
+
+if __name__ == '__main__':
+    main()

simthinkd/core.py

@@ -0,0 +1,158 @@
+"""High-level API: load a decider, ask it for one action, get the choice, probabilities and time.
+
+    from simthinkd import Decider
+    d = Decider("doom-defend")
+    print(d.decide("seen: Demon left a30 d5 | enemies 1 | sway left | gun ready | ammo25"))
+
+A decider is a weights file (about 1 MB, 265,665 parameters) plus the action set and goal it was trained with
+(a "preset"). Your own deciders come from `simthinkd.fit(...)`; they carry their preset inside the weights folder.
+"""
+import hashlib
+import json
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .policy import Policy
+
+WEIGHTS = Path(__file__).resolve().parent / 'weights'
+
+DOOM_DEFEND_ACTIONS = {
+    'TURN_LEFT': 'Turn left toward the target.',
+    'TURN_RIGHT': 'Turn right toward the target.',
+    'ATTACK': 'Shoot now, standing still.',
+    'STRAFE_LEFT': 'Sidestep left without shooting.',
+    'STRAFE_RIGHT': 'Sidestep right without shooting.',
+    'ATTACK_STRAFE_LEFT': 'Shoot while sidestepping left.',
+    'ATTACK_STRAFE_RIGHT': 'Shoot while sidestepping right.',
+}
+DOOM_CORRIDOR_ACTIONS = {
+    'MOVE_LEFT': 'Sidestep left, away from fire.',
+    'MOVE_RIGHT': 'Sidestep right, away from fire.',
+    'ATTACK': 'Shoot now; an enemy is lined up ahead.',
+    'MOVE_FORWARD': 'Advance down the corridor toward the armor.',
+    'MOVE_BACKWARD': 'Back off from what is in front.',
+    'TURN_LEFT': 'Turn left toward something on the left.',
+    'TURN_RIGHT': 'Turn right toward something on the right.',
+}
+
+PRESETS = {
+    'doom-defend': {
+        'weights': 'doom-defend.npz',
+        'sha256': 'a814587e03478f451f1ab478558de7e076dbe9a3de9cb2ee4cc84124cdfa2a19',
+        'model': 'doom-showcase-s1', 'url': 'doom://defend_the_center/showcase', 'title': 'defend the center tick {tick}',
+        'goal': 'Aim, shoot and sway to survive the horde.', 'actions': DOOM_DEFEND_ACTIONS,
+        'about': 'ViZDoom defend_the_center: aim, shoot and sway against a horde.',
+        'example': 'seen: Demon left a30 d5 | enemies 1 | sway left | gun ready | ammo25',
+    },
+    'doom-corridor': {
+        'weights': 'doom-corridor.npz',
+        'sha256': 'a164d90514f172ff2f1ac9452aaf83a637ffd8ef3136d0f553179e5c7ab035d8',
+        'model': 'doom-corridor', 'url': 'doom://deadly_corridor', 'title': 'deadly corridor tick {tick}',
+        'goal': 'Clear the corridor and reach the green armor.', 'actions': DOOM_CORRIDOR_ACTIONS,
+        'about': 'ViZDoom deadly_corridor: clear the corridor and reach the armor.',
+        'example': 'enemies: ShotgunGuy left near offset15 ; Zombieman right near offset15 | goal: armor ahead distant | body healthy | ammo stocked',
+    },
+}
+
+
+def build_request(state, actions, goal, *, url='sim://custom', title='', model='simthinkd', recent_actions=None):
+    """Turn (situation sentence, {action: description}, goal) into a decision request (see PROTOCOL.md)."""
+    if not isinstance(state, str) or not state.strip():
+        raise ValueError('state must be a non-empty sentence describing the situation')
+    if not actions or len(actions) > 8:
+        raise ValueError('offer between 1 and 8 actions')
+    return {
+        'model': model,
+        'state': {'page': {'url': url, 'title': title, 'text': state},
+                  'elements': [{'id': name, 'role': 'button', 'label': name} for name in actions],
+                  'recent_actions': list(recent_actions or [])},
+        'questions': {'operation': {'type': 'choice',
+                                    'criteria': {name: {'element': f'[button] {name}', 'description': why}
+                                                 for name, why in actions.items()},
+                                    'instructions': {'goal': goal}}},
+    }
+
+
+def answer(policy, body):
+    """Reply `answers` block for a protocol request (operation, and `<op>_target` when targets were offered)."""
+    chosen, op, conditional, joint, rows, operations = policy.predict(body)
+    op_probs = {key: float(op[i]) for i, key in enumerate(operations)}
+    top = max(op_probs, key=op_probs.get)
+    answers = {'operation': {'choice': top, 'probabilities': op_probs, 'confidence': op_probs[top]}}
+    group = operations.index(top)
+    targets = [(r['target'], float(joint[i])) for i, r in enumerate(rows) if r['group'] == group and r['target'] is not None]
+    if targets:
+        total = sum(p for _, p in targets) or 1.0
+        probs = {t: p / total for t, p in targets}
+        best = max(probs, key=probs.get)
+        answers[top.lower() + '_target'] = {'choice': best, 'probabilities': probs, 'confidence': probs[best]}
+    return answers
+
+
+@dataclass(frozen=True)
+class Decision:
+    choice: str
+    confidence: float
+    probabilities: dict = field(repr=False)
+    ms: float = 0.0
+
+    def __str__(self):
+        return f'{self.choice} ({self.confidence:.0%}, {self.ms:.2f} ms)'
+
+
+class Decider:
+    """A trained decider. `Decider("doom-defend")`, `Decider("path/to/folder_or.npz")`."""
+
+    def __init__(self, name_or_path='doom-defend'):
+        preset = PRESETS.get(name_or_path)
+        if preset:
+            path = WEIGHTS / preset['weights']
+            digest = hashlib.sha256(path.read_bytes()).hexdigest()
+            if digest != preset['sha256']:
+                raise RuntimeError(f'weights file {path.name} does not match its recorded SHA-256')
+            self.preset = dict(preset, name=name_or_path)
+        else:
+            path = Path(name_or_path)
+            if path.is_dir():
+                card = json.loads((path / 'decider.json').read_text(encoding='utf8'))
+                self.preset = dict(card, name=card.get('name', path.name))
+                path = path / card['weights']
+            else:
+                self.preset = {'name': path.stem, 'actions': None, 'goal': '', 'url': 'sim://custom', 'title': '',
+                               'model': path.stem}
+        self.policy = Policy(path)
+        self.sha256 = self.policy.digest
+
+    @property
+    def actions(self):
+        return dict(self.preset['actions'] or {})
+
+    def request(self, state, actions=None, goal=None, tick=0, recent_actions=None):
+        actions = actions or self.preset['actions']
+        if not actions:
+            raise ValueError('this decider has no stored action set; pass actions={name: description}')
+        return build_request(state, actions, self.preset['goal'] if goal is None else goal,
+                             url=self.preset.get('url', 'sim://custom'),
+                             title=self.preset.get('title', '').format(tick=tick),
+                             model=self.preset.get('model', 'simthinkd'), recent_actions=recent_actions)
+
+    def predict(self, body):
+        """Protocol-level call: request dict in, `answers` dict out (same as the HTTP server)."""
+        return answer(self.policy, body)
+
+    def decide(self, state, actions=None, goal=None, tick=0, recent_actions=None):
+        """One decision for one situation sentence. Returns a Decision (choice, confidence, probabilities, ms)."""
+        body = self.request(state, actions, goal, tick, recent_actions)
+        start = time.perf_counter()
+        op = answer(self.policy, body)['operation']
+        ms = (time.perf_counter() - start) * 1000
+        return Decision(op['choice'], op['confidence'], op['probabilities'], ms)
+
+    def __repr__(self):
+        return f'Decider({self.preset["name"]!r}, sha256={self.sha256[:12]})'
+
+
+def available():
+    """Names of the deciders that ship with the package."""
+    return {name: p['about'] for name, p in PRESETS.items()}