# saranyadharani/uber-support-agent architecture

> Architecture diagram of the GitHub repository saranyadharani/uber-support-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saranyadharani/uber-support-agent
- Repository: https://github.com/saranyadharani/uber-support-agent

## Overview

This repository is an Uber customer-support agent: a customer message enters through the chat UI or pipeline, is classified with intent and risk signals, passes through a deterministic escalation policy, and receives a reply grounded in similar resolved cases. The reply is drafted even when the policy recommends human review. Other substantial capabilities include thread reconstruction and retrieval-index preparation, three comparable intent classifiers, and a golden-set evaluation harness with reply judging and metrics. Some data-preparation and evaluation links are documented rather than shown in excerpts; those edges cite the README.

Main entry points: [`eval/run_eval.py`](https://github.com/saranyadharani/uber-support-agent/blob/main/eval/run_eval.py) (Evaluation runner), [`agent/reply_generator.py`](https://github.com/saranyadharani/uber-support-agent/blob/main/agent/reply_generator.py) (Reply generator), [`pipeline.py`](https://github.com/saranyadharani/uber-support-agent/blob/main/pipeline.py) (Agent pipeline), [`intents/classify_llm.py`](https://github.com/saranyadharani/uber-support-agent/blob/main/intents/classify_llm.py) (LLM classifier)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Customer interaction"]
  node_chat_ui["Chat UI<br/>[index.html]"]
  node_web_api["Flask API<br/>[app.py]"]
end

subgraph group_agent["Agent decisions"]
  node_pipeline["Agent pipeline<br/>[pipeline.py]"]
  node_llm_classifier["LLM classifier<br/>[classify_llm.py]"]
  node_taxonomy["Intent taxonomy<br/>[taxonomy.py]"]
  node_escalation["Escalation policy"]
  node_reply["Reply generator<br/>[reply_generator.py]"]
end

subgraph group_knowledge["Support knowledge"]
  node_retriever["Similar-case retrieval<br/>[retrieve.py]"]
  node_thread_reconstruction["Thread reconstruction"]
  node_index_builder["Retrieval index builder<br/>[build_index.py]"]
  node_case_index[("Resolved-case index")]
end

subgraph group_evaluation["Evaluation"]
  node_keyword_classifier["Keyword baseline"]
  node_knn_classifier["Embedding baseline"]
  node_golden_set["Golden examples<br/>[golden_set.csv]"]
  node_eval_runner["Evaluation runner<br/>[run_eval.py]"]
  node_judge["Reply judge<br/>[llm_judge.py]"]
  node_metrics["Evaluation metrics<br/>[metrics.py]"]
end

node_customer(("Customer"))
node_groq{{"Groq API"}}

node_customer -->|"sends message"| node_chat_ui
node_chat_ui -->|"submits chat"| node_web_api
node_web_api -->|"runs agent"| node_pipeline
node_pipeline -->|"classifies message"| node_llm_classifier
node_pipeline -->|"decides escalation"| node_escalation
node_pipeline -->|"drafts reply"| node_reply
node_llm_classifier -->|"uses categories"| node_taxonomy
node_escalation -->|"reads rules"| node_taxonomy
node_reply -->|"retrieves cases"| node_retriever
node_reply -->|"maps help links"| node_taxonomy
node_retriever -->|"loads vectors and records"| node_case_index
node_thread_reconstruction -.->|"prepares resolved threads"| node_index_builder
node_index_builder -.->|"builds index"| node_case_index
node_llm_classifier -->|"requests classification"| node_groq
node_reply -->|"requests draft"| node_groq
node_eval_runner -->|"reads examples"| node_golden_set
node_eval_runner -->|"runs baseline"| node_keyword_classifier
node_eval_runner -->|"runs baseline"| node_knn_classifier
node_eval_runner -->|"runs classifier"| node_llm_classifier
node_eval_runner -->|"tests policy"| node_escalation
node_eval_runner -->|"evaluates drafts"| node_reply
node_eval_runner -->|"scores replies"| node_judge
node_eval_runner -->|"reports metrics"| node_metrics
node_judge -->|"requests judgment"| node_groq

click node_chat_ui "https://github.com/saranyadharani/uber-support-agent/blob/main/frontend/static/index.html"
click node_web_api "https://github.com/saranyadharani/uber-support-agent/blob/main/frontend/app.py"
click node_pipeline "https://github.com/saranyadharani/uber-support-agent/blob/main/pipeline.py"
click node_llm_classifier "https://github.com/saranyadharani/uber-support-agent/blob/main/intents/classify_llm.py"
click node_taxonomy "https://github.com/saranyadharani/uber-support-agent/blob/main/intents/taxonomy.py"
click node_escalation "https://github.com/saranyadharani/uber-support-agent/blob/main/agent/escalation_policy.py"
click node_reply "https://github.com/saranyadharani/uber-support-agent/blob/main/agent/reply_generator.py"
click node_retriever "https://github.com/saranyadharani/uber-support-agent/blob/main/retrieval/retrieve.py"
click node_thread_reconstruction "https://github.com/saranyadharani/uber-support-agent/blob/main/data/01_reconstruct_threads.py"
click node_index_builder "https://github.com/saranyadharani/uber-support-agent/blob/main/retrieval/build_index.py"
click node_case_index "https://github.com/saranyadharani/uber-support-agent/tree/main/data/processed/Uber_Support_index"
click node_keyword_classifier "https://github.com/saranyadharani/uber-support-agent/blob/main/intents/classify_baseline_keyword.py"
click node_knn_classifier "https://github.com/saranyadharani/uber-support-agent/blob/main/intents/classify_embedding_knn.py"
click node_golden_set "https://github.com/saranyadharani/uber-support-agent/blob/main/eval/golden_set.csv"
click node_eval_runner "https://github.com/saranyadharani/uber-support-agent/blob/main/eval/run_eval.py"
click node_judge "https://github.com/saranyadharani/uber-support-agent/blob/main/eval/llm_judge.py"
click node_metrics "https://github.com/saranyadharani/uber-support-agent/blob/main/eval/metrics.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_chat_ui,node_web_api toneBlue
class node_pipeline,node_llm_classifier,node_taxonomy,node_escalation,node_reply toneAmber
class node_retriever,node_thread_reconstruction,node_index_builder,node_case_index,node_groq toneMint
class node_keyword_classifier,node_knn_classifier,node_golden_set,node_eval_runner,node_judge,node_metrics toneRose
class node_customer toneIndigo
```

## Components

### Customer interaction

- [Chat UI](https://github.com/saranyadharani/uber-support-agent/blob/main/frontend/static/index.html): `frontend/static/index.html`
- [Flask API](https://github.com/saranyadharani/uber-support-agent/blob/main/frontend/app.py): `frontend/app.py`

### Agent decisions

- [Agent pipeline](https://github.com/saranyadharani/uber-support-agent/blob/main/pipeline.py): `pipeline.py`
- [LLM classifier](https://github.com/saranyadharani/uber-support-agent/blob/main/intents/classify_llm.py): `intents/classify_llm.py`
- [Intent taxonomy](https://github.com/saranyadharani/uber-support-agent/blob/main/intents/taxonomy.py): `intents/taxonomy.py`
- [Escalation policy](https://github.com/saranyadharani/uber-support-agent/blob/main/agent/escalation_policy.py): `agent/escalation_policy.py`
- [Reply generator](https://github.com/saranyadharani/uber-support-agent/blob/main/agent/reply_generator.py): `agent/reply_generator.py`

### Support knowledge

- [Similar-case retrieval](https://github.com/saranyadharani/uber-support-agent/blob/main/retrieval/retrieve.py): `retrieval/retrieve.py`
- [Thread reconstruction](https://github.com/saranyadharani/uber-support-agent/blob/main/data/01_reconstruct_threads.py): `data/01_reconstruct_threads.py`
- [Retrieval index builder](https://github.com/saranyadharani/uber-support-agent/blob/main/retrieval/build_index.py): `retrieval/build_index.py`
- [Resolved-case index](https://github.com/saranyadharani/uber-support-agent/tree/main/data/processed/Uber_Support_index): `data/processed/Uber_Support_index`

### Evaluation

- [Keyword baseline](https://github.com/saranyadharani/uber-support-agent/blob/main/intents/classify_baseline_keyword.py): `intents/classify_baseline_keyword.py`
- [Embedding baseline](https://github.com/saranyadharani/uber-support-agent/blob/main/intents/classify_embedding_knn.py): `intents/classify_embedding_knn.py`
- [Golden examples](https://github.com/saranyadharani/uber-support-agent/blob/main/eval/golden_set.csv): `eval/golden_set.csv`
- [Evaluation runner](https://github.com/saranyadharani/uber-support-agent/blob/main/eval/run_eval.py): `eval/run_eval.py`
- [Reply judge](https://github.com/saranyadharani/uber-support-agent/blob/main/eval/llm_judge.py): `eval/llm_judge.py`
- [Evaluation metrics](https://github.com/saranyadharani/uber-support-agent/blob/main/eval/metrics.py): `eval/metrics.py`

### Other components

- **Customer**
- **Groq API**

## Connections

- Customer → Chat UI: sends message (evidence: `README.md`)
- Chat UI → Flask API: submits chat (evidence: `README.md`)
- Flask API → Agent pipeline: runs agent (evidence: `frontend/app.py`)
- Agent pipeline → LLM classifier: classifies message (evidence: `pipeline.py`)
- Agent pipeline → Escalation policy: decides escalation (evidence: `pipeline.py`)
- Agent pipeline → Reply generator: drafts reply (evidence: `pipeline.py`)
- LLM classifier → Intent taxonomy: uses categories (evidence: `intents/classify_llm.py`)
- Escalation policy → Intent taxonomy: reads rules (evidence: `agent/escalation_policy.py`)
- Reply generator → Similar-case retrieval: retrieves cases (evidence: `agent/reply_generator.py`)
- Reply generator → Intent taxonomy: maps help links (evidence: `agent/reply_generator.py`)
- Similar-case retrieval → Resolved-case index: loads vectors and records (evidence: `retrieval/retrieve.py`)
- Thread reconstruction → Retrieval index builder: prepares resolved threads (evidence: `README.md`)
- Retrieval index builder → Resolved-case index: builds index (evidence: `README.md`)
- LLM classifier → Groq API: requests classification (evidence: `intents/classify_llm.py`)
- Reply generator → Groq API: requests draft (evidence: `agent/reply_generator.py`)
- Evaluation runner → Golden examples: reads examples (evidence: `eval/run_eval.py`)
- Evaluation runner → Keyword baseline: runs baseline (evidence: `eval/run_eval.py`)
- Evaluation runner → Embedding baseline: runs baseline (evidence: `eval/run_eval.py`)
- Evaluation runner → LLM classifier: runs classifier (evidence: `eval/run_eval.py`)
- Evaluation runner → Escalation policy: tests policy (evidence: `eval/run_eval.py`)
- Evaluation runner → Reply generator: evaluates drafts (evidence: `eval/run_eval.py`)
- Evaluation runner → Reply judge: scores replies (evidence: `eval/run_eval.py`)
- Evaluation runner → Evaluation metrics: reports metrics (evidence: `eval/run_eval.py`)
- Reply judge → Groq API: requests judgment (evidence: `eval/llm_judge.py`)
