GeoTask

Open verifiable spatiotemporal task protocol and deterministic Core for AI agents.

Current: turn observations, evidence, world state and action conditions into computable, updatable and traceable machine contracts.
Near term: deliver a Reference Agent and developer product toward a trusted world-state runtime.
Long term: become a reusable trusted task infrastructure layer for high-consequence physical-world agents.

pip install geotask-core

GeoTask turns multimodal models, sensors, maps, authoritative data, and human input into explicit world objects, spatiotemporal relations, state, evidence, and action constraints. It builds a world state that is computable, verifiable, updatable, and traceable. Rather than hiding the whole world inside a neural representation, GeoTask makes the facts an agent depends on inspectable, recomputable, correctable, and maintainable.

Multimodal models perceive and reason openly: observations, hypotheses, explanations, and plans from text, maps, imagery, video, and state data.
GeoTask Core provides world-state specifications, interface contracts, and a verification kernel: explicit objects, coordinates, time, relations, evidence, and claims with local deterministic verification.
Verification and control maintain the world: preserve supported facts, expose conflict and unknown states, constrain correction, and manage action eligibility.
Runtimes and Domain Packs connect reality: authoritative data, industry rules, local predictive models, human review, and production actions.

Engineering boundary: GeoTask Core provides public world-state contracts, deterministic validation, exact Artifact binding, and fail-closed control semantics; the verifiable task protocol remains the current implementation form. The implemented public profile covers Observation, World State, bounded Observation Merge, State Transition, Verification Session, Discrepancy Report, Correction Request, Impact Graph, bounded recompute derivation, bounded successor materialization, Incremental Reevaluation Result, Verification Provider Descriptor, Verification Request, Verification Response, Assurance Profile, Trajectory Identity Adjudication, Identity Merge Proposal, Identity Merge Approval Record, Object Graph Change Request, and Object Graph Change Application Approval Record. Core does not fetch external truth, invent undeclared source precedence, publish production output, authorize actions, or execute side effects.

Start here

Why agents need a verifiable world model

Multimodal models are becoming better at understanding scenes, calling tools, and proposing plans, but their “understanding of the world” is usually implicit in context, vectors, or parameters. Before real action, an agent still needs an explicit, shared, verifiable world state that continuously answers:

which objects exist, where and when they exist, and what state they are in;
which relations and constraints hold, remain unknown, conflict, or lack evidence;
which world states and conclusions must change when a new observation arrives;
which facts come from models, sensors, authoritative data, or human review;
which actions are currently permitted by the maintained world state.

A tool call can compute one function, but it does not automatically maintain object identity, world snapshots, evidence state, change impact, or action boundaries. GeoTask organizes those concerns into verifiable and auditable world-model primitives and Artifacts:

flowchart LR
  O[Multimodal observations and external state] --> W[Explicit spatiotemporal world state]
  W --> R[Relations, constraints, and world claims]
  R --> V[Local verification and evidence governance]
  V --> U[State update, correction, and recheck]
  U --> G[Action eligibility and external Runtime]
  N[New observation arrives] --> W

The current public Core implements world objects and spatial contracts, source and evidence bindings, Observation, World State, bounded Observation Merge, State Transition, Verification Session, Discrepancy Report, Correction Request, Impact Graph, source-bound bounded recompute derivation, bounded successor-state materialization, Incremental Reevaluation Result, Verification Provider contracts, Trajectory Identity Adjudication, Identity Merge Proposal, Identity Merge Approval Record, Object Graph Change Request, Object Graph Change Application Approval Record, world claims, deterministic relation verification, control states, mechanical Agent repair, and bounded-path retry. Automatic diff computation, resolution of ambiguous claims without a declared policy, automatic impact discovery and propagation execution, object-graph change application and application-result records, and general-purpose derivation methods remain roadmap capabilities.

Five-minute quickstart

python -m pip install geotask-core
geotask --help
geotask inspect operators

Save this minimal task as my_distance.yaml:

