An AI-powered internal support operations agent for CalQuity's ParcelPilot platform.
ParcelPilot helps support staff answer operational questions by combining an LLM with controlled data tools, document retrieval, and deterministic business-rule actions. The agent can retrieve structured account, order, and ticket information, search current SOPs and customer agreements, and evaluate operational decisions such as cancellation eligibility, service credits, SLA targets, bulk-upload limits, and pickup status.
The system is designed around controlled tool use and read-only source data. The LLM is responsible for understanding requests and selecting tools, while business-critical decisions are handled by deterministic application logic. State-changing requests require a human confirmation gate and are not automatically executed.
Support Staff
|
v
Streamlit UI
|
v
FastAPI API
|
v
Agent / LLM
|
+-------------------+-------------------+
| | |
v v v
Data Tools Retrieval Actions
| | |
| | +-- Cancellation
| | +-- Service Credits
| | +-- SLA
| | +-- Bulk Upload / Pickup
| |
| +-- SOPs
| +-- Agreements
| +-- Policies
|
+-- Accounts
+-- Orders
+-- Tickets
|
v
Data Pack
Excel + PDFs
Read-only
- Streamlit UI — provides the interface used by support staff.
- FastAPI — exposes the backend chat API and connects the UI with the agent.
- Agent / LLM — interprets requests, selects the appropriate tool, supplies tool inputs, and presents the resulting information.
- Data Tools — provide controlled access to structured accounts, orders, and tickets.
- Retrieval — searches the supplied SOPs, policies, agreements, and operational documents.
- Actions — apply deterministic business rules to operational questions and return structured decisions.
- Data Pack — contains the read-only Excel operational snapshot and PDF documentation.
- Confirmation Gate — state-changing proposals require explicit staff confirmation and are not automatically executed.
The agent can work with operational data including:
- Accounts
- Orders
- Tickets
- Order and account relationships
- Ticket status and severity
The retrieval layer searches the provided documentation, including:
- Current support policies
- Cancellation and service-credit SOPs
- Product operations and known-issues documentation
- Enterprise customer agreements
Deprecated policy documents are filtered out so that obsolete policy information is not accidentally used when answering operational questions.
Business-rule modules handle operational evaluations such as:
- Cancellation eligibility and applicable fees
- Failed-pickup service-credit eligibility
- First-response SLA targets
- Bulk-upload capability and row limits
- Pickup-status interpretation and known timing risks
The LLM does not independently calculate these business rules. It selects the appropriate action/tool, while the application logic produces the structured decision.
The system separates decision-making from execution.
For requests involving state-changing operations, the agent produces a confirmation-required proposal rather than automatically modifying operational state.
The provided data pack is a read-only snapshot, so there is no direct write-back to the Excel data or operational system.
| Layer | Technology |
|---|---|
| UI | Streamlit |
| Backend API | FastAPI |
| Agent / LLM | Groq using an OpenAI-compatible API |
| Language | Python |
| Structured Data | Excel |
| Knowledge Sources | PDF documents |
| Retrieval | Document retrieval layer |
| Testing | pytest |
ParcelPilot/
│
├── app/
│ ├── actions/
│ │ ├── cancellation.py
│ │ ├── models.py
│ │ ├── policy.py
│ │ ├── product.py
│ │ ├── service.py
│ │ ├── service_credit.py
│ │ └── sla.py
│ │
│ ├── agent/
│ │ ├── agent.py
│ │ ├── executor.py
│ │ ├── openai_tools.py
│ │ └── prompts.py
│ │
│ ├── api/
│ │ └── main.py
│ │
│ ├── data/
│ │ ├── models.py
│ │ └── repository.py
│ │
│ ├── retrieval/
│ │ ├── models.py
│ │ └── retriever.py
│ │
│ ├── tools/
│ │ └── tools.py
│ │
│ └── ui/
│ ├── client.py
│ └── streamlit_app.py
│
├── data/
│ ├── ParcelPilot_Assessment_Data.xlsx
│ └── documents/
│ ├── 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
│
├── docs/
│ ├── architecture.png
│ └── DATA_MODEL.md
│
├── scripts/
├── tests/
├── .env.example
├── .gitignore
├── requirements.txt
└── README.md
Run all commands from the repository root.
python -m venv .venvpython -m venv .venv
source .venv/bin/activate.\.venv\Scripts\Activate.ps1If PowerShell blocks script execution, you can use the virtual environment's Python directly or use Command Prompt.
.venv\Scripts\activate.batsource .venv/bin/activatepip install -r requirements.txtCopy .env.example to .env.
Copy-Item .env.example .envcp .env.example .envSet the required API key:
GROQ_API_KEY=your_groq_api_key_here
GROQ_MODEL=openai/gpt-oss-120bGROQ_MODEL is optional. If omitted, the application uses the project's configured default model.
The application uses two processes:
- FastAPI backend
- Streamlit frontend
Open two terminals at the repository root.
uvicorn app.api.main:app --reloadThe API will run on:
http://127.0.0.1:8000
streamlit run app/ui/streamlit_app.pyOpen the Streamlit URL displayed in the terminal.
The Streamlit client sends chat requests to the FastAPI /chat endpoint.
The backend URL can be configured through the application's configuration options.
Once the application is running, example support questions include:
Can ORD-1001 be cancelled?
Is ORD-1002 eligible for a service credit?
What is the first-response SLA for a P1 ticket for ACCT-001?
Does ACCT-002 have Bulk Upload, and what is the maximum CSV row limit?
What is the pickup status of ORD-1002?
The agent determines which tool or combination of tools is required, retrieves the relevant data or documents, and returns a grounded response with the applicable reasoning and sources.
The agent uses explicit tools rather than allowing the language model to directly access the underlying data sources.
The general flow is:
User Request
|
v
Agent / LLM
|
v
Tool Selection
|
+----------------------+----------------------+
| | |
v v v
Structured Lookup Document Search Action Evaluation
| | |
v v v
Accounts / Orders SOPs / Policies Business Rules
Tickets Agreements Structured Decision
| | |
+----------------------+----------------------+
|
v
Final Response
This separation allows the LLM to focus on request understanding and orchestration while application code handles deterministic business logic.
ParcelPilot intentionally separates LLM orchestration from business logic.
User Request
|
v
LLM interprets request
|
v
Selects controlled tool
|
+--------------------+
| |
v v
Structured Data Document Retrieval
| |
+---------+----------+
|
v
Deterministic Action
|
v
Structured Decision
|
v
Human Confirmation
when required
This prevents the language model from directly modifying operational data or independently implementing critical business rules.
The provided Excel workbook and PDF documents are treated as read-only sources of truth.
The retrieval layer works with the supplied operational documentation and prioritizes current policy information.
The project includes both current and deprecated policy material. Deprecated support-policy documents are explicitly filtered from retrieval results so that obsolete rules are not accidentally used when answering operational questions.
Customer-specific agreements can also be retrieved when determining account-specific terms.
The system can therefore combine:
Current SOP / Policy
+
Customer Agreement
+
Operational Data
|
v
Grounded Operational Decision
ParcelPilot distinguishes between evaluating an operation and actually executing it.
For example, a cancellation request can be evaluated to determine:
- Whether the shipment is eligible for cancellation
- Whether a cancellation fee applies
- Why the decision was reached
However, the evaluation itself does not cancel the shipment.
For state-changing requests, the system creates a confirmation-required proposal. The support staff member can explicitly confirm or cancel the proposal through the UI.
The current assignment data pack does not provide a writable operational system, so the project does not directly mutate the underlying Excel snapshot.
The repository contains automated tests covering the major application layers, including:
- Agent behavior
- API behavior
- Data repository access
- Retrieval
- Tool wrappers
- Business actions
- UI behavior
Run the complete test suite with:
python -m pytest -qResponses are based on the supplied operational data and documentation rather than relying only on general model knowledge.
The agent interacts with data through explicit application tools instead of directly accessing files or implementing arbitrary operations.
Critical operational rules are implemented in Python action modules rather than being left entirely to the LLM.
The provided Excel and PDF data pack is treated as a read-only source.
Potentially state-changing operations require explicit confirmation rather than being automatically executed.
The application separates:
- UI
- API
- Agent orchestration
- Tool access
- Retrieval
- Business actions
- Data access
This makes the individual components easier to test, reason about, and extend.
A recommended demonstration of the project is:
- Start the FastAPI backend.
- Start the Streamlit application.
- Demonstrate a structured-data lookup.
- Demonstrate a policy/document retrieval question.
- Demonstrate a deterministic business-rule evaluation.
- Demonstrate an account-specific SLA or agreement lookup.
- Demonstrate a state-changing request and show the confirmation gate.
- Explain how the LLM selects tools while deterministic application code performs business-rule evaluation.
ParcelPilot demonstrates how an internal support agent can combine an LLM with structured tools, document retrieval, deterministic business logic, and human confirmation to provide reliable operational assistance without giving the language model unrestricted access to business systems.

