# Renewable Grid Intelligence Atlas

Aragon-first geospatial intelligence project for renewable energy infrastructure.

The atlas ingests public energy and environmental datasets, normalizes them into
a local canonical model, serves them through a deterministic API, renders an
interactive MapLibre UI, and exposes local MCP tools that return cited evidence
packs for AI agents.

The goal is not to make legal, permitting or grid-connection decisions. The goal
is to show a practical, inspectable data product around renewable assets:
source ingestion, geospatial normalization, evidence retrieval, guardrails,
local analytics and an agent-ready interface.

![Renewable Grid Intelligence Atlas MVP](docs/assets/rgia-mvp-dashboard.png)

## What The Demo Does

Current MVP scope is deliberately narrow:

- **Region**: Aragon, Spain.
- **Assets**: wind and solar PV renewable generation projects.
- **Data model**: normalized renewable assets with source provenance.
- **Enrichment**:
  - municipality and province from Aragon administrative boundaries;
  - bounded PVGIS solar-potential estimates;
  - MITECO environmental zoning context;
  - REE regional electricity-generation context.
- **Serving layer**:
  - FastAPI read API over DuckDB;
  - Vite + React + MapLibre frontend;
  - local MCP server over the same DuckDB snapshot.
- **Evidence**: cited evidence packs with source URLs, license notes,
  retrieval timestamps, raw record identifiers and limitations.

The first public snapshot contains **1,351 Aragon assets**:

- 855 solar PV assets;
- 496 wind assets;
- 25 cached PVGIS solar estimates;
- 1,351 MITECO environmental context records;
- 2025 REE regional electricity context for Aragon.

## Quick Start With Docker

Requirements:

- Docker;
- Docker Compose.

Start the API and UI:

```bash
docker compose up --build
```

Open:

- UI: <http://127.0.0.1:5173>
- API health: <http://127.0.0.1:8000/api/health>

On the first run, the API container checks whether
`data/processed/canonical/atlas.duckdb` exists inside the Docker volume. If it
does not, it builds the local snapshot before starting the API.

The Docker data volume is named `renewable-grid-intelligence-atlas_rgia-data`.
To force a clean rebuild:

```bash
docker compose down -v
docker compose up --build
```

Useful environment variables:

```bash
RGIA_SNAPSHOT_DATE=2026-07-05
RGIA_PVGIS_LIMIT=25
RGIA_REE_YEAR=2025
VITE_API_BASE_URL=http://127.0.0.1:8000
```

Example:

```bash
RGIA_PVGIS_LIMIT=5 docker compose up --build
```

## MCP

The MCP server is local-first and does not require project-owned OpenAI,
Anthropic, Azure or other LLM API keys. Your MCP client/model provides any LLM
credentials.

Run the MCP server locally:

```bash
uv run serve-rgia-mcp
```

Run it through Docker:

```bash
docker compose run --rm mcp
```

Available tools:

- `search_renewable_assets`
- `get_renewable_asset_evidence`
- `analyze_renewable_location`
- `get_source_quality`
- `get_regional_energy_context`

Example MCP client configuration:

```json
{
  "mcpServers": {
    "rgia": {
      "command": "uv",
      "args": ["run", "serve-rgia-mcp"],
      "cwd": "/path/to/renewable-grid-intelligence-atlas"
    }
  }
}
```

Docker-based MCP configuration:

```json
{
  "mcpServers": {
    "rgia": {
      "command": "docker",
      "args": ["compose", "run", "--rm", "mcp"],
      "cwd": "/path/to/renewable-grid-intelligence-atlas"
    }
  }
}
```

See [MCP smoke-test examples](docs/examples/mcp-smoke-tests.md).

## Local Development Without Docker

Requirements:

- Python 3.12+;
- `uv`;
- Node.js and npm.

Install dependencies:

```bash
uv sync
cd frontend
npm install
cd ..
```

Build the current local MVP snapshot:

```bash
uv run build-rgia-snapshot \
  --snapshot-date 2026-07-05 \
  --pvgis-limit 25 \
  --ree-year 2025
```

Start the API:

```bash
uv run serve-rgia-api
```

Start the frontend in another terminal:

```bash
cd frontend
npm run dev
```

Run checks:

```bash
uv run ruff check .
uv run pytest
cd frontend
npm run lint
npm run build
```

## API Examples

Health:

```bash
curl http://127.0.0.1:8000/api/health
```

Search Aragon solar PV assets in Zaragoza municipality:

```bash
curl "http://127.0.0.1:8000/api/assets?province=Zaragoza&municipality=Zaragoza&technology=solar_pv&limit=3"
```

