# gromanchenko/hydrag architecture

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

- Interactive diagram: https://gitdiagram.com/gromanchenko/hydrag
- Repository: https://github.com/gromanchenko/hydrag

## Overview

HydRAG Core is a Python library, not an application service. Its architecture is centered on a query-time retrieval pipeline that sits between a caller and a pluggable vector-store backend, then optionally consults an LLM/CRAG supervisor before returning fused results.

1. **Top-level runtime boundary**
   - The main entry point is the `HydRAG` engine in `src/hydrag/core.py`.
   - Callers pass a query and receive ranked retrieval results.
   - The package is intentionally stdlib-first, with optional extras for vector stores, web fallback, and model tuning.

2. **Primary external integration: vector store adapter**
   - The core retrieval boundary is `VectorStoreAdapter` in `src/hydrag/protocols.py`.
   - Required methods are `semantic_search`, `keyword_search`, and `hybrid_search`.
   - Optional adapter methods such as `crag_search`, `graph_search`, and `rewrite_query` let the engine exploit richer backends without making them mandatory.

3. **Multi-head retrieval pipeline**
   - The engine is organized as a staged pipeline in `core.py` plus retrieval helpers.
   - Query flow follows the README’s heads:
     - Head 0: BM25 fast-path
     - Head 1: primary retrieval
     - Head 2: CRAG supervisor
     - Head 3a: semantic fallback
     - Head 3b: optional web fallback
   - The final output is fused across active heads using Reciprocal Rank Fusion.

4. **Ranking and fusion layer**
   - `src/hydrag/fusion.py` implements the rank-combination logic, especially RRF.
   - `src/hydrag/similarity_search.py` provides similarity-based scoring/search helpers.
   - This layer is what turns multiple retrieval heads into one ordered result set.

5. **Profile-driven routing**
   - `src/hydrag/config.py` controls behavior via `HydRAGConfig`.
   - The `prose` profile is the default domain-agnostic mode.
   - The `code` profile changes routing so symbol-heavy queries can use code-aware retrieval paths.
   - Head enable/disable flags and thresholds are all runtime-configurable, so the pipeline is highly dynamic.

6. **CRAG supervision**
   - `src/hydrag/core.py` and `src/hydrag/enrichment.py` coordinate the “corrective RAG” step.
   - The supervisor decides whether Head 1 is sufficient or whether fallback retrieval should run.
   - It can operate in LLM mode or classifier mode, with the classifier path using an exported ONNX model.
   - Streaming verdict parsing is supported through the LLM provider abstraction to reduce latency.

7. **LLM provider subsystem**
   - `src/hydrag/providers/` contains the backend implementations:
     - `ollama.py`
     - `huggingface.py`
     - `openai_compat.py`
   - `providers/factory.py` selects the backend from config.
   - `_retry.py` centralizes retry behavior for remote model calls.
   - This subsystem is isolated so the retrieval engine never depends on one provider shape.

8. **Fallback enrichment and query rewriting**
   - `src/hydrag/doc2query.py` and `src/hydrag/enrichment.py` support query expansion and fallback retrieval.
   - These modules help the semantic fallback head broaden poor or underspecified queries.
   - `rewrite_query` is also part of the adapter contract, allowing backends to influence fallback behavior.

9. **Input sanitization and web content handling**
   - `src/hydrag/sanitize.py` strips or normalizes content, especially for web fallback results.
   - This is important because external web content is treated as untrusted and may need markdown handling or chunk limiting before fusion.
   - The web fallback itself is optional and gated by config.

10. **Backend/storage implementations in the repo**
    - `src/hydrag/sqlite_store.py` and `src/hydrag/surreal_adapter.py` provide concrete persistence/backend integration points.
    - They are implementation examples of how the adapter boundary can be backed by local SQLite or SurrealDB-oriented storage.
    - These are not the core architecture, but they show how the retrieval engine is meant to be embedded into different stores.

11. **CRAG tuning and model generation path**
    - `src/hydrag/tune.py` is the training/fine-tuning subsystem for the CRAG classifier.
    - It sits outside the online retrieval path and is used to produce a low-latency model artifact consumed later by the engine.
    - This creates a clear offline/online split: training builds the classifier, runtime loads it.

12. **Cross-cutting concerns**
    - `src/hydrag/logging.py` centralizes logging behavior across the pipeline.
    - `src/hydrag/protocols.py` defines the typed interfaces that keep the package extensible.
    - `py.typed` signals that the package is designed for typed downstream integration.

