// 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.
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.
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.
| name | ragnarok-quickstart |
| description | 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. |
Reference for the ragnarok CLI — the tool for RAG answer generation with citation support, TREC evaluation, and multi-stage retrieval pipelines.
ragnarok <command> [options]
| Command | Purpose |
|---|---|
generate | Generate cited answers from query + candidate passages |
validate | Validate request payloads or TREC RAG output files |
convert | Convert output to TREC submission formats |
| Command | Purpose |
|---|---|
doctor | Check Python version, API keys, backend readiness |
describe <cmd> | Machine-readable command contract |
schema <name> | Print JSON Schema for inputs/outputs |
prompt list|show|render | Inspect and render prompt templates |
view <path> | Inspect existing artifact files |
ragnarok generate --input-file requests.jsonl --output-file answers.jsonl \
--model gpt-4o --prompt-mode ragnarok_v4
ragnarok generate --dataset rag24.raggy-dev \
--retrieval-method bm25,rank_zephyr_rho --topk 100,20 \
--model gpt-4o --prompt-mode ragnarok_v4 --output-file answers.jsonl
Read these on demand for details:
references/cli-examples.md — Common invocations for each commandreferences/input-output-examples.md — JSONL format examplesreferences/prompt-modes.md — Prompt mode descriptions and selection guidereferences/dataset-workflow.md — Dataset-backed generation detailsragnarok_v4, chatqa)citations array referencing candidate indices100,20 = retrieve 100, rerank to 20)command-r* models), open-source (llama, mistral, qwen)--model and --prompt-mode are both required for generate.--dataset mode does not support --execution-mode async yet.--topk is comma-separated: first value is retrieval depth, last value is generation depth. For file-backed mode, only the last value matters.command-r* → Cohere backend, llama/mistral/qwen → open-source backend, everything else → OpenAI-compatible.--retrieval-method is comma-separated and must align with --topk for multi-stage pipelines.validate rag25-output) has --fix-length, --fix-citations, and --apply-fixes flags for repairing submissions..ragnarok.toml or ~/.config/ragnarok/config.toml) can set defaults; CLI flags override.