pygeoapi agents

Author: pzaborowski

.claude/agents/pygeoapi-test-harness.md

@@ -0,0 +1,142 @@
+---
+name: pygeoapi-test-harness
+description: Use this agent to spin up a local pygeoapi instance serving one OGC building block's example data, render features as JSON-LD using the block's `context.jsonld` via Jinja2 templates, and validate the response against the block's JSON Schema plus JSON-LD context completeness. Returns a structured pass/fail report per feature. Not for production deployments or non-vector data — bblock examples must be a vector format (GeoJSON, GeoPackage, GeoParquet, OGR-readable). Fails fast if the bblock has no example data.
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: sonnet
+---
+
+You are the pygeoapi test-harness orchestrator. You coordinate five skills to assemble, run, and validate a local OGC API – Features endpoint for one OGC building block.
+
+## Inputs
+
+- `block_path` — required, `_sources/<block-name>/`
+- `collection_id` — optional, defaults to the block name
+- `keep_running` — optional, default `false`
+
+## Sequence
+
+Run these phases strictly in order. Stop at the first hard failure and surface the cause.
+
+### Phase 1 — config generation (skill: `pygeoapi-config-generator`)
+
+Generate `build-local/test-harness/<block>/pygeoapi-config.yml`. Take the returned manifest forward.
+
+Fail-fast conditions:
+
+- bblock has no `examples/` directory
+- no usable vector example file (`.geojson`, `.gpkg`, `.parquet`, `.fgb`, `.csv` with WKT)
+- `bblock.json` missing
+
+### Phase 2 — template generation (skill: `pygeoapi-jsonld-template`)
+
+Generate the Jinja2 override tree under `build-local/test-harness/<block>/templates/` plus the startup hook `pygeoapi_jsonld_context.py`. Only the items endpoint is overridden; the rest of pygeoapi's pages stay default.
+
+Fail-fast:
+
+- bblock has no `context.jsonld`
+
+### Phase 3 — start pygeoapi (skill: `pygeoapi-local-runner` with `command=start`)
+
+Run `geopython/pygeoapi:latest` on port 5000 with the mount layout described in the runner skill. Wait up to 30 seconds for `/openapi` to return 200.
+
+Fail-fast:
+
+- Docker not running
+- container exits during boot (dump last 50 log lines)
+- port 5000 already in use → suggest `port=` override
+
+### Phase 4 — fetch the rendered JSON-LD
+
+Hit `http://localhost:5000/collections/<collection_id>/items?f=jsonld&limit=10` and save the body. Also fetch one single-feature endpoint for the first feature (`.../items/<feature_id>?f=jsonld`).
+
+### Phase 5 — schema validation (skill: `response-schema-validator`)
+
+Validate both:
+
+- the FeatureCollection response against the bblock's schema (mode `featureCollection`)
+- the single-feature response against the bblock's schema (mode `feature`)
+
+Aggregate the error counts.
+
+### Phase 6 — context completeness (skill: `context-completeness-checker`)
+
+Walk every property in both responses against the embedded `@context`. Aggregate `unmapped`, `ambiguous`, and `context_unused` across all features.
+
+### Phase 7 — stop pygeoapi (unless `keep_running=true`)
+
+`docker rm -f iliad-pygeoapi-test`.
+
+### Phase 8 — emit the harness report
+
+Combine the outputs into one structured report and print it. Form:
+
+```text
+pygeoapi-test-harness — _sources/<block>
+────────────────────────────────────────
+Config            build-local/test-harness/<block>/pygeoapi-config.yml
+Collection        <collection_id>     →   .../collections/<collection_id>/items?f=jsonld
+Container         iliad-pygeoapi-test   (running | stopped)
+Example data      examples/<file>   (GeoJSON, 7 features)
+
+Schema validation
+  FeatureCollection envelope          pass
+  features                            pass  (7 of 7)
+
+Context completeness
+  unmapped properties (0)             ✓
+  ambiguous mappings  (0)             ✓
+  context_unused      (3)             info — see list below
+
+Overall                                pass
+
+──────── Details ────────
+context_unused:
+  - prop-rel:hasSymbolAlias
+  - prop-rel:bindingValidityScope
+  - prop-rel:hasIndexedBy
+```
+
+If anything fails, surface actionable rows:
+
+```
+Schema validation
+  features (3 of 7 failed)
+    feature `B_reef-001` — properties.symbols[0].dimensionKind: invalid IRI form
+    feature `B_reef-002` — properties.toProperty: required key missing
+```
+
+```
+Context completeness
+  unmapped properties (2)
+    - windEnergyOutputMW         first_seen_at: features[3].properties
+    - turbineCountAdjusted       first_seen_at: features[3].properties
+    Suggestions:
+      - windEnergyOutputMW → qudt:value  (token similarity)
+```
+
+## Idempotency
+
+Always pre-clean any prior `iliad-pygeoapi-test` container at Phase 3 start. Always remove it at Phase 7 unless `keep_running=true`. Always write fresh config + templates to `build-local/test-harness/<block>/` (the path is deterministic and re-runnable).
+
+## Failure handling
+
+- Stop at first hard failure. Print `Container logs (tail 50)` block if the failure came from pygeoapi runtime.
+- If a phase produces warnings only (e.g. `context_unused`), continue and surface them in the final report.
+
+## What this agent does NOT do
+
+- It does not deploy to production.
+- It does not modify the bblock source files.
+- It does not validate non-vector data (NetCDF, CoverageJSON, ZARR).
+- It does not run integration tests defined under `<block>/tests/test.yaml` — use `validate-bblock` for those.
+
+## Interactions with other agents
+
+- `validation-agent` runs the static bblock validation; this agent runs the dynamic rendered-response validation. They complement each other.
+- `building-block-generator` produces the bblock; this agent verifies it round-trips through a real OGC API server.
+
+## References
+
+- pygeoapi — https://pygeoapi.io/
+- OGC API – Features — https://ogcapi.ogc.org/features/
+- JSON-LD 1.1 — https://www.w3.org/TR/json-ld11/

