sci-rag-kit 0.3.0__tar.gz

sci_rag_kit-0.3.0/.devcontainer/compose.yml

@@ -0,0 +1,18 @@
+# Devcontainer overlay: adds an app container next to the db service from
+# the root docker-compose.yml. Inside this network the database is reached
+# as host "db" on 5432 (no published-port indirection).
+#
+# Note on the volume path: with multiple compose files, relative paths
+# resolve against the FIRST file's directory (the repo root), so the
+# workspace mount is "." here, not "..".
+services:
+  app:
+    image: mcr.microsoft.com/devcontainers/python:3.12
+    volumes:
+      - .:/workspaces/sci-rag-kit:cached
+    command: sleep infinity
+    environment:
+      SCI_RAG_DATABASE_URL: postgresql+asyncpg://sci_rag:sci_rag@db:5432/sci_rag
+    depends_on:
+      db:
+        condition: service_healthy

sci_rag_kit-0.3.0/.devcontainer/devcontainer-lock.json

@@ -0,0 +1,9 @@
+{
+  "features": {
+    "ghcr.io/va-h/devcontainers-features/uv:1": {
+      "version": "1.1.4",
+      "resolved": "ghcr.io/va-h/devcontainers-features/uv@sha256:a15737142539d150ef4d358e2d6a7424a0a2f3dc43b29a3aa1b50162a8b11bc1",
+      "integrity": "sha256:a15737142539d150ef4d358e2d6a7424a0a2f3dc43b29a3aa1b50162a8b11bc1"
+    }
+  }
+}

sci_rag_kit-0.3.0/.devcontainer/devcontainer.json

@@ -0,0 +1,19 @@
+{
+  "name": "sci-rag-kit",
+  "dockerComposeFile": ["../docker-compose.yml", "compose.yml"],
+  "service": "app",
+  "workspaceFolder": "/workspaces/sci-rag-kit",
+  "features": {
+    "ghcr.io/va-h/devcontainers-features/uv:1": {}
+  },
+  "postCreateCommand": "uv sync && uv run sci-rag db upgrade",
+  "forwardPorts": [8000],
+  "customizations": {
+    "vscode": {
+      "extensions": ["ms-python.python", "charliermarsh.ruff"],
+      "settings": {
+        "python.defaultInterpreterPath": "${containerWorkspaceFolder}/.venv/bin/python"
+      }
+    }
+  }
+}

sci_rag_kit-0.3.0/.env.example

