GEO-INFER Framework

GEO-INFER is a 44-module geospatial inference monorepo from the Active Inference Institute — spatial analysis, Active Inference, Bayesian modeling, domain modeling, agent workflows, and reproducible repository validation in one uv/Python workspace.

Build geospatial and place-based models, run Active-Inference and Bayesian inference over them, orchestrate agents and domain workflows, and keep the whole thing reproducible — served from a user documentation hub backed by an auto-generated, validation-gated module catalog.

What's inside

• 🧭 Spatial & place-based analysis — geospatial data, H3 grids, place & time modeling, and Earth-system domains (water, marine, forest, climate, energy, transport, emergency).
• 🧠 Active Inference & Bayesian modeling — Active-Inference agents and Bayesian models (Bayes, simulation, SPM, cognition, math).
• 🤖 Agent & AI orchestration — agent workflows, AI/LLM integration, communications, and operations.
• 🏛️ Governance, risk & domain modeling — risk, meta-governance, norms, economics, policy, security, health, and civil domains.
• 🗄️ Data, API & applications — data pipelines, APIs, applications, IoT, art, and education.
• 🛠️ Infrastructure & validation — documentation hub (INTRA), the validation & test harness, logging, git, examples, and bio.

Current Repository Facts

Metric	Value
Modules	44
Python source files	894
Python test files	503
Repository README.md files	849
Repository AGENTS.md files	848

Quick Start

uv sync --all-packages --all-extras
python -m compileall GEO-INFER-*/src GEO-INFER-*/examples
uv run python GEO-INFER-TEST/validate_repo_contracts.py --strict-source-language
uv run python GEO-INFER-TEST/validate_documentation.py --strict
uv run python manuscript/generate_research_artifacts.py
uv run python GEO-INFER-TEST/run_unified_tests.py --category unit

Documentation Map

• User documentation hub: GEO-INFER-INTRA/docs/index.md
• Installation and first workflow: GEO-INFER-INTRA/docs/getting_started/index.md
• Framework architecture: GEO-INFER-INTRA/docs/overview.md
• Module catalog: GEO-INFER-INTRA/docs/modules/index.md
• Developer workflow: GEO-INFER-INTRA/docs/developer_guide/index.md
• Test and release gates: GEO-INFER-TEST/docs/index.md
• Manuscript generation and evidence: manuscript/README.md
• Active Inference reference: GEO-INFER-INTRA/docs/active_inference_guide.md
• Spatial/H3 reference: GEO-INFER-INTRA/docs/geospatial/data_formats/h3/index.md
• Contribution rules: CONTRIBUTING.md
• Security reporting: SECURITY.md
• Release history: CHANGELOG.md

The repository root and module-level README.md/AGENTS.md files are generated signposts. Conceptual tutorials, integration guidance, and policy live in the INTRA documentation hub; executable behavior and public exports remain owned by the module source and its tests.

Choose an Installation Profile

The repository is a uv workspace. Use the full sync when working across module boundaries, or sync a single package when developing one module:

uv sync --all-packages --all-extras
uv sync --package geo-infer-act
uv sync --package geo-infer-space
uv sync --package geo-infer-ant

--all-extras installs optional scientific, Bayesian, web, IoT, performance, quality, and documentation dependencies. CI intentionally omits native-only extras that cannot build on its CPU runner; see .github/workflows/ci.yml for the exact reproducible exception list.

Module Themes

