victus-rag is operated through the victus-rag CLI.
Typical operational work includes:
The system is currently operated as a local CLI workflow. It does not expose a production
service or deployment runtime.
The primary runtime is a local shell with Python, uv, repository files, and optional
Docker Compose services.
Use this environment for:
Qdrant is required for:
Phoenix is optional and used as an OpenTelemetry collector and trace UI.
Some workflows rely only on local files:
Synthetic BEIR single-specificity generation uses the OpenAI API. This path requires
OPENAI_API_KEY in the environment or repository .env.
uv sync
Inspect the CLI:
uv run victus-rag --help
Build the sparse index:
uv run victus-rag index sparse
Run a sparse query:
uv run victus-rag query sparse --query "mediterranean diet metabolic syndrome" --top-k 5
Start Qdrant:
docker compose up -d qdrant
docker compose ps
Index embedded claims into Qdrant:
uv run victus-rag index qdrant --parquet-path data/claims_embedded.parquet
Run a dense query:
uv run victus-rag query dense --query "mediterranean diet metabolic syndrome" --top-k 5
Limit local embedder CPU threads when needed:
uv run victus-rag query dense \
--query "mediterranean diet metabolic syndrome" \
--cpu-threads 4 \
--cpu-interop-threads 1
Hybrid retrieval requires both a sparse index and a populated Qdrant collection.
uv run victus-rag query hybrid --query "mediterranean diet metabolic syndrome" --top-k 5
uv run victus-rag eval sparse --top-k 5
uv run victus-rag eval dense --top-k 5
uv run victus-rag eval hybrid --top-k 5
Generation requires:
OPENAI_API_KEYuv run victus-rag eval generate-beir --overwrite
uv run victus-rag eval sparse-beir
uv run victus-rag eval dense-beir
uv run victus-rag eval hybrid-beir
uv run victus-rag export claims-csv
Runtime configuration is loaded from:
config/default.yaml
Synthetic BEIR generation defaults are loaded from:
config/beir_generation.yaml
The CLI loads .env from the repository root before executing commands.
Required environment variables:
OPENAI_API_KEY for synthetic BEIR single-specificity query generation.Important runtime configuration areas:
paths: data, index, BEIR, evaluation, and artifact locations.qdrant: Qdrant URL and collection.dense: embedded claim/query Parquet locations and vector settings.query_provider: local, HTTP, or offline Parquet query embedding mode.telemetry: OTLP endpoint, dataset name, and trace enablement.Configuration schema details belong in docs/300-CONTRACTS.md.
CLI commands print runtime results or JSON payloads directly to stdout.
Use help commands to inspect available flags:
uv run victus-rag query sparse --help
uv run victus-rag query dense --help
uv run victus-rag query hybrid --help
uv run victus-rag eval generate-beir --help
Default artifact root:
artifacts/
BEIR metrics and run artifacts are written under:
artifacts/metrics/
artifacts/runs/
Generated BEIR datasets are written under:
data/beir/
Sparse indexes are written under:
data/indexes/
Start Phoenix:
docker compose up -d phoenix
docker compose ps
Phoenix UI:
http://localhost:6006
OTLP gRPC endpoint:
http://localhost:4317
Run an audited retrieval query:
uv run victus-rag query sparse \
--query "diet metabolic syndrome" \
--top-k 1 \
--telemetry \
--dataset-name claims-v1
Expected result:
rag.query trace.Run lightweight validation before handing off changes:
uv run python -m compileall src
uv run victus-rag --help
uv run victus-rag index qdrant --help
uv run victus-rag query sparse --help
uv run victus-rag query dense --help
uv run victus-rag query hybrid --help
There is no committed test suite in the current repository state.
Runtime validation requiring services should only be used when those services are available:
Rebuild the sparse index:
uv run victus-rag index sparse
Inspect local service state:
docker compose ps
docker compose logs qdrant
Restart Qdrant when needed:
docker compose up -d qdrant
Recreate the collection from embedded claims:
uv run victus-rag index qdrant --parquet-path data/claims_embedded.parquet --recreate
Validate the configured Parquet contract:
uv run python -c "from src.config import load_app_config; from src.indexing.parquet_contract import validate_embedded_parquet_schema; c=load_app_config(); validate_embedded_parquet_schema(c.dense.claims_parquet_path, c.parquet_contract)"
Use a local or HTTP query provider, or provide the configured query embeddings Parquet file.
The relevant config area is:
query_provider:
mode: LOCAL_SENTENCE_TRANSFORMERS
Inspect:
data/beir/<dataset>/generation_status.json
If the output directory exists and should be regenerated, rerun with:
uv run victus-rag eval generate-beir --overwrite
Inspect service state:
docker compose ps
docker compose logs phoenix
Emit a minimal trace:
uv run victus-rag query sparse --query "diet metabolic syndrome" --top-k 1 --telemetry
If running inside a sandboxed environment, local OTLP traffic to localhost:4317 may be
blocked. Run the audited query from the host shell.
Dependency import failures:
uv sync.uv run.OpenAI authentication failures:
OPENAI_API_KEY is present in .env or exported in the shell.Dense query model load failures:
sentence-transformers dependencies are installed.ONLINE_HTTP or OFFLINE_PARQUET query provider when appropriate.Empty or invalid query failures:
No compatible relevant IDs during evaluation:
This document owns:
This document does not own:
docs/000-SYSTEM-CONTEXT.md for repository purpose, scope, and vocabulary.docs/100-ARCHITECTURE.md for system shape and component interaction.docs/300-CONTRACTS.md for stable interfaces, guarantees, and artifact expectations.docs/runbooks/ for focused operational procedures.docs/decisions/ for architecture and compatibility decisions.