{"id":50226971,"url":"https://github.com/arianxdev/constitution-sim","last_synced_at":"2026-05-28T18:00:33.561Z","repository":{"id":359535845,"uuid":"1246529063","full_name":"arianXdev/constitution-sim","owner":"arianXdev","description":"Stress-test constitutions with AI-powered agentic politicians before trying them out on a real nation.","archived":false,"fork":false,"pushed_at":"2026-05-23T13:34:27.000Z","size":98,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T16:37:30.827Z","etag":null,"topics":["ai-agents","constitution","multiagent-systems"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arianXdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-22T09:29:23.000Z","updated_at":"2026-05-23T13:34:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/arianXdev/constitution-sim","commit_stats":null,"previous_names":["arianxdev/constitution-sim"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/arianXdev/constitution-sim","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arianXdev%2Fconstitution-sim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arianXdev%2Fconstitution-sim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arianXdev%2Fconstitution-sim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arianXdev%2Fconstitution-sim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arianXdev","download_url":"https://codeload.github.com/arianXdev/constitution-sim/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arianXdev%2Fconstitution-sim/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33575520,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-27T02:00:06.184Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","constitution","multiagent-systems"],"created_at":"2026-05-26T16:11:05.063Z","updated_at":"2026-05-27T17:00:44.839Z","avatar_url":"https://github.com/arianXdev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Constitution-Sim\n\n**Stress-test constitutions with AI-powered agentic politicians before trying them out on a real nation!**\n\n`constitution-sim` is a research-grade multi-agent AI simulator. You give it\na constitution and a scenario; it spins up an LLM-powered agent for each\npolitical role (Executive, Legislature, Judiciary, Media, Bureaucracy)\nand lets them act under the rules you wrote, turn by turn. Every action\nis checked by a rules engine, every event is logged, and every run is\nreproducible from a seed.\n\n## Why\n\nPoliticians are not utility-maximisers reading from a spec — they\ndeliberate, bargain, posture, and reach for legitimacy. The interesting\nquestion is *how the rules of a constitution shape that behaviour*. So\nthe agents here are LLMs (OpenAI / Anthropic) instructed with a\nrole-specific persona, the constitution they live under, their own\ngoals and utility weights, and a memory of their own recent decisions.\nThey never get to mutate the world directly — every move passes the\ntyped rules engine first.\n\nA deterministic heuristic agent is still available as a no-LLM fallback,\nso the project also runs offline / in CI / with zero API keys.\n\n## Features\n\n- **AI cognition is the default.** When `OPENAI_API_KEY` or\n  `ANTHROPIC_API_KEY` is in the environment, `constitution-sim run`\n  uses LLM-powered agents out of the box. With no key, it falls back to\n  a deterministic heuristic — same CLI, same outputs, no setup required.\n- **Role-specific personas.** Each role (Executive, Legislature,\n  Judiciary, Media, Bureaucracy) gets its own LLM system prompt. The\n  Executive is ambitious; the Judiciary is reactive; the Media chases a\n  narrative; the Bureaucracy implements steadily.\n- **Agent memory \u0026 shared history.** Each agent remembers its own recent decisions and can see a public history of what other actors just did (if the constitution allows).\n- **Inter-agent deliberation.** Each turn features a deliberation phase where agents can negotiate, threaten, or signal intent by sending messages to each other's inboxes.\n- **Schema-driven constitutions.** Strict Pydantic v2 models; YAML in, typed objects out. Constitutions can enforce communication limits (e.g. authoritarian gag orders).\n- **Rules engine is source of truth.** Agents propose typed actions; the engine accepts or rejects with a reason. The LLM cannot mutate state directly.\n- **Partial observability.** Each role gets a state view filtered by its `observation_limits`.\n- **Institutional metrics.** Power concentration, deadlock, trust\n  volatility, legitimacy, corruption pressure, emergency-power drift.\n- **Repeated-run evaluation harness.** Multi-seed runs with pandas /\n  matplotlib output.\n- **Deterministic when seeded** (heuristic mode is byte-for-byte\n  reproducible; LLM mode is reproducible up to provider variance).\n\n\u003cimg width=\"700\" alt=\"num_pending_bills\" src=\"https://github.com/user-attachments/assets/e53c4e03-25d4-4b50-80aa-359fb1c44299\" /\u003e\n\n\u003cimg width=\"700\" alt=\"corruption_proxy\" src=\"https://github.com/user-attachments/assets/f6127e60-0db6-4c34-a996-361dfde64c27\" /\u003e\n\n\u003cimg width=\"700\" alt=\"num_active_laws\" src=\"https://github.com/user-attachments/assets/d5959e29-70ce-4a1e-bc4e-ea216e1a08b5\" /\u003e\n\n\u003cimg width=\"700\"  alt=\"power_concentration\" src=\"https://github.com/user-attachments/assets/0bdc1b80-07d7-4c51-901e-dd38dc598483\" /\u003e\n\n\u003cimg width=\"700\" alt=\"public_trust\" src=\"https://github.com/user-attachments/assets/b004146e-51ed-43ef-a170-e8351982b702\" /\u003e\n\n\u003cimg width=\"700\" alt=\"num_active_laws\" src=\"https://github.com/user-attachments/assets/06955b78-383b-4249-b6cb-a05ce6db8080\" /\u003e\n\n\u003cimg width=\"700\" alt=\"emergency_turns\" src=\"https://github.com/user-attachments/assets/85d8bbcd-b605-423f-bf95-3891e4592c66\" /\u003e\n\n\u003cimg width=\"700\"  alt=\"trust_volatility\" src=\"https://github.com/user-attachments/assets/b65a2565-e155-457e-9e44-eafb2bfa3f3e\" /\u003e\n\n\n\n## Requirements\n\n- Python 3.10+ (target: 3.14)\n- `pydantic \u003e= 2`, `PyYAML`, `pandas`, `matplotlib`, `seaborn`\n- For AI cognition: `openai` (and/or `anthropic`)\n\n## Install\n\n```bash\ngit clone https://github.com/arianXdev/constitution-sim.git\ncd constitution-sim\npip install -e \".[dev,llm]\"     # core + tests + LLM SDKs (recommended)\n# or, no-LLM-only install:\npip install -e \".[dev]\"\n```\n\nThis exposes a `constitution-sim` console entry point.\n\n## Quickstart (AI-powered)\n\n```bash\nexport OPENAI_API_KEY=sk-...\nconstitution-sim run \\\n  --constitution constitutions/advanced_constitution.yaml \\\n  --scenario     constitutions/scenario.yaml \\\n  --turns 20 --seed 42 \\\n  --log         /tmp/cs/events.jsonl \\\n  --metrics-out /tmp/cs/metrics.csv\n```\n\nThat's it. The default `--agent-type auto` notices the key, spins up\nLLM-powered Executive / Legislature / Judiciary / Media / Bureaucracy\nagents, and runs the simulation. You'll see a one-liner telling you\nwhich provider was picked.\n\nWant to force a provider explicitly?\n\n```bash\nconstitution-sim run --agent-type openai    --model gpt-4o-mini       ...\nconstitution-sim run --agent-type anthropic --model claude-sonnet-4-5 ...\n```\n\nWant deterministic, no-API runs (for tests / reproducibility)?\n\n```bash\nconstitution-sim run --agent-type heuristic ...\n```\n\n## The four CLI subcommands\n\n```bash\n# 1. Validate a constitution YAML against the schema.\nconstitution-sim validate --constitution constitutions/advanced_constitution.yaml\n\n# 2. Run a simulation (single seed or multi-seed evaluation).\nconstitution-sim run \\\n  --constitution constitutions/advanced_constitution.yaml \\\n  --scenario     constitutions/scenario.yaml \\\n  --turns 30 --runs 5 --seed 42 \\\n  --log         /tmp/cs/events.jsonl \\\n  --metrics-out /tmp/cs/metrics.csv \\\n  --plot-dir    /tmp/cs/plots\n\n# 3. Replay a recorded event log (structured summary, not re-execution).\nconstitution-sim replay --log /tmp/cs/eval_logs/run_0_events.jsonl --show-first 5\n\n# 4. Compare two evaluations (e.g. two constitutions).\nconstitution-sim compare --a /tmp/cs/metrics_A.csv --b /tmp/cs/metrics_B.csv\n```\n\n## What the LLM sees\n\nFor each turn, the LLM agent is prompted with:\n\n- A role-specific persona (Executive / Legislature / …).\n- The constitution's name, description, and the list of other roles.\n- Its own declared goals and utility weights (from the YAML).\n- A partial state view filtered by its `observation_limits`.\n- **Public political history**: recent public actions taken by all actors.\n- **Inbox messages**: any negotiation/signals received during the turn's deliberation phase.\n- A short memory of its own recent decisions (and whether they were legal).\n- The exact set of typed actions it's allowed to return.\n\nIt replies with one JSON object describing a single action. If the LLM\nreturns malformed JSON or an action outside its permission set, the\nagent silently falls back to the deterministic heuristic policy — the\nsimulator never breaks.\n\n## Project structure\n\n```\nsrc/constitution_sim/\n  models/        Pydantic schemas: Constitution, Role, Rule, WorldState, actions\n  core/          SimulationEngine, RulesEngine, Scheduler, EventLogger\n  agents/        BaseAgent, DeterministicHeuristicAgent, LLMAgent, providers\n  scenarios/     Shock model + ScenarioEngine\n  analysis/      MetricsCollector, Evaluator, plot\n  app/           CLI (validate / run / replay / compare)\nconstitutions/\n  simple_constitution.yaml\n  advanced_constitution.yaml\n  strong_executive_constitution.yaml\n  scenario.yaml\ndocs/\n  architecture.md\n  tutorial.md\ntests/\n```\n\n## Tests\n\n```bash\npytest -q\n```\n\nAll tests should pass. `tests/test_determinism.py` explicitly asserts\nthat two heuristic-mode runs with the same seed produce byte-identical\nevent logs. `tests/test_llm_agent.py::test_live_openai_smoke` runs a\nreal LLM round-trip when `OPENAI_API_KEY` is set, and is automatically\nskipped otherwise.\n\n## Headline experiment\n\nCompare a balanced constitution against a strong-executive one (3 runs ×\n12 turns, seed 11). The strong-executive YAML pushes power_concentration\nfrom ~0.47 to ~0.92 and adds illegal-action attempts to the log: laws\nwritten by one actor, judiciary unable to push back. That's the\nframework working as intended — see `docs/tutorial.md` for a walkthrough.\n\n## Design highlights\n\n- `WorldState` is the single canonical truth; agents only ever see a\n  `StateView`.\n- Every action attempt is recorded in the JSONL event log, including\n  the rules-engine reason for any rejection.\n- `Role.observation_limits` lets the constitution define what each role\n  can see (e.g. the Bureaucracy doesn't see pending bills in\n  `advanced_constitution.yaml`).\n- `Role.utility_weights` drives heuristic voting and is surfaced to\n  LLM agents in their prompt as part of the persona.\n- `RulesEngine` does both permission checks AND state-level legality\n  checks (you can't vote on a non-existent bill, you can't declare\n  emergency powers if the constitution doesn't allow them).\n\nSee [`docs/architecture.md`](docs/architecture.md) for the full design\nand [`docs/tutorial.md`](docs/tutorial.md) for an end-to-end \"use it\nlike I'm 10\" walkthrough.\n\n## Out of scope (intentional)\n\nThis is an MVP, not a finished research instrument. The following are\nexplicit non-goals at this stage:\n\n- Persistent economic/demographic simulation (state variables are scalars, not vector economies).\n- Fine-tuned LLMs or RL self-play.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farianxdev%2Fconstitution-sim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farianxdev%2Fconstitution-sim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farianxdev%2Fconstitution-sim/lists"}