Get an evidence pack:

```bash
curl "http://127.0.0.1:8000/api/assets/aragon-open-data:321:31064/evidence"
```

Analyze a map location:

```bash
curl "http://127.0.0.1:8000/api/locations/analyze?lat=41.65&lon=-0.88&radius_km=25&limit=5"
```

## Architecture

The repository is split into explicit layers:

- `backend/src/renewable_grid_atlas/ingestion/`: source ingestion,
  source-specific normalization and canonical output generation.
- `backend/src/renewable_grid_atlas/schemas/`: Pydantic schemas and public
  JSON Schema export.
- `backend/src/renewable_grid_atlas/api/`: FastAPI read API over DuckDB.
- `backend/src/renewable_grid_atlas/mcp/`: MCP tools over the same canonical
  DuckDB snapshot.
- `backend/src/renewable_grid_atlas/evals/`: deterministic guardrail eval
  cases.
- `backend/src/renewable_grid_atlas/benchmarks/`: local DuckDB benchmark
  command.
- `frontend/`: Vite, React and MapLibre UI.
- `docs/`: requirements, architecture notes, source research, schema examples,
  evidence samples and demo limitations.

The ingestion pattern is source-isolated:

1. Each public source has its own ingestor and source-specific normalized
   output.
2. Canonical merge code builds stable project records.
3. Every canonical record keeps provenance:
   `source_name`, `source_url`, `retrieved_at`, `license`, `raw_record_id` and
   `confidence`.
4. API, UI and MCP all read from the same canonical DuckDB snapshot.

This keeps source-specific mess out of the domain model and makes it possible
to add another autonomous community later without hardcoding Aragon assumptions
through the whole codebase.

## Data Sources

Included in the MVP:

| Source | Used For | Why It Is Included |
| --- | --- | --- |
| Aragon Open Data | Renewable wind and solar asset geometries, status and capacity | Primary Aragon-first renewable asset source with clear reuse terms. |
| Aragon Open Data / IDEARAGON boundaries | Municipality and province enrichment | Independent administrative-boundary source, separated from the asset source. |
| MITECO environmental zoning | Environmental sensitivity context for wind/PV assets | Public national environmental zoning layers useful as contextual evidence. |
| PVGIS | Bounded solar-potential estimates | Public JRC service, used conservatively and cached locally. |
| REE REData | Regional Aragon generation mix | Regional context only, not asset-level production or grid capacity. |

Not included yet:

- **CNMC capacity maps**: technically useful and already inspected, but blocked
  for automated ingestion until service-level reuse and attribution are explicit
  for the ArcGIS FeatureServer payloads.
- **Spain-wide coverage**: intentionally deferred until the Aragon-first data
  model, evidence shape and source-boundary pattern are stable.
- **Private maps or paid APIs**: excluded from the MVP.
- **Project-owned LLM APIs**: excluded by design. LLM clients should call the
  MCP tools with their own credentials.

More detail:

- [Data source research](docs/research/data-sources.md)
- [Limitations](docs/limitations.md)
- [Regional expansion playbook](docs/architecture/regional-expansion.md)

## Evidence And Guardrails

The project avoids asking an LLM to invent conclusions. It returns structured,
cited facts and explicit limitations.

Examples:

- asset-level evidence packs under [docs/samples](docs/samples);
- public JSON Schema contracts under [docs/schemas](docs/schemas);
- deterministic guardrail eval cases under [docs/evals](docs/evals).

Important limitations:

- REE data is regional context, not asset-level generation.
- MITECO context is environmental zoning evidence, not permitting approval.
- PVGIS values are local solar-resource estimates, not project production.
- CNMC grid-capacity data is not ingested yet.
- The project must not be used as legal, permitting or engineering advice.

## Benchmarks And DuckDB Examples

Run local benchmarks:

```bash
uv run benchmark-rgia-local --iterations 5
```

See:

- [DuckDB SQL examples](docs/examples/duckdb-sql.md)
- [Local benchmark docs](docs/commands.md)

## Project Status

This is a work in progress local MVP. The current focus is making the
Aragon-first data/API/UI/MCP path credible, reproducible and inspectable before
expanding to more regions or adding phase-2 products such as permitting
watchers.

Current tracker:

- [Implementation checklist](docs/checklists/implementation.md)
- [Agent context](docs/agent-context.md)
- [Roadmap](docs/roadmap.md)

## License

No project license has been selected yet.

Source datasets keep their own reuse terms and attribution requirements. See
[data source research](docs/research/data-sources.md) and the provenance stored
on each normalized record.