Metadata-Version: 2.4
Name: swarma
Version: 0.2.0
Summary: Learning agent swarms that get smarter every cycle
Author-email: Rabin <rabin@theglitch.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,llm,orchestration,swarm
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: apscheduler>=3.10
Requires-Dist: fastapi>=0.110
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn>=0.29
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# swarma

the growth experiment loop for AI agent swarms.

**[swarma.dev](https://swarma.dev)**

[English](README.md) | [中文](README.zh.md) | [日本語](README.ja.md)

---

![Version](https://img.shields.io/badge/version-0.2.0-blue)
![Python](https://img.shields.io/badge/python-3.11+-green)
![License](https://img.shields.io/badge/license-MIT-yellow)

your agents run tasks. swarma makes them run A/B tests instead.

describe what you want to improve. swarma generates the team, seeds it with real growth knowledge, runs experiments, scores results, issues verdicts, and evolves the strategy. after enough cycles, you have a validated playbook of what actually works.

```
strategy.md → execute → measure → verdict → updated strategy.md
     ↑                                              |
     └──────────────────────────────────────────────┘
```

applied learnings from [QMD](https://github.com/glitch-rabin/qmd) and the [karpathy autoresearch pattern](https://github.com/karpathy/autoresearch) -- the same experiment loop that growth teams run, now applied to AI agent swarms.

## why this exists

every growth team at Uber, Spotify, Facebook, Airbnb runs the same loop: hypothesize, test, measure, learn, repeat. the ones that win aren't smarter -- they just run more experiments and actually listen to the data. the playbook that emerges after thousands of cycles is the real asset.

the bottleneck was always human bandwidth. even the best teams max out at 2-5 experiments per week. AI agents remove that constraint. a swarm can run 50 experiments while a human team runs 2. but only if something is closing the loop.

that's what swarma does. the experiment infrastructure that growth teams at scale take for granted, packaged so any agent swarm can use it. same loop, same rigor, same compounding.

## quickstart

```bash
pip install swarma
```

or from source:

```bash
git clone https://github.com/glitch-rabin/swarma.git
cd swarma && pip install -e .
```

```bash
swarma init                    # creates instance + starter team
swarma cycle starter           # run one cycle, see it work
swarma status                  # costs, runs, experiments
```

python 3.11+ and an [openrouter](https://openrouter.ai/) API key. no GPU, no postgres, no docker. runs on a laptop or a $5 VPS.

## generate a team from a goal

don't configure agents by hand. describe what you want and swarma builds the team.

```bash
swarma team create my-growth --from-goal "improve landing page conversion rate"
```

this calls an LLM to design a team with the right agents, flow, models, and a first experiment hypothesis. the generated team comes with:

- `team.yaml` -- goal, flow, budget
- `agents/*.yaml` -- individual agent configs with specific instructions
- `program.md` -- experiment patterns and constraints
- a first experiment ready to run

add business context for better results:

```bash
swarma team create growth-lab \
  --from-goal "optimize our signup funnel" \
  --context "B2B SaaS, 500 free users, 2% conversion to paid" \
  --budget 50
```

## how the loop works

1. agent reads its `strategy.md` before every run
2. produces output (research, copy, analysis -- whatever the team does)
3. a cheap LLM scores the output against the agent's metric (1-10 scale, forced decimals)
4. score + reasoning logged to `results.tsv`
5. after `min_sample_size` cycles (default 3-5), verdict is issued automatically
6. `strategy.md` updated with what was learned
7. next cycle uses the evolved strategy

**scoring**: each output gets evaluated by a separate LLM call using the cheapest model in your routing table. the evaluator sees the output, the current strategy, the last 5 scores, and the metric definition. returns a precise score (7.3, not 7) plus reasoning and a strategy suggestion.

**verdicts**: after enough samples, swarma compares the experiment average against baseline. >20% improvement = **keep** (pattern validated, strategy updated). >20% decline = **discard** (reverted). in between = **inconclusive** (logged, try again with more data).

after a few experiments, your `strategy.md` evolves from seed knowledge into validated patterns:

```markdown
## Validated (Exp 5)
contrarian opening + specific numbers in first line
> 23% improvement over baseline. keep this pattern.

## Inconclusive (Exp 2)
story-led hooks vs data-led hooks -- no significant difference (avg=8.1 vs baseline=7.9)
> next: increase sample size, results may be noise
```

## feed real metrics back

LLM self-eval is a starting proxy. for production, feed back real-world signals:

```bash
# log a single metric
swarma metric log hook-lab copywriter 4.2 --metric ctr_pct

# attach to a specific experiment
swarma metric log hook-lab copywriter 127 --metric impressions --exp 3

# bulk import from CSV
swarma metric import hook-lab metrics.csv

# view logged metrics
swarma metric show hook-lab
```

CSV format: `agent,value,metric_name,note`

metrics auto-attach to the agent's active experiment. the experiment loop uses external metrics alongside LLM scores when both are available.

## pre-seeded strategies

agents don't start from zero. each example squad includes a `strategy.md` seeded with real growth knowledge -- validated patterns, anti-patterns, and hypotheses to test. the experiment loop refines these over time.

example from the hook-lab strategy:

```markdown
### Validated Patterns

**Specificity wins**
- Hooks with specific numbers outperform vague claims by 2-3x on saves
- "47% of startups" > "most startups"

**Loss framing > gain framing**
- "You're losing $X/month" outperforms "You could save $X/month" on CTR
- Exception: aspirational audiences respond better to gain framing

### Patterns to Test
- [ ] First-person confession vs third-person case study
- [ ] Time-anchored ("In 2024...") vs timeless hooks
```

## teams as config

a team is a folder. no code required.

```
teams/my-squad/
├── team.yaml          # goal, flow, schedule, budget
├── program.md         # team context and constraints
└── agents/
    ├── researcher.yaml
    ├── writer.yaml
    └── strategy.md    # pre-seeded growth knowledge
```

```yaml
# team.yaml
name: my-squad
goal: find what works.
flow: "researcher -> writer"
schedule: "0 8 * * 1-5"
```

```yaml
# agents/writer.yaml
id: writer
name: Writer
instructions: |
  turn research into a post. max 200 words.
  hook in the first line. practitioner voice.
metric:
  name: content_quality
  target: 8.0
experiment_config:
  min_sample_size: 5
  auto_propose: true
```

models, tools, and expert lenses are configured in `config.yaml`. agents inherit defaults or override per-agent.

flow DSL supports sequential (`a -> b`), parallel (`a -> [b, c, d]`), and mixed pipelines.

## 18 example squads

ready-to-use squads in [`examples/`](examples/), each with pre-seeded strategies:

```bash
cp -r examples/hook-lab ~/.swarma/instances/default/teams/
swarma cycle hook-lab
```

**core growth squads:**

| squad | AARRR stage | what it tests |
|-------|------------|--------------|
| `hook-lab` | acquisition | opening lines -- what stops the scroll |
| `landing-lab` | acquisition | landing page copy and structure |
| `seo-engine` | acquisition | search presence and content ranking |
| `cold-outbound` | acquisition | outreach messaging and sequences |
| `channel-mix` | acquisition | multi-platform content strategy |
| `activation-flow` | activation | signup-to-value onboarding flows |
| `pricing-lab` | revenue | pricing presentation and packaging |
| `retention-squad` | retention | churn signals and win-back patterns |
| `referral-engine` | referral | viral loops and invite mechanics |
| `competitive-intel` | -- | market monitoring and positioning |

**2026 growth ops squads:**

| squad | what it tests |
|-------|--------------|
| `ad-creative-lab` | AI-generated ad creatives, multi-variant testing (50+ per campaign) |
| `faceless-factory` | faceless TikTok/Shorts at scale, retention curve optimization |
| `ugc-factory` | AI UGC-style content ($2-20/video vs $150-2K human) |
| `programmatic-seo` | template + data variable SEO pages at scale |
| `newsletter-engine` | newsletter growth, referral programs, ad placement |
| `acquisition-squad` | AI-powered outbound, intent signals, multi-channel sequences |
| `community-engine` | community-led growth, XP/quest gamification, ambassador programs |
| `agentic-storefront` | AI commerce optimization, dynamic pricing, conversational checkout |

each includes a `program.md` with experiment patterns and a `strategy.md` with real growth knowledge as starting baseline.

## integrations

### hermes agent

swarma exposes an MCP server. connect it to [hermes](https://github.com/nousresearch/hermes-agent) and your agent gets a dedicated experiment team that learns while it sleeps.

```yaml
# hermes config.yaml
mcp_servers:
  swarma:
    transport: stdio
    command: swarma
    args: ["serve", "--mcp"]
```

hermes stays clean -- sets direction, approves plans, asks "what did we learn?" swarma does the messy work.

### claude code / claude desktop

```json
{
  "mcpServers": {
    "swarma": {
      "command": "swarma",
      "args": ["serve", "--mcp"]
    }
  }
}
```

### REST API

```bash
swarma serve --port 8282        # 30+ endpoints, OpenAPI docs at /docs
```

### any MCP client

```bash
swarma serve --mcp              # stdio
swarma serve --mcp --mcp-port 8383   # HTTP
```

**note**: when running as MCP subprocess, pass `OPENROUTER_API_KEY` in your MCP config's `env` block -- the instance `.env` is not inherited by subprocesses.

## knowledge layer (QMD)

agents learn individually via strategy.md. to learn *across* teams, add [QMD](https://github.com/glitch-rabin/qmd) -- a search engine that indexes all agent outputs. BM25 + vector + rerank. no GPU required.

```bash
pip install qmd
qmd init
qmd serve                          # http://localhost:8181
```

```yaml
# config.yaml
knowledge:
  engine: qmd
  qmd_endpoint: http://localhost:8181/mcp
```

every agent output gets indexed automatically. agents search what other agents learned. the experiment loop gets shared memory.

when an experiment gets a **keep** verdict, the validated pattern is automatically saved to a cross-team `playbook` collection. every agent sees patterns from every other team in their context window. anti-patterns (discarded experiments) are tracked too, so teams avoid repeating failed approaches.

```bash
# semantic search across all validated patterns
curl localhost:8282/playbook/search?q=hook+specificity
```

## what swarma is not

- **not memory** -- [honcho](https://github.com/plastic-labs/honcho) does memory. swarma does learning loops.
- **not automation** -- n8n/make do workflows. swarma runs experiments.
- **not a prompt library** -- [agency-agents](https://github.com/msitarzewski/agency-agents) has 135 templates. swarma teaches them what works through feedback loops.
- **not orchestration** -- crewai/autogen run pipelines. swarma adds the feedback loop that makes pipelines improve.

the difference: a prompt template tells an agent what to do once. swarma teaches it what works over time. templates are the starting point. the playbook is the output.

## roadmap

- [x] experiment loop (strategy -> execute -> measure -> verdict)
- [x] expert reasoning lenses (34 composable thinking frameworks)
- [x] dashboard UI (experiment viewer, playbook, strategy evolution)
- [x] team generator (`swarma team create --from-goal`)
- [x] external metric ingestion (`swarma metric log/import/show`)
- [x] pre-seeded strategy files with real growth knowledge
- [x] `pip install swarma` on PyPI
- [x] QMD cross-team wiring (verdict -> playbook -> shared knowledge)
- [x] 18 example squads covering full AARRR funnel + 2026 growth ops
- [x] anti-pattern tracking (discard verdicts saved to playbook)
- [x] `/playbook/search` semantic search across teams via QMD
- [ ] webhook metric ingestion (real-time analytics callbacks)
- [ ] hermes skills hub + openclaw marketplace publishing
- [ ] squad marketplace (share and discover validated teams)
- [ ] HuggingFace dataset seeding for squad knowledge

## contributing

swarma is early. if you're interested in experiment loops for agents, open an issue or PR.

## license

MIT
