sci-rag-kit 0.3.0a1__tar.gz

sci_rag_kit-0.3.0a1/.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.0a1/.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.0a1/.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.0a1/.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.0a1/.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.0a1/.github/ISSUE_TEMPLATE/config.yml

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

sci_rag_kit-0.3.0a1/.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.0a1/.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.0a1/.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.0a1/.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.0a1/.github/workflows/ci.yml

@@ -0,0 +1,114 @@
+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
+        run: uv sync --group docs
+      - name: Check and build documentation exactly as contributors do
+        run: make docs
+      - 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.0a1/.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

sci_rag_kit-0.3.0a1/.github/workflows/generated-projects.yml

@@ -0,0 +1,189 @@
+# Does a project the wizard generates actually work?
+#
+# The unit tests assert that no manager's commands leak into another manager's
+# project. They cannot assert that the resulting project installs and runs,
+# because that needs the real manager on a real runner. This workflow does.
+#
+# uv runs on every pull request, because it is the manager the template itself
+# uses and its leg is fast. pixi and conda pull large environments over the
+# network, so the full four-way matrix runs nightly and on release tags. An
+# untested manager option is worse than no option, so a manager that is not
+# green here should not be advertised in the documentation.
+name: generated-projects
+
+on:
+  pull_request:
+  schedule:
+    - cron: "0 6 * * *"
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+concurrency:
+  group: generated-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # Which managers this run covers. Everything except a pull request gets all
+  # four. A pull request gets uv only, unless it touches the code that decides
+  # what a generated project looks like, in which case it gets all four too:
+  # those are exactly the changes a uv-only leg cannot catch.
+  select:
+    runs-on: ubuntu-latest
+    outputs:
+      managers: ${{ steps.pick.outputs.managers }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - id: pick
+        env:
+          BASE: ${{ github.event.pull_request.base.ref }}
+        run: |
+          ALL='["uv","pixi","conda","venv+pip"]'
+          if [ "${{ github.event_name }}" != "pull_request" ]; then
+            echo "managers=$ALL" >> "$GITHUB_OUTPUT"; exit 0
+          fi
+          CHANGED=$(git diff --name-only "origin/$BASE...HEAD")
+          echo "$CHANGED"
+          if echo "$CHANGED" | grep -qE '^(src/sci_rag/scaffold/|\.github/workflows/generated-projects\.yml|Dockerfile|\.devcontainer/|Makefile)'; then
+            echo "the diff changes what a generated project looks like; running all four"
+            echo "managers=$ALL" >> "$GITHUB_OUTPUT"
+          else
+            echo 'managers=["uv"]' >> "$GITHUB_OUTPUT"
+          fi
+
+  generate:
+    needs: select
+    runs-on: ubuntu-latest
+    timeout-minutes: 40
+    strategy:
+      fail-fast: false
+      matrix:
+        manager: ${{ fromJSON(needs.select.outputs.managers) }}
+    services:
+      postgres:
+        image: pgvector/pgvector:pg16
+        env:
+          POSTGRES_DB: sci_rag
+          POSTGRES_USER: sci_rag
+          POSTGRES_PASSWORD: sci_rag
+        ports:
+          - 5433:5432
+        options: >-
+          --health-cmd "pg_isready -U sci_rag -d sci_rag"
+          --health-interval 2s
+          --health-timeout 5s
+          --health-retries 15
+    env:
+      # The generated project runs fully offline: the deterministic local
+      # embedder, no credentials, no model calls.
+      SCI_RAG_EMBEDDING_PROVIDER: local-hash
+      SCI_RAG_EMBEDDING_DIM: "1536"
+      SCI_RAG_DATABASE_URL: postgresql+asyncpg://sci_rag:sci_rag@localhost:5433/sci_rag
+    steps:
+      - uses: actions/checkout@v7
+
+      # The generator itself always runs under the template's own toolchain.
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+          enable-cache: true
+      - run: uv sync
+
+      - name: Generate a project for ${{ matrix.manager }}
+        run: |
+          mkdir -p "$RUNNER_TEMP/generated"
+          git archive HEAD | tar -x -C "$RUNNER_TEMP/generated"
+          cat > "$RUNNER_TEMP/answers.yaml" <<EOF
+          project_name: Generated KB
+          repo_name: generated-kb
+          description: A project generated by the sci-rag wizard in CI.
+          author_name: sci-rag-kit CI
+          contact_email: ""
+          python_version: "3.12"
+          environment_manager: ${{ matrix.manager }}
+          credentials: offline
+          ontology: keep_demo_example
+          corpus_source: demo_only
+          include_terraform: "No"
+          include_demo_corpus: "Yes"
+          open_source_license: BSD-3-Clause
+          initialize_git: "No"
+          EOF
+          uv run sci-rag init --answers-file "$RUNNER_TEMP/answers.yaml" \
+            --target "$RUNNER_TEMP/generated"
+
+      - name: The generated build surfaces agree with the chosen manager
+        run: |
+          cd "$RUNNER_TEMP/generated"
+          # The install command this job runs below has to be the one the
+          # generated project tells its users to run. Read it, do not assume it.
+          SYNC=$(sed -n '/^setup:/,/^$/p' Makefile | sed -n '2p' | sed 's/^\t//')
+          echo "generated setup command: $SYNC"
+          echo "SYNC=$SYNC" >> "$GITHUB_ENV"
+          for other in "uv run" "pixi run" "conda run" "astral-sh/setup-uv" \
+                       "prefix-dev/setup-pixi" "conda-incubator/setup-miniconda"; do
+            case "${{ matrix.manager }}:$other" in
+              uv:"uv run"|uv:"astral-sh/setup-uv") continue ;;
+              pixi:"pixi run"|pixi:"prefix-dev/setup-pixi") continue ;;
+              conda:"conda run"|conda:"conda-incubator/setup-miniconda") continue ;;
+            esac
+            if grep -rqF -- "$other" Makefile Dockerfile .github/workflows README.md docs; then
+              echo "::error::a ${{ matrix.manager }} project still mentions '$other'"
+              grep -rnF -- "$other" Makefile Dockerfile .github/workflows README.md docs | head -20
+              exit 1
+            fi
+          done
+
+      - name: Install pixi
+        if: matrix.manager == 'pixi'
+        uses: prefix-dev/setup-pixi@v0
+        with:
+          manifest-path: ${{ runner.temp }}/generated/pyproject.toml
+          cache: false
+
+      - uses: conda-incubator/setup-miniconda@v3
+        if: matrix.manager == 'conda'
+        with:
+          auto-activate-base: true
+          activate-environment: ""
+
+      - name: Install the generated project and run its own checks
+        shell: bash -el {0}
+        run: |
+          cd "$RUNNER_TEMP/generated"
+          case "${{ matrix.manager }}" in
+            uv)       eval "$SYNC"; RUN="uv run" ;;
+            pixi)     eval "$SYNC"; RUN="pixi run" ;;
+            conda)    eval "$SYNC"; RUN="conda run -n generated-kb" ;;
+            # An activated venv has no prefix; putting its bin directory on
+            # PATH is how a user works in it, and it keeps one code path here.
+            # GITHUB_PATH only applies to later steps, so export it here too.
+            venv+pip) eval "$SYNC"
+                      echo "$PWD/.venv/bin" >> "$GITHUB_PATH"
+                      export PATH="$PWD/.venv/bin:$PATH"
+                      RUN="" ;;
+          esac
+          echo "RUN=$RUN" >> "$GITHUB_ENV"
+          $RUN ruff check src tests examples scripts
+          $RUN mypy
+
+      - name: The offline demo runs in the generated project
+        shell: bash -el {0}
+        run: |
+          cd "$RUNNER_TEMP/generated"
+          $RUN sci-rag db upgrade
+          $RUN sci-rag ingest --manifest data/demo/manifest.jsonl
+          $RUN sci-rag retrieve "How much rice straw was generated in the Colusa Basin in 2023?" --profile interactive --limit 3
+          # No `eval retrieval` here: the wizard resets the seed questions to a
+          # guided blank, so a freshly generated project has no ground truth
+          # yet. That is the point of the reset, not a regression.
+
+      # A gate. A project generated with `credentials: offline` is a state the
+      # user chose, so `doctor` warns about the unavailable generation features
+      # rather than failing on them; anything it does report as FAIL here is a
+      # real defect in what the wizard produced.
+      - name: sci-rag doctor
+        shell: bash -el {0}
+        run: cd "$RUNNER_TEMP/generated" && $RUN sci-rag doctor