geotask:
  id: "example"
  schema_version: "1.0"

objects:
  a: {type: "point", coordinates: [0, 0]}
  b: {type: "point", coordinates: [3, 4]}

operator_set: [distance_2d]

tasks:
  - id: "calc"
    assertions:
      - id: "ab"
        operator: "distance_2d"
        object_refs: ["a", "b"]

The local executor returns ab = 5.0 meter with assurance_level: local_deterministic.

geotask validate my_distance.yaml
geotask run my_distance.yaml

42 public reference examples across 38 scenario entries

The examples show how model proposals are materialized, recomputed, contradicted, evidence-gated, corrected, and kept behind action boundaries across robotics, UAV, vehicle, and emergency scenarios. GT38–GT42 are not five independent application cases: together they form one five-stage identity-governance composite case about inspection drone UAV-017 receiving a new provisional identity after a brief tracking loss.

Stage	Cases	Main question
Geometry	GT01–GT03	What spatial relationship is actually true?
Space-time composition	GT04–GT06	Do horizontal, vertical, and temporal conditions all hold?
Uncertainty and evidence	GT07–GT09	What happens when evidence is missing or conflicting?
Action and feasibility	GT10–GT20	What executable action follows from verified spatial, resource, response, live-environment, multi-UAV conflict, city-event deduplication, equipment-capability, and high-risk action-gate constraints?
World-state cycle	GT21–GT28	How do multi-source observations, state change, impact scope, bounded correction, incremental reevaluation, and action gates close the loop?
Verification Provider ecosystem	GT29–GT32	How do independent sources, explicit adjudication, progressive authorization, and action gates remain separate?
Dynamic world objects	GT33–GT37 plus the GT38–GT42 composite case	The first five examples cover trajectory semantics and identity candidates; the final five reference examples form one UAV-017 re-identification and identity-governance workflow.

Selected examples:

