# znbne/telco-retrieve architecture

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

- Interactive diagram: https://gitdiagram.com/znbne/telco-retrieve
- Repository: https://github.com/znbne/telco-retrieve

## Overview

TelcoRetrieve is a telecom-specification RAG product: users ingest standards corpora, then ask questions and receive generated answers with source passages. The principal path runs from CLI-selected source loaders through cleaning, chunking, embedding and indexing, then retrieval, optional reranking and generation. README-documented capabilities also include hybrid/multi-collection search, prebuilt Hugging Face chunks, and evaluation/challenge workflows. Edges are limited to relationships explicit in the README or shown by the supplied excerpts and SOURCE INDEX; other plausible runtime connections are omitted.

Main entry points: [`cli/main.py`](https://github.com/znbne/telco-retrieve/blob/main/cli/main.py) (CLI commands), [`open_telco_rag/core/retrieval.py`](https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/core/retrieval.py) (Retrieval and fusion), [`open_telco_rag/core/pipeline.py`](https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/core/pipeline.py) (Ingest pipeline), [`open_telco_rag/evaluation/evaluate.py`](https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/evaluation/evaluate.py) (RAG evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Corpus ingestion"]
  node_loaders["Standards loaders"]
  node_clean["Text cleaning<br/>[cleaning.py]"]
  node_chunk["Chunking and bounds<br/>[chunking.py]"]
  node_enrich["Chunk enrichment<br/>[enrichment.py]"]
  node_embed["Embedding backends"]
  node_pipeline["Ingest pipeline<br/>[pipeline.py]"]
end

subgraph group_search["Search and retrieval"]
  node_vector[("Vector index<br/>[chroma.py]")]
  node_keyword[("Keyword index<br/>[fts.py]")]
  node_retrieval["Retrieval and fusion<br/>[retrieval.py]"]
  node_multisearch["Multi-collection search<br/>[multi_search.py]"]
  node_rerank["Reranking<br/>[reranker.py]"]
  node_hf["Prebuilt chunks<br/>[hf.py]"]
end

subgraph group_answer["Answer generation"]
  node_generator["LLM generators"]
end

subgraph group_quality["Evaluation and challenge"]
  node_eval["RAG evaluation<br/>[evaluate.py]"]
  node_evalmetrics["Evaluation metrics"]
  node_evalresults["Evaluation results<br/>[results.py]"]
  node_challenge["Challenge workflow<br/>[cli.py]"]
  node_challengeindex["Challenge index<br/>[index.py]"]
  node_challengeclient["Challenge client<br/>[client.py]"]
  node_challengechecks["Challenge scoring<br/>[score.py]"]
end

node_user(("CLI user"))
node_cli["CLI commands<br/>[main.py]"]
node_llm{{"LLM services"}}

node_user -->|"runs commands"| node_cli
node_cli -->|"selects corpus"| node_loaders
node_loaders -->|"cleans text"| node_clean
node_pipeline -->|"chunks documents"| node_chunk
node_pipeline -->|"enriches chunks"| node_enrich
node_pipeline -->|"writes vectors"| node_vector
node_pipeline -->|"writes text index"| node_keyword
node_chunk -->|"prepares passages"| node_embed
node_cli -->|"starts ingestion"| node_pipeline
node_cli -->|"configures search"| node_retrieval
node_retrieval -->|"embeds query"| node_embed
node_retrieval -->|"queries vectors"| node_vector
node_retrieval -->|"searches terms"| node_keyword
node_retrieval -.->|"reranks hits"| node_rerank
node_multisearch -->|"opens collections"| node_vector
node_cli -.->|"configures search"| node_multisearch
node_cli -->|"loads dataset"| node_hf
node_cli -->|"selects generator"| node_generator
node_generator -->|"requests completion"| node_llm
node_eval -->|"runs retrieval"| node_retrieval
node_eval -->|"runs generation"| node_generator
node_eval -->|"scores outputs"| node_evalmetrics
node_eval -->|"records results"| node_evalresults
node_cli -.->|"starts evaluation"| node_eval
node_challenge -->|"uses client"| node_challengeclient
node_challenge -->|"uses index"| node_challengeindex
node_challenge -.->|"checks scores"| node_challengechecks
node_cli -->|"delegates challenge"| node_challenge

click node_cli "https://github.com/znbne/telco-retrieve/blob/main/cli/main.py"
click node_loaders "https://github.com/znbne/telco-retrieve/tree/main/open_telco_rag/sources"
click node_clean "https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/core/cleaning.py"
click node_chunk "https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/core/chunking.py"
click node_enrich "https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/core/enrichment.py"
click node_embed "https://github.com/znbne/telco-retrieve/tree/main/open_telco_rag/embedders"
click node_pipeline "https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/core/pipeline.py"
click node_vector "https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/stores/chroma.py"
click node_keyword "https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/stores/fts.py"
click node_retrieval "https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/core/retrieval.py"
click node_multisearch "https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/core/multi_search.py"
click node_rerank "https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/embedders/reranker.py"
click node_hf "https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/stores/hf.py"
click node_generator "https://github.com/znbne/telco-retrieve/tree/main/open_telco_rag/generators"
click node_eval "https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/evaluation/evaluate.py"
click node_evalmetrics "https://github.com/znbne/telco-retrieve/tree/main/open_telco_rag/evaluation/metrics"
click node_evalresults "https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/evaluation/results.py"
click node_challenge "https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/challenge/cli.py"
click node_challengeindex "https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/challenge/index.py"
click node_challengeclient "https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/challenge/client.py"
click node_challengechecks "https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/challenge/score.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_loaders,node_clean,node_chunk,node_enrich,node_embed,node_pipeline,node_user toneBlue
class node_vector,node_keyword,node_retrieval,node_multisearch,node_rerank,node_hf toneAmber
class node_generator toneMint
class node_eval,node_evalmetrics,node_evalresults,node_challenge,node_challengeindex,node_challengeclient,node_challengechecks toneRose
class node_cli toneTeal
class node_llm toneIndigo
```

## Components

### Corpus ingestion

- [Standards loaders](https://github.com/znbne/telco-retrieve/tree/main/open_telco_rag/sources): `open_telco_rag/sources`
- [Text cleaning](https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/core/cleaning.py): `open_telco_rag/core/cleaning.py`
- [Chunking and bounds](https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/core/chunking.py): `open_telco_rag/core/chunking.py`
- [Chunk enrichment](https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/core/enrichment.py): `open_telco_rag/core/enrichment.py`
- [Embedding backends](https://github.com/znbne/telco-retrieve/tree/main/open_telco_rag/embedders): `open_telco_rag/embedders`
- [Ingest pipeline](https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/core/pipeline.py): `open_telco_rag/core/pipeline.py`

### Search and retrieval

- [Vector index](https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/stores/chroma.py): `open_telco_rag/stores/chroma.py`
- [Keyword index](https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/stores/fts.py): `open_telco_rag/stores/fts.py`
- [Retrieval and fusion](https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/core/retrieval.py): `open_telco_rag/core/retrieval.py`
- [Multi-collection search](https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/core/multi_search.py): `open_telco_rag/core/multi_search.py`
- [Reranking](https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/embedders/reranker.py): `open_telco_rag/embedders/reranker.py`
- [Prebuilt chunks](https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/stores/hf.py): `open_telco_rag/stores/hf.py`

### Answer generation

- [LLM generators](https://github.com/znbne/telco-retrieve/tree/main/open_telco_rag/generators): `open_telco_rag/generators`

### Evaluation and challenge

- [RAG evaluation](https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/evaluation/evaluate.py): `open_telco_rag/evaluation/evaluate.py`
- [Evaluation metrics](https://github.com/znbne/telco-retrieve/tree/main/open_telco_rag/evaluation/metrics): `open_telco_rag/evaluation/metrics`
- [Evaluation results](https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/evaluation/results.py): `open_telco_rag/evaluation/results.py`
- [Challenge workflow](https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/challenge/cli.py): `open_telco_rag/challenge/cli.py`
- [Challenge index](https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/challenge/index.py): `open_telco_rag/challenge/index.py`
- [Challenge client](https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/challenge/client.py): `open_telco_rag/challenge/client.py`
- [Challenge scoring](https://github.com/znbne/telco-retrieve/blob/main/open_telco_rag/challenge/score.py): `open_telco_rag/challenge/score.py`

### Other components

- **CLI user**
- [CLI commands](https://github.com/znbne/telco-retrieve/blob/main/cli/main.py): `cli/main.py`
- **LLM services**

## Connections

- CLI user → CLI commands: runs commands
- CLI commands → Standards loaders: selects corpus (evidence: `cli/main.py`)
- Standards loaders → Text cleaning: cleans text (evidence: `open_telco_rag/sources/camara.py`)
- Ingest pipeline → Chunking and bounds: chunks documents (evidence: `open_telco_rag/core/pipeline.py`)
- Ingest pipeline → Chunk enrichment: enriches chunks (evidence: `open_telco_rag/core/pipeline.py`)
- Ingest pipeline → Vector index: writes vectors (evidence: `open_telco_rag/core/pipeline.py`)
- Ingest pipeline → Keyword index: writes text index (evidence: `open_telco_rag/core/pipeline.py`)
- Chunking and bounds → Embedding backends: prepares passages
- CLI commands → Ingest pipeline: starts ingestion (evidence: `cli/main.py`)
- CLI commands → Retrieval and fusion: configures search (evidence: `cli/main.py`)
- Retrieval and fusion → Embedding backends: embeds query (evidence: `open_telco_rag/core/retrieval.py`)
- Retrieval and fusion → Vector index: queries vectors (evidence: `open_telco_rag/core/retrieval.py`)
- Retrieval and fusion → Keyword index: searches terms (evidence: `open_telco_rag/core/retrieval.py`)
- Retrieval and fusion → Reranking: reranks hits
- Multi-collection search → Vector index: opens collections (evidence: `open_telco_rag/core/multi_search.py`)
- CLI commands → Multi-collection search: configures search (evidence: `cli/main.py`)
- CLI commands → Prebuilt chunks: loads dataset (evidence: `cli/main.py`)
- CLI commands → LLM generators: selects generator (evidence: `cli/main.py`)
- LLM generators → LLM services: requests completion (evidence: `open_telco_rag/generators/openrouter.py`)
- RAG evaluation → Retrieval and fusion: runs retrieval (evidence: `open_telco_rag/evaluation/evaluate.py`)
- RAG evaluation → LLM generators: runs generation (evidence: `open_telco_rag/evaluation/evaluate.py`)
- RAG evaluation → Evaluation metrics: scores outputs (evidence: `open_telco_rag/evaluation/evaluate.py`)
- RAG evaluation → Evaluation results: records results (evidence: `open_telco_rag/evaluation/evaluate.py`)
- CLI commands → RAG evaluation: starts evaluation (evidence: `cli/main.py`)
- Challenge workflow → Challenge client: uses client (evidence: `open_telco_rag/challenge/cli.py`)
- Challenge workflow → Challenge index: uses index (evidence: `open_telco_rag/challenge/cli.py`)
- Challenge workflow → Challenge scoring: checks scores (evidence: `open_telco_rag/challenge/cli.py`)
- CLI commands → Challenge workflow: delegates challenge (evidence: `cli/main.py`)