# MLL Intake Multi-Agent AI Chatbot

A production-ready multi-agent AI chatbot system for IT service request management, built for the Manufacturing, Logistics & Labs (MLL) division.

## 🌟 Features

- **8 Specialized AI Agents** orchestrated through a LangGraph-style state machine
- **Semantic Classification** using a 4-stage pipeline (NER, Ontology, Embeddings, Graph)
- **16,000+ Historical Records** for context-aware responses
- **Streamlit UI** for intuitive chat interaction
- **Anthropic Claude Integration** for natural language understanding

## 📋 System Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    Streamlit UI (app.py)                     │
├─────────────────────────────────────────────────────────────┤
│                   Orchestrator (orchestrator.py)             │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              Multi-Agent State Machine               │    │
│  └─────────────────────────────────────────────────────┘    │
├─────────────────────────────────────────────────────────────┤
│                      8 Specialized Agents                    │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │Supervisor│ │Classifier│ │  Intake  │ │ Network  │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │ Incident │ │  Access  │ │  Status  │ │Knowledge │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
├─────────────────────────────────────────────────────────────┤
│                    Semantic Intelligence                     │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐        │
│  │ Classifier   │ │  Embeddings  │ │ Data Loader  │        │
│  │ (4-stage)    │ │  (Vector)    │ │ (Historical) │        │
│  └──────────────┘ └──────────────┘ └──────────────┘        │
└─────────────────────────────────────────────────────────────┘
```

## 🚀 Quick Start

### 1. Prerequisites

- Python 3.9+
- Anthropic API Key

### 2. Installation

```bash
# Extract the package
unzip mll_intake_chatbot.zip
cd mll_intake

# Install dependencies
pip install -r requirements.txt

# (Optional) For enhanced semantic search
pip install sentence-transformers faiss-cpu
```

### 3. Configuration

Edit `.env` file with your API key:

```env
ANTHROPIC_API_KEY=your_api_key_here
```

### 4. Run the Application

```bash
# Using the run script
chmod +x run.sh
./run.sh

# Or directly with Streamlit
streamlit run app.py
```

### 5. Access the UI

Open your browser to: `http://localhost:8501`

## 📁 Project Structure

```
mll_intake/
├── app.py                  # Streamlit UI
├── orchestrator.py         # Multi-agent orchestrator
├── config.py               # Configuration management
├── requirements.txt        # Python dependencies
├── .env                    # Environment variables (API keys)
├── run.sh                  # Startup script
│
├── agents/                 # 8 Specialized Agents
│   ├── __init__.py
│   ├── base_agent.py       # Base agent class
│   ├── supervisor.py       # Orchestration agent
│   ├── classifier.py       # Request classification
│   ├── intake.py           # Solution Intake handling
│   ├── network.py          # Network/Firewall requests
│   ├── incident.py         # Break-fix incidents
│   ├── access.py           # Access requests
│   ├── status.py           # Ticket status tracking
│   └── knowledge.py        # KB and documentation
│
├── models/                 # Data models
│   ├── __init__.py
│   └── schemas.py          # Pydantic schemas
│
├── utils/                  # Utilities
│   ├── __init__.py
│   ├── data_loader.py      # Historical data loading
│   ├── embeddings.py       # Vector embeddings
│   └── semantic_classifier.py  # 4-stage classification
│
└── data/                   # Historical data
    ├── IRIS_Solution_Intake_requests.xlsx  (3,091 records)
    ├── MLL_JIRA_Epics_extract.xlsx         (7,210 records)
    └── MLL_JIRA_Userstory_extracts.xlsx    (6,551 records)
```

## 🤖 Agent Descriptions

| Agent | Purpose | Key Tools |
|-------|---------|-----------|
| **Supervisor** | Orchestrates conversation flow | route_to_agent, update_state |
| **Classifier** | 4-stage semantic classification | extract_entities, apply_ontology |
| **Intake** | Solution Intake RITM creation | validate_site, create_ritm |
| **Network** | Network/Firewall requests | validate_ritm, create_network_ritm |
| **Incident** | Break-fix issue handling | create_incident, search_known_issues |
| **Access** | Application access (TS ENGAGE) | search_app_ci, create_access_request |
| **Status** | RITM/Jira ticket tracking | lookup_ritm, lookup_jira |
| **Knowledge** | Process documentation | search_kb, search_confluence |

## 🔍 Classification Pipeline

The 4-stage semantic classification:

1. **Named Entity Recognition** - Extracts sites, RITM numbers, Jira keys, components
2. **Ontology Reasoning** - Applies SWRL-like rules for request categorization
3. **Embedding Similarity** - Finds similar historical requests
4. **Graph Context** - Enriches with team patterns and recommendations

## 🎯 Supported Request Types

- **Solution Intake** - New IT service requests
- **Network/Firewall** - LAN/WAN, Firewall MACD, Switch config
- **Incident** - Break-fix for existing systems
- **Access** - Application access (TS ENGAGE-PROD, Jira, etc.)
- **Status** - Check RITM or Jira ticket status

## ⚙️ Configuration Options

Environment variables in `.env`:

```env
# Required
ANTHROPIC_API_KEY=your_key

# Model Settings
ANTHROPIC_MODEL=claude-sonnet-4-20250514
MAX_TOKENS=4096
TEMPERATURE=0.1

# Vector Search (optional)
EMBEDDING_MODEL=all-MiniLM-L6-v2
TOP_K_RESULTS=5
SIMILARITY_THRESHOLD=0.7
```

## 📊 Data Statistics

The system is trained on:
- **3,091** IRIS Solution Intake records
- **7,210** Jira Epics (MLL Project ABFZ)
- **6,551** Jira User Stories
- **16,852** Total searchable documents

## 🔒 Security Notes

⚠️ **IMPORTANT**: Never commit your API key to version control!

The `.env` file containing your API key should be:
- Added to `.gitignore`
- Kept secure and not shared
- Rotated if accidentally exposed

## 🐛 Troubleshooting

### API Key Issues
```bash
# Verify your key is set
cat .env | grep ANTHROPIC_API_KEY
```

### Import Errors
```bash
# Ensure all dependencies are installed
pip install -r requirements.txt --upgrade
```

### Data Loading Issues
```bash
# Verify data files exist
ls -la data/
```

## 📝 License

Internal use only - Proprietary

## 👥 Support

For issues or questions, contact the MLL IT Services team.

---

Built with ❤️ using Claude AI and LangGraph architecture
