pinakes 0.2.2__tar.gz

pinakes-0.2.2/.github/workflows/ci.yml

@@ -0,0 +1,168 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # Three legs (I1): the light-only core, [pdf] added, then [claude] added on top. Each is a
+        # supported install state (docs/DESIGN.md §4.5) and each must pass this job on its own —
+        # a matrix that stopped at [light] would prove nothing about the other two for six
+        # increments, the exact gap I1's own exit criterion closes.
+        extras: ["light", "light pdf", "light pdf claude"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install Python and dependencies
+        # The [light] extra, never [st]: a 2GB torch download per job is untenable, and fastembed
+        # exercises the same protocols (docs/DESIGN.md §4.5). [pdf]/[claude] install one pure-Python
+        # SDK apiece and never call them — this job proves the extra installs and imports cleanly,
+        # not that the paid path works.
+        run: |
+          set -e
+          args=""
+          for extra in ${{ matrix.extras }}; do
+            args="$args --extra $extra"
+          done
+          uv sync --frozen $args
+
+      # Model weights are a download, not an install. Keyed on the models the demo KB names, so a
+      # model change invalidates the cache and nothing else does. Without this the reranker alone
+      # would pull ~1GB per job.
+      - name: Cache model weights
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/huggingface
+          key: hf-${{ hashFiles('tests/demo-kb/pinakes.toml') }}
+          restore-keys: hf-
+
+      - name: Format
+        run: uv run --frozen ruff format --check .
+
+      - name: Lint
+        run: uv run --frozen ruff check .
+
+      - name: Types (ty, fast pre-check)
+        run: uv run --frozen ty check --extra-search-path stubs .
+
+      - name: Types (pyright, strict — the gate)
+        run: uv run --frozen pyright
+
+      - name: Tests
+        # Warnings are errors here (pyproject), which is how a deprecation reaches a human.
+        run: uv run --frozen pytest -q
+
+      - name: Model-backed tests
+        # Pinned to the [light] leg alone (I1): `_runnable()` skips only when fastembed is absent or
+        # the HF cache is empty, both true on every leg alike, so this dedicated step would triple
+        # for no benefit on the other two. (The Tests step above already runs these once per leg too
+        # when the cache is warm — this step's own redundancy predates the matrix and is unrelated.)
+        if: matrix.extras == 'light'
+        run: uv run --frozen pytest -q -m model
+
+  eval:
+    # The scoreboard §7 requires: a retrieval change has to move these numbers, and a regression
+    # beyond tolerance fails the build rather than being noticed later.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - run: uv sync --frozen --extra light
+
+      - name: Cache model weights
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/huggingface
+          key: hf-${{ hashFiles('tests/demo-kb/pinakes.toml') }}
+          restore-keys: hf-
+
+      - name: Index the demo KB
+        run: uv run --frozen pnk sync --kb tests/demo-kb
+
+      - name: Health check
+        run: uv run --frozen pnk doctor --kb tests/demo-kb
+
+      - name: Golden-set evaluation against the baseline
+        run: uv run --frozen python -m pinakes.eval tests/demo-kb
+
+  pdf-eval:
+    # I3b: joins CI in the same commit that adds the gate, not deferred until I9 the way the draft
+    # plan would have left it for six intervening increments to land ungated.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - run: uv sync --frozen --extra light --extra pdf
+
+      - name: Extraction-quality baseline + floor-drift check
+        run: |
+          uv run --frozen python -m pinakes.extract.quality tests/pdf-corpus \
+            --check-floors src/pinakes/extract/floors.toml
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Build the wheel and sdist
+        run: uv build
+
+      # Proves the templates travel inside the wheel. `pnk init` reads them through
+      # importlib.resources, so a packaging mistake is invisible until someone installs it.
+      - name: Smoke-test the built wheel
+        run: |
+          set -e
+          uv run --isolated --no-project --with dist/*.whl pnk --version
+          mkdir -p /tmp/smoke
+          uv run --isolated --no-project --with dist/*.whl pnk init /tmp/smoke/kb
+          test -f /tmp/smoke/kb/pinakes.toml
+          test -f /tmp/smoke/kb/eval/questions.yaml
+          grep -q '.pinakes/' /tmp/smoke/kb/.gitignore
+
+      # plans/v0.1.md promised this gate under "Verification of the whole" and it never shipped:
+      # the item carried no increment number, so no increment owned it (see that plan's close-out,
+      # rule 8). The invariant holds structurally today — core deps are jinja2, mcp, numpy,
+      # python-ulid, pyyaml — but "holds today" is not "cannot break", and CLAUDE.md calls the free
+      # path non-negotiable.
+      - name: The free path stays free — no paid-API client imported in src/
+        run: |
+          set -e
+          if grep -rniE '^[[:space:]]*(import|from)[[:space:]]+(anthropic|openai|cohere|mistralai|google\.generativeai)\b' src/; then
+            echo "::error::A paid-API client is imported in src/. DESIGN §1: no code path may make a paid call outside 'pnk ask --deep'." >&2
+            exit 1
+          fi
+          echo "no paid-API imports in src/"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

pinakes-0.2.2/.github/workflows/release.yml

@@ -0,0 +1,57 @@
+name: Release
+
+# Publishing is deliberately manual: it runs only when a maintainer pushes a v* tag, never on a
+# merge. PyPI trusted publishing must be configured for this repository first — a human step that
+# cannot be automated from here (plans/v0.1.md, I15).
+#
+# Until that human step happens, the PyPI upload is *skipped rather than attempted*, gated on the
+# repository variable PUBLISH_TO_PYPI. Everything before it still runs on every tag — version/tag
+# agreement, build, and the isolated wheel smoke test — so a tag is fully validated even when
+# nothing is uploaded, and pushing one never produces a red run for a reason the maintainer
+# already knows about. To start publishing: configure trusted publishing on PyPI, then set the
+# variable (`gh variable set PUBLISH_TO_PYPI --body true`). Nothing else here changes.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write        # trusted publishing; no API token is stored anywhere
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Refuse a tag that disagrees with the package version
+        run: |
+          set -e
+          tag="${GITHUB_REF_NAME#v}"
+          version="$(uv run --frozen python -c 'import pinakes; print(pinakes.__version__)')"
+          if [ "$tag" != "$version" ]; then
+            echo "tag $tag does not match pinakes $version" >&2
+            exit 1
+          fi
+
+      - run: uv build
+
+      - name: Smoke-test the wheel before it leaves the building
+        run: |
+          set -e
+          uv run --isolated --no-project --with dist/*.whl pnk --version
+          uv run --isolated --no-project --with dist/*.whl pnk init /tmp/release-smoke
+          test -f /tmp/release-smoke/pinakes.toml
+
+      - name: Publish to PyPI
+        if: vars.PUBLISH_TO_PYPI == 'true'
+        run: uv publish
+
+      - name: Explain why nothing was published
+        if: vars.PUBLISH_TO_PYPI != 'true'
+        run: |
+          echo "::notice::PUBLISH_TO_PYPI is not 'true' — the wheel was built and smoke-tested but not uploaded."
+          echo "Configure PyPI trusted publishing, then: gh variable set PUBLISH_TO_PYPI --body true"

pinakes-0.2.2/.gitignore

@@ -0,0 +1,26 @@
+# Generated KB state — index, spend ledger, caches. Never committed, always rebuildable.
+.pinakes/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Models and data that must never enter a public repo
+*.safetensors
+*.onnx
+*.bin
+
+# OS
+.DS_Store