218 lines
7.3 KiB
Markdown
218 lines
7.3 KiB
Markdown
# 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
|
|
|
|
```text
|
|
/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:
|
|
|
|
```text
|
|
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.
|