rag-spine 0.1.1__tar.gz

rag_spine-0.1.1/.claude/settings.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "allow": [
+      "Bash(.venv/bin/python:*)",
+      "Bash(.venv/bin/python -m pytest:*)",
+      "Bash(python:*)",
+      "Bash(python3:*)",
+      "Bash(uv venv:*)",
+      "Bash(uv pip:*)",
+      "Bash(uv run:*)",
+      "Bash(ruff:*)",
+      "Bash(mypy:*)",
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git show:*)",
+      "Bash(git branch:*)"
+    ],
+    "deny": []
+  }
+}

rag_spine-0.1.1/.claude/skills/ragspine-make/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: ragspine-make
+description: "How to run dev / CI-CD tasks in the RAGSpine repo via the Makefile. Use whenever you need to install deps, run tests, run the local CI gate, lint/format, check doc drift, run the demo, ask a question, run evals, start the server/worker, or regenerate fixtures in this project. Keywords: make, Makefile, run tests, pytest, CI, ci gate, pre-push, lint, ruff, mypy, format, doc drift, demo, ask, eval, qa eval, retrieval ab, serve, FastAPI, worker, RQ, redis, fixtures, install, venv, uv, hooks, build docs, 跑测试, 跑CI, 本地CI, 格式化, 漂移, 评估, 启动服务, 安装依赖, 怎么运行, 命令"
+allowed-tools: ["Bash", "Read"]
+---
+
+# RAGSpine — dev / CI-CD commands (Makefile)
+
+The repo wraps common commands in a root `Makefile`. **Always run from the repo root**
+(scripts anchor on `.project-root`). `make help` lists every target. The raw commands
+live in `scripts/`; the Makefile is a thin, discoverable wrapper over them.
+
+**Interpreter:** every target defaults to `.venv/bin/python`. Override with
+`make <target> PYTHON=python3.12` (passed through to `scripts/ci.sh` / `lint.sh` too).
+
+## First-time setup
+
+| Command | What it does | Notes |
+|---|---|---|
+| `make venv` | `uv venv .venv` | Creates the project venv. |
+| `make install` | editable install, `[dev,service]` extras | The usual dev setup. |
+| `make install-all` | editable install, `[dev,service,llm,embed]` | Adds real LLM + embedding backends (heavier). `[pdf]`/`[ocr]` are platform-specific and intentionally excluded. |
+| `make hooks` | `git config core.hooksPath .githooks` | **One-time per clone.** Enables the pre-push CI gate so red code never leaves the machine. Emergency bypass: `git push --no-verify`. |
+
+## The quality gate
+
+| Command | What it does | Notes |
+|---|---|---|
+| `make ci` | tests (`-m "not gpu"`) + demo smoke | **The gate** — exactly what the pre-push hook runs (`scripts/ci.sh`). This is the single source of truth for "is it green". |
+| `make test` | `pytest tests/ -q -m "not gpu"` | Expect **943 passed, 1 gpu-skipped**. |
+| `make test-all` | full suite incl. `gpu` marker | Needs Ubuntu + NVIDIA GPU + real OCR model; skipped/failing elsewhere. |
+| `make lint` | ruff check + ruff format --check + mypy | **Informational, non-blocking** (always exits 0). The inherited codebase predates linting; adopt fixes incrementally — it is *not* wired into the CI gate yet. |
+| `make fmt` | `ruff check --fix` + `ruff format` | Auto-fix lint + format `ragspine scripts tests`. |
+| `make drift` | `scripts/check_doc_drift.py` | Flags docs whose covered code changed since `verified-against`. Expect **10 tracked, 0 stale**. See `docs/README.md` for the convention. |
+
+GitHub Actions is dormant (manual-trigger only) to avoid consuming minutes — the local
+gate is authoritative.
+
+## Demo / ask / eval
+
+| Command | What it does | Notes |
+|---|---|---|
+| `make demo` | `scripts/run_demo.py` | Offline end-to-end; expect `ALL CHECKS PASSED`. |
+| `make ask Q="…"` | offline question via MockProvider | e.g. `make ask Q="中国内地FY2024的REVENUE是多少"`. Uses `--provider mock --db data/fact_metric.db`. Ask for missing data → honest refusal, never a guess. |
+| `make eval-qa` | `scripts/run_qa_eval.py` | QA harness, **baseline-gated** (fails on regression below the frozen floor; don't launder a regression with `--update-baseline`). |
+| `make eval-retrieval` | `scripts/eval_retrieval_ab.py` | BM25-vs-hybrid Recall@k / MRR. Default gold is synthetic (proves the harness math, not real recall). |
+
+## Service
+
+| Command | What it does | Notes |
+|---|---|---|
+| `make serve` | `scripts/run_server.py` | FastAPI app. |
+| `make worker` | `scripts/run_worker.py` | RQ worker — **needs Redis running**. Tests use `FakeQueue`, so this is only for real async runs. |
+
+## Fixtures / docs / housekeeping
+
+| Command | What it does | Notes |
+|---|---|---|
+| `make fixtures` | regenerate synthetic demo data | Deterministic, regenerable (`make_synthetic_deck` + `make_fixtures_{excel,pptx,pdf}`). **Never add real-world data.** |
+| `make docs` | `scripts/build_docs.py` | Static doc site (md→HTML). |
+| `make clean` | remove `__pycache__` + `.pytest_cache` / `.ruff_cache` / `.mypy_cache` | |
+
+## Typical loops
+
+- **Before pushing:** `make ci` (or just push — the pre-push hook runs it).
+- **TDD inner loop:** `make test` (fast, offline, deterministic).
+- **Touched docs/code contracts:** `make drift`.
+- **Cleaning up style:** `make fmt` then `make lint`.

rag_spine-0.1.1/.githooks/pre-push

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+#
+# Pre-push CI gate: run the local CI before allowing a push, so red code never leaves
+# your machine. This replaces server-side CI (no GitHub Actions minutes used).
+#
+# Enable once per clone:   git config core.hooksPath .githooks
+# Bypass in an emergency:  git push --no-verify
+#
+exec "$(git rev-parse --show-toplevel)/scripts/ci.sh"

rag_spine-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+# RAGSpine CI.
+#
+# ⚠️ DORMANT BY DESIGN — manual trigger only (`workflow_dispatch`). This workflow does NOT
+# run on push or pull_request, so it consumes ZERO GitHub Actions minutes automatically.
+# The real gate runs LOCALLY: `scripts/ci.sh`, enforced by the `.githooks/pre-push` hook.
+#
+# To enable server-side CI later (when you have Actions quota), uncomment the `push:` /
+# `pull_request:` triggers below. It runs the exact same `scripts/ci.sh` as your local gate.
+name: CI
+
+on:
+  workflow_dispatch:
+  # push:
+  #   branches: [main]
+  # pull_request:
+
+jobs:
+  ci:
+    strategy:
+      fail-fast: false
+      matrix:
+        # Expand to [ubuntu-latest, macos-latest, windows-latest] once enabled, if desired.
+        os: [ubuntu-latest]
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install (dev + service + pdf)
+        run: |
+          python -m pip install -U pip
+          pip install -e ".[dev,service,pdf]"
+      - name: Run the local CI gate
+        run: bash scripts/ci.sh
+        env:
+          PYTHON: python

rag_spine-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,57 @@
+# Release → PyPI via Trusted Publishing (OIDC — NO stored token / secret).
+#
+# Trigger: publishing a GitHub Release. The `gate` job runs the exact same checks as
+# `scripts/ci.sh` across the support matrix; only if every leg is green does `publish`
+# build + upload the `rag-spine` distribution.
+#
+# ── One-time PyPI setup (web UI; needs account login) ──────────────────────────────────
+# The `rag-spine` project already exists, so add a trusted publisher on it directly:
+#   Manage → rag-spine → Publishing → "Add a new publisher":
+#   Owner: VoldemortGin   Repository: ragspine   Workflow: release.yml   Environment: (blank)
+#
+# ── To cut a release ───────────────────────────────────────────────────────────────────
+# Bump `version` in pyproject.toml, commit, then publish a GitHub Release tagged e.g.
+# v0.1.0. The published version is taken from pyproject, not the tag — keep them in sync.
+name: Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  gate:
+    strategy:
+      fail-fast: true
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install (dev + service + pdf)
+        run: |
+          python -m pip install -U pip
+          pip install -e ".[dev,service,pdf]"
+      - name: Gate (scripts/ci.sh)
+        run: bash scripts/ci.sh
+        env:
+          PYTHON: python
+
+  publish:
+    needs: gate
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # OIDC — required for Trusted Publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install -U build
+          python -m build
+      - name: Publish to PyPI (Trusted Publishing / OIDC)
+        uses: pypa/gh-action-pypi-publish@release/v1

rag_spine-0.1.1/.gitignore

@@ -0,0 +1,40 @@
+# Virtualenvs & caches
+.venv/
+venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+*.pyc
+*.egg-info/
+build/
+dist/
+
+# data/ holds regenerable artifacts (synthetic fixtures, sqlite DBs) — ignore its
+# contents, but KEEP the directory present and force-track the version-controlled
+# golden evaluation sets. NOTE: this must be `data/*` (ignore contents), not `data/`
+# (ignore the dir) — git won't descend into a wholesale-excluded directory, so a bare
+# `!data/golden/` would have no effect.
+data/*
+!data/golden/
+!data/.gitkeep
+
+# Claude Code: share project settings, ignore local/personal overrides
+.claude/settings.local.json
+.claude/*.local.json
+
+# Generated docs (API ref, symbol/dependency indexes) — script-produced, regenerable.
+# Ignore contents but keep the directory present, mirroring the data/ rule above.
+docs/generated/*
+!docs/generated/.gitkeep
+
+# Built static doc site (make docs → pdoc API reference); regenerable, nginx-served.
+docs/site/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+
+# Local tooling artifacts (eval scratch output)
+.jbeval/

rag_spine-0.1.1/CLAUDE.md

@@ -0,0 +1,94 @@
+# CLAUDE.md — RAGSpine
+
+Working contract for AI coding sessions (and humans) on this repo. Read `README.md` for the
+full pitch; this file is the operational guide.
+
+## What this is
+
+RAGSpine — a **framework-free backend RAG engine** (no Dify/LangGraph). Deterministic
+dual-channel (structured numeric + narrative RAG) + agent orchestration, with
+**anti-fabrication** and **source provenance** as code-enforced invariants. Every external
+dependency is a `Protocol`, so the core imports zero SDKs and runs offline.
+
+## Layout (deep, domain-grouped — find the file by folder first)
+
+```
+src/ragspine/{common, extraction, ingestion, storage, retrieval, agent, eval, service}
+```
+
+See the "Architecture" tree in `README.md` for what lives where and the request flow.
+
+## Docs map (find docs by folder, like code)
+
+Docs are a retrieval system, not a library — at scale no agent reads them whole.
+Full convention in `docs/README.md`. Short version:
+
+- **This file** — the always-on routing table. Keep it small; no content lives here.
+- `src/ragspine/<domain>/CLAUDE.md` — per-domain contract, auto-loaded in that subtree.
+- `src/ragspine/<domain>/docs/*.md` — deep dives, pulled by grep / explicit read.
+- `docs/` — cross-cutting: `architecture.md`, `invariants.md`, `glossary.md`, `adr/`.
+- `docs/generated/` — script-produced (API ref, indexes); git-ignored, never hand-edited.
+
+Docs describing code carry `covers:` + `verified-against:` frontmatter;
+`scripts/check_doc_drift.py` flags any whose code changed since last verified.
+
+## Run (always from the project root)
+
+- **Make:** common commands are wrapped in the repo-root `Makefile` — `make help` lists them
+  (`make install` · `make ci` · `make test` · `make demo` · `make lint` · `make fmt` ·
+  `make drift` · `make hooks` · `make serve`/`make worker` · `make ask Q="…"`). Override the
+  interpreter with `make <t> PYTHON=python3.12`. The raw commands below remain the source of truth.
+- **Setup:** `uv venv .venv` then `VIRTUAL_ENV="$(pwd)/.venv" uv pip install -e ".[dev,service]"`
+  (the `VIRTUAL_ENV=` prefix is required so `uv` targets this venv, not a system Python).
+  Extras: `[pdf]` `[ocr]` `[llm]` `[embed]`.
+- **Tests:** `.venv/bin/python -m pytest tests/ -q` → expect **1078 passed, 1 gpu-skipped**.
+- **CI (local):** `scripts/ci.sh` is the gate (tests + demo smoke); enable the pre-push hook
+  once with `git config core.hooksPath .githooks`. GitHub Actions is dormant (manual-only) to
+  avoid consuming quota — see README "Continuous integration (local)".
+- **Demo:** `.venv/bin/python scripts/run_demo.py` → expect `ALL CHECKS PASSED`.
+- **Ask:** `.venv/bin/python scripts/ask.py --provider mock --db data/fact_metric.db "中国内地FY2024的REVENUE是多少"`.
+- **Service:** `scripts/run_server.py` (FastAPI) + `scripts/run_worker.py` (RQ, needs Redis).
+
+## Conventions
+
+- **TDD** — tests are the spec: write the failing test first, then implement to green.
+  Never weaken a test to make it pass; if a frozen/regression test breaks, you broke behavior.
+- Python **3.10+** type hints. Import order: **stdlib > third-party > local**. Stay simple;
+  match the surrounding style.
+- **Deep, domain-grouped layout** — organize by domain/feature, never by technical layer
+  (a *Screaming Architecture* / *package-by-feature* stance): the folder path should locate a
+  file before you read its name. Split a package as soon as it holds a second responsibility;
+  prefer pushing code into a deeper domain subtree over letting a flat module become a
+  catch-all. Depth tracks responsibility — go as deep as each level earns a distinct concern.
+- **Cross-platform** (`pathlib`, no OS-specific calls). Run scripts/tests from the repo root.
+- **Minimal diff** — change only what the task needs; don't refactor unrelated code or delete
+  pre-existing dead code.
+
+## Invariants (do not break)
+
+- **Anti-fabrication** — when the structured channel returns no `found` fact, the orchestrator
+  rewrites the answer to "not found" regardless of model output (`agent/agent.py`).
+- **Provenance** — every fact/answer carries `source_doc_id` + locator. Don't drop lineage.
+- **RESTRICTED isolation** — sensitivity-`RESTRICTED` content is filtered at **two** exits
+  (`retrieval/link`, `retrieval/rerank`) before it can reach a prompt.
+- **Privacy-aware traces** — `common/observability` records codes/counts/timings only, never
+  answer / fact value / chunk text.
+- **Config-driven, no hardcoded company** — identity / metrics / competitors come from
+  `CompanyProfile` (`config/company.example.toml`). Don't hardcode a company anywhere.
+- **Pluggability** — LLM / embeddings / reranker / OCR / queue are `Protocol`s, lazy-imported.
+  The core runs offline with `MockProvider`.
+
+## Demo data
+
+The bundled demo uses a **fictional** company (ACME), synthetic figures, and a fictional
+competitor set, generated by `scripts/make_*.py` (deterministic, regenerable). The
+version-controlled golden evaluation sets live under `data/golden/` (force-tracked via the
+`.gitignore` `!data/golden/` rule). **Never add real-world data.**
+
+## Service layer
+
+`service/`: `ServiceConfig` (env `RAGSPINE_*`), FastAPI app (app factory + dependency
+injection), RQ task queue (`FakeQueue` for tests, `RQQueue` for prod), ingestion jobs
+(worker-owned stores), and the FAQ short-circuit cache. The FAQ layer must keep its
+conservative exclusions (structured-numeric / competitor / real-time / expired / disabled /
+RESTRICTED never short-circuit) — it sits in front of the anti-fabrication guard.

rag_spine-0.1.1/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do
+          not modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 The RAGSpine Authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

rag_spine-0.1.1/Makefile

@@ -0,0 +1,127 @@
+# RAGSpine — common dev / CI-CD commands.
+#
+# `make` or `make help` lists every target. Targets honour the project venv by default;
+# override the interpreter with:  make test PYTHON=python3.12
+#
+# Always run from the repo root (the scripts anchor on .project-root).
+
+.DEFAULT_GOAL := help
+PYTHON ?= .venv/bin/python
+VENV   ?= .venv
+
+# ---- setup ---------------------------------------------------------------------------
+
+.PHONY: venv
+venv: ## Create the project virtualenv (.venv) with uv
+	uv venv $(VENV)
+
+.PHONY: install
+install: ## Editable install with dev+service extras (the usual dev setup)
+	VIRTUAL_ENV="$(CURDIR)/$(VENV)" uv pip install -e ".[dev,service]"
+
+.PHONY: install-all
+install-all: ## Editable install with all non-GPU extras (dev,service,llm,embed)
+	VIRTUAL_ENV="$(CURDIR)/$(VENV)" uv pip install -e ".[dev,service,llm,embed]"
+
+.PHONY: hooks
+hooks: ## Enable the pre-push CI gate (one-time, per clone)
+	git config core.hooksPath .githooks
+	@echo "pre-push CI gate enabled (emergency bypass: git push --no-verify)"
+
+# ---- quality gate --------------------------------------------------------------------
+
+.PHONY: ci
+ci: ## Local CI gate: tests + demo smoke (exactly what pre-push runs)
+	PYTHON=$(PYTHON) scripts/ci.sh
+
+.PHONY: test
+test: ## Run the test suite (excludes gpu-marked tests)
+	$(PYTHON) -m pytest tests/ -q -m "not gpu"
+
+.PHONY: test-all
+test-all: ## Run the full suite including gpu-marked tests
+	$(PYTHON) -m pytest tests/ -q
+
+.PHONY: lint
+lint: ## ruff + mypy (informational, non-blocking)
+	PYTHON=$(PYTHON) scripts/lint.sh
+
+.PHONY: fmt
+fmt: ## Auto-fix lint and format with ruff
+	$(PYTHON) -m ruff check --fix src/ragspine scripts tests
+	$(PYTHON) -m ruff format src/ragspine scripts tests
+
+.PHONY: drift
+drift: ## Flag docs whose covered code changed since last verified
+	$(PYTHON) scripts/check_doc_drift.py
+
+# ---- demo / eval ---------------------------------------------------------------------
+
+.PHONY: demo
+demo: ## Run the offline end-to-end demo (expects ALL CHECKS PASSED)
+	$(PYTHON) scripts/run_demo.py
+
+.PHONY: ask
+ask: ## Ask offline, e.g. make ask Q="中国内地FY2024的REVENUE是多少"
+	$(PYTHON) scripts/ask.py --provider mock --db data/fact_metric.db "$(Q)"
+
+.PHONY: eval-qa
+eval-qa: ## QA evaluation against the golden set (baseline-gated)
+	$(PYTHON) scripts/run_qa_eval.py
+
+.PHONY: eval-retrieval
+eval-retrieval: ## BM25-vs-hybrid retrieval A/B harness
+	$(PYTHON) scripts/eval_retrieval_ab.py
+
+# ---- service -------------------------------------------------------------------------
+
+.PHONY: serve
+serve: ## Run the FastAPI server
+	$(PYTHON) scripts/run_server.py
+
+.PHONY: worker
+worker: ## Run the RQ worker (needs Redis)
+	$(PYTHON) scripts/run_worker.py
+
+# ---- fixtures / docs -----------------------------------------------------------------
+
+.PHONY: fixtures
+fixtures: ## Regenerate the synthetic demo fixtures (deterministic)
+	$(PYTHON) scripts/make_synthetic_deck.py
+	$(PYTHON) scripts/make_fixtures_excel.py
+	$(PYTHON) scripts/make_fixtures_pptx.py
+	$(PYTHON) scripts/make_fixtures_pdf.py
+
+.PHONY: docs
+docs: ## Build the static API-reference site from docstrings (pdoc → docs/site, nginx-ready)
+	$(PYTHON) -m pdoc ragspine -o docs/site
+	@echo "API docs → docs/site/  (deploy: point nginx 'root' at $(abspath docs/site))"
+
+.PHONY: clean
+clean: ## Remove caches (pyc, pytest/ruff/mypy) and build artifacts
+	find . -type d -name __pycache__ -prune -exec rm -rf {} +
+	rm -rf .pytest_cache .ruff_cache .mypy_cache dist build *.egg-info
+
+# ---- release -------------------------------------------------------------------------
+
+.PHONY: build
+build: ## Build wheel + sdist into dist/ and validate with twine check
+	rm -rf dist
+	$(PYTHON) -m build
+	$(PYTHON) -m twine check dist/*
+
+.PHONY: publish-test
+publish-test: build ## Build, then upload to TestPyPI (rehearse a real release; needs a TestPyPI token)
+	$(PYTHON) -m twine upload --repository testpypi dist/*
+
+.PHONY: publish
+publish: build ## Build, then upload to PyPI (real release; needs a PyPI token)
+	$(PYTHON) -m twine upload dist/*
+
+# ---- meta ----------------------------------------------------------------------------
+
+.PHONY: help
+help: ## List available targets
+	@grep -hE '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) \
+		| sort \
+		| awk 'BEGIN{FS=":.*?## "}{printf "  \033[36m%-16s\033[0m %s\n", $$1, $$2}'