← Back to Docs

DOWNSIZING REPORT 20250724

Documentation for DOWNSIZING_REPORT_20250724 from the Dspex repository.

DSPex Downsizing Report - July 24, 2025

Executive Summary

This report analyzes the DSPex codebase to identify deprecated, redundant, and unnecessary components following Snakepit’s transition to gRPC-only architecture. The analysis focuses on removing legacy bridge implementations, deprecated adapters, and redundant state management systems.

Key Findings

1. Snakepit Current State (v0.4.1)

  • gRPC-only architecture: All legacy bridge implementations removed in v0.4.0
  • No JSON/MessagePack support: Removed in favor of protocol buffers
  • Unified gRPC protocol: Single communication method for all adapters
  • BridgeState pattern: Centralized session storage with Snakepit.Bridge.SessionStore

2. DSPex Architecture Assessment

Current State:

  • Uses both LocalState and BridgedState backends
  • Maintains legacy JSON-based Python bridges
  • Contains deprecated adapter implementations
  • Has redundant proto directory structure

A. Python Bridge Legacy Code (High Priority)

Files to Remove:

/priv/python/dspy_bridge.py                    # Old JSON protocol bridge
/priv/python/dspy_bridge_enhanced.py           # Enhanced JSON bridge
/priv/python/dspy_general.py                   # Basic JSON bridge
/priv/python/test_port_communication.py        # Debug tool for old protocol

Rationale: These files implement the old length-prefixed JSON protocol that was deprecated in Snakepit v0.4.0. They contain extensive JSON parsing/writing code with 4-byte headers that are incompatible with the current gRPC architecture.

Files Removed:

/priv/python/dspy_grpc.py                      # Duplicate removed

Rationale: This was an exact duplicate of /priv/python/snakepit_bridge/adapters/dspy_grpc.py and was safely removed.

B. Protocol Buffer Directory Structure (Medium Priority)

Current State:

  • DSPex has empty /priv/proto/ directory
  • All protocol definitions now in Snakepit at /snakepit/priv/proto/snakepit_bridge.proto

Status: Empty proto directory removed as protocol definitions are centralized in Snakepit.

C. State Management Architecture Decision

Current DSPex Implementation:

  • LocalState (/lib/dspex/bridge/state/local.ex) - In-process Agent-based storage
  • BridgedState (/lib/dspex/bridge/state/bridged.ex) - Delegates to Snakepit.Bridge.SessionStore

Recommended Architecture Change: Use Snakepit’s SessionStore directly - remove DSPex state management layer

Rationale:

  1. Avoid Duplication: Snakepit already provides robust SessionStore for bridged state management
  2. Simplify Architecture: State management should be in Snakepit, not duplicated in DSPex
  3. Start Simple: Begin with bridged state using Snakepit’s proven infrastructure
  4. Future Optimization: If pure Elixir performance is needed later, add local optimization as DSPex extension

Implementation:

  • Remove DSPex state management backends (/lib/dspex/bridge/state/)
  • Use Snakepit.Bridge.SessionStore directly for all state operations
  • Focus DSPex on DSPy-specific logic rather than reinventing state management

State Management Architecture Decision

Current Implementation Status

DSPex implements a dual-backend state management system:

  • LocalState: For pure Elixir workflows
  • BridgedState: For Python-integrated workflows using Snakepit’s SessionStore

Comparison with Snakepit BridgeState

Snakepit’s SessionStore (what we’re calling “bridgestate”) provides:

  • Centralized ETS-based session management
  • TTL-based expiration
  • High concurrency optimization
  • Variables API with type system integration
  • Cross-process state sharing

Assessment: No Additional DSPex BridgeState Implementation Needed

Recommendation: Use Snakepit’s SessionStore directly through BridgedState adapter.

Rationale:

  1. Avoid Duplication: Snakepit already provides robust session state management
  2. Maintain Simplicity: DSPex should focus on DSPy-specific logic, not reinventing state management
  3. Leverage Optimization: Snakepit’s SessionStore is optimized for high concurrency and performance
  4. Consistent Architecture: Aligns with Snakepit’s gRPC-only approach

Additional Cleanup Opportunities

Documentation Directory

The /docs/ directory contains extensive historical documentation that could be consolidated:

  • Multiple version-specific implementation plans
  • Deprecated architecture discussions
  • Obsolete technical specifications

Recommendation: Archive historical documents and maintain only current architecture documentation.

Test Infrastructure

Legacy test files in /test/ that test deprecated functionality should be removed after confirming they’re no longer needed.

Implementation Priority

Phase 1: Immediate Removals (High Impact, Low Risk)

  1. Remove 4 deprecated Python bridge files
  2. Remove empty /priv/proto/ directory
  3. Investigate and potentially remove duplicate dspy_grpc.py

Phase 2: Documentation Cleanup (Medium Impact, Low Risk)

  1. Archive historical documentation
  2. Update current documentation to reflect gRPC-only architecture
  3. Remove obsolete technical specifications

Phase 3: Test Infrastructure (Low Impact, Medium Risk)

  1. Audit test files for deprecated functionality
  2. Remove tests for removed components
  3. Update integration tests for gRPC-only workflow

Risk Assessment

Low Risk:

  • Removing deprecated Python bridges (functionality replaced)
  • Removing empty directories
  • Documentation cleanup

Medium Risk:

  • Removing duplicate gRPC adapters (requires verification)
  • Test infrastructure changes (requires thorough testing)

No Risk:

  • Keeping both LocalState and BridgedState (different use cases)
  • Using Snakepit’s SessionStore (proven architecture)

Conclusion

The DSPex codebase can be significantly simplified by removing legacy JSON-based bridges while maintaining the dual-backend state architecture. The key insight is that LocalState and BridgedState serve different use cases rather than being redundant implementations.

By leveraging Snakepit’s proven SessionStore implementation through the BridgedState adapter, DSPex avoids reinventing session management while maintaining performance optimization for pure Elixir workflows through LocalState.

Next Steps

  1. Remove deprecated Python bridges - Safe immediate cleanup
  2. Verify gRPC adapter consolidation - Requires code comparison
  3. Archive historical documentation - Maintains history while reducing clutter
  4. Update integration examples - Ensure all examples use gRPC-only architecture

This downsizing approach maintains functionality while significantly reducing maintenance burden and architectural complexity.