Bounded Peer-Review Swarm Orchestration for Instruction Models
A high-performance, zero-dependency framework for orchestrating intelligent agent swarms via structured peer review and strict mathematical budget bounds.
Why Swarmmy? β’ Architecture β’ Installation β’ Supported Providers β’ Tutorials β’ Examples Catalog β’ CLI Tool β’ API Reference β’ Ψ§ΩΨΉΨ±Ψ¨ΩΨ©
In Large Language Models (LLMs), relying on a solitary call often leads to untested assumptions, logic gaps, and hallucinations. Meanwhile, traditional multi-agent frameworks often suffer from infinite execution loops, runaway token bills, and massive dependency bloat (>500 MB).
Swarmmy introduces an entirely different engineering philosophy: deterministic, bounded, and ultra-lightweight.
| Criterion | Single LLM Call | Traditional Agent Frameworks (CrewAI / AutoGen) | Swarmmy π |
|---|---|---|---|
| Perspective & Role Diversity | β Single viewpoint | β Distinct autonomous roles generated automatically | |
| Critical Peer Review | β Self-confirmation bias | β Disciplined cross-review (no self-grading) | |
| Cost & Call Ceiling | 1 call | β Unbounded (prone to infinite loops) | β
Hard mathematical upper bound: N*(2+2R)+1 |
| External Dependencies | Dependent on SDKs | β Heavy packages (>500MB) | β Zero external dependencies (Pure Python stdlib) |
| Rate Limiting & 429 Protection | Manual | β Built-in RPM Throttling + Adaptive 429 Retry | |
| Real-Time Live Formatted Output | Raw text | Cluttered / unstructured console text | β Live colorized terminal dashboard per agent & stage |
The swarm operates across 4 mathematically bounded, rigorous stages:
flowchart TD
Task["π― User Task Prompt"] --> P["Stage 1: Independent Proposals<br/>N diverse agents generate independent candidate solutions"]
P --> R1["Stage 2: Cross Peer Reviews<br/>Each agent scores peer solutions (0.0 to 1.0) with constructive critique (no self-grading)"]
R1 --> V["Stage 3: Revisions & Refinement<br/>Refining proposals based on peer feedback while dismissing unsupported claims"]
V --> Loop{"More review rounds?<br/>(based on rounds)"}
Loop -- "If rounds > 1" --> R1
Loop -- "Rounds completed" --> S["Stage 4: Synthesis & Consensus<br/>Synthesizing best ideas, resolving contradictions with evidence, preserving methodical doubt"]
S --> Res["π Final Result Object<br/>Answer + Ranked Candidates + Reviews + Usage Report"]
- Where
$N$ = Number of peer agents. - And
$R$ = Number of revision and review rounds. -
Example: 4 agents and 1 round =
$4 \times (2 + 2) + 1 = 17$ maximum total calls (strictly enforced hard ceiling).
Requires Python 3.10 or higher:
# 1. Base installation (supports all cloud providers + Ollama with zero external dependencies)
pip install swarmmy
# 2. Optional: Local GPU inference for Hugging Face models (PyTorch)
pip install 'swarmmy[hf]'Swarmmy includes built-in native providers for major LLM services, communicating directly via Python's standard library with zero third-party dependencies required:
| Provider | Identifier in create_provider |
Default Model | API Key Environment Variable |
|---|---|---|---|
| Google Gemini | "gemini" or "google" |
gemini-2.0-flash |
GEMINI_API_KEY or GOOGLE_API_KEY |
| Anthropic Claude | "anthropic" or "claude" |
claude-3-5-sonnet-20241022 |
ANTHROPIC_API_KEY |
| OpenAI | "openai" |
gpt-4o-mini |
OPENAI_API_KEY |
| Groq (Ultra-fast Llama/Mixtral) | "groq" |
llama-3.3-70b-versatile |
GROQ_API_KEY |
| DeepSeek (V3 & R1) | "deepseek" |
deepseek-chat |
DEEPSEEK_API_KEY |
| Ollama (Local & Offline) | "ollama" |
llama3:latest |
Connects to http://localhost:11434 |
| Mistral AI | "mistral" |
mistral-large-latest |
MISTRAL_API_KEY |
| Cohere (Command R+) | "cohere" |
command-r-plus-08-2024 |
COHERE_API_KEY |
| OpenRouter (200+ models) | "openrouter" |
meta-llama/llama-3.3-70b-instruct |
OPENROUTER_API_KEY |
| Azure OpenAI | "azure" |
Deployment-dependent | AZURE_OPENAI_API_KEY |
| Hugging Face (Serverless API) | "hf-api" |
Custom | HF_TOKEN |
| Hugging Face (Local GPU) | "hf" |
Local model path | No key required |
π‘ Looking for provider-specific guides & code? Explore our dedicated Examples Catalog organized by provider: Google Gemini β’ OpenAI β’ Anthropic Claude β’ Groq β’ DeepSeek β’ Ollama Offline β’ Hugging Face Local GPU β’ OpenRouter β’ Mistral β’ Cohere β’ Azure OpenAI β’ Custom Callables & Streaming
Ideal for straightforward scripts, CLI tools, and Jupyter Notebooks:
from swarmmy import run_sync, create_provider, Config
# Create the provider (automatically reads API key from environment variables)
backend = create_provider("gemini")
# Run the swarm in a single synchronous call
result = run_sync(
"Propose an architectural plan for an educational platform handling 1M concurrent users and review vulnerabilities.",
backend=backend,
config=Config(agents=4, rounds=1)
)
print("π Final Synthesized Answer:")
print(result.answer)
print(f"\nTotal API Calls: {result.calls} | Elapsed Time: {result.elapsed_seconds:.2f}s")Ideal for high-concurrency cloud services, web backends, and async pipelines (FastAPI / Starlette):
import asyncio
from swarmmy import Swarm, Config, create_provider
async def main():
backend = create_provider("anthropic", model="claude-3-5-sonnet-20241022")
swarm = Swarm(backend=backend, config=Config(agents=4, rounds=1, concurrency=4))
result = await swarm.run("Design an intelligent load-balancing algorithm and benchmark against alternatives.")
# Inspect individual candidate solutions and their peer scores
for candidate in result.candidates:
print(f"Candidate {candidate.id} - Peer Score: {candidate.peer_score}")
print("\nFinal Answer:\n", result.answer)
if __name__ == "__main__":
asyncio.run(main())Run an entire swarm completely offline on your local machine with zero data sent to external cloud servers:
from swarmmy import run_sync, create_provider, Config
# Ensure Ollama is running: ollama run llama3 or ollama run deepseek-r1:8b
backend = create_provider("ollama", model="llama3:latest")
result = run_sync(
"Explain the differences between Event-Driven Architecture and Monolith with practical examples.",
backend=backend,
config=Config(agents=3, rounds=1)
)
print(result.answer)Observe the thought process, peer grading, and revisions of every agent in real time with distinct colors and formatted boxes:
from swarmmy import run_sync, create_provider, Config
backend = create_provider("groq", model="llama-3.3-70b-versatile")
# Enable live streaming terminal output via live=True
result = run_sync(
"Design a disaster-resilient multi-region cloud infrastructure.",
backend=backend,
config=Config(agents=3, rounds=1),
live=True # π Enables real-time colored live display
)Terminal Output Preview:
========================================================================
>>> STAGE 1: PROPOSALS <<<
Independent solutions generated across diverse roles
========================================================================
ββ AGENT 0 (PROPOSE | 0.35s) [OK] βββββββββββββββββββββββββββββββββββββ
β Proposal 0: Active-active multi-region deployment with Aurora Global.
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
ββ AGENT 1 (PROPOSE | 0.38s) [OK] βββββββββββββββββββββββββββββββββββββ
β Proposal 1: Event-driven replication using Kafka MirrorMaker 2.
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
========================================================================
>>> STAGE 2: PEER REVIEWS <<<
Cross-evaluating peer solutions (no self-grading)
========================================================================
ββ AGENT 0 (REVIEW | 0.25s) [OK] ββββββββββββββββββββββββββββββββββββββ
β π― Review for Agent 1: Score: 0.90 (β
β
β
β
β
)
β "Strong consistency guarantees, but consider cross-region network costs."
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Protect your account from exceeding API limits (e.g. 15 RPM on Gemini free tiers) and control spend with hard cost limits:
from swarmmy import Config, UsageLimits, create_provider, run_sync
# Configure strict usage and budget boundaries
limits = UsageLimits(
rpm=15, # Max 15 requests per minute (automatic client-side rate limiting)
max_total_tokens=40_000, # Hard ceiling on total consumed tokens (prompt + completion)
max_cost_usd=0.05, # Hard budget cap: $0.05 USD (stops immediately if exceeded)
max_retries=3 # Automatic retry with exponential backoff on HTTP 429
)
config = Config(agents=3, rounds=1, limits=limits)
backend = create_provider("gemini")
result = run_sync("Topic for group deliberation", backend=backend, config=config)
# Inspect comprehensive usage metrics
report = result.usage
print(f"π Total Tokens: {report.total_tokens}")
print(f"π₯ Prompt Tokens: {report.prompt_tokens} | π€ Completion Tokens: {report.completion_tokens}")
print(f"π° Estimated Cost: ${report.estimated_cost_usd:.4f} USD")
print(f"β±οΈ Throttling Wait Time: {report.rate_limit_waits_seconds:.2f}s")Guide the swarm's agents toward specialized perspectives:
from swarmmy import Config
# 1. Code Review & Software Architecture Preset
config_code = Config(roles="code")
# 2. Creative Thinking & Ideation Preset
config_creative = Config(roles="creative")
# 3. Fully Custom Domain Roles
security_roles = [
"Focus meticulously on cybersecurity, input validation, and preventing injection vulnerabilities.",
"Focus on code maintainability, Clean Architecture principles, and SOLID design.",
"Focus on memory footprints, execution throughput, and cloud scalability."
]
config_custom = Config(roles=security_roles)Easily integrate custom functions, proprietary SDKs (LiteLLM, Anthropic SDK, Google GenAI SDK), or fine-tuned local models in just a few lines:
from swarmmy import Swarm, Config
def my_custom_llm(messages, temperature=0.7, max_tokens=1024):
user_prompt = messages[0]["content"]
# Call any custom service or local model
return "Custom model response..."
swarm = Swarm(backend=my_custom_llm, config=Config(agents=3, rounds=1))
result = swarm.run_sync("Group discussion task")
print(result.answer)When embedding Swarmmy inside an API service (such as FastAPI, Starlette, Flask, or systems using Server-Sent Events (SSE) or WebSockets), Swarmmy provides real-time streaming tunnels (StreamTunnel, WebhookTunnel, WebSocketTunnel, FunctionTunnel).
This allows you to stream each model step, peer review, critique, and synthesis update directly to the client browser in real time without waiting for the full swarm run to complete:
import asyncio
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from swarmmy import Swarm, StreamTunnel, create_provider, Config
app = FastAPI(title="Swarmmy Streaming API")
@app.get("/stream-swarm")
async def stream_swarm_endpoint(prompt: str):
"""Stream swarm events step-by-step to the client via Server-Sent Events (SSE)."""
tunnel = StreamTunnel()
backend = create_provider("gemini")
swarm = Swarm(backend=backend, config=Config(agents=4, rounds=1))
# Launch swarm execution as background task attached to the tunnel
asyncio.create_task(swarm.run(prompt, tunnel=tunnel))
# Return continuous Server-Sent Events stream to the client
return StreamingResponse(
tunnel.sse_stream(),
media_type="text/event-stream",
headers={"Cache-Control": "no-cache", "Connection": "keep-alive"}
)Real-Time SSE Event Payload Structure:
event: step
data: {
"event_type": "step",
"stage": "propose",
"agent": 0,
"status": "ok",
"data": "First proposal generated by Agent 0...",
"seconds": 0.42,
"timestamp": 1727025000.12,
"metadata": {}
}Other available tunnels:
WebhookTunnel(url="https://...", headers={...}): Posts each step event as an HTTP POST request to your remote backend.WebSocketTunnel(websocket): Sends JSON events directly through an active WebSocket client connection.FunctionTunnel(fn): Executes a custom async or sync callback function for every step event.
Swarmmy includes a full-featured command-line utility swarmmy:
# Use Google Gemini with real-time colored live display
swarmmy "Design a disaster-resilient cloud infrastructure plan" --provider gemini --live
# Use Anthropic Claude with strict RPM rate limiting
swarmmy "Review this codebase and suggest optimizations" --provider anthropic --rpm 20 --live
# Use ultra-fast Groq
swarmmy "Suggest 5 novel startup concepts" --provider groq --live
# Use Ollama locally and offline
swarmmy "What are the best practices for Docker in production?" --provider ollama --model deepseek-r1:8b
# Enforce a strict token and cost budget ceiling
swarmmy "Analyze this architecture document" --provider openai --max-total-tokens 30000 --max-cost 0.10 --provider, --backend LLM provider (gemini, anthropic, openai, groq, deepseek, ollama, mistral, cohere, openrouter, hf, api)
--model Model name (optional; defaults to recommended model for the provider)
--api-key API key (optional; defaults to provider's environment variable)
--base-url Custom base URL endpoint (for local or compatible servers)
--agents Number of peer agents (default: 4)
--rounds Number of review and revision rounds (default: 1)
--concurrency Maximum concurrent API requests (default: 4)
--max-calls Hard ceiling on total model calls (default: 40)
--max-tokens Maximum generated tokens per response (default: 1024)
--peer-chars Character limit per peer candidate in reviews (default: 3000)
--roles Role preset ('default', 'code', 'creative') or custom roles
--rpm Rate limit: maximum requests per minute (throttling)
--max-total-tokens Hard ceiling on total tokens consumed across all calls
--max-cost Hard ceiling on estimated financial cost in USD
--max-retries Maximum retries when encountering HTTP 429 Too Many Requests (default: 3)
-l, --live Display real-time rich colored output from each agent, round, and stage
-v, --verbose Display detailed execution logs
--output Path to save results JSON (default: swarmmy-result.json)
Config(
agents: int = 4, # Number of agents (>= 2)
rounds: int = 1, # Review and revision rounds (>= 0)
concurrency: int = 4, # Maximum concurrent requests
max_calls: int = 40, # Hard ceiling on total model calls
max_tokens: int = 1024, # Max tokens per generation
peer_chars: int = 3000, # Character limit per peer candidate in review prompt
roles: str | Sequence[str] = None, # Preset name ("code", "creative") or list of custom roles
limits: UsageLimits = None, # UsageLimits instance for budgets and rate limiting
rpm: int = None, # Shorthand to set requests per minute
max_total_tokens: int = None, # Shorthand for cumulative token ceiling
max_cost_usd: float = None, # Shorthand for financial cost cap in USD
max_retries: int = 3 # Automatic retries on HTTP 429
)result.answer # Final synthesized consensus answer (str)
result.candidates # List of generated candidate solutions (list[Candidate])
result.reviews # List of cross-peer reviews and scores (list[Review])
result.trace # Step-by-step execution event trace (list[TraceEvent])
result.calls # Total count of model API calls made (int)
result.elapsed_seconds # Total wall-clock execution time in seconds (float)
result.warnings # List of handled warnings or fallback notices (list[str])
result.usage # Detailed usage metrics and cost report (UsageReport)
result.to_dict() # Serialize result to a standard Python dictionary
result.to_json(indent=2) # Serialize result to a formatted JSON stringUsageLimits(
rpm: int = None, # Requests-per-minute rate limit throttling
max_total_tokens: int = None, # Hard cap on accumulated tokens across all calls
max_cost_usd: float = None, # Hard financial spend cap in USD
max_retries: int = 3, # Max retry attempts on HTTP 429 rate limits
retry_backoff_factor: float = 2.0, # Exponential multiplier for backoff
min_retry_wait: float = 1.0, # Initial backoff delay in seconds
max_retry_wait: float = 60.0 # Maximum backoff delay cap in seconds
)
# Access metrics from result.usage:
report.prompt_tokens # Input tokens consumed
report.completion_tokens # Output tokens generated
report.total_tokens # Total cumulative tokens
report.estimated_cost_usd # Calculated financial cost in USD
report.rate_limit_waits_seconds # Total time spent waiting for RPM throttling
report.retries_attempted # Total 429 retry attempts performedtunnel = StreamTunnel()
# Attach to Swarm execution:
swarm = Swarm(backend=backend, config=config, tunnel=tunnel)
# Consume in FastAPI or async web frameworks:
async for sse_chunk in tunnel.sse_stream():
# Returns formatted Server-Sent Event strings:
# "event: step\ndata: {...}\n\n"
pass
# Or iterate over raw StepEvent objects:
async for event in tunnel:
print(event.event_type, event.stage, event.agent, event.data, event.seconds)create_provider(
provider: str, # Provider name: 'gemini', 'anthropic', 'openai', 'groq', 'deepseek', 'ollama', etc.
model: str = None, # Model identifier (defaults to recommended model)
api_key: str = "", # Optional API key (reads from env vars automatically)
base_url: str = "", # Optional custom endpoint URL
)All library features and edge cases are thoroughly verified by 42 unit and integration tests with 100% pass rate:
python -m unittest discover -s tests -vContributions, feedback, and suggestions are warmly welcomed!
- Open an Issue to discuss new features, bug reports, or architecture ideas.
- Submit a Pull Request after ensuring all tests pass:
python -m unittest discover -s tests.
Distributed under the MIT License. Open-source and free for commercial and academic use.
Copyright Β© 2026 Swarmmy Team.
