feat: integrate Elephant Alpha ecosystem with full ADR-012/013 compliance
Some checks failed
CD Pipeline / deploy (push) Has been cancelled
Some checks failed
CD Pipeline / deploy (push) Has been cancelled
- Add ElephantService, AutonomousEngine, Orchestrator, DecisionRouter (EA 4-file stack) - Fix 10 bugs: URL typo, SQL schema mismatches (price_records JOIN), enum mapping, metadata_json, NemoTron PriceThreat dispatch, async/await mismatch, broken imports - Wire ADR-012 Agent Action Ladder: EventRouter L2 → EA first + AIOrch fallback; all decisions dual-write DB + triaged_alert Telegram; momo: callback prefix - Wire ADR-013 AutoHeal: resource_optimization trigger → AutoHealService - Add W3 guards: connection cache 300s TTL, $5/hr cost hard limit - Add W4 persistence: routing decisions + agent performance snapshots → ai_insights - Add Migration 015: confidence + created_by columns on ai_insights - Fix run_scheduler.py broken imports (DecisionTracker service didn't exist) - Fix verify_elephant_integration.py: check_status() → check_connection() Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
ogt
352
docs/ELEPHANT_ALPHA_SETUP.md
Normal file
352
docs/ELEPHANT_ALPHA_SETUP.md
Normal file
@@ -0,0 +1,352 @@
|
||||
# Elephant Alpha AI Agent Super Orchestrator Setup Guide
|
||||
|
||||
## Overview
|
||||
|
||||
Elephant Alpha (100B parameter, 256K context) serves as the AI 3.0 Super Orchestrator for momo-pro-system, enabling autonomous decision-making and intelligent coordination across all AI agents.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Elephant Alpha (Super Orchestrator)
|
||||
|
|
||||
|-- Hermes Analyst (Price Competition Intelligence)
|
||||
|-- NemoTron Dispatcher (Action & Tool Calling)
|
||||
|-- OpenClaw Strategist (Strategic Planning)
|
||||
|
|
||||
|-- Autonomous Decision Engine
|
||||
|-- Intelligent Decision Router
|
||||
|-- Self-Learning & Adaptation
|
||||
```
|
||||
|
||||
## Features
|
||||
|
||||
### 1. **Super Orchestration**
|
||||
- Cross-agent coordination and optimization
|
||||
- Strategic long-term planning
|
||||
- Resource allocation optimization
|
||||
- Conflict resolution between agents
|
||||
|
||||
### 2. **Autonomous Decision Engine**
|
||||
- Continuous monitoring and triggers
|
||||
- Self-learning from outcomes
|
||||
- Predictive decision making
|
||||
- Automatic escalation to human oversight
|
||||
|
||||
### 3. **Intelligent Routing**
|
||||
- Performance-based agent selection
|
||||
- Dynamic task allocation
|
||||
- Cost-aware routing
|
||||
- Adaptive strategy selection
|
||||
|
||||
## Setup Instructions
|
||||
|
||||
### Step 1: Environment Configuration
|
||||
|
||||
1. **Copy environment template:**
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
2. **Configure OpenRouter API:**
|
||||
```bash
|
||||
# Get API key from https://openrouter.ai/keys
|
||||
export OPENROUTER_API_KEY="sk-or-v1-your-api-key"
|
||||
```
|
||||
|
||||
3. **Update .env file:**
|
||||
```env
|
||||
# Elephant Alpha Configuration
|
||||
OPENROUTER_API_KEY=sk-or-v1-your-openrouter-api-key-here
|
||||
ELEPHANT_ALPHA_MODEL=openrouter/elephant-alpha
|
||||
ELEPHANT_ALPHA_CONFIDENCE_THRESHOLD=0.7
|
||||
ELEPHANT_ALPHA_MAX_AUTONOMOUS_DECISIONS_PER_HOUR=10
|
||||
```
|
||||
|
||||
### Step 2: Install Dependencies
|
||||
|
||||
```bash
|
||||
# Install required packages
|
||||
pip install requests numpy asyncio
|
||||
|
||||
# Elephant Alpha uses existing infrastructure
|
||||
# No additional dependencies required
|
||||
```
|
||||
|
||||
### Step 3: Start the Application
|
||||
|
||||
```bash
|
||||
# Start momo-pro-system
|
||||
python app.py
|
||||
|
||||
# Elephant Alpha will automatically initialize
|
||||
# Check logs for registration status
|
||||
```
|
||||
|
||||
### Step 4: Verify Installation
|
||||
|
||||
```bash
|
||||
# Health check
|
||||
curl http://localhost:5000/api/elephant-alpha/health
|
||||
|
||||
# Expected response:
|
||||
{
|
||||
"success": true,
|
||||
"healthy": true,
|
||||
"components": {
|
||||
"orchestrator": true,
|
||||
"autonomous_engine": true,
|
||||
"decision_router": true,
|
||||
"api_key_configured": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## API Usage
|
||||
|
||||
### 1. **Strategic Orchestration**
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:5000/api/elephant-alpha/orchestrate \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"business_context": {
|
||||
"task_type": "price_optimization",
|
||||
"urgency": "high",
|
||||
"complexity": "medium",
|
||||
"objectives": ["revenue_protection", "market_share"],
|
||||
"constraints": {"budget": 1000, "time_limit": "1 hour"}
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### 2. **Intelligent Routing**
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:5000/api/elephant-alpha/route \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"task_type": "threat_response",
|
||||
"urgency": "critical",
|
||||
"complexity": "simple",
|
||||
"quality_requirement": "premium"
|
||||
}'
|
||||
```
|
||||
|
||||
### 3. **Start Autonomous Engine**
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:5000/api/elephant-alpha/autonomous/start
|
||||
```
|
||||
|
||||
### 4. **Monitor Performance**
|
||||
|
||||
```bash
|
||||
# Agent performance
|
||||
curl http://localhost:5000/api/elephant-alpha/agents/performance
|
||||
|
||||
# Autonomous status
|
||||
curl http://localhost:5000/api/elephant-alpha/autonomous/status
|
||||
|
||||
# Decision history
|
||||
curl http://localhost:5000/api/elephant-alpha/decisions/history
|
||||
```
|
||||
|
||||
## Autonomous Triggers
|
||||
|
||||
Elephant Alpha monitors and automatically responds to:
|
||||
|
||||
### 1. **Price Drop Alerts**
|
||||
- Competitor price drops > 15%
|
||||
- Multiple products affected
|
||||
- Automatic price optimization recommendations
|
||||
|
||||
### 2. **Market Opportunities**
|
||||
- Competitor stockouts
|
||||
- Our inventory availability
|
||||
- Automatic promotion suggestions
|
||||
|
||||
### 3. **Threat Escalation**
|
||||
- High threat scores (> 0.9)
|
||||
- Worsening trends
|
||||
- Automatic human escalation
|
||||
|
||||
### 4. **Resource Optimization**
|
||||
- High system load
|
||||
- Queue management
|
||||
- Dynamic resource allocation
|
||||
|
||||
## Configuration Options
|
||||
|
||||
### Behavior Settings
|
||||
- `ELEPHANT_ALPHA_CONFIDENCE_THRESHOLD`: Minimum confidence for autonomous decisions (0.5-0.9)
|
||||
- `ELEPHANT_ALPHA_MAX_AUTONOMOUS_DECISIONS_PER_HOUR`: Rate limiting (1-20)
|
||||
- `ELEPHANT_ALPHA_TIMEOUT_SECONDS`: Maximum decision time (30-300)
|
||||
|
||||
### Integration Settings
|
||||
- `ELEPHANT_ALPHA_HERMES_URL`: Hermes agent endpoint
|
||||
- `ELEPHANT_ALPHA_HERMES_MODEL`: Hermes model name
|
||||
- `ELEPHANT_ALPHA_NEMOTRON_NIM_ENDPOINT`: NemoTron NIM endpoint
|
||||
- `ELEPHANT_ALPHA_OPENCLAW_GEMINI_ENDPOINT`: OpenClaw Gemini endpoint
|
||||
|
||||
## Monitoring and Debugging
|
||||
|
||||
### 1. **Logs**
|
||||
```bash
|
||||
# Elephant Alpha logs
|
||||
tail -f logs/elephant_alpha_orchestrator.log
|
||||
tail -f logs/elephant_alpha_autonomous.log
|
||||
tail -f logs/elephant_alpha_router.log
|
||||
```
|
||||
|
||||
### 2. **Metrics**
|
||||
```bash
|
||||
# Performance metrics
|
||||
curl http://localhost:5000/api/elephant-alpha/agents/performance
|
||||
|
||||
# Decision history
|
||||
curl http://localhost:5000/api/elephant-alpha/decisions/history?limit=50
|
||||
```
|
||||
|
||||
### 3. **Health Checks**
|
||||
```bash
|
||||
# Overall health
|
||||
curl http://localhost:5000/api/elephant-alpha/health
|
||||
|
||||
# Component status
|
||||
curl http://localhost:5000/api/elephant-alpha/agents/status
|
||||
```
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### 1. **Custom Triggers**
|
||||
Create custom autonomous triggers by modifying `services/elephant_alpha_autonomous_engine.py`:
|
||||
|
||||
```python
|
||||
# Add to _initialize_triggers()
|
||||
AutonomousTrigger(
|
||||
trigger_type="custom_business_rule",
|
||||
conditions={"your_condition": "value"},
|
||||
threshold=0.8,
|
||||
enabled=True
|
||||
)
|
||||
```
|
||||
|
||||
### 2. **Routing Strategies**
|
||||
Modify routing behavior in `services/elephant_alpha_decision_router.py`:
|
||||
|
||||
```python
|
||||
# Add custom routing strategy
|
||||
class RoutingStrategy(Enum):
|
||||
CUSTOM_STRATEGY = "custom_strategy"
|
||||
```
|
||||
|
||||
### 3. **Agent Integration**
|
||||
Add new agents to the orchestrator:
|
||||
|
||||
```python
|
||||
# Register new agent in elephant_orchestrator.py
|
||||
self.agents["new_agent"] = AgentCapability(
|
||||
name="New Agent",
|
||||
model="new-model",
|
||||
strengths=["capability1", "capability2"],
|
||||
limitations=["limitation1"],
|
||||
cost_per_token=0.0,
|
||||
max_context=32000
|
||||
)
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **API Key Not Configured**
|
||||
```
|
||||
Error: OPENROUTER_API_KEY environment variable required
|
||||
```
|
||||
Solution: Set the environment variable or add to .env file
|
||||
|
||||
2. **Agent Connection Failed**
|
||||
```
|
||||
Error: Agent execution failed
|
||||
```
|
||||
Solution: Check agent endpoints and network connectivity
|
||||
|
||||
3. **High Memory Usage**
|
||||
```
|
||||
Error: Memory allocation failed
|
||||
```
|
||||
Solution: Reduce context window or increase system memory
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Enable debug mode for detailed logging:
|
||||
|
||||
```env
|
||||
ELEPHANT_ALPHA_DEBUG_MODE=true
|
||||
```
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### 1. **Context Window**
|
||||
- Default: 256K tokens
|
||||
- Adjust based on available memory
|
||||
- Larger context = better strategic reasoning
|
||||
|
||||
### 2. **Confidence Threshold**
|
||||
- Default: 0.7
|
||||
- Higher = more conservative decisions
|
||||
- Lower = more autonomous actions
|
||||
|
||||
### 3. **Rate Limiting**
|
||||
- Default: 10 decisions/hour
|
||||
- Adjust based on business needs
|
||||
- Prevents API overuse
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **API Key Protection**
|
||||
- Never commit API keys to version control
|
||||
- Use environment variables
|
||||
- Rotate keys regularly
|
||||
|
||||
2. **Autonomous Safeguards**
|
||||
- Confidence thresholds prevent risky decisions
|
||||
- Human escalation for critical impacts
|
||||
- Audit logging for all decisions
|
||||
|
||||
3. **Network Security**
|
||||
- Secure agent communication
|
||||
- Validate all inputs
|
||||
- Monitor for anomalies
|
||||
|
||||
## Support
|
||||
|
||||
For issues and questions:
|
||||
|
||||
1. Check logs for error details
|
||||
2. Verify environment configuration
|
||||
3. Test individual components
|
||||
4. Review decision history for patterns
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
Planned features for Elephant Alpha:
|
||||
|
||||
1. **Multi-Model Support**
|
||||
- GPT-4 Turbo integration
|
||||
- Claude 3.5 Sonnet support
|
||||
- Dynamic model selection
|
||||
|
||||
2. **Advanced Learning**
|
||||
- Reinforcement learning
|
||||
- Pattern recognition
|
||||
- Predictive analytics
|
||||
|
||||
3. **Enhanced Automation**
|
||||
- Workflow orchestration
|
||||
- Process optimization
|
||||
- Resource auto-scaling
|
||||
|
||||
---
|
||||
|
||||
**Elephant Alpha transforms momo-pro-system into an AI 3.0 autonomous platform, enabling intelligent decision-making and self-optimization across all business operations.**
|
||||
Reference in New Issue
Block a user