Walkthrough: the ORSA module on the seeded stack

Read ORSA climate module first — in particular its "what it is NOT" section. This page demonstrates exactly two things, and is explicit about where each one stops:

1. Seed data → submit a scenario × horizon matrix → poll it → read each cell's EAD/AAI. This is sdk/python/examples/orsa_matrix.py.
2. Compose the orsa PDF pack for that batch and download it, over the batch-shaped report routes issue #415 added. This is scripts/orsa_report_demo.py, a thin HTTP client — same as step 1, it runs from the host and needs no container access. There is no SDK wrapper method or UI button for this step yet, only the two REST routes it drives directly.

POST /v1/compute/impact/matrix resolves each cell's own hazard dataset from its scenario_label/horizon_year against the catalog (issue #420) — a cell is no longer a relabeled copy of the same run. Because scripts/seed_demo.py ingests only one historical hazard dataset (scenario: "baseline", no scenario siblings), that resolution plays out unevenly on the seeded stack below:

• The baseline column resolves every horizon to that one seeded dataset, so its EAD/AAI is identical across 2030/2050/2080 — correctly, since there is genuinely only one baseline dataset to run against.
• The ssp2-4.5/ssp5-8.5 columns have no matching dataset in the seeded stack, so those six cells resolve to a clear per-cell error (job_id: null, status: null — never dispatched — and error_message naming the missing scenario/horizon) instead of silently reusing the baseline dataset. That is the correct, current behaviour on this stack — not a bug in this walkthrough.

To see every cell actually differentiated, ingest the real scenario-conditioned Aqueduct pack first — python scripts/ingest_scenario_hazards.py ingest (issue #386) — which records each dataset's own scenario/horizon so every cell in a river_flood matrix over it resolves to a distinct dataset and a distinct EAD. See that script's module docstring and the EIOPA scenario mapping concept page for what it ingests and why.

This walkthrough is private-stack-only: everything below runs against your own docker compose stack, never a hosted environment, and nothing here is published anywhere.

Prerequisites

• Docker and Docker Compose
• Python 3.10+ with httpx installed (pip install httpx — the SDK example imports the SDK directly from the checkout, so no pip install climate-lama is needed) and requests installed (pip install requests — scripts/orsa_report_demo.py uses it the same way scripts/demo.py does)
• A clone of this repository, with .env created from .env.example

1. Set a usable, ANALYST-role demo password

Running an impact matrix and requesting a report both require Role.ANALYST. scripts/seed_demo.py only grants that role to the seeded demo@example.com user when CL_DEMO_USER_PASSWORD is set before it seeds (see Demo data seeder for the full seeder reference — this page only adds the ANALYST-role prerequisite the seeder's own docs don't need). Add it to .env:

echo "CL_DEMO_USER_PASSWORD=demo1234" >> .env

If you already seeded acme-demo without this set, the seeder's idempotency guard will skip re-seeding. Wipe and start over:

docker compose down -v

2. Start the stack and seed demo data

docker compose up -d
docker compose exec api python scripts/seed_demo.py --verbose

Expected last log line: Demo seed complete for org acme-demo (result_id=…). This creates org acme-demo, user demo@example.com, one historical river-flood hazard dataset, one LitPop exposure dataset, and the JRC flood impact function — see Demo data seeder.

3. Run the scenario matrix (SDK, over HTTP)

From a checkout of this repo (no install needed — the example imports the SDK package directly):

cd sdk/python
CLIMATE_LAMA_BASE_URL=http://localhost:8000 \
CLIMATE_LAMA_EMAIL=demo@example.com \
CLIMATE_LAMA_PASSWORD=demo1234 \
CLIMATE_LAMA_ORG_SLUG=acme-demo \
PYTHONPATH=. python examples/orsa_matrix.py

This logs in, submits a 3×3 (baseline/ssp2-4.5/ssp5-8.5 × 2030/2050/2080) scenario matrix against the seeded hazard/exposure pair, polls GET /v1/compute/impact/matrix/{batch_id} to completion, and prints each cell's EAD/AAI plus the org_id and batch_id you need for the next step. On the seeded stack, expect the baseline rows to print matching EAD/AAI and the ssp2-4.5/ssp5-8.5 rows to print failed in place of a figure, per the note above.

4. Render and download the ORSA pack (over HTTP, from the host)

Using the batch_id the previous step printed:

SDK_SMOKE_EMAIL=demo@example.com \
SDK_SMOKE_PASSWORD=demo1234 \
SDK_SMOKE_ORG_SLUG=acme-demo \
python scripts/orsa_report_demo.py --batch-id <batch_id>

This calls POST /v1/compute/impact/matrix/{batch_id}/report to queue the render (202 + job_id), polls GET /v1/jobs/{job_id} until it completes, then downloads the finished document from GET /v1/compute/impact/matrix/{batch_id}/report — the batch-shaped report routes issue #415 added, mirroring how POST/GET /v1/results/{id}/report already work for a single-result report. It runs from the host, the same as step 3 — no docker compose exec needed — and writes orsa_report.pdf to the current directory (override with --out).

Open orsa_report.pdf. You should see the cover/scope box, the executive-summary grid (baseline figures populated, the ssp2-4.5/ssp5-8.5 rows reported as absent per the note above, not as zero loss), the horizon-comparison chart, one exceedance-probability panel per scenario/horizon that has a result, the methodology section citing EIOPA scenario mapping, and the assumptions and attribution annexes.

What this walkthrough does not demonstrate

• A fully-populated matrix on the seeded stack. See the note above — the seeded stack only carries the baseline scenario, so the ssp2-4.5/ssp5-8.5 cells resolve to a per-cell error rather than a figure. Run python scripts/ingest_scenario_hazards.py ingest (issue #386) first to load the real scenario-conditioned Aqueduct datasets, then re-run step 3 for a matrix where every cell in the river_flood grid resolves and reports its own EAD/AAI.
• Asset- or portfolio-level views. scripts/seed_demo.py does not create Assets, portfolio membership, or admin boundaries (issue #405); this walkthrough only needs an exposure dataset and a hazard dataset, both of which the seeder provides.
• A real EIOPA-ORSA filing. See ORSA climate module.