@@ -0,0 +1,90 @@
+# ---------------------------------------------------------------------------
+# sci-rag-kit configuration
+#
+# Copy this file to `.env`, then fill in the handful of values you need.
+# Everything has a sensible default for the local quickstart; you only need
+# Google credentials when you want real embeddings, graph extraction, and
+# generated answers (see docs/quickstart.md).
+# ---------------------------------------------------------------------------
+
+# --- Database ---------------------------------------------------------------
+# The default matches docker-compose.yml (`docker compose up -d`).
+SCI_RAG_DATABASE_URL=postgresql+asyncpg://sci_rag:sci_rag@localhost:5433/sci_rag
+
+# --- Models: pick ONE of the two options below ------------------------------
+# Option A (easiest): a free Google AI Studio API key, https://aistudio.google.com/apikey
+# SCI_RAG_GOOGLE_API_KEY=
+
+# Option B (labs/teams on Google Cloud): Vertex AI with application-default
+# credentials. Run `gcloud auth application-default login` first.
+# SCI_RAG_GCP_PROJECT=your-project-id
+# SCI_RAG_GCP_LOCATION=us-central1
+
+# --- Embeddings -------------------------------------------------------------
+# "google" needs one of the credential options above. "local-hash" is a
+# deterministic, no-network embedder meant for tests and pipeline dry runs;
+# its rankings are lexical, not semantic.
+SCI_RAG_EMBEDDING_PROVIDER=google
+SCI_RAG_EMBEDDING_MODEL=gemini-embedding-001
+# 1536 keeps vectors inside pgvector's HNSW index limit (2000 dims).
+# Changing this after ingestion requires a migration plus re-embedding.
+SCI_RAG_EMBEDDING_DIM=1536
+
+# --- Generation (answers, graph extraction, HyDE, summaries) ----------------
+# Every model setting below is a spec: either a bare model id, which belongs to
+# SCI_RAG_LLM_PROVIDER, or "provider:model" to override the provider inline.
+# Providers: google | anthropic | openai-compatible
+SCI_RAG_LLM_PROVIDER=google
+SCI_RAG_LLM_MODEL=gemini-2.5-flash
+
+# Optional lower-cost model for high-volume graph extraction, HyDE, and
+# reranking. Unset inherits SCI_RAG_LLM_MODEL.
+# SCI_RAG_EXTRACTION_MODEL=
+
+# Optional model for the evaluation judge. Unset inherits SCI_RAG_LLM_MODEL.
+# Pointing this at a different provider than SCI_RAG_LLM_MODEL avoids grading
+# a model's answers with its own family, which flatters the score.
+# SCI_RAG_JUDGE_MODEL=
+
+# Worked examples (each needs the matching extra installed):
+#   uv sync --extra anthropic
+#   SCI_RAG_GCP_LOCATION=global
+#   SCI_RAG_LLM_MODEL=anthropic:claude-haiku-4-5
+#     Claude as a Vertex partner model. Uses SCI_RAG_GCP_PROJECT and
+#     application-default credentials; no separate key needed.
+#
+#   uv sync --extra openai
+#   SCI_RAG_GCP_LOCATION=global
+#   SCI_RAG_LLM_MODEL=openai-compatible:xai/grok-4.1-fast-non-reasoning
+#     Grok through Vertex Model Garden's OpenAI-compatible endpoint, which is
+#     how every non-Google partner model (Grok, Llama, Mistral, DeepSeek) is
+#     served. Also uses SCI_RAG_GCP_PROJECT.
+#
+#   NOTE: partner models are not served from every region. The us-central1
+#   default serves Gemini but not Claude or Grok; both work from "global", and
+#   Grok is only offered there. Run `sci-rag doctor --probe` after changing
+#   providers -- it probes each one and names the fix.
+
+# --- Credentials for the non-Google generation providers --------------------
+# Only needed to call these providers directly instead of through Vertex AI.
+# SCI_RAG_ANTHROPIC_API_KEY=
+# SCI_RAG_OPENAI_API_KEY=
+# Point the OpenAI-compatible provider somewhere other than Vertex: OpenAI
+# itself (unset the base URL, set the key) or a self-hosted vLLM/Ollama server.
+# SCI_RAG_OPENAI_BASE_URL=
+
+# --- Retrieval stage timeouts (seconds) -------------------------------------
+# SCI_RAG_INTERACTIVE_STAGE_TIMEOUT_S=8.0
+# SCI_RAG_DEEP_STAGE_TIMEOUT_S=30.0
+
+# --- Repository-relative paths ---------------------------------------------
+# SCI_RAG_DOMAIN_DIR=domain
+# SCI_RAG_DATA_DIR=data
+
+# --- Server (only needed for `sci-rag serve`) -------------------------------
+# JSON map of API key -> settings. Leave unset for open local development
+# (the server will warn loudly). Example:
+# SCI_RAG_API_KEYS={"dev-key-123": {"scopes": ["retrieval:query", "retrieval:answer"]}}
+# SCI_RAG_SERVER_HOST=127.0.0.1
+# SCI_RAG_SERVER_PORT=8000
+# SCI_RAG_CORS_ORIGINS=*

sci_rag_kit-0.3.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,30 @@
+name: Bug report
+description: Something broke or behaved wrongly
+labels: [bug]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+      description: What you did, what you expected, what you got instead.
+      placeholder: Ran `sci-rag ingest data/raw` and ...
+    validations:
+      required: true
+  - type: textarea
+    id: doctor
+    attributes:
+      label: sci-rag doctor output
+      description: Paste the output of `uv run sci-rag doctor` (redact anything sensitive).
+      render: text
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Version / commit
+      placeholder: v0.1.0a0, or a commit SHA
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs or traceback
+      render: text

sci_rag_kit-0.3.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

sci_rag_kit-0.3.0/.github/ISSUE_TEMPLATE/domain_help.yml

@@ -0,0 +1,24 @@
+name: Domain specialization help
+description: Questions about adapting the kit to your field (ontology, prompts, evals)
+labels: [domain-help]
+body:
+  - type: textarea
+    id: domain
+    attributes:
+      label: Your domain and corpus
+      description: What field, roughly how many documents, and what kinds (papers, reports, protocols).
+    validations:
+      required: true
+  - type: textarea
+    id: question
+    attributes:
+      label: What you are trying to figure out
+      description: Ontology design, seed questions, disappointing retrieval, prompt wording, and so on.
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: What you have tried and measured
+      description: Eval numbers help enormously (`sci-rag eval retrieval --ablation` output, or the report.md).
+      render: text