Theme	Modules
🌍 Spatial & Place-based	GEO-INFER-SPACE, GEO-INFER-PLACE, GEO-INFER-TIME, GEO-INFER-MARINE, GEO-INFER-WATER, GEO-INFER-FOREST, GEO-INFER-CLIMATE, GEO-INFER-ENERGY, GEO-INFER-TRANSPORT, GEO-INFER-EMERGENCY
🧠 Bayesian & Active Inference	GEO-INFER-BAYES, GEO-INFER-SIM, GEO-INFER-SPM, GEO-INFER-COG, GEO-INFER-ACT, GEO-INFER-MATH
🤖 Agents & AI Orchestration	GEO-INFER-AGENT, GEO-INFER-AG, GEO-INFER-AI, GEO-INFER-ANT, GEO-INFER-OPS, GEO-INFER-COMMS
🏛️ Governance, Risk & Domain	GEO-INFER-RISK, GEO-INFER-METAGOV, GEO-INFER-NORMS, GEO-INFER-ECON, GEO-INFER-PEP, GEO-INFER-REQ, GEO-INFER-SEC, GEO-INFER-CIV, GEO-INFER-HEALTH, GEO-INFER-ORG
🗄️ Data, API & Applications	GEO-INFER-API, GEO-INFER-APP, GEO-INFER-DATA, GEO-INFER-IOT, GEO-INFER-ART, GEO-INFER-EDU
🛠️ Infrastructure & Validation	GEO-INFER-INTRA, GEO-INFER-TEST, GEO-INFER-LOG, GEO-INFER-GIT, GEO-INFER-EXAMPLES, GEO-INFER-BIO

Module Index

Module	Package	Source files	Test files
GEO-INFER-ACT	geo_infer_act	42	32
GEO-INFER-AG	geo_infer_ag	15	10
GEO-INFER-AGENT	geo_infer_agent	25	13
GEO-INFER-AI	geo_infer_ai	15	11
GEO-INFER-ANT	geo_infer_ant	24	9
GEO-INFER-API	geo_infer_api	13	9
GEO-INFER-APP	geo_infer_app	13	7
GEO-INFER-ART	geo_infer_art	21	8
GEO-INFER-BAYES	geo_infer_bayes	33	19
GEO-INFER-BIO	geo_infer_bio	9	7
GEO-INFER-CIV	geo_infer_civ	8	7
GEO-INFER-CLIMATE	geo_infer_climate	13	8
GEO-INFER-COG	geo_infer_cog	20	13
GEO-INFER-COMMS	geo_infer_comms	19	8
GEO-INFER-DATA	geo_infer_data	23	20
GEO-INFER-ECON	geo_infer_econ	34	13
GEO-INFER-EDU	geo_infer_edu	7	7
GEO-INFER-EMERGENCY	geo_infer_emergency	7	8
GEO-INFER-ENERGY	geo_infer_energy	11	9
GEO-INFER-EXAMPLES	geo_infer_examples	4	5
GEO-INFER-FOREST	geo_infer_forest	11	8
GEO-INFER-GIT	geo_infer_git	20	9
GEO-INFER-HEALTH	geo_infer_health	18	9
GEO-INFER-INTRA	geo_infer_intra	11	7
GEO-INFER-IOT	geo_infer_iot	16	9
GEO-INFER-LOG	geo_infer_log	19	9
GEO-INFER-MARINE	geo_infer_marine	12	8
GEO-INFER-MATH	geo_infer_math	66	16
GEO-INFER-METAGOV	geo_infer_metagov	23	13
GEO-INFER-NORMS	geo_infer_norms	19	9
GEO-INFER-OPS	geo_infer_ops	23	12
GEO-INFER-ORG	geo_infer_org	8	7
GEO-INFER-PEP	geo_infer_pep	33	9
GEO-INFER-PLACE	geo_infer_place	29	14
GEO-INFER-REQ	geo_infer_req	8	7
GEO-INFER-RISK	geo_infer_risk	30	14
GEO-INFER-SEC	geo_infer_sec	21	10
GEO-INFER-SIM	geo_infer_sim	15	6
GEO-INFER-SPACE	geo_infer_space	83	35
GEO-INFER-SPM	geo_infer_spm	26	18
GEO-INFER-TEST	geo_infer_test	14	23
GEO-INFER-TIME	geo_infer_time	15	13
GEO-INFER-TRANSPORT	geo_infer_transport	7	8
GEO-INFER-WATER	geo_infer_water	11	7

Modular Hygiene

