# jeeva-004/customer-support-ai-agent architecture

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

- Interactive diagram: https://gitdiagram.com/jeeva-004/customer-support-ai-agent
- Repository: https://github.com/jeeva-004/customer-support-ai-agent

## Overview

AmazonHelp is a retrieval-grounded customer-support agent. Offline, it extracts and pairs brand replies, filters the corpus, and builds an embedding index. Online, an inbound message passes through intent classification and semantic retrieval; escalation rules route unsupported or weak matches to a human, while eligible messages receive a grounded generated reply. The README documents corpus preparation, dense retrieval, a TF-IDF baseline, and evaluation capabilities; the graph focuses on the product runtime and preparation flow. Some preparation links are documented rather than verified in sampled source.

Main entry points: [`src/production/pipeline.py`](https://github.com/jeeva-004/customer-support-ai-agent/blob/main/src/production/pipeline.py) (Message Pipeline), [`src/production/filter_english.py`](https://github.com/jeeva-004/customer-support-ai-agent/blob/main/src/production/filter_english.py) (English Filtering), [`src/production/generate_reply.py`](https://github.com/jeeva-004/customer-support-ai-agent/blob/main/src/production/generate_reply.py) (Reply Generation), [`src/production/retrieve_embeddings.py`](https://github.com/jeeva-004/customer-support-ai-agent/blob/main/src/production/retrieve_embeddings.py) (Semantic Retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_corpus["Support Corpus"]
  node_rawdata["TWCS Dataset"]
  node_brandfilter["Brand Extraction<br/>[filter_brand.py]"]
  node_threadbuild["Tweet Pairing<br/>[build_threads.py]"]
  node_englishfilter["English Filtering<br/>[filter_english.py]"]
  node_preprocess["Text Preprocessing<br/>[preprocess.py]"]
  node_indexbuild["Embedding Index Build"]
  node_embeddingstore[("Dense Embeddings")]
end

subgraph group_runtime["Agent Runtime"]
  node_pipeline["Message Pipeline<br/>[pipeline.py]"]
  node_intent["Intent Classification<br/>[classify_intent.py]"]
  node_escalation["Escalation Rules<br/>[escalate.py]"]
  node_reply["Reply Generation<br/>[generate_reply.py]"]
end

subgraph group_retrieval["Retrieval Methods"]
  node_retriever["Semantic Retrieval"]
  node_tfidf["TF-IDF Baseline<br/>[classify_tfidf.py]"]
end

subgraph group_evaluation["Evaluation"]
end

node_customer(("Customer"))
node_ollama["Local Ollama LLM"]
node_human(("Human Agent"))

node_rawdata -->|"extracts brand replies"| node_brandfilter
node_brandfilter -->|"pairs tweets"| node_threadbuild
node_threadbuild -->|"filters pairs"| node_englishfilter
node_englishfilter -->|"encodes corpus"| node_indexbuild
node_indexbuild -->|"writes vectors"| node_embeddingstore
node_englishfilter -.->|"prepares text"| node_preprocess
node_customer -->|"submits message"| node_pipeline
node_pipeline -->|"classifies"| node_intent
node_intent -->|"fallback inference"| node_ollama
node_pipeline -->|"retrieves cases"| node_retriever
node_retriever -->|"searches vectors"| node_embeddingstore
node_pipeline -->|"checks decision"| node_escalation
node_escalation -->|"routes escalation"| node_human
node_pipeline -->|"generates when eligible"| node_reply
node_reply -->|"retrieves grounding"| node_retriever
node_reply -->|"requests generation"| node_ollama
node_tfidf -->|"uses reference cases"| node_rawdata

click node_brandfilter "https://github.com/jeeva-004/customer-support-ai-agent/blob/main/src/production/filter_brand.py"
click node_threadbuild "https://github.com/jeeva-004/customer-support-ai-agent/blob/main/src/production/build_threads.py"
click node_englishfilter "https://github.com/jeeva-004/customer-support-ai-agent/blob/main/src/production/filter_english.py"
click node_preprocess "https://github.com/jeeva-004/customer-support-ai-agent/blob/main/src/production/preprocess.py"
click node_indexbuild "https://github.com/jeeva-004/customer-support-ai-agent/blob/main/src/production/build_retrieval_index.py"
click node_pipeline "https://github.com/jeeva-004/customer-support-ai-agent/blob/main/src/production/pipeline.py"
click node_intent "https://github.com/jeeva-004/customer-support-ai-agent/blob/main/src/production/classify_intent.py"
click node_retriever "https://github.com/jeeva-004/customer-support-ai-agent/blob/main/src/production/retrieve_embeddings.py"
click node_escalation "https://github.com/jeeva-004/customer-support-ai-agent/blob/main/src/production/escalate.py"
click node_reply "https://github.com/jeeva-004/customer-support-ai-agent/blob/main/src/production/generate_reply.py"
click node_tfidf "https://github.com/jeeva-004/customer-support-ai-agent/blob/main/src/evaluation/classify_tfidf.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_rawdata,node_brandfilter,node_threadbuild,node_englishfilter,node_preprocess,node_indexbuild,node_embeddingstore toneBlue
class node_pipeline,node_intent,node_escalation,node_reply toneAmber
class node_retriever,node_tfidf toneMint
class node_customer,node_ollama,node_human toneIndigo
```

## Components

### Support Corpus

- **TWCS Dataset**
- [Brand Extraction](https://github.com/jeeva-004/customer-support-ai-agent/blob/main/src/production/filter_brand.py): `src/production/filter_brand.py`
- [Tweet Pairing](https://github.com/jeeva-004/customer-support-ai-agent/blob/main/src/production/build_threads.py): `src/production/build_threads.py`
- [English Filtering](https://github.com/jeeva-004/customer-support-ai-agent/blob/main/src/production/filter_english.py): `src/production/filter_english.py`
- [Text Preprocessing](https://github.com/jeeva-004/customer-support-ai-agent/blob/main/src/production/preprocess.py): `src/production/preprocess.py`
- [Embedding Index Build](https://github.com/jeeva-004/customer-support-ai-agent/blob/main/src/production/build_retrieval_index.py): `src/production/build_retrieval_index.py`
- **Dense Embeddings**

### Agent Runtime

- [Message Pipeline](https://github.com/jeeva-004/customer-support-ai-agent/blob/main/src/production/pipeline.py): `src/production/pipeline.py`
- [Intent Classification](https://github.com/jeeva-004/customer-support-ai-agent/blob/main/src/production/classify_intent.py): `src/production/classify_intent.py`
- [Escalation Rules](https://github.com/jeeva-004/customer-support-ai-agent/blob/main/src/production/escalate.py): `src/production/escalate.py`
- [Reply Generation](https://github.com/jeeva-004/customer-support-ai-agent/blob/main/src/production/generate_reply.py): `src/production/generate_reply.py`

### Retrieval Methods

- [Semantic Retrieval](https://github.com/jeeva-004/customer-support-ai-agent/blob/main/src/production/retrieve_embeddings.py): `src/production/retrieve_embeddings.py`
- [TF-IDF Baseline](https://github.com/jeeva-004/customer-support-ai-agent/blob/main/src/evaluation/classify_tfidf.py): `src/evaluation/classify_tfidf.py`

### Other components

- **Customer**
- **Local Ollama LLM**
- **Human Agent**

## Connections

- TWCS Dataset → Brand Extraction: extracts brand replies (evidence: `README.md`)
- Brand Extraction → Tweet Pairing: pairs tweets (evidence: `README.md`)
- Tweet Pairing → English Filtering: filters pairs (evidence: `README.md`)
- English Filtering → Embedding Index Build: encodes corpus (evidence: `README.md`)
- Embedding Index Build → Dense Embeddings: writes vectors (evidence: `README.md`)
- English Filtering → Text Preprocessing: prepares text
- Customer → Message Pipeline: submits message (evidence: `README.md`)
- Message Pipeline → Intent Classification: classifies (evidence: `src/production/pipeline.py`)
- Intent Classification → Local Ollama LLM: fallback inference (evidence: `README.md`)
- Message Pipeline → Semantic Retrieval: retrieves cases (evidence: `src/production/pipeline.py`)
- Semantic Retrieval → Dense Embeddings: searches vectors (evidence: `src/production/retrieve_embeddings.py`)
- Message Pipeline → Escalation Rules: checks decision (evidence: `src/production/pipeline.py`)
- Escalation Rules → Human Agent: routes escalation (evidence: `README.md`)
- Message Pipeline → Reply Generation: generates when eligible (evidence: `src/production/pipeline.py`)
- Reply Generation → Semantic Retrieval: retrieves grounding (evidence: `src/production/generate_reply.py`)
- Reply Generation → Local Ollama LLM: requests generation (evidence: `README.md`)
- TF-IDF Baseline → TWCS Dataset: uses reference cases (evidence: `README.md`)
