proactive-librarian 0.1.0__tar.gz

proactive_librarian-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Orban
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

proactive_librarian-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: proactive-librarian
+Version: 0.1.0
+Summary: Index a PDF library and answer queries with page-accurate citations. Backend-agnostic; ships with a QMD adapter.
+Author: David Orban
+License: MIT
+Project-URL: Source, https://github.com/davidorban/proactive-librarian
+Keywords: pdf,search,rag,citation,qmd
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Text Processing :: Indexing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pypdf>=4.0
+Requires-Dist: cryptography>=3.1
+Requires-Dist: tqdm>=4.65
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Dynamic: license-file
+
+# proactive-librarian
+
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Status](https://img.shields.io/badge/status-v0.1.0-orange.svg)](CHANGELOG.md)
+
+> Turn a directory of PDFs into a searchable index and get back **page-accurate citations** like `Report.pdf:p.27`.
+
+`proactive-librarian` indexes a large document library once, then answers queries with the exact file **and page number** — ready to paste into a memo, brief, paper, or deck. It is a sharp, single-purpose CLI tool: not a chatbot, not a RAG framework, not a vector database you have to operate. Backend-agnostic, with a [QMD](https://github.com/eatonphil/qmd) adapter shipped in the box.
+
+It replaces the brutal friction of citing your own research at scale — folder grep is slow, filenames lie, and Ctrl+F across thousands of PDFs is unworkable.
+
+## Features
+
+- 📄 **Page-accurate citations** — results come back as `file.pdf:p.N`, the page number derived from the cache path, not parsed (and mis-parsed) from a snippet.
+- 🔍 **Hybrid retrieval** — keyword + semantic search via the backend (QMD adapter included; bring your own).
+- ♻️ **Deterministic, reproducible cache** — rebuildable from the PDFs at any time; safe to delete.
+- 🧱 **Page-per-file layout** — pure page text with no metadata leakage into snippets (see [why](#why-page-per-file)).
+- 🔐 **Robust ingest** — handles AES-encrypted PDFs, sanitises surrogate/4-byte characters, and logs every failure with a reason to `_failures.json`.
+- 🗂️ **Optional taxonomy enforcement** — constrain the library to a known subject/geography scheme and fail loudly on stragglers.
+- ⚡ **Incremental** — sha1 manifest means re-ingest only touches changed PDFs.
+- ✅ **Tested** — 36+ pytest cases over hashing, path mapping, manifest persistence, atomic writes, failure logging, and taxonomy validation.
+
+## Who it's for
+
+Built originally for one person's research-citation workflow, but it solves a general problem — **anyone who maintains a large PDF/document library and needs to quote it with precision**:
+
+- researchers and analysts citing a corpus of papers/reports,
+- policy, legal, and compliance teams working from regulatory documents,
+- technical writers and maintainers grounding docs in source material,
+- AI agents/assistants that need **citation-grounded retrieval** they can shell out to (`librarian query "…"`).
+
+## Install
+
+Not yet on PyPI. Install from source:
+
+```bash
+pip install git+https://github.com/davidorban/proactive-librarian
+# or, for local development:
+git clone https://github.com/davidorban/proactive-librarian
+cd proactive-librarian
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+You also need a search backend. The shipped adapter targets **QMD** — install it from https://github.com/eatonphil/qmd (or implement another backend; see [ADR-001](docs/adr/ADR-001-storage-substrate.md)).
+
+## Quickstart
+
+```bash
+# 1. Point at your PDF library
+cat > proactive-librarian.yaml <<'EOF'
+pdf_root: /path/to/your/pdfs
+collection_name: research
+EOF
+
+# 2. Index (first run; ~30 min for ~1,400 PDFs, then incremental)
+librarian ingest --full
+
+# 3. Tell your backend about the new cache (one-time; see backend docs)
+
+# 4. Query
+librarian query "stablecoin regulation in the UAE"
+```
+
+Example output:
+
+```
+1. Digital-Assets-Regulatory-Landscape.pdf:p.27   (0.81)
+   "...the payment-token services regulation establishes a licensing regime for fiat-backed..."
+2. ADGM-Virtual-Asset-Framework-2025.pdf:p.12      (0.74)
+   "...issuers must maintain reserves on a 1:1 basis, audited monthly by an approved..."
+3. Stablecoin-Market-Structure.pdf:p.4             (0.69)
+   "...redemption-at-par guarantees are the load-bearing assumption behind..."
+```
+
+Paste the `file.pdf:p.N` straight into your draft.
+
+## What it produces
+
+```
+<pdf_root>/.derived/
+├── _manifest.json                    # sha1 cache for incremental re-ingest
+├── _failures.json                    # last run's failed PDFs (with reasons)
+└── <rel-pdf-stem-tree>/
+    ├── _meta.json                    # per-PDF metadata sidecar (NOT indexed)
+    ├── p0001.md                      # pure page text — no frontmatter
+    ├── p0002.md
+    └── ...
+```
+
+The cache lives next to the PDFs in `.derived/` (gitignored), is **reproducible** from the source PDFs, and is safe to delete and rebuild. The PDFs stay canonical; the markdown is a disposable index ([ADR-004](docs/adr/ADR-004-pdf-canonical-cache.md)).
+
+## Why page-per-file?
+
+Single-file-per-PDF chunking has two failure modes:
+
+1. **Metadata leaks into snippets.** YAML frontmatter gets indexed with the content, so citation snippets end up containing `sha1: abc…` and `source_pdf: …`.
+2. **Page numbers become unreliable.** When a chunk spans page boundaries, parsing `## Page N` markers collapses everything to `p.1` and citations lose precision.
+
+Page-per-file fixes both: each markdown file holds only one page's text (nothing to leak), and the page number is a property of the path (`p0042.md` → page 42). The trade-off is a high file count (~1,377 PDFs × ~50 pages ≈ 67k files); modern filesystems (APFS, ext4) handle it fine. Full rationale in [ADR-002](docs/adr/ADR-002-page-level-granularity.md).
+
+## Configuration
+
+`proactive-librarian.yaml` in the working directory, or `--config /path/to/config.yaml`:
+
+```yaml
+# Required
+pdf_root: /path/to/pdfs
+
+# Optional (defaults shown)
+derived_dir: .derived              # relative to pdf_root
+collection_name: research          # backend collection key
+
+taxonomy:                          # optional subject-category enforcement
+  enabled: false
+  allowed_subjects: []             # first path component under pdf_root must match
+
+backend:
+  type: qmd
+  binary: qmd                      # on PATH, or an absolute path
+  timeout_seconds: 30
+```
+
+With no config file present, it runs with permissive defaults (`pdf_root: .`, no taxonomy). See [`examples/`](examples/) for annotated config and taxonomy files.
+
+## Architecture
+
+Five load-bearing decisions, each documented as an ADR:
+
+| ADR | Decision |
+|-----|----------|
+| [ADR-001](docs/adr/ADR-001-storage-substrate.md) | QMD as the search substrate, not a standalone vector DB |
+| [ADR-002](docs/adr/ADR-002-page-level-granularity.md) | Page-per-file granularity, not paragraph chunks |
+| [ADR-003](docs/adr/ADR-003-explicit-invocation.md) | Explicit CLI invocation, not an ambient hook (yet) |
+| [ADR-004](docs/adr/ADR-004-pdf-canonical-cache.md) | PDFs canonical; markdown is a disposable cache |
+| [ADR-005](docs/adr/ADR-005-no-new-services.md) | A Python package + adapter, not a long-running service |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest          # 36+ cases
+ruff check .    # lint
+```
+
+## Roadmap
+
+- Additional backends beyond QMD (the adapter boundary already exists).
+- Publish to PyPI for a plain `pip install proactive-librarian`.
+- Optional ambient/agent invocation surface (the explicit-CLI decision in ADR-003 is revisitable as adoption grows).
+- Richer query output formats (JSON, BibTeX-style citation export).
+
+## Contributing
+
+Issues and pull requests welcome. The codebase is small and well-tested — run `pytest` and `ruff check .` before opening a PR. If you're adding a backend, start from the QMD adapter and the ADR-001 rationale.
+
+## License
+
+[MIT](LICENSE) © David Orban.
+
+## Status
+
+**v0.1.0** — in single-user production use; the API will stabilise as more backends and surfaces are added. The cache format and CLI are stable. See [CHANGELOG.md](CHANGELOG.md).

proactive_librarian-0.1.0/README.md

@@ -0,0 +1,164 @@
+# proactive-librarian
+
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Status](https://img.shields.io/badge/status-v0.1.0-orange.svg)](CHANGELOG.md)
+
+> Turn a directory of PDFs into a searchable index and get back **page-accurate citations** like `Report.pdf:p.27`.
+
+`proactive-librarian` indexes a large document library once, then answers queries with the exact file **and page number** — ready to paste into a memo, brief, paper, or deck. It is a sharp, single-purpose CLI tool: not a chatbot, not a RAG framework, not a vector database you have to operate. Backend-agnostic, with a [QMD](https://github.com/eatonphil/qmd) adapter shipped in the box.
+
+It replaces the brutal friction of citing your own research at scale — folder grep is slow, filenames lie, and Ctrl+F across thousands of PDFs is unworkable.
+
+## Features
+
+- 📄 **Page-accurate citations** — results come back as `file.pdf:p.N`, the page number derived from the cache path, not parsed (and mis-parsed) from a snippet.
+- 🔍 **Hybrid retrieval** — keyword + semantic search via the backend (QMD adapter included; bring your own).
+- ♻️ **Deterministic, reproducible cache** — rebuildable from the PDFs at any time; safe to delete.
+- 🧱 **Page-per-file layout** — pure page text with no metadata leakage into snippets (see [why](#why-page-per-file)).
+- 🔐 **Robust ingest** — handles AES-encrypted PDFs, sanitises surrogate/4-byte characters, and logs every failure with a reason to `_failures.json`.
+- 🗂️ **Optional taxonomy enforcement** — constrain the library to a known subject/geography scheme and fail loudly on stragglers.
+- ⚡ **Incremental** — sha1 manifest means re-ingest only touches changed PDFs.
+- ✅ **Tested** — 36+ pytest cases over hashing, path mapping, manifest persistence, atomic writes, failure logging, and taxonomy validation.
+
+## Who it's for
+
+Built originally for one person's research-citation workflow, but it solves a general problem — **anyone who maintains a large PDF/document library and needs to quote it with precision**:
+
+- researchers and analysts citing a corpus of papers/reports,
+- policy, legal, and compliance teams working from regulatory documents,
+- technical writers and maintainers grounding docs in source material,
+- AI agents/assistants that need **citation-grounded retrieval** they can shell out to (`librarian query "…"`).
+
+## Install
+
+Not yet on PyPI. Install from source:
+
+```bash
+pip install git+https://github.com/davidorban/proactive-librarian
+# or, for local development:
+git clone https://github.com/davidorban/proactive-librarian
+cd proactive-librarian
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+You also need a search backend. The shipped adapter targets **QMD** — install it from https://github.com/eatonphil/qmd (or implement another backend; see [ADR-001](docs/adr/ADR-001-storage-substrate.md)).
+
+## Quickstart
+
+```bash
+# 1. Point at your PDF library
+cat > proactive-librarian.yaml <<'EOF'
+pdf_root: /path/to/your/pdfs
+collection_name: research
+EOF
+
+# 2. Index (first run; ~30 min for ~1,400 PDFs, then incremental)
+librarian ingest --full
+
+# 3. Tell your backend about the new cache (one-time; see backend docs)
+
+# 4. Query
+librarian query "stablecoin regulation in the UAE"
+```
+
+Example output:
+
+```
+1. Digital-Assets-Regulatory-Landscape.pdf:p.27   (0.81)
+   "...the payment-token services regulation establishes a licensing regime for fiat-backed..."
+2. ADGM-Virtual-Asset-Framework-2025.pdf:p.12      (0.74)
+   "...issuers must maintain reserves on a 1:1 basis, audited monthly by an approved..."
+3. Stablecoin-Market-Structure.pdf:p.4             (0.69)
+   "...redemption-at-par guarantees are the load-bearing assumption behind..."
+```
+
+Paste the `file.pdf:p.N` straight into your draft.
+
+## What it produces
+
+```
+<pdf_root>/.derived/
+├── _manifest.json                    # sha1 cache for incremental re-ingest
+├── _failures.json                    # last run's failed PDFs (with reasons)
+└── <rel-pdf-stem-tree>/
+    ├── _meta.json                    # per-PDF metadata sidecar (NOT indexed)
+    ├── p0001.md                      # pure page text — no frontmatter
+    ├── p0002.md
+    └── ...
+```
+
+The cache lives next to the PDFs in `.derived/` (gitignored), is **reproducible** from the source PDFs, and is safe to delete and rebuild. The PDFs stay canonical; the markdown is a disposable index ([ADR-004](docs/adr/ADR-004-pdf-canonical-cache.md)).
+
+## Why page-per-file?
+
+Single-file-per-PDF chunking has two failure modes:
+
+1. **Metadata leaks into snippets.** YAML frontmatter gets indexed with the content, so citation snippets end up containing `sha1: abc…` and `source_pdf: …`.
+2. **Page numbers become unreliable.** When a chunk spans page boundaries, parsing `## Page N` markers collapses everything to `p.1` and citations lose precision.
+
+Page-per-file fixes both: each markdown file holds only one page's text (nothing to leak), and the page number is a property of the path (`p0042.md` → page 42). The trade-off is a high file count (~1,377 PDFs × ~50 pages ≈ 67k files); modern filesystems (APFS, ext4) handle it fine. Full rationale in [ADR-002](docs/adr/ADR-002-page-level-granularity.md).
+
+## Configuration
+
+`proactive-librarian.yaml` in the working directory, or `--config /path/to/config.yaml`:
+
+```yaml
+# Required
+pdf_root: /path/to/pdfs
+
+# Optional (defaults shown)
+derived_dir: .derived              # relative to pdf_root
+collection_name: research          # backend collection key
+
+taxonomy:                          # optional subject-category enforcement
+  enabled: false
+  allowed_subjects: []             # first path component under pdf_root must match
+
+backend:
+  type: qmd
+  binary: qmd                      # on PATH, or an absolute path
+  timeout_seconds: 30
+```
+
+With no config file present, it runs with permissive defaults (`pdf_root: .`, no taxonomy). See [`examples/`](examples/) for annotated config and taxonomy files.
+
+## Architecture
+
+Five load-bearing decisions, each documented as an ADR:
+
+| ADR | Decision |
+|-----|----------|
+| [ADR-001](docs/adr/ADR-001-storage-substrate.md) | QMD as the search substrate, not a standalone vector DB |
+| [ADR-002](docs/adr/ADR-002-page-level-granularity.md) | Page-per-file granularity, not paragraph chunks |
+| [ADR-003](docs/adr/ADR-003-explicit-invocation.md) | Explicit CLI invocation, not an ambient hook (yet) |
+| [ADR-004](docs/adr/ADR-004-pdf-canonical-cache.md) | PDFs canonical; markdown is a disposable cache |
+| [ADR-005](docs/adr/ADR-005-no-new-services.md) | A Python package + adapter, not a long-running service |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest          # 36+ cases
+ruff check .    # lint
+```
+
+## Roadmap
+
+- Additional backends beyond QMD (the adapter boundary already exists).
+- Publish to PyPI for a plain `pip install proactive-librarian`.
+- Optional ambient/agent invocation surface (the explicit-CLI decision in ADR-003 is revisitable as adoption grows).
+- Richer query output formats (JSON, BibTeX-style citation export).
+
+## Contributing
+
+Issues and pull requests welcome. The codebase is small and well-tested — run `pytest` and `ruff check .` before opening a PR. If you're adding a backend, start from the QMD adapter and the ADR-001 rationale.
+
+## License
+
+[MIT](LICENSE) © David Orban.
+
+## Status
+
+**v0.1.0** — in single-user production use; the API will stabilise as more backends and surfaces are added. The cache format and CLI are stable. See [CHANGELOG.md](CHANGELOG.md).

proactive_librarian-0.1.0/proactive_librarian/__init__.py

@@ -0,0 +1,7 @@
+"""proactive-librarian — PDF library indexing with page-accurate citations."""
+
+__version__ = "0.1.0"
+
+from proactive_librarian.config import Config, load_config
+
+__all__ = ["Config", "load_config", "__version__"]

proactive_librarian-0.1.0/proactive_librarian/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point so `python -m proactive_librarian` works the same as `librarian`."""
+from proactive_librarian.cli import main
+
+if __name__ == "__main__":
+    main()

proactive_librarian-0.1.0/proactive_librarian/cli.py

@@ -0,0 +1,107 @@
+"""Command-line entry: `librarian ingest` and `librarian query`."""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Optional
+
+from proactive_librarian import __version__
+from proactive_librarian.config import load_config
+
+
+def _add_common_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--config", type=Path, default=None,
+                   help="Path to proactive-librarian.yaml (overrides default discovery)")
+    p.add_argument("--pdf-root", type=str, default=None,
+                   help="Override pdf_root from config")
+    p.add_argument("--collection", type=str, default=None,
+                   help="Override backend collection_name")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="librarian",
+        description="Index a PDF library and answer queries with page-accurate citations.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # --- ingest ---
+    ing = sub.add_parser("ingest", help="Walk pdf_root and refresh the cache")
+    _add_common_args(ing)
+    ing.add_argument("--full", action="store_true",
+                     help="Ignore manifest sha1 cache; re-extract every PDF")
+    ing.add_argument("--incremental", action="store_true", default=True,
+                     help="Default mode: only process new or sha1-changed PDFs")
+    ing.add_argument("--dry-run", action="store_true",
+                     help="Walk + validate + sha1 but write nothing")
+    ing.add_argument("--limit", type=int, default=0,
+                     help="Process at most N PDFs (useful for testing)")
+    ing.add_argument("--category", type=str, default=None,
+                     help="Only process PDFs under this exact top-level subject")
+    ing.add_argument("--clean", action="store_true",
+                     help="Delete the derived cache first (use for format migrations)")
+    ing.add_argument("--verbose", "-v", action="store_true",
+                     help="Print every file decision")
+
+    # --- query ---
+    qry = sub.add_parser("query", help="Search the indexed library")
+    _add_common_args(qry)
+    qry.add_argument("query", type=str, help="Natural language query")
+    qry.add_argument("--limit", "-n", type=int, default=5,
+                     help="Max results (default 5)")
+    qry.add_argument("--json", action="store_true",
+                     help="Raw JSON output instead of formatted citations")
+
+    return parser
+
+
+def _build_overrides(args: argparse.Namespace) -> dict:
+    overrides: dict = {}
+    if getattr(args, "pdf_root", None):
+        overrides["pdf_root"] = args.pdf_root
+    if getattr(args, "collection", None):
+        overrides["collection_name"] = args.collection
+    return overrides
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        config = load_config(
+            explicit_path=args.config,
+            cli_overrides=_build_overrides(args),
+        )
+    except (FileNotFoundError, ValueError) as e:
+        print(f"Config error: {e}", file=sys.stderr)
+        return 2
+
+    if args.command == "ingest":
+        from proactive_librarian.ingest import run_ingest
+        stats = run_ingest(
+            config,
+            full=args.full,
+            dry_run=args.dry_run,
+            limit=args.limit,
+            category=args.category,
+            clean=args.clean,
+            verbose=args.verbose,
+        )
+        return 1 if stats.errors > 0 else 0
+
+    if args.command == "query":
+        from proactive_librarian.query import run_query
+        return run_query(
+            args.query, config, limit=args.limit, as_json=args.json,
+        )
+
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

proactive_librarian-0.1.0/proactive_librarian/config.py

@@ -0,0 +1,143 @@
+"""Configuration loader for proactive-librarian.
+
+Everything that was hardcoded in the original personal-vault implementation
+lives here as overridable settings. The intent is "config file in repo root,
+sensible defaults everywhere else."
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+
+DEFAULT_CONFIG_FILENAMES = ("proactive-librarian.yaml", "proactive-librarian.yml")
+
+
+@dataclass(frozen=True)
+class TaxonomyConfig:
+    """Optional subject-category enforcement."""
+    enabled: bool = False
+    allowed_subjects: tuple[str, ...] = ()
+    guide_reference: Optional[str] = None  # human-readable pointer to a docs file
+
+
+@dataclass(frozen=True)
+class BackendConfig:
+    """Retrieval backend settings. Only QMD is implemented today."""
+    type: str = "qmd"
+    binary: str = "qmd"
+    timeout_seconds: int = 30
+
+
+@dataclass(frozen=True)
+class Config:
+    """All settings for a single proactive-librarian instance.
+
+    Construct via `load_config(...)`. The dataclass is frozen so callers can
+    safely share it across threads / passes.
+    """
+    pdf_root: Path
+    derived_dir: str = ".derived"
+    collection_name: str = "research"
+    page_filename_padding: int = 4
+    taxonomy: TaxonomyConfig = field(default_factory=TaxonomyConfig)
+    backend: BackendConfig = field(default_factory=BackendConfig)
+
+    @property
+    def derived_root(self) -> Path:
+        return self.pdf_root / self.derived_dir
+
+    @property
+    def manifest_path(self) -> Path:
+        return self.derived_root / "_manifest.json"
+
+    @property
+    def failures_path(self) -> Path:
+        return self.derived_root / "_failures.json"
+
+    def page_filename(self, n: int) -> str:
+        return f"p{n:0{self.page_filename_padding}d}.md"
+
+
+def _find_default_config(start: Path) -> Optional[Path]:
+    """Look for a config file in `start` (typically cwd). No upward search —
+    explicit beats implicit."""
+    for name in DEFAULT_CONFIG_FILENAMES:
+        candidate = start / name
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def load_config(
+    explicit_path: Optional[Path] = None,
+    cli_overrides: Optional[dict] = None,
+) -> Config:
+    """Resolve config from (in priority order): CLI overrides > config file > defaults.
+
+    Args:
+        explicit_path: an absolute path passed via `--config`. Required to exist if given.
+        cli_overrides: a dict like `{"pdf_root": "/x/y"}` from argparse. Wins over file values.
+
+    Returns:
+        Frozen `Config`.
+
+    Raises:
+        FileNotFoundError if `explicit_path` was passed but doesn't exist.
+        ValueError if `pdf_root` cannot be resolved from any source.
+    """
+    cli_overrides = cli_overrides or {}
+
+    file_data: dict = {}
+    config_path: Optional[Path] = None
+
+    if explicit_path is not None:
+        if not explicit_path.exists():
+            raise FileNotFoundError(f"Config file not found: {explicit_path}")
+        config_path = explicit_path
+    else:
+        config_path = _find_default_config(Path.cwd())
+
+    if config_path is not None:
+        try:
+            file_data = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+        except yaml.YAMLError as e:
+            raise ValueError(f"Invalid YAML in {config_path}: {e}") from e
+
+    # Layer: defaults < file < CLI
+    merged: dict = {**file_data, **cli_overrides}
+
+    pdf_root_str = merged.get("pdf_root") or os.environ.get("LIBRARIAN_PDF_ROOT")
+    if not pdf_root_str:
+        raise ValueError(
+            "pdf_root is required. Set it in proactive-librarian.yaml, "
+            "via --pdf-root, or via $LIBRARIAN_PDF_ROOT."
+        )
+    pdf_root = Path(pdf_root_str).expanduser().resolve()
+
+    taxonomy_data = merged.get("taxonomy") or {}
+    taxonomy = TaxonomyConfig(
+        enabled=bool(taxonomy_data.get("enabled", False)),
+        allowed_subjects=tuple(taxonomy_data.get("allowed_subjects", []) or []),
+        guide_reference=taxonomy_data.get("guide_reference"),
+    )
+
+    backend_data = merged.get("backend") or {}
+    backend = BackendConfig(
+        type=backend_data.get("type", "qmd"),
+        binary=backend_data.get("binary", "qmd"),
+        timeout_seconds=int(backend_data.get("timeout_seconds", 30)),
+    )
+
+    return Config(
+        pdf_root=pdf_root,
+        derived_dir=merged.get("derived_dir", ".derived"),
+        collection_name=merged.get("collection_name", "research"),
+        page_filename_padding=int(merged.get("page_filename_padding", 4)),
+        taxonomy=taxonomy,
+        backend=backend,
+    )