GT07: unknown is not false when a schedule cannot be verified.
GT09: two individually verified no-fly notices can still conflict.
GT10: two robots competing for one corridor need an explicit coordination policy.
GT11: a target 50 meters away may require a 300-meter accessible route.
GT12: enough energy to arrive is not enough to complete a UAV mission safely.
GT13: an open road may still be impassable for a specific vehicle envelope.
GT14: the nearest rescue team may not have the earliest verified arrival or meet the response deadline.
GT15: a structurally passable map corridor may still be occupied by a live obstacle.
GT16: an initially verified plan does not justify stopping monitoring after new telemetry arrives; a delay reduces predicted separation from 120 to 80 seconds, so valid findings are preserved while reevaluation remains armed.
GT17: ten reports of one incident should create one dispatch task while preserving all ten evidence sources.
GT18: the geometrically shortest route may be unsafe when it crosses a hazard beyond the rescue robot's operating capability.
GT19: reaching the target overhead does not authorize payload release while the live ground-clearance condition remains false.
GT20: a green signal does not authorize intersection entry while the downstream exit cannot store and clear the full vehicle.
GT21: when telemetry says a 60-second delay and an operations review says 55 seconds, the AI must not overwrite by arrival order, average the values, or invent source authority; it must expose the conflict and apply a caller-declared rule.
GT22: when position and battery data come from different systems, the AI must not assemble a “current state” from the latest fields alone; it must first bind object identity, time, and field ownership into one traceable operational snapshot;
GT23: when position and battery change over five minutes, the system must not overwrite the earlier values; it must retain both snapshots, bind the 300-second interval, and explicitly record position, battery, and object-validity changes;
GT24: when a temporary no-fly zone is published, the system must neither recompute every operation nor update only the map; it must follow an explicit dependency chain and recheck only the intersecting route, its mission, approval conclusion, and launch action;
GT25: when the UAV position moves from corridor chainage 100 to 130 metres, the system recomputes only the crane and tower distances that depend on position while preserving fixed-facility spacing and battery state;
GT26: when a flight-service station schedule changes from 08:00–22:00 to 09:00–18:00, the system replaces only the schedule, preserves location, radio frequency, service types, and contact channel, and blocks the 20:30 mission until recheck;
GT27: when east-zone wind rises from 6 to 12 m/s, the system reevaluates only Missions A and D in the matching region and active time window; Mission A becomes unsuitable, Mission D remains suitable after recheck, and Missions B and C are reused;
GT28: route, altitude, weather-window, and wind checks all pass, but airspace, operator, departure-site, weather-release, and mission authorizations remain absent; the precheck is reusable while automatic takeoff authorization and the takeoff command stay blocked.
GT29: a mock weather service reports 8 m/s while an onsite sensor reports 13 m/s against a 12 m/s mission limit; both responses are fresh and independently grouped, but the result remains unknown and a third independent source is requested;
GT30: a third independent source also reports 13 m/s, creating a two-to-one split; because no majority policy is declared, Assurance remains unknown, the 8 m/s minority source is preserved, and explicit weather adjudication is requested;
GT31: a fictional human review binds the three conflicting responses and scoped context evidence, preserves all raw results, and treats the two 13 m/s readings as local-test-flow observations; the 8 m/s weather conclusion becomes eligible while automatic takeoff authorization and the takeoff command remain blocked;
GT32: five fictional authorization records arrive one by one, reducing unknown authorization fields from five to zero. The final control evaluation makes automatic takeoff authorization and the takeoff command eligible, while Core still does not publish output, send a command, authorize reality, or execute flight.
GT33: three timezone-aware position observations bind to one moving object as a strictly ordered discrete trajectory. Core deterministically returns a 300-second duration without interpolation, prediction, map matching, publication, or action execution.
GT34: three explicit observations bind into two adjacent trajectory segments. Core returns 120/180-second durations, 60/90 document-horizontal-unit distances, and 0.5 horizontal-unit-per-second averages without treating average speed as instantaneous state, interpolating, predicting, or executing action.
GT35: with a caller-declared 5-unit stationary radius, 120-second minimum duration, 300-second maximum observation interval, and explicit gap permission, three adjacent segments become stationary_candidate, moving_observed, and observation_gap. When gap marking is disallowed, the same excessive interval becomes unverifiable; Core does not infer lost link, anomaly, or continuous stationary motion.
GT36: segment midpoints represent adjacent segment-average speeds under a caller-declared 300-second maximum interval. The first two transitions produce scalar acceleration estimates of 0 and 1/300 horizontal units per second squared; the third becomes unverifiable with null speed change and acceleration because the next segment lasts 600 seconds. Core does not infer instantaneous or vector acceleration, direction change, future position, or action.
GT37: two trajectory fragments bound to different provisional identities have boundary samples 60 seconds and 5 meters apart and share the same object class. Under caller-declared 120-second, 10-unit, and class-equality limits, Core returns same_object_candidate while preserving both identities and subject references. It does not verify real-world identity, merge objects, publish, or execute an identity update.
GT38–GT42 composite case: fictional inspection drone UAV-017 enters a building-shadow region and is briefly lost. Observation resumes 60 seconds later and five meters away, but the tracker creates a new trajectory and provisional subject. A fictional asset registry reports the same Remote ID and device serial number, while a fictional human review confirms mission, model, operator, and temporal continuity. GT38 adjudicates the identity evidence; GT39 selects the original subject and retains the resumed subject as an alias; GT40 records proposal approval; GT41 narrows the requested mutation to track_beta /subject_ref, from provisional_beta to provisional_alpha; and GT42 records application approval. All five stages keep the actual references, object graph, and World State unchanged. See the composite-case cookbook.

See the GT01–GT20 Cookbook, the GT21–GT28 World-State Cycle Cookbook, the Verification Provider Profile for GT29–GT32, the Trajectory and Moving Object Profile for GT33–GT42, the Trajectory Identity Adjudication v0.1 for GT38, the Identity Merge Proposal v0.1 for GT39, the Identity Merge Approval Record v0.1 for GT40, the Object Graph Change Request v0.1 for GT41, and the Object Graph Change Application Approval Record v0.1 for GT42.

