Skip to content
Spatial.Properties

AI-Assisted Analysis

Early Access

Prerequisites

Section titled “Prerequisites”
  • spatialpack CLI installed (pip install -e ".[full]")
  • An existing Spatial Pack with at least one vector layer (GeoParquet)
  • AI gateway configured with one of the following:
    • ANTHROPIC_API_KEY environment variable set, or
    • OPENROUTER_API_KEY environment variable set

Steps

Section titled “Steps”

1. Check your AI gateway configuration

Section titled “1. Check your AI gateway configuration”

Verify the gateway is configured and can reach the language model provider.

Terminal window
spatialpack ai config show

Expected output:

AI Gateway Configuration
  Provider:    anthropic
  Model:       claude-haiku-4-5-20251001
  Status:      configured

If the configuration is missing, set your API key:

Terminal window
# For Anthropic
export ANTHROPIC_API_KEY=sk-...your-key


# For OpenRouter
export OPENROUTER_API_KEY=sk-or-...your-key

2. Analyze a spatial data source

Section titled “2. Analyze a spatial data source”

Run spatialpack ai analyze on a source file to generate an enrichment YAML. The AI profiles the data — examining column names, types, value distributions, and geometry characteristics — and proposes human-readable field descriptions, display names, and formatting rules.

Terminal window
spatialpack ai analyze ./layers/cadastre.parquet

Expected output:

AI Analysis
  Source:     ./layers/cadastre.parquet
  Features:  12,345
  Columns:   8
  Profiling: complete


Enrichment Proposals:
  lot_number   -> "Lot Number" (identifier)
  area_m2      -> "Area (m2)" (numeric, format: 0,000.0)
  zoning       -> "Zoning Classification" (categorical)
  geometry     -> kept as-is


Output: enrichments/cadastre.yaml

The AI reads a sample of the data (up to 10,000 rows by default), infers the semantic meaning of each column, and writes an enrichment YAML file. The enrichment file captures display names, descriptions, formatting rules, and column visibility settings.

3. Preview proposals without writing files

Section titled “3. Preview proposals without writing files”

Use --dry-run to see what the AI would propose without creating any files.

Terminal window
spatialpack ai analyze ./layers/roads.parquet --dry-run

Expected output:

AI Analysis (dry run)
  Source:     ./layers/roads.parquet


Proposals:
  road_name       -> "Road Name" (text)
  road_class      -> "Road Classification" (categorical)
  speed_limit_kmh -> "Speed Limit (km/h)" (numeric)
  length_m        -> "Length (m)" (numeric, format: 0,000.0)


No files written (dry run mode).

Review the proposals before committing them to disk. This is useful when exploring unfamiliar datasets.

4. Customize the analysis model

Section titled “4. Customize the analysis model”

Override the default model for more detailed analysis on complex datasets.

Terminal window
spatialpack ai analyze ./layers/energy_infrastructure.parquet \
  --model claude-sonnet-4-20250514

Higher-capability models produce more nuanced field descriptions and better detect domain-specific terminology (e.g., distinguishing “transmission” from “distribution” lines in energy datasets).

5. Accept all proposals in CI mode

Section titled “5. Accept all proposals in CI mode”

Skip interactive review and accept all AI proposals. This is useful in automated pipelines where human review happens at a later stage.

Terminal window
spatialpack ai analyze ./layers/bushfire_prone.parquet --accept-all

Expected output:

AI Analysis
  Source:     ./layers/bushfire_prone.parquet
  Features:  2,847
  Mode:      accept-all (CI)
  Output:    enrichments/bushfire_prone.yaml

The --accept-all flag writes the enrichment file without pausing for review. Combine with --overwrite to replace an existing enrichment file.

6. Set routing rules for AI tasks

Section titled “6. Set routing rules for AI tasks”

Configure the AI gateway to route different task types to different models and providers. Use faster, cheaper models for routine profiling and more capable models for complex analysis.

Terminal window
spatialpack ai config set enrichment \
  --model claude-haiku-4-5-20251001 \
  --provider anthropic \
  --max-tokens 4096

Expected output:

Gateway Configuration Updated
  Task type:   enrichment
  Model:       claude-haiku-4-5-20251001
  Provider:    anthropic
  Max tokens:  4096

This sets the default model for all enrichment tasks. Individual commands can still override the model with the --model flag.

7. Use enrichment results in a pipeline

Section titled “7. Use enrichment results in a pipeline”

Once you have an enrichment YAML file, the pipeline automatically discovers and applies it during conversion. Place the enrichment file in the enrichments/ directory with a filename matching the layer ID.

pipeline.yaml (excerpt)
stages:
  - name: convert_cadastre
    action: convert.shp
    input: cadastre
    output: "layers/cadastre.parquet"
    options:
      crs: EPSG:4326
      bbox: ${pack.region.bbox}
    layer:
      id: cadastre
      title: "Cadastre Boundaries"
      type: vector

With enrichments/cadastre.yaml present, the convert stage automatically applies the AI-generated display names, descriptions, and formatting rules to the output GeoParquet file.

Next steps

Section titled “Next steps”