RAG-Templates

🎯 Project Status: Complete & Ready for Integration

RAG-Templates is now complete as a reusable framework with all core components delivered:

• ✅ 6 Production RAG Pipelines with standardized API
  • BasicRAG - Standard vector similarity search
  • BasicRAGReranking - Vector search with cross-encoder reranking
  • CRAG - Corrective RAG with self-evaluation
  • HybridGraphRAG - Graph + vector + text hybrid search with RRF fusion
  • PyLateColBERT - ColBERT late interaction retrieval
  • IRIS-Global-GraphRAG - Academic papers with 3D visualization
• ✅ 100% Test Coverage (136/136 tests passing)
  • Contract tests for API validation
  • Integration tests with live database
  • E2E workflow validation
• ✅ Unified API Surface - Consistent interfaces across all pipelines
• ✅ Enterprise IRIS Backend with connection pooling and mode detection
• ✅ LangChain & RAGAS Compatible - Standard Document objects and metadata

Documentation: 📑 Full Documentation Index

Quick Links:

• 📖 API Reference - Complete API documentation with examples
• 📚 User Guide - Step-by-step installation and usage
• 🧪 Test Validation Summary - 100% test pass rate (136/136)
• 🔗 Integration Guide - How to integrate into your app
• 🏗️ Architecture Summary - System design
• 🚀 Production Readiness - Deployment checklist

Quick Start

# 1. Clone and setup environment
git clone 
cd rag-templates
make setup-env  # Creates .venv using uv
make install    # Installs dependencies
2. Activate environment
source .venv/bin/activate  # Windows: .venv\Scripts\activate
3. Start database
docker-compose up -d
4. Initialize database
make setup-db

make load-data
5. Create .env file with API keys
cat > .env << 'EOF'

OPENAI_API_KEY=your-key-here

IRIS_HOST=localhost

IRIS_PORT=1972

EOF
6. Try different pipelines
python -c "

from iris_rag import create_pipeline
Basic RAG - simplest approach
pipeline = create_pipeline('basic')

result = pipeline.query('What is machine learning?', top_k=5)

print(result['answer'])

"

🔬 Test Fixture Quick Start

RAG-Templates uses binary .DAT fixtures for fast, reproducible testing. .DAT fixtures are 100-200x faster than JSON fixtures (0.5-2 seconds vs 39-75 seconds for 100 entities).

Why .DAT Fixtures?

• Speed: Binary IRIS format loads in seconds instead of minutes
• Reproducibility: Checksums ensure identical database state across test runs
• Isolation: Each test gets a clean, versioned database snapshot
• No LLM Required: Pre-computed embeddings and entities included

Quick Fixture Workflow

# 1. List available fixtures
make fixture-list
Example output:
Name                           Version    Type     Tables          Rows     Embeddings
----------------------------------------------------------------------------------------------
medical-graphrag-20            1.0.0      dat      3 tables        39       Required
2. Get detailed fixture information
make fixture-info FIXTURE=medical-graphrag-20
3. Load fixture into IRIS database
make fixture-load FIXTURE=medical-graphrag-20
4. Validate fixture integrity
make fixture-validate FIXTURE=medical-graphrag-20

Using Fixtures in Tests

Automatic Loading (Recommended):

import pytest
@pytest.mark.dat_fixture("medical-graphrag-20")

def test_with_fixture():

# Fixture automatically loaded before test

# Database contains 21 entities, 15 relationships, pre-computed embeddings

pipeline = create_pipeline("graphrag")

result = pipeline.query("What are cancer treatment targets?")

assert len(result["retrieved_documents"]) > 0

Manual Loading:

from tests.fixtures.manager import FixtureManager
def test_manual_fixture_load():

manager = FixtureManager()

result = manager.load_fixture(

fixture_name="medical-graphrag-20",

cleanup_first=True,           # Clean database first

validate_checksum=True,        # Verify fixture integrity

generate_embeddings=False,     # Already included in .DAT

)
assert result.success
assert result.rows_loaded == 39   # Total rows across all tables

Creating Your Own Fixtures

# 1. Populate IRIS with test data (manually or via script)
python scripts/load_test_data.py
2. Create fixture from current database state
make fixture-create FIXTURE=my-test-data
Interactive mode (recommended for first-time users):
python -m tests.fixtures.cli workflow
Command-line mode:
python -m tests.fixtures.cli create my-fixture 

--tables RAG.SourceDocuments,RAG.Entities,RAG.EntityRelationships 

--description "My test fixture" 

--generate-embeddings

Fixture Management CLI

# Full CLI help
python -m tests.fixtures.cli --help
Common commands:
python -m tests.fixtures.cli list                     # List all fixtures

python -m tests.fixtures.cli info medical-graphrag-20 # Fixture details

python -m tests.fixtures.cli load medical-graphrag-20 # Load fixture

python -m tests.fixtures.cli validate my-fixture      # Validate integrity

python -m tests.fixtures.cli snapshot snapshot-20250114  # Quick DB snapshot

Constitutional Requirement

