nanomind-analyst 0.1.0__tar.gz

nanomind_analyst-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.venv/
+.venv-gate/
+build/
+dist/
+*.whl
+.coverage
+.tox/
+
+# Sensitive files — never commit
+.env
+.env.*
+secrets.json
+*.pem
+*.key
+*.p12
+*.pfx
+credentials/
+secrets/

nanomind_analyst-0.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+- CLI: `install`, `uninstall`, `start`, `stop`, `restart`, `status`, `logs`.
+- Vendors the NanoMind-Guard daemon serving the v3.0.0 Qwen3-1.7B Analyst NLM behind the v1 input-classifier gate.
+- Fetches NLM weights from `opena2a/nanomind-security-analyst` at the pinned v3.0.0 commit and verifies SHA256 against wheel-baked constants. Uses `local_dir_use_symlinks=False` so the verify reads bytes at the install location, not a swappable cache symlink.
+- Bundles the input-classifier-v1 artifacts (~5 KB) inside the wheel; daemon re-verifies SHA256 at every boot before `joblib.load()` runs.
+- Per-user launchd LaunchAgent at `~/Library/LaunchAgents/org.opena2a.nanomind-analyst.plist`. No root, no `sudo`. `install` calls `bootout` then `bootstrap` so upgrades reload the new plist rather than silently keeping the old in-memory definition.
+- Installer's healthz probe refuses to connect to `/tmp/nanomind-guard.sock` when the path is a symlink or owned by a different uid (defense against same-host socket squatting).
+- `nanomind-analyst-daemon` entrypoint is wrapped with a Darwin-arm64 platform check so a direct invocation on Linux/Intel fails with a clear message instead of a torch/MPS stacktrace.
+- Release workflow refuses to publish if the tag's commit is not an ancestor of `origin/main`, and if `pyproject.toml` version does not match the tag suffix.
+- Apple Silicon (Darwin arm64) only. Linux/cloud daemon support is tracked separately; the NLM is bf16-MPS and fp16 yields 0% accuracy on Qwen3-1.7B.
+
+### Known limitations
+
+- The daemon's default socket lives at `/tmp/nanomind-guard.sock`. On a multi-user macOS host, a different local user can prevent the daemon from binding by pre-creating the path (sticky-bit `/tmp` blocks the daemon's `unlink`). Migrating the default to a per-user path requires coordinated changes in `hackmyagent`'s IPC client; tracked separately.
+- `uninstall --remove-artifacts` clears the user's Application Support dir but does not clear the Hugging Face cache at `~/.cache/huggingface/`. Symlinks are off (the install copies real files), so disk-space recovery requires both removals.
+- GHA workflow steps reference upstream actions by tag (`actions/checkout@v4`, `pypa/gh-action-pypi-publish@release/v1`). Pinning to commit SHAs is a follow-up.

nanomind_analyst-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenA2A
+
+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.