sci_rag_kit-0.3.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,23 @@
+name: Feature request
+description: Propose an improvement to the kit
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem it solves
+      description: What is hard or impossible today, concretely.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed change
+      description: What you would change, and where it fits (see docs/architecture.md extension points).
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Evidence it helps
+      description: For retrieval/eval changes, before/after ablation numbers are the currency here.

sci_rag_kit-0.3.0/.github/dependabot.yml

@@ -0,0 +1,19 @@
+# Weekly dependency update PRs. CI (including the coverage floor and the
+# smoke eval) is the gate that keeps them honest.
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      python-dependencies:
+        patterns: ["*"]
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"

sci_rag_kit-0.3.0/.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## What this changes
+
+<!-- One or two sentences. Link the issue if there is one. -->
+
+## Checklist
+
+- [ ] `make check` is green (ruff, mypy, tests)
+- [ ] Tests cover the change (offline by default)
+- [ ] Docs updated if user-visible behavior changed
+- [ ] For retrieval or eval changes: before/after `sci-rag eval retrieval --ablation` tables included below
+
+## Eval evidence (if applicable)
+
+<!-- Paste the ablation tables, or delete this section. -->

sci_rag_kit-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,121 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    services:
+      postgres:
+        image: pgvector/pgvector:pg16
+        env:
+          POSTGRES_DB: sci_rag_test
+          POSTGRES_USER: sci_rag
+          POSTGRES_PASSWORD: sci_rag
+        ports:
+          - 5433:5432
+        options: >-
+          --health-cmd "pg_isready -U sci_rag -d sci_rag_test"
+          --health-interval 2s
+          --health-timeout 5s
+          --health-retries 15
+    env:
+      SCI_RAG_TEST_DATABASE_URL: postgresql+asyncpg://sci_rag:sci_rag@localhost:5433/sci_rag_test
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - name: Install dependencies
+        # The provider extras are light and carry the LLM adapters' tests, so
+        # CI installs them rather than skipping that coverage.
+        run: uv sync --extra anthropic --extra openai
+      - name: Lint
+        run: |
+          uv run ruff check src tests examples scripts
+          uv run ruff format --check src tests examples scripts
+      - name: Type check
+        run: uv run mypy
+      - name: Tests (unit + integration + smoke eval, with coverage floor)
+        run: uv run pytest -q --cov=sci_rag --cov-report=term --cov-fail-under=78
+
+  docker:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v7
+      - name: Build the server image
+        run: docker build -t sci-rag-kit:ci .
+      - name: Image smoke (CLI runs inside the container)
+        run: docker run --rm sci-rag-kit:ci sci-rag --help
+
+  terraform:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    defaults:
+      run:
+        working-directory: infra/terraform
+    steps:
+      - uses: actions/checkout@v7
+      - uses: hashicorp/setup-terraform@v4
+      - name: Format check
+        run: terraform fmt -check -diff
+      - name: Validate
+        run: |
+          terraform init -backend=false -input=false
+          terraform validate
+
+  docs-links:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - name: Check internal documentation links
+        uses: lycheeverse/lychee-action@v2
+        with:
+          # Offline: internal file links only, so external-site flake can
+          # never break the build.
+          args: --offline --no-progress "**/*.md"
+          fail: true
+
+  docs:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+          enable-cache: true
+      - name: Install project and documentation dependencies
+        # docs-test carries Playwright for the rendered-geometry guard below.
+        run: uv sync --group docs --group docs-test
+      - name: Check and build documentation exactly as contributors do
+        run: make docs
+      - name: Install the browser the geometry guard measures with
+        run: uv run playwright install --with-deps chromium
+      - name: Measure the built site's code snippets
+        # Reads site/ from the build above. Geometry is what the Markdown-level
+        # guard in tests/unit cannot see.
+        run: uv run pytest tests/docs -q
+      - name: Upload documentation preview
+        if: github.event_name == 'pull_request'
+        uses: actions/upload-artifact@v7
+        with:
+          name: docs-preview
+          path: site/
+          if-no-files-found: error
+          retention-days: 7

sci_rag_kit-0.3.0/.github/workflows/docker-free-postgres.yml

