Agent Catalogue#

The pyCSAMT agent catalogue is the navigation map for the AI-assisted workflow layer. It lists the public classes exported by pycsamt.agents, groups them by the role they play in a survey workflow, and points to the detail page where each agent is documented.

Use this page when you need to answer one of these questions:

Which agent should I start with?
Which agents can operate before inversion?
Which agents write files for Occam2D, ModEM, or MARE2DEM?
Which agents belong to the AI/model-zoo layer?
Which agents produce reports, maps, scripts, or EDI exports?

The catalogue intentionally separates agent classes from support interfaces. Modules such as web.py, __main__.py, and _pricing.py support agent usage, but they are not listed as workflow agents because they do not define an executable BaseAgent subclass.

How to read the catalogue#

Most users should think in terms of a workflow lifecycle:

request or config
    -> load survey
    -> QC and correction
    -> tensor / tipper / strike diagnostics
    -> denoise / decimate / rotate if needed
    -> forward model or inversion preparation
    -> evaluate, interpret, export, report

The agent groups follow that lifecycle. Each group page contains deeper examples and agent-specific input/output notes.

Catalogue groups#

Group	Use it for	Detail page
Foundation and survey intake	The execution contract, LLM-aware base class, result object, natural language request parsing, data loading, and explicit workflow chaining.	Foundation And Survey Intake Agents
Processing and diagnostics	Data QC, static-shift correction, tensor diagnostics, strike analysis, tipper products, tensor rotation, frequency decimation, and denoising.	Processing And Diagnostics Agents
Forward and inversion workflows	Synthetic forward modelling, inversion preparation, Occam2D, ModEM, MARE2DEM, backend execution, result evaluation, and model comparison.	Forward And Inversion Workflow Agents
AI and model-zoo agents	Neural 1-D, 2-D, and 3-D inversion, ensemble uncertainty, joint inversion, anomaly detection, and checkpoint discovery.	AI And Model-Zoo Agents
Orchestration, pipeline, and outputs	Natural-language workflow routing, pyCSAMT pipeline execution, batch processing, interpretation, maps, sensitivity, EDI export, reports, and reproducible scripts.	Orchestration, Pipeline, And Output Agents

Choosing the right entry point#

Need	Start with	Continue with
A user writes a natural-language request.	ContextInputAgent	WorkflowOrchestratorAgent or AgentCoordinator
You already know the data path.	MTLoaderAgent	DataQCAgent, StaticShiftAgent, or PhaseAnalysisAgent
You want a reproducible fixed chain.	AgentCoordinator	Any ordered set of processing, inversion, and output agents
You want the request to choose the workflow.	WorkflowOrchestratorAgent	The orchestrator builds and runs the matching chain
You want pyCSAMT pipeline presets.	PipelineAgent	Pipeline System
You need inversion-ready files.	InversionPrepAgent	Occam2DAgent, ModEmAgent, or Mare2DEMAgent
You need AI inversion.	AIInversionAgent	Inv2DAgent, Inv3DAgent, or ModelZooAgent
You need deliverables.	ReportAgent	CodeGenerationAgent and EDIExportAgent

Foundation and survey intake#

These components are the first layer of the agent system. They define how agents are built, how results are returned, and how a survey enters the workflow.

Component	Main responsibility	Typical input	Detail
BaseAgent	Shared execution base for LLM access, provider/model resolution, cost tracking, JSON extraction, plotting helpers, and validation helpers.	Subclass code	Foundation And Survey Intake Agents
AgentResult	Standard return object with `status`, `summary`, `data`, `warnings`, optional LLM interpretation, elapsed time, cost, and failure hints.	Agent output	Foundation And Survey Intake Agents
ContextInputAgent	Convert natural-language requests into structured workflow configuration. Falls back to deterministic parsing when no LLM is configured.	`request` text	Foundation And Survey Intake Agents
MTLoaderAgent	Load EDI, AVG, J, path lists, existing `Sites`, or compatible EDI collections into a validated pyCSAMT survey object.	`path` or `sites`	Foundation And Survey Intake Agents
AgentCoordinator	Chain explicit agent steps with input mapping, dry-run previews, checkpoints, and cost aggregation.	Step graph	Foundation And Survey Intake Agents