nanomind_analyst-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: nanomind-analyst
+Version: 0.1.0
+Summary: Installer for the NanoMind Analyst daemon: serves the Qwen3-1.7B security analyst NLM behind an input-classifier gate over a Unix socket.
+Project-URL: Homepage, https://github.com/opena2a-org/nanomind/tree/main/packages/nanomind-analyst
+Project-URL: Repository, https://github.com/opena2a-org/nanomind
+Project-URL: Documentation, https://github.com/opena2a-org/nanomind/tree/main/packages/nanomind-analyst#readme
+Project-URL: Model Card, https://huggingface.co/opena2a/nanomind-security-analyst
+Project-URL: Bug Tracker, https://github.com/opena2a-org/nanomind/issues
+Author-email: OpenA2A <hello@opena2a.org>
+License: MIT
+License-File: LICENSE
+Keywords: agent-trust,ai-security,daemon,nanomind,opena2a
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: MacOS X
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: huggingface-hub<2.0,>=0.24
+Requires-Dist: joblib>=1.3
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: sentence-transformers>=2.7
+Requires-Dist: torch>=2.2
+Requires-Dist: transformers>=4.43
+Provides-Extra: test
+Requires-Dist: pytest-mock>=3.12; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# nanomind-analyst
+
+Installer for the NanoMind Analyst daemon. The daemon serves the Qwen3-1.7B security analyst NLM behind an input-classifier gate over a Unix socket at `/tmp/nanomind-guard.sock`. Consumers (hackmyagent, opena2a-cli, ai-trust) connect to that socket for generative threat analysis on individual findings.
+
+This package writes a per-user launchd LaunchAgent, fetches and verifies the model artifacts from Hugging Face, and manages the daemon lifecycle. Apple Silicon (Darwin arm64) only in v0.1.
+
+## Install
+
+```bash
+pip install nanomind-analyst
+nanomind-analyst install
+```
+
+The install step:
+
+1. Verifies platform (Apple Silicon required).
+2. Copies the input-classifier-v1 artifacts (bundled in the wheel) into `~/Library/Application Support/nanomind-analyst/artifacts/input-classifier-v1/`. SHA256 verified before copy.
+3. Fetches the Analyst NLM (~3.4 GB) from `opena2a/nanomind-security-analyst` at the pinned v3.0.0 commit. SHA256 verified after fetch.
+4. Writes a launchd plist to `~/Library/LaunchAgents/org.opena2a.nanomind-analyst.plist`.
+5. Bootstraps the LaunchAgent into the user's gui session.
+6. Waits up to 60 seconds for the daemon to bind the socket and pass its healthz probe.
+
+The fetch step is the long one (several minutes on first run; cached on subsequent runs).
+
+## Commands
+
+| Command | What |
+|---------|------|
+| `nanomind-analyst install` | Full install flow. Idempotent. |
+| `nanomind-analyst uninstall` | Stop, unload, remove plist. `--remove-artifacts` also deletes the 3.4 GB NLM. |
+| `nanomind-analyst start` | Kickstart the loaded LaunchAgent. |
+| `nanomind-analyst stop` | SIGTERM the daemon. Agent stays loaded; no auto-restart on clean exit. |
+| `nanomind-analyst restart` | Stop then start. |
+| `nanomind-analyst status` | Report whether the agent is loaded and healthz returns ready. |
+| `nanomind-analyst logs` | Tail `~/Library/Logs/nanomind-analyst.log`. `--no-follow` for one-shot. |
+| `nanomind-analyst --version` | Print the package version. |
+
+## What gets written where
+
+| Path | Purpose |
+|------|---------|
+| `~/Library/LaunchAgents/org.opena2a.nanomind-analyst.plist` | LaunchAgent plist. |
+| `~/Library/Application Support/nanomind-analyst/artifacts/input-classifier-v1/` | Classifier joblib + meta.json (~5 KB). |
+| `~/Library/Application Support/nanomind-analyst/artifacts/nanomind-security-analyst/` | NLM weights, tokenizer, configs (~3.4 GB). |
+| `~/Library/Logs/nanomind-analyst.log` | Daemon stdout + stderr. |
+| `/tmp/nanomind-guard.sock` | Unix socket the daemon binds (0600, owner-only). |
+
+No root, no `/opt`, no `sudo`.
+
+## Trust chain
+
+The install does not depend on Hugging Face being trustworthy. The wheel manifest is the authoritative source of artifact identity:
+
+1. PyPI Trusted Publishing (OIDC) attests the wheel was built by the workflow at `.github/workflows/release-nanomind-analyst.yml` from a commit in `opena2a-org/nanomind` (SLSA v1 provenance).
+2. The wheel bakes `EXPECTED_NLM_SAFETENSORS_SHA256` and `EXPECTED_NLM_TOKENIZER_SHA256` constants in `artifacts.py`.
+3. At `install`, the fetched NLM files are SHA256-verified against those constants. A tampered Hugging Face artifact causes install to refuse.
+4. At daemon boot, `INPUT_CLASSIFIER_JOBLIB_SHA256` is re-verified before `joblib.load()` runs (joblib uses pickle = arbitrary code execution at deserialization).
+
+Verify wheel provenance after publish:
+
+```bash
+npm  # no equivalent; use:
+python -m pip download nanomind-analyst --no-deps --dest /tmp/verify
+# Then inspect the wheel's METADATA + RECORD; PyPI surfaces attestations
+# at https://pypi.org/project/nanomind-analyst/#files
+```
+
+## Linux / cloud daemon
+
+Not supported in v0.1. The daemon is bf16 on Apple MPS; fp16 yields 0% accuracy on Qwen3-1.7B. Cross-platform inference is tracked in `opena2a-org/nanomind` issues with the labels `nanomind-analyst` + `platform-linux`.
+
+## Known limitations
+
+- **Cold-boot latency.** Daemon takes ~30 seconds to load the NLM on first request after a system reboot. The install flow waits up to 60 seconds for this; subsequent restarts are faster (the launchd-managed process stays warm).
+- **NLM latency floor.** The Analyst NLM emits ~400 tokens of structured output per request at ~15 ms/token on bf16 MPS. Floor is ~6 seconds per finding. Consumers (HMA, opena2a-cli) should batch or filter before invoking. The input-classifier gate bypasses the NLM on off-topic inputs (~92% bypass rate on benign user input).
+- **Single-instance.** The daemon binds a single Unix socket. Multiple `nanomind-analyst install` runs on the same machine share the same socket; the LaunchAgent label is unique to the user.
+
+## Companion package
+
+`hackmyagent` (npm) `--nanomind` flag uses this daemon. After installing this package, `hackmyagent nanomind setup` detects the `nanomind-analyst` CLI on PATH and shells out to `nanomind-analyst install`. If the CLI is missing, it prints the `pip install` instructions.
+
+## Model card
+
+[opena2a/nanomind-security-analyst](https://huggingface.co/opena2a/nanomind-security-analyst). v3.0.0 (Qwen3-1.7B SFT LoRA r=64), Apache-2.0.
+
+## License
+
+MIT.

nanomind_analyst-0.1.0/README.md

@@ -0,0 +1,88 @@
+# nanomind-analyst
+
+Installer for the NanoMind Analyst daemon. The daemon serves the Qwen3-1.7B security analyst NLM behind an input-classifier gate over a Unix socket at `/tmp/nanomind-guard.sock`. Consumers (hackmyagent, opena2a-cli, ai-trust) connect to that socket for generative threat analysis on individual findings.
+
+This package writes a per-user launchd LaunchAgent, fetches and verifies the model artifacts from Hugging Face, and manages the daemon lifecycle. Apple Silicon (Darwin arm64) only in v0.1.
+
+## Install
+
+```bash
+pip install nanomind-analyst
+nanomind-analyst install
+```
+
+The install step:
+
+1. Verifies platform (Apple Silicon required).
+2. Copies the input-classifier-v1 artifacts (bundled in the wheel) into `~/Library/Application Support/nanomind-analyst/artifacts/input-classifier-v1/`. SHA256 verified before copy.
+3. Fetches the Analyst NLM (~3.4 GB) from `opena2a/nanomind-security-analyst` at the pinned v3.0.0 commit. SHA256 verified after fetch.
+4. Writes a launchd plist to `~/Library/LaunchAgents/org.opena2a.nanomind-analyst.plist`.
+5. Bootstraps the LaunchAgent into the user's gui session.
+6. Waits up to 60 seconds for the daemon to bind the socket and pass its healthz probe.
+
+The fetch step is the long one (several minutes on first run; cached on subsequent runs).
+
+## Commands
+
+| Command | What |
+|---------|------|
+| `nanomind-analyst install` | Full install flow. Idempotent. |
+| `nanomind-analyst uninstall` | Stop, unload, remove plist. `--remove-artifacts` also deletes the 3.4 GB NLM. |
+| `nanomind-analyst start` | Kickstart the loaded LaunchAgent. |
+| `nanomind-analyst stop` | SIGTERM the daemon. Agent stays loaded; no auto-restart on clean exit. |
+| `nanomind-analyst restart` | Stop then start. |
+| `nanomind-analyst status` | Report whether the agent is loaded and healthz returns ready. |
+| `nanomind-analyst logs` | Tail `~/Library/Logs/nanomind-analyst.log`. `--no-follow` for one-shot. |
+| `nanomind-analyst --version` | Print the package version. |
+
+## What gets written where
+
+| Path | Purpose |
+|------|---------|
+| `~/Library/LaunchAgents/org.opena2a.nanomind-analyst.plist` | LaunchAgent plist. |
+| `~/Library/Application Support/nanomind-analyst/artifacts/input-classifier-v1/` | Classifier joblib + meta.json (~5 KB). |
+| `~/Library/Application Support/nanomind-analyst/artifacts/nanomind-security-analyst/` | NLM weights, tokenizer, configs (~3.4 GB). |
+| `~/Library/Logs/nanomind-analyst.log` | Daemon stdout + stderr. |
+| `/tmp/nanomind-guard.sock` | Unix socket the daemon binds (0600, owner-only). |
+
+No root, no `/opt`, no `sudo`.
+
+## Trust chain
+
+The install does not depend on Hugging Face being trustworthy. The wheel manifest is the authoritative source of artifact identity:
+
+1. PyPI Trusted Publishing (OIDC) attests the wheel was built by the workflow at `.github/workflows/release-nanomind-analyst.yml` from a commit in `opena2a-org/nanomind` (SLSA v1 provenance).
+2. The wheel bakes `EXPECTED_NLM_SAFETENSORS_SHA256` and `EXPECTED_NLM_TOKENIZER_SHA256` constants in `artifacts.py`.
+3. At `install`, the fetched NLM files are SHA256-verified against those constants. A tampered Hugging Face artifact causes install to refuse.
+4. At daemon boot, `INPUT_CLASSIFIER_JOBLIB_SHA256` is re-verified before `joblib.load()` runs (joblib uses pickle = arbitrary code execution at deserialization).
+
+Verify wheel provenance after publish:
+
+```bash
+npm  # no equivalent; use:
+python -m pip download nanomind-analyst --no-deps --dest /tmp/verify
+# Then inspect the wheel's METADATA + RECORD; PyPI surfaces attestations
+# at https://pypi.org/project/nanomind-analyst/#files
+```
+
+## Linux / cloud daemon
+
+Not supported in v0.1. The daemon is bf16 on Apple MPS; fp16 yields 0% accuracy on Qwen3-1.7B. Cross-platform inference is tracked in `opena2a-org/nanomind` issues with the labels `nanomind-analyst` + `platform-linux`.
+
+## Known limitations
+
+- **Cold-boot latency.** Daemon takes ~30 seconds to load the NLM on first request after a system reboot. The install flow waits up to 60 seconds for this; subsequent restarts are faster (the launchd-managed process stays warm).
+- **NLM latency floor.** The Analyst NLM emits ~400 tokens of structured output per request at ~15 ms/token on bf16 MPS. Floor is ~6 seconds per finding. Consumers (HMA, opena2a-cli) should batch or filter before invoking. The input-classifier gate bypasses the NLM on off-topic inputs (~92% bypass rate on benign user input).
+- **Single-instance.** The daemon binds a single Unix socket. Multiple `nanomind-analyst install` runs on the same machine share the same socket; the LaunchAgent label is unique to the user.
+
+## Companion package
+
+`hackmyagent` (npm) `--nanomind` flag uses this daemon. After installing this package, `hackmyagent nanomind setup` detects the `nanomind-analyst` CLI on PATH and shells out to `nanomind-analyst install`. If the CLI is missing, it prints the `pip install` instructions.
+
+## Model card
+
+[opena2a/nanomind-security-analyst](https://huggingface.co/opena2a/nanomind-security-analyst). v3.0.0 (Qwen3-1.7B SFT LoRA r=64), Apache-2.0.
+
+## License
+
+MIT.

nanomind_analyst-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nanomind-analyst"
+version = "0.1.0"
+description = "Installer for the NanoMind Analyst daemon: serves the Qwen3-1.7B security analyst NLM behind an input-classifier gate over a Unix socket."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "OpenA2A", email = "hello@opena2a.org" }]
+keywords = ["nanomind", "ai-security", "agent-trust", "opena2a", "daemon"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: MacOS X",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS :: MacOS X",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security",
+]
+dependencies = [
+    "huggingface_hub>=0.24,<2.0",
+    "joblib>=1.3",
+    "scikit-learn>=1.3",
+    "sentence-transformers>=2.7",
+    "torch>=2.2",
+    "transformers>=4.43",
+]
+
+[project.urls]
+Homepage = "https://github.com/opena2a-org/nanomind/tree/main/packages/nanomind-analyst"
+Repository = "https://github.com/opena2a-org/nanomind"
+Documentation = "https://github.com/opena2a-org/nanomind/tree/main/packages/nanomind-analyst#readme"
+"Model Card" = "https://huggingface.co/opena2a/nanomind-security-analyst"
+"Bug Tracker" = "https://github.com/opena2a-org/nanomind/issues"
+
+[project.scripts]
+nanomind-analyst = "nanomind_analyst.cli:main"
+# Wrapped entrypoint so a `nanomind-analyst-daemon` invocation on Linux/Intel
+# fails fast with a clear platform message instead of crashing inside torch.
+nanomind-analyst-daemon = "nanomind_analyst.daemon:guarded_daemon_main"
+
+[project.optional-dependencies]
+test = ["pytest>=8.0", "pytest-mock>=3.12"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nanomind_analyst"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/nanomind_analyst/data/input-classifier-v1/classifier.joblib" = "nanomind_analyst/data/input-classifier-v1/classifier.joblib"
+"src/nanomind_analyst/data/input-classifier-v1/meta.json" = "nanomind_analyst/data/input-classifier-v1/meta.json"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/tests",
+    "/README.md",
+    "/CHANGELOG.md",
+    "/LICENSE",
+    "/pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"

nanomind_analyst-0.1.0/src/nanomind_analyst/__init__.py

@@ -0,0 +1,12 @@
+"""Installer for the NanoMind Analyst daemon.
+
+The daemon serves the v3.0.0 Qwen3-1.7B Analyst NLM behind an input-classifier
+gate over a Unix socket. This package writes the launchd plist, fetches and
+verifies the model artifacts, and manages the daemon lifecycle.
+
+Apple Silicon (Darwin arm64) only in v0.1. The daemon is bf16 on MPS; fp16
+yields 0% accuracy on Qwen3-1.7B.
+"""
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

nanomind_analyst-0.1.0/src/nanomind_analyst/artifacts.py

@@ -0,0 +1,232 @@
+"""Fetch and verify the Analyst NLM artifacts from Hugging Face.
+
+The trust chain for v0.1:
+
+  PyPI Trusted Publishing -> GHA OIDC -> wheel build
+    -> bakes EXPECTED_*_SHA256 constants below at build time
+    -> wheel ships with classifier.joblib + meta.json embedded as package data
+    -> daemon at runtime verifies fetched NLM weights against EXPECTED_*_SHA256
+
+The wheel manifest is authoritative. Hugging Face is reduced to a CDN; if HF
+serves tampered bytes, the SHA check refuses to install. The daemon then does
+a second verify before joblib.load() runs (joblib uses pickle = ACE at
+deserialization).
+
+The pinned revision is the v3.0.0 release of opena2a/nanomind-security-analyst.
+Bumping it requires recomputing EXPECTED_NLM_*_SHA256 from the live HF tree.
+"""
+from __future__ import annotations
+
+import hashlib
+import os
+import shutil
+import stat
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+
+HF_REPO_ID = "opena2a/nanomind-security-analyst"
+
+# Pinned to the v3.0.0 release commit (model card: nanomind/MODEL_CARD links
+# this exact commit). Bumping it requires recomputing the SHA constants below.
+HF_REVISION = "13bc3112ec9666a37f301b83d3e8bce53da4e3c5"
+
+# SHA256 of model.safetensors as published on Hugging Face at HF_REVISION.
+# Source: https://huggingface.co/api/models/opena2a/nanomind-security-analyst
+#         /tree/main -> file=model.safetensors -> lfs.oid
+EXPECTED_NLM_SAFETENSORS_SHA256 = (
+    "53cb9441e370b097f556a200efb483dc8fb977a4a57ed79aaae1b99c71426da0"
+)
+
+# SHA256 of tokenizer.json (also LFS at HF_REVISION).
+EXPECTED_NLM_TOKENIZER_SHA256 = (
+    "be75606093db2094d7cd20f3c2f385c212750648bd6ea4fb2bf507a6a4c55506"
+)
+
+# SHA256 of the input-classifier-v1 artifacts. These files are shipped INSIDE
+# the wheel (under nanomind_analyst/data/input-classifier-v1/) and copied into
+# the user's Application Support dir during install. The daemon verifies them
+# at boot before joblib.load() runs.
+EXPECTED_CLASSIFIER_JOBLIB_SHA256 = (
+    "a9a699cf2adc1768d2d8777fdb2f9c5ce16fd087ead060ba9e2944a5bd5f9db6"
+)
+EXPECTED_CLASSIFIER_META_SHA256 = (
+    "79ac141c5b039e62ca7c7b111ba065545c2528b8c06524c9432410d8f11212b2"
+)
+
+# These are the NLM files the daemon actually needs. Anything else fetched by
+# snapshot_download is fine but not required.
+NLM_REQUIRED_FILES = (
+    "config.json",
+    "generation_config.json",
+    "model.safetensors",
+    "model.safetensors.index.json",
+    "tokenizer.json",
+    "tokenizer_config.json",
+    "chat_template.jinja",
+)
+
+
+class ArtifactError(Exception):
+    """Raised when artifact fetch or verification fails."""
+
+
+@dataclass
+class FetchProgress:
+    """Reports progress during fetch. The CLI prints these; tests assert on them."""
+
+    stage: str  # "fetching" | "verifying" | "installing-classifier" | "done"
+    detail: str = ""
+
+
+ProgressCallback = Callable[[FetchProgress], None]
+
+
+def _sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as fh:
+        for chunk in iter(lambda: fh.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _verify(path: Path, expected: str, *, name: str) -> None:
+    if not path.exists():
+        raise ArtifactError(f"{name} missing after fetch: {path}")
+    # Defense in depth: reject symlinks at the artifact path. snapshot_download
+    # with local_dir_use_symlinks=False should never produce one, but if some
+    # future HF library version regresses, or if a hostile process slipped a
+    # symlink under target_dir between fetch and verify, we want SHA verify to
+    # read the file at this path, not whatever the symlink resolves to.
+    st = os.lstat(path)
+    if stat.S_ISLNK(st.st_mode):
+        raise ArtifactError(
+            f"{name} is a symlink ({path}); refusing to verify or load. The "
+            f"snapshot_download call requested local_dir_use_symlinks=False; "
+            f"the presence of a symlink here may indicate a tampered fetch."
+        )
+    actual = _sha256_file(path)
+    if actual != expected:
+        raise ArtifactError(
+            f"SHA256 mismatch on {name}: expected {expected}, got {actual}. "
+            f"Refusing to install. The Hugging Face artifact at {HF_REPO_ID}"
+            f"@{HF_REVISION[:7]} may have been retagged, or the wheel was "
+            f"built against a different revision. File: {path}"
+        )
+
+
+def fetch_nlm(
+    *,
+    target_dir: Path,
+    progress: ProgressCallback | None = None,
+    hf_downloader: Callable[..., str] | None = None,
+) -> None:
+    """Download NLM artifacts from Hugging Face into target_dir.
+
+    `hf_downloader` is injected for tests; default is
+    huggingface_hub.snapshot_download.
+    """
+    if progress is not None:
+        progress(
+            FetchProgress(
+                stage="fetching",
+                detail=f"{HF_REPO_ID}@{HF_REVISION[:7]} -> {target_dir}",
+            )
+        )
+
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    downloader = hf_downloader
+    if downloader is None:
+        # Imported lazily so tests that inject a fake downloader don't pay the
+        # huggingface_hub import cost.
+        from huggingface_hub import snapshot_download as downloader  # type: ignore[no-redef]
+
+    # local_dir_use_symlinks=False makes snapshot_download write real files
+    # into target_dir, not symlinks into ~/.cache/huggingface. We want SHA
+    # verify to read the bytes actually present at the install location, not
+    # follow a symlink the user (or an attacker on the cache dir) could swap
+    # under our feet between verify and the daemon's joblib.load.
+    downloader(
+        repo_id=HF_REPO_ID,
+        revision=HF_REVISION,
+        local_dir=str(target_dir),
+        allow_patterns=list(NLM_REQUIRED_FILES),
+        local_dir_use_symlinks=False,
+    )
+
+    if progress is not None:
+        progress(FetchProgress(stage="verifying", detail="model.safetensors"))
+    _verify(
+        target_dir / "model.safetensors",
+        EXPECTED_NLM_SAFETENSORS_SHA256,
+        name="NLM model.safetensors",
+    )
+
+    if progress is not None:
+        progress(FetchProgress(stage="verifying", detail="tokenizer.json"))
+    _verify(
+        target_dir / "tokenizer.json",
+        EXPECTED_NLM_TOKENIZER_SHA256,
+        name="NLM tokenizer.json",
+    )
+
+    for fname in NLM_REQUIRED_FILES:
+        if not (target_dir / fname).exists():
+            raise ArtifactError(
+                f"required NLM file missing after fetch: {fname}. Check the "
+                f"Hugging Face revision {HF_REVISION[:7]} or your network."
+            )
+
+
+def install_classifier(
+    *,
+    source_dir: Path,
+    target_dir: Path,
+    progress: ProgressCallback | None = None,
+) -> None:
+    """Copy the wheel-embedded input-classifier-v1 files into target_dir.
+
+    Verifies SHA against EXPECTED_CLASSIFIER_*_SHA256 BEFORE copying, so a
+    tampered wheel cannot ship a poisoned pickle through this path. The
+    daemon will re-verify at boot before joblib.load() runs.
+    """
+    if progress is not None:
+        progress(
+            FetchProgress(
+                stage="installing-classifier",
+                detail=f"{source_dir} -> {target_dir}",
+            )
+        )
+
+    _verify(
+        source_dir / "classifier.joblib",
+        EXPECTED_CLASSIFIER_JOBLIB_SHA256,
+        name="input-classifier-v1 classifier.joblib (in wheel)",
+    )
+    _verify(
+        source_dir / "meta.json",
+        EXPECTED_CLASSIFIER_META_SHA256,
+        name="input-classifier-v1 meta.json (in wheel)",
+    )
+
+    target_dir.mkdir(parents=True, exist_ok=True)
+    for fname in ("classifier.joblib", "meta.json"):
+        shutil.copy2(source_dir / fname, target_dir / fname)
+
+
+def wheel_classifier_source_dir() -> Path:
+    """Locate the input-classifier-v1 directory shipped inside the wheel."""
+    # Resolves to <site-packages>/nanomind_analyst/data/input-classifier-v1/
+    here = Path(__file__).resolve().parent
+    return here / "data" / "input-classifier-v1"
+
+
+def python_executable() -> str:
+    """The interpreter that launched the installer.
+
+    Baked into the launchd plist so the daemon runs under the same Python the
+    user installed `nanomind-analyst` into (no `/usr/bin/env python3` ambiguity).
+    """
+    return sys.executable