← Back to DocsPrototype20250712

DSPEX PROTOTYPE IMPLEMENTATION PLAN

Documentation for DSPEX_PROTOTYPE_IMPLEMENTATION_PLAN from the Foundation repository.

DSPEx Prototype Implementation Plan

Date: July 12, 2025
Status: Active Implementation
Scope: DSPEx buildout on simplified Jido foundation with selective MABEAM integration

Executive Summary

This plan implements the DSPEx platform using the hybrid Jido-MABEAM architecture defined in 20250712_IMPLEMENTATION_SYNTHESIS.md. We start with a working QA pipeline in Week 1, proving the complete vertical slice works end-to-end, then incrementally add sophistication following the monthly delivery strategy from 20250712_VERTICAL_BUILDOUT_STRATEGY.md.

Implementation Strategy

Core Architecture Decision: Hybrid Jido-MABEAM

Primary Foundation: Jido agents, signals, supervision
Selective Enhancement: Foundation MABEAM coordination patterns
Revolutionary Innovation: Cognitive Variables as Jido agents

DSPEx.Application
├── Jido.Application                    # Primary foundation
├── DSPEx.Foundation.Bridge             # MABEAM integration layer
├── DSPEx.Variables.Supervisor          # Cognitive Variables as Jido agents
├── DSPEx.Signature.Supervisor          # Native DSPy syntax support
└── DSPEx.Infrastructure.Supervisor     # Minimal services

Phase 1: Foundation + Basic QA Pipeline (Week 1)

Day 1: Project Structure Setup

Create DSPEx namespace:

mkdir -p lib/dsp_ex/{foundation,variables,signature,coordination,clustering}
mkdir -p lib/dsp_ex/variables/{actions,sensors,skills}
mkdir -p lib/dsp_ex/signature/{dsl,compiler,types}
mkdir -p test/dsp_ex/{foundation,variables,signature}

Update mix.exs dependencies:

{:jido, "~> 0.1"},
{:uuid, "~> 1.1"},
{:jason, "~> 1.4"},
{:telemetry, "~> 1.2"}

Day 2: Core Application Structure

Create DSPEx.Application (primary supervision tree):

defmodule DSPEx.Application do
  use Application
  
  def start(_type, _args) do
    children = [
      # Primary Jido foundation
      {Jido.Application, []},
      
      # DSPEx components
      DSPEx.Foundation.Bridge,
      DSPEx.Variables.Supervisor,
      DSPEx.Signature.Supervisor,
      DSPEx.Infrastructure.Supervisor
    ]
    
    Supervisor.start_link(children, strategy: :one_for_one, name: DSPEx.Supervisor)
  end
end

Day 3: Foundation Bridge Implementation

Create DSPEx.Foundation.Bridge (MABEAM integration):

defmodule DSPEx.Foundation.Bridge do
  @moduledoc """
  Bridge between Jido agents and Foundation MABEAM coordination patterns.
  Provides selective integration of advanced coordination without coupling.
  """
  
  use GenServer
  
  # Simple registry integration
  def register_cognitive_variable(id, metadata) do
    GenServer.call(__MODULE__, {:register_variable, id, metadata})
  end
  
  # Basic agent discovery
  def find_affected_agents(agent_specs) do
    GenServer.call(__MODULE__, {:find_agents, agent_specs})
  end
  
  # Minimal consensus for critical coordination
  def start_consensus(participants, proposal, timeout) do
    GenServer.call(__MODULE__, {:start_consensus, participants, proposal, timeout})
  end
end

Day 4: Cognitive Variables as Jido Agents

Create DSPEx.Variables.CognitiveFloat:

defmodule DSPEx.Variables.CognitiveFloat do
  @moduledoc """
  Revolutionary cognitive variable that is both a Jido agent AND uses MABEAM coordination
  """
  
  use Jido.Agent
  
  @actions [
    DSPEx.Variables.Actions.UpdateValue,
    DSPEx.Variables.Actions.CoordinateAffectedAgents,
    DSPEx.Variables.Actions.AdaptBasedOnFeedback
  ]
  
  @sensors [
    DSPEx.Variables.Sensors.PerformanceFeedbackSensor,
    DSPEx.Variables.Sensors.AgentHealthMonitor
  ]
  
  defstruct [
    :name,
    :current_value,
    :valid_range,
    :affected_agents,
    :adaptation_strategy,
    coordination_enabled: true,
    performance_history: []
  ]
  
  def mount(agent, opts) do
    initial_state = struct(__MODULE__, opts)
    
    # Register with Foundation Bridge for coordination
    DSPEx.Foundation.Bridge.register_cognitive_variable(agent.id, initial_state)
    
    {:ok, initial_state}
  end
end

Day 5: Native DSPy Signature Support

Create DSPEx.Signature.DSL:

defmodule DSPEx.Signature.DSL do
  @moduledoc """
  Native DSPy signature syntax support for ElixirML
  """
  
  defmacro __using__(_opts) do
    quote do
      import DSPEx.Signature.DSL
      Module.register_attribute(__MODULE__, :signatures, accumulate: true)
    end
  end
  
  defmacro signature(definition) do
    quote do
      @signatures unquote(definition)
      
      def __signature__() do
        @signatures |> List.first() |> DSPEx.Signature.Compiler.compile()
      end
    end
  end
end

Day 6-7: Basic QA Pipeline Implementation

Create working QA system proving vertical slice:

defmodule BasicQA do
  use DSPEx.Signature.DSL
  
  signature "question: str, context?: str -> answer: str, confidence: float"
end

