build.md

# Build and distribution

Python source requires 3.11+. Local tested interpreter: Windows x64 Python 3.13.14 in an isolated `.venv`. Install `.[dev]`, then:

```powershell
python -m pytest -q
python -m build
python -m PyInstaller --noconfirm packaging/book-agent.spec
python packaging/release.py
```

`dist/book-agent/` is a Windows x64 onedir application; keep `_internal` adjacent to EXE. `release/` includes Windows ZIP, generic wheel, source sdist/ZIP, Skill ZIP, hashes and dependency licenses. No sample, `.work`, production data, credentials or model weights enter the lightweight archives. A separate directly loadable `weights/BAAI-bge-m3/` directory supplies optional offline weights. The MCP SDK's optional CLI modules are excluded from collection; Book Agent implements its own CLI. Console executable is suitable for redirected stdio; host launchers control whether a window appears.

The binary supports normal retrieval/PDF/EPUB/ZIP7z/stdIO/HTTP rerank/query adapters. Local PyTorch is deliberately not bundled: use a Python environment with `[local-query]` and the shared weights for offline vector queries, or `[local-rerank]` with existing rerank models. An executable cannot acquire Python extras by pip into a different environment.

## Optional fully offline query runtime

The supplied wheel sets target **Windows x64 CPython 3.13**. Copy the release directory (including wheelhouse, offline-wheelhouse and weights) to the receiving machine. Verify `release-manifest.json` against the independently transferred SHA-256 first. Then, from that release directory:

```powershell
python install-offline.py --release-dir . --venv '.\query-runtime'
$ba = '.\query-runtime\Scripts\book-agent.exe'
& $ba --data-dir '.\runtime-data' init '<your-book-package>' --json
& $ba --data-dir '.\runtime-data' install-query-model BOOK_ID --model-dir '.\weights\BAAI-bge-m3'
& $ba --data-dir '.\runtime-data' configure BOOK_ID --vector-search offline --query-model-path '.\weights\BAAI-bge-m3'
& $ba --data-dir '.\runtime-data' search BOOK_ID '<question>' --strict --json
& $ba --data-dir '.\runtime-data' install-host BOOK_ID --host codex --dry-run
```

The helper verifies local wheel hashes and interpreter identity, passes only explicit hashed wheel URLs to isolated pip, disables pip configuration/update checks, rejects URL dependencies, and runs `pip check`. It installs no models. Weight adoption verifies pinned artifacts and writes a portable receipt. All books share one weight directory; do not copy it into each book. Source installation on other OS/Python versions uses `pip install '.[local-query]'` and the same portable weights; those native environments remain untested here. The default `none` and optional `online` modes use only the lightweight program.

For source installation on another platform, install that platform's CPU-only PyTorch wheel from the [official PyTorch CPU index](https://download.pytorch.org/whl/cpu) before installing `.[local-query]`; follow the upstream platform instructions. This avoids unnecessary CUDA libraries for this CPU-only recipe. The supplied Windows offline wheels already use a CPU build.

Offline queries retain one float32 encoder layer at a time and read only the current query's embedding rows. The 2.29 GB weight directory remains necessary on disk; model loading does not require keeping the full checkpoint resident. Each query reads the encoder layers again, so a slow disk still affects latency. The CPU recipe defaults to two threads and a 512-token question budget; it never truncates a question silently. Prefer one `book-agent --data-dir <shared-data> mcp` server exposing registered books to share dependencies and query serialization. Measure one strict CLI query before selecting the offline route; that process does not warm the MCP process cache. MCP tool deadlines accept 1–900 seconds (`mcp BOOK_ID --timeout 600` for a slow offline cold query). The host startup/tool deadlines are separate and may also need adjustment. Remote adapters retain their own 120-second maximum.

`packaging/smoke_binary.py` checks the built binary independently from editable source. It covers Unicode/spaces, import, SQLite, source rendering, EPUB and MCP. Actual results are in `docs/windows-binary-validation.md`. SHA manifest is reproducible metadata for the generated artifacts, not a reproducible-bit-build claim.

Source installation can use package indexes; the Skill bootstrap is specifically offline. Its manifest must include **all required dependency wheels matching the target OS/Python**. A release without wheelhouse can still use its tested Windows onedir or an existing compatible Python environment; bootstrap refuses missing dependencies rather than reaching an online index. For a matching Windows CPython3.13 wheelhouse, `release/wheelhouse/` is prepared locally and hashed in the manifest.

Linux and macOS have source/CI definitions only in this workspace. The workflow declares Windows/Linux/macOS tests plus a Windows binary job, but it has not run on a CI service here. Each native OS needs its own build/test; never reuse the Windows EXE as a cross-platform binary. Optional real-example tests skip when private `.work` fixture is unavailable in a distributed checkout.