# opendatalab/earth-agent architecture

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

- Interactive diagram: https://gitdiagram.com/opendatalab/earth-agent
- Repository: https://github.com/opendatalab/earth-agent

## Overview

Earth-Agent is an Earth-observation question-answering and evaluation framework. In the principal workflow, a user’s question and data are handled by a LangChain ReAct agent, which can call MCP tools for index, inversion, perception, and statistical analysis before returning an answer. The repository also evaluates final answers and tool-use trajectories, and provides a training-free GRPO workflow that rolls out agents, verifies answers, and distills experiences into an enhanced prompt. The graph reflects documented capabilities and shown calls; unsampled integrations are not inferred.

Main entry points: [`langchain_gpt_enhanced.py`](https://github.com/opendatalab/earth-agent/blob/main/langchain_gpt_enhanced.py) (ReAct agent), [`training_free_grpo/rollout_manager.py`](https://github.com/opendatalab/earth-agent/blob/main/training_free_grpo/rollout_manager.py) (Agent rollouts), [`training_free_grpo/training_free_grpo.py`](https://github.com/opendatalab/earth-agent/blob/main/training_free_grpo/training_free_grpo.py) (GRPO orchestrator), [`agent/tools/utils.py`](https://github.com/opendatalab/earth-agent/blob/main/agent/tools/utils.py) (Raster helpers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent runtime"]
  node_agent["ReAct agent"]
  node_config["Agent configuration<br/>[config_utils.py]"]
  node_answer["Agent answer"]
end

subgraph group_tools["EO toolkits"]
  node_index["Index analysis<br/>[Index.py]"]
  node_inversion["Spectral inversion<br/>[Inversion.py]"]
  node_perception["EO perception<br/>[Perception.py]"]
  node_analysis["Spatial analysis<br/>[Analysis.py]"]
  node_statistics["Raster statistics<br/>[Statistics.py]"]
  node_raster_utils["Raster helpers<br/>[utils.py]"]
end

subgraph group_evaluation["Evaluation workflow"]
  node_extract["Tool extraction"]
  node_polish["Answer polishing<br/>[polish_answer.py]"]
  node_end_eval["End-to-end metrics<br/>[end_to_end.py]"]
  node_step_eval["Trajectory metrics<br/>[step_by_step.py]"]
end

subgraph group_grpo["Training-free GRPO"]
  node_grpo_entry["GRPO orchestrator"]
  node_grpo_config["GRPO configuration<br/>[config.py]"]
  node_data["Dataset manager<br/>[data_manager.py]"]
  node_rollout["Agent rollouts<br/>[rollout_manager.py]"]
  node_verify["Answer verifier"]
  node_experience["Experience updater"]
  node_enhanced_config["Enhanced prompt"]
end

node_user(("Questioner"))

node_user -->|"asks"| node_agent
node_agent -->|"loads config"| node_config
node_agent -.->|"calls tools"| node_index
node_agent -.->|"calls tools"| node_inversion
node_agent -.->|"calls tools"| node_perception
node_agent -.->|"calls tools"| node_analysis
node_agent -.->|"calls tools"| node_statistics
node_index -->|"reads rasters"| node_raster_utils
node_inversion -->|"reads rasters"| node_raster_utils
node_perception -->|"reads rasters"| node_raster_utils
node_analysis -->|"uses helpers"| node_raster_utils
node_statistics -->|"reads rasters"| node_raster_utils
node_agent -->|"returns answer"| node_answer
node_answer -.->|"extracts tool calls"| node_extract
node_answer -.->|"polishes result"| node_polish
node_extract -.->|"supplies tool data"| node_step_eval
node_answer -.->|"scores final answer"| node_end_eval
node_user -.->|"starts evolution"| node_grpo_entry
node_grpo_entry -->|"uses settings"| node_grpo_config
node_grpo_entry -->|"loads samples"| node_data
node_grpo_entry -->|"runs batches"| node_rollout
node_rollout -->|"gets and updates samples"| node_data
node_grpo_entry -->|"verifies responses"| node_verify
node_grpo_entry -->|"updates experiences"| node_experience
node_experience -->|"distills prompt"| node_enhanced_config
node_rollout -.->|"loads MCP tools"| node_index
node_rollout -.->|"loads MCP tools"| node_inversion
node_rollout -.->|"loads MCP tools"| node_perception
node_rollout -.->|"loads MCP tools"| node_analysis
node_rollout -.->|"loads MCP tools"| node_statistics

click node_agent "https://github.com/opendatalab/earth-agent/blob/main/langchain_gpt_enhanced.py"
click node_config "https://github.com/opendatalab/earth-agent/blob/main/config_utils.py"
click node_index "https://github.com/opendatalab/earth-agent/blob/main/agent/tools/Index.py"
click node_inversion "https://github.com/opendatalab/earth-agent/blob/main/agent/tools/Inversion.py"
click node_perception "https://github.com/opendatalab/earth-agent/blob/main/agent/tools/Perception.py"
click node_analysis "https://github.com/opendatalab/earth-agent/blob/main/agent/tools/Analysis.py"
click node_statistics "https://github.com/opendatalab/earth-agent/blob/main/agent/tools/Statistics.py"
click node_raster_utils "https://github.com/opendatalab/earth-agent/blob/main/agent/tools/utils.py"
click node_answer "https://github.com/opendatalab/earth-agent/blob/main/langchain_gpt_enhanced.py"
click node_extract "https://github.com/opendatalab/earth-agent/blob/main/process/extract_tool_Model.py"
click node_polish "https://github.com/opendatalab/earth-agent/blob/main/process/polish_answer.py"
click node_end_eval "https://github.com/opendatalab/earth-agent/blob/main/evaluate/end_to_end.py"
click node_step_eval "https://github.com/opendatalab/earth-agent/blob/main/evaluate/step_by_step.py"
click node_grpo_entry "https://github.com/opendatalab/earth-agent/blob/main/training_free_grpo/training_free_grpo.py"
click node_grpo_config "https://github.com/opendatalab/earth-agent/blob/main/training_free_grpo/config.py"
click node_data "https://github.com/opendatalab/earth-agent/blob/main/training_free_grpo/data_manager.py"
click node_rollout "https://github.com/opendatalab/earth-agent/blob/main/training_free_grpo/rollout_manager.py"
click node_verify "https://github.com/opendatalab/earth-agent/blob/main/training_free_grpo/verify/earth_science_enhanced.py"
click node_experience "https://github.com/opendatalab/earth-agent/blob/main/training_free_grpo/experience_updater.py"
click node_enhanced_config "https://github.com/opendatalab/earth-agent/blob/main/training_free_grpo/training_free_grpo.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_agent,node_config,node_answer toneBlue
class node_index,node_inversion,node_perception,node_analysis,node_statistics,node_raster_utils toneAmber
class node_extract,node_polish,node_end_eval,node_step_eval toneMint
class node_grpo_entry,node_grpo_config,node_data,node_rollout,node_verify,node_experience,node_enhanced_config toneRose
class node_user toneIndigo
```

## Components

### Agent runtime

- [ReAct agent](https://github.com/opendatalab/earth-agent/blob/main/langchain_gpt_enhanced.py): `langchain_gpt_enhanced.py`
- [Agent configuration](https://github.com/opendatalab/earth-agent/blob/main/config_utils.py): `config_utils.py`
- [Agent answer](https://github.com/opendatalab/earth-agent/blob/main/langchain_gpt_enhanced.py): `langchain_gpt_enhanced.py`

### EO toolkits

- [Index analysis](https://github.com/opendatalab/earth-agent/blob/main/agent/tools/Index.py): `agent/tools/Index.py`
- [Spectral inversion](https://github.com/opendatalab/earth-agent/blob/main/agent/tools/Inversion.py): `agent/tools/Inversion.py`
- [EO perception](https://github.com/opendatalab/earth-agent/blob/main/agent/tools/Perception.py): `agent/tools/Perception.py`
- [Spatial analysis](https://github.com/opendatalab/earth-agent/blob/main/agent/tools/Analysis.py): `agent/tools/Analysis.py`
- [Raster statistics](https://github.com/opendatalab/earth-agent/blob/main/agent/tools/Statistics.py): `agent/tools/Statistics.py`
- [Raster helpers](https://github.com/opendatalab/earth-agent/blob/main/agent/tools/utils.py): `agent/tools/utils.py`

### Evaluation workflow

- [Tool extraction](https://github.com/opendatalab/earth-agent/blob/main/process/extract_tool_Model.py): `process/extract_tool_Model.py`
- [Answer polishing](https://github.com/opendatalab/earth-agent/blob/main/process/polish_answer.py): `process/polish_answer.py`
- [End-to-end metrics](https://github.com/opendatalab/earth-agent/blob/main/evaluate/end_to_end.py): `evaluate/end_to_end.py`
- [Trajectory metrics](https://github.com/opendatalab/earth-agent/blob/main/evaluate/step_by_step.py): `evaluate/step_by_step.py`

### Training-free GRPO

- [GRPO orchestrator](https://github.com/opendatalab/earth-agent/blob/main/training_free_grpo/training_free_grpo.py): `training_free_grpo/training_free_grpo.py`
- [GRPO configuration](https://github.com/opendatalab/earth-agent/blob/main/training_free_grpo/config.py): `training_free_grpo/config.py`
- [Dataset manager](https://github.com/opendatalab/earth-agent/blob/main/training_free_grpo/data_manager.py): `training_free_grpo/data_manager.py`
- [Agent rollouts](https://github.com/opendatalab/earth-agent/blob/main/training_free_grpo/rollout_manager.py): `training_free_grpo/rollout_manager.py`
- [Answer verifier](https://github.com/opendatalab/earth-agent/blob/main/training_free_grpo/verify/earth_science_enhanced.py): `training_free_grpo/verify/earth_science_enhanced.py`
- [Experience updater](https://github.com/opendatalab/earth-agent/blob/main/training_free_grpo/experience_updater.py): `training_free_grpo/experience_updater.py`
- [Enhanced prompt](https://github.com/opendatalab/earth-agent/blob/main/training_free_grpo/training_free_grpo.py): `training_free_grpo/training_free_grpo.py`

### Other components

- **Questioner**

## Connections

- Questioner → ReAct agent: asks
- ReAct agent → Agent configuration: loads config (evidence: `langchain_gpt_enhanced.py`)
- ReAct agent → Index analysis: calls tools
- ReAct agent → Spectral inversion: calls tools
- ReAct agent → EO perception: calls tools
- ReAct agent → Spatial analysis: calls tools
- ReAct agent → Raster statistics: calls tools
- Index analysis → Raster helpers: reads rasters (evidence: `agent/tools/Index.py`)
- Spectral inversion → Raster helpers: reads rasters (evidence: `agent/tools/Inversion.py`)
- EO perception → Raster helpers: reads rasters (evidence: `agent/tools/Perception.py`)
- Spatial analysis → Raster helpers: uses helpers (evidence: `agent/tools/Analysis.py`)
- Raster statistics → Raster helpers: reads rasters (evidence: `agent/tools/Statistics.py`)
- ReAct agent → Agent answer: returns answer (evidence: `langchain_gpt_enhanced.py`)
- Agent answer → Tool extraction: extracts tool calls
- Agent answer → Answer polishing: polishes result
- Tool extraction → Trajectory metrics: supplies tool data
- Agent answer → End-to-end metrics: scores final answer
- Questioner → GRPO orchestrator: starts evolution
- GRPO orchestrator → GRPO configuration: uses settings (evidence: `training_free_grpo/training_free_grpo.py`)
- GRPO orchestrator → Dataset manager: loads samples (evidence: `training_free_grpo/training_free_grpo.py`)
- GRPO orchestrator → Agent rollouts: runs batches (evidence: `training_free_grpo/training_free_grpo.py`)
- Agent rollouts → Dataset manager: gets and updates samples (evidence: `training_free_grpo/rollout_manager.py`)
- GRPO orchestrator → Answer verifier: verifies responses (evidence: `training_free_grpo/training_free_grpo.py`)
- GRPO orchestrator → Experience updater: updates experiences (evidence: `training_free_grpo/training_free_grpo.py`)
- Experience updater → Enhanced prompt: distills prompt (evidence: `training_free_grpo/training_free_grpo.py`)
- Agent rollouts → Index analysis: loads MCP tools
- Agent rollouts → Spectral inversion: loads MCP tools
- Agent rollouts → EO perception: loads MCP tools
- Agent rollouts → Spatial analysis: loads MCP tools
- Agent rollouts → Raster statistics: loads MCP tools