feat: external blueprint registration

[TomCC7]

Summary

Adds dynamic discovery for externally packaged DimOS blueprints via Python package entry points.

External packages can expose runnable blueprints with:

[project.entry-points."dimos.blueprints"]
go2 = "my_robot_stack.go2:go2_blueprint"

Users can then run them by namespaced name:

dimos run my-robot-stack.go2
dimos run unitree-go2 my-robot-stack.keyboard-teleop

Changes

• Add external blueprint discovery/resolution through importlib.metadata.
• Require external names to use <canonical-distribution-namespace>.<local-kebab-name>.
• Keep bare names reserved for built-in DimOS blueprints/modules.
• Support external entry point targets that are:
  • Blueprint objects
  • DimOS Module classes converted with .blueprint()
• Reject factories and unsupported targets.
• Add metadata-only external blueprint listing in dimos list.
• Add namespace-aware errors for missing namespaces, missing local names, invalid metadata, load failures, ambiguous namespaces, and invalid targets.
• Cover shared resolution paths used by CLI, Python API, and coordinator loading.
• Update user, contributor, and coding-agent docs for built-in vs external blueprint registration.

Testing

• Manual QA with temporary external packages:
  • dimos list
  • dimos run my-test-stack.demo --daemon
  • dimos run demo-mcp-stress-test my-test-stack.demo --daemon
  • broken external entry point load failure

[greptile-apps]

Greptile Summary

This PR adds dynamic discovery of externally packaged DimOS blueprints via Python package entry points (dimos.blueprints group), allowing external packages to register runnable blueprints without modifying the in-repo all_blueprints.py. Resolution, error handling, and listing are cleanly layered across CLI, Python API, and coordinator paths.

• New external_blueprints.py: Implements _collect_external_blueprints(), list_external_blueprint_names(), and resolve_external_blueprint_by_name() using importlib.metadata. Entry points are validated against a kebab-case pattern; invalid and missing-distribution entries are skipped gracefully, and previously-reported issues (misleading error classes, halted discovery on bad packages, spurious ambiguity from all-invalid distributions) are addressed with dedicated tests.
• Updated get_all_blueprints.py: Routes namespaced names (containing .) to the new external resolver, and fixes the sys.exit \u2192 raise typer.Exit(1) inconsistency flagged in a previous review.
• Two unused dependencies added to pyproject.toml: annotation-protocol and lazy_loader are declared as runtime dependencies but are not imported or used anywhere in the codebase, unnecessarily inflating the dependency tree.

Confidence Score: 4/5

Safe to merge after removing the two unused dependencies from pyproject.toml; the external blueprint discovery logic itself is well-tested and correct.

Two packages — annotation-protocol and lazy_loader — are declared as runtime dependencies in pyproject.toml but are not imported or used anywhere in the codebase. Shipping them expands the install footprint, widens the transitive dependency surface, and could introduce unexpected version conflicts for downstream users. The external blueprint discovery and resolution implementation is otherwise clean, all previously-reported issues have been addressed with targeted tests, and the routing logic in get_all_blueprints is straightforward.

pyproject.toml — the annotation-protocol and lazy_loader entries should be removed before merging.

Important Files Changed

Filename	Overview
dimos/robot/external_blueprints.py	New core module implementing external blueprint discovery and resolution via importlib.metadata; gracefully handles invalid names, missing distributions, load errors, and unsupported targets with clear error messages.
pyproject.toml	Adds packaging (used), but also adds annotation-protocol and lazy_loader which are not imported or used anywhere in the codebase — likely accidental inclusions.
dimos/robot/get_all_blueprints.py	Routes namespaced names to the new external resolver; fixes the sys.exit → typer.Exit inconsistency and adds _exit_with_error helper for clean error propagation.
dimos/robot/test_external_blueprints.py	Comprehensive test suite covering valid/invalid names, Blueprint and Module class targets, load failures, missing namespaces, invalid metadata, distribution collisions, and bare-name isolation.
dimos/robot/cli/dimos.py	Updates dimos list to show built-in and external blueprint groups separately; propagates ExternalBlueprintError to the user with exit code 1.
dimos/robot/cli/test_dimos.py	Adds CLI-level tests for grouped list output, empty external section, discovery errors, run error propagation, and unknown bare blueprint handling.
dimos/core/module.py	Upgrades is_module_type signature to use TypeGuard[type[Module]] for proper narrowing; no behavioral change.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant User
    participant CLI as dimos CLI / Porcelain API
    participant Resolver as get_all_blueprints.get_by_name
    participant BuiltIn as all_blueprints / all_modules
    participant External as external_blueprints
    participant Meta as importlib.metadata

    User->>CLI: dimos run my-robot-stack.go2
    CLI->>Resolver: get_by_name("my-robot-stack.go2")
    Resolver->>BuiltIn: name in all_blueprints? No
    Resolver->>BuiltIn: name in all_modules? No
    Resolver->>External: is_namespaced_blueprint_name() True
    Resolver->>External: resolve_external_blueprint_by_name()
    External->>External: validate local name valid
    External->>Meta: "entry_points(group="dimos.blueprints")"
    Meta-->>External: "[EntryPoint(name="go2", dist="my-robot-stack")]"
    External->>External: canonicalize namespace
    External->>External: find matching entry
    External->>External: entry_point.load()
    External->>External: _target_to_blueprint(target)
    External-->>Resolver: Blueprint
    Resolver-->>CLI: Blueprint
    CLI->>User: runs blueprint

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant User
    participant CLI as dimos CLI / Porcelain API
    participant Resolver as get_all_blueprints.get_by_name
    participant BuiltIn as all_blueprints / all_modules
    participant External as external_blueprints
    participant Meta as importlib.metadata

    User->>CLI: dimos run my-robot-stack.go2
    CLI->>Resolver: get_by_name("my-robot-stack.go2")
    Resolver->>BuiltIn: name in all_blueprints? No
    Resolver->>BuiltIn: name in all_modules? No
    Resolver->>External: is_namespaced_blueprint_name() True
    Resolver->>External: resolve_external_blueprint_by_name()
    External->>External: validate local name valid
    External->>Meta: "entry_points(group="dimos.blueprints")"
    Meta-->>External: "[EntryPoint(name="go2", dist="my-robot-stack")]"
    External->>External: canonicalize namespace
    External->>External: find matching entry
    External->>External: entry_point.load()
    External->>External: _target_to_blueprint(target)
    External-->>Resolver: Blueprint
    Resolver-->>CLI: Blueprint
    CLI->>User: runs blueprint

