anyformat 2.2.0__tar.gz → 2.4.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 (25) hide show
  1. {anyformat-2.2.0 → anyformat-2.4.0}/PKG-INFO +1 -1
  2. {anyformat-2.2.0 → anyformat-2.4.0}/pyproject.toml +1 -1
  3. {anyformat-2.2.0 → anyformat-2.4.0}/src/anyformat/sdk/cli.py +1 -1
  4. {anyformat-2.2.0 → anyformat-2.4.0}/src/anyformat/sdk/views.py +5 -5
  5. {anyformat-2.2.0 → anyformat-2.4.0}/src/anyformat/workflow/nodes.py +115 -2
  6. {anyformat-2.2.0 → anyformat-2.4.0}/src/anyformat/workflow/results.py +102 -33
  7. anyformat-2.4.0/src/anyformat/workflow/template_tokens.py +46 -0
  8. {anyformat-2.2.0 → anyformat-2.4.0}/src/anyformat/workflow/topology.py +24 -10
  9. {anyformat-2.2.0 → anyformat-2.4.0}/README.md +0 -0
  10. {anyformat-2.2.0 → anyformat-2.4.0}/src/anyformat/sdk/__init__.py +0 -0
  11. {anyformat-2.2.0 → anyformat-2.4.0}/src/anyformat/sdk/_banner.py +0 -0
  12. {anyformat-2.2.0 → anyformat-2.4.0}/src/anyformat/sdk/_http.py +0 -0
  13. {anyformat-2.2.0 → anyformat-2.4.0}/src/anyformat/sdk/_source.py +0 -0
  14. {anyformat-2.2.0 → anyformat-2.4.0}/src/anyformat/sdk/_viz.py +0 -0
  15. {anyformat-2.2.0 → anyformat-2.4.0}/src/anyformat/sdk/builder.py +0 -0
  16. {anyformat-2.2.0 → anyformat-2.4.0}/src/anyformat/sdk/client.py +0 -0
  17. {anyformat-2.2.0 → anyformat-2.4.0}/src/anyformat/sdk/errors.py +0 -0
  18. {anyformat-2.2.0 → anyformat-2.4.0}/src/anyformat/sdk/handles.py +0 -0
  19. {anyformat-2.2.0 → anyformat-2.4.0}/src/anyformat/sdk/result.py +0 -0
  20. {anyformat-2.2.0 → anyformat-2.4.0}/src/anyformat/workflow/__init__.py +0 -0
  21. {anyformat-2.2.0 → anyformat-2.4.0}/src/anyformat/workflow/builder.py +0 -0
  22. {anyformat-2.2.0 → anyformat-2.4.0}/src/anyformat/workflow/checks.py +0 -0
  23. {anyformat-2.2.0 → anyformat-2.4.0}/src/anyformat/workflow/definition.py +0 -0
  24. {anyformat-2.2.0 → anyformat-2.4.0}/src/anyformat/workflow/fields.py +0 -0
  25. {anyformat-2.2.0 → anyformat-2.4.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.2.0
3
+ Version: 2.4.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
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "anyformat"
3
- version = "2.2.0"
3
+ version = "2.4.0"
4
4
  description = "Python SDK for the AnyFormat API"
5
5
  readme = "README.md"
6
6
  authors = [
@@ -655,7 +655,7 @@ def _print_rich_table(out: Console, scalar_fields: dict, raw_fields: dict) -> No
655
655
  table.add_column("Confidence")
656
656
 
657
657
  for field_name, f in scalar_fields.items():
658
- confidence = f"{f.confidence:.2f}" if f.confidence is not None else "-"
658
+ confidence = str(f.confidence) if f.confidence is not None else "-"
659
659
  table.add_row(field_name, str(f.value), confidence)
660
660
 
661
661
  for name, items in object_items:
@@ -47,14 +47,14 @@ class ParseView:
47
47
  return None if isinstance(self._parse, ParseBlocksResultV3) else self._parse.text
48
48
 
49
49
  @property
50
- def parse_confidence(self) -> float | None:
51
- """Document-level confidence (0-100) in the parsed content. May be
52
- ``None`` for some parse modes — fall back to :attr:`layout_confidence`."""
50
+ def parse_confidence(self) -> int | None:
51
+ """Document-level confidence in the parsed content, a whole number from 0 to 100.
52
+ May be ``None`` for some parse modes — fall back to :attr:`layout_confidence`."""
53
53
  return self._parse.parse_confidence
54
54
 
55
55
  @property
56
- def layout_confidence(self) -> float | None:
57
- """Document-level layout model score (0-1) for the block positions.
56
+ def layout_confidence(self) -> int | None:
57
+ """Document-level confidence in the block positions, a whole number from 0 to 100.
58
58
  ``None`` when not available."""
59
59
  return self._parse.layout_confidence
60
60
 
@@ -13,6 +13,7 @@ from pydantic import (
13
13
  BeforeValidator,
14
14
  ConfigDict,
15
15
  Field,
16
+ StringConstraints,
16
17
  model_validator,
17
18
  )
18
19
 
@@ -81,6 +82,11 @@ class BaseNode(BaseModel):
81
82
  def builder_verb(cls) -> str | None:
82
83
  return None
83
84
 
85
+ @classmethod
86
+ def required_flag(cls) -> str | None:
87
+ """The feature flag a caller must hold to write this node; a stored node still reads without it."""
88
+ return None
89
+
84
90
 
85
91
  ParseMode = Literal["standard", "agentic", "lite", "flash"]
86
92
  # How much reasoning a caller asks a model for. Every stage that turns the knob reads
@@ -503,10 +509,12 @@ class SlackAlertNode(BaseNode):
503
509
 
504
510
  Sits at the end of a branch (typically the ``true`` branch of an
505
511
  ``IfElseNode``) and emits nothing downstream — the topology's terminal
506
- role. The template supports two token grammars:
512
+ role. The template supports three token grammars:
507
513
 
508
514
  - ``${field.<persistent_id>}`` — extraction-field value, resolved via
509
515
  ``field_index`` (backend-injected at message-build time).
516
+ - ``${table.<persistent_id>}`` — a list-of-objects field as a plain-text
517
+ table, every column in schema order.
510
518
  - ``${validation.<rule_id>.<attr>}`` — outcome of an upstream
511
519
  ``ValidateNode`` rule; ``<attr>`` is one of ``status`` / ``detail`` /
512
520
  ``severity``. Rendered against ``state.validation_results`` filtered
@@ -534,7 +542,8 @@ class SlackAlertNode(BaseNode):
534
542
  message_template: str = Field(
535
543
  min_length=1,
536
544
  description=(
537
- "Message body with ``${field.<persistent_id>}`` placeholders and, when "
545
+ "Message body with ``${field.<persistent_id>}`` placeholders, "
546
+ "``${table.<persistent_id>}`` placeholders for a list-of-objects field and, when "
538
547
  "an upstream ``ValidateNode`` is present, ``${validation.<rule_id>.<attr>}`` "
539
548
  "placeholders (``<attr>`` = ``status`` | ``detail`` | ``severity``). "
540
549
  "Missing / renamed fields or unknown rule ids render as ``<missing: <name>>`` "
@@ -563,6 +572,104 @@ class SlackAlertNode(BaseNode):
563
572
  return True
564
573
 
565
574
 
575
+ # Loose on purpose: one address, no display name, no list separators. Deliverability is the gateway's call.
576
+ EmailAddress = Annotated[
577
+ str,
578
+ StringConstraints(strip_whitespace=True, max_length=254, pattern=r"^[^@\s,;<>]+@[^@\s,;<>]+\.[^@\s,;<>]+$"),
579
+ ]
580
+
581
+
582
+ # Caps each of to and cc, so the email a node sends per split has a bounded fan-out.
583
+ MAX_EMAIL_RECIPIENTS = 50
584
+
585
+
586
+ class EmailBody(BaseModel):
587
+ """Where an Email node's body comes from: its own template, or an upstream report."""
588
+
589
+ model_config = ConfigDict(extra="forbid")
590
+
591
+ kind: Literal["template", "report"] = Field(description="The body source.")
592
+ template: OptionalText = Field(
593
+ default=None,
594
+ description="Body with ``${field.*}`` and ``${validation.*}`` tokens. Required when ``kind`` is ``template``.",
595
+ )
596
+ report_node_id: OptionalText = Field(
597
+ default=None, description="The Report generator before the node. Required when ``kind`` is ``report``."
598
+ )
599
+ wrapper: OptionalText = Field(
600
+ default=None, description="Text around the report; ``${report}`` marks where it goes."
601
+ )
602
+ placement: Literal["inline", "attachment", "both"] = Field(
603
+ default="inline", description="Where the report goes: in the body, as an attachment, or both."
604
+ )
605
+
606
+ @model_validator(mode="after")
607
+ def _source_matches_kind(self) -> "EmailBody":
608
+ if self.kind == "report":
609
+ raise ValueError("a report body is not supported; use kind 'template'")
610
+ if self.template is None or not self.template.strip():
611
+ raise ValueError("a template body needs a template")
612
+ if self.report_node_id is not None or self.wrapper is not None:
613
+ raise ValueError("report_node_id and wrapper apply only to a report body")
614
+ return self
615
+
616
+
617
+ class EmailAlertNode(BaseNode):
618
+ """Terminal sink that sends one email per split that reaches it.
619
+
620
+ Recipients come only from this config, never from the extraction. Takes the
621
+ same upstreams as ``SlackAlertNode``, for the same reason: each carries an
622
+ extraction the templates render against.
623
+ """
624
+
625
+ type: Literal["email_alert"]
626
+ to: list[EmailAddress] = Field(min_length=1, max_length=MAX_EMAIL_RECIPIENTS, description="Recipients.")
627
+ cc: list[EmailAddress] = Field(
628
+ default_factory=list, max_length=MAX_EMAIL_RECIPIENTS, description="Copied recipients."
629
+ )
630
+ reply_to: Annotated[EmailAddress | None, BeforeValidator(_empty_str_to_none)] = Field(
631
+ default=None, description="Where replies go."
632
+ )
633
+ subject_template: str = Field(
634
+ min_length=1, description="Subject with ``${field.*}`` tokens, on one line."
635
+ )
636
+ body: EmailBody
637
+ on_missing: Literal["hold", "send"] = Field(
638
+ default="hold",
639
+ description="When a template field is missing: ``hold`` sends nothing and records the field; "
640
+ "``send`` sends with the field marked missing.",
641
+ )
642
+ field_index: dict[str, str] | None = Field(
643
+ default=None,
644
+ description="Executor-injected at run time (persistent_id → field name); never set by callers or persisted.",
645
+ )
646
+
647
+ @model_validator(mode="after")
648
+ def _subject_on_one_line(self) -> "EmailAlertNode":
649
+ if "\n" in self.subject_template or "\r" in self.subject_template:
650
+ raise ValueError("subject_template must not contain line breaks")
651
+ return self
652
+
653
+ @model_validator(mode="after")
654
+ def _each_recipient_once(self) -> "EmailAlertNode":
655
+ recipients = [address.lower() for address in [*self.to, *self.cc]]
656
+ if len(recipients) != len(set(recipients)):
657
+ raise ValueError("an address appears more than once across to and cc")
658
+ return self
659
+
660
+ @classmethod
661
+ def accepts(cls, predecessor: type["BaseNode"]) -> bool:
662
+ return predecessor in (ExtractNode, ValidateNode, IfElseNode)
663
+
664
+ @classmethod
665
+ def resolves_single_upstream(cls) -> bool:
666
+ return True
667
+
668
+ @classmethod
669
+ def required_flag(cls) -> str:
670
+ return "email_alert"
671
+
672
+
566
673
  class KnowledgeNode(BaseNode):
567
674
  """Terminal knowledge sink — its presence opts the workflow into the
568
675
  knowledge base (priced separately, so absent by default).
@@ -720,6 +827,7 @@ AnyNode = Annotated[
720
827
  IfElseNode,
721
828
  FilterNode,
722
829
  SlackAlertNode,
830
+ EmailAlertNode,
723
831
  KnowledgeNode,
724
832
  EditNode,
725
833
  CodeNode,
@@ -741,6 +849,7 @@ NODE_CLASSES_BY_TYPE: dict[str, type[BaseNode]] = {
741
849
  "if_else": IfElseNode,
742
850
  "filter": FilterNode,
743
851
  "slack_alert": SlackAlertNode,
852
+ "email_alert": EmailAlertNode,
744
853
  "knowledge": KnowledgeNode,
745
854
  "edit": EditNode,
746
855
  "code": CodeNode,
@@ -769,6 +878,7 @@ PUBLIC_HIDDEN_NODE_KEYS: dict[str, frozenset[str]] = {
769
878
  "validate": frozenset({"field_index"}),
770
879
  "if_else": frozenset({"field_index"}),
771
880
  "slack_alert": frozenset({"field_index"}),
881
+ "email_alert": frozenset({"field_index"}),
772
882
  "edit": frozenset({"reference_uris"}),
773
883
  }
774
884
 
@@ -801,8 +911,11 @@ __all__ = [
801
911
  "ClassifyCategory",
802
912
  "ClassifyNode",
803
913
  "EditNode",
914
+ "EmailAlertNode",
915
+ "EmailBody",
804
916
  "ExtractNode",
805
917
  "MAX_CODE_BYTES",
918
+ "MAX_EMAIL_RECIPIENTS",
806
919
  "MAX_EXAMPLE_REPORT_BYTES",
807
920
  "PUBLIC_HIDDEN_NODE_KEYS",
808
921
  "strip_public_hidden_keys",
@@ -24,6 +24,9 @@ from pydantic import (
24
24
  # is referenced unparameterised (T resolves to ``Any``).
25
25
  ValueT = TypeVar("ValueT")
26
26
 
27
+ # Every confidence this API serves: a whole number of percent, whatever scale it was computed on.
28
+ Percent = Annotated[int, Field(ge=0, le=100)]
29
+
27
30
 
28
31
  def _drop_unset_file_refs(data: dict[str, Any]) -> dict[str, Any]:
29
32
  """``data`` without ``file_id``, ``file_name`` and ``file_page`` when unset: an absent field is omitted, never ``null``."""
@@ -89,11 +92,23 @@ class Evidence(BaseModel):
89
92
  "block of the packet's parse."
90
93
  ),
91
94
  )
95
+ cell_ids: Optional[list[str]] = Field(
96
+ default=None,
97
+ description=(
98
+ "The table cells of `block_id` the value was read from, each as `<block_id>.r<row>c<col>`: the block's "
99
+ "id and a cell id as its `rows` name it. The one cell the value came from when it is known, otherwise "
100
+ "every cell the snippet cites, which can be its whole row. They are the extraction's citation, not "
101
+ "checked against the block's table, and `bbox` can be the box of another row when the cited row did not "
102
+ "hold the value. Absent when the snippet cites no cell, when `block_id` is absent, and for a run saved "
103
+ "before cell ids were kept that named no single cell."
104
+ ),
105
+ examples=[["p3_b0.r1c2"]],
106
+ )
92
107
 
93
108
  @model_serializer(mode="wrap")
94
109
  def _omit_unset_locators(self, handler: SerializerFunctionWrapHandler): # noqa: ANN202 — pydantic reads a return annotation as the serialization schema
95
110
  data = _drop_unset_file_refs(handler(self))
96
- for key in ("bbox", "block_id"):
111
+ for key in ("bbox", "block_id", "cell_ids"):
97
112
  if data.get(key) is None:
98
113
  data.pop(key, None)
99
114
  return data
@@ -143,9 +158,9 @@ class ExtractedField(BaseModel, Generic[ValueT]):
143
158
  default=None,
144
159
  description="Verification state for this datapoint (e.g. `not_verified`, `verified`). `null` when not yet reviewed.",
145
160
  )
146
- confidence: Optional[float] = Field(
161
+ confidence: Optional[Percent] = Field(
147
162
  default=None,
148
- description="Model confidence in the extracted value, on a 0-100 scale. `null` when the backend did not produce a confidence (e.g. manual entry).",
163
+ description="Model confidence in the extracted value, a whole number from 0 to 100. `null` when the backend did not produce a confidence (e.g. manual entry).",
149
164
  )
150
165
  evidence: list[Evidence] = Field(
151
166
  default_factory=list,
@@ -238,17 +253,17 @@ class Block(_OmitsUnsetFileRefs):
238
253
  bbox: dict[str, float] = Field(
239
254
  description="Normalised bounding box in [0, 1] page coordinates with keys `x0`/`y0`/`x1`/`y1`.",
240
255
  )
241
- layout_confidence: Optional[float] = Field(
256
+ layout_confidence: Optional[Percent] = Field(
242
257
  default=None,
243
258
  description=(
244
- "0-1 layout detection confidence for this block. `null` when no layout detector ran "
259
+ "Layout detection confidence for this block, a whole number from 0 to 100. `null` when no layout detector ran "
245
260
  "— the `lite` tier gets its layout from the OCR response, "
246
261
  "which reports no confidence in the type it assigned."
247
262
  ),
248
263
  )
249
- parse_confidence: Optional[float] = Field(
264
+ parse_confidence: Optional[Percent] = Field(
250
265
  default=None,
251
- description="0-100 parse confidence calibrated from LLM logprobs. `null` when logprobs were unavailable (e.g. text-bytes strategy).",
266
+ description="Parse confidence calibrated from LLM logprobs, a whole number from 0 to 100. `null` when logprobs were unavailable (e.g. text-bytes strategy).",
252
267
  )
253
268
  regions: list[Detection] = Field(
254
269
  default_factory=list,
@@ -303,17 +318,17 @@ class ParseResult(BaseModel):
303
318
  "read one or the other, not both. `null` if `markdown` is null."
304
319
  ),
305
320
  )
306
- layout_confidence: Optional[float] = Field(
321
+ layout_confidence: Optional[Percent] = Field(
307
322
  default=None,
308
323
  description=(
309
- "Document-level YOLO layout confidence on a 0-1 scale, "
310
- "char-weighted mean across all blocks. `null` if no annotated sections."
324
+ "Document-level layout confidence, a whole number from 0 to 100: "
325
+ "the char-weighted mean across all blocks. `null` if no annotated sections."
311
326
  ),
312
327
  )
313
- parse_confidence: Optional[float] = Field(
328
+ parse_confidence: Optional[Percent] = Field(
314
329
  default=None,
315
330
  description=(
316
- "Document-level parse confidence on a 0-100 scale, char-weighted mean "
331
+ "Document-level parse confidence, a whole number from 0 to 100: the char-weighted mean "
317
332
  "of per-block LLM logprob scores. `null` when no blocks have logprob-based confidence."
318
333
  ),
319
334
  )
@@ -386,8 +401,8 @@ class RunParseLayerAbsence(BaseModel):
386
401
 
387
402
 
388
403
  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.")
404
+ mean: Percent = Field(description="The mean confidence of the sequence's elements, a whole number from 0 to 100.")
405
+ min: Percent = Field(description="The lowest confidence of the sequence's elements, a whole number from 0 to 100.")
391
406
 
392
407
 
393
408
  class RunParseSequence(_OmitsUnsetFileRefs):
@@ -427,18 +442,70 @@ class RunParseElement(_OmitsUnsetFileRefs):
427
442
  bbox: dict[str, float] = Field(
428
443
  description="Normalised bounding box in [0, 1] page coordinates with keys `x0`/`y0`/`x1`/`y1`.",
429
444
  )
430
- confidence: Optional[float] = Field(description="0-1, as core measured it; `null` when nothing scored it.")
445
+ confidence: Optional[Percent] = Field(
446
+ description="A whole number from 0 to 100; `null` when nothing scored it."
447
+ )
431
448
  source: str = Field(description="Where its text came from: `embedded`, `ocr` or `transcribed`.")
432
449
 
433
450
 
434
451
  class RunParseLayerLink(BaseModel):
435
- """A stored layer object too large to serve inline, handed out as stored, in its published format."""
452
+ """A stored layer object too large to serve inline, handed out as stored: its confidences are on 0-1."""
436
453
 
437
454
  url: str = Field(description="A presigned GET of the object, valid for 15 minutes; it is served gzip-encoded.")
438
455
  version: int = Field(description="The published format version the object is stored in.")
439
456
  size_bytes: int = Field(description="The object's size as stored, gzipped.")
440
457
 
441
458
 
459
+ class RunParseTableCell(BaseModel):
460
+ """One table cell as table grounding mapped it onto the page."""
461
+
462
+ id: str = Field(
463
+ description="`r<row>c<col>`, the grid row and column it starts at across its block's tables; unique within its block only."
464
+ )
465
+ text: str = Field(description="The cell's text, as the table's markup gives it.")
466
+ bbox: Optional[dict[str, float]] = Field(
467
+ description=(
468
+ "Normalised bounding box in [0, 1] page coordinates with keys `x0`/`y0`/`x1`/`y1`, as grounding mapped it, "
469
+ "unchecked against the page; `null` when grounding found none."
470
+ ),
471
+ )
472
+ match: Optional[str] = Field(
473
+ description="How grounding placed it, such as `anchor` or `orphan_spatial`; `null` when it matched nothing."
474
+ )
475
+
476
+
477
+ class RunParseLink(BaseModel):
478
+ """One link annotation of the page that lies over its block."""
479
+
480
+ uri: str = Field(description="The link's target, as the PDF names it.")
481
+ bbox: dict[str, float] = Field(
482
+ description="The annotation's normalised bounding box in [0, 1] page coordinates with keys `x0`/`y0`/`x1`/`y1`.",
483
+ )
484
+
485
+
486
+ class RunParseV3Block(Block):
487
+ """A block of one parse of a run, with the cells grounding stored for it."""
488
+
489
+ bbox: Optional[dict[str, float]] = Field(
490
+ description=(
491
+ "Normalised bounding box in [0, 1] page coordinates with keys `x0`/`y0`/`x1`/`y1`; `null` for a block "
492
+ "with no page geometry, such as one of a spreadsheet, a CSV or a text file."
493
+ ),
494
+ )
495
+
496
+ cells: list[RunParseTableCell] = Field(
497
+ default_factory=list,
498
+ description="Each cell of a table block, as its packet parse stored it; empty on any other block, and when the parse is read from its files' own parses instead.",
499
+ )
500
+ links: list[RunParseLink] = Field(
501
+ default_factory=list,
502
+ description=(
503
+ "Each link annotation of a PDF page that lies over the block, once, as its packet parse stored it; empty "
504
+ "when the parse is read from its files' own parses instead."
505
+ ),
506
+ )
507
+
508
+
442
509
  class RunParseV3(ParseResult):
443
510
  """One parse of a run: the parse node that read the packet, and what it read, as the anchored markdown and its blocks.
444
511
 
@@ -464,18 +531,20 @@ class RunParseV3(ParseResult):
464
531
  "their node."
465
532
  ),
466
533
  )
