AGENTS.md@docs/other/geo_infer git:20261013.15abd4bA

Immutable. This exact content never changes and is served at /api/v1/blob/711a497d0d985c23.

# geo_infer (docs/other archive entry)

## Overview

**Status**: active documentation program (draft) | **Version**: 0.1 | **Last
Updated**: 2026-09-06

## Purpose

Document, for GNN-side readers and agents, the artifact-level interchange
with the sibling spatial active-inference monorepo `GEO_INFER`: how GNN
models are exported as versioned JSON artifacts, and how GEO_INFER consumes
and validates them. This folder is the GNN-side mirror of the canonical
interchange documentation at `../GEO_INFER/GEO-INFER-ACT/docs/gnn_interchange.md`
(cross-repo references are inline code paths, never markdown links). The
sibling is a foreign git repository: never commit into it from GNN tooling.

## Contents

| File | Role |
| --- | --- |
| [README.md](README.md) | Reader-facing entry point: contracts, export command, validation harness |
| [cascadia_river_homing.md](cascadia_river_homing.md) | Worked H3 example: the Cascadia GNN source, exporter checks and fixtures |

## Key paths (post-reorg)

- Producers: `src/gnn/export/geo_infer.py` (categorical),
  `src/gnn/export/geo_infer_gaussian.py` (Gaussian),
  `src/gnn/export/geo_infer_factored.py` (factored).
- Normative format docs: `src/gnn/export/geo_infer_contract.md` and
  `src/gnn/export/geo_infer_factored_contract.md`.
- Export entry point: `uv run python -m gnn.export.geo_infer ...`.
- Consumer boundary (GEO_INFER side): `geo_infer_act.core.gnn_contract`
  (`GNNArtifact`, `run_gnn_inference`).
- Validation harness (GEO_INFER side):
  `GEO-INFER-TEST/validate_gnn_interchange.py`.

## Version facts

- Contracts: `gnn-geo-infer/1` (categorical), `gnn-geo-infer/2` (Gaussian
  `F`/`G`/`H`/`Q`/`R`), `gnn-geo-infer/factored/1` (factored).
- Integration is artifact-level only: separate environments, JSON artifacts
  with SHA-256 provenance, no cross-checkout imports (the GEO_INFER contract
  forbids it).
- H3 support is optional (`--extra geo-infer`).
- The Cascadia seed study emits variant artifacts into its own output edition;
  retain source/state order/export custody and never promote reference golden
  fixtures or native Lean receipts to variant claims.

## Editing rules

- Keep all links relative and verify targets exist; the repository-wide
  documentation audit (`uv run python
  docs/development/docs_audit.py --strict --check-anchors --no-write`) checks
  them for every markdown file.
- Follow [style_guide.md](../../style_guide.md): `uv run python` command
  spellings, H1 title, metadata block, honest claims without embedded
  ungenerated counts.
- Update this folder together with the producer modules under
  `src/gnn/export/`; contract changes bump the contract versions named here.

---

**Status**: active | **Maintenance**: update together with the export
modules under `src/gnn/export/` | **Last Updated**: 2026-09-06