# vardhan2428/customer-support-bot architecture

> Architecture diagram of the GitHub repository vardhan2428/customer-support-bot, 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/vardhan2428/customer-support-bot
- Repository: https://github.com/vardhan2428/customer-support-bot

## Overview

This repository is a Twitter-based AmazonHelp support-agent prototype plus the data and evaluation workflows that support it. A customer message enters the CLI and the end-to-end pipeline coordinates intent classification/resolution, precedent retrieval, escalation assessment, and reply generation. Separate data workflows reconstruct conversations, create annotations and silver labels, train the local classifier, and build retrieval examples; frozen-set evaluation measures the resulting agent. The README documents these capabilities, but several data-workflow implementations were not excerpted, so their internal connections are left unasserted.

Main entry points: [`src/agent/pipeline.py`](https://github.com/vardhan2428/customer-support-bot/blob/main/src/agent/pipeline.py) (Agent pipeline), [`src/agent/agent.py`](https://github.com/vardhan2428/customer-support-bot/blob/main/src/agent/agent.py) (Intent classifier), [`src/reconstruct_amazon_conversations.py`](https://github.com/vardhan2428/customer-support-bot/blob/main/src/reconstruct_amazon_conversations.py) (Conversation reconstruction), [`src/create_annotation_pilot.py`](https://github.com/vardhan2428/customer-support-bot/blob/main/src/create_annotation_pilot.py) (Frozen evaluation set)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Support agent"]
  node_cli["Agent CLI<br/>[agent_cli.py]"]
  node_pipeline["Agent pipeline<br/>[pipeline.py]"]
  node_intent["Intent classifier<br/>[agent.py]"]
  node_resolver["LLM resolver<br/>[llm_resolver.py]"]
  node_retriever["Historical retriever<br/>[retriever.py]"]
  node_corpus[("Precedent corpus<br/>[retriever.py]")]
  node_escalation["Escalation decision<br/>[escalation.py]"]
  node_generator["Reply generator<br/>[generator.py]"]
end

subgraph group_data["Data preparation"]
  node_raw_data["Twitter support data"]
  node_reconstruction["Conversation reconstruction"]
  node_thread_analysis["Thread analysis"]
  node_annotation["Intent annotation"]
  node_silver["Silver labeling"]
  node_training["Classifier training"]
  node_retrieval_build["Retrieval corpus build"]
end

subgraph group_quality["Evaluation"]
  node_golden["Frozen evaluation set"]
  node_agent_eval["Agent evaluation"]
  node_retrieval_eval["Retrieval evaluation"]
end

node_customer(("Customer"))
node_llm_service{{"Groq service"}}

node_customer -->|"enters message"| node_cli
node_cli -->|"runs pipeline"| node_pipeline
node_pipeline -->|"prepares intent"| node_intent
node_intent -->|"resolves low confidence"| node_resolver
node_intent -->|"retrieves precedents"| node_retriever
node_corpus -->|"loads and ranks"| node_retriever
node_pipeline -->|"assesses escalation"| node_escalation
node_pipeline -->|"generates reply"| node_generator
node_resolver -->|"requests completion"| node_llm_service
node_generator -->|"requests completion"| node_llm_service
node_raw_data -.->|"provides tweets"| node_reconstruction
node_reconstruction -.->|"supports analysis"| node_thread_analysis
node_annotation -.->|"creates labeled set"| node_golden
node_silver -.->|"supplies labels"| node_training
node_training -.->|"trains classifier"| node_intent
node_reconstruction -.->|"supports corpus build"| node_retrieval_build
node_retrieval_build -.->|"builds examples"| node_corpus
node_golden -->|"evaluates pipeline"| node_agent_eval
node_golden -->|"evaluates retrieval"| node_retrieval_eval
node_retrieval_eval -->|"queries candidates"| node_retriever

click node_cli "https://github.com/vardhan2428/customer-support-bot/blob/main/src/agent/agent_cli.py"
click node_pipeline "https://github.com/vardhan2428/customer-support-bot/blob/main/src/agent/pipeline.py"
click node_intent "https://github.com/vardhan2428/customer-support-bot/blob/main/src/agent/agent.py"
click node_resolver "https://github.com/vardhan2428/customer-support-bot/blob/main/src/agent/llm_resolver.py"
click node_retriever "https://github.com/vardhan2428/customer-support-bot/blob/main/src/agent/retriever.py"
click node_corpus "https://github.com/vardhan2428/customer-support-bot/blob/main/src/agent/retriever.py"
click node_escalation "https://github.com/vardhan2428/customer-support-bot/blob/main/src/agent/escalation.py"
click node_generator "https://github.com/vardhan2428/customer-support-bot/blob/main/src/agent/generator.py"
click node_reconstruction "https://github.com/vardhan2428/customer-support-bot/blob/main/src/reconstruct_amazon_conversations.py"
click node_thread_analysis "https://github.com/vardhan2428/customer-support-bot/blob/main/src/reconstruct_amazon_threads.py"
click node_annotation "https://github.com/vardhan2428/customer-support-bot/blob/main/src/create_annotation_pilot.py"
click node_silver "https://github.com/vardhan2428/customer-support-bot/blob/main/src/build_silver_corpus.py"
click node_training "https://github.com/vardhan2428/customer-support-bot/blob/main/src/train_silver_intent_classifier.py"
click node_retrieval_build "https://github.com/vardhan2428/customer-support-bot/blob/main/src/build_retrieval_corpus.py"
click node_golden "https://github.com/vardhan2428/customer-support-bot/blob/main/src/create_annotation_pilot.py"
click node_agent_eval "https://github.com/vardhan2428/customer-support-bot/blob/main/evaluation/evaluate_agent_frozen.py"
click node_retrieval_eval "https://github.com/vardhan2428/customer-support-bot/blob/main/evaluation/evaluate_retrieval.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_cli,node_pipeline,node_intent,node_resolver,node_retriever,node_corpus,node_escalation,node_generator toneBlue
class node_raw_data,node_reconstruction,node_thread_analysis,node_annotation,node_silver,node_training,node_retrieval_build toneAmber
class node_golden,node_agent_eval,node_retrieval_eval toneMint
class node_customer,node_llm_service toneIndigo
```

## Components

### Support agent

- [Agent CLI](https://github.com/vardhan2428/customer-support-bot/blob/main/src/agent/agent_cli.py): `src/agent/agent_cli.py`
- [Agent pipeline](https://github.com/vardhan2428/customer-support-bot/blob/main/src/agent/pipeline.py): `src/agent/pipeline.py`
- [Intent classifier](https://github.com/vardhan2428/customer-support-bot/blob/main/src/agent/agent.py): `src/agent/agent.py`
- [LLM resolver](https://github.com/vardhan2428/customer-support-bot/blob/main/src/agent/llm_resolver.py): `src/agent/llm_resolver.py`
- [Historical retriever](https://github.com/vardhan2428/customer-support-bot/blob/main/src/agent/retriever.py): `src/agent/retriever.py`
- [Precedent corpus](https://github.com/vardhan2428/customer-support-bot/blob/main/src/agent/retriever.py): `src/agent/retriever.py`
- [Escalation decision](https://github.com/vardhan2428/customer-support-bot/blob/main/src/agent/escalation.py): `src/agent/escalation.py`
- [Reply generator](https://github.com/vardhan2428/customer-support-bot/blob/main/src/agent/generator.py): `src/agent/generator.py`

### Data preparation

- **Twitter support data**
- [Conversation reconstruction](https://github.com/vardhan2428/customer-support-bot/blob/main/src/reconstruct_amazon_conversations.py): `src/reconstruct_amazon_conversations.py`
- [Thread analysis](https://github.com/vardhan2428/customer-support-bot/blob/main/src/reconstruct_amazon_threads.py): `src/reconstruct_amazon_threads.py`
- [Intent annotation](https://github.com/vardhan2428/customer-support-bot/blob/main/src/create_annotation_pilot.py): `src/create_annotation_pilot.py`
- [Silver labeling](https://github.com/vardhan2428/customer-support-bot/blob/main/src/build_silver_corpus.py): `src/build_silver_corpus.py`
- [Classifier training](https://github.com/vardhan2428/customer-support-bot/blob/main/src/train_silver_intent_classifier.py): `src/train_silver_intent_classifier.py`
- [Retrieval corpus build](https://github.com/vardhan2428/customer-support-bot/blob/main/src/build_retrieval_corpus.py): `src/build_retrieval_corpus.py`

### Evaluation

- [Frozen evaluation set](https://github.com/vardhan2428/customer-support-bot/blob/main/src/create_annotation_pilot.py): `src/create_annotation_pilot.py`
- [Agent evaluation](https://github.com/vardhan2428/customer-support-bot/blob/main/evaluation/evaluate_agent_frozen.py): `evaluation/evaluate_agent_frozen.py`
- [Retrieval evaluation](https://github.com/vardhan2428/customer-support-bot/blob/main/evaluation/evaluate_retrieval.py): `evaluation/evaluate_retrieval.py`

### Other components

- **Customer**
- **Groq service**

## Connections

- Customer → Agent CLI: enters message (evidence: `src/agent/agent_cli.py`)
- Agent CLI → Agent pipeline: runs pipeline (evidence: `src/agent/agent_cli.py`)
- Agent pipeline → Intent classifier: prepares intent (evidence: `src/agent/pipeline.py`)
- Intent classifier → LLM resolver: resolves low confidence (evidence: `src/agent/agent.py`)
- Intent classifier → Historical retriever: retrieves precedents (evidence: `src/agent/agent.py`)
- Precedent corpus → Historical retriever: loads and ranks (evidence: `src/agent/retriever.py`)
- Agent pipeline → Escalation decision: assesses escalation (evidence: `src/agent/pipeline.py`)
- Agent pipeline → Reply generator: generates reply (evidence: `src/agent/pipeline.py`)
- LLM resolver → Groq service: requests completion (evidence: `src/agent/llm_resolver.py`)
- Reply generator → Groq service: requests completion (evidence: `src/agent/generator.py`)
- Twitter support data → Conversation reconstruction: provides tweets
- Conversation reconstruction → Thread analysis: supports analysis
- Intent annotation → Frozen evaluation set: creates labeled set (evidence: `src/create_annotation_pilot.py`)
- Silver labeling → Classifier training: supplies labels
- Classifier training → Intent classifier: trains classifier
- Conversation reconstruction → Retrieval corpus build: supports corpus build
- Retrieval corpus build → Precedent corpus: builds examples
- Frozen evaluation set → Agent evaluation: evaluates pipeline (evidence: `evaluation/evaluate_agent_frozen.py`)
- Frozen evaluation set → Retrieval evaluation: evaluates retrieval (evidence: `evaluation/evaluate_retrieval.py`)
- Retrieval evaluation → Historical retriever: queries candidates (evidence: `evaluation/evaluate_retrieval.py`)