@@ -0,0 +1,126 @@
+# Does the Docker-free database actually work?
+#
+# `docs/quickstart.md` tells pixi and conda users they can run PostgreSQL and
+# pgvector from conda-forge instead of a container. An untested instruction is
+# worse than no instruction, so this runs the real integration and server
+# suites against a server installed that way, on the two platforms the
+# quickstart names.
+#
+# It is deliberately separate from `ci.yml`. That workflow proves the
+# supported floor, PostgreSQL 16 from the pgvector container image, on every
+# pull request. This one proves the other end of the range in ADR 0008:
+# whatever conda-forge resolves inside it, which is PostgreSQL 18 today.
+#
+# macOS runners are expensive, so a pull request gets linux-64 only unless it
+# changes something that decides what the Docker-free path looks like. Nightly
+# runs and release tags get both.
+name: docker-free-postgres
+
+on:
+  pull_request:
+  schedule:
+    - cron: "30 6 * * *"
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+concurrency:
+  group: docker-free-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  select:
+    runs-on: ubuntu-latest
+    outputs:
+      platforms: ${{ steps.pick.outputs.platforms }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - id: pick
+        env:
+          BASE: ${{ github.event.pull_request.base.ref }}
+        run: |
+          BOTH='[{"os":"ubuntu-latest","platform":"linux-64"},{"os":"macos-latest","platform":"osx-arm64"}]'
+          LINUX='[{"os":"ubuntu-latest","platform":"linux-64"}]'
+          if [ "${{ github.event_name }}" != "pull_request" ]; then
+            echo "platforms=$BOTH" >> "$GITHUB_OUTPUT"; exit 0
+          fi
+          CHANGED=$(git diff --name-only "origin/$BASE...HEAD")
+          echo "$CHANGED"
+          if echo "$CHANGED" | grep -qE '^(scripts/local_postgres|src/sci_rag/db/|migrations/|src/sci_rag/scaffold/runners|[.]github/workflows/docker-free-postgres)'; then
+            echo "the diff changes what this path looks like; running both platforms"
+            echo "platforms=$BOTH" >> "$GITHUB_OUTPUT"
+          else
+            echo "platforms=$LINUX" >> "$GITHUB_OUTPUT"
+          fi
+
+  integration:
+    needs: select
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        include: ${{ fromJSON(needs.select.outputs.platforms) }}
+    env:
+      SCI_RAG_LOCAL_PG_PORT: "5433"
+      SCI_RAG_LOCAL_PG_DB: sci_rag_test
+      SCI_RAG_TEST_DATABASE_URL: postgresql+asyncpg://sci_rag:sci_rag@127.0.0.1:5433/sci_rag_test
+    steps:
+      - uses: actions/checkout@v7
+
+      # The project itself installs with uv, exactly as in ci.yml. Only the
+      # database comes from conda-forge, which is the whole subject here.
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+          enable-cache: true
+      - run: uv sync
+
+      # micromamba rather than a full conda: this needs two packages, and the
+      # action caches them, so the leg stays close to a uv one in cost.
+      - uses: mamba-org/setup-micromamba@v2
+        with:
+          environment-name: pgserver
+          condarc: |
+            channels:
+              - conda-forge
+          # No quotes: the action execs micromamba directly rather than
+          # through a shell, so a quote here becomes part of the version spec
+          # and libmamba rejects `19"`.
+          create-args: >-
+            postgresql>=16,<19
+            pgvector
+          cache-environment: true
+          init-shell: bash
+
+      - name: The server and the extension came from conda-forge
+        shell: bash -el {0}
+        run: |
+          which initdb pg_ctl psql
+          postgres --version
+
+      - name: Start the database with no container runtime
+        shell: bash -el {0}
+        run: |
+          uv run python scripts/local_postgres.py start
+          uv run python scripts/local_postgres.py status
+
+      - name: The integration and server suites pass against it
+        shell: bash -el {0}
+        run: |
+          # A skipped integration suite is indistinguishable from a passing
+          # one in the check mark, and proving these tests really ran is this
+          # job's only purpose, so treat the skip path as a failure.
+          set -o pipefail
+          uv run pytest tests/integration tests/server -q -rs 2>&1 | tee run.log
+          if grep -q "Postgres unavailable" run.log; then
+            echo "::error::the suite skipped instead of running against the conda-forge server"
+            exit 1
+          fi
+
+      - name: Stop it again
+        if: always()
+        shell: bash -el {0}
+        run: uv run python scripts/local_postgres.py stop

sci_rag_kit-0.3.0/.github/workflows/docs-deploy.yml

@@ -0,0 +1,57 @@
+name: docs-deploy
+
+on:
+  workflow_run:
+    workflows: [ci]
+    types: [completed]
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    if: >-
+      github.event.workflow_run.event == 'push' &&
+      github.event.workflow_run.head_repository.full_name == github.repository &&
+      github.event.workflow_run.head_branch == 'main' &&
+      github.event.workflow_run.head_sha == github.sha &&
+      github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+          enable-cache: true
+      - name: Install project and documentation dependencies
+        run: uv sync --group docs
+      - name: Check and build documentation exactly as contributors do
+        run: make docs
+      - name: Upload GitHub Pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: site/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v6
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5