README.md

# ParcelPilot AI Customer Support & Operations System

A production-grade AI Customer Support System and Operations Intelligence Platform built for **ParcelPilot** (CalQuity AI Systems Engineer Assessment).

The system features multi-step natural language query reasoning, strict data-layer privacy controls, source authority precedence resolution, human-in-the-loop action confirmations, proactive issue detection, and a modern glassmorphism web interface.

---

## 🌟 Key System Capabilities

1. **Multi-Step Agent Reasoning & Tool Calls**:
   - **Tool 1: Document Search (`tool_document_search`)**: Scoped retrieval over PDF policies, SOPs, product guides, and customer agreements.
   - **Tool 2: Data Lookup & Calculators (`tool_structured_data_lookup`, `tool_calculate_cancellation_fee`, `tool_calculate_service_credit`)**: Relational queries over accounts, orders, and tickets with time-based delay and SLA calculations.
   - **Tool 3: State-Changing Action Drafter (`tool_prepare_state_action`)**: Drafts escalations, ticket updates, tasks, and credit approvals.

2. **Data Privacy & Security Scoping**:
   - Enforced strictly at the **backend Python data/tool layer**.
   - Customer view limits access to the user's specific `account_id`.
   - Hides confidential customer agreements and orders belonging to other accounts.

3. **Source Precedence & Reliability Engine**:
   - Evaluates sources by authority level: `Signed Customer Agreement (Level 4) > Support Policy v3 (Level 3) > SOP v4 / Ops Guide (Level 2) > Historical Tickets (Level 1 Context) > Deprecated Policy v2 (Level 0 Excluded)`.
   - Handles contract overrides (e.g. Northstar $0 cancellation fee override and LumenWorks >4h service credit threshold).

4. **Human-in-the-Loop Action Confirmation**:
   - State-changing actions enter a `PENDING_CONFIRMATION` state, rendering an interactive approval card in the UI.

5. **Problem 1: Proactive Issue Detection Dashboard**:
   - Automatically detects SLA breaches (e.g. TKT-501 Northstar P1 15m breach), security alerts (TKT-505 API key exposure), ticket clusters (KI-208 CSV bulk upload failures), and carrier anomalies (ORD-2002 RoadRunner delay).

---

## 🚀 Quickstart Guide

### 1. Prerequisites & Environment Setup
The project includes a pre-configured Python virtual environment (`venv`).

```bash
# Clone repository and navigate to root
cd /path/to/repository

# Activate virtual environment (or use python executable directly)
source venv/bin/activate
```

### 2. Run Automated Test Suite
Run the comprehensive `pytest` suite validating access control, contract overrides, SLA breaches, and state actions:

```bash
PYTHONPATH=. ./venv/bin/pytest tests/ -v
```

### 3. Launch Web Application Server
Start the FastAPI server:

```bash
./venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

Open your browser at **[http://localhost:8000](http://localhost:8000)**.

---

## 📂 Repository Structure

```
├── app/
│   ├── main.py                  # FastAPI Application Entrypoint
│   ├── config.py                # Reference timestamp (16 Aug 2026 11:00 IST) & Precedence weights
│   ├── core/
│   │   ├── security.py          # Data-layer Security & Access Control
│   │   ├── document_indexer.py  # PDF Document Indexer & Authority Classifier
│   │   └── data_store.py        # Excel Data Store & Time Calculator
│   ├── agent/
│   │   ├── tools.py             # 3 Required Tool Suites
│   │   ├── agent_engine.py      # Multi-Step Reasoning & Trace Generator
│   │   └── proactive_detector.py# Proactive Issue Detection Engine (Problem 1)
│   └── api/
│       ├── routes_chat.py       # Chat & Action Endpoints (/api/chat, /api/confirm)
│       ├── routes_data.py       # Operational Data Endpoints
│       └── routes_proactive.py  # Proactive Insights Endpoint (/api/proactive/insights)
├── frontend/
│   ├── index.html               # Main Glassmorphism UI Layout
│   ├── styles.css               # Modern Dark-Mode Design System
│   └── app.js                   # Interactive UI & Real-Time Trace Renderer
├── data/                        # Data Pack PDFs & Excel Workbook
├── tests/
│   └── test_suite.py            # 100% Passing Pytest Test Suite
├── ARCHITECTURE.md              # Architecture Note
├── PRODUCT_NOTE.md              # Product Note (Problem 1 Selection & Roadmap)
├── AI_TOOL_USAGE.md             # AI Coding Tool Usage
└── requirements.txt             # Dependencies
```

---

## 🧪 Submission Form Details
- **Task Submission Form**: [https://forms.gle/hLGBrDrNRmK7UAbv6](https://forms.gle/hLGBrDrNRmK7UAbv6)