{"id":51456714,"url":"https://github.com/arvarik/bmas","last_synced_at":"2026-07-06T01:02:04.605Z","repository":{"id":365621513,"uuid":"1238230931","full_name":"arvarik/bmas","owner":"arvarik","description":"Blackboard multi-agent system coordinating autonomous LLM agents via a shared blackboard to solve complex tasks","archived":false,"fork":false,"pushed_at":"2026-06-18T06:31:42.000Z","size":13346,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-18T07:23:34.889Z","etag":null,"topics":["agentic-ai","ai-agents","blackboard-architecture","docker-compose","fastapi","llama-cpp","llm","llm-agents","multi-agent-system","python","redis","stigmergy","swarm","swarm-intelligence"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arvarik.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-14T00:00:37.000Z","updated_at":"2026-06-18T06:31:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/arvarik/bmas","commit_stats":null,"previous_names":["arvarik/bmas"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/arvarik/bmas","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arvarik%2Fbmas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arvarik%2Fbmas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arvarik%2Fbmas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arvarik%2Fbmas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arvarik","download_url":"https://codeload.github.com/arvarik/bmas/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arvarik%2Fbmas/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35174071,"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-07-05T02:00:06.290Z","response_time":100,"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":["agentic-ai","ai-agents","blackboard-architecture","docker-compose","fastapi","llama-cpp","llm","llm-agents","multi-agent-system","python","redis","stigmergy","swarm","swarm-intelligence"],"created_at":"2026-07-06T01:01:59.947Z","updated_at":"2026-07-06T01:02:04.565Z","avatar_url":"https://github.com/arvarik.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"mission-control/public/ant-head.png\" alt=\"Stigmergic Swarm Logo\" width=\"128\" height=\"128\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eStigmergic\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eBlackboard Multi-Agent Swarm (bMAS) Orchestration System\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#how-it-works\"\u003eHow It Works\u003c/a\u003e •\n  \u003ca href=\"#see-it-in-action\"\u003eSee It In Action\u003c/a\u003e •\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e •\n  \u003ca href=\"#documentation\"\u003eDocumentation\u003c/a\u003e •\n  \u003ca href=\"#components\"\u003eComponents\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-AGPL--3.0-blue.svg\" alt=\"License: AGPL-3.0\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/arvarik/bmas/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/arvarik/bmas/actions/workflows/ci.yml/badge.svg\" alt=\"CI\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://python.org\"\u003e\u003cimg src=\"https://img.shields.io/badge/Python-3.13+-3776AB?logo=python\u0026logoColor=white\" alt=\"Python 3.13+\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://typescriptlang.org\"\u003e\u003cimg src=\"https://img.shields.io/badge/TypeScript-6.x-3178C6?logo=typescript\u0026logoColor=white\" alt=\"TypeScript 6.x\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://nextjs.org\"\u003e\u003cimg src=\"https://img.shields.io/badge/Next.js-16-000000?logo=nextdotjs\u0026logoColor=white\" alt=\"Next.js 16\" /\u003e\u003c/a\u003e\n  \u003ca href=\"docker-compose.yml\"\u003e\u003cimg src=\"https://img.shields.io/badge/Docker-Compose-2496ED?logo=docker\u0026logoColor=white\" alt=\"Docker\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n**A distributed AI swarm built on the Blackboard Multi-Agent System (bMAS) architecture.** Stigmergic coordinates multiple LLM-powered agents through a shared blackboard with an LLM-driven Control Unit that dynamically selects agents per round and achieves structured, multi-round debate and consensus.\n\n\u003e *Named after [stigmergy](https://en.wikipedia.org/wiki/Stigmergy) — the mechanism by which individual agents coordinate through shared environmental signals (the blackboard) rather than direct communication.*\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/bmas-hero.png\" alt=\"Stigmergic — Landing Page\" width=\"720\" /\u003e\n\u003c/p\u003e\n\n## How It Works\n\n**Orchestration** — A Control Unit reads the shared blackboard each round, selects which agents to activate, and those agents execute concurrently by writing findings, plans, and critiques back to the board. Rounds repeat until the swarm reaches consensus, hits a budget ceiling, or exhausts max rounds. Domain-specific experts are generated dynamically per task, not pre-configured.\n\n**Observability** — Real-time execution graphs, distributed log streams across all agents, a blackboard command center, and per-model cost tracking are all visible in a live dashboard built with Next.js and Server-Sent Events.\n\n**Operations** — Pause at round boundaries, inject directives, steer which agents run next, and set budget ceilings. A complexity classifier routes every task to the cheapest capable model before any paid API call — using Gemini Flash Lite by default (or a local Qwen3-1.7B model on GPU). One YAML file configures the entire deployment. Just `docker compose up` and you're running.\n\n## See It In Action\n\n### Execution Graph\n\nSwimlane visualization showing agent turns grouped by round. Each node reveals what the agent did, why the Control Unit selected it, and what it cost.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/bmas-graph.png\" alt=\"Execution Graph — swimlane view of rounds and agent turns\" width=\"900\" /\u003e\n\u003c/p\u003e\n\n### Distributed Log Stream\n\nUnified chronological log across all agents with per-role filtering. Click any entry to expand structured fields — actor, model, round, output, and duration.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/bmas-logs.png\" alt=\"Distributed Log Stream — per-agent filtering with structured detail drawer\" width=\"900\" /\u003e\n\u003c/p\u003e\n\n### Blackboard Command Center\n\nThe shared knowledge store. Timeline of board entries with salience heat, entry types, and debate threading. Agent Minds shows each agent's model and contribution count.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/bmas-board.png\" alt=\"Blackboard Command Center — board entries and agent minds\" width=\"900\" /\u003e\n\u003c/p\u003e\n\n### Cost \u0026 Performance\n\nPer-model token breakdown, cost tracking, and an agent timeline showing when each role was active across rounds.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/bmas-stats.png\" alt=\"Cost tracking — token usage, cost breakdown, and agent timeline\" width=\"900\" /\u003e\n\u003c/p\u003e\n\n## Quick Start\n\n```bash\ngit clone https://github.com/arvarik/bmas.git\ncd bmas\n\n# Configure\ncp bmas.example.yaml bmas.yaml    # edit with your IPs and settings\ncp .env.example .env              # fill in secrets (API keys, passwords)\n\n# Start\ndocker compose up -d              # without GPU\ndocker compose --profile gpu up -d  # with GPU (enables triage)\n\n# Open Mission Control\nopen http://localhost:9321\n```\n\nSee [Quick Start Guide](docs/QUICKSTART.md) for the full walkthrough.\n\n## Documentation\n\n| Document | Description |\n|:---|:---|\n| [Quick Start](docs/QUICKSTART.md) | Get running in 5 minutes |\n| [Configuration](docs/CONFIGURATION.md) | Full `bmas.yaml` reference |\n| [Architecture](docs/architecture/README.md) | System architecture \u0026 component deep-dive |\n| [Node Setup](docs/NODE_SETUP.md) | Provisioning edge nodes with inference + agents |\n| [Design System](docs/design/DESIGN.md) | Mission Control UI specification |\n| [Hermes API](docs/HERMES_API.md) | Hermes Dashboard \u0026 Gateway API reference |\n\n## Components\n\nThe project is organized into six deployable components, each with its own README:\n\n| Component | Description |\n|:---|:---|\n| [`daemon/`](daemon/README.md) | **The brain.** Python FastAPI orchestrator — manages task lifecycle, cyclic blackboard execution, agent dispatch, and dual-write persistence (Redis + SQLite). |\n| [`mission-control/`](mission-control/README.md) | **The eyes.** Next.js 16 real-time dashboard — execution graphs, distributed logs, blackboard command center, cost tracking, and HITL controls. |\n| [`agent/`](agent/README.md) | **The hands.** FastAPI server deployed to each edge node — bridges the Daemon to Hermes agents via the Runs API with real-time trace and log shipping. |\n| [`redis/`](redis/README.md) | **The shared memory.** Redis 8 serves as the blackboard — the central knowledge store through which all agents coordinate via Pub/Sub, Streams, and Redlock. |\n| [`litellm/`](litellm/README.md) | **The router.** Unified OpenAI-compatible gateway that abstracts all model backends behind routing, cost tracking, and retry logic. |\n| [`triage/`](triage/README.md) | **The gatekeeper.** Complexity classifier that routes tasks to the cheapest capable model — Gemini Flash Lite API by default (no GPU), or local Qwen3-1.7B on vLLM for zero-cost classification. |\n\nAdditional directories:\n\n| Directory | Description |\n|:---|:---|\n| [`examples/`](examples/) | Sample configurations — multi-node homelab, minimal cloud, multi-provider routing |\n| [`scripts/`](scripts/) | Operational utilities — CI checks, profile deployment, health checks |\n| [`eval/`](eval/) | Evaluation harness — A/B testing, accuracy scoring, failure injection |\n| [`docs/`](docs/) | All documentation — architecture, design system, guides |\n\n## Papers\n\nThis project implements and extends multi-agent coordination architectures from published research:\n\n\u003e **Han, B. \u0026 Zhang, S. (2025).** *Exploring Advanced LLM Multi-Agent Systems Based on Blackboard Architecture.*\n\u003e [arXiv:2507.01701](https://arxiv.org/abs/2507.01701)\n\nThe foundational architecture. LLM agents coordinate through a shared blackboard with an LLM-driven control unit that dynamically selects agents per round — achieving competitive performance with state-of-the-art multi-agent systems while consuming fewer tokens. Stigmergic implements this as the **traditional** coordination variant.\n\n\u003e **Zhang, S., Shi, W. \u0026 Wang, H. (2026).** *PatchBoard: Schema-Grounded State Mutation for Reliable and Auditable LLM Multi-Agent Collaboration.*\n\u003e [arXiv:2605.29313](https://arxiv.org/abs/2605.29313)\n\nA complementary coordination paradigm where agents emit validated JSON-Patch mutations against a schema-grounded state tree through a deterministic kernel — achieving 84.6% task success (vs. 30.8% for LangGraph) with zero committed-state contamination under fault injection. Stigmergic implements this as the **PatchBoard** coordination variant.\n\n## License\n\nThis project is licensed under the [GNU Affero General Public License v3.0](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farvarik%2Fbmas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farvarik%2Fbmas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farvarik%2Fbmas/lists"}