anyformat 2.0.0__tar.gz → 2.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (24) hide show
  1. {anyformat-2.0.0 → anyformat-2.2.0}/PKG-INFO +3 -1
  2. {anyformat-2.0.0 → anyformat-2.2.0}/README.md +2 -0
  3. {anyformat-2.0.0 → anyformat-2.2.0}/pyproject.toml +1 -1
  4. {anyformat-2.0.0 → anyformat-2.2.0}/src/anyformat/sdk/__init__.py +14 -0
  5. {anyformat-2.0.0 → anyformat-2.2.0}/src/anyformat/sdk/_http.py +156 -0
  6. {anyformat-2.0.0 → anyformat-2.2.0}/src/anyformat/sdk/client.py +142 -0
  7. {anyformat-2.0.0 → anyformat-2.2.0}/src/anyformat/workflow/nodes.py +3 -3
  8. {anyformat-2.0.0 → anyformat-2.2.0}/src/anyformat/workflow/results.py +110 -14
  9. {anyformat-2.0.0 → anyformat-2.2.0}/src/anyformat/workflow/topology.py +13 -14
  10. {anyformat-2.0.0 → anyformat-2.2.0}/src/anyformat/sdk/_banner.py +0 -0
  11. {anyformat-2.0.0 → anyformat-2.2.0}/src/anyformat/sdk/_source.py +0 -0
  12. {anyformat-2.0.0 → anyformat-2.2.0}/src/anyformat/sdk/_viz.py +0 -0
  13. {anyformat-2.0.0 → anyformat-2.2.0}/src/anyformat/sdk/builder.py +0 -0
  14. {anyformat-2.0.0 → anyformat-2.2.0}/src/anyformat/sdk/cli.py +0 -0
  15. {anyformat-2.0.0 → anyformat-2.2.0}/src/anyformat/sdk/errors.py +0 -0
  16. {anyformat-2.0.0 → anyformat-2.2.0}/src/anyformat/sdk/handles.py +0 -0
  17. {anyformat-2.0.0 → anyformat-2.2.0}/src/anyformat/sdk/result.py +0 -0
  18. {anyformat-2.0.0 → anyformat-2.2.0}/src/anyformat/sdk/views.py +0 -0
  19. {anyformat-2.0.0 → anyformat-2.2.0}/src/anyformat/workflow/__init__.py +0 -0
  20. {anyformat-2.0.0 → anyformat-2.2.0}/src/anyformat/workflow/builder.py +0 -0
  21. {anyformat-2.0.0 → anyformat-2.2.0}/src/anyformat/workflow/checks.py +0 -0
  22. {anyformat-2.0.0 → anyformat-2.2.0}/src/anyformat/workflow/definition.py +0 -0
  23. {anyformat-2.0.0 → anyformat-2.2.0}/src/anyformat/workflow/fields.py +0 -0
  24. {anyformat-2.0.0 → anyformat-2.2.0}/src/anyformat/workflow/schema.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: anyformat
3
- Version: 2.0.0
3
+ Version: 2.2.0
4
4
  Summary: Python SDK for the AnyFormat API
5
5
  Project-URL: Homepage, https://anyformat.ai
6
6
  Project-URL: Documentation, https://docs.anyformat.ai
@@ -538,6 +538,8 @@ afx parse invoice.pdf
538
538
  | `client.edit_field(extraction_id, *, value, sanitized_name= \| persistent_id=, column=, row_index=)` | `None` | corrects one field or table cell; `value=None` empties it |
539
539
  | `client.add_row(extraction_id, index, *, sanitized_name= \| persistent_id=)` / `delete_row(...)` | `None` | not idempotent: a retry adds or deletes another row |
540
540
  | `client.verify_extraction(extraction_id)` | `None` | marks every field verified; edited values stay |
541
+ | `client.create_webhook(url, events)` | `CreatedWebhook` | `.secret` is returned here only; admin or owner key |
542
+ | `client.list_webhooks()` / `ping_webhook(id)` / `delete_webhook(id)` | `list[Webhook]` / `WebhookPing` / `str` | listed webhooks carry no secret; a ping is sent once, unretried |
541
543
  | `run.wait(timeout=300, poll_interval=3)` | `Result` | polls run status; retries transient 429/5xx; `ExtractionFailed`/`ExtractionCancelled` on terminal failure |
542
544
  | `client.get_run(run_id)` | `RunDetail` | `.status`, `.result` inline when processed |
543
545
  | `client.list_runs(workflow_id, limit, cursor)` | `Page[RunSummary]` | newest first |
@@ -520,6 +520,8 @@ afx parse invoice.pdf
520
520
  | `client.edit_field(extraction_id, *, value, sanitized_name= \| persistent_id=, column=, row_index=)` | `None` | corrects one field or table cell; `value=None` empties it |
521
521
  | `client.add_row(extraction_id, index, *, sanitized_name= \| persistent_id=)` / `delete_row(...)` | `None` | not idempotent: a retry adds or deletes another row |
522
522
  | `client.verify_extraction(extraction_id)` | `None` | marks every field verified; edited values stay |
