Release: Complete EarthReach implementation v1.0

This commit represents the final day release of the EarthReach project,
replacing the initial main branch with the full implementation.

Key Features:
- Dual-LLM framework (Generator + Evaluator agents)
- Complete earth_reach package structure
- VLLM inference server integration
- Full CLI interface with era command
- Documentation and example notebooks

Package structure migrated from src/earth_reach_agent/ to src/earth_reach/

Author: rbazin

.github/workflows/ci.yaml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, develop ]
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - 'README*'
+      - '.gitignore'
+  pull_request:
+    branches: [ main, develop ]
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - 'README*'
+      - '.gitignore'
+  workflow_dispatch:
+
+jobs:
+  code-analysis:
+    name: Code Quality Analysis
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Install Python
+        run: uv python install
+
+      - name: Install dependencies
+        run: uv sync --locked --all-extras --dev
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+      - name: Check linting
+        run: uv run ruff check .

.gitignore

@@ -9,10 +9,6 @@ wheels/
 # Virtual environments
 .venv
 
-# Notebooks
-.ipynb_checkpoints/
-*.ipynb
-
 # Data
 weather_images/
 
@@ -22,7 +18,6 @@ weather_images/
 # Common
 *.DS_Store
 
-# Images
-*.png
-*.jpg
-*.jpeg
+# Data
+data/monthly_average.zarr
+data/*.nc

.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.7
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format

.python-version

@@ -0,0 +1 @@
+3.12

LICENSE

@@ -199,4 +199,4 @@
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
+   limitations under the License.

README.md

@@ -1,6 +1,9 @@
 # EarthReach Agent: Dual-LLM Framework for Validated Meteorological Chart Descriptions
 
 <p align="center">
+  <a href="https://www.python.org/downloads/release/python-3120/">
+    <img src="https://img.shields.io/badge/python-3.12-blue.svg" alt="Python 3.12">
+  </a>
   <a href="https://opensource.org/licenses/apache-2-0">
     <img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License: Apache 2.0">
   </a>
@@ -14,14 +17,19 @@
 
 ## EarthReach
 
-EarthReach is a challenge from the 2025 edition dedicated to enhancing the accessibility of meteorological data visualisations produced by Earthkit, by equipping the plots module with LLM-powered alternative text generation capabilities.
+EarthReach is a Python library for generating natural language descriptions of meteorological data visualizations. The library extends [earthkit-plots](https://github.com/ecmwf/earthkit-plots) by providing automated text generation capabilities for weather charts, enabling programmatic conversion of visual data representations into structured textual descriptions.
+
+The system implements a dual-LLM architecture consisting of a generator agent and an evaluator agent. The generator creates initial descriptions from chart images and associated GRIB file metadata, while the evaluator assesses output quality across multiple criteria including scientific accuracy, coherence, and meteorological relevance. This iterative process continues until quality thresholds are met or maximum iterations are reached.
+
+![Global temperature and mean sea level map](./docs/source/_static/example_global_chart.png)
 
 ## Installation
 
 ### Prerequisites
 
-- Python 3.12 or higher
-- [uv](https://docs.astral.sh/uv/) - Python package and project manager
+- [uv](https://docs.astral.sh/uv/): Python package and project manager (will automatically install Python 3.12+ if needed)
+- [Climate Data Store ](https://cds.climate.copernicus.eu/how-to-api): API key configured for accessing meteorological data
+- API key for a supported LLM provider (OpenAI, Google Gemini, Anthropic Claude, Groq, or any OpenAI-compatible API provider)
 
 ### Setup
 
@@ -32,42 +40,63 @@ EarthReach is a challenge from the 2025 edition dedicated to enhancing the acces
   ```
 2. **Create a virtual environment and install dependencies**
   ```sh
-  uv sync
+  uv sync --group dev
   ```
 This command will automatically:
 - Create a .venv virtual environment
 - Install all project dependencies from pyproject.toml
+- Install development dependencies
 
 3. **Activate the virtual environment**
   ```sh
   source .venv/bin/activate  # On Windows, use: .venv\Scripts\activate
   ```
 
+4. **Set up pre-commit hooks (recommended for development)**
+  ```sh
+  uv run pre-commit install
+  ```
+
 You're now ready to use the project.
 
 ## Project Structure
 
 ```sh
-. 
+.
 ├── docs/                     # Project documentation
 ├── notebooks/                # Tutorials & experiments
 ├── src/
-│   ├── earth_reach_agent/    # Main package
+│   ├── earth_reach/    # Main package
 │   └── tests/                # Unit and integration tests (to come)
 ├── vllm/                     # VLLM inference server setup
 ├── pyproject.toml            # Project dependencies and metadata
 └── uv.lock                   # Locked dependency versions
 ```
 
-## VLLM Inference Server
+## Basic Usage
 
-To run this project, you will need to have an openAI-compatible LLM inference server. 
+```python
+from earth_reach import EarthReachAgent
+import earthkit.plots as ekp
+import earthkit.data as ekd
 
-We provide instructions on how to setup your own secured inference server using [VLLM](./vllm/setup.md).
+# Load your data with earthkit-data
+data = ekd.from_source("file", "your_data.grib")
 
-## Usage
+# Create a weather chart with earthkit-plots
+figure = ekp.quickplot(data, mode="overlay")
+
+# Generate description
+agent = EarthReachAgent(provider="openai")
+description = agent.generate_alt_description(figure, data)
+print(description)
+```
 
-The project provides a command-line interface (CLI) accessible through `earth-reach-agent` or its shorter alias `era`.
+See `notebooks/example.ipynb` for a practical usage example.
+
+## CLI Interface
+
+EarthReach includes a standalone CLI that works on image files only, producing less detailed descriptions than the full library integration.
 
 ### Available Commands
 
@@ -76,20 +105,66 @@ View all commands and options:
 uv run era --help
 ```
 
-### Generate weather chart descriptions
-
 Generate a natural language description from a weather chart image:
 ```sh
 uv run era generate --image-path <path_to_image>
 ```
 
-### Evaluate descriptions
-
 Evaluate the accuracy of a description against a weather chart:
 
 ```sh
 uv run era evaluate --image-path <path_to_image> --description "<description_string>"
 ```
+## VLLM Inference Server
+
+EarthReach supports any OpenAI-compatible API endpoint for self-hosted LLMs. See `vllm/` directory for a VLLM setup example.
+
+**Warning**: Self-hosting requires advanced system administration skills and significant GPU resources. Recommended only for experienced users.
+
+## Development
+
+### Development Tooling
+
+This project uses the following development tools:
+
+- **Ruff**: Fast Python linter and formatter
+- **mypy**: Static type checker for Python
+- **Pre-commit**: Git hooks for code quality checks
+- **Pytest**: Testing framework
+
+### Code Quality
+
+The project is configured with pre-commit hooks that run automatically before each commit to ensure code quality:
+
+- **Ruff linting**: Checks for common Python issues and enforces coding standards
+- **Ruff formatting**: Automatically formats code for consistency
+- **mypy type checking**: Validates type hints and catches import errors
+- **Basic checks**: Trailing whitespace, file endings, YAML/TOML syntax, merge conflicts
+
+### Running Tools Manually
+
+You can run the development tools manually:
+
+```sh
+# Run ruff linter
+uv run ruff check .
+
+# Run ruff formatter
+uv run ruff format .
+
+# Run mypy type checker
+uv run mypy .
+
+# Run pre-commit hooks on all files
+uv run pre-commit run --all-files
+```
+
+### Configuration
+
+- Ruff configuration is in `pyproject.toml` under `[tool.ruff]`
+- mypy configuration is in `pyproject.toml` under `[tool.mypy]`
+- Pre-commit configuration is in `.pre-commit-config.yaml`
+
 ## License
 
 See [LICENSE](LICENSE)

docs/.gitkeep

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/Makefile

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd