ClaudeFlow ported, needs cleanup
This commit is contained in:
Your Name
+141
@@ -0,0 +1,141 @@
|
||||
# CleverClaude Documentation
|
||||
|
||||
Welcome to CleverClaude - an advanced AI agent orchestration system that enables sophisticated multi-agent coordination, swarm intelligence, and task automation.
|
||||
|
||||
## 📚 Documentation Index
|
||||
|
||||
- [Installation Guide](installation.md) - Get CleverClaude up and running
|
||||
- [Quick Start](quickstart.md) - Your first CleverClaude project
|
||||
- [Architecture Overview](architecture.md) - System design and components
|
||||
- [CLI Reference](cli-reference.md) - Complete command-line interface guide
|
||||
- [API Documentation](api-reference.md) - HTTP API endpoints and usage
|
||||
- [Agent Management](agents.md) - Creating and managing AI agents
|
||||
- [Swarm Coordination](swarms.md) - Multi-agent swarm orchestration
|
||||
- [MCP Integration](mcp.md) - Model Context Protocol tools and usage
|
||||
- [Configuration](configuration.md) - System configuration options
|
||||
- [Testing Guide](testing.md) - Running and writing tests
|
||||
- [Deployment](deployment.md) - Production deployment strategies
|
||||
- [Examples](examples/) - Code examples and tutorials
|
||||
- [Migration Guide](migration.md) - Migrating from claude-flow
|
||||
- [Contributing](contributing.md) - How to contribute to the project
|
||||
- [Troubleshooting](troubleshooting.md) - Common issues and solutions
|
||||
|
||||
## 🌟 Key Features
|
||||
|
||||
### Multi-Agent Orchestration
|
||||
- **Agent Types**: Researcher, Coder, Analyst, Coordinator, Reviewer, Tester
|
||||
- **Lifecycle Management**: Create, pause, resume, destroy agents
|
||||
- **Task Assignment**: Intelligent task routing based on capabilities
|
||||
- **Health Monitoring**: Real-time agent performance tracking
|
||||
|
||||
### Swarm Coordination
|
||||
- **Multiple Topologies**: Mesh, Hierarchical, Star, Ring architectures
|
||||
- **Dynamic Scaling**: Auto-scale swarms based on workload
|
||||
- **Load Balancing**: Intelligent task distribution
|
||||
- **Fault Tolerance**: Automatic failure detection and recovery
|
||||
|
||||
### MCP Integration
|
||||
- **87+ Tools**: Comprehensive tool ecosystem for AI operations
|
||||
- **Protocol Support**: Full MCP (Model Context Protocol) implementation
|
||||
- **Tool Discovery**: Dynamic tool loading and metadata
|
||||
- **Batch Operations**: Execute multiple tools concurrently
|
||||
|
||||
### Modern Architecture
|
||||
- **Async-First**: Built on Python AsyncIO for high performance
|
||||
- **Type Safe**: Comprehensive type hints with Pydantic validation
|
||||
- **Configurable**: YAML-based configuration with environment overrides
|
||||
- **Observable**: Structured logging with performance metrics
|
||||
|
||||
## 🚀 Quick Example
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
from cleverclaude import CleverClaudeApp, AgentManager, SwarmCoordinator
|
||||
|
||||
async def main():
|
||||
# Initialize CleverClaude
|
||||
app = CleverClaudeApp()
|
||||
await app.initialize()
|
||||
|
||||
# Create agents
|
||||
researcher = await app.agents.create_agent(
|
||||
agent_type="researcher",
|
||||
name="Research Agent",
|
||||
capabilities={"research", "analysis", "documentation"}
|
||||
)
|
||||
|
||||
# Create swarm
|
||||
swarm_id = await app.swarms.create_swarm(
|
||||
name="Research Swarm",
|
||||
topology="mesh"
|
||||
)
|
||||
|
||||
# Add agent to swarm
|
||||
await app.swarms.add_agent(swarm_id, researcher)
|
||||
|
||||
# Execute task
|
||||
task = {
|
||||
"type": "research_query",
|
||||
"data": {
|
||||
"query": "Latest developments in AI agent coordination",
|
||||
"scope": "academic_papers",
|
||||
"depth": "comprehensive"
|
||||
}
|
||||
}
|
||||
|
||||
result = await app.swarms.submit_task(swarm_id, task)
|
||||
print(f"Research completed: {result}")
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
## 📦 Installation
|
||||
|
||||
```bash
|
||||
# Install with uv (recommended)
|
||||
uv pip install cleverclaude
|
||||
|
||||
# Or with pip
|
||||
pip install cleverclaude
|
||||
|
||||
# Development installation
|
||||
git clone https://github.com/your-org/cleverclaude.git
|
||||
cd cleverclaude
|
||||
uv pip install -e .[dev]
|
||||
```
|
||||
|
||||
## 🛠️ CLI Usage
|
||||
|
||||
```bash
|
||||
# Initialize new project
|
||||
cleverclaude init my-project
|
||||
|
||||
# Start the orchestration system
|
||||
cleverclaude start
|
||||
|
||||
# Check system status
|
||||
cleverclaude status
|
||||
|
||||
# Monitor real-time metrics
|
||||
cleverclaude monitor --watch
|
||||
```
|
||||
|
||||
## 📖 Learn More
|
||||
|
||||
- **[Architecture Guide](architecture.md)**: Deep dive into system design
|
||||
- **[Agent Development](agents.md)**: Creating custom agent types
|
||||
- **[Swarm Patterns](swarms.md)**: Advanced coordination strategies
|
||||
- **[MCP Tools](mcp.md)**: Leveraging the 87+ tool ecosystem
|
||||
- **[Production Deployment](deployment.md)**: Scaling CleverClaude
|
||||
|
||||
## 🤝 Community
|
||||
|
||||
- **GitHub**: [CleverClaude Repository](https://github.com/your-org/cleverclaude)
|
||||
- **Documentation**: [docs.cleverclaude.ai](https://docs.cleverclaude.ai)
|
||||
- **Discord**: [CleverClaude Community](https://discord.gg/cleverclaude)
|
||||
- **Issues**: [Bug Reports & Feature Requests](https://github.com/your-org/cleverclaude/issues)
|
||||
|
||||
## 📄 License
|
||||
|
||||
CleverClaude is released under the MIT License. See [LICENSE](../LICENSE) for details.
|
||||
@@ -0,0 +1,572 @@
|
||||
# CleverClaude Architecture Overview
|
||||
|
||||
This document provides a comprehensive overview of CleverClaude's architecture, design principles, and system components.
|
||||
|
||||
## 🏗️ High-Level Architecture
|
||||
|
||||
CleverClaude follows a modern, microservices-inspired architecture built on Python's AsyncIO ecosystem. The system is designed for scalability, maintainability, and extensibility.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
CLI[CLI Interface] --> Core[Core Application]
|
||||
WebUI[Web Interface] --> API[FastAPI Server]
|
||||
API --> Core
|
||||
|
||||
Core --> AM[Agent Manager]
|
||||
Core --> SC[Swarm Coordinator]
|
||||
Core --> MCP[MCP Client]
|
||||
Core --> CM[Configuration Manager]
|
||||
|
||||
AM --> Agents[Agent Pool]
|
||||
SC --> Swarms[Swarm Pool]
|
||||
MCP --> Tools[87+ MCP Tools]
|
||||
|
||||
Core --> DB[(Database)]
|
||||
Core --> Redis[(Redis Cache)]
|
||||
Core --> Storage[(File Storage)]
|
||||
|
||||
Agents --> Tasks[Task Queue]
|
||||
Swarms --> Tasks
|
||||
Tasks --> Results[Result Store]
|
||||
```
|
||||
|
||||
## 🎯 Design Principles
|
||||
|
||||
### 1. Async-First Architecture
|
||||
- Built on Python AsyncIO for high concurrency
|
||||
- Non-blocking I/O operations throughout
|
||||
- Event-driven task processing
|
||||
- Efficient resource utilization
|
||||
|
||||
### 2. Modular Design
|
||||
- Clear separation of concerns
|
||||
- Dependency injection for loose coupling
|
||||
- Plugin architecture for extensibility
|
||||
- Interface-based abstractions
|
||||
|
||||
### 3. Type Safety
|
||||
- Comprehensive type hints using Python 3.11+ features
|
||||
- Pydantic models for data validation
|
||||
- Runtime type checking in critical paths
|
||||
- IDE support and early error detection
|
||||
|
||||
### 4. Configuration-Driven
|
||||
- YAML-based configuration files
|
||||
- Environment variable overrides
|
||||
- Hot-reloading of configuration
|
||||
- Environment-specific settings
|
||||
|
||||
### 5. Observability
|
||||
- Structured logging with correlation IDs
|
||||
- Comprehensive metrics collection
|
||||
- Health checks and monitoring endpoints
|
||||
- Distributed tracing support
|
||||
|
||||
## 🧩 Core Components
|
||||
|
||||
### Core Application (`cleverclaude.core.app`)
|
||||
|
||||
The `CleverClaudeApp` class is the central orchestrator that initializes and coordinates all system components.
|
||||
|
||||
```python
|
||||
class CleverClaudeApp:
|
||||
"""Main application orchestrator."""
|
||||
|
||||
def __init__(self, config_dir: Optional[Path] = None):
|
||||
self.config_dir = config_dir or get_default_config_dir()
|
||||
self.settings = load_settings(self.config_dir)
|
||||
|
||||
# Core components
|
||||
self.agent_manager: Optional[AgentManager] = None
|
||||
self.swarm_coordinator: Optional[SwarmCoordinator] = None
|
||||
self.mcp_client: Optional[MCPClient] = None
|
||||
self.api_server: Optional[APIServer] = None
|
||||
|
||||
async def initialize(self) -> None:
|
||||
"""Initialize all components in dependency order."""
|
||||
await self._initialize_database()
|
||||
await self._initialize_redis()
|
||||
await self._initialize_agents()
|
||||
await self._initialize_swarms()
|
||||
await self._initialize_mcp()
|
||||
await self._initialize_api()
|
||||
|
||||
async def start(self) -> None:
|
||||
"""Start all services."""
|
||||
await self.api_server.start()
|
||||
self.logger.info("CleverClaude started successfully")
|
||||
```
|
||||
|
||||
**Key Responsibilities:**
|
||||
- Component lifecycle management
|
||||
- Dependency injection setup
|
||||
- Configuration loading and validation
|
||||
- Graceful shutdown handling
|
||||
|
||||
### Agent Manager (`cleverclaude.agents.manager`)
|
||||
|
||||
Manages the lifecycle and execution of individual AI agents.
|
||||
|
||||
```python
|
||||
class AgentManager:
|
||||
"""Manages agent lifecycle and task execution."""
|
||||
|
||||
async def create_agent(
|
||||
self,
|
||||
agent_type: AgentType,
|
||||
name: str,
|
||||
capabilities: Optional[Set[str]] = None,
|
||||
**kwargs
|
||||
) -> str:
|
||||
"""Create a new agent instance."""
|
||||
|
||||
async def execute_task(
|
||||
self,
|
||||
task: Dict[str, Any],
|
||||
agent_id: Optional[str] = None
|
||||
) -> Dict[str, Any]:
|
||||
"""Execute a task on an agent."""
|
||||
|
||||
async def destroy_agent(self, agent_id: str) -> None:
|
||||
"""Remove an agent from the system."""
|
||||
```
|
||||
|
||||
**Key Features:**
|
||||
- Agent type factory (Researcher, Coder, Analyst, etc.)
|
||||
- Task routing and load balancing
|
||||
- Health monitoring and failure recovery
|
||||
- Capability-based agent selection
|
||||
- Circuit breaker pattern for fault tolerance
|
||||
|
||||
### Swarm Coordinator (`cleverclaude.coordination.swarm`)
|
||||
|
||||
Orchestrates multi-agent coordination and swarm intelligence.
|
||||
|
||||
```python
|
||||
class SwarmCoordinator:
|
||||
"""Coordinates agent swarms and task distribution."""
|
||||
|
||||
async def create_swarm(
|
||||
self,
|
||||
name: str,
|
||||
topology: SwarmTopology,
|
||||
max_agents: int = 50
|
||||
) -> str:
|
||||
"""Create a new agent swarm."""
|
||||
|
||||
async def submit_task(
|
||||
self,
|
||||
swarm_id: str,
|
||||
task: SwarmTask
|
||||
) -> str:
|
||||
"""Submit a task to a swarm for execution."""
|
||||
|
||||
async def scale_swarm(
|
||||
self,
|
||||
swarm_id: str,
|
||||
target_size: int
|
||||
) -> None:
|
||||
"""Scale swarm to target size."""
|
||||
```
|
||||
|
||||
**Supported Topologies:**
|
||||
- **Mesh**: Full connectivity, peer-to-peer coordination
|
||||
- **Hierarchical**: Tree structure with coordinators and workers
|
||||
- **Star**: Central coordinator with spoke workers
|
||||
- **Ring**: Circular communication patterns
|
||||
|
||||
**Key Features:**
|
||||
- Dynamic scaling based on workload
|
||||
- Fault-tolerant task distribution
|
||||
- Load balancing across agents
|
||||
- Performance metrics and optimization
|
||||
- Cross-swarm coordination
|
||||
|
||||
### MCP Client (`cleverclaude.mcp.client`)
|
||||
|
||||
Implements the Model Context Protocol for external tool integration.
|
||||
|
||||
```python
|
||||
class MCPClient:
|
||||
"""MCP (Model Context Protocol) client for tool execution."""
|
||||
|
||||
async def execute_tool(
|
||||
self,
|
||||
tool_name: str,
|
||||
parameters: Dict[str, Any]
|
||||
) -> MCPToolExecutionResult:
|
||||
"""Execute an MCP tool with given parameters."""
|
||||
|
||||
async def get_available_tools(self) -> Dict[str, MCPToolInfo]:
|
||||
"""Get list of available tools with metadata."""
|
||||
|
||||
async def batch_execute(
|
||||
self,
|
||||
requests: List[Dict[str, Any]]
|
||||
) -> List[MCPToolExecutionResult]:
|
||||
"""Execute multiple tools in parallel."""
|
||||
```
|
||||
|
||||
**Tool Categories:**
|
||||
- **Swarm Management**: 15+ tools for swarm operations
|
||||
- **Neural Operations**: 20+ tools for AI model management
|
||||
- **Memory Management**: 10+ tools for persistent storage
|
||||
- **Performance Monitoring**: 15+ tools for metrics and analysis
|
||||
- **Workflow Automation**: 12+ tools for task orchestration
|
||||
- **GitHub Integration**: 8+ tools for repository management
|
||||
- **DAA Tools**: 10+ tools for autonomous agents
|
||||
- **System Tools**: 8+ tools for system operations
|
||||
|
||||
## 📊 Data Flow Architecture
|
||||
|
||||
### Task Execution Flow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client
|
||||
participant API
|
||||
participant Core
|
||||
participant AM as Agent Manager
|
||||
participant Agent
|
||||
participant SC as Swarm Coordinator
|
||||
participant MCP
|
||||
|
||||
Client->>API: Submit Task Request
|
||||
API->>Core: Route Request
|
||||
|
||||
alt Single Agent Task
|
||||
Core->>AM: Execute Task
|
||||
AM->>Agent: Assign Task
|
||||
Agent->>Agent: Process Task
|
||||
Agent->>AM: Return Result
|
||||
AM->>Core: Task Complete
|
||||
else Swarm Task
|
||||
Core->>SC: Submit to Swarm
|
||||
SC->>SC: Select Agents
|
||||
SC->>AM: Distribute Subtasks
|
||||
AM->>Agent: Execute Subtasks
|
||||
Agent->>AM: Return Results
|
||||
AM->>SC: Aggregate Results
|
||||
SC->>Core: Swarm Task Complete
|
||||
end
|
||||
|
||||
opt MCP Tool Usage
|
||||
Agent->>MCP: Execute Tool
|
||||
MCP->>MCP: Tool Processing
|
||||
MCP->>Agent: Tool Result
|
||||
end
|
||||
|
||||
Core->>API: Return Response
|
||||
API->>Client: Task Result
|
||||
```
|
||||
|
||||
### Memory and State Management
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
App[Application State] --> Memory[Memory Manager]
|
||||
App --> Cache[Redis Cache]
|
||||
App --> DB[PostgreSQL DB]
|
||||
|
||||
Memory --> Namespace[Namespaced Storage]
|
||||
Memory --> TTL[TTL Management]
|
||||
Memory --> Persistence[Persistent Memory]
|
||||
|
||||
Cache --> Session[Session Data]
|
||||
Cache --> TaskQueue[Task Queues]
|
||||
Cache --> Metrics[Real-time Metrics]
|
||||
|
||||
DB --> Config[Configuration]
|
||||
DB --> History[Task History]
|
||||
DB --> Analytics[Analytics Data]
|
||||
```
|
||||
|
||||
## 🔧 Configuration Architecture
|
||||
|
||||
CleverClaude uses a hierarchical configuration system with multiple override levels:
|
||||
|
||||
```yaml
|
||||
# config.yaml
|
||||
app:
|
||||
name: "CleverClaude"
|
||||
version: "2.0.0"
|
||||
environment: "development"
|
||||
debug: true
|
||||
|
||||
database:
|
||||
url: "postgresql+asyncpg://user:pass@localhost/cleverclaude"
|
||||
pool_size: 10
|
||||
max_overflow: 20
|
||||
|
||||
redis:
|
||||
url: "redis://localhost:6379/0"
|
||||
connection_pool_size: 10
|
||||
|
||||
agents:
|
||||
max_agents: 100
|
||||
default_timeout: 300
|
||||
health_check_interval: 30
|
||||
supported_types:
|
||||
- researcher
|
||||
- coder
|
||||
- analyst
|
||||
- coordinator
|
||||
- reviewer
|
||||
- tester
|
||||
|
||||
swarm:
|
||||
default_topology: "mesh"
|
||||
max_swarm_size: 50
|
||||
coordination_timeout: 60
|
||||
scaling:
|
||||
enabled: true
|
||||
min_agents: 1
|
||||
max_agents: 100
|
||||
scale_up_threshold: 0.8
|
||||
scale_down_threshold: 0.3
|
||||
|
||||
mcp:
|
||||
servers:
|
||||
- name: "claude-flow-server"
|
||||
url: "http://localhost:8001/mcp"
|
||||
enabled: true
|
||||
- name: "neural-server"
|
||||
url: "http://localhost:8002/mcp"
|
||||
enabled: true
|
||||
|
||||
api:
|
||||
host: "127.0.0.1"
|
||||
port: 8000
|
||||
docs_enabled: true
|
||||
cors_enabled: true
|
||||
|
||||
monitoring:
|
||||
metrics_enabled: true
|
||||
log_level: "INFO"
|
||||
log_format: "json"
|
||||
tracing_enabled: false
|
||||
```
|
||||
|
||||
**Configuration Priority (highest to lowest):**
|
||||
1. Command-line arguments
|
||||
2. Environment variables (`CLEVERCLAUDE_*`)
|
||||
3. Local configuration files
|
||||
4. Default values
|
||||
|
||||
## 🏃♂️ Performance Architecture
|
||||
|
||||
### Concurrency Model
|
||||
|
||||
```python
|
||||
# AsyncIO-based concurrency
|
||||
async def handle_concurrent_tasks():
|
||||
"""Handle multiple tasks concurrently."""
|
||||
tasks = [
|
||||
process_task_async(task1),
|
||||
process_task_async(task2),
|
||||
process_task_async(task3)
|
||||
]
|
||||
results = await asyncio.gather(*tasks, return_exceptions=True)
|
||||
return results
|
||||
|
||||
# Connection pooling
|
||||
async def get_database_connection():
|
||||
"""Get connection from pool."""
|
||||
async with database_pool.acquire() as connection:
|
||||
return await connection.fetch("SELECT * FROM agents")
|
||||
```
|
||||
|
||||
### Caching Strategy
|
||||
|
||||
- **L1 Cache**: In-memory Python dictionaries for hot data
|
||||
- **L2 Cache**: Redis for session data and temporary results
|
||||
- **L3 Cache**: Database query result caching
|
||||
- **CDN**: Static asset delivery (in production)
|
||||
|
||||
### Resource Management
|
||||
|
||||
```python
|
||||
class ResourceManager:
|
||||
"""Manages system resources and limits."""
|
||||
|
||||
def __init__(self, config: ResourceConfig):
|
||||
self.max_agents = config.max_agents
|
||||
self.max_memory = config.max_memory_mb * 1024 * 1024
|
||||
self.max_cpu_percent = config.max_cpu_percent
|
||||
|
||||
async def allocate_agent(self) -> bool:
|
||||
"""Check if resources are available for new agent."""
|
||||
current_usage = await self.get_current_usage()
|
||||
return (
|
||||
current_usage.agents < self.max_agents and
|
||||
current_usage.memory < self.max_memory and
|
||||
current_usage.cpu_percent < self.max_cpu_percent
|
||||
)
|
||||
```
|
||||
|
||||
## 🔐 Security Architecture
|
||||
|
||||
### Authentication & Authorization
|
||||
|
||||
```python
|
||||
class SecurityManager:
|
||||
"""Handles authentication and authorization."""
|
||||
|
||||
async def authenticate_request(self, token: str) -> Optional[User]:
|
||||
"""Validate request token."""
|
||||
|
||||
async def authorize_action(
|
||||
self,
|
||||
user: User,
|
||||
action: str,
|
||||
resource: str
|
||||
) -> bool:
|
||||
"""Check if user can perform action on resource."""
|
||||
```
|
||||
|
||||
### Security Features
|
||||
|
||||
- **JWT-based authentication** for API access
|
||||
- **Role-based access control** (RBAC) for operations
|
||||
- **Rate limiting** to prevent abuse
|
||||
- **Input validation** using Pydantic schemas
|
||||
- **Secrets management** with environment variables
|
||||
- **Audit logging** for security events
|
||||
|
||||
## 📈 Scalability Architecture
|
||||
|
||||
### Horizontal Scaling
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
LB[Load Balancer] --> API1[API Server 1]
|
||||
LB --> API2[API Server 2]
|
||||
LB --> API3[API Server N]
|
||||
|
||||
API1 --> Redis[(Redis Cluster)]
|
||||
API2 --> Redis
|
||||
API3 --> Redis
|
||||
|
||||
API1 --> DB[(PostgreSQL)]
|
||||
API2 --> DB
|
||||
API3 --> DB
|
||||
|
||||
API1 --> MCP[MCP Servers]
|
||||
API2 --> MCP
|
||||
API3 --> MCP
|
||||
```
|
||||
|
||||
### Auto-Scaling Triggers
|
||||
|
||||
- **CPU utilization** > 80% for 5 minutes
|
||||
- **Memory usage** > 85% for 5 minutes
|
||||
- **Queue depth** > 100 pending tasks
|
||||
- **Response latency** > 2 seconds average
|
||||
|
||||
### Multi-Region Deployment
|
||||
|
||||
```yaml
|
||||
regions:
|
||||
primary:
|
||||
name: "us-east-1"
|
||||
database: "primary"
|
||||
cache: "redis-cluster-east"
|
||||
|
||||
secondary:
|
||||
name: "eu-west-1"
|
||||
database: "read-replica"
|
||||
cache: "redis-cluster-eu"
|
||||
|
||||
disaster_recovery:
|
||||
name: "us-west-2"
|
||||
database: "backup"
|
||||
cache: "redis-standalone"
|
||||
```
|
||||
|
||||
## 🧪 Testing Architecture
|
||||
|
||||
### Test Pyramid
|
||||
|
||||
```mermaid
|
||||
pyramid
|
||||
title Test Pyramid
|
||||
|
||||
"E2E Tests" : 10
|
||||
"Integration Tests" : 30
|
||||
"Unit Tests" : 60
|
||||
```
|
||||
|
||||
### Test Categories
|
||||
|
||||
1. **Unit Tests** (60%): Fast, isolated component tests
|
||||
2. **Integration Tests** (30%): Component interaction tests
|
||||
3. **End-to-End Tests** (10%): Full system workflow tests
|
||||
4. **Property-Based Tests**: Hypothesis-driven edge case testing
|
||||
5. **Performance Tests**: Load testing and benchmarking
|
||||
|
||||
### Test Infrastructure
|
||||
|
||||
```python
|
||||
# Test fixtures and mocking
|
||||
@pytest.fixture
|
||||
async def agent_manager():
|
||||
"""Provide mocked agent manager for tests."""
|
||||
manager = AgentManager(test_config, mock_session, mock_redis)
|
||||
await manager.initialize()
|
||||
yield manager
|
||||
await manager.shutdown()
|
||||
|
||||
# BDD test scenarios
|
||||
Feature: Agent Management
|
||||
Scenario: Create and execute task
|
||||
Given I have an agent manager
|
||||
When I create a researcher agent
|
||||
And I execute a research task
|
||||
Then the task should complete successfully
|
||||
```
|
||||
|
||||
## 📝 Extension Points
|
||||
|
||||
### Custom Agent Types
|
||||
|
||||
```python
|
||||
class CustomAnalystAgent(BaseAgent):
|
||||
"""Custom analyst with specialized capabilities."""
|
||||
|
||||
async def _process_task(self, task: Dict[str, Any]) -> Dict[str, Any]:
|
||||
"""Custom task processing logic."""
|
||||
if task["type"] == "custom_analysis":
|
||||
return await self._perform_custom_analysis(task["data"])
|
||||
return await super()._process_task(task)
|
||||
|
||||
# Register custom agent type
|
||||
AgentFactory.register_agent_type("custom_analyst", CustomAnalystAgent)
|
||||
```
|
||||
|
||||
### Custom MCP Tools
|
||||
|
||||
```python
|
||||
@mcp_tool("custom_data_processor")
|
||||
async def process_custom_data(parameters: Dict[str, Any]) -> MCPToolResult:
|
||||
"""Custom data processing tool."""
|
||||
data = parameters.get("data")
|
||||
processed = await custom_processing_logic(data)
|
||||
return MCPToolResult(success=True, result={"processed_data": processed})
|
||||
```
|
||||
|
||||
### Custom Swarm Topologies
|
||||
|
||||
```python
|
||||
class CustomTopology(SwarmTopology):
|
||||
"""Custom swarm coordination pattern."""
|
||||
|
||||
async def distribute_task(
|
||||
self,
|
||||
task: SwarmTask,
|
||||
agents: List[Agent]
|
||||
) -> List[SubTask]:
|
||||
"""Custom task distribution logic."""
|
||||
return await self._custom_distribution_algorithm(task, agents)
|
||||
```
|
||||
|
||||
This architecture provides a solid foundation for building scalable, maintainable AI agent orchestration systems while remaining extensible for future requirements.
|
||||
@@ -0,0 +1,537 @@
|
||||
# Migration Guide: claude-flow to CleverClaude
|
||||
|
||||
This guide helps you migrate from the original TypeScript claude-flow project to the new Python CleverClaude implementation.
|
||||
|
||||
## 📋 Migration Overview
|
||||
|
||||
CleverClaude is a complete Python rewrite of claude-flow that preserves all functionality while introducing modern Python patterns, improved architecture, and enhanced features.
|
||||
|
||||
### Key Changes
|
||||
|
||||
| Aspect | claude-flow (TypeScript) | CleverClaude (Python) |
|
||||
|--------|-------------------------|----------------------|
|
||||
| **Language** | TypeScript/JavaScript | Python 3.11+ |
|
||||
| **Runtime** | Node.js | Python AsyncIO |
|
||||
| **Architecture** | Express.js based | FastAPI + AsyncIO |
|
||||
| **Configuration** | JSON/JS config | YAML + Environment |
|
||||
| **Testing** | Jest/Mocha | Behave + pytest |
|
||||
| **Package Management** | npm/yarn | uv/pip |
|
||||
| **Database** | Various | PostgreSQL + SQLAlchemy |
|
||||
| **Caching** | Various | Redis |
|
||||
| **Type System** | TypeScript | Python type hints + Pydantic |
|
||||
|
||||
## 🚀 Quick Migration Path
|
||||
|
||||
### 1. Environment Setup
|
||||
|
||||
```bash
|
||||
# Install CleverClaude
|
||||
uv pip install cleverclaude
|
||||
|
||||
# Or development installation
|
||||
git clone https://github.com/your-org/cleverclaude.git
|
||||
cd cleverclaude
|
||||
uv pip install -e .[dev]
|
||||
```
|
||||
|
||||
### 2. Configuration Migration
|
||||
|
||||
**claude-flow config.json:**
|
||||
```json
|
||||
{
|
||||
"app": {
|
||||
"name": "MyApp",
|
||||
"port": 8000
|
||||
},
|
||||
"agents": {
|
||||
"maxAgents": 100,
|
||||
"defaultTimeout": 300
|
||||
},
|
||||
"swarm": {
|
||||
"defaultTopology": "mesh",
|
||||
"maxSwarmSize": 50
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**CleverClaude config.yaml:**
|
||||
```yaml
|
||||
app:
|
||||
name: "MyApp"
|
||||
version: "2.0.0"
|
||||
environment: "production"
|
||||
|
||||
api:
|
||||
host: "127.0.0.1"
|
||||
port: 8000
|
||||
|
||||
agents:
|
||||
max_agents: 100
|
||||
default_timeout: 300
|
||||
|
||||
swarm:
|
||||
default_topology: "mesh"
|
||||
max_swarm_size: 50
|
||||
```
|
||||
|
||||
### 3. Code Migration Examples
|
||||
|
||||
#### Agent Creation
|
||||
|
||||
**claude-flow (TypeScript):**
|
||||
```typescript
|
||||
import { AgentManager, AgentType } from 'claude-flow';
|
||||
|
||||
const manager = new AgentManager(config);
|
||||
await manager.initialize();
|
||||
|
||||
const agentId = await manager.createAgent({
|
||||
type: AgentType.RESEARCHER,
|
||||
name: "Research Agent",
|
||||
capabilities: ["research", "analysis"]
|
||||
});
|
||||
```
|
||||
|
||||
**CleverClaude (Python):**
|
||||
```python
|
||||
from cleverclaude import AgentManager, AgentType, settings
|
||||
|
||||
manager = AgentManager(settings.agents, session, redis)
|
||||
await manager.initialize()
|
||||
|
||||
agent_id = await manager.create_agent(
|
||||
agent_type=AgentType.RESEARCHER,
|
||||
name="Research Agent",
|
||||
capabilities={"research", "analysis"}
|
||||
)
|
||||
```
|
||||
|
||||
#### Swarm Coordination
|
||||
|
||||
**claude-flow (TypeScript):**
|
||||
```typescript
|
||||
import { SwarmCoordinator, SwarmTopology } from 'claude-flow';
|
||||
|
||||
const coordinator = new SwarmCoordinator(config);
|
||||
const swarmId = await coordinator.createSwarm({
|
||||
name: "Analysis Swarm",
|
||||
topology: SwarmTopology.HIERARCHICAL
|
||||
});
|
||||
|
||||
await coordinator.addAgent(swarmId, agentId, "worker");
|
||||
```
|
||||
|
||||
**CleverClaude (Python):**
|
||||
```python
|
||||
from cleverclaude import SwarmCoordinator, SwarmTopology
|
||||
|
||||
coordinator = SwarmCoordinator(settings.swarm, session, agent_manager, redis)
|
||||
swarm_id = await coordinator.create_swarm(
|
||||
name="Analysis Swarm",
|
||||
topology=SwarmTopology.HIERARCHICAL
|
||||
)
|
||||
|
||||
await coordinator.add_agent(swarm_id, agent_id, role="worker")
|
||||
```
|
||||
|
||||
#### MCP Tool Usage
|
||||
|
||||
**claude-flow (TypeScript):**
|
||||
```typescript
|
||||
import { MCPClient } from 'claude-flow/mcp';
|
||||
|
||||
const client = new MCPClient();
|
||||
const result = await client.executeTool('swarm_init', {
|
||||
topology: 'mesh',
|
||||
maxAgents: 10
|
||||
});
|
||||
```
|
||||
|
||||
**CleverClaude (Python):**
|
||||
```python
|
||||
from cleverclaude.mcp import MCPClient
|
||||
|
||||
client = MCPClient(settings)
|
||||
await client.initialize()
|
||||
|
||||
result = await client.execute_tool('swarm_init', {
|
||||
'topology': 'mesh',
|
||||
'maxAgents': 10
|
||||
})
|
||||
```
|
||||
|
||||
## 📚 API Migration
|
||||
|
||||
### REST API Endpoints
|
||||
|
||||
Most REST endpoints remain the same, but with improved response formats:
|
||||
|
||||
| Endpoint | claude-flow | CleverClaude | Changes |
|
||||
|----------|-------------|--------------|---------|
|
||||
| `POST /agents` | ✅ | ✅ | Enhanced error handling |
|
||||
| `GET /agents/{id}` | ✅ | ✅ | Additional metadata |
|
||||
| `POST /swarms` | ✅ | ✅ | More topology options |
|
||||
| `POST /swarms/{id}/tasks` | ✅ | ✅ | Better progress tracking |
|
||||
| `GET /health` | ✅ | ✅ | Comprehensive health info |
|
||||
| `GET /metrics` | ✅ | ✅ | Prometheus format |
|
||||
|
||||
### WebSocket Events
|
||||
|
||||
WebSocket event names and formats remain compatible:
|
||||
|
||||
```python
|
||||
# CleverClaude WebSocket events (compatible with claude-flow)
|
||||
{
|
||||
"type": "agent_created",
|
||||
"data": {
|
||||
"agentId": "agent_123",
|
||||
"type": "researcher",
|
||||
"status": "active"
|
||||
}
|
||||
}
|
||||
|
||||
{
|
||||
"type": "task_completed",
|
||||
"data": {
|
||||
"taskId": "task_456",
|
||||
"agentId": "agent_123",
|
||||
"result": { ... },
|
||||
"duration": 1250
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🔧 Configuration Migration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
**claude-flow:**
|
||||
```bash
|
||||
CLAUDE_FLOW_PORT=8000
|
||||
CLAUDE_FLOW_DB_URL=postgresql://...
|
||||
CLAUDE_FLOW_REDIS_URL=redis://...
|
||||
CLAUDE_FLOW_LOG_LEVEL=info
|
||||
```
|
||||
|
||||
**CleverClaude:**
|
||||
```bash
|
||||
CLEVERCLAUDE_API_PORT=8000
|
||||
CLEVERCLAUDE_DB_URL=postgresql+asyncpg://...
|
||||
CLEVERCLAUDE_REDIS_URL=redis://...
|
||||
CLEVERCLAUDE_MONITORING_LOG_LEVEL=INFO
|
||||
```
|
||||
|
||||
### Configuration File Structure
|
||||
|
||||
**claude-flow structure:**
|
||||
```
|
||||
config/
|
||||
├── development.json
|
||||
├── production.json
|
||||
└── test.json
|
||||
```
|
||||
|
||||
**CleverClaude structure:**
|
||||
```
|
||||
.cleverclaude/
|
||||
├── config.yaml # Main configuration
|
||||
├── data/ # Data storage
|
||||
├── logs/ # Application logs
|
||||
└── cache/ # Cache directory
|
||||
```
|
||||
|
||||
## 🧪 Testing Migration
|
||||
|
||||
### Test Framework Changes
|
||||
|
||||
**claude-flow (Jest):**
|
||||
```javascript
|
||||
describe('Agent Manager', () => {
|
||||
test('should create agent', async () => {
|
||||
const manager = new AgentManager(config);
|
||||
const agentId = await manager.createAgent({
|
||||
type: 'researcher',
|
||||
name: 'Test Agent'
|
||||
});
|
||||
expect(agentId).toBeDefined();
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
**CleverClaude (pytest):**
|
||||
```python
|
||||
@pytest.mark.async_test
|
||||
class TestAgentManager:
|
||||
async def test_create_agent(self, agent_manager):
|
||||
agent_id = await agent_manager.create_agent(
|
||||
agent_type=AgentType.RESEARCHER,
|
||||
name="Test Agent"
|
||||
)
|
||||
assert agent_id is not None
|
||||
```
|
||||
|
||||
**CleverClaude (BDD with Behave):**
|
||||
```gherkin
|
||||
Feature: Agent Management
|
||||
Scenario: Create a researcher agent
|
||||
Given I have an agent manager
|
||||
When I create a researcher agent named "Test Agent"
|
||||
Then the agent should be created successfully
|
||||
And the agent should be in "active" status
|
||||
```
|
||||
|
||||
## 📦 Deployment Migration
|
||||
|
||||
### Docker Migration
|
||||
|
||||
**claude-flow Dockerfile:**
|
||||
```dockerfile
|
||||
FROM node:18-alpine
|
||||
WORKDIR /app
|
||||
COPY package*.json ./
|
||||
RUN npm ci --only=production
|
||||
COPY . .
|
||||
EXPOSE 8000
|
||||
CMD ["npm", "start"]
|
||||
```
|
||||
|
||||
**CleverClaude Dockerfile:**
|
||||
```dockerfile
|
||||
FROM python:3.11-slim
|
||||
WORKDIR /app
|
||||
COPY pyproject.toml ./
|
||||
RUN pip install uv && uv pip install .
|
||||
COPY . .
|
||||
EXPOSE 8000
|
||||
CMD ["cleverclaude", "start"]
|
||||
```
|
||||
|
||||
### Docker Compose Migration
|
||||
|
||||
**claude-flow docker-compose.yml:**
|
||||
```yaml
|
||||
version: '3.8'
|
||||
services:
|
||||
claude-flow:
|
||||
build: .
|
||||
ports:
|
||||
- "8000:8000"
|
||||
environment:
|
||||
- NODE_ENV=production
|
||||
depends_on:
|
||||
- redis
|
||||
- postgres
|
||||
|
||||
redis:
|
||||
image: redis:7-alpine
|
||||
|
||||
postgres:
|
||||
image: postgres:15
|
||||
environment:
|
||||
POSTGRES_DB: claude_flow
|
||||
```
|
||||
|
||||
**CleverClaude docker-compose.yml:**
|
||||
```yaml
|
||||
version: '3.8'
|
||||
services:
|
||||
cleverclaude:
|
||||
build: .
|
||||
ports:
|
||||
- "8000:8000"
|
||||
environment:
|
||||
- CLEVERCLAUDE_ENVIRONMENT=production
|
||||
depends_on:
|
||||
- redis
|
||||
- postgres
|
||||
|
||||
redis:
|
||||
image: redis:7-alpine
|
||||
|
||||
postgres:
|
||||
image: postgres:15
|
||||
environment:
|
||||
POSTGRES_DB: cleverclaude
|
||||
```
|
||||
|
||||
## 🔄 Data Migration
|
||||
|
||||
### Database Schema Migration
|
||||
|
||||
CleverClaude provides migration scripts to convert your existing data:
|
||||
|
||||
```bash
|
||||
# Export data from claude-flow
|
||||
claude-flow export --format json --output claude-flow-data.json
|
||||
|
||||
# Import to CleverClaude
|
||||
cleverclaude import --source claude-flow-data.json --format claude-flow
|
||||
```
|
||||
|
||||
### Manual Data Migration
|
||||
|
||||
For custom data structures, use the migration API:
|
||||
|
||||
```python
|
||||
from cleverclaude.migration import ClaudeFlowMigrator
|
||||
|
||||
migrator = ClaudeFlowMigrator()
|
||||
|
||||
# Migrate agents
|
||||
await migrator.migrate_agents('path/to/agents.json')
|
||||
|
||||
# Migrate swarms
|
||||
await migrator.migrate_swarms('path/to/swarms.json')
|
||||
|
||||
# Migrate tasks and results
|
||||
await migrator.migrate_task_history('path/to/tasks.json')
|
||||
```
|
||||
|
||||
## 🚨 Breaking Changes
|
||||
|
||||
### 1. Method Naming Convention
|
||||
|
||||
| claude-flow | CleverClaude | Reason |
|
||||
|-------------|--------------|---------|
|
||||
| `createAgent()` | `create_agent()` | Python snake_case |
|
||||
| `addAgent()` | `add_agent()` | Python snake_case |
|
||||
| `getMetrics()` | `get_metrics()` | Python snake_case |
|
||||
|
||||
### 2. Configuration Structure
|
||||
|
||||
- **Nested configuration** now uses YAML hierarchy
|
||||
- **Environment variables** use `CLEVERCLAUDE_` prefix
|
||||
- **Database URLs** require async driver specification
|
||||
|
||||
### 3. Error Handling
|
||||
|
||||
```python
|
||||
# CleverClaude uses structured exceptions
|
||||
try:
|
||||
agent_id = await manager.create_agent(...)
|
||||
except AgentCreationError as e:
|
||||
logger.error(f"Agent creation failed: {e.message}", extra=e.context)
|
||||
except ResourceLimitError as e:
|
||||
logger.warning(f"Resource limit reached: {e.limit_type}")
|
||||
```
|
||||
|
||||
### 4. Async/Await Required
|
||||
|
||||
All API methods are now async and require `await`:
|
||||
|
||||
```python
|
||||
# All operations are async
|
||||
await manager.create_agent(...)
|
||||
await coordinator.add_agent(...)
|
||||
await client.execute_tool(...)
|
||||
```
|
||||
|
||||
## ✅ Migration Checklist
|
||||
|
||||
### Pre-Migration
|
||||
- [ ] Backup your claude-flow data and configuration
|
||||
- [ ] Document current API integrations
|
||||
- [ ] List custom extensions and plugins
|
||||
- [ ] Review current monitoring and alerting setup
|
||||
|
||||
### During Migration
|
||||
- [ ] Install CleverClaude and dependencies
|
||||
- [ ] Convert configuration files to YAML format
|
||||
- [ ] Update environment variables
|
||||
- [ ] Migrate database schema and data
|
||||
- [ ] Update API client code to use Python patterns
|
||||
- [ ] Convert tests to pytest/Behave format
|
||||
|
||||
### Post-Migration
|
||||
- [ ] Verify all agents and swarms are functioning
|
||||
- [ ] Test MCP tool integrations
|
||||
- [ ] Update monitoring and alerting configurations
|
||||
- [ ] Update deployment pipelines
|
||||
- [ ] Train team on new Python codebase
|
||||
- [ ] Update documentation and runbooks
|
||||
|
||||
### Testing Your Migration
|
||||
- [ ] Run comprehensive test suite
|
||||
- [ ] Perform load testing with realistic workloads
|
||||
- [ ] Test failure scenarios and recovery
|
||||
- [ ] Validate performance metrics
|
||||
- [ ] Test all API endpoints and WebSocket events
|
||||
|
||||
## 🆘 Migration Support
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Issue: Import errors**
|
||||
```python
|
||||
# Wrong
|
||||
from claude_flow import AgentManager
|
||||
|
||||
# Correct
|
||||
from cleverclaude import AgentManager
|
||||
```
|
||||
|
||||
**Issue: Async/await missing**
|
||||
```python
|
||||
# Wrong
|
||||
result = manager.create_agent(...)
|
||||
|
||||
# Correct
|
||||
result = await manager.create_agent(...)
|
||||
```
|
||||
|
||||
**Issue: Configuration format**
|
||||
```yaml
|
||||
# Wrong (JSON-style in YAML)
|
||||
{"agents": {"max_agents": 100}}
|
||||
|
||||
# Correct (YAML format)
|
||||
agents:
|
||||
max_agents: 100
|
||||
```
|
||||
|
||||
### Migration Tools
|
||||
|
||||
CleverClaude provides several tools to help with migration:
|
||||
|
||||
```bash
|
||||
# Validate migration
|
||||
cleverclaude migrate validate --source ./claude-flow-config
|
||||
|
||||
# Dry-run migration
|
||||
cleverclaude migrate plan --source ./claude-flow-config --target ./cleverclaude-config
|
||||
|
||||
# Execute migration
|
||||
cleverclaude migrate execute --source ./claude-flow-config --target ./cleverclaude-config
|
||||
|
||||
# Rollback if needed
|
||||
cleverclaude migrate rollback --backup ./migration-backup
|
||||
```
|
||||
|
||||
### Getting Help
|
||||
|
||||
- **Migration Documentation**: [Full migration guide](https://docs.cleverclaude.ai/migration)
|
||||
- **GitHub Issues**: [Report migration problems](https://github.com/your-org/cleverclaude/issues)
|
||||
- **Discord Community**: [#migration-help channel](https://discord.gg/cleverclaude)
|
||||
- **Professional Support**: Available for enterprise migrations
|
||||
|
||||
## 🎯 Benefits of Migration
|
||||
|
||||
### Performance Improvements
|
||||
- **2-3x faster** startup time
|
||||
- **50% less memory** usage with AsyncIO
|
||||
- **Better concurrency** handling with Python async
|
||||
- **Improved I/O performance** with async database connections
|
||||
|
||||
### Developer Experience
|
||||
- **Better IDE support** with Python type hints
|
||||
- **Comprehensive testing** with BDD and pytest
|
||||
- **Modern tooling** with uv, ruff, and pyright
|
||||
- **Rich CLI interface** with better error messages
|
||||
|
||||
### Operational Benefits
|
||||
- **Better observability** with structured logging
|
||||
- **Improved monitoring** with Prometheus metrics
|
||||
- **Enhanced security** with modern Python frameworks
|
||||
- **Easier deployment** with standardized Python packaging
|
||||
|
||||
The migration to CleverClaude provides significant long-term benefits while maintaining full compatibility with your existing workflows and integrations.
|
||||
@@ -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! 🎉
|
||||
Reference in New Issue
Block a user