Add GPT API-based multi-agent system for automated ERT workflows

[Copilot]

Implements an AI-powered orchestration system for the complete geophysical processing pipeline: load ERT → invert → convert to water content → report, with optional seismic integration for structure-constrained inversion.

Architecture

AgentCoordinator orchestrates workflow execution with state management and error recovery.

Five specialized agents:

• ERTLoaderAgent - Multi-format data loading (14+ instruments) with AI quality assessment
• ERTInversionAgent - Resistivity inversion with GPT-4 parameter recommendations
• WaterContentAgent - Petrophysical conversion with Monte Carlo uncertainty
• SeismicAgent - Travel time inversion and interface extraction for structural constraints
• ReportAgent - Markdown/HTML report generation with visualizations

Key Implementation Details

• BaseAgent provides configurable LLM integration (gpt-4, gpt-3.5-turbo, etc.)
• Graceful degradation without API key using sensible defaults
• Robust LLM response parsing with regex fallbacks
• Type-safe array operations with proper numpy checks
• Optional dependency: openai>=1.0.0 in setup.py extras

Usage

from PyHydroGeophysX.agents import (
    AgentCoordinator, ERTLoaderAgent, ERTInversionAgent,
    WaterContentAgent, ReportAgent, SeismicAgent
)

coordinator = AgentCoordinator(api_key=os.getenv('OPENAI_API_KEY'))
coordinator.register_agent('ert_loader', ERTLoaderAgent())
coordinator.register_agent('ert_inversion', ERTInversionAgent())
coordinator.register_agent('water_content', WaterContentAgent())
coordinator.register_agent('seismic_processor', SeismicAgent())  # optional
coordinator.register_agent('report', ReportAgent())

results = coordinator.execute_workflow({
    'data_file': 'survey.dat',
    'instrument': 'E4D',
    'run_uncertainty': True,
    'n_realizations': 100,
    'use_seismic': True,  # enables structure-constrained inversion
    'velocity_threshold': 1200
})

Files Added

• PyHydroGeophysX/agents/ - Complete agent system (~1,865 LOC)
• examples/Ex_multi_agent_workflow.py - Working demonstrations
• PyHydroGeophysX/agents/README.md - API documentation

Integration

• Uses existing data_processing.ert_data_agent for loading
• Delegates to inversion.ert_inversion for computation
• Leverages Geophy_modular.ERT_to_WC for petrophysics
• Integrates Geophy_modular.seismic_processor for constraints

System works with or without OpenAI API key - LLM features enhance but don't gate core functionality.

Original prompt

I want to use GPT API to create multiple agents to “load ERT → invert → convert to water content → report,” aligned with your PyHydroGeophysX structure. you can read all of my examples. also if seismic data existed, we can have addional agent to get it into process

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[geohang]

This is for adding agent function to my code!

[geohang]

@copilot not only ERT, in the future, it can get other geophysical data into hydrologic information. I want to use this agent to publish a paper like "Automatic cross‑modal geophysics agent for subsurface hydrology." so update the describiton. also not only GPT API. we can also add others like gemimi and claude