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.

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:

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:

docker compose down -v
docker compose up --build

Useful environment variables:

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:

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:

uv run serve-rgia-mcp

Run it through Docker:

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:

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

Docker-based MCP configuration:

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

See MCP smoke-test examples.

Local Development Without Docker

Requirements:

• Python 3.12+;
• uv;
• Node.js and npm.

Install dependencies:

uv sync
cd frontend
npm install
cd ..

Build the current local MVP snapshot:

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

Start the API:

uv run serve-rgia-api

Start the frontend in another terminal:

cd frontend
npm run dev

Run checks:

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

API Examples

Health:

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

Search Aragon solar PV assets in Zaragoza municipality:

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

Get an evidence pack:

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

Analyze a map location:

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
• Limitations
• Regional expansion playbook

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;
• public JSON Schema contracts under docs/schemas;
• deterministic guardrail eval cases under 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:

uv run benchmark-rgia-local --iterations 5

See:

• DuckDB SQL examples
• Local benchmark docs

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
• Agent context
• Roadmap

License

No project license has been selected yet.

Source datasets keep their own reuse terms and attribution requirements. See data source research and the provenance stored on each normalized record.