Processing and diagnostics#

Processing agents operate after loading and before inversion, interpretation, or reporting. They are useful in notebooks, desktop/web tools, batch pipelines, and orchestrated workflows.

Agent	Main responsibility	Typical output	Detail
DataQCAgent	Assess station coverage, dead bands, outliers, frequency gaps, and survey quality indicators.	QC table, figures	Processing And Diagnostics Agents
StaticShiftAgent	Detect and correct near-surface static-shift effects using supported correction strategies.	Corrected sites	Processing And Diagnostics Agents
PhaseAnalysisAgent	Produce phase-tensor, skew, strike, dimensionality, Mohr, and Argand diagnostics.	Diagnostic figures	Processing And Diagnostics Agents
TensorRotationAgent	Rotate impedance tensors to a target angle or strike reference while preserving survey metadata.	Rotated sites	Processing And Diagnostics Agents
TipperAnalysisAgent	Analyze tipper amplitude, phase, real/imaginary induction arrows, and spatial induction-vector products.	Tipper summaries	Processing And Diagnostics Agents
FrequencyDecimationAgent	Select stable, inversion-ready periods from dense, irregular, or noisy frequency sampling.	Selected periods	Processing And Diagnostics Agents
DenoisingAgent	Apply robust and AI-assisted denoising before diagnostics, inversion, or AI training.	Denoised sites	Processing And Diagnostics Agents

Forward and inversion workflows#

These agents connect processed survey data to modelling and inversion workflows. Use the general agent when you want backend-agnostic behavior, and the specialized agents when you already know the inversion code.

Agent	Main responsibility	Typical output	Detail
ForwardModelAgent	Run 1-D, 2-D, or 3-D forward modelling from resistivity models for synthetic checks and sensitivity experiments.	Forward response	Forward And Inversion Workflow Agents
InversionPrepAgent	Prepare inversion-ready files through a backend-agnostic interface.	Input directory	Forward And Inversion Workflow Agents
Occam2DAgent	Write Occam2D data, mesh, model, startup, and run-control files.	Occam2D project	Forward And Inversion Workflow Agents
ModEmAgent	Prepare ModEM 3-D impedance data files and related model inputs.	ModEM project	Forward And Inversion Workflow Agents
Mare2DEMAgent	Prepare, run, or inspect MARE2DEM 2.5-D EM inversion projects, including data, resistivity, settings, and optional MPI execution.	MARE2DEM project	Forward And Inversion Workflow Agents
InversionBackendAgent	Drive pyCSAMT inversion backends from an agent workflow rather than only writing external-code input files.	Backend result	Forward And Inversion Workflow Agents
InversionEvaluationAgent	Load inversion outputs and compute RMS, residuals, misfit sections, and quality summaries.	Evaluation report	Forward And Inversion Workflow Agents
InversionComparisonAgent	Compare inversion sections, parameter sweeps, before/after corrections, or outputs from different backends.	Comparison figures	Forward And Inversion Workflow Agents

AI and model-zoo agents#

AI agents are useful when a trained model or model-zoo checkpoint is available, when rapid approximate inversion is acceptable, or when anomaly/uncertainty screening should complement deterministic processing.

Agent	Main responsibility	Typical output	Detail
AIInversionAgent	Run end-to-end 1-D neural inversion from observed survey data.	1-D models	AI And Model-Zoo Agents
Inv2DAgent	Run 2-D profile inversion with U-Net style models and lateral continuity.	2-D section	AI And Model-Zoo Agents
Inv3DAgent	Run 3-D spatial inversion using graph-based neural models and inter-station message passing.	3-D volume	AI And Model-Zoo Agents
EnsembleAgent	Estimate uncertainty by combining multiple model predictions or ensemble members.	Uncertainty bands	AI And Model-Zoo Agents
JointInversionAgent	Run multi-modal inversion across MT, TEM, CSAMT, gravity, or paired datasets when available.	Joint model	AI And Model-Zoo Agents
AnomalyDetectionAgent	Flag anomalous station-frequency samples, unusual profiles, or survey regions needing manual review.	Anomaly table	AI And Model-Zoo Agents
ModelZooAgent	List, download, inspect, and use pre-trained EM inversion checkpoints.	Checkpoint path	AI And Model-Zoo Agents

