ewoooc/docs/ELEPHANT_ALPHA_SETUP.md

# 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 NVIDIA NIM API:**
```bash
# Get API key from NVIDIA NIM / build.nvidia.com
export NVIDIA_API_KEY="nvapi-your-api-key"
```

3. **Update .env file:**
```env
# Elephant Alpha Configuration
NVIDIA_API_KEY=nvapi-your-nvidia-api-key-here
ELEPHANT_ALPHA_NEMOTRON_NIM_ENDPOINT=https://integrate.api.nvidia.com/v1
ELEPHANT_ALPHA_URL=https://integrate.api.nvidia.com/v1/chat/completions
ELEPHANT_ALPHA_MODEL=nvidia/llama-3.3-nemotron-super-49b-v1.5
ELEPHANT_ALPHA_FALLBACK_MODELS=nvidia/llama-3.3-nemotron-super-49b-v1.5,nvidia/llama-3.1-nemotron-70b-instruct,meta/llama-3.1-8b-instruct
ELEPHANT_TIMEOUT=120
ELEPHANT_ALPHA_CONFIDENCE_THRESHOLD=0.7
ELEPHANT_ALPHA_MAX_AUTONOMOUS_DECISIONS_PER_HOUR=10
```

Runtime fallback rule: ElephantService tries the next `ELEPHANT_ALPHA_FALLBACK_MODELS` entry when NVIDIA NIM returns 403/404, transient 408/409/425/429, 5xx, timeout, or connection error. Non-transient client errors such as HTTP 400 fail fast so bad requests do not burn quota across all models.

### 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/event_router.py` and `services/elephant_alpha_orchestrator.py`.
`services/elephant_alpha_decision_router.py` was removed during Phase 3f cleanup and must not be reintroduced:

```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.**