IRIS Vector RAG

RAG (Retrieval-Augmented Generation) pipelines powered by InterSystems IRIS vector search.

Author: Thomas Dyar (thomas.dyar@intersystems.com)

Quick Start

# 1. Clone and install
git clone https://github.com/intersystems-community/iris-vector-rag.git
cd iris-vector-rag
pip install -e .

# 2. Start IRIS
docker compose up -d

# 3. Configure
cp .env.example .env
# Edit .env — add your OPENAI_API_KEY

# 4. Query
python -c "
from iris_vector_rag import create_pipeline
from iris_vector_rag.core.models import Document

pipeline = create_pipeline('basic')
pipeline.load_documents(documents=[
    Document(page_content='RAG combines retrieval with generation for accurate AI.', metadata={'source': 'intro.pdf'}),
    Document(page_content='Vector search finds similar content using embeddings.', metadata={'source': 'vectors.pdf'}),
])
result = pipeline.query('What is RAG?', top_k=5, generate_answer=True)
print(result['answer'])
"

Pipelines

All pipelines share the same interface — switch with one line:

from iris_vector_rag import create_pipeline

pipeline = create_pipeline('basic')           # Vector similarity search
pipeline = create_pipeline('basic_rerank')    # + cross-encoder reranking
pipeline = create_pipeline('crag')            # + self-correction + web fallback
pipeline = create_pipeline('graphrag')        # + knowledge graph + entity reasoning
pipeline = create_pipeline('multi_query_rrf') # + query expansion + rank fusion
pipeline = create_pipeline('pylate_colbert')  # + ColBERT late interaction

Pipeline	Method	Best For
`basic`	Vector similarity	General Q&A, getting started
`basic_rerank`	Vector + reranking	Higher accuracy, medical/legal
`crag`	Vector + evaluation + web	Fact-checking, current events
`graphrag`	Vector + text + graph + RRF	Complex relationships, research
`multi_query_rrf`	Query expansion + fusion	Comprehensive coverage
`pylate_colbert`	ColBERT embeddings	Fine-grained matching

Response Format

All pipelines return the same structure (LangChain/RAGAS compatible):

result = pipeline.query("What is diabetes?", top_k=5)

result["answer"]                # LLM-generated answer
result["retrieved_documents"]   # List[Document]
result["contexts"]              # List[str] — for RAGAS evaluation
result["sources"]               # Source citations
result["metadata"]              # Timing, pipeline type, method used

Configuration

Environment variables (loaded automatically from .env):

OPENAI_API_KEY=sk-...          # Required for answer generation
IRIS_HOST=localhost             # IRIS SuperServer host
IRIS_PORT=1972                  # IRIS SuperServer port
IRIS_NAMESPACE=USER             # IRIS namespace
IRIS_USERNAME=_SYSTEM           # IRIS username
IRIS_PASSWORD=SYS               # IRIS password

Evaluate with RAGAS

Compare pipelines side-by-side using real RAGAS metrics:

python examples/compare_pipelines.py --pipelines basic,basic_rerank

Or in code:

from iris_vector_rag import create_pipeline
from ragas import evaluate, EvaluationDataset, SingleTurnSample
from ragas.metrics import faithfulness, context_precision, context_recall

pipeline = create_pipeline('basic')
pipeline.load_documents(documents=docs)
result = pipeline.query("What is diabetes?", top_k=3, generate_answer=True)

sample = SingleTurnSample(
    user_input="What is diabetes?",
    response=result["answer"],
    retrieved_contexts=result["contexts"],
    reference="Diabetes is a chronic condition...",
)
scores = evaluate(EvaluationDataset(samples=[sample]),
                  metrics=[faithfulness, context_precision, context_recall])

Optional Extras

pip install iris-vector-rag[colbert]     # ColBERT/PyLate support
pip install iris-vector-rag[dspy]        # DSPy prompt optimization
pip install iris-vector-rag[evaluation]  # RAGAS evaluation framework
pip install iris-vector-rag[api]         # REST API server (FastAPI + Redis)

