v0.1.0

Stigmergic v0.1.0 — First Public Release

The first tagged release of Stigmergic — a distributed AI swarm built on the Blackboard Multi-Agent System (bMAS) architecture.

What Is Stigmergic?

Stigmergic coordinates multiple LLM-powered agents through a shared blackboard. An LLM-driven Control Unit reads the board each round, selects which agents to activate, those agents execute concurrently — writing findings, plans, and critiques back to the board — and the cycle repeats until the swarm reaches consensus.

Named after stigmergy, the mechanism by which individual agents coordinate through shared environmental signals rather than direct communication.

Architecture

The system runs as 5 Docker containers on a single control plane, dispatching work to edge agent nodes (Proxmox LXCs) running Hermes agents with optional local inference via llama.cpp.

Service	Port	Role
Daemon	9000	Python FastAPI orchestrator — task lifecycle, cyclic blackboard execution, agent dispatch
Mission Control	9321	Next.js 16 real-time dashboard — execution graphs, distributed logs, HITL controls
Redis	6379	Shared blackboard — Pub/Sub, Streams, Redlock coordination
LiteLLM	4000	Unified model gateway — routes to Gemini, Claude, OpenAI, or local models
Triage	8001	Local Qwen3-1.7B complexity classifier (GPU profile)

Coordination Variants

Variant	Description	Paper
Traditional	Cyclic CU → agent selection → board read/write → convergence loop	Han & Zhang (2025)
PatchBoard	Schema-grounded JSON-Patch mutations against a deterministic kernel	Zhang, Shi & Wang (2026)
Stigmergic	Fully decentralized — agents coordinate through environmental signals only	Experimental

Key Features

Orchestration

• Cyclic blackboard execution with dynamic agent selection per round
• 7 agent roles: Planner, Expert (dynamic), Critic, Conflict Resolver, Cleaner, Decider, Universal
• Multi-provider model routing via LiteLLM (Gemini, Claude, OpenAI, local)
• Intelligent triage — local classifier routes tasks to the cheapest capable model
• Budget ceilings, stall detection, and max-round convergence criteria
• Human-in-the-loop: pause/resume, inject directives, steer agent selection, approve/reject

Observability (Mission Control Dashboard)

• Execution Graph — Swimlane visualization of agent turns grouped by round (React Flow)
• Distributed Log Stream — Unified chronological logs across all agents with structured detail drawers (TanStack Virtual)
• Blackboard Command Center — Timeline, thread, and graph views of board entries with salience heat
• Mission Cockpit — 4-panel live layout: board graph, agent minds, global firehose, convergence strip
• Cost Tracking — Per-model token usage and USD cost with budget gauges
• Agent Trace Inspector — Structured view of every tool call, reasoning step, and output
• Hardware Telemetry — CPU, RAM, disk, temperature for all nodes via Beszel Hub

Operations

• Single bmas.yaml configuration file for the entire deployment
• docker compose up to start the control plane
• Edge node provisioning guide with systemd services
• CI checks: ruff, mypy, pytest (470 tests), eslint, tsc, production build

Tech Stack

Layer	Technology
Orchestrator	Python 3.13 + FastAPI + Uvicorn
Persistence	SQLite (aiosqlite, 12 tables) + Redis 8
Dashboard	Next.js 16 + React 19 + TypeScript 6
Execution Graph	React Flow (@xyflow/react 12.x)
Log Virtualization	TanStack Virtual 3.x
State Management	Zustand 5.x
Styling	Vanilla CSS with design tokens (dark-mode-first)
Agent Runtime	Hermes (Runs API + CLI fallback)
Local Inference	llama.cpp (Vulkan/CUDA)
Triage	vLLM + Qwen3-1.7B

By the Numbers

• ~38,000 lines of code (Python + TypeScript + CSS)
• 268 files tracked
• 470 automated tests (431 daemon + 39 agent)
• 5 Docker services
• 45 React components (11 UI primitives, 22 feature components, 12 board/layout)
• 18 SSE event types for real-time streaming
• 117 triage evaluation cases

Getting Started

git clone https://github.com/arvarik/bmas.git && cd bmas
cp bmas.example.yaml bmas.yaml   # Edit for your setup
cp .env.example .env             # Add API keys
docker compose up -d
open http://localhost:9321

See the Quick Start Guide for the full walkthrough.

Documentation

• Quick Start — Get running in 5 minutes
• Configuration — Full bmas.yaml reference
• Architecture — System architecture deep-dive
• Node Setup — Edge node provisioning
• Design System — Mission Control UI specification

Papers

Han, B. & Zhang, S. (2025). Exploring Advanced LLM Multi-Agent Systems Based on Blackboard Architecture. arXiv:2507.01701

Zhang, S., Shi, W. & Wang, H. (2026). PatchBoard: Schema-Grounded State Mutation for Reliable and Auditable LLM Multi-Agent Collaboration. arXiv:2605.29313