Quick Start Guide#

This guide will help you get started with the PyHydroGeophysX multi-agent system in just a few minutes.

Installation#

The agent system requires an API key from your preferred LLM provider:

# Set your API key as an environment variable
export OPENAI_API_KEY="your-api-key-here"
# or
export GEMINI_API_KEY="your-api-key-here"
# or
export ANTHROPIC_API_KEY="your-api-key-here"

Pass the key to the agents you create, as the examples below do (api_key=os.environ.get('OPENAI_API_KEY')), or pass api_key="env" to have an agent read its provider’s variable. An agent given no key runs without a model whatever the environment holds, so a library call never spends credit you did not ask it to; when a key is set but not passed, it warns once.

Try Without an API Key#

The Streamlit app opens with demo mode off; switch on Demo mode at the top of the sidebar to load bundled cached results, make no LLM calls, and inspect the expected outputs before uploading your own data. The hosted app:

https://pyhydrogeophysx.streamlit.app/

To preview a local agent workflow without running an inversion or interpretation step, use the dry-run mode:

from PyHydroGeophysX.agents import AgentCoordinator
coordinator = AgentCoordinator(api_key=None)
result = coordinator.execute_workflow(
    {"user_request": "Run ERT inversion on examples/data/ERT/E4D/2021-10-08_1400.ohm"},
    dry_run=True,
)
# result contains: execution_plan, validation_warnings, cost_estimate_usd

For a local no-LLM smoke test that runs a short ERT inversion on a bundled field line (about 10 seconds on a laptop CPU), run this from the repository root:

from PyHydroGeophysX.inversion.ert_inversion import run_ert_manager_inversion

result = run_ert_manager_inversion(
    "examples/data/ERT/Bert/fielddataline2.dat", "out_cpu", max_iterations=4
)
print(result["engine"], result["chi2"])

Launch the 3D Mesh Builder#

A dedicated interactive GUI for building 3D ERT meshes ships with the package:

# Recommended: via the package launcher
python -m PyHydroGeophysX.gui_mesh3d

# Or run directly with Streamlit
streamlit run examples/app_mesh3d.py

The app opens in your browser with three tabs: Electrode View (interactive 3D preview), Generate Mesh (runs Mesh3DCreator), and Export (.bms / .vtk download). See Agent Web App for the full step-by-step guide.

Dry-Run / Preview Workflow#

Before committing to a full inversion run, use dry_run=True (or resume=True to skip completed steps after a failure):

from PyHydroGeophysX.agents import AgentCoordinator

coordinator = AgentCoordinator(api_key=None, output_dir='./results')
config = {"data_file": "field_ert.ohm", "instrument": "E4D"}

# Preview: validates files, checks dependencies, estimates LLM cost
preview = coordinator.execute_workflow(config, dry_run=True)
print(preview["data"]["execution_plan"])
print(preview["data"]["validation_warnings"])
print(f"Est. cost: ${preview['cost_estimate_usd']:.4f}")

# Resume a previously interrupted run (skips checkpointed steps)
results = coordinator.execute_workflow(config, resume=True)

Basic Usage#

The simplest way to use the agent system is through the AgentCoordinator:

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

api_key = os.environ.get('OPENAI_API_KEY')
coordinator = AgentCoordinator(api_key=api_key, output_dir='./results')

coordinator.register_agent('context', ContextInputAgent(api_key))
coordinator.register_agent('ert_loader', ERTLoaderAgent(api_key))
coordinator.register_agent('ert_inversion', ERTInversionAgent(api_key))
coordinator.register_agent('water_content', WaterContentAgent(api_key))
coordinator.register_agent('report', ReportAgent(api_key))

config = {
    'data_file': 'data/field_ert.ohm',
    'instrument': 'E4D',
    'inversion_params': {'lambda': 20, 'max_iter': 10},
}

results = coordinator.execute_workflow(config)

# Check LLM cost after the run
summary = coordinator.get_workflow_summary()
print(f"Total LLM cost: ${summary['total_llm_cost_estimate_usd']:.4f}")
print(f"Tokens used:    {summary['total_llm_tokens']}")
print(f"LLM calls:      {summary['llm_calls']}")

Natural Language Interface#

Describe your workflow in plain English and let ContextInputAgent translate it:

from PyHydroGeophysX.agents import ContextInputAgent
import os

context = ContextInputAgent(api_key=os.environ['OPENAI_API_KEY'])

request = """
I have ERT data from a Syscal Pro instrument.
The data file is data/field_data.bin. I want to perform
a standard inversion with moderate smoothing and then convert the
resistivity to water content using Archie's law with porosity 0.35.
"""

result = context.execute({'user_request': request})
workflow_config = result['workflow_config']

Example: Standard ERT Workflow#

from PyHydroGeophysX.agents import (
    ERTLoaderAgent, ERTInversionAgent,
    InversionEvaluationAgent, WaterContentAgent,
)
import os

api_key = os.environ.get('OPENAI_API_KEY')

# Step 1: Load ERT data
loader = ERTLoaderAgent(api_key)
data_result = loader.execute({
    'data_file': 'data/field_ert.ohm',
    'instrument': 'E4D',
    'quality_check': True,
})

# Step 2: Invert
inverter = ERTInversionAgent(api_key)
inv_result = inverter.execute({
    'ert_data': data_result['ert_data'],
    'inversion_mode': 'standard',
    'inversion_params': {'lambda': 20, 'max_iter': 10},
})

# Step 3: Evaluate and auto-optimize if chi² is poor
evaluator = InversionEvaluationAgent(api_key)
eval_result = evaluator.execute({
    'inversion_results': inv_result,
    'ert_data': data_result['ert_data'],
    'auto_adjust': True,
})

# Step 4: Convert to water content
converter = WaterContentAgent(api_key)
wc_result = converter.execute({
    'inversion_results': eval_result['final_results'],
    'petrophysical_params': {
        'layer1': {'porosity': 0.35, 'n': 2.0, 'm': 1.5},
    },
})

print(f"Water content range: {wc_result['statistics']}")

# Step 5: Save results (numpy arrays → .npy, meshes → .bms)
converter.save_results('./results/water_content')

Example: Multi-Method Fusion#

Combining seismic and ERT data with structural constraints:

from PyHydroGeophysX.agents import DataFusionAgent
import os

fusion = DataFusionAgent(api_key=os.environ.get('OPENAI_API_KEY'))

pattern_result = fusion.execute({
    'fusion_pattern': 'structure_constraint',
    'methods': ['seismic', 'ert'],
    'data': {'seismic': 'data/seismic.sgt', 'ert': 'data/ert.ohm'},
})
# DataFusionAgent creates a structured execution plan and runs it end-to-end.

Next Steps#