ClaudeFlow ported, needs cleanup
This commit is contained in:
Your Name
@@ -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.
|
||||
Reference in New Issue
Block a user