segment-geospatial 1.3.3__tar.gz → 1.4.0__tar.gz

{segment_geospatial-1.3.3 → segment_geospatial-1.4.0}/.github/workflows/ubuntu.yml

@@ -50,6 +50,8 @@ jobs:
                   pip install --user .
             - name: Test import
               run: python -c "import samgeo; print('samgeo import successful')"
+            - name: Fast unit tests
+              run: python -m unittest tests.test_utmconv
             # - name: PKG-TEST
             #   run: |
             #       python -m unittest discover tests/

{segment_geospatial-1.3.3 → segment_geospatial-1.4.0}/.pre-commit-config.yaml

@@ -12,7 +12,7 @@ repos:
             args: ["--maxkb=500"]
 
     - repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.15.16
+      rev: v0.15.17
       hooks:
           - id: ruff
             types_or: [pyi, jupyter]

{segment_geospatial-1.3.3 → segment_geospatial-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: segment-geospatial
-Version: 1.3.3
+Version: 1.4.0
 Summary: Meta AI's Segment Anything Model (SAM) for Geospatial Data.
 Author-email: Qiusheng Wu <giswqs@gmail.com>
 License: MIT license
@@ -71,7 +71,7 @@ Requires-Dist: scikit-image; extra == "samgeo2"
 Requires-Dist: scipy; extra == "samgeo2"
 Provides-Extra: samgeo3
 Requires-Dist: segment_geospatial[core]; extra == "samgeo3"
-Requires-Dist: sam3; extra == "samgeo3"
+Requires-Dist: sam3>=0.1.4; extra == "samgeo3"
 Requires-Dist: scikit-learn; extra == "samgeo3"
 Requires-Dist: scikit-image; extra == "samgeo3"
 Requires-Dist: transformers; extra == "samgeo3"

{segment_geospatial-1.3.3 → segment_geospatial-1.4.0}/docs/api.md

@@ -96,7 +96,7 @@ Runs automatic mask generation on an uploaded image. Supports SAM, SAM2, and SAM
 |-----------|------|---------|-------------|
 | `file` | file | required | Image file (TIFF, PNG, JPEG) |
 | `model_version` | string | `sam2` | One of `sam`, `sam2`, `sam3` |
-| `model_id` | string | auto | Model identifier (e.g., `sam2-hiera-large`) |
+| `model_id` | string | auto | Model identifier (e.g., `sam2-hiera-large`, `facebook/sam3.1`) |
 | `output_format` | string | `geojson` | One of `geojson`, `geotiff`, `png`, `json`, `detections` |
 | `foreground` | bool | `true` | Extract foreground objects only |
 | `unique` | bool | `true` | Assign unique ID to each object |
@@ -131,7 +131,7 @@ For SAM3 with bounding box prompts, the model finds **all similar objects** in t
 |-----------|------|---------|-------------|
 | `file` | file | required | Image file (TIFF, PNG, JPEG) |
 | `model_version` | string | `sam3` | One of `sam`, `sam2`, `sam3` |
-| `model_id` | string | auto | Model identifier |
+| `model_id` | string | auto | Model identifier (e.g., `facebook/sam3.1`) |
 | `output_format` | string | `geojson` | One of `geojson`, `geotiff`, `png`, `json`, `detections` |
 | `point_coords` | string | none | JSON array of `[[x, y], ...]` |
 | `point_labels` | string | none | JSON array of `[1, 0, ...]` (1=foreground, 0=background) |
@@ -222,8 +222,8 @@ Runs text-prompt segmentation using SAM3.
 |-----------|------|---------|-------------|
 | `file` | file | required | Image file (TIFF, PNG, JPEG) |
 | `prompt` | string | required | Text description (e.g., `building`, `tree`) |
-| `model_id` | string | auto | SAM3 model identifier |
-| `backend` | string | `meta` | One of `meta`, `transformers` |
+| `model_id` | string | auto | SAM3 model identifier (`facebook/sam3` or `facebook/sam3.1`) |
+| `backend` | string | `meta` | One of `meta`, `transformers`; SAM 3.1 uses `meta` |
 | `output_format` | string | `geojson` | One of `geojson`, `geotiff`, `png`, `json`, `detections` |
 | `confidence_threshold` | float | `0.5` | Detection confidence threshold |
 | `min_size` | int | `0` | Minimum mask size in pixels |

{segment_geospatial-1.3.3 → segment_geospatial-1.4.0}/docs/installation.md

@@ -145,9 +145,9 @@ If CUDA is `False`, check:
 
 ---
 
-### 6) Request access to SAM 3 (Optional)
+### 6) Request access to SAM 3 and SAM 3.1 (Optional)
 
-To use SAM 3, you will need to request access by filling out this form on Hugging Face at <https://huggingface.co/facebook/sam3>. Once your request has been approved, run the following command in the terminal to authenticate:
+To use SAM 3, you will need to request access by filling out this form on Hugging Face at <https://huggingface.co/facebook/sam3>. To use SAM 3.1, request access at <https://huggingface.co/facebook/sam3.1>. Once your request has been approved, run the following command in the terminal to authenticate:
 
 ```bash
 pixi run hf auth login
@@ -159,7 +159,17 @@ After authentication, you can download the SAM 3 model from Hugging Face:
 pixi run hf download facebook/sam3
 ```
 
-**Important Note**: SAM 3 currently requires an NVIDIA GPU with CUDA support. You won't be able to use SAM 3 if you have a CPU only system ([source](https://github.com/facebookresearch/sam3/issues/164)). You will get an error message like this: `Failed to load model: Torch not compiled with CUDA enabled`.
+For SAM 3.1:
+
+```bash
+pixi run hf download facebook/sam3.1
+```
+
+When `segment-geospatial` is installed with a released `sam3` package whose
+checkpoint helper only downloads `facebook/sam3`, SAM 3.1 still downloads
+`facebook/sam3.1` directly through Hugging Face Hub.
+
+**Important Note**: SAM 3 and SAM 3.1 currently require an NVIDIA GPU with CUDA support. You won't be able to use them if you have a CPU only system ([source](https://github.com/facebookresearch/sam3/issues/164)). You will get an error message like this: `Failed to load model: Torch not compiled with CUDA enabled`.
 
 ---
 

{segment_geospatial-1.3.3 → segment_geospatial-1.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "segment-geospatial"
-version = "1.3.3"
+version = "1.4.0"
 dynamic = [
     "dependencies",
 ]
@@ -69,7 +69,7 @@ samgeo2 = [
 ]
 samgeo3 = [
     "segment_geospatial[core]",
-    "sam3",
+    "sam3>=0.1.4",
     "scikit-learn",
     "scikit-image",
     "transformers",
@@ -117,7 +117,7 @@ dependencies = {file = ["requirements.txt"]}
 universal = true
 
 [tool.bumpversion]
-current_version = "1.3.3"
+current_version = "1.4.0"
 commit = true
 tag = true
 

{segment_geospatial-1.3.3 → segment_geospatial-1.4.0}/qgis-samgeo-plugin/metadata.txt

@@ -2,7 +2,7 @@
 name=SamGeo
 qgisMinimumVersion=3.22
 description=Segment remote sensing images using SAM (Segment Anything Model) with text, point, and box prompts.
-version=1.0.0
+version=1.4.0
 author=Qiusheng Wu
 email=giswqs@gmail.com
 about=A QGIS plugin for remote sensing image segmentation powered by Meta's Segment Anything Model (SAM).

{segment_geospatial-1.3.3 → segment_geospatial-1.4.0}/samgeo/__init__.py

@@ -2,7 +2,7 @@
 
 __author__ = """Qiusheng Wu"""
 __email__ = "giswqs@gmail.com"
-__version__ = "1.3.3"
+__version__ = "1.4.0"
 
 
 from .samgeo import *  # noqa: F403

{segment_geospatial-1.3.3 → segment_geospatial-1.4.0}/samgeo/api.py

@@ -35,6 +35,7 @@ from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import FileResponse, JSONResponse
 
 from samgeo import __version__
+from samgeo.model_registry import AVAILABLE_MODELS, DEFAULT_MODEL_IDS, EXTRAS_MAP
 
 logger = logging.getLogger("uvicorn.error")
 
@@ -77,30 +78,10 @@ _model_cache_lock = threading.Lock()
 # When the same image is sent again, we skip the expensive set_image() call.
 _image_hash_cache: dict = {}
 
-# Default model IDs per version
-_DEFAULT_MODEL_IDS = {
-    "sam": "vit_h",
-    "sam2": "sam2-hiera-large",
-    "sam3": "facebook/sam3",
-}
-
-_AVAILABLE_MODELS = {
-    "sam": ["vit_h", "vit_l", "vit_b"],
-    "sam2": [
-        "sam2-hiera-tiny",
-        "sam2-hiera-small",
-        "sam2-hiera-base-plus",
-        "sam2-hiera-large",
-    ],
-    "sam3": ["facebook/sam3"],
-}
-
-# Maps model_version to the correct pip extra name
-_EXTRAS_MAP = {
-    "sam": "samgeo",
-    "sam2": "samgeo2",
-    "sam3": "samgeo3",
-}
+# Backward-compatible aliases for code that imported these private constants.
+_DEFAULT_MODEL_IDS = DEFAULT_MODEL_IDS
+_AVAILABLE_MODELS = AVAILABLE_MODELS
+_EXTRAS_MAP = EXTRAS_MAP
 
 
 def _freeze_kwargs(kwargs: dict):
@@ -147,19 +128,19 @@ def get_model(model_version: str, model_id: Optional[str] = None, **kwargs):
         HTTPException: If model_version or model_id is invalid, or
             dependencies are missing.
     """
-    if model_version not in _DEFAULT_MODEL_IDS:
+    if model_version not in DEFAULT_MODEL_IDS:
         raise HTTPException(
             status_code=400,
             detail=(
                 f"Invalid model_version '{model_version}'. "
-                f"Must be one of: {list(_DEFAULT_MODEL_IDS.keys())}"
+                f"Must be one of: {list(DEFAULT_MODEL_IDS.keys())}"
             ),
         )
 
     if not model_id:
-        model_id = _DEFAULT_MODEL_IDS[model_version]
+        model_id = DEFAULT_MODEL_IDS[model_version]
 
-    valid_ids = _AVAILABLE_MODELS[model_version]
+    valid_ids = AVAILABLE_MODELS[model_version]
     if model_id not in valid_ids:
         raise HTTPException(
             status_code=400,
@@ -185,7 +166,7 @@ def get_model(model_version: str, model_id: Optional[str] = None, **kwargs):
             return model, lock, key
 
         logger.info("Loading model %s", key)
-        extra = _EXTRAS_MAP.get(model_version, model_version)
+        extra = EXTRAS_MAP.get(model_version, model_version)
         try:
             if model_version == "sam":
                 from samgeo.samgeo import SamGeo
@@ -199,7 +180,16 @@ def get_model(model_version: str, model_id: Optional[str] = None, **kwargs):
                 from samgeo.samgeo3 import SamGeo3
 
                 kwargs.setdefault("enable_inst_interactivity", True)
-                model = SamGeo3(**kwargs)
+                model = SamGeo3(model_id=model_id, **kwargs)
+        except ValueError as e:
+            msg = str(e)
+            is_user_config_error = model_version == "sam3" and (
+                msg.startswith("Invalid backend")
+                or "only supported with backend='meta'" in msg
+            )
+            if is_user_config_error:
+                raise HTTPException(status_code=400, detail=msg) from e
+            raise
         except ImportError as e:
             raise HTTPException(
                 status_code=503,
@@ -570,7 +560,7 @@ def health():
 def list_models():
     """List available and currently loaded models."""
     loaded = [list(key) for key in _model_cache]
-    return {"models": _AVAILABLE_MODELS, "loaded": loaded}
+    return {"models": AVAILABLE_MODELS, "loaded": loaded}
 
 
 @app.delete("/models")

segment_geospatial-1.4.0/samgeo/model_registry.py

@@ -0,0 +1,28 @@
+"""Shared model identifiers used across samgeo entry points."""
+
+SAM3_MODEL_ID = "facebook/sam3"
+SAM31_MODEL_ID = "facebook/sam3.1"
+SAM3_MODEL_IDS = (SAM3_MODEL_ID, SAM31_MODEL_ID)
+
+DEFAULT_MODEL_IDS = {
+    "sam": "vit_h",
+    "sam2": "sam2-hiera-large",
+    "sam3": SAM3_MODEL_ID,
+}
+
+AVAILABLE_MODELS = {
+    "sam": ["vit_h", "vit_l", "vit_b"],
+    "sam2": [
+        "sam2-hiera-tiny",
+        "sam2-hiera-small",
+        "sam2-hiera-base-plus",
+        "sam2-hiera-large",
+    ],
+    "sam3": list(SAM3_MODEL_IDS),
+}
+
+EXTRAS_MAP = {
+    "sam": "samgeo",
+    "sam2": "samgeo2",
+    "sam3": "samgeo3",
+}

{segment_geospatial-1.3.3 → segment_geospatial-1.4.0}/samgeo/samgeo3.py

@@ -3,6 +3,7 @@ https://github.com/facebookresearch/sam3
 """
 
 import glob
+import inspect
 import os
 from typing import Any, Dict, List, Optional, Tuple, Union
 
@@ -13,8 +14,15 @@ from tqdm import tqdm
 
 
 SAM3_META_IMPORT_ERROR = None
+download_ckpt_from_hf = None
 try:
     from sam3.model_builder import build_sam3_image_model, build_sam3_video_predictor
+
+    try:
+        from sam3.model_builder import download_ckpt_from_hf
+    except ImportError:
+        download_ckpt_from_hf = None
+
     from sam3.model.sam3_image_processor import Sam3Processor as MetaSam3Processor
     from sam3.visualization_utils import load_frame
 
@@ -43,6 +51,7 @@ except ImportError as e:
     print(f"To use SamGeo 3, install it as:\n\tpip install segment-geospatial[samgeo3]")
 
 from samgeo import common
+from samgeo.model_registry import DEFAULT_MODEL_IDS, SAM31_MODEL_ID
 from .common import show_image
 
 try:
@@ -53,13 +62,37 @@ except ImportError:
     pass
 
 
+SAM31_CKPT_NAME = "sam3.1_multiplex.pt"
+SAM31_CONFIG_NAME = "config.json"
+
+
+def _download_sam31_checkpoint():
+    """Download the SAM 3.1 checkpoint with released and source sam3 builds."""
+    if download_ckpt_from_hf is not None:
+        signature = inspect.signature(download_ckpt_from_hf)
+        if "version" in signature.parameters:
+            return download_ckpt_from_hf(version="sam3.1")
+
+    try:
+        from huggingface_hub import hf_hub_download
+    except ImportError as e:
+        raise ImportError(
+            "SAM 3.1 requires either a sam3 package whose "
+            "download_ckpt_from_hf supports version='sam3.1' or "
+            "huggingface_hub to download facebook/sam3.1 directly."
+        ) from e
+
+    _ = hf_hub_download(repo_id=SAM31_MODEL_ID, filename=SAM31_CONFIG_NAME)
+    return hf_hub_download(repo_id=SAM31_MODEL_ID, filename=SAM31_CKPT_NAME)
+
+
 class SamGeo3:
     """The main class for segmenting geospatial data with the Segment Anything Model 3 (SAM3)."""
 
     def __init__(
         self,
         backend="meta",
-        model_id="facebook/sam3",
+        model_id=DEFAULT_MODEL_IDS["sam3"],
         bpe_path=None,
         device=None,
         eval_mode=True,
@@ -78,8 +111,10 @@ class SamGeo3:
 
         Args:
             backend (str): Backend to use ('meta' or 'transformers'). Default is 'meta'.
-            model_id (str): Model ID for Transformers backend (e.g., 'facebook/sam3').
-                Only used when backend='transformers'.
+            model_id (str): Model ID to use. Official values include
+                'facebook/sam3' and 'facebook/sam3.1'. The Meta backend uses
+                'facebook/sam3.1' to select the SAM 3.1 Hugging Face checkpoint
+                when load_from_HF=True and checkpoint_path is not provided.
             bpe_path (str, optional): Path to the BPE tokenizer vocabulary (Meta backend only).
             device (str, optional): Device to load the model on ('cuda' or 'cpu').
             eval_mode (bool, optional): Whether to set the model to evaluation mode (Meta backend only).
@@ -117,6 +152,13 @@ class SamGeo3:
                 f"Invalid backend '{backend}'. Choose 'meta' or 'transformers'."
             )
 
+        if backend == "transformers" and model_id == SAM31_MODEL_ID:
+            raise ValueError(
+                "facebook/sam3.1 is a checkpoint repository and is only "
+                "supported with backend='meta'. Use model_id='facebook/sam3' "
+                "for the Transformers backend."
+            )
+
         if backend == "meta" and not SAM3_META_AVAILABLE:
             error_msg = (
                 "Meta SAM3 is not available. Please install it as:\n"
@@ -152,6 +194,7 @@ class SamGeo3:
         # Initialize backend-specific components
         if backend == "meta":
             self._init_meta_backend(
+                model_id=model_id,
                 bpe_path=bpe_path,
                 device=device,
                 eval_mode=eval_mode,
@@ -191,6 +234,7 @@ class SamGeo3:
 
     def _init_meta_backend(
         self,
+        model_id,
         bpe_path,
         device,
         eval_mode,
@@ -223,6 +267,14 @@ class SamGeo3:
                 raise ValueError(f"Checkpoint path {checkpoint_path} does not exist.")
             load_from_HF = False
 
+        if (
+            load_from_HF
+            and checkpoint_path is None
+            and model_id == SAM31_MODEL_ID
+        ):
+            checkpoint_path = _download_sam31_checkpoint()
+            load_from_HF = False
+
         model = build_sam3_image_model(
             bpe_path=bpe_path,
             device=device,

{segment_geospatial-1.3.3 → segment_geospatial-1.4.0}/segment_geospatial.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: segment-geospatial
-Version: 1.3.3
+Version: 1.4.0
 Summary: Meta AI's Segment Anything Model (SAM) for Geospatial Data.
 Author-email: Qiusheng Wu <giswqs@gmail.com>
 License: MIT license
@@ -71,7 +71,7 @@ Requires-Dist: scikit-image; extra == "samgeo2"
 Requires-Dist: scipy; extra == "samgeo2"
 Provides-Extra: samgeo3
 Requires-Dist: segment_geospatial[core]; extra == "samgeo3"
-Requires-Dist: sam3; extra == "samgeo3"
+Requires-Dist: sam3>=0.1.4; extra == "samgeo3"
 Requires-Dist: scikit-learn; extra == "samgeo3"
 Requires-Dist: scikit-image; extra == "samgeo3"
 Requires-Dist: transformers; extra == "samgeo3"

{segment_geospatial-1.3.3 → segment_geospatial-1.4.0}/segment_geospatial.egg-info/SOURCES.txt

@@ -136,6 +136,7 @@ samgeo/detectree2.py
 samgeo/fast_sam.py
 samgeo/fer.py
 samgeo/hq_sam.py
+samgeo/model_registry.py
 samgeo/samgeo.py
 samgeo/samgeo2.py
 samgeo/samgeo3.py
@@ -151,4 +152,7 @@ segment_geospatial.egg-info/top_level.txt
 tests/__init__.py
 tests/test_api.py
 tests/test_common.py
-tests/test_samgeo.py
+tests/test_model_registry.py
+tests/test_samgeo.py
+tests/test_samgeo3.py
+tests/test_utmconv.py

{segment_geospatial-1.3.3 → segment_geospatial-1.4.0}/segment_geospatial.egg-info/requires.txt

@@ -76,7 +76,7 @@ scipy
 
 [samgeo3]
 segment_geospatial[core]
-sam3
+sam3>=0.1.4
 scikit-learn
 scikit-image
 transformers

{segment_geospatial-1.3.3 → segment_geospatial-1.4.0}/tests/test_api.py

@@ -55,9 +55,19 @@ def test_list_models():
     assert "sam" in data["models"]
     assert "sam2" in data["models"]
     assert "sam3" in data["models"]
+    assert "facebook/sam3.1" in data["models"]["sam3"]
     assert data["loaded"] == []
 
 
+def test_private_model_constant_aliases_remain_available():
+    """Legacy private constants still point to the shared registry values."""
+    from samgeo import api
+
+    assert api._DEFAULT_MODEL_IDS is api.DEFAULT_MODEL_IDS
+    assert api._AVAILABLE_MODELS is api.AVAILABLE_MODELS
+    assert api._EXTRAS_MAP is api.EXTRAS_MAP
+
+
 def test_clear_models():
     """Test clearing the model cache."""
     response = client.delete("/models")
@@ -190,7 +200,7 @@ def test_get_model_caches_automatic_and_predict_separately():
     ``'SamGeo2' object has no attribute 'predictor'``. The cache key now
     includes the ``automatic`` flag so the two are distinct instances.
     """
-    import samgeo.api as api
+    from samgeo import api
 
     with patch("samgeo.samgeo2.SamGeo2") as mock_cls:
         mock_cls.side_effect = lambda **kw: MagicMock()
@@ -217,7 +227,7 @@ def test_get_model_caches_distinct_configs_separately():
     request with a different ``points_per_side``) silently reused the first,
     differently-configured instance. The key now folds in the kwargs.
     """
-    import samgeo.api as api
+    from samgeo import api
 
     # SAM3: two text requests differing only by confidence_threshold.
     with patch("samgeo.samgeo3.SamGeo3") as mock_sam3:
@@ -238,6 +248,54 @@ def test_get_model_caches_distinct_configs_separately():
     assert s_a is not s_b
 
 
+def test_get_model_accepts_sam31_model_id():
+    """SAM 3.1 is a supported SAM3 model id and keeps its own cache key."""
+    from samgeo import api
+
+    with patch("samgeo.samgeo3.SamGeo3") as mock_sam3:
+        mock_sam3.side_effect = lambda **kw: MagicMock()
+        sam3_model, _, sam3_key = api.get_model("sam3", "facebook/sam3")
+        sam31_model, _, sam31_key = api.get_model("sam3", "facebook/sam3.1")
+        sam31_again, _, _ = api.get_model("sam3", "facebook/sam3.1")
+
+    assert sam3_key != sam31_key
+    assert sam3_model is not sam31_model
+    assert sam31_again is sam31_model
+    mock_sam3.assert_any_call(
+        model_id="facebook/sam3",
+        enable_inst_interactivity=True,
+    )
+    mock_sam3.assert_any_call(
+        model_id="facebook/sam3.1",
+        enable_inst_interactivity=True,
+    )
+
+
+def test_get_model_returns_400_for_invalid_constructor_config():
+    """Invalid model/backend config should be reported as a user error."""
+    from samgeo import api
+
+    with patch("samgeo.samgeo3.SamGeo3") as mock_sam3:
+        mock_sam3.side_effect = ValueError(
+            "facebook/sam3.1 is only supported with backend='meta'"
+        )
+        with pytest.raises(api.HTTPException) as excinfo:
+            api.get_model("sam3", "facebook/sam3.1", backend="transformers")
+
+    assert excinfo.value.status_code == 400
+    assert "backend='meta'" in excinfo.value.detail
+
+
+def test_get_model_does_not_hide_unexpected_constructor_value_errors():
+    """Unexpected constructor ValueErrors should not be reported as bad input."""
+    from samgeo import api
+
+    with patch("samgeo.samgeo3.SamGeo3") as mock_sam3:
+        mock_sam3.side_effect = ValueError("unexpected runtime failure")
+        with pytest.raises(ValueError, match="unexpected runtime failure"):
+            api.get_model("sam3", "facebook/sam3.1", backend="meta")
+
+
 def test_freeze_kwargs_is_order_independent():
     """_freeze_kwargs yields the same hashable key regardless of arg order."""
     from samgeo.api import _freeze_kwargs

segment_geospatial-1.4.0/tests/test_model_registry.py

@@ -0,0 +1,39 @@
+"""Tests for shared model registry constants."""
+
+import importlib.util
+from pathlib import Path
+
+
+def _load_model_registry():
+    module_path = Path(__file__).resolve().parents[1] / "samgeo" / "model_registry.py"
+    spec = importlib.util.spec_from_file_location("model_registry", module_path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+model_registry = _load_model_registry()
+
+
+def test_default_model_ids_are_available_models():
+    """Every default model id should be listed as available."""
+    for model_version, model_id in model_registry.DEFAULT_MODEL_IDS.items():
+        assert model_id in model_registry.AVAILABLE_MODELS[model_version]
+
+
+def test_registry_keys_stay_in_sync():
+    """Shared registry sections should describe the same model versions."""
+    assert set(model_registry.DEFAULT_MODEL_IDS) == set(model_registry.AVAILABLE_MODELS)
+    assert set(model_registry.DEFAULT_MODEL_IDS) == set(model_registry.EXTRAS_MAP)
+
+
+def test_sam31_is_registered_as_a_sam3_model():
+    """SAM 3.1 is exposed as a SAM3-compatible model id."""
+    assert model_registry.SAM3_MODEL_ID == "facebook/sam3"
+    assert model_registry.SAM31_MODEL_ID == "facebook/sam3.1"
+    assert model_registry.SAM3_MODEL_ID in model_registry.SAM3_MODEL_IDS
+    assert model_registry.SAM31_MODEL_ID in model_registry.SAM3_MODEL_IDS
+    assert (
+        list(model_registry.SAM3_MODEL_IDS)
+        == model_registry.AVAILABLE_MODELS["sam3"]
+    )