activeinferenceinstitute/geo_infer/geo-infer-api

GEO-INFER-API

Instructions

Core Capabilities

• Agent interfaces: AgentSession script API, geo-infer JSON CLI and

geo-infer-mcp stdio tools share public API discovery and execution across all 45 modules. Native handles, typed inputs and context entry/exit support stateful scientific workflows. Installed wheels include all 46 skill texts.

• REST endpoints: FastAPI app with health, GeoJSON feature, and processing-algorithm routes (/api/v1)
• GeoJSON utilities: RFC 7946 models plus validation, ray-cast containment, buffering, and RDP simplification helpers
• Middleware: error handling and request logging wired into create_app
• CORS: explicit, wildcard-free origin lists enable credentialed CORS (fail-closed)

Out of scope for this module: GraphQL schema, JWT/API-key authentication middleware, rate limiting. There is no auth middleware today; SECRET_KEY is a required fail-closed setting only.

Key Imports

from geo_infer_api.app import create_app
from geo_infer_api import AgentSession
from geo_infer_api.core.config import Settings, get_settings
from geo_infer_api.core.middleware import ErrorHandlerMiddleware, RequestLoggingMiddleware
from geo_infer_api import (
    Feature, FeatureCollection, Polygon, PolygonFeature,
)
from geo_infer_api.utils.geojson_helpers import (
    polygon_contains_point, create_buffer, simplify_polygon,
    calculate_polygon_area, validate_polygon_rings,
)

Examples

Build the FastAPI application (requires SECRET_KEY to be set):

import os
os.environ["SECRET_KEY"] = "change-me"
from geo_infer_api.app import create_app
app = create_app()  # serve with: uvicorn geo_infer_api.app:main_app

Point-in-polygon and buffering on GeoJSON polygons:

from geo_infer_api.utils.geojson_helpers import polygon_contains_point, create_buffer
square = {"type": "Polygon", "coordinates": [[(0, 0), (10, 0), (10, 10), (0, 10), (0, 0)]]}
assert polygon_contains_point(square, (5.0, 5.0)) is True
buffered = create_buffer(square, distance=1.0, unit="kilometers")

Agent interfaces

Use uv run --frozen geo-infer catalog API to discover public source APIs, then geo-infer describe before calling a selected target. Scripts use geo_infer_api.agent_runtime.AgentSession; the optional stdio MCP server is geo-infer-mcp. See requests, native objects and composition. The adapter retains this module's dependencies and authorization requirements.

Guidelines

• FastAPI with async handlers for spatial operations
• Response format defaults to GeoJSON (RFC 7946, [lon, lat] coordinate order)
• The polygon feature store is process-local memory — data does not survive worker restarts; it is capped at polygon_store_max_size (default 10,000) and further POSTs beyond the cap return 409 RESOURCE_CONFLICT
• Test: uv run python GEO-INFER-TEST/run_unified_tests.py --module API

Integrations

• SEC → Security utilities; authentication middleware requires explicit application integration
• DATA → Spatial query endpoint data sources
• SPACE → H3 and geographic query parameters (algorithms router proxies geo_infer_space.core.algorithm_registry when installed; 503 otherwise)
• OPS → API monitoring via /health
• APP → Frontend consuming API endpoints

Persistent sessions and performance

Use geo-infer doctor to inspect actual runtime and unprobed native status. Use geo-infer session for JSON Lines with persistent handles, or Python with AgentSession() / async with for deterministic entered-context cleanup. MCP exposes geo_diagnostics and geo_close; close ends execution until restart. Benchmark the real adapter with python -m geo_infer_api.agent_benchmarks or call geo_infer_api.agent_benchmarks:benchmark_agent through any surface. Read profiling controls and evidence before selecting Python 3.15 sampling or interpreting throughput results.

Native result selection

Use get / MCP geo_get with a path array to index a retained result after public member selection. Tagged slice values use data: [start, stop, step] with integers/null and a nonzero step; tagged tuple indexes select multiple scientific axes. These indexes also work in $ref.path for native composition. Use save_as when retaining a selected native view and its dtype matters. Automatic opaque reads reuse an existing identity handle; explicit aliases still consume capacity. Read a public value directly with geo-infer get TARGET --path JSON.

Strict requests and native maps

Selectors must name exactly one nonempty target or handle; optional members must also be nonempty. The MCP adapter validates raw arguments before SDK coercion, rejecting unknown keys and incorrect types before execution. Optional null defaults retain their advertised meaning. Returned dictionaries containing reserved $ref, $type, $literal or $callable keys are retained as native handles, including nested collisions. Use $ref and get.path to compose or select them. Explicit caller $literal inputs remain exact user data. Python session context managers preserve an entered native context's exception suppression as well as cleanup.

If retaining an enter result fails (including handle capacity), its newly entered context is unwound immediately with that exception. Existing entered contexts and aliases remain owned. Native suppression still runs cleanup, but the missing response remains a failure; native cleanup exceptions propagate. REST polygon IDs use string storage identity, so integer 1 and string "1" conflict. Updates validate supplied body IDs even when the ID is zero.