{"id":29625543,"url":"https://github.com/maxonary/a2a-electoral-rag","last_synced_at":"2025-07-21T06:37:23.067Z","repository":{"id":301639954,"uuid":"1009890777","full_name":"maxonary/a2a-electoral-rag","owner":"maxonary","description":"U.S. governance-inspired coordination strategies in multi-agent AI systems","archived":false,"fork":false,"pushed_at":"2025-07-06T10:40:30.000Z","size":6,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-06T11:33:21.075Z","etag":null,"topics":["a2a-protocol","elections","multi-agent-systems"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maxonary.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2025-06-27T22:44:30.000Z","updated_at":"2025-07-06T10:42:04.000Z","dependencies_parsed_at":"2025-06-27T23:31:18.255Z","dependency_job_id":"cc1c8e7a-ba09-4c4a-9c48-d56f8f76973d","html_url":"https://github.com/maxonary/a2a-electoral-rag","commit_stats":null,"previous_names":["maxonary/electoral-rag","maxonary/electoral-a2a"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/maxonary/a2a-electoral-rag","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxonary%2Fa2a-electoral-rag","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxonary%2Fa2a-electoral-rag/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxonary%2Fa2a-electoral-rag/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxonary%2Fa2a-electoral-rag/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maxonary","download_url":"https://codeload.github.com/maxonary/a2a-electoral-rag/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxonary%2Fa2a-electoral-rag/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266253928,"owners_count":23900058,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["a2a-protocol","elections","multi-agent-systems"],"created_at":"2025-07-21T06:37:22.566Z","updated_at":"2025-07-21T06:37:23.061Z","avatar_url":"https://github.com/maxonary.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Electoral \"RAG\": Republic of Agents Governance\n\nA research prototype exploring governance-inspired coordination strategies in multi-agent AI systems.\n\u003cimg width=\"1121\" alt=\"screenshot\" src=\"https://github.com/user-attachments/assets/22f37a4d-5809-40db-8545-75395ca40d2a\" /\u003e\n\nThis project simulates a democratic decision-making process among LLM-based agents — modeled after the U.S. electoral system — to reason, vote, and act collaboratively on complex tasks. The system compares hierarchical, democratic, and electoral college-style approaches to evaluate performance, robustness, and interpretability in distributed agent environments.\n\n## Why?\n\nMany multi-agent systems rely on flat hierarchical designs. In the real-world, humans govern often democratically. Were drawing inspiration from political structures like the Electoral College, popular votes, and checks-and-balances.\n\n## The System\nAgents reason individually and cast votes. Electors aggregate group decisions. The Coordinator Agent collects electoral outcomes and executes final actions.\n\n```mermaid\n---\nconfig:\n  theme: neo\n---\ngraph TD\n  subgraph \"Agent Clusters (States)\"\n    A1[\"Agent A1 (Data)\"] --\u003e|votes| S1[\"State Elector 1 (5 votes)\"]\n    A2[\"Agent A2 (Data)\"] --\u003e|votes| S1\n    B1[\"Agent B1 (Planning)\"] --\u003e|votes| S2[\"State Elector 2 (10 votes)\"]\n    B2[\"Agent B2 (Planning)\"] --\u003e|votes| S2\n    B3[\"Agent B3 (Planning)\"] --\u003e|votes| S2\n    C1[\"Agent C1 (Security)\"] --\u003e|votes| S3[\"State Elector 3 (3 votes)\"]\n  end\n\n  subgraph \"Electors\"\n    S1 --\u003e Coordinator[\"Coordinator Agent\"]\n    S2 --\u003e Coordinator\n    S3 --\u003e Coordinator\n  end\n\n  Coordinator --\u003e|majority| Decision[\"Final Action or Plan\"]\n```\n\n- **Elector Aggregation**: Weighted \"state\" electors aggregate group decisions.\n- **Coordinator Agent**: Collects electoral outcomes and executes final actions.\n- **Benchmarking Tools**: Compare decision quality, latency, and cost across governance models.\n\n## Example Scenarios\n\n- Choosing optimal plans from multiple LLM agent proposals  \n- Prioritizing features for an app from subdomain agents (e.g., UI, Backend, Security)  \n- Deciding on procurement strategies using weighted expert groups  \n- Writing a Jira ticket\n- Writing a PR description\n\n## Quick-start\n\nFollow the steps below to set up a fresh virtual environment, install the required dependencies, and run a demo election locally. The only prerequisite is Python 3.9 or newer.\n\n```bash\n# Create an isolated virtual environment\npython -m venv .venv\nsource .venv/bin/activate\n\n# Install the dependencies\npip install --upgrade pip\npip install -r requirements.txt\n\n# Run the built-in demo in the terminal\npython agent_voting_system.py\n```\n\n### Using GPT-4o instead of the random agent\n\nIf you have an OpenAI API key you can power each agent with GPT-4o. Simply export your key **before** running the demo:\n\n```bash\nexport OPENAI_API_KEY=\"sk-...\"\npython agent_voting_system.py\n```\n\nThe system will automatically detect the environment variable and switch to `ChatGPTAgent` for a more meaningful election.\n\nYou can also create a .env file and add your OpenAI API key to it.\n\n---\n\n## Running as an Agent-to-Agent (A2A) service\n\nThe repository also ships with a minimal HTTP server that exposes the coordinator through [Google's Agent-to-Agent protocol](https://github.com/a2aproject/a2a-python). To start the service run:\n\n![Agent Card JSON Data](https://github.com/user-attachments/assets/f9566bed-46e6-4401-a2a9-f8bd81c6b307)\n\n```bash\npython a2a_voting_server.py\n```\n\nThe server listens on `http://localhost:5000` by default (change the port via `PORT=…`). Once it is up you can\n\n```bash\n# Inspect the agent card              \ncurl http://localhost:5000/.well-known/agent.json | jq\n\n# Delegate an arbitrary task via the a2a CLI\npip install python-a2a[cli]   # one-off\n\na2a send http://localhost:5000 \"Design a data warehouse for e-commerce\"\n```\n\n---\n\n## File overview\n\n- `agent_voting_system.py` – core logic: agents, electors, coordinator, demo main\n- `chatgpt_agent.py` – optional drop-in replacement backed by the OpenAI Chat Completion API\n- `a2a_voting_server.py` – HTTP wrapper that exposes the coordinator as an A2A agent\n\n---\n\n## License\n\nThis project is licensed under the terms of the MIT licence. See the `LICENSE` file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxonary%2Fa2a-electoral-rag","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxonary%2Fa2a-electoral-rag","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxonary%2Fa2a-electoral-rag/lists"}