# carlosom21/self-rag architecture

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

- Interactive diagram: https://gitdiagram.com/carlosom21/self-rag
- Repository: https://github.com/carlosom21/self-rag

## Overview

EvidenciaLocal is a local, PDF-grounded RAG application with Baseline and Corrective query modes. Users index PDFs, then ask questions through the CLI or Streamlit and receive answers, citations, evidence, and abstentions when needed. Corrective mode critiques evidence and may reformulate retrieval before a single final answer; evaluation supports comparing modes and human annotation. The graph follows documented workflows and excerpted calls; several evaluation and interface details are documented but their implementations were not sampled.

Main entry points: [`src/evidencialocal/pipeline/rag_pipeline.py`](https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/pipeline/rag_pipeline.py) (RAG orchestrator), [`src/evidencialocal/pipeline/indexer.py`](https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/pipeline/indexer.py) (Indexing orchestrator), [`src/evidencialocal/cli/main.py`](https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/cli/main.py) (CLI commands), [`src/evidencialocal/ui/streamlit_app.py`](https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/ui/streamlit_app.py) (Streamlit app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoints["User interfaces"]
  node_cli["CLI commands<br/>[main.py]"]
  node_ui["Streamlit app<br/>[streamlit_app.py]"]
end

subgraph group_indexing["Document indexing"]
  node_indexer["Indexing orchestrator<br/>[indexer.py]"]
  node_processor["PDF processing"]
end

subgraph group_query["RAG query"]
  node_rag["RAG orchestrator<br/>[rag_pipeline.py]"]
  node_retriever["Retriever<br/>[retriever.py]"]
end

subgraph group_runtime["Local inference and state"]
  node_settings["Configuration<br/>[settings.py]"]
  node_domain["Domain models<br/>[models.py]"]
  node_embedder["E5 embeddings<br/>[embedder.py]"]
  node_chroma[("Vector index<br/>[chroma_store.py]")]
  node_sqlite[("Metadata and traces<br/>[sqlite_store.py]")]
  node_llm["Local LLM client<br/>[llama_client.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_evaluation["Mode evaluation<br/>[evaluate.py]"]
end

node_user(("User"))

node_user -->|"runs commands"| node_cli
node_user -->|"uses interface"| node_ui
node_cli -->|"indexes PDFs"| node_indexer
node_cli -->|"submits questions"| node_rag
node_ui -->|"indexes uploads"| node_indexer
node_ui -->|"submits questions"| node_rag
node_indexer -->|"processes PDFs"| node_processor
node_processor -->|"embeds chunks"| node_embedder
node_indexer -->|"stores vectors"| node_chroma
node_indexer -->|"stores metadata"| node_sqlite
node_rag -->|"requests retrieval"| node_retriever
node_retriever -->|"embeds queries"| node_embedder
node_retriever -->|"queries vectors"| node_chroma
node_rag -->|"critiques and generates"| node_llm
node_rag -->|"records traces"| node_sqlite
node_cli -->|"runs evaluation"| node_evaluation
node_evaluation -->|"compares modes"| node_rag
node_evaluation -->|"stores results"| node_sqlite

click node_cli "https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/cli/main.py"
click node_ui "https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/ui/streamlit_app.py"
click node_settings "https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/config/settings.py"
click node_domain "https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/core/models.py"
click node_indexer "https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/pipeline/indexer.py"
click node_processor "https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/retrieval/document_processor.py"
click node_embedder "https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/embeddings/embedder.py"
click node_chroma "https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/vectorstore/chroma_store.py"
click node_sqlite "https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/metadata/sqlite_store.py"
click node_rag "https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/pipeline/rag_pipeline.py"
click node_retriever "https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/retrieval/retriever.py"
click node_llm "https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/llm/llama_client.py"
click node_evaluation "https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/cli/evaluate.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_ui,node_user toneBlue
class node_indexer,node_processor toneAmber
class node_rag,node_retriever toneMint
class node_settings,node_domain,node_embedder,node_chroma,node_sqlite,node_llm toneRose
class node_evaluation toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/cli/main.py): `src/evidencialocal/cli/main.py`
- [Streamlit app](https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/ui/streamlit_app.py): `src/evidencialocal/ui/streamlit_app.py`

### Document indexing

- [Indexing orchestrator](https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/pipeline/indexer.py): `src/evidencialocal/pipeline/indexer.py`
- [PDF processing](https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/retrieval/document_processor.py): `src/evidencialocal/retrieval/document_processor.py`

### RAG query

- [RAG orchestrator](https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/pipeline/rag_pipeline.py): `src/evidencialocal/pipeline/rag_pipeline.py`
- [Retriever](https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/retrieval/retriever.py): `src/evidencialocal/retrieval/retriever.py`

### Local inference and state

- [Configuration](https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/config/settings.py): `src/evidencialocal/config/settings.py`
- [Domain models](https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/core/models.py): `src/evidencialocal/core/models.py`
- [E5 embeddings](https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/embeddings/embedder.py): `src/evidencialocal/embeddings/embedder.py`
- [Vector index](https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/vectorstore/chroma_store.py): `src/evidencialocal/vectorstore/chroma_store.py`
- [Metadata and traces](https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/metadata/sqlite_store.py): `src/evidencialocal/metadata/sqlite_store.py`
- [Local LLM client](https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/llm/llama_client.py): `src/evidencialocal/llm/llama_client.py`

### Evaluation

- [Mode evaluation](https://github.com/carlosom21/self-rag/blob/main/src/evidencialocal/cli/evaluate.py): `src/evidencialocal/cli/evaluate.py`

### Other components

- **User**

## Connections

- User → CLI commands: runs commands (evidence: `README.md`)
- User → Streamlit app: uses interface (evidence: `README.md`)
- CLI commands → Indexing orchestrator: indexes PDFs (evidence: `src/evidencialocal/cli/main.py`)
- CLI commands → RAG orchestrator: submits questions (evidence: `src/evidencialocal/cli/main.py`)
- Streamlit app → Indexing orchestrator: indexes uploads (evidence: `src/evidencialocal/ui/streamlit_app.py`)
- Streamlit app → RAG orchestrator: submits questions (evidence: `src/evidencialocal/ui/streamlit_app.py`)
- Indexing orchestrator → PDF processing: processes PDFs (evidence: `src/evidencialocal/pipeline/indexer.py`)
- PDF processing → E5 embeddings: embeds chunks (evidence: `src/evidencialocal/retrieval/document_processor.py`)
- Indexing orchestrator → Vector index: stores vectors (evidence: `src/evidencialocal/pipeline/indexer.py`)
- Indexing orchestrator → Metadata and traces: stores metadata (evidence: `src/evidencialocal/pipeline/indexer.py`)
- RAG orchestrator → Retriever: requests retrieval (evidence: `src/evidencialocal/pipeline/rag_pipeline.py`)
- Retriever → E5 embeddings: embeds queries (evidence: `src/evidencialocal/retrieval/retriever.py`)
- Retriever → Vector index: queries vectors (evidence: `src/evidencialocal/retrieval/retriever.py`)
- RAG orchestrator → Local LLM client: critiques and generates (evidence: `README.md`)
- RAG orchestrator → Metadata and traces: records traces (evidence: `src/evidencialocal/pipeline/rag_pipeline.py`)
- CLI commands → Mode evaluation: runs evaluation (evidence: `src/evidencialocal/cli/main.py`)
- Mode evaluation → RAG orchestrator: compares modes (evidence: `src/evidencialocal/cli/evaluate.py`)
- Mode evaluation → Metadata and traces: stores results (evidence: `src/evidencialocal/cli/evaluate.py`)
