# alihassanwarsi/hybridix architecture

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

- Interactive diagram: https://gitdiagram.com/alihassanwarsi/hybridix
- Repository: https://github.com/alihassanwarsi/hybridix

## Overview

Hybridix is a documentation-focused hybrid RAG engine. Its main workflow ingests Markdown/MDX into chunks, builds and activates validated versioned dense and sparse indexes, then retrieves and reranks evidence for a generated answer that is citation-linked and verified or refused. The README also documents automated retrieval and answer-quality evaluation. Relationships are shown only where supported by README statements or the supplied source index/excerpts; some evaluation and ingestion details are represented at their exact module paths because their implementations were not excerpted.

Main entry points: [`src/hybridix/pipeline.py`](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/pipeline.py) (RAG pipeline), [`src/hybridix/evaluation/runner.py`](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/evaluation/runner.py) (Retrieval evaluation), [`src/hybridix/cli.py`](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/cli.py) (CLI), [`src/hybridix/retrieval/hybrid_retriever.py`](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/retrieval/hybrid_retriever.py) (Hybrid RRF search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Ingestion"]
  node_processor["Document processing<br/>[processor.py]"]
  node_loader["Document loader<br/>[loader.py]"]
  node_chunking["Heading chunking<br/>[chunking.py]"]
end

subgraph group_index["Indexing"]
  node_budget["Token budgeting<br/>[token_budget.py]"]
  node_builder["Version builder<br/>[builder.py]"]
  node_dense_index["Dense indexer<br/>[dense_indexer.py]"]
  node_embeddings["Embeddings<br/>[embeddings.py]"]
  node_search_text["Search text<br/>[search_text.py]"]
  node_sparse_index["Sparse indexer<br/>[sparse_indexer.py]"]
  node_index_store[("Versioned indexes<br/>[active.py]")]
  node_validator["Index validator<br/>[validator.py]"]
end

subgraph group_retrieve["Retrieval"]
  node_hybrid["Hybrid RRF search"]
  node_dense_search["Dense search<br/>[dense_retriever.py]"]
  node_sparse_search["BM25 search"]
  node_reranker["Cross-encoder reranker<br/>[reranker.py]"]
end

subgraph group_answer["Answering"]
  node_pipeline["RAG pipeline<br/>[pipeline.py]"]
  node_generator["Answer generation<br/>[generator.py]"]
  node_context["Context merging<br/>[context.py]"]
  node_citations["Citation resolution<br/>[citations.py]"]
  node_verifier["Evidence verification"]
end

subgraph group_evaluate["Evaluation"]
  node_eval_runner["Retrieval evaluation<br/>[runner.py]"]
  node_eval_data["Evaluation datasets<br/>[dataset_loader.py]"]
  node_answer_eval["Answer evaluation<br/>[answer_runner.py]"]
  node_ragas["RAGAS evaluation<br/>[ragas_runner.py]"]
end

node_user(("Questioner"))
node_docs["Markdown/MDX"]
node_cli["CLI<br/>[cli.py]"]
node_groq{{"Groq API"}}

node_docs -->|"ingest input"| node_cli
node_user -->|"asks question"| node_cli
node_cli -->|"ingests via"| node_processor
node_processor -->|"loads files"| node_loader
node_processor -->|"chunks documents"| node_chunking
node_cli -->|"runs query"| node_pipeline
node_pipeline -->|"fits chunks"| node_budget
node_pipeline -->|"builds version"| node_builder
node_builder -->|"builds dense"| node_dense_index
node_builder -->|"builds sparse"| node_sparse_index
node_dense_index -->|"embeds text"| node_embeddings
node_dense_index -->|"formats search text"| node_search_text
node_pipeline -->|"activates version"| node_index_store
node_index_store -->|"validates pair"| node_validator
node_validator -->|"checks dense IDs"| node_dense_index
node_hybrid -->|"resolves active paths"| node_index_store
node_hybrid -->|"requests candidates"| node_dense_search
node_hybrid -->|"requests candidates"| node_sparse_search
node_dense_search -->|"queries collection"| node_dense_index
node_dense_search -->|"embeds query"| node_embeddings
node_pipeline -->|"searches reranked"| node_reranker
node_reranker -->|"reranks results"| node_hybrid
node_pipeline -->|"generates answer"| node_generator
node_generator -->|"merges evidence"| node_context
node_generator -->|"resolves citations"| node_citations
node_generator -.->|"calls model"| node_groq
node_pipeline -->|"verifies answer"| node_verifier
node_cli -->|"runs retrieval evaluation"| node_eval_runner
node_eval_runner -->|"loads cases"| node_eval_data
node_eval_runner -->|"evaluates dense"| node_dense_search
node_eval_runner -->|"evaluates sparse"| node_sparse_search
node_eval_runner -->|"evaluates hybrid"| node_hybrid
node_eval_runner -->|"evaluates reranked"| node_reranker
node_answer_eval -->|"evaluates answers"| node_pipeline
node_ragas -->|"loads evaluation cases"| node_eval_data

click node_cli "https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/cli.py"
click node_processor "https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/ingestion/processor.py"
click node_loader "https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/ingestion/loader.py"
click node_chunking "https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/ingestion/chunking.py"
click node_budget "https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/indexing/token_budget.py"
click node_builder "https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/indexing/versioning/builder.py"
click node_dense_index "https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/indexing/dense_indexer.py"
click node_embeddings "https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/indexing/embeddings.py"
click node_search_text "https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/indexing/search_text.py"
click node_sparse_index "https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/indexing/sparse_indexer.py"
click node_index_store "https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/indexing/versioning/active.py"
click node_validator "https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/indexing/versioning/validator.py"
click node_hybrid "https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/retrieval/hybrid_retriever.py"
click node_dense_search "https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/retrieval/dense_retriever.py"
click node_sparse_search "https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/retrieval/sparse_retriever.py"
click node_reranker "https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/retrieval/reranker.py"
click node_pipeline "https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/pipeline.py"
click node_generator "https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/generation/generator.py"
click node_context "https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/generation/context.py"
click node_citations "https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/generation/citations.py"
click node_verifier "https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/generation/evidence_verifier.py"
click node_eval_runner "https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/evaluation/runner.py"
click node_eval_data "https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/evaluation/dataset_loader.py"
click node_answer_eval "https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/evaluation/answer_runner.py"
click node_ragas "https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/evaluation/ragas_runner.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_processor,node_loader,node_chunking toneBlue
class node_budget,node_builder,node_dense_index,node_embeddings,node_search_text,node_sparse_index,node_index_store,node_validator toneAmber
class node_hybrid,node_dense_search,node_sparse_search,node_reranker,node_groq toneMint
class node_pipeline,node_generator,node_context,node_citations,node_verifier toneRose
class node_eval_runner,node_eval_data,node_answer_eval,node_ragas,node_user,node_docs toneIndigo
class node_cli toneTeal
```

## Components

### Ingestion

- [Document processing](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/ingestion/processor.py): `src/hybridix/ingestion/processor.py`
- [Document loader](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/ingestion/loader.py): `src/hybridix/ingestion/loader.py`
- [Heading chunking](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/ingestion/chunking.py): `src/hybridix/ingestion/chunking.py`

### Indexing

- [Token budgeting](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/indexing/token_budget.py): `src/hybridix/indexing/token_budget.py`
- [Version builder](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/indexing/versioning/builder.py): `src/hybridix/indexing/versioning/builder.py`
- [Dense indexer](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/indexing/dense_indexer.py): `src/hybridix/indexing/dense_indexer.py`
- [Embeddings](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/indexing/embeddings.py): `src/hybridix/indexing/embeddings.py`
- [Search text](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/indexing/search_text.py): `src/hybridix/indexing/search_text.py`
- [Sparse indexer](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/indexing/sparse_indexer.py): `src/hybridix/indexing/sparse_indexer.py`
- [Versioned indexes](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/indexing/versioning/active.py): `src/hybridix/indexing/versioning/active.py`
- [Index validator](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/indexing/versioning/validator.py): `src/hybridix/indexing/versioning/validator.py`

### Retrieval

- [Hybrid RRF search](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/retrieval/hybrid_retriever.py): `src/hybridix/retrieval/hybrid_retriever.py`
- [Dense search](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/retrieval/dense_retriever.py): `src/hybridix/retrieval/dense_retriever.py`
- [BM25 search](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/retrieval/sparse_retriever.py): `src/hybridix/retrieval/sparse_retriever.py`
- [Cross-encoder reranker](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/retrieval/reranker.py): `src/hybridix/retrieval/reranker.py`

### Answering

- [RAG pipeline](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/pipeline.py): `src/hybridix/pipeline.py`
- [Answer generation](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/generation/generator.py): `src/hybridix/generation/generator.py`
- [Context merging](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/generation/context.py): `src/hybridix/generation/context.py`
- [Citation resolution](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/generation/citations.py): `src/hybridix/generation/citations.py`
- [Evidence verification](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/generation/evidence_verifier.py): `src/hybridix/generation/evidence_verifier.py`

### Evaluation

- [Retrieval evaluation](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/evaluation/runner.py): `src/hybridix/evaluation/runner.py`
- [Evaluation datasets](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/evaluation/dataset_loader.py): `src/hybridix/evaluation/dataset_loader.py`
- [Answer evaluation](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/evaluation/answer_runner.py): `src/hybridix/evaluation/answer_runner.py`
- [RAGAS evaluation](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/evaluation/ragas_runner.py): `src/hybridix/evaluation/ragas_runner.py`

### Other components

- **Questioner**
- **Markdown/MDX**
- [CLI](https://github.com/alihassanwarsi/hybridix/blob/main/src/hybridix/cli.py): `src/hybridix/cli.py`
- **Groq API**

## Connections

- Markdown/MDX → CLI: ingest input (evidence: `README.md`)
- Questioner → CLI: asks question (evidence: `README.md`)
- CLI → Document processing: ingests via (evidence: `src/hybridix/cli.py`)
- Document processing → Document loader: loads files (evidence: `src/hybridix/ingestion/processor.py`)
- Document processing → Heading chunking: chunks documents (evidence: `src/hybridix/ingestion/processor.py`)
- CLI → RAG pipeline: runs query (evidence: `src/hybridix/cli.py`)
- RAG pipeline → Token budgeting: fits chunks (evidence: `src/hybridix/pipeline.py`)
- RAG pipeline → Version builder: builds version (evidence: `src/hybridix/pipeline.py`)
- Version builder → Dense indexer: builds dense (evidence: `src/hybridix/indexing/versioning/builder.py`)
- Version builder → Sparse indexer: builds sparse (evidence: `src/hybridix/indexing/versioning/builder.py`)
- Dense indexer → Embeddings: embeds text (evidence: `src/hybridix/indexing/dense_indexer.py`)
- Dense indexer → Search text: formats search text (evidence: `src/hybridix/indexing/dense_indexer.py`)
- RAG pipeline → Versioned indexes: activates version (evidence: `src/hybridix/pipeline.py`)
- Versioned indexes → Index validator: validates pair (evidence: `src/hybridix/indexing/versioning/active.py`)
- Index validator → Dense indexer: checks dense IDs (evidence: `src/hybridix/indexing/versioning/validator.py`)
- Hybrid RRF search → Versioned indexes: resolves active paths (evidence: `src/hybridix/retrieval/hybrid_retriever.py`)
- Hybrid RRF search → Dense search: requests candidates (evidence: `src/hybridix/retrieval/hybrid_retriever.py`)
- Hybrid RRF search → BM25 search: requests candidates (evidence: `src/hybridix/retrieval/hybrid_retriever.py`)
- Dense search → Dense indexer: queries collection (evidence: `src/hybridix/retrieval/dense_retriever.py`)
- Dense search → Embeddings: embeds query (evidence: `src/hybridix/retrieval/dense_retriever.py`)
- RAG pipeline → Cross-encoder reranker: searches reranked (evidence: `src/hybridix/pipeline.py`)
- Cross-encoder reranker → Hybrid RRF search: reranks results (evidence: `src/hybridix/retrieval/reranker.py`)
- RAG pipeline → Answer generation: generates answer (evidence: `src/hybridix/pipeline.py`)
- Answer generation → Context merging: merges evidence (evidence: `src/hybridix/generation/generator.py`)
- Answer generation → Citation resolution: resolves citations (evidence: `src/hybridix/generation/generator.py`)
- Answer generation → Groq API: calls model (evidence: `README.md`)
- RAG pipeline → Evidence verification: verifies answer (evidence: `src/hybridix/pipeline.py`)
- CLI → Retrieval evaluation: runs retrieval evaluation (evidence: `src/hybridix/cli.py`)
- Retrieval evaluation → Evaluation datasets: loads cases (evidence: `src/hybridix/evaluation/runner.py`)
- Retrieval evaluation → Dense search: evaluates dense (evidence: `src/hybridix/evaluation/runner.py`)
- Retrieval evaluation → BM25 search: evaluates sparse (evidence: `src/hybridix/evaluation/runner.py`)
- Retrieval evaluation → Hybrid RRF search: evaluates hybrid (evidence: `src/hybridix/evaluation/runner.py`)
- Retrieval evaluation → Cross-encoder reranker: evaluates reranked (evidence: `src/hybridix/evaluation/runner.py`)
- Answer evaluation → RAG pipeline: evaluates answers (evidence: `src/hybridix/evaluation/answer_runner.py`)
- RAGAS evaluation → Evaluation datasets: loads evaluation cases (evidence: `src/hybridix/evaluation/ragas_runner.py`)