← Back to DocsRebuild20250712

CURRENT INTERFACE MAPPING

Documentation for CURRENT_INTERFACE_MAPPING from the Foundation repository.

Current Interface Mapping - Foundation Jido System

Date: 2025-07-12
Status: Comprehensive mapping of existing interfaces in the Foundation cognitive variables implementation
Purpose: Document all current interface patterns to inform strategic interface design decisions

📊 INTERFACE TAXONOMY

Classification System:

🔴 Direct Jido - Raw Jido API usage
🟡 Foundation Wrapper - Foundation abstractions over Jido
🟢 Domain-Specific - Cognitive variable specific interfaces
🔵 Test Helper - Testing infrastructure interfaces

🏗️ AGENT CREATION INTERFACES

🔴 Direct Jido Pattern - Agent Definition

# File: lib/foundation/variables/cognitive_variable.ex
defmodule Foundation.Variables.CognitiveVariable do
  use Jido.Agent,
    name: "cognitive_variable",
    description: "ML parameter as intelligent coordination primitive",
    category: "ml_optimization", 
    tags: ["ml", "optimization", "coordination"],
    vsn: "1.0.0",
    schema: [
      name: [type: :atom, required: true],
      type: [type: :atom, default: :float],
      current_value: [type: :any, required: true],
      range: [type: :any],
      coordination_scope: [type: :atom, default: :local],
      affected_agents: [type: {:list, :pid}, default: []],
      adaptation_strategy: [type: :atom, default: :performance_feedback]
    ],
    actions: [
      Foundation.Variables.Actions.ChangeValue,
      Foundation.Variables.Actions.PerformanceFeedback,
      Foundation.Variables.Actions.CoordinateAgents,
      Foundation.Variables.Actions.GetStatus
    ]
end

Interface Characteristics:

Type: Direct Jido Agent DSL
Complexity: High (requires Jido knowledge)
Flexibility: Maximum (full Jido feature access)
Domain Specificity: High (ML-optimized schema)

🟡 Foundation Wrapper - Agent Creation

# File: lib/foundation/variables/cognitive_variable.ex
def create(id, initial_state \\ %{}) do
  # Set defaults for cognitive variable
  default_state = %{
    name: :default_variable,
    type: :float,
    current_value: 0.5,
    range: {0.0, 1.0},
    coordination_scope: :local,
    affected_agents: [],
    adaptation_strategy: :performance_feedback
  }
  
  merged_state = Map.merge(default_state, initial_state)
  routes = build_signal_routes()
  
  start_link([
    id: id,
    initial_state: merged_state,
    routes: routes
  ])
end

Interface Characteristics:

Type: Foundation creation wrapper
Complexity: Medium (hides Jido details)
Flexibility: High (configurable via initial_state)
Domain Specificity: High (cognitive variable defaults)

🔵 Test Helper - Agent Creation

# File: test/test_helper.exs
def create_test_cognitive_variable(name, type, opts \\ []) do
  initial_state = %{
    name: name,
    type: type,
    current_value: Keyword.get(opts, :default, get_default_for_type(type)),
    coordination_scope: Keyword.get(opts, :coordination_scope, :local),
    range: Keyword.get(opts, :range),
    choices: Keyword.get(opts, :choices),
    affected_agents: Keyword.get(opts, :affected_agents, []),
    adaptation_strategy: Keyword.get(opts, :adaptation_strategy, :none)
  }
  |> Enum.reject(fn {_k, v} -> is_nil(v) end)
  |> Enum.into(%{})
  
  case type do
    :float ->
      enhanced_state = Map.merge(initial_state, %{
        learning_rate: Keyword.get(opts, :learning_rate, 0.01),
        momentum: Keyword.get(opts, :momentum, 0.9),
        gradient_estimate: 0.0,
        velocity: 0.0,
        optimization_history: [],
        bounds_behavior: Keyword.get(opts, :bounds_behavior, :clamp)
      })
      Foundation.Variables.CognitiveFloat.create("test_#{name}", enhanced_state)
    _ ->
      Foundation.Variables.CognitiveVariable.create("test_#{name}", initial_state)
  end