467
- is_entry: bool = Field(description="Whether this is the run's entry parse, the one every run starts with.")
468
- read_by_extraction: bool = Field(
469
- description="Whether an extraction of the run read this parse: the nearest parse upstream of its extract node.",
470
- )
471
534
  layers: Optional[dict[str, RunParseLayerAbsence]] = Field(
472
535
  default=None,
473
536
  description=(
474
537
  "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 "
538
+ "the read could not serve; any other stored layer is not listed. A parse with a file parsed by a tier that "
539
+ "measures neither `sequences` nor `elements` (`lite`) lists both as `not_for_tier`, whatever it stored. "
540
+ "Otherwise `null` when the run stored no listing of this node's packet parse, as for a parse stored before "
476
541
  "listings were."
477
542
  ),
478
543
  )
544
+ blocks: list[RunParseV3Block] = Field(
545
+ default_factory=list,
546
+ description="Each block, in packet page and reading order, with its table cells.",
547
+ )
479
548
  sequences: Optional[list[RunParseSequence]] = Field(
480
549
  default=None,
481
550
  description="Each sequence, in packet page and reading order, when asked for and served; else `null`.",
@@ -517,13 +586,13 @@ class ParseBlocksResultV3(BaseModel):
517
586
  """
518
587
 
519
588
  format: Literal["blocks"] = Field(description="`blocks`: the parse as `pages` of blocks.")
520
- layout_confidence: Optional[float] = Field(
589
+ layout_confidence: Optional[Percent] = Field(
521
590
  default=None,
522
- description="Document-level layout confidence on a 0-1 scale, char-weighted mean across all blocks.",
591
+ description="Document-level layout confidence, a whole number from 0 to 100: the char-weighted mean across all blocks.",
523
592
  )
524
- parse_confidence: Optional[float] = Field(
593
+ parse_confidence: Optional[Percent] = Field(
525
594
  default=None,
526
- description="Document-level parse confidence on a 0-100 scale, char-weighted mean across all blocks.",
595
+ description="Document-level parse confidence, a whole number from 0 to 100: the char-weighted mean across all blocks.",
527
596
  )
528
597
  pages: list[ParsePage] = Field(default_factory=list, description="The pages that hold a block, in page order.")
529
598
 
@@ -559,8 +628,8 @@ class SplitPartition(BaseModel):
559
628
  )
560
629
  name: str = Field(description="The partition value (free-form string).")
561
630
  files: list[FilePages]
562
- confidence: Optional[int] = Field(
563
- description="0-100 minimum confidence across the partition's ranges. "
631
+ confidence: Optional[Percent] = Field(
632
+ description="The minimum confidence across the partition's ranges, a whole number from 0 to 100. "
564
633
  "`null` when the partition holds no page, because nothing was measured.",
565
634
  )
566
635
 
@@ -582,8 +651,8 @@ class SplitResult(BaseModel):
582
651
  )
583
652
  name: str = Field(description="The split's category name.")
584
653
  files: list[FilePages] = Field(description="Per-file page lists, union of all partitions.")
585
- confidence: Optional[int] = Field(
586
- description="0-100 aggregate confidence (min across partitions). "
654
+ confidence: Optional[Percent] = Field(
655
+ description="Aggregate confidence, a whole number from 0 to 100 (min across partitions). "
587
656
  "`null` when the category matched no page, because nothing was measured.",
588
657
  )
589
658
  partitions: list[SplitPartition] = Field(default_factory=list)
@@ -593,8 +662,8 @@ class ClassificationResult(BaseModel):
593
662
  """One classifier verdict for the collection."""
594
663
 
595
664
  category: str = Field(description="The category the document was classified as.")
596
- confidence: Optional[float] = Field(
597
- description="0-100 model confidence in the verdict. "
665
+ confidence: Optional[Percent] = Field(
666
+ description="Model confidence in the verdict, a whole number from 0 to 100. "
598
667
  "`null` when the verdict carries no score, because nothing was measured.",
599
668
  )
600
669
  evidence: Optional[str] = Field(
@@ -708,9 +777,9 @@ class EditFormField(BaseModel):
708
777
  "`checkbox`. `null` when no instruction addressed this field."
709
778
  ),
710
779
  )
711
- confidence: Optional[int] = Field(
780
+ confidence: Optional[Percent] = Field(
712
781
  description=(
713
- "Raw, uncalibrated 0-100 match score for pairing an instruction with this "
782
+ "Raw, uncalibrated match score, a whole number from 0 to 100, for pairing an instruction with this "
714
783
  "field. It grades how surely the instruction addresses the field, not whether "
715
784
  "the written value is correct, and it is not a probability. `null` when no "
716
785
  "instruction addressed this field, because nothing was measured."
@@ -0,0 +1,46 @@
1
+ """The ``${…}`` token grammar of an alert node's message template.
2
+
3
+ It lives with the node definitions so every package that reads a template, from the
4
+ topology checks to the renderer in ``anyformat.domain.alert_template``, parses it
5
+ with this one pattern.
6
+ """
7
+
8
+ import re
9
+ from collections.abc import Callable
10
+
11
+ __all__ = ["TOKEN_RE", "referenced_field_ids", "referenced_rule_ids", "remap_field_ids"]
12
+
13
+ _ID = r"[A-Za-z0-9_\-]+"
14
+ TOKEN_RE = re.compile(
15
+ r"\$\{(?:"
16
+ rf"field\.(?P<field>{_ID})"
17
+ rf"|table\.(?P<table>{_ID})"
18
+ rf"|validation\.(?P<rule>{_ID})\.(?P<attr>status|detail|severity)"
19
+ r"|document\.(?P<document>category|filename|link)"
20
+ r")\}"
21
+ )
22
+
23
+
24
+ def referenced_field_ids(template: str) -> list[str]:
25
+ """The persistent ids a template's ``${field.*}`` and ``${table.*}`` tokens name."""
26
+ return [
27
+ match["field"] or match["table"] for match in TOKEN_RE.finditer(template) if match["field"] or match["table"]
28
+ ]
29
+
30
+
31
+ def referenced_rule_ids(template: str) -> list[str]:
32
+ """The rule ids a template's ``${validation.*}`` tokens name."""
33
+ return [match["rule"] for match in TOKEN_RE.finditer(template) if match["rule"]]
34
+
35
+
36
+ def remap_field_ids(template: str, remap: Callable[[str], str]) -> str:
37
+ """``template`` with each ``${field.*}`` and ``${table.*}`` persistent id passed through ``remap``."""
38
+
39
+ def _remapped(match: re.Match[str]) -> str:
40
+ if match["field"]:
41
+ return f"${{field.{remap(match['field'])}}}"
42
+ if match["table"]:
43
+ return f"${{table.{remap(match['table'])}}}"
44
+ return match[0]
45
+
46
+ return TOKEN_RE.sub(_remapped, template)
@@ -14,8 +14,7 @@ the backend to run :func:`validate` on the graph it is building, so neither
14
14
  half is restated in the frontend.
15
15
  """
16
16
 
17
- import re
18
- from collections.abc import Callable, Sequence
17
+ from collections.abc import Callable, Mapping, Sequence
19
18
  from dataclasses import dataclass, field
20
19
  from typing import TYPE_CHECKING, Protocol, runtime_checkable
21
20
 
@@ -35,6 +34,7 @@ from anyformat.workflow.nodes import (
35
34
  SplitterNode,
36
35
  ValidateNode,
37
36
  )
37
+ from anyformat.workflow.template_tokens import referenced_rule_ids
38
38
 
39
39
  if TYPE_CHECKING:
40
40
  from anyformat.workflow.definition import WorkflowDefinition
@@ -744,13 +744,6 @@ class AtMostOneKnowledgeNode:
744
744
  ]
745
745
 
746
746
 
747
- # Mirrors the runtime regex in
748
- # ``anyformat_core.operations.alerting.base._VALIDATION_REF_RE`` and the backend
749
- # extractor in ``core_tasks``. Kept here so the topology rule below
750
- # doesn't import from either side (they don't import each other).
751
- _TEMPLATE_VALIDATION_REF_RE = re.compile(r"\$\{validation\.([A-Za-z0-9_\-]+)\.(?:status|detail|severity)\}")
752
-
753
-
754
747
  def _validation_rule_ids_in_check(check: Check) -> list[str]:
755
748
  """Every ``rule_id`` a check tree references — walks combinators."""
756
749
  if isinstance(check, ValidationCheck):
@@ -843,7 +836,7 @@ class ValidationRuleIdReferencesExist:
843
836
  )
844
837
  )
845
838
  elif isinstance(node, SlackAlertNode):
846
- referenced_template = _TEMPLATE_VALIDATION_REF_RE.findall(node.message_template)
839
+ referenced_template = referenced_rule_ids(node.message_template)
847
840
  if not referenced_template:
848
841
  continue
849
842
  reachable = _upstream_validate_rule_ids(node.id, nodes_by_id, edges_by_target)
@@ -929,6 +922,26 @@ def skippable_topology_rules(has_flag: FlagCheck) -> frozenset[str]:
929
922
  return frozenset(rule for flag, rules in _RULES_WAIVED_BY_FLAG.items() if has_flag(flag) for rule in rules)
930
923
 
931
924
 
925
+ NODE_NEEDS_FLAG = "node_needs_flag"
926
+
927
+
928
+ def unavailable_nodes(node_types: Mapping[str, str], has_flag: FlagCheck) -> list[Violation]:
929
+ """The nodes, given as id to type, whose type needs a flag ``has_flag`` does not hold.
930
+
931
+ Separate from :func:`validate`, so a stored node keeps loading wherever its flag is off."""
932
+ return [
933
+ Violation(
934
+ rule=NODE_NEEDS_FLAG,
935
+ message=f"node {node_id!r}: {node_type} nodes are not enabled for this organization.",
936
+ node_ids=[node_id],
937
+ )
938
+ for node_id, node_type in node_types.items()
939
+ if (node_cls := NODE_CLASSES_BY_TYPE.get(node_type)) is not None
940
+ and (flag := node_cls.required_flag()) is not None
941
+ and not has_flag(flag)
942
+ ]
943
+
944
+
932
945
  def validate(graph: "WorkflowDefinition", *, skip_rules: "frozenset[str]" = frozenset()) -> list[Violation]:
933
946
  """Run every registered rule and return the combined list of violations.
934
947
 
@@ -1066,5 +1079,6 @@ __all__ = [
1066
1079
  "Violation",
1067
1080
  "format_violations",
1068
1081
  "node_adjacency",
1082
+ "unavailable_nodes",
1069
1083
  "validate",
1070
1084
  ]
File without changes