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).

# 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:

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

3. Launch Web Application Server

Start the FastAPI server:

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

Open your browser at 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