Quickstart

Commands that reference scripts/ are source-checkout commands and must be run from the RAGSpine repository root. The installed ragspine command works from any directory.

1. Verify the offline engine

ragspine quickstart
ragspine version

In a source checkout, the larger end-to-end fixture run is:

.venv/bin/python scripts/run_demo.py

It extracts and ingests synthetic facts, queries them, checks source lineage, and ends with ALL CHECKS PASSED on success. No API key is required.

2. Create a workflow from one sentence

The shortest form treats an unknown first positional argument as workflow create:

ragspine "A RAG form-understanding paper workflow using CNN"

The command first tries to match one of the 1,000 bundled templates. If the match is not confident enough, it creates a fixed start → llm → end Dify 0.6 workflow. The command writes a new YAML file by default and does not run it. Equivalent explicit forms include:

ragspine workflow create "invoice extraction and approval" --stdout
ragspine workflow create "support triage" --format json -o support.json
ragspine workflow create --template conditional-response-routing -o routing.yml
ragspine workflow list
ragspine workflow show conditional-response-routing --format json
ragspine workflow preview conditional-response-routing

The default auto matcher uses the ONNX matcher when [embed-onnx] is available and otherwise falls back to deterministic lexical matching. Use --matcher lexical for a guaranteed no-model path, --no-reuse to force generation, and --force only when replacing a normal existing file. Symlinks and special files are always rejected.

See the Workflow guide for catalog provenance, format limits, and the preview schema.

3. Ask through Python

from ragspine.agent.agent import answer_question
from ragspine.agent.llm_provider import MockProvider
from ragspine.storage.fact_store import SqliteFactStore

store = SqliteFactStore("data/fact_metric.db")
store.init_schema()
result = answer_question("China FY2024 revenue", store, MockProvider())
print(result.answer)
print(result.sources)

answer_question returns cited evidence or an explicit refusal. Optional conversation history is generation context only: it is never used as retrieval evidence or as input to the intent and security decisions.

4. Start the optional HTTP service

Install [service], then in a source checkout:

RAGSPINE_DB_PATH=data/fact_metric.db \
  .venv/bin/python scripts/run_server.py --host 127.0.0.1 --port 8000

curl -s http://127.0.0.1:8000/healthz
curl -s http://127.0.0.1:8000/v1/workflow-templates?limit=10
curl -s http://127.0.0.1:8000/v1/workflow-scaffold \
  -H 'content-type: application/json' \
  -d '{"description":"invoice extraction and approval"}'

Catalog and scaffold routes are read-only/non-executing. Dify and n8n run routes are disabled unless RAGSPINE_DIFY_RUN_ENABLED=true. The general engine routes do not include application authentication; place the service behind an authenticated reverse proxy or a private network before exposing it.

To process queued ingestion jobs, run Redis and a second source-checkout process:

RAGSPINE_REDIS_URL=redis://localhost:6379/0 \
  .venv/bin/python scripts/run_worker.py