ClaudeFlow ported, needs cleanup

2025-08-10 12:00:13 -04:00
parent 08df0d26aa
commit 475b483850
61 changed files with 14025 additions and 3000 deletions
@@ -0,0 +1,389 @@
+# CleverClaude Quick Start Guide
+
+Get up and running with CleverClaude in minutes! This guide walks you through creating your first AI agent swarm.
+
+## 📋 Prerequisites
+
+- Python 3.11+ 
+- Git (optional, for development)
+- Redis server (for production usage)
+- PostgreSQL (for production usage)
+
+## 🚀 Installation
+
+### Option 1: Quick Install with uv (Recommended)
+
+```bash
+# Install uv if you don't have it
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install CleverClaude
+uv pip install cleverclaude
+
+# Verify installation
+cleverclaude --version
+```
+
+### Option 2: Standard pip Install
+
+```bash
+pip install cleverclaude
+```
+
+### Option 3: Development Install
+
+```bash
+git clone https://github.com/your-org/cleverclaude.git
+cd cleverclaude
+uv venv
+source .venv/bin/activate
+uv pip install -e .[dev]
+```
+
+## 🏁 Your First CleverClaude Project
+
+### Step 1: Initialize a New Project
+
+```bash
+# Create a new CleverClaude project
+cleverclaude init my-first-project
+
+# Navigate to the project directory
+cd my-first-project
+
+# Explore the generated structure
+ls -la
+```
+
+This creates:
+```
+my-first-project/
+├── .cleverclaude/          # Configuration directory
+│   ├── config.yaml        # Main configuration
+│   ├── data/              # Data storage
+│   ├── logs/              # Application logs
+│   └── cache/             # Cache directory
+├── agents/                # Custom agent definitions
+├── tasks/                 # Task definitions
+├── workflows/             # Workflow templates
+├── memory/                # Persistent memory
+├── examples/              # Example code
+│   ├── basic_agent.py     # Single agent example
+│   ├── swarm_coordination.py  # Multi-agent swarm
+│   └── task_orchestration.py  # Complex workflows
+├── .env.example           # Environment variables
+└── docker-compose.yml     # Optional Docker setup
+```
+
+### Step 2: Configure Your Environment
+
+```bash
+# Copy environment template
+cp .env.example .env
+
+# Edit configuration (optional)
+nano .cleverclaude/config.yaml
+```
+
+Basic configuration:
+```yaml
+app:
+  name: "My First Project"
+  environment: "development"
+  debug: true
+
+agents:
+  max_agents: 10
+  default_timeout: 300
+
+swarm:
+  default_topology: "mesh"
+  max_swarm_size: 5
+
+api:
+  host: "127.0.0.1"
+  port: 8000
+```
+
+### Step 3: Start CleverClaude
+
+```bash
+# Start the orchestration system
+cleverclaude start
+
+# Or start in the background
+cleverclaude start --daemon
+
+# Check if it's running
+cleverclaude status
+```
+
+You should see:
+```
+🧠 CleverClaude System Status
+
+System Health:     ✅ Healthy
+Uptime:           00:01:23
+Version:          2.0.0
+
+Agents:           0 active, 0 total
+Swarms:           0 active, 0 total  
+Tasks:            0 completed, 0 running
+
+API Server:       http://127.0.0.1:8000
+Documentation:    http://127.0.0.1:8000/docs
+```
+
+## 👨‍💻 Run Your First Example
+
+### Example 1: Single Agent Task
+
+```bash
+# Run the basic agent example
+python examples/basic_agent.py
+```
+
+Or create your own:
+
+```python
+# my_first_agent.py
+import asyncio
+from cleverclaude import AgentManager, settings
+from cleverclaude.agents.types import AgentType
+
+async def main():
+    # Initialize agent manager
+    manager = AgentManager(settings.agents, None)
+    await manager.initialize()
+    
+    # Create a researcher agent
+    agent_id = await manager.create_agent(
+        agent_type=AgentType.RESEARCHER,
+        name="My First Agent",
+        capabilities={"research", "analysis", "documentation"}
+    )
+    
+    print(f"✅ Created agent: {agent_id}")
+    
+    # Execute a task
+    task = {
+        "id": "first_task",
+        "type": "research_query",
+        "data": {
+            "query": "What are the benefits of AI agent coordination?",
+            "scope": "general",
+            "depth": "standard"
+        }
+    }
+    
+    result = await manager.execute_task(task, agent_id=agent_id)
+    print(f"📋 Task completed: {result['status']}")
+    
+    # Clean up
+    await manager.destroy_agent(agent_id)
+    await manager.shutdown()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Example 2: Multi-Agent Swarm
+
+```python
+# my_first_swarm.py
+import asyncio
+from cleverclaude import SwarmCoordinator, AgentManager, settings
+from cleverclaude.agents.types import AgentType
+from cleverclaude.coordination.types import SwarmTask, TaskPriority
+
+async def main():
+    # Initialize systems
+    agent_manager = AgentManager(settings.agents, None)
+    await agent_manager.initialize()
+    
+    coordinator = SwarmCoordinator(settings.swarm, None, agent_manager)
+    await coordinator.initialize()
+    
+    # Create swarm
+    swarm_id = await coordinator.create_swarm(
+        name="My First Swarm",
+        topology="mesh"
+    )
+    
+    # Add agents
+    agents = []
+    for i, agent_type in enumerate([AgentType.RESEARCHER, AgentType.ANALYST, AgentType.CODER]):
+        agent_id = await agent_manager.create_agent(
+            agent_type=agent_type,
+            name=f"Agent-{i+1}"
+        )
+        agents.append(agent_id)
+        await coordinator.add_agent(swarm_id, agent_id, role="worker")
+    
+    print(f"✅ Created swarm with {len(agents)} agents")
+    
+    # Submit tasks
+    tasks = []
+    for i in range(3):
+        task = SwarmTask(
+            task_type="analysis",
+            priority=TaskPriority.NORMAL,
+            data={
+                "analysis_type": "data_analysis",
+                "dataset": {"records": [f"data_{j}" for j in range(5)]},
+                "task_number": i
+            }
+        )
+        task_id = await coordinator.submit_task(swarm_id, task)
+        tasks.append(task_id)
+    
+    print(f"📋 Submitted {len(tasks)} tasks")
+    
+    # Wait for completion
+    await asyncio.sleep(3)
+    
+    # Get metrics
+    metrics = await coordinator.get_swarm_metrics(swarm_id)
+    print(f"📊 Swarm metrics:")
+    print(f"   Completed tasks: {metrics.completed_tasks}")
+    print(f"   Efficiency: {metrics.efficiency_score:.1f}%")
+    
+    # Cleanup
+    await coordinator.destroy_swarm(swarm_id)
+    await coordinator.shutdown()
+    await agent_manager.shutdown()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## 🔧 Using the CLI
+
+### Basic Commands
+
+```bash
+# Get help
+cleverclaude --help
+
+# Initialize project with specific template
+cleverclaude init --template production my-prod-project
+
+# Start with custom configuration
+cleverclaude start --config-dir ./custom-config --port 9000
+
+# Monitor system in real-time
+cleverclaude status --watch --interval 5
+
+# Get detailed status in JSON
+cleverclaude status --format json
+```
+
+### Configuration Management
+
+```bash
+# Validate configuration
+cleverclaude config validate
+
+# Show current configuration
+cleverclaude config show
+
+# Update configuration
+cleverclaude config set agents.max_agents 20
+cleverclaude config set swarm.default_topology hierarchical
+```
+
+## 🌐 Using the Web Interface
+
+When CleverClaude is running, you can access:
+
+- **Main Dashboard**: http://127.0.0.1:8000
+- **API Documentation**: http://127.0.0.1:8000/docs
+- **Metrics**: http://127.0.0.1:8000/metrics
+- **Health Check**: http://127.0.0.1:8000/health
+
+## 🔍 Monitoring and Debugging
+
+### Check System Health
+
+```bash
+# Basic status
+cleverclaude status
+
+# Detailed system information
+cleverclaude status --format table --verbose
+
+# Watch for changes
+cleverclaude status --watch
+```
+
+### View Logs
+
+```bash
+# View recent logs
+tail -f .cleverclaude/logs/cleverclaude.log
+
+# Filter by level
+grep ERROR .cleverclaude/logs/cleverclaude.log
+
+# View structured JSON logs
+cat .cleverclaude/logs/cleverclaude.log | jq '.'
+```
+
+### Performance Monitoring
+
+```bash
+# Monitor system performance
+cleverclaude monitor
+
+# Get performance report
+cleverclaude monitor --report --timeframe 1h
+```
+
+## 🚀 Next Steps
+
+Now that you have CleverClaude running, explore these advanced topics:
+
+1. **[Agent Development](agents.md)**: Create custom agent types
+2. **[Swarm Patterns](swarms.md)**: Learn advanced coordination strategies
+3. **[MCP Tools](mcp.md)**: Leverage the 87+ tool ecosystem
+4. **[Workflow Automation](workflows.md)**: Build complex task pipelines
+5. **[Production Deployment](deployment.md)**: Scale for production usage
+
+## ❓ Troubleshooting
+
+### Common Issues
+
+**"Command not found: cleverclaude"**
+```bash
+# Make sure CleverClaude is in your PATH
+which cleverclaude
+
+# Or run directly with Python
+python -m cleverclaude --help
+```
+
+**"Connection refused" errors**
+```bash
+# Check if services are running
+cleverclaude status
+
+# Restart services
+cleverclaude start --force-restart
+```
+
+**"Permission denied" on configuration**
+```bash
+# Fix permissions
+chmod -R 755 .cleverclaude/
+```
+
+For more troubleshooting, see the [Troubleshooting Guide](troubleshooting.md).
+
+## 🤝 Getting Help
+
+- **Documentation**: [docs.cleverclaude.ai](https://docs.cleverclaude.ai)
+- **GitHub Issues**: [Report bugs or request features](https://github.com/your-org/cleverclaude/issues)
+- **Discord Community**: [Join the discussion](https://discord.gg/cleverclaude)
+- **Examples Repository**: [More examples and tutorials](https://github.com/your-org/cleverclaude-examples)
+
+Happy orchestrating! 🎉