Agents Module#

The agents module provides the multi-agent system for automating geophysical workflows using Large Language Models.

Base Classes#

Base Agent Class for Multi-Agent System

Provides the foundation for all specialized agents in the workflow.

class PyHydroGeophysX.agents.base_agent.BaseAgent(name: str, api_key: str | None = None, model: str | None = None, llm_provider: str = 'openai')[source]#

Bases: ABC

Abstract base class for all agents in the multi-agent system.

Each agent is specialized for a specific task and can communicate with other agents through the coordinator.

abstract execute(input_data: Dict[str, Any]) → Dict[str, Any][source]#

Execute the agent’s primary task.

Parameters:

input_data – Input data dictionary

Returns:

Dictionary containing execution results

get_context(key: str, default: Any | None = None) → Any[source]#

Get value from agent’s context.

query_llm(prompt: str, system_message: str | None = None, temperature: float = 0.7, max_tokens: int = 1000) → str[source]#

Query the LLM API for assistance. Supports multiple LLM providers: OpenAI (GPT), Google (Gemini), and Anthropic (Claude).

Parameters:

  • prompt – User prompt for the LLM

  • system_message – System message defining agent behavior

  • temperature – Sampling temperature (0-1)

  • max_tokens – Maximum tokens in response

Returns:

LLM response as string

static run_unified_agent_workflow(workflow_config, api_key, llm_model, llm_provider, output_dir, progress_callback=None)[source]#

Unified agent workflow: infers task type from config and runs the appropriate pipeline. Supported: data fusion, time-lapse, direct ERT conversion. Returns: results dict, execution plan, interpretation, report files

Parameters:

  • workflow_config – Configuration dictionary from ContextInputAgent

  • api_key – LLM API key

  • llm_model – LLM model name

  • llm_provider – LLM provider (‘openai’, ‘gemini’, ‘claude’)

  • output_dir – Output directory path

  • progress_callback – Optional callback function(step: str, progress: float, details: str)

save_results(output_dir: str)[source]#

Save agent results to file.

Parameters:

output_dir – Directory to save results

update_context(key: str, value: Any)[source]#

Update agent’s context with new information.

Coordinator#

Agent Coordinator for Multi-Agent Workflow

Coordinates the execution of multiple specialized agents to complete the full geophysical processing workflow. Supports cross-modal geophysical data processing (ERT, seismic, and more) with multiple LLM API providers (GPT, Gemini, Claude).

class PyHydroGeophysX.agents.agent_coordinator.AgentCoordinator(api_key: str | None = None, output_dir: str = 'results/agents', llm_provider: str = 'openai')[source]#

Bases: object

Coordinates multiple agents to execute a complete workflow.

The coordinator manages cross-modal geophysical workflows such as: “load geophysical data → process → invert → convert to hydrologic parameters → report” with support for multiple data types (ERT, seismic, etc.) and LLM providers (GPT, Gemini, Claude).

execute_workflow(config: Dict[str, Any]) → Dict[str, Any][source]#

Execute the complete workflow with registered agents.

Parameters:

config – Configuration dictionary containing: - data_file: Path to ERT data file - instrument: Instrument type (E4D, Syscal, etc.) - inversion_params: Parameters for inversion - petrophysical_params: Parameters for water content conversion - use_seismic: Whether to include seismic processing (default: False) - seismic_data: Optional seismic data file - use_climate: Whether to include climate data (default: False) - climate_config: Climate data configuration (coords/geometry, dates, etc.) - ert_timestamps: Timestamps for ERT acquisitions (for climate alignment)

Returns:

Dictionary containing workflow results

get_workflow_summary() → Dict[str, Any][source]#

Get summary of workflow execution.

register_agent(agent_name: str, agent_instance)[source]#

Register an agent with the coordinator.

Parameters:

  • agent_name – Unique identifier for the agent

  • agent_instance – Agent instance to register

Input Agents#

ContextInputAgent#

Context Input Agent for Natural Language Workflow Configuration

Translates user’s natural language requests into structured workflow configurations. Supports multiple LLM providers (OpenAI GPT, Google Gemini, Anthropic Claude).

class PyHydroGeophysX.agents.context_input_agent.ContextInputAgent(api_key: str | None = None, model: str = 'gpt-4', llm_provider: str = 'openai')[source]#

Bases: BaseAgent

Agent that interprets natural language requests and generates workflow configurations.

This agent uses LLM to understand user intent and create appropriate configuration dictionaries for the AgentCoordinator, including parameters for: - Data loading (file paths, instruments, CRS) - Inversion settings (regularization, iterations, time-lapse mode) - Petrophysical parameters - Climate data integration - Seismic constraints - Uncertainty quantification

execute(input_data: Dict[str, Any]) → Dict[str, Any][source]#

Execute the context input agent (parse natural language request).

Parameters:

input_data – Dictionary containing: - user_request: Natural language workflow description - available_data: Optional dict with available files/instruments

Returns:

  • status: ‘success’ or ‘failed’

  • workflow_config: Generated configuration

  • explanation: Human-readable explanation

Return type:

Dictionary containing

explain_config(config: Dict[str, Any]) → str[source]#

Generate human-readable explanation of workflow configuration.

Parameters:

config – Workflow configuration dictionary

Returns:

Formatted explanation string

parse_request(user_request: str, available_data: Dict[str, Any] | None = None) → Dict[str, Any][source]#

Parse natural language request into workflow configuration.

Uses TWO focused prompts for better reliability: 1. Inversion configuration prompt (ERT-specific parameters) 2. Climate configuration prompt (meteorological parameters)

