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.AgentResult(status: ~typing.Literal['success', 'failed', 'needs_review'], summary: str, data: ~typing.Dict[str, ~typing.Any], warnings: ~typing.List[str] = <factory>, next_suggested_action: str | None = None, llm_interpretation: str | None = None, elapsed_seconds: float = 0.0, cost_estimate_usd: float | None = None, error: str | None = None, error_fix_hint: str | None = None)[source]#

Bases: object

Standard user-facing result returned by agent workflows.

Parameters:

status ({"success", "failed", "needs_review"}) – Execution state for the agent or workflow.
summary (str) – One-sentence human-readable summary. This is always populated.
data (dict) – Numerical, object, or artifact outputs.
warnings (list of str, optional) – Non-fatal issues the user should review.
next_suggested_action (str, optional) – Suggested next step for the user.
llm_interpretation (str, optional) – AI-generated interpretation. UIs should label this before rendering.
elapsed_seconds (float, optional) – Wall-clock runtime.
cost_estimate_usd (float, optional) – Approximate LLM cost associated with this result.
error (str, optional) – Error message when status="failed".
error_fix_hint (str, optional) – Plain-language fix hint for the user.

Returns:

Dict-like result object. Existing code can continue to call result["status"] or result.get("artifact_key").

Return type:

AgentResult

Raises:

KeyError – Raised by __getitem__ when a key is not present.

Examples

>>> result = AgentResult(status="success", summary="Loaded data.", data={"n": 2})
>>> result["status"]
'success'
>>> result.get("n")
2

cost_estimate_usd: float | None = None#

data: Dict[str, Any]#

elapsed_seconds: float = 0.0#

error: str | None = None#

error_fix_hint: str | None = None#

classmethod from_dict(payload: Dict[str, Any], default_summary: str = 'Agent completed.') → AgentResult[source]#

Create an AgentResult from a legacy dictionary.

Parameters:

payload (dict) – Legacy result dictionary.
default_summary (str, optional) – Summary to use if the dictionary does not provide one.

Returns:

Normalized result object.

Return type:

AgentResult

Raises:

TypeError – If payload is not a dictionary.

Examples

>>> AgentResult.from_dict({"status": "success", "value": 1}).get("value")
1

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

items() → Iterable[Tuple[str, Any]][source]#

keys() → Iterable[str][source]#

llm_interpretation: str | None = None#

next_suggested_action: str | None = None#

status: Literal['success', 'failed', 'needs_review']#

summary: str#

to_dict(include_data_keys: bool = True) → Dict[str, Any][source]#

Return a dictionary representation.

Parameters:: include_data_keys (bool, optional) – If True, merge data into the top level for legacy callers.
Returns:: Serialized result.
Return type:: dict
Raises:: None –

Examples

>>> AgentResult("success", "ok", {"x": 1}).to_dict()["x"]
1

values() → Iterable[Any][source]#

warnings: List[str]#

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.

abstractmethod 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) → Any[source]#: Get value from agent’s context.

llm_usage_ledger: List[Dict[str, Any]]#

query_llm(prompt: str, system_message: str = 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 disk, preserving numpy arrays and PyGIMLi meshes.

numpy arrays → {agent}_{key}.npy
PyGIMLi meshes → {agent}_{key}.bms
Everything else → {agent}_results.json (metadata)

Parameters:: output_dir (str) – Target directory; created if absent.
Returns:: Path to the JSON metadata file.
Return type:: str

update_context(key: str, value: Any)[source]#: Update agent’s context with new information.

validate_input_file(file_path: Any, supported_extensions: Iterable[str], field_name: str = 'data_file', max_size_mb: float | None = None) → AgentResult | None[source]#

Validate a user-provided input file before processing.

Parameters:

file_path (Any) – Path-like value to validate.
supported_extensions (iterable of str) – Allowed file extensions, including the leading dot.
field_name (str, optional) – Name of the field being validated.
max_size_mb (float, optional) – Optional file-size limit in megabytes.

Returns:

Failure result if validation fails; otherwise None.

Return type:

AgentResult or None

Raises:

None –

Examples

>>> BaseAgent.__dict__["validate_input_file"]
<function BaseAgent.validate_input_file at ...

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], dry_run: bool = False, resume: bool = False) → 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)
dry_run – If True, return a preview plan without executing.
resume – If True, load checkpointed intermediate results and skip already-completed steps.

Returns:

Dictionary containing workflow results, or AgentResult when dry_run=True.

get_workflow_summary() → Dict[str, Any][source]#: Get summary of workflow execution.

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

Resolve and validate a workflow plan without running processing.

Parameters:: config (dict) – Workflow configuration. May include user_request or request for deterministic preview parsing.
Returns:: Preview result with resolved config, validation warnings, plan, and approximate LLM cost.
Return type:: AgentResult
Raises:: None –

Examples

