Eurus - ERA5 Climate Analysis Agent

Next-Generation Oceanographic & Climate Data Intelligence

---

Eurus is a high-performance, intelligent climate analysis agent designed for oceanographers, climate scientists, and data engineers. Built on the cutting-edge Icechunk transactional storage engine, Eurus bridges Earthmover's cloud-optimized ERA5 archives with advanced LLM reasoning, enabling seamless, natural language-driven exploration of planetary-scale climate data.

❄️ Powered By

This project is made possible by the incredible open-source work from the Earthmover team:

• Icechunk: The transactional storage engine for Zarr that provides the backbone for our high-performance data access.
• Arraylake: The cloud-native data lake that hosts the global ERA5 reanalysis archives used by this agent.

🚀 Core Pillars

• Intelligence-First Analysis: Leveraging LLMs to translate complex natural language queries into precise data retrieval and scientific analysis.
• Multi-Interface Access: Interact via a powerful CLI, a rich Web Interface, or integrate directly into IDEs via the Model Context Protocol (MCP).
• Cloud-Native Performance: Direct integration with Earthmover's Arraylake and Icechunk/Zarr storage for lightning-fast, subsetted data access.
• Python REPL: Built-in interactive Python environment with pandas, xarray, matplotlib for custom analysis.
• Maritime Routing: Calculate optimal shipping routes with weather risk assessment.
• Persistent Context: Memory system that tracks cached datasets across sessions.

---

Features

• Cloud-Optimized Data Retrieval: Downloads ERA5 reanalysis data directly from Earthmover's Arraylake.
• Python REPL: Interactive Python environment with pre-loaded scientific libraries (pandas, numpy, xarray, matplotlib).
• Maritime Routing: Calculate optimal shipping routes considering land masks (requires scgraph).
• Analysis Guides: Built-in methodology guides for climate analysis and visualization.
• Automatic Visualization: Matplotlib plots automatically saved to ./data/plots/.
• Intelligent Caching: Re-uses previously downloaded data to save bandwidth.
• MCP Server: Acts as a brain for Claude and other AI assistants.

Installation

Prerequisites

• Python 3.10 or higher
• An Earthmover Arraylake API Key
• An OpenAI API Key

Setup

1. Clone the repository:

   git clone https://github.com/yourusername/era_5_agent.git
   cd era_5_agent

2. Create and activate a virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # or `.venv\Scripts\activate` on Windows

3. Install dependencies:

   pip install -r requirements.txt

4. Configuration: Create a .env file in the root directory with your API keys:

   OPENAI_API_KEY=your_openai_api_key
   ARRAYLAKE_API_KEY=your_arraylake_api_key
   # Optional: Custom Host/Port for Web UI
   # WEB_HOST=127.0.0.1
   # WEB_PORT=8000

---

Usage

Eurus provides three ways to interact with the agent.

1. Interactive CLI Agent

The classic terminal experience with rich text output and direct interaction.

python main.py

Commands:

• /help - Show help message
• /clear - Clear conversation history
• /cache - List cached datasets
• /memory - Show memory summary
• /cleardata - Clear all downloaded datasets
• /quit or q - Exit

2. Web Interface

A modern web-based chat interface with rendered plots and easier navigation.

python web/app.py
# or
eurus-web

Access the interface at http://127.0.0.1:8000.

3. MCP Server (for Claude / IDEs)

Integrate Eurus's capabilities directly into Claude Desktop or compatible IDEs using the Model Context Protocol.

Configuration for Claude Desktop: Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "eurus": {
      "command": "python",
      "args": ["-m", "eurus.server"],
      "env": {
        "ARRAYLAKE_API_KEY": "your_key_here",
        "PYTHONPATH": "/absolute/path/to/era_5_agent/src"
      }
    }
  }
}

Or run directly for testing:

python -m eurus.server

---

Example Queries

Eurus can answer questions like:

• Data Retrieval: "Show me the sea surface temperature off California for 2023."
• Visualization: "Plot a time series of temperature anomalies in the North Atlantic."
• Comparison: "Compare SST between El Niño region and the California coast."
• Routing: "Calculate a ship route from Rotterdam to Singapore with weather risk."
• Custom Analysis: "Use Python to calculate the monthly mean SST and plot it."

Available Data

Variables

Variable	Description	Units
sst	Sea Surface Temperature	K
t2	2m Air Temperature	K
u10	10m U-Wind Component	m/s
v10	10m V-Wind Component	m/s
mslp	Mean Sea Level Pressure	Pa
sp	Surface Pressure	Pa
tcc	Total Cloud Cover	0-1
tp	Total Precipitation	m

Predefined Regions

Eurus knows many regions by name, including:

• north_atlantic, south_atlantic
• north_pacific, south_pacific
• california_coast, gulf_of_mexico, caribbean
• mediterranean, europe, asia_east
• arctic, antarctic
• nino34, nino3, nino4

---

Project Structure

era_5_agent/
├── main.py              # CLI Entry Point
├── pyproject.toml       # Project configuration
├── requirements.txt     # Python dependencies
├── src/
│   └── eurus/
│       ├── config.py    # Configuration & Constants
│       ├── memory.py    # Persistent Memory System
│       ├── server.py    # MCP Server Entry Point
│       └── tools/       # Agent Tools
│           ├── era5.py       # Data Retrieval
│           ├── routing.py    # Maritime Routing
│           └── analysis_guide.py
├── web/                 # Web Interface
│   ├── app.py           # FastAPI Application
│   ├── routes/          # API & Page Routes
│   └── templates/       # HTML Templates
├── data/                # Data Storage (Local)
│   ├── plots/           # Generated Visualizations
│   └── *.zarr/          # Cached ERA5 Datasets
└── .memory/             # Agent Conversation History

License

MIT License

---

Special thanks to the Icechunk and Earthmover teams for their pioneering work in cloud-native scientific data storage.