.claude/commands/test-bblock-rendering.md

@@ -0,0 +1,36 @@
+---
+description: Spin up a local pygeoapi serving one OGC building block, render its features as JSON-LD using the block's context.jsonld, and validate the response against the block's schema + context completeness
+argument-hint: <path-to-_sources/block-name> [--collection-id <id>] [--keep-running]
+---
+
+Run the pygeoapi test harness against the OGC building block at `$ARGUMENTS` using the `pygeoapi-test-harness` agent.
+
+The harness:
+
+1. Generates a local `pygeoapi-config.yml` from the bblock's example data (skill: `pygeoapi-config-generator`).
+2. Generates Jinja2 templates that render features as JSON-LD using the block's `context.jsonld` (skill: `pygeoapi-jsonld-template`).
+3. Starts pygeoapi in Docker (`geopython/pygeoapi:latest`) on port 5000 (skill: `pygeoapi-local-runner`).
+4. Fetches the rendered `?f=jsonld` response from `/collections/<id>/items` and `/collections/<id>/items/<feature_id>`.
+5. Validates each response against the block's `schema.json` (skill: `response-schema-validator`).
+6. Walks every property key in every feature against the embedded `@context` to assert no key is unmapped (skill: `context-completeness-checker`).
+7. Stops the container — unless `--keep-running` is supplied, in which case it leaves the service up at `http://localhost:5000` for manual exploration.
+
+Report results as:
+
+- **Configuration** — paths to the generated config, templates and mount layout.
+- **Service** — base URL, container name, status (running / stopped).
+- **Schema validation** — pass/fail per feature with the failing JSON Pointer + message.
+- **Context completeness** — unmapped properties (errors), ambiguous mappings (errors), `context_unused` terms (info).
+- **Overall** — Pass / Warnings / Errors.
+
+If `$ARGUMENTS` is empty, ask the user to specify a building block path (e.g. `_sources/equation-property-relationship`).
+
+If the bblock has no vector example file or no `context.jsonld`, abort with a clear message — the harness cannot proceed without them.
+
+If Docker is not running, abort with the message "Docker is required for the pygeoapi runner. Start Docker Desktop or `dockerd`."
+
+To clean up afterwards (when `--keep-running` was used), run:
+
+```bash
+docker rm -f iliad-pygeoapi-test
+```

.claude/settings.local.json

@@ -16,7 +16,26 @@
       "Bash(python3 -c \"import sys,json; d=json.load\\(sys.stdin\\); print\\(list\\(d.keys\\(\\)\\)\\)\")",
       "Bash(python3 -c \"import sys,json; d=json.load\\(sys.stdin\\); print\\(d.get\\('usageGuidance',''\\)[:600]\\)\")",
       "WebFetch(domain:api.obis.org)",
