{"id":51196875,"url":"https://github.com/mohith-das/leanswarm","last_synced_at":"2026-06-27T21:08:22.929Z","repository":{"id":352834780,"uuid":"1216695684","full_name":"mohith-das/leanswarm","owner":"mohith-das","description":"Lean Swarm is a cost-focused multi-agent prediction and simulation engine designed to approximate MiroFish-class narrative forecasting with aggressive batching, sparse activation, hybrid state, and strict LLM routing guardrails.","archived":false,"fork":false,"pushed_at":"2026-04-21T10:39:50.000Z","size":2284,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-04T01:04:06.727Z","etag":null,"topics":["future-prediction","knowledge-graph","low-cost","multi-agent-simulation","python3","social-prediction","swarm-intelligence"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/leanswarm/","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/mohith-das.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","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-04-21T06:36:45.000Z","updated_at":"2026-06-03T02:57:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mohith-das/leanswarm","commit_stats":null,"previous_names":["mohith-das/leanswarm"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/mohith-das/leanswarm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mohith-das%2Fleanswarm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mohith-das%2Fleanswarm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mohith-das%2Fleanswarm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mohith-das%2Fleanswarm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mohith-das","download_url":"https://codeload.github.com/mohith-das/leanswarm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mohith-das%2Fleanswarm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34867868,"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-27T02:00:06.362Z","response_time":126,"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":["future-prediction","knowledge-graph","low-cost","multi-agent-simulation","python3","social-prediction","swarm-intelligence"],"created_at":"2026-06-27T21:08:22.105Z","updated_at":"2026-06-27T21:08:22.919Z","avatar_url":"https://github.com/mohith-das.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lean Swarm\n\nLean Swarm is a cost-focused multi-agent prediction and simulation engine designed to approximate\nMiroFish-class narrative forecasting with aggressive batching, sparse activation, hybrid state, and\nstrict LLM routing guardrails.\n\n## Overview\n\nGiven a seed document and a prediction question, Lean Swarm builds a simulated world of agents,\nruns a bounded number of interaction ticks, and returns:\n\n- a structured prediction report\n- a post-simulation world snapshot with agent states and relationship edges\n\nThe project is structured for open-source collaboration, MIT licensing, and PyPI publishing from\nday one.\n\n## Quickstart\n\n### Install From PyPI\n\n```bash\npip install leanswarm\n```\n\nThis installs the Python package, API, and CLI. Node.js is not required for the core package.\n\nOptional with `uv`:\n\n```bash\nuv pip install leanswarm\n```\n\n### Configure Live Providers\n\nDry-run mode works without any API keys. If you want live model routing, set one of:\n\n```bash\nexport OPENAI_API_KEY=...\nexport ANTHROPIC_API_KEY=...\n```\n\n### Run\n\n```bash\nleanswarm smoke\nleanswarm simulate --seed examples/seed.txt --question \"Will public trust rise this quarter?\"\nleanswarm api\nleanswarm bench\n```\n\n### Import In Python\n\n```python\nfrom leanswarm.engine.models import SimulationRequest\nfrom leanswarm.engine.simulator import LeanSwarmEngine\n```\n\n## Architecture\n\n### Core rules\n\n- All model traffic is routed through `engine/llm.py`.\n- Every LLM route and simulation tick is logged.\n- The engine uses Pydantic schemas at every boundary.\n- LLM calls are retried and concurrency-limited with semaphores.\n\n### Current engine shape\n\n- Tiered model routing with `FLAGSHIP`, `STANDARD`, and `CHEAP` tiers.\n- Batched group actions for active agents.\n- Seed-ingestion and world-building helpers that extract topics, entities, and a world graph from the seed document.\n- Seed-conditioned population construction with archetype jittering and bounded named-agent counts.\n- Hybrid numeric state for mood, energy, attention, and relationships.\n- Sparse activation and trigger heuristics that keep only a subset of agents active per tick.\n- Hierarchical memory slices for working, episodic, and semantic references backed by SQLite with vector-search support and deterministic offline fallback.\n- Disk-backed action caching via `diskcache`.\n- Early convergence detection on low-delta ticks.\n- A minimal Next.js viewer under `web/` for inspecting pasted simulation JSON and exploring the post-simulation world snapshot.\n\nSee [docs/architecture.md](docs/architecture.md) for more detail.\n\n### Optional web viewer\n\nThe `web/` app is a separate, optional Next.js inspector for pasted simulation JSON. It is not\nrequired to install or use the Python package or `leanswarm` CLI.\n\n```bash\ncd web\nnpm install\nnpm run dev\n```\n\n## CLI Usage\n\n### Smoke test\n\n```bash\nleanswarm smoke\n```\n\n### Simulate a scenario\n\n```bash\nleanswarm simulate \\\n  --seed examples/seed.txt \\\n  --question \"Will the policy announcement improve sentiment?\" \\\n  --activation-mode lean \\\n  --active-agent-fraction 0.25\n```\n\n### Run the API\n\n```bash\nleanswarm api --host 127.0.0.1 --port 8000\n```\n\n### Run the benchmark harness\n\n```bash\nleanswarm bench\n```\n\n## API Usage\n\n### Start server\n\n```bash\nleanswarm api\n```\n\n### Example request\n\n```bash\ncurl -X POST http://127.0.0.1:8000/simulate \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"seed_document\": \"A national survey shows mixed views on new policy proposals.\",\n    \"question\": \"Will approval improve over the next month?\",\n    \"rounds\": 4\n  }'\n```\n\n## Benchmarks\n\n`leanswarm bench` runs the same benchmark cases in both `lean` and `naive` activation modes and\nreturns a comparison payload with:\n\n- top-level deltas: `cost_ratio_naive_to_lean`, `quality_delta_lean_vs_naive`,\n  `runtime_ratio_naive_to_lean`\n- per-mode outputs under `modes.lean` and `modes.naive` (quality proxy, runtime, cache stats, token\n  and estimated cost totals)\n- `plot_points`: per-case points with `mode`, `score`, `cost_usd`, `runtime_seconds`,\n  `token_total`, and related fields for quality-vs-cost plotting\n\nThis lets you compare lean efficiency against naive full activation and plot quality-vs-cost points\ndirectly from benchmark output without extra transforms. The shipped cases are still lightweight\nproxy benchmarks rather than a full public benchmark pack.\n\n## Limitations\n\n- Dry-run routing is still heuristic even though it is seed-sensitive and grouped by task type.\n- The benchmark harness is still a compact proxy suite, not a full public-opinion evaluation set.\n- The web client is intentionally minimal, focused on inspecting and exploring simulation JSON.\n\n## Contributing\n\nContributions are welcome. Please open a focused PR with a clear summary of the behavior change\nand the validation you ran locally.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmohith-das%2Fleanswarm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmohith-das%2Fleanswarm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmohith-das%2Fleanswarm/lists"}