annolabel 0.5.0__tar.gz

annolabel-0.5.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.3
+Name: annolabel
+Version: 0.5.0
+Summary: Local image annotation primitives for vision-capable agents
+Requires-Dist: pillow>=12.3.0
+Requires-Dist: pydantic>=2.13.5
+Requires-Python: >=3.11
+Project-URL: Repository, https://github.com/Andesprit/annolabel
+Project-URL: Issues, https://github.com/Andesprit/annolabel/issues
+Description-Content-Type: text/markdown
+
+# AnnoLabel by Andesprit
+
+A local image-labeling CLI for vision-capable agents. The agent inspects your image and chooses scene labels, bounding boxes, and segmentation polygons. AnnoLabel validates and saves annotations, renders review images, and exports **COCO datasets**.
+
+The PyPI distribution, executable, and Python module are all `annolabel`.
+
+## Install
+
+```sh
+uv tool install annolabel
+annolabel --version
+annolabel --help
+```
+
+Or install into an existing Python environment:
+
+```sh
+python -m pip install annolabel
+```
+
+Requires Python 3.11 or later. Runtime dependencies are Pillow and Pydantic. AnnoLabel itself does not call LLMs, download models, or need API keys. Your chosen agent needs an image-viewing tool and shell access, and uses its own model-provider authentication.
+
+Previously published as `andesprit-labelkit`. When upgrading, replace `labelkit` commands and Python imports with `annolabel`; the core facade is now `AnnoLabel` in `annolabel.core.annolabel`. Existing annotation sidecars and task handles remain compatible. Keep active task directories in place.
+
+## Label an image
+
+```sh
+annolabel task /data/photo.jpg --output /data/work/photo-task
+```
+
+Open the returned `view` using your agent's image tool. It has the source image's exact EXIF-oriented pixel dimensions with no padding, grid or resizing. The top-left corner is `(0,0)`; x increases right and y increases down.
+
+Ask the agent to write a complete JSON snapshot such as this, replacing every label and coordinate with its own visual interpretation:
+
+```json
+{
+  "classifications": [{"label": "outdoor"}],
+  "objects": [
+    {
+      "key": "object-1",
+      "label": "example object",
+      "box": [50, 30, 250, 180],
+      "polygon": [[50, 100], [120, 30], [250, 100], [200, 180], [50, 180]],
+      "note": "Describe uncertain identity or boundary placement here."
+    }
+  ]
+}
+```
+
+These are schema examples, not annotations for your image. Both `classifications` and `objects` arrays are required. Coordinates must stay within the original oriented image bounds. Polygons need at least three distinct vertices, no self-intersections, and no repeated closing vertex. The box must contain the polygon; omit `box` to derive it automatically from the polygon.
+
+Submit all annotations together:
+
+```sh
+annolabel submit /data/work/photo-task/task.json --file /data/annotations.json
+```
+
+Open the returned review `view`. Check missing objects, class meaning, clipped contours, excess background, and coordinate shifts. If necessary, submit one corrected complete snapshot using the **new task handle**:
+
+```sh
+annolabel submit /data/work/photo-task/pass1/task.json --file /data/corrected.json
+```
+
+Retain stable object keys and every unchanged object/class. Each submission replaces the whole image snapshot; omitted objects and classes are removed. By default a task allows two successful submissions. Use `--max-passes 1` when creating a task to allow one.
+
+If output is lost, recover the latest handle and view:
+
+```sh
+annolabel task-status /data/work/photo-task/task.json
+```
+
+Invalid submissions preserve the existing annotations. Stale external edits are rejected. Keep a single writer per source image; revision checks are not a multi-process lock.
+
+## Choose the task
+
+- Whole-image classification: `annolabel label IMAGE --label CLASS`.
+- Boxes only: create a task with `--geometry boxes` and submit objects with `box` and no polygon.
+- Segmentation: the default requires a polygon per object, with a derived or explicit bounding box.
+- Restrict object labels: pass `--categories categories.json`, a JSON array such as `["car", "person"]`. Scene labels are independent.
+- Save research instructions: pass `--instructions instructions.txt` when creating a task. Also supply those instructions directly to the agent; the compact response does not repeat them.
+
+## Export for training
+
+```sh
+annolabel export /data/photo.jpg --output /data/dataset
+# Or export every annotated source discovered recursively:
+annolabel export /data/images --output /data/dataset-all
+```
+
+COCO is the default and currently the only built-in training format. Export produces:
+
+```text
+dataset/
+  annotations/instances_default.json
+  images/default/000001.png
+  categories.json
+  classifications.csv
+  provenance.json
+  README.txt
+```
+
+Use `images/default/` as your COCO loader's image root. Each object has one record combining its box and optional polygon. COCO boxes use `[x,y,width,height]`; the CLI accepts `[x1,y1,x2,y2]`. Scene classifications and original IDs/notes are preserved separately. Provenance includes original source paths.
+
+Reuse an ordered category vocabulary through `export --categories categories.json` across splits. AnnoLabel does not invent a train/validation split. Folder export skips images without annotation sidecars.
+
+## Give your agent this workflow
+
+```text
+Use AnnoLabel to annotate IMAGE_PATH. Research task: YOUR_LABELS_AND_BOUNDARY_POLICY.
+Create a task in NEW_OUTPUT_DIRECTORY. Open its returned view and use original
+oriented pixels. Submit all scene labels and objects together. Review the returned
+view once and, if needed, submit one corrected full snapshot with the new task
+handle. Retain unchanged objects. Use your own vision; no detectors, segmentation
+models, crop scripts or implementation inspection. Export COCO and report paths
+and remaining uncertainty. Use task-status if a command response is lost.
+```
+
+Works with Codex, Claude Code, Gemini/Antigravity, or another image-capable agent with shell access. Folder traversal and batching are handled by the calling agent, with one task per image.
+
+## More tools and limitations
+
+Run `annolabel COMMAND --help` for any of: `task`, `submit`, `task-status`, `info`, `label`, `box`, `polygon`, `link`, `remove`, `render`, `mask`, `prepare`, `apply`, `review`, and `export`.
+
+`prepare` / `apply` / `review` support detailed packets and padded crop reviews when more inspection is needed. They use a full revision-aware snapshot instead of the short `submit` contract. Detailed ruler values are original coordinates, not PNG margin positions.
+
+Annotations are stored beside the source as `IMAGE.labels.json`. Output directories must be new. Source images remain unchanged. Task handles contain absolute paths and should stay in place during active work; use COCO exports for portable datasets.
+
+Supports single-frame raster images and simple single-component polygons. No polygon holes, multipart instances, keypoints, video, inference engine, or GUI. Geometry validation does not establish visual accuracy: the agent must review the pixels and report uncertainty.
+
+Public source repository: [Andesprit/annolabel](https://github.com/Andesprit/annolabel).

annolabel-0.5.0/docs/PYPI.md

@@ -0,0 +1,130 @@
+# AnnoLabel by Andesprit
+
+A local image-labeling CLI for vision-capable agents. The agent inspects your image and chooses scene labels, bounding boxes, and segmentation polygons. AnnoLabel validates and saves annotations, renders review images, and exports **COCO datasets**.
+
+The PyPI distribution, executable, and Python module are all `annolabel`.
+
+## Install
+
+```sh
+uv tool install annolabel
+annolabel --version
+annolabel --help
+```
+
+Or install into an existing Python environment:
+
+```sh
+python -m pip install annolabel
+```
+
+Requires Python 3.11 or later. Runtime dependencies are Pillow and Pydantic. AnnoLabel itself does not call LLMs, download models, or need API keys. Your chosen agent needs an image-viewing tool and shell access, and uses its own model-provider authentication.
+
+Previously published as `andesprit-labelkit`. When upgrading, replace `labelkit` commands and Python imports with `annolabel`; the core facade is now `AnnoLabel` in `annolabel.core.annolabel`. Existing annotation sidecars and task handles remain compatible. Keep active task directories in place.
+
+## Label an image
+
+```sh
+annolabel task /data/photo.jpg --output /data/work/photo-task
+```
+
+Open the returned `view` using your agent's image tool. It has the source image's exact EXIF-oriented pixel dimensions with no padding, grid or resizing. The top-left corner is `(0,0)`; x increases right and y increases down.
+
+Ask the agent to write a complete JSON snapshot such as this, replacing every label and coordinate with its own visual interpretation:
+
+```json
+{
+  "classifications": [{"label": "outdoor"}],
+  "objects": [
+    {
+      "key": "object-1",
+      "label": "example object",
+      "box": [50, 30, 250, 180],
+      "polygon": [[50, 100], [120, 30], [250, 100], [200, 180], [50, 180]],
+      "note": "Describe uncertain identity or boundary placement here."
+    }
+  ]
+}
+```
+
+These are schema examples, not annotations for your image. Both `classifications` and `objects` arrays are required. Coordinates must stay within the original oriented image bounds. Polygons need at least three distinct vertices, no self-intersections, and no repeated closing vertex. The box must contain the polygon; omit `box` to derive it automatically from the polygon.
+
+Submit all annotations together:
+
+```sh
+annolabel submit /data/work/photo-task/task.json --file /data/annotations.json
+```
+
+Open the returned review `view`. Check missing objects, class meaning, clipped contours, excess background, and coordinate shifts. If necessary, submit one corrected complete snapshot using the **new task handle**:
+
+```sh
+annolabel submit /data/work/photo-task/pass1/task.json --file /data/corrected.json
+```
+
+Retain stable object keys and every unchanged object/class. Each submission replaces the whole image snapshot; omitted objects and classes are removed. By default a task allows two successful submissions. Use `--max-passes 1` when creating a task to allow one.
+
+If output is lost, recover the latest handle and view:
+
+```sh
+annolabel task-status /data/work/photo-task/task.json
+```
+
+Invalid submissions preserve the existing annotations. Stale external edits are rejected. Keep a single writer per source image; revision checks are not a multi-process lock.
+
+## Choose the task
+
+- Whole-image classification: `annolabel label IMAGE --label CLASS`.
+- Boxes only: create a task with `--geometry boxes` and submit objects with `box` and no polygon.
+- Segmentation: the default requires a polygon per object, with a derived or explicit bounding box.
+- Restrict object labels: pass `--categories categories.json`, a JSON array such as `["car", "person"]`. Scene labels are independent.
+- Save research instructions: pass `--instructions instructions.txt` when creating a task. Also supply those instructions directly to the agent; the compact response does not repeat them.
+
+## Export for training
+
+```sh
+annolabel export /data/photo.jpg --output /data/dataset
+# Or export every annotated source discovered recursively:
+annolabel export /data/images --output /data/dataset-all
+```
+
+COCO is the default and currently the only built-in training format. Export produces:
+
+```text
+dataset/
+  annotations/instances_default.json
+  images/default/000001.png
+  categories.json
+  classifications.csv
+  provenance.json
+  README.txt
+```
+
+Use `images/default/` as your COCO loader's image root. Each object has one record combining its box and optional polygon. COCO boxes use `[x,y,width,height]`; the CLI accepts `[x1,y1,x2,y2]`. Scene classifications and original IDs/notes are preserved separately. Provenance includes original source paths.
+
+Reuse an ordered category vocabulary through `export --categories categories.json` across splits. AnnoLabel does not invent a train/validation split. Folder export skips images without annotation sidecars.
+
+## Give your agent this workflow
+
+```text
+Use AnnoLabel to annotate IMAGE_PATH. Research task: YOUR_LABELS_AND_BOUNDARY_POLICY.
+Create a task in NEW_OUTPUT_DIRECTORY. Open its returned view and use original
+oriented pixels. Submit all scene labels and objects together. Review the returned
+view once and, if needed, submit one corrected full snapshot with the new task
+handle. Retain unchanged objects. Use your own vision; no detectors, segmentation
+models, crop scripts or implementation inspection. Export COCO and report paths
+and remaining uncertainty. Use task-status if a command response is lost.
+```
+
+Works with Codex, Claude Code, Gemini/Antigravity, or another image-capable agent with shell access. Folder traversal and batching are handled by the calling agent, with one task per image.
+
+## More tools and limitations
+
+Run `annolabel COMMAND --help` for any of: `task`, `submit`, `task-status`, `info`, `label`, `box`, `polygon`, `link`, `remove`, `render`, `mask`, `prepare`, `apply`, `review`, and `export`.
+
+`prepare` / `apply` / `review` support detailed packets and padded crop reviews when more inspection is needed. They use a full revision-aware snapshot instead of the short `submit` contract. Detailed ruler values are original coordinates, not PNG margin positions.
+
+Annotations are stored beside the source as `IMAGE.labels.json`. Output directories must be new. Source images remain unchanged. Task handles contain absolute paths and should stay in place during active work; use COCO exports for portable datasets.
+
+Supports single-frame raster images and simple single-component polygons. No polygon holes, multipart instances, keypoints, video, inference engine, or GUI. Geometry validation does not establish visual accuracy: the agent must review the pixels and report uncertainty.
+
+Public source repository: [Andesprit/annolabel](https://github.com/Andesprit/annolabel).

annolabel-0.5.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "annolabel"
+version = "0.5.0"
+description = "Local image annotation primitives for vision-capable agents"
+readme = "docs/PYPI.md"
+requires-python = ">=3.11"
+dependencies = [
+    "pillow>=12.3.0",
+    "pydantic>=2.13.5",
+]
+
+[project.urls]
+Repository = "https://github.com/Andesprit/annolabel"
+Issues = "https://github.com/Andesprit/annolabel/issues"
+
+[project.scripts]
+annolabel = "annolabel.main:main"
+
+[build-system]
+requires = ["uv_build>=0.11.29,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pycocotools>=2.0.11",
+    "pytest>=9.1.1",
+]
+
+[tool.uv.build-backend]
+module-name = "annolabel"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

annolabel-0.5.0/pyproject.toml.orig

@@ -0,0 +1,33 @@
+[project]
+name = "annolabel"
+version = "0.5.0"
+description = "Local image annotation primitives for vision-capable agents"
+readme = "docs/PYPI.md"
+requires-python = ">=3.11"
+dependencies = [
+    "pillow>=12.3.0",
+    "pydantic>=2.13.5",
+]
+
+[project.urls]
+Repository = "https://github.com/Andesprit/annolabel"
+Issues = "https://github.com/Andesprit/annolabel/issues"
+
+[project.scripts]
+annolabel = "annolabel.main:main"
+
+[build-system]
+requires = ["uv_build>=0.11.29,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pycocotools>=2.0.11",
+    "pytest>=9.1.1",
+]
+
+[tool.uv.build-backend]
+module-name = "annolabel"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

annolabel-0.5.0/src/annolabel/core/annolabel.py

@@ -0,0 +1,114 @@
+"""Local annotation operations exposed to the CLI."""
+import os
+import tempfile
+from pathlib import Path
+from uuid import uuid4
+from annolabel.modules.images import polygon_mask, render
+from annolabel.schemas.annotations import Annotation, Document, Point
+from annolabel.services.images.base import ImageServiceBase
+from annolabel.services.images.local import LocalImageService
+
+
+class AnnoLabel:
+    """Open an image and its optional sidecar without modifying either.
+
+    :param image_path: Source image filename.
+    :param image_service: Image reader; defaults to the local Pillow service.
+    """
+    def __init__(self, image_path: str, *, image_service: ImageServiceBase | None = None) -> None:
+        self.image_service = image_service if image_service is not None else LocalImageService()
+        self.path = Path(image_path).expanduser().resolve(strict=True)
+        self.sidecar = self.path.with_name(self.path.name + ".labels.json")
+        self.image, info = self.image_service.load(self.path)
+        if self.sidecar.exists():
+            self.document = Document.model_validate_json(self.sidecar.read_text())
+            if self.document.image != info:
+                raise ValueError("source image differs from its annotation sidecar; restore the original image or move the old sidecar before starting again")
+        else:
+            self.document = Document(image=info)
+
+    def info(self) -> dict:
+        """Return source dimensions, annotation data, and sidecar location."""
+        return {"image_path": str(self.path), "sidecar": str(self.sidecar),
+                **self.document.model_dump(mode="json")}
+
+    def _save(self, annotations: list[Annotation]) -> None:
+        document = Document(image=self.document.image, annotations=annotations)
+        # Same-directory replace prevents partially written annotation documents.
+        fd, temporary = tempfile.mkstemp(prefix=".annolabel-", dir=self.sidecar.parent)
+        try:
+            with os.fdopen(fd, "w") as handle:
+                handle.write(document.model_dump_json(indent=2) + "\n")
+            os.replace(temporary, self.sidecar)
+        finally:
+            Path(temporary).unlink(missing_ok=True)
+        self.document = document
+
+    def annotate(self, kind: str, label: str, points: list[Point],
+                 annotation_id: str | None = None, note: str | None = None,
+                 object_id: str | None = None) -> dict:
+        """Add an annotation, or replace an existing ID when supplied."""
+        existing = self.document.annotations
+        if annotation_id is not None and not any(a.id == annotation_id for a in existing):
+            raise ValueError(f"annotation ID not found: {annotation_id}")
+        previous = next((a for a in existing if a.id == annotation_id), None)
+        if object_id is not None and not any(a.object_id == object_id for a in existing):
+            raise ValueError(f"object ID not found: {object_id}")
+        if previous and object_id is None and kind != "label":
+            object_id = previous.object_id
+        annotation = Annotation(id=annotation_id or uuid4().hex[:8], kind=kind,
+                                label=label, points=points, note=note, object_id=object_id)
+        if annotation_id:
+            updated = [annotation if a.id == annotation_id else
+                       a.model_copy(update={"label": label}) if
+                       annotation.object_id is not None and a.object_id == annotation.object_id else a
+                       for a in existing]
+        else:
+            updated = [*existing, annotation]
+        self._save(updated)
+        return {"sidecar": str(self.sidecar), "annotation": annotation.model_dump(mode="json")}
+
+    def link(self, annotation_ids: list[str]) -> dict:
+        """Join existing shapes into the first selected shape’s object."""
+        if len(set(annotation_ids)) < 2:
+            raise ValueError("link requires at least two different annotation IDs")
+        by_id = {a.id: a for a in self.document.annotations}
+        if any(i not in by_id for i in annotation_ids):
+            raise ValueError("one or more annotation IDs were not found")
+        selected = [by_id[i] for i in annotation_ids]
+        if any(a.kind == "label" for a in selected):
+            raise ValueError("whole-image labels cannot be linked to objects")
+        groups = {a.object_id for a in selected}
+        object_id = selected[0].object_id
+        updated = [a.model_copy(update={"object_id": object_id}) if a.object_id in groups else a
+                   for a in self.document.annotations]
+        self._save(updated)
+        return {"sidecar": str(self.sidecar), "object_id": object_id,
+                "annotation_ids": [a.id for a in updated if a.object_id == object_id]}
+
+    def remove(self, annotation_id: str) -> dict:
+        """Remove exactly one existing annotation by ID."""
+        updated = [a for a in self.document.annotations if a.id != annotation_id]
+        if len(updated) == len(self.document.annotations):
+            raise ValueError(f"annotation ID not found: {annotation_id}")
+        self._save(updated)
+        return {"sidecar": str(self.sidecar), "removed": annotation_id}
+
+    def export_image(self, output: str, *, grid: int = 0,
+                     annotation_id: str | None = None, force: bool = False) -> dict:
+        """Write a preview or polygon mask as PNG, protecting source files."""
+        destination = Path(output).expanduser().absolute()
+        for protected in [self.path, self.sidecar]:
+            if destination.resolve() == protected.resolve() or (
+                destination.exists() and protected.exists() and destination.samefile(protected)
+            ):
+                raise ValueError("output must not overwrite the source image or annotation sidecar")
+        if destination.suffix.lower() != ".png":
+            raise ValueError("output must end with .png")
+        result = (polygon_mask(self.document, annotation_id) if annotation_id
+                  else render(self.image, self.document, grid))
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        with destination.open("wb" if force else "xb") as handle:
+            result.save(handle, format="PNG")
+        return {"output": str(destination), "width": result.width, "height": result.height,
+                "kind": "mask" if annotation_id else "preview"}

annolabel-0.5.0/src/annolabel/core/export.py

@@ -0,0 +1,43 @@
+"""Resolve source files and invoke the default dataset exporter."""
+import json
+from pathlib import Path
+from annolabel.core.annolabel import AnnoLabel
+from annolabel.modules.coco import export_coco
+from annolabel.services.images.base import ImageServiceBase
+from annolabel.services.images.local import LocalImageService
+
+
+def export_dataset(source: str, output: str, categories_file: str | None = None, *,
+                   image_service: ImageServiceBase | None = None) -> dict:
+    """Export one image or recursively discovered annotation sidecars.
+
+    :param source: Image or directory containing sidecars.
+    :param output: New dataset directory.
+    :param categories_file: Optional ordered category vocabulary.
+    :param image_service: Image reader; defaults to the local Pillow service.
+    :returns: COCO export receipt and dataset paths.
+    """
+    service = image_service if image_service is not None else LocalImageService()
+    path = Path(source).expanduser().resolve(strict=True)
+    if path.is_dir():
+        suffix = ".labels.json"
+        sources = [p.with_name(p.name[:-len(suffix)]) for p in sorted(path.rglob("*" + suffix))]
+        if not sources:
+            raise ValueError("no annotation sidecars found in input directory")
+    else:
+        sources = [path]
+    items = []
+    seen = set()
+    for image_path in sources:
+        resolved = image_path.resolve(strict=True)
+        if resolved in seen:
+            continue
+        seen.add(resolved)
+        kit = AnnoLabel(str(resolved), image_service=service)
+        items.append((kit.path, kit.document))
+    categories = None
+    if categories_file:
+        categories = json.loads(Path(categories_file).expanduser().read_text())
+        if not isinstance(categories, list):
+            raise ValueError("categories file must contain a JSON array of label names")
+    return export_coco(items, output, categories, image_service=service)

annolabel-0.5.0/src/annolabel/core/task.py

@@ -0,0 +1,93 @@
+"""Short annotation tasks with immutable checkpoints and compact receipts."""
+import hashlib
+import json
+import shutil
+from pathlib import Path
+from annolabel.core.workflow import Workflow
+from annolabel.modules.batch import batch_document, revision
+from annolabel.schemas.task import Submission, TaskHandle
+from annolabel.schemas.workflow import Batch
+
+
+class TaskError(ValueError):
+    """Actionable task failure without implementation details."""
+    def __init__(self, code: str, message: str, recovery: str) -> None:
+        super().__init__(message)
+        self.code, self.recovery = code, recovery
+
+
+def start_task(image: str, output: str, *, instructions: str | None = None,
+               categories: str | None = None, geometry: str = "both", max_passes: int = 2) -> dict:
+    """Create a coordinate view and immutable initial task handle."""
+    workflow = Workflow(image)
+    output_path = Path(output).expanduser().absolute()
+    handle = TaskHandle(image=str(workflow.path), snapshot=str(output_path/"annotations.json"),
+                        packet=str(output_path/"packet.json"), max_passes=max_passes)
+    workflow.prepare(str(output_path), instructions=instructions, categories=categories,
+                     geometry=geometry, short=True)
+    try:
+        (output_path/"task.json").write_text(handle.model_dump_json(indent=2)+"\n")
+    except Exception:
+        shutil.rmtree(output_path)
+        raise
+    return {"status": "ready", "task": str(output_path/"task.json"), "view": str(output_path/"view.png"),
+            "width": workflow.image.width, "height": workflow.image.height, "passes_left": max_passes}
+
+
+class Task:
+    """Read or submit a task checkpoint; serialize writers for each source image."""
+    def __init__(self, path: str) -> None:
+        self.path = Path(path).expanduser().absolute()
+        self.handle = TaskHandle.model_validate_json(self.path.read_text())
+        self.workflow = Workflow(self.handle.image)
+        self.snapshot = Batch.model_validate_json(Path(self.handle.snapshot).read_text())
+        self.next_dir = self.path.parent/f"pass{self.handle.pass_count+1}"
+
+    def _check_current(self, expected_revision: str) -> None:
+        if (self.snapshot.image_sha256 != self.workflow.document.image.sha256
+                or expected_revision != revision(self.workflow.document)):
+            raise TaskError("TASK_CONFLICT", "Source image or annotations changed since this checkpoint.",
+                            "Stop and reconcile the changed source; do not overwrite it or reconstruct hashes.")
+
+    def status(self) -> dict:
+        """Recover the latest committed receipt without resubmitting geometry."""
+        if self.next_dir.exists():
+            receipt = json.loads((self.next_dir/"receipt.json").read_text())
+            next_task = Task(receipt["result"]["task"])
+            return next_task.status()
+        self._check_current(self.snapshot.base_revision)
+        receipt_path = self.path.parent/"receipt.json"
+        if receipt_path.exists():
+            return json.loads(receipt_path.read_text())["result"]
+        return {"status": "ready", "task": str(self.path), "view": str(self.path.parent/"view.png"),
+                "objects": len(self.snapshot.objects),
+                "passes_left": self.handle.max_passes-self.handle.pass_count}
+
+    def submit(self, payload: str) -> dict:
+        """Validate and save all annotations; an identical retry replays its receipt."""
+        submission = Submission.model_validate_json(payload)
+        digest = hashlib.sha256(submission.model_dump_json().encode()).hexdigest()
+        if self.next_dir.exists():
+            receipt = json.loads((self.next_dir/"receipt.json").read_text())
+            if receipt["submission_sha256"] != digest:
+                raise TaskError("CHECKPOINT_USED", "This checkpoint already saved a different submission.",
+                                f"Run annolabel task-status {self.path} and use the returned task for a correction.")
+            self._check_current(receipt["saved_revision"])
+            return receipt["result"]
+        if self.handle.pass_count >= self.handle.max_passes:
+            raise TaskError("PASS_LIMIT", "This task has used its allowed annotation passes.",
+                            "Stop labeling and report any remaining uncertainty. Export is still available.")
+        self._check_current(self.snapshot.base_revision)
+        batch = Batch(image_sha256=self.snapshot.image_sha256, base_revision=self.snapshot.base_revision,
+                      **submission.model_dump())
+        packet = self.workflow._packet(self.handle.packet)
+        document = batch_document(batch, self.workflow.document, packet)
+        next_handle = TaskHandle(image=self.handle.image, snapshot=str(self.next_dir/"annotations.json"),
+                                 packet=str(self.next_dir/"packet.json"), pass_count=self.handle.pass_count+1,
+                                 max_passes=self.handle.max_passes)
+        result = {"status": "saved", "task": str(self.next_dir/"task.json"), "view": str(self.next_dir/"view.png"),
+                  "objects": len(submission.objects), "passes_left": next_handle.max_passes-next_handle.pass_count}
+        receipt = {"submission_sha256": digest, "saved_revision": revision(document), "result": result}
+        self.workflow.apply(batch.model_dump_json(), output=str(self.next_dir), packet_path=self.handle.packet,
+                            short=True, extra_files={"task.json": next_handle.model_dump(), "receipt.json": receipt})
+        return result

annolabel-0.5.0/src/annolabel/core/workflow.py

@@ -0,0 +1,61 @@
+"""Prepare, atomically apply, and review agent annotation snapshots."""
+import json
+import shutil
+from pathlib import Path
+from uuid import uuid4
+from pydantic import TypeAdapter
+from annolabel.core.annolabel import AnnoLabel
+from annolabel.modules.batch import batch_document, check_packet, revision
+from annolabel.modules.views import write_bundle
+from annolabel.schemas.workflow import Batch, Packet, Region, Rules
+
+
+class Workflow(AnnoLabel):
+    """Agent workflow facade over the existing annotation sidecars."""
+
+    def _packet(self, path: str | None) -> Packet | None:
+        packet = Packet.model_validate_json(Path(path).expanduser().read_text()) if path else None
+        if packet:
+            check_packet(packet, self.document)
+        return packet
+
+    def prepare(self, output: str, *, instructions: str | None = None,
+                categories: str | None = None, geometry: str = "both", short: bool = False) -> dict:
+        """Create original/grid views, current snapshot, schema, and task context."""
+        rules = Rules(geometry=geometry,
+                      **({"instructions": Path(instructions).expanduser().read_text()} if instructions else {}),
+                      categories=json.loads(Path(categories).expanduser().read_text()) if categories else None)
+        return write_bundle(self.image, self.document, output, rules=rules, prepare=True, short=short)
+
+    def review(self, output: str, *, packet_path: str | None = None, regions: str | None = None,
+               per_page: int = 2, padding: float = .25) -> dict:
+        """Create paired original/annotated views for objects or supplied regions."""
+        packet = self._packet(packet_path)
+        selected = TypeAdapter(list[Region]).validate_json(Path(regions).expanduser().read_text()) if regions else None
+        return write_bundle(self.image, self.document, output, rules=packet.rules if packet else Rules(),
+                            regions=selected, per_page=per_page, padding=padding)
+
+    def apply(self, payload: str, *, output: str, packet_path: str | None = None,
+              short: bool = False, extra_files: dict[str, dict] | None = None) -> dict:
+        """Replace a full snapshot and render its review; failures preserve labels."""
+        batch = Batch.model_validate_json(payload)
+        packet = self._packet(packet_path)
+        document = batch_document(batch, self.document, packet)
+        bundle = write_bundle(self.image, document, output, rules=packet.rules if packet else Rules(),
+                              short=short, extra_files=extra_files)
+        try:
+            # Optimistic stale edit detection, not a lock: keep one writer per image.
+            if revision(AnnoLabel(str(self.path), image_service=self.image_service).document) != revision(self.document):
+                raise ValueError("source annotations changed during apply; prepare again")
+            self._save(document.annotations)
+        except Exception:
+            shutil.rmtree(bundle["output"])
+            raise
+        return {**bundle, "sidecar": str(self.sidecar), "operation": "replace_snapshot",
+                "objects": [{"key": a.object_id, "annotation_id": a.id, "kind": a.kind}
+                            for a in self.document.annotations if a.object_id is not None]}
+
+    def default_review_output(self, file: str) -> str:
+        """Place generated reviews beside the batch file, outside its source inputs."""
+        parent = Path(file).expanduser().absolute().parent if file != "-" else Path.cwd()
+        return str(parent / "annolabel-reviews" / f"{self.path.stem}-{uuid4().hex[:8]}")