Installable package foundation, Python client, and User-facing docs

[turban]

Why

The Climate API was designed from the start for a single deployment scenario: clone the repo, edit files in place, run. This worked for early development but creates real problems as we move toward production deployments and want users to be able to install the package with pip install climate-api:

• Instance configuration (extent, custom datasets) was stored inside the repository, making upgrades destructive.
• Built-in dataset templates were found by walking directory paths relative to source files — a technique that breaks when the package is installed into site-packages/ because the project root is no longer accessible.
• There was no Python client for discovering and opening datasets without constructing raw URLs.
• Documentation assumed you had already cloned the repo and knew the internal structure.

This PR addresses all of these to make the package usable outside a source checkout.

What changed

Instance configuration via CLIMATE_API_CONFIG (closes #61)

A new CLIMATE_API_CONFIG environment variable points to a YAML file that lives outside the repository. This separates instance-specific configuration from the package itself, so the package can be upgraded without overwriting local config.

# climate-api.yaml — lives outside the repo, not committed
extent:
  id: rwa
  name: Rwanda
  bbox: [28.8, -2.9, 30.9, -1.0]
  country_code: RWA

datasets_dir: ./my-datasets/   # optional — merged on top of built-ins

The extent is a single block per instance (not a list). The GET /extent endpoint returns it, or 404 if not configured. Dataset templates from datasets_dir are merged with the built-ins — a custom template with the same id overrides the built-in one.

Built-in dataset templates bundled inside the package

Previously, the built-in YAML templates (chirps3.yaml, era5_land.yaml, worldpop.yaml) lived in data/datasets/ at the project root and were located by walking four directory levels up from the source file. This breaks when the package is installed with pip install, because the package ends up in site-packages/ with no path to the original project root.

The YAMLs are now bundled inside the package at src/climate_api/data/datasets/ and loaded via importlib.resources, which resolves the correct location regardless of how the package was installed.

Coordinate normalisation at write time

All Zarr datasets are now written with canonical coordinate names (time, latitude, longitude) regardless of what the upstream source uses (valid_time, lat/lon, x/y). This is enforced in build_dataset_zarr() for both flat and pyramid outputs.

Every downstream consumer — the client, the user guide, the OGC API — can now use ds.latitude, ds.longitude, ds.time without dataset-specific branching.

Python client for dataset discovery and access (closes #60)

A new climate_api.client module makes it possible to discover and open datasets without constructing URLs manually:

from climate_api.client import Client

api = Client("http://127.0.0.1:8000")
datasets = api.catalog()          # list published datasets
ds = api.open(datasets[0]["id"]) # open as xarray.Dataset

Module-level functions (list_datasets, open_dataset) fall back to the CLIMATE_API_BASE_URL environment variable, so scripts work without hardcoding a URL.

create_app() factory function

The FastAPI application is now created via a create_app() factory, making it straightforward to embed the API in a larger application:

from climate_api.main import create_app
app = create_app()

CORS credentials flag corrected

allow_credentials was incorrectly set to True alongside allow_origins=["*"]. This combination violates the CORS specification and is rejected by browsers. It is now set to False, which is correct for a public data API that does not use cookies or session tokens.

Dataset template field renamed: cache_info → ingestion

The cache_info block in dataset template YAMLs is renamed to ingestion. The ingestion.eo_function field is now required for all sync kinds, not just temporal ones.

Documentation

• docs/setup_guide.md — step-by-step instance setup from install to first ingestion
• docs/user_guide.md — consumer guide: STAC discovery, opening with xarray, subsetting
• docs/adding_custom_datasets.md — how to write a custom dataset template and wire it up
• examples/stac_discover_and_open.py and examples/zarr_direct_access.py — runnable examples using the client

Migration note

Existing datasets must be deleted and re-ingested. Coordinate normalisation only applies to newly written Zarr stores. Zarr files written before this PR will retain their original source coordinate names.

Rename cache_info: to ingestion: in any custom dataset YAML templates.

Test plan

• make run starts the API without errors
• uv run examples/stac_discover_and_open.py lists published datasets and prints dataset info
• uv run examples/zarr_direct_access.py opens a Zarr store and prints a spatial mean time series
• from climate_api.client import Client; print(Client("http://127.0.0.1:8000").catalog()) works in a Python session
• A fresh instance configured with only climate-api.yaml serves the correct extent and built-in datasets
• datasets_dir with a custom YAML adds that dataset alongside the built-ins
• Setup guide is followable end to end for a new country
• make test passes