end

Interface Characteristics:

Type: Test-specific helper
Complexity: Low (simple keyword arguments)
Flexibility: High (comprehensive options)
Domain Specificity: Very High (test-optimized)

🔄 COMMUNICATION INTERFACES

🔴 Direct Jido Pattern - Signal Creation & Dispatch

# File: lib/foundation/variables/actions/change_value.ex
def run(%{new_value: new_value} = params, context) do
  # Direct signal creation
  signal = Jido.Signal.new!(%{
    type: "cognitive_variable.value.changed",
    source: "agent:#{agent.id}",
    subject: "jido://agent/cognitive_variable/#{agent.id}",
    data: %{
      variable_name: agent.state.name,
      old_value: old_value,
      new_value: new_value,
      agent_id: agent.id
    },
    jido_dispatch: case agent.state.coordination_scope do
      :global -> {:pubsub, topic: "cognitive_variables_global"}
      :local -> {:logger, level: :debug}
      _ -> {:logger, level: :debug}
    end
  })
  
  # Direct dispatch
  Jido.Signal.Dispatch.dispatch(signal, signal.jido_dispatch)
end

Interface Characteristics:

Type: Direct Jido Signal API
Complexity: High (CloudEvents structure)
Flexibility: Maximum (full signal control)
Domain Specificity: High (cognitive variable events)

🔴 Direct Jido Pattern - Agent Communication

# File: lib/foundation/variables/actions/coordinate_agents.ex
def coordinate_with_agents(agent, affected_agents) do
  signal = Jido.Signal.new!(%{
    type: "get_status",
    source: "coordination_request",
    data: %{requesting_agent: agent.id}
  })
  
  Enum.map(affected_agents, fn agent_pid ->
    case Jido.Agent.Server.call(agent_pid, signal, 5000) do
      {:ok, response} -> {:ok, agent_pid, response}
      {:error, reason} -> {:error, agent_pid, reason}
    end
  end)
end

Interface Characteristics:

Type: Direct Jido Agent Server API
Complexity: Medium (synchronous communication)
Flexibility: Maximum (timeout control, error handling)
Domain Specificity: Medium (generic agent communication)

🔵 Test Helper - Communication

# File: test/test_helper.exs
def wait_for_agent(agent_pid, timeout \\ 5000) do
  try do
    signal = Jido.Signal.new!(%{
      type: "get_status",
      source: "test",
      data: %{include_metadata: true}
    })
    
    case Jido.Agent.Server.call(agent_pid, signal, timeout) do
      {:ok, _response} -> :ok
      {:error, reason} -> {:error, reason}
    end
  catch
    :exit, reason -> {:error, reason}
  end
end

def change_agent_value(agent_pid, new_value, context \\ %{}) do
  signal = Jido.Signal.new!(%{
    type: "change_value",
    source: "test",
    data: %{
      new_value: new_value,
      requester: :test,
      context: context
    }
  })
  
  case Jido.Agent.Server.cast(agent_pid, signal) do
    {:ok, _signal_id} -> :ok
    error -> error
  end
end

Interface Characteristics:

Type: Test-specific communication helpers
Complexity: Low (simple function calls)
Flexibility: Medium (basic options)
Domain Specificity: High (test-optimized)

⚙️ ACTION INTERFACES

🔴 Direct Jido Pattern - Action Definition

# File: lib/foundation/variables/actions/change_value.ex
defmodule Foundation.Variables.Actions.ChangeValue do
  use Jido.Action,
    name: "change_value",
    description: "Changes the value of a cognitive variable with validation",
    category: "ml_optimization",
    tags: ["ml", "variables", "coordination"],
    schema: [
      new_value: [type: :any, required: true, doc: "The new value to set"],
      requester: [type: :atom, doc: "Who/what is requesting the change"],
      context: [type: :map, default: %{}, doc: "Additional context for the change"],
      force: [type: :boolean, default: false, doc: "Force change even if validation fails"]
    ]

  def run(%{new_value: new_value} = params, context) do
    # Implementation...
  end
