fix(perception): guard EdgeTAM import with actionable error for missing sam2

[spomichter]

Problem

unitree-go2-agentic blueprint crashes on fresh installs with a cryptic Hydra InstantiationException:

InstantiationException: Error locating target 'sam2.sam2_video_predictor.SAM2VideoPredictor'
ModuleNotFoundError: No module named 'sam2'

The sam2 module is provided by the edgetam-dimos package, which lives in the [misc] optional extra. But the agentic blueprint unconditionally instantiates SecurityModule → EdgeTAMProcessor, so any uv sync without --extra misc produces an unactionable crash.

Introduced in: PR #1619 (feat(security): add security demo) which added SecurityModule to the unitree_go2_spatial blueprint without moving edgetam-dimos from misc to core dependencies.

Solution

Add an early try: import sam2 guard in EdgeTAMProcessor.__init__ that raises a clear ImportError with install instructions before Hydra's instantiate() produces an opaque error.

Breaking Changes

None

How to Test

# Without edgetam-dimos installed:
uv sync  # no --extra misc
uv run python -c "from dimos.models.segmentation.edge_tam import EdgeTAMProcessor; EdgeTAMProcessor()"
# Should see: ImportError: EdgeTAM requires the 'edgetam-dimos' package (provides sam2). Install with: uv sync --extra misc

# With edgetam-dimos installed:
uv sync --extra misc
# Behavior unchanged (guard passes, continues to CUDA check etc.)

Contributor License Agreement

• I have read and approved the CLA

[greptile-apps]

Greptile Summary

This PR guards the EdgeTAMProcessor.__init__ against a missing sam2 module (provided by the optional edgetam-dimos extra) by adding an early try/import check that raises an actionable ImportError before Hydra's instantiate() produces an opaque InstantiationException.

• Adds a try: import sam2 guard at the top of __init__ that short-circuits with a clear install hint when the package is absent, replacing a previously unactionable Hydra crash on fresh installs of the unitree-go2-agentic blueprint.
• Uses raise ... from None to suppress the original exception chain and surface only the curated message; the existing TYPE_CHECKING-gated import on line 38 is unaffected at runtime.

Confidence Score: 5/5

This is a safe, minimal guard that fires only when sam2 is absent and is otherwise a no-op on working installs.

The change is a single try/except block added at the very top of init, with no effect on the happy path. The guard correctly surfaces a clear, actionable message before Hydra's opaque instantiation error would otherwise appear. The only open question is whether to preserve the original exception cause, which is a minor style concern.

No files require special attention.

Important Files Changed

Filename	Overview
dimos/models/segmentation/edge_tam.py	Adds an early sam2 import guard in EdgeTAMProcessor.init that raises a clear, actionable ImportError when edgetam-dimos is not installed; rest of the file is unchanged.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[EdgeTAMProcessor.__init__ called] --> B{try: import sam2}
    B -- ImportError --> C[raise ImportError with install hint\nuv sync --extra misc]
    B -- success --> D[Load edgetam.yaml config]
    D --> E{local_config_path.exists?}
    E -- No --> F[raise FileNotFoundError]
    E -- Yes --> G{torch.cuda.is_available?}
    G -- No --> H[raise RuntimeError CUDA required]
    G -- Yes --> I[OmegaConf.load + overrides]
    I --> J[instantiate SAM2VideoPredictor via Hydra]
    J --> K[Patch sam2.sam2_video_predictor.tqdm]
    K --> L[Load checkpoint weights]
    L --> M[Move predictor to CUDA + eval mode]
    M --> N[Init complete]

Loading

_{Reviews (1): Last reviewed commit: "fix(perception): guard EdgeTAM import wi..." | Re-trigger Greptile}

[greptile-apps]

Using from None suppresses the original ImportError's __cause__, so if sam2 is partially installed and raises a more informative sub-error (e.g., a missing native .so), that detail is silently discarded. Keeping the cause chain lets developers distinguish "package not installed at all" from "package installed but broken", without harming the curated message.

Suggested change

	except ImportError:
	raise ImportError(
	"EdgeTAM requires the 'edgetam-dimos' package (provides sam2). "
	"Install with: uv sync --extra misc"
	) from None
	except ImportError as exc:
	raise ImportError(
	"EdgeTAM requires the 'edgetam-dimos' package (provides sam2). "
	"Install with: uv sync --extra misc"
	) from exc

[codecov]

Codecov Report

❌ Patch coverage is 0% with 4 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
dimos/models/segmentation/edge_tam.py	0.00%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!