defmodule QAAgent do
  use Jido.Agent
  
  @actions [QAAgent.Actions.ProcessQuestion]
  
  def mount(agent, opts) do
    initial_state = %{
      temperature: 0.7,
      model: :mock_llm
    }
    {:ok, initial_state}
  end
end

defmodule QASystem do
  def process(question, opts \\ []) do
    context = Keyword.get(opts, :context, "")
    
    # Get temperature from cognitive variable
    {:ok, temp} = DSPEx.Variables.get_value(:temperature)
    
    # Process with QA agent
    {:ok, agent} = Jido.get_agent("qa_processor")
    {:ok, result} = Jido.Agent.cmd(agent, QAAgent.Actions.ProcessQuestion, %{
      question: question,
      context: context,
      temperature: temp
    })
    
    result
  end
end

Phase 2: Multi-Agent Coordination (Week 2)

Week 2 Expansion

  • Add ReviewerAgent for code generation
  • Implement agent coordination protocols
  • Add choice variables for strategy selection
  • Demonstrate measurable coordination benefits
defmodule CodeGenTeam do
  use DSPEx.MABEAM.CognitiveTeam
  
  agent :coder, CoderAgent, %{language: :elixir}
  agent :reviewer, ReviewerAgent, %{strictness: 0.8}
  
  cognitive_variable :review_strategy, :choice,
    choices: [:fast, :thorough, :adaptive],
    default: :adaptive
end

Phase 3: Real-Time Adaptation (Week 3)

Week 3 Features

  • Performance monitoring and feedback loops
  • Strategy adaptation based on performance
  • Module variables for algorithm selection
  • Measurable performance optimization

Phase 4: Scientific Evaluation (Week 4)

Week 4 Validation

  • Systematic evaluation and benchmarking
  • Hypothesis testing and statistical analysis
  • SIMBA optimization integration
  • Reproducible research capabilities

Success Criteria

Week 1 Gates (Must Pass):

  • DSPEx.Application starts successfully with Jido
  • DSPEx signature compiles: BasicQA.__signature__() != nil
  • Cognitive variable coordination: DSPEx.Variables.set(:temperature, 0.8) affects processing
  • QA pipeline processes 100 questions without failure
  • Agent crash triggers supervisor restart
  • Processing latency < 100ms per question
  • Memory usage < 50MB for basic operation

Test-First Implementation

Complete end-to-end test (write first, implement after):

test "complete QA pipeline with variable coordination" do
  # Initialize system
  {:ok, _} = QASystem.start_link()
  
  # Test signature compilation
  assert BasicQA.__signature__() != nil
  
  # Test variable coordination
  assert :ok = DSPEx.Variables.set(:temperature, 0.8)
  
  # Test pipeline processing
  result = QASystem.process("What is Elixir?", context: "Elixir is a programming language")
  
  assert result.answer != nil
  assert result.confidence > 0.0
  assert result.temperature == 0.8  # Variable coordination worked
  
  # Test supervision 
  agent_pid = QASystem.get_agent_pid()
  Process.exit(agent_pid, :kill)
  :timer.sleep(100)  # Allow supervisor to restart
  
  # Should still work after restart
  result2 = QASystem.process("What is AI?")
  assert result2.answer != nil
end

Implementation Timeline

Day 1: Project Structure + Dependencies

  • Create lib/dsp_ex structure
  • Update mix.exs
  • Basic application skeleton

Day 2: Core Application Framework

  • DSPEx.Application supervision tree
  • Jido integration
  • Basic infrastructure services

Day 3: Foundation Bridge

  • MABEAM integration bridge
  • Registry patterns
  • Coordination primitives

Day 4: Cognitive Variables

  • Variables as Jido agents
  • Basic coordination
  • Performance tracking

Day 5: DSPy Signature Support

  • Native syntax DSL
  • Signature compilation
  • Type validation

Day 6-7: QA Pipeline + Testing

  • Complete QA system
  • End-to-end tests
  • Performance validation

Quality Assurance

Development Standards:

  • Test-First: Write tests before implementation
  • Minimal Complexity: Simplest design that works
  • Jido-Native: Use Jido patterns, not GenServer directly
  • MABEAM Selective: Only add MABEAM where it provides clear value

Quality Gates:

  1. All tests pass - No exceptions
  2. Performance targets met - Latency and memory requirements
  3. Supervision works - Graceful failure handling
  4. Integration clean - Components work together seamlessly

Risk Mitigation

High-Risk Areas:

  1. Jido-MABEAM Integration - Bridge complexity
  2. Signature Compilation - DSL parsing and validation
  3. Variable Coordination - Performance and consistency
  4. Test Coverage - End-to-end scenario validation

Mitigation Strategies:

  • Start with simplest possible implementation
  • Extensive testing at each step
  • Incremental complexity addition
  • Clear rollback plans

Expected Deliverables

Week 1 Deliverable:

Complete working DSPEx QA system demonstrating:

  1. Native DSPy signature syntax works
  2. Variables coordinate system behavior
  3. Foundation provides reliable infrastructure
  4. End-to-end processing works correctly
  5. System handles failures gracefully

Community Engagement:

  • Release working QA pipeline
  • Show native DSPy syntax working
  • Demonstrate variable coordination
  • Gather feedback on developer experience

Next Steps

  1. Start Implementation: Begin with Day 1 project structure
  2. Follow Test-First: Write comprehensive tests before code
  3. Incremental Development: Build and validate each component
  4. Quality Gates: Pass all criteria before proceeding
  5. Community Release: Share working prototype for feedback

Implementation starts immediately with simplified Jido foundation + selective MABEAM integration for revolutionary DSPEx platform.