PolyRAG 🧬

PolyRAG is a modular, multi-paradigm Retrieval-Augmented Generation (RAG) framework designed to unify multiple RAG architectures—from standard Naive 1-Shot RAG and Advanced Multi-Query RAG, to autonomous Agentic RAG and future expansions like GraphRAG.

🏛️ The RAG Class Hierarchy

PolyRAG is architected around an object-oriented class hierarchy rooted in BaseRAG:

                       ┌─────────────────────────┐
                       │         BaseRAG         │
                       │  (Abstract Base Class)  │
                       └────────────┬────────────┘
                                    │
         ┌──────────────────────────┼──────────────────────────┐
         ▼                          ▼                          ▼
  ┌──────────────┐           ┌──────────────┐           ┌──────────────┐
  │   NaiveRAG   │           │ AdvancedRAG  │           │  AgenticRAG  │
  │ (1-Shot RAG) │           │ (Expand/RRF) │           │ (Reflection) │
  └──────────────┘           └──────────────┘           └──────┬───────┘
                                                               │
                                                               ▼
                                                        ┌──────────────┐
                                                        │  ReActAgent  │
                                                        │ (ReActRAG)   │
                                                        └──────────────┘

All derived pipelines inherit shared document ingestion (ingest_text, ingest_file, ingest_directory), vector search (retrieve), and context assembly (format_context) from BaseRAG.

🌟 Key Features

• Multi-Paradigm Pipelines:

  • NaiveRAG: Standard retrieve-then-read pipeline with minimal latency.
  • AdvancedRAG: Multi-query expansion, parallel search, and Reciprocal Rank Fusion (RRF) re-ranking.
  • AgenticRAG: Planning, keyword rewriting, iterative multi-round search, deduplication, and fused self-reflection with source citations.
  • ReActAgent: Structured Thought-Action-Observation reasoning loop with dynamic tool execution.
  • Coming Soon: GraphRAG (knowledge graph entity extraction, community detection, and summarization).

• Native LangChain Foundation:

  • Built directly on top of langchain-core and langchain-text-splitters primitives.
  • Zero-wrapper pluggability: pass ANY LangChain VectorStore (Chroma, Milvus, Pinecone, FAISS, PGVector), Embeddings (OpenAI, HuggingFace, Ollama, Cohere), BaseChatModel (ChatOpenAI, ChatAnthropic, ChatGoogleGenerativeAI, ChatOllama), or TextSplitter directly into PolyRAG pipelines.
  • Full bidirectional compatibility: PolyRAG components can be used anywhere a LangChain runnable or component is expected.

• Dependency Injection:

  • Built-in Container acting as the Composition Root for all services, adapters, and pipelines.
  • Seamless DI resolution and alias mapping for both PolyRAG and LangChain types (VectorStore, Embeddings, BaseChatModel, TextSplitter).
  • Full support for Singleton and Transient scopes, lifecycle management, and 1-line test mocking.

• Clean & Swappable Components:

  • Vector Stores: Built-in InMemoryVectorStore (zero-dependency cosine/L2/dot similarity) or any LangChain VectorStore (Chroma, Milvus, FAISS, Pinecone, PGVector, Qdrant).
  • Chunkers: FixedSizeChunker, RecursiveCharacterChunker (subclassing LangChain's TextSplitter).
  • Embeddings: Built-in FakeEmbeddings for zero-setup local dev or any LangChain Embeddings (OpenAIEmbeddings, HuggingFaceEmbeddings, OllamaEmbeddings, CohereEmbeddings).
  • Chat Models: Standard LangChain BaseChatModel and ChatOpenAI (supporting OpenAI, Anthropic, Gemini, Ollama, Azure, and vLLM).

📚 Documentation

Comprehensive documentation is available in the docs/ directory:

• Getting Started: Installation & Quickstart
• Configuration: Environment Variables, Custom Pipelines, & Dependency Injection Guide
• Guides: Class Hierarchy, Naive RAG, Advanced RAG, Agentic RAG, & ReAct Agent
• Modules: Vector Stores, Embeddings, LLMs, Chunkers, App & Factory
• API Reference: Core Entities, Pipelines, & Services / Container
• Roadmap: GraphRAG & Hybrid Search
• Deep Analysis: Deep Agents Cost & Architecture

📦 Installation

# Minimal installation (core pipelines, DI container, in-memory vector store)
pip install polyrag

# With OpenAI support (langchain-openai)
pip install "polyrag[openai]"

# With ChromaDB vector store (langchain-chroma)
pip install "polyrag[chroma]"

# With Milvus vector store (langchain-milvus)
pip install "polyrag[milvus]"

# With HuggingFace embeddings (langchain-huggingface)
pip install "polyrag[huggingface]"

# Complete installation with all official partner packages
pip install "polyrag[all]"

🚀 Quick Start

1. Instant Setup from Environment (PolyRAG)

from polyrag import PolyRAG

# Automatically loads configuration from environment variables (.env)
app = PolyRAG.from_env()

# Ingest raw text, a file, or an entire folder into the shared store
app.ingest("RFC 1035 specifies DNS domain name syntax.", source="rfc1035.txt")
app.ingest_file("data/rfc9000.txt")
app.ingest_directory("docs/", glob_pattern="*.txt")

# End-to-end question answering (convenience shortcut)
response = app.query("How does DNS translate domain names?")
print("Answer:", response.answer)
print("Sources:", response.sources)

2. Manufacturing Across the Pipeline Hierarchy

Manufacture the exact pipeline strategy you need from the configured setup:

# Level 1: Standard 1-Shot RAG
naive = app.create_naive_rag()
naive_res = naive.query("What is DNS?")

# Level 2: Advanced RAG (Multi-Query Expansion & RRF Re-ranking)
advanced = app.create_advanced_rag(num_expanded_queries=3, top_k=5)
advanced_res = advanced.query("How does DNS handle packet truncation?")

# Level 3: Agentic RAG (Autonomous Multi-Round Loop & Fused Reflection)
agentic = app.create_agentic_rag(max_rounds=2, top_k=3, verbose=True)
agentic_res = agentic.query(
    "What transport protocol does HTTP/3 rely on, and how does connection migration work?"
)

print("Agentic Grounded Answer:\n", agentic_res.answer)
print("Confidence:", agentic_res.confidence)
print("Trajectory:", agentic_res.reasoning_summary)

3. Advanced: Dependency Injection (For Custom Backends & Testing)

from polyrag import (
    Container,
    PolyRAG,
    BaseVectorStore,
    BaseLLMClient,
    InMemoryVectorStore,
)

# 1. Initialize DI Container (Composition Root)
container = Container()

# 2. Register custom implementations or test mocks
container.register_instance(BaseVectorStore, InMemoryVectorStore())
# container.register_instance(BaseLLMClient, MyCustomOllamaLLM())

# 3. Option A: Build pipelines directly with injected dependencies
pipeline = container.build_agentic_rag(top_k=3, max_rounds=2)
response = pipeline.query("Explain TLS 1.3 0-RTT handshakes.")
print(response.answer)

# 3. Option B: Pass to PolyRAG for familiar ingestion & pipeline manufacturing
app = PolyRAG.from_container(container)
app.ingest("RFC 8446 defines the TLS 1.3 protocol.")
advanced = app.create_advanced_rag()

🧪 Testing

PolyRAG includes a complete suite of unit tests verifying all chunkers, stores, pipelines, and the DI container:

pytest tests

🛠️ Building & Publishing

To package PolyRAG for distribution:

# Build wheel and sdist
python -m build

# Upload to PyPI using twine
twine upload dist/*

📄 License

This project is licensed under the MIT License.