Metadata-Version: 2.4
Name: freecomai-hybrid-rag
Version: 0.0.0
Summary: Hybrid retrieval-augmented generation — graph × vectorstore → enriched context. Placeholder release.
Author-email: Bolatbek Barmagambetov <barmagambetov.b@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/FreeComAI/hybrid-rag
Project-URL: Repository, https://github.com/FreeComAI/hybrid-rag
Project-URL: Issues, https://github.com/FreeComAI/hybrid-rag/issues
Keywords: rag,graph-rag,hybrid-search,retrieval-augmented-generation,knowledge-graph,ai,llm
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# freecomai-hybrid-rag

> **Hybrid retrieval-augmented generation — graph × vectorstore → enriched context.**

[![PyPI version](https://img.shields.io/pypi/v/freecomai-hybrid-rag)](https://pypi.org/project/freecomai-hybrid-rag/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)

## Status

🚧 **Placeholder release — v0.0.0.** Full API lands in **v0.1.0 (planned Q2-Q3 2026)**.

This package reserves the name `freecomai-hybrid-rag` on PyPI. Do not install for production yet.

## What it will do

A **domain-agnostic Python library** that takes two inputs — a knowledge graph (NetworkX) and a vectorstore (ChromaDB / Qdrant / Pinecone / ...) — and returns enriched search results that combine:

- **Dense retrieval** (semantic similarity top-K chunks)
- **Graph context** (entities mentioned in those chunks + their 1-hop neighbors)
- **Cluster summary** (dominant community the result falls into, with LLM-generated description)
- **Related bugs / decisions / events** from the same cluster

One function call → not just "here are 5 similar chunks", but "here is the full contextual map around your query".

## Why

Vector RAG alone misses structural relationships. GraphRAG (Microsoft pattern, 2024) adds Leiden clustering + community reports but loses fast semantic retrieval. **HybridRAG** (arXiv 2408.04948, NVIDIA + BlackRock, 2024) fuses both — proven superior on financial QA tasks.

This library makes that pattern **plug-and-play** for any domain: your graph, your vectorstore, our enrichment logic.

## Planned API (v0.1.0)

```python
from hybrid_rag import enriched_search, EnrichedResult

result: EnrichedResult = enriched_search(
    graph=my_networkx_graph,
    vectorstore=my_chroma_client,
    query="how did we decide on architecture X?",
    k=5,
)

print(result.dominant_cluster.summary)
for chunk in result.chunks:
    print(chunk.text, chunk.score)
for bug in result.related_bugs:
    print(bug.name, bug.status)
```

## Roadmap

- **v0.0.0** (placeholder) — name reservation
- **v0.1.0** (Q2-Q3 2026) — core `enriched_search()` function
- **v0.2.0** — pluggable cluster summarizers (Claude / GPT / local LLMs)
- **v0.3.0** — optional reranker integration (bge-reranker-v2-m3, Cohere, Jina)
- **v1.0.0** — stable API + comprehensive docs

## Author

Built by [FreeComAI](https://github.com/FreeComAI), Astana, Kazakhstan.
Founder: Bolatbek Barmagambetov (barmagambetov.b@gmail.com).

## License

Apache 2.0 — see [LICENSE](./LICENSE).
