Metadata-Version: 2.4
Name: techtide-swarm
Version: 0.2.2
Summary: TechTide Swarm 357 — layered orchestration, durable memory bridge, and observability hooks.
Project-URL: Homepage, https://github.com/TechTideOhio/swarm-357
Project-URL: Repository, https://github.com/TechTideOhio/swarm-357
Project-URL: Documentation, https://github.com/TechTideOhio/swarm-357/blob/main/docs/EVALS.md
Project-URL: Changelog, https://github.com/TechTideOhio/swarm-357/blob/main/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/TechTideOhio/swarm-357/issues
Author-email: TechTide AI <ai@techtide.ai>
License: Apache-2.0
License-File: LICENSE
Keywords: agents,ai,ai-agents,anthropic,claude,llm,multi-agent,orchestration,swarm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.40
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.5
Requires-Dist: pyyaml>=6
Requires-Dist: rich>=13
Requires-Dist: uvicorn[standard]>=0.30
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Provides-Extra: supabase
Requires-Dist: supabase>=2.0; extra == 'supabase'
Provides-Extra: web
Requires-Dist: exa-py>=1.0; extra == 'web'
Requires-Dist: firecrawl-py>=0.0.20; extra == 'web'
Description-Content-Type: text/markdown

# techtide-swarm

[![PyPI](https://img.shields.io/pypi/v/techtide-swarm.svg)](https://pypi.org/project/techtide-swarm/)
[![Python](https://img.shields.io/pypi/pyversions/techtide-swarm.svg)](https://pypi.org/project/techtide-swarm/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/TechTideOhio/swarm-357/blob/main/LICENSE)
[![CI](https://github.com/TechTideOhio/swarm-357/actions/workflows/ci.yml/badge.svg)](https://github.com/TechTideOhio/swarm-357/actions/workflows/ci.yml)

Python package for **Swarm 357**: layered orchestration of 357 Claude agent roles across six business layers, portable Memvid memory, cost controls, and a FastAPI HTTP surface.

## Install

```bash
pip install techtide-swarm
swarm demo
```

Editable (from repo root):

```bash
pip install -e "packages/techtide-swarm[dev]"
```

The wheel bundles `config/swarm-compact.yaml` and `templates/soul/` so `swarm boot` works after a plain `pip install`.

## Quickstart

```bash
export ANTHROPIC_API_KEY=sk-ant-...   # or OPENROUTER_API_KEY + ANTHROPIC_BASE_URL
swarm init
swarm boot                            # loads 357-agent compact roster
swarm run "Draft a Tier-1 401 triage checklist" --budget 1.0
swarm serve --port 8000
```

OpenRouter (recommended for evals/cost control):

```bash
export OPENROUTER_API_KEY=...
export ANTHROPIC_BASE_URL=https://openrouter.ai/api
export SWARM_MODEL_SONNET=anthropic/claude-sonnet-4
```

## Public API

```python
from techtide_swarm import (
    Agent, AgentConfig, Swarm, UltraPlan, UltraPlanConfig,
    MemoryManager, CostController, BashSecurityGate, __version__,
)
from techtide_swarm.core.types import LayerType

agent = Agent(AgentConfig(
    name="research-market-001",
    layer=LayerType.RESEARCH,
    role="market_researcher",
    soul="templates/soul/research/market-analyst.md",
    tools=["Read", "Write"],
    model="sonnet",
    budget_limit_usd=1.0,
))
```

Also exported: `AgentResult`, `SwarmExecutionResult`, `SwarmStore`, `MemvidBridge`, `ToolRegistry`, `TOOLSET_MAP`, `registry`.

## CLI

| Command | Purpose |
|---------|---------|
| `swarm init` | Create `.swarm/`, `.env`, memory index |
| `swarm demo` | Stub or live 3-agent demo |
| `swarm boot` | Load roster + print layer budgets |
| `swarm run <task>` | Full swarm or `--layer` execution |
| `swarm agent` | List / inspect / run one agent |
| `swarm status` / `swarm cost` | Telemetry dashboards |
| `swarm dream` | Memory consolidation cycle |
| `swarm plan <task>` | UltraPlan (Opus by default) |
| `swarm migrate` | Flat topics → Memvid `.mv2` |
| `swarm eval` | Budgeted eval harness |
| `swarm serve` | FastAPI via uvicorn |
| `swarm mcp list\|connect` | MCP server tools |

## HTTP API

`uvicorn techtide_swarm.server:app` (or `swarm serve`):

| Method | Path | Notes |
|--------|------|-------|
| GET | `/api/health` | version, agent count, API key presence |
| GET | `/api/swarm/status` | layer stats + cost |
| GET | `/api/swarm/agents` | roster summary |
| GET | `/api/swarm/agents/{name}` | agent detail |
| GET | `/api/swarm/cost` | spend report |
| GET | `/api/swarm/runs` | recent runs |
| POST | `/api/swarm/run` | swarm/layer run (`X-SWARM-API-KEY` when set) |
| POST | `/api/agent/run` | single agent |
| POST | `/api/swarm/dream` | dream cycle |

## Environment

| Variable | Purpose |
|----------|---------|
| `ANTHROPIC_API_KEY` / `OPENROUTER_API_KEY` | LLM credentials |
| `ANTHROPIC_BASE_URL` | e.g. `https://openrouter.ai/api` |
| `SWARM_MODEL_{OPUS,SONNET,HAIKU}` | Model ID overrides |
| `SWARM_API_KEY` | Protect POST routes |
| `SWARM_MAX_RUN_BUDGET_USD` | Cap request `budget_usd` |
| `SWARM_RATE_LIMIT_PER_MINUTE` | Per-IP rate limit (`0` disables) |
| `SWARM_CONFIG_PATH` | Roster YAML override |
| `MEMVID_SWARM_BRIDGE` | Path to Rust bridge binary |
| `SWARM_WRITE_SAFE_ROOT` | Sandbox for Write tool |

## Docs

- Full project: [TechTideOhio/swarm-357](https://github.com/TechTideOhio/swarm-357)
- Evals: [docs/EVALS.md](https://github.com/TechTideOhio/swarm-357/blob/main/docs/EVALS.md)
- Architecture notes: [CLAUDE.md](https://github.com/TechTideOhio/swarm-357/blob/main/CLAUDE.md)

## License

Apache-2.0
