Add Enrichment to a Pack

Raw spatial data tells you what exists — property boundaries, road segments, terrain elevation. Enrichment adds meaning: which properties are best suited for solar, which road segments serve the most traffic, which terrain slopes are too steep for development. The spatialpack ai commands use AI to analyze your data and propose derived attributes automatically.

This recipe walks through enriching an existing Spatial Pack layer with AI-generated attributes.

Note

AI enrichment requires a configured AI gateway. Run spatialpack ai config show to check your current configuration. See the CLI ai reference for setup details.

Prerequisites

• spatialpack CLI installed (pip install -e ".[full]")
• An existing Spatial Pack with at least one vector layer (GeoParquet file)
• AI gateway configured (Anthropic API key or OpenRouter credentials)

Steps

1. Identify the layer to enrich

List the layers in your Spatial Pack by inspecting the manifest.

spatialpack pack info ./my-solar-pack

Expected output:

Pack: spatial.properties:wa:solar-feasibility:v1
Version: 2025.01.31
Layers:
  - cadastre (vector) - Cadastre Boundaries
  - roads (vector) - Road Network
  - bushfire_prone (vector) - Bushfire Prone Areas

What just happened: The pack info command read the spatialpack.json manifest and listed all available layers. Pick the layer you want to enrich — in this example, the cadastre layer.

2. Analyze the layer

Run spatialpack ai analyze against the GeoParquet file. The AI profiles the data (column types, value distributions, spatial extent) and proposes enrichment attributes.

spatialpack ai analyze ./my-solar-pack/layers/cadastre.parquet

Expected output:

Profiling cadastre.parquet...
  Features: 12,847
  Columns: lot_number, plan_number, area_m2, geometry
  CRS: EPSG:4326
  Bbox: [115.65, -32.15, 116.15, -31.65]

AI Analysis (claude-haiku-4-5):
  Proposed enrichments:
  1. lot_size_category: Classify lots by area (small/medium/large/broadacre)
  2. solar_suitability_score: Rate solar potential based on lot area and shape
  3. development_density: Estimate development intensity from lot patterns

Accept proposals? [y/n/edit]

What just happened: The AI profiled your data — examining column types, value ranges, and spatial distribution — then proposed three new derived attributes. Each proposal includes a name, description, and the logic the AI will use to compute it.

3. Review and accept proposals

Review the AI’s proposals. Accept all of them, or edit individual proposals before proceeding.

# Accept all proposals without interactive review (useful in CI)
spatialpack ai analyze ./my-solar-pack/layers/cadastre.parquet --accept-all

Expected output:

Enrichment YAML written to: enrichments/cadastre.yaml
  3 enrichments defined
  Apply with: spatialpack pack build (include enrichment stage in pipeline)

What just happened: The AI generated an enrichment definition file in YAML format. This file describes the derived attributes and the logic to compute them. The enrichment is not applied yet — it produces a specification that the Pipeline system executes.

4. Preview without writing

Use --dry-run to see what the AI proposes without saving anything to disk.

spatialpack ai analyze ./my-solar-pack/layers/cadastre.parquet --dry-run

What just happened: The AI ran the same analysis but only displayed the proposals in the terminal. No files were created. This is useful for evaluating whether enrichment makes sense for a given layer before committing to it.

5. Customize the analysis

Control the AI model and the number of rows profiled for large datasets.

spatialpack ai analyze ./my-solar-pack/layers/cadastre.parquet \
  --model claude-haiku-4-5-20251001 \
  --max-rows 5000 \
  -o enrichments/cadastre-custom.yaml

What just happened: You specified a particular AI model, limited profiling to 5,000 rows (faster for large datasets), and directed the output to a custom path. The --max-rows flag samples the dataset rather than reading every row, which speeds up analysis on datasets with millions of features.

Tip

Enrichment works best on vector layers with meaningful attribute columns. Layers that only contain geometry (no attribute data) produce less useful enrichments.

6. Check your AI gateway configuration

If you encounter authentication errors, verify your gateway setup.

spatialpack ai config show

Expected output:

AI Gateway Configuration:
  Provider: anthropic
  Model: claude-haiku-4-5-20251001
  Max tokens: 4096
  Temperature: 0.0

What just happened: The config show command displayed your current AI gateway settings. If the provider or model is incorrect, use spatialpack ai config set to update it. See the CLI ai reference for the full configuration options.

Next steps

• Build a Pipeline from YAML — Include enrichment stages in a Pipeline for automated processing
• What is a Spatial Pack — Understand how enrichment fits into the pack structure
• CLI ai reference — Full options for spatialpack ai analyze and spatialpack ai config