GEOAI — THE STACK IN ACTION
X-GeoAI — a design for explainable geospatial AI.
Where volunteers can scale crisis response, offline.
X-GeoAI (Explainable Geospatial AI) is the first real application outside of QuKaiZen's own components. The design is a zero-egress inference runtime for the MapSwipe/fAIr ecosystem, aimed at rapid damage assessment: ARAIL conducts the research, DDaC controls and compiles the data plane, and QueueLLM provides the reasoning engine via secure, local, and controllable inference. The X is the point — vision language models compare pre-disaster baseline imagery against post-disaster imagery and return plain-language claims with their evidence and alternatives (“building destroyed, trees downed, road impassable”), so a responder gets the why, not just a score. Every run carries a cryptographic receipt proving what happened, and no data leaves the machine. None of it is built or deployed yet; this site documents the design and the schemas so the plan is honest about what exists today.
STATUS: PRE-PRODUCTION, DESIGN STAGE (M0) — schemas and docs are drafted; the runtime is not built. Aimed at crisis response and the OpenStreetMap ecosystem, with MapSwipe as the intended first integration. Independent project, not affiliated with MapSwipe, HeiGIT, HOT, or the OSMF.
THE GOAL
Volunteer time goes down at equal-or-better map quality — and every prediction can prove where it came from.
The humanitarian mapping and crisis response loop starts with rapid damage assessment: open satellite imagery and OSM baselines train geospatial reasoning models (HOT's fAIr), X-GeoAI provides explainable predictions via VLM reasoning with evidence, volunteers validate findings (MapSwipe), and reviewed changes land in OpenStreetMap. X-GeoAI supplies what the loop lacks — a zero-egress inference runtime with receipts, explainable predictions (not just scores), an analyst review gate, and geographic grounding. Humans stay in the loop structurally: AI reasoning is never pushed into OSM directly.
open imagery + OSM labels → local model predictions (fAIr / GeoAI)
→ analyst review + receipts (GeoAI)
→ volunteer validation (MapSwipe)
→ reviewed edits in OpenStreetMap
→ feedback for better modelsHOW IT WORKS — THE FIVE PLANES
THE HARD BOUNDARY
Nothing that touches the network ever touches a model. Acquisition (ACQUIRE) and publishing (PUBLISH) are online and explicit; inference (INFER) runs zero-network in secure-zero-egress-claw. One process is never allowed to do all three.
THE TARGET CLI
dac materialize project.yaml dac verify bundle/sha256-87af geoai run bundle/... --profile \ secure-zero-egress-claw geoai review run_01J... dac export run_01J... \ --format mapswipe-review-package
THE CONTRACTS — SHIPPED TODAY
geoai.bundle-manifest/v1alpha1
The trust boundary. Content-addressed assets, declared model + task + policy. No URLs, no credentials.
geoai.prediction/v1alpha1
Label, evidence claims with GeoJSON geometry, alternative explanations, raw model score only.
geoai.receipt/v1alpha1
What actually executed: bundle/model/task digests, engine build, enforcement level, egress result.
geoai.sandbox-profile/v1alpha1
secure-zero-egress-claw: network none, read-only inputs, write-only output, fail-closed.
POWERED BY DAC — DATA AS CODE
DaC is the control plane of this integration.
GeoAI never touches the network — DaC does, explicitly.
Every run starts and ends in Data as Code. DDaC owns everything online and declarative: dataset manifests and STAC ingestion, imagery acquisition with licenses and provenance hashes, geographic train/eval splits, task definitions, model selection, and the run declaration itself. It resolves all of that into an immutable, content-addressed bundle — then hands off. Inference runs zero-network inside secure-zero-egress-claw; when a human approves the reviewed results, it is DaC again that exports the MapSwipe review package. One process is never allowed to acquire, infer, and publish.
DaC (online) declare InferenceRun → acquire assets → pin licenses,
provenance, spatial splits → materialize bundle
GeoAI (offline) verify digests → infer in the sandbox → receipt
DaC (online) dac export run_01J... --format mapswipe-review-package
— explicit, human-approved, the only exitTHE PINNED CONTRACTS
GeoAI consumes three DaC contracts as pinned spec: dac.manifest/v2 (what assets, which licenses, which digests, which splits), dac.zero-claw-exec/v1 (the fully resolved envelope handed to the sandbox), and the InferenceRun declaration — a run as code, every input digest-pinned.
ALSO THE KNOWLEDGE BASE
DaC isn't only the control plane and the zero-egress sandbox's supplier — it's also the engine that built the GeoAI World: 100+ sourced terms covering imagery, the MapSwipe/fAIr ecosystem, this stack, and the runtime itself, every card gated for a source and a closed reference graph. Same engine, two jobs.
HONESTY NOTE
The contracts are pinned from DaC ADR-0005, still on an unmerged branch — GeoAI tracks them as spec without blocking on the merge, and without drifting from them.
GO DEEPER
ARCHITECTURE
The five-plane design
CLI walkthrough, the analyst review UI, and the four pinned schemas.
WORKER INTEGRATION
The engine-level plumbing
QueueLLM lifecycle, the DaC control-plane flow, receipts — not MapSwipe-specific.
MAPSWIPE INTEGRATION
The community path
The fAIrSwipe flow, the export package, the four maintainer agreements.
YOUNG MAPPERS
Check the AI's homework.
Every swipe helps real mappers help real people. The judgment is visual and binary — is that a building, or a shadow? — which means kids are genuinely good at it, and they love catching a computer being wrong.
The real thing happens in the MapSwipe app: a family mapathon on the couch, a classroom session on a Saturday, a few spare minutes on a phone. GeoAI's job is invisible — composing prediction queues that are representative, calibrated, and worth a volunteer's time. The fun part is all MapSwipe.
Kid participation happens entirely in MapSwipe under MapSwipe's own terms. GeoAI runs no volunteer accounts and collects nothing.
Before you swipe, learn the world →TRY IT — CHECK THE AI'S HOMEWORK
TILE 1/8 · SCORE 0
The AI thinks: BUILDING (91% sure)
Is it right? Tap a button, or use ← / → arrow keys.
DEMO WITH ILLUSTRATED TILES — REAL MISSIONS HAPPEN ON MAPSWIPE. NO DATA IS COLLECTED.
WHAT IT'S DESIGNED TO DO — none of this is built yet
ZERO-EGRESS BY DESIGN
To be proven, not just configured
The sandbox profile is specified to enforce DNS, IPv4/IPv6, UDP, and subprocess isolation, with every run producing an egress audit report signed into the receipt. The adversarial test suite that proves this is a roadmap item, not shipped.
DETERMINISTIC LIFECYCLE
Designed: load → infer → unload cleanly
QueueLLM's LifecycleController (BUILT, in QueueLLM itself) enforces Init → Loading → Running → ShuttingDown. The geoai worker that would drive it for volunteers so they never manage model memory directly is still design, not code.
CRYPTOGRAPHIC RECEIPTS
Designed so every run is auditable
The schema (geoai.receipt/v1alpha1, shipped as a draft) specifies start/end time, peak RSS, token count, model digest, telemetry events, egress audit status — signed and immutable. No receipt has been produced by a real run yet.
VOLUNTEER-FRIENDLY, BY DESIGN
Meant to run on consumer hardware
Single-binary CLI, no Python interpreter on the hot path, models streaming from NVMe (QueueLLM's layer streaming, BUILT) so even large models can fit on modest RAM. The geoai CLI wrapper volunteers would run doesn't exist yet.
OBSERVABLE TELEMETRY
Designed so every layer transition is tracked
QueueLLM (BUILT) already publishes TokenEmitted, PrefetchHit, LayerEvicted, ArenaReset events to an in-process bus. The geoai worker that would subscribe and log them into a receipt is design, not code.
SCHEMA-VERSIONED CONTRACTS
No drift between tools
geoai.bundle/v1alpha1, geoai.receipt/v1alpha1, geoai.profile/v1alpha1. Consumes pinned dac contracts. Schemas live in qukaizen-geoai repo.
CURRENT WORK
M1 VERTICAL SLICE
Worker Lifecycle Integration
Building the geoai worker to manage QueueLLM's model lifecycle deterministically. The worker will load a model, stream inference while collecting telemetry from the QueueLLM bus, unload cleanly, and finalize a receipt with all observable state transitions.
Pattern: Model fetch → AeroRuntime::new() → subscription to aerollm-bus → generate_streaming() with telemetry drain → LifecycleController::shutdown() on drop → receipt finalization → loop.
See the worker integration guide →