# rameshucs06/subtitle_rag architecture

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

- Interactive diagram: https://gitdiagram.com/rameshucs06/subtitle_rag
- Repository: https://github.com/rameshucs06/subtitle_rag

## Overview

Bilingual Subtitle Search & Q&A is a Streamlit front end over a FastAPI service for English/Telugu subtitle search, cited answers, episode summaries, and monitoring. The main path is user → UI → API → retrieval and (for answers) RAG generation; Telugu questions are translated for English retrieval. Cleaning and chunking, evaluation, and monitoring are distinct supporting capabilities. The README documents the index and product capabilities; links not shown in the excerpts or source references are omitted rather than inferred.

Main entry points: [`api/main.py`](https://github.com/rameshucs06/subtitle_rag/blob/main/api/main.py) (HTTP API), [`src/subtitle_rag/retrieval/search.py`](https://github.com/rameshucs06/subtitle_rag/blob/main/src/subtitle_rag/retrieval/search.py) (Hybrid retriever), [`src/subtitle_rag/generation/rag.py`](https://github.com/rameshucs06/subtitle_rag/blob/main/src/subtitle_rag/generation/rag.py) (RAG workflow), [`src/subtitle_rag/generation/llm.py`](https://github.com/rameshucs06/subtitle_rag/blob/main/src/subtitle_rag/generation/llm.py) (Gemini wrapper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_streamlit["Ask UI<br/>[app.py]"]
  node_inspect["Inspect page<br/>[1_Inspect.py]"]
  node_summarize_page["Summarize page<br/>[2_Summarize.py]"]
  node_monitor_page["Monitor page<br/>[3_Monitor.py]"]
  node_api_client["HTTP client<br/>[api_client.py]"]
end

subgraph group_service["API orchestration"]
  node_api["HTTP API<br/>[main.py]"]
  node_config["Configuration<br/>[config.py]"]
end

subgraph group_retrieval["Search and corpus"]
  node_retriever["Hybrid retriever<br/>[search.py]"]
  node_bm25["BM25 index<br/>[bm25.py]"]
  node_vector_store[("Chroma index")]
  node_chunks[("Subtitle chunks")]
  node_cleaning["Subtitle cleaning<br/>[cleaning.py]"]
  node_chunking["Chunk creation<br/>[chunking.py]"]
end

subgraph group_generation["Answer generation"]
  node_rag["RAG workflow<br/>[rag.py]"]
  node_prompts["Prompt templates<br/>[prompts.py]"]
  node_summarizer["Episode summarizer<br/>[summarizer.py]"]
  node_llm["Gemini wrapper<br/>[llm.py]"]
end

subgraph group_operations["Monitoring and evaluation"]
  node_monitoring["Request monitoring<br/>[monitoring.py]"]
  node_request_log[("Request log")]
  node_retrieval_metrics["Retrieval metrics<br/>[metrics.py]"]
  node_answer_eval["Answer evaluation<br/>[answer_eval.py]"]
  node_eval_data[("Evaluation questions<br/>[eval_questions.csv]")]
end

node_user(("User"))
node_gemini{{"Gemini service"}}

node_user -->|"asks or browses"| node_streamlit
node_streamlit -->|"calls"| node_api_client
node_inspect -->|"calls"| node_api_client
node_summarize_page -->|"calls"| node_api_client
node_monitor_page -->|"calls"| node_api_client
node_api_client -->|"sends HTTP requests"| node_api
node_api -->|"searches"| node_retriever
node_api -->|"asks"| node_rag
node_api -->|"summarizes"| node_summarizer
node_api -->|"records and reads events"| node_monitoring
node_retriever -->|"scores keywords"| node_bm25
node_retriever -->|"queries and fetches"| node_vector_store
node_retriever -->|"loads chunk data"| node_chunks
node_rag -->|"retrieves passages"| node_retriever
node_rag -->|"builds prompts"| node_prompts
node_rag -->|"generates and translates"| node_llm
node_summarizer -->|"builds summary prompts"| node_prompts
node_summarizer -->|"requests summaries"| node_llm
node_llm -->|"calls"| node_gemini
node_llm -->|"updates counters"| node_monitoring
node_monitoring -->|"writes and reads"| node_request_log
node_monitor_page -->|"requests metrics"| node_api
node_answer_eval -->|"uses hit ranking"| node_retrieval_metrics
node_answer_eval -->|"checks citations"| node_rag
node_answer_eval -->|"judges answers"| node_llm
node_eval_data -.->|"evaluates against"| node_answer_eval

click node_streamlit "https://github.com/rameshucs06/subtitle_rag/blob/main/ui/app.py"
click node_inspect "https://github.com/rameshucs06/subtitle_rag/blob/main/ui/pages/1_Inspect.py"
click node_summarize_page "https://github.com/rameshucs06/subtitle_rag/blob/main/ui/pages/2_Summarize.py"
click node_monitor_page "https://github.com/rameshucs06/subtitle_rag/blob/main/ui/pages/3_Monitor.py"
click node_api_client "https://github.com/rameshucs06/subtitle_rag/blob/main/ui/api_client.py"
click node_api "https://github.com/rameshucs06/subtitle_rag/blob/main/api/main.py"
click node_config "https://github.com/rameshucs06/subtitle_rag/blob/main/src/subtitle_rag/config.py"
click node_retriever "https://github.com/rameshucs06/subtitle_rag/blob/main/src/subtitle_rag/retrieval/search.py"
click node_bm25 "https://github.com/rameshucs06/subtitle_rag/blob/main/src/subtitle_rag/indexing/bm25.py"
click node_vector_store "https://github.com/rameshucs06/subtitle_rag/tree/main/artifacts"
click node_chunks "https://github.com/rameshucs06/subtitle_rag/tree/main/data/processed"
click node_cleaning "https://github.com/rameshucs06/subtitle_rag/blob/main/src/subtitle_rag/ingestion/cleaning.py"
click node_chunking "https://github.com/rameshucs06/subtitle_rag/blob/main/src/subtitle_rag/ingestion/chunking.py"
click node_rag "https://github.com/rameshucs06/subtitle_rag/blob/main/src/subtitle_rag/generation/rag.py"
click node_prompts "https://github.com/rameshucs06/subtitle_rag/blob/main/src/subtitle_rag/generation/prompts.py"
click node_summarizer "https://github.com/rameshucs06/subtitle_rag/blob/main/src/subtitle_rag/generation/summarizer.py"
click node_llm "https://github.com/rameshucs06/subtitle_rag/blob/main/src/subtitle_rag/generation/llm.py"
click node_monitoring "https://github.com/rameshucs06/subtitle_rag/blob/main/src/subtitle_rag/monitoring.py"
click node_request_log "https://github.com/rameshucs06/subtitle_rag/tree/main/logs"
click node_retrieval_metrics "https://github.com/rameshucs06/subtitle_rag/blob/main/src/subtitle_rag/evaluation/metrics.py"
click node_answer_eval "https://github.com/rameshucs06/subtitle_rag/blob/main/src/subtitle_rag/evaluation/answer_eval.py"
click node_eval_data "https://github.com/rameshucs06/subtitle_rag/blob/main/data/eval/eval_questions.csv"

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_streamlit,node_inspect,node_summarize_page,node_monitor_page,node_api_client,node_user toneBlue
class node_api,node_config toneAmber
class node_retriever,node_bm25,node_vector_store,node_chunks,node_cleaning,node_chunking toneMint
class node_rag,node_prompts,node_summarizer,node_llm toneRose
class node_monitoring,node_request_log,node_retrieval_metrics,node_answer_eval,node_eval_data,node_gemini toneIndigo
```

## Components

### User experience

- [Ask UI](https://github.com/rameshucs06/subtitle_rag/blob/main/ui/app.py): `ui/app.py`
- [Inspect page](https://github.com/rameshucs06/subtitle_rag/blob/main/ui/pages/1_Inspect.py): `ui/pages/1_Inspect.py`
- [Summarize page](https://github.com/rameshucs06/subtitle_rag/blob/main/ui/pages/2_Summarize.py): `ui/pages/2_Summarize.py`
- [Monitor page](https://github.com/rameshucs06/subtitle_rag/blob/main/ui/pages/3_Monitor.py): `ui/pages/3_Monitor.py`
- [HTTP client](https://github.com/rameshucs06/subtitle_rag/blob/main/ui/api_client.py): `ui/api_client.py`

### API orchestration

- [HTTP API](https://github.com/rameshucs06/subtitle_rag/blob/main/api/main.py): `api/main.py`
- [Configuration](https://github.com/rameshucs06/subtitle_rag/blob/main/src/subtitle_rag/config.py): `src/subtitle_rag/config.py`

### Search and corpus

- [Hybrid retriever](https://github.com/rameshucs06/subtitle_rag/blob/main/src/subtitle_rag/retrieval/search.py): `src/subtitle_rag/retrieval/search.py`
- [BM25 index](https://github.com/rameshucs06/subtitle_rag/blob/main/src/subtitle_rag/indexing/bm25.py): `src/subtitle_rag/indexing/bm25.py`
- [Chroma index](https://github.com/rameshucs06/subtitle_rag/tree/main/artifacts): `artifacts`
- [Subtitle chunks](https://github.com/rameshucs06/subtitle_rag/tree/main/data/processed): `data/processed`
- [Subtitle cleaning](https://github.com/rameshucs06/subtitle_rag/blob/main/src/subtitle_rag/ingestion/cleaning.py): `src/subtitle_rag/ingestion/cleaning.py`
- [Chunk creation](https://github.com/rameshucs06/subtitle_rag/blob/main/src/subtitle_rag/ingestion/chunking.py): `src/subtitle_rag/ingestion/chunking.py`

### Answer generation

- [RAG workflow](https://github.com/rameshucs06/subtitle_rag/blob/main/src/subtitle_rag/generation/rag.py): `src/subtitle_rag/generation/rag.py`
- [Prompt templates](https://github.com/rameshucs06/subtitle_rag/blob/main/src/subtitle_rag/generation/prompts.py): `src/subtitle_rag/generation/prompts.py`
- [Episode summarizer](https://github.com/rameshucs06/subtitle_rag/blob/main/src/subtitle_rag/generation/summarizer.py): `src/subtitle_rag/generation/summarizer.py`
- [Gemini wrapper](https://github.com/rameshucs06/subtitle_rag/blob/main/src/subtitle_rag/generation/llm.py): `src/subtitle_rag/generation/llm.py`

### Monitoring and evaluation

- [Request monitoring](https://github.com/rameshucs06/subtitle_rag/blob/main/src/subtitle_rag/monitoring.py): `src/subtitle_rag/monitoring.py`
- [Request log](https://github.com/rameshucs06/subtitle_rag/tree/main/logs): `logs`
- [Retrieval metrics](https://github.com/rameshucs06/subtitle_rag/blob/main/src/subtitle_rag/evaluation/metrics.py): `src/subtitle_rag/evaluation/metrics.py`
- [Answer evaluation](https://github.com/rameshucs06/subtitle_rag/blob/main/src/subtitle_rag/evaluation/answer_eval.py): `src/subtitle_rag/evaluation/answer_eval.py`
- [Evaluation questions](https://github.com/rameshucs06/subtitle_rag/blob/main/data/eval/eval_questions.csv): `data/eval/eval_questions.csv`

### Other components

- **User**
- **Gemini service**

## Connections

- User → Ask UI: asks or browses (evidence: `README.md`)
- Ask UI → HTTP client: calls (evidence: `ui/app.py`)
- Inspect page → HTTP client: calls (evidence: `ui/pages/1_Inspect.py`)
- Summarize page → HTTP client: calls (evidence: `ui/pages/2_Summarize.py`)
- Monitor page → HTTP client: calls (evidence: `ui/pages/3_Monitor.py`)
- HTTP client → HTTP API: sends HTTP requests (evidence: `ui/api_client.py`)
- HTTP API → Hybrid retriever: searches (evidence: `api/main.py`)
- HTTP API → RAG workflow: asks (evidence: `api/main.py`)
- HTTP API → Episode summarizer: summarizes (evidence: `api/main.py`)
- HTTP API → Request monitoring: records and reads events (evidence: `api/main.py`)
- Hybrid retriever → BM25 index: scores keywords (evidence: `src/subtitle_rag/retrieval/search.py`)
- Hybrid retriever → Chroma index: queries and fetches (evidence: `README.md`)
- Hybrid retriever → Subtitle chunks: loads chunk data (evidence: `README.md`)
- RAG workflow → Hybrid retriever: retrieves passages (evidence: `src/subtitle_rag/generation/rag.py`)
- RAG workflow → Prompt templates: builds prompts (evidence: `src/subtitle_rag/generation/rag.py`)
- RAG workflow → Gemini wrapper: generates and translates (evidence: `src/subtitle_rag/generation/rag.py`)
- Episode summarizer → Prompt templates: builds summary prompts (evidence: `src/subtitle_rag/generation/summarizer.py`)
- Episode summarizer → Gemini wrapper: requests summaries (evidence: `src/subtitle_rag/generation/summarizer.py`)
- Gemini wrapper → Gemini service: calls (evidence: `src/subtitle_rag/generation/llm.py`)
- Gemini wrapper → Request monitoring: updates counters (evidence: `src/subtitle_rag/generation/llm.py`)
- Request monitoring → Request log: writes and reads (evidence: `src/subtitle_rag/monitoring.py`)
- Monitor page → HTTP API: requests metrics (evidence: `README.md`)
- Answer evaluation → Retrieval metrics: uses hit ranking (evidence: `src/subtitle_rag/evaluation/answer_eval.py`)
- Answer evaluation → RAG workflow: checks citations (evidence: `src/subtitle_rag/evaluation/answer_eval.py`)
- Answer evaluation → Gemini wrapper: judges answers (evidence: `src/subtitle_rag/evaluation/answer_eval.py`)
- Evaluation questions → Answer evaluation: evaluates against