alihassanwarsi/hybridix

How alihassanwarsi/hybridix works

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: pipeline.py RAG pipeline · runner.py Retrieval evaluation · cli.py CLI · hybrid_retriever.py Hybrid RRF search

Components 28

Ingestion

Document processing src/hybridix/ingestion/processor.py
Document loader src/hybridix/ingestion/loader.py
Heading chunking src/hybridix/ingestion/chunking.py

Indexing

Token budgeting src/hybridix/indexing/token_budget.py
Version builder src/hybridix/indexing/versioning/builder.py
Dense indexer src/hybridix/indexing/dense_indexer.py
Embeddings src/hybridix/indexing/embeddings.py
Search text src/hybridix/indexing/search_text.py
Sparse indexer src/hybridix/indexing/sparse_indexer.py
Versioned indexes src/hybridix/indexing/versioning/active.py
Index validator src/hybridix/indexing/versioning/validator.py

Retrieval

Hybrid RRF search src/hybridix/retrieval/hybrid_retriever.py
Dense search src/hybridix/retrieval/dense_retriever.py
BM25 search src/hybridix/retrieval/sparse_retriever.py
Cross-encoder reranker src/hybridix/retrieval/reranker.py

Answering

RAG pipeline src/hybridix/pipeline.py
Answer generation src/hybridix/generation/generator.py
Context merging src/hybridix/generation/context.py
Citation resolution src/hybridix/generation/citations.py
Evidence verification src/hybridix/generation/evidence_verifier.py

Evaluation

Retrieval evaluation src/hybridix/evaluation/runner.py
Evaluation datasets src/hybridix/evaluation/dataset_loader.py
Answer evaluation src/hybridix/evaluation/answer_runner.py
RAGAS evaluation src/hybridix/evaluation/ragas_runner.py

Other components

Questioner
Markdown/MDX
CLI src/hybridix/cli.py
Groq API

Connections 35

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

Drawn by GitDiagram on November 11, 2026 from the repository's file tree, README and source files. Read as Markdown ·