# lamhotsiagian/retail_rag_sim architecture

> Architecture diagram of the GitHub repository lamhotsiagian/retail_rag_sim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lamhotsiagian/retail_rag_sim
- Repository: https://github.com/lamhotsiagian/retail_rag_sim

## Overview

This repository is an OpenAI-backed retail customer-service RAG application. A user asks in the Streamlit UI; the LangGraph workflow plans the request, executes model-selected retrieval or business tools, then verifies grounding and confidence before returning an answer with citations. Separate capabilities include KB indexing, local/hosted evaluation, and optional experiment logging. The graph follows the sampled call sites and README; the API tool’s HTTP wiring is not shown in the excerpts, so that connection is marked unverified.

Main entry points: [`src/retail_rag_sim/agents/graph.py`](https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/agents/graph.py) (Agent workflow), [`src/retail_rag_sim/eval/run_langsmith_eval.py`](https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/eval/run_langsmith_eval.py) (LangSmith evaluation), [`src/retail_rag_sim/retrieval/retriever.py`](https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/retrieval/retriever.py) (Hybrid retrieval), [`ui/app.py`](https://github.com/lamhotsiagian/retail_rag_sim/blob/main/ui/app.py) (Chat UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Conversation workflow"]
  node_ui["Chat UI<br/>[app.py]"]
  node_workflow["Agent workflow<br/>[graph.py]"]
  node_prompts["Agent prompts<br/>[prompts.py]"]
  node_llm["OpenAI models<br/>[factory.py]"]
end

subgraph group_knowledge["Knowledge retrieval"]
  node_ingest["KB ingestion<br/>[ingest.py]"]
  node_hybrid["Hybrid retrieval<br/>[retriever.py]"]
  node_reranker["Cross-encoder reranker<br/>[reranker.py]"]
  node_chroma[("Chroma index")]
end

subgraph group_business["Business tools"]
  node_dbtool["SQL query tool<br/>[db.py]"]
  node_sqlite[("SQLite database")]
  node_apitool["Retail API tool<br/>[api.py]"]
  node_api["Dummy tools API<br/>[dummy_api.py]"]
  node_email["Email tool<br/>[email.py]"]
end

subgraph group_quality["Evaluation and observability"]
  node_local_eval["Local evaluation<br/>[run_local_eval.py]"]
  node_hosted_eval["LangSmith evaluation"]
  node_metrics["Evaluation metrics<br/>[metrics.py]"]
  node_observability["Experiment logging<br/>[observability.py]"]
end

node_customer(("Customer"))
node_smtp["Gmail SMTP"]
node_langsmith["LangSmith"]

node_customer -->|"asks"| node_ui
node_ui -->|"calls chat"| node_workflow
node_workflow -->|"returns answer"| node_ui
node_workflow -->|"uses instructions"| node_prompts
node_workflow -->|"gets models"| node_llm
node_workflow -->|"retrieves documents"| node_hybrid
node_workflow -->|"reranks results"| node_reranker
node_ingest -->|"gets embeddings"| node_llm
node_ingest -->|"writes chunks"| node_chroma
node_hybrid -->|"gets embeddings"| node_llm
node_hybrid -->|"reads index"| node_chroma
node_workflow -->|"runs queries"| node_dbtool
node_dbtool -->|"reads rows"| node_sqlite
node_workflow -->|"calls tool"| node_apitool
node_apitool -.->|"requests endpoints"| node_api
node_workflow -->|"sends messages"| node_email
node_email -.->|"sends email"| node_smtp
node_local_eval -->|"evaluates answers"| node_workflow
node_local_eval -->|"scores outputs"| node_metrics
node_hosted_eval -->|"evaluates answers"| node_workflow
node_hosted_eval -->|"scores outputs"| node_metrics
node_hosted_eval -->|"submits evaluation"| node_langsmith
node_hosted_eval -->|"logs summaries"| node_observability

click node_ui "https://github.com/lamhotsiagian/retail_rag_sim/blob/main/ui/app.py"
click node_workflow "https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/agents/graph.py"
click node_prompts "https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/agents/prompts.py"
click node_llm "https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/llms/factory.py"
click node_ingest "https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/retrieval/ingest.py"
click node_hybrid "https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/retrieval/retriever.py"
click node_reranker "https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/retrieval/reranker.py"
click node_dbtool "https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/tools/db.py"
click node_apitool "https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/tools/api.py"
click node_api "https://github.com/lamhotsiagian/retail_rag_sim/blob/main/api/dummy_api.py"
click node_email "https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/tools/email.py"
click node_local_eval "https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/eval/run_local_eval.py"
click node_hosted_eval "https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/eval/run_langsmith_eval.py"
click node_metrics "https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/eval/metrics.py"
click node_observability "https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/ops/observability.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_ui,node_workflow,node_prompts,node_llm toneBlue
class node_ingest,node_hybrid,node_reranker,node_chroma toneAmber
class node_dbtool,node_sqlite,node_apitool,node_api,node_email toneMint
class node_local_eval,node_hosted_eval,node_metrics,node_observability toneRose
class node_customer,node_smtp,node_langsmith toneIndigo
```

## Components

### Conversation workflow

- [Chat UI](https://github.com/lamhotsiagian/retail_rag_sim/blob/main/ui/app.py): `ui/app.py`
- [Agent workflow](https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/agents/graph.py): `src/retail_rag_sim/agents/graph.py`
- [Agent prompts](https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/agents/prompts.py): `src/retail_rag_sim/agents/prompts.py`
- [OpenAI models](https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/llms/factory.py): `src/retail_rag_sim/llms/factory.py`

### Knowledge retrieval

- [KB ingestion](https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/retrieval/ingest.py): `src/retail_rag_sim/retrieval/ingest.py`
- [Hybrid retrieval](https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/retrieval/retriever.py): `src/retail_rag_sim/retrieval/retriever.py`
- [Cross-encoder reranker](https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/retrieval/reranker.py): `src/retail_rag_sim/retrieval/reranker.py`
- **Chroma index**

### Business tools

- [SQL query tool](https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/tools/db.py): `src/retail_rag_sim/tools/db.py`
- **SQLite database**
- [Retail API tool](https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/tools/api.py): `src/retail_rag_sim/tools/api.py`
- [Dummy tools API](https://github.com/lamhotsiagian/retail_rag_sim/blob/main/api/dummy_api.py): `api/dummy_api.py`
- [Email tool](https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/tools/email.py): `src/retail_rag_sim/tools/email.py`

### Evaluation and observability

- [Local evaluation](https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/eval/run_local_eval.py): `src/retail_rag_sim/eval/run_local_eval.py`
- [LangSmith evaluation](https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/eval/run_langsmith_eval.py): `src/retail_rag_sim/eval/run_langsmith_eval.py`
- [Evaluation metrics](https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/eval/metrics.py): `src/retail_rag_sim/eval/metrics.py`
- [Experiment logging](https://github.com/lamhotsiagian/retail_rag_sim/blob/main/src/retail_rag_sim/ops/observability.py): `src/retail_rag_sim/ops/observability.py`

### Other components

- **Customer**
- **Gmail SMTP**
- **LangSmith**

## Connections

- Customer → Chat UI: asks (evidence: `ui/app.py`)
- Chat UI → Agent workflow: calls chat (evidence: `ui/app.py`)
- Agent workflow → Chat UI: returns answer (evidence: `ui/app.py`)
- Agent workflow → Agent prompts: uses instructions (evidence: `src/retail_rag_sim/agents/graph.py`)
- Agent workflow → OpenAI models: gets models (evidence: `src/retail_rag_sim/agents/graph.py`)
- Agent workflow → Hybrid retrieval: retrieves documents (evidence: `src/retail_rag_sim/agents/graph.py`)
- Agent workflow → Cross-encoder reranker: reranks results (evidence: `src/retail_rag_sim/agents/graph.py`)
- KB ingestion → OpenAI models: gets embeddings (evidence: `src/retail_rag_sim/retrieval/ingest.py`)
- KB ingestion → Chroma index: writes chunks (evidence: `src/retail_rag_sim/retrieval/ingest.py`)
- Hybrid retrieval → OpenAI models: gets embeddings (evidence: `src/retail_rag_sim/retrieval/retriever.py`)
- Hybrid retrieval → Chroma index: reads index (evidence: `src/retail_rag_sim/retrieval/retriever.py`)
- Agent workflow → SQL query tool: runs queries (evidence: `src/retail_rag_sim/agents/graph.py`)
- SQL query tool → SQLite database: reads rows (evidence: `src/retail_rag_sim/tools/db.py`)
- Agent workflow → Retail API tool: calls tool (evidence: `src/retail_rag_sim/agents/graph.py`)
- Retail API tool → Dummy tools API: requests endpoints
- Agent workflow → Email tool: sends messages (evidence: `src/retail_rag_sim/agents/graph.py`)
- Email tool → Gmail SMTP: sends email
- Local evaluation → Agent workflow: evaluates answers (evidence: `src/retail_rag_sim/eval/run_local_eval.py`)
- Local evaluation → Evaluation metrics: scores outputs (evidence: `src/retail_rag_sim/eval/run_local_eval.py`)
- LangSmith evaluation → Agent workflow: evaluates answers (evidence: `src/retail_rag_sim/eval/run_langsmith_eval.py`)
- LangSmith evaluation → Evaluation metrics: scores outputs (evidence: `src/retail_rag_sim/eval/run_langsmith_eval.py`)
- LangSmith evaluation → LangSmith: submits evaluation (evidence: `src/retail_rag_sim/eval/run_langsmith_eval.py`)
- LangSmith evaluation → Experiment logging: logs summaries (evidence: `src/retail_rag_sim/eval/run_langsmith_eval.py`)