Implemented public Core

Canonical object types

point, polyline, multi_polyline, polygon, rect, time_interval, altitude_interval, feature_collection, moving_object, and trajectory.

A moving_object declares stable identity without embedding position. A trajectory must reference one moving_object, contain at least two strictly increasing timezone-aware 2D observation samples, and declare interpolation: none. feature_collection remains represented in the Canonical IR; individual operators accept only combinations declared by the operator registry.

Deterministic operators

Operator	Inputs	Output
`distance_2d`	point, point	number
`line_intersects_rect`	polyline, rect	boolean
`multi_polyline_intersects_rect`	multi-polyline, rect	boolean
`point_in_polygon`	point, polygon	boolean
`polygon_contains_point`	polygon, point	boolean
`point_to_line_distance_2d`	point, polyline	number
`rect_contains_point`	rect, point	boolean
`time_overlap`	time interval, time interval	boolean
`altitude_overlap`	altitude interval, altitude interval	boolean
`trajectory_duration_seconds`	discrete trajectory	seconds
`trajectory_segment_metrics`	discrete trajectory	ordered segment list with duration, horizontal distance, and average speed
`trajectory_segment_classifications`	discrete trajectory + explicit thresholds	ordered `stationary_candidate`, `moving_observed`, `observation_gap`, or `unverifiable` records
`trajectory_segment_acceleration_estimates`	discrete trajectory + explicit midpoint/gap parameters	adjacent segment-average speed-change rates; gap transitions are `unverifiable` with null values
`trajectory_identity_candidate`	two discrete trajectories + explicit time/distance/class policy	`same_object_candidate`, `different_object_candidate`, or `unverifiable` without identity merge or reference mutation

Cross-task space contract

All tasks in one document share one CRS, coordinate order, horizontal/vertical unit, and boundary contract. Planar operators accept only local_cartesian or an identified projected CRS and require [x, y]; Core does not treat longitude/latitude as Euclidean coordinates or convert units. Distance assertions and altitude objects must match the document units. Current boundary-sensitive operators support closed only and fail closed when open is declared. Pure temporal tasks are not blocked by the planar CRS gate.

Provenance, evidence, and audit

Documents may optionally declare provenance.sources, evidence_bindings, and audit. Core strictly validates source identity, kind, URI/Artifact identity, SHA-256, timezone-aware timestamps, assertion bindings, and audit references. Valid bindings are copied to the corresponding CheckResult.evidence_refs. Core does not fetch sources, recompute external digests, or raise assurance merely because provenance metadata exists.

geotask inspect schemas --format json also returns portable ide_file_patterns for every public Artifact, suitable for VS Code YAML, JetBrains, and other IDEs that associate files with JSON Schemas.

Public conformance and performance benchmark

geotask benchmark core --enforce-performance --output core-benchmark.json

The offline benchmark uses ten fixed fictional cases to cover all fourteen public deterministic operators, result round trips, semantic replay digests, and provenance evidence bindings. It measures the full JSON decode → canonicalize → validate → execute → serialize path. The default 100 ms p95 threshold is only a broad local regression guardrail, not a cross-hardware ranking, production SLA, or model-quality benchmark. The retained report is registered as geotask.core-benchmark-report and can be strictly validated again.

Execution chain

parse YAML → canonicalize → validate → execute → GeotaskResult

The public Core includes YAML parsing, Canonical IR, structured diagnostics, deterministic execution, result assembly, assurance metadata, model-output normalization, local verification, Agent tool-contract discovery, mechanical preparation of generated drafts, structured revision requests, guarded revision-diff retries, offline validation of four registered Agent report Artifacts, deterministic GT08 evidence recovery, CLI commands, JSON Schema, examples, and conformance tests.

Workflow semantics in the weekly cases

