# 📦 ParcelPilot AI

Intelligent customer-support operations agent built with **LangGraph, MCP, Agentic RAG, and Streamlit**.

ParcelPilot AI can retrieve customer/account/order/ticket information, answer policy questions using hybrid retrieval, apply customer-specific agreements, and enforce confirmation before state-changing operations.

## ✨ Features

- LangGraph-based agent orchestration
- Remote FastMCP server over Streamable HTTP
- 9 MCP tools for customer-support operations
- Hybrid Agentic RAG using Chroma + BM25
- Customer-specific agreement retrieval
- Source authority and document precedence handling
- Structured Excel data for accounts, orders, and tickets
- Mock role-based access control
- Human-in-the-loop confirmation for escalations and follow-ups
- Streamlit interface for interacting with the agent

## 🏗️ Architecture

```text
                    ┌─────────────────────┐
                    │   Streamlit App     │
                    │      app.py         │
                    └──────────┬──────────┘
                               │
                               │ MCP / HTTP
                               ▼
                    ┌─────────────────────┐
                    │   FastMCP Server     │
                    │   mcp_server.py      │
                    └──────────┬──────────┘
                               │
              ┌────────────────┼────────────────┐
              │                │                │
              ▼                ▼                ▼
       Structured Data    Agentic RAG       Security
       Excel workbook    Chroma + BM25     Access checks
              │                │
              └────────────────┼────────────────┘
                               ▼
                    Grounded Tool Results
                               │
                               ▼
                         LangGraph Agent
                               │
                               ▼
                         Final Response
```

## 🔧 MCP Tools

The MCP server exposes:

1. `get_account`
2. `get_order`
3. `get_ticket`
4. `search_knowledge`
5. `search_customer_agreement`
6. `calculate_service_credit`
7. `prepare_escalation`
8. `execute_escalation`
9. `create_followup`

State-changing operations use a confirmation step before execution.

## 📚 Agentic RAG

The retrieval pipeline combines:

```text
User Query
    ↓
Chroma Semantic Retrieval
    +
BM25 Keyword Retrieval
    ↓
Source Authority
    ↓
Customer-Aware Ranking
    ↓
Conflict / Precedence Handling
    ↓
Grounded Evidence
    ↓
LLM Answer
```

Document precedence:

1. Current signed customer agreement
2. Current ParcelPilot policy/SOP
3. Other valid documentation

Deprecated documents are given lower authority and should not override current sources.

## 📁 Project Structure

```text
ParcelPilot/
│
├── app.py
├── mcp_server.py
├── PARCELPILOT.ipynb
├── ParcelPilot_Assessment_Data.xlsx
│
├── 01_Support_Policy_v3_CURRENT.pdf
├── 02_Support_Policy_v2_DEPRECATED.pdf
├── 03_Cancellation_and_Service_Credit_SOP_v4.pdf
├── 04_Product_Operations_Guide_and_Known_Issues.pdf
├── 05_Northstar_Logistics_Enterprise_Agreement.pdf
├── 06_LumenWorks_Service_Agreement.pdf
│
├── pyproject.toml
└── README.md
```

## ⚙️ Setup

### 1. Clone the repository

```bash
git clone <YOUR_GITHUB_REPOSITORY_URL>
cd ParcelPilot
```

### 2. Install dependencies

This project uses `pyproject.toml`.

With `uv`:

```bash
uv sync
```

Or install the required packages using your preferred Python environment.

### 3. Create `.env`

Create a `.env` file in the project root:

```env
OPENAI_API_KEY=your_openai_api_key
PARCELPILOT_USER=support_agent
MCP_HOST=0.0.0.0
MCP_PORT=8000
```

For the Streamlit client, set the MCP URL:

```env
PARCELPILOT_MCP_URL=http://127.0.0.1:8000/mcp
```

Do **not** commit `.env` or API keys to GitHub.

## ▶️ Run the MCP Server

Start the MCP server first:

```bash
uv run python mcp_server.py
```

The server runs at:

```text
http://127.0.0.1:8000/mcp
```

You should see the ParcelPilot MCP server startup information in the terminal.

## ▶️ Run Streamlit

In a second terminal:

```bash
uv run streamlit run app.py
```

Open the Streamlit URL shown in the terminal, normally:

```text
http://localhost:8501
```

## 🔐 Prototype Access Control

This submission includes mock authenticated-user context for demonstrating authorization behavior.

Supported prototype users include:

```text
support_agent
customer_acct_002
customer_acct_003
admin
```

The server uses `PARCELPILOT_USER` to select the current prototype user.

In a production system, this would be replaced with real authentication and authorization, such as identity-provider-issued tokens, tenant/account claims, and server-side permission checks.

## 🧑‍💼 Human-in-the-Loop

For state-changing actions, the agent first prepares the operation.

Example:

```text
User
  ↓
prepare_escalation
  ↓
Preview
  ↓
Explicit confirmation
  ↓
execute_escalation
```

The prototype does not modify persistent operational data during execution.

## 🧪 Example Queries

Try these in the Streamlit application:

```text
What is the current status of ORD-1001?

Show me the account details for ACCT-001.

What is the cancellation fee for a BOOKED shipment?

Can Northstar Logistics cancel a BOOKED shipment without a fee?

What is Northstar Logistics' P1 response target?

What are the failed-pickup service-credit rules for LumenWorks?

What is the current Enterprise P1 response target?

Escalate ticket TKT-501 because the customer needs urgent assistance.
```

For the escalation example, the agent should prepare the escalation and request confirmation before execution.

## 🎯 Product Decisions

The solution focuses on reducing support-agent effort while keeping operational actions controlled.

Key decisions:

- Use MCP to separate the agent from operational tools.
- Keep retrieval inside the MCP server rather than duplicating it in the UI.
- Combine structured data and document retrieval.
- Give customer agreements higher authority than general policies.
- Require explicit confirmation for state-changing actions.
- Include authorization checks at the tool layer rather than relying only on the UI.

## 🚀 Future Improvements

If continuing development, I would prioritize:

1. Production authentication and tenant isolation
2. Persistent audit logs for every tool call and action
3. Real ticket/order updates through production APIs
4. Better retrieval evaluation and automated RAG testing
5. Observability for latency, tool failures, and answer quality
6. Approval workflows for high-impact actions
7. Support analytics and customer-risk detection

## 📊 Success Metric

A primary product metric would be:

**Support resolution time per ticket**

The goal would be to reduce average resolution time while maintaining high accuracy and preventing unauthorized or incorrect operational actions.

## 📌 Submission

### Demo Video

https://drive.google.com/file/d/1gTZlT4bx4oSflD68SWqcN6-uHPtcaT8l/view?usp=sharing

---

Built as a ParcelPilot assessment prototype.