Grounded retrieval
Responses are designed around retrieved business knowledge rather than unsupported generation.
Engineering case study
SupportPilot AI
A controlled AI support workflow combining knowledge retrieval, order context and human escalation.
01
Business problem
The workflow before automation.
Support work often requires agents to move repeatedly between the customer request, internal knowledge and operational context before deciding how to respond. The simulated SupportPilot AI scenario explores how AI can assist that workflow without treating every generated response as safe to send automatically.
- 01
Read and classify the incoming customer request.
- 02
Search internal knowledge for relevant guidance.
- 03
Look up customer or order context.
- 04
Determine whether the available information supports a response.
- 05
Escalate uncertain, sensitive or unsupported cases.
- 06
Track the resulting support action.
02
Automated solution
A controlled system around the business process.
SupportPilot AI combines the incoming request with retrieved business knowledge and customer or order context, then applies confidence and safety boundaries before producing a controlled response or escalating the case to a human.
Reduce repetitive information gathering.
Ground support assistance in approved business context.
Keep uncertain cases behind escalation boundaries.
Improve visibility into AI-assisted support decisions.
03
Architecture
System architecture at a glance.
This structured view establishes the architecture narrative. Final portfolio-safe diagrams are added during the evidence pass.
- 01
Next.js support workspace
Customer chat, authenticated agent queue, ticket workspace, decision evidence, and operations dashboard.
- 02
FastAPI support core
Owns ticket processing, classification, safety policy, retrieval, grounded generation, commerce access, audit state, and delivery contracts.
- 03
Supabase PostgreSQL + pgvector
Stores users, roles, tickets, messages, published knowledge, vector embeddings, AI-run evidence, and audit events.
- 04
FastEmbed retrieval
Local BAAI/bge-small-en-v1.5 embeddings power published-knowledge similarity retrieval through pgvector.
- 05
Ollama generation
Local qwen3:1.7b generates grounded drafts only after evidence and policy gates permit generation.
- 06
Read-only commerce adapter
A Shopify-style synthetic commerce service exposes scoped customer, order, fulfillment, and product facts without write-capable actions.
- 07
n8n + Gmail
n8n normalizes authenticated Gmail intake and coordinates controlled outbound email delivery.
- 08
Safety + observability layer
Restricted actions, identity checks, grounding requirements, idempotency, failure persistence, and audit events remain application-controlled.
04
Workflow
How information moves through the system.
01
Interpret
Evaluate the incoming support request and relevant operational signals.
02
Retrieve
Find business knowledge relevant to the customer request.
03
Contextualize
Combine retrieved knowledge with customer or order information when appropriate.
04
Evaluate
Apply confidence, access and safety boundaries before allowing an AI-assisted outcome.
05
Respond or escalate
Use the available context when sufficiently supported, otherwise preserve human control.
05
Engineering
The parts that make the automation dependable.
Operational context
Customer and order information can inform the workflow alongside knowledge retrieval.
Low-confidence handling
Insufficient support for an answer becomes an explicit workflow state rather than a reason to guess.
Escalation logic
Human escalation is treated as a normal system outcome rather than a failure of the automation.
06
Controls
Security, reliability and human control.
01
Access boundaries
Business context is designed around explicit access control rather than unrestricted retrieval.
02
Grounding requirement
Available evidence and retrieved knowledge influence whether the system should respond.
03
Human escalation
Cases outside safe automation boundaries can be routed to an operator.
04
Observability
Support decisions and workflow status are designed to remain inspectable.
07
Evidence
Proof will come from the completed repository.
Backend regression
111 / 111
Complete Pytest regression passed; database authorization also passed 9/9 pgTAP checks.
RAG top-1
91.7%
Measured across 12 retrieval cases; top-3 retrieval, evidence decisions, and grounding contracts reached 100%.
Safety evaluation
72 / 72
Deterministic commerce and policy suite passed with zero unsafe auto-responses and zero cross-customer gate violations.
Final evidence also includes 33/33 adversarial safety cases, passing controlled-failure reliability probes, and a 5.97 second local p95 for the full grounded RAG decision path. The latency figure is a local portfolio measurement, not a production SLA. The backend regression completed with one known Starlette/httpx deprecation warning.
Operations dashboard surfaces queue health, review load, priority mix, channel activity, escalation causes, decision outcomes, and delivery status.
Explainable AI decision state showing medium evidence, a safe draft, and automatic response blocked because confidence was not high enough.
Ranked retrieval evidence from published support knowledge is exposed to staff rather than hidden inside model output.
Identity-aware, read-only commerce context gives the support workflow verified order facts without exposing write-capable commerce actions.
Restricted commerce request routed to human review with automatic response blocked and the restricted-action reason preserved for the agent.
Authenticated support queue showing ticket state, priority, intent, channel, assignee, and review status across synthetic support cases.
Agent ticket workspace combining conversation history with reply and internal-note controls so support work stays inside one operational surface.
Redacted Gmail smoke-test proof showing the controlled outbound email path exercised end to end with synthetic portfolio content.
08
Implementation
Technology and current boundaries.
Technology
Next.jsReactTypeScriptFastAPIPython 3.12Supabase PostgreSQLSupabase Authpgvectorn8nFastEmbedBAAI/bge-small-en-v1.5Ollamaqwen3:1.7bGmailDocker Compose
Limitations
SupportPilot AI is a synthetic portfolio implementation rather than a live help-desk deployment. Irreversible commerce operations such as refunds, cancellations, address changes, payments, replacement authorization and policy exceptions are intentionally absent. AUTO_RESPOND represents decision eligibility rather than an unrestricted unattended-send guarantee. Prompt-injection defenses are deterministic and bounded rather than universal jailbreak protection. The local embedding implementation adapts a 384-dimensional model to the project's 1536-dimensional vector contract, Gmail/n8n OAuth remains environment-specific, email attachment handling is MVP-level, Slack escalation remains deferred, and the knowledge-authoring interface is not a finished administration product. Reported performance is local test-environment evidence rather than a production SLA.
09
Client relevance
What this project proves.
This project demonstrates the ability to build AI-assisted support around grounding, business context, access boundaries, escalation and operational control rather than unconstrained generation.
Project resources
View GitHub repositoryDemo video coming before portfolio launch.