Agent Reference#

This document provides detailed documentation for each agent in the PyHydroGeophysX multi-agent system, including their inputs, outputs, and responsibilities.

BaseAgent#

The abstract base class that all agents inherit from.

class BaseAgent:
    def __init__(self, name, api_key, model, llm_provider):
        self.name = name
        self.api_key = api_key
        self.model = model
        self.llm_provider = llm_provider

    def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
        raise NotImplementedError

AgentCoordinator#

Purpose: Orchestrates multi-agent workflows and manages execution state.

This is not a processing agent but an orchestration layer that:

  • Registers agents

  • Manages workflow state

  • Coordinates agent execution

  • Handles data flow between agents

  • Logs execution history

Key Methods:

register_agent(name, instance)  # Add agent to workflow
execute_workflow(config)        # Run complete workflow
get_workflow_state()           # Get current state
save_workflow_results()        # Persist results

ContextInputAgent#

Purpose: Translates natural language workflow descriptions into structured configurations.

System Prompt:

You are an expert in geophysical workflow design. You translate natural language descriptions of geophysical workflows into structured JSON configurations.

Inputs:

  • user_request (str): Natural language workflow description

  • available_data (dict, optional): Available files/instruments

Outputs:

  • workflow_config (dict): Structured configuration

  • explanation (str): Human-readable explanation

ERTLoaderAgent#

Purpose: Loads and validates ERT field data from various instruments.

System Prompt:

You are an expert in electrical resistivity tomography (ERT) data processing. Your role is to load and validate ERT field data from various commercial instruments.

Inputs:

  • data_file (str): Path to ERT data file

  • instrument (str): Instrument type (E4D, Syscal, ABEM, BERT)

  • project_dir (str): Project directory

  • crs (str): Coordinate reference system

  • quality_check (bool): Whether to perform QC

Outputs:

  • ert_data (object): Loaded ERT dataset (PyGIMLi DataContainer)

  • num_electrodes (int): Number of electrodes

  • num_measurements (int): Number of measurements

  • quality_metrics (dict): Data quality statistics

ERTInversionAgent#

Purpose: Performs ERT inversion (standard or time-lapse).

System Prompt:

You are an expert in electrical resistivity tomography (ERT) inversion. Your role is to configure and execute ERT inversions, select appropriate regularization parameters, and interpret inversion results.

Inputs:

  • ert_data (object): ERT data (for standard inversion)

  • time_lapse_data (list): List of ERT datasets (for time-lapse)

  • inversion_mode (str): ‘standard’ or ‘time-lapse’

  • time_lapse_method (str): ‘difference’, ‘ratio’, or ‘joint’

  • temporal_regularization (float): Temporal smoothing weight

  • inversion_params (dict): Lambda, max_iter, method

  • use_structure_constraint (bool): Whether to use seismic structure

  • seismic_structure (object): Optional seismic structure data

Outputs:

  • resistivity_model (array): Inverted resistivity model

  • mesh (object): PyGIMLi mesh

  • chi2_values (list): Chi-squared fit statistics

  • coverage (array): Model coverage/sensitivity

  • final_models (array): Time-series models (for time-lapse)

InversionEvaluationAgent#

Purpose: Evaluates inversion quality and automatically optimizes parameters.

System Prompt:

You are an expert in geophysical inversion quality assessment. Your role is to evaluate ERT inversion results based on data fit, model smoothness, and physical plausibility.

Inputs:

  • inversion_results (dict): Results from ERTInversionAgent

  • ert_data (object): Original ERT data

  • inversion_params (dict): Current parameters

  • auto_adjust (bool): Whether to auto-adjust parameters

  • max_attempts (int): Maximum re-inversion attempts

Outputs:

  • quality_score (float): Overall quality (0-100)

  • quality_metrics (dict): Detailed metrics

  • component_scores (dict): Individual component scores

  • recommendations (list): Improvement suggestions

  • adjusted_params (dict): Optimized parameters

  • final_results (dict): Best inversion results

Quality Metrics:

  1. Data Fit: Chi-squared target (0.8-1.5 acceptable)

  2. Smoothness: Model roughness evaluation

  3. Physical Plausibility: Resistivity range (1-10,000 Ohm-m)

  4. Convergence: Iteration stability

  5. Coverage: Model sensitivity

DataFusionAgent#

Purpose: Intelligent coordinator for multi-method geophysical workflows.

System Prompt:

You are an expert in multi-method geophysical data fusion. You understand how different geophysical methods complement each other and can recommend optimal workflows for integrating multiple datasets.

Inputs:

  • fusion_pattern (str): Pattern name or ‘auto’

  • methods (list): Available methods

  • workflow_config (dict): Configuration for fusion

  • data (dict): Data for each method

  • output_dir (str): Results directory

Outputs:

  • fusion_pattern (str): Selected pattern

  • execution_plan (list): Step-by-step plan

  • status (str): Success/failure

  • interpretation (str): AI interpretation of results

StructureConstraintAgent#

Purpose: Applies seismic velocity interfaces as structural constraints to ERT inversion.

System Prompt:

You are an expert in structure-constrained geophysical inversion. You understand how to incorporate a priori geological information from seismic data into ERT inversions.

Inputs:

  • ert_data (object): ERT measurement data

  • seismic_data (object): Seismic travel time data (optional)

  • velocity_model (array): Velocity model from seismic inversion

  • mesh (object): PyGIMLi mesh

  • velocity_thresholds (list): Thresholds for interface extraction

  • mesh_quality (int): Constrained mesh quality

  • lambda (float): ERT regularization parameter

  • limits (list): Resistivity bounds [min, max]

