Add portable prototype explorer with browser inference and GBIF integration

.agents/notes/2026-09-10-prototype-explorer.md

@@ -0,0 +1,63 @@
+# Prototype explorer handoff
+
+Status: completed
+Updated: 2026-09-10
+Scope: initial prototype-space exploration, log-domain diagnostics, GBIF image labels
+Related: `42cef5c`, `d4663e7`; [reproduction guide](../../dev/prototype_space/README.md)
+
+## Context and decision
+
+The feature is isolated on `feature/prototype-space` in
+`/home/asger/mini_trainer/.worktrees/prototype-space`. The main `quant` checkout
+received only the worktree workflow/rules; its pre-existing roadmap edits were
+verified unchanged. No subagents were started. Shared `.venv` was used read-only.
+
+The real epoch-4 checkpoint supplies the baseline geometry. Existing effective
+weight handling, cosine-to-z transform and Ward distances are retained. Added
+float32 log-tail computation and adjustable colour clipping distinguish numerical
+saturation from actual prototype identity. Public GBIF examples visually label
+classes at their learned target directions; measured image embedding proximity
+would be a separate selection criterion. Taxon names never replace checkpoint IDs.
+
+## Evidence and limits
+
+- Final source revision: `d4663e7` (includes numerical commit `42cef5c`).
+- Full `bash dev/check.sh all`: 655 passed, 162 skipped, 1 expected failure;
+  exit 0 in 598.56 seconds. Ruff, formatting and both import contracts passed.
+  Used absolute worktree `PYTHONPATH`, `MPLCONFIGDIR=/tmp/mini-trainer-prototype-mpl`,
+  `OMP_NUM_THREADS=4 MKL_NUM_THREADS=4 OPENBLAS_NUM_THREADS=4`, and
+  `PYTEST_ADDOPTS='-o faulthandler_timeout=120'`. CUDA was hidden. This does not
+  establish GPU execution or performance. No package installation was performed.
+- A preceding sandboxed full run was interrupted after waiting on loader workers:
+  340 passed, 13 skipped. The successful rerun allowed local multiprocessing
+  sockets. Do not confuse that interrupted result with full-suite success.
+- Browser helper: 25 interaction checks, zero JavaScript errors, including
+  colour controls, baseline comparisons, tree/search/neighbour navigation,
+  synthetic cases, photo cycling and photo navigation. Photo controls used
+  deterministic fixtures; a separate live check rendered actual GBIF images for
+  class 1837646 and its neighbours with credits.
+- Real payload: 12,632 x 1,280 prototypes; 249,324 unordered baseline zero-distance
+  pairs, all positive under the independent float64 log-CDF reference; all
+  79,777,396 off-diagonal float32 log-tail pairs finite. Three labelled synthetic
+  probes accompany the checkpoint; their smaller class counts are not matched
+  packing controls.
+- Checkpoint SHA256:
+  `42d50f56cb0c6e3ee17ae64fbbcc4eb2ae24335ffe7080197c479c130fff5a81`.
+- Ignored, machine-local artifacts: `tmp/prototype-report/`,
+  `tmp/prototype-browser-check/`, `tmp/prototype-live-browser-check/`.
+  The generated HTML was checked against current templates and stored numerical
+  JSON. The JSON records the numerical-generation script hash; later UI-only
+  refreshes did not recompute or relabel numerical provenance.
+- Preview was healthy at `http://localhost:8765/explorer.html` on completion,
+  served with `python -m dev.prototype_space.serve`; it is not a persistent service.
+  GBIF metadata/thumbnails are cached outside the served directory. Images require
+  optional network access; the numerical report is self-contained.
+- Evaluation logging changes apply to this feature branch, not to an already
+  running training process. Existing Ward clustering remains the baseline;
+  alternate stable clustering and measured sample occupancy are future work.
+
+## Next actions
+
+None required for this initial exploration. Gather feedback on the runnable views
+before choosing further directions listed in the reproduction guide. Keep source
+integration into `quant` separate from this completed feature-branch handoff.

AGENTS.md

@@ -52,6 +52,18 @@ Complete a bounded, validated increment before moving to the next priority.
 - Slow backbone tests require `RUN_SLOW_TESTS=1` and may need model downloads.
   The compatibility runner can update the backbone blacklist; use it only when
   that mutation is part of the task.
+- Be economical with validation: choose the smallest set of checks that covers the
+  changed behavior and credible regressions, while satisfying the requirements above.
+  Before an expensive suite or benchmark, identify the unresolved question it answers.
+- Reuse passing evidence for unchanged code and environments. Batch related edits
+  before expensive checks; do not rerun the same suite for documentation changes or
+  automatically repeat focused checks already covered by a passing broader run.
+  Repeat or broaden checks when new changes, failures, integration conflicts or a
+  concrete unresolved risk justify it, not merely for additional reassurance.
+- Add tests for meaningful behavior and failure modes, not assertions that mirror
+  implementation details or low-impact presentation changes. Prefer existing
+  coverage and a focused browser/manual check where appropriate. Keep required CI
+  gates intact; report the limits of focused validation rather than implying full coverage.
 - Report checks run, failures, skips, and limits honestly. Do not weaken checks or
   alter expected results merely to make a refactor pass.
 

README.md

@@ -16,6 +16,13 @@ All code in `mini_trainer` should follow the following core principles:
 * All hyperparameters and system configuration should have smart defaults that are as general as possible
 * All functionality should be extendable to custom model architectures, loss functions, training regimes, data formats etc.
 
+## Explore model prototypes
+
+With the optional `explorer` dependencies installed, run `mt_explore weights.pt`
+to open the interactive prototype explorer, or `mt_explore` to choose weights in
+the browser. See the [prototype explorer guide](docs/prototype-explorer.md) for
+installation, portable exports, supported checkpoints, and interpretation.
+
 # Installation
 
 We recommend using `uv` for package and environment management.
@@ -86,6 +93,9 @@ preloading; use uncached loading when you need that explicit bound.
 
 `mini_trainer` supports logging your training runs, including metrics, confusion matrices, and the probabilistic dendrogram, directly to [Weights & Biases](https://wandb.ai). 
 
+Class-matrix diagnostics use [log-domain probabilities](docs/prototype-diagnostics.md)
+to retain small tails during evaluation logging.
+
 To use this feature you must install `mini_trainer` with the `recommended` extras. See [Installation](#installation) for more information.
 
 1. **Login to your wandb account**: