PRODUCT_NOTE.md

# ParcelPilot AI Operating System — CalQuity Product Note

## 1. Additional Client Problems Addressed
We tackled **both** problems outlined in the assignment brief to deliver a complete operational solution.

### Problem 1: Proactive Issue Detection (The Ops Radar)
Instead of a purely reactive chatbot, we built a **Proactive Operations Radar** (`app/agent/proactive_detector.py`):
1. **SLA Breach Monitoring**: Real-time evaluation against contract SLAs at the dataset snapshot timestamp (`2026-08-16 11:00 IST`). It successfully detects **TKT-501** (Northstar P1 outage created at 10:30, 15m contract SLA target -> flagged as **15 minutes overdue**).
2. **Security Incident Detection**: Automated scanning for credential and API key exposures (e.g., **TKT-505** public channel posting), generating immediate critical alerts.
3. **Systemic Product Issue Clustering**: Auto-clusters active tickets against known engineering issues (e.g., grouping TKT-502 CSV upload failures into the KI-208 cluster).
4. **Carrier Performance Anomalies**: Identifies unfulfilled carrier pickups across the entire order volume (e.g., **ORD-2002** RoadRunner missed pickup).

### Problem 2: Trust and Reliability (Evidence Anchoring & Conflict Matrix)
To solve the trust problem, we eliminated the "black box" of AI reasoning:
- **Evidence Anchoring UI**: Every answer in the chat is anchored to a specific document, quote, and authority level in a side-by-side split pane.
- **Precedence Conflict Matrix**: A dedicated view showing exactly *why* a decision was made when sources conflict (e.g., explicitly showing the Northstar Signed Agreement at Level 4 overriding the standard SOP v4 at Level 2).

---

## 2. Think Beyond the Immediate Requirements (Future Roadmap)
If we were to continue developing ParcelPilot, we would prioritize the following architectural and product enhancements:

### A. Automated SLA Remediation Engine (High Priority)
* **What**: An asynchronous worker that automatically detects SLA/pickup breaches, calculates the required service credit, applies it to the customer's billing ledger, and emails the customer an apology—all before the customer even files a support ticket.
* **Why**: Support is a cost center. Moving from "reactive resolution" to "proactive remediation" dramatically increases customer satisfaction while reducing ticket volume and human support costs.

### B. Self-Healing Knowledge Graph (Medium Priority)
* **What**: A background system that analyzes the resolution of escalated tickets. If a human agent successfully resolves an issue in a way that contradicts an existing SOP, the system flags the SOP as potentially outdated and drafts a pull request to update the documentation.
* **Why**: Static policies decay quickly in fast-moving startups. Trust in AI systems degrades rapidly if the underlying retrieval corpus is stale.

### C. Multi-Agent Swarm Architecture (Medium Priority)
* **What**: Splitting the monolithic agent into a routing agent that delegates to specialized sub-agents (e.g., a Billing Agent, a Logistics Agent, a Legal/Contract Agent).
* **Why**: As the product scales, different operational domains require entirely different toolsets and security permissions. A swarm architecture prevents context window bloat and allows independent scaling of agent capabilities.

---

## 3. Scope Intentionally Omitted
- **Heavy Vector Database Overhead**: Omitted external vector database dependencies (e.g., Chroma/Qdrant) in favor of an in-memory document authority indexer, maintaining sub-10ms startup latency and zero external service dependencies for this assignment.
- **Production OAuth Server**: Mocked the context selector to allow effortless evaluation of customer vs. internal roles without requiring reviewers to juggle JWTs.

---

## 4. Primary Utility Metric
**First-Contact Resolution Rate with Zero Policy Violations (FCR-ZPV)**:
The percentage of customer support inquiries resolved accurately on first contact *without* violating signed contract overrides, misapplying fees, or exceeding SLA response targets.