A reusable Python engine for games controlled through an API. It separates the generic observe–plan–act–reconcile loop from game rules, provides typed outcomes, persists in-flight intent before mutations, and includes bounded operational tooling.
The default configuration runs a bundled loopback demonstration. The canonical contract scenario goes further: it runs entirely in memory, with no socket, account, token, language model, container, or real sleep.
Quick start
./install.sh --no-service
./manage.sh start
./manage.sh status
Run the sale-contract smoke test:
./smoke_test.sh
python3 agent.py canonical
Validate an adapter before connecting it to a real game:
from sdk.testkit import run_conformance
report = run_conformance(your_adapter_factory)
print(report.summary())
What is included
core/: deterministic loop, typed outcomes, persistence, pacing, guards, journal, health and storage protection.sdk/: five-method adapter contract and offline conformance kit.sim/andadapters/demo/: seed-derived reference world and complete adapter.ops/: configuration, runtime, diagnostics, backup and bounded watchdog.agent.py: offline benchmark hook plus optional post-run briefing.
The language-model adapter is not imported by core/, sdk/, ops/ or
run_engine.py. It can only summarize an already completed report.
Safety boundary
The engine never purchases, transfers, trades, messages, or authenticates on its own. A game adapter defines the authorized API and credentials. Start with the simulator, pass the conformance suite, inspect the configuration, and only then point an adapter at an endpoint you control.
See SPEC.md for the contract, CUSTOMIZE.md for adapter wiring, and
CHECKLIST.md for deployment gates.