Metadata-Version: 2.4
Name: geotask-core
Version: 0.1.0
Summary: GeoTask Core: deterministic verification for verifiable spatiotemporal AI-agent tasks
Author: GeoTask Contributors
License-Expression: MIT
Project-URL: Homepage, https://stpku.github.io/GeoTask/
Project-URL: Documentation, https://stpku.github.io/GeoTask/
Project-URL: Repository, https://github.com/stpku/GeoTask
Project-URL: Issues, https://github.com/stpku/GeoTask/issues
Project-URL: Changelog, https://github.com/stpku/GeoTask/blob/main/CHANGELOG.md
Project-URL: Roadmap, https://github.com/stpku/GeoTask/blob/main/ROADMAP.md
Keywords: ai-agents,spatiotemporal,spatial-reasoning,deterministic-verification,geospatial,robotics,uav,geotask
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: jsonschema>=4.18; extra == "dev"
Requires-Dist: matplotlib>=3.5; extra == "dev"
Dynamic: license-file

# GeoTask

[简体中文](README.md) | **English**

**Verifiable spatiotemporal task protocol for AI agents.**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![CI](https://github.com/stpku/GeoTask/actions/workflows/ci.yml/badge.svg)](https://github.com/stpku/GeoTask/actions/workflows/ci.yml)
[![Pages](https://github.com/stpku/GeoTask/actions/workflows/pages.yml/badge.svg)](https://stpku.github.io/GeoTask/)
[![Release](https://img.shields.io/github/v/release/stpku/GeoTask?include_prereleases&label=release)](https://github.com/stpku/GeoTask/releases)

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–GT13 experience](https://stpku.github.io/GeoTask/)
- [Quickstart](docs/tutorials/quickstart.md)
- [White Paper v0.1](docs/whitepaper/GeoTask_White_Paper_v0.1.md)
- [Implemented Language and Execution Specification v1.0](docs/spec/geotask-language-spec-v1.0.md)
- [GT01–GT13 Cookbook](docs/cookbook/gt01-gt13.md)
- [v0.1.0 Public Preview release notes](docs/release_v0_1_0.md)
- [Public roadmap](ROADMAP.md)
- [Documentation index](docs/README.en.md)

## 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:

```mermaid
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

```bash
git clone https://github.com/stpku/GeoTask.git
cd GeoTask
pip install -e ".[dev]"

geotask validate examples/core/v1_minimal_distance.yaml
geotask run examples/core/v1_minimal_distance.yaml
pytest
```

Minimal task:

```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`.

## 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–GT13 | What executable action follows from a verified constraint? |

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.

See the [Cookbook](docs/cookbook/gt01-gt13.md) 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

```text
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, 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 are application or workflow semantics carried through `extensions`; they must not be confused with every current Core enum.

## 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](docs/spec/target-specification-status.md) and [Open Core Boundary](docs/open_core_commercial_runtime_boundary.md).

## CLI

```bash
geotask validate <file.yaml>
geotask run <file.yaml>
geotask normalize <model-output.txt>
geotask eval <file.yaml> <model-output.txt>
geotask inspect operators
```

## Version map

| Artifact | Current version | Meaning |
|---|---:|---|
| GeoTask Core package | `0.1.0` | Python implementation version |
| GeoTask document schema | `1.0` | YAML/JSON document format |
| Language specification | `1.0` | Implemented public normative profile |
| White paper | `0.1` | Public conceptual draft |

## Documentation

- [English documentation index](docs/README.en.md)
- [中文文档导航](docs/README.md)
- [JSON Schema](schemas/geotask-v1.0.schema.json)
- [Status and Assurance Model](docs/reference/status-model.md)
- [Evidence, Conflict, Blocking, and Recovery](docs/reference/evidence-and-recovery.md)
- [Architecture](docs/architecture.md)
- [Operator extension guide](docs/operator-guide.md)

## Contributing

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

## License and boundary

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