The cases also demonstrate unverifiable, conflicted, blocked, evidence_request, blocked_outputs, resume_when, and next_action. These remain control and workflow semantics under extensions, not base ClaimStatus enum values. The public Core strictly validates and read-only evaluates them through geotask.control/1.0, and can recover one single-named condition by rerunning the affected deterministic assertion. The recovery trace is available as the offline-verifiable geotask.agent-evidence-recovery Artifact. Real evidence retrieval, approval, and action execution remain outside Core in a Runtime or Domain Pack.

Not included in the public Core

Hosted model execution or API keys
Production orchestration and model routing
Industry Domain Packs and customer rules
Private data connectors and approval thresholds
Automatic device control
Patent-sensitive optimization and commercial governance

See Target Specification Status and Security.

CLI

geotask validate <file.yaml>
geotask run <file.yaml>
geotask normalize <model-output.txt>
geotask eval <file.yaml> <model-output.txt>
geotask inspect operators
geotask agent inspect --format json
geotask agent prepare <generated.yaml> --repaired-output <prepared.yaml>
geotask agent retry <blocked-report.json> <revised.yaml> --verification-output <verification.json> --prepared-output <prepared.yaml>
geotask agent recover <task.yaml> --evidence <verified-state.yaml> --output <recovery-report.json>
geotask artifact validate geotask.agent-evidence-recovery <recovery-report.json> --format json
geotask runtime inspect examples/core/runtime_reference_descriptor.json --format json
geotask runtime check examples/core/runtime_reference_descriptor.json examples/core/runtime_validate_artifact_request.json --format json
geotask runtime mock examples/core/runtime_validate_artifact_request.json --output runtime-response.json
geotask provider inspect --profile --format json
geotask provider check examples/core/verification_provider_descriptor_authoritative_weather_gt29.json examples/core/verification_request_weather_conflict_gt29.json --format json
geotask provider validate examples/core/verification_response_authoritative_weather_gt29.json --request examples/core/verification_request_weather_conflict_gt29.json --descriptor examples/core/verification_provider_descriptor_authoritative_weather_gt29.json --format json
geotask verify examples/core/verification_session_uav_recheck.json --state examples/core/world_state_uav_separation_recheck.json --observation examples/core/observation_uav_b_delay_recheck.json --bind task-gt16=examples/core/uav_route_crossing_temporal_separation.yaml --bind result-gt16-initial=examples/core/verification_session_uav_execution_result.json --bind transition-uav-recheck=examples/core/state_transition_uav_separation_recheck.json --format json
geotask recheck examples/core/incremental_reevaluation_result_uav_recheck.json --bind base-world-state=examples/core/world_state_uav_separation_recheck.json --bind successor-world-state=examples/core/world_state_uav_separation_successor.json --bind impact-graph-uav-recheck=examples/core/impact_graph_uav_recheck.json --bind correction-uav-recheck=examples/core/correction_request_uav_recheck.json --bind discrepancy-uav-recheck=examples/core/discrepancy_report_uav_recheck.json --bind result-gt16-reevaluation=examples/core/incremental_reevaluation_uav_execution_result.json --format json

The public repository also includes examples/adapters/http_json_runtime_adapter.py, showing how an offline-inspected Descriptor can be bound to an independently hosted HTTP Runtime outside geotask_core. The paired examples/endpoints/reference_runtime_http_server.py starts a real loopback HTTP Endpoint and completes the Adapter-to-Endpoint path. Neither example fetches the Descriptor online, manages credentials, retries, calls a model, or executes production actions; transport errors remain separate from Runtime states, and the returned Response still passes Core's Descriptor / Request / Response three-way contract validation.

examples/model_adapters/provider_neutral/ adds an independently buildable provider-neutral model Adapter package skeleton. It defines non-secret configuration, a structural Provider Protocol, a Mock Provider, and execute-nonlocal mapping, validates registered input and output Artifacts, and rejects model output that pretends to be verified, local_deterministic, or deterministic.

