# terria-catalog

> A Python SDK and AI toolset for editing TerriaJS initialization catalogs as
> typed objects instead of raw JSON, with safe versioned publishing to S3.

An AI assistant can manage a Terria catalog (add/move/remove/update datasets,
organize groups, validate, publish, roll back) through three surfaces that all
share the same tool set: an MCP server, a `terria-catalog` CLI, and a Python
`CatalogSession`. Items are described as **partial Terria JSON**
(`{"type": "wms", "name": "...", "url": "..."}`); the toolkit resolves the correct
typed object, validates, and publishes with version history and rollback.

## Core rules for an AI editing a catalog

- Call `reload_catalog` / `describe_catalog` first to see the current tree.
- Address members by `id`, `name`, or path (`/Water Resources/Reservoirs`).
- Make edits (they accumulate in a working copy), then `preview_changes`.
- `validate_catalog` before publishing; fix any reported problems.
- `publish` and `rollback` REQUIRE `confirm: true` — surface the preview to the
  human first.
- Never emit raw catalog JSON to the user; use the tools.

## Item types (the `type` field)

geojson, wms, wmts, csv, shp, cog, cesium-terrain, 3d-tiles, ion-imagery,
esri-mapServer, esri-featureServer, group. Any Terria trait may be set on an item;
unknown traits are preserved.

## Docs

- [AI usage guide](docs/AI_USAGE.md): MCP setup, CLI, tools, safety model.
- [System prompt](docs/system_prompt.md): drop-in grounding for an assistant.
- [Architecture](docs/ARCHITECTURE.md): how the library is built.
- [README](README.md): the Python API.