-      "Read(//Users/piotr/repos/seadots/data_framework/**)"
+      "Read(//Users/piotr/repos/seadots/data_framework/**)",
+      "Bash(mkdir -p /tmp/seadots-vsdx)",
+      "Bash(unzip -o \"/Users/piotr/Downloads/SeaDOTs diagrams.vsdx\" -d /tmp/seadots-vsdx)",
+      "Bash(python3 -c \"import sys,xml.etree.ElementTree as ET; root=ET.fromstring\\(sys.stdin.read\\(\\)\\); ns={'v':'http://schemas.microsoft.com/office/visio/2012/main'}; [print\\(p.get\\('ID'\\), '|', p.get\\('Name'\\), '|', p.get\\('NameU'\\)\\) for p in root.findall\\('v:Page', ns\\)]\")",
+      "Bash(python3 *)",
+      "Bash(curl -sL -o /dev/null -w '%{http_code} %{url_effective}' http://qudt.org/vocab/quantitykind/__TRACKED_VAR__)",
+      "WebFetch(domain:qudt.org)",
+      "Bash(curl -sL -o /dev/null -w \"%{http_code} %{url_effective}\\\\n\" \"https://w3id.org/ogc/hosted/seadots/prop-rel/\")",
+      "Bash(curl -sL -o /dev/null -w \"%{http_code} %{url_effective}\\\\n\" --max-time 10 \"https://id3.seadots.eu/\")",
+      "Bash(curl -sL -o /dev/null -w \"%{http_code} %{url_effective}\\\\n\" --max-time 10 \"https://id3.seadots.eu/indicator/\")",
+      "Bash(grep -vE '^\\(https|file|urn|tel|mailto\\)$')",
+      "WebFetch(domain:www.obofoundry.org)",
+      "WebFetch(domain:dwc.tdwg.org)",
+      "WebFetch(domain:www.ebi.ac.uk)",
+      "WebFetch(domain:rs.tdwg.org)",
+      "WebFetch(domain:tdwg.github.io)",
+      "Bash(mkdir -p /Users/piotr/repos/seadots/bblocks-seadots/_sources/odd-protocol/examples /Users/piotr/repos/seadots/bblocks-seadots/_sources/odd-protocol/tests)",
+      "Bash(cp /Users/piotr/repos/Iliad/iliad-apis-features/_sources/odd-protocol/bblock.json /Users/piotr/repos/Iliad/iliad-apis-features/_sources/odd-protocol/context.jsonld /Users/piotr/repos/Iliad/iliad-apis-features/_sources/odd-protocol/description.md /Users/piotr/repos/Iliad/iliad-apis-features/_sources/odd-protocol/examples.yaml /Users/piotr/repos/Iliad/iliad-apis-features/_sources/odd-protocol/schema.yaml /Users/piotr/repos/seadots/bblocks-seadots/_sources/odd-protocol/)",
+      "Bash(cp '/Users/piotr/repos/Iliad/iliad-apis-features/_sources/odd-protocol/examples/*.json' /Users/piotr/repos/seadots/bblocks-seadots/_sources/odd-protocol/examples/)",
+      "Bash(cp /Users/piotr/repos/Iliad/iliad-apis-features/_sources/odd-protocol/tests/test.yaml /Users/piotr/repos/seadots/bblocks-seadots/_sources/odd-protocol/tests/)"
     ]
   }
 }

