# zhengyangfang/geosage architecture

> Architecture diagram of the GitHub repository zhengyangfang/geosage, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zhengyangfang/geosage
- Repository: https://github.com/zhengyangfang/geosage

## Overview

GeoSAGE is a geophysical modeling and interpretation package, with an optional PyHydroGeophysX Professional Studio assistant. The primary workflow accepts a case configuration and local survey data, runs or reuses a gravity–magnetic inversion, builds pseudo-geological models, then prepares interpretation and reports. Studio adds task planning, approvals, visualization, and provider-backed review; notebooks and shared plotting support assessment and presentation. Edges are limited to README statements and relationships visible in the supplied excerpts or SOURCE INDEX; unsampled implementations are represented without speculative links.

Main entry points: [`src/geosage/runner.py`](https://github.com/zhengyangfang/geosage/blob/main/src/geosage/runner.py) (Workflow Runner), [`src/geosage/multi_agent_runner.py`](https://github.com/zhengyangfang/geosage/blob/main/src/geosage/multi_agent_runner.py) (Agent Interpretation), [`src/geosage/pyhydrogeophysx/tools.py`](https://github.com/zhengyangfang/geosage/blob/main/src/geosage/pyhydrogeophysx/tools.py) (Workflow Tools), [`src/geosage/existing_results.py`](https://github.com/zhengyangfang/geosage/blob/main/src/geosage/existing_results.py) (Existing Results)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Workflow Orchestration"]
  node_config["Run Configuration"]
  node_runner["Workflow Runner<br/>[runner.py]"]
end

subgraph group_science["Scientific Modeling"]
  node_inversion["Joint Inversion"]
  node_archive["Existing Results"]
  node_geology["Geological Modeling"]
  node_outputs[("Models and Results")]
end

subgraph group_interpret["Interpretation"]
  node_agents["Agent Interpretation"]
  node_evidence["Evidence Bundles<br/>[evidence_bundle.py]"]
  node_compare["Interpretation Comparison"]
  node_survey["Study Area Survey<br/>[studio_survey.py]"]
end

subgraph group_studio["Studio Integration"]
  node_studio_config["Studio Configuration<br/>[configuration.py]"]
  node_lifecycle["Task Lifecycle<br/>[lifecycle.py]"]
  node_studio_workflow["Studio Workflow<br/>[workflow.py]"]
  node_tools["Workflow Tools<br/>[tools.py]"]
  node_visualization["Result Visualization<br/>[visualization.py]"]
  node_providers["LLM Providers<br/>[providers.py]"]
end

subgraph group_support["Shared Support"]
  node_workspace["Workspace Paths<br/>[paths.py]"]
  node_validation["Input Validation<br/>[validation.py]"]
  node_plots["Scientific Figures<br/>[paper.py]"]
  node_scales["Display Scales<br/>[scales.py]"]
end

node_user(("Researcher"))
node_host(("Professional Studio"))

node_user -->|"specifies run"| node_config
node_config -->|"configures"| node_runner
node_runner -->|"runs inversion"| node_inversion
node_runner -->|"loads existing"| node_archive
node_runner -->|"builds geology"| node_geology
node_inversion -->|"writes models"| node_outputs
node_archive -->|"loads models"| node_outputs
node_runner -.->|"enables interpretation"| node_agents
node_agents -->|"prepares evidence"| node_evidence
node_agents -->|"reuses results"| node_archive
node_compare -->|"uses agents"| node_agents
node_compare -->|"loads results"| node_archive
node_runner -->|"resolves paths"| node_workspace
node_runner -.->|"validates inputs"| node_validation
node_geology -->|"validates models"| node_validation
node_plots -->|"uses scales"| node_scales
node_host -->|"provides task inputs"| node_studio_config
node_studio_config -->|"builds run config"| node_runner
node_studio_workflow -->|"uses lifecycle"| node_lifecycle
node_studio_workflow -->|"dispatches tools"| node_tools
node_lifecycle -->|"plans tools"| node_tools
node_tools -->|"runs workflow"| node_runner
node_tools -->|"exports results"| node_visualization
node_visualization -->|"renders figures"| node_plots
node_providers -->|"backs LLM"| node_agents
node_survey -.->|"assesses study data"| node_outputs

click node_config "https://github.com/zhengyangfang/geosage/tree/main/configs"
click node_runner "https://github.com/zhengyangfang/geosage/blob/main/src/geosage/runner.py"
click node_inversion "https://github.com/zhengyangfang/geosage/blob/main/src/geosage/gravity_mag_joint_inversion.py"
click node_archive "https://github.com/zhengyangfang/geosage/blob/main/src/geosage/existing_results.py"
click node_geology "https://github.com/zhengyangfang/geosage/blob/main/src/geosage/geo_modeling_workflow.py"
click node_agents "https://github.com/zhengyangfang/geosage/blob/main/src/geosage/multi_agent_runner.py"
click node_evidence "https://github.com/zhengyangfang/geosage/blob/main/src/geosage/evidence_bundle.py"
click node_compare "https://github.com/zhengyangfang/geosage/blob/main/src/geosage/compare_interpretations.py"
click node_survey "https://github.com/zhengyangfang/geosage/blob/main/src/geosage/studio_survey.py"
click node_workspace "https://github.com/zhengyangfang/geosage/blob/main/src/geosage/paths.py"
click node_validation "https://github.com/zhengyangfang/geosage/blob/main/src/geosage/validation.py"
click node_plots "https://github.com/zhengyangfang/geosage/blob/main/src/geosage/plotting/paper.py"
click node_scales "https://github.com/zhengyangfang/geosage/blob/main/src/geosage/plotting/scales.py"
click node_studio_config "https://github.com/zhengyangfang/geosage/blob/main/src/geosage/pyhydrogeophysx/configuration.py"
click node_lifecycle "https://github.com/zhengyangfang/geosage/blob/main/src/geosage/pyhydrogeophysx/lifecycle.py"
click node_studio_workflow "https://github.com/zhengyangfang/geosage/blob/main/src/geosage/pyhydrogeophysx/workflow.py"
click node_tools "https://github.com/zhengyangfang/geosage/blob/main/src/geosage/pyhydrogeophysx/tools.py"
click node_visualization "https://github.com/zhengyangfang/geosage/blob/main/src/geosage/pyhydrogeophysx/visualization.py"
click node_providers "https://github.com/zhengyangfang/geosage/blob/main/src/geosage/pyhydrogeophysx/providers.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_config,node_runner toneBlue
class node_inversion,node_archive,node_geology,node_outputs toneAmber
class node_agents,node_evidence,node_compare,node_survey toneMint
class node_studio_config,node_lifecycle,node_studio_workflow,node_tools,node_visualization,node_providers toneRose
class node_workspace,node_validation,node_plots,node_scales,node_user,node_host toneIndigo
```

## Components

### Workflow Orchestration

- [Run Configuration](https://github.com/zhengyangfang/geosage/tree/main/configs): `configs`
- [Workflow Runner](https://github.com/zhengyangfang/geosage/blob/main/src/geosage/runner.py): `src/geosage/runner.py`

### Scientific Modeling

- [Joint Inversion](https://github.com/zhengyangfang/geosage/blob/main/src/geosage/gravity_mag_joint_inversion.py): `src/geosage/gravity_mag_joint_inversion.py`
- [Existing Results](https://github.com/zhengyangfang/geosage/blob/main/src/geosage/existing_results.py): `src/geosage/existing_results.py`
- [Geological Modeling](https://github.com/zhengyangfang/geosage/blob/main/src/geosage/geo_modeling_workflow.py): `src/geosage/geo_modeling_workflow.py`
- **Models and Results**

### Interpretation

- [Agent Interpretation](https://github.com/zhengyangfang/geosage/blob/main/src/geosage/multi_agent_runner.py): `src/geosage/multi_agent_runner.py`
- [Evidence Bundles](https://github.com/zhengyangfang/geosage/blob/main/src/geosage/evidence_bundle.py): `src/geosage/evidence_bundle.py`
- [Interpretation Comparison](https://github.com/zhengyangfang/geosage/blob/main/src/geosage/compare_interpretations.py): `src/geosage/compare_interpretations.py`
- [Study Area Survey](https://github.com/zhengyangfang/geosage/blob/main/src/geosage/studio_survey.py): `src/geosage/studio_survey.py`

### Studio Integration

- [Studio Configuration](https://github.com/zhengyangfang/geosage/blob/main/src/geosage/pyhydrogeophysx/configuration.py): `src/geosage/pyhydrogeophysx/configuration.py`
- [Task Lifecycle](https://github.com/zhengyangfang/geosage/blob/main/src/geosage/pyhydrogeophysx/lifecycle.py): `src/geosage/pyhydrogeophysx/lifecycle.py`
- [Studio Workflow](https://github.com/zhengyangfang/geosage/blob/main/src/geosage/pyhydrogeophysx/workflow.py): `src/geosage/pyhydrogeophysx/workflow.py`
- [Workflow Tools](https://github.com/zhengyangfang/geosage/blob/main/src/geosage/pyhydrogeophysx/tools.py): `src/geosage/pyhydrogeophysx/tools.py`
- [Result Visualization](https://github.com/zhengyangfang/geosage/blob/main/src/geosage/pyhydrogeophysx/visualization.py): `src/geosage/pyhydrogeophysx/visualization.py`
- [LLM Providers](https://github.com/zhengyangfang/geosage/blob/main/src/geosage/pyhydrogeophysx/providers.py): `src/geosage/pyhydrogeophysx/providers.py`

### Shared Support

- [Workspace Paths](https://github.com/zhengyangfang/geosage/blob/main/src/geosage/paths.py): `src/geosage/paths.py`
- [Input Validation](https://github.com/zhengyangfang/geosage/blob/main/src/geosage/validation.py): `src/geosage/validation.py`
- [Scientific Figures](https://github.com/zhengyangfang/geosage/blob/main/src/geosage/plotting/paper.py): `src/geosage/plotting/paper.py`
- [Display Scales](https://github.com/zhengyangfang/geosage/blob/main/src/geosage/plotting/scales.py): `src/geosage/plotting/scales.py`

### Other components

- **Researcher**
- **Professional Studio**

## Connections

- Researcher → Run Configuration: specifies run (evidence: `README.md`)
- Run Configuration → Workflow Runner: configures (evidence: `README.md`)
- Workflow Runner → Joint Inversion: runs inversion (evidence: `src/geosage/runner.py`)
- Workflow Runner → Existing Results: loads existing (evidence: `src/geosage/runner.py`)
- Workflow Runner → Geological Modeling: builds geology (evidence: `src/geosage/runner.py`)
- Joint Inversion → Models and Results: writes models (evidence: `src/geosage/gravity_mag_joint_inversion.py`)
- Existing Results → Models and Results: loads models (evidence: `src/geosage/existing_results.py`)
- Workflow Runner → Agent Interpretation: enables interpretation (evidence: `src/geosage/multi_agent_runner.py`)
- Agent Interpretation → Evidence Bundles: prepares evidence (evidence: `src/geosage/multi_agent_runner.py`)
- Agent Interpretation → Existing Results: reuses results (evidence: `src/geosage/multi_agent_runner.py`)
- Interpretation Comparison → Agent Interpretation: uses agents (evidence: `src/geosage/compare_interpretations.py`)
- Interpretation Comparison → Existing Results: loads results (evidence: `src/geosage/compare_interpretations.py`)
- Workflow Runner → Workspace Paths: resolves paths (evidence: `src/geosage/runner.py`)
- Workflow Runner → Input Validation: validates inputs
- Geological Modeling → Input Validation: validates models (evidence: `src/geosage/geo_modeling_workflow.py`)
- Scientific Figures → Display Scales: uses scales (evidence: `src/geosage/plotting/paper.py`)
- Professional Studio → Studio Configuration: provides task inputs (evidence: `README.md`)
- Studio Configuration → Workflow Runner: builds run config (evidence: `src/geosage/pyhydrogeophysx/configuration.py`)
- Studio Workflow → Task Lifecycle: uses lifecycle (evidence: `src/geosage/pyhydrogeophysx/workflow.py`)
- Studio Workflow → Workflow Tools: dispatches tools (evidence: `src/geosage/pyhydrogeophysx/workflow.py`)
- Task Lifecycle → Workflow Tools: plans tools (evidence: `src/geosage/pyhydrogeophysx/lifecycle.py`)
- Workflow Tools → Workflow Runner: runs workflow (evidence: `src/geosage/pyhydrogeophysx/tools.py`)
- Workflow Tools → Result Visualization: exports results (evidence: `src/geosage/pyhydrogeophysx/tools.py`)
- Result Visualization → Scientific Figures: renders figures (evidence: `src/geosage/pyhydrogeophysx/visualization.py`)
- LLM Providers → Agent Interpretation: backs LLM (evidence: `src/geosage/pyhydrogeophysx/providers.py`)
- Study Area Survey → Models and Results: assesses study data