end

Interface Characteristics:

Type: Direct Jido Action DSL
Complexity: High (requires Jido Action knowledge)
Flexibility: Maximum (full action capabilities)
Domain Specificity: High (ML-specific parameters)

🟢 Domain-Specific - ML Operations

# File: lib/foundation/variables/actions/gradient_feedback.ex
def run(%{gradient: gradient} = params, context) do
  # ML-specific validation
  cond do
    not is_number(gradient) ->
      {:error, {:invalid_gradient, "Gradient must be a number, got: #{inspect(gradient)}"}}
    
    abs(gradient) > @gradient_threshold ->
      Logger.warning("Gradient overflow detected: #{gradient}")
      {:error, {:gradient_overflow, gradient}}
    
    true ->
      # Process gradient with momentum
      smoothed_gradient = apply_gradient_smoothing(gradient, params)
      new_velocity = agent.state.momentum * agent.state.velocity + 
                     agent.state.learning_rate * smoothed_gradient
      
      # Apply bounds behavior
      new_value = apply_bounds_behavior(
        agent.state.current_value + new_velocity,
        agent.state.range,
        agent.state.bounds_behavior
      )
      
      # Update optimization history
      new_history = update_optimization_history(agent.state, %{
        gradient: gradient,
        smoothed_gradient: smoothed_gradient,
        velocity: new_velocity,
        old_value: agent.state.current_value,
        new_value: new_value,
        timestamp: DateTime.utc_now()
      })
      
      new_state = %{agent.state |
        current_value: new_value,
        velocity: new_velocity,
        gradient_estimate: smoothed_gradient,
        optimization_history: new_history
      }
      
      {:ok, %{action: "gradient_feedback", new_state: new_state}}
  end
end

Interface Characteristics:

Type: Domain-specific ML operations
Complexity: High (sophisticated ML algorithms)
Flexibility: High (configurable parameters)
Domain Specificity: Very High (gradient optimization specific)

🏛️ INFRASTRUCTURE INTERFACES

🔴 Direct Jido Pattern - Signal Routing

# File: lib/foundation/variables/cognitive_variable.ex
defp build_signal_routes do
  [
    {"change_value", Jido.Instruction.new!(
      action: Foundation.Variables.Actions.ChangeValue
    )},
    {"get_status", Jido.Instruction.new!(
      action: Foundation.Variables.Actions.GetStatus  
    )},
    {"performance_feedback", Jido.Instruction.new!(
      action: Foundation.Variables.Actions.PerformanceFeedback
    )},
    {"coordinate_agents", Jido.Instruction.new!(
      action: Foundation.Variables.Actions.CoordinateAgents
    )}
  ]
end

Interface Characteristics:

Type: Direct Jido routing infrastructure
Complexity: Medium (signal-to-action mapping)
Flexibility: Maximum (custom routing patterns)
Domain Specificity: High (cognitive variable specific routes)

🟡 Foundation Wrapper - Process Management

# File: lib/foundation/variables/cognitive_variable.ex
def start_link(opts) do
  id = Keyword.get(opts, :id) || Jido.Util.generate_id()
  initial_state = Keyword.get(opts, :initial_state, %{})
  routes = Keyword.get(opts, :routes, [])
  
  # Foundation defaults
  default_state = %{
    name: :default_variable,
    type: :float,
    current_value: 0.5,
    range: {0.0, 1.0},
    coordination_scope: :local,
    affected_agents: [],
    adaptation_strategy: :performance_feedback
  }
  
  merged_state = Map.merge(default_state, initial_state)
  agent = __MODULE__.new(id, merged_state)
  
  # Delegate to Jido infrastructure
  Jido.Agent.Server.start_link([
    agent: agent,
    routes: routes
  ])
