{"id":51040256,"url":"https://github.com/sneg55/simswarm","last_synced_at":"2026-06-22T10:02:30.619Z","repository":{"id":363454775,"uuid":"1192957315","full_name":"sneg55/SimSwarm","owner":"sneg55","description":"Open-source, self-hostable swarm-intelligence simulations with LLM agents: reports, entity graphs, and prediction markets.","archived":false,"fork":false,"pushed_at":"2026-06-09T00:55:59.000Z","size":17448,"stargazers_count":3,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T02:24:14.288Z","etag":null,"topics":["agent-based-simulation","fastapi","llm-agents","mit-license","multi-agent","prediction-markets","self-hosted","simulation","temporal","vue"],"latest_commit_sha":null,"homepage":"https://simswarm.xyz","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/sneg55.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-26T18:20:42.000Z","updated_at":"2026-06-09T00:52:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sneg55/SimSwarm","commit_stats":null,"previous_names":["sneg55/simswarm"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/sneg55/SimSwarm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sneg55%2FSimSwarm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sneg55%2FSimSwarm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sneg55%2FSimSwarm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sneg55%2FSimSwarm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sneg55","download_url":"https://codeload.github.com/sneg55/SimSwarm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sneg55%2FSimSwarm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34643624,"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-22T02:00:06.391Z","response_time":106,"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-based-simulation","fastapi","llm-agents","mit-license","multi-agent","prediction-markets","self-hosted","simulation","temporal","vue"],"created_at":"2026-06-22T10:02:29.818Z","updated_at":"2026-06-22T10:02:30.609Z","avatar_url":"https://github.com/sneg55.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SimSwarm\n\nSwarm intelligence simulations. Upload a document, set a prediction goal, and watch AI agents debate, trade, and publish across a simulated ecosystem. Get a deep analysis report, entity knowledge graph, prediction market data, and full chat replay.\n\nSimSwarm is open source and self-hostable. A read-only public demo (a static snapshot) runs at [simswarm.xyz](https://simswarm.xyz). Self-host with `DEMO_MODE=true` to run your own instance in the same read-only mode.\n\n**Live demo: [simswarm.xyz](https://simswarm.xyz)  ·  Documentation: [docs.simswarm.xyz](https://docs.simswarm.xyz)**\n\n## Architecture\n\n```\nFrontend (Vue 3 + Vite + Tailwind)\n        |\nSaaS API (FastAPI)\n        |\n   +----------+-----------+-----------+\n   |                      |           |\nTemporal Worker     PostgreSQL    Redis\n   |\n   +-- sim_workflow (Temporal) — owns full sim lifecycle + GPU provisioning\n   |        |\n   |        +-- GPU Workers (RunPod spot) -- simswarm engine + vLLM (Qwen3-14B)\n   |                 |\n   |                 +-- artifacts → MinIO (chat_log, posts, trades, graph)\n   |\n   +-- generate_report_task (Celery task, Redis broker; enqueued by a Temporal activity) -- Claude Opus 4.6 (Anthropic Messages API)\n```\n\n| Layer | Technology |\n|-------|-----------|\n| Frontend | Vue 3 (Composition API), Vite 6, Pinia, Tailwind CSS, Cytoscape.js |\n| Backend | Python 3.11+, FastAPI, async SQLAlchemy + asyncpg, Celery + Redis (report task), Alembic |\n| Orchestration | Temporal — owns sim lifecycle, GPU provisioning, and activity retries |\n| Database | PostgreSQL 16 |\n| Engine | `simswarm/` — native async Python swarm engine |\n| GPU | RunPod spot instances (H100/L40S/A100), ephemeral per-job |\n| Fast LLM | Qwen3-14B via vLLM on-pod with tool calling (hermes parser) |\n| Smart LLM | Claude Opus 4.6 via Anthropic Messages API (off-pod, report gen) |\n| Enrichment | xAI Grok (web_search + x_search) |\n| Object storage | MinIO (S3-compatible) for simulation artifacts |\n| Proxy | Caddy with automatic TLS, security headers, SSRF protection |\n| CI/CD | GitHub Actions — on push: tests + Cloudflare Pages deploys (static demo + docs). Worker-image build and single-VPS deploy are manual (`workflow_dispatch`). |\n\n## Prerequisites\n\n- Docker \u0026 Docker Compose\n- Node.js 20+ (for local frontend dev)\n- Python 3.11+ (for local backend dev)\n\n## Quick Start (Docker)\n\n```bash\n# 1. Clone\ngit clone https://github.com/sneg55/SimSwarm.git\ncd SimSwarm\n\n# 2. Configure environment\ncp .env.example .env\n# Edit .env with your values:\n#   POSTGRES_PASSWORD, SECRET_KEY, RUNPOD_API_KEY, NEO4J_PASSWORD, DOMAIN\n\n# 3. Build and run\ndocker compose build\ndocker compose run --rm migrate    # run database migrations\ndocker compose up -d               # start all services\n```\n\nThe app will be available at `http://localhost` (or your configured `DOMAIN`).\n\n\u003e Neo4j and MinIO are **not** in the Compose stack — they're external services. You also need a RunPod key for GPU pods, and the model weights must be uploaded to MinIO before the first run. See the full **[self-hosting guide](https://docs.simswarm.xyz/self-hosting/architecture)** for the complete walkthrough.\n\n### Services\n\n| Service | Container | Port | Description |\n|---------|-----------|------|-------------|\n| API | simswarm-api | 8080 | FastAPI backend |\n| Celery | simswarm-celery | — | Async job worker |\n| PostgreSQL | simswarm-db | 5432 | Database |\n| Redis | simswarm-redis | 6379 | Message queue \u0026 cache |\n| Caddy | simswarm-caddy | 80, 443 | Reverse proxy + TLS |\n\n## Local Development\n\n### Backend\n\n```bash\npython -m venv .venv\nsource .venv/bin/activate\npip install -e \".[dev]\"\n\n# Run API server\nuvicorn saas.main:create_app --factory --reload --port 8080\n\n# Run Celery worker\ncelery -A saas.workers.celery_app worker --loglevel=info\n```\n\n### Frontend\n\n```bash\ncd frontend\nnpm install\nnpm run dev        # Vite dev server at http://localhost:5173\nnpm run build      # Production build to frontend/dist/\n```\n\n### Tests\n\n```bash\n# Backend tests (1000+ tests, in-memory SQLite — no external DB needed)\npytest\n\n# Frontend tests (Vitest)\ncd frontend \u0026\u0026 npm test\n```\n\n## Deployment\n\n**Self-hosting** is the Docker Compose stack above — see the [Quick Start](#quick-start-docker) and the [self-hosting docs](https://docs.simswarm.xyz/self-hosting/architecture). It brings up the API, Celery, Temporal worker, Postgres, Redis, and Caddy; you supply a RunPod key for GPU pods and an S3-compatible store (MinIO) for artifacts.\n\n**This repo's hosted surfaces** deploy automatically on push to `main` via GitHub Actions, both to Cloudflare Pages:\n\n- `simswarm.xyz` — a static, read-only demo snapshot (`deploy-pages.yml`)\n- `docs.simswarm.xyz` — this documentation (`deploy-docs.yml`)\n\nA single-VPS deploy script (`deploy.sh`) and the GPU worker-image build remain available as manual (`workflow_dispatch`) workflows. `deploy.sh` validates a single Alembic head, gracefully stops Celery, runs migrations, rebuilds frontend assets, and health-checks the API.\n\n### Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `DATABASE_URL` | Yes | PostgreSQL connection string |\n| `SECRET_KEY` | Yes | JWT signing key |\n| `POSTGRES_PASSWORD` | Yes | Database password (used by docker-compose) |\n| `NEO4J_PASSWORD` | Yes | Neo4j graph database password |\n| `RUNPOD_API_KEY` | Yes | RunPod GPU provisioning |\n| `ANTHROPIC_API_KEY` | Yes | Claude Opus 4.6 for report generation |\n| `SMART_MODEL` | No | Report model override (default: `claude-opus-4-6`) |\n| `DEMO_MODE` | No | Set `true` for read-only demo (disables signup + job submission) |\n| `XAI_API_KEY` | No | xAI API key for seed enrichment (web + X search) |\n| `DOMAIN` | No | Production domain (default: `localhost`) |\n| `MINIO_ENDPOINT` | Yes | MinIO for simulation artifact storage |\n| `MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY` | Yes | MinIO credentials |\n| `OPENAI_API_KEY` | No | Optional embeddings fallback |\n| `ALERT_WEBHOOK_URL` | No | Webhook URL for orphan pod / error alerts |\n\nFull variable reference: **[docs.simswarm.xyz/self-hosting/env-reference](https://docs.simswarm.xyz/self-hosting/env-reference)**.\n\n## Project Structure\n\n```\nsaas/\n  adapters/         # External LLM adapter (Anthropic Messages API)\n  auth/             # Authentication: API, models, JWT, email verification\n  jobs/             # Simulation lifecycle: API, runner, tasks, tasks_report (off-pod\n                    #   report gen), recovery, persistence, enrichment, cleanup, alerts,\n                    #   export, share, report + report_tools_minio\n  gpu/              # GPU providers: abstract base + RunPod implementation\n  storage/          # MinIO client for simulation artifact upload/download\n  constants/        # Tier config (timeouts, etc.)\n  workers/          # Celery app + async utilities\n  middleware/       # Error tracking middleware\n  models/           # Base model class + re-exports for Alembic discovery\n  config.py         # Pydantic Settings\n  main.py           # FastAPI app factory\nsimswarm/           # Native swarm engine — entities, engine, belief, graph, report, envs\nfrontend/src/\n  views/            # Pages (Landing, Dashboard, Wizard, Results, Account)\n  components/       # Reusable components (graph/, wizard/, results/, data/)\n  composables/      # Shared Composition API logic\n  stores/           # Pinia (auth, config)\n  api/              # Axios clients\ninfra/docker/       # GPU worker image (Dockerfile.worker, run_job_v2.py, worker_api.py)\nalembic/            # Database migrations\ntests/              # pytest + pytest-asyncio (1000+ tests)\n```\n\n## Simulation Tiers\n\nThree tiers (`small` / `medium` / `large`) set the GPU class and timeout. Agent count, model, GPU type, and round count are operator-configurable **per tier** via the `model_routing` table — they are not fixed by the tier itself.\n\n| Tier | Timeout | Default GPU cloud |\n|------|---------|-------------------|\n| Small | 45 min | ALL |\n| Medium | 5 hours | ALL |\n| Large | 12 hours | SECURE |\n\nSee [GPU Runner](https://docs.simswarm.xyz/self-hosting/gpu-runner) for tier configuration and routing.\n\n## Key Features\n\n- **Four result views** — Story (narrative overview), Graph (interactive entity graph), Data (prediction market charts), Report (deep analysis with citations).\n- **Off-pod report generation** — GPU pod uploads sim artifacts to MinIO and tears down; a Celery task then drives Claude Opus 4.6 through a tool-calling loop over the artifacts. Any failure before `COMPLETED` marks the job FAILED.\n- **Draft workflow** — Save partial simulations and resume later from any wizard step.\n- **Seed enrichment** — Optionally enriches seed text with live web + X/Twitter research via xAI Grok. Toggle per-simulation, retry on failure.\n- **Entity graph** — Interactive Cytoscape viz with per-agent activity stats and interaction edges (follow / reply / like / mention) extracted by `simswarm.graph`.\n- **Belief dynamics** — Agent positions and confidence mutate per round via `simswarm.belief.update_beliefs` using trust-weighted exposure math.\n- **Simulation data** — Market predictions, social posts, and trading data extracted from the GPU simulation's SQLite databases and uploaded to MinIO.\n- **Deploy-safe recovery** — If a deploy kills the Celery worker mid-simulation, recovery auto-resumes jobs on their existing GPU pods, and re-enqueues orphaned `REPORTING`-state jobs.\n- **Share links** — Public share URLs with OpenGraph meta tags for rich previews on Slack/Twitter/LinkedIn.\n- **Error monitoring** — API exceptions and Celery failures captured to `error_events` table with auto-pruning.\n\n## Documentation\n\nFull documentation — concepts, self-hosting, engine internals, and API reference — lives at **[docs.simswarm.xyz](https://docs.simswarm.xyz)**:\n\n- [What is SimSwarm](https://docs.simswarm.xyz/introduction/what-is-simswarm) · [Lineage vs MiroFish/MiroShark](https://docs.simswarm.xyz/introduction/lineage-and-differences)\n- [Quickstart](https://docs.simswarm.xyz/quickstart/docker-quickstart) · [Self-Hosting](https://docs.simswarm.xyz/self-hosting/architecture)\n- [Engine Internals](https://docs.simswarm.xyz/engine/architecture) (belief dynamics, environments, story signals, graph build)\n- [API Reference](https://docs.simswarm.xyz/api/simswarm)\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsneg55%2Fsimswarm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsneg55%2Fsimswarm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsneg55%2Fsimswarm/lists"}