Outputs:

  • resistivity_model (array): Constrained resistivity model

  • mesh (object): Constrained mesh with layer markers

  • cell_markers (array): Cell layer identifications

  • coverage (array): Model coverage

  • interfaces (list): Extracted velocity interfaces

  • statistics (dict): Resistivity range, chi2, data fit, n_layers

PetrophysicsAgent#

Purpose: Converts resistivity to water content using layer-specific petrophysical models with Monte Carlo uncertainty quantification.

System Prompt:

You are an expert in petrophysical modeling and hydrogeophysics. You understand how to convert electrical resistivity to water content using Archie’s law and modified petrophysical relationships.

Petrophysical Model:

Archie's Law (modified with surface conductivity):
sigma_bulk = sigma_fluid * phi^m * S^n + sigma_surface

Where:
- sigma_bulk: Bulk conductivity (1/resistivity)
- sigma_fluid: Fluid conductivity (1/rho_fluid)
- phi: Porosity
- S: Saturation (water content / porosity)
- m: Cementation exponent
- n: Saturation exponent
- sigma_surface: Surface conductivity (clay effect)

Default Layer Parameters:

Layer Type

Porosity (phi)

m

n

sigma_surface

rho_fluid

Regolith

0.42 +/- 0.05

1.3

2.1

1/200 +/- 1/200

20 Ohm-m

Bedrock

0.25 +/- 0.15

1.9

1.7

0.0 +/- 0.0

20 Ohm-m

Inputs:

  • resistivity_model (array): Resistivity values

  • mesh (object): PyGIMLi mesh

  • cell_markers (array): Layer identifications

  • layer_params (dict): Parameters for each layer

  • n_realizations (int): Monte Carlo samples (default: 100)

Outputs:

  • water_content_mean (array): Mean water content per cell

  • water_content_std (array): Standard deviation (uncertainty)

  • saturation_mean (array): Mean saturation

  • saturation_std (array): Saturation uncertainty

  • statistics (dict): WC range, mean WC, mean uncertainty

WaterContentAgent#

Purpose: General resistivity to water content conversion (simpler than PetrophysicsAgent).

System Prompt:

You are an expert in petrophysical relationships and rock physics. Your role is to convert electrical resistivity to water content using appropriate models.

Inputs:

  • inversion_results (dict): ERT inversion results

  • petrophysical_params (dict): Parameters for each layer

  • uncertainty_analysis (bool): Whether to run Monte Carlo

  • n_realizations (int): MC realizations (default: 100)

Outputs:

  • water_content (array): Water content estimates

  • uncertainties (array): Uncertainty estimates (if MC enabled)

  • statistics (dict): Summary statistics

SeismicAgent#

Purpose: Processes seismic refraction data and extracts velocity structures.

System Prompt:

You are an expert in seismic refraction tomography (SRT). Your role is to process seismic travel time data, perform velocity inversions, and extract geological structure interfaces.

Inputs:

  • seismic_data (object): Seismic travel time data

  • velocity_threshold (float): Threshold for interface detection

  • inversion_params (dict): Seismic inversion parameters

  • output_dir (str): Results directory

Outputs:

  • velocity_model (array): Velocity distribution

  • interface_coords (tuple): (x, z) coordinates of interface

  • mesh (object): Seismic inversion mesh

  • statistics (dict): Velocity range, chi2, data fit

TDEMAgent#

Purpose: Performs Time-Domain Electromagnetic forward modeling and inversion.

Inputs:

  • layer_thicknesses (array): Layer thicknesses for 1D model

  • conductivity (array): Layer conductivities

  • survey_config (TDEMSurveyConfig): Survey parameters

  • inversion_params (dict): Inversion configuration

Outputs:

  • forward_response (array): TDEM response

  • recovered_model (array): Inverted conductivity model

  • chi2 (float): Data misfit

  • statistics (dict): Inversion statistics

ClimateDataAgent#

Purpose: Fetches and processes climate data for temporal analysis.

System Prompt:

You are an expert in climate data analysis for hydrogeophysical studies. You understand how precipitation, evapotranspiration, and temperature affect subsurface moisture and resistivity measurements.

Inputs:

  • geometry (dict): Site coordinates (lat, lon)

  • start_date (str): Start date (YYYY-MM-DD)

  • end_date (str): End date (YYYY-MM-DD)

  • variables (list): Climate variables

  • source (str): Data source (default: ‘daymet’)

Outputs:

  • climate_data (DataFrame): Time-series climate data

  • precipitation (Series): Daily precipitation (mm)

  • temperature (Series): Daily temperature (C)

  • pet (Series): Potential evapotranspiration (mm)

  • statistics (dict): Summary statistics

ReportAgent#

Purpose: Generates comprehensive reports from workflow results.

System Prompt:

You are an expert in technical report writing for geophysical and hydrological studies. Your role is to synthesize results from ERT data processing, inversion, water content analysis, and climate data into clear, informative reports.

Report Sections:

  1. Executive Summary

  2. Data Processing Summary

  3. Climate Data Summary (if available)

  4. Inversion Results

  5. Water Content Analysis

  6. Climate-Resistivity Analysis (if climate data available)

  7. Quality Assessment

  8. Conclusions & Recommendations

Inputs:

  • workflow_data (dict): All data from workflow steps

  • config (dict): Original workflow configuration

  • output_dir (str): Report output directory

Outputs:

  • report_path (str): Path to generated report

  • figures (list): Generated figure paths

  • summary_stats (dict): Key statistics