Raise configured YOLO max detections

docs/AI_PIPELINES.md

@@ -109,8 +109,16 @@ Environment variables:
 - `YOLO_DEVICE`
 - `YOLO_IMAGE_SIZE`
 - `YOLO_MAX_TILES`
+- `YOLO_MAX_DETECTIONS`
 - `YOLO_BATCH_SIZE`
 
+`YOLO_MAX_DETECTIONS` is forwarded to Ultralytics as `max_det` for each
+prediction call. GeoIntel defaults it to `1000` because building-rich AOIs can
+contain far more than the Ultralytics default of 300 candidate boxes; keeping
+the upstream default would cap recall before QA/QC begins. Operators may lower
+the value for small rasters or raise it for dense urban tiles after reviewing
+runtime and false-positive behavior.
+
 ### Local model asset catalog
 
 GeoIntel can list local runtime model files mounted into the backend model

docs/API_CONTRACTS.md

@@ -782,6 +782,9 @@ Validation errors:
 - `DETECTION_TILE_MANIFEST_NOT_FOUND` when the provided manifest path does not exist.
 - `DETECTION_TILE_MANIFEST_INVALID` when the manifest cannot be parsed or lacks tile metadata.
 - `DETECTION_TILE_LIMIT_EXCEEDED` when the manifest exceeds `YOLO_MAX_TILES`.
+- Configured YOLO inference forwards `YOLO_MAX_DETECTIONS` to Ultralytics
+  `max_det` and defaults to `1000` so dense building AOIs are not silently
+  limited by the upstream default of 300 detections before persisted QA/QC.
 - `DETECTION_DEPENDENCY_UNAVAILABLE` when YOLO dependencies are not installed.
 - `DETECTION_MODEL_LOAD_FAILED` when the local model file exists but cannot be loaded.
 

docs/CODEX_EXECUTION_LOG.md

@@ -1,3 +1,32 @@
+## Sprint 148 YOLO max-detection cap hardening (2026-07-09)
+
+Changed:
+- Added backend setting `YOLO_MAX_DETECTIONS` / `Settings.yolo_max_detections`.
+- `YoloDetectionAdapter` now forwards the value to Ultralytics as `max_det`.
+- Default is `1000` instead of relying on Ultralytics' upstream default of 300.
+- Added Docker/Unraid/runtime wiring:
+  - `.env.example`
+  - `docker-compose.yml`
+  - `docker-compose.unraid.yml`
+  - `deploy/unraid/geointel.env.example`
+  - `deploy/unraid/run-dockerman-container.sh`
+- Updated backend/API/AI environment documentation.
+
+Why:
+- Real Kempen building AOIs often contain more than 300 reference buildings.
+- The previous configured-YOLO path could saturate at 300 detections before QA/QC, capping recall independently of model quality.
+- This does not activate a model and does not fake detections; it removes an inference runtime cap so persisted QA/QC can measure candidate models honestly.
+
+Tested:
+- Red step: targeted YOLO adapter tests failed because `max_det` was not passed to the model.
+- `python -m pytest backend\tests\test_sprint8b_yolo_foundation.py::test_yolo_adapter_converts_single_band_tiles_to_rgb_before_prediction backend\tests\test_sprint8b_yolo_foundation.py::test_yolo_adapter_uses_configured_max_detections -q` (`2 passed`)
+- Red step: Docker runtime config tests failed before `.env.example` and Unraid runner exposed `YOLO_MAX_DETECTIONS`.
+- `python -m pytest backend\tests\test_docker_runtime_config.py::test_env_example_uses_runtime_env_names_read_by_backend_and_frontend backend\tests\test_docker_runtime_config.py::test_unraid_deploy_passes_ai_build_arg_and_yolo_runtime_env backend\tests\test_sprint8b_yolo_foundation.py -q` (`16 passed`)
+
+Open:
+- Rebuild/redeploy the Tower all-in-one image before rerunning live calibration so the container uses `YOLO_MAX_DETECTIONS=1000`.
+- After deploy, rerun at least one high-density AOI calibration to confirm detection counts are no longer capped at 300.
+
 ## Sprint 147 AOI512 YOLOv8s scale-match candidate gate (2026-07-09)
 
 Changed:

docs/ENVIRONMENT_SPEC.md

@@ -21,6 +21,7 @@ YOLO_ENABLED=false
 YOLO_MODEL_PATH=
 YOLO_MODEL_VERSION=
 YOLO_MAX_TILES=100
+YOLO_MAX_DETECTIONS=1000
 ENABLE_GRB_WFS=false
 GRB_WFS_URL=
 OSM_OVERPASS_URL=https://overpass-api.de/api/interpreter

docs/TODO.md

@@ -110,9 +110,11 @@ This file now starts with the current implementation status. Older preparation/b
 - [x] Benchmark an external remote-sensing YOLOv8l building candidate as an explicit local model asset.
 - [x] Train and gate the `uniquehardneg160e50` YOLOv8s candidate through 7 positive AOIs and 9 hard-negative/background samples.
 - [x] Train and gate an AOI-scale `aoi512e80` YOLOv8s candidate to test the 160px training-scale hypothesis.
+- [x] Raise configured-YOLO `max_det` through `YOLO_MAX_DETECTIONS` so dense AOIs are not capped at 300 detections before QA/QC.
 - [ ] Find or train a materially stronger aerial/Kempen building model candidate; `geointel-building-yolov8n-expanded160e50-pt` is the best current dense-AOI candidate but still too weak and too noisy for a V1 default.
 - [ ] Train a higher-capacity local aerial-building detector with stronger positive recall while preserving the hard-negative false-positive gate.
 - [ ] Add more diverse positive AOIs and revisit geometry-to-box label strategy before the next default-model training attempt.
+- [ ] Rerun live dense-AOI calibration after redeploy with `YOLO_MAX_DETECTIONS=1000` to measure uncapped recall and false-positive pressure.
 
 ## Sprint 8 status