geointel/docs/superpowers/specs/2026-07-06-model-reference-catalog-design.md

Model And Reference Catalog Design

Goal

Make GeoIntel operationally clearer for V1 users by separating two concepts that currently look too similar in the UI:

• local AI model assets that can be selected for configured YOLO inference;
• official or contextual reference data providers such as GRB, OSM, manual uploads and fixtures.

This pass must not download model weights, fetch live GRB/OSM data, add training, add auth, or bypass the existing dataset, job, analysis run and detection persistence architecture.

Current State

Detection currently exposes a model capability list with:

• yolo-placeholder;
• one configured slot, yolo-configured, backed by YOLO_MODEL_PATH;
• manual-fixture-detector.

This is import-safe and honest, but it does not feel like a model picker. A user can place multiple files in /app/models, yet the UI can only show the single configured environment slot.

Reference data currently exposes provider capabilities for:

• grb;
• osm;
• manual;
• fixture.

This is architecturally correct, but the UI does not yet make the distinction explicit enough between authoritative reference sources and AI model assets.

Non-Goals

• No automatic model downloads.
• No bundled production model files in git.
• No live GRB WFS or OSM Overpass import.
• No direct writes from providers into vector_features.
• No new database tables for model assets in this pass.
• No training studio, model management workflow, LiDAR, reports, copilot or multi-user scope.

Options Considered

Option A: Keep Only YOLO_MODEL_PATH

Keep the current single configured model slot and document that users must edit .env.

Benefits:

• smallest code change;
• preserves all existing contracts.

Drawbacks:

• poor operator experience;
• no visible list of available local model files;
• users cannot tell whether the model directory contains other usable files.

Option B: Filesystem-Backed Model Asset Catalog

Scan a configured model directory, expose local model files through an API, and let the UI select one asset for yolo-configured runs.

Benefits:

• aligns with the current runtime model mount (/app/models);
• no database migration;
• no downloads or fake model metadata;
• can show file existence, size, checksum and active environment model;
• keeps actual inference inside DetectionService and YoloDetectionAdapter.

Drawbacks:

• metadata is limited unless optional sidecar files are added later;
• model classes are not guaranteed without loading the model.

Option C: Persisted Model Registry

Create database tables for model registry records, model versions, model artifacts and model lifecycle state.

Benefits:

• strong long-term foundation for training studio and MLOps;
• full metadata and auditability.

Drawbacks:

• too broad for V1;
• adds migration and lifecycle complexity before runtime needs justify it;
• risks distracting from core GIS workflow completion.

Recommended Approach

Use Option B.

Add a filesystem-backed model asset catalog for local runtime model files. It should scan YOLO_MODELS_DIR, defaulting to /app/models, and fall back to the parent directory of YOLO_MODEL_PATH when appropriate. It should only report local files with known model suffixes such as .pt, .onnx and .engine.

The catalog must be read-only. It must never download, create, mutate, move or delete model files.

Detection runs should still use model_id="yolo-configured" for the real YOLO execution path, but may include a selected model_asset_id. The backend resolves that ID to a path inside the configured model directory and uses that path for the run. This avoids arbitrary path injection while keeping the existing detection contract compatible.

Backend Design

Create ModelAssetCatalogService.

Responsibilities:

• resolve the model directory from settings;
• scan known model file suffixes;
• return deterministic asset IDs derived from file names;
• compute SHA-256 and size for visible provenance;
• mark which asset matches the active YOLO_MODEL_PATH;
• resolve a selected asset ID to a local path;
• reject missing, unknown or out-of-directory model assets.

Add schemas:

• ModelAssetRead;
• ModelAssetListResponse.

Add endpoint:

• GET /api/v1/detection/model-assets

Extend existing endpoints without breaking older clients:

• GET /api/v1/detection/yolo/preflight accepts optional model_asset_id;
• POST /api/v1/detection/run accepts optional model_asset_id.

When model_asset_id is supplied, DetectionService should use a settings copy with yolo_model_path replaced by the resolved asset path. The run parameters should persist the selected asset ID and path for reproducibility.

Frontend Design

Detection Lab should show:

• model capability cards;
• a local model asset picker for configured YOLO;
• active model indicator;
• asset size and checksum prefix;
• selected asset passed to preflight and detection run;
• clear warning that GeoIntel does not download weights.

Provider panel should show:

• official reference source catalog;
• GRB as authoritative but not configured for live fetch;
• OSM as contextual and not configured for live fetch;
• manual uploads as the configured way to add real reference datasets now;
• fixtures as demo/test only.

Data Flow

/app/models/*.pt
  -> ModelAssetCatalogService
  -> GET /api/v1/detection/model-assets
  -> Detection Lab model asset picker
  -> POST /api/v1/detection/run model_id=yolo-configured + model_asset_id
  -> DetectionService resolves local path
  -> YoloDetectionAdapter loads selected local model
  -> Job + AnalysisRun + Detection persistence

Reference data remains:

Provider registry
  -> capabilities/status/limitations
  -> manual upload or future provider import
  -> DatasetService / VectorFeatureService
  -> vector_features
  -> detection/segmentation QA

Error Handling

• Unknown model_asset_id: DETECTION_MODEL_ASSET_NOT_FOUND.
• Model asset outside configured directory: DETECTION_MODEL_ASSET_INVALID.
• Missing configured YOLO dependencies: existing dependency unavailable behavior.
• Missing tile manifest: existing tile manifest required behavior.
• Missing model file after catalog resolution: existing model unavailable behavior.

Tests

Backend tests should cover:

• catalog lists only supported local model files;
• catalog marks the active model;
• checksum and size are reported;
• invalid assets are ignored;
• unknown asset ID fails cleanly;
• selected model asset is persisted in job and analysis run parameters;
• model assets endpoint uses canonical envelope;
• preflight accepts selected asset without model downloads.

Frontend tests should cover:

• Detection Lab exposes local model asset selection;
• selected model asset is sent to run and preflight requests;
• Provider Panel copy distinguishes reference providers from model assets.

Documentation

Update:

• docs/API_CONTRACTS.md;
• docs/AI_PIPELINES.md;
• backend/README.md;
• frontend/README.md;
• docs/CODEX_EXECUTION_LOG.md;
• CHANGELOG.md;
• docs/TODO.md.

Future Work

• Sidecar model metadata files, for example model.pt.json, for class names, source, license and intended task;
• optional model compatibility smoke per selected asset;
• persisted model registry after V1 foundation is stable;
• live GRB/OSM imports through provider contracts;
• official reference dataset browser after live provider imports exist.