MCP Server

The MCP server is implemented and available at iris_vector_rag/mcp/. It exposes 8 tools (rag_basic, rag_basic_rerank, rag_crag, rag_graphrag, rag_pylate_colbert, rag_iris_global_graphrag, rag_health_check, rag_metrics) over the Model Context Protocol.

pip install iris-vector-rag[mcp]
python -m iris_vector_rag.mcp start       # start server
python -m iris_vector_rag.mcp list-tools  # list available tools
python -m iris_vector_rag.mcp status      # server status

For MCP tool orchestration across IRIS packages, use iris-agentic-dev.

Development

pip install -e ".[dspy,evaluation]"
pytest tests/unit/                    # Fast, no IRIS needed
pytest tests/unit/ tests/contract/    # Full suite, needs IRIS running

Architecture

iris_vector_rag/
├── pipelines/      # 6 RAG implementations (basic, crag, graphrag, etc.)
├── core/           # Base classes, models, connection management
├── storage/        # IRIS vector store, schema management
├── embeddings/     # Embedding generation and caching
├── services/       # Entity extraction, storage adapters
├── config/         # Configuration management
├── mcp/            # MCP server implementation
└── api/            # Optional REST API (FastAPI)

License

MIT

Metadata

Release files for iris-vector-rag 0.14.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for iris-vector-rag 0.14.1
File	Size	Uploaded
iris_vector_rag-0.14.1.tar.gz	383.6 kB	Sep 7, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for iris-vector-rag 0.14.1
File	Interpreter	ABI	Platform	Reset
iris_vector_rag-0.14.1-py3-none-any.whl 419.6 kB Sep 7, 2026	Python 3	none	any	Details

Total release size: 803.1 kB

Release files / iris_vector_rag-0.14.1.tar.gz

Download URL	iris_vector_rag-0.14.1.tar.gz
Size	383.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`75d10ac3d3d1ca6238a0ca5f066faa8322476877d79b7a08f1346f7714768c7e`
BLAKE2b-256 checksum How to use checksums	`e3aae77bb9e005bda57a9ac0fda798f1df2a38e5e357838a2471ef0304ea4254`
Upload date	Sep 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/intersystems-community/iris-vector-rag
Publishing commit: github.com/intersystems-community/iris-vector-rag/tree/870d06c84951fad655e2741bfa849300adb59558

Workflow

Publishing configuration: github.com/intersystems-community/iris-vector-rag/blob/870d06c84951fad655e2741bfa849300adb59558/.github/workflows/release.yml
Publishing logs: github.com/intersystems-community/iris-vector-rag/actions/runs/34156256382/attempts/1

Artifact

Subject: iris_vector_rag-0.14.1.tar.gz
SHA-256 checksum: 75d10ac3d3d1ca6238a0ca5f066faa8322476877d79b7a08f1346f7714768c7e Verifying attestations

Release files / iris_vector_rag-0.14.1-py3-none-any.whl

Download URL	iris_vector_rag-0.14.1-py3-none-any.whl
Size	419.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`d75e14c569bae3eb55b2289c3682979468e3275f9c68d0f47595ce2c5bfe87b2`
BLAKE2b-256 checksum How to use checksums	`c7411468f49a06271d9c9534ce2241a535817da7bf227db88f07ca2981c9679e`
Upload date	Sep 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/intersystems-community/iris-vector-rag
Publishing commit: github.com/intersystems-community/iris-vector-rag/tree/870d06c84951fad655e2741bfa849300adb59558

Workflow

Publishing configuration: github.com/intersystems-community/iris-vector-rag/blob/870d06c84951fad655e2741bfa849300adb59558/.github/workflows/release.yml
Publishing logs: github.com/intersystems-community/iris-vector-rag/actions/runs/34156256382/attempts/1

Artifact

Subject: iris_vector_rag-0.14.1-py3-none-any.whl
SHA-256 checksum: d75e14c569bae3eb55b2289c3682979468e3275f9c68d0f47595ce2c5bfe87b2 Verifying attestations