gromanchenko/hydrag

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.