Spaces:
Configuration error
Configuration error
| # 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) | |