examples/model_adapters/openai_responses/ builds the first real provider integration on that boundary. Private startup code injects an authenticated official OpenAI SDK client; the public package performs one no-retry, no-storage, tool-free Responses API call with strict Structured Outputs and then sends the nested result through Artifact and truthfulness validation. Repository tests use only a fake SDK-shaped client, read no key, and make no live request.

Version map

Artifact	Current version	Meaning
GeoTask Core package	`0.4.0`	Python implementation version
GeoTask document schema	`1.0`	YAML/JSON document format
Language specification	`1.0`	Implemented public normative profile
Agent Integration Profile	`0.1`	Model-neutral tool contract, evidence recovery, and recovery-report Artifact
Runtime Interface Profile	`0.1`	Descriptor, Request, and Response contracts between Core and an external Runtime
Verification Provider Profile	`0.1`	Provider Descriptor, Verification Request, Verification Response, and Assurance Profile contracts
White paper	`0.1`	Public conceptual draft

Documentation

Contributing

Read CONTRIBUTING.md or 中文贡献指南. Bug reports, operator proposals, documentation improvements, and new application-case ideas are welcome.

Use an editable source install only when contributing to development:

git clone https://github.com/stpku/GeoTask.git
cd GeoTask
python -m pip install -e ".[dev]"
pytest

License and boundary

GeoTask Core is released under the MIT License. Public code, specifications, and examples are separate from private Runtime, Domain Packs, customer data, and patent-sensitive implementation details.

Metadata

Release files for geotask-core 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for geotask-core 0.4.0
File	Size	Uploaded
geotask_core-0.4.0.tar.gz	381.0 kB	Aug 8, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for geotask-core 0.4.0
File	Interpreter	ABI	Platform	Reset
geotask_core-0.4.0-py3-none-any.whl 409.1 kB Aug 8, 2026	Python 3	none	any	Details

Total release size: 790.0 kB

Release files / geotask_core-0.4.0.tar.gz

Download URL	geotask_core-0.4.0.tar.gz
Size	381.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`e3a5fe77ce2a3406445734d123831a6e04747426e8b78f02fa4edf989fce790f`
BLAKE2b-256 checksum How to use checksums	`7b7c891229fe783d9088ff024915ed307fc4912073fac109e3e285b5c4339951`
Upload date	Aug 8, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/stpku/GeoTask
Publishing commit: github.com/stpku/GeoTask/tree/06694b89d552f5290d354ce59805dde06b31f908

Workflow

Publishing configuration: github.com/stpku/GeoTask/blob/06694b89d552f5290d354ce59805dde06b31f908/.github/workflows/publish-pypi.yml
Publishing logs: github.com/stpku/GeoTask/actions/runs/31265044071/attempts/1

Artifact

Subject: geotask_core-0.4.0.tar.gz
SHA-256 checksum: e3a5fe77ce2a3406445734d123831a6e04747426e8b78f02fa4edf989fce790f Verifying attestations

Release files / geotask_core-0.4.0-py3-none-any.whl

Download URL	geotask_core-0.4.0-py3-none-any.whl
Size	409.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`84c77d4c654724decae69af4e4f591b98998bc6c67be5ec5f23e5eb56945fe94`
BLAKE2b-256 checksum How to use checksums	`97fdcd3ed98390f39b779576bc19ed1142c57ab8f441149c2094b717e34785dc`
Upload date	Aug 8, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/stpku/GeoTask
Publishing commit: github.com/stpku/GeoTask/tree/06694b89d552f5290d354ce59805dde06b31f908

Workflow

Publishing configuration: github.com/stpku/GeoTask/blob/06694b89d552f5290d354ce59805dde06b31f908/.github/workflows/publish-pypi.yml
Publishing logs: github.com/stpku/GeoTask/actions/runs/31265044071/attempts/1

Artifact

Subject: geotask_core-0.4.0-py3-none-any.whl
SHA-256 checksum: 84c77d4c654724decae69af4e4f591b98998bc6c67be5ec5f23e5eb56945fe94 Verifying attestations