RPC Rework: Part 3: Define Spec and Spec tooling

[jeff-hykin]

No description provided.

[greptile-apps]

Greptile Overview

Greptile Summary

This PR introduces new Spec tooling and performs a comprehensive rename of the blueprint API. The changes establish a foundation for Module-Spec Protocol validation while cleaning up the naming conventions.

Key Changes:

• Added dimos/spec/utils.py with Spec Protocol class and utility functions for structural and annotation compliance checking
• Added comprehensive test coverage in dimos/spec/test_utils.py
• Renamed ModuleBlueprintSet → Blueprint and ModuleBlueprint → _BlueprintAtom throughout the codebase
• Converted create_module_blueprint() function to Blueprint.create() classmethod
• Converted _make_module_blueprint() function to _BlueprintAtom.create() classmethod
• Added annotation-protocol>=1.4.0 dependency for strict protocol checking
• Updated all documentation and tests to reflect the new naming

Issues Found:

• One docstring typo in dimos/spec/utils.py line 87 (wrong function name in example)

Confidence Score: 4/5

• Safe to merge with minor docstring fix - comprehensive refactoring with good test coverage
• The refactoring is thorough and systematic across all files. Tests are comprehensive and passing. The only issue is a docstring typo that doesn't affect functionality. The API rename is well-executed with consistent updates across code, tests, and documentation.
• dimos/spec/utils.py has a docstring typo that should be fixed before merge

Important Files Changed

Filename	Overview
dimos/spec/utils.py	New spec utilities for Protocol validation with structural and annotation compliance checking - docstring typo found
dimos/spec/test_utils.py	Comprehensive test suite for spec utilities with good coverage of edge cases
dimos/core/blueprints.py	Renamed ModuleBlueprintSet to Blueprint and ModuleBlueprint to _BlueprintAtom, moved factory method to classmethod
dimos/core/test_blueprints.py	Updated tests to use new naming (Blueprint and _BlueprintAtom) with proper .create() classmethod calls
pyproject.toml	Added new dependency annotation-protocol>=1.4.0 for strict protocol checking

Sequence Diagram

sequenceDiagram
    participant User
    participant Module
    participant Blueprint
    participant _BlueprintAtom
    participant autoconnect
    participant Spec
    participant SpecUtils

    Note over User,SpecUtils: Part 3: Define Spec and Spec tooling

    User->>Module: Call Module.blueprint()
    Module->>Blueprint: Blueprint.create(Module, args, kwargs)
    Blueprint->>_BlueprintAtom: _BlueprintAtom.create(Module, args, kwargs)
    _BlueprintAtom->>_BlueprintAtom: Extract In/Out connections from annotations
    _BlueprintAtom-->>Blueprint: Return _BlueprintAtom instance
    Blueprint-->>User: Return Blueprint with single blueprint atom

    User->>autoconnect: autoconnect(blueprint1, blueprint2, ...)
    autoconnect->>autoconnect: Merge blueprints, transports, configs
    autoconnect-->>User: Return combined Blueprint

    Note over Spec,SpecUtils: New Spec Protocol utilities

    User->>Spec: Define Protocol inheriting from Spec
    User->>SpecUtils: is_spec(MyProtocol)
    SpecUtils-->>User: Returns True if inherits from Spec

    User->>SpecUtils: spec_structural_compliance(obj, MySpec)
    SpecUtils->>SpecUtils: Check if obj has required methods (ignore types)
    SpecUtils-->>User: Return compliance result

    User->>SpecUtils: spec_annotation_compliance(obj, MySpec)
    SpecUtils->>SpecUtils: Build strict AnnotationProtocol
    SpecUtils->>SpecUtils: Check obj against strict protocol
    SpecUtils-->>User: Return annotation compliance result

Loading

[greptile-apps]

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

docstring example uses wrong function name - should be spec_annotation_compliance not spec_structural_compliance

Suggested change

	assert True == spec_structural_compliance(FullyCompliant(), MySpec)
	assert True == spec_annotation_compliance(FullyCompliant(), MySpec)