Install¶

Cairn needs Python 3.10 or newer. The base install runs the whole pipeline with the deterministic stub provider and the hashing embedder, so it needs no API key, no model download and no network.

pip install cairn-pipeline

The command line is cairn, because that is what a person types.

Extras¶

Each extra adds one capability. Install only the ones a configuration names; a component whose dependency is missing raises an error saying which extra provides it, rather than failing somewhere further in.

Extra	Brings	Needed for
`local`	a local sentence-transformer and a cross-encoder	the `sentence_transformers` embedder, the `cross_encoder` reranker
`faiss`	a FAISS vector index	`index.backend: faiss`
`qdrant`	a Qdrant client	`index.backend: qdrant`
`openai`	the hosted client used by the `openai` provider and embedder	`configs/hybrid-openai.yaml`
`anthropic`	the hosted client used by the `anthropic` provider	`configs/hybrid-anthropic.yaml`
`serve`	the HTTP service, Prometheus metrics, OpenTelemetry	`cairn serve`
`pdfgen`	PDF generation	generating the sample corpus (`cairn init`, `cairn corpus generate`)
`dev`	the test tools, plus `serve` and `pdfgen`	working on Cairn itself
`all`	every extra above	trying everything

pip install "cairn-pipeline[local]"          # local models
pip install "cairn-pipeline[serve]"          # the HTTP service
pip install "cairn-pipeline[dev]"            # developing Cairn

Check the installation¶

cairn doctor

doctor reports which extras are installed, which components are registered, whether the configuration's corpus and golden set exist, whether an index has been built, and whether each provider is usable. It contacts only the local model daemon, on its free listing endpoint. Hosted providers are reported by whether their client is installed and a key is present in the environment: a reachability check that spends money is a bill, not a diagnostic.

Providers¶

Provider	Configuration	Environment
`stub`	nothing	none; deterministic and free
`ollama`	`configs/hybrid-ollama.yaml`	`OLLAMA_HOST`, default `http://127.0.0.1:11434`
`openai`	`configs/hybrid-openai.yaml`	`OPENAI_API_KEY`
`anthropic`	`configs/hybrid-anthropic.yaml`	`ANTHROPIC_API_KEY`

The stub is not a toy. It is deterministic and extractive: given the passages, it selects the sentence with the highest overlap with the question and cites its span. That makes the whole pipeline, including citation verification, calibration and the gate, runnable and testable with no model at all, which is how the published numbers reproduce.

From source¶

git clone https://github.com/rhs2/cairn
cd cairn
make install
make check

make install creates a virtualenv and installs the package with the dev extra. make check runs the linter, the type checker and the offline test suite: the same three things CI runs before it runs the pipeline itself.

The sample corpus is generated, not checked out. make ingest, make bench and the other pipeline targets run cairn corpus generate when data/sample is absent; make sample does it explicitly.

Documentation locally¶

The documentation site is built with a separate virtualenv so its dependencies never mix with the package's:

make install-docs
make docs