System Architecture#

This document provides a comprehensive overview of the PyHydroGeophysX multi-agent system architecture, including agent relationships, data flow, and communication protocols.

Agent Communication Protocol#

Standard Input/Output Format#

All agents follow a standardized I/O pattern:

def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
    """
    Standard agent execution method.

    Args:
        input_data: Dictionary with agent-specific inputs

    Returns:
        Dictionary containing:
            - status: 'success', 'failed', or 'needs_improvement'
            - [agent-specific outputs]
            - error: Error message (if status='failed')
            - interpretation: AI interpretation (if LLM available)
    """

Standard Output Keys#

All agents include these common output keys:

  • status (str): ‘success’, ‘failed’, or ‘needs_improvement’

  • error (str): Error message if failed

  • interpretation (str): AI interpretation (if LLM available)

Data Flow Patterns#

Natural Language to Structured Workflow#

User Natural Language Request
        │
        ▼
ContextInputAgent (LLM Processing)
        │
        ▼
Structured Configuration (JSON)
        │
        ▼
DataFusionAgent (Create Execution Plan)
        │
        ▼
Sequential Agent Execution

Structure-Constrained ERT Data Path#

Seismic Data          ERT Data
    │                     │
    ▼                     ▼
SeismicAgent      ERTLoaderAgent
    │                     │
    ▼                     │
velocity_model        ert_data
    │                     │
    └───────┬─────────────┘
            │
            ▼
StructureConstraintAgent
    │
    ├─ Extract interfaces
    ├─ Create constrained mesh
    └─ Constrained ERT inversion
    │
    ▼
PetrophysicsAgent
    │
    └─ Layer-specific conversion
    │
    ▼
water_content ± uncertainty

Inversion Quality Optimization Loop#

Initial ERT Inversion (lambda = 20)
        │
        ▼
InversionEvaluationAgent
    │
    ├─ Calculate chi-squared
    ├─ Evaluate smoothness
    ├─ Check physical plausibility
    └─ Compute quality score
    │
    ▼
Quality Score < 70?
    │
┌───┴───┐
│ Yes   │ No
│       │
▼       ▼
Adjust     Accept
Parameters Results
    │
    ▼
Re-run Inversion
    │
    └────────────────────┐
                         │
                         ▼
                (repeat until quality >= 70
                 or max_attempts reached)

Monte Carlo Uncertainty Propagation#

Layer-Specific Parameters
    │
    ├─ Layer 1: porosity ± σ, n ± σ, m ± σ
    ├─ Layer 2: porosity ± σ, n ± σ, m ± σ
    └─ Layer 3: porosity ± σ, n ± σ, m ± σ
    │
    ▼
PetrophysicsAgent
    │
    For each cell:
      For i = 1 to N_realizations:
        Sample parameters from distributions
        Calculate WC(i) = f(resistivity, params_i)
    │
    ▼
Output:
    - water_content_mean
    - water_content_std
    - 95% confidence intervals

Workflow State Management#

The AgentCoordinator maintains workflow state:

{
    'status': 'initialized' | 'running' | 'completed' | 'failed',
    'current_step': 'agent_name',
    'completed_steps': ['agent1', 'agent2', ...],
    'data': {
        'agent1': {...},
        'agent2': {...}
    }
}

Fusion Patterns#

The DataFusionAgent supports several pre-defined fusion patterns:

Pattern 1: structure_constraint#

  • Methods: Seismic → ERT

  • Description: Use seismic velocity interfaces to constrain ERT inversion

  • Workflow: seismic_inversion → interface_extraction → constrained_ert

  • Benefits: Improved layer boundary resolution, reduced artifacts

Pattern 2: petrophysics_integration#

  • Methods: ERT → Petrophysics

  • Description: Convert resistivity to hydrological properties

  • Workflow: ert_inversion → petrophysics_conversion

  • Benefits: Direct hydrological interpretation

Pattern 3: full_integration#

  • Methods: Seismic → ERT → Petrophysics

  • Description: Complete geological-to-hydrological workflow

  • Workflow: seismic_inversion → interface_extraction → constrained_ert → petrophysics_conversion

  • Benefits: Comprehensive subsurface characterization with constraints

Extension Points#

Adding New Agents#

To add a new agent to the system:

  1. Inherit from BaseAgent:

from PyHydroGeophysX.agents.base_agent import BaseAgent

class NewMethodAgent(BaseAgent):
    def __init__(self, api_key, model='gpt-4', llm_provider='openai'):
        super().__init__("new_method", api_key, model, llm_provider)
        self.system_message = "Your expert role description"

  1. Implement execute() method:

def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
    # Your processing logic
    return {
        'status': 'success',
        'output_key': output_value
    }

  1. Register in __init__.py:

from .new_method_agent import NewMethodAgent
__all__ = [..., 'NewMethodAgent']

  1. Update DataFusionAgent patterns (if multi-method):

FUSION_PATTERNS = {
    'new_pattern': {
        'methods': ['method1', 'new_method'],
        'workflow': ['step1', 'step2'],
        ...
    }
}

Error Handling#

The agent system implements robust error handling:

  • Input Validation: All agents validate inputs before processing

  • Graceful Degradation: LLM features are optional; system works without them

  • Retry Logic: Failed operations can be retried with adjusted parameters

  • Comprehensive Logging: All agent actions are logged for debugging

Performance Considerations#

  • Parallel Execution: Independent agents can run in parallel

  • Caching: Intermediate results are cached to avoid recomputation

  • Memory Management: Large arrays are processed in chunks when necessary

  • GPU Acceleration: TDEM forward modeling supports GPU via SimPEG