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.