PyHydroGeophysX.agents package

Submodules

PyHydroGeophysX.agents.agent_coordinator module

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

PyHydroGeophysX.agents.base_agent module

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.

PyHydroGeophysX.agents.climate_data_agent module

PyHydroGeophysX.agents.code_generation_agent module

PyHydroGeophysX.agents.context_input_agent module

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

PyHydroGeophysX.agents.data_fusion_agent module

PyHydroGeophysX.agents.data_fusion_agent-HChen-W24 module

PyHydroGeophysX.agents.ert_inversion_agent module

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

PyHydroGeophysX.agents.ert_loader_agent module

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

PyHydroGeophysX.agents.inversion_evaluation_agent module

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

PyHydroGeophysX.agents.petrophysics_agent module

PyHydroGeophysX.agents.report_agent module

PyHydroGeophysX.agents.seismic_agent module

PyHydroGeophysX.agents.structure_constraint_agent module

PyHydroGeophysX.agents.tdem_agent module

PyHydroGeophysX.agents.water_content_agent module

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

PyHydroGeophysX.agents.workflow_orchestrator_agent module

Module contents