>>> coordinator = AgentCoordinator(api_key=None)
>>> result = coordinator.preview_workflow({"data_file": "missing.ohm"})
>>> result["status"]
'failed'

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]) → AgentResult[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

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

Build a deterministic preview config without calling an LLM.

Parameters:

user_request (str) – Natural-language workflow request.
available_data (dict, optional) – Optional file and instrument hints supplied by the caller.

Returns:

Preview configuration with missing-field warnings.

Return type:

AgentResult

Raises:

None –

Examples

>>> agent = ContextInputAgent(api_key=None)
>>> result = agent.preview_config("Run ERT inversion on data.ohm")
>>> result.get("workflow_config")["data_file"]
'data.ohm'

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#

Seismic Data Processing Agent

Specialized agent for processing seismic refraction data and extracting velocity structures. Supports standalone seismic refraction tomography (SRT) inversion workflows.

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

Bases: BaseAgent

Agent specialized in seismic refraction tomography (SRT) processing.

Uses PyGIMLI and PyHydroGeophysX seismic processing modules to invert seismic travel time data and extract velocity interfaces for structural constraints.

Supports two modes: - ‘inversion’: Load seismic data file and run SRT inversion - ‘interface’: Extract velocity interfaces from existing velocity model

Example

>>> agent = SeismicAgent()
>>> result = agent.execute({
...     'seismic_file': 'seismic_data.dat',
...     'velocity_threshold': 1200,
...     'output_dir': 'results/seismic'
... })

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

Process seismic data and extract velocity structure.

Parameters:: input_data – Dictionary containing seismic_file or pre-loaded seismic_data, optional velocity thresholds, inversion parameters, an output directory, and an extract_interfaces flag. Supported inversion parameters include lam, zWeight, vTop, vBottom, paraDepth, paraMaxCellSize, and limits.
Returns:: Dictionary containing velocity model, mesh, interfaces, and visualizations

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: 3) - quality_threshold: Overall quality threshold (default: 70) - progress_callback: Optional callback for transparent loop logs - custom_thresholds: Optional custom quality thresholds

Returns:

status: ‘success’, ‘needs_review’, or ‘failed’
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#

TDEM (Time-Domain Electromagnetic) Agent

Agent for processing Time-Domain Electromagnetic data using SimPEG. Supports forward modeling, inversion, and integration with hydrological models.

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

Bases: BaseAgent

Agent for Time-Domain Electromagnetic (TDEM) data processing.

This agent provides functionality for: - Loading TDEM sounding data from text files - Forward modeling from hydrological models (MODFLOW, ParFlow) - 1D TDEM inversion with L2 and sparse (IRLS) regularization - Petrophysical conversion between water content and conductivity - Visualization and reporting

Example

>>> agent = TDEMAgent()
>>> result = agent.execute({
...     'data_file': 'tdem_data.txt',
...     'source_radius': 10.0,
...     'n_layers': 20,
...     'output_dir': 'results/tdem'
... })

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

Execute TDEM workflow based on input configuration.

Parameters:

input_data –

Dictionary containing: - data_file: Path to TDEM data file (optional if forward modeling) - mode: ‘inversion’, ‘forward’, or ‘hydro_to_tdem’ - source_radius: Loop radius in meters (default: 10) - n_layers: Number of layers for inversion (default: 20) - output_dir: Output directory for results - use_irls: Use sparse regularization (default: True)

For forward modeling: - thicknesses: Layer thicknesses (m) - conductivity: Layer conductivities (S/m)

For hydro_to_tdem: - water_content: Water content array - porosity: Porosity array - layer_thicknesses: Layer thicknesses (m) - petrophysical_params: Petrophysical parameters

Returns:

Dictionary containing results based on mode

GeophysicalInversionAgent#

Unified geophysical inversion agent for SRT and FDEM workflows.

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

Bases: BaseAgent

Agent for multi-method inversion orchestration.

Supports SRT and FDEM natively and delegates ERT to ERTInversionAgent.

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

DataFusionAgent#

Data Fusion Agent

Intelligent coordinator for multi-method geophysical workflows. This agent understands which geophysical methods should work together and orchestrates complex data fusion workflows like seismic-constrained ERT inversion.

The DataFusionAgent is designed to be extensible for future multi-method combinations.

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

Bases: BaseAgent

Agent for intelligent coordination of multi-method geophysical workflows.

This agent understands common geophysical data fusion patterns and can recommend and execute appropriate multi-method workflows based on user requirements.

Supported Fusion Patterns:

ERT + Seismic: Structure-constrained resistivity inversion
ERT + Gravity: Density-constrained models
Multiple Time-Lapse: Joint temporal inversion
(Extensible for future methods)

FUSION_PATTERNS = {'full_integration': {'benefits': 'Complete geological-to-hydrological workflow with constraints', 'description': 'Structure-constrained ERT with hydrological conversion', 'methods': ['seismic', 'ert', 'petrophysics'], 'workflow': ['seismic_inversion', 'interface_extraction', 'constrained_ert', 'petrophysics_conversion']}, 'petrophysics_integration': {'benefits': 'Direct hydrological interpretation from geophysical data', 'description': 'Convert resistivity to hydrological properties', 'methods': ['ert', 'petrophysics'], 'workflow': ['ert_inversion', 'petrophysics_conversion']}, 'structure_constraint': {'benefits': 'Improved layer boundary resolution and reduced artifacts', 'description': 'Use seismic velocity interfaces to constrain ERT inversion', 'methods': ['seismic', 'ert'], 'workflow': ['seismic_inversion', 'interface_extraction', 'constrained_ert']}}#

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

