Metadata-Version: 2.4
Name: geepers-framework
Version: 1.0.0
Summary: Multi-agent orchestration system with MCP tools and Claude Code plugin agents
Author-email: Luke Steuber <luke@lukesteuber.com>
License-Expression: MIT
Project-URL: Homepage, https://dr.eamer.dev/geepers/
Project-URL: Repository, https://github.com/lukeslp/geepers
Project-URL: Issues, https://github.com/lukeslp/geepers/issues
Project-URL: Documentation, https://dr.eamer.dev/geepers/
Keywords: mcp,orchestration,multi-agent,llm,claude-code,geepers
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: dr-eamer-ai-shared>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: requests>=2.31.0
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.18.0; extra == "anthropic"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: xai
Requires-Dist: openai>=1.0.0; extra == "xai"
Provides-Extra: mistral
Requires-Dist: requests>=2.31.0; extra == "mistral"
Provides-Extra: cohere
Requires-Dist: cohere>=5.0.0; extra == "cohere"
Provides-Extra: gemini
Requires-Dist: google-generativeai>=0.3.0; extra == "gemini"
Provides-Extra: perplexity
Requires-Dist: openai>=1.0.0; extra == "perplexity"
Provides-Extra: groq
Requires-Dist: groq>=0.4.0; extra == "groq"
Provides-Extra: huggingface
Requires-Dist: huggingface-hub>=0.19.0; extra == "huggingface"
Provides-Extra: arxiv
Requires-Dist: arxiv>=2.0.0; extra == "arxiv"
Provides-Extra: wikipedia
Requires-Dist: wikipedia>=1.4.0; extra == "wikipedia"
Provides-Extra: youtube
Requires-Dist: google-api-python-client>=2.0.0; extra == "youtube"
Provides-Extra: tts
Requires-Dist: gtts>=2.5.0; extra == "tts"
Provides-Extra: citations
Requires-Dist: bibtexparser>=1.4.0; extra == "citations"
Provides-Extra: redis
Requires-Dist: redis>=5.0.0; extra == "redis"
Provides-Extra: documents
Requires-Dist: reportlab>=4.0.0; extra == "documents"
Requires-Dist: python-docx>=1.0.0; extra == "documents"
Requires-Dist: markdown>=3.5.0; extra == "documents"
Provides-Extra: telemetry
Requires-Dist: opentelemetry-api>=1.20.0; extra == "telemetry"
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "telemetry"
Provides-Extra: all
Requires-Dist: anthropic>=0.18.0; extra == "all"
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: cohere>=5.0.0; extra == "all"
Requires-Dist: google-generativeai>=0.3.0; extra == "all"
Requires-Dist: groq>=0.4.0; extra == "all"
Requires-Dist: huggingface-hub>=0.19.0; extra == "all"
Requires-Dist: arxiv>=2.0.0; extra == "all"
Requires-Dist: wikipedia>=1.4.0; extra == "all"
Requires-Dist: google-api-python-client>=2.0.0; extra == "all"
Requires-Dist: gtts>=2.5.0; extra == "all"
Requires-Dist: bibtexparser>=1.4.0; extra == "all"
Requires-Dist: redis>=5.0.0; extra == "all"
Requires-Dist: reportlab>=4.0.0; extra == "all"
Requires-Dist: python-docx>=1.0.0; extra == "all"
Requires-Dist: markdown>=3.5.0; extra == "all"
Requires-Dist: opentelemetry-api>=1.20.0; extra == "all"
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "all"
Dynamic: license-file

# Geepers

Multi-agent orchestration framework and Claude Code plugin. Ships 60+ specialized agents as markdown definitions and a Python package with orchestrator patterns, config management, and MCP server bridges.

## Install

```bash
# Python package
pip install geepers

# With specific LLM providers
pip install "geepers[anthropic]"
pip install "geepers[openai]"
pip install "geepers[all]"      # everything

# As Claude Code plugin (agents only)
/plugin add lukeslp/geepers
```

## Python Package

The `geepers` package provides orchestration infrastructure:

```python
from geepers import ConfigManager
from geepers.orchestrators import (
    DreamCascadeOrchestrator,   # Hierarchical 3-tier research
    DreamSwarmOrchestrator,     # Parallel multi-domain search
    SequentialOrchestrator,
    ConditionalOrchestrator,
    IterativeOrchestrator,
)
```

### Orchestrators

All orchestrators share the same interface:

```python
async def decompose_task(task, context=None) -> List[SubTask]
async def execute_subtask(subtask, context=None) -> AgentResult
async def synthesize_results(results, context=None) -> str
```

The base class handles parallel execution with semaphores, timeouts, retries, and streaming progress events.

**Dream Cascade** - Three-tier hierarchical research. Decomposes tasks into subtasks, fans out to worker agents, synthesizes through a mid-level coordinator, then produces a final executive summary.

**Dream Swarm** - Parallel multi-domain search. Dispatches specialized agents (web search, academic, data analysis) simultaneously and merges results.

### Config Management

```python
from geepers import ConfigManager

config = ConfigManager(app_name="myapp")
# Loads: defaults < config file < .env < env vars < CLI args
api_key = config.get_api_key("anthropic")
```

Auto-discovers keys for 16 LLM providers from environment variables.

### MCP Server Bridges

Entry points for STDIO-based MCP servers:

- `geepers-unified` - All tools in one server
- `geepers-providers` - LLM provider access
- `geepers-data` - Data source clients
- `geepers-cache` - Caching layer
- `geepers-utility` - File and text utilities
- `geepers-websearch` - Web search tools

### Naming Registry

```python
from geepers.naming import get_identifier, resolve_legacy

get_identifier("orchestrator", "cascade")  # Returns scoped identifier
resolve_legacy("BeltalowdaOrchestrator")   # Maps to canonical name
```

## Claude Code Agents

60+ markdown-defined agents organized into 15 domains:

| Domain | Orchestrator | Specialists |
|--------|-------------|-------------|
| **Master** | conductor_geepers | Routes to all domains |
| **Checkpoint** | orchestrator_checkpoint | scout, repo, status, snippets |
| **Deploy** | orchestrator_deploy | caddy, services, validator |
| **Quality** | orchestrator_quality | a11y, perf, deps, critic, security, testing |
| **Frontend** | orchestrator_frontend | css, design, motion, typescript, uxpert, webperf |
| **Fullstack** | orchestrator_fullstack | db, react |
| **Hive** | orchestrator_hive | builder, planner, integrator, quickwin, refactor |
| **Research** | orchestrator_research | data, links, diag, citations, fetcher, searcher |
| **Web** | orchestrator_web | flask, express |
| **Python** | orchestrator_python | pycli |
| **Games** | orchestrator_games | game, gamedev, godot |
| **Corpus** | orchestrator_corpus | corpus, corpus_ux |
| **Datavis** | orchestrator_datavis | viz, color, story, math, data |
| **System** | (standalone) | help, onboard, diag |
| **Standalone** | (standalone) | api, scalpel, janitor, canary, dashboard, git, docs |

Agents follow a strict routing hierarchy: **Conductor -> Orchestrators -> Specialists**.

```
# Usage in Claude Code (via Task tool)
Task with subagent_type="geepers_scout"
Task with subagent_type="geepers_orchestrator_frontend"
Task with subagent_type="conductor_geepers"
```

## Related

- [dr-eamer-ai-shared](https://pypi.org/project/dr-eamer-ai-shared/) - Core shared library (LLM providers, data clients)
- [geepers-orchestrators](https://pypi.org/project/geepers-orchestrators/) - Standalone orchestration patterns
- [MCP-Dreamwalker](https://github.com/lukeslp/mcp-dreamwalker) - MCP server for multi-agent workflows

## License

MIT - Luke Steuber
