Package Structure

Layered subpackages — each layer depends only on layers below it

swarm/ — directory layout
swarm/
├── __init__.py              # public API re-exports
├── py.typed                 # PEP 561 marker

├── core/                    # ── Layer 0: protocols + data types
│   ├── __init__.py
│   ├── protocols.py         # LLMProvider, Agent, Pattern, Tool protocols
│   ├── types.py             # AgentResult, SwarmResult, SwarmContext, Message
│   └── errors.py            # SwarmError, ProviderError, PatternError

├── providers/               # ── Layer 1: LLM backends
│   ├── __init__.py
│   ├── base.py              # BaseProvider (implements LLMProvider protocol)
│   ├── claude.py            # ClaudeProvider (auth token OR api key)
│   ├── ollama.py            # OllamaProvider (Gemma4, Qwen-2.5b, etc.)
│   └── litellm.py           # LiteLLMProvider (any litellm-supported model)

├── agents/                  # ── Layer 2: agent implementations
│   ├── __init__.py
│   ├── base.py              # BaseAgent (implements Agent protocol)
│   ├── llm_agent.py         # LLMAgent — config-driven declarative agent
│   └── context.py           # SwarmContext implementation

├── patterns/                # ── Layer 3: swarm pattern implementations
│   ├── __init__.py
│   ├── base.py              # BasePattern (implements Pattern protocol)
│   ├── decentralized.py     # peer voting, no hierarchy
│   ├── hierarchical.py      # coordinator → workers
│   ├── parallel.py          # concurrent fan-out + merge
│   ├── sequential.py        # strict ordered pipeline
│   ├── adaptive.py          # dynamic routing based on confidence
│   └── mesh.py              # P2P agent communication graph

├── builder/                 # ── Layer 4: swarm composition
│   ├── __init__.py
│   ├── swarm.py             # Swarm builder class (fluent API)
│   ├── dag.py               # DAG engine (nodes + edges)
│   └── config.py            # serialize/deserialize to/from dict/YAML

└── cli/                     # ── Layer 5: CLI interface
    ├── __init__.py
    └── main.py              # click/typer CLI commands

Layer dependency rules

  cli  →  builder  →  patterns  →  agents  →  providers  →  core
                                                               ↑
                                                        (no external deps)

Each layer imports only from layers to its right. core has zero deps. providers imports only core. Tests mock at protocol boundaries.

Public API surface (swarm/__init__.py)

from swarm import (
    Swarm,           # builder
    Agent,           # base agent class
    LLMAgent,        # config-driven agent
    ClaudeProvider,  # auth token or API key
    OllamaProvider,  # open-source LLMs
    LiteLLMProvider, # any model via litellm
    AgentResult,     # typed message
    SwarmContext,    # shared state store
)