Support-Pilot: The AI Support Agent That Knows When to Hand Off

A grounded triage system for customer email, where retrieval, policy, and human review matter more than flashy automation.

7 min read • View on GitHub • More from Manjiswari

A wide editorial scene shows a support desk split into three lanes. Incoming emails stack up on the left, a judgment station in the center stamps cases as Auto Resolve, Review Required, or Escalate, and a human operator reviews the flagged cases on the right beside a policy ledger and reference files. The image explains that the system is built around controlled triage, not blind automation. — Support-Pilot turns inbox chaos into a routed decision, with human review built into the workflow.

Key Takeaways

Support-Pilot’s real product idea is triage, not autopilot, because its core decision is when to defer to a human.
The decision engine is grounded by policy text and retrieval, which makes its outputs structured rather than improvisational.
Thread reconstruction is the operational glue, because Gmail metadata turns scattered replies into a single support case.
The repo points toward a hybrid support system where AI drafts and routes, but humans keep authority on edge cases.

Why review_required is the real feature

Most AI support tools obsess over the reply. Support-Pilot obsesses over the decision. That is the difference between a chatbot and a triage system.

Its core schema does not just ask what to say. It asks whether the case should be auto-resolved, sent to review, or escalated. That sounds modest, but it is the kind of restraint production support teams actually need.

The hidden trick is not the model. It is the routing logic that keeps uncertain cases in human hands.

A close-up diagram-like editorial scene shows three fragments of a customer message being stitched together: subject tags, a thread ID tag, and an In-Reply-To header ribbon. They converge into one ticket card that then feeds a policy-backed decision box. The image explains that message identity resolution is what makes the workflow operationally real. — Support-Pilot treats message identity as a first-class problem, not a bookkeeping detail.

How the decision engine stays grounded

The interesting file is ai_service.py. It does not just generate a draft response. It performs structured analysis and returns fields like sentiment, severity, and ai_decision.

That matters because the model is not acting alone. It is given company policy from policy.txt and relevant retrieved context from Pinecone before it decides what to do. The result is a system that can answer, but also knows when not to.

# Simplified shape of the decision layer
result = {
    "sentiment": "negative",
    "severity": "high",
    "ai_decision": "review_required",
    "draft_reply": "...",
    "reasoning": "Policy conflict or missing context"
}

# Policy and retrieval are injected before the model decides
context = search_documents(query)
policy = load_policy_text()
analysis = analyze_incoming_email(email, context, policy)

That architecture changes the product from a text generator into a policy-aware control system. The model is still important, but it is no longer the only authority in the loop.

The knowledge base is split across two systems on purpose

The repo does not treat vector search as a magic box. services.py chunks documents, stores metadata, and keeps Pinecone and PostgreSQL synchronized so the knowledge base can be queried and administered at the same time.

Layer	What it does	Why it matters
Pinecone	Vector retrieval for relevant chunks	Finds policy and knowledge fast
PostgreSQL	Administrative and relational tracking	Keeps documents and tickets auditable
LangChain splitter	Breaks documents into usable chunks	Improves retrieval quality without manual slicing
Health checks	Verifies Pinecone and database availability	Makes the system operational, not just clever

That split is deliberate. Pinecone helps with semantic recall. PostgreSQL helps with the boring but essential truth of what was stored, when, and under which metadata.

The email pipeline is the hidden hard part

AI demos often stop at the inbox metaphor. This repo goes deeper. email_service.py tries to resolve the same ticket across subject tags, Gmail thread IDs, and In-Reply-To headers.

That is the operational glue. Without thread resolution, replies fragment, duplicates multiply, and the support team loses trust in the automation. Support-Pilot is careful because email is messy in ways chatbots usually ignore.

The operator experience matters as much as the model

The UI tells the same story as the backend. The glassmorphic dashboard and the newer React frontend both point to a supervised workflow, not a hands-off agent.

Operators need drafts, overrides, uploads, and exception handling. The interface is there to keep a human in charge when the model is uncertain, and that is exactly the right move for customer support.

Support-Pilot is building toward managed delegation

The best comparison is not AI versus manual support. It is auto-reply versus triage. A single-output bot tries to sound correct. Support-Pilot tries to route risk well.

Pattern	Strength	Weakness
Auto-reply bot	Fast responses	Can be confidently wrong
Manual inbox workflow	High control	Slow and expensive
Support-Pilot triage	Policy-grounded delegation	Still needs human review for edge cases

That is why the repo’s architectural signal matters. The move from Jinja2 toward React suggests a system becoming more operational, more modular, and more usable for the people who actually handle support load.

Support-Pilot is not trying to replace support staff. It is trying to give them a safer queue, cleaner context, and fewer bad decisions to unwind.