CLI & Scripts
Reference for the make targets and the developer entry-point scripts — ask, demo, server, worker, evals, and fixtures.
RAGSpine wraps its common dev and CI/CD commands in a root Makefile, a thin discoverable
layer over the raw scripts in scripts/. Run make help to list every target.
Always run from the repo root. The scripts anchor on a .project-root marker — running from a
subfolder breaks path resolution. You can read files anywhere, but invoke from root.
Every target defaults to the project venv interpreter (.venv/bin/python). Override it with
make <target> PYTHON=python3.12 (the override is passed through to scripts/ci.sh and
scripts/lint.sh too).
Make targets
| Command | What it does |
|---|---|
make venv | uv venv .venv — create the project venv |
make install | editable install with [dev,service] extras (the usual dev setup) |
make install-all | editable install with [dev,service,llm,embed] (adds real LLM + embeddings) |
make hooks | git config core.hooksPath .githooks — enable the pre-push CI gate (one-time per clone) |
| Command | What it does |
|---|---|
make ci | the gate: tests (-m "not gpu") + demo smoke — exactly what the pre-push hook runs |
make test | pytest tests/ -q -m "not gpu" |
make lint | ruff + mypy (informational, non-blocking — not wired into the gate) |
make fmt | ruff check --fix then ruff format over src/ragspine, scripts, tests |
make drift | flag docs whose covered code changed since last verified (scripts/check_doc_drift.py) |
GitHub Actions is dormant (manual-trigger only) to avoid consuming minutes — the local gate is
authoritative. scripts/ci.sh is the single source of truth for "is it green".
| Command | What it does |
|---|---|
make demo | run the offline end-to-end demo — expects ALL CHECKS PASSED |
make ask Q="…" | ask offline via MockProvider, e.g. make ask Q="中国内地FY2024的REVENUE是多少" |
make eval-qa | QA evaluation against the golden set (baseline-gated) |
make eval-retrieval | BM25-vs-hybrid retrieval A/B harness |
| Command | What it does |
|---|---|
make serve | run the FastAPI server (scripts/run_server.py) |
make worker | run the RQ worker (scripts/run_worker.py) — needs Redis running |
There are also housekeeping and release targets: make fixtures (regenerate synthetic demo
data, deterministic), make docs (build the static API-reference site), make clean, and
make build / make publish / make publish-test for packaging.
Entry-point scripts
The make targets above are wrappers — here are the underlying scripts and their real flags.
scripts/ask.py
Single-question CLI: intent parse → clarification gateway → tool-use loop → definite value +
lineage. mock mode is offline and deterministic and needs no API key.
.venv/bin/python scripts/ask.py --provider mock --db data/fact_metric.db "香港去年REVENUE多少"| Argument | Default | Purpose |
|---|---|---|
question (positional) | — | the user question |
--provider | mock | mock (offline, deterministic) or anthropic (real Claude) |
--db | the default fact DB | path to the fact_metric sqlite store |
--chunk-db | None | narrative chunk-store path; when set, narrative/composite questions use real retrieval (BM25 + RRF + listwise rerank) — otherwise the narrative channel degrades honestly |
--embedding | none | vector-channel backend: none (pure BM25), deterministic (offline lexical-hash, non-semantic), or openai (needs the SDK + config) |
--reference-date | today | base date YYYY-MM-DD for relative-period resolution |
--model | the default Anthropic model | model name for the anthropic provider |
--base-url | None | override the Anthropic API base URL (for an enterprise gateway) |
scripts/run_demo.py
Offline end-to-end demo — generate synthetic data, extract, ingest, query, assert against
ground truth. No flags; prints ALL CHECKS PASSED on success, exits non-zero on any mismatch.
.venv/bin/python scripts/run_demo.pyscripts/run_server.py
Starts the FastAPI app under uvicorn. Configuration is injected via RAGSPINE_* environment
variables (see Configuration); requires the [service] extra.
RAGSPINE_DB_PATH=data/fact_metric.db .venv/bin/python scripts/run_server.py --host 0.0.0.0 --port 8000| Argument | Default | Purpose |
|---|---|---|
--host | 127.0.0.1 | listen address |
--port | 8000 | listen port |
scripts/run_worker.py
RQ worker that consumes the ingestion-job queue out-of-process. Needs Redis reachable and the
[service] extra. The worker owns its own stores per job.
RAGSPINE_REDIS_URL=redis://localhost:6379/0 .venv/bin/python scripts/run_worker.py| Argument | Default | Purpose |
|---|---|---|
--queue | ragspine-ingest | queue name (must match the RQQueue default) |
Next steps
Quickstart
Run the offline demo, ask a question with the deterministic MockProvider, use the Python API, and start the HTTP service plus async worker.
Dual Channel
A deterministic structured/numeric channel and a narrative RAG channel, unified by one agent router that splits composite questions and runs both.