13. **Project shape and packaging**
    - The repo is structured as a distributable library with packaging metadata in `pyproject.toml` and build logic in `hatch_build.py`.
    - Optional extras in the README reflect separate dependency domains: vector-store support, web fallback, tuning, and dev tooling.
    - The CI/test suite is broad enough to validate config, providers, fusion, sanitization, storage adapters, and Phase A requirements, which reinforces that the architecture is interface-heavy and regression-sensitive.

In diagram terms, the key shape is: caller → `HydRAG` engine → configurable retrieval heads → CRAG decision point → optional fallbacks → RRF fusion → ranked results, with the main external boundaries being the vector-store adapter and the LLM provider abstraction.

Main entry points: [`src/hydrag/core.py`](https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/core.py) (HydRAG), [`src/hydrag/providers/factory.py`](https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/providers/factory.py) (Factory), [`src/hydrag/enrichment.py`](https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/enrichment.py) (Enrichment), [`src/hydrag/providers/_retry.py`](https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/providers/_retry.py) (Retry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_core["HydRAG<br/>engine<br/>[core.py]"]
  node_config["Config<br/>[config.py]"]
  node_protocols["Protocols<br/>adapter contracts<br/>[protocols.py]"]
  node_fusion["Fusion<br/>[fusion.py]"]
  node_similarity["Similarity<br/>scoring helpers"]
  node_enrichment["Enrichment<br/>crag fallback<br/>[enrichment.py]"]
  node_doc2query["Doc2Query<br/>query expansion<br/>[doc2query.py]"]
  node_sanitize["Sanitize<br/>content hygiene<br/>[sanitize.py]"]
  node_indexer["Indexer<br/>index build<br/>[indexer.py]"]
end

subgraph group_providers["Providers"]
  node_factory["Factory<br/>provider selector<br/>[factory.py]"]
  node_retry["Retry<br/>resilience<br/>[_retry.py]"]
  node_ollama["Ollama<br/>llm backend<br/>[ollama.py]"]
  node_huggingface["Hugging Face<br/>llm backend<br/>[huggingface.py]"]
  node_openai["OpenAI Compat<br/>llm backend<br/>[openai_compat.py]"]
end

subgraph group_storage["Storage"]
  node_sqlite[("SQLite Store<br/>vector store<br/>[sqlite_store.py]")]
  node_surreal[("Surreal Adapter<br/>vector store<br/>[surreal_adapter.py]")]
end

subgraph group_offline["Offline"]
  node_tune["Tune<br/>offline training<br/>[tune.py]"]
end

node_caller(("Caller<br/>external client"))
node_logging["Logging<br/>cross-cutting<br/>[logging.py]"]

node_caller -->|"query"| node_core
node_core -->|"profile"| node_config
node_core -->|"adapter contract"| node_protocols
node_core -->|"retrieve"| node_similarity
node_core -->|"supervise"| node_enrichment
node_core -->|"fuse"| node_fusion
node_enrichment -->|"llm select"| node_factory
node_factory -->|"backend"| node_ollama
node_factory -->|"backend"| node_huggingface
node_factory -->|"backend"| node_openai
node_ollama -->|"uses"| node_retry
node_huggingface -->|"uses"| node_retry
node_openai -->|"uses"| node_retry
node_core -->|"expand"| node_doc2query
node_core -->|"clean"| node_sanitize
node_core -.->|"store"| node_sqlite
node_core -.->|"store"| node_surreal
node_tune -->|"artifact"| node_enrichment
node_indexer -.->|"build index"| node_sqlite
node_indexer -.->|"build index"| node_surreal
node_logging -.->|"observe"| node_core

click node_core "https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/core.py"
click node_config "https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/config.py"
click node_protocols "https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/protocols.py"
click node_fusion "https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/fusion.py"
click node_similarity "https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/similarity_search.py"
click node_enrichment "https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/enrichment.py"
click node_doc2query "https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/doc2query.py"
click node_sanitize "https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/sanitize.py"
click node_indexer "https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/indexer.py"
click node_factory "https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/providers/factory.py"
click node_retry "https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/providers/_retry.py"
click node_ollama "https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/providers/ollama.py"
click node_huggingface "https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/providers/huggingface.py"
click node_openai "https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/providers/openai_compat.py"
click node_sqlite "https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/sqlite_store.py"
click node_surreal "https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/surreal_adapter.py"
click node_tune "https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/tune.py"
click node_logging "https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/logging.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_core,node_config,node_protocols,node_fusion,node_similarity,node_enrichment,node_doc2query,node_sanitize,node_indexer toneBlue
class node_factory,node_retry,node_ollama,node_huggingface,node_openai toneAmber
class node_sqlite,node_surreal toneMint
class node_tune toneRose
class node_caller,node_logging toneNeutral
```

## Components

### Runtime

Online query-time retrieval pipeline and orchestration

- [HydRAG](https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/core.py): engine · Main retrieval engine and orchestration entry point · `src/hydrag/core.py`
- [Config](https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/config.py): routing config · Runtime profile, thresholds, and head selection · `src/hydrag/config.py`
- [Protocols](https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/protocols.py): adapter contracts · Typed interfaces for vector stores and optional capabilities · `src/hydrag/protocols.py`
- [Fusion](https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/fusion.py): rank fusion · Reciprocal Rank Fusion and result combination · `src/hydrag/fusion.py`
- [Similarity](https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/similarity_search.py): scoring helpers · Similarity-based search and ranking utilities · `src/hydrag/similarity_search.py`
- [Enrichment](https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/enrichment.py): crag fallback · Corrective retrieval decisions and fallback orchestration · `src/hydrag/enrichment.py`
- [Doc2Query](https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/doc2query.py): query expansion · Query expansion helpers for sparse or weak queries · `src/hydrag/doc2query.py`
- [Sanitize](https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/sanitize.py): content hygiene · Normalizes and constrains untrusted content before fusion · `src/hydrag/sanitize.py`
- [Indexer](https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/indexer.py): index build · Offline indexing and corpus preparation support · `src/hydrag/indexer.py`

### Providers

LLM backend integrations and retry/factory layer

- [Factory](https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/providers/factory.py): provider selector · Chooses an LLM backend from configuration · `src/hydrag/providers/factory.py`
- [Retry](https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/providers/_retry.py): resilience · Shared retry logic for remote provider calls · `src/hydrag/providers/_retry.py`
- [Ollama](https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/providers/ollama.py): llm backend · Local model provider implementation · `src/hydrag/providers/ollama.py`
- [Hugging Face](https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/providers/huggingface.py): llm backend · Hosted or local Hugging Face provider implementation · `src/hydrag/providers/huggingface.py`
- [OpenAI Compat](https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/providers/openai_compat.py): llm backend · OpenAI-compatible provider implementation · `src/hydrag/providers/openai_compat.py`

### Storage

Concrete vector-store and persistence adapters

- [SQLite Store](https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/sqlite_store.py): vector store · Local storage-backed adapter implementation · `src/hydrag/sqlite_store.py`
- [Surreal Adapter](https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/surreal_adapter.py): vector store · SurrealDB-oriented adapter implementation · `src/hydrag/surreal_adapter.py`

### Offline

Training and build-time support

- [Tune](https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/tune.py): offline training · Classifier tuning and artifact generation for CRAG · `src/hydrag/tune.py`

### Other components

- **Caller**: external client · Library consumer issuing retrieval queries
- [Logging](https://github.com/gromanchenko/hydrag/blob/main/src/hydrag/logging.py): cross-cutting · Shared logging setup for the package · `src/hydrag/logging.py`

## Connections

- Caller → HydRAG: query · Caller submits a query to the engine
- HydRAG → Config: profile · Engine reads runtime profile and head settings
- HydRAG → Protocols: adapter contract · Engine depends on vector-store capabilities
- HydRAG → Similarity: retrieve · Similarity helpers support search and scoring
- HydRAG → Enrichment: supervise · CRAG step decides whether to continue or fall back
- HydRAG → Fusion: fuse · Active heads are merged into one ranked list
- Enrichment → Factory: llm select · Supervisor obtains the configured LLM backend
- Factory → Ollama: backend · Selects Ollama provider implementation
- Factory → Hugging Face: backend · Selects Hugging Face provider implementation
- Factory → OpenAI Compat: backend · Selects OpenAI-compatible provider implementation
- Ollama → Retry: uses · Provider calls share retry behavior
- Hugging Face → Retry: uses · Provider calls share retry behavior
- OpenAI Compat → Retry: uses · Provider calls share retry behavior
- HydRAG → Doc2Query: expand · Fallback queries may be expanded before retrieval
- HydRAG → Sanitize: clean · External content is normalized before fusion
- HydRAG → SQLite Store: store · One concrete vector-store backend
- HydRAG → Surreal Adapter: store · Another concrete vector-store backend
- Tune → Enrichment: artifact · Offline tuning produces model artifacts consumed at runtime
- Indexer → SQLite Store: build index · Indexing can populate a local backend
- Indexer → Surreal Adapter: build index · Indexing can populate a Surreal-backed backend
- Logging → HydRAG: observe · Shared logging supports the runtime pipeline