RPC Rework: Part 4: Create ModuleRef

[jeff-hykin]

No description provided.

[greptile-apps]

Greptile Overview

Greptile Summary

This PR implements Part 4 of the RPC Rework by introducing ModuleRef to track RPC method references between modules. The changes include:

• Major refactoring: Renamed ModuleBlueprintSet → Blueprint, ModuleBlueprint → _BlueprintAtom, ModuleConnection → StreamRef
• New ModuleRef class: Tracks module references with their RPC method names, supporting two patterns:
  • Spec protocol annotations (using new is_spec() and get_protocol_method_signatures() utilities)
  • Direct Module instance references (checking class attributes)
• New dimos/spec/utils.py: Utilities for Spec protocol handling including structural/annotation compliance checking
• Comprehensive updates: All references updated across tests, documentation, introspection, and visualization modules
• New dependency: annotation-protocol>=1.4.0 for strict annotation checking

The refactoring improves naming clarity (Blueprint is more intuitive than ModuleBlueprintSet) and extends the blueprint system to capture RPC method relationships, enabling better module composition and validation.

Confidence Score: 4/5

• Safe to merge with minor consideration for unused code path
• Well-structured refactoring with comprehensive test coverage and documentation updates. The ModuleRef feature is properly implemented with two detection mechanisms (Spec protocols and Module instances). One code path (Module instance detection on line 93) appears unused in practice but doesn't break anything. All tests pass and the changes are backward compatible through proper renaming.
• dimos/core/blueprints.py warrants attention for the potentially unused Module instance check pattern

Important Files Changed

Filename	Overview
dimos/core/blueprints.py	Major refactoring: renamed ModuleBlueprintSet to Blueprint, ModuleBlueprint to _BlueprintAtom, ModuleConnection to StreamRef, and added ModuleRef for RPC method tracking
dimos/spec/utils.py	New utility file for Spec protocol handling with is_spec, structural/annotation compliance checks, and method signature extraction
dimos/spec/test_utils.py	Comprehensive tests for Spec protocol utilities covering is_spec, structural compliance, and annotation compliance
dimos/core/module.py	Updated blueprint property to use Blueprint.create instead of create_module_blueprint
dimos/core/test_blueprints.py	Updated tests to use renamed classes (Blueprint, _BlueprintAtom, StreamRef) and added module_refs field to assertions

Sequence Diagram

sequenceDiagram
    participant User
    participant Module as Module Class
    participant Blueprint as Blueprint.create()
    participant Atom as _BlueprintAtom.create()
    participant SpecUtils as spec/utils
    participant ModuleRef as ModuleRef

    User->>Module: Call Module.blueprint(*args, **kwargs)
    Module->>Blueprint: Blueprint.create(Module, args, kwargs)
    Blueprint->>Atom: _BlueprintAtom.create(Module, args, kwargs)
    
    Note over Atom: Iterate through module annotations
    
    Atom->>Atom: Check if annotation is In/Out
    alt Stream annotation (In/Out)
        Atom->>Atom: Create StreamRef(name, type, direction)
    else Spec Protocol annotation
        Atom->>SpecUtils: is_spec(annotation)
        SpecUtils-->>Atom: True
        Atom->>SpecUtils: get_protocol_method_signatures(annotation)
        SpecUtils-->>Atom: Return method signatures
        Atom->>ModuleRef: Create ModuleRef(name, rpc_method_names)
    else Module instance annotation
        Atom->>Atom: Check isinstance(getattr(module, name), Module)
        Atom->>ModuleRef: Create ModuleRef(name, other_module.rpc_calls)
    end
    
    Atom-->>Blueprint: Return _BlueprintAtom(module, connections, module_refs, args, kwargs)
    Blueprint-->>Module: Return Blueprint(blueprints=(atom,))
    Module-->>User: Return Blueprint

Loading

[greptile-apps]

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Consider if this Module instance check pattern is needed - no examples exist in the codebase where Module instances are used as class attributes.

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}