precisionai-agritune 1.0.0__tar.gz

precisionai_agritune-1.0.0/.env.example

@@ -0,0 +1,10 @@
+# Copy to .env and fill in — .env is gitignored and never committed.
+#
+# Loaded into the environment before Hydra/OmegaConf composes the config, so
+# `${oc.env:AGRITUNE_ENCODER_API_KEY,null}` in configs/encoder/remote.yaml resolves from here.
+# Requires python-dotenv: pip install -e ".[dotenv]"
+#
+# Anything already exported in your shell wins over the values below.
+
+# API key for the hosted encoder embeddings API (encoder=remote).
+AGRITUNE_ENCODER_API_KEY=

precisionai_agritune-1.0.0/.gitattributes

@@ -0,0 +1,13 @@
+# Normalize line endings to LF on commit, regardless of editor/OS settings.
+* text=auto eol=lf
+
+# Treat binary files as binary (no line-ending conversion).
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.JPG binary
+*.JPEG binary
+*.svg binary
+*.pdf binary
+*.safetensors binary
+*.ipynb text eol=lf

precisionai_agritune-1.0.0/.gitignore

@@ -0,0 +1,152 @@
+# Local environment / secrets — .env holds the encoder API key, .env.example is committed
+.env
+.env.local
+
+# Virtual environments
+.venv/
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Sphinx documentation
+docs/_build/
+docs/readme.md
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# pdm
+.pdm.toml
+
+# PEP 582
+__pypackages__/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+.idea/
+
+# VS Code
+.vscode/
+
+# PyTorch / Machine Learning artefacts
+*.pth
+*.pt
+*.ckpt
+*.pkl
+*.h5
+*.hdf5
+*.onnx
+*.pb
+*.tflite
+*.tfl
+checkpoints/
+models/
+weights/
+wandb/
+mlruns/
+.neptune/
+
+# AgriTune run artefacts
+runs/
+feature_store/
+*.safetensors
+
+# Downloaded / prepared example datasets (see examples/datasets/)
+examples/datasets/cwfid/
+examples/datasets/phenobench/
+sample_data/
+
+# Claude Code local runtime state — session-local, changes every run
+.claude/scheduled_tasks.lock
+
+# OS files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+*~
+
+# Temporary files
+*.tmp
+*.temp
+*.swp
+*.swo

precisionai_agritune-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,48 @@
+repos:
+  # ── File hygiene ────────────────────────────────────────────────────────────
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+        args: ["--maxkb=1800"]
+      - id: check-yaml
+      - id: check-json
+      - id: check-toml
+      - id: end-of-file-fixer
+        exclude: ^\.github/badges/
+      - id: trailing-whitespace
+        args: ["--markdown-linebreak-ext=md"]
+        exclude: ^\.github/badges/
+      - id: check-merge-conflict
+      - id: detect-private-key
+      - id: debug-statements
+      - id: fix-byte-order-marker
+
+  # ── Ruff: lint + format + import sorting ───────────────────────────────────
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.17
+    hooks:
+      - id: ruff
+        args: ["--fix"]
+      - id: ruff-format
+
+  # ── Type checking (pyright / pylance engine) ────────────────────────────────
+  - repo: local
+    hooks:
+      - id: pyright
+        name: pyright
+        entry: python -m pyright
+        language: system
+        types: [python]
+        pass_filenames: false
+
+  # ── Tests + coverage (≥ 90%) ────────────────────────────────────────────────
+  - repo: local
+    hooks:
+      - id: pytest
+        name: pytest (coverage ≥ 90%)
+        entry: python -m pytest
+        language: system
+        args: ["tests/", "-q", "--tb=short", "--no-header", "-m", "not integration and not distributed"]
+        pass_filenames: false
+        always_run: true

precisionai_agritune-1.0.0/CHANGELOG.md

