@intentsolutionsio/geepers-agents 1.0.0

package/README.md

@@ -0,0 +1,378 @@
+# Geepers
+
+Multi-agent orchestration system with MCP tools and Claude Code plugin agents.
+
+## Installation
+
+### From PyPI (MCP tools)
+```bash
+pip install geepers
+
+# With optional dependencies
+pip install geepers[all]
+pip install geepers[anthropic,openai]
+```
+
+### As Claude Code Plugin (agents)
+```bash
+/plugin add lukeslp/geepers
+```
+
+## What's Included
+
+### 43 Specialized Agents
+
+Markdown-defined agents for Claude Code that provide specialized workflows:
+
+| Category | Agents | Purpose |
+|----------|--------|---------|
+| **Master** | conductor_geepers | Intelligent routing to specialists |
+| **Checkpoint** | scout, repo, status, snippets, orchestrator | Session maintenance |
+| **Deploy** | caddy, services, validator, orchestrator | Infrastructure |
+| **Quality** | a11y, perf, api, deps, critic, orchestrator | Code audits |
+| **Fullstack** | db, design, react, orchestrator | End-to-end features |
+| **Research** | data, links, diag, citations, orchestrator | Data gathering |
+| **Games** | game, gamedev, godot, orchestrator | Game development |
+| **Corpus** | corpus, corpus_ux, orchestrator | Linguistics/NLP |
+| **Web** | flask, orchestrator | Web applications |
+| **Python** | pycli, orchestrator | Python projects |
+
+### 90+ MCP Tools
+
+Six specialized MCP servers expose tools for:
+
+- **geepers-unified** - All tools in one server
+- **geepers-providers** - 13 LLM providers (Anthropic, OpenAI, xAI, etc.)
+- **geepers-data** - 29+ data sources (Census, arXiv, GitHub, NASA, etc.)
+- **geepers-cache** - Redis-backed caching
+- **geepers-utility** - Document parsing, citations, TTS
+- **geepers-websearch** - Multi-engine web search
+
+## FREE Alternative: Use Ollama for Local LLM
+
+**Want to run geepers without paying for LLM APIs?** Replace Anthropic/OpenAI/xAI with Ollama for $0/month.
+
+### Quick Comparison
+
+| Component | Paid (Cloud APIs) | FREE (Ollama) |
+|-----------|-------------------|---------------|
+| **LLM Provider** | Anthropic/OpenAI/xAI | Ollama (local) |
+| **Monthly Cost** | $50-200/mo | **$0/mo** |
+| **Privacy** | Data sent to cloud | 100% local |
+| **API Keys** | Required (3+ keys) | None required |
+| **Rate Limits** | Yes (varies by tier) | Unlimited |
+| **Latency** | 2-5s (network) | 1-3s (local) |
+
+**Savings: $600-2,400/year** for multi-agent orchestration.
+
+### Why Ollama for Geepers?
+
+**Benefits:**
+- **Zero Cost:** No API usage fees for 43 agents
+- **Privacy:** All 90+ MCP tools run locally
+- **Unlimited:** Run as many agent calls as needed
+- **Offline:** No internet required after model download
+- **GDPR/HIPAA:** Compliant by default (local-only)
+
+**Recommended Models:**
+- **llama3.2:7b** - Best for general agents (4GB)
+- **mistral:7b** - Fast and efficient (4GB)
+- **codellama:13b** - Code-focused agents (7GB)
+- **mixtral:8x7b** - Advanced reasoning (26GB)
+
+### Setup Guide
+
+#### 1. Install Ollama
+
+```bash
+# macOS
+brew install ollama
+brew services start ollama
+
+# Linux
+curl -fsSL https://ollama.com/install.sh | sh
+sudo systemctl start ollama
+
+# Pull model (4GB download)
+ollama pull llama3.2
+```
+
+See [ollama-local-ai](../../ai-ml/ollama-local-ai/) plugin for detailed setup.
+
+#### 2. Install Geepers with Local LLM Support
+
+```bash
+# Install without paid provider dependencies
+pip install geepers
+
+# No need for [anthropic,openai] extras!
+```
+
+#### 3. Configure Ollama as LLM Provider
+
+Create `~/.geepers/config.yaml`:
+
+```yaml
+llm:
+  provider: ollama
+  base_url: http://localhost:11434
+  model: llama3.2
+  temperature: 0.7
+
+# No API keys required!
+```
+
+#### 4. Update MCP Config
+
+```json
+{
+  "mcpServers": {
+    "geepers": {
+      "command": "geepers-unified",
+      "env": {
+        "GEEPERS_LLM_PROVIDER": "ollama",
+        "OLLAMA_BASE_URL": "http://localhost:11434",
+        "OLLAMA_MODEL": "llama3.2"
+      }
+    }
+  }
+}
+```
+
+### Cost Comparison: 43 Agents
+
+#### Cloud APIs (Anthropic/OpenAI)
+
+```
+43 agents × 1000 calls/month × $0.002/call = $86/month
+Annual cost: $1,032
+```
+
+**Required API Keys:**
+- Anthropic Claude API: $50-100/mo
+- OpenAI GPT-4: $30-80/mo
+- xAI Grok: $20-50/mo
+- **Total: $100-230/mo**
+
+#### Ollama (Local LLM)
+
+```
+43 agents × unlimited calls/month × $0 = $0/month
+Annual cost: $0
+```
+
+**Required:**
+- Hardware you already own
+- One-time model download (4-26GB)
+- **Total: $0/mo**
+
+**Savings: $1,200-2,760/year**
+
+### Migration Examples
+
+#### Before (Paid APIs)
+
+```bash
+# Install with paid dependencies
+pip install geepers[anthropic,openai]
+
+# Set API keys
+export ANTHROPIC_API_KEY=sk-ant-...
+export OPENAI_API_KEY=sk-...
+export XAI_API_KEY=xai-...
+```
+
+**Monthly Cost:** $100-230
+
+#### After (Ollama)
+
+```bash
+# Install without paid dependencies
+pip install geepers
+
+# Start Ollama (one-time setup)
+ollama pull llama3.2
+ollama serve
+
+# Configure geepers
+export GEEPERS_LLM_PROVIDER=ollama
+export OLLAMA_BASE_URL=http://localhost:11434
+```
+
+**Monthly Cost:** $0
+
+### Real Use Case: Multi-Agent Session
+
+**Scenario:** Running geepers_orchestrator_checkpoint (5 agent calls per session)
+
+#### Cloud APIs Version
+```python
+# Using Anthropic Claude
+import anthropic
+
+client = anthropic.Anthropic(api_key="sk-ant-...")
+response = client.messages.create(
+    model="claude-3-5-sonnet-20241022",
+    messages=[{"role": "user", "content": "Scout the repo"}]
+)
+```
+
+**Cost per session:** 5 calls × $0.002 = **$0.01**
+**Monthly (100 sessions):** **$1.00**
+**Annual:** **$12.00**
+
+#### Ollama Version
+```python
+# Using local Ollama
+import ollama
+
+response = ollama.chat(
+    model='llama3.2',
+    messages=[{"role": "user", "content": "Scout the repo"}]
+)
+```
+
+**Cost per session:** 5 calls × $0 = **$0.00**
+**Monthly (100 sessions):** **$0.00**
+**Annual:** **$0.00**
+
+**Same intelligence, zero cost.**
+
+### Performance Comparison
+
+| Metric | Cloud APIs | Ollama (Local) |
+|--------|-----------|----------------|
+| **Response Time** | 2-5s | 1-3s (with GPU) |
+| **Throughput** | Rate limited | Unlimited |
+| **Privacy** | Cloud processed | 100% local |
+| **Offline** | ❌ Requires internet | ✅ Works offline |
+| **Cost (1M tokens)** | $10-30 | $0 |
+
+### Agent-Specific Recommendations
+
+**Fast Agents (scout, status, snippets):**
+```bash
+ollama pull llama3.2:7b  # Fast, 4GB
+```
+
+**Code Agents (pycli, react, db, flask):**
+```bash
+ollama pull codellama:13b  # Code-optimized, 7GB
+```
+
+**Research Agents (data, citations, corpus):**
+```bash
+ollama pull mixtral:8x7b  # Advanced reasoning, 26GB
+```
+
+**Game Dev Agents (game, godot, gamedev):**
+```bash
+ollama pull llama3.2:7b  # Balanced, 4GB
+```
+
+### When to Use Cloud vs Local
+
+**Use Cloud APIs (Anthropic/OpenAI) if:**
+- You need latest GPT-4 Turbo or Claude Opus specifically
+- Your hardware has <8GB RAM
+- You need real-time web search results
+- Budget allows $100-230/month
+
+**Use Ollama (Local LLM) if:**
+- You want $1,200-2,760/year savings
+- You need privacy/compliance (HIPAA, GDPR, SOC2)
+- You have 8GB+ RAM (16GB+ recommended)
+- You want unlimited agent calls
+- You need offline capability
+
+### Hybrid Approach
+
+**Best of both worlds:** Use Ollama for 90% of calls, cloud APIs for specialized tasks.
+
+```yaml
+# ~/.geepers/config.yaml
+llm:
+  default_provider: ollama  # $0/mo for most calls
+  fallback_provider: anthropic  # Only when needed
+
+providers:
+  ollama:
+    base_url: http://localhost:11434
+    model: llama3.2
+  anthropic:
+    api_key: ${ANTHROPIC_API_KEY}
+    model: claude-3-5-sonnet-20241022
+```
+
+**Cost Reduction:** ~90% savings ($10-23/mo instead of $100-230/mo)
+
+### Resources
+
+- **Ollama Setup:** Use `/setup-ollama` command from [ollama-local-ai](../../ai-ml/ollama-local-ai/) plugin
+- **Ollama Docs:** [ollama.com/docs](https://ollama.com/docs)
+- **Geepers Docs:** [github.com/lukeslp/geepers](https://github.com/lukeslp/geepers)
+- **Model Library:** [ollama.com/library](https://ollama.com/library)
+
+**Bottom Line:** For 43 specialized agents running locally, Ollama saves $1,200-2,760/year with comparable performance.
+
+---
+
+## Configuration
+
+### Claude Code MCP Config
+
+Add to `~/.config/claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "geepers": {
+      "command": "geepers-unified"
+    }
+  }
+}
+```
+
+### Environment Variables
+
+```bash
+# LLM Providers
+ANTHROPIC_API_KEY=...
+OPENAI_API_KEY=...
+XAI_API_KEY=...
+
+# Data Sources
+GITHUB_TOKEN=...
+NASA_API_KEY=...
+CENSUS_API_KEY=...
+```
+
+## Usage
+
+### Using Agents in Claude Code
+
+```
+@geepers_scout          # Quick project reconnaissance
+@geepers_caddy          # Caddy configuration changes
+@geepers_orchestrator_checkpoint  # End-of-session cleanup
+```
+
+### Using MCP Tools
+
+Once configured, tools are available via the MCP protocol.
+
+## Development
+
+```bash
+# Clone and install in dev mode
+git clone https://github.com/lukeslp/geepers
+cd geepers
+pip install -e .
+
+# Run tests
+pytest
+```
+
+## License
+
+MIT License - Luke Steuber

package/agents/conductor_geepers.md

@@ -0,0 +1,283 @@
+---
+name: conductor-geepers
+description: "Master orchestrator for coordinating geepers_* agents. Use this when you ne..."
+model: sonnet
+---
+
+## Examples
+
+### Example 1
+
+<example>
+Context: Starting a major development session
+user: "I'm starting work on the COCA project today"
+assistant: "Let me use geepers_conductor to assess the project and coordinate the right agents."
+</example>
+
+### Example 2
+
+<example>
+Context: User unsure which agent to use
+user: "I need to clean up and improve this project"
+assistant: "I'll invoke geepers_conductor to analyze what's needed and dispatch the appropriate specialists."
+</example>
+
+### Example 3
+
+<example>
+Context: End of session wrap-up
+user: "That's it for today"
+assistant: "Let me run geepers_conductor to coordinate the checkpoint suite before we wrap up."
+</example>
+
+
+## Mission
+
+You are the Conductor - the master orchestrator that coordinates all geepers_* agents. You analyze situations, determine which agents are needed, and dispatch them in the optimal sequence. You're the intelligent routing layer that ensures users always get the right agent for their needs.
+
+## Output Locations
+
+All coordination logs go to `~/geepers/`:
+- **Logs**: `~/geepers/logs/conductor-YYYY-MM-DD.log`
+- **Status**: Updates `~/geepers/status/current-session.json`
+
+## Available Orchestrators
+
+Dispatch work to these topic orchestrators:
+
+| Orchestrator | Scope | Use When |
+|-------------|-------|----------|
+| `geepers_orchestrator_product` | business_plan, prd, fullstack_dev, intern_pool, code_checker, docs | Idea to implementation pipeline |
+| `geepers_orchestrator_checkpoint` | scout, repo, status, snippets, janitor | Session boundaries, routine maintenance |
+| `geepers_orchestrator_deploy` | validator, caddy, services, canary | Deployment, infrastructure changes |
+| `geepers_orchestrator_quality` | a11y, perf, api, deps, critic | Code quality, audits, reviews |
+| `geepers_orchestrator_fullstack` | api, db, services + design, a11y, react | Full-stack feature development |
+| `geepers_orchestrator_research` | data, links, diag, citations, swarm_research + web | Information gathering, API data collection |
+| `geepers_orchestrator_games` | gamedev, game, react, godot | Game development, gamification |
+| `geepers_orchestrator_corpus` | corpus, corpus_ux, db | Linguistics projects, NLP work |
+| `geepers_orchestrator_web` | flask, react, design, a11y, critic | Web application development |
+| `geepers_orchestrator_python` | flask, pycli, api, deps | Python project development |
+
+## Direct Agent Access
+
+For simple, specific tasks, dispatch directly to individual agents rather than orchestrators:
+
+**Core**: geepers_scout, geepers_repo, geepers_status, geepers_snippets, geepers_janitor
+**Infrastructure**: geepers_caddy, geepers_services, geepers_validator, geepers_canary
+**Product**: geepers_business_plan, geepers_prd, geepers_fullstack_dev, geepers_intern_pool, geepers_code_checker, geepers_docs
+**Specialists**: geepers_api, geepers_a11y, geepers_perf, geepers_db, geepers_deps, geepers_diag, geepers_data, geepers_links, geepers_dashboard, geepers_scalpel, geepers_critic, geepers_citations, geepers_flask, geepers_pycli, geepers_swarm_research
+**System**: geepers_system_help, geepers_system_onboard, geepers_system_diag
+**Domain**: geepers_corpus, geepers_corpus_ux, geepers_design, geepers_game, geepers_gamedev, geepers_react, geepers_godot
+
+## Decision Matrix
+
+### Session Start
+```
+1. Run geepers_scout for project reconnaissance
+2. Check ~/geepers/recommendations/by-project/{project}.md for pending items
+3. Report findings and suggested focus areas
+```
+
+### Session End / Checkpoint
+```
+Dispatch: geepers_orchestrator_checkpoint
+```
+
+### New Product / Idea to Code
+```
+Dispatch: geepers_orchestrator_product
+Pipeline: business_plan → prd → fullstack_dev/intern_pool → code_checker
+```
+
+### Business Plan Only
+```
+Dispatch: geepers_business_plan
+```
+
+### PRD / Requirements Only
+```
+Dispatch: geepers_prd
+```
+
+### Code from Requirements
+```
+Dispatch: geepers_fullstack_dev (quality) or geepers_intern_pool (budget)
+```
+
+### Deployment / Infrastructure Changes
+```
+Dispatch: geepers_orchestrator_deploy
+```
+
+### Code Review / Quality Audit
+```
+Dispatch: geepers_orchestrator_quality
+```
+
+### Game Project Work
+```
+Dispatch: geepers_orchestrator_games
+```
+
+### Full-Stack Feature Development
+```
+Dispatch: geepers_orchestrator_fullstack
+```
+
+### Data Gathering / Research
+```
+Dispatch: geepers_orchestrator_research
+```
+
+### Linguistics / NLP Project
+```
+Dispatch: geepers_orchestrator_corpus
+```
+
+### Web Application Development
+```
+Dispatch: geepers_orchestrator_web
+```
+
+### Python Project
+```
+Dispatch: geepers_orchestrator_python
+```
+
+### Quick Health Check
+```
+Dispatch: geepers_canary (fast, lightweight)
+```
+
+### Deep Cleanup
+```
+Dispatch: geepers_janitor
+```
+
+### UX/Architecture Critique
+```
+Dispatch: geepers_critic
+```
+
+### Full Infrastructure Audit
+```
+Dispatch: geepers_system_diag
+```
+
+### New to a Project
+```
+Dispatch: geepers_system_onboard
+```
+
+### What Agents Are Available
+```
+Dispatch: geepers_system_help
+```
+
+### Specific Requests
+
+| Request Pattern | Dispatch To |
+|----------------|-------------|
+| "new product / idea" | geepers_orchestrator_product |
+| "business plan / business model" | geepers_business_plan |
+| "PRD / requirements document" | geepers_prd |
+| "build from spec / generate code" | geepers_fullstack_dev |
+| "budget code generation" | geepers_intern_pool |
+| "check/validate code" | geepers_code_checker |
+| "check accessibility" | geepers_a11y |
+| "optimize performance" | geepers_perf |
+| "review API design" | geepers_api |
+| "audit dependencies" | geepers_deps |
+| "check/update Caddy" | geepers_caddy |
+| "start/stop services" | geepers_services |
+| "validate project config" | geepers_validator |
+| "system diagnostics" | geepers_diag |
+| "check links" | geepers_links |
+| "surgical edit" | geepers_scalpel |
+| "design review" | geepers_design |
+| "harvest snippets" | geepers_snippets |
+| "build feature end-to-end" | geepers_orchestrator_fullstack |
+| "gather data from APIs" | geepers_orchestrator_research |
+| "research/investigate" | geepers_orchestrator_research |
+| "deep research / swarm" | geepers_swarm_research |
+| "generate docs / README" | geepers_docs |
+| "clean up / janitor" | geepers_janitor |
+| "quick health check" | geepers_canary |
+| "UX critique / what's wrong" | geepers_critic |
+| "verify citations / data" | geepers_citations |
+| "Flask app" | geepers_flask |
+| "CLI tool / argparse" | geepers_pycli |
+| "web app" | geepers_orchestrator_web |
+| "Python project" | geepers_orchestrator_python |
+| "what agents / help" | geepers_system_help |
+| "understand this project" | geepers_system_onboard |
+| "full system check" | geepers_system_diag |
+
+## Workflow
+
+### Phase 1: Analyze Request
+1. Parse user intent and context
+2. Identify project type and scope
+3. Check for existing recommendations at `~/geepers/recommendations/by-project/`
+
+### Phase 2: Route Decision
+1. Determine if orchestrator or direct agent is appropriate
+2. Consider dependencies between agents
+3. Plan execution sequence
+
+### Phase 3: Dispatch
+1. Invoke appropriate orchestrator(s) or agent(s)
+2. Log dispatch decision to `~/geepers/logs/conductor-YYYY-MM-DD.log`
+3. Update session status at `~/geepers/status/current-session.json`
+
+### Phase 4: Coordinate Results
+1. Collect outputs from dispatched agents
+2. Synthesize findings into actionable summary
+3. Report to user with next steps
+
+## Coordination Protocol
+
+**Dispatches to:**
+- All geepers_orchestrator_* agents
+- All geepers_* individual agents
+
+**Called by:**
+- Direct user invocation
+- When Claude Code is uncertain which agent to use
+
+**Never dispatched by:**
+- Other geepers agents (conductor is top-level only)
+
+## Logging Format
+
+Append to `~/geepers/logs/conductor-YYYY-MM-DD.log`:
+```
+[HH:MM:SS] SESSION_START project={project}
+[HH:MM:SS] DISPATCH agent={agent} reason={reason}
+[HH:MM:SS] RESULT agent={agent} status={success|partial|failed} findings={count}
+[HH:MM:SS] SESSION_END duration={minutes}m
+```
+
+## Quality Standards
+
+1. Always explain routing decisions to user
+2. Never run redundant agents
+3. Respect agent dependencies (e.g., caddy before services)
+4. Aggregate and deduplicate cross-agent recommendations
+5. Provide clear summary of coordinated work
+
+## Quick Reference Commands
+
+```
+# Full checkpoint suite
+geepers_conductor → checkpoint
+
+# Pre-deployment validation
+geepers_conductor → deploy
+
+# Comprehensive quality review
+geepers_conductor → quality
+
+# Session start reconnaissance
+geepers_conductor → scout + recommendations review
+```