RPC Rework: Part 6: add _connect_module_refs

[jeff-hykin]

I'll fix the test in just a bit

[greptile-apps]

Greptile Overview

Greptile Summary

This PR implements Part 6 of the RPC rework, introducing a module reference system that enables Protocol/Spec-based dependency injection for inter-module RPC communication.

Key Changes

• Module Reference System: Added ModuleRef and Spec protocol to allow modules to declare dependencies on other modules via interface specifications rather than concrete types
• Blueprint Refactoring: Renamed ModuleBlueprintSet → Blueprint, ModuleBlueprint → _BlueprintAtom, ModuleConnection → StreamRef, and create_module_blueprint → Blueprint.create
• Spec Compliance Checking: New dimos/spec/utils.py with structural and annotation compliance validation for protocol matching
• _connect_module_refs Method: Core logic in blueprints.py:295-375 that matches module references to available modules using spec compliance checks, with support for remapping ambiguous cases
• Type Safety Improvements: Added ModuleProxy type hint class for better IDE support and type annotations across module coordinator and RPC client

Issues Found

• Critical Logic Bug (line 300): issubclass(replacement, Module) will raise TypeError if replacement is not a class type
• Unreachable Code (lines 352-358): The condition len(valid_module_candidates) == 0 is already handled by lines 337-345, making lines 352-358 unreachable

Testing

Comprehensive test coverage added including Spec validation tests, module reference resolution tests, and ambiguity handling tests

Confidence Score: 2/5

• This PR has critical logic bugs that will cause runtime errors
• Score reflects two critical logic bugs in _connect_module_refs: a TypeError risk from unchecked issubclass call and unreachable error handling code. While the feature is well-tested and the refactoring is clean, these bugs need fixing before merge
• dimos/core/blueprints.py requires immediate attention for logic bugs at lines 300 and 337-364

Important Files Changed

Filename	Overview
dimos/core/blueprints.py	Added module reference system with Spec-based dependency injection; contains critical logic bugs in conditional branches
dimos/core/module.py	Added set_module_ref RPC method and updated blueprint property to use Blueprint.create
dimos/core/rpc_client.py	Added ModuleProxy type hint class for better IDE support when interacting with remote modules
dimos/spec/utils.py	New file with Spec protocol and compliance checking functions for structural and annotation validation
dimos/core/test_blueprints.py	Updated tests for renamed classes and added comprehensive module reference/RPC tests with Spec protocol

Sequence Diagram

sequenceDiagram
    participant User
    participant Blueprint
    participant ModuleCoordinator
    participant RPCClient
    participant Module1
    participant Module2

    User->>Blueprint: autoconnect(Module1.blueprint(), Module2.blueprint())
    Blueprint->>Blueprint: _BlueprintAtom.create() - extract StreamRefs & ModuleRefs
    User->>Blueprint: .build()
    
    Blueprint->>Blueprint: _check_requirements()
    Blueprint->>Blueprint: _verify_no_name_conflicts()
    Blueprint->>Blueprint: _start_rerun()
    
    Blueprint->>ModuleCoordinator: start()
    Blueprint->>ModuleCoordinator: _deploy_all_modules()
    ModuleCoordinator->>RPCClient: deploy(Module1)
    RPCClient-->>ModuleCoordinator: ModuleProxy(Module1)
    ModuleCoordinator->>RPCClient: deploy(Module2)
    RPCClient-->>ModuleCoordinator: ModuleProxy(Module2)
    
    Blueprint->>Blueprint: _connect_transports()
    Note over Blueprint: Match StreamRefs by name+type<br/>Handle remappings<br/>Set transports on proxies
    
    Blueprint->>Blueprint: _connect_rpc_methods()
    Note over Blueprint: Register RPC methods<br/>Handle interface methods<br/>Set method references
    
    Blueprint->>Blueprint: _connect_module_refs()
    Note over Blueprint: Match ModuleRefs to Spec<br/>Structural compliance check<br/>Annotation compliance check
    
    alt Spec match found
        Blueprint->>RPCClient: setattr(proxy1, "module_ref", proxy2)
        Blueprint->>Module1: set_module_ref("module_ref", proxy2)
    else Ambiguous or missing
        Blueprint-->>User: Exception with remapping suggestion
    end
    
    Blueprint->>ModuleCoordinator: start_all_modules()
    ModuleCoordinator->>Module1: start()
    Module1->>Module2: RPC call via module_ref
    Module2-->>Module1: RPC response

Loading

[greptile-apps]

_{2 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}