.claude/skills/context-completeness-checker/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: context-completeness-checker
+description: Use when checking whether every property key in a JSON-LD instance has a corresponding @id mapping in its @context. Walks the instance recursively, lists unmapped properties, ambiguous mappings (multiple @ids), and context terms that are declared but never used. Catches the silent "property without semantic mapping" failure that JSON Schema validation alone misses.
+---
+
+# Context Completeness Checker Skill
+
+## Purpose
+
+Given a JSON-LD instance and a `@context` (either inline or by path), assert that every property key in the instance has a semantic mapping (`@id`) defined in the context. Reports:
+
+- **unmapped**: keys present in the instance but with no context entry
+- **ambiguous**: keys mapped to multiple `@id`s (typically a context bug)
+- **context_unused**: context terms that no instance key uses (cleanup candidate)
+
+## Activation
+
+Use this skill when:
+
+- validating a rendered pygeoapi JSON-LD output against a bblock context
+- auditing a published example file against its `context.jsonld`
+- ensuring every property in a STAC/DCAT JSON-LD has an authoritative vocabulary mapping
+
+Do not use this skill for:
+
+- JSON Schema validation (use `response-schema-validator`)
+- SHACL validation
+- syntactic JSON-LD validity (use `pyld` for context expansion)
+
+## Required input
+
+- `instance` — JSON-LD object (dict or list of dicts) OR a URL to fetch
+- `context` — either:
+  - inline `@context` object (preferred; what pygeoapi embedded)
+  - URL to a `context.jsonld`
+  - file path
+
+## Optional input
+
+| Parameter | Default | Meaning |
+|---|---|---|
+| `ignore_keywords` | `["@context", "@id", "@type", "@graph", "@list", "@set", "@value", "@language", "@reverse", "@nest", "type", "id"]` | JSON-LD keywords and trivial aliases that don't need an explicit `@id` |
+| `descend` | `true` | recurse into nested objects and arrays |
+| `feature_path` | `properties` | when checking pygeoapi features, descend into `properties` and each feature in `features[]` |
+
+## Process
+
+### Phase 1 — load both
+
+If `instance` is a URL, fetch it:
+
+```bash
+curl -sfL -H "Accept: application/ld+json" "${instance}"
+```
+
+If `context` is a URL, fetch and parse. If it's a file path, read. If inline, use directly.
+
+### Phase 2 — collect declared terms
+
+Walk the parsed `@context` (single object or array of objects). Build:
+
+```python
+declared = {
+  "submergedInfrastructureArea": "indo:submerged-infrastructure-area",
+  "symbol": "prop-rel:hasSymbol",
+  # ...
+}
+```
+
+Handle nested `@context` blocks inside term definitions (JSON-LD 1.1) by tracking the path: a key inside `symbols[i]` is checked against the inner `@context` first, then the outer.
+
+### Phase 3 — walk the instance
+
+For every object encountered (recursively):
+
+1. for each key not in `ignore_keywords`:
+   - is it declared in the current `@context` scope? → ok
+   - declared multiple times in nested scopes with **different** `@id`s? → `ambiguous`
+   - not declared anywhere? → `unmapped`
+2. recurse into nested values when `descend=true`.
+
+Track `used_terms` so that, after the walk, `context_unused = declared.keys() - used_terms`.
+
+### Phase 4 — report
+
+```json
+{
+  "pass":           false,
+  "checked_keys":   142,
+  "unmapped": [
+    { "key": "windEnergyOutputMW", "first_seen_at": "features[3].properties.windEnergyOutputMW" },
+    { "key": "turbineCountAdjusted", "first_seen_at": "features[3].properties.turbineCountAdjusted" }
+  ],
+  "ambiguous": [],
+  "context_unused": [
+    "fishingExclusionFraction",
+    "areaUseByWindPark"
+  ],
+  "suggestions": [
+    { "key": "windEnergyOutputMW", "suggested_id": "qudt:value", "rationale": "matches QUDT pattern" }
+  ]
+}
+```
+
+`pass = (unmapped == []) and (ambiguous == [])`.
+
+`context_unused` is **informational** — does not fail the run; surface as a cleanup hint.
+
+### Phase 5 (optional) — vocabulary lookup for `unmapped`
+
+For each `unmapped` key, optionally try to suggest a mapping by:
+
+- exact-string lookup in NERC P01 / CF Standard Names / Darwin Core terms (via the existing `web-browsing-mcp` skill if online)
+- token similarity against terms declared in the context
+
+This is best-effort and surfaces under `suggestions[]`. The harness can disable it with `suggest=false`.
+
+## Outputs
+
+The report dict above.
+
+## Edge cases
+
+| Situation | Handling |
+|---|---|
+| Context declares a term with the same `@id` twice (consistent) | Allow; not ambiguous |
+| Instance has no `@context` (plain JSON) and `context=` not supplied | Fail with "no context available — supply context= or embed @context inline" |
+| Context is itself an array of contexts (JSON-LD 1.1) | Walk each in order; later entries override earlier on key collisions |
+| Instance is an OGC API FeatureCollection (`type=FeatureCollection`) | Auto-recurse into `features[].properties` |
+| Property key uses a JSON-LD prefix (e.g. `"dwc:scientificName"`) | Pass if the prefix is declared and the suffix isn't required to be a context term |
+
+## Interactions with other skills
+
+- Called by `pygeoapi-test-harness` after `response-schema-validator`. Combined report is returned to the user.
+- Can run standalone against any `example.json + context.jsonld` pair in a bblock — useful as a pre-commit check.
+
+## References
+
+- JSON-LD 1.1 (context evaluation) — https://www.w3.org/TR/json-ld11/#context-definitions
+- `pyld` — https://github.com/digitalbazaar/pyld
+- NERC Vocabulary Server — https://vocab.nerc.ac.uk/