All integration and E2E tests with ≥10 entities MUST use .DAT fixtures (see .specify/memory/constitution.md for complete IRIS testing principles).

Decision Tree:

• Unit tests → Use programmatic fixtures (Python code)
• Integration tests with < 10 entities → Use programmatic fixtures
• Integration tests with ≥ 10 entities → Use .DAT fixtures (REQUIRED)
• E2E tests → Use .DAT fixtures (REQUIRED)

Documentation:

• Complete Guide: tests/fixtures/README.md
• Examples: examples/fixtures/basic_usage.py
• Constitution: .specify/memory/constitution.md (Principle II)

📖 Unified API Reference

All pipelines follow a consistent, standardized API:

Creating Pipelines

from iris_rag import create_pipeline
Available pipeline types:
- "basic"          : BasicRAG (vector similarity)
- "basic_rerank"   : BasicRAG + cross-encoder reranking
- "crag"           : Corrective RAG with self-evaluation
- "graphrag"       : HybridGraphRAG (vector + text + graph)
- "pylate_colbert" : ColBERT late interaction
pipeline = create_pipeline(

pipeline_type="basic",

validate_requirements=True,  # Auto-validate DB setup

auto_setup=False,            # Auto-fix issues if True

)

Loading Documents

from iris_rag.core.models import Document
Option 1: From Document objects
docs = [

Document(

page_content="Python is a programming language...",

metadata={"source": "intro.txt", "author": "John"}

)

]

result = pipeline.load_documents(documents=docs)
Option 2: From file path
result = pipeline.load_documents(documents_path="data/docs.json")
Returns: {"documents_loaded": 10, "embeddings_generated": 10, "documents_failed": 0}

Querying

# Standard query signature for ALL pipelines
result = pipeline.query(
    query="What is machine learning?",
    top_k=5,                    # Number of documents to return (1-100)
    generate_answer=True,       # Generate LLM answer (default: True)
    include_sources=True,       # Include source metadata (default: True)
)
Standardized response format (LangChain & RAGAS compatible):
{

"query": "What is machine learning?",

"answer": "Machine learning is...",                 # LLM-generated answer

"retrieved_documents": [Document(...)],             # LangChain Document objects

"contexts": ["context 1", "context 2"],             # RAGAS-compatible contexts

"sources": [{"source": "file.txt", ...}],           # Source references

"execution_time": 0.523,

"metadata": {

"num_retrieved": 5,

"pipeline_type": "basic",

"retrieval_method": "vector",

"context_count": 5,

...

}

}

Pipeline-Specific Features

# BasicRAGReranking - Control reranking behavior
pipeline = create_pipeline("basic_rerank")
result = pipeline.query(query, top_k=5)  # Retrieves rerank_factor*5, returns top 5
CRAG - Retrieval evaluation
pipeline = create_pipeline("crag")

result = pipeline.query(query, top_k=5, generate_answer=True)
HybridGraphRAG - Multi-modal search
pipeline = create_pipeline("graphrag")

result = pipeline.query(

query_text="cancer targets",

method="rrf",        # rrf, hybrid, vector, text, graph

vector_k=30,

text_k=30

)
PyLateColBERT - Late interaction retrieval
pipeline = create_pipeline("pylate_colbert")

result = pipeline.query(query, top_k=5)  # Uses ColBERT late interaction

🧪 Testing & Quality Assurance

The RAG-Templates framework includes comprehensive testing tools to ensure code quality and maintainability:

Testing Compliance Tools

Coverage Warnings - Automated coverage monitoring without failing builds

• Warns when modules fall below 60% coverage (80% for critical modules)
• Configure critical modules in .coveragerc
• Detailed Documentation

Error Message Validation - Ensures helpful test failure messages

• Validates three-part structure: What failed, Why, and Action to take
• Provides improvement suggestions for unclear messages
• Best Practices Guide

TDD Compliance - Validates Test-Driven Development workflow

• Ensures contract tests failed before implementation
• Integrates with CI/CD for automated checking
• TDD Workflow Guide

Running Tests

# Run all tests with coverage
pytest --cov=iris_rag --cov=common
Run specific test categories
pytest tests/unit/          # Unit tests only

pytest tests/integration/   # Integration tests

pytest tests/contract/      # Contract tests
Validate TDD compliance
python scripts/validate_tdd_compliance.py
Check requirement-task mapping
python scripts/validate_task_mapping.py --spec specs//spec.md --tasks specs//tasks.md

Pre-commit Hooks

Install pre-commit hooks for automated quality checks:

pip install pre-commit
pre-commit install

This enables:

• TDD compliance checking on contract test commits
• Requirement-task mapping validation
• Code formatting (black, isort)
• Error message quality reminders

📚 References & Research

RAG Technique Papers & Implementations

Core Technologies

• Vector Databases: InterSystems IRIS Vector Search
• Embeddings: Sentence Transformers, OpenAI Embeddings
• LLM Integration: LangChain, OpenAI API

📄 License

MIT License - see https://github.com/intersystems-community/iris-vector-rag/blob/master/LICENSE file for details.