# Multi-Agent System Quick Start

## 🚀 5-Minute Setup

### Step 1: Install Dependencies (2 min)

```bash
cd /Users/moshesmanihuruk/Downloads/PSANEW/psa/HACKATHON_SOLUTION
pip install -r requirements_agents.txt
```

### Step 2: Configure Database (1 min)

Edit `config/db_config.json`:
```json
{
  "host": "localhost",
  "user": "root",
  "password": "your_password",
  "database": "appdb"
}
```

### Step 3: Build FAISS Index (1 min)

```bash
cd python
python agent_kb_search.py
```

Output:
```
🔍 Initializing KnowledgeBaseAgent...
   Building FAISS index from Knowledge Base...
   Extracted 313 KB entries
   Generating embeddings...
   ✅ FAISS index built with 313 vectors
   💾 Index saved to kb_faiss.index
```

### Step 4: Test the System (1 min)

```bash
python orchestrator_langgraph.py
```

Expected output:
```
🤖 INITIALIZING MULTI-AGENT ORCHESTRATOR
======================================================================
🔍 Initializing KnowledgeBaseAgent...
   ✅ Loaded 313 KB entries
🔍 Initializing HistoricalIncidentAgent...
   ✅ Connected to database: appdb
🔍 Initializing LogsSearchAgent...
   ✅ Connected to database: appdb
✅ Orchestrator initialized

🚀 PROCESSING INCIDENT THROUGH MULTI-AGENT SYSTEM
======================================================================

STEP 1: Knowledge Base Search
======================================================================
🔍 KnowledgeBaseAgent - Searching Knowledge Base
   ✅ Found 3 relevant KB articles
   Best Match: EDI Timeout Issues
   Similarity: 85%

STEP 2: Historical Incident Search
======================================================================
📚 HistoricalIncidentAgent - Searching Historical Data
   ✅ Found 5 similar incidents
   Average Resolution Time: 18.5 minutes

STEP 3: Logs Analysis
======================================================================
📝 LogsSearchAgent - Analyzing Recent Logs
   ✅ Found 12 recent changes
   Critical Changes: 3

STEP 4: Decision Making
======================================================================
📊 CONFIDENCE SCORES:
   KB Agent:         85%
   Historical Agent: 72%
   Logs Agent:       65%
   Combined:         76%

🎯 FINAL DECISION: RESOLVE
✅ Resolution Steps: 5
✅ Verification Steps: 3
```

## 📖 Usage Examples

### Example 1: Complete Pipeline

```python
from Source_Parser import EmailParser
from orchestrator_langgraph import IncidentResolutionOrchestrator

# Parse alert
parser = EmailParser()
alert = """
Subject: URGENT - COARRI Timeout
COARRI EDI message for vessel MSC GEMMA failed with timeout.
"""
parsed = parser.parse_email(alert)

# Run agents
orchestrator = IncidentResolutionOrchestrator()
result = orchestrator.process_incident(parsed)

# Get recommendation
print(f"Decision: {result['decision']}")
print(f"Steps: {len(result['resolution']['steps'])}")

orchestrator.close()
```

### Example 2: Test Single Agent

```python
from agent_kb_search import KnowledgeBaseAgent

agent = KnowledgeBaseAgent()

incident = {
    'problem_statement': 'BAPLIE position mismatch detected',
    'module': 'Vessel Operations'
}

result = agent.execute(incident)
print(f"Confidence: {result['confidence']:.1%}")
print(f"Steps: {result['resolution_steps']}")
```

### Example 3: Custom Decision Logic

```python
from orchestrator_langgraph import IncidentResolutionOrchestrator

orchestrator = IncidentResolutionOrchestrator()

# Override decision threshold
def custom_decision(state):
    if state['combined_confidence'] > 0.9:
        return "RESOLVE"
    return "ESCALATE"

# Process with custom logic
result = orchestrator.process_incident(parsed_incident)
```

## 🎯 Decision Flow

```
Alert/Email
    ↓
Parser (Objective)
    ↓
Orchestrator
    ↓
┌───────────┬───────────┬───────────┐
│  KB       │ Historical│   Logs    │
│  Agent    │   Agent   │   Agent   │
└─────┬─────┴─────┬─────┴─────┬─────┘
      └───────────┴───────────┘
               ↓
        Decision Engine
               ↓
        ┌──────┴──────┐
        ↓             ↓
    RESOLVE       ESCALATE
```

## 📊 Output Interpretation

### RESOLVE Decision
```json
{
  "decision": "RESOLVE",
  "combined_confidence": 0.85,
  "resolution": {
    "steps": ["Step 1", "Step 2", "..."],
    "verification": ["Check 1", "Check 2"],
    "root_cause": "Connection pool exhausted"
  }
}
```