Loading

_{Reviews (9): Last reviewed commit: "Merge remote-tracking branch 'origin/mai..." | Re-trigger Greptile}

[codecov]

❌ 1 Tests Failed:

Tests completed	Failed	Passed	Skipped
2857	1	2856	71

View the full list of 1 ❄️ flaky test(s)

dimos.e2e_tests.test_dimsim_walk_forward::test_walk_forward

Flake rate in main: 19.85% (Passed 105 times, Failed 26 times)

Stack Traces | 203s run time

lcm_spy = <dimos.e2e_tests.lcm_spy.LcmSpy object at 0x72f3b62dd520>
start_blueprint = <function start_blueprint.<locals>.set_name_and_start at 0x72f3b3d3c5e0>
human_input = <function human_input.<locals>.send_human_input at 0x72f3b3d3c4a0>
dim_sim = <dimos.e2e_tests.dim_sim_client.DimSimClient object at 0x72f3b61377d0>

    @pytest.mark.self_hosted_large
    def test_walk_forward(lcm_spy, start_blueprint, human_input, dim_sim) -> None:
        start_blueprint(
            "run",
            "--disable",
            "spatial-memory",
            "--disable",
            "security-module",
            "unitree-go2-agentic",
            simulator="dimsim",
        )
        lcm_spy.save_topic(".../McpClient/on_system_modules/res")
        lcm_spy.wait_for_saved_topic(".../McpClient/on_system_modules/res", timeout=1200.0)
    
        origin_x, origin_y = 1, 2
        dim_sim.set_agent_position(origin_x, origin_y)
    
        human_input("move forward 3 meter")
    
>       lcm_spy.wait_until_odom_position(origin_x + 3, origin_y, threshold=0.4, timeout=120)

dim_sim    = <dimos.e2e_tests.dim_sim_client.DimSimClient object at 0x72f3b61377d0>
human_input = <function human_input.<locals>.send_human_input at 0x72f3b3d3c4a0>
lcm_spy    = <dimos.e2e_tests.lcm_spy.LcmSpy object at 0x72f3b62dd520>
origin_x   = 1
origin_y   = 2
start_blueprint = <function start_blueprint.<locals>.set_name_and_start at 0x72f3b3d3c5e0>

dimos/e2e_tests/test_dimsim_walk_forward.py:37: 
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
dimos/e2e_tests/lcm_spy.py:167: in wait_until_odom_position
    self.wait_for_message_result(
        predicate  = <function LcmSpy.wait_until_odom_position.<locals>.predicate at 0x72f3b66db600>
        self       = <dimos.e2e_tests.lcm_spy.LcmSpy object at 0x72f3b62dd520>
        threshold  = 0.4
        timeout    = 120
        x          = 4
        y          = 2
dimos/e2e_tests/lcm_spy.py:153: in wait_for_message_result
    wait_until(
        event      = <threading.Event at 0x72f3b615c260: unset>
        fail_message = 'Failed to get to position x=4, y=2'
        listener   = <function LcmSpy.wait_for_message_result.<locals>.listener at 0x72f3b3d3c9a0>
        predicate  = <function LcmSpy.wait_until_odom_position.<locals>.predicate at 0x72f3b66db600>
        self       = <dimos.e2e_tests.lcm_spy.LcmSpy object at 0x72f3b62dd520>
        timeout    = 120
        topic      = '/odom#geometry_msgs.PoseStamped'
        type       = <class 'dimos.msgs.geometry_msgs.PoseStamped.PoseStamped'>
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 

predicate = <bound method Event.is_set of <threading.Event at 0x72f3b615c260: unset>>

    def wait_until(
        predicate: Callable[[], bool],
        *,
        timeout: float,
        interval: float = 0.1,
        message: str | None = None,
    ) -> None:
        """Poll ``predicate`` until it returns truthy or ``timeout`` elapses."""
        deadline = time.monotonic() + timeout
        while time.monotonic() < deadline:
            if predicate():
                return
            time.sleep(interval)
>       raise TimeoutError(message or f"Timed out after {timeout}s waiting for condition")
E       TimeoutError: Failed to get to position x=4, y=2

deadline   = 219390.386463015
interval   = 0.1
message    = 'Failed to get to position x=4, y=2'
predicate  = <bound method Event.is_set of <threading.Event at 0x72f3b615c260: unset>>
timeout    = 120

.../utils/testing/waiting.py:35: TimeoutError

To view more test analytics, go to the Test Analytics Dashboard
_{📋 Got 3 mins? Take this short survey to help us improve Test Analytics.}

[github-actions]

This pull request has been automatically marked as stale because it has not had recent activity. It will be closed in 7 days if no further activity occurs.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
dimensional	🟢 Ready	View Preview	Jul 11, 2026, 5:57 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.