Installation, configuration, the complete CLI surface, the HTTP API with its event catalog, sessions and recall, authentication, verticals and Docker.
# recommended: uv uv sync # or pip pip install ragstack # optional extras uv sync --extra neo4j # Neo4j graph backend driver uv sync --extra dev # pytest + ruff for contributors
Pick a stack mode by copying config.example.yaml → ragstack.yaml: local (needs Ollama running), hybrid (local search + cloud LLM via OPENAI_API_KEY/ANTHROPIC_API_KEY) or cloud. Any OpenAI-compatible server (vLLM, LM Studio) works through llm.base_url.
| Command | What it does |
|---|---|
ragstack index PATHS... | Index files/folders. Flags: |
ragstack crawl URL | Crawl + index a site. |
ragstack query QUESTION | Ask. |
ragstack watch PATHS... | Poll paths every N seconds ( |
ragstack serve | Web console + HTTP API. |
ragstack modes | The eight-mode catalog with tools/pipeline per mode (also |
ragstack sessions | List conversation sessions with turn counts. |
ragstack forget [SESSION] | Delete conversation turns (and all recall entries when no session given). |
ragstack db NAME URL | Register a database for text-to-SQL (e.g. |
ragstack bench --docs N | Synthetic-corpus self-benchmark: indexing throughput, retrieval latency p50/p95, hit@k, MRR. |
ragstack eval GOLDEN.yaml | Golden-set evaluation: hit@k, MRR, keyword pass-rate, optional LLM-judged faithfulness. |
ragstack status / reset | Store counts and provider resolution / wipe all indexes, caches, memory. |
Passing --session demo stores each question/answer pair. On later turns the system rewrites co-references into standalone queries before retrieval — "and its pricing?" becomes "what is the pricing of <subject>?". The original phrasing still reaches the generator so tone is preserved. Every answered pair is also embedded into the recall store so future sessions can find it via the agent's recall_memory tool.
ragstack query "summarize the supplier agreement" --session legal ragstack query "and its termination notice period?" --session legal ragstack sessions ragstack forget legal
Tune retention with agent.memory_turns (turns kept per session); disable entirely with 0.
One line adapts chunking and answer discipline to a domain:
vertical: legal # medical | academic| Vertical | Tunes |
|---|---|
legal | Smaller chunks (384/48); verbatim clause quoting; exact section/statute citations; binding vs recital distinction. |
medical | 512/96 chunks; population/intervention/dosage surfaced; uncertainty and limitations flagged explicitly. |
academic | 640/96 chunks; author-year attribution; results vs hypotheses vs speculation separated. |
| Endpoint | Purpose |
|---|---|
POST /api/query | Body |
POST /api/index |
|
POST /api/crawl |
|
GET /api/status | Version, providers, store counts, memory/recall stats, auth flag. |
GET /api/modes | The machine-readable mode catalog. |
| Event | Payload highlights |
|---|---|
start | mode, tool list, trace_id, cached flag |
route | chosen route + full classification object (auto mode) |
rewrite | original vs standalone rewritten query (session follow-ups) |
tool_start / tool_end | name, arguments, truncated preview |
retrieval | count, refs, verdict (direct modes) |
answer | delta text (direct-mode streaming) |
verification | claim manifest with per-claim verdicts |
done | answer, citations[], steps[], confidence, manifest, abstained?, trace_id |
clarify / error | clarifying question / failure message |
Set server.auth_token (or env RAGSTACK_AUTH_TOKEN) to require Authorization: Bearer … on mutating endpoints. Loopback callers without a header remain frictionless; remote callers must present the token. The console UI prompts once and remembers.
docker compose up --build # console at :8000 docker compose --profile neo4j up # + Neo4j sidecar
Indexes persist in ./.ragstack; model caches in a named volume. Point the console's Data tab at paths inside the container.