end

Interface Characteristics:

Type: Foundation wrapper over Jido infrastructure
Complexity: Medium (hides Jido details)
Flexibility: High (configurable options)
Domain Specificity: High (cognitive variable defaults)

📊 INTERFACE COMPLEXITY ANALYSIS

Complexity Distribution:

Interface Type	Count	Avg Complexity	Domain Specificity	Jido Coupling
Direct Jido Agent	2	High	High	Very High
Direct Jido Action	5	High	High	Very High
Direct Jido Signal	8	High	Medium	Very High
Foundation Wrapper	4	Medium	High	Medium
Domain-Specific	3	High	Very High	Low
Test Helper	7	Low	High	Medium

Learning Curve Analysis:

New Developer Onboarding:
- Test Helpers: ✅ Easy (simple function calls)
- Foundation Wrappers: 🟡 Medium (need to understand options)
- Direct Jido: ❌ Hard (requires Jido ecosystem knowledge)
Advanced Use Cases:
- Direct Jido: ✅ Full capability
- Foundation Wrappers: 🟡 Limited by abstraction
- Test Helpers: ❌ Test-specific only

🎯 INTERFACE GAPS IDENTIFIED

Missing High-Level Interfaces:

Bulk Operations

# Currently: Individual agent operations
# Needed: Bulk operations
Foundation.CognitiveVariables.update_multiple(variable_pids, values)
Foundation.CognitiveVariables.coordinate_group(variable_pids, strategy)

Configuration Management

# Currently: Per-agent configuration
# Needed: Global configuration
Foundation.Config.set_defaults(:cognitive_float, %{learning_rate: 0.01})
Foundation.Config.apply_profile(:conservative_optimization)

Monitoring and Observability

# Currently: Manual status checking
# Needed: Built-in monitoring
Foundation.Monitor.watch_variables(variable_pids)
Foundation.Monitor.get_performance_metrics()

Workflow Orchestration

# Currently: Manual coordination
# Needed: Workflow patterns
Foundation.Workflow.create_optimization_pipeline(variables, algorithm)
Foundation.Workflow.run_adaptive_learning(variables, training_data)

📋 INTERFACE RECOMMENDATIONS

Immediate Improvements:

Formalize Test Helpers

# Move from test_helper.exs to:
defmodule Foundation.CognitiveVariables.TestHelpers do
  # Comprehensive test interface
end

Create High-Level API

defmodule Foundation.CognitiveVariables do
  # Simplified interface for common operations
end

Add Error Handling Layer

# Wrap Jido errors in domain-specific error types
{:error, {:optimization_failure, reason}}
{:error, {:coordination_timeout, agents}}

Interface Design Principles:

Progressive Disclosure: Start simple, expose complexity as needed
Domain Optimization: Optimize for cognitive variable use cases
Zero Abstraction Loss: Always provide access to underlying Jido
Consistent Patterns: Similar operations should have similar interfaces
Error Clarity: Domain-specific error messages and types

🏆 CONCLUSION

Current State: Hybrid interface architecture with organic patterns

Strengths:

✅ Rich functionality through direct Jido access
✅ Domain-specific optimizations in actions and agents
✅ Excellent test infrastructure with helper functions
✅ Flexible architecture supporting multiple interface patterns

Opportunities:

🔄 Formalize interface strategy with clear guidelines
🔄 Add high-level API layer for common operations
🔄 Enhance error handling with domain-specific types
🔄 Create configuration management for system-wide settings

Next Steps: Build on existing patterns to create a strategic layered interface architecture that maximizes both ease of use and power.

Mapping Date: 2025-07-12
Implementation Status: ✅ Functional hybrid approach
Interface Count: 29 distinct interface patterns
Recommendation: ✅ Formalize and enhance existing patterns