// Set up a ragnarok development environment — checks Python 3.11+, installs via uv or pip with cloud extras, and verifies with doctor. Use when someone is onboarding, setting up a fresh clone, or troubleshooting their environment.
| name | ragnarok-install |
| description | Set up a ragnarok development environment — checks Python 3.11+, installs via uv or pip with cloud extras, and verifies with doctor. Use when someone is onboarding, setting up a fresh clone, or troubleshooting their environment. |
Development environment setup for ragnarok — RAG answer generation and TREC evaluation.
github.com:castorini)python3 --version # must be 3.11+
command -v uv # if present, use uv path; otherwise recommend uv
If uv is on PATH, use it silently. If not, ask the user once: install uv or proceed with pip.
If no pyproject.toml in cwd:
git clone git@github.com:castorini/ragnarok.git && cd ragnarok
uv venv --python 3.11
source .venv/bin/activate
uv sync --group dev --extra cloud
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[cloud]"
pip install pre-commit pytest
pip install pyragnarok
Note: the PyPI package name is pyragnarok, not ragnarok.
ragnarok doctor --output json
ragnarok --help
pre-commit install
references/extras.md — Optional dependency stacks (cloud, local, api, pyserini)pyragnarok on PyPI, but the CLI binary and import name are both ragnarok.[dependency-groups] — only uv sync --group dev resolves them natively. With pip, install each package manually.local extra pulls in PyTorch, vLLM, and transformers — large downloads, only needed for local model inference.test/ (no trailing s).Use when working with ragnarok dataset-backed generation — retrieval configuration, pyserini dependency setup, topk multi-stage pipelines, dataset naming conventions, and retrieval method selection. Use when setting up or debugging dataset-backed workflows.
Use when validating ragnarok generate outputs — checks TREC format compliance, citation integrity (valid indices, non-empty references), response length bounds, and JSONL structure. Wraps `ragnarok validate` plus custom assertions. Use after running generate or convert to verify output correctness.
Use when working with ragnarok CLI commands (generate, validate, convert), prompt modes (chatqa, ragnarok_v4, etc.), dataset-backed or file-backed generation, TREC RAG output formats, or introspection (doctor, describe, schema). Covers all entry points, flags, and generation workflows.