Installation
Install RAGSpine on Python 3.11+, choose optional capabilities deliberately, and distinguish a PyPI release from the repository version.
RAGSpine requires Python 3.11 or newer. The repository currently declares version 0.11.0;
that is not a guarantee that PyPI has published the same version. After installation, run
ragspine version to see the selected distribution.
PyPI installation
uv add rag-spine
# or
python -m pip install rag-spineThe distribution name is rag-spine; the import and console-command names are ragspine:
import ragspineTo request the project's aggregate runtime extra in one command:
uv add "rag-spine[all]"[all] aggregates the runtime extras listed in pyproject.toml; it deliberately excludes
development tooling. It also does not include the separately opt-in [ppt] or heavy
[pdf-docling] alternatives. Add either explicitly when required, for example:
uv add "rag-spine[all,ppt,pdf-docling]"Optional extras
| Extra | Main capability |
|---|---|
[service] | FastAPI, uvicorn, HTTP test/client support, RQ, and Redis |
[pdf] / [pdf-docling] | Default pdfspine extraction / heavy Docling fallback |
[ocr] | PaddleOCR; the CUDA-specific Paddle runtime is installed separately |
[doc] / [ppt] | docspine DOCX / opt-in pptspine PPTX extraction |
[llm] | Anthropic and OpenAI SDK adapters |
[embed] / [embed-onnx] | sentence-transformers / FastEmbed ONNX embeddings |
[rerank], [colbert], [splade], [colpali] | optional neural reranking or visual-document representation |
[vector] / [graph] | sqlite-vec, pgvector, Qdrant / NetworkX adapters |
[otel] | OpenTelemetry trace export |
[connectors] | HTTP and Notion source connectors |
[dify] | Dify compiler boundary validation with Pydantic 2 |
[dev] | tests, lint/type checks, docs, build, and Twine |
PyYAML is a base dependency because workflow JSON/YAML wire-format support is part of the base
CLI. TOML reading uses Python 3.11's tomllib. The Dify compiler adds Pydantic 2 through
[dify]; [service] also uses modern FastAPI (>=0.110) and therefore Pydantic 2.
An application pinned to fastapi>=0.99,<0.100 and pydantic>=1.10,<2 cannot install
RAGSpine's modern service or Dify extras in the same environment. Keep that application in its
existing environment and run RAGSpine's service in a separate virtual environment or process.
A base rag-spine install does not itself require Pydantic 2.
ONNX extras may download model weights on first use and cache them for later offline runs.
[ocr] is primarily intended for Linux/NVIDIA deployments. ColPali model weights have their own
license; installing an Apache-licensed Python dependency does not change a model's license.
Install current source
Run these commands from the cloned repository root:
git clone https://github.com/VoldemortGin/ragspine.git
cd ragspine
uv venv .venv
uv pip install --python .venv/bin/python -e ".[dev,service,vector]"On Windows, use .venv\\Scripts\\python.exe in the final command. The Make targets are
conveniences for Unix-like development environments:
make venv
make installmake install selects [dev,service,vector]. Despite its name, make install-all selects
[dev,service,vector,llm,embed]; it is not the same set as the published [all] extra.
Offline boundary
A base install can run the structured channel, deterministic orchestration, catalog browsing, lexical workflow matching, workflow generation, format normalization, and graph preview without an API key. Real model providers, remote connectors, Redis, external vector databases, and first model downloads are opt-in networked capabilities.
Introduction
RAGSpine is an offline-first Python RAG engine with deterministic dual-channel retrieval, provenance, workflow scaffolding, and optional HTTP compatibility surfaces.
Quickstart
Run the deterministic demo, scaffold a Dify-compatible workflow, call the Python API, and start the optional service.