Docs Clean

[leshy]

depends on
Repair Stream #932
Repair Camera #929

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[greptile-apps]

Greptile Summary

This PR represents a comprehensive modernization and type-safety cleanup of the DimOS codebase, with significant focus on removing technical debt and improving code maintainability.

Key Changes

• Type Safety Improvements: Systematic addition of type annotations throughout the codebase, resolving mypy compliance issues. Removed # type: ignore comments and properly typed generic parameters across core modules.

• Stream System Enhancements: Refactored dimos/core/stream.py to improve implementation:

  • Implemented previously stubbed In.connect() method to actively subscribe when connecting streams
  • Enhanced Out.subscribe() to maintain local subscriber lists for direct callbacks
  • Improved Transport abstract methods with proper NotImplementedError implementations

• Module Lifecycle Management: Added robust serialization support in ModuleBase with __getstate__/__setstate__ methods to handle unpicklable runtime attributes, improving distributed execution reliability.

• Module Introspection System: New introspection tooling (dimos/core/introspection/) for visualizing module blueprints and I/O structure with ANSI, SVG, and DOT format support.

• Documentation Expansion: Added comprehensive documentation including RxPY patterns, temporal alignment concepts, transform chains, and module/transport configuration guides. Implemented doclinks validation system for maintaining accurate documentation references.

• Code Reorganization: File structure improvements including moving gstreamer camera modules into subdirectories and consolidating deprecated code removal (agents2, old ROS navigation, legacy ML models).

• Infrastructure Updates: Pre-commit configuration improvements, additions to .gitattributes for proper file handling.

Areas of Confidence

• Type annotations are thorough and properly integrated across modified files
• Stream connection logic changes are validated by existing test suite (test_stream.py)
• Documentation is comprehensive and includes practical examples
• Serialization/deserialization logic properly handles module distribution

Minor Observations

• The In.connect() implementation change from stub to active subscription represents a behavioral modification; however, this appears intentional and aligns with test expectations

Confidence Score: 4/5

• This PR is safe to merge. It implements a well-organized modernization effort with no critical issues detected. Type safety improvements and stream refactoring are validated by existing tests.
• The PR demonstrates comprehensive type-safety improvements and code organization without introducing breaking changes. The test suite validates the stream connection logic changes. All documentation additions are well-structured. The score of 4/5 (not 5/5) reflects the significant scope of changes affecting core modules, which warrant careful integration testing in the dev branch before wider release, but the quality and implementation approach is sound.
• No files require special attention. All core infrastructure changes are properly typed and validated. Documentation files are well-written with clear examples. The introspection system additions are self-contained and additive in nature.

Important Files Changed

Filename	Overview
dimos/core/stream.py	Added type annotations and implemented In.connect() method which now actively subscribes when connecting streams. Changed Out.subscribe() to maintain local subscriber list. Improved type safety throughout with proper type hints for generic parameters.
dimos/core/module.py	Type annotations improvements, added proper serialization/deserialization methods (__getstate__/__setstate__), fixed runtime attribute initialization in DaskModule.__init__, and added module introspection via module_info descriptor. Changes improve robustness of module lifecycle.
dimos/core/transport.py	Type annotations and documentation improvements. Changed abstract method signatures to raise NotImplementedError instead of using empty ellipsis. All transport implementations properly type-hinted with improvements to LCM, shared memory, and JPEG transport classes.
dimos/utils/reactive.py	Comprehensive type annotations added throughout reactive utilities. Includes backpressure handling, observable-to-getter converters, and threading primitives. All functions properly typed and documented with thread-safe implementations for latest-value accessors.
dimos/hardware/sensors/camera/module.py	Camera module properly uses type annotations, correctly initializes hardware configuration, and properly manages subscriptions and metadata publishing. Implements frame filtering with sharpness barrier and properly manages resource lifecycle.
docs/api/reactivex.md	Comprehensive documentation for RxPY patterns used in the codebase with practical examples. Covers backpressure handling, operators, subscription patterns, and custom observable creation. Well-structured with clear explanations and working code examples.

Sequence Diagram

sequenceDiagram
    actor User
    participant Output as Out[T]
    participant Input as In[T]
    participant Transport as Transport[T]
    participant Subscriber as Callback

    User->>Input: .connect(output)
    activate Input
    Input->>Output: .subscribe(self.transport.publish)
    activate Output
    Output->>Output: _subscribers.append(callback)
    Output-->>Input: unsubscribe_fn
    deactivate Output
    Input-->>User: connection established

    User->>Output: .publish(msg)
    activate Output
    Output->>Subscriber: callback(msg)
    activate Subscriber
    Subscriber->>Transport: .publish(msg)
    deactivate Subscriber
    Output->>Output: for cb in _subscribers: cb(msg)
    deactivate Output

    Note over Output,Input: New behavior: In.connect() now actively subscribes<br/>Previously it was just a type stub

Loading