sci-rag-kit 0.4.0

A template repository for retrieval-augmented generation, built around your scientific domain. It implements hybrid GraphRAG retrieval, grounded answer generation with citations, an evaluation harness, and REST API plus MCP endpoints.

Read the documentation site for the guided path, or go directly to the methodology for the design specification.

To start a project of your own, run pipx install sci-rag-kit and then sci-rag new; the wizard asks about your field and writes a configured, git-initialized project. To evaluate the kit first, run the quickstart below against the bundled demo corpus.

Components

• Ingestion: PDF, HTML, Markdown, and plain-text parsing (Docling when installed, pypdf fallback; HTML through the standard library, with page chrome stripped), structure-aware chunking that preserves section hierarchy and keeps tables intact, content-hash deduplication, per-document license metadata.
• Retrieval: five candidate generators run in parallel and fuse by weighted reciprocal rank: dense vectors (pgvector + HNSW), Postgres full-text search, knowledge-graph traversal, community summaries, and HyDE. Per-stage timeouts, traces, and graceful degradation.
• Knowledge graph: LLM extraction of entities and typed relationships constrained to a user-defined ontology (domain/domain.yaml), with evidence provenance per edge; deterministic community detection with LLM-written, embedded summaries. Stored as ordinary Postgres rows; no separate graph database (see ADR 0001).
• Access control on content: each document carries a redistribution class (public, open_commercial, open_noncommercial, restricted, unknown). Retrieval scopes are applied inside every layer's SQL before ranking; an empty allowlist returns nothing.
• Answering: numbered inline citations tied to retrieved sources; when retrieval finds nothing in scope, the system states that instead of answering from model priors.
• Model providers: Gemini, Claude, and any OpenAI-compatible endpoint, chosen per role with a provider:model setting. On Google Cloud that reaches the Vertex Model Garden partner models (Claude, Grok, Llama, Mistral) with no credentials beyond the project you already have.
• Evaluation: expert-authored seed questions, retrieval metrics (hit@k, MRR) with per-layer ablation configs, and a two-pass LLM judge: the grounding pass never sees the reference answer, and correctness is graded separately against it. Reports are stamped with a corpus fingerprint and git commit.
• Serving: a FastAPI service (/v1, OpenAPI at /docs) and an MCP server (eight tools, mounted at /mcp and runnable over stdio) backed by the same service instance. Static API keys with scopes and rate limits, an interface seam for OAuth, and per-request LLM key override.

Everything runs in a single PostgreSQL database: text, vectors, full-text indexes, and the graph.

Quickstart

Requirements: uv, a supported PostgreSQL backend (Docker by default, local PostgreSQL, or the opt-in Cloud SQL development backend), and optionally a Google AI Studio API key or Vertex AI credentials for real embeddings and generation.

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

cp .env.example .env
chmod 600 .env          # owner only: it is about to hold a credential
# In .env, set one of:
#   SCI_RAG_GOOGLE_API_KEY=...              AI Studio key
#   SCI_RAG_GCP_PROJECT=...                 Vertex AI (after gcloud auth application-default login)
#   SCI_RAG_EMBEDDING_PROVIDER=local-hash   offline mode: no credentials, lexical-only retrieval, no generation
# To generate with Claude or Grok instead of Gemini, see docs/extend.md.

make setup     # sync dependencies, start the selected backend, create the schema
make demo      # ingest the demo corpus, run a traced retrieval, score it

make setup starts the selected database backend and applies every migration. Docker is the template default; generated projects may select conda-forge, system PostgreSQL, or the optional Cloud SQL development helper. See Run Postgres your way for the supported combinations.

With credentials configured, generation and the graph work too:

uv run sci-rag answer "What conversion route suits rice straw given its ash content?"
make demo-cloud   # graph extraction + communities + a deep answer + ablation report
uv run sci-rag serve   # REST at /docs, MCP at /mcp

Example answer from the demo corpus (five numbered sources across three documents, all claims cited):

Given its ash content, anaerobic digestion is a suitable conversion route for rice straw [2][4]. Rice straw has an ash content near 18 percent, which includes high silica [2]. This high ash and silica limit direct combustion [2] and prevent its use in gasifiers due to accelerated clinker formation [5]. ... a mild alkali soak raises the biogas yield to 320 cubic meters per dry ton [1][3].

The demo corpus is five synthetic documents about agricultural residues (realistic form, fictional numbers, CC0), included so the pipeline can be exercised end to end before you commit your own documents.

Customizing to your domain

You do not have to write the domain files cold. sci-rag draft creates corpus-grounded first passes; the LLM-assisted setup guide also shows a copy-paste workflow that needs no model credentials.

1. Put documents in data/raw/ and describe them in a JSONL corpus manifest (title, authors, license class, source).
2. Edit domain/domain.yaml: entity types, relationship types, and HyDE query classes for your field.
3. Adjust the wording of the prompts in domain/prompts/ where needed.
4. Write 10 to 20 ground-truth questions in domain/eval_seed_questions.jsonl.
5. Run sci-rag ingest, sci-rag graph extract, sci-rag graph communities, then sci-rag eval retrieval --ablation.

The step-by-step version with worked examples is Bring your own domain. Inside a checkout, uv run sci-rag init lets you choose Quick or Advanced setup, while uv run sci-rag init --advanced asks every applicable question; uv run python scripts/init_domain.py is the narrow path when all you want is the project name, description, and a seed-question reset.

Repository layout

domain/            Ontology, prompts, seed questions (everything specific to your field)
src/sci_rag/       ingest, embed, graph, retrieve, answer, evals, server, cli
data/demo/         Demo corpus (synthetic, CC0; optional)
migrations/        Alembic schema (pgvector + HNSW + FTS indexes)
tests/             Offline-first suite; database tests use a disposable selected backend
infra/terraform/   Optional production deployment plus a separate dev database module
docs/              Methodology, tutorials, API reference, ADRs

CLI

Register the MCP server with a local agent:

claude mcp add my-corpus -- uv run --directory /path/to/your/repo sci-rag mcp

Documentation

The complete, searchable site is published at sustainability-software-lab.github.io/sci-rag-kit.

Defaults and requirements

Python 3.11+; PostgreSQL 16 to 18 with pgvector from the selected backend. Docker is the template default and matches the PostgreSQL 16 CI service. Default models: gemini-embedding-001 at 1536 dimensions (within pgvector's HNSW index limit; see ADR 0002) and gemini-2.5-flash for generation, via AI Studio key or Vertex AI. A deterministic offline embedder covers tests and credential-free runs. Docling is an optional extra (uv sync --extra docling) because of its install size; without it, PDF parsing falls back to pypdf at reduced table fidelity.

License

BSD 3-Clause. See LICENSE.