System Overview#

The PyHydroGeophysX multi-agent system runs geophysical workflows in subsurface hydrology from a request written in natural language: a Large Language Model (LLM) reads the request, and the system carries out the processing steps it calls for.

Who This Is For#

  • Hydrogeophysics researchers who know the science but may not know this codebase should start with Quick Start Guide and the Python API examples.

  • Graduate students and non-experts running field data should start with the Agent Web App, especially demo mode before using their own uploads.

  • Reviewers and collaborators evaluating the project should start with Agent Web App, then use Common Workflow Patterns and Agent Reference to inspect the supported workflow surface.

Design Principles#

Specialization

Each agent handles one specific task (data loading, inversion, conversion, etc.) with expert-level knowledge encoded in its system prompt.

Coordination

The AgentCoordinator orchestrates multi-agent workflows, managing state and data flow between agents.

Extensibility

New agents are added by inheriting from BaseAgent and implementing the execute() method.

LLM Integration

Natural language interfaces allow non-expert users to describe complex workflows without programming knowledge.

Uncertainty Quantification

Monte Carlo methods are built into conversion agents to propagate parameter uncertainties through the analysis pipeline.

Supported LLM Providers#

The system supports multiple LLM providers:

  • OpenAI GPT (the GPT-5.6 family, and the GPT-4.x names)

  • Google Gemini (Gemini 2.5)

  • Anthropic Claude (Claude Haiku 4.5, Sonnet 5, Opus 5)

  • Any OpenAI-compatible endpoint (DeepSeek, OpenRouter, a local server)

Each provider is configured with an API key; without one, the LLM features are unavailable and the rest of the system keeps working.

For OpenAI and Anthropic the chat surfaces do not ask you to name a model. They offer a three-step request level instead — level 1 for the simple majority of requests, level 2 for coding, reasoning, and agent work, level 3 for what the levels below could not finish — and resolve the level to a model per provider. The ladder lives in PyHydroGeophysX.llm.providers.MODEL_TIERS, so the desktop studio and the web app always offer the same levels; see Choosing a Request Level for the models and their prices.

Agent Hierarchy#

┌─────────────────────────────────────────────────────────────────┐
│                      AgentCoordinator                           │
│  (Orchestrates multi-agent workflows, manages state)            │
└──────────────────────┬──────────────────────────────────────────┘
                       │
         ┌─────────────┼─────────────┐
         │             │             │
    ┌────▼────┐   ┌────▼────┐   ┌───▼────┐
    │ Input   │   │ Process │   │ Output │
    │ Agents  │   │ Agents  │   │ Agents │
    └─────────┘   └─────────┘   └────────┘

Agent Categories#

Input/Configuration Agents#

  • ContextInputAgent - Parses natural language requests into structured configurations

  • ERTLoaderAgent - Loads ERT field data from various commercial instruments

  • SeismicAgent - Processes seismic refraction data

  • ClimateDataAgent - Fetches climate data for temporal analysis

Processing/Inversion Agents#

  • ERTInversionAgent - Performs standard and time-lapse ERT inversions

  • InversionEvaluationAgent - Evaluates quality and optimizes parameters

  • TDEMAgent - Performs TDEM forward modeling and inversion

  • DataFusionAgent - Coordinates multi-method data fusion

  • StructureConstraintAgent - Applies seismic constraints to ERT inversion

Conversion/Analysis Agents#

  • PetrophysicsAgent - Layer-specific resistivity to water content conversion

  • WaterContentAgent - General petrophysical conversion

Output/Reporting Agents#

  • ReportAgent - Generates reports with figures

Benefits#

For Researchers

Automate repetitive processing tasks while maintaining full control over parameters and methods.

For Practitioners

Access expert-level analysis without deep programming expertise through natural language interfaces.

For Educators

Demonstrate complete geophysical workflows with reproducible steps and a report of each run.