{"id":50995020,"url":"https://github.com/vinodhalaharvi/societyos","last_synced_at":"2026-06-20T08:03:17.088Z","repository":{"id":362909718,"uuid":"1259402606","full_name":"vinodhalaharvi/societyos","owner":"vinodhalaharvi","description":"Multi-agent collaboration system built with Qwen Cloud — agents with distinct roles decompose tasks, negotiate, and resolve conflicts to outperform single-agent baselines.","archived":false,"fork":false,"pushed_at":"2026-06-06T13:46:15.000Z","size":77,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-06T14:21:56.572Z","etag":null,"topics":["agent-society","alibaba-cloud","autonomous-agents","d3js","fastapi","hackathon","llm","multi-agent","python","qwen","rule-engine","sqlite"],"latest_commit_sha":null,"homepage":null,"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/vinodhalaharvi.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-06-04T13:24:46.000Z","updated_at":"2026-06-06T12:57:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vinodhalaharvi/societyos","commit_stats":null,"previous_names":["vinodhalaharvi/societyos"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/vinodhalaharvi/societyos","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vinodhalaharvi%2Fsocietyos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vinodhalaharvi%2Fsocietyos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vinodhalaharvi%2Fsocietyos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vinodhalaharvi%2Fsocietyos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vinodhalaharvi","download_url":"https://codeload.github.com/vinodhalaharvi/societyos/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vinodhalaharvi%2Fsocietyos/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34561766,"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-06-20T02:00:06.407Z","response_time":98,"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":["agent-society","alibaba-cloud","autonomous-agents","d3js","fastapi","hackathon","llm","multi-agent","python","qwen","rule-engine","sqlite"],"created_at":"2026-06-20T08:03:16.324Z","updated_at":"2026-06-20T08:03:17.083Z","avatar_url":"https://github.com/vinodhalaharvi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SocietyOS\n# SocietyOS\n\n**A configurable multi-agent platform where specialized AI citizens negotiate, debate, and collaborate to solve complex problems.**\n\nDrop in a task. Watch a society of agents — each with a distinct role, memory, and voting weight — argue, revise, and synthesize a final report. Every decision is persisted and replayable via a visual time machine.\n\nBuilt for the **Alibaba Cloud × Qwen Hackathon — Track 3: Agent Society**.\n\n---\n\n## Demo\n\n![SocietyOS UI](docs/demo.gif)\n\n```\nsocietyos serve\n# open http://localhost:8000\n# click ▶ RUN SOCIETY\n```\n\n---\n\n## Quickstart\n\n```bash\n# 1. Clone\ngit clone https://github.com/vinodhalaharvi/societyos.git\ncd societyos\n\n# 2. Virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# 3. Install\npip install -e \".[dev]\"\n\n# 4. Configure\ncp .env.example .env\n# Edit .env — add your QWEN_API_KEY\n\n# 5. Run\nsocietyos serve\n# open http://localhost:8000\n```\n\n---\n\n## What it does\n\n| Feature | Description |\n|---|---|\n| **Configurable societies** | Define any agent society in a YAML file — roles, personalities, voting weights, tools, memory |\n| **Rule engine** | Write rules in markdown — injected as the first block of every agent's system prompt |\n| **Orchestration loop** | Decompose → assign → parallel execution → conflict detection → debate → vote → synthesize |\n| **Pluggable voting** | `weighted_vote`, `majority`, `consensus`, `dictator` — set per society in config |\n| **Persistent memory** | Every run, proposal, vote, and report saved to SQLite — nothing is lost |\n| **Time machine** | Drag the timeline scrubber to replay any past run round by round |\n| **Agent reputation** | Win/loss record tracked per agent per society across all runs |\n| **D3 visualization** | Live force-directed graph — nodes pulse when thinking, edges flash when proposals travel |\n| **Benchmark** | Every run compares society output vs a single-agent baseline |\n\n---\n\n## Society config\n\nDefine a society in YAML:\n\n```yaml\nsociety:\n  name: \"Startup Board\"\n  decision_strategy: weighted_vote   # weighted_vote | majority | consensus | dictator\n  max_rounds: 5\n  benchmark_vs_single_agent: true\n\nagents:\n  - name: CEO\n    role: Strategic decision maker\n    personality: visionary, bold, risk-tolerant\n    weight: 1.5\n    tools: [web_search]\n    memory: short_term\n\n  - name: CFO\n    role: Financial risk evaluator\n    personality: conservative, data-driven\n    weight: 1.2\n    tools: [calculator]\n    memory: short_term\n\n  - name: Devil's Advocate\n    role: Challenge every proposal\n    personality: skeptical, contrarian\n    weight: 0.8\n    tools: []\n    memory: none\n\nrules: |\n  ## Board Rules\n  - Every claim must be backed by reasoning or data.\n  - CFO has financial veto on any unquantified cost proposal.\n  - Final report must include a Risk section and Next Steps.\n\noutput:\n  format: markdown\n  save_to: ./reports/\n```\n\nRun it:\n\n```bash\nsocietyos validate configs/examples/startup_board.yaml\nsocietyos serve\n```\n\n---\n\n## Rule engine\n\nRules are written in markdown and compiled into the system prompt prefix for every agent:\n\n```\nYou are {name}, the {role} in {society_name}.\n\n## Society rules (follow these strictly)\n- Every claim must be backed by reasoning or data.\n- CFO has financial veto on any unquantified cost proposal.\n...\n```\n\nThe LLM reads rules before the task — they reliably shape agent behavior. Edit rules live in the UI rule editor and apply them to the next run.\n\n---\n\n## Architecture\n\n```\nBrowser (index.html)\n  │  POST /api/runs → SSE stream\n  │  GET  /api/runs/{id}/replay?up_to_round=N  ← time machine\n  ▼\nFastAPI (uvicorn)\n  │  Router → Runner → Coordinator → Agents (asyncio.gather)\n  │                                      │\n  │                                      └── chat() → Qwen Cloud API\n  │                                               (qwen-plus model)\n  │\n  └── SQLite (WAL mode)\n        runs · events · votes · reports · agent_reputation\n```\n\nSee `architecture.png` for the full diagram.\n\n---\n\n## Project structure\n\n```\nsocietyos/\n├── societyos/\n│   ├── cli.py              # societyos hello | validate | serve\n│   ├── settings.py         # env var config\n│   ├── qwen_client.py      # async Qwen API wrapper\n│   ├── config/\n│   │   ├── models.py       # Pydantic: SocietyConfig, AgentConfig\n│   │   └── loader.py       # YAML → validated SocietyConfig\n│   ├── agents/\n│   │   ├── base.py         # BaseAgent, RoundContext\n│   │   ├── factory.py      # AgentFactory.build_all(config)\n│   │   ├── proposal.py     # Proposal dataclass + JSON parser\n│   │   ├── prompt.py       # System prompt compiler\n│   │   └── memory/         # none | short_term | episodic\n│   ├── society/\n│   │   ├── coordinator.py  # Main orchestration loop\n│   │   ├── blackboard.py   # Shared state between agents\n│   │   ├── runner.py       # Coordinator + SQLite persistence\n│   │   ├── events.py       # RunEvent → SSE\n│   │   └── voting/         # weighted | majority | consensus\n│   ├── db/\n│   │   ├── migrations.py   # Schema creation on startup\n│   │   ├── connection.py   # aiosqlite connection\n│   │   └── queries/        # runs | events | votes | reports | reputation\n│   └── server/\n│       ├── app.py          # FastAPI app + static frontend\n│       └── routes/runs.py  # REST + SSE endpoints\n├── frontend/\n│   └── index.html          # D3 graph + timeline + feed + rule editor\n├── configs/examples/\n│   └── startup_board.yaml\n└── tests/                  # 66 passing tests\n```\n\n---\n\n## CLI\n\n```bash\nsocietyos hello                                    # check install\nsocietyos validate configs/examples/startup_board.yaml  # validate config\nsocietyos serve                                    # start server at :8000\nsocietyos serve --port 9000 --no-reload            # custom port\n```\n\n---\n\n## API\n\n```\nPOST /api/runs                    start a run (SSE stream)\nGET  /api/runs                    list recent runs\nGET  /api/runs/{id}               get run metadata\nGET  /api/runs/{id}/replay        replay events (time machine)\n  ?up_to_round=N                  filter to round N\nGET  /api/runs/{id}/report        final report markdown\nGET  /api/runs/{id}/reputation    agent win/loss record\nGET  /health                      liveness check\n```\n\n---\n\n## Tests\n\n```bash\npytest tests/ -v   # 66 passing\n```\n\n---\n\n## Environment variables\n\n| Variable | Default | Description |\n|---|---|---|\n| `QWEN_API_KEY` | — | Alibaba Cloud API key (required for real runs) |\n| `QWEN_BASE_URL` | dashscope-intl endpoint | Qwen compatible API base URL |\n| `QWEN_MODEL` | `qwen-plus` | Model name |\n| `SOCIETYOS_DB_PATH` | `./societyos.db` | SQLite database file |\n| `SOCIETYOS_REPORTS_DIR` | `./reports/` | Where reports are saved |\n\n---\n\n## Built with\n\n- **Qwen Cloud** (Alibaba) — LLM for all agent reasoning\n- **FastAPI** — async backend + SSE streaming\n- **D3.js** — force-directed agent graph\n- **SQLite** — WAL-mode persistence\n- **Pydantic** — config validation\n- **Python asyncio** — parallel agent execution\n\n---\n\n## License\n\nMIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvinodhalaharvi%2Fsocietyos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvinodhalaharvi%2Fsocietyos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvinodhalaharvi%2Fsocietyos/lists"}