Installation¶

From PyPI (recommended)¶

pip install intersystems-iris-haystack

This installs the core package with two required dependencies:

Optional extras¶

Embedding model¶

The retrievers require embeddings. The recommended free, local model is all-MiniLM-L6-v2 via sentence-transformers:

pip install sentence-transformers

You can use any Haystack-compatible embedder — the DocumentStore itself is model-agnostic.

Development extras¶

For running tests and working on the source code:

pip install intersystems-iris-haystack

This adds pytest, pytest-cov, pytest-asyncio, ruff, mypy, and python-dotenv.

With hatch (contributor workflow)¶

If you are contributing to the project, use hatch to manage isolated environments automatically:

# Install hatch
pip install hatch

# Clone the repository
git clone https://github.com/s-c-ai/iris-haystack.git
cd iris-haystack

# Enter the default dev environment (installs all deps automatically)
hatch shell

# Or run a command directly in the test environment
hatch run test:all

See Development Setup for a full breakdown of all hatch environments.

Verify the installation¶

from intersystems_iris_haystack.document_stores import IRISDocumentStore
from intersystems_iris_haystack.components.retrievers import (
    IRISEmbeddingRetriever,
    IRISBm25Retriever,
)
print("iris-haystack installed correctly")

Version pinning¶

For reproducible deployments, pin the exact version:

pip install "intersystems-iris-haystack==1.0.0"

Or in pyproject.toml / requirements.txt:

dependencies = [
    "intersystems-iris-haystack>=1.0.0,<2.0.0",
]

Upgrading¶

pip install --upgrade intersystems-iris-haystack