quarry-kb 0.1.0__tar.gz

quarry_kb-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,84 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+    tags: ["v*", "test-v*"]  # release / testpypi jobs gate on the tag ref
+  pull_request:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 6 * * 1"  # weekly — exercises the gated integration job
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Lint
+        run: uv run --python ${{ matrix.python-version }} --extra dev ruff check .
+      - name: Test (hermetic, no network) + coverage gate
+        run: |
+          uv run --python ${{ matrix.python-version }} --extra dev --extra all \
+            python -m coverage run -m pytest -q
+          uv run --python ${{ matrix.python-version }} --extra dev --extra all \
+            python -m coverage report --fail-under=90
+      - name: Coverage XML
+        run: uv run --python ${{ matrix.python-version }} --extra dev python -m coverage xml
+      - name: Upload coverage
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-${{ matrix.python-version }}
+          path: coverage.xml
+
+  # Live network tests for the adapters — manual/nightly only, never in the default gate.
+  integration:
+    if: github.event_name == 'workflow_dispatch' || github.event_name == 'schedule'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv python install 3.12
+      - name: Integration tests
+        run: uv run --python 3.12 --extra dev --extra all python -m pytest -m integration -q
+
+  # Dry-run publish to TestPyPI via trusted publishing. Fires on a `test-v*` tag
+  # (e.g. test-v0.1.0) — a throwaway rehearsal of the real release flow.
+  testpypi:
+    if: startsWith(github.ref, 'refs/tags/test-v')
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build
+        run: uv build
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  # Tagged-release publish to PyPI via trusted publishing. DEFERRED: wired but only
+  # fires on a version tag, which is not pushed until publishing is enabled.
+  release:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

quarry_kb-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# transient — build reference only, delete after extraction
+EXTRACTION-SOURCE-kb.py
+.quarry/
+__pycache__/
+*.pyc
+
+# Python tooling
+.venv/
+.coverage
+htmlcov/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+uv.lock

quarry_kb-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to Quarry are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and Quarry adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial implementation, generalised from the private `bin/kb` harness.
+- Configuration layer (`quarry.toml`) with `quarry init` scaffolding a fully-commented
+  default; walk-up discovery, `[tool.quarry]` fallback, validation (unknown-key warnings,
+  type and enum errors), and a `Config` dataclass threaded through every command.
+- Store path templating: `raw_layout` and `slug` from config across the full token set.
+- Compile-manifest seam (`manifest.py`) — write/load/hash round-trip.
+- Adapters: contract + registry with entry-point plugin discovery and an `enabled`
+  allowlist; built-in `youtube` and `web` adapters (extras-gated, hermetically tested).
+- `ingest` (resolve → fetch → raw → manifest with an `on_duplicate` dedup pre-check) and
+  `finish` (provenance verify → lint → commit, push only when opted in).
+- Config-driven structural-health `lint` returning a structured `LintResult`, with a
+  golden-output test.
+- Optional `discovery` backend (`qmd`) powering dedup, `related`, and `densify`; degrades
+  gracefully when the backend is `none` or the tool is absent.
+- `doctor` command; commands `init`, `adapters`, `ingest`, `finish`, `lint`, `related`,
+  `densify`.
+- Extensive hermetic test suite (no network, no API keys) with a ≥90% coverage gate,
+  `ruff`, and a Python 3.11–3.13 CI matrix.
+
+[Unreleased]: https://github.com/asachs/quarry-kb/commits/master

quarry_kb-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing to Quarry
+
+Thanks for your interest. Quarry is small, deterministic, and heavily tested by design —
+contributions are expected to keep it that way.
+
+## Development setup
+
+Quarry uses [`uv`](https://docs.astral.sh/uv/) for environments and Python management.
+
+```bash
+uv run --extra dev --extra all python -m pytest      # run the suite
+uv run --extra dev ruff check .                      # lint
+uv run --extra dev --extra all python -m coverage run -m pytest \
+  && uv run --extra dev python -m coverage report --fail-under=90
+```
+
+Quality gates (enforced in CI): **all tests pass**, **`ruff` clean**, **coverage ≥ 90%**,
+across Python 3.11–3.13.
+
+## The adapter contract
+
+A new source type is a small, self-contained adapter — no fork required.
+
+```python
+from quarry.adapters.base import Adapter, FetchResult
+
+class PdfAdapter(Adapter):
+    name = "pdf"
+
+    def matches(self, url: str) -> bool:
+        return url.lower().endswith(".pdf")
+
+    def fetch(self, url: str) -> FetchResult:
+        # Put network/IO in small overridable methods so tests stay hermetic.
+        return FetchResult(content="...", metadata={
+            "title": "...", "url": url, "date": "2026-01-01", "source_id": "...",
+        })
+```
+
+Register it via an entry point in your package's `pyproject.toml`:
+
+```toml
+[project.entry-points."quarry.adapters"]
+pdf = "your_package.pdf:PdfAdapter"
+```
+
+Then enable it in the consuming wiki's `quarry.toml`:
+
+```toml
+[adapters]
+enabled = ["youtube", "web", "pdf"]
+```
+
+### Requirements for an adapter PR
+
+1. **Hermetic test.** Network calls live behind overridable methods; tests use a recorded
+   fixture/cassette and must pass with no network and no API keys.
+2. **One `@pytest.mark.integration` live test** is allowed (excluded from the default run).
+3. **Clean errors.** A missing optional dependency raises a `QuarryError` with an install
+   hint — never a bare `ImportError` traceback.
+
+## Principles to respect
+
+- **Quarry never calls an LLM.** The article-writing step happens between `ingest` and
+  `finish`, performed by a human or agent — not by Quarry.
+- **No hardcoded conventions.** Everything configurable flows through the `Config` dataclass.
+- **Fail loud, fail tested.** Every mechanical step has a test that catches its break.