geotask-core 0.3.0

GeoTask Core: deterministic verification for verifiable spatiotemporal AI-agent tasks

GeoTask

简体中文 | English

Verifiable spatiotemporal task protocol for AI agents.

pip install geotask-core

GeoTask turns spatial, temporal, evidential, resource, and action constraints into explicit YAML tasks that both models and programs can read. GeoTask Core then recomputes supported claims with local deterministic operators, so a fluent model response is not mistaken for a verified result.

• Models propose: objects, assertions, explanations, and candidate actions.
• GeoTask Core verifies: structure, references, operator contracts, deterministic results, and assurance metadata.
• Applications decide: whether a result can continue, must be blocked, needs evidence, or requires review.

A model-generated answer is a proposal. It becomes trustworthy only through an explicit verification path.

Start here

• Try the GT01–GT20 experience
• Quickstart
• White Paper v0.1
• Implemented Language and Execution Specification v1.0
• GeoTask Agent Integration Profile v0.1
• GeoTask Core Agent Skill
• GT01–GT20 Cookbook
• v0.3.0 Agent Integration release notes
• v0.2.0 artifact-contract release notes
• Public roadmap
• Documentation index

Why GeoTask

LLMs can misunderstand coordinates, boundaries, interval semantics, object capabilities, and resource margins. Tool calling solves individual function calls, but it does not by itself preserve task intent, object binding, evidence status, blocked outputs, or resume conditions.

GeoTask provides a task-level intermediate representation:

flowchart LR
  A[Natural-language intent] --> B[GeoTask document]
  B --> C[Parse and canonicalize]
  C --> D[Validate]
  D --> E[Deterministic execution]
  E --> F[Structured result and assurance]
  M[Model-generated proposal] --> G[Comparator]
  F --> G
  G --> H[verified / contradicted / review]

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

Public application cases

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?

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: crossing routes and overlapping altitudes do not prove collision when crossing-zone occupancy times are separated.
• 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.

See the Cookbook for all cases and source files.

Implemented public Core

Canonical object types

point, polyline, rect, time_interval, altitude_interval, and feature_collection.

feature_collection is 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
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

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 Open Core Boundary.

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

Version map

Artifact	Current version	Meaning
GeoTask Core package	0.3.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
White paper	0.1	Public conceptual draft

Documentation

• English documentation index
• 中文文档导航
• JSON Schema
• Status and Assurance Model
• Evidence, Conflict, Blocking, and Recovery
• Architecture
• Operator extension guide

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.