Skip to content

Quickstart

Set up a served, agent-accessible knowledge base over the bundled demo corpus. You will see the evidence returned by each retrieval stage before you add your own literature.

LevelBeginner
TimeAbout 10 minutes
ServicesDocker + Postgres
CredentialsOptional
Tested withv0.2

Every command runs from the repository root.

Before you start

Requirement Why it is needed Check
Python 3.11 or 3.12 Supported runtime python --version
uv Environment and dependency management uv --version
Docker Local Postgres with pgvector docker version
Google credential, optional Real semantic embeddings, graph extraction, and answers AI Studio key or Vertex ADC

No Docker? There are two ways past it, and which one applies depends on your environment manager. See without Docker in step 3.

1. Get the repository

For your own project, run the wizard from whatever directory you keep projects in. It asks about your domain, credentials, ontology, corpus, and environment manager, then writes a configured, git-initialized project directory:

Terminal
$ pipx install sci-rag-kit
$ sci-rag-new

Every question has a default, so you can press Enter through the whole session and still get a project that runs. Steps 2 and 3 below are the questions it asked; read them to understand what it wrote, then skip to step 4.

Evaluating the kit rather than starting a project? Clone it:

Terminal
$ git clone https://github.com/sustainability-software-lab/sci-rag-kit.git
$ cd sci-rag-kit

Clicking Use this template on GitHub also works. Inside a checkout you already have, sci-rag init runs the same wizard. The included dev container is another supported path. In GitHub Codespaces it installs the project and starts Postgres, so continue with configuration.

2. Choose a credential mode

Create the local environment file:

$ cp .env.example .env

Choose exactly one mode.

AI Studio: fastest real model

Create an API key at Google AI Studio, then set:

~/.env
SCI_RAG_GOOGLE_API_KEY=your-key-here

Vertex AI: labs & Google Cloud

Authenticate Application Default Credentials once, then set the project:

$ gcloud auth application-default login
~/.env
SCI_RAG_GCP_PROJECT=your-project-id

Offline: no credentials

Use the deterministic local embedder:

~/.env
SCI_RAG_EMBEDDING_PROVIDER=local-hash

This mode exercises parsing, chunking, storage, ranking, and retrieval evaluation without network calls. Its similarity is lexical rather than semantic. Graph extraction, HyDE, community summaries, generated answers, and model-based judging remain unavailable until you add a model credential.

3. Install & initialize

With Docker:

$ make setup

The target runs uv sync, starts the compose Postgres on host port 5433, and applies every Alembic migration.

Without Docker

With pixi or conda, the server comes from conda-forge along with everything else, so there is nothing extra to install. Those two managers put postgresql and pgvector in the project manifest, and make setup starts that server instead of a container:

$ make setup
$ make db-down    # stops it again

The data lives in .pgdata/ inside the project, and the server listens on 127.0.0.1:5433, which is the address .env.example already carries. Nothing to configure and no connection string to edit.

This path is not available to uv or venv+pip projects. PyPI has no PostgreSQL server, so those two need either Docker or a Postgres you already run.

With an external PostgreSQL service, any supported server works. Point SCI_RAG_DATABASE_URL at it, make sure the pgvector extension is available, then run the two non-Docker steps directly:

$ uv sync
$ uv run sci-rag db upgrade

Supported servers are PostgreSQL 16 through 18. CI proves 16 through the container image on every change and 18 through the conda-forge path, so both ends of that range are tested rather than assumed. ADR 0008 records why the range exists.

Expected output

Database schema is up to date.

Checkpoint: the foundation is healthy

Run uv run sci-rag doctor. Configuration, domain, database, and schema should report healthy. An empty corpus or missing optional credential can still be informational at this point.

4. Ingest & inspect the demo

$ make demo

This command ingests five synthetic CC0 documents about agricultural residues, retrieves evidence for one question, and scores retrieval against the bundled seed questions. The numbers are plausible but fictional; the fixture demonstrates the pipeline, not the state of a real region.

Expected output

Ingestion report
5 ingested, 0 skipped, 0 failed.

vector     success     ...
keyword    success     ...
graph      disabled    ...

Exact candidate counts and metric values depend on the credential mode. graph disabled is normal here because make demo uses the interactive profile, which intentionally leaves the model-dependent graph layer off.

Checkpoint: evidence is inspectable

The retrieval table should show a title, section path, license class, contributing layers, fused score, and content excerpt. The stage table should distinguish success, empty, disabled, or failure rather than silently omitting a layer.

5. Generate a cited answer

With a Google credential:

$ uv run sci-rag answer "How much rice straw was generated in the Colusa Basin in 2023?"

The demo answer is approximately 302,000 dry tons and cites the synthetic resource assessment. Check the cited passage rather than treating the number alone as success.

In offline mode this command reports that no LLM is configured. That refusal is expected: the system does not fabricate an answer when generation is unavailable.

6. Build the graph & deep path

With a Google credential:

$ make demo-cloud

The target extracts ontology-constrained entities and relationships, builds community summaries, asks a multi-document question, and runs the per-layer retrieval ablation. Reports are written under eval_results/.

Checkpoint: complexity produced evidence

Open the newest retrieval report. It should identify the corpus fingerprint, models, profile, enabled layers, metrics, confidence intervals, and per-question records. Do not enable an expensive layer in your own profile merely because it worked on this fixture.

7. Serve humans & agents

$ uv run sci-rag serve

The one process exposes:

Try retrieval through REST:

$ curl -s -X POST http://127.0.0.1:8000/v1/query \
    -H 'Content-Type: application/json' \
    -d '{"query": "rice straw availability", "top_k": 3}'

For a local agent over stdio:

$ claude mcp add demo-corpus -- uv run --directory "$(pwd)" sci-rag mcp

Ask the agent to use demo-corpus for a question. You should see a search_corpus or answer_question tool call rather than an answer from the agent's unaided memory.

What you built

You now have one Postgres database containing source records, structure-aware chunks, dense vectors, full-text search, and, if enabled, a concept graph and community summaries. One service exposes the same retrieval and answer behavior to CLI users, REST clients, and MCP agents. The evaluation artifacts record what that system did on known questions.

Continue