Execute multi-method data fusion workflow.

Parameters:: input_data – Dictionary containing: - fusion_pattern: Name of fusion pattern or ‘auto’ for LLM recommendation - methods: List of available methods (e.g., [‘seismic’, ‘ert’]) - workflow_config: Configuration for the fusion workflow - data: Dictionary of data for each method - output_dir: Directory for saving results
Returns:: Dictionary containing fused results and workflow metadata

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

Execute the complete multi-method data fusion workflow, not just planning.

This method actually runs the agents and produces results, unlike execute() which only creates a plan.

Parameters:: input_data – Dictionary containing: - fusion_pattern: Name of fusion pattern - methods: List of available methods - workflow_config: Configuration for the fusion workflow - data: Dictionary of data for each method - output_dir: Directory for saving results
Returns:: Dictionary containing complete workflow results

get_available_patterns() → Dict[str, Dict][source]#

Get information about all available fusion patterns.

Returns:: Dictionary of fusion patterns with descriptions

validate_workflow(available_methods: List[str], desired_pattern: str) → Dict[str, Any][source]#

Validate if a desired fusion pattern can be executed with available methods.

Parameters:

available_methods – List of available methods
desired_pattern – Desired fusion pattern name

Returns:

Validation result dictionary

StructureConstraintAgent#

Structure Constraint Agent

Applies seismic velocity interfaces as structural constraints to ERT inversion. Implements the workflow from Ex_Structure_resinv.py for creating structure-constrained resistivity models.

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

Bases: BaseAgent

Agent for applying structural constraints from seismic data to ERT inversion.

This agent creates ERT meshes that honor geological boundaries derived from seismic velocity interfaces, leading to more accurate resistivity models that preserve sharp layer contrasts.

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

Execute structure-constrained ERT inversion.

Parameters:: input_data – Dictionary containing: - ert_data: ERT measurement data - seismic_data: (Optional) Seismic traveltime data for interface extraction - interface_coords: (Optional) Tuple of (x, z) coordinates from seismic - velocity_threshold: (Optional) Velocity threshold for interface extraction - seismic_params: (Optional) Parameters for seismic inversion - inversion_params: ERT inversion parameters - output_dir: Directory for saving results - mesh_quality: Mesh quality parameter (default: 31)
Returns:: Dictionary containing constrained resistivity model and mesh

Conversion Agents#

PetrophysicsAgent#

Petrophysics Agent

Converts resistivity models to hydrological properties (water content, saturation, porosity) using structure-constrained petrophysical models with Monte Carlo uncertainty quantification. Implements the workflow from Ex_MC_Hydro.py.

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

Bases: BaseAgent

Agent for converting resistivity to hydrological properties with uncertainty.

This agent uses Archie’s law and modified petrophysical models to convert resistivity to water content, incorporating: - Layer-specific parameters from structural constraints - Monte Carlo uncertainty quantification - Surface conductivity effects in clay-rich materials

DEFAULT_LAYER_PARAMS = {'bedrock': {'m': {'mean': 1.9, 'std': 0.2}, 'n': {'mean': 1.7, 'std': 0.2}, 'porosity': {'mean': 0.25, 'std': 0.15}, 'rho_fluid': 20.0, 'sigma_sur': {'mean': 0.0, 'std': 0.0}}, 'regolith': {'m': {'mean': 1.3, 'std': 0.1}, 'n': {'mean': 2.1, 'std': 0.1}, 'porosity': {'mean': 0.42, 'std': 0.05}, 'rho_fluid': 20.0, 'sigma_sur': {'mean': 0.005, 'std': 0.005}}}#

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

Convert resistivity to water content with uncertainty quantification.

Parameters:: input_data – Dictionary containing: - resistivity_model: Resistivity values (can be 1D or 2D for time-lapse) - mesh: PyGIMLI mesh with cell markers - cell_markers: Array identifying geological layers - layer_params: Dictionary of parameters for each layer (optional) - n_realizations: Number of Monte Carlo samples (default: 100) - output_dir: Directory for saving results
Returns:: Dictionary containing water content statistics and uncertainty

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#

Deterministic workflow code export with optional LLM explanation.

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

Bases: BaseAgent

Export reproducible workflow code without asking an LLM to write code.

LLM access is limited to prose explanations and parameter suggestions. The executable file always comes from the versioned workflow generator.

check_request_scope(user_request: str, workflow_config: Dict[str, Any]) → Dict[str, Any][source]#: Report whether a serializable registered workflow was supplied.

execute(input_data: Dict[str, Any]) → Dict[str, Any][source]#: Validate a spec and export its recipe plus deterministic Python.

explain_recipe(spec: WorkflowSpec, *, user_request: str = '') → str[source]#: Optionally ask the LLM for prose; never use its response as code.

suggest_parameters(spec: WorkflowSpec, user_request: str) → str[source]#: Return advisory suggestions without mutating the recipe.