Orchestration, pipeline, and outputs#

These agents sit above individual processing steps. They route workflows, execute batches, bridge the pyCSAMT pipeline system, and create deliverables.

Agent	Main responsibility	Typical output	Detail
WorkflowOrchestratorAgent	Classify a natural-language request, choose a workflow type, assemble a chain, and run or preview it.	Workflow result	Orchestration, Pipeline, And Output Agents
PipelineAgent	Recommend or run pyCSAMT pipeline presets and step lists from an agent workflow.	Pipeline result	Orchestration, Pipeline, And Output Agents
BatchSurveyAgent	Apply the same workflow to multiple lines, folders, or profiles with a consistent output structure.	Batch manifest	Orchestration, Pipeline, And Output Agents
InterpretationAgent	Convert resistivity, inversion, and diagnostic products into geological or hydrogeological interpretation.	Interpretation text	Orchestration, Pipeline, And Output Agents
ResistivityMapAgent	Generate horizontal depth-slice maps from inversion or resistivity products.	Map figures	Orchestration, Pipeline, And Output Agents
SensitivityAgent	Estimate depth of investigation, vertical resolution, and constrained model regions.	Sensitivity section	Orchestration, Pipeline, And Output Agents
EDIExportAgent	Export corrected, rotated, filtered, or recomputed survey objects back to standard EDI files.	EDI files	Orchestration, Pipeline, And Output Agents
ReportAgent	Assemble figures, tables, warnings, and interpretation into Markdown, HTML, or PDF reports.	Report files	Orchestration, Pipeline, And Output Agents
CodeGenerationAgent	Generate a standalone Python script from workflow configuration and outputs so interactive work can be reproduced.	Python script	Orchestration, Pipeline, And Output Agents

Typical chains#

Quality-control chain#

MTLoaderAgent
-> DataQCAgent
-> PhaseAnalysisAgent
-> ReportAgent

Correction and inversion-preparation chain#

MTLoaderAgent
-> DataQCAgent
-> StaticShiftAgent
-> TensorRotationAgent
-> FrequencyDecimationAgent
-> Occam2DAgent or ModEmAgent or Mare2DEMAgent

AI inversion chain#

MTLoaderAgent
-> DataQCAgent
-> DenoisingAgent
-> AIInversionAgent or Inv2DAgent or Inv3DAgent
-> EnsembleAgent
-> InterpretationAgent
-> ReportAgent

Batch workflow chain#

ContextInputAgent
-> WorkflowOrchestratorAgent
-> BatchSurveyAgent
-> ReportAgent
-> CodeGenerationAgent

Minimal examples#

Load and QC a survey:

from pycsamt.agents import MTLoaderAgent, DataQCAgent

loaded = MTLoaderAgent().execute({"path": "data/edis"})
qc = DataQCAgent().execute({"sites": loaded["sites"]})

print(qc.status)
print(qc.summary)

Prepare an Occam2D project from processed sites:

from pycsamt.agents import Occam2DAgent

occam = Occam2DAgent().execute({
    "sites": processed_sites,
    "output_dir": "outputs/occam2d",
    "run_external": False,
})

print(occam["output_dir"])

Run a dry-run orchestrated workflow:

from pycsamt.agents import WorkflowOrchestratorAgent

plan = WorkflowOrchestratorAgent().execute({
    "request": "Load data/edis, run QC, correct static shift, and report",
    "dry_run": True,
})

print(plan["workflow_type"])
print(plan["steps"])

Support interfaces#

The following modules support the agent system but are not workflow agents:

pycsamt.agents._pricing: Cost estimation helpers used by pycsamt.agents.AGENT_CONFIG and BaseAgent.
pycsamt.agents.web: Optional Gradio interface for interactive agent usage.
pycsamt.agents.__main__: Command-line entry point for lightweight agent demonstrations and utility commands.
pycsamt.api.agents: The global provider, key, model, pricing, and budget configuration layer. See Agent And LLM Configuration.