**Action**: Execute resolution steps, verify, mark resolved

### ESCALATE Decision
```json
{
  "decision": "ESCALATE",
  "combined_confidence": 0.35,
  "escalation": {
    "required": true,
    "reason": "Novel incident, requires expert analysis"
  }
}
```

**Action**: Create escalation ticket, notify product team

## 🔧 Configuration

### Adjust Confidence Weights

In `orchestrator_langgraph.py`:
```python
combined_confidence = (
    kb_confidence * 0.4 +          # Change to 0.5 for more KB weight
    historical_confidence * 0.4 +   # Change to 0.3
    logs_confidence * 0.2           # Keep at 0.2
)
```

### Change Escalation Threshold

```python
# In _make_decision() method
if severity == 'CRITICAL' and combined_confidence < 0.8:  # Change to 0.9
    decision = "ESCALATE"
```

### Add Custom Agent

1. Create new agent file:
```python
# agent_custom.py
class CustomAgent:
    def execute(self, parsed_incident):
        # Your logic
        return {'confidence': 0.8, 'result': '...'}
```

2. Add to orchestrator:
```python
# In orchestrator_langgraph.py
self.custom_agent = CustomAgent()

# Add node
workflow.add_node("custom_search", self._execute_custom_agent)
workflow.add_edge("logs_search", "custom_search")
```

## 📝 Troubleshooting

| Issue | Solution |
|-------|----------|
| ImportError: faiss | `pip install faiss-cpu` |
| Database connection failed | Check `db_config.json` credentials |
| No KB entries | Run `python agent_kb_search.py` first |
| LangGraph not found | `pip install langgraph` |
| Low confidence scores | Rebuild FAISS index, check KB data |

## 🎓 Understanding Confidence Scores

| Score | Meaning | Action |
|-------|---------|--------|
| 90-100% | Exact match found | Auto-resolve |
| 70-89% | Strong match | Resolve with monitoring |
| 50-69% | Moderate match | Resolve cautiously |
| 30-49% | Weak match | Escalate (novel case) |
| 0-29% | No match | Escalate immediately |

## 🚦 Status Indicators

```python
result['decision'] == 'RESOLVE' and result['combined_confidence'] > 0.8
# ✅ Green: High confidence resolution

result['decision'] == 'RESOLVE' and result['combined_confidence'] < 0.7
# ⚠️  Yellow: Cautious resolution, monitor closely

result['decision'] == 'ESCALATE'
# 🔴 Red: Escalation required
```

## 📈 Performance Tips

1. **FAISS Index**: Rebuild weekly to include new KB articles
2. **Database**: Add indexes on `category`, `status`, `reported_at`
3. **Caching**: Cache frequent queries for faster response
4. **Parallel**: Run agents in true parallel (requires async)

## 🔗 Integration Points

### With Ticketing System (Django)
```python
# In Django view
from orchestrator_langgraph import IncidentResolutionOrchestrator

def handle_incident(request):
    alert_text = request.POST['alert']
    parsed = parser.parse_email(alert_text)
    result = orchestrator.process_incident(parsed)
    
    if result['decision'] == 'RESOLVE':
        # Create ticket with resolution steps
        Ticket.objects.create(
            status='IN_PROGRESS',
            resolution_steps=result['resolution']['steps']
        )
    else:
        # Escalate
        Escalation.objects.create(
            reason=result['escalation']['reason']
        )
```

### With Real-time Dashboard
```python
# WebSocket update
result = orchestrator.process_incident(parsed)
websocket.send({
    'type': 'incident_analyzed',
    'decision': result['decision'],
    'confidence': result['combined_confidence'],
    'steps': result['resolution']['steps']
})
```

## 🎯 Next Steps

1. ✅ **You are here**: Multi-agent system working
2. 🔄 **Integrate with parser**: Connect parser → orchestrator
3. 🎨 **Build UI**: Dashboard showing agent decisions
4. 📊 **Add metrics**: Track resolution success rate
5. 🚀 **Deploy**: Production deployment with monitoring

## 📞 Quick Reference

```bash
# Test parser only
python Source_Parser.py

# Test KB agent
python agent_kb_search.py

# Test historical agent
python agent_historical_search.py

# Test logs agent
python agent_logs_search.py

# Test full orchestrator
python orchestrator_langgraph.py

# Rebuild FAISS index
python -c "from agent_kb_search import KnowledgeBaseAgent; KnowledgeBaseAgent().rebuild_index()"
```

---

**Ready to start?** Run `python orchestrator_langgraph.py` 🚀