523
+ | `client.create_webhook(url, events)` | `CreatedWebhook` | `.secret` is returned here only; admin or owner key |
524
+ | `client.list_webhooks()` / `ping_webhook(id)` / `delete_webhook(id)` | `list[Webhook]` / `WebhookPing` / `str` | listed webhooks carry no secret; a ping is sent once, unretried |
523
525
  | `run.wait(timeout=300, poll_interval=3)` | `Result` | polls run status; retries transient 429/5xx; `ExtractionFailed`/`ExtractionCancelled` on terminal failure |
524
526
  | `client.get_run(run_id)` | `RunDetail` | `.status`, `.result` inline when processed |
525
527
  | `client.list_runs(workflow_id, limit, cursor)` | `Page[RunSummary]` | newest first |
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "anyformat"
3
- version = "2.0.0"
3
+ version = "2.2.0"
4
4
  description = "Python SDK for the AnyFormat API"
5
5
  readme = "README.md"
6
6
  authors = [
@@ -3,8 +3,12 @@ from importlib.metadata import PackageNotFoundError, version
3
3
  from anyformat.sdk._http import (
4
4
  Accuracy,
5
5
  AccuracyCoverage,
6
+ CreatedWebhook,
6
7
  DatasetTag,
7
8
  DatasetTagAccuracy,
9
+ DeletionCertificate,
10
+ DeletionCertificateFile,
11
+ DeletionCertificateSummary,
8
12
  DocumentPacketAccuracy,
9
13
  DocumentPacketDetail,
10
14
  DocumentPacketSummary,
@@ -23,6 +27,9 @@ from anyformat.sdk._http import (
23
27
  Page,
24
28
  RunDetail,
25
29
  RunSummary,
30
+ Webhook,
31
+ WebhookEvent,
32
+ WebhookPing,
26
33
  WorkflowUsage,
27
34
  WorkflowVersionSummary,
28
35
  )
@@ -82,10 +89,14 @@ __all__ = [
82
89
  "BadRequest",
83
90
  "Citation",
84
91
  "Client",
92
+ "CreatedWebhook",
85
93
  "DatasetDocument",
86
94
  "DatasetTag",
87
95
  "DatasetTagAccuracy",
88
96
  "DatasetUpload",
97
+ "DeletionCertificate",
98
+ "DeletionCertificateFile",
99
+ "DeletionCertificateSummary",
89
100
  "DocumentPacketAccuracy",
90
101
  "DocumentPacketDetail",
91
102
  "DocumentPacketSummary",
@@ -124,6 +135,9 @@ __all__ = [
124
135
  "TermsAcceptanceRequired",
125
136
  "Unauthorized",
126
137
  "Upload",
138
+ "Webhook",
139
+ "WebhookEvent",
140
+ "WebhookPing",
127
141
  "Workflow",
128
142
  "WorkflowDefinition",
129
143
  "WorkflowNameConflict",
@@ -7,6 +7,7 @@ The only thing that changes between Client and AsyncClient is the single
7
7
  # TODO: collapse sync/async via synchronicity if duplication grows
8
8
  """
9
9
 
10
+ import base64
10
11
  import json
11
12
  from dataclasses import dataclass, field
12
13
  from datetime import date, datetime, timezone
@@ -334,6 +335,74 @@ class EditReference:
334
335
  return self.status == "ready"
335
336
 
336
337
 
338
+ WebhookEvent = Literal["run.completed", "run.failed", "run.cancelled", "run.validated"]
339
+
340
+
341
+ @dataclass(frozen=True)
342
+ class Webhook:
343
+ """An HTTPS endpoint subscribed to the organization's run events. A listed webhook never
344
+ carries its signing secret."""
345
+
346
+ id: str
347
+ url: str
348
+ events: list[str]
349
+ created_at: str
350
+
351
+
352
+ @dataclass(frozen=True)
353
+ class CreatedWebhook(Webhook):
354
+ """The webhook as created, with the ``whsec_`` signing secret no later read returns."""
355
+
356
+ secret: str
357
+
358
+
359
+ @dataclass(frozen=True)
360
+ class WebhookPing:
361
+ """How the endpoint answered one signed ``webhook.ping``. ``status_code`` is ``None``
362
+ when it did not answer."""
363
+
364
+ delivered: bool
365
+ status_code: int | None
366
+
367
+
368
+ @dataclass(frozen=True)
369
+ class DeletionCertificateFile:
370
+ id: str
371
+ filename: str
372
+ created_at: str
373
+
374
+
375
+ @dataclass(frozen=True)
376
+ class DeletionCertificateSummary:
377
+ """What one document packet's deletion destroyed. ``assurance`` is set once ``status`` is ``final``."""
378
+
379
+ id: str
380
+ workflow_id: str
381
+ document_packet_id: str
382
+ deletion_kind: str
383
+ status: str
384
+ assurance: str | None
385
+ files: list[DeletionCertificateFile]
386
+ requested_at: str
387
+ forgotten_at: str
388
+ issued_at: str
389
+ finalized_at: str | None
390
+ signed_at: str | None
391
+
392
+
393
+ @dataclass(frozen=True)
394
+ class DeletionCertificate(DeletionCertificateSummary):
395
+ """A certificate with its signed XML ``document`` and detached ``signature``, both ``None`` until signed.
396
+
397
+ Verify with ``openssl dgst -sha256 -verify <public key> -signature <signature> <document>``.
398
+ """
399
+
400
+ document: bytes | None
401
+ signature: bytes | None
402
+ document_sha256: str | None
403
+ signing_key_id: str | None
404
+
405
+
337
406
  def _auth_headers(api_key: str, idempotency_key: str | None = None) -> dict[str, str]:
338
407
  headers = {"Authorization": f"Bearer {api_key}"}
339
408
  if idempotency_key is not None:
@@ -837,6 +906,38 @@ def build_delete_edit_reference_request(
837
906
  return httpx.Request("DELETE", url, headers=_auth_headers(api_key))
838
907
 
839
908
 
909
+ def build_create_webhook_request(base_url: str, api_key: str, url: str, events: list[WebhookEvent]) -> httpx.Request:
910
+ endpoint = f"{base_url.rstrip('/')}/v3/webhooks/"
911
+ return httpx.Request("POST", endpoint, json={"url": url, "events": list(events)}, headers=_auth_headers(api_key))
912
+
913
+
914
+ def build_list_webhooks_request(base_url: str, api_key: str) -> httpx.Request:
915
+ url = f"{base_url.rstrip('/')}/v3/webhooks/"
916
+ return httpx.Request("GET", url, headers=_auth_headers(api_key))
917
+
918
+
919
+ def build_delete_webhook_request(base_url: str, api_key: str, webhook_id: str) -> httpx.Request:
920
+ url = f"{base_url.rstrip('/')}/v3/webhooks/{webhook_id}/"
921
+ return httpx.Request("DELETE", url, headers=_auth_headers(api_key))
922
+
923
+
924
+ def build_ping_webhook_request(base_url: str, api_key: str, webhook_id: str) -> httpx.Request:
925
+ url = f"{base_url.rstrip('/')}/v3/webhooks/{webhook_id}/ping/"
926
+ return httpx.Request("POST", url, headers=_auth_headers(api_key))
927
+
928
+
929
+ def build_list_deletion_certificates_request(
930
+ base_url: str, api_key: str, workflow_id: str, limit: int, cursor: str | None
931
+ ) -> httpx.Request:
932
+ url = f"{base_url.rstrip('/')}/v3/workflows/{workflow_id}/deletion-certificates/"
933
+ return httpx.Request("GET", url, params=_keyset_params(limit, cursor), headers=_auth_headers(api_key))
934
+
935
+
936
+ def build_get_deletion_certificate_request(base_url: str, api_key: str, certificate_id: str) -> httpx.Request:
937
+ url = f"{base_url.rstrip('/')}/v3/deletion-certificates/{certificate_id}/"
938
+ return httpx.Request("GET", url, headers=_auth_headers(api_key))
939
+
940
+
840
941
  def build_parse_request(base_url: str, api_key: str, source: SourceDocument) -> httpx.Request:
841
942
  url = f"{base_url.rstrip('/')}/v3/parse/"
842
943
  return httpx.Request(
@@ -1183,6 +1284,61 @@ def parse_edit_references_response(data: dict) -> list[EditReference]:
1183
1284
  ]
1184
1285
 
1185
1286
 
1287
+ def parse_webhook(data: dict) -> Webhook:
1288
+ return Webhook(id=data["id"], url=data["url"], events=list(data["events"]), created_at=data["created_at"])
1289
+
1290
+
1291
+ def parse_created_webhook(data: dict) -> CreatedWebhook:
1292
+ webhook = parse_webhook(data)
1293
+ return CreatedWebhook(**vars(webhook), secret=data["secret"])
1294
+
1295
+
1296
+ def parse_webhooks(data: dict) -> list[Webhook]:
1297
+ return [parse_webhook(row) for row in data["items"]]
1298
+
1299
+
1300
+ def parse_webhook_ping(data: dict) -> WebhookPing:
1301
+ return WebhookPing(delivered=data["delivered"], status_code=data.get("status_code"))
1302
+
1303
+
1304
+ def _certificate_fields(data: dict) -> dict:
1305
+ return {
1306
+ "id": data["id"],
1307
+ "workflow_id": data["workflow_id"],
1308
+ "document_packet_id": data["document_packet_id"],
1309
+ "deletion_kind": data["deletion_kind"],
1310
+ "status": data["status"],
1311
+ "assurance": data.get("assurance"),
1312
+ "files": [
1313
+ DeletionCertificateFile(id=f["id"], filename=f["filename"], created_at=f["created_at"])
1314
+ for f in data.get("files") or []
1315
+ ],
1316
+ "requested_at": data["requested_at"],
1317
+ "forgotten_at": data["forgotten_at"],
1318
+ "issued_at": data["issued_at"],
1319
+ "finalized_at": data.get("finalized_at"),
1320
+ "signed_at": data.get("signed_at"),
1321
+ }
1322
+
1323
+
1324
+ def _decoded(value: str | None) -> bytes | None:
1325
+ return base64.b64decode(value) if value is not None else None
1326
+
1327
+
1328
+ def parse_deletion_certificate_summary(data: dict) -> DeletionCertificateSummary:
1329
+ return DeletionCertificateSummary(**_certificate_fields(data))
1330
+
1331
+
1332
+ def parse_deletion_certificate(data: dict) -> DeletionCertificate:
1333
+ return DeletionCertificate(
1334
+ **_certificate_fields(data),
1335
+ document=_decoded(data.get("document_base64")),
1336
+ signature=_decoded(data.get("signature_base64")),
1337
+ document_sha256=data.get("document_sha256"),
1338
+ signing_key_id=data.get("signing_key_id"),
1339
+ )
1340
+
1341
+
1186
1342
  def parse_run_summary(data: dict) -> RunSummary:
1187
1343
  return RunSummary(
1188
1344
  id=data["id"],
@@ -10,7 +10,10 @@ import httpx
10
10
 
11
11
  from anyformat.sdk._http import (
12
12
  Accuracy,
13
+ CreatedWebhook,
13
14
  DatasetTag,
15
+ DeletionCertificate,
16
+ DeletionCertificateSummary,
14
17
  Delivery,
15
18
  DocumentPacketDetail,
16
19
  DocumentPacketSummary,
@@ -26,16 +29,22 @@ from anyformat.sdk._http import (
26
29
  ParseFormat,
27
30
  RunDetail,
28
31
  RunSummary,
32
+ Webhook,
33
+ WebhookEvent,
34
+ WebhookPing,
29
35
  WorkflowUsage,
30
36
  WorkflowVersionSummary,
31
37
  build_add_row_request,
32
38
  build_ask_request,
33
39
  build_create_request,
40
+ build_create_webhook_request,
34
41
  build_delete_edit_reference_request,
35
42
  build_delete_packet_request,
36
43
  build_delete_request,
37
44
  build_delete_row_request,
45
+ build_delete_webhook_request,
38
46
  build_edit_field_request,
47
+ build_get_deletion_certificate_request,
39
48
  build_get_eval_accuracy_request,
40
49
  build_get_eval_document_packet_fields_request,
41
50
  build_get_eval_request,
@@ -47,14 +56,17 @@ from anyformat.sdk._http import (
47
56
  build_get_workflow_usage_request,
48
57
  build_launch_eval_request,
49
58
  build_list_dataset_tags_request,
59
+ build_list_deletion_certificates_request,
50
60
  build_list_edit_references_request,
51
61
  build_list_evals_request,
52
62
  build_list_optimizations_request,
53
63
  build_list_packets_request,
54
64
  build_list_request,
55
65
  build_list_runs_request,
66
+ build_list_webhooks_request,
56
67
  build_list_workflow_versions_request,
57
68
  build_parse_request,
69
+ build_ping_webhook_request,
58
70
  build_run_packet_request,
59
71
  build_set_ground_truth_request,
60
72
  build_split_pdf_request,
@@ -63,8 +75,11 @@ from anyformat.sdk._http import (
63
75
  build_upload_edit_references_request,
64
76
  build_verify_extraction_request,
65
77
  parse_accuracy,
78
+ parse_created_webhook,
66
79
  parse_dataset_tags,
67
80
  parse_definition_response,
81
+ parse_deletion_certificate,
82
+ parse_deletion_certificate_summary,
68
83
  parse_edit_references_response,
69
84
  parse_eval_detail,
70
85
  parse_eval_document_packet_fields,
@@ -77,6 +92,8 @@ from anyformat.sdk._http import (
77
92
  parse_run_detail,
78
93
  parse_run_summary,
79
94
  parse_run_triggered_response,
95
+ parse_webhook_ping,
96
+ parse_webhooks,
80
97
  parse_workflow_response,
81
98
  parse_workflow_usage,
82
99
  parse_workflow_version_summary,
@@ -703,6 +720,67 @@ class Client:
703
720
  raise_for_status(response)
704
721
  return document_id
705
722
 
723
+ def list_deletion_certificates(
724
+ self, workflow_id: str, limit: int = 20, cursor: str | None = None
725
+ ) -> Page[DeletionCertificateSummary]:
726
+ """A workflow's deletion certificates, one per deleted packet, newest issued first.
727
+
728
+ Zero-data-retention organizations only; any other gets ``Forbidden``. Answers after the workflow is deleted.
729
+ """
730
+ req = build_list_deletion_certificates_request(self._base_url, self._api_key, workflow_id, limit, cursor)
731
+ response = self._send(req)
732
+ raise_for_status(response)
733
+ data = response.json()
734
+ return Page(
735
+ items=[parse_deletion_certificate_summary(item) for item in data.get("items", [])],
736
+ next_cursor=data.get("next_cursor"),
737
+ )
738
+
739
+ def iter_deletion_certificates(self, workflow_id: str, limit: int = 20) -> Iterator[DeletionCertificateSummary]:
740
+ """Every deletion certificate of a workflow, newest issued first, following ``next_cursor`` lazily."""
741
+ cursor: str | None = None
742
+ while True:
743
+ page = self.list_deletion_certificates(workflow_id, limit=limit, cursor=cursor)
744
+ yield from page.items
745
+ if page.next_cursor is None:
746
+ return
747
+ cursor = page.next_cursor
748
+
749
+ def get_deletion_certificate(self, certificate_id: str) -> DeletionCertificate:
750
+ """One deletion certificate with its signed document and signature, as bytes.
751
+
752
+ Zero-data-retention organizations only; any other gets ``Forbidden``.
753
+ """
754
+ req = build_get_deletion_certificate_request(self._base_url, self._api_key, certificate_id)
755
+ response = self._send(req)
756
+ raise_for_status(response)
757
+ return parse_deletion_certificate(response.json())
758
+
759
+ def create_webhook(self, url: str, events: list[WebhookEvent]) -> CreatedWebhook:
760
+ """Subscribe an HTTPS endpoint to the organization's run events.
761
+
762
+ Store the returned ``secret``: no later call returns it, and every delivery's
763
+ ``webhook-signature`` is verified with it (Standard Webhooks).
764
+ """
765
+ response = self._send(build_create_webhook_request(self._base_url, self._api_key, url, events))
766
+ raise_for_status(response)
767
+ return parse_created_webhook(response.json())
768
+
769
+ def list_webhooks(self) -> list[Webhook]:
770
+ response = self._send(build_list_webhooks_request(self._base_url, self._api_key))
771
+ raise_for_status(response)
772
+ return parse_webhooks(response.json())
773
+
774
+ def delete_webhook(self, webhook_id: str) -> str:
775
+ raise_for_status(self._send(build_delete_webhook_request(self._base_url, self._api_key, webhook_id)))
776
+ return webhook_id
777
+
778
+ def ping_webhook(self, webhook_id: str) -> WebhookPing:
779
+ """Send one signed ``webhook.ping`` to the endpoint, without retries, and report how it answered."""
780
+ response = self._send(build_ping_webhook_request(self._base_url, self._api_key, webhook_id))
781
+ raise_for_status(response)
782
+ return parse_webhook_ping(response.json())
783
+
706
784
  def close(self) -> None:
707
785
  self._http.close()
708
786
 
@@ -1301,6 +1379,70 @@ class AsyncClient:
1301
1379
  raise_for_status(response)
1302
1380
  return document_id
1303
1381
 
1382
+ async def list_deletion_certificates(
1383
+ self, workflow_id: str, limit: int = 20, cursor: str | None = None
1384
+ ) -> Page[DeletionCertificateSummary]:
1385
+ """A workflow's deletion certificates, one per deleted packet, newest issued first.
1386
+
1387
+ Zero-data-retention organizations only; any other gets ``Forbidden``. Answers after the workflow is deleted.
1388
+ """
1389
+ req = build_list_deletion_certificates_request(self._base_url, self._api_key, workflow_id, limit, cursor)
1390
+ response = await self._send(req)
1391
+ raise_for_status(response)
1392
+ data = response.json()
1393
+ return Page(
1394
+ items=[parse_deletion_certificate_summary(item) for item in data.get("items", [])],
1395
+ next_cursor=data.get("next_cursor"),
1396
+ )
1397
+
1398
+ async def iter_deletion_certificates(
1399
+ self, workflow_id: str, limit: int = 20
1400
+ ) -> AsyncIterator[DeletionCertificateSummary]:
1401
+ """Every deletion certificate of a workflow, newest issued first, following ``next_cursor`` lazily."""
1402
+ cursor: str | None = None
1403
+ while True:
1404
+ page = await self.list_deletion_certificates(workflow_id, limit=limit, cursor=cursor)
1405
+ for item in page.items:
1406
+ yield item
1407
+ if page.next_cursor is None:
1408
+ return
1409
+ cursor = page.next_cursor
1410
+
1411
+ async def get_deletion_certificate(self, certificate_id: str) -> DeletionCertificate:
1412
+ """One deletion certificate with its signed document and signature, as bytes.
1413
+
1414
+ Zero-data-retention organizations only; any other gets ``Forbidden``.
1415
+ """
1416
+ req = build_get_deletion_certificate_request(self._base_url, self._api_key, certificate_id)
1417
+ response = await self._send(req)
1418
+ raise_for_status(response)
1419
+ return parse_deletion_certificate(response.json())
1420
+
1421
+ async def create_webhook(self, url: str, events: list[WebhookEvent]) -> CreatedWebhook:
1422
+ """Subscribe an HTTPS endpoint to the organization's run events.
1423
+
1424
+ Store the returned ``secret``: no later call returns it, and every delivery's
1425
+ ``webhook-signature`` is verified with it (Standard Webhooks).
1426
+ """
1427
+ response = await self._send(build_create_webhook_request(self._base_url, self._api_key, url, events))
1428
+ raise_for_status(response)
1429
+ return parse_created_webhook(response.json())
1430
+
1431
+ async def list_webhooks(self) -> list[Webhook]:
1432
+ response = await self._send(build_list_webhooks_request(self._base_url, self._api_key))
1433
+ raise_for_status(response)
1434
+ return parse_webhooks(response.json())
1435
+
1436
+ async def delete_webhook(self, webhook_id: str) -> str:
1437
+ raise_for_status(await self._send(build_delete_webhook_request(self._base_url, self._api_key, webhook_id)))
1438
+ return webhook_id
1439
+
1440
+ async def ping_webhook(self, webhook_id: str) -> WebhookPing:
1441
+ """Send one signed ``webhook.ping`` to the endpoint, without retries, and report how it answered."""
1442
+ response = await self._send(build_ping_webhook_request(self._base_url, self._api_key, webhook_id))
1443
+ raise_for_status(response)
1444
+ return parse_webhook_ping(response.json())
1445
+
1304
1446
  async def aclose(self) -> None:
1305
1447
  await self._http.aclose()
1306
1448
 
@@ -184,9 +184,9 @@ class ParseNode(BaseNode):
184
184
 
185
185
  @classmethod
186
186
  def accepts(cls, predecessor: type["BaseNode"]) -> bool:
187
- # A branch Parse re-reads the document on a Classify/If-Else arm; a
188
- # splitter arm is already a sub-document, not a Parse feeder.
189
- return predecessor in (ClassifyNode, IfElseNode)
187
+ # A branch Parse re-reads the document on a Classify/If-Else arm, or only
188
+ # the pages of a splitter partition.
189
+ return predecessor in (ClassifyNode, IfElseNode, SplitterNode)
190
190
 
191
191
  @classmethod
192
192
  def builder_verb(cls) -> str:
@@ -33,6 +33,14 @@ def _drop_unset_file_refs(data: dict[str, Any]) -> dict[str, Any]:
33
33
  return data
34
34
 
35
35
 
36
+ class _OmitsUnsetFileRefs(BaseModel):
37
+ """A model whose ``file_id``, ``file_name`` and ``file_page`` are omitted when unset, never ``null``."""
38
+
39
+ @model_serializer(mode="wrap")
40
+ def _omit_unset_file_refs(self, handler: SerializerFunctionWrapHandler): # noqa: ANN202 — pydantic reads a return annotation as the serialization schema
41
+ return _drop_unset_file_refs(handler(self))
42
+
43
+
36
44
  class Evidence(BaseModel):
37
45
  """A snippet of source text supporting an extracted value, with the page it came from.
38
46
 
@@ -201,7 +209,7 @@ class Detection(BaseModel):
201
209
  text: str = Field(description="The words the page prints inside this box.")
202
210
 
203
211
 
204
- class Block(BaseModel):
212
+ class Block(_OmitsUnsetFileRefs):
205
213
  """One semantic block of a parsed document — a structured alternative to
206
214
  walking `<a id></a>` anchors in `markdown`.
207
215
 
@@ -273,10 +281,6 @@ class Block(BaseModel):
273
281
  ),
274
282
  )
275
283
 
276
- @model_serializer(mode="wrap")
277
- def _omit_unset_file_refs(self, handler: SerializerFunctionWrapHandler): # noqa: ANN202 — pydantic reads a return annotation as the serialization schema
278
- return _drop_unset_file_refs(handler(self))
279
-
280
284
 
281
285
  class ParseResult(BaseModel):
282
286
  """Parsed markdown for a file."""
@@ -344,7 +348,7 @@ class RunParsePageStatus(BaseModel):
344
348
  reason: Optional[str] = Field(description="Why the fallback was taken; `null` when `kind` is `ok`.")
345
349
 
346
350
 
347
- class RunParsePage(BaseModel):
351
+ class RunParsePage(_OmitsUnsetFileRefs):
348
352
  """One page a parse read, as it recorded the page, whether or not the page holds a block.
349
353
 
350
354
  A value is `null` where the parse did not record it: a parse stored before page facts were, or a file without pages.
@@ -368,9 +372,71 @@ class RunParsePage(BaseModel):
368
372
  default=None, description="Where the page's text came from: `embedded`, `ocr`, `mixed` or `none`."
369
373
  )
370
374
 
371
- @model_serializer(mode="wrap")
372
- def _omit_unset_file_refs(self, handler: SerializerFunctionWrapHandler): # noqa: ANN202 — pydantic reads a return annotation as the serialization schema
373
- return _drop_unset_file_refs(handler(self))
375
+
376
+ class RunParseLayerAbsence(BaseModel):
377
+ """Why a parse answers one of its layers without the layer's records."""
378
+
379
+ absent: str = Field(
380
+ description=(
381
+ "The stored reason, such as `build_failed`, or why a read could not serve a stored layer: `too_large` "
382
+ "above the inline limit, `unreadable` when its object cannot be read back. The public API words each as "
383
+ "its own."
384
+ )
385
+ )
386
+
387
+
388
+ class RunParseSequenceConfidence(BaseModel):
389
+ mean: float = Field(description="The mean confidence of the sequence's elements, 0-1, as core measured it.")
390
+ min: float = Field(description="The lowest confidence of the sequence's elements, 0-1, as core measured it.")
391
+
392
+
393
+ class RunParseSequence(_OmitsUnsetFileRefs):
394
+ """A run of elements the parse grouped by horizontal proximity inside one block: often a line, never guaranteed."""
395
+
396
+ id: str = Field(description="`p<page>_s<index>`, numbered by the packet page `page`.")
397
+ block_id: str = Field(description="The `blocks[].id` of the block that holds it.")
398
+ page: int = Field(description="1-indexed page number, counted across the packet's files in packet order.")
399
+ file_id: Optional[str] = Field(default=None, description="The file this page belongs to.")
400
+ file_page: Optional[int] = Field(default=None, description="1-indexed page of that file.")
401
+ text: str = Field(description="The sequence's text, as core read it.")
402
+ bbox: dict[str, float] = Field(
403
+ description="Normalised bounding box in [0, 1] page coordinates with keys `x0`/`y0`/`x1`/`y1`.",
404
+ )
405
+ confidence: Optional[RunParseSequenceConfidence] = Field(
406
+ description="`null` when nothing scored it: a model's reading of handwriting."
407
+ )
408
+ cell_id: Optional[str] = Field(
409
+ default=None,
410
+ description=(
411
+ "The `r<row>c<col>` cell of its block that table grounding gave every one of its elements; `null` when "
412
+ "they were grounded to no cell, or to two."
413
+ ),
414
+ )
415
+
416
+
417
+ class RunParseElement(_OmitsUnsetFileRefs):
418
+ """One piece of text as read: a word, or a whole line when the OCR engine boxed it as one."""
419
+
420
+ id: str = Field(description="`p<page>_e<index>`, numbered by the packet page `page`.")
421
+ block_id: str = Field(description="The `blocks[].id` of the block that owns it.")
422
+ sequence_id: Optional[str] = Field(description="The sequence of its block that holds it; `null` when none does.")
423
+ page: int = Field(description="1-indexed page number, counted across the packet's files in packet order.")
424
+ file_id: Optional[str] = Field(default=None, description="The file this page belongs to.")
425
+ file_page: Optional[int] = Field(default=None, description="1-indexed page of that file.")
426
+ text: str = Field(description="The element's text, as core read it.")
427
+ bbox: dict[str, float] = Field(
428
+ description="Normalised bounding box in [0, 1] page coordinates with keys `x0`/`y0`/`x1`/`y1`.",
429
+ )
430
+ confidence: Optional[float] = Field(description="0-1, as core measured it; `null` when nothing scored it.")
431
+ source: str = Field(description="Where its text came from: `embedded`, `ocr` or `transcribed`.")
432
+
433
+
434
+ class RunParseLayerLink(BaseModel):
435
+ """A stored layer object too large to serve inline, handed out as stored, in its published format."""
436
+
437
+ url: str = Field(description="A presigned GET of the object, valid for 15 minutes; it is served gzip-encoded.")
438
+ version: int = Field(description="The published format version the object is stored in.")
439
+ size_bytes: int = Field(description="The object's size as stored, gzipped.")
374
440
 
375
441
 
376
442
  class RunParseV3(ParseResult):
@@ -402,9 +468,39 @@ class RunParseV3(ParseResult):
402
468
  read_by_extraction: bool = Field(
403
469
  description="Whether an extraction of the run read this parse: the nearest parse upstream of its extract node.",
404
470
  )
471
+ layers: Optional[dict[str, RunParseLayerAbsence]] = Field(
472
+ default=None,
473
+ description=(
474
+ "Each layer the parse stored without its object, by name, with the reason, and each layer asked for that "
475
+ "the read could not serve; any other stored layer is not listed. `null` when the run stored no listing of this node's packet parse, as for a parse stored before "
476
+ "listings were."
477
+ ),
478
+ )
479
+ sequences: Optional[list[RunParseSequence]] = Field(
480
+ default=None,
481
+ description="Each sequence, in packet page and reading order, when asked for and served; else `null`.",
482
+ )
483
+ elements: Optional[list[RunParseElement]] = Field(
484
+ default=None,
485
+ description="Each element, in packet page and reading order, when asked for and served; else `null`.",
486
+ )
487
+ sequences_link: Optional[RunParseLayerLink] = Field(
488
+ default=None,
489
+ description=(
490
+ "When asked for and too large to serve inline, the link to the stored sequences object, holding every "
491
+ "page; `sequences` is then `null`. Else `null`."
492
+ ),
493
+ )
494
+ elements_link: Optional[RunParseLayerLink] = Field(
495
+ default=None,
496
+ description=(
497
+ "When asked for and too large to serve inline, the link to the stored elements object, holding every "
498
+ "page; `elements` is then `null`. Else `null`."
499
+ ),
500
+ )
405
501
 
406
502
 
407
- class ParsePage(BaseModel):
503
+ class ParsePage(_OmitsUnsetFileRefs):
408
504
  """One page of a parse as its blocks, in reading order."""
409
505
 
410
506
  page: int = Field(description="1-indexed page number, counted across the packet's files in packet order.")
@@ -413,10 +509,6 @@ class ParsePage(BaseModel):
413
509
  file_page: Optional[int] = Field(default=None, description="1-indexed page of that file.")
414
510
  blocks: list[Block] = Field(description="The page's blocks in reading order, each with its `content`.")
415
511
 
416
- @model_serializer(mode="wrap")
417
- def _omit_unset_file_refs(self, handler: SerializerFunctionWrapHandler): # noqa: ANN202 — pydantic reads a return annotation as the serialization schema
418
- return _drop_unset_file_refs(handler(self))
419
-
420
512
 
421
513
  class ParseBlocksResultV3(BaseModel):
422
514
  """The parse as pages of blocks, each block with its text, and no markdown: `parse_format=blocks`.
@@ -862,8 +954,12 @@ __all__ = [
862
954
  "ResultsResponse",
863
955
  "ResultsResponseV3",
864
956
  "CodeOutput",
957
+ "RunParseElement",
958
+ "RunParseLayerAbsence",
959
+ "RunParseLayerLink",
865
960
  "RunParsePage",
866
961
  "RunParsePageStatus",
962
+ "RunParseSequence",
867
963
  "RunParseV3",
868
964
  "SplitPartition",
869
965
  "SplitResult",
@@ -27,6 +27,7 @@ from anyformat.workflow.nodes import (
27
27
  ClassifyNode,
28
28
  CodeNode,
29
29
  ExtractNode,
30
+ FilterNode,
30
31
  IfElseNode,
31
32
  KnowledgeNode,
32
33
  ParseNode,
@@ -81,7 +82,7 @@ class ExactlyOneParseNode:
81
82
 
82
83
  class ExactlyOneEntryParseNode:
83
84
  """One entry Parse (no incoming edge); every other Parse fed by a single
84
- edge from a branching node (classify / if_else). Silent below two Parses.
85
+ edge from a branching node (classify / if_else / splitter). Silent below two Parses.
85
86
  """
86
87
 
87
88
  name = "exactly_one_entry_parse_node"
@@ -136,16 +137,14 @@ class ExactlyOneEntryParseNode:
136
137
  )
137
138
  ]
138
139
  source = nodes_by_id.get(sources[0])
139
- # Same feeder set as ``ParseNode.accepts``: a splitter arm is a routed
140
- # sub-document, not a Parse feeder.
141
- if type(source) in (ClassifyNode, IfElseNode):
140
+ if type(source) in (ClassifyNode, IfElseNode, SplitterNode):
142
141
  return []
143
142
  found = source.type if source else "unknown"
144
143
  return [
145
144
  Violation(
146
145
  rule=self.name,
147
146
  message=f"branch `parse` node {parse.id!r} must be fed by a branching "
148
- f"node (classify / if_else), not by {found!r}",
147
+ f"node (classify / if_else / splitter), not by {found!r}",
149
148
  node_ids=[parse.id],
150
149
  )
151
150
  ]
@@ -673,11 +672,11 @@ class NoParseAsBranchTarget:
673
672
  ]
674
673
 
675
674
 
676
- class NoParseUnderSplitter:
677
- """Reject a Parse reachable from a Splitter, however deep. A Parse inside a
678
- partition re-parses every file of the packet once per partition, not the slice."""
675
+ class NoRouterUnderSplitter:
676
+ """Reject a Classify, Splitter or Filter reachable from a Splitter, however deep. A partition is
677
+ re-read by a Parse at most, never classified, split or discarded on its own (ADR platform/0106)."""
679
678
 
680
- name = "no_parse_under_splitter"
679
+ name = "no_router_under_splitter"
681
680
 
682
681
  def check(self, graph: "WorkflowDefinition") -> list[Violation]:
683
682
  successors: dict[str, list[str]] = {}
@@ -693,12 +692,12 @@ class NoParseUnderSplitter:
693
692
  return [
694
693
  Violation(
695
694
  rule=self.name,
696
- message=f"parse node {node.id!r} sits downstream of a splitter; a parse "
697
- "cannot run inside a partition.",
695
+ message=f"{node.type} node {node.id!r} sits downstream of a splitter; a partition "
696
+ "cannot be classified, split or filtered again.",
698
697
  node_ids=[node.id],
699
698
  )
700
699
  for node in graph.nodes
701
- if isinstance(node, ParseNode) and node.id in downstream_of_splitter
700
+ if isinstance(node, (ClassifyNode, SplitterNode, FilterNode)) and node.id in downstream_of_splitter
702
701
  ]
703
702
 
704
703
 
@@ -906,7 +905,7 @@ RULES: list[TopologyRule] = [
906
905
  EveryExtractNodeHasFields(),
907
906
  EveryIfElseHasTrueBranch(),
908
907
  NoParseAsBranchTarget(),
909
- NoParseUnderSplitter(),
908
+ NoRouterUnderSplitter(),
910
909
  NoCodeInstructions(),
911
910
  ValidationRuleIdReferencesExist(),
912
911
  NoCycles(),
@@ -1052,7 +1051,7 @@ __all__ = [
1052
1051
  "NoCycles",
1053
1052
  "NodeAdjacency",
1054
1053
  "NoParseAsBranchTarget",
1055
- "NoParseUnderSplitter",
1054
+ "NoRouterUnderSplitter",
1056
1055
  "NonBranchingNodeHasAtMostOneOutgoing",
1057
1056
  "RULES",
1058
1057
  "SingleUpstreamNodeHasOneIncoming",