Parameters:

  • user_request – Natural language description of desired workflow

  • available_data – Optional dict with available data files, instruments, etc.

Returns:

Dict containing workflow_config ready for AgentCoordinator

suggest_improvements(config: Dict[str, Any], site_conditions: str | None = None) → str[source]#

Suggest improvements to configuration based on best practices.

Parameters:

  • config – Current workflow configuration

  • site_conditions – Optional description of site conditions

Returns:

Suggestions for improving the configuration

ERTLoaderAgent#

ERT Loader Agent

Specialized agent for loading and quality-checking ERT field data.

class PyHydroGeophysX.agents.ert_loader_agent.ERTLoaderAgent(api_key: str | None = None, model: str | None = None, llm_provider: str = 'openai')[source]#

Bases: BaseAgent

Agent specialized in loading ERT data from various instruments.

Uses PyHydroGeophysX data_processing module to load, validate, and prepare ERT data for inversion.

execute(input_data: Dict[str, Any]) → Dict[str, Any][source]#

Load and process ERT data.

Parameters:

input_data – Dictionary containing: - data_file: Path to ERT data file - instrument: Instrument type (E4D, Syscal, ABEM, etc.) - project_dir: Project directory - crs: Coordinate reference system (‘local’ or EPSG code) - quality_check: Whether to perform quality checks (default: True)

Returns:

Dictionary containing loaded ERT data and quality metrics

SeismicAgent#

ClimateDataAgent#

Processing Agents#

ERTInversionAgent#

ERT Inversion Agent

Specialized agent for performing ERT inversion with optional structural constraints.

class PyHydroGeophysX.agents.ert_inversion_agent.ERTInversionAgent(api_key: str | None = None, model: str | None = None, llm_provider: str = 'openai')[source]#

Bases: BaseAgent

Agent specialized in ERT inversion.

Uses PyHydroGeophysX inversion module to perform resistivity inversion with optional structural constraints from seismic data.

execute(input_data: Dict[str, Any]) → Dict[str, Any][source]#

Perform ERT inversion (standard or time-lapse).

Parameters:

input_data – Dictionary containing: - ert_data: Loaded ERT data (for standard inversion) - inversion_mode: ‘standard’ or ‘time-lapse’ - time_lapse_data: List of ERT datasets (for time-lapse) - time_lapse_method: ‘difference’, ‘ratio’, or ‘joint’ (for time-lapse) - temporal_regularization: Temporal smoothing weight (for time-lapse) - inversion_params: Inversion parameters (lambda, max_iter, etc.) - use_structure_constraint: Whether to use seismic structure (default: False) - seismic_structure: Optional seismic structure data - output_dir: Directory for saving results

Returns:

Dictionary containing inversion results

InversionEvaluationAgent#

Inversion Evaluation Agent

Specialized agent for evaluating ERT inversion quality and automatically adjusting regularization parameters to achieve optimal results.

class PyHydroGeophysX.agents.inversion_evaluation_agent.InversionEvaluationAgent(api_key: str | None = None, model: str | None = None, llm_provider: str = 'openai')[source]#

Bases: BaseAgent

Agent specialized in evaluating inversion quality and optimizing parameters.

This agent: 1. Evaluates inversion results using multiple quality metrics 2. Determines if results are acceptable 3. Automatically adjusts regularization parameters if needed 4. Triggers re-inversion with improved parameters

execute(input_data: Dict[str, Any]) → Dict[str, Any][source]#

Evaluate inversion results and adjust parameters if needed.

Parameters:

input_data – Dictionary containing: - inversion_results: Results from ERTInversionAgent - ert_data: Original ERT data - inversion_params: Current inversion parameters - time_lapse_data: List of ERT datasets (for time-lapse) - inversion_mode: ‘standard’ or ‘time-lapse’ - auto_adjust: Whether to automatically adjust and re-run (default: True) - max_attempts: Maximum re-inversion attempts (default: 5) - custom_thresholds: Optional custom quality thresholds

Returns:

  • status: ‘success’, ‘needs_improvement’, or ‘error’

  • quality_score: Overall quality score (0-100)

  • quality_metrics: Detailed quality metrics

  • recommendations: List of improvement recommendations

  • adjusted_params: Adjusted parameters (if auto_adjust=True)

  • final_results: Best inversion results

  • evaluation_history: History of all attempts

Return type:

Dictionary containing

TDEMAgent#

GeophysicalInversionAgent#

DataFusionAgent#

StructureConstraintAgent#

Conversion Agents#

PetrophysicsAgent#

WaterContentAgent#

Water Content Conversion Agent

Specialized agent for converting resistivity to water content using petrophysical models.

class PyHydroGeophysX.agents.water_content_agent.WaterContentAgent(api_key: str | None = None, model: str | None = None, llm_provider: str = 'openai')[source]#

Bases: BaseAgent

Agent specialized in converting resistivity to water content.

Uses PyHydroGeophysX petrophysical models and Monte Carlo uncertainty quantification to estimate water content from resistivity.

execute(input_data: Dict[str, Any]) → Dict[str, Any][source]#

Convert resistivity to water content.

Parameters:

input_data – Dictionary containing: - inversion_results: ERT inversion results - petrophysical_params: Parameters for each layer (rhos, n, porosity, etc.) - uncertainty_analysis: Whether to run Monte Carlo (default: False) - n_realizations: Number of MC realizations (default: 100) - output_dir: Directory for saving results

Returns:

Dictionary containing water content estimates and uncertainties

Output Agents#

ReportAgent#

CodeGenerationAgent#