• Root pyproject.toml, uv.lock, and .python-version are the canonical uv environment surfaces.
• Sync the full workspace with uv sync --all-packages --all-extras before repo-wide validation.
• Each module owns importable behavior under src/ and keeps at least four pytest files under tests/.
• Planned work belongs in root TODO.md or a tracked issue, not source or test task markers.
• Importable libraries use logging.getLogger(__name__); process-wide logging configuration belongs in CLI entrypoints.

Validation

• Repository contracts: uv run python GEO-INFER-TEST/validate_repo_contracts.py --strict-source-language
• Documentation links and current-state claims: uv run python GEO-INFER-TEST/validate_documentation.py --strict
• Syntax gate: python -m compileall GEO-INFER-*/src GEO-INFER-*/examples
• Skill contracts: uv run python GEO-INFER-TEST/validate_skills.py --check-xrefs
• Unit tests: uv run python GEO-INFER-TEST/run_unified_tests.py --category unit
• Integration tests: uv run python GEO-INFER-TEST/run_unified_tests.py --category integration
• System tests: uv run python GEO-INFER-TEST/run_unified_tests.py --category system
• Performance tests: uv run python GEO-INFER-TEST/run_unified_tests.py --category performance
• Coverage gate: uv run python GEO-INFER-TEST/run_unified_tests.py --category coverage --timeout 900
• H3 contracts: uv run python GEO-INFER-TEST/run_unified_tests.py --h3-migration
• Test contract: uv run python GEO-INFER-TEST/validate_test_contracts.py --strict
• Model contract: uv run python GEO-INFER-TEST/validate_model_contracts.py --strict --seed 42
• Reproducible model audit: uv run python GEO-INFER-TEST/run_model_audit.py --seed 42 --reproducible
• Source runtime hygiene: uv run --with 'ruff>=0.3.0' ruff check GEO-INFER-*/src --select F821,F823,E721,E722
• Manuscript variables, figures, captions, and resolved copies: uv run python manuscript/generate_research_artifacts.py

Repo-wide Change Workflow

1. Inspect the owning module and keep behavior in its src/ package.
2. Add or update a focused test in the owning module's tests/ directory.
3. Run the focused test, then compile and run the contract validators.
4. Refresh generated signposts with uv run python GEO-INFER-TEST/rewrite_readme_agents.py.
5. Confirm generated documentation is stable with uv run python GEO-INFER-TEST/rewrite_readme_agents.py --check.

Artifact and Output Hygiene

• Test reports belong under .geo-infer-test-results/.
• Model-audit artifacts are emitted under .geo-infer-test-results/model-audit/.
• The manuscript pipeline is the only approved writer to ignored repository-root output/; scenario and other visualization outputs must use an explicit output directory and must not write there.
• Generated signposts must describe tracked files only; local caches and build products are intentionally excluded.

README.md and AGENTS.md files below the repository root are generated signposts. The generator derives their contents from tracked files, public symbols, module metadata, validation commands, and test inventories; update the generator when the documentation contract itself changes.

Failure Triage

• validate_repo_contracts.py: source layout, language, dependency, logger, and documentation contract.
• validate_test_contracts.py: test inventories, markers, fixtures, skips, and warning policy.
• run_unified_tests.py: module behavior by unit, integration, performance, or H3 category.
• validate_model_contracts.py and run_model_audit.py: deterministic model outputs and reproducibility artifacts.
• rewrite_readme_agents.py --check: generated README/AGENTS drift; rerun the generator after intentional tracked-file changes.

Zero-warning test policy

The shared pytest policy treats warnings as errors, requires strict markers/configuration, assigns exactly one primary marker to every test, and rejects skips, xfails, xpasses, collection errors, missing dependencies, missing fixtures, and empty selections. Every module has a test inventory at GEO-INFER-*/tests/README.md; the inventory records purpose, fixtures, dependencies, artifacts, and triage commands.

Documentation Policy

README.md and AGENTS.md files describe current, discoverable repository state. Do not add aspirational APIs to these files unless the implementation, export path, and validation command exist in this checkout. Keep module-local public exports and test commands synchronized through the generator.