areneau commited on
Commit
f65336d
·
verified ·
1 Parent(s): 46ba706

Add complete Clairic Transformers package

Browse files
This view is limited to 50 files because it contains too many changes.   See raw diff
Files changed (50) hide show
  1. README.md +182 -3
  2. clairic_model.py +129 -0
  3. clairic_runtime/__init__.py +6 -0
  4. clairic_runtime/api.py +201 -0
  5. clairic_runtime/ar.py +228 -0
  6. clairic_runtime/backend.py +1722 -0
  7. clairic_runtime/batch_completion.py +449 -0
  8. clairic_runtime/clair_schema.py +563 -0
  9. clairic_runtime/contracts.py +128 -0
  10. clairic_runtime/documents.py +91 -0
  11. clairic_runtime/embedded.py +144 -0
  12. clairic_runtime/entity_scope.py +37 -0
  13. clairic_runtime/errors.py +10 -0
  14. clairic_runtime/financial_scope.py +94 -0
  15. clairic_runtime/grounding.py +417 -0
  16. clairic_runtime/html_rows.py +132 -0
  17. clairic_runtime/identifier_scope.py +89 -0
  18. clairic_runtime/identifier_spelling.py +281 -0
  19. clairic_runtime/image_financial_lines.py +393 -0
  20. clairic_runtime/image_focus.py +48 -0
  21. clairic_runtime/image_identifier.py +170 -0
  22. clairic_runtime/image_party_names.py +68 -0
  23. clairic_runtime/image_ragged_rows.py +350 -0
  24. clairic_runtime/image_rows.py +323 -0
  25. clairic_runtime/image_table_rows.py +225 -0
  26. clairic_runtime/kernels.py +478 -0
  27. clairic_runtime/large.py +204 -0
  28. clairic_runtime/lists.py +49 -0
  29. clairic_runtime/math.py +391 -0
  30. clairic_runtime/media.py +98 -0
  31. clairic_runtime/media_cache.py +105 -0
  32. clairic_runtime/media_state_prompt.py +139 -0
  33. clairic_runtime/model.py +0 -0
  34. clairic_runtime/native.py +441 -0
  35. clairic_runtime/ordinary_list_completion.py +163 -0
  36. clairic_runtime/orientation.py +85 -0
  37. clairic_runtime/pdf_number_focus.py +86 -0
  38. clairic_runtime/po_image_supplement.py +220 -0
  39. clairic_runtime/printed_numbers.py +259 -0
  40. clairic_runtime/printed_temporal.py +178 -0
  41. clairic_runtime/readout.py +83 -0
  42. clairic_runtime/receipt_hybrid_inventory.py +377 -0
  43. clairic_runtime/receipt_totals.py +555 -0
  44. clairic_runtime/schema.py +533 -0
  45. clairic_runtime/settings.py +29 -0
  46. clairic_runtime/source_dates.py +320 -0
  47. clairic_runtime/source_rows.py +159 -0
  48. clairic_runtime/source_sums.py +334 -0
  49. clairic_runtime/table_rows.py +541 -0
  50. clairic_runtime/text_ar.py +164 -0
README.md CHANGED
@@ -1,10 +1,189 @@
1
  ---
2
- library_name: transformers
3
  license: apache-2.0
 
 
 
 
 
 
 
 
 
 
4
  ---
5
 
6
  # Clairic
7
 
8
- Clairic is a multimodal model for structured extraction, classification, estimation, and forecasting.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
9
 
10
- This private snapshot contains the model weights, typed prediction head, processor, and tokenizer. The System One Transformers helper is being finalized.
 
1
  ---
 
2
  license: apache-2.0
3
+ library_name: transformers
4
+ pipeline_tag: image-text-to-text
5
+ tags:
6
+ - clairic
7
+ - cloudflare
8
+ - systemone
9
+ - multimodal
10
+ - structured-output
11
+ - information-extraction
12
+ - custom-code
13
  ---
14
 
15
  # Clairic
16
 
17
+ Clairic is a 27B multimodal model that turns a state and a schema of typed fields
18
+ into structured answers. It supports text and image inputs, extraction, numerical
19
+ estimation, and forecasting. Each field has its own value and scoring information;
20
+ the response also reports input truncation and token usage.
21
+
22
+ See [Clairic Flash](https://huggingface.co/Cloudflare/clairic-flash) for the other model
23
+ in the Clairic family.
24
+
25
+ ## Model
26
+
27
+ - **Inputs:** a text or JSON state, optional images, and a mapping of field names to specifications.
28
+ - **Outputs:** typed values, lists, nulls, estimates, and forecast paths.
29
+ - **Scoring:** extraction confidence and null probabilities, plus optional quantiles for estimates.
30
+ - **Runtime:** PyTorch and Transformers, with local Python request helpers.
31
+
32
+ ## Usage
33
+
34
+ Use Python 3.11 or later and install the packages listed in `requirements.txt`. Inference uses PyTorch and
35
+ Transformers; `xgrammar` supplies schema constraints through a Transformers logits
36
+ processor.
37
+
38
+ The supported GPU setup is Linux x86_64 with an H100 or H200, PyTorch 2.11.0
39
+ with CUDA 13.0, and Transformers 5.10.2. The CUDA BF16 default uses FlashAttention 3
40
+ for text and vision, with batches of up to eight sequences. The first load fetches
41
+ the pinned attention kernel through `kernels`; cache it before running offline.
42
+ Explicit `attn_implementation`, `batch_size`, and `text_batch_size` loader options
43
+ remain available.
44
+
45
+ Download the repository, load the model and processor, and call `systemone` with a
46
+ System One: Predict request.
47
+
48
+ ```python
49
+ import sys
50
+
51
+ from huggingface_hub import snapshot_download
52
+
53
+ path = snapshot_download("Cloudflare/clairic")
54
+ sys.path.insert(0, path)
55
+ from clairic_model import load_release_model, systemone
56
+
57
+ model, processor = load_release_model(path, device="cuda")
58
+
59
+ response = systemone(
60
+ model,
61
+ processor,
62
+ {
63
+ "state": (
64
+ "Invoice from Northwind Supply. Issued 2026-09-02. "
65
+ "Items: Pens; Paper. Total: $1080.00."
66
+ ),
67
+ "fields": {
68
+ "vendor": {"type": "text", "instructions": "The invoice vendor."},
69
+ "total": {"type": "number", "decimals": 2},
70
+ "issued": {"type": "date"},
71
+ "items": {
72
+ "type": "list",
73
+ "items": "text",
74
+ "instructions": "The purchased item names, in order.",
75
+ },
76
+ },
77
+ },
78
+ )
79
+ print(response["answers"])
80
+ ```
81
+
82
+ ### Images
83
+
84
+ Pass PIL images alongside the state. Embedded base64 image inputs are also accepted.
85
+
86
+ ```python
87
+ from PIL import Image
88
+
89
+ response = systemone(
90
+ model,
91
+ processor,
92
+ {
93
+ "state": "Read the attached receipt.",
94
+ "images": [Image.open("receipt.png")],
95
+ "fields": {
96
+ "merchant": {"type": "text", "instructions": "The merchant name."},
97
+ "total": {"type": "number", "decimals": 2},
98
+ },
99
+ },
100
+ )
101
+ print(response["answers"])
102
+ ```
103
+
104
+ ### Estimates and forecasts
105
+
106
+ Declare a range for estimated values. Forecasts also specify a horizon and interval.
107
+ Set `include_quantiles` to return the available quantiles.
108
+
109
+ ```python
110
+ response = systemone(
111
+ model,
112
+ processor,
113
+ {
114
+ "state": "Daily demand for the last seven days: 41, 45, 43, 47, 49, 46, 48.",
115
+ "fields": {
116
+ "next_day": {"type": "estimate", "min": 0, "max": 100},
117
+ "next_three_days": {
118
+ "type": "forecast",
119
+ "min": 0,
120
+ "max": 100,
121
+ "horizon": 3,
122
+ "interval": "day",
123
+ },
124
+ },
125
+ "options": {"include_quantiles": True},
126
+ },
127
+ )
128
+ print(response["answers"])
129
+ ```
130
+
131
+ ## Input format
132
+
133
+ | Field | Description |
134
+ |---|---|
135
+ | `model` | Optional `clairic` or serving alias `clairic-27b`; `@cf/cloudflare/` aliases are accepted |
136
+ | `state` | Source text; the Python helper serializes JSON values to text |
137
+ | `images` | Optional PIL images or embedded base64 images |
138
+ | `documents` | Optional embedded PDF data URIs or `content_type` / `base64` objects |
139
+ | `fields` | Mapping of output field names to typed specifications |
140
+ | `reference_date` | Optional ISO date for relative date instructions |
141
+ | `options.include_quantiles` | Include available estimate and forecast quantiles |
142
+ | `options.return_state_text` | Include the retained source text in the response |
143
+
144
+ Field specifications support `text`, `number`, `date`, `time`, `datetime`, `duration`,
145
+ `boolean`, `enum`, `object`, `list`, `compute`, `estimate`, and `forecast`.
146
+ `instructions` describes what to return. Numeric fields can specify units and
147
+ rounding; lists declare their item schema; estimates and forecasts require bounds.
148
+ `nullable` defaults to true. `source_only: true` selects literal printed numbers,
149
+ dates, times, datetimes, or number/date lists. `knowledge: true` permits knowledge
150
+ answers for text, numbers, and supported list children. `compute` selects the typed
151
+ numeric head. Unsupported options and invalid combinations are rejected.
152
+
153
+ Embedded inputs are limited to 4 MiB each and 8 MiB combined. Images and rendered
154
+ PDF pages share a four-image/page limit. Image `rotation` accepts 0, 90, 180, or 270
155
+ clockwise degrees after EXIF orientation. Remote media URLs are not accepted.
156
+
157
+ ## Response
158
+
159
+ `systemone` returns a dictionary with `model`, `answers`, `truncated`, and `usage`.
160
+ Answers are keyed by the requested field names. Generated scalar extraction answers
161
+ retain `valid`, `complete`, full-sequence `confidence`, and independently scored `p_null`.
162
+ Uniquely matched text evidence includes character spans in `state`; image-only or
163
+ ambiguous evidence has null spans. Lists preserve item order and duplicates.
164
+ Estimates and forecasts include their typed values and, when requested, quantiles.
165
+
166
+ Scores are model probabilities and should be evaluated for the application's own
167
+ acceptance thresholds. Inspect `truncated` and any answer completeness indicators
168
+ before relying on a result.
169
+
170
+ Usage includes retries and supplemental work. The response model ID is `clairic`.
171
+ The Python API raises validation or request errors for invalid inputs, a queue-full
172
+ error for simultaneous requests, and an inference error for failed generation.
173
+ Use `await model.predict_async(request)` in an async application; cancellation
174
+ drains owned work before admitting another request.
175
+
176
+ ## Files
177
+
178
+ | File | Purpose |
179
+ |---|---|
180
+ | `model*.safetensors`, `model.safetensors.index.json`, `config.json` | Model weights and configuration |
181
+ | `clair_head.safetensors`, `clair_head_config.json` | Typed output components |
182
+ | `clairic_model.py` and supporting Python modules | Transformers loading and request handling |
183
+ | Tokenizer and processor files | Text and image preprocessing |
184
+ | `requirements.txt` | Python dependencies |
185
+ | `LICENSE` | Apache-2.0 license |
186
+
187
+ ## License
188
 
189
+ Released under the Apache-2.0 license.
clairic_model.py ADDED
@@ -0,0 +1,129 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Clairic's Transformers loader and System One prediction interface."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ import base64
7
+ import io
8
+ import json
9
+ from pathlib import Path
10
+ from typing import Any, Mapping
11
+
12
+ from clairic_runtime.api import PredictRequest, serialize_response
13
+ from clairic_runtime.backend import ClairicFlashModel
14
+ from clairic_runtime.errors import ClairRequestError
15
+ from clairic_runtime.large import Clairic27BModel
16
+ from clairic_runtime.settings import RuntimeSettings
17
+
18
+
19
+ def _request(value: Mapping[str, Any] | PredictRequest) -> PredictRequest:
20
+ if isinstance(value, PredictRequest):
21
+ return value
22
+ from PIL import Image, ImageOps
23
+
24
+ request = dict(value)
25
+ if "state" in request and not isinstance(request["state"], str):
26
+ request["state"] = json.dumps(request["state"], ensure_ascii=False)
27
+ images = request.get("images")
28
+ if isinstance(images, (list, tuple)):
29
+ images = list(images)
30
+ for index, image in enumerate(images):
31
+ if isinstance(image, Image.Image):
32
+ buffer = io.BytesIO()
33
+ ImageOps.exif_transpose(image).convert("RGBA").save(
34
+ buffer, format="PNG"
35
+ )
36
+ images[index] = "data:image/png;base64," + base64.b64encode(
37
+ buffer.getvalue()
38
+ ).decode("ascii")
39
+ request["images"] = images
40
+ return PredictRequest.model_validate(request)
41
+
42
+
43
+ class ClairicModel:
44
+ """A model and its typed prediction head, with synchronous and async APIs."""
45
+
46
+ def __init__(self, runtime: ClairicFlashModel, public_name: str) -> None:
47
+ self.runtime = runtime
48
+ self.model_id = public_name
49
+ names = {public_name, runtime.model_id}
50
+ self._model_selectors = names | {"@cf/cloudflare/" + name for name in names}
51
+ self.processor = runtime.processor
52
+ self.backbone = runtime.engine.backbone
53
+ self.head = runtime.engine.head
54
+ self.device = runtime.engine.device
55
+
56
+ async def predict_async(
57
+ self, request: Mapping[str, Any] | PredictRequest
58
+ ) -> dict[str, Any]:
59
+ validated = _request(request)
60
+ if validated.model is not None and validated.model not in self._model_selectors:
61
+ raise ClairRequestError(
62
+ f"Unsupported model '{validated.model}'. Use '{self.model_id}'."
63
+ )
64
+ output = await self.runtime.predict_async(validated)
65
+ return serialize_response(validated, output, self.model_id)
66
+
67
+ def predict(self, request: Mapping[str, Any] | PredictRequest) -> dict[str, Any]:
68
+ """Return structured values and scores for a prediction request."""
69
+ try:
70
+ asyncio.get_running_loop()
71
+ except RuntimeError:
72
+ return asyncio.run(self.predict_async(request))
73
+ raise RuntimeError(
74
+ "Use await model.predict_async(request) inside an active event loop"
75
+ )
76
+
77
+ def eval(self) -> ClairicModel:
78
+ self.backbone.eval()
79
+ self.head.eval()
80
+ return self
81
+
82
+ def close(self) -> None:
83
+ self.runtime.shutdown()
84
+
85
+
86
+ def load_release_model(
87
+ model_path: str | Path,
88
+ device: Any = "cuda",
89
+ dtype: Any = None,
90
+ max_length: int = 65_273,
91
+ **from_pretrained_kwargs: Any,
92
+ ) -> tuple[ClairicModel, Any]:
93
+ """Load a local snapshot or a Hugging Face repository with Transformers."""
94
+ path = Path(model_path)
95
+ if not path.is_dir():
96
+ from huggingface_hub import snapshot_download
97
+
98
+ path = Path(snapshot_download(str(model_path)))
99
+ configuration = json.loads((path / "clair_head_config.json").read_text())
100
+ large = int(configuration["hidden_size"]) == 5120
101
+ model_id = "clairic-27b" if large else "clairic-flash"
102
+ settings = RuntimeSettings(
103
+ model_path=str(path),
104
+ version="1",
105
+ model_id=model_id,
106
+ max_length=max_length,
107
+ max_concurrency=1,
108
+ )
109
+ implementation = Clairic27BModel if large else ClairicFlashModel
110
+ runtime = implementation.load(
111
+ settings, device=str(device), dtype=dtype, **from_pretrained_kwargs
112
+ )
113
+ return ClairicModel(
114
+ runtime, "clairic" if large else "clairic-flash"
115
+ ), runtime.processor
116
+
117
+
118
+ def systemone(
119
+ model: ClairicModel,
120
+ processor: Any,
121
+ request: Mapping[str, Any] | PredictRequest,
122
+ max_length: int | None = None,
123
+ ) -> dict[str, Any]:
124
+ """Answer a System One prediction request with typed fields and confidence."""
125
+ if processor is not model.processor:
126
+ raise ValueError("Use the processor returned with this model")
127
+ if max_length is not None and max_length != model.runtime.settings.max_length:
128
+ raise ValueError("Set max_length when calling load_release_model")
129
+ return model.predict(request)
clairic_runtime/__init__.py ADDED
@@ -0,0 +1,6 @@
 
 
 
 
 
 
 
1
+ """Clairic inference with Transformers."""
2
+
3
+ CONTEXT_WINDOW = 65_536
4
+ MAX_OUTPUT_TOKENS = 256
5
+ CONTEXT_HEADROOM_TOKENS = MAX_OUTPUT_TOKENS + 7
6
+ MAX_INPUT_TOKENS = CONTEXT_WINDOW - CONTEXT_HEADROOM_TOKENS
clairic_runtime/api.py ADDED
@@ -0,0 +1,201 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Clairic request and response schemas."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import base64
6
+ import io
7
+ from dataclasses import dataclass
8
+ from typing import Any, LiteralString, cast
9
+
10
+ from .embedded import (
11
+ MAX_IMAGE_BYTES,
12
+ MAX_IMAGES,
13
+ MAX_IMAGES_BYTES,
14
+ EmbeddedImageError,
15
+ decoded_base64_size,
16
+ normalize_embedded_image,
17
+ validate_image_count,
18
+ validate_total_image_bytes,
19
+ )
20
+ from PIL import Image, ImageOps
21
+ from pydantic import (
22
+ BaseModel,
23
+ ConfigDict,
24
+ Field,
25
+ StrictStr,
26
+ field_validator,
27
+ model_validator,
28
+ )
29
+ from pydantic_core import PydanticCustomError
30
+
31
+ from .documents import ClairDocument
32
+
33
+ MODEL_ID = "clairic"
34
+
35
+
36
+ def _image_error(error: EmbeddedImageError) -> PydanticCustomError:
37
+ # Every code and message originates from fixed literals in the shared helper.
38
+ return PydanticCustomError(
39
+ cast(LiteralString, error.code), cast(LiteralString, str(error))
40
+ )
41
+
42
+
43
+ class ClairImage(BaseModel):
44
+ """An embedded PNG, JPEG, or WebP image validated before it reaches the processor."""
45
+
46
+ model_config = ConfigDict(extra="forbid", frozen=True)
47
+
48
+ content_type: StrictStr
49
+ base64: StrictStr
50
+ rotation: int = 0
51
+
52
+ @model_validator(mode="before")
53
+ @classmethod
54
+ def parse_image(cls, value: object) -> object:
55
+ try:
56
+ rotation = 0
57
+ explicit_rotation = isinstance(value, dict) and "rotation" in value
58
+ if explicit_rotation:
59
+ value = dict(value) # type: ignore[call-overload] # explicit_rotation guards the dict input.
60
+ rotation = value.pop("rotation") # type: ignore[attr-defined]
61
+ if type(rotation) is not int or rotation not in (0, 90, 180, 270):
62
+ raise EmbeddedImageError(
63
+ "invalid_image",
64
+ "rotation must be 0, 90, 180 or 270 clockwise degrees",
65
+ )
66
+ normalized = normalize_embedded_image(
67
+ value, strict=True, max_image_bytes=MAX_IMAGE_BYTES
68
+ )
69
+ return (
70
+ {**normalized, "rotation": rotation}
71
+ if explicit_rotation
72
+ else normalized
73
+ )
74
+ except EmbeddedImageError as error:
75
+ raise _image_error(error) from error
76
+
77
+ def to_pil(self) -> Image.Image:
78
+ from .orientation import orient_document
79
+
80
+ with Image.open(io.BytesIO(base64.b64decode(self.base64))) as image:
81
+ result = ImageOps.exif_transpose(image)
82
+ if "A" in result.getbands() or "transparency" in result.info:
83
+ # Render visible document pixels before discarding alpha. Hidden
84
+ # RGB values can otherwise erase opaque black text completely.
85
+ rgba = result if result.mode == "RGBA" else result.convert("RGBA")
86
+ result = Image.new("RGB", rgba.size, "white")
87
+ result.paste(rgba, mask=rgba.getchannel("A"))
88
+ else:
89
+ result = result.convert("RGB")
90
+ if "rotation" in self.model_fields_set:
91
+ return (
92
+ result.rotate(-self.rotation, expand=True)
93
+ if self.rotation
94
+ else result
95
+ )
96
+ return orient_document(result)
97
+
98
+ @property
99
+ def decoded_size(self) -> int:
100
+ return decoded_base64_size(self.base64)
101
+
102
+
103
+ class PredictOptions(BaseModel):
104
+ model_config = ConfigDict(extra="forbid")
105
+
106
+ include_quantiles: bool = False
107
+ return_state_text: bool = False
108
+
109
+
110
+ class PredictRequest(BaseModel):
111
+ """A state (any text), optional images, and any number of typed fields. Field specs are checked against
112
+ the field schema when the request is encoded."""
113
+
114
+ model_config = ConfigDict(extra="forbid")
115
+
116
+ model: StrictStr | None = None
117
+ state: StrictStr = ""
118
+ images: tuple[ClairImage, ...] = Field(
119
+ default=(), json_schema_extra={"maxItems": MAX_IMAGES}
120
+ )
121
+ documents: tuple[ClairDocument, ...] = Field(default=(), max_length=MAX_IMAGES)
122
+ fields: dict[StrictStr, dict[StrictStr, Any]]
123
+ reference_date: StrictStr | None = None
124
+ options: PredictOptions = Field(default_factory=PredictOptions)
125
+
126
+ @field_validator("images", mode="before")
127
+ @classmethod
128
+ def check_image_count(cls, value: object) -> object:
129
+ try:
130
+ return validate_image_count(value, max_images=MAX_IMAGES)
131
+ except EmbeddedImageError as error:
132
+ raise _image_error(error) from error
133
+
134
+ @model_validator(mode="after")
135
+ def check_content(self) -> PredictRequest:
136
+ if not self.fields:
137
+ raise PydanticCustomError(
138
+ "empty_fields", "fields must declare at least one field"
139
+ )
140
+ if not self.state.strip() and not self.images and not self.documents:
141
+ raise PydanticCustomError(
142
+ "empty_state", "state must be non-empty when no images are sent"
143
+ )
144
+ try:
145
+ validate_total_image_bytes(
146
+ (
147
+ decoded_base64_size(item.base64)
148
+ for item in (*self.images, *self.documents)
149
+ ),
150
+ max_bytes=MAX_IMAGES_BYTES, # type: ignore[attr-defined] # Both validated media types have base64.
151
+ )
152
+ except EmbeddedImageError as error:
153
+ raise _image_error(error) from error
154
+ return self
155
+
156
+
157
+ @dataclass(frozen=True, slots=True)
158
+ class PredictOutput:
159
+ answers: dict[str, dict[str, Any]]
160
+ truncated: bool
161
+ state_tokens: int
162
+ image_tokens: int
163
+ schema_tokens: int
164
+ input_tokens: int
165
+ passes: int
166
+ state_text: str | None = None
167
+ output_tokens: int = 0
168
+
169
+
170
+ def _without_quantiles(answer: dict[str, Any]) -> dict[str, Any]:
171
+ answer = {key: value for key, value in answer.items() if key != "quantiles"}
172
+ if isinstance(answer.get("steps"), list):
173
+ answer["steps"] = [_without_quantiles(step) for step in answer["steps"]]
174
+ return answer
175
+
176
+
177
+ def serialize_response(
178
+ request: PredictRequest, output: PredictOutput, model_id: str
179
+ ) -> dict[str, Any]:
180
+ answers = {
181
+ name: answer
182
+ if request.options.include_quantiles
183
+ else _without_quantiles(answer)
184
+ for name, answer in output.answers.items()
185
+ }
186
+ content: dict[str, Any] = {
187
+ "model": model_id,
188
+ "answers": answers,
189
+ "truncated": output.truncated,
190
+ "usage": {
191
+ "state_tokens": output.state_tokens,
192
+ "image_tokens": output.image_tokens,
193
+ "schema_tokens": output.schema_tokens,
194
+ "input_tokens": output.input_tokens,
195
+ "output_tokens": output.output_tokens,
196
+ "passes": output.passes,
197
+ },
198
+ }
199
+ if request.options.return_state_text and output.state_text is not None:
200
+ content["state_text"] = output.state_text
201
+ return content
clairic_runtime/ar.py ADDED
@@ -0,0 +1,228 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ import json
3
+ import math
4
+ from decimal import ROUND_HALF_UP, Decimal, DecimalException, localcontext
5
+ from typing import Any
6
+ from . import image_rows
7
+
8
+ VERSION = "parallel-ar-json-scalar-v1"
9
+ EOS = "<|im_end|>"
10
+ EXTRACTION_INSTRUCTION = "Extract the requested value from the supplied input, following the field instructions and scope."
11
+ MEDIA_EVIDENCE_INSTRUCTION = "The attached images are the document pages and contain extraction evidence. Use all attached pages together with the accompanying text, following the field instructions and requested scope."
12
+ COMPUTATION_INSTRUCTION = "Answer the requested field using the supplied input and field instructions. Perform any required arithmetic, reasoning, normalization, or unit conversion. A computable answer is available even when it is not written literally in the source."
13
+ KNOWLEDGE_INSTRUCTION = "Answer the requested field using reliable prior knowledge and any relevant supplied input. This field explicitly permits knowledge: true. The answer does not need to appear in the document. Missing source evidence does not make a known factual answer unavailable. Return null only when neither reliable prior knowledge nor the input determines the answer. Follow the field instructions and scope."
14
+ RECOVERY_INSTRUCTION = "Answer the requested field using the supplied input and field instructions. Copy the matching source value exactly. Check labels, surrounding context and requested entity. Do not calculate, convert units, complete a name, or substitute a related field. Return the value if it is explicitly present; return null if it is absent."
15
+ BOOLEAN_INSTRUCTION = " This field is a Boolean statement about the input. Evaluate its condition using the supplied evidence: return true when the condition is affirmed, false when the condition is explicitly negated, and null only when evidence does not determine whether it holds. The literal words true and false do not need to be printed."
16
+
17
+
18
+ def normalize_number(value: Any, spec: dict[str, Any]) -> Any:
19
+ decimals = 0 if spec.get("integer") else spec.get("decimals")
20
+ if value is None or spec["type"] != "number":
21
+ return value
22
+ if isinstance(value, bool):
23
+ raise TypeError("A boolean is not a numeric answer")
24
+ if decimals is None:
25
+ if isinstance(value, Decimal):
26
+ if not value.is_finite():
27
+ raise ValueError("Nonfinite number")
28
+ value = int(value) if value == value.to_integral_value() else float(value)
29
+ if isinstance(value, float) and (not math.isfinite(value)):
30
+ raise ValueError("Nonfinite number")
31
+ return value
32
+ number = value if isinstance(value, Decimal) else Decimal(str(value))
33
+ if not number.is_finite():
34
+ raise ValueError("Nonfinite number")
35
+ try:
36
+ with localcontext() as context:
37
+ context.prec = max(context.prec, number.adjusted() + decimals + 2)
38
+ number = number.quantize(
39
+ Decimal(1).scaleb(-decimals), rounding=ROUND_HALF_UP
40
+ )
41
+ except DecimalException as error:
42
+ raise ValueError(
43
+ "Cannot represent numeric answer at the requested precision"
44
+ ) from error
45
+ return int(number) if decimals == 0 else float(number)
46
+
47
+
48
+ def names(record: dict[str, Any]) -> list[str]:
49
+ return [
50
+ n
51
+ for (n, s) in record["fields"].items()
52
+ if s["type"] in ("text", "number", "boolean", "enum", "object")
53
+ or image_rows.is_inventory(s)
54
+ ]
55
+
56
+
57
+ def schema(spec: dict[str, Any]) -> dict[str, Any]:
58
+ if image_rows.is_inventory(spec):
59
+ return image_rows.inventory_schema(spec)
60
+ if spec["type"] == "object":
61
+ return {
62
+ "type": ["object", "null"] if spec.get("nullable", True) else "object",
63
+ "properties": {
64
+ name: schema(child) for (name, child) in spec["properties"].items()
65
+ },
66
+ "required": list(spec["properties"]),
67
+ "additionalProperties": False,
68
+ }
69
+ if spec["type"] == "boolean":
70
+ return {
71
+ "type": ["boolean", "null"] if spec.get("nullable", True) else "boolean"
72
+ }
73
+ if spec["type"] == "enum":
74
+ values = list(spec["enum"])
75
+ if spec.get("nullable", True) and None not in values:
76
+ values.append(None)
77
+ return {"enum": values}
78
+ kind = (
79
+ "string"
80
+ if spec["type"] == "text"
81
+ else "integer"
82
+ if spec.get("integer")
83
+ else "number"
84
+ )
85
+ result = {"type": [kind, "null"] if spec.get("nullable", True) else kind}
86
+ if kind == "string":
87
+ for key in ["minLength", "maxLength", "pattern", "enum"]:
88
+ if key in spec:
89
+ result[key] = spec[key]
90
+ elif kind in ("number", "integer"):
91
+ for key in [
92
+ "minimum",
93
+ "maximum",
94
+ "exclusiveMinimum",
95
+ "exclusiveMaximum",
96
+ "enum",
97
+ ]:
98
+ if key in spec:
99
+ result[key] = spec[key]
100
+ return result
101
+
102
+
103
+ def complete_spec(record: dict[str, Any], name: str) -> dict[str, Any]:
104
+ spec = dict(record["fields"][name])
105
+ annotation = (
106
+ record.get("_meta", {})
107
+ .get("extraction_contract", {})
108
+ .get("fields", {})
109
+ .get(name, {})
110
+ )
111
+ parent = annotation.get("parent")
112
+ if parent:
113
+ parent_spec = record["fields"].get(parent)
114
+ if not parent_spec or parent_spec["type"] != "list":
115
+ raise ValueError("Missing parent list definition: " + name)
116
+ spec["instructions"] = (
117
+ "Parent list "
118
+ + parent
119
+ + ": "
120
+ + parent_spec.get("instructions", "")
121
+ + "\nRequested element: "
122
+ + spec.get("instructions", "")
123
+ )
124
+ return spec
125
+
126
+
127
+ def instruction(
128
+ record: dict[str, Any], name: str, *, compact_lists: bool = True
129
+ ) -> str:
130
+ image_instruction = image_rows.instruction(record, name, schema)
131
+ if image_instruction is not None:
132
+ return image_instruction
133
+ spec = complete_spec(record, name)
134
+ annotation = (
135
+ record.get("_meta", {})
136
+ .get("extraction_contract", {})
137
+ .get("fields", {})
138
+ .get(name, {})
139
+ )
140
+ if (
141
+ spec["type"] == "boolean"
142
+ and (not annotation.get("parent"))
143
+ and (not spec.get("_physical_row_scope"))
144
+ and (name not in record.get("_source_row_gates", ()))
145
+ ):
146
+ spec["instructions"] = spec.get("instructions", "") + BOOLEAN_INSTRUCTION
147
+ numeric_instructions = ""
148
+ if spec["type"] == "number":
149
+ if spec.get("unit"):
150
+ numeric_instructions += " Return the value in " + str(spec["unit"]) + "."
151
+ intro = (
152
+ (KNOWLEDGE_INSTRUCTION if spec.get("knowledge") else EXTRACTION_INSTRUCTION)
153
+ + " Return exactly one JSON scalar matching the field schema: quote and escape strings, write numbers without digit-group separators, and use null only when the value is unavailable and null is allowed. Zero is a present number. Preserve repeated source words and list entries. End immediately after the value."
154
+ )
155
+ parent = annotation.get("parent")
156
+ source_bound = spec.get("_physical_row_scope") or (
157
+ parent
158
+ and name
159
+ in record.get("_meta", {})
160
+ .get("extraction_contract", {})
161
+ .get("fields", {})
162
+ .get(parent, {})
163
+ .get("source_fields", [])
164
+ )
165
+ if parent and compact_lists and (spec["type"] != "object") and (not source_bound):
166
+ return (
167
+ intro
168
+ + "\nSchema: "
169
+ + json.dumps(schema(spec), ensure_ascii=False, separators=(",", ":"))
170
+ + "\nInstructions: "
171
+ + record["fields"][parent].get("instructions", "")
172
+ + numeric_instructions
173
+ + f"\nList: {parent}\nRequested element: Item {annotation['index']} of {parent}, "
174
+ + "following requested order and duplicate policy. Return null if this item does not exist.\nField: "
175
+ + name
176
+ )
177
+ if spec["type"] == "object":
178
+ row_instruction = (
179
+ "Check whether this exact physical source row satisfies the requested row scope and exclusions. Return null if this physical row does not match the requested scope, even though it exists. If it qualifies, return one JSON object matching the schema, using only this row's cells. "
180
+ if source_bound
181
+ else "Extract one complete requested row from the supplied document. Return one JSON object matching the schema, or null only if that row does not exist. Keep all properties on the same physical row. "
182
+ )
183
+ return (
184
+ row_instruction
185
+ + "Use null for a missing cell in an existing row. Preserve distinct rows with identical values. Follow the requested row scope and exclusions. End immediately after the object or null."
186
+ + "\nField: "
187
+ + name
188
+ + "\nSchema: "
189
+ + json.dumps(schema(spec), ensure_ascii=False, separators=(",", ":"))
190
+ + "\nInstructions: "
191
+ + spec.get("instructions", "")
192
+ + "\nProperty instructions: "
193
+ + json.dumps(spec["properties"], ensure_ascii=False)
194
+ )
195
+ return (
196
+ intro
197
+ + "\nField: "
198
+ + record.get("_source_row_names", {}).get(name, name)
199
+ + "\nSchema: "
200
+ + json.dumps(schema(spec), ensure_ascii=False, separators=(",", ":"))
201
+ + "\nInstructions: "
202
+ + spec.get("instructions", "")
203
+ + numeric_instructions
204
+ )
205
+
206
+
207
+ def typed_record(record: dict[str, Any]) -> dict[str, Any] | None:
208
+ active = set(names(record))
209
+ annotations = (
210
+ record.get("_meta", {}).get("extraction_contract", {}).get("fields", {})
211
+ )
212
+ omitted = set(active)
213
+ for name, spec in record["fields"].items():
214
+ annotation = annotations.get(name, {})
215
+ queries = annotation.get("query_fields", annotation.get("source_fields", []))
216
+ if spec["type"] == "list" and queries and all((n in active for n in queries)):
217
+ omitted.add(name)
218
+ fields = {
219
+ n: {**s, "type": "number"} if s["type"] == "compute" else s
220
+ for (n, s) in record["fields"].items()
221
+ if n not in omitted
222
+ }
223
+ if not fields:
224
+ return None
225
+ result = {**record, "fields": fields}
226
+ if "answers" in record:
227
+ result["answers"] = {n: record["answers"][n] for n in fields}
228
+ return result
clairic_runtime/backend.py ADDED
@@ -0,0 +1,1722 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ from collections.abc import Callable, Collection, Sequence
3
+ from typing import TYPE_CHECKING
4
+
5
+ if TYPE_CHECKING:
6
+ from .api import ClairImage
7
+ from .documents import ClairDocument
8
+ from PIL import Image
9
+ import asyncio
10
+ import concurrent.futures
11
+ import json
12
+ import logging
13
+ import math
14
+ import uuid
15
+ from decimal import Decimal
16
+ from pathlib import Path
17
+ from typing import Any, cast
18
+ from .api import MAX_IMAGES, PredictOutput, PredictRequest
19
+ from .errors import ClairInferenceError, ClairQueueFull, ClairRequestError
20
+ from .settings import RuntimeSettings
21
+ from . import (
22
+ MAX_OUTPUT_TOKENS,
23
+ ar,
24
+ batch_completion,
25
+ contracts,
26
+ entity_scope,
27
+ financial_scope,
28
+ grounding,
29
+ identifier_scope,
30
+ identifier_spelling,
31
+ image_financial_lines,
32
+ image_focus,
33
+ image_identifier,
34
+ image_party_names,
35
+ image_ragged_rows,
36
+ image_rows,
37
+ image_table_rows,
38
+ ordinary_list_completion,
39
+ pdf_number_focus,
40
+ printed_numbers,
41
+ printed_temporal,
42
+ receipt_totals,
43
+ source_dates,
44
+ source_rows,
45
+ table_rows,
46
+ )
47
+ from . import lists as extraction
48
+ from . import model as cm
49
+ from . import schema as zs
50
+ from .media_cache import ImageCache
51
+ from .media import batch_image_data, media_warmup_groups
52
+
53
+ if TYPE_CHECKING:
54
+ MediaPayload = list[dict[str, Any]]
55
+ ARTask = tuple[str, list[int], MediaPayload | None]
56
+ EncodedRequest = tuple[
57
+ dict[str, Any], dict[str, list[str]], list[ARTask], cm.EncodedRecord | None, int
58
+ ]
59
+ logger = logging.getLogger(__name__)
60
+
61
+
62
+ def common_prefix(tasks: Sequence[ARTask]) -> list[int]:
63
+ (first, last) = (min((t[1] for t in tasks)), max((t[1] for t in tasks)))
64
+ length = next(
65
+ (i for (i, (a, b)) in enumerate(zip(first, last)) if a != b),
66
+ min(len(first), len(last)),
67
+ )
68
+ return first[:length]
69
+
70
+
71
+ def expand_request(
72
+ request: PredictRequest,
73
+ *,
74
+ date_role_guidance: bool = True,
75
+ source_row_eligibility: bool = False,
76
+ local_scoped_pairs: bool = False,
77
+ fee_guidance: bool = False,
78
+ service_guidance: bool = False,
79
+ literal_payment_rows: bool = False,
80
+ ) -> tuple[dict[str, Any], dict[str, list[str]]]:
81
+ contracts.validate_public_fields(request.fields)
82
+ (fields, forecasts) = zs.expand_forecasts(
83
+ financial_scope.prepare(
84
+ request.fields,
85
+ has_media=bool(request.images or request.documents),
86
+ fee_guidance=fee_guidance,
87
+ service_guidance=service_guidance,
88
+ )
89
+ )
90
+ zs.validate_fields(fields)
91
+ zs.validate_reference_date(request.reference_date)
92
+ fields = {n: dict(s) for (n, s) in fields.items()}
93
+ for spec in fields.values():
94
+ if date_role_guidance and spec["type"] == "date":
95
+ instructions = spec.get("instructions", "")
96
+ spec["instructions"] = (
97
+ (instructions + "\n" if instructions else "")
98
+ + "Follow field instructions. Match the requested date role; null if unavailable."
99
+ )
100
+ annotations: dict[str, dict[str, Any]] = {}
101
+ row_inputs: dict[str, str]
102
+ row_names: dict[str, str]
103
+ (row_inputs, row_names) = ({}, {})
104
+ source_tables = table_rows.prepare(
105
+ request.state,
106
+ fields,
107
+ has_media=bool(request.images or request.documents),
108
+ allow_scoped_pairs=source_row_eligibility or local_scoped_pairs,
109
+ )
110
+ for name, spec in list(fields.items()):
111
+ if spec["type"] != "list":
112
+ continue
113
+ source_candidates = source_tables.get(name)
114
+ row_eligibility = source_row_eligibility or any(
115
+ (row.get("eligibility_only") for row in source_candidates or [])
116
+ )
117
+ budget = (
118
+ len(source_candidates)
119
+ if source_candidates
120
+ else zs.MAX_LIST_ITEMS + 1
121
+ if (request.images or request.documents) and "max_items" not in spec
122
+ else extraction.list_query_budget(request.state, spec)[0]
123
+ )
124
+ queries = []
125
+ item_spec = contracts.item_spec(spec)
126
+ for index in range(1, budget + 1):
127
+ child = zs.list_item_name(name, index)
128
+ if child in fields:
129
+ raise ValueError("Generated list field conflicts with " + child)
130
+ fields[child] = {
131
+ k: v
132
+ for (k, v) in spec.items()
133
+ if k not in {"type", "items", "instructions", "max_items"}
134
+ }
135
+ fields[child].update(item_spec)
136
+ fields[child].update(
137
+ type=item_spec["type"],
138
+ instructions=(
139
+ f"Item {index} of {name}, following requested order and duplicate policy. "
140
+ + spec.get("instructions", "")
141
+ + " Return null if this item does not exist."
142
+ ).strip(),
143
+ )
144
+ if source_candidates:
145
+ fields[child] = table_rows.row_spec(
146
+ spec, source_candidates[index - 1], eligibility=row_eligibility
147
+ )
148
+ if item_spec["type"] in ("text", "number", "object") and (
149
+ not (source_candidates and row_eligibility)
150
+ ):
151
+ fields[child]["nullable"] = True
152
+ if "enum" in fields[child] and None not in fields[child]["enum"]:
153
+ fields[child]["enum"] = [*fields[child]["enum"], None]
154
+ annotations[child] = {"parent": name, "index": index}
155
+ queries.append(child)
156
+ annotations[name] = (
157
+ {
158
+ "source_fields": queries,
159
+ "source_rows": source_candidates,
160
+ "source_row_eligibility": row_eligibility,
161
+ }
162
+ if source_candidates
163
+ else {"query_fields": queries}
164
+ )
165
+ if local_scoped_pairs and source_candidates:
166
+ (inputs, names) = table_rows.local_scope_context(
167
+ source_candidates, queries, offset=len(row_names)
168
+ )
169
+ row_inputs.update(inputs)
170
+ row_names.update(names)
171
+ (fields, temporal_kinds) = printed_temporal.prepare(fields)
172
+ payments = (
173
+ printed_numbers.payment_lists(request.fields)
174
+ if literal_payment_rows and (request.images or request.documents)
175
+ else []
176
+ )
177
+ payment_rows = [
178
+ child
179
+ for parent in payments
180
+ for child in annotations.get(parent, {}).get("query_fields", ())
181
+ ]
182
+ (fields, number_contracts) = printed_numbers.prepare(
183
+ fields, payment_rows=payment_rows
184
+ )
185
+ meta = {
186
+ "category": "extraction",
187
+ "construction": zs.EVIDENCE_CONSTRUCTION,
188
+ "extraction_contract": {"fields": annotations},
189
+ "printed_temporal": temporal_kinds,
190
+ "printed_numbers": number_contracts,
191
+ }
192
+ return (
193
+ {
194
+ "input": request.state,
195
+ "fields": fields,
196
+ "reference_date": request.reference_date,
197
+ "_meta": meta,
198
+ "_source_row_inputs": row_inputs,
199
+ "_source_row_names": row_names,
200
+ "_source_row_gates": [
201
+ query
202
+ for annotation in annotations.values()
203
+ if annotation.get("source_row_eligibility")
204
+ for query in annotation["source_fields"]
205
+ ],
206
+ },
207
+ forecasts,
208
+ )
209
+
210
+
211
+ def typed_readout_record(
212
+ request: PredictRequest,
213
+ record: dict[str, Any],
214
+ *,
215
+ automatic_temporal: dict[str, dict[str, Any]] | None = None,
216
+ **expand_options: Any,
217
+ ) -> dict[str, Any] | None:
218
+ typed = ar.typed_record(record)
219
+ if typed is None or not automatic_temporal:
220
+ return typed
221
+ original = request.model_copy(
222
+ update={"fields": {**request.fields, **automatic_temporal}}
223
+ )
224
+ (original_record, _) = expand_request(original, **expand_options)
225
+ return ar.typed_record(original_record)
226
+
227
+
228
+ def scalar_result(
229
+ result: dict[str, Any],
230
+ spec: dict[str, Any],
231
+ tokenizer: Any,
232
+ source: str | None = None,
233
+ evidence: grounding.Source | None = None,
234
+ *,
235
+ excluded_token_id: int | None = None,
236
+ provenance: grounding.Source | None = None,
237
+ ) -> dict[str, Any]:
238
+ from jsonschema import Draft202012Validator, ValidationError
239
+
240
+ meta = result.get("meta_info", {})
241
+ finish = meta.get("finish_reason", {}) or {}
242
+ eos = tokenizer.convert_tokens_to_ids(ar.EOS)
243
+ complete = finish.get("type") == "stop" and finish.get("matched") == eos
244
+ ids = result.get("output_ids")
245
+ if ids is not None:
246
+ ids = ids[:-1] if ids and ids[-1] == eos else ids
247
+ raw = tokenizer.decode(
248
+ ids, skip_special_tokens=False, clean_up_tokenization_spaces=False
249
+ )
250
+ else:
251
+ raw = result.get("text", "")
252
+ if complete and raw.endswith(ar.EOS):
253
+ raw = raw[: -len(ar.EOS)]
254
+ raw = raw.strip()
255
+ value = None
256
+ valid = False
257
+ span = None
258
+ failure_reason = None
259
+ if complete:
260
+ try:
261
+ value = json.loads(
262
+ raw, parse_constant=lambda s: (_ for _ in ()).throw(ValueError(s))
263
+ )
264
+ Draft202012Validator(ar.schema(spec)).validate(value)
265
+ if isinstance(value, float) and (not math.isfinite(value)):
266
+ raise ValueError("Nonfinite number")
267
+ if value is not None and evidence is not None:
268
+ literal = json.loads(raw, parse_float=Decimal, parse_int=Decimal)
269
+ (found, span) = (
270
+ evidence.span(literal, spec=spec)
271
+ if getattr(evidence, "normalize_whitespace", False)
272
+ else evidence.span(literal)
273
+ )
274
+ if not found:
275
+ failure_reason = "not_in_source"
276
+ raise ValueError("AR extraction is not a literal source value")
277
+ decimals = zs.allowed_decimals(spec) if spec["type"] == "number" else None
278
+ if value is not None and decimals is not None:
279
+ literal = json.loads(raw, parse_float=Decimal, parse_int=Decimal)
280
+ value = ar.normalize_number(literal, spec)
281
+ Draft202012Validator(ar.schema(spec)).validate(value)
282
+ if value is not None and spec["type"] == "object":
283
+ precise = json.loads(raw, parse_float=Decimal, parse_int=Decimal)
284
+ value = {
285
+ name: ar.normalize_number(precise[name], child)
286
+ if child["type"] == "number"
287
+ else value[name]
288
+ for (name, child) in spec["properties"].items()
289
+ }
290
+ Draft202012Validator(ar.schema(spec)).validate(value)
291
+ valid = True
292
+ except (ValueError, TypeError, ValidationError):
293
+ value = None
294
+ prediction = {
295
+ "value": value,
296
+ "valid": valid,
297
+ "complete": complete,
298
+ "decoder": ar.VERSION,
299
+ "tokens": int(meta.get("completion_tokens", 0)),
300
+ "raw": raw,
301
+ "span": span if valid else None,
302
+ }
303
+ if failure_reason is not None:
304
+ prediction["failure_reason"] = failure_reason
305
+ if valid and evidence is not None and (value is not None):
306
+ prediction["grounding_method"] = "literal_source"
307
+ if span is not None:
308
+ prediction["span_method"] = "unique_literal_match"
309
+ if (
310
+ getattr(evidence, "normalize_whitespace", False)
311
+ and isinstance(value, str)
312
+ and (value not in evidence.text)
313
+ ):
314
+ prediction["grounding_method"] = "whitespace_normalized_source"
315
+ if span is not None:
316
+ prediction["span_method"] = "unique_whitespace_normalized_match"
317
+ token_logprobs = meta.get("output_token_logprobs")
318
+ null_scores = meta.get("output_token_ids_logprobs")
319
+ if excluded_token_id is not None:
320
+ score = (
321
+ next(
322
+ (
323
+ float(token[0])
324
+ for token in null_scores[0]
325
+ if token[1] == excluded_token_id
326
+ ),
327
+ None,
328
+ )
329
+ if null_scores
330
+ else None
331
+ )
332
+ if score is None or math.isnan(score) or score > 1e-06:
333
+ raise ValueError(
334
+ "Transformers omitted a valid row-exclusion log probability"
335
+ )
336
+ prediction.update(
337
+ p_excluded=math.exp(min(0.0, score)),
338
+ p_excluded_method="ar_first_token_false_probability",
339
+ )
340
+ if not spec.get("nullable", True):
341
+ prediction.update(p_null=0.0, p_null_method="schema_disallows_null")
342
+ elif null_scores:
343
+ null_id = tokenizer.convert_tokens_to_ids("null")
344
+ score = next(
345
+ (float(token[0]) for token in null_scores[0] if token[1] == null_id), None
346
+ )
347
+ if score is None or math.isnan(score) or score > 1e-06:
348
+ raise ValueError("Transformers omitted a valid null-token log probability")
349
+ prediction.update(
350
+ p_null=math.exp(min(0.0, score)),
351
+ p_null_method="ar_first_token_null_probability",
352
+ )
353
+ if valid and token_logprobs:
354
+ log_probability = sum((float(token[0]) for token in token_logprobs))
355
+ if not math.isfinite(log_probability) or log_probability > 1e-06:
356
+ raise ValueError("Transformers returned invalid token log probabilities")
357
+ prediction.update(
358
+ confidence=math.exp(min(0.0, log_probability)),
359
+ log_probability=log_probability,
360
+ confidence_method="ar_sequence_probability",
361
+ )
362
+ elif not valid:
363
+ prediction["confidence"] = 0.0
364
+ if (
365
+ valid
366
+ and evidence is None
367
+ and (provenance is not None)
368
+ and (value is not None)
369
+ and (spec["type"] == "number")
370
+ ):
371
+ literal = json.loads(raw, parse_float=Decimal, parse_int=Decimal)
372
+ (found, literal_span) = provenance.span(literal)
373
+ if found and literal_span is not None:
374
+ prediction.update(span=literal_span, span_method="unique_literal_match")
375
+ if valid and evidence is None and isinstance(value, str) and value and source:
376
+ start = source.find(value)
377
+ if start >= 0 and source.find(value, start + 1) < 0:
378
+ prediction.update(
379
+ span=[start, start + len(value)], span_method="unique_literal_match"
380
+ )
381
+ return prediction
382
+
383
+
384
+ def validate_eos(path: Path, tokenizer: Any) -> None:
385
+ config = json.loads((path / "config.json").read_text())
386
+ generation = json.loads((path / "generation_config.json").read_text())
387
+ eos = tokenizer.convert_tokens_to_ids(ar.EOS)
388
+ configured = [
389
+ config.get("eos_token_id"),
390
+ config.get("text_config", {}).get("eos_token_id"),
391
+ generation.get("eos_token_id"),
392
+ ]
393
+ if any((value != eos for value in configured)):
394
+ raise ValueError(
395
+ "Model, text, and generation EOS must match the <|im_end|> terminator"
396
+ )
397
+
398
+
399
+ class ClairicFlashModel:
400
+ RELEASE_MODEL_ID = "clairic-v2"
401
+ COMPACT_LIST_PROMPTS = True
402
+ DATE_ROLE_GUIDANCE = True
403
+ RECOVER_NULLS = True
404
+ SOURCE_ROW_ELIGIBILITY = False
405
+ LOCAL_SOURCE_SCOPE = True
406
+ FINANCIAL_SERVICE_GUIDANCE = True
407
+ FINANCIAL_FEE_GUIDANCE = False
408
+ EXPLICIT_TEMPORAL_READS = True
409
+ SPELL_VISUAL_PO_REFERENCES = True
410
+ FOCUS_SPARSE_IMAGES = True
411
+ FOCUS_IMAGE_IDENTIFIERS = True
412
+ FOCUS_IMAGE_PARTY_NAMES = True
413
+ LITERAL_IMAGE_PAYMENT_ROWS = False
414
+ BIND_IMAGE_FINANCIAL_LINES = True
415
+ PRESERVE_IMAGE_ENTITY_NAMES = False
416
+ BIND_IMAGE_TABLE_ROWS = True
417
+ BIND_IMAGE_RAGGED_ROWS = True
418
+ IMAGE_TABLE_ROW_SCALE = 2
419
+ REQUEST_TIMEOUT_SECONDS = 600
420
+ DATE_SUPPLEMENT_TIMEOUT_SECONDS = 600
421
+ RECEIPT_SUPPLEMENT_TIMEOUT_SECONDS = 600
422
+
423
+ def __init__(
424
+ self,
425
+ engine: Any,
426
+ tokenizer: Any,
427
+ processor: Any,
428
+ settings: RuntimeSettings,
429
+ head_config: dict[str, Any],
430
+ ) -> None:
431
+ (self.engine, self.tokenizer, self.processor) = (engine, tokenizer, processor)
432
+ (self.settings, self.head_config) = (settings, head_config)
433
+ (self.max_concurrency, self.model_id) = (
434
+ settings.max_concurrency,
435
+ settings.model_id,
436
+ )
437
+ self._encoder = concurrent.futures.ThreadPoolExecutor(
438
+ max_workers=1, thread_name_prefix="clairic-encode"
439
+ )
440
+ self._in_flight = 0
441
+ self._image_cache = ImageCache()
442
+
443
+ def encode(
444
+ self,
445
+ request: PredictRequest,
446
+ *,
447
+ identifier_view: bool = False,
448
+ party_name_view: bool = False,
449
+ image_views: Callable[[], Sequence[Image.Image]] | None = None,
450
+ physical_row_view: bool = False,
451
+ image_view_key: str | None = None,
452
+ pdf_spelling_view: bool = False,
453
+ identifier_spelling_disabled: bool = False,
454
+ po_detail_view: bool = False,
455
+ ) -> EncodedRequest:
456
+ original_request = request
457
+ automatic_temporal = {}
458
+ if self.EXPLICIT_TEMPORAL_READS:
459
+ routed_fields = printed_temporal.explicit_fields(request.fields)
460
+ automatic_temporal = {
461
+ name: spec
462
+ for (name, spec) in request.fields.items()
463
+ if routed_fields[name] is not spec
464
+ }
465
+ request = request.model_copy(update={"fields": routed_fields})
466
+ if self.PRESERVE_IMAGE_ENTITY_NAMES:
467
+ request = request.model_copy(
468
+ update={
469
+ "fields": entity_scope.prepare(
470
+ request.fields,
471
+ has_media=bool(request.images or request.documents),
472
+ )
473
+ }
474
+ )
475
+ (scoped_fields, query_labels) = identifier_scope.prepare_fields(
476
+ request.fields, has_media=bool(request.images or request.documents)
477
+ )
478
+ if scoped_fields is not request.fields:
479
+ request = request.model_copy(update={"fields": scoped_fields})
480
+ if self.FOCUS_SPARSE_IMAGES and request.images or pdf_spelling_view:
481
+ request = request.model_copy(
482
+ update={"fields": image_focus.preserve_scalar_fields(request.fields)}
483
+ )
484
+ expand_options = {
485
+ "date_role_guidance": self.DATE_ROLE_GUIDANCE,
486
+ "source_row_eligibility": self.SOURCE_ROW_ELIGIBILITY,
487
+ "local_scoped_pairs": self.LOCAL_SOURCE_SCOPE,
488
+ "service_guidance": self.FINANCIAL_SERVICE_GUIDANCE,
489
+ "fee_guidance": self.FINANCIAL_FEE_GUIDANCE,
490
+ "literal_payment_rows": self.LITERAL_IMAGE_PAYMENT_ROWS,
491
+ }
492
+ (record, forecasts) = expand_request(request, **expand_options)
493
+ state_only_fields = {
494
+ name
495
+ for (name, spec) in original_request.fields.items()
496
+ if grounding.state_only(spec)
497
+ }
498
+ if self.SPELL_VISUAL_PO_REFERENCES and (not identifier_spelling_disabled):
499
+ identifier_spelling.prepare(
500
+ record,
501
+ original_request.fields,
502
+ query_labels,
503
+ has_media=bool(original_request.images or original_request.documents),
504
+ )
505
+ if query_labels:
506
+ spelling = record["_meta"].get("identifier_spelling", {})
507
+ record.setdefault("_source_row_names", {}).update(
508
+ {
509
+ name: name if name in spelling else label
510
+ for (name, label) in query_labels.items()
511
+ }
512
+ )
513
+ if physical_row_view:
514
+ for spec in record["fields"].values():
515
+ spec["_physical_row_scope"] = True
516
+ image_rows.prepare(
517
+ record,
518
+ has_media=bool(request.images or request.documents),
519
+ share_description=getattr(
520
+ self._image_cache, "_share_image_row_description", False
521
+ ),
522
+ )
523
+ record["_list_source_bounds"] = source_rows.list_bounds(
524
+ request.state,
525
+ request.fields,
526
+ has_images=bool(request.images or request.documents),
527
+ )
528
+ sources: tuple[ClairImage | ClairDocument, ...] = (
529
+ *request.images,
530
+ *request.documents,
531
+ )
532
+ source_key = ImageCache.key(sources) if sources else None
533
+ image_key = source_key
534
+ if image_key is not None:
535
+ image_key += (
536
+ ":identifier:" + image_identifier.VIEW_ID
537
+ if identifier_view
538
+ else ":default"
539
+ )
540
+ if image_view_key is not None:
541
+ image_key += ":view:" + image_view_key
542
+ prepared = self._image_cache.get(image_key) if image_key is not None else None
543
+ if sources and prepared is None:
544
+ images = (
545
+ list(image_views())
546
+ if image_views is not None
547
+ else [i.to_pil() for i in request.images]
548
+ )
549
+ original_images = list(images)
550
+ if self.FOCUS_SPARSE_IMAGES or pdf_spelling_view or po_detail_view:
551
+ focus = (
552
+ (
553
+ lambda image: image_focus.focus_document(
554
+ image,
555
+ max_pixels=identifier_spelling.MANY_IMAGE_MAX_PIXELS,
556
+ max_scale=3.0,
557
+ )
558
+ )
559
+ if po_detail_view
560
+ else image_focus.focus_document
561
+ )
562
+ unfocused_image = None
563
+ if (
564
+ type(self) is ClairicFlashModel
565
+ and identifier_view
566
+ and (len(request.images) == 1)
567
+ and (not request.documents)
568
+ ):
569
+ default = self._image_cache.entries.get(
570
+ cast(str, source_key) + ":default"
571
+ )
572
+ if (
573
+ default is not None
574
+ and len(default.images) == 1
575
+ and default.source_images
576
+ and (default.images[0] is default.source_images[0])
577
+ ):
578
+ unfocused_image = default.images[0]
579
+ if unfocused_image is None:
580
+ images = [focus(image) for image in images]
581
+ else:
582
+ images = [
583
+ image if image is unfocused_image else focus(image)
584
+ for image in images
585
+ ]
586
+ if image_views is None:
587
+ for document in request.documents:
588
+ pages = document.render(MAX_IMAGES - len(images))
589
+ images.extend(pages)
590
+ original_images.extend(pages)
591
+ media: cm.EncodedMedia | None = cm.encode_media(
592
+ self.tokenizer, images, self.processor
593
+ )
594
+ prepared = self._image_cache.put(
595
+ cast(str, image_key),
596
+ images,
597
+ cast(cm.EncodedMedia, media),
598
+ self.media_payload(
599
+ request,
600
+ cast(dict[str, Any], cast(cm.EncodedMedia, media).media),
601
+ source_digest=image_key,
602
+ feature_namespace=self._image_cache.namespace,
603
+ ),
604
+ source_images=original_images,
605
+ )
606
+ images = prepared.images if prepared else []
607
+ media = prepared.media if prepared else None
608
+ payload = prepared.payload if prepared else None
609
+ record["_media_payload"] = payload
610
+ record["_original_images"] = prepared.source_images if prepared else []
611
+ tasks = []
612
+ state_tasks = set()
613
+ eos = self.tokenizer.convert_tokens_to_ids(ar.EOS)
614
+ if images:
615
+ names = ar.names(record)
616
+ if names:
617
+ marker = "PARALLEL_AR_CONTENT_4A61DB"
618
+ messages = [
619
+ {
620
+ "role": "user",
621
+ "content": [{"type": "image", "image": i} for i in images]
622
+ + [{"type": "text", "text": marker}],
623
+ }
624
+ ]
625
+ template = self.processor.apply_chat_template(
626
+ messages,
627
+ tokenize=False,
628
+ add_generation_prompt=True,
629
+ enable_thinking=False,
630
+ )
631
+ (header, footer) = template.split(marker)
632
+ boundary = header.rfind("<|vision_end|>")
633
+ if boundary < 0:
634
+ raise ValueError(
635
+ "The image chat template is missing its vision terminator"
636
+ )
637
+ boundary += len("<|vision_end|>")
638
+ replacements = [
639
+ self.processor.replace_image_token(
640
+ cast(cm.EncodedMedia, media).media, i
641
+ )
642
+ for i in range(len(images))
643
+ ]
644
+ (prefix_text, _) = self.processor.get_text_with_replacements(
645
+ [header[:boundary]], replacements, [], []
646
+ )
647
+ prefix = self.tokenizer(prefix_text, add_special_tokens=False)[
648
+ "input_ids"
649
+ ][0]
650
+ source = self.tokenizer.encode(
651
+ request.state, add_special_tokens=False, split_special_tokens=True
652
+ )
653
+ scoped_media = {
654
+ name
655
+ for (name, spec) in original_request.fields.items()
656
+ if grounding.explicit_media_scope(spec)
657
+ }
658
+ tails = self.tokenizer(
659
+ [
660
+ header[boundary:]
661
+ + (
662
+ ar.MEDIA_EVIDENCE_INSTRUCTION + "\n\n"
663
+ if request.state and name in scoped_media
664
+ else ""
665
+ )
666
+ + ar.instruction(
667
+ record, name, compact_lists=self.COMPACT_LIST_PROMPTS
668
+ ).rstrip()
669
+ + (
670
+ (
671
+ "\n\nAccompanying text:\n"
672
+ if name in scoped_media
673
+ else "\n\nDocument:\n"
674
+ )
675
+ if request.state
676
+ else footer
677
+ )
678
+ for name in names
679
+ ],
680
+ add_special_tokens=False,
681
+ )["input_ids"]
682
+ if request.state:
683
+ footer_ids = self.tokenizer.encode(footer, add_special_tokens=False)
684
+ tails = [tail + source + footer_ids for tail in tails]
685
+ tasks = [
686
+ (name, prefix + tail, payload)
687
+ for (name, tail) in zip(names, tails, strict=True)
688
+ ]
689
+ state_tasks = {
690
+ name
691
+ for name in names
692
+ if name in state_only_fields
693
+ or grounding.state_only(record["fields"][name])
694
+ }
695
+ if state_tasks:
696
+ text_template = self.tokenizer.apply_chat_template(
697
+ [{"role": "user", "content": marker}],
698
+ tokenize=False,
699
+ add_generation_prompt=True,
700
+ enable_thinking=False,
701
+ )
702
+ (text_header, text_footer) = text_template.split(marker)
703
+ text_footer_ids = self.tokenizer.encode(
704
+ text_footer, add_special_tokens=False
705
+ )
706
+ tasks = [
707
+ (
708
+ name,
709
+ self.tokenizer.encode(
710
+ text_header
711
+ + ar.instruction(
712
+ record,
713
+ name,
714
+ compact_lists=self.COMPACT_LIST_PROMPTS,
715
+ )
716
+ + "\n\nDocument:\n",
717
+ add_special_tokens=False,
718
+ )
719
+ + source
720
+ + text_footer_ids,
721
+ None,
722
+ )
723
+ if name in state_tasks
724
+ else (name, ids, task_media)
725
+ for (name, ids, task_media) in tasks
726
+ ]
727
+ else:
728
+ marker = "PARALLEL_AR_CONTENT_4A61DB"
729
+ template = self.tokenizer.apply_chat_template(
730
+ [{"role": "user", "content": marker}],
731
+ tokenize=False,
732
+ add_generation_prompt=True,
733
+ enable_thinking=False,
734
+ )
735
+ (header, footer) = template.split(marker)
736
+ source = self.tokenizer.encode(
737
+ request.state, add_special_tokens=False, split_special_tokens=True
738
+ )
739
+ tail = self.tokenizer.encode(footer, add_special_tokens=False)
740
+ for name in ar.names(record):
741
+ ids = (
742
+ self.tokenizer.encode(
743
+ header
744
+ + ar.instruction(
745
+ record, name, compact_lists=self.COMPACT_LIST_PROMPTS
746
+ )
747
+ + "\n\nDocument:\n",
748
+ add_special_tokens=False,
749
+ )
750
+ + (
751
+ self.tokenizer.encode(
752
+ record["_source_row_inputs"][name],
753
+ add_special_tokens=False,
754
+ split_special_tokens=True,
755
+ )
756
+ if name in record["_source_row_inputs"]
757
+ else source
758
+ )
759
+ + tail
760
+ )
761
+ tasks.append((name, ids, None))
762
+ typed = typed_readout_record(
763
+ request, record, automatic_temporal=automatic_temporal, **expand_options
764
+ )
765
+ item = None
766
+ if typed:
767
+ item = cm.encode_record(
768
+ self.tokenizer,
769
+ typed,
770
+ self.settings.max_length,
771
+ media=media,
772
+ answer_slots=True,
773
+ text_answer_slots=True,
774
+ )
775
+ if item is None or item.text != record["input"]:
776
+ raise ValueError("Typed fields and input must fit one complete context")
777
+ if any((len(ids) > self.settings.max_length for (_, ids, _) in tasks)):
778
+ raise ValueError(
779
+ "AR input exceeds the model context; no input was truncated"
780
+ )
781
+ record["_ar_tasks"] = tasks
782
+ source = (
783
+ grounding.Source(request.state, normalize_whitespace=True)
784
+ if tasks and (not images or state_tasks)
785
+ else None
786
+ )
787
+ record["_ar_source"] = source if not images else None
788
+ record["_ar_sources"] = dict.fromkeys(state_tasks, source)
789
+ record["_ar_constraints"] = {
790
+ name: source.constraint(record["fields"][name])
791
+ if (source := record["_ar_sources"].get(name, record["_ar_source"]))
792
+ is not None
793
+ and grounding.applies(record["fields"][name], media)
794
+ else {"json_schema": json.dumps(ar.schema(record["fields"][name]))}
795
+ for (name, _, media) in tasks
796
+ }
797
+ record["_cache_salt"] = prepared.salt if prepared else uuid.uuid4().hex
798
+ if state_tasks:
799
+ record["_ar_task_salts"] = {name: uuid.uuid4().hex for name in state_tasks}
800
+ if len(tasks) > 1:
801
+ prefix = common_prefix(tasks)
802
+ if len(prefix) >= 128:
803
+ record["_ar_prefix"] = prefix
804
+ groups: dict[str, list[tuple[str, list[int], Any]]] = {}
805
+ annotations = record["_meta"]["extraction_contract"]["fields"]
806
+ for task in tasks:
807
+ parent = annotations.get(task[0], {}).get("parent")
808
+ if parent:
809
+ groups.setdefault(parent, []).append(task)
810
+ record["_ar_group_prefixes"] = [
811
+ common_prefix(group) for group in groups.values() if len(group) > 1
812
+ ]
813
+ encoded = (record, forecasts, tasks, item, eos)
814
+ detail_view = (
815
+ identifier_view
816
+ or party_name_view
817
+ or physical_row_view
818
+ or identifier_spelling_disabled
819
+ )
820
+ if self.BIND_IMAGE_TABLE_ROWS and (not detail_view):
821
+ encoded = image_table_rows.prepare(
822
+ request, encoded, self.encode, scale=self.IMAGE_TABLE_ROW_SCALE
823
+ )
824
+ if self.BIND_IMAGE_RAGGED_ROWS and (not detail_view):
825
+ encoded = image_ragged_rows.prepare(
826
+ request, encoded, self.encode, scale=self.IMAGE_TABLE_ROW_SCALE
827
+ )
828
+ if self.BIND_IMAGE_FINANCIAL_LINES and (not detail_view):
829
+ encoded = image_financial_lines.prepare(request, encoded, self.encode)
830
+ if self.FOCUS_IMAGE_IDENTIFIERS and (not detail_view):
831
+ prefix_overlap = getattr(self, "_invoice_prefix_overlap", None)
832
+ if prefix_overlap is not None:
833
+ prefix_overlap.start(original_request, encoded, eos)
834
+ unfocused_image = None
835
+ if (
836
+ type(self) is ClairicFlashModel
837
+ and self.FOCUS_SPARSE_IMAGES
838
+ and (len(request.images) == 1)
839
+ and (not request.documents)
840
+ and (prepared is not None)
841
+ and (len(prepared.images) == 1)
842
+ and prepared.source_images
843
+ and (prepared.images[0] is prepared.source_images[0])
844
+ ):
845
+ unfocused_image = prepared.images[0]
846
+ if unfocused_image is None:
847
+ encoded = image_identifier.prepare(
848
+ original_request, encoded, self.encode
849
+ )
850
+ else:
851
+ encoded = image_identifier.prepare(
852
+ original_request,
853
+ encoded,
854
+ self.encode,
855
+ unfocused_image=unfocused_image,
856
+ )
857
+ if self.FOCUS_IMAGE_PARTY_NAMES and (not detail_view):
858
+ encoded = self._party_name_tasks(original_request, encoded)
859
+ if not detail_view:
860
+ encoded = pdf_number_focus.prepare(
861
+ original_request, encoded, self.encode, enabled=self.FOCUS_SPARSE_IMAGES
862
+ )
863
+ encoded = identifier_spelling.prepare_pdf_tasks(
864
+ original_request, encoded, self.encode, enabled=True
865
+ )
866
+ encoded = identifier_spelling.prepare_many_image_tasks(
867
+ original_request, encoded, self.encode
868
+ )
869
+ encoded = identifier_spelling.prepare_fallback(
870
+ original_request, encoded, self.encode
871
+ )
872
+ record = encoded[0]
873
+ record["_first_item_list_gating"] = getattr(
874
+ self._image_cache, "_share_image_row_description", False
875
+ )
876
+ if record.get("_ar_task_salts"):
877
+ record["_ar_media_groups"] = media_warmup_groups(
878
+ record["_ar_tasks"],
879
+ default_salt=record["_cache_salt"],
880
+ task_salts=record["_ar_task_salts"],
881
+ annotations=record["_meta"]["extraction_contract"]["fields"],
882
+ )
883
+ return encoded
884
+
885
+ def _party_name_tasks(
886
+ self, request: PredictRequest, encoded: EncodedRequest
887
+ ) -> EncodedRequest:
888
+ selected = image_party_names.fields(request.fields)
889
+ if not selected or len(request.images) != 1 or request.documents:
890
+ return encoded
891
+ (record, forecasts, tasks, typed, eos) = encoded
892
+ originals = record.get("_original_images")
893
+ image = originals[0] if originals else request.images[0].to_pil()
894
+ views = image_party_names.views(image)
895
+ if len(views) == 1:
896
+ return encoded
897
+ fields = {
898
+ name: {
899
+ **request.fields[name],
900
+ "instructions": request.fields[name].get("instructions", "")
901
+ + image_party_names.VIEW_INSTRUCTION,
902
+ }
903
+ for name in selected
904
+ }
905
+ child_request = request.model_copy(update={"fields": fields})
906
+ (child, _, replacements, _, _) = self.encode(
907
+ child_request,
908
+ party_name_view=True,
909
+ image_views=lambda: views,
910
+ image_view_key=image_party_names.VIEW_ID,
911
+ )
912
+ by_name = {task[0]: task for task in replacements}
913
+ tasks = [by_name.get(task[0], task) for task in tasks]
914
+ salts = dict(record.get("_ar_task_salts", {}))
915
+ for name in selected:
916
+ record["fields"][name] = child["fields"][name]
917
+ record["_ar_constraints"][name] = child["_ar_constraints"][name]
918
+ salts[name] = child["_cache_salt"]
919
+ record.update(
920
+ _ar_tasks=tasks, _ar_task_salts=salts, _ar_prefix=[], _ar_group_prefixes=[]
921
+ )
922
+ return (record, forecasts, tasks, typed, eos)
923
+
924
+ @staticmethod
925
+ def media_payload(
926
+ request: PredictRequest,
927
+ encoded: dict[str, Any],
928
+ *,
929
+ source_digest: str | None = None,
930
+ feature_namespace: str = "",
931
+ ) -> list[dict[str, Any]]:
932
+ import torch
933
+
934
+ digest = source_digest or ImageCache.key((*request.images, *request.documents))
935
+ return [
936
+ {
937
+ "format": "processor_output",
938
+ "clair_media_digest": digest,
939
+ **{
940
+ key: encoded[key].to(torch.bfloat16)
941
+ if key == "pixel_values"
942
+ else encoded[key]
943
+ for key in cm.MEDIA_BATCH_KEYS
944
+ },
945
+ }
946
+ ]
947
+
948
+ async def _ar(
949
+ self, record: dict[str, Any], task: ARTask, eos: int
950
+ ) -> tuple[str, dict[str, Any]]:
951
+ if "_ar_future" not in record:
952
+ record["_ar_future"] = asyncio.create_task(self._ar_all(record, eos))
953
+ predictions = await record["_ar_future"]
954
+ return (task[0], predictions[task[0]])
955
+
956
+ async def _ar_all(
957
+ self, record: dict[str, Any], eos: int
958
+ ) -> dict[str, dict[str, Any]]:
959
+ tasks = record["_ar_tasks"]
960
+ salt = record["_cache_salt"]
961
+ row_gates = set(record.get("_source_row_gates", ()))
962
+ false_id = self.tokenizer.convert_tokens_to_ids("false") if row_gates else None
963
+ score_ids = [self.tokenizer.convert_tokens_to_ids("null")]
964
+ if false_id is not None:
965
+ score_ids.append(false_id)
966
+ results = await ordinary_list_completion.generate(
967
+ self.engine,
968
+ record,
969
+ tasks,
970
+ eos,
971
+ self.tokenizer,
972
+ initial_frontier=32
973
+ if type(self) is ClairicFlashModel
974
+ and self.settings.model_id == "clairic-flash"
975
+ and (self.max_concurrency == self.settings.max_concurrency == 1)
976
+ else 0,
977
+ next_frontier=64,
978
+ parse_result=scalar_result,
979
+ normalize=lambda record, predictions: printed_numbers.normalize_predictions(
980
+ record, printed_temporal.normalize_predictions(record, predictions)
981
+ ),
982
+ input_ids=[ids for (_, ids, _) in tasks],
983
+ image_data=batch_image_data([media for (_, _, media) in tasks]),
984
+ rid=["ar-" + uuid.uuid4().hex for _ in tasks],
985
+ cache_salt=[
986
+ record.get("_ar_task_salts", {}).get(name, salt)
987
+ for (name, _, _) in tasks
988
+ ],
989
+ return_logprob=True,
990
+ logprob_start_len=-1,
991
+ token_ids_logprob=score_ids,
992
+ sampling_params=[
993
+ {
994
+ "temperature": 0,
995
+ "max_new_tokens": image_rows.output_limit(
996
+ record, name, len(ids), self.settings.max_length
997
+ )
998
+ if image_rows.is_inventory(record["fields"][name])
999
+ else record.get("_ar_max_output_tokens", MAX_OUTPUT_TOKENS),
1000
+ "stop_token_ids": [eos],
1001
+ **(
1002
+ record["_ar_constraints"][name]
1003
+ if name in record.get("_ar_constraints", {})
1004
+ else {
1005
+ "json_schema": json.dumps(ar.schema(record["fields"][name]))
1006
+ }
1007
+ ),
1008
+ "skip_special_tokens": False,
1009
+ }
1010
+ for (name, ids, _) in tasks
1011
+ ],
1012
+ )
1013
+ if usage := record.get("_completed_generation_usage"):
1014
+ usage["tasks"].extend(tasks)
1015
+ usage["readings"].extend(
1016
+ (
1017
+ {
1018
+ "tokens": int(
1019
+ result.get("meta_info", {}).get("completion_tokens", 0)
1020
+ )
1021
+ }
1022
+ for result in results
1023
+ )
1024
+ )
1025
+ predictions = {
1026
+ name: batch_completion.unused_prediction(result)
1027
+ if result.get("_clair_unused_row_proposal")
1028
+ else scalar_result(
1029
+ result,
1030
+ record["fields"][name],
1031
+ self.tokenizer,
1032
+ record["input"],
1033
+ record.get("_ar_sources", {}).get(name, record.get("_ar_source"))
1034
+ if grounding.applies(record["fields"][name], media)
1035
+ else None,
1036
+ excluded_token_id=false_id if name in row_gates else None,
1037
+ provenance=record.get("_ar_sources", {}).get(
1038
+ name, record.get("_ar_source")
1039
+ )
1040
+ if media is None and (not record["fields"][name].get("knowledge"))
1041
+ else None,
1042
+ )
1043
+ for ((name, _, media), result) in zip(tasks, results, strict=True)
1044
+ }
1045
+ if any(
1046
+ (
1047
+ "confidence" not in prediction
1048
+ for prediction in predictions.values()
1049
+ if not prediction.get("_unused_row_proposal")
1050
+ )
1051
+ ):
1052
+ raise ClairInferenceError(
1053
+ "Transformers omitted generation log probabilities"
1054
+ )
1055
+ if any(
1056
+ (
1057
+ "p_null" not in prediction
1058
+ for prediction in predictions.values()
1059
+ if not prediction.get("_unused_row_proposal")
1060
+ )
1061
+ ):
1062
+ raise ClairInferenceError(
1063
+ "Transformers omitted null-token log probabilities"
1064
+ )
1065
+ if self.RECOVER_NULLS and (not record.get("_null_recovery")):
1066
+ fields = {
1067
+ name
1068
+ for (name, prediction) in predictions.items()
1069
+ if (
1070
+ prediction["valid"]
1071
+ and prediction["value"] is None
1072
+ or prediction.get("failure_reason") == "not_in_source"
1073
+ )
1074
+ and (not record["fields"][name].get("knowledge"))
1075
+ and (name not in record.get("_meta", {}).get("printed_temporal", {}))
1076
+ and (name not in record.get("_meta", {}).get("printed_numbers", {}))
1077
+ and (
1078
+ record["fields"][name]["type"] == "number"
1079
+ or (record["fields"][name]["type"] == "text" and record["input"])
1080
+ )
1081
+ and (
1082
+ not record["_meta"]["extraction_contract"]["fields"]
1083
+ .get(name, {})
1084
+ .get("parent")
1085
+ )
1086
+ }
1087
+ if fields:
1088
+ repair = await asyncio.get_running_loop().run_in_executor(
1089
+ self._encoder, self.null_recovery_record, record, fields
1090
+ )
1091
+ if repair["_ar_tasks"]:
1092
+ alternatives = await self._ar_all(repair, eos)
1093
+ retry_lengths = {
1094
+ name: len(ids) for (name, ids, _) in repair["_ar_tasks"]
1095
+ }
1096
+ for name, alternative in alternatives.items():
1097
+ original = predictions[name]
1098
+ tokens = original["tokens"] + alternative["tokens"]
1099
+ if (
1100
+ alternative["valid"]
1101
+ and alternative["value"] is not None
1102
+ and (
1103
+ alternative.get("grounding_method")
1104
+ in ("literal_source", "whitespace_normalized_source")
1105
+ or record["fields"][name]["type"] == "number"
1106
+ or (
1107
+ alternative.get("span") is not None
1108
+ and alternative.get("confidence", 0.0)
1109
+ > alternative.get("p_null", 1.0)
1110
+ )
1111
+ )
1112
+ ):
1113
+ predictions[name] = {**alternative, "null_recovered": True}
1114
+ predictions[name]["tokens"] = tokens
1115
+ predictions[name]["retry_input_tokens"] = retry_lengths[name]
1116
+ return predictions
1117
+
1118
+ def null_recovery_record(
1119
+ self, record: dict[str, Any], fields: Collection[str]
1120
+ ) -> dict[str, Any]:
1121
+ original = self.tokenizer.encode(
1122
+ ar.EXTRACTION_INSTRUCTION, add_special_tokens=False
1123
+ )
1124
+ tasks = []
1125
+ for name, ids, media in record["_ar_tasks"]:
1126
+ if name not in fields:
1127
+ continue
1128
+ source = record.get("_ar_sources", {}).get(name, record.get("_ar_source"))
1129
+ instruction = (
1130
+ ar.COMPUTATION_INSTRUCTION
1131
+ if source is not None
1132
+ else ar.RECOVERY_INSTRUCTION
1133
+ )
1134
+ replacement = self.tokenizer.encode(instruction, add_special_tokens=False)
1135
+ matches = [
1136
+ i
1137
+ for (i, token) in enumerate(ids)
1138
+ if token == original[0] and ids[i : i + len(original)] == original
1139
+ ]
1140
+ if len(matches) != 1:
1141
+ continue
1142
+ start = matches[0]
1143
+ prompt = ids[:start] + replacement + ids[start + len(original) :]
1144
+ if len(prompt) <= self.settings.max_length:
1145
+ tasks.append((name, prompt, media))
1146
+ return {
1147
+ **record,
1148
+ "_ar_tasks": tasks,
1149
+ "_ar_prefix": None,
1150
+ "_ar_group_prefixes": [],
1151
+ "_ar_media_groups": [],
1152
+ "_null_recovery": True,
1153
+ }
1154
+
1155
+ async def _typed(
1156
+ self,
1157
+ request: PredictRequest,
1158
+ item: cm.EncodedRecord,
1159
+ media: list[dict[str, Any]] | None = None,
1160
+ ) -> dict[str, dict[str, Any]]:
1161
+ if (request.images or request.documents) and media is None:
1162
+ media = self.media_payload(request, cast(dict[str, Any], item.media))
1163
+ return await self.engine.read_typed(item, media)
1164
+
1165
+ def _encode_receipt_repairs(
1166
+ self,
1167
+ request: PredictRequest,
1168
+ record: dict[str, Any],
1169
+ predictions: dict[str, dict[str, Any]],
1170
+ ) -> list[tuple[str, dict[str, Any], dict[str, Any]]]:
1171
+ prepared = []
1172
+ value: Any
1173
+ p_null: Any
1174
+ source = {**record, "input": request.state, "fields": request.fields}
1175
+ for name in record.get("_receipt_sum_fields", ()):
1176
+ previous = predictions.get(name, {})
1177
+ (value, p_null) = (previous.get("value"), previous.get("p_null"))
1178
+ if (
1179
+ type(value) not in (int, float)
1180
+ or not math.isfinite(value)
1181
+ or previous.get("decoder") != ar.VERSION
1182
+ or (type(p_null) not in (int, float))
1183
+ or (not 0 <= p_null <= 1)
1184
+ ):
1185
+ continue
1186
+ packet = receipt_totals.prepare_task(source, name)
1187
+ if packet is None:
1188
+ continue
1189
+ tasks = []
1190
+ for task in packet["tasks"]:
1191
+ rendered = self.tokenizer.apply_chat_template(
1192
+ [{"role": "user", "content": task["prompt"]}],
1193
+ tokenize=False,
1194
+ add_generation_prompt=True,
1195
+ enable_thinking=False,
1196
+ )
1197
+ ids = self.tokenizer.encode(rendered, add_special_tokens=False)
1198
+ if not ids or len(ids) > self.settings.max_length:
1199
+ raise ValueError(
1200
+ "Receipt selector exceeds the model context; no input was truncated"
1201
+ )
1202
+ tasks.append((task["occurrence_id"], ids, None))
1203
+ auxiliary = {
1204
+ "input": request.state,
1205
+ "fields": {
1206
+ key: {"type": "boolean", "nullable": True} for (key, _, _) in tasks
1207
+ },
1208
+ "_ar_tasks": tasks,
1209
+ "_ar_constraints": {
1210
+ task["occurrence_id"]: task["grammar"] for task in packet["tasks"]
1211
+ },
1212
+ "_ar_prefix": common_prefix(tasks),
1213
+ "_cache_salt": uuid.uuid4().hex,
1214
+ "_null_recovery": True,
1215
+ "_ar_max_output_tokens": 8,
1216
+ "_meta": {"extraction_contract": {"fields": {}}},
1217
+ }
1218
+ prepared.append((name, packet, auxiliary))
1219
+ return prepared
1220
+
1221
+ async def _complete_receipt_sums(
1222
+ self,
1223
+ request: PredictRequest,
1224
+ record: dict[str, Any],
1225
+ predictions: dict[str, dict[str, Any]],
1226
+ eos: int,
1227
+ progress: dict[str, list[Any]] | None = None,
1228
+ ) -> tuple[
1229
+ dict[str, dict[str, Any]],
1230
+ list[tuple[str, list[int], Any]],
1231
+ list[dict[str, Any]],
1232
+ ]:
1233
+ if progress is None:
1234
+ progress = {"encodings": [], "tasks": [], "readings": []}
1235
+ encoding = asyncio.get_running_loop().run_in_executor(
1236
+ self._encoder, self._encode_receipt_repairs, request, record, predictions
1237
+ )
1238
+ progress["encodings"].append(encoding)
1239
+ prepared = await asyncio.shield(encoding)
1240
+ updates = {}
1241
+ for name, packet, auxiliary in prepared:
1242
+ decisions = {}
1243
+ tasks = auxiliary["_ar_tasks"]
1244
+ for start in range(0, len(tasks), 32):
1245
+ batch = {
1246
+ **auxiliary,
1247
+ "_ar_tasks": tasks[start : start + 32],
1248
+ "_ar_prefix": auxiliary["_ar_prefix"] if start == 0 else None,
1249
+ "_completed_generation_usage": progress,
1250
+ }
1251
+ completed = len(progress["tasks"])
1252
+ results = await self._ar_all(batch, eos)
1253
+ if len(progress["tasks"]) == completed:
1254
+ progress["tasks"].extend(batch["_ar_tasks"])
1255
+ progress["readings"].extend(results.values())
1256
+ decisions.update(
1257
+ {
1258
+ key: {**answer, "raw_json": answer["raw"]}
1259
+ for (key, answer) in results.items()
1260
+ }
1261
+ )
1262
+ checked = receipt_totals.validate_result(packet, decisions)
1263
+ if (
1264
+ not checked["valid"]
1265
+ or checked["value"] is None
1266
+ or (not checked.get("selection_scores"))
1267
+ or (checked["value"] == predictions[name]["value"])
1268
+ ):
1269
+ continue
1270
+ updates[name] = {
1271
+ "value": checked["value"],
1272
+ "valid": True,
1273
+ "complete": True,
1274
+ "decoder": "source_receipt_block_sum_v1",
1275
+ "span": None,
1276
+ "raw": checked["decimal_sum"],
1277
+ **checked["selection_scores"],
1278
+ "p_null": predictions[name]["p_null"],
1279
+ "p_null_method": "primary_numeric_ar_first_token_null_probability",
1280
+ "source_receipt_operands": [
1281
+ {key: item[key] for key in ("span", "printed")}
1282
+ for item in checked["operands"]
1283
+ ],
1284
+ "tokens": sum((answer["tokens"] for answer in decisions.values())),
1285
+ }
1286
+ return (updates, progress["tasks"], progress["readings"])
1287
+
1288
+ def _encode_request(self, request: PredictRequest) -> EncodedRequest:
1289
+ source: Any
1290
+ previous = self._image_cache
1291
+ cache = ImageCache(
1292
+ max_bytes=previous.max_bytes, max_entries=previous.max_entries
1293
+ )
1294
+ cache._share_image_row_description = (
1295
+ type(self) is ClairicFlashModel
1296
+ and len(getattr(request, "images", ())) == 1
1297
+ and (not getattr(request, "documents", ()))
1298
+ )
1299
+ self._image_cache = cache
1300
+ try:
1301
+ encoded = self.encode(request)
1302
+ fields = {
1303
+ name: spec
1304
+ for (name, spec) in getattr(request, "fields", {}).items()
1305
+ if source_dates.eligible(spec)
1306
+ }
1307
+ if fields and (not request.images) and (not request.documents):
1308
+ record = encoded[0]
1309
+ fields = {
1310
+ name: spec
1311
+ for (name, spec) in fields.items()
1312
+ if name not in record.get("_meta", {}).get("printed_temporal", {})
1313
+ }
1314
+ source = source_dates.DateSource(request.state)
1315
+ names = [name for (name, spec) in fields.items() if source.allows(spec)]
1316
+ if names:
1317
+ internal_fields = {
1318
+ name: {
1319
+ "type": "text",
1320
+ "nullable": fields[name].get("nullable", True),
1321
+ "instructions": source_dates.INSTRUCTION
1322
+ + "\n"
1323
+ + fields[name].get("instructions", ""),
1324
+ }
1325
+ for name in names
1326
+ }
1327
+ internal = request.model_copy(update={"fields": internal_fields})
1328
+ try:
1329
+ (dated, _, _, _, date_eos) = self.encode(internal)
1330
+ except ValueError:
1331
+ return encoded
1332
+ dated["_ar_constraints"].update(
1333
+ {
1334
+ name: source.constraint(
1335
+ nullable=internal_fields[name]["nullable"]
1336
+ )
1337
+ for name in names
1338
+ }
1339
+ )
1340
+ dated.update(
1341
+ _ar_source=source,
1342
+ _ar_sources=dict.fromkeys(names, source),
1343
+ _null_recovery=True,
1344
+ )
1345
+ record["_date_supplement"] = (dated, source, names, date_eos)
1346
+ if (
1347
+ type(self) is ClairicFlashModel
1348
+ and (not getattr(request, "images", ()))
1349
+ and (not getattr(request, "documents", ()))
1350
+ ):
1351
+ source = {
1352
+ "input": getattr(request, "state", ""),
1353
+ "fields": getattr(request, "fields", {}),
1354
+ }
1355
+ names = [
1356
+ name
1357
+ for name in source["fields"]
1358
+ if receipt_totals.eligible(source, name)
1359
+ ]
1360
+ if names:
1361
+ encoded[0]["_receipt_sum_fields"] = names
1362
+ return encoded
1363
+ finally:
1364
+ cache.clear()
1365
+ cache._share_image_row_description = False
1366
+
1367
+ async def predict_async(self, request: PredictRequest) -> PredictOutput:
1368
+ if self._in_flight >= self.max_concurrency:
1369
+ raise ClairQueueFull("Clairic inference queue is full")
1370
+ self._in_flight += 1
1371
+ loop = asyncio.get_running_loop()
1372
+ deadline = loop.time() + self.REQUEST_TIMEOUT_SECONDS
1373
+ encoding: asyncio.Future[EncodedRequest] | None = None
1374
+ work: list[asyncio.Task[Any]] = []
1375
+ auxiliary: asyncio.Task[Any]
1376
+ receipt_progress: dict[str, list[Any]] = {
1377
+ "encodings": [],
1378
+ "tasks": [],
1379
+ "readings": [],
1380
+ }
1381
+ try:
1382
+ self.engine.begin_request()
1383
+ try:
1384
+ encoding = loop.run_in_executor(
1385
+ self._encoder, self._encode_request, request
1386
+ )
1387
+ (record, forecasts, tasks, item, eos) = await asyncio.wait_for(
1388
+ asyncio.shield(encoding), timeout=max(0, deadline - loop.time())
1389
+ )
1390
+ except ValueError as error:
1391
+ raise ClairRequestError(str(error)) from error
1392
+ work = [asyncio.create_task(self._ar(record, task, eos)) for task in tasks]
1393
+ if item is not None:
1394
+ work.append(
1395
+ asyncio.create_task(
1396
+ self._typed(request, item, record.get("_media_payload"))
1397
+ )
1398
+ )
1399
+ outputs: list[Any] = await asyncio.wait_for(
1400
+ asyncio.gather(*work), timeout=max(0, deadline - loop.time())
1401
+ )
1402
+ predictions: dict[str, dict[str, Any]] = (
1403
+ outputs[-1] if item is not None else {}
1404
+ )
1405
+ for name, value in outputs[: len(tasks)]:
1406
+ predictions[name] = value
1407
+ predictions = printed_temporal.normalize_predictions(record, predictions)
1408
+ predictions = printed_numbers.normalize_predictions(record, predictions)
1409
+ predictions = identifier_spelling.normalize_predictions(record, predictions)
1410
+ fallback = identifier_spelling.fallback_record(record, predictions)
1411
+ identifier_fallback_results = {}
1412
+ if fallback is not None:
1413
+ identifier_fallback_results = await asyncio.wait_for(
1414
+ self._ar_all(fallback, eos), timeout=max(0, deadline - loop.time())
1415
+ )
1416
+ predictions = identifier_spelling.merge_fallback(
1417
+ predictions, identifier_fallback_results, fallback
1418
+ )
1419
+ date_results = {}
1420
+ date_tasks = []
1421
+ if supplement := record.get("_date_supplement"):
1422
+ (dated, source, names, date_eos) = supplement
1423
+ names = [
1424
+ name
1425
+ for name in names
1426
+ if isinstance(predictions.get(name, {}).get("value"), str)
1427
+ and predictions[name]["value"] not in source.support
1428
+ ]
1429
+ if supplement and names:
1430
+ date_tasks = dated["_ar_tasks"]
1431
+ auxiliary = asyncio.create_task(self._ar_all(dated, date_eos))
1432
+ work.append(auxiliary)
1433
+ try:
1434
+ date_results = await asyncio.wait_for(
1435
+ auxiliary,
1436
+ timeout=max(
1437
+ 0,
1438
+ min(
1439
+ self.DATE_SUPPLEMENT_TIMEOUT_SECONDS,
1440
+ deadline - loop.time(),
1441
+ ),
1442
+ ),
1443
+ )
1444
+ date_results = source.annotate_predictions(date_results, names)
1445
+ predictions = source.merge_predictions(
1446
+ predictions, date_results, names
1447
+ )
1448
+ except Exception:
1449
+ (date_results, date_tasks) = ({}, [])
1450
+ receipt_tasks: list[ARTask]
1451
+ receipt_readings: list[dict[str, Any]]
1452
+ (receipt_tasks, receipt_readings) = ([], [])
1453
+ if record.get("_receipt_sum_fields"):
1454
+ auxiliary = asyncio.create_task(
1455
+ self._complete_receipt_sums(
1456
+ request, record, predictions, eos, receipt_progress
1457
+ )
1458
+ )
1459
+ work.append(auxiliary)
1460
+ try:
1461
+ (updates, receipt_tasks, receipt_readings) = await asyncio.wait_for(
1462
+ auxiliary,
1463
+ timeout=max(
1464
+ 0,
1465
+ min(
1466
+ self.RECEIPT_SUPPLEMENT_TIMEOUT_SECONDS,
1467
+ deadline - loop.time(),
1468
+ ),
1469
+ ),
1470
+ )
1471
+ predictions = {**predictions, **updates}
1472
+ except Exception:
1473
+ pass
1474
+ (receipt_tasks, receipt_readings) = (
1475
+ receipt_progress["tasks"],
1476
+ receipt_progress["readings"],
1477
+ )
1478
+ predictions = source_rows.bounded_predictions(
1479
+ predictions,
1480
+ record["fields"],
1481
+ record.get("_list_source_bounds", {}),
1482
+ zs.list_item_name,
1483
+ )
1484
+ merged = zs.assemble_list_predictions(record, predictions)
1485
+ merged.update(image_rows.assemble(record, predictions))
1486
+ merged.update(image_table_rows.assemble(record, predictions))
1487
+ merged.update(image_ragged_rows.assemble(record, predictions))
1488
+ merged.update(image_financial_lines.assemble(record, predictions))
1489
+ annotations = record["_meta"]["extraction_contract"]["fields"]
1490
+ for name, annotation in annotations.items():
1491
+ if annotation.get("source_fields"):
1492
+ merged[name] = table_rows.assemble(
1493
+ predictions,
1494
+ annotation["source_rows"],
1495
+ annotation["source_fields"],
1496
+ eligibility=annotation.get("source_row_eligibility", False),
1497
+ )
1498
+ truncated = any(
1499
+ (
1500
+ not predictions[n].get("valid", False)
1501
+ for (n, _, _) in tasks
1502
+ if not annotations.get(n, {}).get("parent")
1503
+ )
1504
+ )
1505
+ truncated |= any(
1506
+ (
1507
+ not merged[name]["valid"] or not merged[name]["complete"]
1508
+ for name in record.get("_financial_line_plans", {})
1509
+ )
1510
+ )
1511
+ for name, annotation in record["_meta"]["extraction_contract"][
1512
+ "fields"
1513
+ ].items():
1514
+ if annotation.get("source_fields"):
1515
+ truncated |= not merged[name]["complete"]
1516
+ if (
1517
+ annotation.get("image_row_fields")
1518
+ or annotation.get("geometric_row_fields")
1519
+ or annotation.get("ragged_row_fields")
1520
+ ):
1521
+ truncated |= (
1522
+ not merged[name]["valid"] or not merged[name]["complete"]
1523
+ )
1524
+ queries = annotation.get("query_fields")
1525
+ if queries:
1526
+ used = []
1527
+ for child in queries:
1528
+ used.append(predictions[child])
1529
+ if predictions[child]["value"] is None:
1530
+ break
1531
+ valid = all((child.get("valid", True) for child in used))
1532
+ complete = (
1533
+ valid
1534
+ and used[-1]["value"] is None
1535
+ and used[-1].get("complete", True)
1536
+ )
1537
+ merged[name].update(valid=valid, complete=complete)
1538
+ merged[name].update(
1539
+ p_null=used[0]["p_null"],
1540
+ p_null_method="first_item_null_probability",
1541
+ p_nulls=[
1542
+ child["p_null"]
1543
+ for child in used
1544
+ if child["value"] is not None
1545
+ ],
1546
+ )
1547
+ if all((child.get("decoder") == ar.VERSION for child in used)):
1548
+ merged[name]["confidence"] = 0.0
1549
+ if all(("log_probability" in child for child in used)):
1550
+ log_probability = sum(
1551
+ (child["log_probability"] for child in used)
1552
+ )
1553
+ merged[name].update(
1554
+ confidence=math.exp(min(0.0, log_probability))
1555
+ if complete
1556
+ else 0.0,
1557
+ log_probability=log_probability,
1558
+ confidence_method="ar_sequence_probability_with_structural_end"
1559
+ if any(
1560
+ (
1561
+ child.get("grounding_method")
1562
+ == "source_row_bound"
1563
+ for child in used
1564
+ )
1565
+ )
1566
+ else "ar_sequence_probability",
1567
+ )
1568
+ merged[name]["spans"] = [
1569
+ child.get("span")
1570
+ for child in used
1571
+ if child["value"] is not None
1572
+ ]
1573
+ truncated |= not complete
1574
+ merged = cm.merge_forecasts(merged, forecasts) if forecasts else merged
1575
+ answers = {
1576
+ name: {"type": spec["type"], **merged[name]}
1577
+ for (name, spec) in request.fields.items()
1578
+ }
1579
+ state_tokens = len(
1580
+ self.tokenizer.encode(request.state, add_special_tokens=False)
1581
+ )
1582
+ input_tokens = sum((len(ids) for (_, ids, _) in tasks)) + (
1583
+ len(item.input_ids) if item is not None else 0
1584
+ )
1585
+ input_tokens += sum(
1586
+ (v.get("retry_input_tokens", 0) for (_, v) in outputs[: len(tasks)])
1587
+ )
1588
+ input_tokens += sum(
1589
+ (
1590
+ v.get("retry_input_tokens", 0)
1591
+ - v["identifier_spelling_attempt"].get("retry_input_tokens", 0)
1592
+ for v in predictions.values()
1593
+ if v.get("identifier_spelling_fallback")
1594
+ )
1595
+ )
1596
+ input_tokens += sum((len(ids) for (_, ids, _) in date_tasks))
1597
+ input_tokens += sum((len(ids) for (_, ids, _) in receipt_tasks))
1598
+ unexecuted = record.get("_unexecuted_list_items", {})
1599
+ input_tokens -= sum(unexecuted.values())
1600
+ input_work = (
1601
+ len(tasks)
1602
+ + (item is not None)
1603
+ - len(unexecuted)
1604
+ + len(identifier_fallback_results)
1605
+ + len(date_tasks)
1606
+ + len(receipt_tasks)
1607
+ )
1608
+ image_id: Any = getattr(self.processor, "image_token_id", None)
1609
+ image_tokens = (
1610
+ tasks[0][1].count(image_id)
1611
+ if record.get("_media_payload") and tasks
1612
+ else list(item.input_ids).count(image_id)
1613
+ if record.get("_media_payload") and item is not None
1614
+ else 0
1615
+ )
1616
+ return PredictOutput(
1617
+ answers=answers,
1618
+ truncated=truncated,
1619
+ state_tokens=state_tokens,
1620
+ image_tokens=image_tokens,
1621
+ schema_tokens=max(
1622
+ 0, input_tokens - (state_tokens + image_tokens) * input_work
1623
+ ),
1624
+ input_tokens=input_tokens,
1625
+ output_tokens=sum((v["tokens"] for (_, v) in outputs[: len(tasks)]))
1626
+ + sum((v["tokens"] for v in identifier_fallback_results.values()))
1627
+ + sum((v["tokens"] for v in date_results.values()))
1628
+ + sum((v["tokens"] for v in receipt_readings)),
1629
+ passes=max(
1630
+ [1]
1631
+ + [v["tokens"] for (_, v) in outputs[: len(tasks)]]
1632
+ + [
1633
+ predictions[name]["tokens"]
1634
+ for name in identifier_fallback_results
1635
+ ]
1636
+ + [v["tokens"] for v in date_results.values()]
1637
+ + [v["tokens"] for v in receipt_readings]
1638
+ ),
1639
+ state_text=request.state,
1640
+ )
1641
+ except (ClairRequestError, ClairQueueFull):
1642
+ raise
1643
+ except Exception as error:
1644
+ raise ClairInferenceError(
1645
+ "Clairic Transformers inference failed"
1646
+ ) from error
1647
+ finally:
1648
+ await asyncio.shield(
1649
+ asyncio.create_task(
1650
+ self._release_request(work, encoding, receipt_progress["encodings"])
1651
+ )
1652
+ )
1653
+
1654
+ async def _release_request(
1655
+ self,
1656
+ work: Sequence[asyncio.Task[Any]],
1657
+ encoding: asyncio.Future[Any] | None,
1658
+ extra_encodings: Sequence[asyncio.Future[Any]] = (),
1659
+ ) -> None:
1660
+ for task in work:
1661
+ if not task.done():
1662
+ task.cancel()
1663
+ if work:
1664
+ await asyncio.gather(*work, return_exceptions=True)
1665
+ await self.engine.end_request()
1666
+ if extra_encodings:
1667
+ encoding = asyncio.gather(
1668
+ *([encoding] if encoding is not None else []),
1669
+ *extra_encodings,
1670
+ return_exceptions=True,
1671
+ )
1672
+ if encoding is not None and (not encoding.done()):
1673
+ encoding.add_done_callback(self._release_encoding)
1674
+ else:
1675
+ self._in_flight -= 1
1676
+
1677
+ def _release_encoding(self, future: asyncio.Future[Any]) -> None:
1678
+ if not future.cancelled():
1679
+ future.exception()
1680
+ self._in_flight -= 1
1681
+
1682
+ def shutdown(self) -> None:
1683
+ self._encoder.shutdown(wait=False, cancel_futures=True)
1684
+ self.engine.shutdown()
1685
+
1686
+ @classmethod
1687
+ def load(
1688
+ cls,
1689
+ settings: RuntimeSettings,
1690
+ *,
1691
+ device: str = "cuda",
1692
+ dtype: Any = None,
1693
+ **model_kwargs: Any,
1694
+ ) -> ClairicFlashModel:
1695
+ from transformers import AutoProcessor, AutoTokenizer
1696
+ from .native import TransformersEngine
1697
+
1698
+ path = Path(settings.model_path)
1699
+ tokenizer = AutoTokenizer.from_pretrained(path, local_files_only=True)
1700
+ validate_eos(path, tokenizer)
1701
+ for token in ("null", "false"):
1702
+ if tokenizer.encode(token, add_special_tokens=False) != [
1703
+ tokenizer.convert_tokens_to_ids(token)
1704
+ ]:
1705
+ raise ValueError(f"{token} must be one token for confidence scoring")
1706
+ processor = AutoProcessor.from_pretrained(path, local_files_only=True)
1707
+ processor.tokenizer = tokenizer
1708
+ cm.configure_image_processor(processor, 1600000)
1709
+ if getattr(processor, "image_token_id", None) is None:
1710
+ processor.image_token_id = tokenizer.convert_tokens_to_ids(
1711
+ processor.image_token
1712
+ )
1713
+ engine = TransformersEngine.load(
1714
+ path, tokenizer, device=device, dtype=dtype, **model_kwargs
1715
+ )
1716
+ return cls(
1717
+ engine,
1718
+ tokenizer,
1719
+ processor,
1720
+ settings,
1721
+ json.loads((path / "clair_head_config.json").read_text()),
1722
+ )
clairic_runtime/batch_completion.py ADDED
@@ -0,0 +1,449 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ from collections.abc import Callable
3
+ from typing import TYPE_CHECKING, Any, cast
4
+
5
+ if TYPE_CHECKING:
6
+ from types import ModuleType
7
+ from . import ar, image_rows, schema
8
+
9
+
10
+ def unused_prediction(result: dict[str, Any]) -> dict[str, Any]:
11
+ return {
12
+ "value": None,
13
+ "valid": False,
14
+ "complete": False,
15
+ "tokens": int(result.get("meta_info", {}).get("completion_tokens", 0)),
16
+ "_unused_row_proposal": True,
17
+ }
18
+
19
+
20
+ def _empty_inventory(result: dict[str, Any], eos: int, tokenizer: Any) -> bool:
21
+ finish = result.get("meta_info", {}).get("finish_reason", {}) or {}
22
+ if finish.get("type") != "stop" or finish.get("matched") != eos:
23
+ return False
24
+ ids = result.get("output_ids")
25
+ if ids is not None:
26
+ ids = ids[:-1] if ids and ids[-1] == eos else ids
27
+ text = tokenizer.decode(
28
+ ids, skip_special_tokens=False, clean_up_tokenization_spaces=False
29
+ )
30
+ else:
31
+ text = result.get("text", "").removesuffix(ar.EOS)
32
+ return text.strip() == "null"
33
+
34
+
35
+ async def _generate(
36
+ engine: Any,
37
+ record: dict[str, Any],
38
+ tasks: list[tuple[str, list[int], Any]],
39
+ eos: int,
40
+ tokenizer: Any,
41
+ **kwargs: Any,
42
+ ) -> list[dict[str, Any]]:
43
+ return await engine.async_generate(**kwargs)
44
+
45
+
46
+ _BATCHED_KEYS = {"input_ids", "image_data", "rid", "cache_salt", "sampling_params"}
47
+ _SHARED_KEYS = {"return_logprob", "logprob_start_len", "token_ids_logprob"}
48
+
49
+
50
+ def _select_kwargs(
51
+ kwargs: dict[str, Any], indices: list[int], size: int
52
+ ) -> dict[str, Any]:
53
+ if set(kwargs) - _BATCHED_KEYS - _SHARED_KEYS:
54
+ raise ValueError("Unknown native argument for first-item scheduling")
55
+ result = {}
56
+ for key, value in kwargs.items():
57
+ if key in _BATCHED_KEYS and isinstance(value, list):
58
+ if len(value) != size:
59
+ raise ValueError("Native batch argument cardinality differs: " + key)
60
+ result[key] = [value[index] for index in indices]
61
+ else:
62
+ result[key] = value
63
+ return result
64
+
65
+
66
+ def _ordinary_lists(
67
+ record: dict[str, Any],
68
+ tasks: list[tuple[str, list[int], Any]],
69
+ item_name: Callable[[str, int], str],
70
+ ) -> dict[str, tuple[int, ...]]:
71
+ if record.get("_null_recovery"):
72
+ return {}
73
+ fields = record["fields"]
74
+ annotations = (
75
+ record.get("_meta", {}).get("extraction_contract", {}).get("fields", {})
76
+ )
77
+ names = [name for (name, _, _) in tasks]
78
+ if len(set(names)) != len(names):
79
+ raise ValueError("AR task names must be distinct")
80
+ indices = {name: index for (index, name) in enumerate(names)}
81
+ (claimed, groups) = (set(), {})
82
+ forbidden = {"_physical_row_scope", "_image_row_inventory", "_image_row_proposal"}
83
+ plans = (
84
+ record.get("_financial_line_plans", {}),
85
+ record.get("_list_source_bounds", {}),
86
+ )
87
+ for parent, annotation in annotations.items():
88
+ spec = fields.get(parent, {})
89
+ queries = annotation.get("query_fields")
90
+ item = spec.get("items")
91
+ kind = item.get("type") if isinstance(item, dict) else item
92
+ if (
93
+ spec.get("type") != "list"
94
+ or kind not in ("text", "number", "date")
95
+ or spec.get("knowledge")
96
+ or (set(annotation) != {"query_fields"})
97
+ or (not isinstance(queries, list))
98
+ or (len(queries) < 2)
99
+ or any((spec.get(key) for key in forbidden))
100
+ or (parent in indices)
101
+ or any((parent in plan for plan in plans))
102
+ ):
103
+ continue
104
+ valid = True
105
+ for ordinal, name in enumerate(queries, 1):
106
+ child = fields.get(name, {})
107
+ ownership = annotations.get(name, {})
108
+ if (
109
+ name != item_name(parent, ordinal)
110
+ or name not in indices
111
+ or name in claimed
112
+ or (ownership != {"parent": parent, "index": ordinal})
113
+ or (child.get("type") not in ("text", "number", "date"))
114
+ or (child.get("nullable", True) is not True)
115
+ or any((child.get(key) for key in forbidden))
116
+ or (name in record.get("_source_row_gates", ()))
117
+ ):
118
+ valid = False
119
+ break
120
+ if "enum" in child and None not in child["enum"]:
121
+ valid = False
122
+ break
123
+ if valid:
124
+ groups[parent] = tuple((indices[name] for name in queries))
125
+ claimed.update(queries)
126
+ return groups
127
+
128
+
129
+ def _completed_null(result: dict[str, Any], eos: int, tokenizer: Any) -> bool:
130
+ meta = result.get("meta_info", {})
131
+ finish = meta.get("finish_reason", {}) or {}
132
+ ids = result.get("output_ids")
133
+ if (
134
+ finish.get("type") != "stop"
135
+ or finish.get("matched") != eos
136
+ or (not isinstance(ids, list))
137
+ or (not ids)
138
+ or (ids[-1] != eos)
139
+ or (meta.get("completion_tokens") != len(ids))
140
+ ):
141
+ return False
142
+ return (
143
+ tokenizer.decode(
144
+ ids[:-1], skip_special_tokens=False, clean_up_tokenization_spaces=False
145
+ ).strip()
146
+ == "null"
147
+ )
148
+
149
+
150
+ def _row_cohorts(
151
+ record: dict[str, Any],
152
+ tasks: list[tuple[str, list[int], Any]],
153
+ item_name: Callable[[str, int], str],
154
+ ) -> dict[str, dict[str, Any]]:
155
+ fields = record["fields"]
156
+ annotations = (
157
+ record.get("_meta", {}).get("extraction_contract", {}).get("fields", {})
158
+ )
159
+ indices = {name: index for (index, (name, _, _)) in enumerate(tasks)}
160
+ result = {}
161
+ for parent, annotation in annotations.items():
162
+ (queries, spec) = (annotation.get("image_row_fields"), fields.get(parent, {}))
163
+ if (
164
+ set(annotation) != {"image_row_fields"}
165
+ or not spec.get("_image_row_inventory")
166
+ or parent not in indices
167
+ or (not isinstance(queries, list))
168
+ or (len(queries) <= 8)
169
+ or (parent in record.get("_list_source_bounds", {}))
170
+ or (parent in record.get("_financial_line_plans", {}))
171
+ or (not isinstance(spec.get("items"), dict))
172
+ or (spec["items"].get("type") != "object")
173
+ ):
174
+ continue
175
+ text_keys = [
176
+ key
177
+ for (key, child) in spec["items"].get("properties", {}).items()
178
+ if child.get("type") == "text"
179
+ ]
180
+ if not text_keys:
181
+ continue
182
+ if any(
183
+ (
184
+ name != item_name(parent, ordinal)
185
+ or name not in indices
186
+ or annotations.get(name) != {"parent": parent, "index": ordinal}
187
+ or (fields.get(name, {}).get("type") != "object")
188
+ or (not fields[name].get("_image_row_proposal"))
189
+ for (ordinal, name) in enumerate(queries, 1)
190
+ )
191
+ ):
192
+ continue
193
+ result[parent] = {
194
+ "inventory": indices[parent],
195
+ "proposals": tuple((indices[name] for name in queries)),
196
+ "text_keys": text_keys,
197
+ }
198
+ return result
199
+
200
+
201
+ def _cohort_proof(
202
+ record: dict[str, Any],
203
+ tasks: list[tuple[str, list[int], Any]],
204
+ results: list[dict[str, Any]],
205
+ parent: str,
206
+ cohort: dict[str, Any],
207
+ tokenizer: Any,
208
+ scalar_result: Callable[..., dict[str, Any]],
209
+ image_rows: ModuleType,
210
+ normalize: Callable[
211
+ [dict[str, Any], dict[str, dict[str, Any]]], dict[str, dict[str, Any]]
212
+ ],
213
+ ) -> dict[str, Any] | None:
214
+ spec = record["fields"][parent]
215
+ native = results[cohort["inventory"]]
216
+ inventory = scalar_result(native, spec, tokenizer, record.get("input", ""), None)
217
+ if not inventory.get("valid") or not inventory.get("complete"):
218
+ return None
219
+ value = inventory.get("value")
220
+ if value is not None and (
221
+ not isinstance(value, list)
222
+ or any(
223
+ (
224
+ not isinstance(row, dict)
225
+ or set(row) != {"label"}
226
+ or (not isinstance(row["label"], str))
227
+ for row in value
228
+ )
229
+ )
230
+ ):
231
+ return None
232
+ labels = [row["label"] for row in value or []]
233
+ if len(labels) > 8 or len(labels) > spec.get("max_items", 32):
234
+ return None
235
+ retained = {parent: inventory}
236
+ for index in cohort["proposals"][: len(labels)]:
237
+ name = tasks[index][0]
238
+ result = results[index]
239
+ if result.get("_clair_unused_row_proposal"):
240
+ return None
241
+ parsed = scalar_result(
242
+ result, record["fields"][name], tokenizer, record.get("input", ""), None
243
+ )
244
+ retained[name] = parsed
245
+ normalized = normalize(record, retained)
246
+ normalized_inventory = normalized[parent]
247
+ if (
248
+ not normalized_inventory.get("valid")
249
+ or not normalized_inventory.get("complete")
250
+ or normalized_inventory.get("value") != value
251
+ ):
252
+ return None
253
+ proposals = []
254
+ for index in cohort["proposals"][: len(labels)]:
255
+ parsed = normalized[tasks[index][0]]
256
+ if (
257
+ not parsed.get("valid")
258
+ or not parsed.get("complete")
259
+ or (not isinstance(parsed.get("value"), dict))
260
+ or (not any((value is not None for value in parsed["value"].values())))
261
+ ):
262
+ return None
263
+ proposals.append(parsed)
264
+ (selected, conflicts) = image_rows._select(labels, proposals, cohort["text_keys"])
265
+ if conflicts or any(
266
+ (row is not proposals[index] for (index, row) in enumerate(selected))
267
+ ):
268
+ return None
269
+ return {
270
+ "inventory_labels": labels,
271
+ "selected_ordinals": list(range(1, len(labels) + 1)),
272
+ "assignment_cost": 0,
273
+ "cohort": 8,
274
+ "original_proposal_capacity": len(cohort["proposals"]),
275
+ "inventory_valid_complete": True,
276
+ "same_ordinal_matches": True,
277
+ }
278
+
279
+
280
+ def _collector_record(
281
+ record: dict[str, Any], tasks: list[tuple[str, list[int], Any]]
282
+ ) -> dict[str, Any]:
283
+ annotations = record["_meta"]["extraction_contract"]["fields"]
284
+ names = {name for (name, _, _) in tasks}
285
+ updated = dict(annotations)
286
+ for parent, annotation in annotations.items():
287
+ if parent in names and annotation.get("image_row_fields"):
288
+ updated[parent] = {
289
+ **annotation,
290
+ "image_row_fields": [
291
+ name for name in annotation["image_row_fields"] if name in names
292
+ ],
293
+ }
294
+ return {
295
+ **record,
296
+ "_meta": {
297
+ **record["_meta"],
298
+ "extraction_contract": {
299
+ **record["_meta"]["extraction_contract"],
300
+ "fields": updated,
301
+ },
302
+ },
303
+ }
304
+
305
+
306
+ def _normalize_retained(
307
+ record: dict[str, Any],
308
+ predictions: dict[str, dict[str, Any]],
309
+ normalize: Callable[
310
+ [dict[str, Any], dict[str, dict[str, Any]]], dict[str, dict[str, Any]]
311
+ ],
312
+ ) -> dict[str, dict[str, Any]]:
313
+ meta = record.get("_meta", {})
314
+ view = {
315
+ **record,
316
+ "_meta": {
317
+ **meta,
318
+ **{
319
+ kind: {
320
+ name: spec
321
+ for (name, spec) in meta.get(kind, {}).items()
322
+ if name in predictions
323
+ }
324
+ for kind in ("printed_temporal", "printed_numbers")
325
+ },
326
+ },
327
+ }
328
+ return normalize(view, predictions)
329
+
330
+
331
+ async def generate(
332
+ engine: Any,
333
+ record: dict[str, Any],
334
+ tasks: list[tuple[str, list[int], Any]],
335
+ eos: int,
336
+ tokenizer: Any,
337
+ *,
338
+ parse_result: Callable[..., dict[str, Any]] | None = None,
339
+ normalize: Callable[
340
+ [dict[str, Any], dict[str, dict[str, Any]]], dict[str, dict[str, Any]]
341
+ ]
342
+ | None = None,
343
+ **kwargs: Any,
344
+ ) -> list[dict[str, Any]]:
345
+ if (
346
+ not record.get("_first_item_list_gating")
347
+ or record.get("_null_recovery")
348
+ or set(kwargs) - _BATCHED_KEYS - _SHARED_KEYS
349
+ ):
350
+ return await _generate(engine, record, tasks, eos, tokenizer, **kwargs)
351
+ groups = _ordinary_lists(record, tasks, schema.list_item_name)
352
+ cohorts = (
353
+ _row_cohorts(record, tasks, schema.list_item_name)
354
+ if parse_result is not None and normalize is not None
355
+ else {}
356
+ )
357
+ if not groups and (not cohorts):
358
+ return await _generate(engine, record, tasks, eos, tokenizer, **kwargs)
359
+ size = len(tasks)
360
+ rids = kwargs.get("rid")
361
+ if (
362
+ not isinstance(rids, list)
363
+ or len(rids) != size
364
+ or len(set(rids)) != size
365
+ or (kwargs.get("input_ids") != [ids for (_, ids, _) in tasks])
366
+ ):
367
+ raise ValueError("Cohort scheduling requires the original distinct AR batch")
368
+ _select_kwargs(kwargs, list(range(size)), size)
369
+ tails = {index for group in groups.values() for index in group[1:]}
370
+ tails.update(
371
+ (index for cohort in cohorts.values() for index in cohort["proposals"][8:])
372
+ )
373
+ results: list[Any] = [None] * size
374
+
375
+ async def submit(indices: list[int]) -> None:
376
+ if not indices:
377
+ return
378
+ selected = _select_kwargs(kwargs, indices, size)
379
+ subset = [tasks[index] for index in indices]
380
+ view = _collector_record(record, subset) if cohorts else record
381
+ received = await _generate(engine, view, subset, eos, tokenizer, **selected)
382
+ if "_completed_inventory_pruning" in view:
383
+ record["_completed_inventory_pruning"] = view[
384
+ "_completed_inventory_pruning"
385
+ ]
386
+ if len(received) != len(indices) or any(
387
+ (
388
+ result.get("meta_info", {}).get("id") != rid
389
+ for (result, rid) in zip(received, selected["rid"], strict=True)
390
+ )
391
+ ):
392
+ raise RuntimeError("Native completion differs from its cohort submission")
393
+ for index, result in zip(indices, received, strict=True):
394
+ results[index] = result
395
+
396
+ def omit(index: int, marker: str) -> None:
397
+ (name, ids, _) = tasks[index]
398
+ unexecuted[name] = len(ids)
399
+ results[index] = {
400
+ "_clair_unused_row_proposal": True,
401
+ marker: True,
402
+ "meta_info": {"completion_tokens": 0},
403
+ }
404
+
405
+ await submit([index for index in range(size) if index not in tails])
406
+ unexecuted: dict[str, int]
407
+ continued: list[int]
408
+ (unexecuted, continued) = ({}, [])
409
+ for group in groups.values():
410
+ if _completed_null(results[group[0]], eos, tokenizer):
411
+ for index in group[1:]:
412
+ omit(index, "_first_item_unexecuted")
413
+ else:
414
+ continued.extend(group[1:])
415
+ proofs = []
416
+ for parent, cohort in cohorts.items():
417
+ proof = _cohort_proof(
418
+ record,
419
+ tasks,
420
+ results,
421
+ parent,
422
+ cohort,
423
+ tokenizer,
424
+ cast(Callable[..., dict[str, Any]], parse_result),
425
+ image_rows,
426
+ lambda record, predictions: _normalize_retained(
427
+ record,
428
+ predictions,
429
+ cast(
430
+ Callable[
431
+ [dict[str, Any], dict[str, dict[str, Any]]],
432
+ dict[str, dict[str, Any]],
433
+ ],
434
+ normalize,
435
+ ),
436
+ ),
437
+ )
438
+ proofs.append({"parent": parent, "proof": proof, "fallback": proof is None})
439
+ if proof is None:
440
+ continued.extend(cohort["proposals"][8:])
441
+ else:
442
+ for index in cohort["proposals"][8:]:
443
+ omit(index, "_row_cohort_unexecuted")
444
+ await submit(sorted(continued))
445
+ if any((result is None for result in results)):
446
+ raise RuntimeError("Cohort scheduling left an unaccounted result slot")
447
+ record["_unexecuted_list_items"] = unexecuted
448
+ record["_row_cohort_gating"] = proofs
449
+ return results
clairic_runtime/clair_schema.py ADDED
@@ -0,0 +1,563 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Field encoding, request validation, and estimate grids for Clairic.
2
+
3
+ Scalar types include text, numbers, dates, times, datetimes, and durations.
4
+ Lists preserve source order. Estimates use declared numeric or date ranges;
5
+ forecasts expand into bounded estimate fields for each requested step.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import datetime
11
+ import difflib
12
+ import itertools
13
+ import math
14
+ import re
15
+ from typing import Any
16
+
17
+ READ_TYPES = ("text", "number", "date", "time", "datetime", "duration")
18
+ FIELD_TYPES = READ_TYPES + ("list", "estimate")
19
+ LIST_ITEM_TYPES = ("text", "number", "date")
20
+ DURATION_UNITS = ("seconds", "minutes", "hours", "days", "weeks", "months", "years")
21
+ MAX_LIST_ITEMS = 32
22
+ MAX_DECIMALS = 6
23
+ MAX_FORECAST_HORIZON = 64
24
+ FORECAST_INTERVALS = (
25
+ "step",
26
+ "minute",
27
+ "hour",
28
+ "day",
29
+ "week",
30
+ "month",
31
+ "quarter",
32
+ "year",
33
+ )
34
+ DEFAULT_NULL_THRESHOLD = 0.5
35
+ MAX_GRID_STEPS = 1_000_000
36
+ COMMON_KEYS = ("type", "instructions", "unit")
37
+ NUMBER_KEYS = ("integer", "decimals")
38
+ ESTIMATE_KEYS = ("min", "max", "scale", "step")
39
+ FIELD_KEYS = {
40
+ "text": (*COMMON_KEYS, "null_threshold"),
41
+ "number": (*COMMON_KEYS, "null_threshold", *NUMBER_KEYS),
42
+ "date": (*COMMON_KEYS, "null_threshold"),
43
+ "time": (*COMMON_KEYS, "null_threshold"),
44
+ "datetime": (*COMMON_KEYS, "null_threshold"),
45
+ "duration": (*COMMON_KEYS, "null_threshold", *NUMBER_KEYS),
46
+ "list": (*COMMON_KEYS, "items", *NUMBER_KEYS),
47
+ "estimate": (*COMMON_KEYS, *ESTIMATE_KEYS),
48
+ "forecast": (*COMMON_KEYS, *ESTIMATE_KEYS, "horizon", "interval"),
49
+ }
50
+ ALL_FIELD_KEYS = tuple(
51
+ dict.fromkeys(key for keys in FIELD_KEYS.values() for key in keys)
52
+ )
53
+
54
+ SYSTEM_PREAMBLE = (
55
+ "Fill each field from the input with a value of its type. Text copies a span of the input. Numbers, "
56
+ "dates, times, datetimes, and durations are read from the input or worked out from it. A list holds "
57
+ "every matching value in input order. A field is not stated when the input does not determine it. "
58
+ "Estimates predict a value inside the declared range."
59
+ )
60
+
61
+ FIELD_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_.\-]{0,63}$")
62
+
63
+
64
+ def format_bound(value: float) -> str:
65
+ if float(value).is_integer() and abs(value) < 1e15:
66
+ return str(int(value))
67
+ return f"{value:.6g}"
68
+
69
+
70
+ def field_line(name: str, spec: dict[str, Any]) -> str:
71
+ kind = spec["type"]
72
+ unit = str(spec.get("unit") or "").strip()
73
+ if kind == "estimate" and is_date_estimate(spec):
74
+ head = f"estimate date, {spec['min']} to {spec['max']}"
75
+ granularity = date_granularity(spec)
76
+ if granularity != "day":
77
+ head += f", by {granularity}"
78
+ elif spec.get("step") and float(spec["step"]) != 1:
79
+ head += f", step {format_bound(float(spec['step']))} days"
80
+ elif kind == "estimate":
81
+ head = (
82
+ f"estimate{(' ' + unit) if unit else ''}, {format_bound(spec['min'])} to "
83
+ f"{format_bound(spec['max'])}, {spec.get('scale', 'linear')} scale"
84
+ )
85
+ if spec.get("step"):
86
+ head += f", step {format_bound(float(spec['step']))}"
87
+ elif kind == "list":
88
+ head = f"list of {spec['items']}{number_options(spec)}{(' (' + unit + ')') if unit else ''}"
89
+ elif kind == "duration":
90
+ head = f"duration in {duration_unit(spec)}{number_options(spec)}"
91
+ else:
92
+ head = f"{kind}{number_options(spec) if kind == 'number' else ''}{(' (' + unit + ')') if unit else ''}"
93
+ instructions = " ".join(str(spec.get("instructions") or "").split())
94
+ return f"{name}: {head}." + (f" {instructions}" if instructions else "")
95
+
96
+
97
+ def number_options(spec: dict[str, Any]) -> str:
98
+ if spec.get("integer"):
99
+ return ", integer"
100
+ if spec.get("decimals") is not None:
101
+ return f", {int(spec['decimals'])} decimals"
102
+ return ""
103
+
104
+
105
+ def duration_unit(spec: dict[str, Any]) -> str:
106
+ return str(spec.get("unit") or "seconds")
107
+
108
+
109
+ def allowed_decimals(spec: dict[str, Any]) -> int | None:
110
+ """Decimal places a number, duration, or number-list field allows (None: any)."""
111
+ if spec.get("integer"):
112
+ return 0
113
+ return None if spec.get("decimals") is None else int(spec["decimals"])
114
+
115
+
116
+ def parse_time(value: Any) -> tuple[int, int, int]:
117
+ """("HH:MM" or "HH:MM:SS") as (hour, minute, second); ValueError otherwise."""
118
+ if not isinstance(value, str):
119
+ raise ValueError(f"time must be a string, got {value!r}") # noqa: TRY004 - callers catch ValueError
120
+ parsed = datetime.time.fromisoformat(value)
121
+ if parsed.microsecond or parsed.tzinfo is not None:
122
+ raise ValueError(f"time {value!r} must be HH:MM or HH:MM:SS")
123
+ return parsed.hour, parsed.minute, parsed.second
124
+
125
+
126
+ def format_time(hour: int, minute: int, second: int) -> str:
127
+ return f"{hour:02d}:{minute:02d}:{second:02d}"
128
+
129
+
130
+ def parse_datetime(value: Any) -> tuple[str, tuple[int, int, int]]:
131
+ """("YYYY-MM-DDTHH:MM[:SS]") as (ISO date, (hour, minute, second)); ValueError otherwise."""
132
+ if not isinstance(value, str) or "T" not in value:
133
+ raise ValueError(f"datetime must be YYYY-MM-DDTHH:MM[:SS], got {value!r}")
134
+ day, clock = value.split("T", 1)
135
+ return datetime.date.fromisoformat(day).isoformat(), parse_time(clock)
136
+
137
+
138
+ def forecast_instructions(instructions: str, step: int, interval: str) -> str:
139
+ """The instructions for one step of a forecast path."""
140
+ what = " ".join(str(instructions or "").split()).rstrip(".") or "the series"
141
+ unit = "step" if interval == "step" else interval
142
+ return f"Forecast {what} {step} {unit}{'s' if step > 1 else ''} after the last observation."
143
+
144
+
145
+ def check_field_keys(fields: dict[str, Any]) -> None:
146
+ """Every field spec uses only the keys its type takes, so a misspelled option ("decimal",
147
+ "interger") is an error instead of a constraint that is silently dropped."""
148
+ for name, spec in fields.items():
149
+ if not isinstance(spec, dict) or spec.get("type") not in FIELD_KEYS:
150
+ continue
151
+ kind = spec["type"]
152
+ for key in spec:
153
+ if key in FIELD_KEYS[kind]:
154
+ continue
155
+ if key in ALL_FIELD_KEYS:
156
+ raise ValueError(f"field {name}: {kind} fields don't take {key!r}")
157
+ close = difflib.get_close_matches(
158
+ str(key), FIELD_KEYS[kind], n=1, cutoff=0.6
159
+ )
160
+ hint = (
161
+ f"; did you mean {close[0]!r}?"
162
+ if close
163
+ else f"; {kind} fields take {', '.join(FIELD_KEYS[kind])}"
164
+ )
165
+ raise ValueError(f"field {name} has unknown key {key!r}{hint}")
166
+
167
+
168
+ def expand_forecasts(
169
+ fields: dict[str, Any],
170
+ ) -> tuple[dict[str, Any], dict[str, list[str]]]:
171
+ """Request fields with every ``forecast`` replaced by ``horizon`` estimate fields named
172
+ ``name.1`` ... ``name.H`` (same range, scale, step, and unit), plus each forecast's step names."""
173
+ expanded: dict[str, Any] = {}
174
+ groups: dict[str, list[str]] = {}
175
+ for name, spec in fields.items():
176
+ if not isinstance(spec, dict) or spec.get("type") != "forecast":
177
+ expanded[name] = spec
178
+ continue
179
+ horizon = spec.get("horizon")
180
+ if (
181
+ isinstance(horizon, bool)
182
+ or not isinstance(horizon, int)
183
+ or not 1 <= horizon <= MAX_FORECAST_HORIZON
184
+ ):
185
+ raise ValueError(
186
+ f"forecast {name} needs an integer horizon from 1 to {MAX_FORECAST_HORIZON}"
187
+ )
188
+ interval = spec.get("interval", "step")
189
+ if interval not in FORECAST_INTERVALS:
190
+ raise ValueError(f"forecast {name} has an unknown interval {interval!r}")
191
+ base = {
192
+ key: value
193
+ for key, value in spec.items()
194
+ if key not in ("type", "horizon", "interval", "instructions")
195
+ }
196
+ if is_date_estimate({"type": "estimate", **base}):
197
+ validate_date_range(name, {"type": "estimate", **base}, kind="forecast")
198
+ else:
199
+ validate_number_range(name, {"type": "estimate", **base}, kind="forecast")
200
+ groups[name] = []
201
+ for step in range(1, horizon + 1):
202
+ step_name = f"{name}.{step}"
203
+ if step_name in fields or step_name in expanded:
204
+ raise ValueError(
205
+ f"forecast {name} step {step_name} collides with another field"
206
+ )
207
+ expanded[step_name] = {
208
+ "type": "estimate",
209
+ **base,
210
+ "instructions": forecast_instructions(
211
+ spec.get("instructions", ""), step, interval
212
+ ),
213
+ }
214
+ groups[name].append(step_name)
215
+ return expanded, groups
216
+
217
+
218
+ # ---------------------------------------------------------------- estimate transforms
219
+
220
+
221
+ def to_unit(value: float, low: float, high: float, scale: str) -> float:
222
+ return min(1.0, max(0.0, raw_unit(value, low, high, scale)))
223
+
224
+
225
+ def raw_unit(value: float, low: float, high: float, scale: str) -> float:
226
+ """Unit position without clamping: below 0 or above 1 when the value is outside the range (a
227
+ non-positive value on a log scale is -1)."""
228
+ if scale == "log":
229
+ if value <= 0:
230
+ return -1.0
231
+ return (math.log(value) - math.log(low)) / (math.log(high) - math.log(low))
232
+ return (value - low) / (high - low)
233
+
234
+
235
+ def from_unit(position: float, low: float, high: float, scale: str) -> float:
236
+ position = min(1.0, max(0.0, position))
237
+ if scale == "log":
238
+ value = math.exp(math.log(low) + position * (math.log(high) - math.log(low)))
239
+ else:
240
+ value = low + position * (high - low)
241
+ return min(high, max(low, value))
242
+
243
+
244
+ def resolution_in_unit(spec: dict[str, Any], resolution: float | None) -> float:
245
+ if not resolution:
246
+ return 0.0
247
+ low, high, scale = estimate_range(spec)
248
+ if scale == "log":
249
+ return math.log1p(resolution) / (math.log(high) - math.log(low))
250
+ return resolution / (high - low)
251
+
252
+
253
+ # ---------------------------------------------------------------- date estimates
254
+
255
+
256
+ def is_date_estimate(spec: dict[str, Any]) -> bool:
257
+ return spec.get("type") == "estimate" and isinstance(spec.get("min"), str)
258
+
259
+
260
+ def date_granularity(spec: dict[str, Any]) -> str:
261
+ step = spec.get("step")
262
+ return step if step in ("month", "year") else "day"
263
+
264
+
265
+ def date_index(value: str, granularity: str = "day") -> float:
266
+ """A date as a number on its grid: day ordinal, months since year 0, or the year."""
267
+ date = datetime.date.fromisoformat(value)
268
+ if granularity == "month":
269
+ return float(date.year * 12 + date.month - 1)
270
+ if granularity == "year":
271
+ return float(date.year)
272
+ return float(date.toordinal())
273
+
274
+
275
+ def index_date(index: float, granularity: str = "day") -> str:
276
+ whole = round(index)
277
+ if granularity == "month":
278
+ year, month = divmod(whole, 12)
279
+ return datetime.date(year, month + 1, 1).isoformat()
280
+ if granularity == "year":
281
+ return datetime.date(whole, 1, 1).isoformat()
282
+ return datetime.date.fromordinal(whole).isoformat()
283
+
284
+
285
+ def estimate_range(spec: dict[str, Any]) -> tuple[float, float, str]:
286
+ """Numeric bounds and scale of an estimate; date bounds become grid indexes (linear scale)."""
287
+ if is_date_estimate(spec):
288
+ granularity = date_granularity(spec)
289
+ return (
290
+ date_index(spec["min"], granularity),
291
+ date_index(spec["max"], granularity),
292
+ "linear",
293
+ )
294
+ return float(spec["min"]), float(spec["max"]), spec.get("scale", "linear")
295
+
296
+
297
+ def estimate_step(spec: dict[str, Any]) -> float:
298
+ """The grid step in the numeric space of ``estimate_range`` (0: continuous). Date estimates always
299
+ have a grid: ``step`` days (default 1), or one month or year."""
300
+ if is_date_estimate(spec):
301
+ return (
302
+ 1.0 if date_granularity(spec) != "day" else float(spec.get("step") or 1.0)
303
+ )
304
+ return float(spec.get("step") or 0.0)
305
+
306
+
307
+ def estimate_number(spec: dict[str, Any], value: Any) -> float:
308
+ if is_date_estimate(spec):
309
+ return date_index(str(value), date_granularity(spec))
310
+ return float(value)
311
+
312
+
313
+ def estimate_value(spec: dict[str, Any], number: float) -> float | str:
314
+ """An estimate output in the field's own terms: an ISO date for date estimates."""
315
+ if is_date_estimate(spec):
316
+ low, high, _ = estimate_range(spec)
317
+ return index_date(min(max(number, low), high), date_granularity(spec))
318
+ return number
319
+
320
+
321
+ def grid_bounds(step: float, low: float, high: float) -> tuple[float, float]:
322
+ """The smallest and largest multiples of ``step`` inside [low, high]."""
323
+ first = math.ceil(low / step - 1e-9) * step
324
+ last = math.floor(high / step + 1e-9) * step
325
+ return float(f"{first:.12g}"), float(f"{last:.12g}")
326
+
327
+
328
+ def snap(value: float, step: float, low: float, high: float) -> float:
329
+ """Nearest grid value inside the range."""
330
+ first, last = grid_bounds(step, low, high)
331
+ return float(f"{min(last, max(first, round(value / step) * step)):.12g}")
332
+
333
+
334
+ def snap_quantile(value: float, step: float, low: float, high: float) -> float:
335
+ """Quantile of the discrete distribution a continuous one implies when every grid value v owns
336
+ [v - step/2, v + step/2): the smallest v with v + step/2 >= the continuous quantile."""
337
+ first, last = grid_bounds(step, low, high)
338
+ return float(
339
+ f"{min(last, max(first, math.ceil((value - step / 2) / step - 1e-9) * step)):.12g}"
340
+ )
341
+
342
+
343
+ def step_interval(spec: dict[str, Any], value: float) -> tuple[float, float]:
344
+ """The value-space interval a grid value owns, clipped to the declared range (``value`` in the
345
+ numeric space of ``estimate_range``)."""
346
+ step = estimate_step(spec)
347
+ low, high, _ = estimate_range(spec)
348
+ if step <= 0:
349
+ return value, value
350
+ return max(low, value - step / 2), min(high, value + step / 2)
351
+
352
+
353
+ # ---------------------------------------------------------------- text spans
354
+
355
+
356
+ def _cuts_word(text: str, start: int, end: int) -> bool:
357
+ """Whether text[start:end] splits an ASCII word or number at either edge ("dock" inside "docks",
358
+ "12" inside "312"). Other scripts are never treated as cut, so CJK matches are unaffected."""
359
+
360
+ def joined(left: str, right: str) -> bool:
361
+ return left.isascii() and left.isalnum() and right.isascii() and right.isalnum()
362
+
363
+ return (start > 0 and joined(text[start - 1], text[start])) or (
364
+ end < len(text) and joined(text[end - 1], text[end])
365
+ )
366
+
367
+
368
+ def _prefer_whole(
369
+ text: str, spans: list[tuple[int, int]], limit: int
370
+ ) -> list[tuple[int, int]]:
371
+ whole = [span for span in spans if not _cuts_word(text, *span)]
372
+ return (whole or spans)[:limit]
373
+
374
+
375
+ def find_spans(text: str, value: str, limit: int = 16) -> list[tuple[int, int]]:
376
+ """Character spans of ``value`` in ``text``: exact matches, else case-insensitive, else with any
377
+ whitespace between words. Within each stage, matches on word boundaries are preferred; substring
378
+ matches inside a longer word are kept only when there is no other match."""
379
+ value = value.strip()
380
+ if not value:
381
+ return []
382
+ scan = max(limit * 8, 64)
383
+ spans: list[tuple[int, int]] = []
384
+ start = text.find(value)
385
+ while start >= 0 and len(spans) < scan:
386
+ spans.append((start, start + len(value)))
387
+ start = text.find(value, start + 1)
388
+ if spans:
389
+ return _prefer_whole(text, spans, limit)
390
+ lowered, target = text.lower(), value.lower()
391
+ if len(lowered) == len(text):
392
+ start = lowered.find(target)
393
+ while start >= 0 and len(spans) < scan:
394
+ spans.append((start, start + len(value)))
395
+ start = lowered.find(target, start + 1)
396
+ if spans:
397
+ return _prefer_whole(text, spans, limit)
398
+ pieces = value.split()
399
+ if not pieces:
400
+ return []
401
+ pattern = re.compile(
402
+ r"\s+".join(re.escape(piece) for piece in pieces), re.IGNORECASE
403
+ )
404
+ spans = [
405
+ (match.start(), match.end())
406
+ for match in itertools.islice(pattern.finditer(text), scan)
407
+ ]
408
+ return _prefer_whole(text, spans, limit)
409
+
410
+
411
+ # ---------------------------------------------------------------- records
412
+
413
+
414
+ def validate_fields(fields: Any) -> None:
415
+ """A schema with any number of fields (at least one): valid names, known types, and for estimates
416
+ a valid range, scale, and step. Requests are checked with this before prediction, so every output
417
+ can be held to its field's type."""
418
+ if not isinstance(fields, dict) or not fields:
419
+ raise ValueError("fields must declare at least one field")
420
+ for name, spec in fields.items():
421
+ if not isinstance(name, str) or not FIELD_NAME.match(name):
422
+ raise ValueError(f"invalid field name {name!r}")
423
+ kind = spec.get("type") if isinstance(spec, dict) else None
424
+ if kind not in FIELD_TYPES:
425
+ raise ValueError(f"field {name} has unknown type {kind!r}")
426
+ if "null_threshold" in spec:
427
+ threshold = spec["null_threshold"]
428
+ if kind in ("estimate", "list"):
429
+ raise ValueError(f"{kind} {name} does not take null_threshold")
430
+ if (
431
+ isinstance(threshold, bool)
432
+ or not isinstance(threshold, (int, float))
433
+ or not 0 < threshold <= 1
434
+ ):
435
+ raise ValueError(f"field {name} needs null_threshold in (0, 1]")
436
+ if kind == "list" and spec.get("items") not in LIST_ITEM_TYPES:
437
+ raise ValueError(f"list {name} needs items in {LIST_ITEM_TYPES}")
438
+ if kind == "duration" and duration_unit(spec) not in DURATION_UNITS:
439
+ raise ValueError(f"duration {name} needs a unit in {DURATION_UNITS}")
440
+ numeric = kind in ("number", "duration") or (
441
+ kind == "list" and spec.get("items") == "number"
442
+ )
443
+ if not numeric and ("integer" in spec or "decimals" in spec):
444
+ raise ValueError(
445
+ f"field {name}: integer and decimals apply to numbers and durations only"
446
+ )
447
+ if "integer" in spec and not isinstance(spec["integer"], bool):
448
+ raise ValueError(f"field {name}: integer must be true or false")
449
+ if "decimals" in spec:
450
+ decimals = spec["decimals"]
451
+ if (
452
+ isinstance(decimals, bool)
453
+ or not isinstance(decimals, int)
454
+ or not 0 <= decimals <= MAX_DECIMALS
455
+ ):
456
+ raise ValueError(
457
+ f"field {name}: decimals must be an integer from 0 to {MAX_DECIMALS}"
458
+ )
459
+ if spec.get("integer") and decimals:
460
+ raise ValueError(f"field {name}: an integer field has 0 decimals")
461
+ if kind == "estimate" and is_date_estimate(spec):
462
+ validate_date_range(name, spec)
463
+ elif kind == "estimate":
464
+ validate_number_range(name, spec)
465
+
466
+
467
+ def null_threshold(spec: dict[str, Any]) -> float:
468
+ """A read field answers null when p_null is at or above this (default 0.5)."""
469
+ return float(spec.get("null_threshold", DEFAULT_NULL_THRESHOLD))
470
+
471
+
472
+ def _number(value: Any) -> float:
473
+ if isinstance(value, bool) or not isinstance(value, (int, float)):
474
+ raise TypeError(value)
475
+ return float(value)
476
+
477
+
478
+ def validate_number_range(
479
+ name: str, spec: dict[str, Any], kind: str = "estimate"
480
+ ) -> None:
481
+ try:
482
+ low, high = _number(spec["min"]), _number(spec["max"])
483
+ except (KeyError, TypeError) as error:
484
+ raise ValueError(f"{kind} {name} needs numeric min and max") from error
485
+ if not (math.isfinite(low) and math.isfinite(high)) or low >= high:
486
+ raise ValueError(
487
+ f"{kind} {name} needs finite min < max, got {spec['min']!r} and {spec['max']!r}"
488
+ )
489
+ scale = spec.get("scale", "linear")
490
+ if scale not in ("linear", "log"):
491
+ raise ValueError(
492
+ f"{kind} {name} has an unknown scale {scale!r}; use 'linear' or 'log'"
493
+ )
494
+ if scale == "log" and low <= 0:
495
+ raise ValueError(
496
+ f"{kind} {name} uses scale 'log', which needs min > 0, got {spec['min']!r}"
497
+ )
498
+ if spec.get("step") is None:
499
+ return
500
+ try:
501
+ step = _number(spec["step"])
502
+ except TypeError as error:
503
+ raise ValueError(
504
+ f"{kind} {name}: step must be a positive number, got {spec['step']!r}"
505
+ ) from error
506
+ if not math.isfinite(step) or step <= 0:
507
+ raise ValueError(
508
+ f"{kind} {name}: step must be a positive number, got {spec['step']!r}"
509
+ )
510
+ steps = (high - low) / step
511
+ if steps < 1:
512
+ raise ValueError(
513
+ f"{kind} {name}: step {spec['step']!r} is larger than the range {spec['min']!r} to {spec['max']!r}"
514
+ )
515
+ if steps > MAX_GRID_STEPS:
516
+ raise ValueError(
517
+ f"{kind} {name}: step {spec['step']!r} divides {spec['min']!r} to {spec['max']!r} into {steps:,.0f} steps; "
518
+ f"the limit is {MAX_GRID_STEPS:,}. Use a larger step or omit it"
519
+ )
520
+
521
+
522
+ def validate_reference_date(value: Any) -> None:
523
+ if value is None:
524
+ return
525
+ try:
526
+ datetime.date.fromisoformat(value)
527
+ except (TypeError, ValueError) as error:
528
+ raise ValueError(
529
+ f"reference_date must be an ISO date, got {value!r}"
530
+ ) from error
531
+
532
+
533
+ def validate_date_range(
534
+ name: str, spec: dict[str, Any], kind: str = "estimate"
535
+ ) -> None:
536
+ try:
537
+ low, high, _ = estimate_range(spec)
538
+ except (KeyError, TypeError, ValueError) as error:
539
+ raise ValueError(
540
+ f"date {kind} {name} needs ISO date min and max (YYYY-MM-DD)"
541
+ ) from error
542
+ if not isinstance(spec.get("max"), str) or not low < high:
543
+ raise ValueError(
544
+ f"date {kind} {name} needs ISO date min < max, got {spec.get('min')!r} and {spec.get('max')!r}"
545
+ )
546
+ if spec.get("scale", "linear") != "linear":
547
+ raise ValueError(f"date {kind} {name} only takes scale 'linear'")
548
+ if date_granularity(spec) != "day" or spec.get("step") is None:
549
+ return
550
+ step = spec["step"]
551
+ if (
552
+ isinstance(step, bool)
553
+ or not isinstance(step, (int, float))
554
+ or not float(step).is_integer()
555
+ or step < 1
556
+ ):
557
+ raise ValueError(
558
+ f"date {kind} {name}: step must be a whole number of days, 'month', or 'year', got {step!r}"
559
+ )
560
+ if (high - low) / step < 1:
561
+ raise ValueError(
562
+ f"date {kind} {name}: step {step!r} days is larger than the range"
563
+ )
clairic_runtime/contracts.py ADDED
@@ -0,0 +1,128 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ from typing import Any
3
+ from jsonschema import Draft202012Validator, SchemaError
4
+
5
+ COMMON = {"type", "instructions", "nullable"}
6
+ NUMERIC = {"integer", "decimals", "unit"}
7
+ GRAMMAR_NUMBER = {"minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "enum"}
8
+ OPTIONS = {
9
+ "text": {"knowledge", "minLength", "maxLength", "pattern", "enum"},
10
+ "number": NUMERIC | GRAMMAR_NUMBER | {"knowledge", "source_only"},
11
+ "compute": NUMERIC | {"null_threshold"},
12
+ "date": {"null_threshold", "source_only"},
13
+ "time": {"null_threshold", "source_only"},
14
+ "datetime": {"null_threshold", "source_only"},
15
+ "duration": NUMERIC | {"null_threshold"},
16
+ "boolean": set(),
17
+ "enum": {"enum"},
18
+ "object": {"properties"},
19
+ "list": {"items", "max_items", "knowledge", "source_only"} | NUMERIC | {"enum"},
20
+ "estimate": {"min", "max", "scale", "step", "unit"},
21
+ "forecast": {"min", "max", "scale", "step", "unit", "horizon", "interval"},
22
+ }
23
+
24
+
25
+ def item_spec(spec: dict[str, Any]) -> dict[str, Any]:
26
+ item = spec["items"]
27
+ return dict(item) if isinstance(item, dict) else {"type": item}
28
+
29
+
30
+ def validate_public_fields(fields: dict[str, dict[str, Any]]) -> None:
31
+ _validate_public_fields(fields, set())
32
+
33
+
34
+ def _validate_public_fields(
35
+ fields: dict[str, dict[str, Any]], checked_scalar_schemas: set[tuple[str, ...]]
36
+ ) -> None:
37
+ for name, spec in fields.items():
38
+ kind = spec.get("type") if isinstance(spec, dict) else None
39
+ if not isinstance(kind, str) or kind not in OPTIONS:
40
+ raise ValueError(f"field {name}: unknown field type")
41
+ unknown = spec.keys() - COMMON - OPTIONS[kind]
42
+ if unknown:
43
+ raise ValueError(f"field {name}: unknown options {sorted(unknown)}")
44
+ if "instructions" in spec and (not isinstance(spec["instructions"], str)):
45
+ raise ValueError(f"field {name}: instructions must be a string")
46
+ if "nullable" in spec and (not isinstance(spec["nullable"], bool)):
47
+ raise ValueError(f"field {name}: nullable must be true or false")
48
+ if "source_only" in spec:
49
+ if not isinstance(spec["source_only"], bool):
50
+ raise ValueError(f"field {name}: source_only must be true or false")
51
+ if kind == "list" and spec.get("items") not in ("date", "number"):
52
+ raise ValueError(
53
+ f"field {name}: source_only lists require date or number items"
54
+ )
55
+ if spec["source_only"] and "null_threshold" in spec:
56
+ raise ValueError(
57
+ f"field {name}: source_only does not support typed null_threshold"
58
+ )
59
+ if spec["source_only"] and spec.get("knowledge"):
60
+ raise ValueError(
61
+ f"field {name}: source_only cannot permit knowledge answers"
62
+ )
63
+ if "enum" in spec and (not isinstance(spec["enum"], list) or not spec["enum"]):
64
+ raise ValueError(f"field {name}: enum must be a nonempty array")
65
+ if kind == "enum" and "enum" not in spec:
66
+ raise ValueError(f"field {name}: enum values are required")
67
+ if kind == "object":
68
+ properties = spec.get("properties")
69
+ if not isinstance(properties, dict) or not properties:
70
+ raise ValueError(f"field {name}: object properties are required")
71
+ if any(
72
+ (
73
+ not isinstance(child, dict)
74
+ or child.get("type") not in ("text", "number", "boolean", "enum")
75
+ for child in properties.values()
76
+ )
77
+ ):
78
+ raise ValueError(
79
+ f"field {name}: row properties must be text, number, boolean or enum"
80
+ )
81
+ if any((child.get("source_only") for child in properties.values())):
82
+ raise ValueError(
83
+ f"field {name}: source_only is supported on scalar numbers and number lists, not row properties"
84
+ )
85
+ _validate_public_fields(properties, checked_scalar_schemas)
86
+ from . import schema as zs
87
+
88
+ zs.validate_fields(properties)
89
+ if kind == "list":
90
+ if "items" not in spec:
91
+ raise ValueError(f"list {name}: items are required")
92
+ child = item_spec(spec)
93
+ if isinstance(spec["items"], dict) and child.get("type") != "object":
94
+ raise ValueError(f"list {name}: structured items must be objects")
95
+ if child.get("type") == "object":
96
+ _validate_public_fields({name + "[]": child}, checked_scalar_schemas)
97
+ if spec.keys() & (NUMERIC | {"knowledge", "enum"}):
98
+ raise ValueError(
99
+ f"list {name}: put numeric or knowledge options on row properties"
100
+ )
101
+ maximum = spec.get("max_items")
102
+ if "max_items" in spec and (
103
+ isinstance(maximum, bool) or not isinstance(maximum, int) or maximum < 0
104
+ ):
105
+ raise ValueError(
106
+ f"list {name}: max_items must be a nonnegative integer"
107
+ )
108
+ if kind in ("text", "number", "boolean", "enum", "object"):
109
+ from . import ar
110
+
111
+ try:
112
+ schema = ar.schema(spec)
113
+ scalar_key = None
114
+ if schema.keys() == {"type"}:
115
+ schema_type = schema["type"]
116
+ scalar_key = (
117
+ tuple(schema_type)
118
+ if isinstance(schema_type, list)
119
+ else (schema_type,)
120
+ )
121
+ if scalar_key is None or scalar_key not in checked_scalar_schemas:
122
+ Draft202012Validator.check_schema(schema)
123
+ if scalar_key is not None:
124
+ checked_scalar_schemas.add(scalar_key)
125
+ except SchemaError as error:
126
+ raise ValueError(
127
+ f"field {name}: invalid schema constraint: {error.message}"
128
+ ) from error
clairic_runtime/documents.py ADDED
@@ -0,0 +1,91 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Validate embedded PDFs and render their pages inside the request encoder."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import TYPE_CHECKING
6
+
7
+ if TYPE_CHECKING:
8
+ from PIL import Image
9
+
10
+ import base64
11
+ import binascii
12
+ import math
13
+ import re
14
+
15
+ from .embedded import MAX_IMAGE_BYTES, MAX_IMAGES
16
+ from pydantic import BaseModel, ConfigDict, StrictStr, model_validator
17
+
18
+
19
+ class ClairDocument(BaseModel):
20
+ model_config = ConfigDict(extra="forbid", frozen=True)
21
+
22
+ content_type: StrictStr
23
+ base64: StrictStr
24
+
25
+ @model_validator(mode="before")
26
+ @classmethod
27
+ def parse_document(cls, value: object) -> dict[str, str]:
28
+ if isinstance(value, str):
29
+ match = re.fullmatch(
30
+ r"data:application/pdf;base64,([A-Za-z0-9+/]*={0,2})",
31
+ value,
32
+ re.IGNORECASE,
33
+ )
34
+ if match is None:
35
+ raise ValueError("document must be an embedded PDF data URI")
36
+ value = {"content_type": "application/pdf", "base64": match[1]}
37
+ if type(value) is not dict or set(value) != {"content_type", "base64"}:
38
+ raise ValueError("document object must contain content_type and base64")
39
+ if value["content_type"] != "application/pdf" or not isinstance(
40
+ value["base64"], str
41
+ ):
42
+ raise ValueError("document content type must be application/pdf")
43
+ try:
44
+ data = base64.b64decode(value["base64"], validate=True)
45
+ except (binascii.Error, ValueError) as error:
46
+ raise ValueError("document base64 is malformed") from error
47
+ if not data.startswith(b"%PDF-") or len(data) > MAX_IMAGE_BYTES:
48
+ raise ValueError("document must be a PDF within the decoded byte limit")
49
+ return {
50
+ "content_type": "application/pdf",
51
+ "base64": base64.b64encode(data).decode("ascii"),
52
+ }
53
+
54
+ def render(self, available_pages: int = MAX_IMAGES) -> list[Image.Image]:
55
+ import pypdfium2 as pdfium
56
+
57
+ from .orientation import orient_document
58
+
59
+ try:
60
+ pdf = pdfium.PdfDocument(base64.b64decode(self.base64))
61
+ try:
62
+ if not 0 < len(pdf) <= available_pages:
63
+ raise ValueError(
64
+ f"PDF pages and images together must not exceed {MAX_IMAGES}"
65
+ )
66
+ images = []
67
+ for index in range(len(pdf)):
68
+ page = pdf[index]
69
+ try:
70
+ width, height = page.get_size()
71
+ if not (
72
+ math.isfinite(width * height) and width > 0 and height > 0
73
+ ):
74
+ raise ValueError("PDF page has invalid dimensions")
75
+ scale = min(2.0, math.sqrt(4_000_000 / (width * height)))
76
+ bitmap = page.render(scale=scale)
77
+ try:
78
+ images.append(
79
+ orient_document(bitmap.to_pil().convert("RGB"))
80
+ )
81
+ finally:
82
+ bitmap.close()
83
+ finally:
84
+ page.close()
85
+ return images
86
+ finally:
87
+ pdf.close()
88
+ except pdfium.PdfiumError as error:
89
+ raise ValueError(
90
+ "PDF cannot be opened or rendered; encrypted PDFs are unsupported"
91
+ ) from error
clairic_runtime/embedded.py ADDED
@@ -0,0 +1,144 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Validation for embedded request images.
2
+
3
+ Callers translate ``EmbeddedImageError`` into their own validation error type.
4
+ The strict mode verifies the complete raster with Pillow; the signature mode
5
+ intentionally accepts header-only images for backends that validate only magic
6
+ bytes before forwarding the image to another service.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import base64
12
+ import binascii
13
+ import io
14
+ import re
15
+ from collections.abc import Iterable
16
+
17
+ MAX_IMAGES = 4
18
+ MAX_IMAGE_BYTES = 4 * 1024 * 1024
19
+ MAX_IMAGES_BYTES = 8 * 1024 * 1024
20
+
21
+ _STRICT_DATA_URI = re.compile(
22
+ r"^data:(image/(?:png|jpe?g|webp));base64,([A-Za-z0-9+/]*={0,2})$", re.IGNORECASE
23
+ )
24
+ _DATA_URL = re.compile(r"^data:([^;,]+);base64,(.*)$", re.DOTALL)
25
+ _FORMATS = {"image/png": "PNG", "image/jpeg": "JPEG", "image/webp": "WEBP"}
26
+
27
+
28
+ class EmbeddedImageError(ValueError):
29
+ """A request-image failure, with a stable code for the serving layer."""
30
+
31
+ def __init__(self, code: str, message: str) -> None:
32
+ super().__init__(message)
33
+ self.code = code
34
+
35
+
36
+ def normalize_embedded_image(
37
+ value: object,
38
+ *,
39
+ strict: bool = False,
40
+ max_image_bytes: int = MAX_IMAGE_BYTES,
41
+ max_pixels: int = 16_000_000,
42
+ ) -> dict[str, str]:
43
+ """Normalize a data URL or exact ``{content_type, base64}`` object.
44
+
45
+ ``strict=True`` verifies restricted data-URI syntax and complete raster data
46
+ with Pillow, including the dimension limit. The default checks image
47
+ signatures and accepts a more permissive data-URL syntax.
48
+ """
49
+ if isinstance(value, str):
50
+ matched = (_STRICT_DATA_URI if strict else _DATA_URL).fullmatch(value)
51
+ if matched is None:
52
+ label = "URI" if strict else "URL"
53
+ raise EmbeddedImageError(
54
+ "invalid_image", f"image must be an embedded base64 data {label}"
55
+ )
56
+ value = {"content_type": matched.group(1), "base64": matched.group(2)}
57
+ if type(value) is not dict or set(value) != {"content_type", "base64"}:
58
+ raise EmbeddedImageError("invalid_image", "image object has invalid fields")
59
+ content_type = value["content_type"]
60
+ encoded = value["base64"]
61
+ if type(content_type) is not str or type(encoded) is not str:
62
+ raise EmbeddedImageError("invalid_image", "image fields must be strings")
63
+ canonical_type = content_type.lower().replace("image/jpg", "image/jpeg")
64
+ if canonical_type not in _FORMATS:
65
+ raise EmbeddedImageError("invalid_image", "image content type is not supported")
66
+ try:
67
+ decoded = base64.b64decode(encoded, validate=True)
68
+ except (binascii.Error, ValueError) as error:
69
+ raise EmbeddedImageError(
70
+ "invalid_image", "image base64 is malformed"
71
+ ) from error
72
+ if not decoded:
73
+ raise EmbeddedImageError("invalid_image", "image payload is empty")
74
+ if len(decoded) > max_image_bytes:
75
+ raise EmbeddedImageError(
76
+ "image_too_large", "image exceeds the decoded byte limit"
77
+ )
78
+ if strict:
79
+ _verify_raster(decoded, _FORMATS[canonical_type], max_pixels=max_pixels)
80
+ elif not _has_image_signature(canonical_type, decoded):
81
+ raise EmbeddedImageError(
82
+ "invalid_image", "image payload does not match its content type"
83
+ )
84
+ return {
85
+ "content_type": canonical_type,
86
+ "base64": base64.b64encode(decoded).decode("ascii"),
87
+ }
88
+
89
+
90
+ def _verify_raster(data: bytes, expected_format: str, *, max_pixels: int) -> None:
91
+ from PIL import Image, UnidentifiedImageError
92
+
93
+ try:
94
+ with Image.open(io.BytesIO(data)) as image:
95
+ if image.format != expected_format:
96
+ raise EmbeddedImageError(
97
+ "invalid_image", "image payload does not match its content type"
98
+ )
99
+ if image.width * image.height > max_pixels:
100
+ raise EmbeddedImageError(
101
+ "invalid_image", "image dimensions are too large"
102
+ )
103
+ image.verify()
104
+ except EmbeddedImageError:
105
+ raise
106
+ except (
107
+ UnidentifiedImageError,
108
+ OSError,
109
+ ValueError,
110
+ Image.DecompressionBombError,
111
+ ) as error:
112
+ raise EmbeddedImageError("invalid_image", "image payload is invalid") from error
113
+
114
+
115
+ def _has_image_signature(content_type: str, data: bytes) -> bool:
116
+ if content_type == "image/png":
117
+ return data.startswith(b"\x89PNG\r\n\x1a\n")
118
+ if content_type == "image/jpeg":
119
+ return data.startswith(b"\xff\xd8\xff")
120
+ return len(data) >= 12 and data.startswith(b"RIFF") and data[8:12] == b"WEBP"
121
+
122
+
123
+ def decoded_base64_size(encoded: str) -> int:
124
+ """Size of already validated, canonical base64 without decoding again."""
125
+ return len(encoded) * 3 // 4 - (len(encoded) - len(encoded.rstrip("=")))
126
+
127
+
128
+ def validate_image_count(value: object, *, max_images: int = MAX_IMAGES) -> object:
129
+ if not isinstance(value, (list, tuple)):
130
+ raise EmbeddedImageError("invalid_image", "images must be an array")
131
+ if len(value) > max_images:
132
+ raise EmbeddedImageError(
133
+ "too_many_images", "request exceeds the image count limit"
134
+ )
135
+ return value
136
+
137
+
138
+ def validate_total_image_bytes(
139
+ sizes: Iterable[int], *, max_bytes: int = MAX_IMAGES_BYTES
140
+ ) -> None:
141
+ if sum(sizes) > max_bytes:
142
+ raise EmbeddedImageError(
143
+ "images_too_large", "images exceed the aggregate decoded byte limit"
144
+ )
clairic_runtime/entity_scope.py ADDED
@@ -0,0 +1,37 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ import re
3
+ from typing import Any
4
+
5
+ COPY_NAME_INSTRUCTION = " Include attached digits and trailing numeric segments that are part of the printed name."
6
+ _ROLE = re.compile(
7
+ "\\b(?:seller|merchant|vendor|customer|bill[- ]?to|recipient|payee|payer|guest|organization|business|company|legal)\\b",
8
+ re.IGNORECASE,
9
+ )
10
+ _OTHER_VALUE = re.compile(
11
+ "\\b(?:address|number|identifier|code|date|row|label|amount)\\b", re.IGNORECASE
12
+ )
13
+
14
+
15
+ def prepare(
16
+ fields: dict[str, dict[str, Any]], *, has_media: bool = False
17
+ ) -> dict[str, dict[str, Any]]:
18
+ if not has_media:
19
+ return fields
20
+ result = dict(fields)
21
+ for name, spec in fields.items():
22
+ if spec.get("type") != "text" or spec.get("knowledge"):
23
+ continue
24
+ instructions = spec.get("instructions", "")
25
+ if not isinstance(instructions, str):
26
+ continue
27
+ requested = re.split("[.\\n]", instructions, maxsplit=1)[0]
28
+ if (
29
+ re.search("\\bname\\b", requested, re.IGNORECASE)
30
+ and _ROLE.search(requested)
31
+ and (not _OTHER_VALUE.search(requested))
32
+ ):
33
+ result[name] = {
34
+ **spec,
35
+ "instructions": instructions + COPY_NAME_INSTRUCTION,
36
+ }
37
+ return result
clairic_runtime/errors.py ADDED
@@ -0,0 +1,10 @@
 
 
 
 
 
 
 
 
 
 
 
1
+ class ClairRequestError(ValueError):
2
+ """A request the model cannot serve, such as an invalid field spec or a schema that leaves no room for the state."""
3
+
4
+
5
+ class ClairQueueFull(RuntimeError):
6
+ pass
7
+
8
+
9
+ class ClairInferenceError(RuntimeError):
10
+ pass
clairic_runtime/financial_scope.py ADDED
@@ -0,0 +1,94 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ import re
3
+ from typing import Any
4
+
5
+ TAX_INSTRUCTION = " A separately printed tax row is present even when its amount is zero or negative, including a tax refund. Copy every matching printed tax row. Do not return null or end the list while a matching printed tax row remains."
6
+ FEE_INSTRUCTION = " A separately printed fee or surcharge row is present even when its amount is zero or negative, including a fee refund. Copy every matching printed fee or surcharge row. Do not return null or end the list while a matching printed fee or surcharge row remains."
7
+ SERVICE_INSTRUCTION = " Use the row's own printed label. Include an ordinary billed product or service charge. Exclude a row whose own label identifies it as a separately printed tax, fee, surcharge, subtotal, total or payment. A neighboring fee or tax does not exclude an otherwise eligible service row."
8
+
9
+
10
+ def prepare(
11
+ fields: dict[str, dict[str, Any]],
12
+ *,
13
+ has_media: bool = False,
14
+ fee_guidance: bool = False,
15
+ service_guidance: bool = False,
16
+ ) -> dict[str, dict[str, Any]]:
17
+ if has_media:
18
+ return fields
19
+ result = dict(fields)
20
+ for name, spec in fields.items():
21
+ item = spec.get("items")
22
+ instructions = spec.get("instructions", "")
23
+ if (
24
+ spec.get("type") != "list"
25
+ or not isinstance(item, dict)
26
+ or item.get("type") != "object"
27
+ or (not isinstance(instructions, str))
28
+ or (not isinstance(item.get("properties"), dict))
29
+ ):
30
+ continue
31
+ properties = list(item["properties"].values())
32
+ if (
33
+ len(properties) != 2
34
+ or not all((isinstance(child, dict) for child in properties))
35
+ or sum((child.get("type") == "number" for child in properties)) != 1
36
+ or (sum((child.get("type") == "text" for child in properties)) != 1)
37
+ or spec.get("knowledge")
38
+ or any((child.get("knowledge") for child in properties))
39
+ ):
40
+ continue
41
+ positive = re.split(
42
+ "[.\\n]|\\bExclude\\b", instructions, maxsplit=1, flags=re.IGNORECASE
43
+ )[0]
44
+ if re.match(
45
+ "\\s*Only\\b[^.\\n]*\\btax(?:es)?\\b[^.\\n]*\\brows\\b",
46
+ positive,
47
+ re.IGNORECASE,
48
+ ) and (
49
+ not re.search(
50
+ "\\b(?:fees?|products?|services?|goods|summar\\w*|calculat\\w*|group\\w*)\\b",
51
+ positive,
52
+ re.IGNORECASE,
53
+ )
54
+ ):
55
+ result[name] = {**spec, "instructions": instructions + TAX_INSTRUCTION}
56
+ elif (
57
+ fee_guidance
58
+ and re.match(
59
+ "\\s*Only\\b[^.\\n]*\\bfees?\\b[^.\\n]*\\brows\\b",
60
+ positive,
61
+ re.IGNORECASE,
62
+ )
63
+ and (
64
+ not re.search(
65
+ "\\b(?:tax(?:es)?|products?|services?|goods|summar\\w*|calculat\\w*|group\\w*|deduplicat\\w*|aggregat\\w*|combin\\w*|normaliz\\w*)\\b",
66
+ positive,
67
+ re.IGNORECASE,
68
+ )
69
+ )
70
+ ):
71
+ result[name] = {**spec, "instructions": instructions + FEE_INSTRUCTION}
72
+ elif (
73
+ service_guidance
74
+ and re.match(
75
+ "\\s*Only\\s+billed\\b[^.\\n]*\\brows\\b", positive, re.IGNORECASE
76
+ )
77
+ and re.search(
78
+ "\\b(?:goods|products?|services?)\\b", positive, re.IGNORECASE
79
+ )
80
+ and (
81
+ not re.search(
82
+ "\\b(?:tax(?:es)?|fees?|surcharges?|summar\\w*|calculat\\w*|group\\w*|deduplicat\\w*|aggregat\\w*|combin\\w*|normaliz\\w*)\\b",
83
+ positive,
84
+ re.IGNORECASE,
85
+ )
86
+ )
87
+ and re.search(
88
+ "\\bExclude\\b[^.\\n]*\\b(?:fees?|surcharges?)\\b",
89
+ instructions,
90
+ re.IGNORECASE,
91
+ )
92
+ ):
93
+ result[name] = {**spec, "instructions": instructions + SERVICE_INSTRUCTION}
94
+ return result
clairic_runtime/grounding.py ADDED
@@ -0,0 +1,417 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ import json
3
+ import re
4
+ import unicodedata
5
+ from decimal import Decimal, InvalidOperation, localcontext
6
+ from typing import Any
7
+ from . import ar
8
+
9
+ MAX_GRAMMAR_CHARACTERS = 4096
10
+ _STATE_ONLY = re.compile(
11
+ "\\b(?:from (?:the )?(?:accompanying (?:state )?|state )text only|supplied in the accompanying state text)\\b",
12
+ re.IGNORECASE,
13
+ )
14
+ _NULL_ABSENCE_GUARD = re.compile(
15
+ "(?:^|(?<=[.;\\n]))\\s*return\\s+null\\s+(?:only\\s+)?if\\s+(?:not\\s+(?:explicitly\\s+)?printed|absent|missing)\\s*(?:[.;]|$)",
16
+ re.IGNORECASE,
17
+ )
18
+ _EXCLUDED_SOURCE = re.compile(
19
+ "\\b(?:not|ignore|exclude|excluding)\\b[^.;:\\n]*$", re.IGNORECASE
20
+ )
21
+ _DOCUMENT = "(?:(?:this|the)(?:\\s+(?:supplied|provided))?|supplied|provided)\\s+(?:note|document|text)"
22
+ _DOCUMENT_ONLY = re.compile(
23
+ f"\\b(?:use\\s+(?:only\\s+{_DOCUMENT}|{_DOCUMENT}\\s+only)|from\\s+{_DOCUMENT}\\s+only)\\b",
24
+ re.IGNORECASE,
25
+ )
26
+ _DOCUMENT_EXCLUDED = re.compile(
27
+ "\\b(?:not|never|don't|ignore|exclude|excluding)\\b[^.;:\\n]*$", re.IGNORECASE
28
+ )
29
+ _DERIVED_NUMBER = re.compile(
30
+ "\\b(?:calculat\\w*|comput\\w*|deriv\\w*|convert\\w*|conversion\\w*|count\\w*|sum\\w*|averag\\w*|mean|median|difference|ratio|growth|product|multipli\\w*|multiply|subtract\\w*|minus|divid\\w*|division|quotient|remainder|add|adding|addition|plus|times|percent\\w*|proportion|fraction)\\b|\\b(?:how many|how much|total number of|number of (?:line )?(?:items|rows|entries|records))\\b|[+*/\\u00d7\\u00f7=]|\\s[-\\u2212]\\s",
31
+ re.IGNORECASE,
32
+ )
33
+ _CURRENCY_CODES = frozenset(
34
+ {
35
+ "USD",
36
+ "EUR",
37
+ "GBP",
38
+ "JPY",
39
+ "CNY",
40
+ "INR",
41
+ "AUD",
42
+ "CAD",
43
+ "CHF",
44
+ "HKD",
45
+ "NZD",
46
+ "SGD",
47
+ "SEK",
48
+ "NOK",
49
+ "DKK",
50
+ "KRW",
51
+ "BRL",
52
+ "MXN",
53
+ "ZAR",
54
+ }
55
+ )
56
+ _EXACT_TEXT = re.compile(
57
+ "\\b(?:verbatim|raw|literal\\w*|print\\w*|exact\\w*|characters?|digits?|whitespace|spacing|newlines?)\\b|\\b(?:line\\s+breaks?|white\\s+space|do\\s+not\\s+normaliz\\w*)\\b",
58
+ re.IGNORECASE,
59
+ )
60
+
61
+
62
+ def allows_whitespace_normalization(spec: dict[str, Any]) -> bool:
63
+ return (
64
+ spec.get("type") == "text"
65
+ and (not spec.get("knowledge"))
66
+ and ("source_only" not in spec)
67
+ and (not spec.get("_physical_row_scope"))
68
+ and (
69
+ not any(
70
+ (key in spec for key in ("enum", "pattern", "minLength", "maxLength"))
71
+ )
72
+ )
73
+ and (not _EXACT_TEXT.search(spec.get("instructions", "")))
74
+ )
75
+
76
+
77
+ def collapse_whitespace(source: str) -> tuple[str, list[tuple[int, int]]]:
78
+ (characters, offsets) = ([], [])
79
+ for match in re.finditer("\\s+|\\S", source):
80
+ characters.append(" " if match[0].isspace() else match[0])
81
+ offsets.append(match.span())
82
+ return ("".join(characters), offsets)
83
+
84
+
85
+ def state_only(spec: dict[str, Any]) -> bool:
86
+ instructions = spec.get("instructions", "")
87
+ scope = _NULL_ABSENCE_GUARD.sub("", instructions)
88
+ return (
89
+ spec["type"] in ("text", "number")
90
+ and (not spec.get("knowledge"))
91
+ and (not re.search("\\b(?:if|unless|compare|combine)\\b", scope, re.IGNORECASE))
92
+ and any(
93
+ (
94
+ not _EXCLUDED_SOURCE.search(instructions[: match.start()])
95
+ for match in _STATE_ONLY.finditer(instructions)
96
+ )
97
+ )
98
+ )
99
+
100
+
101
+ def explicit_media_scope(spec: dict[str, Any]) -> bool:
102
+ return (
103
+ spec.get("type") in ("text", "number")
104
+ and (not spec.get("knowledge"))
105
+ and bool(
106
+ re.search(
107
+ "\\b(?:page|image)\\s+\\d+\\b",
108
+ spec.get("instructions", ""),
109
+ re.IGNORECASE,
110
+ )
111
+ )
112
+ )
113
+
114
+
115
+ def document_only(spec: dict[str, Any]) -> bool:
116
+ instructions = spec.get("instructions", "")
117
+ scope = _NULL_ABSENCE_GUARD.sub("", instructions)
118
+ return (
119
+ spec["type"] in ("text", "number")
120
+ and (not spec.get("knowledge"))
121
+ and (not re.search("\\b(?:if|unless|compare|combine)\\b", scope, re.IGNORECASE))
122
+ and (not (spec["type"] == "number" and _DERIVED_NUMBER.search(scope)))
123
+ and any(
124
+ (
125
+ not _DOCUMENT_EXCLUDED.search(instructions[: match.start()])
126
+ for match in _DOCUMENT_ONLY.finditer(instructions)
127
+ )
128
+ )
129
+ )
130
+
131
+
132
+ def applies(spec: dict[str, Any], media: object | None) -> bool:
133
+ return (
134
+ spec["type"] in ("text", "number")
135
+ and media is None
136
+ and (not spec.get("knowledge", False))
137
+ and (
138
+ spec["type"] == "text"
139
+ or spec.get("source_only", False)
140
+ or state_only(spec)
141
+ or document_only(spec)
142
+ )
143
+ )
144
+
145
+
146
+ def _document_number_span(text: str, span: tuple[int, int]) -> bool:
147
+ (start, _) = span
148
+ left = start
149
+ while left and (text[left - 1].isalnum() or text[left - 1] in "_./-"):
150
+ left -= 1
151
+ prefix = text[left:start].lstrip("_./-")
152
+ return not prefix or not prefix[0].isalpha() or prefix.upper() in _CURRENCY_CODES
153
+
154
+
155
+ def _text_states(source: str, prefix: str) -> list[str]:
156
+ transitions: list[dict[str, int]]
157
+ (transitions, links, lengths) = ([{}], [-1], [0])
158
+ last = 0
159
+ for char in source:
160
+ current = len(transitions)
161
+ transitions.append({})
162
+ lengths.append(lengths[last] + 1)
163
+ links.append(0)
164
+ parent = last
165
+ while parent >= 0 and char not in transitions[parent]:
166
+ transitions[parent][char] = current
167
+ parent = links[parent]
168
+ if parent >= 0:
169
+ target = transitions[parent][char]
170
+ if lengths[parent] + 1 == lengths[target]:
171
+ links[current] = target
172
+ else:
173
+ clone = len(transitions)
174
+ transitions.append(dict(transitions[target]))
175
+ lengths.append(lengths[parent] + 1)
176
+ links.append(links[target])
177
+ while parent >= 0 and transitions[parent].get(char) == target:
178
+ transitions[parent][char] = clone
179
+ parent = links[parent]
180
+ links[target] = links[current] = clone
181
+ last = current
182
+ quote = json.dumps('"')
183
+ rules = []
184
+ for index, edges in enumerate(transitions):
185
+ choices = [quote] if index else []
186
+ for char, target in edges.items():
187
+ escaped = json.dumps(char, ensure_ascii=False)[1:-1]
188
+ choices.append(
189
+ json.dumps(escaped, ensure_ascii=False) + f" {prefix}{target}"
190
+ )
191
+ rules.append(f"{prefix}{index} ::= " + " | ".join(choices))
192
+ return rules
193
+
194
+
195
+ def text_grammar(
196
+ source: str, *, nullable: bool = True, normalized_source: str | None = None
197
+ ) -> str:
198
+ if not source:
199
+ if not nullable:
200
+ raise ValueError("Empty source permits no non-null text value")
201
+ return 'root ::= "null"'
202
+ quote = json.dumps('"')
203
+ starts = ['"null"'] if nullable else []
204
+ starts.append(quote + " s0")
205
+ states = _text_states(source, "s")
206
+ if normalized_source and normalized_source != source:
207
+ starts.append(quote + " n0")
208
+ states.extend(_text_states(normalized_source, "n"))
209
+ return "\n".join(["root ::= " + " | ".join(starts), *states])
210
+
211
+
212
+ def numbers(source: str) -> dict[Decimal, list[tuple[int, int]]]:
213
+ from .model import NUMERAL_RUN, numeral_convention, numeral_values
214
+
215
+ convention = numeral_convention(source)
216
+ result: dict[Decimal, list[tuple[int, int]]] = {}
217
+ consumed_end = 0
218
+ for run in NUMERAL_RUN.finditer(source):
219
+ if run.start() < consumed_end:
220
+ continue
221
+ readings = [(run.group(), run.start(), run.end())]
222
+ if not numeral_values(run.group(), convention):
223
+ readings = [
224
+ (m.group(), run.start() + m.start(), run.start() + m.end())
225
+ for m in re.finditer("[^, \\u00a0\\u202f\\u2009\\u2007]+", run.group())
226
+ ]
227
+ for printed, left, end in readings:
228
+ values = numeral_values(printed, convention)
229
+ if not values:
230
+ continue
231
+ exponent = re.match("[eE]([-+]?\\d+)", source[end:])
232
+ if exponent:
233
+ consumed_end = end + len(exponent[0])
234
+ if len(exponent[1]) > 4 or abs(int(exponent[1])) > 308:
235
+ continue
236
+ with localcontext() as context:
237
+ context.prec = max(context.prec, len(printed) + 310)
238
+ values = [
239
+ value * Decimal(10) ** int(exponent[1]) for value in values
240
+ ]
241
+ end += len(exponent[0])
242
+ start = left
243
+ while start > max(0, left - 32) and (
244
+ source[start - 1] in " \t-+−"
245
+ or unicodedata.category(source[start - 1]) == "Sc"
246
+ ):
247
+ start -= 1
248
+ signed = source[start:left].strip()
249
+ negative = any((c in signed for c in "-−")) and (
250
+ start == 0 or not source[start - 1].isalnum()
251
+ )
252
+ left = start + len(source[start:left]) - len(source[start:left].lstrip())
253
+ before = source[max(0, left - 32) : left]
254
+ after = source[end : end + 64]
255
+ (prefix, suffix) = (before.rstrip(), after.lstrip())
256
+ accounting = (
257
+ any(
258
+ (
259
+ c in ".," or unicodedata.category(c) == "Sc"
260
+ for c in printed + signed
261
+ )
262
+ )
263
+ or not suffix[1:].split("\n")[0].strip()
264
+ )
265
+ if prefix.endswith("(") and suffix.startswith(")") and accounting:
266
+ negative = True
267
+ left -= len(before) - len(prefix) + 1
268
+ end += len(after) - len(suffix) + 1
269
+ for value in values:
270
+ if negative:
271
+ value = value.copy_negate()
272
+ numeric = (
273
+ int(value) if value == value.to_integral_value() else float(value)
274
+ )
275
+ if Decimal(str(numeric)) != value:
276
+ continue
277
+ result.setdefault(value, []).append((left, end))
278
+ return result
279
+
280
+
281
+ class Source:
282
+ def __init__(self, text: str, *, normalize_whitespace: bool = False) -> None:
283
+ self.text = text
284
+ self.numerals = numbers(text)
285
+ self.normalize_whitespace = normalize_whitespace
286
+ self._normalized_source: tuple[str, list[tuple[int, int]]] | None = None
287
+ self._grammars: dict[tuple[bool, bool], str] = {}
288
+ self._constraints: dict[tuple[str, bool, bool], dict[str, str]] = {}
289
+
290
+ def whitespace_normalization(self, spec: dict[str, Any]) -> bool:
291
+ return self.normalize_whitespace and allows_whitespace_normalization(spec)
292
+
293
+ def _whitespace_source(self) -> tuple[str, list[tuple[int, int]]]:
294
+ if self._normalized_source is None:
295
+ self._normalized_source = collapse_whitespace(self.text)
296
+ return self._normalized_source
297
+
298
+ def normalized_span(self, value: object) -> tuple[bool, list[int] | None]:
299
+ if not isinstance(value, str) or not value:
300
+ return (False, None)
301
+ matches = set()
302
+ start = self.text.find(value)
303
+ while start >= 0:
304
+ matches.add((start, start + len(value)))
305
+ start = self.text.find(value, start + 1)
306
+ (normalized, offsets) = self._whitespace_source()
307
+ start = normalized.find(value)
308
+ while start >= 0:
309
+ matches.add((offsets[start][0], offsets[start + len(value) - 1][1]))
310
+ start = normalized.find(value, start + 1)
311
+ return (bool(matches), list(next(iter(matches))) if len(matches) == 1 else None)
312
+
313
+ def span(
314
+ self, value: object, *, spec: dict[str, Any] | None = None
315
+ ) -> tuple[bool, list[int] | None]:
316
+ if isinstance(value, str):
317
+ if spec is not None and self.whitespace_normalization(spec):
318
+ return self.normalized_span(value)
319
+ if not value:
320
+ return (False, None)
321
+ start = self.text.find(value)
322
+ if start < 0:
323
+ return (False, None)
324
+ unique = bool(value) and self.text.find(value, start + 1) < 0
325
+ return (True, [start, start + len(value)] if unique else None)
326
+ try:
327
+ number = Decimal(str(value))
328
+ except InvalidOperation:
329
+ return (False, None)
330
+ if not number.is_finite():
331
+ return (False, None)
332
+ matches = self.numerals.get(number, [])
333
+ return (bool(matches), list(matches[0]) if len(matches) == 1 else None)
334
+
335
+ def constraint(self, spec: dict[str, Any]) -> dict[str, str]:
336
+ document_numbers = (
337
+ spec["type"] == "number"
338
+ and document_only(spec)
339
+ and (not spec.get("source_only"))
340
+ and (not state_only(spec))
341
+ )
342
+ key = (
343
+ json.dumps(ar.schema(spec), ensure_ascii=False),
344
+ bool(document_numbers),
345
+ self.whitespace_normalization(spec),
346
+ )
347
+ if key not in self._constraints:
348
+ self._constraints[key] = self._constraint(
349
+ spec, document_numbers=document_numbers
350
+ )
351
+ return self._constraints[key]
352
+
353
+ def _constraint(
354
+ self, spec: dict[str, Any], *, document_numbers: bool = False
355
+ ) -> dict[str, str]:
356
+ from jsonschema import Draft202012Validator
357
+
358
+ schema = ar.schema(spec)
359
+ if spec["type"] == "number" or "enum" in schema:
360
+ numerals = self.numerals
361
+ if document_numbers:
362
+ numerals = {
363
+ value: spans
364
+ for (value, spans) in numerals.items()
365
+ if any((_document_number_span(self.text, span) for span in spans))
366
+ }
367
+ candidates = schema.get("enum", list(numerals))
368
+ validator = Draft202012Validator(schema)
369
+ values = []
370
+ for candidate in candidates:
371
+ value = candidate
372
+ if isinstance(value, Decimal):
373
+ value = (
374
+ int(value)
375
+ if value == value.to_integral_value()
376
+ else float(value)
377
+ )
378
+ if (
379
+ value is not None
380
+ and validator.is_valid(value)
381
+ and (not document_numbers or Decimal(str(value)) in numerals)
382
+ and self.span(value)[0]
383
+ ):
384
+ values.append(value)
385
+ if validator.is_valid(None):
386
+ values.append(None)
387
+ if not values:
388
+ raise ValueError(
389
+ "Field constraints permit no literal source value or null"
390
+ )
391
+ if spec["type"] == "number":
392
+ literals = [
393
+ "null" if value is None else str(Decimal(str(value)))
394
+ for value in values
395
+ ]
396
+ return {
397
+ "ebnf": "root ::= "
398
+ + " | ".join((json.dumps(value) for value in literals))
399
+ }
400
+ return {
401
+ "json_schema": json.dumps(
402
+ {**schema, "enum": values}, ensure_ascii=False
403
+ )
404
+ }
405
+ if len(self.text) > MAX_GRAMMAR_CHARACTERS or any(
406
+ (key in schema for key in ("minLength", "maxLength", "pattern"))
407
+ ):
408
+ return {"json_schema": json.dumps(schema, ensure_ascii=False)}
409
+ nullable = spec.get("nullable", True)
410
+ normalize = self.whitespace_normalization(spec)
411
+ key = (nullable, normalize)
412
+ if key not in self._grammars:
413
+ normalized = self._whitespace_source()[0] if normalize else None
414
+ self._grammars[key] = text_grammar(
415
+ self.text, nullable=nullable, normalized_source=normalized
416
+ )
417
+ return {"ebnf": self._grammars[key]}
clairic_runtime/html_rows.py ADDED
@@ -0,0 +1,132 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ import re
3
+ from html.parser import HTMLParser
4
+ from typing import Any
5
+
6
+
7
+ class _Tables(HTMLParser):
8
+ def __init__(self, source: str) -> None:
9
+ super().__init__(convert_charrefs=True)
10
+ self.source = source
11
+ self.offsets = [0]
12
+ self.offsets.extend((match.end() for match in re.finditer("\n", source)))
13
+ self.tables: list[list[dict[str, Any]]] = []
14
+ self.table: list[dict[str, Any]] | None
15
+ self.row: list[str] | None
16
+ self.cell: list[str] | None
17
+ self.cell_tag: str | None
18
+ self.cell_parts: list[tuple[str, int]] | None
19
+ self.row_spans: list[list[int] | None] | None
20
+ self.table = self.row = self.cell = None
21
+ self.cell_tag = self.cell_parts = self.row_spans = None
22
+ self.row_start: int | None = None
23
+ self.depth = 0
24
+ self.invalid = False
25
+
26
+ def position(self) -> int:
27
+ (line, column) = self.getpos()
28
+ return self.offsets[line - 1] + column
29
+
30
+ def handle_starttag(
31
+ self, tag: str, attrs: list[tuple[str, str | None]] | dict[str, str | None]
32
+ ) -> None:
33
+ if tag == "table":
34
+ self.depth += 1
35
+ if self.depth != 1:
36
+ self.invalid = True
37
+ else:
38
+ self.table = []
39
+ if not self.depth:
40
+ return
41
+ attrs = dict(attrs)
42
+ if (
43
+ "hidden" in attrs
44
+ or (attrs.get("aria-hidden") or "").lower() == "true"
45
+ or re.search(
46
+ "(?:display\\s*:\\s*none|visibility\\s*:\\s*hidden)",
47
+ attrs.get("style") or "",
48
+ re.IGNORECASE,
49
+ )
50
+ or (tag in ("script", "style"))
51
+ ):
52
+ self.invalid = True
53
+ if tag == "tr":
54
+ if self.row is not None or self.cell is not None:
55
+ self.invalid = True
56
+ (self.row, self.row_start, self.row_spans) = ([], self.position(), [])
57
+ elif tag in ("td", "th"):
58
+ if self.row is None or self.cell is not None:
59
+ self.invalid = True
60
+ if attrs.get("rowspan", "1") != "1" or attrs.get("colspan", "1") != "1":
61
+ self.invalid = True
62
+ (self.cell, self.cell_tag, self.cell_parts) = ([], tag, [])
63
+ elif tag in ("br", "p", "div", "ul", "ol", "li") and self.cell is not None:
64
+ self.cell.append(" ")
65
+
66
+ def handle_data(self, data: str) -> None:
67
+ if self.cell is not None:
68
+ self.cell.append(data)
69
+ self.cell_parts.append((data, self.position()))
70
+ elif self.row is not None and data.strip():
71
+ self.invalid = True
72
+
73
+ def handle_endtag(self, tag: str) -> None:
74
+ if not self.depth:
75
+ return
76
+ if tag in ("td", "th"):
77
+ if self.cell is None or self.row is None or tag != self.cell_tag:
78
+ self.invalid = True
79
+ else:
80
+ value = re.sub("\\s+", " ", "".join(self.cell)).strip()
81
+ self.row.append(value)
82
+ matches = [
83
+ position + data.find(value)
84
+ for (data, position) in self.cell_parts
85
+ if value
86
+ and data.count(value) == 1
87
+ and self.source.startswith(value, position + data.find(value))
88
+ ]
89
+ self.row_spans.append(
90
+ [matches[0], matches[0] + len(value)] if len(matches) == 1 else None
91
+ )
92
+ self.cell = self.cell_tag = self.cell_parts = None
93
+ elif tag == "tr":
94
+ if self.row is None or self.cell is not None or self.table is None:
95
+ self.invalid = True
96
+ else:
97
+ end = self.source.find(">", self.position()) + 1
98
+ self.table.append(
99
+ {
100
+ "cells": self.row,
101
+ "line": self.source[self.row_start : end],
102
+ "offset": self.row_start,
103
+ "spans": self.row_spans,
104
+ }
105
+ )
106
+ self.row = self.row_start = self.row_spans = None
107
+ elif tag == "table":
108
+ if self.depth == 1:
109
+ if self.row is not None or self.cell is not None:
110
+ self.invalid = True
111
+ self.tables.append(self.table)
112
+ self.table = None
113
+ self.depth -= 1
114
+ elif tag in ("p", "div", "ul", "ol", "li") and self.cell is not None:
115
+ self.cell.append(" ")
116
+
117
+
118
+ def tables(source: str) -> list[list[dict[str, Any]]] | None:
119
+ parser = _Tables(source)
120
+ try:
121
+ parser.feed(source)
122
+ parser.close()
123
+ except (ValueError, TypeError):
124
+ return None
125
+ if (
126
+ parser.invalid
127
+ or parser.depth
128
+ or parser.row is not None
129
+ or (parser.cell is not None)
130
+ ):
131
+ return None
132
+ return parser.tables
clairic_runtime/identifier_scope.py ADDED
@@ -0,0 +1,89 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ import re
3
+ from typing import Any
4
+
5
+ ROLE_NOTE = " Select the value by its printed label and requested role. Do not infer the role from the spelling or prefix of an identifier. A similar-looking value under another label is not the requested value. Return null if that role is absent."
6
+ _GENERIC_NAMES = {"reference", "value"}
7
+ _PURCHASE_ORDER = re.compile("\\bpurchase[\\s-]+order\\s+reference\\b", re.IGNORECASE)
8
+ _LITERAL = re.compile(
9
+ "\\b(?:exact|printed|verbatim|copy|extract|read)\\b", re.IGNORECASE
10
+ )
11
+ _EXCLUDED = re.compile(
12
+ "\\b(?:not|exclude|excluding|ignore|rather than)\\b[^.;:\\n]*$", re.IGNORECASE
13
+ )
14
+ _OTHER_ROLE = re.compile(
15
+ "\\b(?:invoice|receipt|payment|tracking|sales[\\s-]+order|account)\\s+(?:reference|number|identifier|id|code)\\b",
16
+ re.IGNORECASE,
17
+ )
18
+ _TRANSFORM = re.compile(
19
+ "\\b(?:compare|combine|join|concatenate|compute|calculate|sum|count|hash|mask|normalize|convert|format|summarize|(?:first|last)\\s+\\d+)\\b",
20
+ re.IGNORECASE,
21
+ )
22
+ _STATE_TEXT = re.compile(
23
+ "\\b(?:state|accompanying)\\s+(?:state\\s+)?text\\b", re.IGNORECASE
24
+ )
25
+ _QUOTED_LITERAL_TARGET = re.compile(
26
+ "\\b(?:copy|extract|read|return)\\s+(?:the\\s+)?(?:(?:exact|printed|literal|verbatim)\\s+)*(?:phrase|words?|sentence|string)\\s*:?\\s*(?:\"([^\"\\n]+)\"|'([^'\\n]+)'|“([^”\\n]+)”|‘([^’\\n]+)’|`([^`\\n]+)`)",
27
+ re.IGNORECASE,
28
+ )
29
+ _LITERAL_COMMAND_NEGATION = re.compile(
30
+ "\\b(?:never|don['’]t)\\b[^.;:\\n]*$", re.IGNORECASE
31
+ )
32
+
33
+
34
+ def _positive(pattern: re.Pattern[str], instructions: str) -> bool:
35
+ return any(
36
+ (
37
+ not _EXCLUDED.search(instructions[: match.start()])
38
+ for match in pattern.finditer(instructions)
39
+ )
40
+ )
41
+
42
+
43
+ def _literal_target(instructions: str) -> bool:
44
+ for match in _QUOTED_LITERAL_TARGET.finditer(instructions):
45
+ prefix = instructions[: match.start()]
46
+ if not (_EXCLUDED.search(prefix) or _LITERAL_COMMAND_NEGATION.search(prefix)):
47
+ if any(
48
+ (
49
+ _PURCHASE_ORDER.search(text)
50
+ for text in match.groups()
51
+ if text is not None
52
+ )
53
+ ):
54
+ return True
55
+ return False
56
+
57
+
58
+ def prepare_fields(
59
+ fields: dict[str, dict[str, Any]], *, has_media: bool
60
+ ) -> tuple[dict[str, dict[str, Any]], dict[str, str]]:
61
+ if not has_media:
62
+ return (fields, {})
63
+ (changed, labels) = ({}, {})
64
+ for name, spec in fields.items():
65
+ if (
66
+ not isinstance(name, str)
67
+ or name.casefold() not in _GENERIC_NAMES
68
+ or (not isinstance(spec, dict))
69
+ or (spec.get("type") != "text")
70
+ or spec.get("knowledge")
71
+ or (spec.get("nullable", True) is False)
72
+ or ("enum" in spec)
73
+ ):
74
+ continue
75
+ instructions = spec.get("instructions", "")
76
+ if (
77
+ not isinstance(instructions, str)
78
+ or not _LITERAL.search(instructions)
79
+ or _TRANSFORM.search(instructions)
80
+ or _STATE_TEXT.search(instructions)
81
+ or _literal_target(instructions)
82
+ or (not _positive(_PURCHASE_ORDER, instructions))
83
+ or _positive(_OTHER_ROLE, instructions)
84
+ ):
85
+ continue
86
+ if not instructions.endswith(ROLE_NOTE):
87
+ changed[name] = {**spec, "instructions": instructions + ROLE_NOTE}
88
+ labels[name] = "purchase_order_reference"
89
+ return ({**fields, **changed} if changed else fields, labels)
clairic_runtime/identifier_spelling.py ADDED
@@ -0,0 +1,281 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ from collections.abc import Callable
3
+ from typing import TYPE_CHECKING, Any
4
+
5
+ if TYPE_CHECKING:
6
+ from .api import PredictRequest
7
+ from .backend import EncodedRequest
8
+ from copy import deepcopy
9
+ from jsonschema import Draft202012Validator, ValidationError
10
+ from . import ar, identifier_scope
11
+
12
+ VERSION = "identifier-codepoint-spelling-v1"
13
+ PDF_VIEW_ID = "pdf-po-codepoint-spelling-focus-v1"
14
+ MANY_IMAGE_VIEW_ID = "po-three-four-images-detail3-800000px-v2"
15
+ MANY_IMAGE_MAX_PIXELS = 800000
16
+ INSTRUCTION = "Spell the printed purchase order reference with one space between each individual character. Preserve the actual characters; do not normalize letters and digits."
17
+
18
+
19
+ def decode_wire(value: object) -> str:
20
+ if not isinstance(value, str):
21
+ raise ValueError("Identifier spelling wire must be a string")
22
+ if any((55296 <= ord(character) <= 57343 for character in value)):
23
+ raise ValueError("Identifier spelling wire contains an unpaired surrogate")
24
+ if value and (
25
+ len(value) % 2 == 0 or any((character != " " for character in value[1::2]))
26
+ ):
27
+ raise ValueError("Invalid identifier spelling separators")
28
+ return value[::2]
29
+
30
+
31
+ def prepare(
32
+ record: dict[str, Any],
33
+ public_fields: dict[str, dict[str, Any]],
34
+ query_labels: dict[str, str],
35
+ *,
36
+ has_media: bool,
37
+ ) -> dict[str, Any]:
38
+ if not has_media or not query_labels:
39
+ return record
40
+ (_, eligible) = identifier_scope.prepare_fields(public_fields, has_media=True)
41
+ contracts = {}
42
+ for name, label in query_labels.items():
43
+ if label != "purchase_order_reference" or eligible.get(name) != label:
44
+ continue
45
+ public = public_fields[name]
46
+ spec = record["fields"][name]
47
+ wire = {
48
+ key: value
49
+ for (key, value) in spec.items()
50
+ if key not in {"minLength", "maxLength", "pattern"}
51
+ }
52
+ wire["instructions"] = INSTRUCTION + "\n" + spec.get("instructions", "")
53
+ record["fields"][name] = wire
54
+ contracts[name] = {
55
+ "scalar": deepcopy(public),
56
+ "wire": VERSION,
57
+ "query_name": name,
58
+ }
59
+ if contracts:
60
+ record["_meta"]["identifier_spelling"] = contracts
61
+ return record
62
+
63
+
64
+ def normalize_predictions(
65
+ record: dict[str, Any], predictions: dict[str, dict[str, Any]]
66
+ ) -> dict[str, dict[str, Any]]:
67
+ result = dict(predictions)
68
+ for name, contract in (
69
+ record.get("_meta", {}).get("identifier_spelling", {}).items()
70
+ ):
71
+ original = result.get(name)
72
+ if (
73
+ original is None
74
+ or not original.get("valid")
75
+ or (not original.get("complete"))
76
+ or (original.get("wire_decoder") == VERSION)
77
+ ):
78
+ continue
79
+ answer = dict(original)
80
+ wire = original["value"]
81
+ answer.update(
82
+ wire_value=wire,
83
+ wire_decoder=VERSION,
84
+ native_decoder=original.get("decoder"),
85
+ decoder=ar.VERSION + "+" + VERSION,
86
+ score_representation="native_json_codepoint_spelling_wire",
87
+ )
88
+ if answer.get("span") is not None:
89
+ answer["native_wire_span"] = answer["span"]
90
+ if "span_method" in answer:
91
+ answer["native_wire_span_method"] = answer.pop("span_method")
92
+ answer["span"] = None
93
+ try:
94
+ decoded = None if wire is None else decode_wire(wire)
95
+ Draft202012Validator(ar.schema(contract["scalar"])).validate(decoded)
96
+ answer["value"] = decoded
97
+ except (ValueError, TypeError, ValidationError):
98
+ answer.update(
99
+ value=None, valid=False, failure_reason="invalid_identifier_spelling"
100
+ )
101
+ result[name] = answer
102
+ return result
103
+
104
+
105
+ def prepare_pdf_tasks(
106
+ request: PredictRequest,
107
+ encoded: EncodedRequest,
108
+ encode: Callable[..., EncodedRequest],
109
+ *,
110
+ enabled: bool,
111
+ ) -> EncodedRequest:
112
+ if not enabled or not request.documents:
113
+ return encoded
114
+ (record, forecasts, tasks, typed, eos) = encoded
115
+ active = {name for (name, _, _) in tasks}
116
+ selected = {
117
+ name: request.fields[name]
118
+ for (name, contract) in record.get("_meta", {})
119
+ .get("identifier_spelling", {})
120
+ .items()
121
+ if name in active and contract.get("wire") == VERSION
122
+ }
123
+ originals = record.get("_original_images", ())
124
+ pdf_pages = originals[len(request.images) :]
125
+ if not selected or not pdf_pages:
126
+ return encoded
127
+ child_request = request.model_copy(update={"fields": selected})
128
+ (child, _, replacements, child_typed, child_eos) = encode(
129
+ child_request,
130
+ identifier_view=True,
131
+ pdf_spelling_view=True,
132
+ image_views=lambda: originals,
133
+ image_view_key=PDF_VIEW_ID,
134
+ )
135
+ if child_typed is not None or child_eos != eos:
136
+ raise ValueError("A PDF PO spelling view must retain the scalar AR contract")
137
+ by_name = {name: (name, ids, media) for (name, ids, media) in replacements}
138
+ if set(by_name) != set(selected):
139
+ raise ValueError("PDF PO spelling tasks differ from the selected public fields")
140
+ updated = [by_name.get(task[0], task) for task in tasks]
141
+ salts = dict(record.get("_ar_task_salts", {}))
142
+ for name in selected:
143
+ record["fields"][name] = child["fields"][name]
144
+ record["_ar_constraints"][name] = child["_ar_constraints"][name]
145
+ salts[name] = child["_cache_salt"]
146
+ record["_meta"]["identifier_spelling_pdf_view"] = {
147
+ "version": PDF_VIEW_ID,
148
+ "fields": list(selected),
149
+ "image_count": len(originals),
150
+ "pdf_page_count": len(pdf_pages),
151
+ }
152
+ record.update(
153
+ _ar_tasks=updated, _ar_task_salts=salts, _ar_prefix=[], _ar_group_prefixes=[]
154
+ )
155
+ return (record, forecasts, updated, typed, eos)
156
+
157
+
158
+ def prepare_fallback(
159
+ request: PredictRequest,
160
+ encoded: EncodedRequest,
161
+ encode: Callable[..., EncodedRequest],
162
+ ) -> EncodedRequest:
163
+ (record, _, tasks, _, eos) = encoded
164
+ contracts = record.get("_meta", {}).get("identifier_spelling", {})
165
+ active = {name for (name, _, _) in tasks}
166
+ selected = {name: request.fields[name] for name in contracts if name in active}
167
+ if not selected:
168
+ return encoded
169
+ child_request = request.model_copy(update={"fields": selected})
170
+ (child, _, child_tasks, child_typed, child_eos) = encode(
171
+ child_request, identifier_spelling_disabled=True
172
+ )
173
+ if (
174
+ child_typed is not None
175
+ or child_eos != eos
176
+ or {name for (name, _, _) in child_tasks} != set(selected)
177
+ or child.get("_meta", {}).get("identifier_spelling")
178
+ ):
179
+ raise ValueError(
180
+ "Identifier spelling fallback must retain the original scalar contract"
181
+ )
182
+ record["_identifier_spelling_fallback"] = child
183
+ return encoded
184
+
185
+
186
+ def prepare_many_image_tasks(
187
+ request: PredictRequest,
188
+ encoded: EncodedRequest,
189
+ encode: Callable[..., EncodedRequest],
190
+ ) -> EncodedRequest:
191
+ if request.documents or len(request.images) not in (3, 4):
192
+ return encoded
193
+ (record, forecasts, tasks, typed, eos) = encoded
194
+ active = {name for (name, _, _) in tasks}
195
+ selected = {
196
+ name: request.fields[name]
197
+ for (name, contract) in record.get("_meta", {})
198
+ .get("identifier_spelling", {})
199
+ .items()
200
+ if name in active and contract.get("wire") == VERSION
201
+ }
202
+ if not selected:
203
+ return encoded
204
+ originals = record.get("_original_images", ())
205
+ if len(originals) != len(request.images):
206
+ raise ValueError("PO detail view must retain every original image in order")
207
+ (child, _, replacements, child_typed, child_eos) = encode(
208
+ request.model_copy(update={"fields": selected}),
209
+ identifier_view=True,
210
+ po_detail_view=True,
211
+ image_views=lambda: originals,
212
+ image_view_key=MANY_IMAGE_VIEW_ID,
213
+ )
214
+ if child_typed is not None or child_eos != eos:
215
+ raise ValueError("A PO image detail view must retain the scalar AR contract")
216
+ by_name = {name: (name, ids, media) for (name, ids, media) in replacements}
217
+ if set(by_name) != set(selected):
218
+ raise ValueError("PO image detail tasks differ from the selected public fields")
219
+ updated = [by_name.get(task[0], task) for task in tasks]
220
+ salts = dict(record.get("_ar_task_salts", {}))
221
+ for name in selected:
222
+ record["fields"][name] = child["fields"][name]
223
+ record["_ar_constraints"][name] = child["_ar_constraints"][name]
224
+ salts[name] = child["_cache_salt"]
225
+ record["_meta"]["identifier_spelling_image_view"] = {
226
+ "version": MANY_IMAGE_VIEW_ID,
227
+ "fields": list(selected),
228
+ "image_count": len(originals),
229
+ "max_scale": 3.0,
230
+ "max_pixels": MANY_IMAGE_MAX_PIXELS,
231
+ }
232
+ record.update(
233
+ _ar_tasks=updated, _ar_task_salts=salts, _ar_prefix=[], _ar_group_prefixes=[]
234
+ )
235
+ return (record, forecasts, updated, typed, eos)
236
+
237
+
238
+ def fallback_record(
239
+ record: dict[str, Any], predictions: dict[str, dict[str, Any]]
240
+ ) -> dict[str, Any] | None:
241
+ selected = {
242
+ name
243
+ for (name, prediction) in predictions.items()
244
+ if prediction.get("failure_reason") == "invalid_identifier_spelling"
245
+ }
246
+ fallback = record.get("_identifier_spelling_fallback")
247
+ if not selected or fallback is None:
248
+ return None
249
+ tasks = [task for task in fallback["_ar_tasks"] if task[0] in selected]
250
+ return (
251
+ {
252
+ **fallback,
253
+ "_ar_tasks": tasks,
254
+ "_ar_prefix": [],
255
+ "_ar_group_prefixes": [],
256
+ "_ar_media_groups": [],
257
+ "_null_recovery": True,
258
+ }
259
+ if tasks
260
+ else None
261
+ )
262
+
263
+
264
+ def merge_fallback(
265
+ predictions: dict[str, dict[str, Any]],
266
+ alternatives: dict[str, dict[str, Any]],
267
+ fallback: dict[str, Any],
268
+ ) -> dict[str, dict[str, Any]]:
269
+ result = dict(predictions)
270
+ lengths = {name: len(ids) for (name, ids, _) in fallback["_ar_tasks"]}
271
+ for name, alternative in alternatives.items():
272
+ original = predictions[name]
273
+ result[name] = {
274
+ **alternative,
275
+ "identifier_spelling_fallback": True,
276
+ "identifier_spelling_attempt": dict(original),
277
+ "score_representation": "native_json_scalar_fallback",
278
+ "tokens": original["tokens"] + alternative["tokens"],
279
+ "retry_input_tokens": original.get("retry_input_tokens", 0) + lengths[name],
280
+ }
281
+ return result
clairic_runtime/image_financial_lines.py ADDED
@@ -0,0 +1,393 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ from collections.abc import Callable
3
+ from typing import TYPE_CHECKING, Any
4
+
5
+ if TYPE_CHECKING:
6
+ from .api import PredictRequest
7
+ from .backend import EncodedRequest
8
+ import math
9
+ import re
10
+ from copy import deepcopy
11
+ import numpy as np
12
+ from jsonschema import Draft202012Validator, ValidationError
13
+ from PIL import Image
14
+ from . import ar, image_ragged_rows, image_table_rows, printed_numbers
15
+ from .schema import MAX_LIST_ITEMS
16
+
17
+ LINE = {
18
+ "type": "text",
19
+ "nullable": False,
20
+ "instructions": "Copy the complete single printed line verbatim, including all words, prefixes, punctuation and numbers. Do not extract a name or normalize any part. Return only the complete line.",
21
+ }
22
+ _TAX = re.compile("\\btax(?:es)?(?:\\s+(?:refund|credit|adjustment))?$", re.IGNORECASE)
23
+ _FEE = re.compile(
24
+ "\\b(?:fees?|surcharges?)(?:\\s+(?:refund|credit|adjustment))?$", re.IGNORECASE
25
+ )
26
+ _SUMMARY = re.compile(
27
+ "(?:sub[ -]?total|grand total|total|amount due|balance(?: due| forward)?|tax total|fee total)",
28
+ re.IGNORECASE,
29
+ )
30
+ _PAYMENT = re.compile(
31
+ "^(?:payments?\\s+(?:received|instructions?|due|method|status)|(?:received|posted|applied)\\s+payments?)\\b|\\bpayments?$",
32
+ re.IGNORECASE,
33
+ )
34
+ _TRANSFORM = re.compile(
35
+ "\\b(?:deduplicat\\w*|unique|aggregat\\w*|summari[sz]\\w*|combin\\w*|group\\w*|averag\\w*|calculat\\w*|normaliz\\w*|convert\\w*|except|unless|instead|knowledge)\\b",
36
+ re.IGNORECASE,
37
+ )
38
+ _CELL = "\\(?[+-]?\\$?[\\d,]+\\.\\d{2}\\)?"
39
+ _SCOPE_WORDS = {
40
+ "only",
41
+ "explicit",
42
+ "printed",
43
+ "separately",
44
+ "tax",
45
+ "taxes",
46
+ "row",
47
+ "rows",
48
+ "fee",
49
+ "fees",
50
+ "billed",
51
+ "goods",
52
+ "product",
53
+ "products",
54
+ "services",
55
+ "service",
56
+ "charge",
57
+ "charges",
58
+ "exclude",
59
+ "excluding",
60
+ "all",
61
+ "subtotal",
62
+ "subtotals",
63
+ "total",
64
+ "totals",
65
+ "grand",
66
+ "payment",
67
+ "payments",
68
+ "amount",
69
+ "due",
70
+ "and",
71
+ "or",
72
+ "null",
73
+ "if",
74
+ "no",
75
+ "when",
76
+ "the",
77
+ "document",
78
+ "has",
79
+ "a",
80
+ "must",
81
+ "be",
82
+ "surcharge",
83
+ "surcharges",
84
+ "return",
85
+ "instructions",
86
+ }
87
+
88
+
89
+ def role(label: str) -> str:
90
+ label = " ".join(label.split()).rstrip(": ")
91
+ if _SUMMARY.fullmatch(label):
92
+ return "summary"
93
+ if _PAYMENT.search(label):
94
+ return "payment"
95
+ if _TAX.search(label):
96
+ return "tax"
97
+ return "fee" if _FEE.search(label) else "charge"
98
+
99
+
100
+ def scope(spec: dict[str, Any]) -> str | None:
101
+ item = spec.get("items")
102
+ if (
103
+ spec.get("type") != "list"
104
+ or spec.get("knowledge")
105
+ or (not isinstance(item, dict))
106
+ ):
107
+ return None
108
+ properties = item.get("properties", {})
109
+ if item.get("type") != "object" or len(properties) != 2:
110
+ return None
111
+ if any(
112
+ (
113
+ not isinstance(child, dict) or child.get("knowledge")
114
+ for child in properties.values()
115
+ )
116
+ ):
117
+ return None
118
+ if sorted((child.get("type", "") for child in properties.values())) != [
119
+ "number",
120
+ "text",
121
+ ]:
122
+ return None
123
+ amount = next((child for child in properties.values() if child["type"] == "number"))
124
+ if amount.get("decimals") != 2 or amount.get("unit") or amount.get("integer"):
125
+ return None
126
+ instructions = spec.get("instructions", "")
127
+ if not isinstance(instructions, str) or _TRANSFORM.search(instructions):
128
+ return None
129
+ if set(re.findall("[a-z]+", instructions.lower())) - _SCOPE_WORDS:
130
+ return None
131
+ if any(
132
+ (
133
+ set(child) - {"type", "instructions", "nullable", "decimals"}
134
+ for child in properties.values()
135
+ )
136
+ ):
137
+ return None
138
+ if any(
139
+ (
140
+ _TRANSFORM.search(child.get("instructions", ""))
141
+ for child in properties.values()
142
+ )
143
+ ):
144
+ return None
145
+ positive = re.split(
146
+ "[.\\n]|\\bExclude\\b", instructions, maxsplit=1, flags=re.IGNORECASE
147
+ )[0].strip()
148
+ if re.fullmatch(
149
+ "Only\\s+(?:(?:explicit|printed|separately\\s+printed)\\s+)?tax(?:es)?\\s+rows",
150
+ positive,
151
+ re.IGNORECASE,
152
+ ):
153
+ return "tax"
154
+ if re.fullmatch(
155
+ "Only\\s+(?:(?:explicit|printed|separately\\s+printed)\\s+)?fees?\\s+rows",
156
+ positive,
157
+ re.IGNORECASE,
158
+ ):
159
+ return "fee"
160
+ if (
161
+ re.fullmatch(
162
+ "Only\\s+billed\\s+(?:(?:goods?|products?|services?)\\s+(?:(?:and|or)\\s+)?)+(?:charge\\s+)?rows",
163
+ positive,
164
+ re.IGNORECASE,
165
+ )
166
+ and all(
167
+ (
168
+ re.search(
169
+ "\\bExclude\\b[^.\\n]*\\b" + token + "\\b",
170
+ instructions,
171
+ re.IGNORECASE,
172
+ )
173
+ for token in ("tax(?:es)?", "fees?", "payments?")
174
+ )
175
+ )
176
+ and (
177
+ not re.search("\\b(?:not|never)\\s+exclude\\b", instructions, re.IGNORECASE)
178
+ )
179
+ ):
180
+ return "charge"
181
+ return None
182
+
183
+
184
+ def parse(line: object) -> tuple[str, int | float | None] | None:
185
+ if not isinstance(line, str):
186
+ raise TypeError("Missing literal image line")
187
+ match = re.fullmatch("(.*?)\\s*(?:\\||:)\\s*(" + _CELL + ")\\s*\\|?\\s*", line)
188
+ if not match:
189
+ match = re.fullmatch("(.*?)\\s+(\\(?[+-]?\\$[\\d,]+\\.\\d{2}\\)?)\\s*", line)
190
+ if not match:
191
+ return None
192
+ label = match[1].rstrip(" |:")
193
+ if not label or "|" in label:
194
+ return None
195
+ return (
196
+ label,
197
+ printed_numbers.normalize(match[2], {"type": "number", "decimals": 2}),
198
+ )
199
+
200
+
201
+ def bands(image: Image.Image) -> list[tuple[int, int]] | None:
202
+ if (
203
+ image.mode != "RGB"
204
+ or image.width < 100
205
+ or image.getpixel((0, 0)) != (255, 255, 255)
206
+ ):
207
+ return None
208
+ ink = np.asarray(image.convert("L")) < 200
209
+ if np.mean(ink) > 0.22:
210
+ return None
211
+ rows = image_table_rows._runs(ink.any(axis=1))
212
+ if not 2 <= len(rows) <= MAX_LIST_ITEMS or any(
213
+ (not 8 <= bottom - top <= 32 for (top, bottom) in rows)
214
+ ):
215
+ return None
216
+ return rows
217
+
218
+
219
+ def prepare(
220
+ request: PredictRequest,
221
+ encoded: EncodedRequest,
222
+ encode: Callable[..., EncodedRequest],
223
+ ) -> EncodedRequest:
224
+ (record, forecasts, tasks, typed, eos) = encoded
225
+ annotations = record["_meta"]["extraction_contract"]["fields"]
226
+ selected = {
227
+ name: kind
228
+ for (name, spec) in request.fields.items()
229
+ if (kind := scope(spec)) and annotations.get(name, {}).get("query_fields")
230
+ }
231
+ if not selected or len(request.images) != 1 or request.documents:
232
+ return encoded
233
+ originals = record.get("_original_images")
234
+ image = originals[0] if originals else request.images[0].to_pil()
235
+ rows = bands(image)
236
+ if rows is None:
237
+ return encoded
238
+ if (
239
+ image_table_rows.detect(image) is not None
240
+ or image_ragged_rows.detect(image) is not None
241
+ ):
242
+ selected = {name: kind for (name, kind) in selected.items() if kind != "charge"}
243
+ if not selected:
244
+ return encoded
245
+ salts = dict(record.get("_ar_task_salts", {}))
246
+
247
+ def add(child_request: PredictRequest, **options: Any) -> list[str]:
248
+ (child, _, prepared, _, _) = encode(
249
+ child_request, physical_row_view=True, **options
250
+ )
251
+ names = []
252
+ for source, ids, payload in prepared:
253
+ target = "financial_line_" + str(len(record["fields"]))
254
+ while target in record["fields"]:
255
+ target += "_"
256
+ record["fields"][target] = child["fields"][source]
257
+ record["_ar_constraints"][target] = child["_ar_constraints"][source]
258
+ salts[target] = child["_cache_salt"]
259
+ tasks.append((target, ids, payload))
260
+ names.append(target)
261
+ return names
262
+
263
+ tasks = list(tasks)
264
+ queries = []
265
+ for top, bottom in rows:
266
+ view = image.crop(
267
+ (0, max(0, top - 3), image.width, min(image.height, bottom + 3))
268
+ )
269
+ view = view.resize((view.width * 2, view.height * 2), Image.Resampling.BICUBIC)
270
+ child_request = request.model_copy(update={"fields": {"printed_line": LINE}})
271
+ queries.extend(
272
+ add(
273
+ child_request,
274
+ image_views=lambda view=view: (view,),
275
+ image_view_key=f"financial-line-v1:{top}:{bottom}",
276
+ )
277
+ )
278
+ plans = {}
279
+ for name, kind in selected.items():
280
+ spec = request.fields[name]
281
+ presence = {
282
+ "type": "enum",
283
+ "enum": [True, None],
284
+ "nullable": True,
285
+ "instructions": "Decide whether at least one printed row satisfies this requested list scope. "
286
+ + spec.get("instructions", "")
287
+ + " Return true if any matching printed row exists; return null only if there are no matching rows. A matching row with amount zero or a negative amount is present. Check the row's own label; a neighboring tax or fee does not remove an eligible service row. This asks only whether a matching row exists, not its value or row count.",
288
+ }
289
+ gate = add(request.model_copy(update={"fields": {name: presence}}))[0]
290
+ previous = annotations[name].pop("query_fields")
291
+ tasks = [task for task in tasks if task[0] not in {name, *previous}]
292
+ for child in previous:
293
+ record["fields"].pop(child)
294
+ record["_ar_constraints"].pop(child, None)
295
+ annotations.pop(child, None)
296
+ plans[name] = {"kind": kind, "presence": gate, "spec": deepcopy(spec)}
297
+ record.update(
298
+ _financial_line_queries=queries,
299
+ _financial_line_plans=plans,
300
+ _ar_tasks=tasks,
301
+ _ar_task_salts=salts,
302
+ _ar_prefix=[],
303
+ _ar_group_prefixes=[],
304
+ )
305
+ return (record, forecasts, tasks, typed, eos)
306
+
307
+
308
+ def assemble(
309
+ record: dict[str, Any], predictions: dict[str, dict[str, Any]]
310
+ ) -> dict[str, dict[str, Any]]:
311
+ queries = record.get("_financial_line_queries", [])
312
+ if not queries:
313
+ return {}
314
+ copies = [predictions[query] for query in queries]
315
+ (parsed, parse_valid) = ([], True)
316
+ for answer in copies:
317
+ try:
318
+ parsed.append(
319
+ parse(answer["value"]) if isinstance(answer.get("value"), str) else None
320
+ )
321
+ except (ValueError, TypeError, OverflowError):
322
+ parsed.append(None)
323
+ parse_valid = False
324
+ result = {}
325
+ for name, plan in record["_financial_line_plans"].items():
326
+ spec = plan["spec"]
327
+ properties = spec["items"]["properties"]
328
+ text = next(
329
+ (key for (key, value) in properties.items() if value["type"] == "text")
330
+ )
331
+ number = next(
332
+ (key for (key, value) in properties.items() if value["type"] == "number")
333
+ )
334
+ selected = [
335
+ (answer, row)
336
+ for (answer, row) in zip(copies, parsed, strict=True)
337
+ if row is not None and role(row[0]) == plan["kind"]
338
+ ]
339
+ values = [{text: row[0], number: row[1]} for (_, row) in selected]
340
+ presence = predictions[plan["presence"]]
341
+ relevant = [*copies, presence]
342
+ complete = all((answer.get("complete", False) for answer in relevant))
343
+ valid = (
344
+ parse_valid
345
+ and complete
346
+ and all((answer.get("valid", False) for answer in relevant))
347
+ )
348
+ valid &= len(values) <= spec.get("max_items", MAX_LIST_ITEMS)
349
+ try:
350
+ for value in values:
351
+ Draft202012Validator(ar.schema(spec["items"])).validate(value)
352
+ except ValidationError:
353
+ valid = False
354
+ p_null = presence["p_null"]
355
+ if (
356
+ type(p_null) not in (int, float)
357
+ or not math.isfinite(p_null)
358
+ or (not 0 <= p_null <= 1)
359
+ or any(
360
+ (
361
+ type(answer.get("log_probability")) not in (int, float)
362
+ or not math.isfinite(answer["log_probability"])
363
+ or answer["log_probability"] > 0
364
+ for answer in copies
365
+ )
366
+ )
367
+ ):
368
+ raise ValueError("Invalid financial-line model scores")
369
+ event = 1 - p_null if values else p_null
370
+ probability = (
371
+ sum((answer["log_probability"] for answer in copies)) + math.log(event)
372
+ if event > 0
373
+ else None
374
+ )
375
+ answer = {
376
+ "value": values,
377
+ "valid": bool(valid),
378
+ "complete": complete,
379
+ "confidence": 0.0,
380
+ "confidence_method": "ar_literal_image_lines_and_scope_presence_probability",
381
+ "confidences": [copy["confidence"] for (copy, _) in selected],
382
+ "p_null": p_null,
383
+ "p_null_method": "ar_parent_scope_presence_null_probability",
384
+ "p_nulls": [copy["p_null"] for (copy, _) in selected],
385
+ "spans": [None] * len(selected),
386
+ }
387
+ if probability is not None:
388
+ answer.update(
389
+ log_probability=probability,
390
+ confidence=math.exp(probability) if valid else 0.0,
391
+ )
392
+ result[name] = answer
393
+ return result
clairic_runtime/image_focus.py ADDED
@@ -0,0 +1,48 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ from typing import Any
3
+ from PIL import Image, ImageChops
4
+
5
+ COPY_INSTRUCTION = " Copy the complete printed value verbatim, including every digit, punctuation and suffix. Do not shorten, sanitize or canonicalize it."
6
+
7
+
8
+ def preserve_scalar_fields(
9
+ fields: dict[str, dict[str, Any]],
10
+ ) -> dict[str, dict[str, Any]]:
11
+ return {
12
+ name: {**spec, "instructions": spec.get("instructions", "") + COPY_INSTRUCTION}
13
+ if spec.get("type") == "text"
14
+ and (not spec.get("knowledge"))
15
+ and isinstance(spec.get("instructions", ""), str)
16
+ else spec
17
+ for (name, spec) in fields.items()
18
+ }
19
+
20
+
21
+ def focus_document(
22
+ image: Image.Image, *, max_pixels: int = 1600000, max_scale: float = 2.0
23
+ ) -> Image.Image:
24
+ if image.mode != "RGB":
25
+ return image
26
+ bounds = ImageChops.difference(
27
+ image, Image.new("RGB", image.size, "white")
28
+ ).getbbox()
29
+ if bounds is None:
30
+ return image
31
+ (left, top, right, bottom) = bounds
32
+ bounds = (
33
+ max(0, left - 24),
34
+ max(0, top - 24),
35
+ min(image.width, right + 24),
36
+ min(image.height, bottom + 24),
37
+ )
38
+ (width, height) = (bounds[2] - bounds[0], bounds[3] - bounds[1])
39
+ if width * height > image.width * image.height / 2:
40
+ return image
41
+ scale = min(max_scale, (max_pixels / (width * height)) ** 0.5)
42
+ if scale <= 1:
43
+ return image
44
+ focused = image.crop(bounds)
45
+ return focused.resize(
46
+ (max(1, int(width * scale)), max(1, int(height * scale))),
47
+ Image.Resampling.BICUBIC,
48
+ )
clairic_runtime/image_identifier.py ADDED
@@ -0,0 +1,170 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ from collections.abc import Callable
3
+ from typing import TYPE_CHECKING, Any
4
+
5
+ if TYPE_CHECKING:
6
+ from .api import PredictRequest
7
+ from .backend import EncodedRequest
8
+ import math
9
+ import re
10
+ from PIL import Image, ImageChops, ImageStat
11
+ from .image_focus import focus_document
12
+
13
+ VIEW_ID = "identifier-content-band-v2"
14
+ _ROLE = re.compile(
15
+ "\\b(?:invoice|receipt|purchase order|order|tracking|reference|transaction|account|application)\\s+(?:number|identifier|id|code)\\b",
16
+ re.IGNORECASE,
17
+ )
18
+ _EXCLUDED_ROLE = re.compile(
19
+ "\\b(?:not|exclude|excluding|ignore|rather than)\\b[^.;:\\n]*$", re.IGNORECASE
20
+ )
21
+
22
+
23
+ def _requested_identifier(value: str) -> bool:
24
+ return any(
25
+ (
26
+ not _EXCLUDED_ROLE.search(value[: match.start()])
27
+ for match in _ROLE.finditer(value)
28
+ )
29
+ )
30
+
31
+
32
+ def fields(fields: dict[str, dict[str, Any]]) -> list[str]:
33
+ selected = []
34
+ for name, spec in fields.items():
35
+ if spec.get("type") != "text" or spec.get("knowledge"):
36
+ continue
37
+ label = re.sub("[_-]+", " ", name)
38
+ if _requested_identifier(label) or _requested_identifier(
39
+ spec.get("instructions", "")
40
+ ):
41
+ selected.append(name)
42
+ return selected
43
+
44
+
45
+ def detail_view(image: Image.Image, *, max_pixels: int = 1600000) -> Image.Image:
46
+ return focus_document(image, max_pixels=max_pixels, max_scale=3.0)
47
+
48
+
49
+ def header_view(image: Image.Image, *, max_pixels: int = 1600000) -> Image.Image | None:
50
+ if image.mode != "RGB":
51
+ return None
52
+ if (
53
+ ImageChops.difference(
54
+ image, Image.new("RGB", image.size, image.getpixel((0, 0)))
55
+ ).getbbox()
56
+ is None
57
+ ):
58
+ return None
59
+ header = image.crop((0, 0, image.width, max(1, math.ceil(image.height * 0.4))))
60
+ scale = min(3.0, math.sqrt(max_pixels / (header.width * header.height)))
61
+ size = (max(1, int(header.width * scale)), max(1, int(header.height * scale)))
62
+ return header.resize(size, Image.Resampling.BICUBIC)
63
+
64
+
65
+ def views(
66
+ image: Image.Image,
67
+ *,
68
+ max_pixels: int = 1600000,
69
+ unfocused_image: Image.Image | None = None,
70
+ ) -> tuple[Image.Image, ...]:
71
+ focused = (
72
+ image
73
+ if image is unfocused_image and max_pixels == 1600000
74
+ else detail_view(image, max_pixels=max_pixels)
75
+ )
76
+ if focused is not image:
77
+ return (focused,)
78
+ header = header_view(image, max_pixels=max_pixels)
79
+ return (image, header) if header is not None else (image,)
80
+
81
+
82
+ def content_view(
83
+ image: Image.Image, *, max_pixels: int = 1600000
84
+ ) -> Image.Image | None:
85
+ if image.mode != "RGB":
86
+ return None
87
+ background = tuple(ImageStat.Stat(image.resize((64, 64))).median)
88
+ if min(background) < 160:
89
+ return None
90
+ difference = ImageChops.difference(image, Image.new("RGB", image.size, background))
91
+ channels = difference.split()
92
+ contrast = ImageChops.lighter(
93
+ ImageChops.lighter(channels[0], channels[1]), channels[2]
94
+ )
95
+ mask = contrast.point(lambda value: 255 if value >= 32 else 0)
96
+ bounds = mask.getbbox()
97
+ if bounds is None:
98
+ return None
99
+ (left, top, right, bottom) = bounds
100
+ bounds = (
101
+ max(0, left - 24),
102
+ max(0, top - 24),
103
+ min(image.width, right + 24),
104
+ min(image.height, bottom + 24),
105
+ )
106
+ (width, height) = (bounds[2] - bounds[0], bounds[3] - bounds[1])
107
+ if width * height > image.width * image.height / 2:
108
+ return None
109
+ scale = min(3.0, math.sqrt(max_pixels / (width * height)))
110
+ if scale <= 1:
111
+ return None
112
+ return image.crop(bounds).resize(
113
+ (max(1, int(width * scale)), max(1, int(height * scale))),
114
+ Image.Resampling.BICUBIC,
115
+ )
116
+
117
+
118
+ def content_views(
119
+ image: Image.Image,
120
+ *,
121
+ max_pixels: int = 1600000,
122
+ unfocused_image: Image.Image | None = None,
123
+ ) -> tuple[Image.Image, ...]:
124
+ selected = (
125
+ views(image, max_pixels=max_pixels)
126
+ if unfocused_image is None
127
+ else views(image, max_pixels=max_pixels, unfocused_image=unfocused_image)
128
+ )
129
+ if selected[0] is not image:
130
+ return selected
131
+ content = content_view(image, max_pixels=max_pixels)
132
+ return (*selected, content) if content is not None else selected
133
+
134
+
135
+ def prepare(
136
+ request: PredictRequest,
137
+ encoded: EncodedRequest,
138
+ encode: Callable[..., EncodedRequest],
139
+ *,
140
+ unfocused_image: Image.Image | None = None,
141
+ ) -> EncodedRequest:
142
+ selected = fields(request.fields)
143
+ if not selected or len(request.images) != 1 or request.documents:
144
+ return encoded
145
+ (record, forecasts, tasks, typed, eos) = encoded
146
+ child_fields = {name: request.fields[name] for name in selected}
147
+ child_request = request.model_copy(update={"fields": child_fields})
148
+
149
+ def image_views() -> tuple[Image.Image, ...]:
150
+ originals = record.get("_original_images")
151
+ image: Image.Image = originals[0] if originals else request.images[0].to_pil()
152
+ return (
153
+ content_views(image, unfocused_image=unfocused_image)
154
+ if image is unfocused_image
155
+ else content_views(image)
156
+ )
157
+
158
+ (child, _, replacements, _, _) = encode(
159
+ child_request, identifier_view=True, image_views=image_views
160
+ )
161
+ by_name = {task[0]: task for task in replacements}
162
+ tasks = [by_name.get(task[0], task) for task in tasks]
163
+ salts = dict(record.get("_ar_task_salts", {}))
164
+ for name in selected:
165
+ record["_ar_constraints"][name] = child["_ar_constraints"][name]
166
+ salts[name] = child["_cache_salt"]
167
+ record.update(
168
+ _ar_tasks=tasks, _ar_task_salts=salts, _ar_prefix=[], _ar_group_prefixes=[]
169
+ )
170
+ return (record, forecasts, tasks, typed, eos)
clairic_runtime/image_party_names.py ADDED
@@ -0,0 +1,68 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ import math
3
+ import re
4
+ from typing import Any
5
+ import numpy as np
6
+ from PIL import Image, ImageChops
7
+
8
+ VIEW_ID = "party-name-header-lines-v1"
9
+ VIEW_INSTRUCTION = " The first image is the complete document. The second image enlarges its first printed lines. Use both views of the same source to read the complete requested name; preserve every digit in the name."
10
+ _ROLE = re.compile(
11
+ "\\b(?:seller|merchant|vendor|customer|bill[- ]?to|recipient|payee|payer|guest|organization|business|company|legal)\\b",
12
+ re.IGNORECASE,
13
+ )
14
+ _OTHER_VALUE = re.compile(
15
+ "\\b(?:address|number|identifier|code|date|row|label|amount)\\b", re.IGNORECASE
16
+ )
17
+
18
+
19
+ def fields(schema: dict[str, dict[str, Any]]) -> list[str]:
20
+ selected = []
21
+ for name, spec in schema.items():
22
+ instructions = spec.get("instructions", "")
23
+ if (
24
+ spec.get("type") != "text"
25
+ or spec.get("knowledge")
26
+ or (not isinstance(instructions, str))
27
+ ):
28
+ continue
29
+ requested = re.split("[.\\n]", instructions, maxsplit=1)[0]
30
+ if (
31
+ re.search("\\bname\\b", requested, re.IGNORECASE)
32
+ and _ROLE.search(requested)
33
+ and (not _OTHER_VALUE.search(requested))
34
+ ):
35
+ selected.append(name)
36
+ return selected
37
+
38
+
39
+ def header_detail(
40
+ image: Image.Image, *, max_pixels: int = 1600000
41
+ ) -> Image.Image | None:
42
+ if image.mode != "RGB" or image.getpixel((0, 0)) != (255, 255, 255):
43
+ return None
44
+ ink = np.asarray(image.convert("L")) < 200
45
+ if np.mean(ink) > 0.22:
46
+ return None
47
+ edges = np.flatnonzero(np.diff(np.pad(ink.any(axis=1).astype(np.int8), (1, 1))))
48
+ bands = edges.reshape(-1, 2).tolist()[:6]
49
+ if not bands or any((not 8 <= bottom - top <= 32 for (top, bottom) in bands)):
50
+ return None
51
+ top = max(0, bands[0][0] - 24)
52
+ bottom = min(image.height, bands[-1][1] + 24)
53
+ block = image.crop((0, top, image.width, bottom))
54
+ bounds = ImageChops.difference(
55
+ block, Image.new("RGB", block.size, "white")
56
+ ).getbbox()
57
+ if bounds is None:
58
+ return None
59
+ (left, right) = (max(0, bounds[0] - 24), min(block.width, bounds[2] + 24))
60
+ block = block.crop((left, 0, right, block.height))
61
+ scale = min(3.0, math.sqrt(max_pixels / (block.width * block.height)))
62
+ size = (max(1, int(block.width * scale)), max(1, int(block.height * scale)))
63
+ return block.resize(size, Image.Resampling.BICUBIC)
64
+
65
+
66
+ def views(image: Image.Image, *, max_pixels: int = 1600000) -> tuple[Image.Image, ...]:
67
+ detail = header_detail(image, max_pixels=max_pixels)
68
+ return (image, detail) if detail is not None else (image,)
clairic_runtime/image_ragged_rows.py ADDED
@@ -0,0 +1,350 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ from collections.abc import Callable
3
+ from typing import TYPE_CHECKING, Any
4
+
5
+ if TYPE_CHECKING:
6
+ from .api import PredictRequest
7
+ from .backend import EncodedRequest
8
+ import hashlib
9
+ import math
10
+ import re
11
+ from copy import deepcopy
12
+ from dataclasses import dataclass
13
+ from itertools import pairwise
14
+ import numpy as np
15
+ from PIL import Image
16
+ from . import image_table_rows, table_rows
17
+ from .schema import MAX_LIST_ITEMS
18
+
19
+ VIEW_ID = "ragged-table-v1"
20
+ TARGET_GATE = "target_is_billed_item"
21
+ TARGET_ROW = "target_row"
22
+ _BILLED_SCOPE = re.compile(
23
+ "\\b(?:line[ _-]?items?|billed\\s+(?:products?|services?|items?|goods))\\b",
24
+ re.IGNORECASE,
25
+ )
26
+ _FINANCIAL_SCOPE = re.compile(
27
+ "\\b(?:tax(?:es)?|fees?|surcharges?|payments?)\\b", re.IGNORECASE
28
+ )
29
+ TARGET_INSTRUCTION = "Image 1 is the complete source document. Image 2 isolates one physical row from image 1. Classify and read only the target row in image 2. Use image 1 to identify the table column labels. A column header is not a billed item. Do not select a neighboring row or count row positions. "
30
+
31
+
32
+ @dataclass(frozen=True)
33
+ class RaggedRows:
34
+ rows: tuple[tuple[int, int], ...]
35
+
36
+ def views(self, image: Image.Image) -> tuple[Image.Image, ...]:
37
+ return tuple(
38
+ (
39
+ image.crop(
40
+ (0, max(0, top - 3), image.width, min(image.height, bottom + 3))
41
+ )
42
+ for (top, bottom) in self.rows
43
+ )
44
+ )
45
+
46
+
47
+ def detect(image: Image.Image) -> RaggedRows | None:
48
+ if image_table_rows.detect(image) is not None:
49
+ return None
50
+ if image.mode != "RGB" or image.width < 100 or image.height < 60:
51
+ return None
52
+ grey = np.asarray(image.convert("L"))
53
+ if np.mean(grey < 245) > 0.22:
54
+ return None
55
+ ink = grey < 200
56
+ candidates = []
57
+ for index, (top, bottom) in enumerate(image_table_rows._runs(ink.any(axis=1))):
58
+ height = bottom - top
59
+ if height < 10:
60
+ continue
61
+ band = ink[top:bottom]
62
+ columns = band.any(axis=0)
63
+ separators = []
64
+ for left, right in image_table_rows._runs(band.sum(axis=0) >= 0.9 * height):
65
+ if (
66
+ right - left > max(3, height * 0.18)
67
+ or left < 3
68
+ or right > image.width - 3
69
+ or columns[left - 3 : left].any()
70
+ or columns[right : right + 3].any()
71
+ ):
72
+ continue
73
+ separators.append((left, right))
74
+ if len(separators) >= 2:
75
+ candidates.append((index, top, bottom, separators, columns))
76
+ if len(candidates) < 2:
77
+ return None
78
+ if any((right[0] != left[0] + 1 for (left, right) in pairwise(candidates))):
79
+ return None
80
+ if len({len(row[3]) for row in candidates}) != 1:
81
+ return None
82
+ if any((row[4][row[3][-1][1] + 3 :].any() for row in candidates)):
83
+ return None
84
+ heights = np.array([bottom - top for (_, top, bottom, _, _) in candidates])
85
+ spacing = np.diff([row[1] for row in candidates])
86
+ if np.max(heights) > 1.2 * np.min(heights) or np.max(spacing) > 1.3 * np.min(
87
+ spacing
88
+ ):
89
+ return None
90
+ return RaggedRows(tuple(((row[1], row[2]) for row in candidates)))
91
+
92
+
93
+ def _eligible(spec: dict[str, Any]) -> bool:
94
+ item = spec.get("items")
95
+ properties = item.get("properties", {}) if isinstance(item, dict) else {}
96
+ (scope, *exclusions) = re.split(
97
+ "\\bExclude\\b", spec.get("instructions", ""), maxsplit=1, flags=re.IGNORECASE
98
+ )
99
+ if exclusions:
100
+ if re.search(
101
+ "\\b(?:not|never|\\w+n['’]t)(?:\\s+\\w+){0,2}\\s*$", scope, re.IGNORECASE
102
+ ):
103
+ return False
104
+ (excluded, *later) = re.split("[.;\\n]", exclusions[0], maxsplit=1)
105
+ if (
106
+ later
107
+ and _FINANCIAL_SCOPE.search(later[0])
108
+ or (
109
+ _FINANCIAL_SCOPE.search(excluded)
110
+ and re.search(
111
+ "\\b(?:include|including|keep|retain|except|unless|not|no|none)\\b",
112
+ excluded,
113
+ re.IGNORECASE,
114
+ )
115
+ )
116
+ ):
117
+ return False
118
+ return (
119
+ spec.get("type") == "list"
120
+ and isinstance(item, dict)
121
+ and (item.get("type") == "object")
122
+ and (not table_rows.join_wrapped_descriptions(spec.get("instructions", "")))
123
+ and (not spec.get("knowledge"))
124
+ and (len(properties) >= 3)
125
+ and bool(_BILLED_SCOPE.search(scope))
126
+ and (not _FINANCIAL_SCOPE.search(scope))
127
+ and all(
128
+ (
129
+ child.get("type") in ("text", "number") and (not child.get("knowledge"))
130
+ for child in properties.values()
131
+ )
132
+ )
133
+ )
134
+
135
+
136
+ def row_fields(spec: dict[str, Any]) -> dict[str, dict[str, Any]]:
137
+ wrapped = table_rows.join_wrapped_descriptions(spec.get("instructions", ""))
138
+ membership = (
139
+ "A logical item can span several printed bands. Include it exactly once, at its first description band. Return false for a later continuation band belonging to that preceding item, even when its numeric cells are printed on the continuation band. Distinct separate source rows remain separate even if they repeat. "
140
+ if wrapped
141
+ else ""
142
+ )
143
+ readout = (
144
+ "For the target item's first band, use the full document to read its complete wrapped description and cells from its continuation bands. Never borrow from a neighboring logical item. "
145
+ if wrapped
146
+ else ""
147
+ )
148
+ return {
149
+ TARGET_GATE: {
150
+ "type": "boolean",
151
+ "nullable": False,
152
+ "instructions": TARGET_INSTRUCTION
153
+ + membership
154
+ + "Is the target row a billed product or service row? Return false for the column header, totals, tax, fees, or payment rows. "
155
+ + spec.get("instructions", ""),
156
+ },
157
+ TARGET_ROW: {
158
+ "type": "object",
159
+ "nullable": False,
160
+ "properties": deepcopy(spec["items"]["properties"]),
161
+ "instructions": TARGET_INSTRUCTION
162
+ + readout
163
+ + "Read the complete printed target row as an object. Whether it belongs in the requested list is decided separately. Always return an object with every requested cell. Missing cells and absent columns are null. Do not relabel an Amount column as Unit price. Never compute missing values.",
164
+ },
165
+ }
166
+
167
+
168
+ def prepare(
169
+ request: PredictRequest,
170
+ encoded: EncodedRequest,
171
+ encode: Callable[..., EncodedRequest],
172
+ *,
173
+ scale: float = 2,
174
+ ) -> EncodedRequest:
175
+ (record, forecasts, tasks, typed, eos) = encoded
176
+ annotations = record["_meta"]["extraction_contract"]["fields"]
177
+ parents = [
178
+ name
179
+ for (name, spec) in request.fields.items()
180
+ if _eligible(spec) and annotations.get(name, {}).get("image_row_fields")
181
+ ]
182
+ if not parents or len(request.images) != 1 or request.documents:
183
+ return encoded
184
+ originals = record.get("_original_images")
185
+ image = originals[0] if originals else request.images[0].to_pil()
186
+ plan = detect(image)
187
+ if plan is None:
188
+ return encoded
189
+ views = []
190
+ for view in plan.views(image):
191
+ factor = min(scale, (1600000 / (view.width * view.height)) ** 0.5)
192
+ if factor > 1:
193
+ view = view.resize(
194
+ (int(view.width * factor), int(view.height * factor)),
195
+ Image.Resampling.BICUBIC,
196
+ )
197
+ views.append(view)
198
+ salts = dict(record.get("_ar_task_salts", {}))
199
+ gates = list(record.get("_source_row_gates", []))
200
+ changed = False
201
+ for name in parents:
202
+ (spec, annotation) = (request.fields[name], annotations[name])
203
+ previous = annotation["image_row_fields"]
204
+ maximum = spec.get("max_items", MAX_LIST_ITEMS)
205
+ if len(views) > maximum + 1 or len(views) > len(previous):
206
+ continue
207
+ (replacements, pairs) = ([], [])
208
+ for index, (view, band) in enumerate(zip(views, plan.rows, strict=True)):
209
+ child = previous[index]
210
+ digest = hashlib.sha256(child.encode()).hexdigest()[:16]
211
+ gate = "ragged_gate_" + digest
212
+ while gate in record["fields"]:
213
+ gate += "_"
214
+ row_request = request.model_copy(update={"fields": row_fields(spec)})
215
+ (row_record, _, row_tasks, _, _) = encode(
216
+ row_request,
217
+ physical_row_view=True,
218
+ image_views=lambda view=view: (image, view),
219
+ image_view_key=f"{VIEW_ID}:{band}:scale{scale}",
220
+ )
221
+ assert len(row_tasks) == 2
222
+ names = {TARGET_GATE: gate, TARGET_ROW: child}
223
+ for source, ids, payload in row_tasks:
224
+ target = names[source]
225
+ record["fields"][target] = row_record["fields"][source]
226
+ record["_ar_constraints"][target] = row_record["_ar_constraints"][
227
+ source
228
+ ]
229
+ salts[target] = row_record["_cache_salt"]
230
+ annotations[target] = {"parent": name}
231
+ replacements.append((target, ids, payload))
232
+ gates.append(gate)
233
+ pairs.append((gate, child))
234
+ tasks = [
235
+ task for task in tasks if task[0] not in {name, *previous}
236
+ ] + replacements
237
+ retained = {copy for (_, copy) in pairs}
238
+ for child in set(previous) - retained:
239
+ record["fields"].pop(child, None)
240
+ record["_ar_constraints"].pop(child, None)
241
+ annotations.pop(child, None)
242
+ salts.pop(child, None)
243
+ annotation.pop("image_row_fields")
244
+ annotation["ragged_row_fields"] = pairs
245
+ annotation["ragged_row_max_items"] = maximum
246
+ record["fields"][name].pop("_image_row_inventory", None)
247
+ changed = True
248
+ if not changed:
249
+ return encoded
250
+ record.update(
251
+ _ar_tasks=tasks,
252
+ _ar_task_salts=salts,
253
+ _source_row_gates=gates,
254
+ _ar_prefix=[],
255
+ _ar_group_prefixes=[],
256
+ )
257
+ record.pop("_ar_media_groups", None)
258
+ return (record, forecasts, tasks, typed, eos)
259
+
260
+
261
+ def _score(value: object, *, probability: bool = False) -> bool:
262
+ return (
263
+ isinstance(value, (int, float))
264
+ and (not isinstance(value, bool))
265
+ and math.isfinite(value)
266
+ and (0 <= value <= 1 if probability else value <= 0)
267
+ )
268
+
269
+
270
+ def assemble(
271
+ record: dict[str, Any], predictions: dict[str, dict[str, Any]]
272
+ ) -> dict[str, dict[str, Any]]:
273
+ result = {}
274
+ for name, annotation in record["_meta"]["extraction_contract"]["fields"].items():
275
+ pairs = annotation.get("ragged_row_fields")
276
+ if not pairs:
277
+ continue
278
+ rows = [(predictions[gate], predictions[copy]) for (gate, copy) in pairs]
279
+ selected = [(gate, copy) for (gate, copy) in rows if gate.get("value") is True]
280
+ complete = all((gate.get("complete", False) for (gate, _) in rows)) and all(
281
+ (copy.get("complete", False) for (_, copy) in selected)
282
+ )
283
+ exclusion_scored = all(
284
+ (_score(gate.get("p_excluded"), probability=True) for (gate, _) in rows)
285
+ )
286
+ relevant = [gate for (gate, _) in rows] + [copy for (_, copy) in selected]
287
+ scored = exclusion_scored and all(
288
+ (_score(answer.get("log_probability")) for answer in relevant)
289
+ )
290
+ probability = (
291
+ sum((answer["log_probability"] for answer in relevant)) if scored else None
292
+ )
293
+ if probability is not None and (not math.isfinite(probability)):
294
+ (scored, probability) = (False, None)
295
+ valid = (
296
+ complete
297
+ and scored
298
+ and all(
299
+ (
300
+ gate.get("valid", False) and type(gate.get("value")) is bool
301
+ for (gate, _) in rows
302
+ )
303
+ )
304
+ and all(
305
+ (
306
+ copy.get("valid", False) and isinstance(copy.get("value"), dict)
307
+ for (_, copy) in selected
308
+ )
309
+ )
310
+ )
311
+ within_limit = len(selected) <= annotation["ragged_row_max_items"]
312
+ valid &= within_limit
313
+ answer = {
314
+ "value": [copy["value"] for (_, copy) in selected],
315
+ "valid": valid,
316
+ "complete": complete,
317
+ "confidence": math.exp(probability)
318
+ if valid and probability is not None
319
+ else 0.0,
320
+ "confidence_method": "ar_physical_image_row_eligibility_and_copy_probability",
321
+ "confidences": [
322
+ math.exp(gate["log_probability"] + copy["log_probability"])
323
+ if scored
324
+ else 0.0
325
+ for (gate, copy) in selected
326
+ ],
327
+ "p_null": math.prod((gate["p_excluded"] for (gate, _) in rows))
328
+ if exclusion_scored
329
+ else 0.0,
330
+ "p_null_method": "product_physical_image_row_exclusion_probabilities"
331
+ if exclusion_scored
332
+ else "unavailable_physical_image_row_exclusion_probability",
333
+ "p_nulls": [
334
+ gate["p_excluded"] if exclusion_scored else 0.0
335
+ for (gate, _) in selected
336
+ ],
337
+ "spans": [None] * len(selected),
338
+ }
339
+ if probability is not None:
340
+ answer["log_probability"] = probability
341
+ if not valid:
342
+ answer["failure_reason"] = (
343
+ "ragged_row_output_exceeds_max_items"
344
+ if not within_limit
345
+ else "ragged_row_unscored"
346
+ if not scored
347
+ else "ragged_row_read_incomplete"
348
+ )
349
+ result[name] = answer
350
+ return result
clairic_runtime/image_rows.py ADDED
@@ -0,0 +1,323 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ import json
3
+ import math
4
+ import re
5
+ import unicodedata
6
+ from collections.abc import Callable
7
+ from typing import Any, cast
8
+ from . import MAX_OUTPUT_TOKENS
9
+ from .schema import MAX_LIST_ITEMS
10
+
11
+ INVENTORY_OUTPUT_TOKENS = 2048
12
+ _ROW_REQUEST = re.compile(
13
+ "\\bone\\s+(?:object|entry|record)\\s+(?:per|for\\s+each)\\b[^.\\n]*\\brow\\b",
14
+ re.IGNORECASE,
15
+ )
16
+ LABEL = {
17
+ "type": "text",
18
+ "nullable": False,
19
+ "instructions": "Brief exact printed identifier of this requested row, without secondary description or numeric cells. Follow the requested field scope: the label may name a product, service, tax, fee, payment or other row.",
20
+ }
21
+
22
+
23
+ def prepare(
24
+ record: dict[str, Any], *, has_media: bool, share_description: bool = False
25
+ ) -> dict[str, Any]:
26
+ if not has_media:
27
+ return record
28
+ annotations = record["_meta"]["extraction_contract"]["fields"]
29
+ for name, spec in record["fields"].items():
30
+ annotation = annotations.get(name, {})
31
+ if (
32
+ spec.get("type") != "list"
33
+ or not isinstance(spec.get("items"), dict)
34
+ or spec["items"].get("type") != "object"
35
+ or (not annotation.get("query_fields"))
36
+ or annotation.get("source_fields")
37
+ or (not _ROW_REQUEST.search(spec.get("instructions", "")))
38
+ ):
39
+ continue
40
+ spec.update(nullable=True, _image_row_inventory=True)
41
+ annotation["image_row_fields"] = annotation.pop("query_fields")
42
+ for index, child in enumerate(annotation["image_row_fields"], 1):
43
+ row = record["fields"][child]
44
+ row.update(nullable=False, _image_row_proposal=True)
45
+ if share_description:
46
+ row["_share_image_row_description"] = True
47
+ row["instructions"] = (
48
+ f"Item {index} of {name} in the supplied document. "
49
+ + spec.get("instructions", "")
50
+ + " Return null for each missing cell, including absent entire columns. If this physical row does not exist return an object with every cell null."
51
+ )
52
+ return record
53
+
54
+
55
+ def is_inventory(spec: dict[str, Any]) -> bool:
56
+ return bool(spec.get("_image_row_inventory"))
57
+
58
+
59
+ def inventory_schema(spec: dict[str, Any]) -> dict[str, Any]:
60
+ return {
61
+ "type": ["array", "null"],
62
+ "minItems": 1,
63
+ "maxItems": spec.get("max_items", MAX_LIST_ITEMS) + 1,
64
+ "items": {
65
+ "type": "object",
66
+ "properties": {"label": {"type": "string"}},
67
+ "required": ["label"],
68
+ "additionalProperties": False,
69
+ },
70
+ }
71
+
72
+
73
+ def instruction(
74
+ record: dict[str, Any],
75
+ name: str,
76
+ schema: Callable[[dict[str, Any]], dict[str, Any]],
77
+ ) -> str | None:
78
+ spec = record["fields"][name]
79
+ if is_inventory(spec):
80
+ return (
81
+ "Extract the requested value from the supplied input, following the field instructions and scope. Return all matching rows together as one JSON array. Return null only if there are no matching rows. Each object describes one physical row. Missing cells are null inside that object; they do not make the row absent. Keep wrapped text in its row and preserve distinct duplicate rows. Stop after the last matching row and close the array. End immediately after the array or null."
82
+ + "\nField: "
83
+ + name
84
+ + "\nSchema: "
85
+ + json.dumps(
86
+ inventory_schema(spec), ensure_ascii=False, separators=(",", ":")
87
+ )
88
+ + "\nInstructions: "
89
+ + spec.get("instructions", "")
90
+ + "\nProperty instructions: "
91
+ + json.dumps({"label": LABEL}, ensure_ascii=False)
92
+ )
93
+ if spec.get("_image_row_proposal"):
94
+ if spec.get("_share_image_row_description"):
95
+ shared = shared_description_instruction(record, name, schema)
96
+ if shared is not None:
97
+ return shared
98
+ return (
99
+ "Extract one complete requested row from the supplied document. Return one JSON object matching the schema. Keep all properties on the same physical row. Use null for a missing cell in an existing row. Preserve distinct rows with identical values. Follow the requested row scope and exclusions. End immediately after the object."
100
+ + "\nField: "
101
+ + name
102
+ + "\nSchema: "
103
+ + json.dumps(schema(spec), ensure_ascii=False, separators=(",", ":"))
104
+ + "\nInstructions: "
105
+ + spec.get("instructions", "")
106
+ + "\nProperty instructions: "
107
+ + json.dumps(spec["properties"], ensure_ascii=False)
108
+ )
109
+ return None
110
+
111
+
112
+ def shared_description_instruction(
113
+ record: dict[str, Any],
114
+ name: str,
115
+ schema: Callable[[dict[str, Any]], dict[str, Any]],
116
+ ) -> str | None:
117
+ spec = record["fields"][name]
118
+ if not spec.get("_image_row_proposal"):
119
+ return None
120
+ annotation = (
121
+ record.get("_meta", {})
122
+ .get("extraction_contract", {})
123
+ .get("fields", {})
124
+ .get(name, {})
125
+ )
126
+ (parent, index) = (annotation.get("parent"), annotation.get("index"))
127
+ if (
128
+ not isinstance(parent, str)
129
+ or not parent
130
+ or type(index) is not int
131
+ or (index < 1)
132
+ ):
133
+ return None
134
+ properties = spec.get("properties", {})
135
+ description = properties.get("description", {})
136
+ if description.get("type") != "text" or not description.get("instructions"):
137
+ return None
138
+ ordinal = f"Item {index} of {parent} in the supplied document. "
139
+ scope = spec.get("instructions", "")
140
+ if not scope.startswith(ordinal):
141
+ return None
142
+ return (
143
+ "Extract one complete requested row from the supplied document. Return one JSON object matching the schema. Keep all properties on the same physical row. Use null for a missing cell in an existing row. Preserve distinct rows with identical values. Follow the requested row scope and exclusions. End immediately after the object."
144
+ + "\nSchema: "
145
+ + json.dumps(schema(spec), ensure_ascii=False, separators=(",", ":"))
146
+ + "\nInstructions: "
147
+ + scope[len(ordinal) :]
148
+ + "\nProperty instructions: "
149
+ + json.dumps(properties, ensure_ascii=False)
150
+ + "\nRequested row: "
151
+ + ordinal.rstrip()
152
+ + "\nField: "
153
+ + name
154
+ + "\nProperty instructions: "
155
+ + json.dumps({"description": description}, ensure_ascii=False)
156
+ )
157
+
158
+
159
+ def output_limit(record: dict[str, Any], name: str, length: int, max_input: int) -> int:
160
+ desired = (
161
+ INVENTORY_OUTPUT_TOKENS
162
+ if is_inventory(record["fields"][name])
163
+ else MAX_OUTPUT_TOKENS
164
+ )
165
+ return min(desired, max_input + MAX_OUTPUT_TOKENS - length)
166
+
167
+
168
+ def _words(value: str) -> str:
169
+ return " ".join(re.findall("\\w+", unicodedata.normalize("NFKC", value).casefold()))
170
+
171
+
172
+ def _assignment(costs: list[list[float]]) -> list[int]:
173
+ if not costs:
174
+ return []
175
+ (count, width) = (len(costs), len(costs[0]))
176
+ (u, v, p, way) = (
177
+ [0.0] * (count + 1),
178
+ [0.0] * (width + 1),
179
+ [0] * (width + 1),
180
+ [0] * (width + 1),
181
+ )
182
+ for index in range(1, count + 1):
183
+ (p[0], column) = (index, 0)
184
+ (minimum, used) = ([math.inf] * (width + 1), [False] * (width + 1))
185
+ while True:
186
+ used[column] = True
187
+ (row, delta, next_column) = (p[column], math.inf, 0)
188
+ for candidate in range(1, width + 1):
189
+ if not used[candidate]:
190
+ cost = costs[row - 1][candidate - 1] - u[row] - v[candidate]
191
+ if cost < minimum[candidate]:
192
+ (minimum[candidate], way[candidate]) = (cost, column)
193
+ if minimum[candidate] < delta:
194
+ (delta, next_column) = (minimum[candidate], candidate)
195
+ for candidate in range(width + 1):
196
+ if used[candidate]:
197
+ u[p[candidate]] += delta
198
+ v[candidate] -= delta
199
+ else:
200
+ minimum[candidate] -= delta
201
+ column = next_column
202
+ if p[column] == 0:
203
+ break
204
+ while column:
205
+ previous = way[column]
206
+ (p[column], column) = (p[previous], previous)
207
+ result: list[int | None] = [None] * count
208
+ for column in range(1, width + 1):
209
+ if p[column]:
210
+ result[p[column] - 1] = column - 1
211
+ return cast(list[int], result)
212
+
213
+
214
+ def _select(
215
+ labels: list[str], proposals: list[dict[str, Any]], text_keys: list[str]
216
+ ) -> tuple[list[dict[str, Any] | None], list[int]]:
217
+ if not text_keys:
218
+ return (
219
+ [
220
+ proposals[index] if index < len(proposals) else None
221
+ for index in range(len(labels))
222
+ ],
223
+ [],
224
+ )
225
+ costs = []
226
+ for index, label in enumerate(labels):
227
+ label = _words(label)
228
+ row_costs = []
229
+ for position, proposal in enumerate(proposals):
230
+ value = proposal.get("value") if proposal.get("valid") else None
231
+ texts = (
232
+ [value.get(key) for key in text_keys] if isinstance(value, dict) else []
233
+ )
234
+ matches = label and any(
235
+ (
236
+ isinstance(text, str) and f" {label} " in f" {_words(text)} "
237
+ for text in texts
238
+ )
239
+ )
240
+ row_costs.append(abs(position - index) * 10 if matches else 1000000000.0)
241
+ costs.append(row_costs + [100000000.0] * len(labels))
242
+ chosen = _assignment(costs)
243
+ conflicts = [
244
+ index
245
+ for (index, column) in enumerate(chosen)
246
+ if column >= len(proposals) or costs[index][column] >= 100000000.0
247
+ ]
248
+ return (
249
+ [
250
+ None if index in conflicts else proposals[column]
251
+ for (index, column) in enumerate(chosen)
252
+ ],
253
+ conflicts,
254
+ )
255
+
256
+
257
+ def assemble(
258
+ record: dict[str, Any], predictions: dict[str, dict[str, Any]]
259
+ ) -> dict[str, dict[str, Any]]:
260
+ answers = {}
261
+ annotations = record["_meta"]["extraction_contract"]["fields"]
262
+ for name, annotation in annotations.items():
263
+ queries = annotation.get("image_row_fields")
264
+ if not queries:
265
+ continue
266
+ (spec, inventory) = (record["fields"][name], predictions[name])
267
+ labels = [row["label"] for row in inventory.get("value") or []]
268
+ maximum = spec.get("max_items", MAX_LIST_ITEMS)
269
+ inventory_complete = (
270
+ inventory.get("valid", False)
271
+ and inventory.get("complete", False)
272
+ and (len(labels) <= maximum)
273
+ )
274
+ properties = spec["items"]["properties"]
275
+ text_keys = [
276
+ key for (key, child) in properties.items() if child["type"] == "text"
277
+ ]
278
+ (selected, conflicts) = _select(
279
+ labels[:maximum], [predictions[child] for child in queries], text_keys
280
+ )
281
+ complete = inventory_complete and all(
282
+ (row and row.get("complete", False) for row in selected)
283
+ )
284
+ valid = (
285
+ complete
286
+ and (not conflicts)
287
+ and all(
288
+ (
289
+ row
290
+ and row.get("valid")
291
+ and isinstance(row.get("value"), dict)
292
+ and any((value is not None for value in row["value"].values()))
293
+ for row in selected
294
+ )
295
+ )
296
+ )
297
+ answer = {
298
+ "value": [row["value"] if row else None for row in selected],
299
+ "valid": valid,
300
+ "complete": complete,
301
+ "confidence": 0.0,
302
+ "confidences": [
303
+ row.get("confidence", 0.0) if row else 0.0 for row in selected
304
+ ],
305
+ "confidence_method": "ar_sequence_probability_with_source_row_labels",
306
+ "p_null": inventory["p_null"],
307
+ "p_null_method": "source_row_labels_null_probability",
308
+ "spans": [None] * len(selected),
309
+ }
310
+ scores = [inventory, *selected]
311
+ if valid and all((row and "log_probability" in row for row in scores)):
312
+ probability = sum(
313
+ (row["log_probability"] for row in cast(list[dict[str, Any]], scores))
314
+ )
315
+ if math.isfinite(probability):
316
+ answer.update(
317
+ log_probability=probability,
318
+ confidence=math.exp(min(0.0, probability)),
319
+ )
320
+ if conflicts:
321
+ answer["failure_reason"] = "source_row_alignment"
322
+ answers[name] = answer
323
+ return answers
clairic_runtime/image_table_rows.py ADDED
@@ -0,0 +1,225 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ from collections.abc import Callable
3
+ from typing import TYPE_CHECKING, Any, cast
4
+
5
+ if TYPE_CHECKING:
6
+ from .api import PredictRequest
7
+ from numpy.typing import ArrayLike
8
+ from .backend import EncodedRequest
9
+ import math
10
+ from dataclasses import dataclass
11
+ import numpy as np
12
+ from PIL import Image
13
+ from .schema import MAX_LIST_ITEMS
14
+
15
+
16
+ @dataclass(frozen=True)
17
+ class RowTable:
18
+ header: tuple[int, int]
19
+ rows: tuple[tuple[int, int], ...]
20
+
21
+ def views(self, image: Image.Image) -> list[Image.Image]:
22
+ result = []
23
+ for top, bottom in self.rows:
24
+ header = image.crop(
25
+ (
26
+ 0,
27
+ max(0, self.header[0] - 3),
28
+ image.width,
29
+ min(image.height, self.header[1] + 3),
30
+ )
31
+ )
32
+ row = image.crop(
33
+ (0, max(0, top - 3), image.width, min(image.height, bottom + 3))
34
+ )
35
+ view = Image.new(
36
+ "RGB", (image.width, header.height + row.height + 12), "white"
37
+ )
38
+ view.paste(header, (0, 0))
39
+ view.paste(row, (0, header.height + 12))
40
+ result.append(view)
41
+ return result
42
+
43
+
44
+ def _runs(values: ArrayLike) -> list[tuple[int, int]]:
45
+ padded = np.pad(np.asarray(values, dtype=np.int8), (1, 1))
46
+ edges = np.flatnonzero(np.diff(padded))
47
+ return cast(
48
+ list[tuple[int, int]], [tuple(pair) for pair in edges.reshape(-1, 2).tolist()]
49
+ )
50
+
51
+
52
+ def detect(image: Image.Image) -> RowTable | None:
53
+ if image.mode != "RGB" or image.width < 100 or image.height < 60:
54
+ return None
55
+ grey = np.asarray(image.convert("L"))
56
+ if np.mean(grey < 245) > 0.22:
57
+ return None
58
+ ink = grey < 200
59
+ bands = _runs(ink.any(axis=1))
60
+ height: float
61
+ candidates = []
62
+ for index, (top, bottom) in enumerate(bands):
63
+ height = bottom - top
64
+ if height < 10:
65
+ continue
66
+ band = ink[top:bottom]
67
+ columns = band.any(axis=0)
68
+ separators = []
69
+ for left, right in _runs(band.sum(axis=0) >= 0.9 * height):
70
+ if (
71
+ right - left > max(3, height * 0.18)
72
+ or left < 3
73
+ or right > image.width - 3
74
+ or columns[left - 3 : left].any()
75
+ or columns[right : right + 3].any()
76
+ ):
77
+ continue
78
+ separators.append((left + right) / 2)
79
+ if len(separators) >= 2:
80
+ candidates.append((index, top, bottom, separators))
81
+ if len(candidates) < 4:
82
+ return None
83
+ groups: list[list[tuple[int, int, int, list[float]]]] = []
84
+ for candidate in candidates:
85
+ if not groups or candidate[0] != groups[-1][-1][0] + 1:
86
+ groups.append([])
87
+ groups[-1].append(candidate)
88
+ if len(groups) != 1:
89
+ return None
90
+ eligible = []
91
+ for group in groups:
92
+ if len(group) < 4 or len({len(row[3]) for row in group}) != 1:
93
+ continue
94
+ (header, body) = (group[0], group[1:])
95
+ heights = np.array([bottom - top for (_, top, bottom, _) in group])
96
+ height = float(np.median(heights))
97
+ positions = np.array([row[3] for row in body])
98
+ middle = np.median(positions, axis=0)
99
+ spacing = np.diff([row[1] for row in group])
100
+ if (
101
+ np.max(heights) > 1.2 * np.min(heights)
102
+ or np.max(spacing) > 1.3 * np.min(spacing)
103
+ or np.max(np.abs(positions - middle)) > height * 1.2
104
+ or (abs(header[3][0] - middle[0]) < height * 2)
105
+ ):
106
+ continue
107
+ eligible.append(
108
+ RowTable((header[1], header[2]), tuple(((row[1], row[2]) for row in body)))
109
+ )
110
+ return eligible[0] if len(eligible) == 1 else None
111
+
112
+
113
+ def prepare(
114
+ request: PredictRequest,
115
+ encoded: EncodedRequest,
116
+ encode: Callable[..., EncodedRequest],
117
+ *,
118
+ scale: float = 2,
119
+ ) -> EncodedRequest:
120
+ (record, forecasts, tasks, typed, eos) = encoded
121
+ annotations = record["_meta"]["extraction_contract"]["fields"]
122
+ parents = [
123
+ name
124
+ for (name, annotation) in annotations.items()
125
+ if annotation.get("image_row_fields")
126
+ ]
127
+ if not parents or len(request.images) != 1 or request.documents:
128
+ return encoded
129
+ originals = record.get("_original_images")
130
+ image = originals[0] if originals else request.images[0].to_pil()
131
+ table = detect(image)
132
+ if table is None:
133
+ return encoded
134
+ views = table.views(image)
135
+ salts = dict(record.get("_ar_task_salts", {}))
136
+ for name in parents:
137
+ spec = request.fields[name]
138
+ if len(views) > spec.get("max_items", MAX_LIST_ITEMS):
139
+ continue
140
+ annotation = annotations[name]
141
+ previous = annotation["image_row_fields"]
142
+ replacements = []
143
+ for index, view in enumerate(views):
144
+ factor = min(scale, (1600000 / (view.width * view.height)) ** 0.5)
145
+ if factor > 1:
146
+ view = view.resize(
147
+ (int(view.width * factor), int(view.height * factor)),
148
+ Image.Resampling.BICUBIC,
149
+ )
150
+ child = previous[index]
151
+ view_field = "source_row"
152
+ row_spec = {
153
+ "type": "object",
154
+ "nullable": True,
155
+ "properties": spec["items"]["properties"],
156
+ "instructions": "Check whether the single data row below the column header matches the requested scope. Return null for an excluded row. Otherwise return the complete printed row. "
157
+ + spec.get("instructions", "")
158
+ + " Missing cells are null. Do not count or select a different row.",
159
+ }
160
+ row_request = request.model_copy(update={"fields": {view_field: row_spec}})
161
+ (row_record, _, row_tasks, _, _) = encode(
162
+ row_request,
163
+ physical_row_view=True,
164
+ image_views=lambda view=view: (view,),
165
+ image_view_key=f"table-row-v1:{table.header}:{table.rows[index]}:{scale}",
166
+ )
167
+ assert len(row_tasks) == 1
168
+ record["fields"][child] = row_record["fields"][view_field]
169
+ record["_ar_constraints"][child] = row_record["_ar_constraints"][view_field]
170
+ salts[child] = row_record["_cache_salt"]
171
+ (_, ids, payload) = row_tasks[0]
172
+ replacements.append((child, ids, payload))
173
+ replaced = {name, *previous}
174
+ tasks = [task for task in tasks if task[0] not in replaced] + replacements
175
+ retained = {task[0] for task in replacements}
176
+ for child in set(previous) - retained:
177
+ record["fields"].pop(child)
178
+ record["_ar_constraints"].pop(child, None)
179
+ annotations.pop(child, None)
180
+ annotation["geometric_row_fields"] = [task[0] for task in replacements]
181
+ annotation.pop("image_row_fields")
182
+ record["fields"][name].pop("_image_row_inventory", None)
183
+ if not any(
184
+ (annotation.get("geometric_row_fields") for annotation in annotations.values())
185
+ ):
186
+ return encoded
187
+ record.update(
188
+ _ar_tasks=tasks, _ar_task_salts=salts, _ar_prefix=[], _ar_group_prefixes=[]
189
+ )
190
+ return (record, forecasts, tasks, typed, eos)
191
+
192
+
193
+ def assemble(
194
+ record: dict[str, Any], predictions: dict[str, dict[str, Any]]
195
+ ) -> dict[str, dict[str, Any]]:
196
+ result = {}
197
+ for name, annotation in record["_meta"]["extraction_contract"]["fields"].items():
198
+ queries = annotation.get("geometric_row_fields")
199
+ if not queries:
200
+ continue
201
+ rows = [predictions[query] for query in queries]
202
+ selected = [row for row in rows if row.get("value") is not None]
203
+ complete = all((row.get("complete", False) for row in rows))
204
+ valid = complete and all((row.get("valid", False) for row in rows))
205
+ answer = {
206
+ "value": [row["value"] for row in selected],
207
+ "complete": complete,
208
+ "valid": valid,
209
+ "confidence": 0.0,
210
+ "confidences": [row.get("confidence", 0.0) for row in selected],
211
+ "confidence_method": "ar_physical_image_row_sequence_probability",
212
+ "p_null": math.prod((row["p_null"] for row in rows)),
213
+ "p_nulls": [row["p_null"] for row in selected],
214
+ "p_null_method": "product_physical_image_row_exclusion_probabilities",
215
+ "spans": [None] * len(selected),
216
+ }
217
+ if valid and all(("log_probability" in row for row in rows)):
218
+ probability = sum((row["log_probability"] for row in rows))
219
+ if math.isfinite(probability):
220
+ answer.update(
221
+ log_probability=probability,
222
+ confidence=math.exp(min(0.0, probability)),
223
+ )
224
+ result[name] = answer
225
+ return result
clairic_runtime/kernels.py ADDED
@@ -0,0 +1,478 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ # SPDX-FileCopyrightText: Copyright contributors to the vLLM project
3
+ # Copyright (c) 2024, Tri Dao.
4
+ # Copyright 2026 Cloudflare, Inc.
5
+
6
+ """CUDA kernels for attention and causal convolution."""
7
+
8
+ from typing import Any
9
+
10
+ import torch
11
+ import triton
12
+ import triton.language as tl
13
+
14
+
15
+ @triton.jit(do_not_specialize=["XB", "XD", "XT", "OB", "OD", "OT"])
16
+ def _prefill(X: tl.tensor, W: tl.tensor, Bias: tl.tensor, Out: tl.tensor,
17
+ T: tl.int32, D: tl.constexpr,
18
+ XB: tl.int64, XD: tl.int64, XT: tl.int64,
19
+ OB: tl.int64, OD: tl.int64, OT: tl.int64,
20
+ HAS_BIAS: tl.constexpr, SILU: tl.constexpr,
21
+ BT: tl.constexpr, BD: tl.constexpr) -> None:
22
+ batch = tl.program_id(1)
23
+ token = tl.program_id(0) * BT + tl.arange(0, BT)
24
+ channel = tl.program_id(2) * BD + tl.arange(0, BD)
25
+ if HAS_BIAS:
26
+ initial = tl.load(Bias + channel, channel < D, other=0).to(tl.float32)
27
+ else:
28
+ initial = tl.full((BD,), 0, tl.float32)
29
+ acc = tl.broadcast_to(initial[None, :], (BT, BD))
30
+ for tap in tl.static_range(4):
31
+ position = token + tap - 3
32
+ value = tl.load(X + batch * XB + channel[None, :] * XD + position[:, None] * XT,
33
+ (position[:, None] >= 0) & (position[:, None] < T)
34
+ & (channel[None, :] < D), other=0)
35
+ weight = tl.load(W + channel * 4 + tap, channel < D, other=0)
36
+ acc += value * weight[None, :]
37
+ if SILU:
38
+ acc = acc / (1 + tl.exp(-acc))
39
+ tl.store(Out + batch * OB + channel[None, :] * OD + token[:, None] * OT,
40
+ acc, (token[:, None] < T) & (channel[None, :] < D))
41
+
42
+
43
+ @triton.jit(do_not_specialize=["XB", "XD", "SB", "SD", "ST", "OB", "OD"])
44
+ def _update(X: tl.tensor, State: tl.tensor, W: tl.tensor, Bias: tl.tensor, Out: tl.tensor,
45
+ D: tl.constexpr, XB: tl.int64, XD: tl.int64,
46
+ SB: tl.int64, SD: tl.int64, ST: tl.int64,
47
+ OB: tl.int64, OD: tl.int64,
48
+ HAS_BIAS: tl.constexpr, SILU: tl.constexpr, BD: tl.constexpr) -> None:
49
+ batch = tl.program_id(0)
50
+ channel = tl.program_id(1) * BD + tl.arange(0, BD)
51
+ mask = channel < D
52
+ base = State + batch * SB + channel * SD
53
+ x0 = tl.load(base + ST, mask, other=0)
54
+ x1 = tl.load(base + 2 * ST, mask, other=0)
55
+ x2 = tl.load(base + 3 * ST, mask, other=0)
56
+ x3 = tl.load(X + batch * XB + channel * XD, mask, other=0)
57
+ if HAS_BIAS:
58
+ acc = tl.load(Bias + channel, mask, other=0).to(tl.float32)
59
+ else:
60
+ acc = tl.full((BD,), 0, tl.float32)
61
+ for tap in tl.static_range(4):
62
+ if tap == 0:
63
+ value = x0
64
+ elif tap == 1:
65
+ value = x1
66
+ elif tap == 2:
67
+ value = x2
68
+ else:
69
+ value = x3
70
+ weight = tl.load(W + channel * 4 + tap, mask, other=0)
71
+ acc += value * weight
72
+ if SILU:
73
+ acc = acc / (1 + tl.exp(-acc))
74
+ tl.store(Out + batch * OB + channel * OD, acc, mask)
75
+ # Preserve the four-token cache owned by Transformers.
76
+ tl.store(base, x0, mask)
77
+ tl.store(base + ST, x1, mask)
78
+ tl.store(base + 2 * ST, x2, mask)
79
+ tl.store(base + 3 * ST, x3, mask)
80
+
81
+
82
+ def prefill(x: torch.Tensor, weight: torch.Tensor, bias: torch.Tensor | None,
83
+ activation: str | None) -> torch.Tensor:
84
+ output = torch.empty_like(x)
85
+ batch, channels, length = x.shape
86
+ _prefill[(triton.cdiv(length, 8), batch, triton.cdiv(channels, 256))](
87
+ x, weight, bias, output, length, channels, *x.stride(), *output.stride(),
88
+ HAS_BIAS=bias is not None, SILU=activation is not None, BT=8, BD=256,
89
+ num_warps=4, num_stages=2,
90
+ )
91
+ return output
92
+
93
+
94
+ def update(x: torch.Tensor, state: torch.Tensor, weight: torch.Tensor,
95
+ bias: torch.Tensor | None, activation: str | None) -> torch.Tensor:
96
+ output = torch.empty_like(x)
97
+ _update[(x.shape[0], triton.cdiv(x.shape[1], 256))](
98
+ x, state, weight, bias, output, x.shape[1], *x.stride()[:2],
99
+ *state.stride(), *output.stride()[:2], HAS_BIAS=bias is not None,
100
+ SILU=activation is not None, BD=256, num_warps=4,
101
+ )
102
+ return output
103
+
104
+
105
+ @triton.jit(do_not_specialize=["QGT", "KT", "QT", "KOT", "GT", "CT", "ST"])
106
+ def _dense_qk_kernel(QG: tl.tensor, K: tl.tensor, QO: tl.tensor, KO: tl.tensor, GO: tl.tensor,
107
+ QW: tl.tensor, KW: tl.tensor, C: tl.tensor, S: tl.tensor,
108
+ QGT: tl.int64, KT: tl.int64, QT: tl.int64, KOT: tl.int64, GT: tl.int64,
109
+ CT: tl.int64, ST: tl.int64,
110
+ NQ: tl.constexpr, NKV: tl.constexpr, D: tl.constexpr, R: tl.constexpr,
111
+ HALF: tl.constexpr, HEAD_BLOCK: tl.constexpr, ROT_BLOCK: tl.constexpr,
112
+ EPS: tl.constexpr) -> None:
113
+ token, head = tl.program_id(0), tl.program_id(1)
114
+ is_k = head >= NQ
115
+ local_head = tl.where(is_k, head - NQ, head)
116
+ if is_k:
117
+ in_base = K + token * KT + local_head * D
118
+ w_ptr = KW
119
+ out_base = KO + token * KOT + local_head * D
120
+ else:
121
+ in_base = QG + token * QGT + local_head * 2 * D
122
+ w_ptr = QW
123
+ out_base = QO + token * QT + local_head * D
124
+ head_offs = tl.arange(0, HEAD_BLOCK)
125
+ head_mask = head_offs < D
126
+ x = tl.load(in_base + head_offs, mask=head_mask, other=0.0).to(tl.float32)
127
+ w = tl.load(w_ptr + head_offs, mask=head_mask, other=0.0).to(tl.float32)
128
+ var = tl.sum(x * x, axis=0) / D
129
+ inv_rms = tl.rsqrt(var + EPS)
130
+ x_norm = (x * inv_rms * (w + 1.0)).to(tl.bfloat16).to(tl.float32)
131
+ pass_mask = head_mask & (head_offs >= R)
132
+ tl.store(out_base + head_offs, x_norm, mask=pass_mask)
133
+ rot_offs = tl.arange(0, ROT_BLOCK)
134
+ rot_mask = rot_offs < HALF
135
+ xr1 = tl.load(in_base + rot_offs, mask=rot_mask, other=0.0).to(tl.float32)
136
+ xr2 = tl.load(in_base + HALF + rot_offs, mask=rot_mask, other=0.0).to(tl.float32)
137
+ wr1 = tl.load(w_ptr + rot_offs, mask=rot_mask, other=0.0).to(tl.float32)
138
+ wr2 = tl.load(w_ptr + HALF + rot_offs, mask=rot_mask, other=0.0).to(tl.float32)
139
+ xr1 = (xr1 * inv_rms * (wr1 + 1.0)).to(tl.bfloat16).to(tl.float32)
140
+ xr2 = (xr2 * inv_rms * (wr2 + 1.0)).to(tl.bfloat16).to(tl.float32)
141
+ cos = tl.load(C + token * CT + rot_offs, mask=rot_mask, other=0.0).to(tl.float32)
142
+ sin = tl.load(S + token * ST + rot_offs, mask=rot_mask, other=0.0).to(tl.float32)
143
+ tl.store(out_base + rot_offs, xr1 * cos - xr2 * sin, mask=rot_mask)
144
+ tl.store(out_base + HALF + rot_offs, xr2 * cos + xr1 * sin, mask=rot_mask)
145
+ gate_in = in_base + D
146
+ if not is_k:
147
+ gate_out = GO + token * GT + local_head * D
148
+ gate = tl.load(gate_in + head_offs, mask=head_mask, other=0.0)
149
+ tl.store(gate_out + head_offs, gate, mask=head_mask)
150
+
151
+
152
+ def dense_qk(q_gate: torch.Tensor, key: torch.Tensor, q_weight: torch.Tensor,
153
+ k_weight: torch.Tensor, cos: torch.Tensor, sin: torch.Tensor,
154
+ eps: float) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
155
+ batch, length, q_width = q_gate.shape
156
+ dim, rotary_dim = q_weight.numel(), cos.shape[-1]
157
+ q_heads, kv_heads = q_width // (2 * dim), key.shape[-1] // dim
158
+ tokens = batch * length
159
+ qg, k = q_gate.view(tokens, -1), key.view(tokens, -1)
160
+ c, s = cos.view(tokens, rotary_dim), sin.view(tokens, rotary_dim)
161
+ q_out = torch.empty(tokens, q_heads * dim, device=q_gate.device, dtype=q_gate.dtype)
162
+ k_out = torch.empty(tokens, kv_heads * dim, device=key.device, dtype=key.dtype)
163
+ gate = torch.empty(tokens, q_heads * dim, device=q_gate.device, dtype=q_gate.dtype)
164
+ _dense_qk_kernel[(tokens, q_heads + kv_heads)](
165
+ qg, k, q_out, k_out, gate, q_weight, k_weight, c, s,
166
+ qg.stride(0), k.stride(0), q_out.stride(0), k_out.stride(0), gate.stride(0),
167
+ c.stride(0), s.stride(0), NQ=q_heads, NKV=kv_heads, D=dim, R=rotary_dim,
168
+ HALF=rotary_dim // 2, HEAD_BLOCK=triton.next_power_of_2(dim),
169
+ ROT_BLOCK=triton.next_power_of_2(rotary_dim // 2), EPS=eps, num_warps=4)
170
+ return (q_out.view(batch, length, q_heads, dim).transpose(1, 2),
171
+ k_out.view(batch, length, kv_heads, dim).transpose(1, 2),
172
+ gate.view(batch, length, q_heads * dim))
173
+
174
+
175
+ @triton.jit(do_not_specialize=["XS", "ZS", "YS"])
176
+ def _gated_norm_kernel(X: tl.tensor, Z: tl.tensor, W: tl.tensor, Y: tl.tensor,
177
+ M: tl.int32, N: tl.constexpr, XS: tl.int64, ZS: tl.int64,
178
+ YS: tl.int64, EPS: tl.float32, BLOCK: tl.constexpr) -> None:
179
+ rows = tl.program_id(0) * 4 + tl.arange(0, 4)
180
+ cols = tl.arange(0, BLOCK)
181
+ mask = (rows[:, None] < M) & (cols[None, :] < N)
182
+ x = tl.load(X + rows[:, None] * XS + cols[None, :], mask, other=0).to(tl.float32)
183
+ xbar = tl.where(mask, x, 0.0)
184
+ var = tl.sum(xbar * xbar, axis=1) / N
185
+ rstd = tl.rsqrt(var + EPS)
186
+ w = tl.load(W + cols, cols < N, other=0).to(tl.float32)
187
+ x_hat = x * rstd[:, None]
188
+ y = x_hat * w[None, :]
189
+ z = tl.load(Z + rows[:, None] * ZS + cols[None, :], mask, other=0).to(tl.float32)
190
+ y *= z * tl.sigmoid(z)
191
+ tl.store(Y + rows[:, None] * YS + cols[None, :], y, mask)
192
+
193
+
194
+ def gated_norm(x: torch.Tensor, z: torch.Tensor, weight: torch.Tensor,
195
+ eps: float) -> torch.Tensor:
196
+ output = torch.empty_like(x)
197
+ _gated_norm_kernel[(triton.cdiv(x.shape[0], 4),)](
198
+ x, z, weight, output, x.shape[0], x.shape[1], x.stride(0),
199
+ z.stride(0), output.stride(0), eps, BLOCK=triton.next_power_of_2(x.shape[1]),
200
+ num_warps=min(max(triton.next_power_of_2(x.shape[1]) // 256, 1), 8),
201
+ )
202
+ return output
203
+
204
+
205
+ # MIT License
206
+ #
207
+ # Copyright 2025 Thinking Machines Lab
208
+ #
209
+ # Permission is hereby granted, free of charge, to any person obtaining a copy
210
+ # of this software and associated documentation files (the "Software"), to deal
211
+ # in the Software without restriction, including without limitation the rights
212
+ # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
213
+ # copies of the Software, and to permit persons to whom the Software is
214
+ # furnished to do so, subject to the following conditions:
215
+ #
216
+ # The above copyright notice and this permission notice shall be included in all
217
+ # copies or substantial portions of the Software.
218
+ #
219
+ # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
220
+ # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
221
+ # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
222
+ # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
223
+ # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
224
+ # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
225
+ # SOFTWARE.
226
+
227
+ def get_device_core_count() -> int:
228
+ return torch.cuda.get_device_properties(torch.cuda.current_device()).multi_processor_count
229
+
230
+ @triton.jit
231
+ def _compute_pid(tile_id: tl.tensor, num_pid_in_group: tl.tensor, num_pid_m: tl.tensor, GROUP_SIZE_M: tl.tensor, NUM_SMS: tl.tensor) -> tuple[tl.tensor, tl.tensor]:
232
+ group_id = tile_id // num_pid_in_group
233
+ first_pid_m = group_id * GROUP_SIZE_M
234
+ group_size_m = min(num_pid_m - first_pid_m, GROUP_SIZE_M)
235
+ pid_m = first_pid_m + tile_id % group_size_m
236
+ pid_n = tile_id % num_pid_in_group // group_size_m
237
+ return (pid_m, pid_n)
238
+
239
+ @triton.jit
240
+ def matmul_kernel_persistent(a_ptr: tl.tensor, b_ptr: tl.tensor, c_ptr: tl.tensor, bias_ptr: tl.tensor, M: tl.int32, N: tl.int32, K: tl.int32, stride_am: tl.int32, stride_ak: tl.int32, stride_bk: tl.int32, stride_bn: tl.int32, stride_cm: tl.int32, stride_cn: tl.int32, BLOCK_SIZE_M: tl.constexpr, BLOCK_SIZE_N: tl.constexpr, BLOCK_SIZE_K: tl.constexpr, GROUP_SIZE_M: tl.constexpr, NUM_SMS: tl.constexpr, A_LARGE: tl.constexpr, B_LARGE: tl.constexpr, C_LARGE: tl.constexpr, HAS_BIAS: tl.constexpr) -> None:
241
+ start_pid = tl.program_id(axis=0)
242
+ num_pid_m = tl.cdiv(M, BLOCK_SIZE_M)
243
+ num_pid_n = tl.cdiv(N, BLOCK_SIZE_N)
244
+ k_tiles = tl.cdiv(K, BLOCK_SIZE_K)
245
+ num_tiles = num_pid_m * num_pid_n
246
+ offs_k_for_mask = tl.arange(0, BLOCK_SIZE_K)
247
+ num_pid_in_group = GROUP_SIZE_M * num_pid_n
248
+ for tile_id in tl.range(start_pid, num_tiles, NUM_SMS, flatten=True):
249
+ (pid_m, pid_n) = _compute_pid(tile_id, num_pid_in_group, num_pid_m, GROUP_SIZE_M, NUM_SMS)
250
+ start_m = pid_m * BLOCK_SIZE_M
251
+ start_n = pid_n * BLOCK_SIZE_N
252
+ offs_am = start_m + tl.arange(0, BLOCK_SIZE_M)
253
+ offs_bn = start_n + tl.arange(0, BLOCK_SIZE_N)
254
+ if A_LARGE:
255
+ offs_am = offs_am.to(tl.int64)
256
+ if B_LARGE:
257
+ offs_bn = offs_bn.to(tl.int64)
258
+ offs_am = tl.where(offs_am < M, offs_am, 0)
259
+ offs_bn = tl.where(offs_bn < N, offs_bn, 0)
260
+ offs_am = tl.max_contiguous(tl.multiple_of(offs_am, BLOCK_SIZE_M), BLOCK_SIZE_M)
261
+ offs_bn = tl.max_contiguous(tl.multiple_of(offs_bn, BLOCK_SIZE_N), BLOCK_SIZE_N)
262
+ accumulator = tl.zeros((BLOCK_SIZE_M, BLOCK_SIZE_N), dtype=tl.float32)
263
+ for ki in range(k_tiles):
264
+ if A_LARGE or B_LARGE:
265
+ offs_k = ki * BLOCK_SIZE_K + tl.arange(0, BLOCK_SIZE_K).to(tl.int64)
266
+ else:
267
+ offs_k = ki * BLOCK_SIZE_K + tl.arange(0, BLOCK_SIZE_K)
268
+ a_ptrs = a_ptr + (offs_am[:, None] * stride_am + offs_k[None, :] * stride_ak)
269
+ b_ptrs = b_ptr + (offs_k[:, None] * stride_bk + offs_bn[None, :] * stride_bn)
270
+ a = tl.load(a_ptrs, mask=offs_k_for_mask[None, :] < K - ki * BLOCK_SIZE_K, other=0.0)
271
+ b = tl.load(b_ptrs, mask=offs_k_for_mask[:, None] < K - ki * BLOCK_SIZE_K, other=0.0)
272
+ accumulator = tl.dot(a, b, accumulator)
273
+ offs_cm = pid_m * BLOCK_SIZE_M + tl.arange(0, BLOCK_SIZE_M)
274
+ offs_cn = pid_n * BLOCK_SIZE_N + tl.arange(0, BLOCK_SIZE_N)
275
+ if C_LARGE:
276
+ offs_cm = offs_cm.to(tl.int64)
277
+ offs_cn = offs_cn.to(tl.int64)
278
+ c_ptrs = c_ptr + stride_cm * offs_cm[:, None] + stride_cn * offs_cn[None, :]
279
+ c_mask = (offs_cm[:, None] < M) & (offs_cn[None, :] < N)
280
+ if HAS_BIAS:
281
+ bias_ptrs = bias_ptr + offs_cn
282
+ bias = tl.load(bias_ptrs, mask=offs_cn < N, other=0.0).to(tl.float32)
283
+ accumulator += bias
284
+ if c_ptr.dtype.element_ty == tl.float8e4nv:
285
+ c = accumulator.to(tl.float8e4nv)
286
+ elif c_ptr.dtype.element_ty == tl.bfloat16:
287
+ c = accumulator.to(tl.bfloat16)
288
+ elif c_ptr.dtype.element_ty == tl.float32:
289
+ c = accumulator.to(tl.float32)
290
+ else:
291
+ c = accumulator.to(tl.float16)
292
+ tl.store(c_ptrs, c, mask=c_mask)
293
+
294
+ def _matmul_persistent_triton(a: torch.Tensor, b: torch.Tensor, bias: torch.Tensor | None=None) -> torch.Tensor:
295
+ assert a.shape[1] == b.shape[0], 'Incompatible dimensions'
296
+ assert a.dtype == b.dtype, 'Incompatible dtypes'
297
+ assert bias is None or bias.dim() == 1, 'Expected a one-dimensional bias'
298
+ NUM_SMS = get_device_core_count()
299
+ (M, K) = a.shape
300
+ (K, N) = b.shape
301
+ dtype = a.dtype
302
+ c = torch.empty((M, N), device=a.device, dtype=dtype)
303
+
304
+ def grid(META: dict[str, Any]) -> tuple[int]:
305
+ return (min(NUM_SMS, triton.cdiv(M, META['BLOCK_SIZE_M']) * triton.cdiv(N, META['BLOCK_SIZE_N'])),)
306
+ configs = {torch.bfloat16: {'BLOCK_SIZE_M': 128, 'BLOCK_SIZE_N': 128, 'BLOCK_SIZE_K': 64, 'GROUP_SIZE_M': 8, 'num_stages': 3, 'num_warps': 8}, torch.float16: {'BLOCK_SIZE_M': 128, 'BLOCK_SIZE_N': 256, 'BLOCK_SIZE_K': 64, 'GROUP_SIZE_M': 8, 'num_stages': 3, 'num_warps': 8}, torch.float32: {'BLOCK_SIZE_M': 128, 'BLOCK_SIZE_N': 128, 'BLOCK_SIZE_K': 32, 'GROUP_SIZE_M': 8, 'num_stages': 3, 'num_warps': 8}}
307
+ matmul_kernel_persistent[grid](a, b, c, bias, M, N, K, a.stride(0), a.stride(1), b.stride(0), b.stride(1), c.stride(0), c.stride(1), NUM_SMS=NUM_SMS, A_LARGE=a.numel() > 2 ** 31, B_LARGE=b.numel() > 2 ** 31, C_LARGE=c.numel() > 2 ** 31, HAS_BIAS=bias is not None, **configs[dtype])
308
+ return c
309
+
310
+ @triton.jit
311
+ def mean_kernel(input_ptr: tl.tensor, output_ptr: tl.tensor, input_stride0: tl.int32, input_stride1: tl.int32, input_stride2: tl.int32, output_stride0: tl.int32, output_stride1: tl.int32, M: tl.int32, N: tl.int32, K: tl.int32, BLOCK_SIZE: tl.constexpr) -> None:
312
+ """
313
+ Kernel for computing mean along a single dimension.
314
+ Input is viewed as (M, N, K) where N is the dimension being reduced.
315
+ """
316
+ pid = tl.program_id(0)
317
+ m_idx = pid // K
318
+ k_idx = pid % K
319
+ if m_idx >= M or k_idx >= K:
320
+ return
321
+ acc = 0.0
322
+ for n_start in range(0, N, BLOCK_SIZE):
323
+ n_offsets = n_start + tl.arange(0, BLOCK_SIZE)
324
+ mask = n_offsets < N
325
+ input_idx = m_idx * input_stride0 + n_offsets * input_stride1 + k_idx * input_stride2
326
+ vals = tl.load(input_ptr + input_idx, mask=mask, other=0.0)
327
+ acc += tl.sum(vals)
328
+ mean_val = acc / N
329
+ output_idx = m_idx * output_stride0 + k_idx * output_stride1
330
+ tl.store(output_ptr + output_idx, mean_val)
331
+
332
+ def mean_dim(input: torch.Tensor, dim: int, keepdim: bool=False, dtype: torch.dtype | None=None) -> torch.Tensor:
333
+ """
334
+ Triton implementation of torch.mean with single dimension reduction.
335
+
336
+ Args:
337
+ input: Input tensor
338
+ dim: Single dimension along which to compute mean
339
+ keepdim: Whether to keep the reduced dimension
340
+ dtype: Output dtype. If None, uses input dtype (or float32 for integer inputs)
341
+
342
+ Returns:
343
+ Tensor with mean values along specified dimension
344
+ """
345
+ assert input.is_cuda or input.is_xpu, 'Input must be a CUDA or XPU tensor'
346
+ assert -input.ndim <= dim < input.ndim, f'Invalid dimension {dim} for tensor with {input.ndim} dimensions'
347
+ if dim < 0:
348
+ dim = dim + input.ndim
349
+ if dtype is None:
350
+ if input.dtype in [torch.int8, torch.int16, torch.int32, torch.int64]:
351
+ dtype = torch.float32
352
+ else:
353
+ dtype = input.dtype
354
+ if input.dtype != dtype:
355
+ input = input.to(dtype)
356
+ shape = list(input.shape)
357
+ M = 1
358
+ for i in range(dim):
359
+ M *= shape[i]
360
+ N = shape[dim]
361
+ K = 1
362
+ for i in range(dim + 1, len(shape)):
363
+ K *= shape[i]
364
+ input_3d = input.reshape(M, N, K)
365
+ if keepdim:
366
+ output_shape = shape.copy()
367
+ output_shape[dim] = 1
368
+ else:
369
+ output_shape = shape[:dim] + shape[dim + 1:]
370
+ output = torch.empty(output_shape, dtype=dtype, device=input.device)
371
+ if keepdim:
372
+ output_2d = output.reshape(M, 1, K).squeeze(1)
373
+ else:
374
+ output_2d = output.reshape(M, K)
375
+ grid = (M * K,)
376
+ BLOCK_SIZE = 1024
377
+ mean_kernel[grid](input_3d, output_2d, input_3d.stride(0), input_3d.stride(1), input_3d.stride(2), output_2d.stride(0), output_2d.stride(1) if output_2d.ndim > 1 else 0, M, N, K, BLOCK_SIZE)
378
+ return output
379
+
380
+ def mean_batch_invariant(input: torch.Tensor, dim: list[int], keepdim: bool=False, dtype: torch.dtype | None=None) -> torch.Tensor:
381
+ assert dtype is None or dtype == torch.float32, f'unsupported dtype: {dtype}'
382
+ if len(dim) == 1:
383
+ return mean_dim(input, dim[0], keepdim=keepdim)
384
+ else:
385
+ assert input.dtype in {torch.float16, torch.bfloat16, torch.float32}, 'only float types supported for now'
386
+ n_elems = 1
387
+ for d in dim:
388
+ n_elems *= input.shape[d]
389
+ return torch.sum(input, dim=dim, keepdim=keepdim, dtype=torch.float32) / n_elems
390
+
391
+ @triton.jit
392
+ def bmm_kernel_persistent(a_ptr: tl.tensor, b_ptr: tl.tensor, c_ptr: tl.tensor, B: tl.int32, M: tl.int32, N: tl.int32, K: tl.int32, stride_ab: tl.int32, stride_am: tl.int32, stride_ak: tl.int32, stride_bb: tl.int32, stride_bk: tl.int32, stride_bn: tl.int32, stride_cb: tl.int32, stride_cm: tl.int32, stride_cn: tl.int32, BLOCK_SIZE_M: tl.constexpr, BLOCK_SIZE_N: tl.constexpr, BLOCK_SIZE_K: tl.constexpr, GROUP_SIZE_M: tl.constexpr, NUM_SMS: tl.constexpr, A_LARGE: tl.constexpr, B_LARGE: tl.constexpr, C_LARGE: tl.constexpr) -> None:
393
+ """
394
+ Batched matrix multiplication kernel that processes batches in parallel.
395
+ Each tile processes a (BLOCK_SIZE_M, BLOCK_SIZE_N) output block for a specific batch.
396
+ """
397
+ start_pid = tl.program_id(axis=0)
398
+ num_pid_m = tl.cdiv(M, BLOCK_SIZE_M)
399
+ num_pid_n = tl.cdiv(N, BLOCK_SIZE_N)
400
+ k_tiles = tl.cdiv(K, BLOCK_SIZE_K)
401
+ num_tiles_per_batch = num_pid_m * num_pid_n
402
+ num_tiles_total = B * num_tiles_per_batch
403
+ offs_k_for_mask = tl.arange(0, BLOCK_SIZE_K)
404
+ num_pid_in_group = GROUP_SIZE_M * num_pid_n
405
+ for tile_id in tl.range(start_pid, num_tiles_total, NUM_SMS, flatten=True):
406
+ batch_idx = tile_id // num_tiles_per_batch
407
+ tile_in_batch = tile_id % num_tiles_per_batch
408
+ (pid_m, pid_n) = _compute_pid(tile_in_batch, num_pid_in_group, num_pid_m, GROUP_SIZE_M, NUM_SMS)
409
+ start_m = pid_m * BLOCK_SIZE_M
410
+ start_n = pid_n * BLOCK_SIZE_N
411
+ offs_am = start_m + tl.arange(0, BLOCK_SIZE_M)
412
+ offs_bn = start_n + tl.arange(0, BLOCK_SIZE_N)
413
+ if A_LARGE:
414
+ offs_am = offs_am.to(tl.int64)
415
+ if B_LARGE:
416
+ offs_bn = offs_bn.to(tl.int64)
417
+ offs_am = tl.where(offs_am < M, offs_am, 0)
418
+ offs_bn = tl.where(offs_bn < N, offs_bn, 0)
419
+ offs_am = tl.max_contiguous(tl.multiple_of(offs_am, BLOCK_SIZE_M), BLOCK_SIZE_M)
420
+ offs_bn = tl.max_contiguous(tl.multiple_of(offs_bn, BLOCK_SIZE_N), BLOCK_SIZE_N)
421
+ if A_LARGE or B_LARGE:
422
+ batch_idx_typed = batch_idx.to(tl.int64)
423
+ else:
424
+ batch_idx_typed = batch_idx
425
+ accumulator = tl.zeros((BLOCK_SIZE_M, BLOCK_SIZE_N), dtype=tl.float32)
426
+ for ki in range(k_tiles):
427
+ if A_LARGE or B_LARGE:
428
+ offs_k = ki * BLOCK_SIZE_K + tl.arange(0, BLOCK_SIZE_K).to(tl.int64)
429
+ else:
430
+ offs_k = ki * BLOCK_SIZE_K + tl.arange(0, BLOCK_SIZE_K)
431
+ a_ptrs = a_ptr + (batch_idx_typed * stride_ab + offs_am[:, None] * stride_am + offs_k[None, :] * stride_ak)
432
+ b_ptrs = b_ptr + (batch_idx_typed * stride_bb + offs_k[:, None] * stride_bk + offs_bn[None, :] * stride_bn)
433
+ a = tl.load(a_ptrs, mask=offs_k_for_mask[None, :] < K - ki * BLOCK_SIZE_K, other=0.0)
434
+ b = tl.load(b_ptrs, mask=offs_k_for_mask[:, None] < K - ki * BLOCK_SIZE_K, other=0.0)
435
+ accumulator = tl.dot(a, b, accumulator)
436
+ offs_cm = pid_m * BLOCK_SIZE_M + tl.arange(0, BLOCK_SIZE_M)
437
+ offs_cn = pid_n * BLOCK_SIZE_N + tl.arange(0, BLOCK_SIZE_N)
438
+ if C_LARGE:
439
+ offs_cm = offs_cm.to(tl.int64)
440
+ offs_cn = offs_cn.to(tl.int64)
441
+ c_ptrs = c_ptr + batch_idx_typed * stride_cb + stride_cm * offs_cm[:, None] + stride_cn * offs_cn[None, :]
442
+ c_mask = (offs_cm[:, None] < M) & (offs_cn[None, :] < N)
443
+ if c_ptr.dtype.element_ty == tl.float8e4nv:
444
+ c = accumulator.to(tl.float8e4nv)
445
+ elif c_ptr.dtype.element_ty == tl.bfloat16:
446
+ c = accumulator.to(tl.bfloat16)
447
+ elif c_ptr.dtype.element_ty == tl.float32:
448
+ c = accumulator.to(tl.float32)
449
+ else:
450
+ c = accumulator.to(tl.float16)
451
+ tl.store(c_ptrs, c, mask=c_mask)
452
+
453
+ def bmm_batch_invariant(a: torch.Tensor, b: torch.Tensor, *, out: torch.Tensor | None=None) -> torch.Tensor:
454
+ if a.ndim == 3 and b.ndim == 3:
455
+ assert a.shape[0] == b.shape[0], 'Batch sizes must match'
456
+ assert a.shape[2] == b.shape[1], 'Incompatible dimensions'
457
+ assert a.dtype == b.dtype, 'Incompatible dtypes'
458
+ B = a.shape[0]
459
+ M = a.shape[1]
460
+ K = a.shape[2]
461
+ N = b.shape[2]
462
+ dtype = a.dtype
463
+ if out is None:
464
+ c = torch.empty((B, M, N), device=a.device, dtype=dtype)
465
+ else:
466
+ c = out
467
+ NUM_SMS = get_device_core_count()
468
+ configs = {torch.bfloat16: {'BLOCK_SIZE_M': 128, 'BLOCK_SIZE_N': 128, 'BLOCK_SIZE_K': 64, 'GROUP_SIZE_M': 8, 'num_stages': 3, 'num_warps': 8}, torch.float16: {'BLOCK_SIZE_M': 128, 'BLOCK_SIZE_N': 256, 'BLOCK_SIZE_K': 64, 'GROUP_SIZE_M': 8, 'num_stages': 3, 'num_warps': 8}, torch.float32: {'BLOCK_SIZE_M': 128, 'BLOCK_SIZE_N': 128, 'BLOCK_SIZE_K': 32, 'GROUP_SIZE_M': 8, 'num_stages': 3, 'num_warps': 8}}
469
+ config = configs.get(dtype)
470
+ if config is None:
471
+ raise ValueError(f'Unsupported dtype {dtype} for bmm_batch_invariant. Supported dtypes are: {list(configs.keys())}')
472
+ num_tiles_per_batch = triton.cdiv(M, config['BLOCK_SIZE_M']) * triton.cdiv(N, config['BLOCK_SIZE_N'])
473
+ num_tiles_total = B * num_tiles_per_batch
474
+ grid = (min(NUM_SMS, num_tiles_total),)
475
+ bmm_kernel_persistent[grid](a, b, c, B, M, N, K, a.stride(0), a.stride(1), a.stride(2), b.stride(0), b.stride(1), b.stride(2), c.stride(0), c.stride(1), c.stride(2), NUM_SMS=NUM_SMS, A_LARGE=a.numel() > 2 ** 31, B_LARGE=b.numel() > 2 ** 31, C_LARGE=c.numel() > 2 ** 31, **config)
476
+ return c
477
+ else:
478
+ raise ValueError(f'bmm_batch_invariant expects 3D tensors, got shapes {a.shape} and {b.shape}')
clairic_runtime/large.py ADDED
@@ -0,0 +1,204 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ from typing import TYPE_CHECKING
3
+ from . import media_state_prompt, po_image_supplement, text_ar, text_list_completion
4
+ from . import grounding, identifier_spelling
5
+ from .backend import ClairicFlashModel
6
+ from .media import media_warmup_groups
7
+
8
+ if TYPE_CHECKING:
9
+ from typing import Any
10
+ from .api import PredictRequest
11
+ from .backend import EncodedRequest
12
+
13
+
14
+ class Clairic27BModel(ClairicFlashModel):
15
+ RELEASE_MODEL_ID = "clairic-27b"
16
+ COMPACT_LIST_PROMPTS = False
17
+ DATE_ROLE_GUIDANCE = False
18
+ SOURCE_ROW_ELIGIBILITY = True
19
+ FINANCIAL_SERVICE_GUIDANCE = False
20
+ FINANCIAL_FEE_GUIDANCE = True
21
+ SPELL_VISUAL_PO_REFERENCES = True
22
+ FOCUS_SPARSE_IMAGES = False
23
+ PRESERVE_IMAGE_ENTITY_NAMES = True
24
+ FOCUS_IMAGE_PARTY_NAMES = False
25
+ LITERAL_IMAGE_PAYMENT_ROWS = True
26
+ BIND_IMAGE_FINANCIAL_LINES = False
27
+ IMAGE_TABLE_ROW_SCALE = 4
28
+ BIND_IMAGE_RAGGED_ROWS = False
29
+
30
+ def encode(self, request: PredictRequest, **options: Any) -> EncodedRequest:
31
+ supplement_disabled = options.pop("po_supplement_disabled", False)
32
+ encoded = self._encode_without_po_supplement(request, **options)
33
+ detail = any(
34
+ (
35
+ options.get(name)
36
+ for name in (
37
+ "identifier_view",
38
+ "party_name_view",
39
+ "physical_row_view",
40
+ "identifier_spelling_disabled",
41
+ "pdf_spelling_view",
42
+ "po_detail_view",
43
+ )
44
+ )
45
+ )
46
+ if (
47
+ type(self) is not Clairic27BModel
48
+ or supplement_disabled
49
+ or detail
50
+ or (not po_image_supplement.selected_fields(request, encoded))
51
+ ):
52
+ return encoded
53
+ if (
54
+ self.settings.model_id != "clairic-27b"
55
+ or self.max_concurrency != self.settings.max_concurrency
56
+ or self.max_concurrency != 1
57
+ ):
58
+ return encoded
59
+ return po_image_supplement.prepare(
60
+ request,
61
+ encoded,
62
+ encode_child=lambda child: self.encode(child, po_supplement_disabled=True),
63
+ tokenizer=self.tokenizer,
64
+ max_length=self.settings.max_length,
65
+ media_groups=media_warmup_groups,
66
+ )
67
+
68
+ def _encode_without_po_supplement(
69
+ self, request: PredictRequest, **options: Any
70
+ ) -> EncodedRequest:
71
+ detail = any(
72
+ (
73
+ options.get(name)
74
+ for name in (
75
+ "identifier_view",
76
+ "party_name_view",
77
+ "physical_row_view",
78
+ "identifier_spelling_disabled",
79
+ "pdf_spelling_view",
80
+ "po_detail_view",
81
+ )
82
+ )
83
+ )
84
+ if type(self) is Clairic27BModel and options.get("po_detail_view"):
85
+ options = {**options, "pdf_spelling_view": True}
86
+ encoded = super().encode(request, **options)
87
+ if type(self) is not Clairic27BModel or detail:
88
+ return encoded
89
+ (record, forecasts, tasks, typed, eos) = encoded
90
+ active = {name for (name, _, _) in tasks}
91
+ contracts = record.get("_meta", {}).get("identifier_spelling", {})
92
+ po_fields = {
93
+ name: request.fields[name]
94
+ for (name, contract) in contracts.items()
95
+ if name in active
96
+ and contract.get("wire") == identifier_spelling.VERSION
97
+ and (len(request.images) in (1, 2))
98
+ and (not request.documents)
99
+ }
100
+ number_fields = {
101
+ name: spec
102
+ for (name, spec) in request.fields.items()
103
+ if name in active
104
+ and spec.get("type") == "number"
105
+ and (spec.get("source_only") is True)
106
+ and (not spec.get("knowledge"))
107
+ and (not grounding.state_only(spec))
108
+ and (len(request.images) > 1 or request.documents)
109
+ }
110
+ selected = {**po_fields, **number_fields}
111
+ if not selected:
112
+ return encoded
113
+ originals = record.get("_original_images", ())
114
+ if len(originals) < len(request.images) or (
115
+ not request.documents and len(originals) != len(request.images)
116
+ ):
117
+ raise ValueError(
118
+ "27B scalar detail must retain every original image in order"
119
+ )
120
+ (child, _, replacements, child_typed, child_eos) = super().encode(
121
+ request.model_copy(update={"fields": selected}),
122
+ identifier_view=True,
123
+ pdf_spelling_view=True,
124
+ image_views=lambda: originals,
125
+ image_view_key="27b-literal-scalars-all-content2-v1",
126
+ )
127
+ if child_typed is not None or child_eos != eos:
128
+ raise ValueError(
129
+ "27B scalar detail must retain the original scalar AR contract"
130
+ )
131
+ by_name = {task[0]: task for task in replacements}
132
+ if set(by_name) != set(selected) or len(replacements) != len(selected):
133
+ raise ValueError(
134
+ "27B scalar detail tasks differ from selected public fields"
135
+ )
136
+ updated = [by_name.get(task[0], task) for task in tasks]
137
+ salts = dict(record.get("_ar_task_salts", {}))
138
+ for name in selected:
139
+ record["fields"][name] = child["fields"][name]
140
+ record["_ar_constraints"][name] = child["_ar_constraints"][name]
141
+ salts[name] = child["_cache_salt"]
142
+ record["_meta"]["model_document_scalar_view"] = {
143
+ "version": "27b-literal-scalars-all-content2-v1",
144
+ "fields": list(selected),
145
+ "po_fields": list(po_fields),
146
+ "number_fields": list(number_fields),
147
+ "image_count": len(originals),
148
+ }
149
+ record.update(
150
+ _ar_tasks=updated,
151
+ _ar_task_salts=salts,
152
+ _ar_prefix=[],
153
+ _ar_group_prefixes=[],
154
+ )
155
+ record["_ar_media_groups"] = media_warmup_groups(
156
+ updated,
157
+ default_salt=record["_cache_salt"],
158
+ task_salts=salts,
159
+ annotations=record["_meta"]["extraction_contract"]["fields"],
160
+ )
161
+ return (record, forecasts, updated, typed, eos)
162
+
163
+ def _encode_request(self, request: PredictRequest) -> EncodedRequest:
164
+ encoded = super()._encode_request(request)
165
+ if (
166
+ type(self) is Clairic27BModel
167
+ and self.settings.model_id == "clairic-27b"
168
+ and (self.max_concurrency == self.settings.max_concurrency == 1)
169
+ and bool(
170
+ getattr(request, "images", ()) or getattr(request, "documents", ())
171
+ )
172
+ ):
173
+ encoded[0]["_first_item_list_gating"] = True
174
+ fallback = encoded[0].get("_identifier_spelling_fallback")
175
+ if fallback is not None:
176
+ fallback["_first_item_list_gating"] = True
177
+ encoded = media_state_prompt.prepare(
178
+ request,
179
+ encoded,
180
+ tokenizer=self.tokenizer,
181
+ max_length=self.settings.max_length,
182
+ media_groups=media_warmup_groups,
183
+ )
184
+ return encoded
185
+
186
+ async def _ar_all(
187
+ self, record: dict[str, Any], eos: int
188
+ ) -> dict[str, dict[str, Any]]:
189
+ caller_record = record
190
+ if len(record["_ar_tasks"]) < 64 and (not record.get("_media_payload")):
191
+ record = {**record, "_ar_prefix": None, "_ar_group_prefixes": []}
192
+ if (
193
+ type(self) is Clairic27BModel
194
+ and self.settings.model_id == "clairic-27b"
195
+ and (self.max_concurrency == self.settings.max_concurrency == 1)
196
+ and text_list_completion.eligible(record, record["_ar_tasks"])
197
+ ):
198
+ predictions = await text_ar.text_ar_all(self, record, eos)
199
+ if record is not caller_record:
200
+ caller_record["_unexecuted_list_items"] = record[
201
+ "_unexecuted_list_items"
202
+ ]
203
+ return predictions
204
+ return await super()._ar_all(record, eos)
clairic_runtime/lists.py ADDED
@@ -0,0 +1,49 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ import re
3
+ from typing import Any
4
+
5
+ _CHAR_LIST_REQUEST = re.compile(
6
+ "\\b(?:(?:extract|list|return|split|read)\\s+(?:(?:the|of)\\s+)?|(?:each|every|all|individual|separate)\\s+)(?:(?:single|individual)\\s+)?(?:characters?|letters?|digits?|symbols?)\\b",
7
+ re.IGNORECASE,
8
+ )
9
+
10
+
11
+ class RejectRecord(ValueError):
12
+ def __init__(self, reason: str, field: str | None = None) -> None:
13
+ (self.reason, self.field) = (reason, field)
14
+ super().__init__(reason + (f": {field}" if field else ""))
15
+
16
+
17
+ def list_query_budget(text: str, spec: dict[str, Any]) -> tuple[int, str]:
18
+ maximum = spec.get("max_items")
19
+ if maximum is not None:
20
+ if isinstance(maximum, bool) or not isinstance(maximum, int) or maximum < 0:
21
+ raise RejectRecord("invalid_explicit_list_budget")
22
+ return (maximum + 1, "request_max_items")
23
+ instructions = str(spec.get("instructions", ""))
24
+ for match in _CHAR_LIST_REQUEST.finditer(instructions):
25
+ if not re.search(
26
+ "\\b(?:preserv\\w*|keep|retain\\w*|including|with)\\s*$",
27
+ instructions[max(0, match.start() - 25) : match.start()],
28
+ re.IGNORECASE,
29
+ ):
30
+ return (sum((not char.isspace() for char in text)) + 1, "source_characters")
31
+ lines = [line for line in text.splitlines() if line.strip()]
32
+ row_list = bool(
33
+ re.search(
34
+ "\\b(?:rows?|top to bottom|line items?|item lines?|receipt order|printed row order)\\b",
35
+ instructions,
36
+ re.IGNORECASE,
37
+ )
38
+ or (
39
+ re.search("\\b(?:receipt|invoice|table)\\b", instructions, re.IGNORECASE)
40
+ and re.search(
41
+ "\\b(?:items?|products?|quantit\\w*|prices?|amounts?|names?)\\b",
42
+ instructions,
43
+ re.IGNORECASE,
44
+ )
45
+ )
46
+ )
47
+ if row_list and len(lines) > 1:
48
+ return (len(lines) + 1, "nonblank_source_lines")
49
+ return (len(re.findall("\\w+|[^\\w\\s]", text)) + 1, "source_lexical_units")
clairic_runtime/math.py ADDED
@@ -0,0 +1,391 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Copyright 2025 The Qwen Team and The HuggingFace Inc. team. All rights reserved.
2
+ # Copyright 2026 Cloudflare, Inc.
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
6
+ # Unless required by applicable law or agreed to in writing, software distributed
7
+ # under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
8
+ # CONDITIONS OF ANY KIND, either express or implied. See the License for the
9
+ # specific language governing permissions and limitations under the License.
10
+
11
+ """Numerical operations for the Transformers Clairic backbone."""
12
+
13
+ from __future__ import annotations
14
+
15
+ from collections.abc import Callable
16
+ from types import MethodType
17
+ from typing import Any
18
+
19
+ import torch
20
+ from torch import nn
21
+ from torch.nn import functional as F
22
+ from torch.utils._python_dispatch import TorchDispatchMode
23
+ from transformers.cache_utils import Cache
24
+ from transformers.modeling_utils import ALL_ATTENTION_FUNCTIONS
25
+ from transformers.models.qwen3_5.modeling_qwen3_5 import (
26
+ Qwen3_5Attention, Qwen3_5DecoderLayer, Qwen3_5ForConditionalGeneration,
27
+ Qwen3_5GatedDeltaNet, Qwen3_5MLP, Qwen3_5RMSNorm,
28
+ Qwen3_5TextRotaryEmbedding, apply_mask_to_padding_states,
29
+ eager_attention_forward, torch_causal_conv1d_update,
30
+ )
31
+
32
+
33
+ def _matmul(a: torch.Tensor, b: torch.Tensor, bias: torch.Tensor | None = None) -> torch.Tensor:
34
+ if a.ndim != 2 or b.ndim != 2 or a.shape[1] != b.shape[0] or a.dtype != b.dtype:
35
+ raise ValueError("Expected aligned matrices with equal dtype")
36
+ from .kernels import _matmul_persistent_triton
37
+ return _matmul_persistent_triton(a, b, bias)
38
+
39
+
40
+ def _first_tensor(values: Any) -> torch.Tensor | None:
41
+ if isinstance(values, torch.Tensor):
42
+ return values
43
+ if isinstance(values, (list, tuple)):
44
+ return next((found for value in values if (found := _first_tensor(value)) is not None), None)
45
+ return None
46
+
47
+
48
+ class ReadoutMath(TorchDispatchMode):
49
+ """Apply CUDA readout operations within the current worker call."""
50
+
51
+ def __torch_dispatch__(self: ReadoutMath, function: Any, types: Any, args: tuple[Any, ...] = (),
52
+ kwargs: dict[str, Any] | None = None) -> Any:
53
+ kwargs = {} if kwargs is None else kwargs
54
+ first = _first_tensor(args)
55
+ eligible = first is not None and first.is_cuda and first.dtype in (torch.bfloat16, torch.float32)
56
+ if eligible and function in (torch.ops.aten.linear.default, torch.ops.aten.matmul.default,
57
+ torch.ops.aten.einsum.default,
58
+ torch.ops.aten.scaled_dot_product_attention.default,
59
+ torch.ops.aten._scaled_dot_product_attention_math.default):
60
+ with self:
61
+ result = function.decompose(*args, **kwargs)
62
+ if result is NotImplemented:
63
+ raise RuntimeError(f"Missing matrix decomposition: {function}")
64
+ return result
65
+ if eligible and function is torch.ops.aten._native_multi_head_attention.default:
66
+ with self:
67
+ return function._op_dk(torch._C.DispatchKey.CUDA, *args, **kwargs)
68
+ if eligible and function is torch.ops.aten.mm.default:
69
+ return _matmul(args[0], args[1])
70
+ if eligible and function is torch.ops.aten.addmm.default:
71
+ if kwargs.get("alpha", 1) != 1 or kwargs.get("beta", 1) != 1:
72
+ raise ValueError("Expected unit addmm alpha and beta")
73
+ return _matmul(args[1], args[2], args[0])
74
+ if eligible and function is torch.ops.aten.mm.dtype:
75
+ return _matmul(args[0].contiguous(), args[1].contiguous()).to(kwargs["out_dtype"])
76
+ if eligible and function is torch.ops.aten.bmm.default:
77
+ from .kernels import bmm_batch_invariant
78
+ return bmm_batch_invariant(args[0], args[1])
79
+ if eligible and function is torch.ops.aten.mean.dim:
80
+ from .kernels import mean_batch_invariant
81
+ return mean_batch_invariant(args[0], args[1], args[2] if len(args) > 2 else False,
82
+ dtype=kwargs.get("dtype"))
83
+ return function(*args, **kwargs)
84
+
85
+
86
+ def _linear_forward(original: Callable[..., Any], lm_head: bool) -> Callable[..., torch.Tensor]:
87
+ def forward(self: Any, input: torch.Tensor) -> torch.Tensor:
88
+ if (not input.is_cuda or input.dtype not in (torch.bfloat16, torch.float32)
89
+ or input.dtype != self.weight.dtype):
90
+ return original(input)
91
+ shape = input.shape[:-1]
92
+ flat = input.reshape(-1, input.shape[-1])
93
+ if lm_head:
94
+ output = _matmul(flat.contiguous(), self.weight.T.contiguous()).float()
95
+ else:
96
+ output = _matmul(flat, self.weight.T, self.bias)
97
+ return output.reshape(*shape, self.weight.shape[0])
98
+ return forward
99
+
100
+
101
+ def _norm(self: Qwen3_5RMSNorm, x: torch.Tensor) -> torch.Tensor:
102
+ value = x.float()
103
+ value = value * torch.rsqrt(value.square().mean(-1, keepdim=True) + self.eps)
104
+ return (value * (1.0 + self.weight.float())).to(self.weight.dtype)
105
+
106
+
107
+ def _decoder(self: Qwen3_5DecoderLayer, hidden_states: torch.Tensor,
108
+ position_embeddings: tuple[torch.Tensor, torch.Tensor],
109
+ attention_mask: torch.Tensor | None = None,
110
+ position_ids: torch.Tensor | None = None, past_key_values: Cache | None = None,
111
+ **kwargs: Any) -> torch.Tensor:
112
+ dtype = self.input_layernorm.weight.dtype
113
+ residual = hidden_states.to(dtype)
114
+ states = self.input_layernorm(hidden_states)
115
+ if self.layer_type == "linear_attention":
116
+ states = self.linear_attn(hidden_states=states, cache_params=past_key_values,
117
+ attention_mask=attention_mask, **kwargs)
118
+ else:
119
+ states, _ = self.self_attn(hidden_states=states, attention_mask=attention_mask,
120
+ position_ids=position_ids, past_key_values=past_key_values,
121
+ position_embeddings=position_embeddings, **kwargs)
122
+ merged = residual.float() + states.float()
123
+ states = self.post_attention_layernorm(merged)
124
+ return merged.to(dtype).float() + self.mlp(states).float()
125
+
126
+
127
+ def _mlp(self: Qwen3_5MLP, x: torch.Tensor) -> torch.Tensor:
128
+ gate, up = self.gate_proj(x), self.up_proj(x)
129
+ return self.down_proj((F.silu(gate.float()) * up.float()).to(gate.dtype))
130
+
131
+
132
+ def _rotate(q: torch.Tensor, k: torch.Tensor, cos: torch.Tensor,
133
+ sin: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
134
+ dim = cos.shape[-1]
135
+ half = dim // 2
136
+ c, s = cos[:, None, :, :half], sin[:, None, :, :half]
137
+
138
+ def apply(value: torch.Tensor) -> torch.Tensor:
139
+ first, second = value[..., :half].float(), value[..., half:dim].float()
140
+ rotated = torch.cat((first * c - second * s, second * c + first * s), -1)
141
+ return torch.cat((rotated.to(value.dtype), value[..., dim:]), -1)
142
+
143
+ return apply(q), apply(k)
144
+
145
+
146
+ def _dense(self: Qwen3_5Attention, hidden_states: torch.Tensor,
147
+ position_embeddings: tuple[torch.Tensor, torch.Tensor],
148
+ attention_mask: torch.Tensor | None, past_key_values: Cache | None = None,
149
+ **kwargs: Any) -> tuple[torch.Tensor, torch.Tensor | None]:
150
+ input_shape = hidden_states.shape[:-1]
151
+ hidden_shape = (*input_shape, -1, self.head_dim)
152
+ q_gate, raw_key = self.q_proj(hidden_states), self.k_proj(hidden_states)
153
+ if hidden_states.is_cuda:
154
+ from .kernels import dense_qk
155
+ query, key, gate = dense_qk(q_gate, raw_key, self.q_norm.weight,
156
+ self.k_norm.weight, *position_embeddings, self.q_norm.eps)
157
+ else:
158
+ query, gate = torch.chunk(q_gate.view(*input_shape, -1, self.head_dim * 2), 2, dim=-1)
159
+ gate = gate.reshape(*input_shape, -1)
160
+ query = self.q_norm(query.view(hidden_shape)).transpose(1, 2)
161
+ key = self.k_norm(raw_key.view(hidden_shape)).transpose(1, 2)
162
+ query, key = _rotate(query, key, *position_embeddings)
163
+ value = self.v_proj(hidden_states).view(hidden_shape).transpose(1, 2)
164
+ if past_key_values is not None:
165
+ key, value = past_key_values.update(key, value, self.layer_idx)
166
+ interface = ALL_ATTENTION_FUNCTIONS.get_interface(
167
+ self.config._attn_implementation, eager_attention_forward)
168
+ output, weights = interface(self, query, key, value, attention_mask,
169
+ dropout=0.0 if not self.training else self.attention_dropout,
170
+ scaling=self.scaling, **kwargs)
171
+ output = output.reshape(*input_shape, -1).contiguous()
172
+ output = (output.float() * torch.sigmoid(gate.float())).to(output.dtype)
173
+ return self.o_proj(output), weights
174
+
175
+
176
+ def _gdn(self: Qwen3_5GatedDeltaNet, hidden_states: torch.Tensor,
177
+ cache_params: Cache | None = None, attention_mask: torch.Tensor | None = None,
178
+ **kwargs: Any) -> torch.Tensor:
179
+ hidden_states = apply_mask_to_padding_states(hidden_states, attention_mask)
180
+ batch, length, _ = hidden_states.shape
181
+ cached = cache_params is not None and cache_params.has_previous_state(self.layer_idx)
182
+ if cached:
183
+ conv_state = cache_params.layers[self.layer_idx].conv_states
184
+ recurrent_state = cache_params.layers[self.layer_idx].recurrent_states
185
+ mixed = self.in_proj_qkv(hidden_states).transpose(1, 2)
186
+ z = self.in_proj_z(hidden_states).reshape(batch, length, -1, self.head_v_dim)
187
+ b, a = self.in_proj_b(hidden_states), self.in_proj_a(hidden_states)
188
+ if cached and length == 1:
189
+ mixed = self.causal_conv1d_update(mixed, conv_state, self.conv1d.weight.squeeze(1),
190
+ self.conv1d.bias, self.activation)
191
+ else:
192
+ if cached:
193
+ mixed = torch.cat((conv_state, mixed), -1)
194
+ if cache_params is not None:
195
+ state = F.pad(mixed, (self.conv_kernel_size - mixed.shape[-1], 0))
196
+ cache_params.update_conv_state(state, self.layer_idx)
197
+ if self.causal_conv1d_fn is not None:
198
+ mixed = self.causal_conv1d_fn(x=mixed, weight=self.conv1d.weight.squeeze(1),
199
+ bias=self.conv1d.bias, activation=self.activation, seq_idx=kwargs.get("seq_idx"))
200
+ else:
201
+ mixed = F.silu(self.conv1d(mixed)[:, :, :mixed.shape[-1]])
202
+ if cached:
203
+ mixed = mixed[:, :, -length:]
204
+ query, key, value = torch.split(mixed.transpose(1, 2),
205
+ (self.key_dim, self.key_dim, self.value_dim), -1)
206
+ query = query.reshape(batch, length, -1, self.head_k_dim)
207
+ key = key.reshape(batch, length, -1, self.head_k_dim)
208
+ value = value.reshape(batch, length, -1, self.head_v_dim)
209
+ beta = b.float().sigmoid() if cached and length == 1 else b.sigmoid()
210
+ g = -self.A_log.float().exp() * F.softplus(a.float() + self.dt_bias)
211
+ if self.num_v_heads // self.num_k_heads > 1:
212
+ groups = self.num_v_heads // self.num_k_heads
213
+ query, key = query.repeat_interleave(groups, 2), key.repeat_interleave(groups, 2)
214
+ if cached and length == 1:
215
+ output, state = self.recurrent_gated_delta_rule(query, key, value, g=g, beta=beta,
216
+ initial_state=recurrent_state, output_final_state=cache_params is not None,
217
+ use_qk_l2norm_in_kernel=True)
218
+ else:
219
+ output, state = self.chunk_gated_delta_rule(query, key, value, g=g, beta=beta,
220
+ initial_state=recurrent_state if cached else None,
221
+ output_final_state=cache_params is not None, use_qk_l2norm_in_kernel=True,
222
+ cu_seqlens=kwargs.get("cu_seq_lens_q"))
223
+ if cache_params is not None:
224
+ cache_params.update_recurrent_state(state, self.layer_idx)
225
+ output = self.norm(output.reshape(-1, self.head_v_dim), z.reshape(-1, self.head_v_dim))
226
+ return self.out_proj(output.reshape(batch, length, -1))
227
+
228
+
229
+ def _gated_norm(self: Any, x: torch.Tensor, z: torch.Tensor) -> torch.Tensor:
230
+ epsilon = getattr(self, "eps", getattr(self, "variance_epsilon", None))
231
+ if (x.ndim != 2 or z.shape != x.shape or self.weight.shape != (128,)
232
+ or x.shape[-1] != 128 or x.shape[0] < 1 or epsilon != 1e-6
233
+ or x.dtype != z.dtype or self.weight.dtype != x.dtype
234
+ or any(v.device != x.device or v.stride(-1) != 1 for v in (x, z, self.weight))):
235
+ raise ValueError("Unsupported gated normalization inputs")
236
+ from .kernels import gated_norm
237
+ return gated_norm(x, z, self.weight, epsilon)
238
+
239
+
240
+ def _nonoverlapping(value: torch.Tensor) -> None:
241
+ span = 1
242
+ for stride, size in sorted((s, n) for s, n in zip(value.stride(), value.shape, strict=True) if n > 1):
243
+ if stride < span:
244
+ raise ValueError("Overlapping convolution tensor")
245
+ span += (size - 1) * stride
246
+
247
+
248
+ def _validate_conv(x: torch.Tensor, weight: torch.Tensor, bias: torch.Tensor | None,
249
+ activation: str | None) -> None:
250
+ if (x.ndim != 3 or weight.ndim != 2 or tuple(weight.shape) != (x.shape[1], 4)
251
+ or min(x.shape) < 1 or weight.dtype != x.dtype or weight.device != x.device
252
+ or not weight.is_contiguous()):
253
+ raise ValueError("Expected nonempty input[B,D,T] and matching contiguous weight[D,4]")
254
+ if bias is not None and (tuple(bias.shape) != (x.shape[1],) or bias.dtype != x.dtype
255
+ or bias.device != x.device or not bias.is_contiguous()):
256
+ raise ValueError("Expected a matching contiguous bias[D]")
257
+ if activation not in (None, "silu", "swish"):
258
+ raise ValueError("Unsupported convolution activation")
259
+ _nonoverlapping(x)
260
+
261
+
262
+ def _prefill(x: torch.Tensor, weight: torch.Tensor, bias: torch.Tensor | None = None,
263
+ activation: str | None = None, seq_idx: torch.Tensor | None = None
264
+ ) -> torch.Tensor:
265
+ if seq_idx is not None:
266
+ raise ValueError("Packed convolution sequence indices are unsupported")
267
+ if not x.is_cuda or x.dtype != torch.bfloat16:
268
+ output = F.conv1d(x, weight.unsqueeze(1), bias, padding=weight.shape[-1] - 1,
269
+ groups=x.shape[1])[:, :, :x.shape[2]]
270
+ return F.silu(output) if activation is not None else output
271
+ _validate_conv(x, weight, bias, activation)
272
+ from .kernels import prefill
273
+ return prefill(x, weight, bias, activation)
274
+
275
+
276
+ def _update(x: torch.Tensor, state: torch.Tensor, weight: torch.Tensor,
277
+ bias: torch.Tensor | None = None, activation: str | None = None) -> torch.Tensor:
278
+ if not x.is_cuda or x.dtype != torch.bfloat16:
279
+ return torch_causal_conv1d_update(x, state, weight, bias, activation)
280
+ _validate_conv(x, weight, bias, activation)
281
+ if (x.shape[2] != 1 or tuple(state.shape) != (x.shape[0], x.shape[1], 4)
282
+ or state.dtype != x.dtype or state.device != x.device):
283
+ raise ValueError("Expected singleton input and matching live cache[B,D,4]")
284
+ _nonoverlapping(state)
285
+ pointer = state.untyped_storage().data_ptr()
286
+ if any(v.untyped_storage().data_ptr() == pointer for v in (x, weight, bias) if v is not None):
287
+ raise ValueError("Convolution cache must not alias input, weight or bias")
288
+ from .kernels import update
289
+ return update(x, state, weight, bias, activation)
290
+
291
+
292
+ def install(backbone: Qwen3_5ForConditionalGeneration, head: nn.Module | None = None
293
+ ) -> Callable[[], None]:
294
+ """Configure this backbone and return an idempotent cleanup function."""
295
+ def native_cleanup() -> None:
296
+ return None
297
+
298
+ language = backbone.model.language_model
299
+ if language.embed_tokens.weight.dtype != torch.bfloat16:
300
+ return native_cleanup
301
+ rotary = language.rotary_emb
302
+ rope = rotary.config.rope_parameters
303
+ if (rope.get("rope_type") != "default" or rope.get("partial_rotary_factor") != 0.25
304
+ or rope.get("rope_theta") != 10000000.0 or rotary.config.head_dim != 256
305
+ or rope.get("mrope_interleaved") is not True
306
+ or list(rope.get("mrope_section", ())) != [11, 11, 10]
307
+ or language.config.hidden_act != "silu"):
308
+ raise ValueError("Unsupported Clairic rotary configuration")
309
+ forwards: list[tuple[nn.Module, bool, Any, Any]] = []
310
+ convolutions: list[tuple[Any, Any, Any]] = []
311
+ caches: dict[torch.device, torch.Tensor] = {}
312
+ closed = False
313
+
314
+ def restore() -> None:
315
+ nonlocal closed
316
+ if closed:
317
+ return
318
+ closed = True
319
+ for module, original_prefill, original_update in reversed(convolutions):
320
+ module.causal_conv1d_fn, module.causal_conv1d_update = original_prefill, original_update
321
+ for module, had_override, original, installed in reversed(forwards):
322
+ if module.forward == installed:
323
+ if had_override:
324
+ module.forward = original
325
+ else:
326
+ del module.forward
327
+ caches.clear()
328
+
329
+ def bind(module: nn.Module, function: Callable[..., Any], argument: str = "hidden_states",
330
+ parameter: torch.Tensor | None = None, *, cuda_only: bool = False) -> None:
331
+ original = module.forward
332
+
333
+ def forward(self: nn.Module, *args: Any, **kwargs: Any) -> Any:
334
+ value = args[0] if args else kwargs[argument]
335
+ dtype = parameter.dtype if parameter is not None else value.dtype
336
+ active = dtype == torch.bfloat16 and (not cuda_only or value.is_cuda)
337
+ return function(self, *args, **kwargs) if active else original(*args, **kwargs)
338
+
339
+ installed = MethodType(forward, module)
340
+ forwards.append((module, "forward" in module.__dict__, original, installed))
341
+ module.forward = installed
342
+
343
+ def text_rotary(self: Qwen3_5TextRotaryEmbedding, x: torch.Tensor,
344
+ position_ids: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
345
+ if x.device not in caches:
346
+ dim = int(self.config.head_dim * rope["partial_rotary_factor"])
347
+ with torch.no_grad(), torch.autocast(device_type=x.device.type, enabled=False):
348
+ inv = 1.0 / (rope["rope_theta"] ** (
349
+ torch.arange(0, dim, 2, dtype=torch.float32, device=x.device) / dim))
350
+ positions = torch.arange(self.config.max_position_embeddings,
351
+ dtype=torch.float32, device=x.device)
352
+ frequencies = torch.einsum("i,j -> ij", positions, inv)
353
+ caches[x.device] = torch.cat((frequencies.cos(), frequencies.sin()), -1)
354
+ positions = position_ids[0] if position_ids.ndim == 3 else position_ids
355
+ cos, sin = caches[x.device][positions].chunk(2, -1)
356
+ return torch.cat((cos, cos), -1), torch.cat((sin, sin), -1)
357
+
358
+ try:
359
+ for module in language.modules():
360
+ if isinstance(module, Qwen3_5RMSNorm):
361
+ bind(module, _norm, "x", module.weight)
362
+ elif isinstance(module, Qwen3_5DecoderLayer):
363
+ bind(module, _decoder, parameter=module.input_layernorm.weight)
364
+ elif isinstance(module, Qwen3_5MLP):
365
+ bind(module, _mlp, "x", module.gate_proj.weight)
366
+ elif isinstance(module, Qwen3_5Attention):
367
+ bind(module, _dense, parameter=module.q_proj.weight)
368
+ elif isinstance(module, Qwen3_5GatedDeltaNet):
369
+ bind(module, _gdn, parameter=module.in_proj_qkv.weight)
370
+ bind(module.norm, _gated_norm, "x", module.norm.weight, cuda_only=True)
371
+ convolutions.append((module, module.causal_conv1d_fn, module.causal_conv1d_update))
372
+ module.causal_conv1d_fn, module.causal_conv1d_update = _prefill, _update
373
+ bind(rotary, text_rotary, "x")
374
+ lm_head = backbone.get_output_embeddings()
375
+ roots = (backbone,) if head is None else (backbone, head)
376
+ seen: set[int] = set()
377
+ for root in roots:
378
+ for module in root.modules():
379
+ if id(module) in seen or (type(module) is not nn.Linear and module is not lm_head):
380
+ continue
381
+ seen.add(id(module))
382
+ if module.weight.dtype not in (torch.bfloat16, torch.float32):
383
+ continue
384
+ original = module.forward
385
+ installed = MethodType(_linear_forward(original, module is lm_head), module)
386
+ forwards.append((module, "forward" in module.__dict__, original, installed))
387
+ module.forward = installed
388
+ except BaseException:
389
+ restore()
390
+ raise
391
+ return restore
clairic_runtime/media.py ADDED
@@ -0,0 +1,98 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ from collections.abc import Sequence
3
+ from typing import Any
4
+
5
+
6
+ def batch_image_data(media: Sequence[Any]) -> list[Any]:
7
+ if all((item is None for item in media)):
8
+ return list(media)
9
+ return [item if item is not None else [] for item in media]
10
+
11
+
12
+ def _grid_identity(grid: Any) -> Any:
13
+ if hasattr(grid, "tolist"):
14
+ grid = grid.tolist()
15
+ if isinstance(grid, (list, tuple)):
16
+ return tuple((_grid_identity(value) for value in grid))
17
+ if isinstance(grid, (str, int, float, bool, type(None))):
18
+ return grid
19
+ return ("opaque", id(grid))
20
+
21
+
22
+ def _media_identity(media: Any) -> tuple[Any, ...]:
23
+ if media is None:
24
+ return ("text",)
25
+ if not isinstance(media, list) or not media:
26
+ return ("opaque", id(media))
27
+ identities = []
28
+ for item in media:
29
+ if (
30
+ not isinstance(item, dict)
31
+ or item.get("format") != "processor_output"
32
+ or (not isinstance(item.get("clair_media_digest"), str))
33
+ or (item.get("pixel_values") is None)
34
+ ):
35
+ return ("opaque", id(media))
36
+ identities.append(
37
+ (
38
+ item["clair_media_digest"],
39
+ id(item["pixel_values"]),
40
+ _grid_identity(item.get("image_grid_thw")),
41
+ )
42
+ )
43
+ return ("prepared", tuple(identities))
44
+
45
+
46
+ def _common_prefix(tasks: list[tuple[str, list[int], Any]]) -> list[int]:
47
+ (first, last) = (min((task[1] for task in tasks)), max((task[1] for task in tasks)))
48
+ length = next(
49
+ (i for (i, (left, right)) in enumerate(zip(first, last)) if left != right),
50
+ min(len(first), len(last)),
51
+ )
52
+ return list(first[:length])
53
+
54
+
55
+ def media_warmup_groups(
56
+ tasks: list[tuple[str, list[int], Any]],
57
+ *,
58
+ default_salt: str,
59
+ task_salts: dict[str, str] | None = None,
60
+ annotations: dict[str, dict[str, Any]] | None = None,
61
+ min_prefix_tokens: int = 128,
62
+ ) -> list[dict[str, Any]]:
63
+ (task_salts, annotations) = (task_salts or {}, annotations or {})
64
+ partitions: dict[tuple[str, tuple[Any, ...]], dict[str, Any]] = {}
65
+ for task in tasks:
66
+ (name, _, media) = task
67
+ salt = task_salts.get(name, default_salt)
68
+ key = (salt, _media_identity(media))
69
+ partitions.setdefault(key, {"media": media, "salt": salt, "tasks": []})[
70
+ "tasks"
71
+ ].append(task)
72
+ records = []
73
+ for partition in partitions.values():
74
+ members = partition["tasks"]
75
+ if len(members) < 2:
76
+ continue
77
+ prefix = _common_prefix(members)
78
+ if len(prefix) < min_prefix_tokens:
79
+ prefix = []
80
+ parents: dict[str, list[tuple[str, list[int], Any]]] = {}
81
+ for task in members:
82
+ parent = annotations.get(task[0], {}).get("parent")
83
+ if parent:
84
+ parents.setdefault(parent, []).append(task)
85
+ subgroups = [
86
+ _common_prefix(group) for group in parents.values() if len(group) > 1
87
+ ]
88
+ subgroups = [group for group in subgroups if group and group != prefix]
89
+ if prefix or subgroups:
90
+ records.append(
91
+ {
92
+ "prefix_ids": prefix,
93
+ "media": partition["media"],
94
+ "salt": partition["salt"],
95
+ "group_prefix_ids": subgroups,
96
+ }
97
+ )
98
+ return records
clairic_runtime/media_cache.py ADDED
@@ -0,0 +1,105 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ from collections.abc import Iterable
3
+ from typing import TYPE_CHECKING, Any, cast
4
+
5
+ if TYPE_CHECKING:
6
+ from .api import ClairImage
7
+ from .documents import ClairDocument
8
+ from PIL import Image
9
+ from .model import EncodedMedia
10
+ import copy
11
+ import hashlib
12
+ import uuid
13
+ from collections import OrderedDict
14
+ from dataclasses import dataclass
15
+
16
+
17
+ @dataclass(frozen=True)
18
+ class PreparedImages:
19
+ images: list[Image.Image]
20
+ media: EncodedMedia
21
+ payload: list[dict[str, Any]]
22
+ salt: str
23
+ size: int
24
+ source_images: list[Image.Image] | None = None
25
+
26
+
27
+ class ImageCache:
28
+ _share_image_row_description: bool
29
+
30
+ def __init__(
31
+ self, max_bytes: int = 128 * 1024 * 1024, max_entries: int = 8
32
+ ) -> None:
33
+ (self.max_bytes, self.max_entries) = (max_bytes, max_entries)
34
+ self.namespace = uuid.uuid4().hex
35
+ self.entries: OrderedDict[str, PreparedImages] = OrderedDict()
36
+ self.size = 0
37
+
38
+ def clear(self) -> None:
39
+ self.entries.clear()
40
+ self.size = 0
41
+
42
+ @staticmethod
43
+ def key(images: Iterable[ClairImage | ClairDocument]) -> str:
44
+ digest = hashlib.sha256()
45
+ for image in images:
46
+ content = image.base64.encode()
47
+ digest.update(getattr(image, "content_type", "image").encode())
48
+ digest.update(str(getattr(image, "rotation", 0)).encode())
49
+ digest.update(bytes(["rotation" in getattr(image, "model_fields_set", ())]))
50
+ digest.update(len(content).to_bytes(8, "big"))
51
+ digest.update(content)
52
+ return digest.hexdigest()
53
+
54
+ def get(self, key: str) -> PreparedImages | None:
55
+ entry = self.entries.get(key)
56
+ if entry is not None:
57
+ self.entries.move_to_end(key)
58
+ return entry
59
+
60
+ def put(
61
+ self,
62
+ key: str,
63
+ images: list[Image.Image],
64
+ media: EncodedMedia,
65
+ payload: list[dict[str, Any]],
66
+ *,
67
+ source_images: list[Image.Image] | None = None,
68
+ ) -> PreparedImages:
69
+ tensors = {}
70
+ for mapping in (cast(dict[str, Any], media.media), *payload):
71
+ for value in mapping.values():
72
+ if hasattr(value, "numel"):
73
+ tensors[id(value)] = value.numel() * value.element_size()
74
+ source_images = images if source_images is None else source_images
75
+ retained = {id(image): image for image in [*images, *source_images]}
76
+ size = sum(tensors.values()) + sum(
77
+ (image.width * image.height * 3 for image in retained.values())
78
+ )
79
+ if (
80
+ media.media
81
+ and len(payload) == 1
82
+ and ("pixel_values" in media.media)
83
+ and ("pixel_values" in payload[0])
84
+ ):
85
+ media = copy.copy(media)
86
+ media.media = {
87
+ **cast(dict[str, Any], media.media),
88
+ "pixel_values": payload[0]["pixel_values"],
89
+ }
90
+ entry = PreparedImages(
91
+ images, media, payload, uuid.uuid4().hex, size, source_images
92
+ )
93
+ if size > self.max_bytes:
94
+ return entry
95
+ old = self.entries.pop(key, None)
96
+ if old is not None:
97
+ self.size -= old.size
98
+ while self.entries and (
99
+ self.size + size > self.max_bytes or len(self.entries) >= self.max_entries
100
+ ):
101
+ (_, old) = self.entries.popitem(last=False)
102
+ self.size -= old.size
103
+ self.entries[key] = entry
104
+ self.size += size
105
+ return entry
clairic_runtime/media_state_prompt.py ADDED
@@ -0,0 +1,139 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ from typing import TYPE_CHECKING
3
+
4
+ if TYPE_CHECKING:
5
+ from collections.abc import Callable
6
+ from typing import Any
7
+ from .api import PredictRequest
8
+ from .backend import ARTask, EncodedRequest
9
+ from transformers import PreTrainedTokenizerBase
10
+
11
+
12
+ def eligible(request: PredictRequest) -> bool:
13
+ if not request.state or not (request.images or request.documents):
14
+ return False
15
+ if len(request.images) > 1:
16
+ return True
17
+ from . import grounding
18
+
19
+ return any(
20
+ (
21
+ spec.get("type") == "boolean"
22
+ and (not spec.get("knowledge"))
23
+ and (not grounding.state_only(spec))
24
+ for spec in request.fields.values()
25
+ )
26
+ )
27
+
28
+
29
+ def rewrite_media_evidence(
30
+ task: ARTask,
31
+ *,
32
+ record: dict[str, Any],
33
+ tokenizer: PreTrainedTokenizerBase,
34
+ max_length: int,
35
+ ) -> ARTask:
36
+ from . import ar
37
+
38
+ (name, ids, media) = task
39
+ if media is None:
40
+ raise ValueError("Media evidence guidance requires actual task media")
41
+ source_ids = list(ids)
42
+ text = tokenizer.decode(
43
+ ids, skip_special_tokens=False, clean_up_tokenization_spaces=False
44
+ )
45
+ if tokenizer.encode(text, add_special_tokens=False) != source_ids:
46
+ raise ValueError(
47
+ "Media evidence prompt must make a lossless tokenizer roundtrip"
48
+ )
49
+ instruction = ar.instruction(record, name, compact_lists=False).rstrip()
50
+ boundary = instruction + "\n\nDocument:\n"
51
+ existing = (
52
+ ar.MEDIA_EVIDENCE_INSTRUCTION
53
+ + "\n\n"
54
+ + instruction
55
+ + "\n\nAccompanying text:\n"
56
+ )
57
+ if text.count(existing) == 1:
58
+ return task
59
+ if text.count(boundary) != 1 or ar.MEDIA_EVIDENCE_INSTRUCTION in text:
60
+ raise ValueError(
61
+ "Expected exactly one original instruction and accompanying-state boundary"
62
+ )
63
+ revised = text.replace(boundary, existing)
64
+ revised_ids = tokenizer.encode(revised, add_special_tokens=False)
65
+ if (
66
+ tokenizer.decode(
67
+ revised_ids, skip_special_tokens=False, clean_up_tokenization_spaces=False
68
+ )
69
+ != revised
70
+ ):
71
+ raise ValueError(
72
+ "Media evidence revised prompt must make a lossless tokenizer roundtrip"
73
+ )
74
+ if len(revised_ids) > max_length:
75
+ raise ValueError("Media evidence prompt exceeds the complete model context")
76
+ return (name, revised_ids, media)
77
+
78
+
79
+ def prepare(
80
+ request: PredictRequest,
81
+ encoded: EncodedRequest,
82
+ *,
83
+ tokenizer: PreTrainedTokenizerBase,
84
+ max_length: int,
85
+ media_groups: Callable[..., list[dict[str, Any]]],
86
+ ) -> EncodedRequest:
87
+ if not eligible(request):
88
+ return encoded
89
+ from . import grounding
90
+
91
+ (record, forecasts, tasks, typed, eos) = encoded
92
+ annotations = (
93
+ record.get("_meta", {}).get("extraction_contract", {}).get("fields", {})
94
+ )
95
+ meta = record.get("_meta", {})
96
+ protected = set(meta.get("identifier_spelling", {})) | set(
97
+ meta.get("model_po_supplement", {}).get("fields", ())
98
+ )
99
+ multi_image = len(request.images) > 1
100
+ updated: list[ARTask] = []
101
+ changed = False
102
+ for task in tasks:
103
+ (name, _, media) = task
104
+ parent = annotations.get(name, {}).get("parent", name)
105
+ spec = request.fields.get(parent)
106
+ selected = (
107
+ media is not None
108
+ and name not in protected
109
+ and (parent not in protected)
110
+ and (spec is not None)
111
+ and (not spec.get("knowledge"))
112
+ and (not grounding.state_only(spec))
113
+ and (multi_image or (name == parent and spec.get("type") == "boolean"))
114
+ )
115
+ revised = task
116
+ if selected:
117
+ try:
118
+ revised = rewrite_media_evidence(
119
+ task, record=record, tokenizer=tokenizer, max_length=max_length
120
+ )
121
+ except ValueError:
122
+ return encoded
123
+ updated.append(revised)
124
+ changed |= revised is not task
125
+ if not changed:
126
+ return encoded
127
+ revised_record = {
128
+ **record,
129
+ "_ar_tasks": updated,
130
+ "_ar_prefix": [],
131
+ "_ar_group_prefixes": [],
132
+ }
133
+ revised_record["_ar_media_groups"] = media_groups(
134
+ updated,
135
+ default_salt=record["_cache_salt"],
136
+ task_salts=record.get("_ar_task_salts", {}),
137
+ annotations=annotations,
138
+ )
139
+ return (revised_record, forecasts, updated, typed, eos)
clairic_runtime/model.py ADDED
The diff for this file is too large to render. See raw diff
 
clairic_runtime/native.py ADDED
@@ -0,0 +1,441 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Constrained extraction and typed readouts using native Transformers models."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ import concurrent.futures
7
+ import copy
8
+ import json
9
+ import threading
10
+ from collections.abc import Callable
11
+ from contextlib import nullcontext
12
+ from collections import defaultdict
13
+ from pathlib import Path
14
+ from typing import Any
15
+
16
+ import torch
17
+ from . import model as cm
18
+ from .readout import load_head, read_record
19
+ from .math import ReadoutMath, install as install_math
20
+ from .vision_cache import VisionBatchCache
21
+
22
+ _FLASH_ATTENTION = 'kernels-community/flash-attn3@e29f138fc363b396e5d2706c8a5f6fa7d36f41e0'
23
+
24
+
25
+ class _ConstrainedScores:
26
+ """Capture probabilities after applying the schema's grammar constraints."""
27
+
28
+ def __init__(self, processor: Any, score_ids: list[int], size: int) -> None:
29
+ self.processor = processor
30
+ self.score_ids = score_ids
31
+ self.chosen: list[list[tuple[float, int, None]]] = [[] for _ in range(size)]
32
+ self.first: list[list[tuple[float, int, None]]] = [[] for _ in range(size)]
33
+
34
+ def __call__(self, input_ids: torch.Tensor, scores: torch.Tensor) -> torch.Tensor:
35
+ masked = self.processor(input_ids, scores.clone())
36
+ logprobs = torch.log_softmax(masked.float(), dim=-1)
37
+ if not self.chosen[0]:
38
+ selected = logprobs[:, self.score_ids].cpu().tolist()
39
+ self.first = [
40
+ [
41
+ (float(value), token, None)
42
+ for token, value in zip(self.score_ids, row, strict=True)
43
+ ]
44
+ for row in selected
45
+ ]
46
+ choices = masked.argmax(dim=-1)
47
+ values = logprobs.gather(1, choices[:, None])[:, 0].cpu().tolist()
48
+ for row, token, value in zip(
49
+ self.chosen, choices.cpu().tolist(), values, strict=True
50
+ ):
51
+ row.append((float(value), int(token), None))
52
+ return masked
53
+
54
+
55
+ class _CancellationCriteria:
56
+ def __init__(self, cancelled: threading.Event) -> None:
57
+ self.cancelled = cancelled
58
+
59
+ def __call__(
60
+ self, input_ids: torch.Tensor, scores: torch.Tensor, **kwargs: Any
61
+ ) -> torch.Tensor:
62
+ return torch.full(
63
+ (input_ids.shape[0],),
64
+ self.cancelled.is_set(),
65
+ dtype=torch.bool,
66
+ device=input_ids.device,
67
+ )
68
+
69
+
70
+ class TransformersEngine:
71
+ """Share one Transformers backbone between extraction and typed readouts."""
72
+
73
+ def __init__(
74
+ self,
75
+ backbone: Any,
76
+ head: cm.ClairicHead,
77
+ tokenizer: Any,
78
+ *,
79
+ batch_size: int = 8,
80
+ text_batch_size: int | None = None,
81
+ batch_token_budget: int = 8192,
82
+ ) -> None:
83
+ import xgrammar as xgr
84
+
85
+ self.backbone = backbone.eval()
86
+ self.head = head.to(backbone.device).float().eval()
87
+ self.tokenizer = tokenizer
88
+ self.batch_size = max(1, int(batch_size))
89
+ self.text_batch_size = (
90
+ self.batch_size if text_batch_size is None else max(1, int(text_batch_size))
91
+ )
92
+ self.batch_token_budget = max(1, int(batch_token_budget))
93
+ self.device, self.dtype = backbone.device, backbone.dtype
94
+ self.eos = tokenizer.convert_tokens_to_ids("<|im_end|>")
95
+ self.image_token = int(backbone.config.image_token_id)
96
+ info = xgr.TokenizerInfo.from_huggingface(
97
+ tokenizer,
98
+ vocab_size=backbone.get_output_embeddings().weight.shape[0],
99
+ stop_token_ids=[self.eos],
100
+ )
101
+ self.compiler = xgr.GrammarCompiler(info, max_threads=2)
102
+ self._worker = concurrent.futures.ThreadPoolExecutor(
103
+ max_workers=1, thread_name_prefix="clairic-model"
104
+ )
105
+ self._vision_cache = VisionBatchCache()
106
+ self._uncached_image_features = self.backbone.model.get_image_features
107
+ self.backbone.model.get_image_features = self._image_features
108
+ self._restore_math: Callable[[], None] | None = None
109
+
110
+ def begin_request(self) -> None:
111
+ self._vision_cache.begin()
112
+
113
+ async def end_request(self) -> None:
114
+ await asyncio.get_running_loop().run_in_executor(
115
+ self._worker, self._vision_cache.clear
116
+ )
117
+
118
+ def _image_features(
119
+ self,
120
+ pixel_values: torch.Tensor,
121
+ image_grid_thw: torch.Tensor | None = None,
122
+ **kwargs: Any,
123
+ ) -> Any:
124
+ return self._vision_cache.features(
125
+ self._uncached_image_features,
126
+ self.backbone.model.visual,
127
+ pixel_values,
128
+ image_grid_thw,
129
+ **kwargs,
130
+ )
131
+
132
+ @classmethod
133
+ def load(
134
+ cls,
135
+ path: Path,
136
+ tokenizer: Any,
137
+ *,
138
+ device: str = "cuda",
139
+ dtype: Any = None,
140
+ batch_size: int = 8,
141
+ text_batch_size: int | None = None,
142
+ batch_token_budget: int = 8192,
143
+ **kwargs: Any,
144
+ ) -> TransformersEngine:
145
+ from transformers import Qwen3_5ForConditionalGeneration
146
+
147
+ class _NativeQwen3_5ForConditionalGeneration(Qwen3_5ForConditionalGeneration):
148
+ _keep_in_fp32_modules_strict: list[str] = ["A_log"]
149
+
150
+ if dtype is None:
151
+ dtype = torch.bfloat16 if str(device).startswith("cuda") else torch.float32
152
+ if isinstance(dtype, str):
153
+ dtype = getattr(torch, dtype)
154
+ kwargs.setdefault("device_map", {"": device})
155
+ if "attn_implementation" not in kwargs:
156
+ attention = "sdpa"
157
+ if str(device).startswith("cuda") and dtype == torch.bfloat16:
158
+ if torch.cuda.get_device_capability(torch.device(device))[0] == 9:
159
+ attention = _FLASH_ATTENTION
160
+ kwargs["attn_implementation"] = {
161
+ "text_config": attention, "vision_config": attention,
162
+ }
163
+ backbone = _NativeQwen3_5ForConditionalGeneration.from_pretrained(
164
+ path,
165
+ dtype=dtype,
166
+ local_files_only=True,
167
+ **kwargs,
168
+ )
169
+ engine = cls(
170
+ backbone,
171
+ load_head(path),
172
+ tokenizer,
173
+ batch_size=batch_size,
174
+ text_batch_size=text_batch_size,
175
+ batch_token_budget=batch_token_budget,
176
+ )
177
+ try:
178
+ engine._restore_math = install_math(backbone, engine.head)
179
+ except BaseException:
180
+ engine.shutdown()
181
+ raise
182
+ return engine
183
+
184
+ def _inputs(
185
+ self, sequences: list[list[int]], media: list[Any]
186
+ ) -> dict[str, torch.Tensor]:
187
+ width = max(map(len, sequences))
188
+ pad = self.tokenizer.pad_token_id
189
+ if pad is None:
190
+ pad = self.eos
191
+ inputs = {
192
+ "input_ids": torch.tensor(
193
+ [[pad] * (width - len(ids)) + ids for ids in sequences],
194
+ dtype=torch.long,
195
+ device=self.device,
196
+ ),
197
+ "attention_mask": torch.tensor(
198
+ [[0] * (width - len(ids)) + [1] * len(ids) for ids in sequences],
199
+ dtype=torch.long,
200
+ device=self.device,
201
+ ),
202
+ }
203
+ mappings = [mapping for payload in media if payload for mapping in payload]
204
+ if mappings:
205
+ for name in cm.MEDIA_BATCH_KEYS:
206
+ inputs[name] = torch.cat(
207
+ [mapping[name] for mapping in mappings], dim=0
208
+ ).to(
209
+ device=self.device,
210
+ dtype=self.dtype if name == "pixel_values" else torch.long,
211
+ )
212
+ inputs["mm_token_type_ids"] = (
213
+ inputs["input_ids"] == self.image_token
214
+ ).long()
215
+ self._vision_cache.prepare(mappings, inputs, self.backbone.model.visual.dtype)
216
+ return inputs
217
+
218
+ def _grammar(self, parameters: dict[str, Any]) -> Any:
219
+ if "json_schema" in parameters:
220
+ value = parameters["json_schema"]
221
+ return self.compiler.compile_json_schema(
222
+ json.loads(value) if isinstance(value, str) else value,
223
+ any_whitespace=True,
224
+ )
225
+ if "regex" in parameters:
226
+ return self.compiler.compile_regex(parameters["regex"])
227
+ if "ebnf" in parameters:
228
+ return self.compiler.compile_grammar(parameters["ebnf"])
229
+ raise ValueError(
230
+ "Extraction continuations require a JSON schema, regex, or grammar"
231
+ )
232
+
233
+ @torch.inference_mode()
234
+ def _generate(
235
+ self,
236
+ *,
237
+ input_ids: list[int] | list[list[int]],
238
+ image_data: Any = None,
239
+ sampling_params: dict[str, Any] | list[dict[str, Any]],
240
+ rid: Any = None,
241
+ token_ids_logprob: list[int] | None = None,
242
+ _cancelled: threading.Event | None = None,
243
+ **kwargs: Any,
244
+ ) -> Any:
245
+ from xgrammar.contrib.hf import LogitsProcessor
246
+
247
+ if _cancelled is not None and _cancelled.is_set():
248
+ raise RuntimeError("Inference cancelled")
249
+ if not input_ids:
250
+ return []
251
+ single = isinstance(input_ids[0], int)
252
+ sequences = [input_ids] if single else input_ids
253
+ size = len(sequences)
254
+ if not size:
255
+ return []
256
+ parameters = (
257
+ [sampling_params] * size
258
+ if isinstance(sampling_params, dict)
259
+ else sampling_params
260
+ )
261
+ media = [image_data] if single else (image_data or [None] * size)
262
+ ids = [rid] if single else (rid or [None] * size)
263
+ if not (len(parameters) == len(media) == len(ids) == size):
264
+ raise ValueError("Extraction batch arguments have inconsistent lengths")
265
+ batch_size = self.batch_size if any(media) else self.text_batch_size
266
+ results: list[Any] = [None] * size
267
+ groups: dict[tuple[int, tuple[int, ...]], list[int]] = defaultdict(list)
268
+ for index, params in enumerate(parameters):
269
+ if params.get("temperature", 0) != 0:
270
+ raise ValueError("Clairic extraction uses deterministic decoding")
271
+ groups[
272
+ (
273
+ int(params.get("max_new_tokens", 256)),
274
+ tuple(params.get("stop_token_ids", [self.eos])),
275
+ )
276
+ ].append(index)
277
+ for (maximum, stop_ids), indices in groups.items():
278
+ pending: list[int] = []
279
+ width = 0
280
+ chunks: list[list[int]] = []
281
+ for index in indices:
282
+ length = len(sequences[index])
283
+ if pending and (
284
+ len(pending) >= batch_size
285
+ or max(width, length) * (len(pending) + 1) > self.batch_token_budget
286
+ ):
287
+ chunks.append(pending)
288
+ pending, width = [], 0
289
+ pending.append(index)
290
+ width = max(width, length)
291
+ if pending:
292
+ chunks.append(pending)
293
+ for chunk in chunks:
294
+ if _cancelled is not None and _cancelled.is_set():
295
+ raise RuntimeError("Inference cancelled")
296
+ inputs = self._inputs(
297
+ [sequences[i] for i in chunk], [media[i] for i in chunk]
298
+ )
299
+ scores = _ConstrainedScores(
300
+ LogitsProcessor([self._grammar(parameters[i]) for i in chunk]),
301
+ token_ids_logprob or [],
302
+ len(chunk),
303
+ )
304
+ config = copy.deepcopy(self.backbone.generation_config)
305
+ config.do_sample, config.num_beams = False, 1
306
+ config.temperature, config.top_p, config.top_k = None, None, None
307
+ config.max_new_tokens, config.use_cache = maximum, True
308
+ config.eos_token_id = list(stop_ids)
309
+ config.pad_token_id = self.tokenizer.pad_token_id or self.eos
310
+ generated = self.backbone.generate(
311
+ **inputs,
312
+ generation_config=config,
313
+ logits_processor=[scores],
314
+ stopping_criteria=[_CancellationCriteria(_cancelled)]
315
+ if _cancelled is not None
316
+ else [],
317
+ )
318
+ if _cancelled is not None and _cancelled.is_set():
319
+ raise RuntimeError("Inference cancelled")
320
+ continuations = (
321
+ generated[:, inputs["input_ids"].shape[1] :].cpu().tolist()
322
+ )
323
+ for offset, (index, continuation) in enumerate(
324
+ zip(chunk, continuations, strict=True)
325
+ ):
326
+ stop = next(
327
+ (
328
+ i
329
+ for i, token in enumerate(continuation)
330
+ if token in stop_ids
331
+ ),
332
+ None,
333
+ )
334
+ output = (
335
+ continuation[: stop + 1] if stop is not None else continuation
336
+ )
337
+ logprobs = scores.chosen[offset][: len(output)]
338
+ if [item[1] for item in logprobs] != output:
339
+ raise RuntimeError(
340
+ "Generated tokens differ from constrained confidence scores"
341
+ )
342
+ text_ids = output[:-1] if stop is not None else output
343
+ results[index] = {
344
+ "output_ids": output,
345
+ "text": self.tokenizer.decode(
346
+ text_ids,
347
+ skip_special_tokens=False,
348
+ clean_up_tokenization_spaces=False,
349
+ ),
350
+ "meta_info": {
351
+ "id": ids[index],
352
+ "completion_tokens": len(output),
353
+ "finish_reason": {"type": "stop", "matched": output[-1]}
354
+ if stop is not None
355
+ else {"type": "length"},
356
+ "output_token_logprobs": logprobs,
357
+ "output_token_ids_logprobs": [scores.first[offset]],
358
+ },
359
+ }
360
+ return results[0] if single else results
361
+
362
+ async def async_generate(self, **kwargs: Any) -> Any:
363
+ return await self._submit(
364
+ lambda cancelled: self._generate(_cancelled=cancelled, **kwargs)
365
+ )
366
+
367
+ async def _submit(self, operation: Callable[[threading.Event], Any]) -> Any:
368
+ cancelled = threading.Event()
369
+ future = asyncio.get_running_loop().run_in_executor(
370
+ self._worker, lambda: operation(cancelled)
371
+ )
372
+ try:
373
+ return await asyncio.shield(future)
374
+ except asyncio.CancelledError:
375
+ cancelled.set()
376
+ # Admission stays occupied until the worker has actually stopped.
377
+ # A prefill cannot be interrupted; generation checks between tokens.
378
+ while not future.done():
379
+ try:
380
+ await asyncio.shield(future)
381
+ except asyncio.CancelledError:
382
+ continue
383
+ except Exception:
384
+ break
385
+ if not future.cancelled():
386
+ future.exception()
387
+ raise
388
+
389
+ @torch.inference_mode()
390
+ def _read_typed(
391
+ self,
392
+ item: cm.EncodedRecord,
393
+ media: Any,
394
+ _cancelled: threading.Event | None = None,
395
+ ) -> dict[str, dict[str, Any]]:
396
+ if _cancelled is not None and _cancelled.is_set():
397
+ raise RuntimeError("Inference cancelled")
398
+ inputs = self._inputs([list(item.input_ids)], [media])
399
+ output = self.backbone.model(**inputs, use_cache=False, return_dict=True)
400
+ if _cancelled is not None and _cancelled.is_set():
401
+ raise RuntimeError("Inference cancelled")
402
+ scope = (
403
+ ReadoutMath()
404
+ if str(self.device).startswith("cuda") and self.dtype == torch.bfloat16
405
+ else nullcontext()
406
+ )
407
+ with scope:
408
+ values = read_record(
409
+ self.head,
410
+ output.last_hidden_state[0],
411
+ item,
412
+ self.backbone.get_output_embeddings().weight,
413
+ )
414
+ values = cm.expand_output(
415
+ cm.compact_output(values).cpu(),
416
+ item,
417
+ bins=self.head.bins.out_features,
418
+ estimate_lexical=self.head.estimate_lexical,
419
+ span_trim=self.head.span_trim,
420
+ number_groups=self.head.number_groups,
421
+ number_pointer=self.head.number_pointer,
422
+ )
423
+ return cm.decode_record(values, item, self.tokenizer)
424
+
425
+ async def read_typed(
426
+ self, item: cm.EncodedRecord, media: Any = None
427
+ ) -> dict[str, dict[str, Any]]:
428
+ return await self._submit(
429
+ lambda cancelled: self._read_typed(item, media, _cancelled=cancelled)
430
+ )
431
+
432
+ def shutdown(self) -> None:
433
+ try:
434
+ self._worker.shutdown(wait=True, cancel_futures=True)
435
+ self._vision_cache.clear()
436
+ if self.backbone.model.get_image_features == self._image_features:
437
+ self.backbone.model.get_image_features = self._uncached_image_features
438
+ finally:
439
+ restore, self._restore_math = self._restore_math, None
440
+ if restore is not None:
441
+ restore()
clairic_runtime/ordinary_list_completion.py ADDED
@@ -0,0 +1,163 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ from typing import TYPE_CHECKING, Any
3
+ from . import batch_completion as shared
4
+ from . import schema
5
+
6
+ if TYPE_CHECKING:
7
+ from collections.abc import Callable
8
+ from transformers import PreTrainedTokenizerBase
9
+
10
+
11
+ def eligible(
12
+ record: dict[str, Any],
13
+ tasks: list[tuple[str, list[int], Any]],
14
+ kwargs: dict[str, Any],
15
+ ) -> bool:
16
+ media = kwargs.get("image_data")
17
+ object_lists = any(
18
+ (
19
+ spec.get("type") == "list"
20
+ and isinstance(spec.get("items"), dict)
21
+ and (spec["items"].get("type") == "object")
22
+ for spec in record.get("fields", {}).values()
23
+ )
24
+ )
25
+ guarded = (
26
+ not record.get("_null_recovery")
27
+ and (not object_lists)
28
+ and (
29
+ record.get("_meta", {}).get("construction") == schema.EVIDENCE_CONSTRUCTION
30
+ )
31
+ and (not record.get("_media_payload"))
32
+ and (not record.get("_original_images"))
33
+ and all((payload is None for (_, _, payload) in tasks))
34
+ and isinstance(media, list)
35
+ and (len(media) == len(tasks))
36
+ and all((payload is None for payload in media))
37
+ and (
38
+ not set(kwargs)
39
+ - shared._BATCHED_KEYS
40
+ - shared._SHARED_KEYS
41
+ - {"parse_result", "normalize"}
42
+ )
43
+ )
44
+ return guarded and bool(
45
+ shared._ordinary_lists(record, tasks, schema.list_item_name)
46
+ )
47
+
48
+
49
+ async def generate(
50
+ engine: Any,
51
+ record: dict[str, Any],
52
+ tasks: list[tuple[str, list[int], Any]],
53
+ eos: int,
54
+ tokenizer: PreTrainedTokenizerBase,
55
+ *,
56
+ initial_frontier: int = 0,
57
+ next_frontier: int = 0,
58
+ parse_result: Callable[..., dict[str, Any]] | None = None,
59
+ normalize: Callable[
60
+ [dict[str, Any], dict[str, dict[str, Any]]], dict[str, dict[str, Any]]
61
+ ]
62
+ | None = None,
63
+ **kwargs: Any,
64
+ ) -> list[dict[str, Any]]:
65
+ enabled = initial_frontier != 0
66
+ if enabled and (
67
+ type(initial_frontier) is not int
68
+ or type(next_frontier) is not int
69
+ or initial_frontier < 1
70
+ or (next_frontier <= initial_frontier)
71
+ ):
72
+ raise ValueError(
73
+ "Ordinary list scheduling requires positive increasing integer endpoints"
74
+ )
75
+ groups = (
76
+ shared._ordinary_lists(record, tasks, schema.list_item_name)
77
+ if enabled and eligible(record, tasks, kwargs)
78
+ else {}
79
+ )
80
+ if not groups:
81
+ return await shared.generate(
82
+ engine,
83
+ record,
84
+ tasks,
85
+ eos,
86
+ tokenizer,
87
+ parse_result=parse_result,
88
+ normalize=normalize,
89
+ **kwargs,
90
+ )
91
+ size = len(tasks)
92
+ rids = kwargs.get("rid")
93
+ if (
94
+ not isinstance(rids, list)
95
+ or len(rids) != size
96
+ or len(set(rids)) != size
97
+ or (not all((isinstance(rid, str) and rid for rid in rids)))
98
+ or (kwargs.get("input_ids") != [ids for (_, ids, _) in tasks])
99
+ ):
100
+ raise ValueError(
101
+ "Ordinary list scheduling requires original distinct task bindings"
102
+ )
103
+ shared._select_kwargs(kwargs, list(range(size)), size)
104
+ results: list[Any] = [None] * size
105
+ unexecuted: dict[str, int] = {}
106
+
107
+ async def submit(indices: list[int]) -> None:
108
+ if not indices:
109
+ return
110
+ selected = shared._select_kwargs(kwargs, indices, size)
111
+ received = await shared._generate(
112
+ engine,
113
+ record,
114
+ [tasks[index] for index in indices],
115
+ eos,
116
+ tokenizer,
117
+ **selected,
118
+ )
119
+ if len(received) != len(indices):
120
+ raise RuntimeError("Ordinary list scheduling received wrong batch size")
121
+ for index, result, rid in zip(indices, received, selected["rid"], strict=True):
122
+ if result.get("meta_info", {}).get("id") != rid:
123
+ raise RuntimeError(
124
+ "Ordinary list scheduling received wrong task identity"
125
+ )
126
+ results[index] = result
127
+
128
+ tails = {index for group in groups.values() for index in group[initial_frontier:]}
129
+ await submit([index for index in range(size) if index not in tails])
130
+ active = dict(groups)
131
+ (start, end, following) = (0, initial_frontier, next_frontier)
132
+ while active:
133
+ continued: list[int] = []
134
+ for parent, group in list(active.items()):
135
+ stopped = False
136
+ for index in group[start:end]:
137
+ try:
138
+ if shared._completed_null(results[index], eos, tokenizer):
139
+ stopped = True
140
+ break
141
+ except (KeyError, TypeError, ValueError, OverflowError):
142
+ continue
143
+ if stopped:
144
+ for index in group[end:]:
145
+ (name, ids, _) = tasks[index]
146
+ unexecuted[name] = len(ids)
147
+ results[index] = {
148
+ "_clair_unused_row_proposal": True,
149
+ "_ordinary_list_unexecuted": True,
150
+ "meta_info": {"completion_tokens": 0},
151
+ }
152
+ del active[parent]
153
+ elif end >= len(group):
154
+ del active[parent]
155
+ else:
156
+ continued.extend(group[end:following])
157
+ if continued:
158
+ await submit(sorted(continued))
159
+ (start, end, following) = (end, following, following * 2)
160
+ if any((result is None for result in results)):
161
+ raise RuntimeError("Ordinary list scheduling left an unaccounted result")
162
+ record["_unexecuted_list_items"] = unexecuted
163
+ return results
clairic_runtime/orientation.py ADDED
@@ -0,0 +1,85 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Conservative page orientation from detached dots beside Latin letter stems.
2
+
3
+ This examines glyph geometry only; it performs no text readout. Pages without
4
+ enough consistent evidence retain their supplied orientation.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from typing import TYPE_CHECKING
10
+
11
+ if TYPE_CHECKING:
12
+ from PIL import Image
13
+
14
+
15
+ def document_rotation(image: Image.Image) -> tuple[int, list[int]]:
16
+ import cv2
17
+ import numpy as np
18
+
19
+ page = image.convert("L")
20
+ page.thumbnail((1600, 1600))
21
+ pixels = np.asarray(page)
22
+ _, ink = cv2.threshold(pixels, 0, 255, cv2.THRESH_BINARY_INV | cv2.THRESH_OTSU)
23
+ _, _, stats, _ = cv2.connectedComponentsWithStats(ink, connectivity=8)
24
+ stats = stats[1:]
25
+ votes = [0, 0, 0, 0]
26
+ if not len(stats) or len(stats) > 12_000:
27
+ return 0, votes
28
+ width, height, area = stats[:, 2:].T
29
+ short, long = np.minimum(width, height), np.maximum(width, height)
30
+ stems = stats[(long >= 9) & (long <= 60) & (long >= 2.5 * short) & (area >= 8)]
31
+ dots = stats[(width <= 12) & (height <= 12) & (area >= 2) & (area <= 100)]
32
+ if not len(stems) or not len(dots) or len(stems) > 1200 or len(dots) > 2400:
33
+ return 0, votes
34
+ dx, dy, dw, dh, da = dots.T
35
+ for sx, sy, sw, sh, sa in stems:
36
+ vertical = sh > sw
37
+ across = dx + dw / 2 if vertical else dy + dh / 2
38
+ center = sx + sw / 2 if vertical else sy + sh / 2
39
+ start, length = (sy, sh) if vertical else (sx, sw)
40
+ left, size = (dy, dh) if vertical else (dx, dw)
41
+ thin = sw if vertical else sh
42
+ aligned = (abs(across - center) <= max(1.5, thin * 0.6)) & (
43
+ size <= length * 0.4
44
+ )
45
+ aligned &= (dw <= max(3, thin * 2)) if vertical else (dh <= max(3, thin * 2))
46
+ aligned &= da < sa * 0.7
47
+ before = (
48
+ aligned & (left + size <= start) & (start - left - size <= length * 0.45)
49
+ )
50
+ after = (
51
+ aligned
52
+ & (left >= start + length)
53
+ & (left - start - length <= length * 0.45)
54
+ )
55
+ if vertical:
56
+ votes[0] += int(np.any(before))
57
+ votes[2] += int(np.any(after))
58
+ else:
59
+ votes[1] += int(np.any(before))
60
+ votes[3] += int(np.any(after))
61
+ letters = (area >= 10) & (short >= 3) & (long <= 60) & (long <= 4 * short)
62
+ if int(letters.sum()) < 80:
63
+ return 0, votes
64
+ aspect = float(np.median(width[letters] / height[letters]))
65
+ if aspect < 0.8:
66
+ directions = (0, 2)
67
+ elif aspect > 1.25:
68
+ directions = (1, 3)
69
+ else:
70
+ return 0, votes
71
+ # Text-line direction excludes accidental dot/stem pairs in the other axis.
72
+ winner = max(directions, key=votes.__getitem__)
73
+ runner = votes[directions[0] if winner == directions[1] else directions[1]]
74
+ if (
75
+ votes[winner] < 12
76
+ or votes[winner] < 3 * max(1, runner)
77
+ or votes[winner] < 0.7 * (votes[winner] + runner)
78
+ ):
79
+ return 0, votes
80
+ return winner * 90, votes
81
+
82
+
83
+ def orient_document(image: Image.Image) -> Image.Image:
84
+ rotation, _ = document_rotation(image)
85
+ return image.rotate(-rotation, expand=True) if rotation else image
clairic_runtime/pdf_number_focus.py ADDED
@@ -0,0 +1,86 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ from collections.abc import Callable
3
+ from typing import TYPE_CHECKING
4
+
5
+ if TYPE_CHECKING:
6
+ from .api import PredictRequest
7
+ from .backend import EncodedRequest
8
+ import re
9
+ from . import grounding, image_focus
10
+
11
+ VIEW_ID = "pdf-source-only-scalars-v1"
12
+ _PAGE_SCOPE = re.compile(
13
+ "\\b(?:page\\s+(?:[1-4]|one|two|three|four)|(?:first|second|third|fourth|1st|2nd|3rd|4th)\\s+page)\\b",
14
+ re.IGNORECASE,
15
+ )
16
+ _EXCLUDED_SCOPE = re.compile(
17
+ "\\b(?:not|ignore|exclude|excluding|except|without|rather than)\\b[^.;:\\n]*$",
18
+ re.IGNORECASE,
19
+ )
20
+
21
+
22
+ def _page_scoped(instructions: object) -> bool:
23
+ return isinstance(instructions, str) and any(
24
+ (
25
+ not _EXCLUDED_SCOPE.search(instructions[: match.start()])
26
+ for match in _PAGE_SCOPE.finditer(instructions)
27
+ )
28
+ )
29
+
30
+
31
+ def prepare(
32
+ request: PredictRequest,
33
+ encoded: EncodedRequest,
34
+ encode: Callable[..., EncodedRequest],
35
+ *,
36
+ enabled: bool,
37
+ ) -> EncodedRequest:
38
+ if not enabled or not request.documents:
39
+ return encoded
40
+ (record, forecasts, tasks, typed, eos) = encoded
41
+ active = {name for (name, _, _) in tasks}
42
+ selected = {
43
+ name: spec
44
+ for (name, spec) in request.fields.items()
45
+ if name in active
46
+ and spec.get("type") == "number"
47
+ and (spec.get("source_only") is True)
48
+ and (not spec.get("knowledge"))
49
+ and (not grounding.state_only(spec))
50
+ and _page_scoped(spec.get("instructions", ""))
51
+ }
52
+ originals = record.get("_original_images", ())
53
+ pdf_pages = originals[len(request.images) :]
54
+ if (
55
+ not selected
56
+ or not pdf_pages
57
+ or (
58
+ not any(
59
+ (image_focus.focus_document(page) is not page for page in pdf_pages)
60
+ )
61
+ )
62
+ ):
63
+ return encoded
64
+ child_request = request.model_copy(update={"fields": selected})
65
+ (child, _, replacements, child_typed, child_eos) = encode(
66
+ child_request,
67
+ identifier_view=True,
68
+ image_views=lambda: originals,
69
+ image_view_key=VIEW_ID,
70
+ )
71
+ if child_typed is not None or child_eos != eos:
72
+ raise ValueError("A literal PDF number view must retain the scalar AR contract")
73
+ by_name = {name: (name, ids, media) for (name, ids, media) in replacements}
74
+ if set(by_name) != set(selected):
75
+ raise ValueError(
76
+ "PDF number detail tasks differ from the selected public fields"
77
+ )
78
+ updated = [by_name.get(name, (name, ids, media)) for (name, ids, media) in tasks]
79
+ salts = dict(record.get("_ar_task_salts", {}))
80
+ for name in selected:
81
+ record["_ar_constraints"][name] = child["_ar_constraints"][name]
82
+ salts[name] = child["_cache_salt"]
83
+ record.update(
84
+ _ar_tasks=updated, _ar_task_salts=salts, _ar_prefix=[], _ar_group_prefixes=[]
85
+ )
86
+ return (record, forecasts, updated, typed, eos)
clairic_runtime/po_image_supplement.py ADDED
@@ -0,0 +1,220 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ import base64
3
+ import io
4
+ import json
5
+ from typing import TYPE_CHECKING
6
+ from .api import ClairImage
7
+ from . import ar, grounding, identifier_spelling, image_focus
8
+ from PIL import Image
9
+
10
+ if TYPE_CHECKING:
11
+ from collections.abc import Callable, Sequence
12
+ from typing import Any
13
+ from .api import PredictRequest
14
+ from .backend import ARTask, EncodedRequest
15
+ from transformers import PreTrainedTokenizerBase
16
+ VERSION = "27b-po-all-content-horizontal2-supplement-v2"
17
+ MAX_PIXELS = 1600000
18
+
19
+
20
+ def supplement(images: Sequence[Image.Image]) -> ClairImage:
21
+ views: list[Image.Image] = []
22
+ for image in images:
23
+ focused = image_focus.focus_document(image)
24
+ views.append(
25
+ focused.resize(
26
+ (round(focused.width * 2.0), focused.height), Image.Resampling.BICUBIC
27
+ )
28
+ )
29
+ board = Image.new(
30
+ "RGB",
31
+ (
32
+ max((image.width for image in views)),
33
+ sum((image.height for image in views)) + 32 * (len(views) - 1),
34
+ ),
35
+ "white",
36
+ )
37
+ y = 0
38
+ for image in views:
39
+ board.paste(image, (0, y))
40
+ y += image.height + 32
41
+ scale = min(1.0, (MAX_PIXELS / (board.width * board.height)) ** 0.5)
42
+ if scale < 1:
43
+ board = board.resize(
44
+ (max(1, int(board.width * scale)), max(1, int(board.height * scale))),
45
+ Image.Resampling.BICUBIC,
46
+ )
47
+ buffer = io.BytesIO()
48
+ board.save(buffer, format="PNG")
49
+ return ClairImage.model_validate(
50
+ {
51
+ "content_type": "image/png",
52
+ "base64": base64.b64encode(buffer.getvalue()).decode(),
53
+ }
54
+ )
55
+
56
+
57
+ def plain_task(
58
+ task: ARTask,
59
+ wire_spec: dict[str, Any],
60
+ public_spec: dict[str, Any],
61
+ tokenizer: PreTrainedTokenizerBase,
62
+ max_length: int,
63
+ ) -> tuple[ARTask, dict[str, Any], dict[str, str]]:
64
+ (name, ids, media) = task
65
+ source_ids = list(ids)
66
+ text = tokenizer.decode(
67
+ ids, skip_special_tokens=False, clean_up_tokenization_spaces=False
68
+ )
69
+ if tokenizer.encode(text, add_special_tokens=False) != source_ids:
70
+ raise ValueError(
71
+ "PO scalar source prompt cannot make a lossless tokenizer roundtrip"
72
+ )
73
+ before = identifier_spelling.INSTRUCTION + "\n"
74
+ if text.count(before) != 1 or wire_spec.get("instructions", "").count(before) != 1:
75
+ raise ValueError(
76
+ "PO scalar source must contain exactly one spelling instruction"
77
+ )
78
+ scalar = {
79
+ **wire_spec,
80
+ "instructions": wire_spec["instructions"].replace(before, ""),
81
+ }
82
+ for key in ("minLength", "maxLength", "pattern"):
83
+ if key in public_spec:
84
+ scalar[key] = public_spec[key]
85
+ (old_schema, schema) = (ar.schema(wire_spec), ar.schema(scalar))
86
+ text = text.replace(before, "")
87
+ if schema != old_schema:
88
+ old = "\nSchema: " + json.dumps(
89
+ old_schema, ensure_ascii=False, separators=(",", ":")
90
+ )
91
+ new = "\nSchema: " + json.dumps(
92
+ schema, ensure_ascii=False, separators=(",", ":")
93
+ )
94
+ if text.count(old) != 1:
95
+ raise ValueError("PO scalar source must contain exactly one native schema")
96
+ text = text.replace(old, new)
97
+ plain_ids = tokenizer.encode(text, add_special_tokens=False)
98
+ if len(plain_ids) > max_length:
99
+ raise ValueError("PO scalar detail exceeds the complete model context")
100
+ return ((name, plain_ids, media), scalar, {"json_schema": json.dumps(schema)})
101
+
102
+
103
+ def selected_fields(
104
+ request: PredictRequest, encoded: EncodedRequest
105
+ ) -> dict[str, dict[str, Any]]:
106
+ image_count = len(request.images)
107
+ if image_count not in (1, 2, 3) or request.documents:
108
+ return {}
109
+ (record, _, tasks, _, _) = encoded
110
+ contracts = record.get("_meta", {}).get("identifier_spelling", {})
111
+ active = {name for (name, _, media) in tasks if media is not None}
112
+ return {
113
+ name: request.fields[name]
114
+ for (name, contract) in contracts.items()
115
+ if name in active
116
+ and contract.get("wire") == identifier_spelling.VERSION
117
+ and (not request.fields[name].get("knowledge"))
118
+ and (not grounding.state_only(request.fields[name]))
119
+ }
120
+
121
+
122
+ def prepare(
123
+ request: PredictRequest,
124
+ encoded: EncodedRequest,
125
+ *,
126
+ encode_child: Callable[[PredictRequest], EncodedRequest],
127
+ tokenizer: PreTrainedTokenizerBase,
128
+ max_length: int,
129
+ media_groups: Callable[..., list[dict[str, Any]]],
130
+ ) -> EncodedRequest:
131
+ selected = selected_fields(request, encoded)
132
+ if not selected:
133
+ return encoded
134
+ image_count = len(request.images)
135
+ (record, forecasts, tasks, typed, eos) = encoded
136
+ contracts = record["_meta"]["identifier_spelling"]
137
+ originals = record.get("_original_images", ())
138
+ if len(originals) != image_count:
139
+ raise ValueError("PO supplement must retain every original image in order")
140
+ fields = image_focus.preserve_scalar_fields(selected)
141
+ supplements = (
142
+ tuple((supplement([image]) for image in originals))
143
+ if image_count == 2
144
+ else (supplement(originals),)
145
+ )
146
+ child_request = request.model_copy(
147
+ update={"fields": fields, "images": (*request.images, *supplements)}
148
+ )
149
+ (child, _, replacements, child_typed, child_eos) = encode_child(child_request)
150
+ by_name = {task[0]: task for task in replacements}
151
+ if (
152
+ child_typed is not None
153
+ or child_eos != eos
154
+ or set(by_name) != set(selected)
155
+ or (len(replacements) != len(selected))
156
+ ):
157
+ raise ValueError(
158
+ "PO supplement must retain the complete selected scalar task contract"
159
+ )
160
+ plain = image_count == 1
161
+ constraints: dict[str, dict[str, Any]]
162
+ remaining: dict[str, Any] | list[str]
163
+ (fields, constraints) = ({}, {})
164
+ for name, public_spec in selected.items():
165
+ if plain:
166
+ (by_name[name], fields[name], constraints[name]) = plain_task(
167
+ by_name[name], child["fields"][name], public_spec, tokenizer, max_length
168
+ )
169
+ else:
170
+ fields[name] = child["fields"][name]
171
+ constraints[name] = child["_ar_constraints"][name]
172
+ updated = [by_name.get(task[0], task) for task in tasks]
173
+ salts = dict(record.get("_ar_task_salts", {}))
174
+ for name in selected:
175
+ record["fields"][name] = fields[name]
176
+ record["_ar_constraints"][name] = constraints[name]
177
+ salts[name] = child.get("_ar_task_salts", {}).get(name, child["_cache_salt"])
178
+ if plain:
179
+ remaining = {
180
+ name: contract
181
+ for (name, contract) in contracts.items()
182
+ if name not in selected
183
+ }
184
+ if remaining:
185
+ record["_meta"]["identifier_spelling"] = remaining
186
+ else:
187
+ record["_meta"].pop("identifier_spelling", None)
188
+ for key in ("model_document_scalar_view", "identifier_spelling_image_view"):
189
+ previous = record["_meta"].get(key)
190
+ if previous is None:
191
+ continue
192
+ remaining = [name for name in previous["fields"] if name not in selected]
193
+ if not remaining:
194
+ record["_meta"].pop(key)
195
+ else:
196
+ retained = {**previous, "fields": remaining}
197
+ if "po_fields" in retained:
198
+ retained["po_fields"] = [
199
+ name for name in retained["po_fields"] if name not in selected
200
+ ]
201
+ record["_meta"][key] = retained
202
+ record["_meta"]["model_po_supplement"] = {
203
+ "version": VERSION,
204
+ "fields": list(selected),
205
+ "original_image_count": image_count,
206
+ "native_image_count": len(child_request.images),
207
+ "horizontal_scale": 2.0,
208
+ "supplement_max_pixels": MAX_PIXELS,
209
+ "wire": "native_scalar" if plain else identifier_spelling.VERSION,
210
+ }
211
+ record.update(
212
+ _ar_tasks=updated, _ar_task_salts=salts, _ar_prefix=[], _ar_group_prefixes=[]
213
+ )
214
+ record["_ar_media_groups"] = media_groups(
215
+ updated,
216
+ default_salt=record["_cache_salt"],
217
+ task_salts=salts,
218
+ annotations=record["_meta"]["extraction_contract"]["fields"],
219
+ )
220
+ return (record, forecasts, updated, typed, eos)
clairic_runtime/printed_numbers.py ADDED
@@ -0,0 +1,259 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ import math
3
+ import re
4
+ from collections.abc import Collection
5
+ from decimal import Decimal, DecimalException
6
+ from typing import Any
7
+ from jsonschema import Draft202012Validator, ValidationError
8
+ from . import ar
9
+
10
+ COPY_INSTRUCTION = " Copy the complete requested number exactly as printed, including every digit, currency symbol, grouping separator, sign or parentheses. Do not calculate, normalize or round. Return null only if this requested value is absent."
11
+ PAYMENT_PRESENCE_INSTRUCTION = " Every separately printed payment actually received is a present row, including an amount of zero, a negative amount, or a few cents. Copy all matching printed received-payment rows in their printed order, preserving duplicate rows. Do not return null or end the list while a matching received-payment row remains."
12
+ _NUMBER = re.compile(
13
+ "\\s*(?P<open>\\()?\\s*(?P<before>[+-]?)\\s*(?:[$€£¥]|USD|EUR|GBP|CAD|AUD|JPY)?\\s*(?P<after>[+-]?)\\s*(?P<number>(?:\\d{1,3}(?:,\\d{3})+|\\d+)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?)\\s*(?P<close>\\))?\\s*",
14
+ re.IGNORECASE,
15
+ )
16
+ _TRANSFORM = re.compile(
17
+ "\\b(?:calculat\\w*|comput\\w*|deriv\\w*|convert\\w*|summar\\w*|aggregat\\w*|group\\w*|combin\\w*|deduplicat\\w*|normaliz\\w*)\\b",
18
+ re.IGNORECASE,
19
+ )
20
+
21
+
22
+ def _literal(spec: dict[str, Any]) -> bool:
23
+ instructions = spec.get("instructions", "")
24
+ if not isinstance(instructions, str) or spec.get("knowledge"):
25
+ return False
26
+ instructions = re.sub(
27
+ "\\b(?:do\\s+not|never|don't)\\s+(?:calculate\\w*|compute\\w*|derive\\w*|convert\\w*|summarize\\w*|aggregate\\w*|group\\w*|combine\\w*|deduplicate\\w*|normalize\\w*)\\b",
28
+ "",
29
+ instructions,
30
+ flags=re.IGNORECASE,
31
+ )
32
+ return not _TRANSFORM.search(instructions)
33
+
34
+
35
+ def _payment_property(spec: dict[str, Any]) -> str | None:
36
+ properties = spec.get("properties", {})
37
+ if (
38
+ spec.get("type") != "object"
39
+ or len(properties) != 2
40
+ or (not _literal(spec))
41
+ or (
42
+ not all(
43
+ (
44
+ isinstance(child, dict) and _literal(child)
45
+ for child in properties.values()
46
+ )
47
+ )
48
+ )
49
+ or (sum((child.get("type") == "text" for child in properties.values())) != 1)
50
+ or (sum((child.get("type") == "number" for child in properties.values())) != 1)
51
+ ):
52
+ return None
53
+ return next(
54
+ (name for (name, child) in properties.items() if child.get("type") == "number")
55
+ )
56
+
57
+
58
+ def payment_lists(fields: dict[str, dict[str, Any]]) -> list[str]:
59
+ selected = []
60
+ for name, spec in fields.items():
61
+ item = spec.get("items")
62
+ if (
63
+ spec.get("type") != "list"
64
+ or not isinstance(item, dict)
65
+ or (not _literal(spec))
66
+ or (_payment_property(item) is None)
67
+ ):
68
+ continue
69
+ positive = re.split(
70
+ "[.\\n]|\\bExclude\\b",
71
+ spec.get("instructions", ""),
72
+ maxsplit=1,
73
+ flags=re.IGNORECASE,
74
+ )[0]
75
+ if (
76
+ re.search("\\bpayments?\\b[^.\\n]*\\breceived\\b", positive, re.IGNORECASE)
77
+ or re.search(
78
+ "\\breceived\\b[^.\\n]*\\bpayments?\\b", positive, re.IGNORECASE
79
+ )
80
+ ) and (
81
+ not re.search(
82
+ "\\b(?:not|never|exclude|excluding|ignore|without)\\b",
83
+ positive,
84
+ re.IGNORECASE,
85
+ )
86
+ ):
87
+ selected.append(name)
88
+ return selected
89
+
90
+
91
+ def normalize(value: object, spec: dict[str, Any]) -> int | float | None:
92
+ if value is None:
93
+ return None
94
+ if not isinstance(value, str):
95
+ raise TypeError("A printed number must be a string")
96
+ raw = value.strip()
97
+ unit = spec.get("unit")
98
+ if unit and raw.endswith(unit):
99
+ raw = raw[: -len(unit)].rstrip()
100
+ match = _NUMBER.fullmatch(raw)
101
+ if (
102
+ match is None
103
+ or bool(match["open"]) != bool(match["close"])
104
+ or (match["before"] and match["after"])
105
+ or (match["open"] and (match["before"] or match["after"]))
106
+ ):
107
+ raise ValueError("Unsupported printed number")
108
+ try:
109
+ number = Decimal(match["number"].replace(",", ""))
110
+ if not math.isfinite(float(number)):
111
+ raise ValueError("Nonfinite numeric answer")
112
+ except DecimalException as error:
113
+ raise ValueError("Unsupported printed number") from error
114
+ if match["open"] or "-" in (match["before"], match["after"]):
115
+ number = number.copy_negate()
116
+ result = ar.normalize_number(number, spec)
117
+ if isinstance(result, float) and (not math.isfinite(result)):
118
+ raise ValueError("Nonfinite numeric answer")
119
+ Draft202012Validator(ar.schema(spec)).validate(result)
120
+ return result
121
+
122
+
123
+ def _text_spec(spec: dict[str, Any]) -> dict[str, Any]:
124
+ return {
125
+ "type": "text",
126
+ "nullable": spec.get("nullable", True),
127
+ "instructions": spec.get("instructions", "") + COPY_INSTRUCTION,
128
+ }
129
+
130
+
131
+ def prepare(
132
+ fields: dict[str, dict[str, Any]], *, payment_rows: Collection[str] = ()
133
+ ) -> tuple[dict[str, dict[str, Any]], dict[str, dict[str, Any]]]:
134
+ fields = {name: dict(spec) for (name, spec) in fields.items()}
135
+ contracts = {}
136
+ payment_rows = set(payment_rows)
137
+ for parent in payment_lists(fields):
138
+ prefix = parent + ".item"
139
+ children = [
140
+ name
141
+ for name in payment_rows
142
+ if name.startswith(prefix) and name[len(prefix) :].isdigit()
143
+ ]
144
+ if not children:
145
+ continue
146
+ instructions = fields[parent].get("instructions", "")
147
+ if PAYMENT_PRESENCE_INSTRUCTION in instructions:
148
+ continue
149
+ fields[parent] = {
150
+ **fields[parent],
151
+ "instructions": instructions + PAYMENT_PRESENCE_INSTRUCTION,
152
+ }
153
+ for child in children:
154
+ if child not in fields or _payment_property(fields[child]) is None:
155
+ continue
156
+ requested = fields[child].get("instructions", "")
157
+ fields[child] = {
158
+ **fields[child],
159
+ "instructions": requested.replace(
160
+ instructions, instructions + PAYMENT_PRESENCE_INSTRUCTION, 1
161
+ )
162
+ if instructions and instructions in requested
163
+ else requested + PAYMENT_PRESENCE_INSTRUCTION,
164
+ }
165
+ for name, spec in fields.items():
166
+ if spec["type"] == "number" and spec.get("source_only"):
167
+ contracts[name] = {"scalar": spec}
168
+ fields[name] = _text_spec(spec)
169
+ elif (
170
+ spec["type"] == "list"
171
+ and spec.get("source_only")
172
+ and (spec["items"] == "number")
173
+ ):
174
+ fields[name] = {
175
+ **spec,
176
+ "items": "text",
177
+ "instructions": spec.get("instructions", "") + COPY_INSTRUCTION,
178
+ }
179
+ elif (
180
+ name in payment_rows
181
+ and (number_name := _payment_property(spec)) is not None
182
+ ):
183
+ number_spec = spec["properties"][number_name]
184
+ contracts[name] = {"row": spec, "properties": {number_name: number_spec}}
185
+ fields[name] = {
186
+ **spec,
187
+ "properties": {
188
+ **spec["properties"],
189
+ number_name: _text_spec(number_spec),
190
+ },
191
+ }
192
+ return (fields, contracts)
193
+
194
+
195
+ def _normalize_row(
196
+ raw: object, contract: dict[str, Any], record: dict[str, Any], name: str
197
+ ) -> dict[str, Any] | None:
198
+ if raw is None:
199
+ result = None
200
+ elif isinstance(raw, dict):
201
+ result = dict(raw)
202
+ current = record.get("fields", {}).get(name, {}).get("properties", {})
203
+ for property_name, spec in contract["properties"].items():
204
+ value = raw[property_name]
205
+ if current.get(property_name, {}).get("type") == "number":
206
+ if value is not None and (
207
+ isinstance(value, bool)
208
+ or not isinstance(value, (int, float, Decimal))
209
+ ):
210
+ raise TypeError("A numeric row value must be a number")
211
+ result[property_name] = ar.normalize_number(value, spec)
212
+ else:
213
+ if value is not None and (not record.get("_media_payload")):
214
+ if not isinstance(value, str) or value not in record["input"]:
215
+ raise ValueError("not_in_source")
216
+ result[property_name] = normalize(value, spec)
217
+ else:
218
+ raise TypeError("A printed payment row must be an object")
219
+ Draft202012Validator(ar.schema(contract["row"])).validate(result)
220
+ return result
221
+
222
+
223
+ def normalize_predictions(
224
+ record: dict[str, Any], predictions: dict[str, dict[str, Any]]
225
+ ) -> dict[str, dict[str, Any]]:
226
+ result = dict(predictions)
227
+ for name, contract in record.get("_meta", {}).get("printed_numbers", {}).items():
228
+ answer = dict(result[name])
229
+ result[name] = answer
230
+ if not answer.get("valid"):
231
+ continue
232
+ raw = answer["value"]
233
+ try:
234
+ if "properties" in contract:
235
+ answer["value"] = _normalize_row(raw, contract, record, name)
236
+ else:
237
+ if raw is not None and (not record.get("_media_payload")):
238
+ if not isinstance(raw, str) or raw not in record["input"]:
239
+ raise ValueError("not_in_source")
240
+ answer["value"] = normalize(raw, contract["scalar"])
241
+ answer["printed_value"] = raw
242
+ answer["normalization_method"] = "printed_number_v1"
243
+ except (
244
+ ValueError,
245
+ TypeError,
246
+ KeyError,
247
+ OverflowError,
248
+ ValidationError,
249
+ ) as error:
250
+ answer.update(
251
+ value=None,
252
+ valid=False,
253
+ confidence=0.0,
254
+ span=None,
255
+ failure_reason="not_in_source"
256
+ if str(error) == "not_in_source"
257
+ else "invalid_printed_number",
258
+ )
259
+ return result
clairic_runtime/printed_temporal.py ADDED
@@ -0,0 +1,178 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ import re
3
+ from datetime import datetime
4
+ from typing import Any
5
+
6
+ TYPES = ("date", "time", "datetime")
7
+ COPY_INSTRUCTION = " Copy only a date or time explicitly printed for this exact requested role. Return null if this role has no printed date or time. Do not use invoice or due dates for service or billing period boundaries. Do not infer a period from its duration. Copy the requested date or time exactly as printed, including AM or PM when present. Preserve every digit. Do not normalize or convert the value. Return null only if the requested value is absent."
8
+ _LITERAL = re.compile("\\b(?:print\\w*|explicit\\w*|verbatim|shown)\\b", re.IGNORECASE)
9
+ _DERIVED = re.compile(
10
+ "\\b(?:calculat\\w*|comput\\w*|deriv\\w*|infer\\w*|after|before|ago|next|previous|following|prior|add|subtract|plus|minus|earlier|later|offset|duration|terms)\\b|\\bnet\\s*\\d+\\b|\\b(?:first|last)\\s+day\\s+of\\b",
11
+ re.IGNORECASE,
12
+ )
13
+ _DOCUMENT_DATE = re.compile(
14
+ "\\b(?:invoice|billing|service|subscription|document|receipt)\\b", re.IGNORECASE
15
+ )
16
+ _DATE_ROLES = {
17
+ "invoice_date",
18
+ "due_date",
19
+ "period_start",
20
+ "period_end",
21
+ "start_date",
22
+ "end_date",
23
+ }
24
+
25
+
26
+ def explicit_fields(fields: dict[str, dict[str, Any]]) -> dict[str, dict[str, Any]]:
27
+ result = dict(fields)
28
+ for name, spec in fields.items():
29
+ date_list = spec.get("type") == "list" and spec.get("items") == "date"
30
+ if (
31
+ spec.get("type") not in TYPES
32
+ and (not date_list)
33
+ or "source_only" in spec
34
+ or "null_threshold" in spec
35
+ or spec.get("knowledge")
36
+ ):
37
+ continue
38
+ instructions = spec.get("instructions", "")
39
+ if not isinstance(instructions, str):
40
+ continue
41
+ role = name.casefold() in _DATE_ROLES and _DOCUMENT_DATE.search(instructions)
42
+ if (_LITERAL.search(instructions) or role) and (
43
+ not _DERIVED.search(instructions)
44
+ ):
45
+ result[name] = {**spec, "source_only": True}
46
+ return result
47
+
48
+
49
+ def clock(value: str) -> str:
50
+ match = re.fullmatch(
51
+ "\\s*(\\d{1,2}):(\\d{2})(?::(\\d{2}))?\\s*([AP]\\.?M\\.?)?\\s*",
52
+ value,
53
+ re.IGNORECASE,
54
+ )
55
+ if match is None:
56
+ raise ValueError("Unsupported printed time")
57
+ (hour, minute, second) = map(int, (match[1], match[2], match[3] or "0"))
58
+ meridiem = match[4]
59
+ if meridiem:
60
+ if not 1 <= hour <= 12:
61
+ raise ValueError("Invalid 12-hour clock")
62
+ hour = hour % 12 + (12 if meridiem.replace(".", "").upper() == "PM" else 0)
63
+ if not 0 <= hour < 24 or not 0 <= minute < 60 or (not 0 <= second < 60):
64
+ raise ValueError("Invalid printed time")
65
+ return f"{hour:02}:{minute:02}:{second:02}"
66
+
67
+
68
+ def day(value: str) -> str:
69
+ value = value.strip()
70
+ for fmt in (
71
+ "%Y-%m-%d",
72
+ "%Y/%m/%d",
73
+ "%Y.%m.%d",
74
+ "%B %d, %Y",
75
+ "%b %d, %Y",
76
+ "%B %d %Y",
77
+ "%b %d %Y",
78
+ "%d %B %Y",
79
+ "%d %b %Y",
80
+ ):
81
+ try:
82
+ return datetime.strptime(value, fmt).date().isoformat()
83
+ except ValueError:
84
+ pass
85
+ numeric = re.fullmatch("(\\d{1,2})([-/.])(\\d{1,2})\\2(\\d{4})", value)
86
+ if numeric:
87
+ (first, second, year) = (int(numeric[1]), int(numeric[3]), int(numeric[4]))
88
+ readings = set()
89
+ for month, date in ((first, second), (second, first)):
90
+ try:
91
+ readings.add(datetime(year, month, date).date().isoformat())
92
+ except ValueError:
93
+ pass
94
+ if len(readings) == 1:
95
+ return readings.pop()
96
+ raise ValueError("Unsupported or ambiguous printed date")
97
+
98
+
99
+ def normalize(value: object, kind: str) -> str | None:
100
+ if value is None:
101
+ return None
102
+ if not isinstance(value, str):
103
+ raise TypeError("A printed temporal answer must be a string")
104
+ if kind == "time":
105
+ return clock(value)
106
+ if kind == "date":
107
+ return day(value)
108
+ if kind == "datetime":
109
+ match = re.fullmatch(
110
+ "(.+?)(?:T|\\s+(?:at\\s+)?)(\\d{1,2}:\\d{2}(?::\\d{2})?\\s*(?:[AP]\\.?M\\.?)?)",
111
+ value.strip(),
112
+ re.IGNORECASE,
113
+ )
114
+ if match is None:
115
+ raise ValueError("Unsupported printed datetime")
116
+ return day(match[1]) + "T" + clock(match[2])
117
+ raise ValueError("Unsupported temporal type")
118
+
119
+
120
+ def prepare(
121
+ fields: dict[str, dict[str, Any]],
122
+ ) -> tuple[dict[str, dict[str, Any]], dict[str, str]]:
123
+ fields = {name: dict(spec) for (name, spec) in fields.items()}
124
+ kinds = {}
125
+ for name, spec in fields.items():
126
+ if not spec.get("source_only"):
127
+ continue
128
+ if spec["type"] == "list" and spec["items"] == "date":
129
+ spec["items"] = "text"
130
+ spec["instructions"] = spec.get("instructions", "") + COPY_INSTRUCTION
131
+ continue
132
+ kind = spec["type"]
133
+ if kind not in TYPES:
134
+ continue
135
+ kinds[name] = kind
136
+ fields[name] = {
137
+ "type": "text",
138
+ "nullable": spec.get("nullable", True),
139
+ "instructions": spec.get("instructions", "") + COPY_INSTRUCTION,
140
+ }
141
+ return (fields, kinds)
142
+
143
+
144
+ def normalize_predictions(
145
+ record: dict[str, Any], predictions: dict[str, dict[str, Any]]
146
+ ) -> dict[str, dict[str, Any]]:
147
+ result = dict(predictions)
148
+ for name, kind in record.get("_meta", {}).get("printed_temporal", {}).items():
149
+ answer = dict(result[name])
150
+ result[name] = answer
151
+ if not answer.get("valid"):
152
+ continue
153
+ printed = answer["value"]
154
+ answer["printed_value"] = printed
155
+ if (
156
+ printed is not None
157
+ and (not record.get("_media_payload"))
158
+ and (not isinstance(printed, str) or printed not in record["input"])
159
+ ):
160
+ answer.update(
161
+ value=None,
162
+ valid=False,
163
+ confidence=0.0,
164
+ span=None,
165
+ failure_reason="not_in_source",
166
+ )
167
+ continue
168
+ try:
169
+ answer["value"] = normalize(printed, kind)
170
+ answer["normalization_method"] = "printed_temporal_v1"
171
+ except (TypeError, ValueError):
172
+ answer.update(
173
+ value=None,
174
+ valid=False,
175
+ confidence=0.0,
176
+ failure_reason="invalid_printed_temporal",
177
+ )
178
+ return result
clairic_runtime/readout.py ADDED
@@ -0,0 +1,83 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Read typed fields from backbone hidden states."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import inspect
6
+ import json
7
+ from pathlib import Path
8
+ from typing import Any
9
+
10
+ import torch
11
+ from safetensors.torch import load_file
12
+ from . import model as cm
13
+
14
+
15
+ def load_head(path: Path) -> cm.ClairicHead:
16
+ configuration = json.loads((path / "clair_head_config.json").read_text())
17
+ accepted = inspect.signature(cm.ClairicHead).parameters
18
+ head = cm.ClairicHead(
19
+ **{name: value for name, value in configuration.items() if name in accepted}
20
+ )
21
+ head.load_state_dict(load_file(path / "clair_head.safetensors"), strict=True)
22
+ return head.float().eval()
23
+
24
+
25
+ def read_slots(
26
+ states: torch.Tensor, output_weight: torch.Tensor, chunk: int = 256
27
+ ) -> tuple[torch.Tensor, torch.Tensor]:
28
+ ids, probabilities = [], []
29
+ for rows in states.split(chunk):
30
+ logits = (rows @ output_weight.t()).float()
31
+ best = logits.max(dim=-1)
32
+ ids.append(best.indices)
33
+ probabilities.append(best.values - torch.logsumexp(logits, dim=-1))
34
+ return torch.cat(ids), torch.cat(probabilities)
35
+
36
+
37
+ @torch.inference_mode()
38
+ def read_record(
39
+ head: cm.ClairicHead,
40
+ states: torch.Tensor,
41
+ item: cm.EncodedRecord,
42
+ output_weight: torch.Tensor,
43
+ ) -> dict[str, Any]:
44
+ start, length, kinds, queries, items, slot_fields, slots = (
45
+ cm.parse_prediction_layout(
46
+ cm.prediction_layout(item),
47
+ len(item.input_ids),
48
+ with_slots=True,
49
+ )
50
+ )
51
+ views = cm.prediction_views(kinds, queries, items, states.device)
52
+ output = head.forward_states(states, start, start + length, views)
53
+ if slots:
54
+ width = max(map(len, slots))
55
+ positions = torch.tensor(
56
+ [row + [row[-1]] * (width - len(row)) for row in slots],
57
+ dtype=torch.long,
58
+ device=states.device,
59
+ )
60
+ if head.answer_slot_routing:
61
+ field_queries = views["query_positions"][slot_fields]
62
+ slot_kinds = torch.tensor(
63
+ [
64
+ cm.ROUTE_KINDS.index(
65
+ "tags" if kinds[row] == "text_list" else kinds[row]
66
+ )
67
+ for row in slot_fields
68
+ ],
69
+ dtype=torch.long,
70
+ device=states.device,
71
+ )
72
+ lengths = torch.tensor(
73
+ [len(row) for row in slots], dtype=torch.long, device=states.device
74
+ )
75
+ slot_states = head.answer_slot_states(
76
+ states, field_queries, slot_kinds, positions, lengths, start + length
77
+ ).flatten(0, 1)
78
+ else:
79
+ slot_states = states[positions.flatten()]
80
+ ids, logprobs = read_slots(slot_states, output_weight)
81
+ output["slot_ids"] = ids.view(positions.shape)
82
+ output["slot_log_probs"] = logprobs.view(positions.shape)
83
+ return output
clairic_runtime/receipt_hybrid_inventory.py ADDED
@@ -0,0 +1,377 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ import hashlib
3
+ import json
4
+ import math
5
+ import re
6
+ import unicodedata
7
+ from collections.abc import Sequence
8
+ from itertools import pairwise
9
+ from typing import Any
10
+ from . import receipt_totals as base
11
+
12
+ canonical = base.canonical
13
+ BOOLEAN_EBNF = 'root ::= "true" | "false" | "null"'
14
+ MAX_DECISIONS = base.MAX_BLOCKS
15
+
16
+
17
+ def metadata_spans(source: str) -> list[tuple[int, int]]:
18
+ spans = [(item.start, item.end) for item in base.source_dates.candidates(source)]
19
+ spans.extend(
20
+ (
21
+ match.span()
22
+ for match in base._REFERENCE.finditer(source)
23
+ if re.match("[a-z]+", match[0], re.IGNORECASE)[0].upper()
24
+ not in base.sums._CURRENCY_CODES
25
+ )
26
+ )
27
+ spans.extend(
28
+ (
29
+ match.span()
30
+ for pattern in (
31
+ base._MEASUREMENT,
32
+ base._DISTANCE_RATE,
33
+ base._CARD_REFERENCE,
34
+ base._CONFIRMATION,
35
+ base._CLOCK,
36
+ base._SHORT_DATE,
37
+ base._DATE_CELL,
38
+ )
39
+ for match in pattern.finditer(source)
40
+ )
41
+ )
42
+ return spans
43
+
44
+
45
+ def unresolved_record_coverage(
46
+ source: str, start: int, end: int, monetary: Sequence[dict[str, Any]]
47
+ ) -> list[dict[str, Any]]:
48
+
49
+ def component_label(item: dict[str, Any], lower: int) -> re.Match[str] | None:
50
+ left = item["span"][0]
51
+ for label in base._COMPONENT.finditer(source, max(lower, left - 48), left):
52
+ gap = "".join(
53
+ (
54
+ "$" if unicodedata.category(char) == "Sc" else char
55
+ for char in source[label.end() : left]
56
+ )
57
+ )
58
+ if base._BRIDGE.fullmatch(gap):
59
+ return label
60
+ return None
61
+
62
+ def metadata_marker(match: re.Match[str]) -> bool:
63
+ line_end = source.find("\n", match.end(), end)
64
+ line_end = end if line_end < 0 else line_end
65
+ if any((match.end() <= item["span"][0] < line_end for item in monetary)):
66
+ return False
67
+ return bool(
68
+ re.match(
69
+ "[ \\t]+(?:method|reference|confirmation|booking|card|date|time)\\b",
70
+ source[match.end() : line_end],
71
+ re.IGNORECASE,
72
+ )
73
+ )
74
+
75
+ markers = [
76
+ match
77
+ for match in base._RECORD.finditer(source, start, end)
78
+ if not metadata_marker(match)
79
+ ]
80
+ boundaries = {start, end, *(match.start() for match in markers)}
81
+ metadata = metadata_spans(source)
82
+ for previous, following in pairwise(monetary):
83
+ if component_label(following, start) is None:
84
+ continue
85
+ (left, right) = (previous["span"][1], following["span"][0])
86
+ for line in re.compile("(?m)^[^\\n]*\\n").finditer(source, left, right):
87
+ if any(
88
+ (
89
+ lower < line.end() and line.start() < upper
90
+ for (lower, upper) in metadata
91
+ )
92
+ ):
93
+ continue
94
+ gap = "".join(
95
+ (
96
+ " " if unicodedata.category(char) == "Sc" else char
97
+ for char in line[0]
98
+ )
99
+ )
100
+ for pattern in (
101
+ base._TOTAL,
102
+ base._COMPONENT,
103
+ base._COMPONENT_CONNECTOR,
104
+ base._CURRENCY_CODE,
105
+ ):
106
+ gap = pattern.sub(" ", gap)
107
+ if not base._AMOUNT_GAP.fullmatch(gap) and (
108
+ not base._RECORD.search(line[0])
109
+ ):
110
+ boundaries.add(line.start())
111
+ marker_starts = {match.start() for match in markers}
112
+ unresolved = []
113
+ for lower, upper in pairwise(sorted(boundaries)):
114
+ amounts = [item for item in monetary if lower <= item["span"][0] < upper]
115
+ if not amounts:
116
+ if lower in marker_starts:
117
+ unresolved.append(
118
+ {
119
+ "span": [lower, upper],
120
+ "text": source[lower:upper],
121
+ "reason": "record_without_numeric_total_candidate",
122
+ }
123
+ )
124
+ continue
125
+ labels = [component_label(item, lower) for item in amounts]
126
+ structured = lower in marker_starts or all(
127
+ (
128
+ label is not None
129
+ and (
130
+ not source[
131
+ max(
132
+ lower, source.rfind("\n", lower, label.start()) + 1
133
+ ) : label.start()
134
+ ].strip()
135
+ )
136
+ for label in labels
137
+ )
138
+ )
139
+ if structured and all((label is not None for label in labels)):
140
+ unresolved.append(
141
+ {
142
+ "span": [lower, upper],
143
+ "text": source[lower:upper],
144
+ "reason": "component_amounts_without_whole_total_candidate",
145
+ "occurrence_ids": [item["id"] for item in amounts],
146
+ }
147
+ )
148
+ return unresolved
149
+
150
+
151
+ def inventory(
152
+ task: dict[str, Any],
153
+ ) -> tuple[list[dict[str, Any]], list[dict[str, Any]], list[dict[str, Any]]]:
154
+ source = task["input_text"]
155
+ metadata = metadata_spans(source)
156
+ (paragraphs, unresolved, unresolved_coverage) = ([], [], [])
157
+ for start, end in base._paragraphs(source):
158
+ numbers = [
159
+ item for item in task["candidates"] if start <= item["span"][0] < end
160
+ ]
161
+
162
+ def non_amount(item: dict[str, Any]) -> bool:
163
+ (left, right) = item["span"]
164
+ return any(
165
+ (
166
+ right <= upper
167
+ and (lower <= left or not source[left:lower].strip(" \t+-"))
168
+ for (lower, upper) in metadata
169
+ )
170
+ )
171
+
172
+ monetary = [item for item in numbers if not non_amount(item)]
173
+ blocks = base._blocks(task, paragraphs=((start, end),))
174
+ if blocks:
175
+ candidates = [
176
+ {
177
+ "kind": "whole_total",
178
+ "occurrence": block["total_occurrence"],
179
+ "source_block": block,
180
+ }
181
+ for block in blocks
182
+ ]
183
+ elif monetary:
184
+ unresolved_coverage.extend(
185
+ unresolved_record_coverage(source, start, end, monetary)
186
+ )
187
+ candidates = [
188
+ {
189
+ "kind": "unresolved_occurrence",
190
+ "occurrence": {key: item[key] for key in ("id", "span", "printed")},
191
+ }
192
+ for item in monetary
193
+ ]
194
+ else:
195
+ text = source[start:end]
196
+ if (
197
+ base._RECORD.search(text)
198
+ or base._TOTAL.search(text)
199
+ or base._CURRENCY_CODE.search(text)
200
+ or any((unicodedata.category(char) == "Sc" for char in text))
201
+ ):
202
+ unresolved.append({"span": [start, end], "text": text})
203
+ continue
204
+ paragraphs.append(
205
+ {
206
+ "span": [start, end],
207
+ "text": source[start:end],
208
+ "candidates": candidates,
209
+ "numeric_occurrence_ids": [item["id"] for item in numbers],
210
+ "metadata_occurrence_ids": [
211
+ item["id"] for item in numbers if non_amount(item)
212
+ ],
213
+ "monetary_occurrence_ids": [item["id"] for item in monetary],
214
+ }
215
+ )
216
+ return (paragraphs, unresolved, unresolved_coverage)
217
+
218
+
219
+ def _from_sum_task(task: dict[str, Any]) -> dict[str, Any] | None:
220
+ (paragraphs, unresolved, unresolved_coverage) = inventory(task)
221
+ if unresolved_coverage:
222
+ return None
223
+ descriptors = []
224
+ for paragraph in paragraphs:
225
+ for candidate in paragraph["candidates"]:
226
+ descriptors.append(
227
+ {
228
+ **candidate,
229
+ "paragraph_span": paragraph["span"],
230
+ "source_paragraph": paragraph["text"],
231
+ }
232
+ )
233
+ if not descriptors or len(descriptors) > MAX_DECISIONS:
234
+ return None
235
+ prefix = (
236
+ "Classify each source block using the entire supplied document.\nOriginal document:\n"
237
+ + task["input_text"]
238
+ + "\n\nRequested numeric field: "
239
+ + task["field"]
240
+ + "\nOriginal field schema and instructions: "
241
+ + json.dumps(task["field_spec"], ensure_ascii=False, separators=(",", ":"))
242
+ + "\nDecide whether the candidate block is one receipt record in the requested sum. Use its category, entity, date and the original requested scope. Return true if and only if this record's explicit total is one requested operand. A total label alone does not establish inclusion. Hotel, airline and claim-summary blocks remain candidates; include them only when the requested receipt scope includes them. A claim summary is not an additional underlying receipt. Do not separately select food, subtotal, tax, tip or other components already included in a total. A zero or refund remains a present amount. Distinct source records remain distinct even with equal totals. Do not calculate the sum. Return false for an excluded record; return null if the evidence does not determine its inclusion. No expected values are supplied. Return exactly one JSON Boolean or null, then end immediately.\n"
243
+ )
244
+ prefix += "When the candidate marks one exact occurrence, evaluate only that marked occurrence as a whole receipt total; its paragraph may contain multiple records or totals. Every candidate still requires its own category, entity, date and requested-scope decision.\n"
245
+ tasks = []
246
+ for descriptor in descriptors:
247
+ if descriptor["kind"] == "whole_total":
248
+ suffix = "\nCandidate source block: " + json.dumps(
249
+ descriptor["source_block"], ensure_ascii=False, separators=(",", ":")
250
+ )
251
+ else:
252
+ suffix = "\nCandidate exact source occurrence: " + json.dumps(
253
+ descriptor, ensure_ascii=False, separators=(",", ":")
254
+ )
255
+ tasks.append(
256
+ {
257
+ "occurrence_id": descriptor["occurrence"]["id"],
258
+ "prompt": prefix + suffix,
259
+ "suffix": suffix,
260
+ "json_schema": {"type": ["boolean", "null"]},
261
+ "grammar": {"ebnf": BOOLEAN_EBNF},
262
+ }
263
+ )
264
+ assert len({task["occurrence_id"] for task in tasks}) == len(tasks)
265
+ return {
266
+ "version": 1,
267
+ "kind": "receipt-hybrid-paragraph-runtime-v1",
268
+ "sum_task": task,
269
+ "paragraphs": paragraphs,
270
+ "descriptors": descriptors,
271
+ "tasks": tasks,
272
+ "currency_compatible": base._compatible_currencies(
273
+ task, [{"source_block": row["text"]} for row in paragraphs]
274
+ ),
275
+ "unresolved_fragments_without_numeric_candidates": unresolved,
276
+ "shared_prefix": prefix,
277
+ "shared_prefix_sha256": hashlib.sha256(prefix.encode()).hexdigest(),
278
+ "diagnostic_only": False,
279
+ "public_repair_path": True,
280
+ "serving_admission_requires_backend_guard": True,
281
+ "runtime_changes": True,
282
+ "all_candidates_require_complete_decisions": True,
283
+ "native_typed_boolean_head": False,
284
+ "semantic_completeness_proven_by_grounding": False,
285
+ }
286
+
287
+
288
+ def prepare_task(
289
+ record: dict[str, Any], field_name: str, *, has_media: bool = False
290
+ ) -> dict[str, Any] | None:
291
+ if not base.eligible(record, field_name, has_media=has_media):
292
+ return None
293
+ task = base.sums.prepare_task(record, field_name, has_media=has_media)
294
+ return None if task is None else _from_sum_task(task)
295
+
296
+
297
+ def validate_result(
298
+ packet: dict[str, Any], decisions: dict[str, dict[str, Any]]
299
+ ) -> dict[str, Any]:
300
+ result: dict[str, Any] = {
301
+ "valid": False,
302
+ "value": None,
303
+ "error": None,
304
+ "decision_count": 0,
305
+ "required_decision_count": len(packet.get("tasks", [])),
306
+ "diagnostic_only": False,
307
+ "public_repair_path": True,
308
+ "serving_admission_requires_backend_guard": True,
309
+ "backend_constructs_public_answer": True,
310
+ "semantic_completeness_proven_by_grounding": False,
311
+ }
312
+ try:
313
+ task = packet["sum_task"]
314
+ rebuilt = base.prepare_task(
315
+ {
316
+ "input": task["input_text"],
317
+ "fields": {task["field"]: task["field_spec"]},
318
+ },
319
+ task["field"],
320
+ )
321
+ if rebuilt is None or canonical(rebuilt) != canonical(packet):
322
+ raise ValueError("hybrid_packet_prompt_or_source_mapping_changed")
323
+ if packet["unresolved_fragments_without_numeric_candidates"]:
324
+ raise ValueError("unresolved_fragment_without_numeric_candidate")
325
+ expected = [item["occurrence_id"] for item in packet["tasks"]]
326
+ if not isinstance(decisions, dict) or set(decisions) != set(expected):
327
+ raise ValueError("hybrid_decision_coverage_incomplete_or_extra")
328
+ selected = []
329
+ for identifier in expected:
330
+ reading = decisions[identifier]
331
+ value = json.loads(
332
+ reading["raw_json"],
333
+ parse_constant=lambda _: (_ for _ in ()).throw(
334
+ ValueError("nonfinite_json")
335
+ ),
336
+ )
337
+ if type(value) is not bool or reading.get("complete") is not True:
338
+ raise ValueError("unresolved_or_incomplete_boolean:" + identifier)
339
+ score: Any
340
+ confidence: Any
341
+ (score, confidence) = (
342
+ reading.get("log_probability"),
343
+ reading.get("confidence"),
344
+ )
345
+ if (
346
+ type(score) not in (int, float)
347
+ or not math.isfinite(score)
348
+ or score > 0
349
+ or (type(confidence) not in (int, float))
350
+ or (not math.isfinite(confidence))
351
+ or (not 0 <= confidence <= 1)
352
+ or (
353
+ not math.isclose(
354
+ confidence, math.exp(score), rel_tol=2e-15, abs_tol=0
355
+ )
356
+ )
357
+ or (type(reading.get("tokens")) is not int)
358
+ or (not 1 <= reading["tokens"] <= 8)
359
+ ):
360
+ raise ValueError(
361
+ "native_boolean_score_or_token_contract_failed:" + identifier
362
+ )
363
+ result["decision_count"] += 1
364
+ if value:
365
+ selected.append(identifier)
366
+ scores = base._selection_scores(decisions, expected)
367
+ if scores is None:
368
+ raise ValueError("native_joint_boolean_scores_required")
369
+ if not packet["currency_compatible"]:
370
+ raise ValueError("explicit_currency_conflict_no_conversion")
371
+ checked = base.sums.validate_result(
372
+ task, json.dumps(selected) if selected else "null", complete=True
373
+ )
374
+ result.update(checked, selected_ids=selected, selection_scores=scores)
375
+ except (ArithmeticError, AttributeError, KeyError, TypeError, ValueError) as error:
376
+ result.update(valid=False, value=None, error=str(error) or type(error).__name__)
377
+ return result
clairic_runtime/receipt_totals.py ADDED
@@ -0,0 +1,555 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ import hashlib
3
+ import json
4
+ import math
5
+ import re
6
+ import unicodedata
7
+ from collections.abc import Iterable, Iterator
8
+ from decimal import Decimal, localcontext
9
+ from itertools import pairwise
10
+ from typing import Any
11
+ from . import ar, source_dates
12
+ from . import source_sums as sums
13
+
14
+ MAX_BLOCKS = 128
15
+ MAX_LABEL_AMOUNT_GAP = 24
16
+ MAX_SUPPORT_BLOCKS = 24
17
+ MAX_SUPPORT_PRECISION = 256
18
+ _RECEIPT = re.compile("\\breceipts?\\b", re.IGNORECASE)
19
+ _REQUESTED_TOTAL = re.compile("\\btotals?\\b", re.IGNORECASE)
20
+ _COMPOUND = re.compile(
21
+ "\\b(?:averag\\w*|mean|median|subtract\\w*|deduct\\w*|minus|less|plus|add(?:s|ed|ing)?|multipl\\w*|times|divid\\w*|quotient|ratio|percent(?:age)?|discount\\w*|surcharge\\w*|convert\\w*|conversion\\w*|exchange|fx|clamp\\w*|cap(?:ped)?|net[ \\t]+of)\\b|[*/×÷%=]|(?<=\\s)[+-][ \\t]*\\d|\\b(?:in|to)[ \\t]+cents?\\b",
22
+ re.IGNORECASE,
23
+ )
24
+ _ROUND = "(?:round\\w*|ceil\\w*|floor\\w*|truncat\\w*)"
25
+ _ROUND_EACH = re.compile(
26
+ "\\b"
27
+ + _ROUND
28
+ + "\\b[^.;\\n]*(?:\\b(?:each|every|per|individually|before)\\b|\\breceipts?\\b)|\\b(?:each|every|per|individual(?:ly)?)\\b[^.;\\n]*\\b"
29
+ + _ROUND
30
+ + "\\b",
31
+ re.IGNORECASE,
32
+ )
33
+ _TOTAL = re.compile(
34
+ "\\b(?:amount[ \\t]+charged|(?:grand[ \\t]+)?total(?:[ \\t]+(?:charges|claimed|paid|due|amount))?)\\b",
35
+ re.IGNORECASE,
36
+ )
37
+ _SEPARATOR = re.compile("\\r?\\n[ \\t]*\\r?\\n")
38
+ _RECORD = re.compile("\\b(?:receipt|payment)\\b", re.IGNORECASE)
39
+ _REFERENCE = re.compile(
40
+ "\\b(?:(?:room|receipt)[ \\t]+\\d+|(?:odometer[ \\t]+(?:start|end)|(?:trip[ \\t]+)?miles)[ \\t]+\\d+|[a-z][a-z0-9_]*[-/#][a-z0-9_/-]*\\d[a-z0-9_/-]*|[a-z]+\\d+[a-z0-9]*)\\b",
41
+ re.IGNORECASE,
42
+ )
43
+ _MEASUREMENT = re.compile(
44
+ "\\b\\d+(?:\\.\\d+)?[ \\t]+(?:miles?|nights?)\\b", re.IGNORECASE
45
+ )
46
+ _DISTANCE_RATE = re.compile(
47
+ "(?<!\\w)(?:\\$|USD[ \\t]+)?\\d+(?:\\.\\d+)?/miles?\\b", re.IGNORECASE
48
+ )
49
+ _CARD_REFERENCE = re.compile("\\*{2,}\\d+\\b")
50
+ _CONFIRMATION = re.compile(
51
+ "\\b(?:conf(?:irmation)?|booking|reference)[ \\t]*[#:]?[ \\t]+[a-z0-9]+\\b",
52
+ re.IGNORECASE,
53
+ )
54
+ _CLOCK = re.compile("\\b(?:[01]?\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d)?\\b")
55
+ _SHORT_DATE = re.compile(
56
+ "(?<!\\w)(?:"
57
+ + source_dates._MONTH
58
+ + "[ \\t]+\\d{1,2}|\\d{1,2}[ \\t-]+"
59
+ + source_dates._MONTH
60
+ + ")(?!\\w)",
61
+ re.IGNORECASE,
62
+ )
63
+ _DATE_CELL = re.compile(
64
+ "(?m)^[ \\t]*(?:0?[1-9]|1[0-2])/(?:0?[1-9]|[12]\\d|3[01])(?=[ \\t])"
65
+ )
66
+ _COMPONENT = re.compile(
67
+ "\\b(?:sub[ \\t-]?total|food|tax(?:es)?(?:/fees)?|tip|fare|room(?:[ \\t]+charge)?|occupancy[ \\t]+tax|facility[ \\t]+fee|balance[ \\t]+due|ticket[ \\t]+was)\\b",
68
+ re.IGNORECASE,
69
+ )
70
+ _COMPONENT_CONNECTOR = re.compile("\\b(?:incl(?:uding)?|and)\\b", re.IGNORECASE)
71
+ _AMOUNT_GAP = re.compile("[\\s.,:;=()+\\-\\u2212/&*]*")
72
+ _CURRENCY = "|".join(sorted(sums._CURRENCY_CODES))
73
+ _BRIDGE = re.compile("(?:[\\s:=()$+\\-\\u2212]|" + _CURRENCY + ")*", re.IGNORECASE)
74
+ _CURRENCY_CODE = re.compile("\\b(?:" + _CURRENCY + ")\\b", re.IGNORECASE)
75
+ _DOLLAR_CURRENCIES = frozenset({"USD", "AUD", "CAD", "HKD", "NZD", "SGD", "MXN", "BRL"})
76
+ _CURRENCY_SYMBOLS = {
77
+ "$": _DOLLAR_CURRENCIES,
78
+ "€": frozenset({"EUR"}),
79
+ "£": frozenset({"GBP"}),
80
+ "¥": frozenset({"JPY", "CNY"}),
81
+ "₹": frozenset({"INR"}),
82
+ "₩": frozenset({"KRW"}),
83
+ }
84
+
85
+
86
+ def canonical(value: object) -> bytes:
87
+ return json.dumps(
88
+ value,
89
+ sort_keys=True,
90
+ ensure_ascii=False,
91
+ separators=(",", ":"),
92
+ allow_nan=False,
93
+ ).encode()
94
+
95
+
96
+ def _paragraphs(source: str) -> Iterator[tuple[int, int]]:
97
+ start = 0
98
+ for boundary in list(_SEPARATOR.finditer(source)) + [None]:
99
+ end = len(source) if boundary is None else boundary.start()
100
+ (left, right) = (start, end)
101
+ while left < right and source[left].isspace():
102
+ left += 1
103
+ while right > left and source[right - 1].isspace():
104
+ right -= 1
105
+ if left < right:
106
+ yield (left, right)
107
+ if boundary is not None:
108
+ start = boundary.end()
109
+
110
+
111
+ def _blocks(
112
+ task: dict[str, Any], *, paragraphs: Iterable[tuple[int, int]] | None = None
113
+ ) -> list[dict[str, Any]] | None:
114
+ source = task["input_text"]
115
+ gap: str | list[str]
116
+ metadata = [(item.start, item.end) for item in source_dates.candidates(source)]
117
+ metadata.extend(
118
+ (
119
+ match.span()
120
+ for match in _REFERENCE.finditer(source)
121
+ if re.match("[a-z]+", match[0], re.IGNORECASE)[0].upper()
122
+ not in sums._CURRENCY_CODES
123
+ )
124
+ )
125
+ metadata.extend(
126
+ (
127
+ match.span()
128
+ for pattern in (
129
+ _MEASUREMENT,
130
+ _DISTANCE_RATE,
131
+ _CARD_REFERENCE,
132
+ _CONFIRMATION,
133
+ _CLOCK,
134
+ _SHORT_DATE,
135
+ _DATE_CELL,
136
+ )
137
+ for match in pattern.finditer(source)
138
+ )
139
+ )
140
+
141
+ def non_amount(item: dict[str, Any]) -> bool:
142
+ (left, right) = item["span"]
143
+ return any(
144
+ (
145
+ right <= end
146
+ and (start <= left or not source[left:start].strip(" \t+-"))
147
+ for (start, end) in metadata
148
+ )
149
+ )
150
+
151
+ blocks = []
152
+ for start, end in _paragraphs(source) if paragraphs is None else paragraphs:
153
+ labels = list(_TOTAL.finditer(source, start, end))
154
+ numbers = [
155
+ item for item in task["candidates"] if start <= item["span"][0] < end
156
+ ]
157
+ if not labels:
158
+ text = source[start:end]
159
+ if (
160
+ any((not non_amount(item) for item in numbers))
161
+ or _RECORD.search(text)
162
+ or _CURRENCY_CODE.search(text)
163
+ or any((unicodedata.category(char) == "Sc" for char in text))
164
+ ):
165
+ return None
166
+ continue
167
+ if len(labels) != 1 or len(list(_RECORD.finditer(source, start, end))) > 1:
168
+ return None
169
+ label = labels[0]
170
+ linked = []
171
+ for item in task["candidates"]:
172
+ (left, right) = item["span"]
173
+ if (
174
+ not label.end() <= left <= label.end() + MAX_LABEL_AMOUNT_GAP
175
+ or right > end
176
+ ):
177
+ continue
178
+ gap = "".join(
179
+ (
180
+ "$" if unicodedata.category(char) == "Sc" else char
181
+ for char in source[label.end() : left]
182
+ )
183
+ )
184
+ if _BRIDGE.fullmatch(gap):
185
+ linked.append(item)
186
+ if not linked:
187
+ for item in task["candidates"]:
188
+ (left, right) = item["span"]
189
+ if (
190
+ left < start
191
+ or not label.start() - MAX_LABEL_AMOUNT_GAP
192
+ <= right
193
+ <= label.start()
194
+ ):
195
+ continue
196
+ gap = "".join(
197
+ (
198
+ "$" if unicodedata.category(char) == "Sc" else char
199
+ for char in source[right : label.start()]
200
+ )
201
+ )
202
+ if _BRIDGE.fullmatch(gap):
203
+ linked.append(item)
204
+ if len(linked) != 1:
205
+ return None
206
+ item = linked[0]
207
+ for other in numbers:
208
+ if other is item or non_amount(other):
209
+ continue
210
+ (left, _) = other["span"]
211
+ components = _COMPONENT.finditer(source, max(start, left - 48), left)
212
+ if not any(
213
+ (
214
+ _BRIDGE.fullmatch(
215
+ "".join(
216
+ (
217
+ "$" if unicodedata.category(char) == "Sc" else char
218
+ for char in source[component.end() : left]
219
+ )
220
+ )
221
+ )
222
+ for component in components
223
+ )
224
+ ):
225
+ return None
226
+ monetary = [other for other in numbers if not non_amount(other)]
227
+ for previous, following in pairwise(monetary):
228
+ (left, right) = (previous["span"][1], following["span"][0])
229
+ gap = list(source[left:right])
230
+ for meta_left, meta_right in metadata:
231
+ for offset in range(max(left, meta_left), min(right, meta_right)):
232
+ gap[offset - left] = " "
233
+ gap = "".join(
234
+ (" " if unicodedata.category(char) == "Sc" else char for char in gap)
235
+ )
236
+ for pattern in (_TOTAL, _COMPONENT, _COMPONENT_CONNECTOR, _CURRENCY_CODE):
237
+ gap = pattern.sub(" ", gap)
238
+ if not _AMOUNT_GAP.fullmatch(gap):
239
+ return None
240
+ blocks.append(
241
+ {
242
+ "block_span": [start, end],
243
+ "source_block": source[start:end],
244
+ "total_label": label[0],
245
+ "total_label_span": [label.start(), label.end()],
246
+ "total_occurrence": {
247
+ key: item[key] for key in ("id", "span", "printed")
248
+ },
249
+ }
250
+ )
251
+ if len(blocks) > MAX_BLOCKS:
252
+ return None
253
+ return blocks or None
254
+
255
+
256
+ def _compatible_currencies(
257
+ task: dict[str, Any], blocks: Iterable[dict[str, Any]]
258
+ ) -> bool:
259
+ allowed = set(sums._CURRENCY_CODES)
260
+ unit = task["field_spec"].get("unit")
261
+ if unit not in (None, ""):
262
+ if not isinstance(unit, str):
263
+ return False
264
+ normalized = unit.strip().upper()
265
+ if normalized in sums._CURRENCY_CODES:
266
+ allowed.intersection_update({normalized})
267
+ elif unit.strip() in _CURRENCY_SYMBOLS:
268
+ allowed.intersection_update(_CURRENCY_SYMBOLS[unit.strip()])
269
+ else:
270
+ return False
271
+ for text in [
272
+ task["field_spec"]["instructions"],
273
+ *(block["source_block"] for block in blocks),
274
+ ]:
275
+ for code in _CURRENCY_CODE.finditer(text):
276
+ allowed.intersection_update({code[0].upper()})
277
+ for char in text:
278
+ if unicodedata.category(char) == "Sc":
279
+ allowed.intersection_update(_CURRENCY_SYMBOLS.get(char, ()))
280
+ if not allowed:
281
+ return False
282
+ return True
283
+
284
+
285
+ def _from_sum_task(task: dict[str, Any]) -> dict[str, Any] | None:
286
+ blocks = _blocks(task)
287
+ if blocks is None or not _compatible_currencies(task, blocks):
288
+ return None
289
+ prefix = (
290
+ "Classify each source block using the entire supplied document.\nOriginal document:\n"
291
+ + task["input_text"]
292
+ + "\n\nRequested numeric field: "
293
+ + task["field"]
294
+ + "\nOriginal field schema and instructions: "
295
+ + json.dumps(task["field_spec"], ensure_ascii=False, separators=(",", ":"))
296
+ + "\nDecide whether the candidate block is one receipt record in the requested sum. Use its category, entity, date and the original requested scope. Return true if and only if this record's explicit total is one requested operand. A total label alone does not establish inclusion. Hotel, airline and claim-summary blocks remain candidates; include them only when the requested receipt scope includes them. A claim summary is not an additional underlying receipt. Do not separately select food, subtotal, tax, tip or other components already included in a total. A zero or refund remains a present amount. Distinct source records remain distinct even with equal totals. Do not calculate the sum. Return false for an excluded record; return null if the evidence does not determine its inclusion. No expected values are supplied. Return exactly one JSON Boolean or null, then end immediately.\n"
297
+ )
298
+ tasks = []
299
+ for block in blocks:
300
+ suffix = "\nCandidate source block: " + json.dumps(
301
+ block, ensure_ascii=False, separators=(",", ":")
302
+ )
303
+ tasks.append(
304
+ {
305
+ "occurrence_id": block["total_occurrence"]["id"],
306
+ "suffix": suffix,
307
+ "prompt": prefix + suffix,
308
+ "json_schema": {"type": ["boolean", "null"]},
309
+ "grammar": {"ebnf": 'root ::= "true" | "false" | "null"'},
310
+ }
311
+ )
312
+ return {
313
+ "version": 1,
314
+ "kind": "source-receipt-block-boolean-sum-diagnostic-v1",
315
+ "sum_task": task,
316
+ "shared_prefix": prefix,
317
+ "shared_prefix_sha256": hashlib.sha256(prefix.encode()).hexdigest(),
318
+ "tasks": tasks,
319
+ "blocks": blocks,
320
+ "all_candidates_require_complete_decisions": True,
321
+ "native_typed_boolean_head": False,
322
+ "runtime_changes": False,
323
+ "semantic_completeness_proven_by_grounding": False,
324
+ }
325
+
326
+
327
+ def eligible(
328
+ record: dict[str, Any], field_name: str, *, has_media: bool = False
329
+ ) -> bool:
330
+ if not sums.eligible(record, field_name, has_media=has_media):
331
+ return False
332
+ instructions = record["fields"][field_name]["instructions"]
333
+ return bool(
334
+ _RECEIPT.search(instructions)
335
+ and _REQUESTED_TOTAL.search(instructions)
336
+ and (not _COMPOUND.search(instructions))
337
+ and (not _ROUND_EACH.search(instructions))
338
+ )
339
+
340
+
341
+ def prepare_task(
342
+ record: dict[str, Any], field_name: str, *, has_media: bool = False
343
+ ) -> dict[str, Any] | None:
344
+ if not eligible(record, field_name, has_media=has_media):
345
+ return None
346
+ from . import receipt_hybrid_inventory
347
+
348
+ task = sums.prepare_task(record, field_name, has_media=has_media)
349
+ if task is None:
350
+ return None
351
+ legacy = _from_sum_task(task)
352
+ if legacy is not None:
353
+ return legacy
354
+ packet = receipt_hybrid_inventory._from_sum_task(task)
355
+ if (
356
+ packet is None
357
+ or not packet["currency_compatible"]
358
+ or packet["unresolved_fragments_without_numeric_candidates"]
359
+ or (len(packet["tasks"]) > MAX_BLOCKS)
360
+ ):
361
+ return None
362
+ return packet
363
+
364
+
365
+ def supports_sum(packet: dict[str, Any], primary_value: object) -> bool | None:
366
+ if isinstance(primary_value, bool) or not isinstance(
367
+ primary_value, (int, float, Decimal)
368
+ ):
369
+ return None
370
+ try:
371
+ target = Decimal(str(primary_value))
372
+ if not target.is_finite():
373
+ return None
374
+ task = packet["sum_task"]
375
+ hybrid = packet.get("kind") == "receipt-hybrid-paragraph-runtime-v1"
376
+ blocks = packet["descriptors" if hybrid else "blocks"]
377
+ if not 0 < len(blocks) <= MAX_SUPPORT_BLOCKS:
378
+ return None
379
+ recomputed = prepare_task(
380
+ {
381
+ "input": task["input_text"],
382
+ "fields": {task["field"]: task["field_spec"]},
383
+ },
384
+ task["field"],
385
+ )
386
+ if recomputed is None or canonical(recomputed) != canonical(packet):
387
+ return None
388
+ indexed = {item["id"]: item for item in task["candidates"]}
389
+ amounts = []
390
+ for block in blocks:
391
+ item = indexed[block["occurrence" if hybrid else "total_occurrence"]["id"]]
392
+ if item["decimal"] is None:
393
+ return None
394
+ amount = Decimal(item["decimal"])
395
+ if not amount.is_finite():
396
+ return None
397
+ amounts.append(amount)
398
+ values = [target, *amounts]
399
+ highest = max((value.adjusted() for value in values))
400
+ lowest: int = min((value.as_tuple().exponent for value in values))
401
+ required_digits = highest - lowest + len(str(len(amounts))) + 3
402
+ precision = max(28, required_digits)
403
+ if precision > MAX_SUPPORT_PRECISION:
404
+ return None
405
+
406
+ def subsets(items: list[Decimal]) -> dict[Decimal, bool]:
407
+ totals = {Decimal(0): False}
408
+ for amount in items:
409
+ previous = list(totals)
410
+ for value in previous:
411
+ totals[value + amount] = True
412
+ return totals
413
+
414
+ with localcontext() as context:
415
+ context.prec = precision
416
+ spec = task["field_spec"]
417
+
418
+ def normalized(value: Decimal) -> Decimal:
419
+ return Decimal(str(ar.normalize_number(value, spec)))
420
+
421
+ if normalized(target) != target:
422
+ return None
423
+ middle = len(amounts) // 2
424
+ (left, right) = (subsets(amounts[:middle]), subsets(amounts[middle:]))
425
+ for value, nonempty in left.items():
426
+ rest = target - value
427
+ if (
428
+ rest in right
429
+ and (nonempty or right[rest])
430
+ and (normalized(value + rest) == target)
431
+ ):
432
+ return True
433
+ if any((normalized(amount) != amount for amount in amounts)):
434
+ return None
435
+ if required_digits > 15 and any(
436
+ (amount != amount.to_integral_value() for amount in amounts)
437
+ ):
438
+ return None
439
+ return False
440
+ except (ArithmeticError, AttributeError, KeyError, TypeError, ValueError):
441
+ return None
442
+
443
+
444
+ def _selection_scores(
445
+ decisions: dict[str, dict[str, Any]], expected: Iterable[str]
446
+ ) -> dict[str, Any] | None:
447
+ scores = []
448
+ for identifier in expected:
449
+ row = decisions[identifier]
450
+ score = row.get("log_probability")
451
+ if (
452
+ row.get("valid") is not True
453
+ or row.get("complete") is not True
454
+ or type(row.get("value")) is not bool
455
+ or (row["value"] is not json.loads(row["raw_json"]))
456
+ or (row.get("decoder") != ar.VERSION)
457
+ or (row.get("confidence_method") != "ar_sequence_probability")
458
+ or isinstance(score, bool)
459
+ or (not isinstance(score, (int, float)))
460
+ ):
461
+ return None
462
+ try:
463
+ if not math.isfinite(score) or score > 0:
464
+ return None
465
+ scores.append(float(score))
466
+ except (OverflowError, ValueError):
467
+ return None
468
+ try:
469
+ total = math.fsum(scores)
470
+ except OverflowError:
471
+ return None
472
+ if not math.isfinite(total):
473
+ return None
474
+ return {
475
+ "log_probability": total,
476
+ "confidence": math.exp(total),
477
+ "confidence_method": "receipt_block_boolean_joint_sequence_probability",
478
+ "score_scope": "all_receipt_block_inclusion_decisions",
479
+ "decision_count": len(scores),
480
+ }
481
+
482
+
483
+ def validate_result(
484
+ packet: dict[str, Any], decisions: dict[str, dict[str, Any]]
485
+ ) -> dict[str, Any]:
486
+ if packet.get("kind") == "receipt-hybrid-paragraph-runtime-v1":
487
+ from . import receipt_hybrid_inventory
488
+
489
+ return receipt_hybrid_inventory.validate_result(packet, decisions)
490
+ result: dict[str, Any] = {
491
+ "valid": False,
492
+ "value": None,
493
+ "operands": [],
494
+ "decimal_sum": None,
495
+ "operand_count": 0,
496
+ "error": None,
497
+ "selection_method": "per_receipt_block_boolean_diagnostic",
498
+ "decision_count": 0,
499
+ "required_decision_count": 0,
500
+ "semantic_completeness_proven_by_grounding": False,
501
+ }
502
+ try:
503
+ task = packet["sum_task"]
504
+ result["required_decision_count"] = len(packet["tasks"])
505
+ recomputed = prepare_task(
506
+ {
507
+ "input": task["input_text"],
508
+ "fields": {task["field"]: task["field_spec"]},
509
+ },
510
+ task["field"],
511
+ )
512
+ if recomputed is None or canonical(recomputed) != canonical(packet):
513
+ raise ValueError("receipt_block_prompt_or_source_mapping_changed")
514
+ expected = [row["occurrence_id"] for row in packet["tasks"]]
515
+ if not isinstance(decisions, dict) or set(decisions) != set(expected):
516
+ raise ValueError("receipt_block_coverage_incomplete_or_extra")
517
+ selected = []
518
+ for identifier in expected:
519
+ row = decisions[identifier]
520
+ if not isinstance(row, dict) or row.get("complete") is not True:
521
+ raise ValueError("incomplete_boolean_generation:" + identifier)
522
+ value = json.loads(
523
+ row["raw_json"],
524
+ parse_constant=lambda _: (_ for _ in ()).throw(
525
+ ValueError("nonfinite_json")
526
+ ),
527
+ )
528
+ if value is None:
529
+ raise ValueError("unresolved_boolean_inclusion:" + identifier)
530
+ if type(value) is not bool:
531
+ raise ValueError("invalid_boolean_scalar:" + identifier)
532
+ result["decision_count"] += 1
533
+ if value:
534
+ selected.append(identifier)
535
+ result.update(
536
+ sums.validate_result(
537
+ task, json.dumps(selected) if selected else "null", complete=True
538
+ )
539
+ )
540
+ result["selected_ids"] = selected
541
+ if (
542
+ result["valid"]
543
+ and (scores := _selection_scores(decisions, expected)) is not None
544
+ ):
545
+ result["selection_scores"] = scores
546
+ except Exception as error:
547
+ result.update(
548
+ valid=False,
549
+ value=None,
550
+ operands=[],
551
+ decimal_sum=None,
552
+ operand_count=0,
553
+ error=str(error) or type(error).__name__,
554
+ )
555
+ return result
clairic_runtime/schema.py ADDED
@@ -0,0 +1,533 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ import datetime
3
+ import hashlib
4
+ import itertools
5
+ import math
6
+ import re
7
+ from typing import Any, cast
8
+
9
+ READ_TYPES = ("text", "number", "date", "time", "datetime", "duration")
10
+ FIELD_TYPES = READ_TYPES + ("list", "estimate")
11
+ EVIDENCE_CONSTRUCTION = "evidence-v1"
12
+ ANSWER_ROUTES = ("copy", "normalize", "derive", "knowledge", "abstain")
13
+ REQUEST_TYPES = FIELD_TYPES + ("compute", "forecast")
14
+ LIST_ITEM_TYPES = ("text", "number", "date")
15
+ DURATION_UNITS = ("seconds", "minutes", "hours", "days", "weeks", "months", "years")
16
+ MAX_LIST_ITEMS = 32
17
+ MAX_DECIMALS = 6
18
+ MAX_FORECAST_HORIZON = 64
19
+ FORECAST_INTERVALS = (
20
+ "step",
21
+ "minute",
22
+ "hour",
23
+ "day",
24
+ "week",
25
+ "month",
26
+ "quarter",
27
+ "year",
28
+ )
29
+ DEFAULT_NULL_THRESHOLD = 0.5
30
+
31
+
32
+ def list_item_name(parent: str, index: int) -> str:
33
+ suffix = f".item{index}"
34
+ if len(parent) + len(suffix) <= 64:
35
+ return parent + suffix
36
+ digest = hashlib.sha256(parent.encode()).hexdigest()[:8]
37
+ return parent[: 64 - len(suffix) - 9] + "_" + digest + suffix
38
+
39
+
40
+ def list_query_fields(fields: dict[str, Any], parent: str) -> list[str]:
41
+ spec = fields[parent]
42
+ item_type = (
43
+ spec["items"].get("type") if isinstance(spec["items"], dict) else spec["items"]
44
+ )
45
+ queries = {}
46
+ for name, child in fields.items():
47
+ (_, separator, ordinal) = name.rpartition(".item")
48
+ if not separator or not ordinal.isascii() or (not ordinal.isdigit()):
49
+ continue
50
+ index = int(ordinal)
51
+ if (
52
+ index > 0
53
+ and name == list_item_name(parent, index)
54
+ and (child.get("type") == item_type)
55
+ ):
56
+ queries[index] = name
57
+ if sorted(queries) != list(range(1, len(queries) + 1)):
58
+ raise ValueError(f"noncontiguous scalar list queries for {parent!r}")
59
+ return [queries[index] for index in range(1, len(queries) + 1)]
60
+
61
+
62
+ def assemble_list_predictions(
63
+ record: dict[str, Any], predictions: dict[str, dict[str, Any]]
64
+ ) -> dict[str, dict[str, Any]]:
65
+ if (record.get("_meta") or {}).get("construction") != EVIDENCE_CONSTRUCTION:
66
+ return predictions
67
+ fields = record["fields"]
68
+ merged = dict(predictions)
69
+ for parent, spec in fields.items():
70
+ if spec.get("type") != "list":
71
+ continue
72
+ queries = list_query_fields(fields, parent)
73
+ if not queries:
74
+ continue
75
+ (values, confidences, probabilities) = ([], [], [])
76
+ for name in queries:
77
+ item = predictions.get(name)
78
+ if item is None or "value" not in item:
79
+ raise ValueError(f"missing scalar list prediction for {name!r}")
80
+ if item["value"] is None:
81
+ probabilities.append(item.get("p_null"))
82
+ break
83
+ values.append(item["value"])
84
+ confidences.append(item.get("confidence"))
85
+ probabilities.append(
86
+ (1.0 - item["p_null"]) * item["confidence"]
87
+ if "p_null" in item and "confidence" in item
88
+ else None
89
+ )
90
+ assembled: dict[str, Any] = {"value": values}
91
+ if all((value is not None for value in confidences)):
92
+ assembled["confidences"] = confidences
93
+ if probabilities and all((value is not None for value in probabilities)):
94
+ assembled["confidence"] = math.prod(cast(list[float], probabilities))
95
+ merged[parent] = assembled
96
+ return merged
97
+
98
+
99
+ SYSTEM_PREAMBLE = "Fill each field from the input with a value of its type. Text copies a span of the input. Numbers, dates, times, datetimes, and durations are read from the input or worked out from it. A list holds every matching value in input order. A field is not stated when the input does not determine it. Estimates predict a value inside the declared range."
100
+ EVIDENCE_SYSTEM_PREAMBLE = "Fill each field with a value of its type, following its instructions and the question's scope. For document-specific extraction, use the supplied input and return not stated when the requested information is missing. Preserve exact text, names and numbers unless normalization or a derived answer is requested. General factual questions may use reliable prior knowledge unless the instructions restrict answers to the supplied evidence; return not stated when the answer cannot be determined reliably. A list holds every matching item in the requested order, including repeated items. Estimates and forecasts predict distributions over the declared range and supported below-range or above-range outcomes. Follow the requested units, time intervals and horizons."
101
+ FIELD_NAME = re.compile("^[A-Za-z_][A-Za-z0-9_.\\-]{0,63}$")
102
+
103
+
104
+ def format_bound(value: float) -> str:
105
+ if float(value).is_integer() and abs(value) < 1000000000000000.0:
106
+ return str(int(value))
107
+ return f"{value:.6g}"
108
+
109
+
110
+ def field_line(
111
+ name: str, spec: dict[str, Any], preserve_instructions: bool = False
112
+ ) -> str:
113
+ kind = spec["type"]
114
+ unit = str(spec.get("unit") or "").strip()
115
+ if kind == "estimate" and is_date_estimate(spec):
116
+ head = f"estimate date, {spec['min']} to {spec['max']}"
117
+ granularity = date_granularity(spec)
118
+ if granularity != "day":
119
+ head += f", by {granularity}"
120
+ elif spec.get("step") and float(spec["step"]) != 1:
121
+ head += f", step {format_bound(float(spec['step']))} days"
122
+ elif kind == "estimate":
123
+ head = f"estimate{(' ' + unit if unit else '')}, {format_bound(spec['min'])} to {format_bound(spec['max'])}, {spec.get('scale', 'linear')} scale"
124
+ if spec.get("step"):
125
+ head += f", step {format_bound(float(spec['step']))}"
126
+ elif kind == "list":
127
+ head = f"list of {spec['items']}{number_options(spec)}{(' (' + unit + ')' if unit else '')}"
128
+ elif kind == "duration":
129
+ head = f"duration in {duration_unit(spec)}{number_options(spec)}"
130
+ else:
131
+ head = f"{kind}{(number_options(spec) if kind == 'number' else '')}{(' (' + unit + ')' if unit else '')}"
132
+ instructions = str(spec.get("instructions") or "")
133
+ if not preserve_instructions:
134
+ instructions = " ".join(instructions.split())
135
+ return f"{name}: {head}." + (f" {instructions}" if instructions else "")
136
+
137
+
138
+ def number_options(spec: dict[str, Any]) -> str:
139
+ if spec.get("integer"):
140
+ return ", integer"
141
+ if spec.get("decimals") is not None:
142
+ return f", {int(spec['decimals'])} decimals"
143
+ return ""
144
+
145
+
146
+ def duration_unit(spec: dict[str, Any]) -> str:
147
+ return str(spec.get("unit") or "seconds")
148
+
149
+
150
+ def allowed_decimals(spec: dict[str, Any]) -> int | None:
151
+ if spec.get("integer"):
152
+ return 0
153
+ return None if spec.get("decimals") is None else int(spec["decimals"])
154
+
155
+
156
+ def parse_time(value: Any) -> tuple[int, int, int]:
157
+ if not isinstance(value, str):
158
+ raise ValueError(f"time must be a string, got {value!r}")
159
+ parsed = datetime.time.fromisoformat(value)
160
+ if parsed.microsecond or parsed.tzinfo is not None:
161
+ raise ValueError(f"time {value!r} must be HH:MM or HH:MM:SS")
162
+ return (parsed.hour, parsed.minute, parsed.second)
163
+
164
+
165
+ def format_time(hour: int, minute: int, second: int) -> str:
166
+ return f"{hour:02d}:{minute:02d}:{second:02d}"
167
+
168
+
169
+ def parse_datetime(value: Any) -> tuple[str, tuple[int, int, int]]:
170
+ if not isinstance(value, str) or "T" not in value:
171
+ raise ValueError(f"datetime must be YYYY-MM-DDTHH:MM[:SS], got {value!r}")
172
+ (day, clock) = value.split("T", 1)
173
+ return (datetime.date.fromisoformat(day).isoformat(), parse_time(clock))
174
+
175
+
176
+ def forecast_instructions(instructions: str, step: int, interval: str) -> str:
177
+ what = " ".join(str(instructions or "").split()).rstrip(".") or "the series"
178
+ unit = "step" if interval == "step" else interval
179
+ return f"Forecast {what} {step} {unit}{('s' if step > 1 else '')} after the last observation."
180
+
181
+
182
+ def expand_forecasts(
183
+ fields: dict[str, Any],
184
+ ) -> tuple[dict[str, Any], dict[str, list[str]]]:
185
+ expanded: dict[str, Any] = {}
186
+ groups: dict[str, list[str]] = {}
187
+ for name, spec in fields.items():
188
+ if not isinstance(spec, dict) or spec.get("type") != "forecast":
189
+ expanded[name] = spec
190
+ continue
191
+ horizon = spec.get("horizon")
192
+ if (
193
+ isinstance(horizon, bool)
194
+ or not isinstance(horizon, int)
195
+ or (not 1 <= horizon <= MAX_FORECAST_HORIZON)
196
+ ):
197
+ raise ValueError(
198
+ f"forecast {name} needs an integer horizon from 1 to {MAX_FORECAST_HORIZON}"
199
+ )
200
+ interval = spec.get("interval", "step")
201
+ if interval not in FORECAST_INTERVALS:
202
+ raise ValueError(f"forecast {name} has an unknown interval {interval!r}")
203
+ base = {
204
+ key: value
205
+ for (key, value) in spec.items()
206
+ if key not in ("type", "horizon", "interval", "instructions")
207
+ }
208
+ groups[name] = []
209
+ for step in range(1, horizon + 1):
210
+ step_name = f"{name}.{step}"
211
+ if step_name in fields or step_name in expanded:
212
+ raise ValueError(
213
+ f"forecast {name} step {step_name} collides with another field"
214
+ )
215
+ expanded[step_name] = {
216
+ "type": "estimate",
217
+ **base,
218
+ "instructions": forecast_instructions(
219
+ spec.get("instructions", ""), step, interval
220
+ ),
221
+ }
222
+ groups[name].append(step_name)
223
+ return (expanded, groups)
224
+
225
+
226
+ def to_unit(value: float, low: float, high: float, scale: str) -> float:
227
+ return min(1.0, max(0.0, raw_unit(value, low, high, scale)))
228
+
229
+
230
+ def raw_unit(value: float, low: float, high: float, scale: str) -> float:
231
+ if scale == "log":
232
+ if value <= 0:
233
+ return -1.0
234
+ return (math.log(value) - math.log(low)) / (math.log(high) - math.log(low))
235
+ return (value - low) / (high - low)
236
+
237
+
238
+ def from_unit(position: float, low: float, high: float, scale: str) -> float:
239
+ position = min(1.0, max(0.0, position))
240
+ if scale == "log":
241
+ value = math.exp(math.log(low) + position * (math.log(high) - math.log(low)))
242
+ else:
243
+ value = low + position * (high - low)
244
+ return min(high, max(low, value))
245
+
246
+
247
+ def resolution_in_unit(spec: dict[str, Any], resolution: float | None) -> float:
248
+ if not resolution:
249
+ return 0.0
250
+ (low, high, scale) = estimate_range(spec)
251
+ if scale == "log":
252
+ return math.log1p(resolution) / (math.log(high) - math.log(low))
253
+ return resolution / (high - low)
254
+
255
+
256
+ def is_date_estimate(spec: dict[str, Any]) -> bool:
257
+ return spec.get("type") == "estimate" and isinstance(spec.get("min"), str)
258
+
259
+
260
+ def date_granularity(spec: dict[str, Any]) -> str:
261
+ step = spec.get("step")
262
+ return step if step in ("month", "year") else "day"
263
+
264
+
265
+ def date_index(value: str, granularity: str = "day") -> float:
266
+ date = datetime.date.fromisoformat(value)
267
+ if granularity == "month":
268
+ return float(date.year * 12 + date.month - 1)
269
+ if granularity == "year":
270
+ return float(date.year)
271
+ return float(date.toordinal())
272
+
273
+
274
+ def index_date(index: float, granularity: str = "day") -> str:
275
+ whole = int(round(index))
276
+ if granularity == "month":
277
+ (year, month) = divmod(whole, 12)
278
+ return datetime.date(year, month + 1, 1).isoformat()
279
+ if granularity == "year":
280
+ return datetime.date(whole, 1, 1).isoformat()
281
+ return datetime.date.fromordinal(whole).isoformat()
282
+
283
+
284
+ def estimate_range(spec: dict[str, Any]) -> tuple[float, float, str]:
285
+ if is_date_estimate(spec):
286
+ granularity = date_granularity(spec)
287
+ return (
288
+ date_index(spec["min"], granularity),
289
+ date_index(spec["max"], granularity),
290
+ "linear",
291
+ )
292
+ return (float(spec["min"]), float(spec["max"]), spec.get("scale", "linear"))
293
+
294
+
295
+ def estimate_step(spec: dict[str, Any]) -> float:
296
+ if is_date_estimate(spec):
297
+ return (
298
+ 1.0 if date_granularity(spec) != "day" else float(spec.get("step") or 1.0)
299
+ )
300
+ return float(spec.get("step") or 0.0)
301
+
302
+
303
+ def estimate_number(spec: dict[str, Any], value: Any) -> float:
304
+ if is_date_estimate(spec):
305
+ return date_index(str(value), date_granularity(spec))
306
+ return float(value)
307
+
308
+
309
+ def estimate_value(spec: dict[str, Any], number: float) -> float | str:
310
+ if is_date_estimate(spec):
311
+ (low, high, _) = estimate_range(spec)
312
+ return index_date(min(max(number, low), high), date_granularity(spec))
313
+ return number
314
+
315
+
316
+ def grid_bounds(step: float, low: float, high: float) -> tuple[float, float]:
317
+ first = math.ceil(low / step - 1e-09) * step
318
+ last = math.floor(high / step + 1e-09) * step
319
+ return (float(f"{first:.12g}"), float(f"{last:.12g}"))
320
+
321
+
322
+ def snap(value: float, step: float, low: float, high: float) -> float:
323
+ (first, last) = grid_bounds(step, low, high)
324
+ return float(f"{min(last, max(first, round(value / step) * step)):.12g}")
325
+
326
+
327
+ def snap_quantile(value: float, step: float, low: float, high: float) -> float:
328
+ (first, last) = grid_bounds(step, low, high)
329
+ return float(
330
+ f"{min(last, max(first, math.ceil((value - step / 2) / step - 1e-09) * step)):.12g}"
331
+ )
332
+
333
+
334
+ def step_interval(spec: dict[str, Any], value: float) -> tuple[float, float]:
335
+ step = estimate_step(spec)
336
+ (low, high, _) = estimate_range(spec)
337
+ if step <= 0:
338
+ return (value, value)
339
+ return (max(low, value - step / 2), min(high, value + step / 2))
340
+
341
+
342
+ def _cuts_word(text: str, start: int, end: int) -> bool:
343
+
344
+ def joined(left: str, right: str) -> bool:
345
+ return left.isascii() and left.isalnum() and right.isascii() and right.isalnum()
346
+
347
+ return (
348
+ start > 0
349
+ and joined(text[start - 1], text[start])
350
+ or (end < len(text) and joined(text[end - 1], text[end]))
351
+ )
352
+
353
+
354
+ def _prefer_whole(
355
+ text: str, spans: list[tuple[int, int]], limit: int
356
+ ) -> list[tuple[int, int]]:
357
+ whole = [span for span in spans if not _cuts_word(text, *span)]
358
+ return (whole or spans)[:limit]
359
+
360
+
361
+ def find_spans(text: str, value: str, limit: int = 16) -> list[tuple[int, int]]:
362
+ value = value.strip()
363
+ if not value:
364
+ return []
365
+ scan = max(limit * 8, 64)
366
+ spans: list[tuple[int, int]] = []
367
+ start = text.find(value)
368
+ while start >= 0 and len(spans) < scan:
369
+ spans.append((start, start + len(value)))
370
+ start = text.find(value, start + 1)
371
+ if spans:
372
+ return _prefer_whole(text, spans, limit)
373
+ (lowered, target) = (text.lower(), value.lower())
374
+ if len(lowered) == len(text):
375
+ start = lowered.find(target)
376
+ while start >= 0 and len(spans) < scan:
377
+ spans.append((start, start + len(value)))
378
+ start = lowered.find(target, start + 1)
379
+ if spans:
380
+ return _prefer_whole(text, spans, limit)
381
+ pieces = value.split()
382
+ if not pieces:
383
+ return []
384
+ pattern = re.compile(
385
+ "\\s+".join((re.escape(piece) for piece in pieces)), re.IGNORECASE
386
+ )
387
+ spans = [
388
+ (match.start(), match.end())
389
+ for match in itertools.islice(pattern.finditer(text), scan)
390
+ ]
391
+ return _prefer_whole(text, spans, limit)
392
+
393
+
394
+ def validate_fields(fields: Any) -> None:
395
+ if not fields or not isinstance(fields, dict):
396
+ raise ValueError("record must declare at least one field")
397
+ for name, spec in fields.items():
398
+ if not isinstance(name, str) or not FIELD_NAME.match(name):
399
+ raise ValueError(f"invalid field name {name!r}")
400
+ kind = spec.get("type") if isinstance(spec, dict) else None
401
+ if isinstance(spec, dict) and "knowledge" in spec:
402
+ if not isinstance(spec["knowledge"], bool):
403
+ raise ValueError(f"field {name}: knowledge must be true or false")
404
+ if kind not in ("text", "number") and (
405
+ not (kind == "list" and spec.get("items") in ("text", "number"))
406
+ ):
407
+ raise ValueError(
408
+ f"field {name}: knowledge applies to text and number fields only"
409
+ )
410
+ if kind == "compute":
411
+ if spec.get("nullable", True) is not True or any(
412
+ (
413
+ key in spec
414
+ for key in (
415
+ "minimum",
416
+ "maximum",
417
+ "exclusiveMinimum",
418
+ "exclusiveMaximum",
419
+ "enum",
420
+ )
421
+ )
422
+ ):
423
+ raise ValueError(
424
+ f"compute {name} does not support AR grammar constraints"
425
+ )
426
+ kind = "number"
427
+ if kind not in FIELD_TYPES + ("boolean", "enum", "object"):
428
+ raise ValueError(f"field {name} has unknown type {kind!r}")
429
+ if "null_threshold" in spec:
430
+ threshold = spec["null_threshold"]
431
+ if kind in ("estimate", "list"):
432
+ raise ValueError(f"{kind} {name} does not take null_threshold")
433
+ if (
434
+ isinstance(threshold, bool)
435
+ or not isinstance(threshold, (int, float))
436
+ or (not 0 < threshold <= 1)
437
+ ):
438
+ raise ValueError(f"field {name} needs null_threshold in (0, 1]")
439
+ row_items = (
440
+ isinstance(spec.get("items"), dict)
441
+ and spec["items"].get("type") == "object"
442
+ )
443
+ if (
444
+ kind == "list"
445
+ and (not row_items)
446
+ and (spec.get("items") not in LIST_ITEM_TYPES)
447
+ ):
448
+ raise ValueError(f"list {name} needs items in {LIST_ITEM_TYPES}")
449
+ if kind == "duration" and duration_unit(spec) not in DURATION_UNITS:
450
+ raise ValueError(f"duration {name} needs a unit in {DURATION_UNITS}")
451
+ numeric = kind in ("number", "duration") or (
452
+ kind == "list" and spec.get("items") == "number"
453
+ )
454
+ if not numeric and ("integer" in spec or "decimals" in spec):
455
+ raise ValueError(
456
+ f"field {name}: integer and decimals apply to numbers and durations only"
457
+ )
458
+ if "integer" in spec and (not isinstance(spec["integer"], bool)):
459
+ raise ValueError(f"field {name}: integer must be true or false")
460
+ if "decimals" in spec:
461
+ decimals = spec["decimals"]
462
+ if (
463
+ isinstance(decimals, bool)
464
+ or not isinstance(decimals, int)
465
+ or (not 0 <= decimals <= MAX_DECIMALS)
466
+ ):
467
+ raise ValueError(
468
+ f"field {name}: decimals must be an integer from 0 to {MAX_DECIMALS}"
469
+ )
470
+ if spec.get("integer") and decimals:
471
+ raise ValueError(f"field {name}: an integer field has 0 decimals")
472
+ if kind == "estimate" and is_date_estimate(spec):
473
+ validate_date_range(name, spec)
474
+ elif kind == "estimate":
475
+ validate_number_range(name, spec)
476
+
477
+
478
+ def null_threshold(spec: dict[str, Any]) -> float:
479
+ return float(spec.get("null_threshold", DEFAULT_NULL_THRESHOLD))
480
+
481
+
482
+ def validate_number_range(name: str, spec: dict[str, Any]) -> None:
483
+ try:
484
+ (low, high) = (float(spec["min"]), float(spec["max"]))
485
+ step = None if spec.get("step") is None else float(spec["step"])
486
+ except (KeyError, TypeError, ValueError) as error:
487
+ raise ValueError(f"estimate {name} needs numeric min, max, and step") from error
488
+ if not (math.isfinite(low) and math.isfinite(high) and (low < high)) or spec.get(
489
+ "scale", "linear"
490
+ ) not in ("linear", "log"):
491
+ raise ValueError(f"field {name} has an invalid range")
492
+ if spec.get("scale") == "log" and low <= 0:
493
+ raise ValueError(f"log field {name} needs a positive minimum")
494
+ if step is not None and (
495
+ not math.isfinite(step)
496
+ or step <= 0
497
+ or (high - low) / step < 1
498
+ or ((high - low) / step > 1000000.0)
499
+ ):
500
+ raise ValueError(f"estimate {name} has an invalid step {spec['step']!r}")
501
+
502
+
503
+ def validate_reference_date(value: Any) -> None:
504
+ if value is None:
505
+ return
506
+ try:
507
+ datetime.date.fromisoformat(value)
508
+ except (TypeError, ValueError) as error:
509
+ raise ValueError(
510
+ f"reference_date must be an ISO date, got {value!r}"
511
+ ) from error
512
+
513
+
514
+ def validate_date_range(name: str, spec: dict[str, Any]) -> None:
515
+ try:
516
+ (low, high, _) = estimate_range(spec)
517
+ step = (
518
+ float(spec["step"])
519
+ if date_granularity(spec) == "day" and spec.get("step") is not None
520
+ else 1.0
521
+ )
522
+ except (KeyError, TypeError, ValueError) as error:
523
+ raise ValueError(
524
+ f"date estimate {name} needs ISO bounds and a step in days, 'month', or 'year'"
525
+ ) from error
526
+ if (
527
+ not isinstance(spec.get("max"), str)
528
+ or spec.get("scale", "linear") != "linear"
529
+ or (not low < high)
530
+ ):
531
+ raise ValueError(f"date estimate {name} has an invalid range")
532
+ if not step.is_integer() or step < 1 or (high - low) / step < 1:
533
+ raise ValueError(f"date estimate {name} has an invalid step {spec['step']!r}")
clairic_runtime/settings.py ADDED
@@ -0,0 +1,29 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Configuration for a local Clairic model instance."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass
6
+
7
+ DEFAULT_MAX_LENGTH = 65_273
8
+ MAX_PASS_TOKENS = 65_536
9
+
10
+
11
+ @dataclass(frozen=True, slots=True)
12
+ class RuntimeSettings:
13
+ model_path: str
14
+ model_id: str = "clairic-flash"
15
+ max_length: int = DEFAULT_MAX_LENGTH
16
+ max_concurrency: int = 1
17
+ version: str = "1"
18
+ model_aliases: tuple[str, ...] = ()
19
+
20
+ def __post_init__(self) -> None:
21
+ if (
22
+ type(self.max_length) is not int
23
+ or not 0 < self.max_length <= DEFAULT_MAX_LENGTH
24
+ ):
25
+ raise ValueError(
26
+ f"max_length must be an integer from 1 to {DEFAULT_MAX_LENGTH}"
27
+ )
28
+ if type(self.max_concurrency) is not int or self.max_concurrency != 1:
29
+ raise ValueError("max_concurrency must be 1")
clairic_runtime/source_dates.py ADDED
@@ -0,0 +1,320 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ import json
3
+ import re
4
+ from collections.abc import Iterable
5
+ from dataclasses import asdict, dataclass
6
+ from datetime import date
7
+ from typing import Any
8
+
9
+ VERSION = "source-date-candidates-v1"
10
+ INSTRUCTION = "Return the complete calendar date for this requested field as YYYY-MM-DD. Choose only a date explicitly printed for the requested role in the supplied source. Use the full day, month, and year, including legal ordinal date wording. Do not derive an unprinted date from a duration, term length, another date, or general knowledge. Return null if the requested role has no printed date. A date for another role does not fill this field."
11
+ _MONTHS = {
12
+ "jan": 1,
13
+ "january": 1,
14
+ "feb": 2,
15
+ "february": 2,
16
+ "mar": 3,
17
+ "march": 3,
18
+ "apr": 4,
19
+ "april": 4,
20
+ "may": 5,
21
+ "jun": 6,
22
+ "june": 6,
23
+ "jul": 7,
24
+ "july": 7,
25
+ "aug": 8,
26
+ "august": 8,
27
+ "sep": 9,
28
+ "sept": 9,
29
+ "september": 9,
30
+ "oct": 10,
31
+ "october": 10,
32
+ "nov": 11,
33
+ "november": 11,
34
+ "dec": 12,
35
+ "december": 12,
36
+ }
37
+ _MONTH = "(?:" + "|".join(sorted(_MONTHS, key=len, reverse=True)) + ")\\.?"
38
+ _DMY = re.compile(
39
+ "(?<!\\w)(?:the\\s+)?(?P<day>\\d{1,2})(?P<ordinal>st|nd|rd|th)?\\s+(?:(?:day\\s+)?of\\s+)?(?P<month>"
40
+ + _MONTH
41
+ + "),?\\s+(?P<year>\\d{4})(?!\\w)",
42
+ re.IGNORECASE,
43
+ )
44
+ _MDY = re.compile(
45
+ "(?<!\\w)(?P<month>"
46
+ + _MONTH
47
+ + ")\\s+(?:the\\s+)?(?P<day>\\d{1,2})(?P<ordinal>st|nd|rd|th)?,?\\s+(?P<year>\\d{4})(?!\\w)",
48
+ re.IGNORECASE,
49
+ )
50
+ _YMD = re.compile(
51
+ "(?<![\\w./-])(?P<year>\\d{4})(?P<sep>[-/.])(?P<month>\\d{1,2})(?P=sep)(?P<day>\\d{1,2})(?!(?:[\\w/-]|\\.\\w))"
52
+ )
53
+ _NUMERIC = re.compile(
54
+ "(?<![\\w./-])(?P<first>\\d{1,2})(?P<sep>[-/.])(?P<second>\\d{1,2})(?P=sep)(?P<year>\\d{4})(?!(?:[\\w/-]|\\.\\w))"
55
+ )
56
+ _DERIVED = re.compile(
57
+ "\\b(?:calculat\\w*|comput\\w*|deriv\\w*|infer\\w*|after|before|ago|next|previous|following|prior|add|subtract|plus|minus|earlier|later|offset|duration|anniversar\\w*|turns?)\\b|\\b(?:first|last)\\s+day\\s+of\\b|\\bnet\\s*\\d+\\b",
58
+ re.IGNORECASE,
59
+ )
60
+ _RELATIVE = re.compile(
61
+ "\\b(?:today|tomorrow|yesterday|now)\\b|\\bcurrent\\s+(?:calendar\\s+)?date\\b|\\bbusiness\\s+days?\\b|\\b(?:days?|weeks?|months?|years?)\\s+from\\b|\\b(?:this|last)\\s+(?:week|month|year)\\b|\\b(?:in|within)\\s+(?:\\d+|[a-z]+(?:[\\s-]+[a-z]+){0,2})\\s+(?:business\\s+)?(?:days?|weeks?|months?|years?)\\b",
62
+ re.IGNORECASE,
63
+ )
64
+ _READING_INTENT = re.compile(
65
+ "\\b(?:dates?|dated|calendar\\s+day|printed|explicit(?:ly)?|stated|shown|recorded|written|literal|verbatim)\\b",
66
+ re.IGNORECASE,
67
+ )
68
+ _EXPRESSION_REQUEST = re.compile(
69
+ "\\b(?:value\\s+(?:of|for)|evaluat\\w*|expression|formula|variable|constant|function|code)\\b",
70
+ re.IGNORECASE,
71
+ )
72
+ _CALENDAR_EXPRESSION = re.compile(
73
+ "\\b(?:add|sub(?:tract)?|plus|minus|offset|shift|set)[_]?(?:business[_]?)?(?:days?|weeks?|months?|years?)\\s*\\(|\\b(?:date_?(?:add|sub|diff)|timedelta|relativedelta|DateOffset|EDATE|EOMONTH|WORKDAY)\\s*\\(|\\.\\s*(?:set(?:UTC)?(?:Date|Month|FullYear)|add|subtract)\\s*\\(|\\binterval\\s+(?:['\\\"]|\\d)|\\b(?:date|datetime)(?:\\s*\\.\\s*\\w+)?\\s*\\([^;\\n]*\\)\\s*[+-]",
74
+ re.IGNORECASE,
75
+ )
76
+
77
+
78
+ def eligible(spec: dict[str, Any]) -> bool:
79
+ instructions = spec.get("instructions", "")
80
+ return (
81
+ spec.get("type") == "date"
82
+ and (not spec.get("knowledge"))
83
+ and ("source_only" not in spec)
84
+ and ("null_threshold" not in spec)
85
+ and isinstance(instructions, str)
86
+ and bool(_READING_INTENT.search(instructions))
87
+ and (
88
+ not (
89
+ _DERIVED.search(instructions)
90
+ or _RELATIVE.search(instructions)
91
+ or _EXPRESSION_REQUEST.search(instructions)
92
+ )
93
+ )
94
+ )
95
+
96
+
97
+ @dataclass(frozen=True)
98
+ class Candidate:
99
+ start: int
100
+ end: int
101
+ printed: str
102
+ iso_values: tuple[str, ...]
103
+ notation: str
104
+
105
+ @property
106
+ def ambiguous(self) -> bool:
107
+ return len(self.iso_values) != 1
108
+
109
+
110
+ def _iso(year: str | int, month: str | int, day: str | int) -> str | None:
111
+ try:
112
+ return date(int(year), int(month), int(day)).isoformat()
113
+ except ValueError:
114
+ return None
115
+
116
+
117
+ def _ordinal_valid(day: int, suffix: str | None) -> bool:
118
+ if not suffix:
119
+ return True
120
+ expected = (
121
+ "th"
122
+ if 11 <= day % 100 <= 13
123
+ else {1: "st", 2: "nd", 3: "rd"}.get(day % 10, "th")
124
+ )
125
+ return suffix.casefold() == expected
126
+
127
+
128
+ def candidates(
129
+ source: str, *, numeric_order: str | None = None
130
+ ) -> tuple[Candidate, ...]:
131
+ if numeric_order not in (None, "mdy", "dmy"):
132
+ raise ValueError("Numeric date order must be explicitly mdy or dmy")
133
+ result = []
134
+ for pattern in (_DMY, _MDY):
135
+ for match in pattern.finditer(source):
136
+ if not _ordinal_valid(int(match["day"]), match["ordinal"]):
137
+ continue
138
+ value = _iso(
139
+ match["year"],
140
+ _MONTHS[match["month"].rstrip(".").casefold()],
141
+ match["day"],
142
+ )
143
+ if value:
144
+ result.append(
145
+ Candidate(
146
+ match.start(), match.end(), match[0], (value,), "named_month"
147
+ )
148
+ )
149
+ for match in _YMD.finditer(source):
150
+ value = _iso(match["year"], match["month"], match["day"])
151
+ if value:
152
+ result.append(
153
+ Candidate(match.start(), match.end(), match[0], (value,), "year_first")
154
+ )
155
+ for match in _NUMERIC.finditer(source):
156
+ (first, second) = (int(match["first"]), int(match["second"]))
157
+ readings = set()
158
+ orders = (numeric_order,) if numeric_order else ("mdy", "dmy")
159
+ for order in orders:
160
+ value = _iso(
161
+ match["year"],
162
+ first if order == "mdy" else second,
163
+ second if order == "mdy" else first,
164
+ )
165
+ if value:
166
+ readings.add(value)
167
+ if readings:
168
+ result.append(
169
+ Candidate(
170
+ match.start(),
171
+ match.end(),
172
+ match[0],
173
+ tuple(sorted(readings)),
174
+ "numeric",
175
+ )
176
+ )
177
+ return tuple(sorted(set(result), key=lambda item: (item.start, -item.end)))
178
+
179
+
180
+ class DateSource:
181
+ def __init__(self, source: str, *, numeric_order: str | None = None) -> None:
182
+ self.text = source
183
+ self.candidates = candidates(source, numeric_order=numeric_order)
184
+ self.ambiguous = tuple((item for item in self.candidates if item.ambiguous))
185
+ self.support: dict[str, list[Candidate]] = {}
186
+ for item in self.candidates:
187
+ if not item.ambiguous:
188
+ self.support.setdefault(item.iso_values[0], []).append(item)
189
+ self.values = tuple(self.support)
190
+
191
+ def constraint(self, *, nullable: bool = True) -> dict[str, str]:
192
+ literals = [json.dumps(value) for value in self.values]
193
+ if nullable:
194
+ literals.append("null")
195
+ if not literals:
196
+ raise ValueError(
197
+ "No unambiguous source date satisfies a nonnullable date contract"
198
+ )
199
+ return {
200
+ "ebnf": "root ::= " + " | ".join((json.dumps(value) for value in literals))
201
+ }
202
+
203
+ def span(self, value: object) -> tuple[bool, list[int] | None]:
204
+ matches = self.support.get(value, ()) if isinstance(value, str) else ()
205
+ intervals = {(item.start, item.end) for item in matches}
206
+ return (
207
+ bool(intervals),
208
+ list(next(iter(intervals))) if len(intervals) == 1 else None,
209
+ )
210
+
211
+ def evidence(self, value: str) -> list[dict[str, Any]]:
212
+ return [asdict(item) for item in self.support.get(value, ())]
213
+
214
+ def annotate_predictions(
215
+ self, predictions: dict[str, dict[str, Any]], names: Iterable[str]
216
+ ) -> dict[str, dict[str, Any]]:
217
+ result = dict(predictions)
218
+ for name in names:
219
+ if name not in predictions:
220
+ continue
221
+ answer = dict(predictions[name])
222
+ result[name] = answer
223
+ answer.update(
224
+ date_decoder=VERSION, score_representation="native_json_iso_date_wire"
225
+ )
226
+ if (
227
+ not answer.get("valid")
228
+ or not answer.get("complete")
229
+ or answer.get("value") is None
230
+ ):
231
+ continue
232
+ (found, span) = self.span(answer["value"])
233
+ if not found:
234
+ answer.update(
235
+ valid=False,
236
+ value=None,
237
+ span=None,
238
+ failure_reason="not_a_printed_date_candidate",
239
+ )
240
+ continue
241
+ answer.update(
242
+ grounding_method="printed_date_candidates_source",
243
+ span=span,
244
+ source_date_candidates=self.evidence(answer["value"]),
245
+ )
246
+ answer.pop("span_method", None)
247
+ if span is not None:
248
+ answer.update(
249
+ span_method="unique_normalized_printed_date_match",
250
+ printed_value=self.text[slice(*span)],
251
+ )
252
+ return result
253
+
254
+ def merge_predictions(
255
+ self,
256
+ original: dict[str, dict[str, Any]],
257
+ alternatives: dict[str, dict[str, Any]],
258
+ names: Iterable[str],
259
+ ) -> dict[str, dict[str, Any]]:
260
+ result = original
261
+ if not self.automatic_route_safe():
262
+ return result
263
+ for name in names:
264
+ previous = original.get(name)
265
+ answer = alternatives.get(name)
266
+ if not isinstance(previous, dict) or not isinstance(answer, dict):
267
+ continue
268
+ if previous.get("type") not in (None, "date"):
269
+ continue
270
+ previous_value = previous.get("value")
271
+ if not isinstance(previous_value, str) or previous_value in self.support:
272
+ continue
273
+ value = answer.get("value")
274
+ if (
275
+ answer.get("valid") is not True
276
+ or answer.get("complete") is not True
277
+ or (not isinstance(value, str))
278
+ or (value not in self.support)
279
+ or (answer.get("date_decoder") != VERSION)
280
+ or (answer.get("grounding_method") != "printed_date_candidates_source")
281
+ or (answer.get("span") != self.span(value)[1])
282
+ or (not isinstance(answer.get("raw"), str))
283
+ ):
284
+ continue
285
+ try:
286
+ if (
287
+ date.fromisoformat(value).isoformat() != value
288
+ or json.loads(answer["raw"]) != value
289
+ ):
290
+ continue
291
+ except (ValueError, TypeError):
292
+ continue
293
+ if value == previous.get("value"):
294
+ continue
295
+ if result is original:
296
+ result = dict(original)
297
+ result[name] = {**answer, "type": "date"}
298
+ return result
299
+
300
+ def automatic_route_safe(self) -> bool:
301
+ return (
302
+ bool(self.values)
303
+ and (not self.ambiguous)
304
+ and (not _CALENDAR_EXPRESSION.search(self.text))
305
+ )
306
+
307
+ def allows(self, spec: dict[str, Any]) -> bool:
308
+ return eligible(spec) and self.automatic_route_safe()
309
+
310
+ def report(self) -> dict[str, Any]:
311
+ return {
312
+ "version": VERSION,
313
+ "values": self.values,
314
+ "candidates": [asdict(item) for item in self.candidates],
315
+ "ambiguous_candidates": [asdict(item) for item in self.ambiguous],
316
+ "calendar_expression_in_source": bool(
317
+ _CALENDAR_EXPRESSION.search(self.text)
318
+ ),
319
+ "automatic_route_safe": self.automatic_route_safe(),
320
+ }
clairic_runtime/source_rows.py ADDED
@@ -0,0 +1,159 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ import csv
3
+ import io
4
+ import re
5
+ from collections.abc import Callable
6
+ from html.parser import HTMLParser
7
+ from typing import Any
8
+
9
+ _ONE_PER_ROW = re.compile(
10
+ "\\bone\\s+(?:[\\w-]+\\s+){0,5}per\\s+(?:[\\w-]+\\s+){0,5}row\\b", re.IGNORECASE
11
+ )
12
+
13
+
14
+ class _Table(HTMLParser):
15
+ def __init__(self) -> None:
16
+ super().__init__(convert_charrefs=False)
17
+ self.tables = self.depth = 0
18
+ self.rows: list[set[str]] = []
19
+ self.closed = False
20
+ self.row_header = False
21
+ self.in_cell = False
22
+ self.ambiguous = False
23
+
24
+ def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
25
+ if self.in_cell and tag in ("br", "div", "p", "ul", "ol", "li", "table"):
26
+ self.ambiguous = True
27
+ if tag == "table":
28
+ self.tables += 1
29
+ self.depth += 1
30
+ if self.depth == 1:
31
+ if tag == "tr":
32
+ self.rows.append(set())
33
+ elif tag in ("td", "th") and self.rows:
34
+ self.in_cell = True
35
+ if any(
36
+ (
37
+ key in ("rowspan", "colspan") and value != "1"
38
+ for (key, value) in attrs
39
+ )
40
+ ):
41
+ self.ambiguous = True
42
+ self.rows[-1].add(tag)
43
+ if len(self.rows) == 1 and (
44
+ dict(attrs).get("scope") or ""
45
+ ).casefold() in ("row", "rowgroup"):
46
+ self.row_header = True
47
+
48
+ def handle_endtag(self, tag: str) -> None:
49
+ if tag in ("td", "th"):
50
+ self.in_cell = False
51
+ if tag == "table":
52
+ self.depth -= 1
53
+ self.closed = self.depth == 0
54
+
55
+ def handle_data(self, data: str) -> None:
56
+ if (
57
+ self.in_cell
58
+ and len([line for line in data.splitlines() if line.strip()]) > 1
59
+ ):
60
+ self.ambiguous = True
61
+
62
+
63
+ def table_rows(source: str) -> int | None:
64
+ if re.search("<table(?:\\s|>)", source, re.IGNORECASE):
65
+ parser = _Table()
66
+ try:
67
+ parser.feed(source)
68
+ parser.close()
69
+ except (ValueError, AssertionError):
70
+ return None
71
+ if (
72
+ parser.tables != 1
73
+ or not parser.closed
74
+ or parser.depth != 0
75
+ or (not parser.rows)
76
+ or (parser.rows[0] != {"th"})
77
+ or parser.row_header
78
+ or parser.ambiguous
79
+ ):
80
+ return None
81
+ return len(parser.rows) - 1
82
+ lines = source.splitlines()
83
+ if len(lines) < 2:
84
+ return None
85
+ for delimiter in (",", "\t", ";", "|"):
86
+ if delimiter not in lines[0]:
87
+ continue
88
+ try:
89
+ rows = list(
90
+ csv.reader(io.StringIO(source), delimiter=delimiter, strict=True)
91
+ )
92
+ except csv.Error:
93
+ continue
94
+ if (
95
+ not rows
96
+ or len(rows[0]) < 2
97
+ or any((not row or len(row) != len(rows[0]) for row in rows))
98
+ or any((not cell.strip() or re.search("\\d", cell) for cell in rows[0]))
99
+ or (not any((re.search("\\d", cell) for row in rows[1:] for cell in row)))
100
+ ):
101
+ continue
102
+ return len(rows) - 1
103
+ return None
104
+
105
+
106
+ def list_bounds(
107
+ source: str, fields: dict[str, dict[str, Any]], *, has_images: bool = False
108
+ ) -> dict[str, int]:
109
+ if has_images:
110
+ return {}
111
+ parents = {}
112
+ for name, spec in fields.items():
113
+ instructions = spec.get("instructions", "")
114
+ if (
115
+ spec.get("type") == "list"
116
+ and spec.get("items") in ("text", "number")
117
+ and (not spec.get("knowledge"))
118
+ and _ONE_PER_ROW.search(instructions)
119
+ and (
120
+ not re.search(
121
+ "\\b(?:not|never|multiple|two|three)\\b|don't",
122
+ instructions,
123
+ re.IGNORECASE,
124
+ )
125
+ )
126
+ ):
127
+ parents[name] = spec
128
+ count = table_rows(source) if parents else None
129
+ return {name: count for name in parents} if count is not None else {}
130
+
131
+
132
+ def bounded_predictions(
133
+ predictions: dict[str, dict[str, Any]],
134
+ fields: dict[str, dict[str, Any]],
135
+ bounds: dict[str, int],
136
+ item_name: Callable[[str, int], str],
137
+ ) -> dict[str, dict[str, Any]]:
138
+ if not bounds:
139
+ return predictions
140
+ result = dict(predictions)
141
+ for parent, count in bounds.items():
142
+ name = item_name(parent, count + 1)
143
+ if name not in fields or name not in result:
144
+ continue
145
+ previous = result[name]
146
+ if previous.get("value") is None and previous.get("valid", True):
147
+ continue
148
+ result[name] = {
149
+ **previous,
150
+ "value": None,
151
+ "valid": True,
152
+ "complete": True,
153
+ "span": None,
154
+ "confidence": 1.0,
155
+ "log_probability": 0.0,
156
+ "confidence_method": "source_structure",
157
+ "grounding_method": "source_row_bound",
158
+ }
159
+ return result
clairic_runtime/source_sums.py ADDED
@@ -0,0 +1,334 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ import hashlib
3
+ import json
4
+ import re
5
+ import unicodedata
6
+ from collections import defaultdict
7
+ from collections.abc import Iterable, Sequence
8
+ from copy import deepcopy
9
+ from decimal import Decimal, localcontext
10
+ from typing import Any
11
+ from . import ar, grounding
12
+
13
+ MAX_SOURCE_CANDIDATES = 512
14
+ MAX_OPERANDS = 32
15
+ _SUM = re.compile("^\\s*(?:the\\s+)?sum\\s+of\\b", re.IGNORECASE)
16
+ _PROTECTED = re.compile(
17
+ "\\b(?:not|never|no|without|don't|avoid|unless|if|copy|copies|copied|printed|verbatim|literal|quoted|label|named|called)\\b",
18
+ re.IGNORECASE,
19
+ )
20
+ _CURRENCY_CODES = frozenset(
21
+ {
22
+ "USD",
23
+ "EUR",
24
+ "GBP",
25
+ "JPY",
26
+ "CNY",
27
+ "INR",
28
+ "AUD",
29
+ "CAD",
30
+ "CHF",
31
+ "HKD",
32
+ "NZD",
33
+ "SGD",
34
+ "SEK",
35
+ "NOK",
36
+ "DKK",
37
+ "KRW",
38
+ "BRL",
39
+ "MXN",
40
+ "ZAR",
41
+ }
42
+ )
43
+ _AMOUNT_PREFIX = re.compile(
44
+ "(?P<open>\\()?[ \\t]*(?P<before>[+-]?)[ \\t]*(?P<currency>\\$|[A-Z]{3})?[ \\t]*(?P<after>[+-]?)[ \\t]*$"
45
+ )
46
+ INSTRUCTION = "Select the printed numeric source occurrences that are operands of the requested sum. Follow the field instructions to identify the requested entities, rows, scope and inclusions. Return exactly one compact JSON array of candidate IDs in their source order. Include every matching occurrence once, even when different occurrences have equal amounts. Select the final amount for each requested record; do not also select its component amounts when those components are already included in that final amount. Exclude unrelated amounts, dates, identifiers and aggregate totals outside the requested scope. Do not calculate the sum, invent an amount, deduplicate equal source occurrences or reuse an ID. The original document is reproduced verbatim below; candidate contexts are source excerpts. Return null if no requested operands are present or the operand scope cannot be determined. A printed zero or negative amount is present. End immediately after the array or null."
47
+
48
+
49
+ def canonical(value: object) -> bytes:
50
+ return json.dumps(
51
+ value,
52
+ sort_keys=True,
53
+ ensure_ascii=False,
54
+ separators=(",", ":"),
55
+ allow_nan=False,
56
+ ).encode()
57
+
58
+
59
+ def eligible(record: dict[str, Any], name: str, *, has_media: bool = False) -> bool:
60
+ spec = record["fields"][name]
61
+ annotation = (
62
+ record.get("_meta", {})
63
+ .get("extraction_contract", {})
64
+ .get("fields", {})
65
+ .get(name, {})
66
+ )
67
+ instructions = spec.get("instructions", "")
68
+ return (
69
+ not has_media
70
+ and (not record.get("images"))
71
+ and (not record.get("documents"))
72
+ and (not record.get("_media_payload"))
73
+ and (spec.get("type") == "number")
74
+ and (not spec.get("source_only"))
75
+ and (not spec.get("knowledge"))
76
+ and (not spec.get("_physical_row_scope"))
77
+ and (not annotation.get("parent"))
78
+ and (name not in record.get("_source_row_gates", ()))
79
+ and (not grounding.state_only(spec))
80
+ and (not grounding.document_only(spec))
81
+ and isinstance(instructions, str)
82
+ and bool(_SUM.search(instructions))
83
+ and (not _PROTECTED.search(instructions))
84
+ )
85
+
86
+
87
+ def _signed_readings(
88
+ source: str, start: int, end: int, values: Iterable[Decimal]
89
+ ) -> set[Decimal]:
90
+ from .model import NUMERAL_RUN
91
+
92
+ numeral = NUMERAL_RUN.search(source, start, end)
93
+ if numeral is None:
94
+ return set()
95
+ left = numeral.start()
96
+ prefix_start = left
97
+ while prefix_start > max(0, left - 64):
98
+ char = source[prefix_start - 1]
99
+ if char in " \t(+-−" or unicodedata.category(char) == "Sc":
100
+ prefix_start -= 1
101
+ elif source[
102
+ max(0, prefix_start - 3) : prefix_start
103
+ ].upper() in _CURRENCY_CODES and (
104
+ prefix_start == 3 or not source[prefix_start - 4].isalnum()
105
+ ):
106
+ prefix_start -= 3
107
+ else:
108
+ break
109
+ prefix = source[prefix_start:left]
110
+ first = prefix_start + len(prefix) - len(prefix.lstrip())
111
+ if prefix.strip() in ("-", "−") and re.match(
112
+ "\\d{4}-\\d{2}-\\d{2}(?!\\d)", source[left:]
113
+ ):
114
+ return {value.copy_abs() for value in values}
115
+ if (
116
+ first < left
117
+ and source[first] in "+-−"
118
+ and first
119
+ and source[first - 1].isalnum()
120
+ ):
121
+ if prefix.strip() in ("+", "-", "−"):
122
+ return {value.copy_abs() for value in values}
123
+ return set()
124
+ normalized = "".join(
125
+ (
126
+ "$"
127
+ if unicodedata.category(char) == "Sc"
128
+ else "-"
129
+ if char == "−"
130
+ else char.upper()
131
+ for char in prefix
132
+ )
133
+ ).lstrip()
134
+ match = _AMOUNT_PREFIX.fullmatch(normalized)
135
+ if match is None or (match["before"] and match["after"]):
136
+ return set()
137
+ explicit_sign = match["before"] or match["after"]
138
+ negative = explicit_sign == "-"
139
+ if match["open"]:
140
+ after = source[end:] if source[end - 1 : end] != ")" else source[end - 1 :]
141
+ closing = re.match("[ \\t]*\\)", after)
142
+ if closing is None or explicit_sign:
143
+ return set()
144
+ rest = after[closing.end() :].split("\n", 1)[0].strip(" \t.;,")
145
+ negative = bool(
146
+ match["currency"] or any((c in numeral[0] for c in ".,")) or (not rest)
147
+ )
148
+ return {
149
+ value.copy_abs().copy_negate() if negative else value.copy_abs()
150
+ for value in values
151
+ }
152
+
153
+
154
+ def _source_candidates(source: str) -> list[dict[str, Any]] | None:
155
+ readings = defaultdict(set)
156
+ for value, spans in grounding.numbers(source).items():
157
+ for span in spans:
158
+ readings[tuple(span)].add(value)
159
+ ordered = sorted(readings)
160
+ if not ordered or len(ordered) > MAX_SOURCE_CANDIDATES:
161
+ return None
162
+ previous_end = 0
163
+ candidates = []
164
+ for index, (start, end) in enumerate(ordered):
165
+ if start < previous_end or not 0 <= start < end <= len(source):
166
+ return None
167
+ previous_end = end
168
+ line_start = source.rfind("\n", 0, start) + 1
169
+ line_end = source.find("\n", end)
170
+ if line_end < 0:
171
+ line_end = len(source)
172
+ (context_start, context_end) = (
173
+ max(line_start, start - 64),
174
+ min(line_end, end + 64),
175
+ )
176
+ values = _signed_readings(source, start, end, readings[start, end])
177
+ candidates.append(
178
+ {
179
+ "id": f"N{index}",
180
+ "span": [start, end],
181
+ "printed": source[start:end],
182
+ "decimal": str(next(iter(values))) if len(values) == 1 else None,
183
+ "decimal_options": sorted((str(value) for value in values)),
184
+ "context": source[context_start:context_end],
185
+ }
186
+ )
187
+ return candidates
188
+
189
+
190
+ def _grammar(candidates: Sequence[dict[str, Any]]) -> str:
191
+ lines = ['root ::= "null" | "[" p0 "]"']
192
+ for index, item in enumerate(candidates):
193
+ literal = json.dumps(json.dumps(item["id"]))
194
+ rule = f"p{index} ::= {literal}"
195
+ if index + 1 < len(candidates):
196
+ rule += f' | {literal} "," p{index + 1} | p{index + 1}'
197
+ lines.append(rule)
198
+ return "\n".join(lines)
199
+
200
+
201
+ def prepare_task(
202
+ record: dict[str, Any], field_name: str, *, has_media: bool = False
203
+ ) -> dict[str, Any] | None:
204
+ if not eligible(record, field_name, has_media=has_media):
205
+ return None
206
+ source = record["input"]
207
+ candidates = _source_candidates(source)
208
+ if not candidates:
209
+ return None
210
+ spec = deepcopy(record["fields"][field_name])
211
+ displayed = [
212
+ {"id": item["id"], "printed": item["printed"], "context": item["context"]}
213
+ for item in candidates
214
+ ]
215
+ schema = {
216
+ "anyOf": [
217
+ {"type": "null"},
218
+ {
219
+ "type": "array",
220
+ "minItems": 1,
221
+ "maxItems": MAX_OPERANDS,
222
+ "uniqueItems": True,
223
+ "items": {
224
+ "type": "string",
225
+ "enum": [item["id"] for item in candidates],
226
+ },
227
+ },
228
+ ]
229
+ }
230
+ prompt = (
231
+ INSTRUCTION
232
+ + "\nField: "
233
+ + field_name
234
+ + "\nField instructions: "
235
+ + spec.get("instructions", "")
236
+ + "\nCandidates in source order: "
237
+ + json.dumps(displayed, ensure_ascii=False, separators=(",", ":"))
238
+ + "\n\nOriginal document:\n"
239
+ + source
240
+ )
241
+ return {
242
+ "version": 2,
243
+ "kind": "source-occurrence-sum-v2",
244
+ "field": field_name,
245
+ "input_text": source,
246
+ "prompt": prompt,
247
+ "grammar": {"ebnf": _grammar(candidates)},
248
+ "json_schema": schema,
249
+ "candidates": candidates,
250
+ "field_spec": spec,
251
+ "max_operands": MAX_OPERANDS,
252
+ "source_sha256": hashlib.sha256(source.encode()).hexdigest(),
253
+ "field_spec_sha256": hashlib.sha256(canonical(spec)).hexdigest(),
254
+ "semantic_completeness_proven_by_grounding": False,
255
+ }
256
+
257
+
258
+ def validate_result(
259
+ task: dict[str, Any], raw_json: str, *, complete: bool = True
260
+ ) -> dict[str, Any]:
261
+ result: dict[str, Any] = {
262
+ "valid": False,
263
+ "value": None,
264
+ "operands": [],
265
+ "decimal_sum": None,
266
+ "operand_count": 0,
267
+ "error": None,
268
+ "semantic_completeness_proven_by_grounding": False,
269
+ }
270
+ try:
271
+ if not complete:
272
+ raise ValueError("incomplete_generation")
273
+ source = task["input_text"]
274
+ if hashlib.sha256(source.encode()).hexdigest() != task["source_sha256"]:
275
+ raise ValueError("source_changed")
276
+ if (
277
+ hashlib.sha256(canonical(task["field_spec"])).hexdigest()
278
+ != task["field_spec_sha256"]
279
+ ):
280
+ raise ValueError("field_spec_changed")
281
+ ids = json.loads(
282
+ raw_json,
283
+ parse_constant=lambda _: (_ for _ in ()).throw(
284
+ ValueError("nonfinite_json")
285
+ ),
286
+ )
287
+ if ids is None:
288
+ from jsonschema import Draft202012Validator
289
+
290
+ Draft202012Validator(ar.schema(task["field_spec"])).validate(None)
291
+ result.update(valid=True, error=None)
292
+ return result
293
+ if not isinstance(ids, list) or not ids or len(ids) > task["max_operands"]:
294
+ raise ValueError("invalid_operand_count")
295
+ if any((not isinstance(identifier, str) for identifier in ids)):
296
+ raise ValueError("operand_id_not_string")
297
+ if len(set(ids)) != len(ids):
298
+ raise ValueError("reused_source_occurrence")
299
+ source_candidates = _source_candidates(source)
300
+ if source_candidates != task["candidates"]:
301
+ raise ValueError("source_candidate_mapping_changed")
302
+ indexed = {
303
+ item["id"]: (index, item) for (index, item) in enumerate(source_candidates)
304
+ }
305
+ if any((identifier not in indexed for identifier in ids)):
306
+ raise ValueError("unknown_source_occurrence")
307
+ indices = [indexed[identifier][0] for identifier in ids]
308
+ if indices != sorted(indices):
309
+ raise ValueError("source_order_changed")
310
+ operands = [deepcopy(indexed[identifier][1]) for identifier in ids]
311
+ if any((item["decimal"] is None for item in operands)):
312
+ raise ValueError("ambiguous_operand_spelling")
313
+ amounts = [Decimal(item["decimal"]) for item in operands]
314
+ highest = max((amount.adjusted() for amount in amounts))
315
+ lowest: int = min((amount.as_tuple().exponent for amount in amounts))
316
+ with localcontext() as context:
317
+ context.prec = max(
318
+ context.prec, highest - lowest + len(str(len(amounts))) + 3
319
+ )
320
+ total = sum(amounts, Decimal(0))
321
+ value = ar.normalize_number(total, task["field_spec"])
322
+ from jsonschema import Draft202012Validator
323
+
324
+ Draft202012Validator(ar.schema(task["field_spec"])).validate(value)
325
+ result.update(
326
+ valid=True,
327
+ value=value,
328
+ operands=operands,
329
+ decimal_sum=str(total),
330
+ operand_count=len(operands),
331
+ )
332
+ except Exception as error:
333
+ result["error"] = str(error) or type(error).__name__
334
+ return result
clairic_runtime/table_rows.py ADDED
@@ -0,0 +1,541 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ import csv
3
+ import json
4
+ import math
5
+ import re
6
+ from collections.abc import Mapping, Sequence
7
+ from typing import Any
8
+ from jsonschema import Draft202012Validator, ValidationError
9
+ from . import ar, html_rows, printed_numbers
10
+
11
+ LOCAL_SCOPE_INPUT = (
12
+ "The row to classify is provided in the requested field instructions."
13
+ )
14
+
15
+
16
+ def _column(value: str) -> str:
17
+ return re.sub("[\\W_]+", "", value.casefold())
18
+
19
+
20
+ def _header_keys(cells: Sequence[str], names: Mapping[str, str]) -> list[str]:
21
+ keys = [_column(cell) for cell in cells]
22
+ return [
23
+ "quantity"
24
+ if key == "qty" and "qty" not in names and ("quantity" in names)
25
+ else key
26
+ for key in keys
27
+ ]
28
+
29
+
30
+ def join_wrapped_descriptions(instructions: str) -> bool:
31
+ positive = False
32
+ for clause in re.split("[.;\\n]", instructions):
33
+ wrapped = re.search(
34
+ "\\b(?:wrapped|multiline|multi-line|continuation)\\b", clause, re.IGNORECASE
35
+ )
36
+ joining = re.search("\\b(?:join|combine|merge)\\b", clause, re.IGNORECASE)
37
+ negative = re.search(
38
+ "\\b(?:not|no|never|without|separate\\w*|independent\\w*)\\b|\\b\\w+n['’]t\\b",
39
+ clause,
40
+ re.IGNORECASE,
41
+ )
42
+ if negative and (wrapped or joining):
43
+ return False
44
+ positive |= bool(
45
+ re.search(
46
+ "\\b(?:join|combine)\\b[^.;\\n]*\\b(?:wrapped|multiline|multi-line|continuation)\\b[^.;\\n]*\\b(?:descriptions?|lines?|text)\\b",
47
+ clause,
48
+ re.IGNORECASE,
49
+ )
50
+ )
51
+ return positive
52
+
53
+
54
+ def _wrapped_rows(
55
+ rows: list[dict[str, Any]], properties: dict[str, dict[str, Any]]
56
+ ) -> list[dict[str, Any]] | None:
57
+ texts = [name for (name, spec) in properties.items() if spec["type"] == "text"]
58
+ numbers = [name for (name, spec) in properties.items() if spec["type"] == "number"]
59
+ if len(texts) != 1 or not numbers:
60
+ return rows
61
+ text = texts[0]
62
+ joined: list[dict[str, Any]] = []
63
+ for row in rows:
64
+ previous = joined[-1] if joined else None
65
+ if (
66
+ previous
67
+ and previous["values"][text]
68
+ and row["values"][text]
69
+ and (previous["spans"][text] is not None)
70
+ and (row["spans"][text] is not None)
71
+ and all((previous["values"][key] is None for key in numbers))
72
+ and any((row["values"][key] is not None for key in numbers))
73
+ and (
74
+ row["line"].find(row["values"][text])
75
+ >= previous["line"].find(previous["values"][text]) + 2
76
+ )
77
+ ):
78
+ value = previous["values"][text] + " " + row["values"][text]
79
+ if not Draft202012Validator(ar.schema(properties[text])).is_valid(value):
80
+ return None
81
+ joined[-1] = {
82
+ "line": previous["line"] + "\n" + row["line"],
83
+ "values": {**row["values"], text: value},
84
+ "spans": {**row["spans"], text: None},
85
+ }
86
+ else:
87
+ joined.append(row)
88
+ return joined
89
+
90
+
91
+ def _source_row(
92
+ cells: Sequence[str],
93
+ keys: Sequence[str],
94
+ line: str,
95
+ offset: int,
96
+ properties: dict[str, dict[str, Any]],
97
+ names: Mapping[str, str],
98
+ ) -> dict[str, Any] | None:
99
+ value: str | int | float | None
100
+ (values, spans) = ({}, {})
101
+ for key, cell in zip(keys, cells, strict=True):
102
+ name = names[key]
103
+ spec = properties[name]
104
+ if not cell:
105
+ value = None
106
+ elif spec["type"] == "number":
107
+ try:
108
+ value = printed_numbers.normalize(cell, spec)
109
+ except (ValueError, TypeError, OverflowError, ValidationError):
110
+ return None
111
+ else:
112
+ value = cell
113
+ if not Draft202012Validator(ar.schema(spec)).is_valid(value):
114
+ return None
115
+ values[name] = value
116
+ start = line.find(cell) if cell and line.count(cell) == 1 else -1
117
+ spans[name] = (
118
+ [offset + start, offset + start + len(cell)] if start >= 0 else None
119
+ )
120
+ for name, spec in properties.items():
121
+ if name not in values:
122
+ if not Draft202012Validator(ar.schema(spec)).is_valid(None):
123
+ return None
124
+ (values[name], spans[name]) = (None, None)
125
+ return {"line": line.rstrip("\r\n"), "values": values, "spans": spans}
126
+
127
+
128
+ def _html_candidates(
129
+ source: str, properties: dict[str, dict[str, Any]], names: Mapping[str, str]
130
+ ) -> list[dict[str, Any]] | None:
131
+ tables = html_rows.tables(source)
132
+ if tables is None or len(tables) != 1 or len(tables[0]) < 2:
133
+ return None
134
+ (header, *body) = tables[0]
135
+ keys = [_column(cell) for cell in header["cells"]]
136
+ if (
137
+ len(keys) < 2
138
+ or len(set(keys)) != len(keys)
139
+ or any((key not in names for key in keys))
140
+ ):
141
+ return None
142
+ rows = []
143
+ for row in body:
144
+ if len(row["cells"]) != len(keys) or not any(row["cells"]):
145
+ return None
146
+ parsed = _source_row(
147
+ row["cells"], keys, row["line"], row["offset"], properties, names
148
+ )
149
+ if parsed is None:
150
+ return None
151
+ for key, span in zip(keys, row["spans"], strict=True):
152
+ parsed["spans"][names[key]] = span
153
+ rows.append(parsed)
154
+ return rows
155
+
156
+
157
+ def candidates(
158
+ source: str, properties: dict[str, dict[str, Any]], *, wrapped: bool = False
159
+ ) -> list[dict[str, Any]] | None:
160
+ if any(
161
+ (
162
+ spec["type"] not in ("text", "number") or spec.get("knowledge")
163
+ for spec in properties.values()
164
+ )
165
+ ):
166
+ return None
167
+ names = {_column(name): name for name in properties}
168
+ if len(names) != len(properties):
169
+ return None
170
+ if re.search("<table\\b", source, re.IGNORECASE):
171
+ return _html_candidates(source, properties, names)
172
+ lines = source.splitlines(keepends=True)
173
+ (offsets, offset) = ([], 0)
174
+ for line in lines:
175
+ offsets.append(offset)
176
+ offset += len(line)
177
+ tables = []
178
+ for delimiter in ("|", "\t", ",", ";"):
179
+ for index, line in enumerate(lines):
180
+ if delimiter not in line:
181
+ continue
182
+ try:
183
+ header = next(csv.reader([line], delimiter=delimiter, strict=True))
184
+ except csv.Error:
185
+ continue
186
+ header = [cell.strip() for cell in header]
187
+ leading = delimiter == "|" and len(header) > 2 and (not header[0])
188
+ trailing = delimiter == "|" and len(header) > 2 and (not header[-1])
189
+ if trailing:
190
+ header = header[:-1]
191
+ if leading:
192
+ header = header[1:]
193
+ keys = _header_keys(header, names)
194
+ if (
195
+ len(keys) < 2
196
+ or len(set(keys)) != len(keys)
197
+ or any((key not in names for key in keys))
198
+ ):
199
+ continue
200
+ rows: list[dict[str, Any]] = []
201
+ for row_index in range(index + 1, len(lines)):
202
+ text = lines[row_index]
203
+ if delimiter not in text:
204
+ break
205
+ try:
206
+ cells = next(csv.reader([text], delimiter=delimiter, strict=True))
207
+ except csv.Error:
208
+ return None
209
+ cells = [cell.strip() for cell in cells]
210
+ if trailing and cells and (not cells[-1]):
211
+ cells = cells[:-1]
212
+ if leading and cells and (not cells[0]):
213
+ cells = cells[1:]
214
+ if len(cells) != len(keys):
215
+ return None
216
+ if not rows and all(
217
+ (re.fullmatch(":?-{3,}:?", cell) for cell in cells)
218
+ ):
219
+ continue
220
+ if not any(cells):
221
+ return None
222
+ row = _source_row(
223
+ cells, keys, text, offsets[row_index], properties, names
224
+ )
225
+ if row is None:
226
+ return None
227
+ rows.append(row)
228
+ tables.append(_wrapped_rows(rows, properties) if wrapped else rows)
229
+ return tables[0] if len(tables) == 1 else None
230
+
231
+
232
+ def _scope_instruction(instructions: str) -> str | None:
233
+ requested = re.split(
234
+ "[.\\n]|\\bExclude\\b", instructions, maxsplit=1, flags=re.IGNORECASE
235
+ )[0]
236
+ roles = [
237
+ bool(re.search(pattern, requested, re.IGNORECASE))
238
+ for pattern in (
239
+ "\\bfees?\\b",
240
+ "\\btax(?:es)?\\b",
241
+ "\\b(?:charges?|goods|products?|services?)\\b",
242
+ )
243
+ ]
244
+ if sum(roles) != 1:
245
+ return None
246
+ priority = "Evaluate exclusions first for this exact row; an exclusion overrides a general category match. "
247
+ if roles[0]:
248
+ return (
249
+ priority
250
+ + "Include only a separately printed fee or surcharge. A billed product or service charge, tax, total or payment is not a fee merely because it has a monetary amount. The row label must explicitly establish that it is a fee or surcharge. "
251
+ )
252
+ if roles[1]:
253
+ return (
254
+ priority
255
+ + "Include only an explicitly identified tax, such as sales tax, VAT or GST. A product, service charge, fee, total or payment is not a tax merely because it has an amount. "
256
+ )
257
+ if roles[2]:
258
+ return (
259
+ priority
260
+ + "Include only billed goods or service charges. A separately identified tax, fee, surcharge, payment, subtotal or total is excluded, even though it is a monetary charge. "
261
+ )
262
+ return None
263
+
264
+
265
+ def scoped_pairs(source: str, spec: dict[str, Any]) -> list[dict[str, Any]] | None:
266
+ instructions = spec.get("instructions", "")
267
+ scope_instruction = _scope_instruction(instructions)
268
+ properties = spec["items"]["properties"]
269
+ if (
270
+ len(properties) != 2
271
+ or scope_instruction is None
272
+ or (not re.match("\\s*Only\\b[^.\\n]*\\brows\\b", instructions, re.IGNORECASE))
273
+ or re.search(
274
+ "\\b(?:summar\\w*|calculat\\w*|combin\\w*|group\\w*|aggregat\\w*|deduplicat\\w*)\\b|\\buse\\b[^.\\n]*\\bas\\b",
275
+ instructions,
276
+ re.IGNORECASE,
277
+ )
278
+ ):
279
+ return None
280
+ texts = [
281
+ name for (name, child) in properties.items() if child.get("type") == "text"
282
+ ]
283
+ numbers = [
284
+ name for (name, child) in properties.items() if child.get("type") == "number"
285
+ ]
286
+ if (
287
+ len(texts) != 1
288
+ or len(numbers) != 1
289
+ or any((child.get("knowledge") for child in properties.values()))
290
+ ):
291
+ return None
292
+ if not re.search(
293
+ "\\b(?:exact|verbatim)\\b[^.\\n]*\\b(?:printed|row)\\b[^.\\n]*\\blabel\\b",
294
+ properties[texts[0]].get("instructions", ""),
295
+ re.IGNORECASE,
296
+ ):
297
+ return None
298
+ names = {_column(name): name for name in properties}
299
+ if len(names) != len(properties):
300
+ return None
301
+ keys = [_column(texts[0]), _column(numbers[0])]
302
+ tables = []
303
+ for delimiter in ("|", "\t", ";"):
304
+ (rows, offset) = ([], 0)
305
+ for line in source.splitlines(keepends=True):
306
+ if delimiter in line:
307
+ try:
308
+ cells = [
309
+ cell.strip()
310
+ for cell in next(
311
+ csv.reader([line], delimiter=delimiter, strict=True)
312
+ )
313
+ ]
314
+ except csv.Error:
315
+ return None
316
+ if len(cells) != 2 or not all(cells):
317
+ return None
318
+ row = _source_row(cells, keys, line, offset, properties, names)
319
+ if row is None:
320
+ return None
321
+ row["eligibility_only"] = True
322
+ row["scope_instruction"] = scope_instruction
323
+ rows.append(row)
324
+ offset += len(line)
325
+ if len(rows) >= 2:
326
+ tables.append(rows)
327
+ return tables[0] if len(tables) == 1 else None
328
+
329
+
330
+ def prepare(
331
+ source: str,
332
+ fields: dict[str, dict[str, Any]],
333
+ *,
334
+ has_media: bool = False,
335
+ allow_scoped_pairs: bool = False,
336
+ ) -> dict[str, list[dict[str, Any]]]:
337
+ if has_media:
338
+ return {}
339
+ result = {}
340
+ for name, spec in fields.items():
341
+ item = spec.get("items")
342
+ if (
343
+ spec.get("type") != "list"
344
+ or not isinstance(item, dict)
345
+ or item.get("type") != "object"
346
+ ):
347
+ continue
348
+ explicit_rows = re.search(
349
+ "\\bone\\s+(?:object|entry|record)\\s+(?:per|for\\s+each)\\b[^.\\n]*\\brow\\b",
350
+ spec.get("instructions", ""),
351
+ re.IGNORECASE,
352
+ )
353
+ wrapped = join_wrapped_descriptions(spec.get("instructions", ""))
354
+ rows = (
355
+ candidates(source, item["properties"], wrapped=wrapped)
356
+ if explicit_rows
357
+ else scoped_pairs(source, spec)
358
+ if allow_scoped_pairs
359
+ else None
360
+ )
361
+ if rows and len(rows) <= spec.get("max_items", 32):
362
+ missing_columns = [
363
+ key
364
+ for (key, child) in item["properties"].items()
365
+ if child.get("type") == "number"
366
+ and all((row["values"][key] is None for row in rows))
367
+ ]
368
+ if missing_columns:
369
+ for row in rows:
370
+ row["eligibility_only"] = True
371
+ result[name] = rows
372
+ return result
373
+
374
+
375
+ def membership_instructions(instructions: str) -> str:
376
+ if re.search(
377
+ "[\\r\\n`\\\"“”]|(?<!\\w)'[^'\\r\\n]+'(?!\\w)|‘[^’]+’|\\b(?:literal|verbatim|quoted|quote|quotation|code|snippet|block|note|label|phrase)\\b",
378
+ instructions,
379
+ re.IGNORECASE,
380
+ ):
381
+ return instructions
382
+ target = "(?:(?:wrapped|multiline|multi-line|continuation)\\s+)?(?:descriptions?(?:\\s+lines?)?|lines?|(?:distinct|separate|duplicate|repeated|physical)\\s+rows?)"
383
+ negative_join = re.compile(
384
+ "\\s*(?:do\\s+not|don't|never)\\s+(?:join|combine|merge)\\s+"
385
+ + target
386
+ + "(?:\\s+or\\s+(?:join|combine|merge)\\s+"
387
+ + target
388
+ + ")*\\s*[.;]?\\s*",
389
+ re.IGNORECASE,
390
+ )
391
+ clauses = re.split("(?<=[.;])(?=\\s|$)|(?<=\\n)", instructions)
392
+ if not any((negative_join.fullmatch(clause) for clause in clauses)):
393
+ return instructions
394
+ return "".join(
395
+ (clause for clause in clauses if not negative_join.fullmatch(clause))
396
+ ).strip()
397
+
398
+
399
+ def row_spec(
400
+ spec: dict[str, Any], row: dict[str, Any], *, eligibility: bool = False
401
+ ) -> dict[str, Any]:
402
+ missing = [name for (name, value) in row["values"].items() if value is None]
403
+ missing_instruction = (
404
+ "Missing cells or entire columns do not exclude an otherwise matching row. These source cells are missing and must remain null: "
405
+ + ", ".join(missing)
406
+ + ". "
407
+ if missing
408
+ else ""
409
+ )
410
+ scope = membership_instructions(spec.get("instructions", ""))
411
+ if eligibility:
412
+ return {
413
+ "type": "boolean",
414
+ "nullable": False,
415
+ "instructions": "Classify exactly this physical source row for inclusion in the requested list. Return true if and only if this row satisfies the requested list instructions. Return false if the row is excluded, unrelated, or does not belong to the requested list, even though it exists. This is an eligibility decision, not a request to copy its cells. "
416
+ + missing_instruction
417
+ + row.get("scope_instruction", "")
418
+ + "Requested list instructions: "
419
+ + scope
420
+ + "\nExact physical source row: "
421
+ + row["line"],
422
+ }
423
+ properties = {}
424
+ for name, child in spec["items"]["properties"].items():
425
+ value = row["values"][name]
426
+ properties[name] = {**child, "nullable": value is None, "enum": [value]}
427
+ return {
428
+ **spec["items"],
429
+ "properties": properties,
430
+ "nullable": True,
431
+ "instructions": scope
432
+ + "\nRead only this exact physical source row: "
433
+ + json.dumps(row["line"], ensure_ascii=False)
434
+ + "\nReturn null if this row does not satisfy the requested scope. Otherwise copy its cells together. "
435
+ + missing_instruction
436
+ + "Do not substitute a different row. Missing cells are null. This query has no list ordinal to count.",
437
+ }
438
+
439
+
440
+ def local_scope_context(
441
+ rows: Sequence[dict[str, Any]], queries: Sequence[str], *, offset: int = 0
442
+ ) -> tuple[dict[str, str], dict[str, str]]:
443
+ if not rows or not all((row.get("scope_instruction") for row in rows)):
444
+ return ({}, {})
445
+ pairs = list(zip(queries, rows, strict=True))
446
+ inputs = dict.fromkeys(queries, LOCAL_SCOPE_INPUT)
447
+ names = {
448
+ query: f"source_scope_{offset + index}"
449
+ for (index, (query, _)) in enumerate(pairs, 1)
450
+ }
451
+ return (inputs, names)
452
+
453
+
454
+ def assemble(
455
+ predictions: dict[str, dict[str, Any]],
456
+ rows: Sequence[dict[str, Any]],
457
+ queries: Sequence[str],
458
+ *,
459
+ eligibility: bool = False,
460
+ ) -> dict[str, Any]:
461
+ checks = [predictions[name] for name in queries]
462
+ selected = [
463
+ (row, answer)
464
+ for (row, answer) in zip(rows, checks, strict=True)
465
+ if (
466
+ answer.get("value") is True
467
+ if eligibility
468
+ else answer.get("value") is not None
469
+ )
470
+ ]
471
+ valid = all(
472
+ (
473
+ answer.get("valid", False) and answer.get("complete", False)
474
+ for answer in checks
475
+ )
476
+ )
477
+ scored = True
478
+ if eligibility:
479
+ valid &= all((type(answer.get("value")) is bool for answer in checks))
480
+ scored = all(
481
+ (
482
+ isinstance((score := answer.get("p_excluded")), (int, float))
483
+ and (not isinstance(score, bool))
484
+ and math.isfinite(score)
485
+ and (0 <= score <= 1)
486
+ for answer in checks
487
+ )
488
+ )
489
+ valid &= scored
490
+ p_null = (
491
+ math.exp(sum((math.log(answer["p_excluded"]) for answer in checks)))
492
+ if scored and all((answer["p_excluded"] > 0 for answer in checks))
493
+ else 0.0
494
+ )
495
+ p_null_method = (
496
+ "product_source_row_exclusion_probabilities"
497
+ if scored
498
+ else "unavailable_source_row_exclusion_probability"
499
+ )
500
+ else:
501
+ p_null = min((answer.get("p_null", 0.0) for answer in checks))
502
+ p_null_method = "minimum_source_row_null_probability"
503
+ log_probability = sum(
504
+ (answer.get("log_probability", -math.inf) for answer in checks)
505
+ )
506
+ if not math.isfinite(log_probability):
507
+ log_probability = None
508
+ result = {
509
+ "value": [
510
+ dict(row["values"]) if eligibility else answer["value"]
511
+ for (row, answer) in selected
512
+ ],
513
+ "valid": valid,
514
+ "complete": valid,
515
+ "confidence": math.exp(min(0, log_probability))
516
+ if valid and log_probability is not None
517
+ else 0.0,
518
+ "confidence_method": "ar_source_row_eligibility_probability"
519
+ if eligibility
520
+ else "ar_source_row_sequence_probability",
521
+ "p_null": p_null,
522
+ "p_null_method": p_null_method,
523
+ "confidences": [answer.get("confidence", 0.0) for (row, answer) in selected],
524
+ "p_nulls": [
525
+ answer.get("p_excluded" if eligibility else "p_null", 0.0)
526
+ for (row, answer) in selected
527
+ ],
528
+ "spans": [None] * len(selected),
529
+ "property_spans": [row["spans"] for (row, answer) in selected],
530
+ }
531
+ if log_probability is not None:
532
+ result["log_probability"] = log_probability
533
+ if eligibility and (not scored):
534
+ result.pop("p_nulls")
535
+ if not valid:
536
+ result["failure_reason"] = (
537
+ "source_row_eligibility_unscored"
538
+ if eligibility and (not scored)
539
+ else "source_row_read_incomplete"
540
+ )
541
+ return result
clairic_runtime/text_ar.py ADDED
@@ -0,0 +1,164 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ from __future__ import annotations
2
+ import asyncio
3
+ import json
4
+ import uuid
5
+ from typing import TYPE_CHECKING
6
+ from . import (
7
+ ar,
8
+ batch_completion,
9
+ grounding,
10
+ image_rows,
11
+ printed_numbers,
12
+ printed_temporal,
13
+ )
14
+ from .backend import MAX_OUTPUT_TOKENS, ClairInferenceError, scalar_result
15
+ from .media import batch_image_data
16
+ from . import text_list_completion
17
+
18
+ if TYPE_CHECKING:
19
+ from typing import Any
20
+ from .large import Clairic27BModel
21
+
22
+
23
+ async def text_ar_all(
24
+ self: Clairic27BModel, record: dict[str, Any], eos: int
25
+ ) -> dict[str, dict[str, Any]]:
26
+ tasks = record["_ar_tasks"]
27
+ salt = record["_cache_salt"]
28
+ row_gates = set(record.get("_source_row_gates", ()))
29
+ false_id = self.tokenizer.convert_tokens_to_ids("false") if row_gates else None
30
+ score_ids = [self.tokenizer.convert_tokens_to_ids("null")]
31
+ if false_id is not None:
32
+ score_ids.append(false_id)
33
+ results = await text_list_completion.generate(
34
+ self.engine,
35
+ record,
36
+ tasks,
37
+ eos,
38
+ self.tokenizer,
39
+ parse_result=scalar_result,
40
+ normalize=lambda record, predictions: printed_numbers.normalize_predictions(
41
+ record, printed_temporal.normalize_predictions(record, predictions)
42
+ ),
43
+ input_ids=[ids for (_, ids, _) in tasks],
44
+ image_data=batch_image_data([media for (_, _, media) in tasks]),
45
+ rid=["ar-" + uuid.uuid4().hex for _ in tasks],
46
+ cache_salt=[
47
+ record.get("_ar_task_salts", {}).get(name, salt) for (name, _, _) in tasks
48
+ ],
49
+ return_logprob=True,
50
+ logprob_start_len=-1,
51
+ token_ids_logprob=score_ids,
52
+ sampling_params=[
53
+ {
54
+ "temperature": 0,
55
+ "max_new_tokens": image_rows.output_limit(
56
+ record, name, len(ids), self.settings.max_length
57
+ )
58
+ if image_rows.is_inventory(record["fields"][name])
59
+ else record.get("_ar_max_output_tokens", MAX_OUTPUT_TOKENS),
60
+ "stop_token_ids": [eos],
61
+ **(
62
+ record["_ar_constraints"][name]
63
+ if name in record.get("_ar_constraints", {})
64
+ else {"json_schema": json.dumps(ar.schema(record["fields"][name]))}
65
+ ),
66
+ "skip_special_tokens": False,
67
+ }
68
+ for (name, ids, _) in tasks
69
+ ],
70
+ )
71
+ if usage := record.get("_completed_generation_usage"):
72
+ usage["tasks"].extend(tasks)
73
+ usage["readings"].extend(
74
+ (
75
+ {"tokens": int(result.get("meta_info", {}).get("completion_tokens", 0))}
76
+ for result in results
77
+ )
78
+ )
79
+ predictions = {
80
+ name: batch_completion.unused_prediction(result)
81
+ if result.get("_clair_unused_row_proposal")
82
+ else scalar_result(
83
+ result,
84
+ record["fields"][name],
85
+ self.tokenizer,
86
+ record["input"],
87
+ record.get("_ar_sources", {}).get(name, record.get("_ar_source"))
88
+ if grounding.applies(record["fields"][name], media)
89
+ else None,
90
+ excluded_token_id=false_id if name in row_gates else None,
91
+ provenance=record.get("_ar_sources", {}).get(name, record.get("_ar_source"))
92
+ if media is None and (not record["fields"][name].get("knowledge"))
93
+ else None,
94
+ )
95
+ for ((name, _, media), result) in zip(tasks, results, strict=True)
96
+ }
97
+ if any(
98
+ (
99
+ "confidence" not in prediction
100
+ for prediction in predictions.values()
101
+ if not prediction.get("_unused_row_proposal")
102
+ )
103
+ ):
104
+ raise ClairInferenceError("Transformers omitted generation log probabilities")
105
+ if any(
106
+ (
107
+ "p_null" not in prediction
108
+ for prediction in predictions.values()
109
+ if not prediction.get("_unused_row_proposal")
110
+ )
111
+ ):
112
+ raise ClairInferenceError("Transformers omitted null-token log probabilities")
113
+ if self.RECOVER_NULLS and (not record.get("_null_recovery")):
114
+ fields = {
115
+ name
116
+ for (name, prediction) in predictions.items()
117
+ if (
118
+ prediction["valid"]
119
+ and prediction["value"] is None
120
+ or prediction.get("failure_reason") == "not_in_source"
121
+ )
122
+ and (not record["fields"][name].get("knowledge"))
123
+ and (name not in record.get("_meta", {}).get("printed_temporal", {}))
124
+ and (name not in record.get("_meta", {}).get("printed_numbers", {}))
125
+ and (
126
+ record["fields"][name]["type"] == "number"
127
+ or (record["fields"][name]["type"] == "text" and record["input"])
128
+ )
129
+ and (
130
+ not record["_meta"]["extraction_contract"]["fields"]
131
+ .get(name, {})
132
+ .get("parent")
133
+ )
134
+ }
135
+ if fields:
136
+ repair = await asyncio.get_running_loop().run_in_executor(
137
+ self._encoder, self.null_recovery_record, record, fields
138
+ )
139
+ if repair["_ar_tasks"]:
140
+ alternatives = await self._ar_all(repair, eos)
141
+ retry_lengths = {
142
+ name: len(ids) for (name, ids, _) in repair["_ar_tasks"]
143
+ }
144
+ for name, alternative in alternatives.items():
145
+ original = predictions[name]
146
+ tokens = original["tokens"] + alternative["tokens"]
147
+ if (
148
+ alternative["valid"]
149
+ and alternative["value"] is not None
150
+ and (
151
+ alternative.get("grounding_method")
152
+ in ("literal_source", "whitespace_normalized_source")
153
+ or record["fields"][name]["type"] == "number"
154
+ or (
155
+ alternative.get("span") is not None
156
+ and alternative.get("confidence", 0.0)
157
+ > alternative.get("p_null", 1.0)
158
+ )
159
+ )
160
+ ):
161
+ predictions[name] = {**alternative, "null_recovered": True}
162
+ predictions[name]["tokens"] = tokens
163
+ predictions[name]["retry_input_tokens"] = retry_lengths[name]
164
+ return predictions