feat(perception): look out loop

[paul-nechifor]

Problem

We need a skill that can scan for something continuously.

Closes DIM-634

Solution

• Added a skill which uses Qwen/Moondream VL models to look out for something in a loop.
• Analyzing the least blurry image in a time window.
• Added ability to disable a module (it's useful to disable spatial-memory to save on VRAM).

Breaking Changes

None

How to Test

MuJoCo test ("lookout for a person (any person) and when you see him, follow him")

uv run pytest -svm mujoco dimos/e2e_tests/test_scan_and_follow_person.py

Contributor License Agreement

• I have read and approved the CLA.

[greptile-apps]

Greptile Summary

This PR introduces a look-out loop perception skill (PerceiveLoopSkill) that enables an agent to continuously monitor the camera feed for specified objects using a configurable VL model, notify the agent upon detection, and then automatically stop. Supporting changes include a create_vl_model factory with lazy imports, a disabled_modules API on Blueprint for selectively excluding modules at build time, a corresponding --disable CLI flag for the run command, and a new unitree-go2-spatial blueprint that wires PerceiveLoopSkill in alongside the existing spatial memory module.

Key changes and issues found:

• perceive_loop_skill.py — lock held during VL inference (logic): Both query_detections and query are called inside with self._lock, meaning these multi-second inference calls block every other lock-protected operation (including stop_looking_out and look_out_for on the agent thread) for their full duration.
• perceive_loop_skill.py — TOCTOU in stop_looking_out (logic): The lock is released between capturing active_lookout_str and calling _stop_lookout(), creating a window where a concurrent image callback can clear the lookout (or a new look_out_for can start), causing _stop_lookout() to either cancel the wrong lookout or report incorrect feedback to the agent.
• pyproject.toml — duplicate types-psutil (logic): The PR adds a second types-psutil specifier without removing the existing one, resulting in two conflicting entries in both pyproject.toml and uv.lock.
• dimos/robot/cli/dimos.py — implicit single-atom assumption (style): The --disable implementation accesses blueprints[0].module with no guard, which is correct for today's single-atom all_modules entries but silently misbehaves for any future multi-atom module blueprint.
• The Blueprint.disabled_modules refactor is clean and well-tested. The create_vl_model lazy-import factory is a solid design, though it still lacks an explicit match fallback (flagged in a prior review).

Confidence Score: 2/5

• Not safe to merge without addressing the lock-during-inference and TOCTOU issues in PerceiveLoopSkill, as they introduce real liveness and correctness bugs in the core new feature.
• The two bugs in perceive_loop_skill.py are in the hot path of the new feature: holding the RLock across slow model inference blocks the agent from cancelling a lookout in a timely manner, and the TOCTOU in stop_looking_out can cause incorrect lookout cancellation. The duplicate dependency is a packaging correctness issue. The surrounding blueprint and CLI work is well-structured.
• dimos/perception/perceive_loop_skill.py requires the most attention — both the lock-scope and the TOCTOU race need to be resolved before this is production-safe. pyproject.toml needs the old types-psutil entry removed.

Important Files Changed

Filename	Overview
dimos/perception/perceive_loop_skill.py	New core module introducing the look-out loop skill. Has two meaningful logic bugs: (1) VL model inference is performed while holding the RLock, blocking stop_looking_out/look_out_for for the full inference duration; (2) TOCTOU race in stop_looking_out between the lock release and the _stop_lookout() call.
dimos/core/blueprints.py	Adds disabled_modules feature to Blueprint dataclass. Refactors all builder methods to use dataclasses.replace instead of manual reconstruction. Clean change; _active_blueprints as a cached_property on a frozen dataclass follows the pre-existing pattern in this file.
dimos/models/vl/create_vl_model.py	New factory module for VL model creation with lazy imports. Annotated return type is VlModel but the match block has no fallback case, so an unexpected name value would implicitly return None, violating the type contract.
dimos/robot/cli/dimos.py	Adds --disable CLI option for disabling modules by name. Logic is correct for single-atom blueprints; silently only disables the first atom for any multi-atom blueprint (currently theoretical).
pyproject.toml	Adds types-psutil>=7.2.2.20260130,<8 to dev deps without removing the pre-existing >=7.0.0.20251001,<8 entry, resulting in two conflicting specifiers for the same package in both pyproject.toml and uv.lock.
dimos/core/test_blueprints.py	Adds two new tests for the disabled_modules feature: one verifying that disabled modules are skipped at build time, another verifying that autoconnect correctly merges disabled_modules_tuple. Tests look correct.
dimos/e2e_tests/conftest.py	Moves the start_person_track fixture from test_person_follow.py into the shared conftest.py so it can be reused by the new test_scan_and_follow_person.py test. Logic is unchanged.
dimos/e2e_tests/test_scan_and_follow_person.py	New end-to-end test for the scan-and-follow-person flow. Correctly uses the shared fixtures. Test body is straightforward.

Sequence Diagram

sequenceDiagram
    participant Agent
    participant PerceiveLoopSkill
    participant ImageStream
    participant VlModel

    Agent->>PerceiveLoopSkill: look_out_for(["person"])
    activate PerceiveLoopSkill
    PerceiveLoopSkill->>VlModel: start()
    PerceiveLoopSkill->>ImageStream: subscribe(sharpness_window)
    PerceiveLoopSkill-->>Agent: "Started looking for ["person"]..."
    deactivate PerceiveLoopSkill

    loop Every ~2s (sharpness window)
        ImageStream->>PerceiveLoopSkill: _on_image(frame)
        activate PerceiveLoopSkill
        Note over PerceiveLoopSkill: Acquires _lock
        PerceiveLoopSkill->>VlModel: query_detections(image, active_lookout_str)
        VlModel-->>PerceiveLoopSkill: detections (empty → return)
        Note over PerceiveLoopSkill: Releases _lock
        deactivate PerceiveLoopSkill
    end

    ImageStream->>PerceiveLoopSkill: _on_image(frame) [match found]
    activate PerceiveLoopSkill
    Note over PerceiveLoopSkill: Acquires _lock (held for entire block)
    PerceiveLoopSkill->>VlModel: query_detections(image, active_lookout_str)
    VlModel-->>PerceiveLoopSkill: detections [non-empty]
    PerceiveLoopSkill->>PerceiveLoopSkill: dispose subscription, clear _active_lookout
    PerceiveLoopSkill->>VlModel: query(image, describe_prompt)
    VlModel-->>PerceiveLoopSkill: description
    PerceiveLoopSkill->>VlModel: stop()
    Note over PerceiveLoopSkill: Releases _lock
    PerceiveLoopSkill->>Agent: add_message("Found a match for ('person',)...")
    deactivate PerceiveLoopSkill

    Agent->>PerceiveLoopSkill: stop_looking_out()
    activate PerceiveLoopSkill
    Note over PerceiveLoopSkill: Acquires _lock → reads active_lookout_str → releases _lock
    PerceiveLoopSkill->>PerceiveLoopSkill: _stop_lookout() [re-acquires _lock]
    PerceiveLoopSkill-->>Agent: "Stopped looking out for..."
    deactivate PerceiveLoopSkill

Loading

_{Last reviewed commit: 32fbd6b}

Comments Outside Diff (1)

1. undefined, line undefined (link)

   Duplicate types-psutil dependency entry

   This line adds a second types-psutil entry to the dev dependencies. The original entry types-psutil>=7.0.0.20251001,<8 already existed in pyproject.toml (as confirmed by the uv.lock diff, which now contains both specifiers side-by-side). Having two entries for the same package with overlapping but different lower bounds is at best redundant and at worst can confuse the resolver.

   The old entry should be removed and replaced by this one, not added alongside it. Please delete the pre-existing "types-psutil>=7.0.0.20251001,<8" line.

[leshy]

looks good, small suggestions at Pauls discression