@@ -0,0 +1,336 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Performance
+
+- `feature_preload: host | device` (new `TrainingRunConfig` field, default `none`): reads the
+  training and validation splits' cached features once, before training, into one contiguous
+  buffer in RAM or GPU memory (new `precisionai.agritune.features.memory.InMemoryFeatureProvider`),
+  and decodes every mask once into a compact `uint8` cache (new
+  `segmentation_common.PreloadedBatches`). Each batch then becomes one gather, instead of a
+  per-sample store read, validation, and concatenation plus a PNG decode per mask every epoch.
+  Measured on an A100 with 113,584 training and 37,707 validation samples and a linear probe,
+  with every change in this release, epoch times including validation went from 1,921 s (reading
+  a sharded store) to 51–62 s with 57x38 grids in host RAM and 7.5 s with 16x16 grids on the GPU.
+  A 100-epoch run at 798x532 masks that took about 80 hours now takes 3 h 45 min end to end, and
+  reaches the same test metrics (mean IoU within 0.05 pp). Requires `feature_provider: cached`.
+- Preloading reads each shard once and copies entries into the buffer on a small thread pool
+  (5.4 minutes for 252 GB of `float16` features, 3.2x faster than a single thread), and
+  `InMemoryFeatureProvider` resolves a sample's row by object identity after its first lookup, so
+  cache keys are not rehashed every epoch.
+- `feature_preload_dtype: float16 | bfloat16 | float32` stores preloaded tokens in a smaller
+  dtype (cast back to `float32` on the device before the decoder); a value that would overflow
+  is rejected while preloading.
+- `shuffle: true` (requires `feature_preload`) reshuffles training samples every epoch in an order
+  derived from `seed` and the epoch index, so a resumed run replays the same order.
+- Every decoder (and the loss/metric resize fallbacks) now resizes logits with
+  `tasks.segmentation.upsample.bilinear_resize`, which computes exactly what
+  `F.interpolate(mode="bilinear", align_corners=False)` does as two small matrix products.
+  PyTorch's CUDA backward for bilinear upsampling scatters gradients with atomic adds, which took
+  48 of 61 ms per linear-probe step when upsampling a 16x16 grid to 224x224; the matrix form takes
+  8 ms for the whole step. Values match `F.interpolate` to floating-point rounding.
+- `PrefetchingFeatureLoader` now issues its copies on a dedicated CUDA stream, so the next batch's
+  host-to-device transfer actually overlaps the current step instead of queueing behind it on the
+  default stream.
+- `CachedFeatureProvider` keys no longer re-read and re-hash every image file on every epoch:
+  `build_image_hash_fn` memoizes each sample's image hash for the life of the run.
+- `ShardedFeatureStore.read()` looks entries up in a per-shard index instead of scanning every
+  tensor name in the shard for each read, and both stores gain `read_many()`, which loads each
+  shard file once no matter what order keys are requested in.
+- `EncoderFeatures.to()` no longer re-runs full validation (a non-finite scan plus host reads,
+  which force a GPU sync on every batch); new `EncoderFeatures.trusted()` builds an instance from
+  already-validated tensors.
+
+### Security
+
+- Every API request field naming a filesystem path (`manifest_path`, `store`, `checkpoint_path`,
+  `output_dir`, `config_path`, `augmentation_config_path`) is now resolved through a new
+  `precisionai.agritune.api.paths.resolve_under_root` helper and rejected with HTTP 400 if it
+  would resolve outside the configured API root (`AGRITUNE_API_ROOT`, defaulting to the server's
+  current working directory) — closing a path-traversal gap where an absolute path or a `..`
+  segment let a request read or write anywhere the server process could access (e.g.
+  `checkpoint_path` into `torch.load`, `output_dir` for prediction PNGs, `config_path` into
+  training). This API still has no built-in authentication by design — see `SECURITY.md`.
+- Pull-request CI now requests `contents: read` only, reusable unit-test/pre-commit jobs declare
+  the same, and their checkouts set `persist-credentials: false` so pull-request code cannot run
+  with a repository write token.
+- Logging redacts API keys, Authorization values, sensitive Hydra/dotlist overrides, and URL
+  userinfo/query credentials before emit, including DEBUG override dumps and encoder base URLs.
+
+### Documentation
+
+- `docs/datasets.md` explains that `agritune train` splits its own manifest into training and
+  validation (`val_fraction`, per sample, ignoring any `split` column), so test samples belong in a
+  separate manifest for `agritune evaluate`, with a worked example that holds out whole fields via
+  `grouped_split`. `docs/configuration.md`, `docs/reproducibility.md`, `docs/segmentation.md`,
+  `docs/feature-caching.md`, and the README cover preloading, shuffling, seeding, and output
+  resolution.
+
+### Fixed
+
+- Two `tests/unit/test_features.py` tests failed on Python 3.13 (and only there) with `Boolean value
+  of Tensor with more than one value is ambiguous`: they compared `EncoderFeatures` instances with
+  `==`, which the generated dataclass `__eq__` can only answer when both sides hold the same tensor
+  objects, and 3.13 now compares field by field. They compare the fields explicitly. No library
+  behavior changed.
+- Training under `augmentation.mode: none` with `geometric.resize` built the decoder at the
+  dataset's *native* mask size, because the output-size probe skipped the resize that every
+  training batch still receives. The decoder then upsampled to the native size (8.5x more pixels
+  for 798x532 masks resized to 224x224), and the loss and metric resized every batch's logits back
+  down: three full-size resizes per step. The probe now applies `resize` exactly like
+  `build_training_batches` (and like `prediction_service` already did). On an A100 this alone cut
+  a 20,000-sample, two-epoch linear-probe run from 36.1 s to 4.7 s.
+- `EncoderFeatures.uniform_patch_grid` reads the batch's patch grids in one host transfer instead
+  of one per sample (each a GPU synchronization when the grid is on a CUDA device).
+- The decoder's initial weights are now drawn right after seeding the global RNG from
+  `trainer.seed`. Previously they depended on whatever had advanced the RNG earlier in the process
+  (every `DataLoader` pass draws a seed from it), so the same config could start from different
+  weights depending on unrelated code paths. New runs therefore start from different (but now
+  seed-determined) weights than earlier versions did for the same config; resuming an existing
+  checkpoint is unaffected.
+- `SegmentationLoss` and `SegmentationMetric` accept class-index targets in any integer dtype
+  (widened to `int64` internally); a `uint8` target used to overflow the metric's
+  `targets * num_classes + predictions` index.
+- Pyright generic-typing error in `segmentation_common._IndexDataset`.
+- Pyright optional-palette subscript in `colorize_predictions` and live-test API-key narrowing
+  after `pytest.skip`.
+- `SegmentationMetric.update` now follows `outputs`/`targets` onto whatever device they're
+  actually on (its confusion-matrix accumulator used to stay fixed on CPU, raising a
+  device-mismatch error the first time `Trainer`/`evaluate()` moved a batch to CUDA).
+- Feature-space augmentation (`augmentations.feature.transforms`) now moves every random
+  mask/noise tensor it draws onto the same device as the features it perturbs, instead of
+  leaving it on the CPU-based checkpointed RNG's device — the same class of device-mismatch bug,
+  triggered whenever `feature_augmentation` is enabled on a CUDA training run.
+
+### Added
+
+- `TrainingRunConfig.device` (`"cpu"`, `"cuda"`, or `"cuda:N"`): the decoder and every batch's
+  features/targets now actually move to the configured device before `forward`/`compute_loss`
+  (previously nothing in the training pipeline ever called `.to()`, so `trainer.precision: fp16`
+  silently never engaged CUDA's gradient scaler). Rejected up front via a new
+  `_validate_device_config` if it names a CUDA device that is unavailable or out of range for the
+  machine's GPU count — never a silent fallback to CPU. Added `EncoderFeatures.to(device)` and a
+  `device` parameter on `evaluate()` to support this.
+- `TrainingRunConfig.feature_read_workers`: exposes `CachedFeatureProvider`'s internal read
+  thread-pool size (previously a fixed constant) so it can be tuned independently of the
+  `DataLoader`'s `num_workers` — the dominant per-batch cost once `feature_provider: cached` skips
+  image loading entirely.
+- `precisionai.agritune.training.prefetch.PrefetchingFeatureLoader`: overlaps one batch's feature
+  fetch (a `FeatureProvider.get_features` call — a disk/store read for `cached`/`hybrid`) with the
+  previous batch's model compute in a single background thread, wired into both `Trainer`'s
+  training loop and `evaluate()`, so the GPU is no longer idle waiting on a synchronous feature
+  read every batch.
+- Info/debug/warning logging across previously-silent modules (services, encoder, evaluator),
+  plus `tqdm` progress bars over every long-running loop (training/validation batches,
+  evaluation, prediction, feature precompute, encoder benchmarking, and the CWFID/PhenoBench prep
+  scripts) via a new `precisionai.agritune.logging.progress_iter` helper. Progress bars are
+  opt-in per call (`show_progress`, default `False`) so the API stays headless; `Trainer`/
+  `evaluate()` gate them on `DistributedContext.is_main_process`, ready for the eventual DDP
+  rollout. The FastAPI app now calls `configure_logging()` on startup
+  (`AGRITUNE_LOG_LEVEL`, default `INFO`), and its Rich console handler now writes to stderr
+  instead of stdout so log lines never interleave with a CLI command's own JSON output.
+- CWFID example: `examples/datasets/prepare_cwfid.py` downloads the public Crop/Weed Field Image
+  Dataset, writes an AgriTune manifest, and `examples/SANITY_CHECK.md` runs the full hosted-encoder
+  pipeline against it. A `--full` flag downloads all 60 frames without needing to know the exact
+  count.
+- PhenoBench example: `examples/datasets/prepare_phenobench.py` downloads the public PhenoBench
+  sugar-beet dataset (1,407 train / 772 val real UAV field images, vs. CWFID's 60) and writes an
+  AgriTune manifest, collapsing its 5-way partial-visibility labels into AgriTune's 3-class
+  background/crop/weed convention.
+- Optional `.env` support (`pip install precisionai-agritune[dotenv]`): a `.env` file is loaded into the
+  environment before Hydra composition, so `${oc.env:AGRITUNE_ENCODER_API_KEY,null}` in
+  `encoder/remote.yaml` resolves from it. Exported shell variables still take precedence, and
+  `AGRITUNE_ENV_FILE` selects a file outside the working directory.
+- Repository foundations: packaging, CI, pre-commit, structured logging, CLI entrypoint (`agritune --help`).
+- Core schemas/protocols, agricultural dataset/manifest/split system, deterministic augmentation
+  pipeline, encoder abstraction (fake + remote) with a rate-limited/retrying gateway, feature
+  cache and resumable precomputation, `CachedFeatureProvider`, segmentation task (linear + TokenFPN
+  decoders, losses, metrics), training engine (AMP, gradient accumulation, checkpointing/exact
+  resume, provenance), optimizer/scheduler registries, and JSONL/TensorBoard/MLflow/W&B tracking.
+- `agritune features verify/inspect/clean`, `agritune evaluate`, `agritune predict`, and
+  `agritune encoder benchmark` commands, backed by their own services.
+- `OnlineFeatureProvider` and `HybridFeatureProvider`, bridging an `EncoderGateway` into the
+  synchronous `FeatureProvider` interface (the v0.2 online/hybrid feature path).
+- Feature-space augmentation (`augmentations.feature`): patch dropout, token masking, Gaussian
+  feature noise, CLS dropout, and channel dropout, wired into `Trainer` as an optional train-only
+  step.
+- Per-class precision/recall in `SegmentationMetric`; a configurable `checkpoint_top_k` for
+  validation-ranked periodic checkpoints; a `temporal_split` dataset split strategy; a prediction
+  visualization module (`--overlays` on `agritune predict`); `NeptuneTracker` and `CometTracker`.
+- Agricultural domain-specific image augmentations: sensor channel dropout, ground-sample-distance
+  (GSD) jitter, a red/green vegetation-index-balance jitter, and a seasonal/growth-stage hue shift.
+- `augmentation.mode: hybrid` — deterministically reuses an offline variant most of the time, and
+  derives a fresh online seed for a configurable fraction of `(sample, epoch, occurrence)` combinations.
+- `PrefetchingFeatureProvider` (`precisionai.agritune.features.prefetch`): overlaps encoding with
+  training via a bounded background queue, so an online/hybrid feature provider's network latency
+  is hidden behind the GPU training step instead of blocking it. Cancellable mid-consumption (e.g.
+  early stopping) without deadlocking `close()`.
+- The API layer (`precisionai.agritune.api`): a thin FastAPI app (`create_app()`) with one route
+  per CLI command (`dataset validate/inspect`, `features build/verify/inspect/clean`, `train`,
+  `evaluate`, `predict`, `encoder benchmark`), calling the exact same `services/` functions as the
+  CLI. `ValueError`/`FileNotFoundError`/`FeatureNotCachedError`/`CheckpointMismatchError` map to
+  400/404/404/409 respectively; everything else surfaces as a 500, same as an uncaught CLI
+  traceback. Encoder-backend selection was extracted into `services.encoder_selection`, shared by
+  both entry points.
+- Real Hydra config-group composition (`precisionai/agritune/configs/`): named YAML variants under
+  `dataset/`, `encoder/`, `augmentation/`, `feature_provider/`, `task/`, `decoder/`, `optimizer/`,
+  `scheduler/`, and `tracking/`, composed via a `defaults:` list in the packaged `config.yaml`.
+  `cli.config.load_training_run_config` resolves either shape: a plain flat YAML file (unchanged,
+  original behavior) or a `defaults:`-bearing file resolved through `hydra.compose()`, with the
+  same `key=value` override list also able to swap group variants (`decoder=token_fpn`,
+  `augmentation=online`). `feature_provider` (`cached`/`online`/`hybrid`), `augmentation`
+  (`none`/`offline`/`online`/`hybrid`), and `tracking` selection are now wired end-to-end into
+  `run_training`, which rejects the `augmentation=online|hybrid` + `feature_provider=cached`
+  combination before training starts.
+- Four new segmentation decoders, alongside a generalized MLP probe replacing the old
+  linear-only baseline: `ASPPDecoder` (Atrous Spatial Pyramid Pooling, DeepLabv3-style),
+  `PyramidPoolingDecoder` (PSPNet-style pyramid pooling), `SegmenterMaskTransformerDecoder`
+  (Segmenter-style joint patch/class-token transformer with a scaled dot-product mask head), and
+  `MaskFormerDecoder` (MaskFormer/Mask2Former-style query-based mask classification, combined into
+  dense per-pixel scores rather than trained with the original papers' bipartite-matching loss).
+  `LinearProbeDecoder` is replaced by `MLPProbeDecoder` (`decoder=mlp_probe`): with
+  `hidden_dims=()` (the default) it is architecturally identical to the old linear probe;
+  `hidden_dims=(256,)` etc. adds non-linear depth. `build_decoder` now accepts a generic
+  `decoder_kwargs` passthrough forwarded to any decoder's constructor (also newly closing a gap
+  for `TokenFPNDecoder`'s `cls_fusion`/`hidden_dim`, previously unconfigurable outside direct
+  Python construction) — set via each decoder's own Hydra config-group variant
+  (`configs/decoder/{mlp_probe,token_fpn,aspp,ppm,segmenter,mask_former}.yaml`).
+- `Trainer.fit`'s optional `train_metric` parameter: a `Metric` accumulated over every training
+  batch each epoch (reset at the epoch's start) and logged as `train_{name}` (e.g. `train_mean_iou`)
+  alongside the existing `train_loss`/`lr`, exposed via `Trainer.last_train_metrics`. `run_training`
+  now always passes one, so `TrainingRunResult.train_metrics` / `agritune train`'s printed summary
+  / `POST /train`'s response report full segmentation metrics for the training set too, not just
+  loss — useful for spotting a train/val gap, though noisier than validation since it reflects a
+  moving model on (possibly augmented) training batches.
+- `Evaluator.evaluate` (shared by `Trainer`'s validation pass and `agritune evaluate`) now also
+  computes a batch-size-weighted mean loss and adds it to its returned dict as `"loss"`, so
+  `val_metric_name: loss` (with `higher_is_better: false`) works as a checkpoint/early-stopping
+  signal. `EvaluationRunConfig`/`agritune evaluate --loss-*`/`POST /evaluate`'s `loss` field let the
+  loss config used for this be set to match what a checkpoint was actually trained under.
+- `agritune features build --augmentation-config <path> --seed <int>` (and `POST /features/build`'s
+  matching `augmentation_config_path`/`seed` fields): precomputes a deterministic offline-augmented
+  variant alongside the unaugmented features, closing a gap where `feature_service.build_features`
+  already supported `augmentation_mode=OFFLINE` but neither entry point exposed it. The
+  `--augmentation-config` file is the same `mode`/`variant`/`geometric`/`photometric` shape as
+  `configs/augmentation/*.yaml` — point both the build and the training config's `augmentation:`
+  block at the same file so their cache keys match. New `cli.config.load_augmentation_selection`
+  shares the parsing between the CLI and the API route.
+- `TrainingRunConfig.feature_augmentation` (`feature_augmentation:` in a flat YAML config, or the
+  new `feature_augmentation` Hydra group — `none`/`light` — in the composed one), closing a gap
+  where `FeatureAugmentationPipeline`/`FeatureAugmentationConfig` (patch dropout, token masking,
+  Gaussian feature noise, CLS dropout, channel dropout) were fully implemented and accepted by
+  `Trainer`'s constructor but never reachable from `agritune train`/`POST /train` — only from
+  direct Python construction. Included in the run's critical-config reproducibility fingerprint,
+  alongside image-space `augmentation`.
+- `agritune config init --output <path> [--force]`: writes a fully-commented, flat training config
+  template spelling out every field `TrainingRunConfig` accepts at its default value, with the
+  dataset-specific fields marked `REQUIRED` as placeholders — the same shape as
+  `examples/segmentation/cwfid.yaml` without the CWFID-specific values. Backed by the new
+  `services.config_template_service`.
+- `agritune dataset init --output <path> [--force]`: writes an example manifest CSV (a header row
+  plus a few placeholder samples) to start a new dataset's manifest from. Backed by
+  `services.dataset_service.write_manifest_template`, sharing its file-writing/overwrite-guard
+  logic with `config init` via the new `utils.scaffold` helper.
+
+### Changed
+
+- The PyPI distribution is now named `precisionai-agritune` (it was `pai-agritune`, which was never
+  published), matching `precisionai-agrieval`. Install with `pip install precisionai-agritune`; the
+  import package (`precisionai.agritune`) and the `agritune` command are unchanged. `release.yml`,
+  the README (including its PyPI and Python-version badges), `SECURITY.md`, the bug-report
+  template, install hints in error messages and tracking configs, and the tests that assert them
+  now use the new name.
+- README: primary header is now "Precision AI AgriTune"; badges moved below the description; the
+  stale "Status" section (internal build-phase notes) was removed; `Installation` no longer opens
+  the document — a runnable `Quick Start` does, followed by `Project layout`, with a new
+  "FastAPI server" subsection under `Installation` covering the `[api]` extra and `uvicorn`.
+  `Quick Start` walks the packaged CWFID example end-to-end (dataset prep, validate, feature
+  build, train, evaluate) instead of a synthetic placeholder manifest, with a `fake-encoder`
+  fallback for anyone without hosted-encoder access yet.
+- `pyproject.toml`'s `api` extra now also installs `uvicorn`, so `pip install "precisionai-agritune[api]"`
+  is sufficient to run the FastAPI server (previously required a separate manual `pip install
+  uvicorn`).
+- The image augmentation pipeline (`augmentations.image`) now composes
+  [albumentations](https://albumentations.ai/) transforms instead of hand-rolled PIL/numpy code,
+  using `Compose.set_random_seed` for the same exact-reproducibility guarantee as before.
+
+### Fixed
+
+- `requirements.txt` no longer hard-pins a CUDA build of `torch` (`torch==2.14.0+cu130` via
+  `--extra-index-url .../cu130`) — that install fails outright on CPU-only/non-Linux machines,
+  contradicting this repo's own CPU-only CI. Now a plain `torch>=2.2`, matching `pyproject.toml`;
+  a comment (and a matching README note) shows the two-step CPU-only install
+  (`pip install torch --index-url https://download.pytorch.org/whl/cpu`, same as
+  `unit-test.yml`) needed on Linux, where PyPI's default wheel still bundles the full CUDA
+  runtime even on a machine with no GPU, plus how to opt into a specific CUDA build instead.
+- `CODE_OF_CONDUCT.md` was missing the "Enforcement Guidelines" section (Correction/Warning/
+  Temporary Ban/Permanent Ban) from the official Contributor Covenant v2.1 text — restored
+  verbatim.
+- `LICENSE.md` had several small wording drifts from the canonical Apache 2.0 text — replaced with
+  the exact upstream text.
+- `.github/dependabot.yml` was missing the `groups: python-dependencies: patterns: ["*"]` block on
+  its `pip` update, so routine dependency bumps opened one PR per package instead of one grouped
+  weekly PR.
+- `examples/SANITY_CHECK.md` and `examples/FEATURE_TEST_COMMANDS.md` pointed evaluate/predict at
+  `runs/cwfid-sanity/checkpoints/...`, a run_id `examples/segmentation/cwfid.yaml` never actually
+  produces (it sets `run_id: cwfid-sanity-mlp_probe-feature_aug`) — the checkpoint path in both
+  docs never existed. Corrected to the run_id the config actually writes.
+- Flush partial gradient-accumulation windows instead of silently dropping their gradients.
+- Execute gateway-split encoder batches concurrently while preserving response order.
+- Preserve augmentation fingerprints through training batches so hybrid cache keys cannot reuse
+  stale features across different augmented images.
+- Harden variable-grid feature masking, remote-response validation, checkpoint fingerprints,
+  secret-safe run provenance, and tracker-failure isolation.
+- Persist early-stopping progress across resume so training cannot run extra epochs after a stop.
+- Derive feature-cache keys from a canonical JSON payload so delimiter characters in sample IDs
+  cannot collide with adjacent fingerprint fields.
+- Decode CLS embeddings from little-endian float32 base64, matching `encoding_format="base64"` on
+  the hosted encoder API — a float-list-only parser crashed on the real `pai-embedding` response.
+- Defer `comet_ml`'s import to `CometTracker` construction instead of importing it at module load.
+  `comet_ml` auto-instruments other frameworks in the process (notably `mlflow`) merely by being
+  imported; since `tracking_selection.py` imports every tracker module up front, selecting any
+  *other* backend (e.g. `mlflow`) silently created an uninvited offline Comet experiment whenever
+  `comet_ml` happened to be installed alongside it — which it always is, since both ship in the
+  `precisionai-agritune[tracking]` extra.
+- Derive a training run's decoder `output_size` from the actually-augmented probe sample instead
+  of the raw pre-augmentation one, so `augmentation.geometric.resize`/`random_crop` (which change
+  spatial size) no longer builds a decoder upsampling to the wrong resolution.
+  `SegmentationLoss.forward`/`SegmentationMetric.update` now also bilinearly resize logits to the
+  target's spatial size when they differ, since validation targets are never augmented and can
+  therefore legitimately disagree with training's working resolution under one fixed decoder.
+- Log every encoder retry attempt (`EncoderGateway`) at `WARNING` instead of only counting it in
+  metrics — a bounded retry-then-fail run and an actual hang were previously indistinguishable from
+  the terminal, since nothing was printed during the backoff sleeps between attempts.
+- CI (`unit-test.yml`/`pre-commit.yml`): install the CPU-only `torch` wheel
+  (`--index-url https://download.pytorch.org/whl/cpu`) before `pip install -e ".[dev]"` — the
+  default Linux PyPI wheel bundles the full CUDA runtime (several GB of `nvidia-*`/`triton`
+  packages) that a CPU-only CI runner never uses, and was exhausting the runner's disk.
+- `evaluation_service.py`/`prediction_service.py`/`training_service.py`: build a decoder's
+  `output_size` via a new `segmentation_common.mask_output_size` helper that returns a concrete
+  `tuple[int, int]`, instead of `tuple(np.array(mask).shape)` (typed as a variable-length
+  `tuple[int, ...]`) — fixes a `pyright` `reportArgumentType` error that a newer `numpy` type-stub
+  resolution surfaces on some Python versions.
+- `trailing-whitespace` pre-commit hook: pass `--markdown-linebreak-ext=md` so it stops stripping
+  intentional Markdown hard-break trailing spaces (it was rewriting `examples/SANITY_CHECK.md` on
+  every run).
+- Fix the remaining pre-existing `pyright` errors, none introduced by recent work but all blocking
+  a clean `pre-commit`/CI run: `LossConfigRequest.name` (API schema) now uses the same `LossName`
+  literal as `SegmentationLossConfig` instead of a bare `str`; `ImageAugmentationPipeline` builds
+  its transform list typed as albumentations' own `TransformsSeqType` instead of the invariant-
+  incompatible `list[BasicTransform]`; `PrecisionContext.autocast()` is typed to yield `Any`
+  (`nullcontext`/`torch.autocast` disagree on what `__enter__` returns, but no caller binds it);
+  `cli/config.py`'s `_config_from_dict(resolved)` call gets the same `# type: ignore[arg-type]`
+  treatment the file already uses for `OmegaConf.to_container`'s deliberately-broad return type;
+  and several tests narrow an `Optional`/generic-`nn.Module` value with an `assert ... is not None`
+  / `isinstance` check before using it, instead of relying on runtime knowledge pyright can't see.
+- Untrack `.claude/scheduled_tasks.lock` (a Claude Code runtime lock file — session ID/PID/
+  timestamp, changes every session) and gitignore it; it was flapping `end-of-file-fixer` on
+  unrelated commits.
+
+[Unreleased]: https://github.com/Precision-AI-Inc/agritune/compare/v0.1.0...HEAD