Swarm Room — Token-Capped Small-Swarm Rehearsal Tool

Swarm Room is a small, concentrated swarm simulator for product and launch decisions — and it is capped on purpose.

Point it at a seed document and a question. It spawns a room of simulated personas, runs bounded interaction rounds, and writes back a stance distribution, the emergent points, the strongest dissent and a confidence caveat. Runs stop at 100 agents and 20 rounds, enforced in the code before anything is sent to a model.

What's inside

• swarm_room.py — the complete CLI: persona generation, deliberation rounds, synthesis and both report writers. Python standard library only.
• README.md — quick start, the full options table, cost-estimate defaults, and a plain list of what it is not.
• docs/CUSTOMIZE.md — change the model price rows, the archetypes, the report templates, and wire it into CI.
• demo/seed.md and demo/seed_debate.md — two sample seed documents.
• demo/mock_output/ — a captured offline run. demo/real_run_final/ — a captured live run: 12 agents, 4 rounds, 60 API calls, 49,058 tokens, about $0.016.
• demo/proof_of_run.sh — the smoke test we run before shipping. It checks the reports, asserts the caps reject an oversized run, and asserts the offline mode reproduces across processes.
• LICENSE and SHA256SUMS — personal-use licence, and per-file hashes for every other file in the package.

Token efficiency, by design

• Hard caps before the run starts: a rehearsal cannot run away from you.
• Built-in token meter: API calls, prompt/completion tokens and an estimated cost in USD and EUR, reported after every run. The price table is editable, and per-run flags override it.
• Offline mode: the full pipeline runs with no API key and no network, in under a second — demos and CI cost nothing.

Live runs: works with any OpenAI-compatible chat-completions endpoint — a hosted provider or a local llama.cpp / vLLM server. You supply your own key; none is included. The meter tells you what the run actually cost.

Honest scope: this is a simulation of plausible reactions, not a prediction of real buyer behavior. It does not replace interviews, surveys or a live test, and a small swarm surfaces disagreement quickly rather than settling it. Every report it writes says so.

Requirements: Python 3.8 or newer, standard library only, a terminal. No account, no hosted service, no lock-in.

Licence: personal use — run and modify it for yourself or inside your own business; don't resell or redistribute the package.

Support: if a file does not run as documented, send what you ran and what you saw to the platform's support address support@masinov.co (answered within one business day) and we will fix the listing.