lucataco commited on
Commit
ae97c5d
·
verified ·
1 Parent(s): a100c70

Clairic Flash, MLX 4-bit, with runtime, server and conversion script

Browse files
This view is limited to 50 files because it contains too many changes.   See raw diff
Files changed (50) hide show
  1. .gitattributes +1 -0
  2. LICENSE +202 -0
  3. NOTICE +25 -0
  4. README.md +243 -0
  5. chat_template.jinja +154 -0
  6. clair_head.safetensors +3 -0
  7. clair_head_config.json +16 -0
  8. clairic_mlx.py +144 -0
  9. clairic_runtime/__init__.py +6 -0
  10. clairic_runtime/api.py +201 -0
  11. clairic_runtime/ar.py +228 -0
  12. clairic_runtime/backend.py +1728 -0
  13. clairic_runtime/batch_completion.py +449 -0
  14. clairic_runtime/clair_schema.py +563 -0
  15. clairic_runtime/contracts.py +128 -0
  16. clairic_runtime/documents.py +91 -0
  17. clairic_runtime/embedded.py +144 -0
  18. clairic_runtime/entity_scope.py +37 -0
  19. clairic_runtime/errors.py +10 -0
  20. clairic_runtime/financial_scope.py +94 -0
  21. clairic_runtime/grounding.py +417 -0
  22. clairic_runtime/html_rows.py +132 -0
  23. clairic_runtime/identifier_scope.py +89 -0
  24. clairic_runtime/identifier_spelling.py +281 -0
  25. clairic_runtime/image_financial_lines.py +393 -0
  26. clairic_runtime/image_focus.py +48 -0
  27. clairic_runtime/image_identifier.py +170 -0
  28. clairic_runtime/image_party_names.py +68 -0
  29. clairic_runtime/image_ragged_rows.py +350 -0
  30. clairic_runtime/image_rows.py +323 -0
  31. clairic_runtime/image_table_rows.py +225 -0
  32. clairic_runtime/large.py +204 -0
  33. clairic_runtime/lists.py +49 -0
  34. clairic_runtime/media.py +98 -0
  35. clairic_runtime/media_cache.py +105 -0
  36. clairic_runtime/media_state_prompt.py +139 -0
  37. clairic_runtime/mlx_engine.py +918 -0
  38. clairic_runtime/model.py +2424 -0
  39. clairic_runtime/ordinary_list_completion.py +163 -0
  40. clairic_runtime/orientation.py +85 -0
  41. clairic_runtime/pdf_number_focus.py +86 -0
  42. clairic_runtime/po_image_supplement.py +220 -0
  43. clairic_runtime/printed_numbers.py +259 -0
  44. clairic_runtime/printed_temporal.py +178 -0
  45. clairic_runtime/processor.py +65 -0
  46. clairic_runtime/receipt_hybrid_inventory.py +377 -0
  47. clairic_runtime/receipt_totals.py +555 -0
  48. clairic_runtime/row_omission.py +190 -0
  49. clairic_runtime/schema.py +533 -0
  50. clairic_runtime/settings.py +29 -0
.gitattributes CHANGED
@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
33
  *.zip filter=lfs diff=lfs merge=lfs -text
34
  *.zst filter=lfs diff=lfs merge=lfs -text
35
  *tfevents* filter=lfs diff=lfs merge=lfs -text
 
 
33
  *.zip filter=lfs diff=lfs merge=lfs -text
34
  *.zst filter=lfs diff=lfs merge=lfs -text
35
  *tfevents* filter=lfs diff=lfs merge=lfs -text
36
+ tokenizer.json filter=lfs diff=lfs merge=lfs -text
LICENSE ADDED
@@ -0,0 +1,202 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+
2
+ Apache License
3
+ Version 2.0, January 2004
4
+ http://www.apache.org/licenses/
5
+
6
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7
+
8
+ 1. Definitions.
9
+
10
+ "License" shall mean the terms and conditions for use, reproduction,
11
+ and distribution as defined by Sections 1 through 9 of this document.
12
+
13
+ "Licensor" shall mean the copyright owner or entity authorized by
14
+ the copyright owner that is granting the License.
15
+
16
+ "Legal Entity" shall mean the union of the acting entity and all
17
+ other entities that control, are controlled by, or are under common
18
+ control with that entity. For the purposes of this definition,
19
+ "control" means (i) the power, direct or indirect, to cause the
20
+ direction or management of such entity, whether by contract or
21
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
22
+ outstanding shares, or (iii) beneficial ownership of such entity.
23
+
24
+ "You" (or "Your") shall mean an individual or Legal Entity
25
+ exercising permissions granted by this License.
26
+
27
+ "Source" form shall mean the preferred form for making modifications,
28
+ including but not limited to software source code, documentation
29
+ source, and configuration files.
30
+
31
+ "Object" form shall mean any form resulting from mechanical
32
+ transformation or translation of a Source form, including but
33
+ not limited to compiled object code, generated documentation,
34
+ and conversions to other media types.
35
+
36
+ "Work" shall mean the work of authorship, whether in Source or
37
+ Object form, made available under the License, as indicated by a
38
+ copyright notice that is included in or attached to the work
39
+ (an example is provided in the Appendix below).
40
+
41
+ "Derivative Works" shall mean any work, whether in Source or Object
42
+ form, that is based on (or derived from) the Work and for which the
43
+ editorial revisions, annotations, elaborations, or other modifications
44
+ represent, as a whole, an original work of authorship. For the purposes
45
+ of this License, Derivative Works shall not include works that remain
46
+ separable from, or merely link (or bind by name) to the interfaces of,
47
+ the Work and Derivative Works thereof.
48
+
49
+ "Contribution" shall mean any work of authorship, including
50
+ the original version of the Work and any modifications or additions
51
+ to that Work or Derivative Works thereof, that is intentionally
52
+ submitted to Licensor for inclusion in the Work by the copyright owner
53
+ or by an individual or Legal Entity authorized to submit on behalf of
54
+ the copyright owner. For the purposes of this definition, "submitted"
55
+ means any form of electronic, verbal, or written communication sent
56
+ to the Licensor or its representatives, including but not limited to
57
+ communication on electronic mailing lists, source code control systems,
58
+ and issue tracking systems that are managed by, or on behalf of, the
59
+ Licensor for the purpose of discussing and improving the Work, but
60
+ excluding communication that is conspicuously marked or otherwise
61
+ designated in writing by the copyright owner as "Not a Contribution."
62
+
63
+ "Contributor" shall mean Licensor and any individual or Legal Entity
64
+ on behalf of whom a Contribution has been received by Licensor and
65
+ subsequently incorporated within the Work.
66
+
67
+ 2. Grant of Copyright License. Subject to the terms and conditions of
68
+ this License, each Contributor hereby grants to You a perpetual,
69
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70
+ copyright license to reproduce, prepare Derivative Works of,
71
+ publicly display, publicly perform, sublicense, and distribute the
72
+ Work and such Derivative Works in Source or Object form.
73
+
74
+ 3. Grant of Patent License. Subject to the terms and conditions of
75
+ this License, each Contributor hereby grants to You a perpetual,
76
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77
+ (except as stated in this section) patent license to make, have made,
78
+ use, offer to sell, sell, import, and otherwise transfer the Work,
79
+ where such license applies only to those patent claims licensable
80
+ by such Contributor that are necessarily infringed by their
81
+ Contribution(s) alone or by combination of their Contribution(s)
82
+ with the Work to which such Contribution(s) was submitted. If You
83
+ institute patent litigation against any entity (including a
84
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
85
+ or a Contribution incorporated within the Work constitutes direct
86
+ or contributory patent infringement, then any patent licenses
87
+ granted to You under this License for that Work shall terminate
88
+ as of the date such litigation is filed.
89
+
90
+ 4. Redistribution. You may reproduce and distribute copies of the
91
+ Work or Derivative Works thereof in any medium, with or without
92
+ modifications, and in Source or Object form, provided that You
93
+ meet the following conditions:
94
+
95
+ (a) You must give any other recipients of the Work or
96
+ Derivative Works a copy of this License; and
97
+
98
+ (b) You must cause any modified files to carry prominent notices
99
+ stating that You changed the files; and
100
+
101
+ (c) You must retain, in the Source form of any Derivative Works
102
+ that You distribute, all copyright, patent, trademark, and
103
+ attribution notices from the Source form of the Work,
104
+ excluding those notices that do not pertain to any part of
105
+ the Derivative Works; and
106
+
107
+ (d) If the Work includes a "NOTICE" text file as part of its
108
+ distribution, then any Derivative Works that You distribute must
109
+ include a readable copy of the attribution notices contained
110
+ within such NOTICE file, excluding those notices that do not
111
+ pertain to any part of the Derivative Works, in at least one
112
+ of the following places: within a NOTICE text file distributed
113
+ as part of the Derivative Works; within the Source form or
114
+ documentation, if provided along with the Derivative Works; or,
115
+ within a display generated by the Derivative Works, if and
116
+ wherever such third-party notices normally appear. The contents
117
+ of the NOTICE file are for informational purposes only and
118
+ do not modify the License. You may add Your own attribution
119
+ notices within Derivative Works that You distribute, alongside
120
+ or as an addendum to the NOTICE text from the Work, provided
121
+ that such additional attribution notices cannot be construed
122
+ as modifying the License.
123
+
124
+ You may add Your own copyright statement to Your modifications and
125
+ may provide additional or different license terms and conditions
126
+ for use, reproduction, or distribution of Your modifications, or
127
+ for any such Derivative Works as a whole, provided Your use,
128
+ reproduction, and distribution of the Work otherwise complies with
129
+ the conditions stated in this License.
130
+
131
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
132
+ any Contribution intentionally submitted for inclusion in the Work
133
+ by You to the Licensor shall be under the terms and conditions of
134
+ this License, without any additional terms or conditions.
135
+ Notwithstanding the above, nothing herein shall supersede or modify
136
+ the terms of any separate license agreement you may have executed
137
+ with Licensor regarding such Contributions.
138
+
139
+ 6. Trademarks. This License does not grant permission to use the trade
140
+ names, trademarks, service marks, or product names of the Licensor,
141
+ except as required for reasonable and customary use in describing the
142
+ origin of the Work and reproducing the content of the NOTICE file.
143
+
144
+ 7. Disclaimer of Warranty. Unless required by applicable law or
145
+ agreed to in writing, Licensor provides the Work (and each
146
+ Contributor provides its Contributions) on an "AS IS" BASIS,
147
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148
+ implied, including, without limitation, any warranties or conditions
149
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150
+ PARTICULAR PURPOSE. You are solely responsible for determining the
151
+ appropriateness of using or redistributing the Work and assume any
152
+ risks associated with Your exercise of permissions under this License.
153
+
154
+ 8. Limitation of Liability. In no event and under no legal theory,
155
+ whether in tort (including negligence), contract, or otherwise,
156
+ unless required by applicable law (such as deliberate and grossly
157
+ negligent acts) or agreed to in writing, shall any Contributor be
158
+ liable to You for damages, including any direct, indirect, special,
159
+ incidental, or consequential damages of any character arising as a
160
+ result of this License or out of the use or inability to use the
161
+ Work (including but not limited to damages for loss of goodwill,
162
+ work stoppage, computer failure or malfunction, or any and all
163
+ other commercial damages or losses), even if such Contributor
164
+ has been advised of the possibility of such damages.
165
+
166
+ 9. Accepting Warranty or Additional Liability. While redistributing
167
+ the Work or Derivative Works thereof, You may choose to offer,
168
+ and charge a fee for, acceptance of support, warranty, indemnity,
169
+ or other liability obligations and/or rights consistent with this
170
+ License. However, in accepting such obligations, You may act only
171
+ on Your own behalf and on Your sole responsibility, not on behalf
172
+ of any other Contributor, and only if You agree to indemnify,
173
+ defend, and hold each Contributor harmless for any liability
174
+ incurred by, or claims asserted against, such Contributor by reason
175
+ of your accepting any such warranty or additional liability.
176
+
177
+ END OF TERMS AND CONDITIONS
178
+
179
+ APPENDIX: How to apply the Apache License to your work.
180
+
181
+ To apply the Apache License to your work, attach the following
182
+ boilerplate notice, with the fields enclosed by brackets "[]"
183
+ replaced with your own identifying information. (Don't include
184
+ the brackets!) The text should be enclosed in the appropriate
185
+ comment syntax for the file format. We also recommend that a
186
+ file or class name and description of purpose be included on the
187
+ same "printed page" as the copyright notice for easier
188
+ identification within third-party archives.
189
+
190
+ Copyright 2026 Alibaba Cloud
191
+
192
+ Licensed under the Apache License, Version 2.0 (the "License");
193
+ you may not use this file except in compliance with the License.
194
+ You may obtain a copy of the License at
195
+
196
+ http://www.apache.org/licenses/LICENSE-2.0
197
+
198
+ Unless required by applicable law or agreed to in writing, software
199
+ distributed under the License is distributed on an "AS IS" BASIS,
200
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201
+ See the License for the specific language governing permissions and
202
+ limitations under the License.
NOTICE ADDED
@@ -0,0 +1,25 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ Clairic for MLX
2
+
3
+ This repository is a derivative of Cloudflare's Clairic release
4
+ (https://huggingface.co/Cloudflare/clairic and https://huggingface.co/Cloudflare/clairic-flash),
5
+ Copyright 2026 Cloudflare, Inc., licensed under the Apache License, Version 2.0 (see LICENSE).
6
+ Clairic is fine-tuned from Qwen models by the Qwen Team, also released under Apache-2.0.
7
+
8
+ Changes made for this MLX port:
9
+
10
+ - The model weights were converted to the MLX format and the language model's linear layers, token embedding
11
+ and vocabulary head were quantized (see README.md for the exact recipe). The typed head
12
+ (`clair_head.safetensors`) is the upstream file, unchanged.
13
+ - `clairic_runtime/` is the upstream request pipeline with its PyTorch engine replaced:
14
+ - removed: `native.py`, `math.py`, `readout.py`, `normalization.py`, `kernels.py`, `gdn/`, `gdn_pool.py`,
15
+ `decoder_capture.py`, `decoder_graph.py`, `vision_cache.py`, `attention_metadata.py`,
16
+ `recurrent_metadata.py` (PyTorch, Triton and CUDA code);
17
+ - added: `mlx_engine.py` (MLX backbone loop, typed head, grammar-constrained decoding) and `processor.py`
18
+ (a torch-free processor);
19
+ - modified: `model.py` (typed head moved to `mlx_engine.py`; tensor code ported from PyTorch to NumPy),
20
+ `backend.py` (`media_payload` and `load`) and `__init__.py` (docstring). Each modified file says so
21
+ at its top. All other files in `clairic_runtime/` are unchanged.
22
+ - `clairic_mlx.py` replaces `clairic_model.py`; `server.py` and `convert.py` are new.
23
+
24
+ The MLX backbone uses mlx-vlm's `qwen3_5` model definition (https://github.com/Blaizzy/mlx-vlm, MIT License,
25
+ Copyright (c) Prince Canuma); the linear-attention layer loop in `mlx_engine.py` follows that implementation.
README.md ADDED
@@ -0,0 +1,243 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ---
2
+ license: apache-2.0
3
+ base_model: Cloudflare/clairic-flash
4
+ base_model_relation: quantized
5
+ library_name: mlx
6
+ pipeline_tag: image-text-to-text
7
+ tags:
8
+ - mlx
9
+ - clairic
10
+ - cloudflare
11
+ - systemone
12
+ - structured-output
13
+ - information-extraction
14
+ - multimodal
15
+ - custom-code
16
+ ---
17
+
18
+ # mlx-community/clairic-flash-4bit
19
+
20
+ An [MLX](https://github.com/ml-explore/mlx) 4-bit conversion of
21
+ [`Cloudflare/clairic-flash`](https://huggingface.co/Cloudflare/clairic-flash) for Apple Silicon, with the runtime it
22
+ needs and a small HTTP server. The larger, more accurate model of the family is at [`mlx-community/clairic-4bit`](https://huggingface.co/mlx-community/clairic-4bit).
23
+
24
+ **Clairic is a structured-extraction model, not a chat model.** Give it a *state* (text or JSON, plus optional
25
+ images or PDFs) and a schema of typed *fields*; it returns one typed value per field with a confidence and a
26
+ null probability. It also does numerical estimates and forecasts.
27
+
28
+ | Field types | Answered by |
29
+ |---|---|
30
+ | `text`, `number`, `boolean`, `enum`, `object`, and `list` items of those | grammar-constrained decoding, one short prompt per field or list item |
31
+ | `date`, `time`, `datetime`, `duration`, `compute`, `estimate`, `forecast`, date lists | a typed head that reads one forward pass |
32
+
33
+ ## Why it needs the included code
34
+
35
+ `mlx_lm.load` / `mlx_vlm.load` can load the backbone, but they **will not reproduce Clairic**:
36
+
37
+ - Answers are produced by Cloudflare's request pipeline, not by chatting: it rewrites each field into its own
38
+ prompt, constrains decoding with a grammar built from the field's schema (and, for values copied from the
39
+ document, from the document itself), scores `null`, retries, and assembles lists and tables.
40
+ - Dates, times, durations, computed numbers, estimates and forecasts come from a separate **typed head**
41
+ (`clair_head.safetensors`) applied to the backbone's hidden states.
42
+ - The upstream runtime is PyTorch with CUDA kernels. This repository keeps Cloudflare's pipeline
43
+ (`clairic_runtime/`, Apache-2.0) and replaces its engine with an MLX one (`clairic_runtime/mlx_engine.py`).
44
+ Requests and responses have the same format as upstream.
45
+
46
+ ## Quick start
47
+
48
+ Requires an Apple Silicon Mac and Python 3.11 or later (tested with 3.12). The model uses 6 GB at rest and up to 11 GB on the requests we timed (see [Speed and memory](#speed-and-memory)), so a 16 GB Mac is the practical minimum; 24 GB gives more room.
49
+
50
+ ```bash
51
+ hf download mlx-community/clairic-flash-4bit --local-dir clairic-flash-4bit
52
+ cd clairic-flash-4bit
53
+ pip install -r requirements.txt
54
+ ```
55
+
56
+ `xgrammar` (the grammar engine upstream uses) depends on PyTorch, so `pip` installs `torch`; the model itself
57
+ runs entirely in MLX.
58
+
59
+ ```python
60
+ from clairic_mlx import load, systemone
61
+
62
+ model = load(".") # or load("mlx-community/clairic-flash-4bit")
63
+ response = systemone(model, {
64
+ "state": "Invoice from Northwind Supply. Issued 2026-09-02. Items: Pens; Paper. Total: $1080.00.",
65
+ "fields": {
66
+ "vendor": {"type": "text", "instructions": "The invoice vendor."},
67
+ "total": {"type": "number", "decimals": 2},
68
+ "issued": {"type": "date"},
69
+ "items": {"type": "list", "items": "text", "instructions": "The purchased item names, in order."},
70
+ },
71
+ })
72
+ print({name: answer["value"] for name, answer in response["answers"].items()})
73
+ # {'vendor': 'Northwind Supply', 'total': 1080.0, 'issued': '2026-09-02', 'items': ['Pens', 'Paper']}
74
+ ```
75
+
76
+ Images and PDFs (up to four images or pages per request) can be PIL images, file paths or base64 data URIs:
77
+
78
+ ```python
79
+ response = systemone(model, {
80
+ "state": "Read the attached receipt.",
81
+ "images": ["receipt.png"],
82
+ "fields": {"merchant": {"type": "text"}, "total": {"type": "number", "decimals": 2}, "date": {"type": "date"}},
83
+ })
84
+ response = systemone(model, {"documents": ["invoice.pdf"], "fields": {"invoice_number": {"type": "text"}}})
85
+ ```
86
+
87
+ Estimates and forecasts return a distribution; `include_quantiles` adds the quantiles:
88
+
89
+ ```python
90
+ response = systemone(model, {
91
+ "state": "Daily demand for the last seven days: 41, 45, 43, 47, 49, 46, 48.",
92
+ "fields": {
93
+ "next_day": {"type": "estimate", "min": 0, "max": 100},
94
+ "next_three_days": {"type": "forecast", "min": 0, "max": 100, "horizon": 3, "interval": "day"},
95
+ },
96
+ "options": {"include_quantiles": True},
97
+ })
98
+ ```
99
+
100
+ Command line and server:
101
+
102
+ ```bash
103
+ python clairic_mlx.py --state "Gate B14 closes at 18:20." --fields '{"gate": {"type": "text"}, "closes": {"type": "time"}}'
104
+ python clairic_mlx.py --image receipt.png --fields '{"total": {"type": "number", "decimals": 2}}'
105
+
106
+ python server.py --port 8093
107
+ curl localhost:8093/v1/systemone -H 'content-type: application/json' -d '{
108
+ "state": "Gate B14 closes at 18:20.",
109
+ "fields": {"gate": {"type": "text"}, "closes": {"type": "time"}}}'
110
+ ```
111
+
112
+ The server answers one request at a time (a request already fans out into many batched prompts); concurrent
113
+ requests wait their turn. Set `CLAIRIC_API_KEY` to require a bearer token. In an async application use
114
+ `await model.predict_async(request)`.
115
+
116
+ The request and response format, the field options (`instructions`, `nullable`, `decimals`, `unit`, `enum`,
117
+ `source_only`, `knowledge`, `reference_date`, ...) and the limits (65k-token context, four images or PDF pages,
118
+ 4 MiB per embedded file) are those of the
119
+ [upstream model card](https://huggingface.co/Cloudflare/clairic-flash).
120
+
121
+ ## Fidelity
122
+
123
+ Tested on 81 requests with known answers: invoices, support tickets, dates and times, computed values, lists and tables, every field option, four languages, documents from 1k to 39k tokens, 13 image requests and 3 PDF requests. They contain 262 fields with exact values, plus estimates and forecasts. The reference is the official Cloudflare runtime on an NVIDIA H100 in its bfloat16 serving configuration, recorded call by call (every prompt, its output tokens and log-probabilities, and every typed-head read).
124
+
125
+ | Build | Fields with the same value | Prompts decoded to the same tokens | Typed-head reads with the same values | Mean confidence difference | Correct against known answers |
126
+ |---|---|---|---|---|---|
127
+ | Official runtime, H100 | reference | reference | reference | | 238 / 256 |
128
+ | MLX, unquantized bf16 (same code as this repo) | 261 / 262 | 1256 / 1258 | 54 / 55 | 0.005 | 238 / 256 |
129
+ | **This repo, 4-bit** | 247 / 262 | 1243 / 1258 | 51 / 55 | 0.031 | 231 / 256 |
130
+
131
+ The unquantized MLX build reproduces the official run almost exactly. **4-bit costs this 9B model some accuracy:** 15 of 262 fields differ from the official run, and 7 fewer answers are correct. The typical error is a misread character in a number or identifier, often one read from an image or PDF (`2231.5` for `2231.25`, `KR-2026-187` for `KR-2026-1187`). Estimate and forecast summaries differ from the official run by 7.8% on average. [`mlx-community/clairic-4bit`](https://huggingface.co/mlx-community/clairic-4bit), the 27B model, loses almost nothing at 4-bit.
132
+
133
+ If you have the memory, a higher-precision build of Flash is closer to the original. On the 77 requests of the suite without the longest documents:
134
+
135
+ | Build (size) | Fields with the same value | Prompts decoded to the same tokens | Typed-head reads with the same values | Mean confidence difference | Correct against known answers |
136
+ |---|---|---|---|---|---|
137
+ | Official runtime, H100 | reference | reference | reference | | 223 / 240 |
138
+ | This repo, 4-bit (6.3 GB) | 231 / 246 | 971 / 986 | 48 / 52 | 0.031 | 216 / 240 |
139
+ | Mixed: first 20 layers 6-bit, last 12 layers 4-bit (7.3 GB) | 241 / 246 | 978 / 986 | 50 / 52 | 0.016 | 223 / 240 |
140
+ | 8-bit (10.8 GB) | 246 / 246 | 985 / 986 | 51 / 52 | 0.006 | 223 / 240 |
141
+
142
+ Both can be built from the upstream checkpoint with the included script and run with the same code:
143
+
144
+ ```bash
145
+ python convert.py <upstream_checkpoint> <output_dir> --bits 4 --high 'layers\.([0-9]|1[0-9])\.' --high-bits 6 # mixed
146
+ python convert.py <upstream_checkpoint> <output_dir> --bits 8 # 8-bit
147
+ ```
148
+
149
+ The mixed recipe comes from a sensitivity test: quantizing only the last 12 of the 32 layers to 4 bits changes the output distribution no more than noise, while the first 20 account for the damage. Leaving the vocabulary head or the embeddings unquantized, or raising only the output projections to 8 bits, did not help.
150
+
151
+ **The port itself is exact.** With unquantized float32 weights on the CPU, the MLX engine agrees with the official PyTorch runtime to float32 rounding on Clairic Flash (confidences within 4e-06, token log-probabilities within 2e-06, same tokens and values on all 27 prompts and 36 fields checked). On the GPU, where MLX multiplies matrices at reduced precision, the float32 build gives the same value on 246 of 246 fields and the same tokens on 987 of 987 prompts of a 77-request run, images and PDFs included.
152
+
153
+ Confidence is a product of token probabilities, so it moves more than the answers do: 4-bit confidences differ from the official ones by 0.031 on average and by up to 0.36. Calibrate thresholds on this build rather than reusing ones tuned on the official runtime.
154
+
155
+ ## Speed and memory
156
+
157
+ MacBook Pro, M5 Max, 128 GB, macOS 27.2, mlx 0.32.4. The model loads in about 2 s and uses 6.2 GB at rest. Times are for a warm model (the first request of a new shape compiles kernels and is slower).
158
+
159
+ | Request | Fields | Prompt tokens run | Time | Peak memory |
160
+ |---|---|---|---|---|
161
+ | short text, 1 generated field | 1 | 131 | 0.1 s | 6.7 GB |
162
+ | short text, 1 typed field (date) | 1 | 207 | 0.1 s | 6.7 GB |
163
+ | short text, 8 fields | 8 | 1,733 | 1.4 s | 8.1 GB |
164
+ | 1000-token document, 1 field | 1 | 1,155 | 0.7 s | 7.6 GB |
165
+ | 1000-token document, 8 fields | 8 | 11,743 | 6.0 s | 8.4 GB |
166
+ | 4000-token document, 1 field | 1 | 4,155 | 2.1 s | 7.8 GB |
167
+ | 4000-token document, 8 fields | 8 | 41,743 | 20.5 s | 7.8 GB |
168
+ | 8000-token document, 1 field | 1 | 8,155 | 4.1 s | 8.1 GB |
169
+ | 8000-token document, 8 fields | 8 | 81,743 | 40.5 s | 8.2 GB |
170
+ | 16000-token document, 1 field | 1 | 16,157 | 8.6 s | 9.4 GB |
171
+ | 32000-token document, 1 field | 1 | 32,156 | 19.2 s | 10.6 GB |
172
+ | receipt image, 3 fields | 3 | 2,698 | 2.1 s | 7.6 GB |
173
+ | invoice image, 8 fields incl. line items | 8 | 42,541 | 8.7 s | 9.1 GB |
174
+ | two images, 4 fields | 4 | 5,163 | 1.4 s | 7.7 GB |
175
+ | 2-page PDF, 3 fields | 3 | 3,629 | 1.2 s | 7.6 GB |
176
+ | CSV table, 5 rows x 3 columns | 1 | 26,955 | 14.1 s | 8.4 GB |
177
+ | 18-row table, 3 columns | 1 | 145,102 | 71.1 s | 8.5 GB |
178
+ | forecast (3 steps) + estimate | 2 | 421 | 0.2 s | 7.0 GB |
179
+
180
+ "Prompt tokens run" is the total over all of a request's prompts: each generated field or list item is its own prompt and re-reads the document, so a request costs roughly *fields x document length*. Typed fields (dates, times, estimates, forecasts) share one pass. Images are read once per request and reused by every field. Inputs longer than 1,024 tokens are processed in segments, so memory grows slowly with length: the 32k-token document peaks at 10.6 GB.
181
+
182
+ `load(path, memory_limit_gb=...)` sets a ceiling (default: 75% of the machine's memory) above which a request fails with an error instead of exhausting memory. `batch_size` (8) and `batch_token_budget` (8192) control how many prompts run together; larger values were not faster in our tests.
183
+
184
+ ## How it was converted
185
+
186
+ `convert.py` (included) reproduces these weights from the upstream checkpoint
187
+ (revision `36ad68b999560f56b57ef16a22180f8cb83c6d77`):
188
+
189
+ ```bash
190
+ python convert.py <upstream_checkpoint> <output_dir> --bits 4 --keep in_proj_a,in_proj_b
191
+ ```
192
+
193
+ - Language model: linear layers, token embedding and vocabulary head quantized to 4 bits (affine, group size 64), 4.5 bits per weight.
194
+ - Left in bf16: the vision tower, the Gated DeltaNet gate projections (`in_proj_a`, `in_proj_b`: 0.07% of the weights), convolutions and decay parameters.
195
+ - RMSNorm weights are stored as exact float32 `1 + w` and evaluated in float32.
196
+ - The typed head is the upstream float32 file, with its weights rounded through bfloat16 at load as upstream's serving path does.
197
+ - The unused `mtp.*` draft-head weights are dropped.
198
+
199
+ ## Differences from the upstream runtime
200
+
201
+ - **Engine.** MLX instead of PyTorch/CUDA. The CUDA-only accelerations (Triton kernels, CUDA graphs,
202
+ FlashAttention-3) are not needed and not included.
203
+ - **Image position encoding.** Upstream has two code paths that treat image tokens differently: in bfloat16
204
+ (its serving configuration, and what it does by default on a GPU) every token of an image gets the same
205
+ rotary position, while in float32 it uses the stock Qwen 3-axis positions. This port defaults to the first
206
+ (`load(path, rope="temporal")`) and also offers the second (`rope="mrope"`). Text-only requests are
207
+ unaffected. Upstream's two paths, which also differ in numeric precision, give the same value on 250 of 252 fields of Clairic Flash on an H100, and this port reproduces each of them with the matching setting.
208
+ - **Images are read once per request.** Upstream re-reads the image tokens for every field's prompt. Attention
209
+ is causal and the linear layers are recurrent, so the engine runs the shared image prefix once and continues
210
+ each prompt from that state. Results are the same up to floating-point rounding; requests with images and
211
+ many fields are much faster.
212
+ - **Image resizing** uses PIL instead of torchvision; pixel values differ from upstream by at most about 2/255.
213
+ - **No PyTorch in the model path.** The typed head runs in MLX and its decoding in NumPy (ported from PyTorch
214
+ and checked against it; see `NOTICE`).
215
+
216
+ ## Limitations
217
+
218
+ - 4-bit quantization costs this model some accuracy, mainly on numbers and identifiers read from images (see Fidelity), and shifts confidences. Use the 27B model or a higher-precision build when that matters.
219
+ - Speed scales with fields x document length: every generated field re-reads the document, as upstream does.
220
+ Long documents with many fields take minutes (see the table above).
221
+ - On the M5 Max we tested (mlx 0.32.4), MLX's GPU matrix multiply is accurate to about 1e-3 even for float32
222
+ inputs, so results are not bit-identical to PyTorch (see Fidelity). `load(path, device="cpu")` is accurate to float32
223
+ rounding and very slow; it exists for verification.
224
+ - Scores are model probabilities. Check `p_null`, `confidence`, `valid`, `complete` and `truncated` before
225
+ relying on an answer, as the upstream card advises.
226
+ - Not tested: requests close to the 65k-token limit.
227
+
228
+ ## Files
229
+
230
+ | File | Purpose |
231
+ |---|---|
232
+ | `model-*.safetensors`, `model.safetensors.index.json`, `config.json` | MLX weights (quantized language model, bf16 vision tower) and configuration |
233
+ | `clair_head.safetensors`, `clair_head_config.json` | The typed head, unchanged from upstream (fp32) |
234
+ | `clairic_mlx.py` | `load`, `systemone`, and the command line |
235
+ | `clairic_runtime/` | Cloudflare's request pipeline with the MLX engine (`mlx_engine.py`, `processor.py`) |
236
+ | `server.py` | HTTP server: `POST /v1/systemone`, `GET /v1/models`, `/health`, `/stats` |
237
+ | `convert.py` | The conversion script |
238
+ | tokenizer and processor files, `requirements.txt`, `LICENSE`, `NOTICE` | As named |
239
+
240
+ ## License
241
+
242
+ Apache-2.0, as upstream. `clairic_runtime/` is Cloudflare's code with the changes listed in `NOTICE`. The
243
+ backbone uses [mlx-vlm](https://github.com/Blaizzy/mlx-vlm)'s `qwen3_5` model definition.
chat_template.jinja ADDED
@@ -0,0 +1,154 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {%- set image_count = namespace(value=0) %}
2
+ {%- set video_count = namespace(value=0) %}
3
+ {%- macro render_content(content, do_vision_count, is_system_content=false) %}
4
+ {%- if content is string %}
5
+ {{- content }}
6
+ {%- elif content is iterable and content is not mapping %}
7
+ {%- for item in content %}
8
+ {%- if 'image' in item or 'image_url' in item or item.type == 'image' %}
9
+ {%- if is_system_content %}
10
+ {{- raise_exception('System message cannot contain images.') }}
11
+ {%- endif %}
12
+ {%- if do_vision_count %}
13
+ {%- set image_count.value = image_count.value + 1 %}
14
+ {%- endif %}
15
+ {%- if add_vision_id %}
16
+ {{- 'Picture ' ~ image_count.value ~ ': ' }}
17
+ {%- endif %}
18
+ {{- '<|vision_start|><|image_pad|><|vision_end|>' }}
19
+ {%- elif 'video' in item or item.type == 'video' %}
20
+ {%- if is_system_content %}
21
+ {{- raise_exception('System message cannot contain videos.') }}
22
+ {%- endif %}
23
+ {%- if do_vision_count %}
24
+ {%- set video_count.value = video_count.value + 1 %}
25
+ {%- endif %}
26
+ {%- if add_vision_id %}
27
+ {{- 'Video ' ~ video_count.value ~ ': ' }}
28
+ {%- endif %}
29
+ {{- '<|vision_start|><|video_pad|><|vision_end|>' }}
30
+ {%- elif 'text' in item %}
31
+ {{- item.text }}
32
+ {%- else %}
33
+ {{- raise_exception('Unexpected item type in content.') }}
34
+ {%- endif %}
35
+ {%- endfor %}
36
+ {%- elif content is none or content is undefined %}
37
+ {{- '' }}
38
+ {%- else %}
39
+ {{- raise_exception('Unexpected content type.') }}
40
+ {%- endif %}
41
+ {%- endmacro %}
42
+ {%- if not messages %}
43
+ {{- raise_exception('No messages provided.') }}
44
+ {%- endif %}
45
+ {%- if tools and tools is iterable and tools is not mapping %}
46
+ {{- '<|im_start|>system\n' }}
47
+ {{- "# Tools\n\nYou have access to the following functions:\n\n<tools>" }}
48
+ {%- for tool in tools %}
49
+ {{- "\n" }}
50
+ {{- tool | tojson }}
51
+ {%- endfor %}
52
+ {{- "\n</tools>" }}
53
+ {{- '\n\nIf you choose to call a function ONLY reply in the following format with NO suffix:\n\n<tool_call>\n<function=example_function_name>\n<parameter=example_parameter_1>\nvalue_1\n</parameter>\n<parameter=example_parameter_2>\nThis is the value for the second parameter\nthat can span\nmultiple lines\n</parameter>\n</function>\n</tool_call>\n\n<IMPORTANT>\nReminder:\n- Function calls MUST follow the specified format: an inner <function=...></function> block must be nested within <tool_call></tool_call> XML tags\n- Required parameters MUST be specified\n- You may provide optional reasoning for your function call in natural language BEFORE the function call, but NOT after\n- If there is no function call available, answer the question like normal with your current knowledge and do not tell the user about function calls\n</IMPORTANT>' }}
54
+ {%- if messages[0].role == 'system' %}
55
+ {%- set content = render_content(messages[0].content, false, true)|trim %}
56
+ {%- if content %}
57
+ {{- '\n\n' + content }}
58
+ {%- endif %}
59
+ {%- endif %}
60
+ {{- '<|im_end|>\n' }}
61
+ {%- else %}
62
+ {%- if messages[0].role == 'system' %}
63
+ {%- set content = render_content(messages[0].content, false, true)|trim %}
64
+ {{- '<|im_start|>system\n' + content + '<|im_end|>\n' }}
65
+ {%- endif %}
66
+ {%- endif %}
67
+ {%- set ns = namespace(multi_step_tool=true, last_query_index=messages|length - 1) %}
68
+ {%- for message in messages[::-1] %}
69
+ {%- set index = (messages|length - 1) - loop.index0 %}
70
+ {%- if ns.multi_step_tool and message.role == "user" %}
71
+ {%- set content = render_content(message.content, false)|trim %}
72
+ {%- if not(content.startswith('<tool_response>') and content.endswith('</tool_response>')) %}
73
+ {%- set ns.multi_step_tool = false %}
74
+ {%- set ns.last_query_index = index %}
75
+ {%- endif %}
76
+ {%- endif %}
77
+ {%- endfor %}
78
+ {%- if ns.multi_step_tool %}
79
+ {{- raise_exception('No user query found in messages.') }}
80
+ {%- endif %}
81
+ {%- for message in messages %}
82
+ {%- set content = render_content(message.content, true)|trim %}
83
+ {%- if message.role == "system" %}
84
+ {%- if not loop.first %}
85
+ {{- raise_exception('System message must be at the beginning.') }}
86
+ {%- endif %}
87
+ {%- elif message.role == "user" %}
88
+ {{- '<|im_start|>' + message.role + '\n' + content + '<|im_end|>' + '\n' }}
89
+ {%- elif message.role == "assistant" %}
90
+ {%- set reasoning_content = '' %}
91
+ {%- if message.reasoning_content is string %}
92
+ {%- set reasoning_content = message.reasoning_content %}
93
+ {%- else %}
94
+ {%- if '</think>' in content %}
95
+ {%- set reasoning_content = content.split('</think>')[0].rstrip('\n').split('<think>')[-1].lstrip('\n') %}
96
+ {%- set content = content.split('</think>')[-1].lstrip('\n') %}
97
+ {%- endif %}
98
+ {%- endif %}
99
+ {%- set reasoning_content = reasoning_content|trim %}
100
+ {%- if loop.index0 > ns.last_query_index %}
101
+ {{- '<|im_start|>' + message.role + '\n<think>\n' + reasoning_content + '\n</think>\n\n' + content }}
102
+ {%- else %}
103
+ {{- '<|im_start|>' + message.role + '\n' + content }}
104
+ {%- endif %}
105
+ {%- if message.tool_calls and message.tool_calls is iterable and message.tool_calls is not mapping %}
106
+ {%- for tool_call in message.tool_calls %}
107
+ {%- if tool_call.function is defined %}
108
+ {%- set tool_call = tool_call.function %}
109
+ {%- endif %}
110
+ {%- if loop.first %}
111
+ {%- if content|trim %}
112
+ {{- '\n\n<tool_call>\n<function=' + tool_call.name + '>\n' }}
113
+ {%- else %}
114
+ {{- '<tool_call>\n<function=' + tool_call.name + '>\n' }}
115
+ {%- endif %}
116
+ {%- else %}
117
+ {{- '\n<tool_call>\n<function=' + tool_call.name + '>\n' }}
118
+ {%- endif %}
119
+ {%- if tool_call.arguments is defined %}
120
+ {%- for args_name, args_value in tool_call.arguments|items %}
121
+ {{- '<parameter=' + args_name + '>\n' }}
122
+ {%- set args_value = args_value | tojson | safe if args_value is mapping or (args_value is sequence and args_value is not string) else args_value | string %}
123
+ {{- args_value }}
124
+ {{- '\n</parameter>\n' }}
125
+ {%- endfor %}
126
+ {%- endif %}
127
+ {{- '</function>\n</tool_call>' }}
128
+ {%- endfor %}
129
+ {%- endif %}
130
+ {{- '<|im_end|>\n' }}
131
+ {%- elif message.role == "tool" %}
132
+ {%- if loop.previtem and loop.previtem.role != "tool" %}
133
+ {{- '<|im_start|>user' }}
134
+ {%- endif %}
135
+ {{- '\n<tool_response>\n' }}
136
+ {{- content }}
137
+ {{- '\n</tool_response>' }}
138
+ {%- if not loop.last and loop.nextitem.role != "tool" %}
139
+ {{- '<|im_end|>\n' }}
140
+ {%- elif loop.last %}
141
+ {{- '<|im_end|>\n' }}
142
+ {%- endif %}
143
+ {%- else %}
144
+ {{- raise_exception('Unexpected message role.') }}
145
+ {%- endif %}
146
+ {%- endfor %}
147
+ {%- if add_generation_prompt %}
148
+ {{- '<|im_start|>assistant\n' }}
149
+ {%- if enable_thinking is defined and enable_thinking is false %}
150
+ {{- '<think>\n\n</think>\n\n' }}
151
+ {%- else %}
152
+ {{- '<think>\n' }}
153
+ {%- endif %}
154
+ {%- endif %}
clair_head.safetensors ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ version https://git-lfs.github.com/spec/v1
2
+ oid sha256:68a7b269b7fe833ac521010b5236c25bfe9463ec60a01e5f82512619b89002af
3
+ size 261485564
clair_head_config.json ADDED
@@ -0,0 +1,16 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "hidden_size": 4096,
3
+ "bins": 256,
4
+ "pointer_width": 256,
5
+ "readout": "lexical",
6
+ "route_width": 1024,
7
+ "route_layers": 2,
8
+ "route_heads": 8,
9
+ "slot_rank": 32,
10
+ "estimate_lexical": true,
11
+ "span_trim": true,
12
+ "answer_slots": true,
13
+ "answer_slot_routing": true,
14
+ "number_groups": true,
15
+ "number_pointer": true
16
+ }
clairic_mlx.py ADDED
@@ -0,0 +1,144 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Clairic on Apple silicon: load an MLX Clairic folder and answer System One: Extract requests.
2
+
3
+ from clairic_mlx import load, systemone
4
+ model = load("mlx-community/clairic-flash-4bit")
5
+ response = systemone(model, {"state": "...", "fields": {"total": {"type": "number", "decimals": 2}}})
6
+
7
+ Command line:
8
+ python clairic_mlx.py --state "Invoice total: $1,080.00, issued 2026-09-02." \\
9
+ --fields '{"total": {"type": "number", "decimals": 2}, "issued": {"type": "date"}}'
10
+
11
+ This mirrors `clairic_model.py` in the Cloudflare release (same request and response format); the request
12
+ pipeline in `clairic_runtime/` is upstream's, with its PyTorch engine replaced by `clairic_runtime/mlx_engine.py`.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ import argparse
18
+ import asyncio
19
+ import base64
20
+ import io
21
+ import json
22
+ import sys
23
+ from collections.abc import Mapping
24
+ from pathlib import Path
25
+ from typing import Any
26
+
27
+ sys.path.insert(0, str(Path(__file__).resolve().parent))
28
+
29
+ from clairic_runtime.api import PredictRequest, serialize_response # noqa: E402
30
+ from clairic_runtime.backend import ClairicFlashModel # noqa: E402
31
+ from clairic_runtime.errors import ClairRequestError # noqa: E402
32
+ from clairic_runtime.large import Clairic27BModel # noqa: E402
33
+ from clairic_runtime.settings import RuntimeSettings # noqa: E402
34
+
35
+
36
+ def _request(value: Mapping[str, Any] | PredictRequest) -> PredictRequest:
37
+ """Accept PIL images, file paths and JSON-like states, as the upstream helper does."""
38
+ if isinstance(value, PredictRequest):
39
+ return value
40
+ from PIL import Image, ImageOps
41
+
42
+ request = dict(value)
43
+ if "state" in request and not isinstance(request["state"], str):
44
+ request["state"] = json.dumps(request["state"], ensure_ascii=False)
45
+ images = request.get("images")
46
+ if isinstance(images, (list, tuple)):
47
+ images = list(images)
48
+ for index, image in enumerate(images):
49
+ if isinstance(image, (str, Path)) and not str(image).startswith("data:") and Path(image).is_file():
50
+ image = Image.open(image)
51
+ if isinstance(image, Image.Image):
52
+ buffer = io.BytesIO()
53
+ ImageOps.exif_transpose(image).convert("RGBA").save(buffer, format="PNG")
54
+ images[index] = "data:image/png;base64," + base64.b64encode(buffer.getvalue()).decode("ascii")
55
+ request["images"] = images
56
+ documents = request.get("documents")
57
+ if isinstance(documents, (list, tuple)):
58
+ request["documents"] = [
59
+ "data:application/pdf;base64," + base64.b64encode(Path(document).read_bytes()).decode("ascii")
60
+ if isinstance(document, (str, Path)) and not str(document).startswith("data:") and Path(document).is_file()
61
+ else document
62
+ for document in documents
63
+ ]
64
+ return PredictRequest.model_validate(request)
65
+
66
+
67
+ class ClairicModel:
68
+ """An MLX Clairic model with synchronous and async prediction."""
69
+
70
+ def __init__(self, runtime: ClairicFlashModel, public_name: str) -> None:
71
+ self.runtime = runtime
72
+ self.model_id = public_name
73
+ names = {public_name, runtime.model_id}
74
+ self._model_selectors = names | {"@cf/cloudflare/" + name for name in names}
75
+ self.processor = runtime.processor
76
+ self.engine = runtime.engine
77
+
78
+ async def predict_async(self, request: Mapping[str, Any] | PredictRequest) -> dict[str, Any]:
79
+ validated = _request(request)
80
+ if validated.model is not None and validated.model not in self._model_selectors:
81
+ raise ClairRequestError(f"Unsupported model '{validated.model}'. Use '{self.model_id}'.")
82
+ output = await self.runtime.predict_async(validated)
83
+ return serialize_response(validated, output, self.model_id)
84
+
85
+ def predict(self, request: Mapping[str, Any] | PredictRequest) -> dict[str, Any]:
86
+ """Return structured values and scores for a System One: Extract request."""
87
+ try:
88
+ asyncio.get_running_loop()
89
+ except RuntimeError:
90
+ return asyncio.run(self.predict_async(request))
91
+ raise RuntimeError("Use await model.predict_async(request) inside an active event loop")
92
+
93
+ def close(self) -> None:
94
+ self.runtime.shutdown()
95
+
96
+
97
+ def load(model_path: str | Path, max_length: int = 65_273, **engine_kwargs: Any) -> ClairicModel:
98
+ """Load a local MLX Clairic folder or a Hugging Face repository."""
99
+ path = Path(model_path)
100
+ if not path.is_dir():
101
+ from huggingface_hub import snapshot_download
102
+
103
+ path = Path(snapshot_download(str(model_path)))
104
+ large = int(json.loads((path / "clair_head_config.json").read_text())["hidden_size"]) == 5120
105
+ settings = RuntimeSettings(model_path=str(path), version="1", model_id="clairic-27b" if large else "clairic-flash",
106
+ max_length=max_length, max_concurrency=1)
107
+ # The exact upstream classes: parts of the pipeline switch on `type(self)`.
108
+ runtime = (Clairic27BModel if large else ClairicFlashModel).load(settings, **engine_kwargs)
109
+ return ClairicModel(runtime, "clairic" if large else "clairic-flash")
110
+
111
+
112
+ def systemone(model: ClairicModel, request: Mapping[str, Any] | PredictRequest) -> dict[str, Any]:
113
+ """Answer a System One: Extract request with typed fields and confidence."""
114
+ return model.predict(request)
115
+
116
+
117
+ def main() -> None:
118
+ ap = argparse.ArgumentParser(description="Clairic structured extraction with MLX")
119
+ ap.add_argument("--model", default=str(Path(__file__).resolve().parent))
120
+ ap.add_argument("--state", default="")
121
+ ap.add_argument("--fields", required=True, help="JSON mapping of field names to specifications")
122
+ ap.add_argument("--image", action="append", default=[], help="image file (repeatable)")
123
+ ap.add_argument("--document", action="append", default=[], help="PDF file (repeatable)")
124
+ ap.add_argument("--reference-date", default=None)
125
+ ap.add_argument("--quantiles", action="store_true")
126
+ args = ap.parse_args()
127
+ request: dict[str, Any] = {"state": args.state, "fields": json.loads(args.fields)}
128
+ if args.image:
129
+ request["images"] = args.image
130
+ if args.document:
131
+ request["documents"] = args.document
132
+ if args.reference_date:
133
+ request["reference_date"] = args.reference_date
134
+ if args.quantiles:
135
+ request["options"] = {"include_quantiles": True}
136
+ model = load(args.model)
137
+ try:
138
+ print(json.dumps(systemone(model, request), indent=2, ensure_ascii=False))
139
+ finally:
140
+ model.close()
141
+
142
+
143
+ if __name__ == "__main__":
144
+ main()
clairic_runtime/__init__.py ADDED
@@ -0,0 +1,6 @@
 
 
 
 
 
 
 
1
+ """Clairic inference with MLX (the Cloudflare release, with its Transformers engine replaced; see NOTICE)."""
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,1728 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Modified from the Cloudflare Clairic release (Apache-2.0) for the MLX port:
2
+ # - `media_payload` keeps pixel values as NumPy arrays (rounded through bfloat16, as upstream does) and adds
3
+ # a content key for the engine's per-request image-feature cache;
4
+ # - `load` builds the MLX engine (`mlx_engine.py`) and the torch-free processor (`processor.py`) instead of
5
+ # the PyTorch engine and the Transformers processor, and takes engine options instead of device / dtype.
6
+ # Everything else is unchanged.
7
+ from __future__ import annotations
8
+ from collections.abc import Callable, Collection, Sequence
9
+ from typing import TYPE_CHECKING
10
+
11
+ if TYPE_CHECKING:
12
+ from .api import ClairImage
13
+ from .documents import ClairDocument
14
+ from PIL import Image
15
+ import asyncio
16
+ import concurrent.futures
17
+ import json
18
+ import logging
19
+ import math
20
+ import uuid
21
+ from decimal import Decimal
22
+ from pathlib import Path
23
+ from typing import Any, cast
24
+ from .api import MAX_IMAGES, PredictOutput, PredictRequest
25
+ from .errors import ClairInferenceError, ClairQueueFull, ClairRequestError
26
+ from .settings import RuntimeSettings
27
+ from . import (
28
+ MAX_OUTPUT_TOKENS,
29
+ ar,
30
+ batch_completion,
31
+ contracts,
32
+ entity_scope,
33
+ financial_scope,
34
+ grounding,
35
+ identifier_scope,
36
+ identifier_spelling,
37
+ image_financial_lines,
38
+ image_focus,
39
+ image_identifier,
40
+ image_party_names,
41
+ image_ragged_rows,
42
+ image_rows,
43
+ image_table_rows,
44
+ ordinary_list_completion,
45
+ pdf_number_focus,
46
+ printed_numbers,
47
+ printed_temporal,
48
+ receipt_totals,
49
+ row_omission,
50
+ source_dates,
51
+ source_rows,
52
+ table_rows,
53
+ )
54
+ from . import lists as extraction
55
+ from . import model as cm
56
+ from . import schema as zs
57
+ from .media_cache import ImageCache
58
+ from .media import batch_image_data, media_warmup_groups
59
+
60
+ if TYPE_CHECKING:
61
+ MediaPayload = list[dict[str, Any]]
62
+ ARTask = tuple[str, list[int], MediaPayload | None]
63
+ EncodedRequest = tuple[
64
+ dict[str, Any], dict[str, list[str]], list[ARTask], cm.EncodedRecord | None, int
65
+ ]
66
+ logger = logging.getLogger(__name__)
67
+
68
+
69
+ def common_prefix(tasks: Sequence[ARTask]) -> list[int]:
70
+ (first, last) = (min((t[1] for t in tasks)), max((t[1] for t in tasks)))
71
+ length = next(
72
+ (i for (i, (a, b)) in enumerate(zip(first, last)) if a != b),
73
+ min(len(first), len(last)),
74
+ )
75
+ return first[:length]
76
+
77
+
78
+ def expand_request(
79
+ request: PredictRequest,
80
+ *,
81
+ date_role_guidance: bool = True,
82
+ source_row_eligibility: bool = False,
83
+ local_scoped_pairs: bool = False,
84
+ fee_guidance: bool = False,
85
+ service_guidance: bool = False,
86
+ literal_payment_rows: bool = False,
87
+ ) -> tuple[dict[str, Any], dict[str, list[str]]]:
88
+ contracts.validate_public_fields(request.fields)
89
+ (fields, forecasts) = zs.expand_forecasts(
90
+ financial_scope.prepare(
91
+ request.fields,
92
+ has_media=bool(request.images or request.documents),
93
+ fee_guidance=fee_guidance,
94
+ service_guidance=service_guidance,
95
+ )
96
+ )
97
+ zs.validate_fields(fields)
98
+ zs.validate_reference_date(request.reference_date)
99
+ fields = {n: dict(s) for (n, s) in fields.items()}
100
+ for spec in fields.values():
101
+ if date_role_guidance and spec["type"] == "date":
102
+ instructions = spec.get("instructions", "")
103
+ spec["instructions"] = (
104
+ (instructions + "\n" if instructions else "")
105
+ + "Follow field instructions. Match the requested date role; null if unavailable."
106
+ )
107
+ annotations: dict[str, dict[str, Any]] = {}
108
+ row_inputs: dict[str, str]
109
+ row_names: dict[str, str]
110
+ (row_inputs, row_names) = ({}, {})
111
+ source_tables = table_rows.prepare(
112
+ request.state,
113
+ fields,
114
+ has_media=bool(request.images or request.documents),
115
+ allow_scoped_pairs=source_row_eligibility or local_scoped_pairs,
116
+ )
117
+ for name, spec in list(fields.items()):
118
+ if spec["type"] != "list":
119
+ continue
120
+ source_candidates = source_tables.get(name)
121
+ row_eligibility = source_row_eligibility or any(
122
+ (row.get("eligibility_only") for row in source_candidates or [])
123
+ )
124
+ budget = (
125
+ len(source_candidates)
126
+ if source_candidates
127
+ else zs.MAX_LIST_ITEMS + 1
128
+ if (request.images or request.documents) and "max_items" not in spec
129
+ else extraction.list_query_budget(request.state, spec)[0]
130
+ )
131
+ queries = []
132
+ item_spec = contracts.item_spec(spec)
133
+ for index in range(1, budget + 1):
134
+ child = zs.list_item_name(name, index)
135
+ if child in fields:
136
+ raise ValueError("Generated list field conflicts with " + child)
137
+ fields[child] = {
138
+ k: v
139
+ for (k, v) in spec.items()
140
+ if k not in {"type", "items", "instructions", "max_items"}
141
+ }
142
+ fields[child].update(item_spec)
143
+ fields[child].update(
144
+ type=item_spec["type"],
145
+ instructions=(
146
+ f"Item {index} of {name}, following requested order and duplicate policy. "
147
+ + spec.get("instructions", "")
148
+ + " Return null if this item does not exist."
149
+ ).strip(),
150
+ )
151
+ if source_candidates:
152
+ fields[child] = table_rows.row_spec(
153
+ spec, source_candidates[index - 1], eligibility=row_eligibility
154
+ )
155
+ if item_spec["type"] in ("text", "number", "object") and (
156
+ not (source_candidates and row_eligibility)
157
+ ):
158
+ fields[child]["nullable"] = True
159
+ if "enum" in fields[child] and None not in fields[child]["enum"]:
160
+ fields[child]["enum"] = [*fields[child]["enum"], None]
161
+ annotations[child] = {"parent": name, "index": index}
162
+ queries.append(child)
163
+ annotations[name] = (
164
+ {
165
+ "source_fields": queries,
166
+ "source_rows": source_candidates,
167
+ "source_row_eligibility": row_eligibility,
168
+ }
169
+ if source_candidates
170
+ else {"query_fields": queries}
171
+ )
172
+ if local_scoped_pairs and source_candidates:
173
+ (inputs, names) = table_rows.local_scope_context(
174
+ source_candidates, queries, offset=len(row_names)
175
+ )
176
+ row_inputs.update(inputs)
177
+ row_names.update(names)
178
+ (fields, temporal_kinds) = printed_temporal.prepare(fields)
179
+ payments = (
180
+ printed_numbers.payment_lists(request.fields)
181
+ if literal_payment_rows and (request.images or request.documents)
182
+ else []
183
+ )
184
+ payment_rows = [
185
+ child
186
+ for parent in payments
187
+ for child in annotations.get(parent, {}).get("query_fields", ())
188
+ ]
189
+ (fields, number_contracts) = printed_numbers.prepare(
190
+ fields, payment_rows=payment_rows
191
+ )
192
+ meta = {
193
+ "category": "extraction",
194
+ "construction": zs.EVIDENCE_CONSTRUCTION,
195
+ "extraction_contract": {"fields": annotations},
196
+ "printed_temporal": temporal_kinds,
197
+ "printed_numbers": number_contracts,
198
+ }
199
+ return (
200
+ {
201
+ "input": request.state,
202
+ "fields": fields,
203
+ "reference_date": request.reference_date,
204
+ "_meta": meta,
205
+ "_source_row_inputs": row_inputs,
206
+ "_source_row_names": row_names,
207
+ "_source_row_gates": [
208
+ query
209
+ for annotation in annotations.values()
210
+ if annotation.get("source_row_eligibility")
211
+ for query in annotation["source_fields"]
212
+ ],
213
+ },
214
+ forecasts,
215
+ )
216
+
217
+
218
+ def typed_readout_record(
219
+ request: PredictRequest,
220
+ record: dict[str, Any],
221
+ *,
222
+ automatic_temporal: dict[str, dict[str, Any]] | None = None,
223
+ **expand_options: Any,
224
+ ) -> dict[str, Any] | None:
225
+ typed = ar.typed_record(record)
226
+ if typed is None or not automatic_temporal:
227
+ return typed
228
+ original = request.model_copy(
229
+ update={"fields": {**request.fields, **automatic_temporal}}
230
+ )
231
+ (original_record, _) = expand_request(original, **expand_options)
232
+ return ar.typed_record(original_record)
233
+
234
+
235
+ def scalar_result(
236
+ result: dict[str, Any],
237
+ spec: dict[str, Any],
238
+ tokenizer: Any,
239
+ source: str | None = None,
240
+ evidence: grounding.Source | None = None,
241
+ *,
242
+ excluded_token_id: int | None = None,
243
+ provenance: grounding.Source | None = None,
244
+ ) -> dict[str, Any]:
245
+ from jsonschema import Draft202012Validator, ValidationError
246
+
247
+ meta = result.get("meta_info", {})
248
+ finish = meta.get("finish_reason", {}) or {}
249
+ eos = tokenizer.convert_tokens_to_ids(ar.EOS)
250
+ complete = finish.get("type") == "stop" and finish.get("matched") == eos
251
+ ids = result.get("output_ids")
252
+ if ids is not None:
253
+ ids = ids[:-1] if ids and ids[-1] == eos else ids
254
+ raw = tokenizer.decode(
255
+ ids, skip_special_tokens=False, clean_up_tokenization_spaces=False
256
+ )
257
+ else:
258
+ raw = result.get("text", "")
259
+ if complete and raw.endswith(ar.EOS):
260
+ raw = raw[: -len(ar.EOS)]
261
+ raw = raw.strip()
262
+ value = None
263
+ valid = False
264
+ span = None
265
+ failure_reason = None
266
+ if complete:
267
+ try:
268
+ value = json.loads(
269
+ raw, parse_constant=lambda s: (_ for _ in ()).throw(ValueError(s))
270
+ )
271
+ Draft202012Validator(ar.schema(spec)).validate(value)
272
+ if isinstance(value, float) and (not math.isfinite(value)):
273
+ raise ValueError("Nonfinite number")
274
+ if value is not None and evidence is not None:
275
+ literal = json.loads(raw, parse_float=Decimal, parse_int=Decimal)
276
+ (found, span) = (
277
+ evidence.span(literal, spec=spec)
278
+ if getattr(evidence, "normalize_whitespace", False)
279
+ else evidence.span(literal)
280
+ )
281
+ if not found:
282
+ failure_reason = "not_in_source"
283
+ raise ValueError("AR extraction is not a literal source value")
284
+ decimals = zs.allowed_decimals(spec) if spec["type"] == "number" else None
285
+ if value is not None and decimals is not None:
286
+ literal = json.loads(raw, parse_float=Decimal, parse_int=Decimal)
287
+ value = ar.normalize_number(literal, spec)
288
+ Draft202012Validator(ar.schema(spec)).validate(value)
289
+ if value is not None and spec["type"] == "object":
290
+ precise = json.loads(raw, parse_float=Decimal, parse_int=Decimal)
291
+ value = {
292
+ name: ar.normalize_number(precise[name], child)
293
+ if child["type"] == "number"
294
+ else value[name]
295
+ for (name, child) in spec["properties"].items()
296
+ }
297
+ Draft202012Validator(ar.schema(spec)).validate(value)
298
+ valid = True
299
+ except (ValueError, TypeError, ValidationError):
300
+ value = None
301
+ prediction = {
302
+ "value": value,
303
+ "valid": valid,
304
+ "complete": complete,
305
+ "decoder": ar.VERSION,
306
+ "tokens": int(meta.get("completion_tokens", 0)),
307
+ "raw": raw,
308
+ "span": span if valid else None,
309
+ }
310
+ if failure_reason is not None:
311
+ prediction["failure_reason"] = failure_reason
312
+ if valid and evidence is not None and (value is not None):
313
+ prediction["grounding_method"] = "literal_source"
314
+ if span is not None:
315
+ prediction["span_method"] = "unique_literal_match"
316
+ if (
317
+ getattr(evidence, "normalize_whitespace", False)
318
+ and isinstance(value, str)
319
+ and (value not in evidence.text)
320
+ ):
321
+ prediction["grounding_method"] = "whitespace_normalized_source"
322
+ if span is not None:
323
+ prediction["span_method"] = "unique_whitespace_normalized_match"
324
+ token_logprobs = meta.get("output_token_logprobs")
325
+ null_scores = meta.get("output_token_ids_logprobs")
326
+ if excluded_token_id is not None:
327
+ score = (
328
+ next(
329
+ (
330
+ float(token[0])
331
+ for token in null_scores[0]
332
+ if token[1] == excluded_token_id
333
+ ),
334
+ None,
335
+ )
336
+ if null_scores
337
+ else None
338
+ )
339
+ if score is None or math.isnan(score) or score > 1e-06:
340
+ raise ValueError(
341
+ "Transformers omitted a valid row-exclusion log probability"
342
+ )
343
+ prediction.update(
344
+ p_excluded=math.exp(min(0.0, score)),
345
+ p_excluded_method="ar_first_token_false_probability",
346
+ )
347
+ if not spec.get("nullable", True):
348
+ prediction.update(p_null=0.0, p_null_method="schema_disallows_null")
349
+ elif null_scores:
350
+ null_id = tokenizer.convert_tokens_to_ids("null")
351
+ score = next(
352
+ (float(token[0]) for token in null_scores[0] if token[1] == null_id), None
353
+ )
354
+ if score is None or math.isnan(score) or score > 1e-06:
355
+ raise ValueError("Transformers omitted a valid null-token log probability")
356
+ prediction.update(
357
+ p_null=math.exp(min(0.0, score)),
358
+ p_null_method="ar_first_token_null_probability",
359
+ )
360
+ if valid and token_logprobs:
361
+ log_probability = sum((float(token[0]) for token in token_logprobs))
362
+ if not math.isfinite(log_probability) or log_probability > 1e-06:
363
+ raise ValueError("Transformers returned invalid token log probabilities")
364
+ prediction.update(
365
+ confidence=math.exp(min(0.0, log_probability)),
366
+ log_probability=log_probability,
367
+ confidence_method="ar_sequence_probability",
368
+ )
369
+ elif not valid:
370
+ prediction["confidence"] = 0.0
371
+ if (
372
+ valid
373
+ and evidence is None
374
+ and (provenance is not None)
375
+ and (value is not None)
376
+ and (spec["type"] == "number")
377
+ ):
378
+ literal = json.loads(raw, parse_float=Decimal, parse_int=Decimal)
379
+ (found, literal_span) = provenance.span(literal)
380
+ if found and literal_span is not None:
381
+ prediction.update(span=literal_span, span_method="unique_literal_match")
382
+ if valid and evidence is None and isinstance(value, str) and value and source:
383
+ start = source.find(value)
384
+ if start >= 0 and source.find(value, start + 1) < 0:
385
+ prediction.update(
386
+ span=[start, start + len(value)], span_method="unique_literal_match"
387
+ )
388
+ return prediction
389
+
390
+
391
+ def validate_eos(path: Path, tokenizer: Any) -> None:
392
+ config = json.loads((path / "config.json").read_text())
393
+ generation = json.loads((path / "generation_config.json").read_text())
394
+ eos = tokenizer.convert_tokens_to_ids(ar.EOS)
395
+ configured = [
396
+ config.get("eos_token_id"),
397
+ config.get("text_config", {}).get("eos_token_id"),
398
+ generation.get("eos_token_id"),
399
+ ]
400
+ if any((value != eos for value in configured)):
401
+ raise ValueError(
402
+ "Model, text, and generation EOS must match the <|im_end|> terminator"
403
+ )
404
+
405
+
406
+ class ClairicFlashModel:
407
+ RELEASE_MODEL_ID = "clairic-v2"
408
+ COMPACT_LIST_PROMPTS = True
409
+ DATE_ROLE_GUIDANCE = True
410
+ RECOVER_NULLS = True
411
+ SOURCE_ROW_ELIGIBILITY = False
412
+ LOCAL_SOURCE_SCOPE = True
413
+ FINANCIAL_SERVICE_GUIDANCE = True
414
+ FINANCIAL_FEE_GUIDANCE = False
415
+ EXPLICIT_TEMPORAL_READS = True
416
+ SPELL_VISUAL_PO_REFERENCES = True
417
+ FOCUS_SPARSE_IMAGES = True
418
+ FOCUS_IMAGE_IDENTIFIERS = True
419
+ FOCUS_IMAGE_PARTY_NAMES = True
420
+ LITERAL_IMAGE_PAYMENT_ROWS = False
421
+ BIND_IMAGE_FINANCIAL_LINES = True
422
+ PRESERVE_IMAGE_ENTITY_NAMES = False
423
+ BIND_IMAGE_TABLE_ROWS = True
424
+ BIND_IMAGE_RAGGED_ROWS = True
425
+ IMAGE_TABLE_ROW_SCALE = 2
426
+ REQUEST_TIMEOUT_SECONDS = 600
427
+ DATE_SUPPLEMENT_TIMEOUT_SECONDS = 600
428
+ RECEIPT_SUPPLEMENT_TIMEOUT_SECONDS = 600
429
+
430
+ def __init__(
431
+ self,
432
+ engine: Any,
433
+ tokenizer: Any,
434
+ processor: Any,
435
+ settings: RuntimeSettings,
436
+ head_config: dict[str, Any],
437
+ ) -> None:
438
+ (self.engine, self.tokenizer, self.processor) = (engine, tokenizer, processor)
439
+ (self.settings, self.head_config) = (settings, head_config)
440
+ (self.max_concurrency, self.model_id) = (
441
+ settings.max_concurrency,
442
+ settings.model_id,
443
+ )
444
+ self._encoder = concurrent.futures.ThreadPoolExecutor(
445
+ max_workers=1, thread_name_prefix="clairic-encode"
446
+ )
447
+ self._in_flight = 0
448
+ self._image_cache = ImageCache()
449
+
450
+ def encode(
451
+ self,
452
+ request: PredictRequest,
453
+ *,
454
+ identifier_view: bool = False,
455
+ party_name_view: bool = False,
456
+ image_views: Callable[[], Sequence[Image.Image]] | None = None,
457
+ physical_row_view: bool = False,
458
+ image_view_key: str | None = None,
459
+ pdf_spelling_view: bool = False,
460
+ identifier_spelling_disabled: bool = False,
461
+ po_detail_view: bool = False,
462
+ ) -> EncodedRequest:
463
+ original_request = request
464
+ automatic_temporal = {}
465
+ if self.EXPLICIT_TEMPORAL_READS:
466
+ routed_fields = printed_temporal.explicit_fields(request.fields)
467
+ automatic_temporal = {
468
+ name: spec
469
+ for (name, spec) in request.fields.items()
470
+ if routed_fields[name] is not spec
471
+ }
472
+ request = request.model_copy(update={"fields": routed_fields})
473
+ if self.PRESERVE_IMAGE_ENTITY_NAMES:
474
+ request = request.model_copy(
475
+ update={
476
+ "fields": entity_scope.prepare(
477
+ request.fields,
478
+ has_media=bool(request.images or request.documents),
479
+ )
480
+ }
481
+ )
482
+ (scoped_fields, query_labels) = identifier_scope.prepare_fields(
483
+ request.fields, has_media=bool(request.images or request.documents)
484
+ )
485
+ if scoped_fields is not request.fields:
486
+ request = request.model_copy(update={"fields": scoped_fields})
487
+ if self.FOCUS_SPARSE_IMAGES and request.images or pdf_spelling_view:
488
+ request = request.model_copy(
489
+ update={"fields": image_focus.preserve_scalar_fields(request.fields)}
490
+ )
491
+ expand_options = {
492
+ "date_role_guidance": self.DATE_ROLE_GUIDANCE,
493
+ "source_row_eligibility": self.SOURCE_ROW_ELIGIBILITY,
494
+ "local_scoped_pairs": self.LOCAL_SOURCE_SCOPE,
495
+ "service_guidance": self.FINANCIAL_SERVICE_GUIDANCE,
496
+ "fee_guidance": self.FINANCIAL_FEE_GUIDANCE,
497
+ "literal_payment_rows": self.LITERAL_IMAGE_PAYMENT_ROWS,
498
+ }
499
+ (record, forecasts) = expand_request(request, **expand_options)
500
+ state_only_fields = {
501
+ name
502
+ for (name, spec) in original_request.fields.items()
503
+ if grounding.state_only(spec)
504
+ }
505
+ if self.SPELL_VISUAL_PO_REFERENCES and (not identifier_spelling_disabled):
506
+ identifier_spelling.prepare(
507
+ record,
508
+ original_request.fields,
509
+ query_labels,
510
+ has_media=bool(original_request.images or original_request.documents),
511
+ )
512
+ if query_labels:
513
+ spelling = record["_meta"].get("identifier_spelling", {})
514
+ record.setdefault("_source_row_names", {}).update(
515
+ {
516
+ name: name if name in spelling else label
517
+ for (name, label) in query_labels.items()
518
+ }
519
+ )
520
+ if physical_row_view:
521
+ for spec in record["fields"].values():
522
+ spec["_physical_row_scope"] = True
523
+ image_rows.prepare(
524
+ record,
525
+ has_media=bool(request.images or request.documents),
526
+ share_description=getattr(
527
+ self._image_cache, "_share_image_row_description", False
528
+ ),
529
+ )
530
+ record["_list_source_bounds"] = source_rows.list_bounds(
531
+ request.state,
532
+ request.fields,
533
+ has_images=bool(request.images or request.documents),
534
+ )
535
+ sources: tuple[ClairImage | ClairDocument, ...] = (
536
+ *request.images,
537
+ *request.documents,
538
+ )
539
+ source_key = ImageCache.key(sources) if sources else None
540
+ image_key = source_key
541
+ if image_key is not None:
542
+ image_key += (
543
+ ":identifier:" + image_identifier.VIEW_ID
544
+ if identifier_view
545
+ else ":default"
546
+ )
547
+ if image_view_key is not None:
548
+ image_key += ":view:" + image_view_key
549
+ prepared = self._image_cache.get(image_key) if image_key is not None else None
550
+ if sources and prepared is None:
551
+ images = (
552
+ list(image_views())
553
+ if image_views is not None
554
+ else [i.to_pil() for i in request.images]
555
+ )
556
+ original_images = list(images)
557
+ if self.FOCUS_SPARSE_IMAGES or pdf_spelling_view or po_detail_view:
558
+ focus = (
559
+ (
560
+ lambda image: image_focus.focus_document(
561
+ image,
562
+ max_pixels=identifier_spelling.MANY_IMAGE_MAX_PIXELS,
563
+ max_scale=3.0,
564
+ )
565
+ )
566
+ if po_detail_view
567
+ else image_focus.focus_document
568
+ )
569
+ unfocused_image = None
570
+ if (
571
+ type(self) is ClairicFlashModel
572
+ and identifier_view
573
+ and (len(request.images) == 1)
574
+ and (not request.documents)
575
+ ):
576
+ default = self._image_cache.entries.get(
577
+ cast(str, source_key) + ":default"
578
+ )
579
+ if (
580
+ default is not None
581
+ and len(default.images) == 1
582
+ and default.source_images
583
+ and (default.images[0] is default.source_images[0])
584
+ ):
585
+ unfocused_image = default.images[0]
586
+ if unfocused_image is None:
587
+ images = [focus(image) for image in images]
588
+ else:
589
+ images = [
590
+ image if image is unfocused_image else focus(image)
591
+ for image in images
592
+ ]
593
+ if image_views is None:
594
+ for document in request.documents:
595
+ pages = document.render(MAX_IMAGES - len(images))
596
+ images.extend(pages)
597
+ original_images.extend(pages)
598
+ media: cm.EncodedMedia | None = cm.encode_media(
599
+ self.tokenizer, images, self.processor
600
+ )
601
+ prepared = self._image_cache.put(
602
+ cast(str, image_key),
603
+ images,
604
+ cast(cm.EncodedMedia, media),
605
+ self.media_payload(
606
+ request,
607
+ cast(dict[str, Any], cast(cm.EncodedMedia, media).media),
608
+ source_digest=image_key,
609
+ feature_namespace=self._image_cache.namespace,
610
+ ),
611
+ source_images=original_images,
612
+ )
613
+ images = prepared.images if prepared else []
614
+ media = prepared.media if prepared else None
615
+ payload = prepared.payload if prepared else None
616
+ record["_media_payload"] = payload
617
+ record["_original_images"] = prepared.source_images if prepared else []
618
+ tasks = []
619
+ state_tasks = set()
620
+ eos = self.tokenizer.convert_tokens_to_ids(ar.EOS)
621
+ if images:
622
+ names = ar.names(record)
623
+ if names:
624
+ marker = "PARALLEL_AR_CONTENT_4A61DB"
625
+ messages = [
626
+ {
627
+ "role": "user",
628
+ "content": [{"type": "image", "image": i} for i in images]
629
+ + [{"type": "text", "text": marker}],
630
+ }
631
+ ]
632
+ template = self.processor.apply_chat_template(
633
+ messages,
634
+ tokenize=False,
635
+ add_generation_prompt=True,
636
+ enable_thinking=False,
637
+ )
638
+ (header, footer) = template.split(marker)
639
+ boundary = header.rfind("<|vision_end|>")
640
+ if boundary < 0:
641
+ raise ValueError(
642
+ "The image chat template is missing its vision terminator"
643
+ )
644
+ boundary += len("<|vision_end|>")
645
+ replacements = [
646
+ self.processor.replace_image_token(
647
+ cast(cm.EncodedMedia, media).media, i
648
+ )
649
+ for i in range(len(images))
650
+ ]
651
+ (prefix_text, _) = self.processor.get_text_with_replacements(
652
+ [header[:boundary]], replacements, [], []
653
+ )
654
+ prefix = self.tokenizer(prefix_text, add_special_tokens=False)[
655
+ "input_ids"
656
+ ][0]
657
+ source = self.tokenizer.encode(
658
+ request.state, add_special_tokens=False, split_special_tokens=True
659
+ )
660
+ scoped_media = {
661
+ name
662
+ for (name, spec) in original_request.fields.items()
663
+ if grounding.explicit_media_scope(spec)
664
+ }
665
+ tails = self.tokenizer(
666
+ [
667
+ header[boundary:]
668
+ + (
669
+ ar.MEDIA_EVIDENCE_INSTRUCTION + "\n\n"
670
+ if request.state and name in scoped_media
671
+ else ""
672
+ )
673
+ + ar.instruction(
674
+ record, name, compact_lists=self.COMPACT_LIST_PROMPTS
675
+ ).rstrip()
676
+ + (
677
+ (
678
+ "\n\nAccompanying text:\n"
679
+ if name in scoped_media
680
+ else "\n\nDocument:\n"
681
+ )
682
+ if request.state
683
+ else footer
684
+ )
685
+ for name in names
686
+ ],
687
+ add_special_tokens=False,
688
+ )["input_ids"]
689
+ if request.state:
690
+ footer_ids = self.tokenizer.encode(footer, add_special_tokens=False)
691
+ tails = [tail + source + footer_ids for tail in tails]
692
+ tasks = [
693
+ (name, prefix + tail, payload)
694
+ for (name, tail) in zip(names, tails, strict=True)
695
+ ]
696
+ state_tasks = {
697
+ name
698
+ for name in names
699
+ if name in state_only_fields
700
+ or grounding.state_only(record["fields"][name])
701
+ }
702
+ if state_tasks:
703
+ text_template = self.tokenizer.apply_chat_template(
704
+ [{"role": "user", "content": marker}],
705
+ tokenize=False,
706
+ add_generation_prompt=True,
707
+ enable_thinking=False,
708
+ )
709
+ (text_header, text_footer) = text_template.split(marker)
710
+ text_footer_ids = self.tokenizer.encode(
711
+ text_footer, add_special_tokens=False
712
+ )
713
+ tasks = [
714
+ (
715
+ name,
716
+ self.tokenizer.encode(
717
+ text_header
718
+ + ar.instruction(
719
+ record,
720
+ name,
721
+ compact_lists=self.COMPACT_LIST_PROMPTS,
722
+ )
723
+ + "\n\nDocument:\n",
724
+ add_special_tokens=False,
725
+ )
726
+ + source
727
+ + text_footer_ids,
728
+ None,
729
+ )
730
+ if name in state_tasks
731
+ else (name, ids, task_media)
732
+ for (name, ids, task_media) in tasks
733
+ ]
734
+ else:
735
+ marker = "PARALLEL_AR_CONTENT_4A61DB"
736
+ template = self.tokenizer.apply_chat_template(
737
+ [{"role": "user", "content": marker}],
738
+ tokenize=False,
739
+ add_generation_prompt=True,
740
+ enable_thinking=False,
741
+ )
742
+ (header, footer) = template.split(marker)
743
+ source = self.tokenizer.encode(
744
+ request.state, add_special_tokens=False, split_special_tokens=True
745
+ )
746
+ tail = self.tokenizer.encode(footer, add_special_tokens=False)
747
+ for name in ar.names(record):
748
+ ids = (
749
+ self.tokenizer.encode(
750
+ header
751
+ + ar.instruction(
752
+ record, name, compact_lists=self.COMPACT_LIST_PROMPTS
753
+ )
754
+ + "\n\nDocument:\n",
755
+ add_special_tokens=False,
756
+ )
757
+ + (
758
+ self.tokenizer.encode(
759
+ record["_source_row_inputs"][name],
760
+ add_special_tokens=False,
761
+ split_special_tokens=True,
762
+ )
763
+ if name in record["_source_row_inputs"]
764
+ else source
765
+ )
766
+ + tail
767
+ )
768
+ tasks.append((name, ids, None))
769
+ typed = typed_readout_record(
770
+ request, record, automatic_temporal=automatic_temporal, **expand_options
771
+ )
772
+ item = None
773
+ if typed:
774
+ item = cm.encode_record(
775
+ self.tokenizer,
776
+ typed,
777
+ self.settings.max_length,
778
+ media=media,
779
+ answer_slots=True,
780
+ text_answer_slots=True,
781
+ )
782
+ if item is None or item.text != record["input"]:
783
+ raise ValueError("Typed fields and input must fit one complete context")
784
+ if any((len(ids) > self.settings.max_length for (_, ids, _) in tasks)):
785
+ raise ValueError(
786
+ "AR input exceeds the model context; no input was truncated"
787
+ )
788
+ record["_ar_tasks"] = tasks
789
+ source = (
790
+ grounding.Source(request.state, normalize_whitespace=True)
791
+ if tasks and (not images or state_tasks)
792
+ else None
793
+ )
794
+ record["_ar_source"] = source if not images else None
795
+ record["_ar_sources"] = dict.fromkeys(state_tasks, source)
796
+ record["_ar_constraints"] = {
797
+ name: source.constraint(record["fields"][name])
798
+ if (source := record["_ar_sources"].get(name, record["_ar_source"]))
799
+ is not None
800
+ and grounding.applies(record["fields"][name], media)
801
+ else {"json_schema": json.dumps(ar.schema(record["fields"][name]))}
802
+ for (name, _, media) in tasks
803
+ }
804
+ record["_cache_salt"] = prepared.salt if prepared else uuid.uuid4().hex
805
+ if state_tasks:
806
+ record["_ar_task_salts"] = {name: uuid.uuid4().hex for name in state_tasks}
807
+ if len(tasks) > 1:
808
+ prefix = common_prefix(tasks)
809
+ if len(prefix) >= 128:
810
+ record["_ar_prefix"] = prefix
811
+ groups: dict[str, list[tuple[str, list[int], Any]]] = {}
812
+ annotations = record["_meta"]["extraction_contract"]["fields"]
813
+ for task in tasks:
814
+ parent = annotations.get(task[0], {}).get("parent")
815
+ if parent:
816
+ groups.setdefault(parent, []).append(task)
817
+ record["_ar_group_prefixes"] = [
818
+ common_prefix(group) for group in groups.values() if len(group) > 1
819
+ ]
820
+ encoded = (record, forecasts, tasks, item, eos)
821
+ detail_view = (
822
+ identifier_view
823
+ or party_name_view
824
+ or physical_row_view
825
+ or identifier_spelling_disabled
826
+ )
827
+ if self.BIND_IMAGE_TABLE_ROWS and (not detail_view):
828
+ encoded = image_table_rows.prepare(
829
+ request, encoded, self.encode, scale=self.IMAGE_TABLE_ROW_SCALE
830
+ )
831
+ if self.BIND_IMAGE_RAGGED_ROWS and (not detail_view):
832
+ encoded = image_ragged_rows.prepare(
833
+ request, encoded, self.encode, scale=self.IMAGE_TABLE_ROW_SCALE
834
+ )
835
+ if self.BIND_IMAGE_FINANCIAL_LINES and (not detail_view):
836
+ encoded = image_financial_lines.prepare(request, encoded, self.encode)
837
+ if self.FOCUS_IMAGE_IDENTIFIERS and (not detail_view):
838
+ prefix_overlap = getattr(self, "_invoice_prefix_overlap", None)
839
+ if prefix_overlap is not None:
840
+ prefix_overlap.start(original_request, encoded, eos)
841
+ unfocused_image = None
842
+ if (
843
+ type(self) is ClairicFlashModel
844
+ and self.FOCUS_SPARSE_IMAGES
845
+ and (len(request.images) == 1)
846
+ and (not request.documents)
847
+ and (prepared is not None)
848
+ and (len(prepared.images) == 1)
849
+ and prepared.source_images
850
+ and (prepared.images[0] is prepared.source_images[0])
851
+ ):
852
+ unfocused_image = prepared.images[0]
853
+ if unfocused_image is None:
854
+ encoded = image_identifier.prepare(
855
+ original_request, encoded, self.encode
856
+ )
857
+ else:
858
+ encoded = image_identifier.prepare(
859
+ original_request,
860
+ encoded,
861
+ self.encode,
862
+ unfocused_image=unfocused_image,
863
+ )
864
+ if self.FOCUS_IMAGE_PARTY_NAMES and (not detail_view):
865
+ encoded = self._party_name_tasks(original_request, encoded)
866
+ if not detail_view:
867
+ encoded = pdf_number_focus.prepare(
868
+ original_request, encoded, self.encode, enabled=self.FOCUS_SPARSE_IMAGES
869
+ )
870
+ encoded = identifier_spelling.prepare_pdf_tasks(
871
+ original_request, encoded, self.encode, enabled=True
872
+ )
873
+ encoded = identifier_spelling.prepare_many_image_tasks(
874
+ original_request, encoded, self.encode
875
+ )
876
+ encoded = identifier_spelling.prepare_fallback(
877
+ original_request, encoded, self.encode
878
+ )
879
+ record = encoded[0]
880
+ record["_first_item_list_gating"] = getattr(
881
+ self._image_cache, "_share_image_row_description", False
882
+ )
883
+ if record.get("_ar_task_salts"):
884
+ record["_ar_media_groups"] = media_warmup_groups(
885
+ record["_ar_tasks"],
886
+ default_salt=record["_cache_salt"],
887
+ task_salts=record["_ar_task_salts"],
888
+ annotations=record["_meta"]["extraction_contract"]["fields"],
889
+ )
890
+ return encoded
891
+
892
+ def _party_name_tasks(
893
+ self, request: PredictRequest, encoded: EncodedRequest
894
+ ) -> EncodedRequest:
895
+ selected = image_party_names.fields(request.fields)
896
+ if not selected or len(request.images) != 1 or request.documents:
897
+ return encoded
898
+ (record, forecasts, tasks, typed, eos) = encoded
899
+ originals = record.get("_original_images")
900
+ image = originals[0] if originals else request.images[0].to_pil()
901
+ views = image_party_names.views(image)
902
+ if len(views) == 1:
903
+ return encoded
904
+ fields = {
905
+ name: {
906
+ **request.fields[name],
907
+ "instructions": request.fields[name].get("instructions", "")
908
+ + image_party_names.VIEW_INSTRUCTION,
909
+ }
910
+ for name in selected
911
+ }
912
+ child_request = request.model_copy(update={"fields": fields})
913
+ (child, _, replacements, _, _) = self.encode(
914
+ child_request,
915
+ party_name_view=True,
916
+ image_views=lambda: views,
917
+ image_view_key=image_party_names.VIEW_ID,
918
+ )
919
+ by_name = {task[0]: task for task in replacements}
920
+ tasks = [by_name.get(task[0], task) for task in tasks]
921
+ salts = dict(record.get("_ar_task_salts", {}))
922
+ for name in selected:
923
+ record["fields"][name] = child["fields"][name]
924
+ record["_ar_constraints"][name] = child["_ar_constraints"][name]
925
+ salts[name] = child["_cache_salt"]
926
+ record.update(
927
+ _ar_tasks=tasks, _ar_task_salts=salts, _ar_prefix=[], _ar_group_prefixes=[]
928
+ )
929
+ return (record, forecasts, tasks, typed, eos)
930
+
931
+ @staticmethod
932
+ def media_payload(
933
+ request: PredictRequest,
934
+ encoded: dict[str, Any],
935
+ *,
936
+ source_digest: str | None = None,
937
+ feature_namespace: str = "",
938
+ ) -> list[dict[str, Any]]:
939
+ # MLX port: pixel values stay NumPy, rounded through bfloat16 as upstream does before the model sees
940
+ # them, and carry a content key so the engine can reuse the vision features within a request.
941
+ import hashlib
942
+
943
+ import mlx.core as mx
944
+ import numpy as np
945
+
946
+ digest = source_digest or ImageCache.key((*request.images, *request.documents))
947
+ pixels = np.array(mx.array(np.asarray(encoded["pixel_values"], dtype=np.float32)).astype(mx.bfloat16).astype(mx.float32))
948
+ grid = np.asarray(encoded["image_grid_thw"])
949
+ return [
950
+ {
951
+ "format": "processor_output",
952
+ "clair_media_digest": digest,
953
+ "clair_pixels_key": hashlib.sha1(pixels.tobytes() + grid.tobytes()).hexdigest(),
954
+ "pixel_values": pixels,
955
+ "image_grid_thw": grid,
956
+ }
957
+ ]
958
+
959
+ async def _ar(
960
+ self, record: dict[str, Any], task: ARTask, eos: int
961
+ ) -> tuple[str, dict[str, Any]]:
962
+ if "_ar_future" not in record:
963
+ record["_ar_future"] = asyncio.create_task(self._ar_all(record, eos))
964
+ predictions = await record["_ar_future"]
965
+ return (task[0], predictions[task[0]])
966
+
967
+ async def _ar_all(
968
+ self, record: dict[str, Any], eos: int
969
+ ) -> dict[str, dict[str, Any]]:
970
+ tasks = record["_ar_tasks"]
971
+ salt = record["_cache_salt"]
972
+ row_gates = set(record.get("_source_row_gates", ()))
973
+ false_id = self.tokenizer.convert_tokens_to_ids("false") if row_gates else None
974
+ score_ids = [self.tokenizer.convert_tokens_to_ids("null")]
975
+ if false_id is not None:
976
+ score_ids.append(false_id)
977
+ results = await ordinary_list_completion.generate(
978
+ self.engine,
979
+ record,
980
+ tasks,
981
+ eos,
982
+ self.tokenizer,
983
+ initial_frontier=32
984
+ if type(self) is ClairicFlashModel
985
+ and self.settings.model_id == "clairic-flash"
986
+ and (self.max_concurrency == self.settings.max_concurrency == 1)
987
+ else 0,
988
+ next_frontier=64,
989
+ parse_result=scalar_result,
990
+ normalize=lambda record, predictions: printed_numbers.normalize_predictions(
991
+ record, printed_temporal.normalize_predictions(record, predictions)
992
+ ),
993
+ input_ids=[ids for (_, ids, _) in tasks],
994
+ image_data=batch_image_data([media for (_, _, media) in tasks]),
995
+ rid=["ar-" + uuid.uuid4().hex for _ in tasks],
996
+ cache_salt=[
997
+ record.get("_ar_task_salts", {}).get(name, salt)
998
+ for (name, _, _) in tasks
999
+ ],
1000
+ return_logprob=True,
1001
+ logprob_start_len=-1,
1002
+ token_ids_logprob=score_ids,
1003
+ sampling_params=[
1004
+ {
1005
+ "temperature": 0,
1006
+ "max_new_tokens": image_rows.output_limit(
1007
+ record, name, len(ids), self.settings.max_length
1008
+ )
1009
+ if image_rows.is_inventory(record["fields"][name])
1010
+ else record.get("_ar_max_output_tokens", MAX_OUTPUT_TOKENS),
1011
+ "stop_token_ids": [eos],
1012
+ **(
1013
+ record["_ar_constraints"][name]
1014
+ if name in record.get("_ar_constraints", {})
1015
+ else {
1016
+ "json_schema": json.dumps(ar.schema(record["fields"][name]))
1017
+ }
1018
+ ),
1019
+ "skip_special_tokens": False,
1020
+ }
1021
+ for (name, ids, _) in tasks
1022
+ ],
1023
+ )
1024
+ if usage := record.get("_completed_generation_usage"):
1025
+ usage["tasks"].extend(tasks)
1026
+ usage["readings"].extend(
1027
+ (
1028
+ {
1029
+ "tokens": int(
1030
+ result.get("meta_info", {}).get("completion_tokens", 0)
1031
+ )
1032
+ }
1033
+ for result in results
1034
+ )
1035
+ )
1036
+ predictions = {
1037
+ name: batch_completion.unused_prediction(result)
1038
+ if result.get("_clair_unused_row_proposal")
1039
+ else scalar_result(
1040
+ result,
1041
+ record["fields"][name],
1042
+ self.tokenizer,
1043
+ record["input"],
1044
+ record.get("_ar_sources", {}).get(name, record.get("_ar_source"))
1045
+ if grounding.applies(record["fields"][name], media)
1046
+ else None,
1047
+ excluded_token_id=false_id if name in row_gates else None,
1048
+ provenance=record.get("_ar_sources", {}).get(
1049
+ name, record.get("_ar_source")
1050
+ )
1051
+ if media is None and (not record["fields"][name].get("knowledge"))
1052
+ else None,
1053
+ )
1054
+ for ((name, _, media), result) in zip(tasks, results, strict=True)
1055
+ }
1056
+ if any(
1057
+ (
1058
+ "confidence" not in prediction
1059
+ for prediction in predictions.values()
1060
+ if not prediction.get("_unused_row_proposal")
1061
+ )
1062
+ ):
1063
+ raise ClairInferenceError(
1064
+ "Transformers omitted generation log probabilities"
1065
+ )
1066
+ if any(
1067
+ (
1068
+ "p_null" not in prediction
1069
+ for prediction in predictions.values()
1070
+ if not prediction.get("_unused_row_proposal")
1071
+ )
1072
+ ):
1073
+ raise ClairInferenceError(
1074
+ "Transformers omitted null-token log probabilities"
1075
+ )
1076
+ if self.RECOVER_NULLS and (not record.get("_null_recovery")):
1077
+ fields = {
1078
+ name
1079
+ for (name, prediction) in predictions.items()
1080
+ if (
1081
+ prediction["valid"]
1082
+ and prediction["value"] is None
1083
+ or prediction.get("failure_reason") == "not_in_source"
1084
+ )
1085
+ and (not record["fields"][name].get("knowledge"))
1086
+ and (name not in record.get("_meta", {}).get("printed_temporal", {}))
1087
+ and (name not in record.get("_meta", {}).get("printed_numbers", {}))
1088
+ and (
1089
+ record["fields"][name]["type"] == "number"
1090
+ or (record["fields"][name]["type"] == "text" and record["input"])
1091
+ )
1092
+ and (
1093
+ not record["_meta"]["extraction_contract"]["fields"]
1094
+ .get(name, {})
1095
+ .get("parent")
1096
+ )
1097
+ }
1098
+ if fields:
1099
+ repair = await asyncio.get_running_loop().run_in_executor(
1100
+ self._encoder, self.null_recovery_record, record, fields
1101
+ )
1102
+ if repair["_ar_tasks"]:
1103
+ alternatives = await self._ar_all(repair, eos)
1104
+ retry_lengths = {
1105
+ name: len(ids) for (name, ids, _) in repair["_ar_tasks"]
1106
+ }
1107
+ for name, alternative in alternatives.items():
1108
+ original = predictions[name]
1109
+ tokens = original["tokens"] + alternative["tokens"]
1110
+ if (
1111
+ alternative["valid"]
1112
+ and alternative["value"] is not None
1113
+ and (
1114
+ alternative.get("grounding_method")
1115
+ in ("literal_source", "whitespace_normalized_source")
1116
+ or record["fields"][name]["type"] == "number"
1117
+ or (
1118
+ alternative.get("span") is not None
1119
+ and alternative.get("confidence", 0.0)
1120
+ > alternative.get("p_null", 1.0)
1121
+ )
1122
+ )
1123
+ ):
1124
+ predictions[name] = {**alternative, "null_recovered": True}
1125
+ predictions[name]["tokens"] = tokens
1126
+ predictions[name]["retry_input_tokens"] = retry_lengths[name]
1127
+ if plan := row_omission.prepare(record, predictions):
1128
+ repair, _ = plan
1129
+ alternatives = await self._ar_all(repair, eos)
1130
+ predictions, _ = row_omission.merge(record, predictions, alternatives, plan)
1131
+ return predictions
1132
+
1133
+ def null_recovery_record(
1134
+ self, record: dict[str, Any], fields: Collection[str]
1135
+ ) -> dict[str, Any]:
1136
+ original = self.tokenizer.encode(
1137
+ ar.EXTRACTION_INSTRUCTION, add_special_tokens=False
1138
+ )
1139
+ tasks = []
1140
+ for name, ids, media in record["_ar_tasks"]:
1141
+ if name not in fields:
1142
+ continue
1143
+ source = record.get("_ar_sources", {}).get(name, record.get("_ar_source"))
1144
+ instruction = (
1145
+ ar.COMPUTATION_INSTRUCTION
1146
+ if source is not None
1147
+ else ar.RECOVERY_INSTRUCTION
1148
+ )
1149
+ replacement = self.tokenizer.encode(instruction, add_special_tokens=False)
1150
+ matches = [
1151
+ i
1152
+ for (i, token) in enumerate(ids)
1153
+ if token == original[0] and ids[i : i + len(original)] == original
1154
+ ]
1155
+ if len(matches) != 1:
1156
+ continue
1157
+ start = matches[0]
1158
+ prompt = ids[:start] + replacement + ids[start + len(original) :]
1159
+ if len(prompt) <= self.settings.max_length:
1160
+ tasks.append((name, prompt, media))
1161
+ return {
1162
+ **record,
1163
+ "_ar_tasks": tasks,
1164
+ "_ar_prefix": None,
1165
+ "_ar_group_prefixes": [],
1166
+ "_ar_media_groups": [],
1167
+ "_null_recovery": True,
1168
+ }
1169
+
1170
+ async def _typed(
1171
+ self,
1172
+ request: PredictRequest,
1173
+ item: cm.EncodedRecord,
1174
+ media: list[dict[str, Any]] | None = None,
1175
+ ) -> dict[str, dict[str, Any]]:
1176
+ if (request.images or request.documents) and media is None:
1177
+ media = self.media_payload(request, cast(dict[str, Any], item.media))
1178
+ return await self.engine.read_typed(item, media)
1179
+
1180
+ def _encode_receipt_repairs(
1181
+ self,
1182
+ request: PredictRequest,
1183
+ record: dict[str, Any],
1184
+ predictions: dict[str, dict[str, Any]],
1185
+ ) -> list[tuple[str, dict[str, Any], dict[str, Any]]]:
1186
+ prepared = []
1187
+ value: Any
1188
+ p_null: Any
1189
+ source = {**record, "input": request.state, "fields": request.fields}
1190
+ for name in record.get("_receipt_sum_fields", ()):
1191
+ previous = predictions.get(name, {})
1192
+ (value, p_null) = (previous.get("value"), previous.get("p_null"))
1193
+ if (
1194
+ type(value) not in (int, float)
1195
+ or not math.isfinite(value)
1196
+ or previous.get("decoder") != ar.VERSION
1197
+ or (type(p_null) not in (int, float))
1198
+ or (not 0 <= p_null <= 1)
1199
+ ):
1200
+ continue
1201
+ packet = receipt_totals.prepare_task(source, name)
1202
+ if packet is None:
1203
+ continue
1204
+ tasks = []
1205
+ for task in packet["tasks"]:
1206
+ rendered = self.tokenizer.apply_chat_template(
1207
+ [{"role": "user", "content": task["prompt"]}],
1208
+ tokenize=False,
1209
+ add_generation_prompt=True,
1210
+ enable_thinking=False,
1211
+ )
1212
+ ids = self.tokenizer.encode(rendered, add_special_tokens=False)
1213
+ if not ids or len(ids) > self.settings.max_length:
1214
+ raise ValueError(
1215
+ "Receipt selector exceeds the model context; no input was truncated"
1216
+ )
1217
+ tasks.append((task["occurrence_id"], ids, None))
1218
+ auxiliary = {
1219
+ "input": request.state,
1220
+ "fields": {
1221
+ key: {"type": "boolean", "nullable": True} for (key, _, _) in tasks
1222
+ },
1223
+ "_ar_tasks": tasks,
1224
+ "_ar_constraints": {
1225
+ task["occurrence_id"]: task["grammar"] for task in packet["tasks"]
1226
+ },
1227
+ "_ar_prefix": common_prefix(tasks),
1228
+ "_cache_salt": uuid.uuid4().hex,
1229
+ "_null_recovery": True,
1230
+ "_ar_max_output_tokens": 8,
1231
+ "_meta": {"extraction_contract": {"fields": {}}},
1232
+ }
1233
+ prepared.append((name, packet, auxiliary))
1234
+ return prepared
1235
+
1236
+ async def _complete_receipt_sums(
1237
+ self,
1238
+ request: PredictRequest,
1239
+ record: dict[str, Any],
1240
+ predictions: dict[str, dict[str, Any]],
1241
+ eos: int,
1242
+ progress: dict[str, list[Any]] | None = None,
1243
+ ) -> tuple[
1244
+ dict[str, dict[str, Any]],
1245
+ list[tuple[str, list[int], Any]],
1246
+ list[dict[str, Any]],
1247
+ ]:
1248
+ if progress is None:
1249
+ progress = {"encodings": [], "tasks": [], "readings": []}
1250
+ encoding = asyncio.get_running_loop().run_in_executor(
1251
+ self._encoder, self._encode_receipt_repairs, request, record, predictions
1252
+ )
1253
+ progress["encodings"].append(encoding)
1254
+ prepared = await asyncio.shield(encoding)
1255
+ updates = {}
1256
+ for name, packet, auxiliary in prepared:
1257
+ decisions = {}
1258
+ tasks = auxiliary["_ar_tasks"]
1259
+ for start in range(0, len(tasks), 32):
1260
+ batch = {
1261
+ **auxiliary,
1262
+ "_ar_tasks": tasks[start : start + 32],
1263
+ "_ar_prefix": auxiliary["_ar_prefix"] if start == 0 else None,
1264
+ "_completed_generation_usage": progress,
1265
+ }
1266
+ completed = len(progress["tasks"])
1267
+ results = await self._ar_all(batch, eos)
1268
+ if len(progress["tasks"]) == completed:
1269
+ progress["tasks"].extend(batch["_ar_tasks"])
1270
+ progress["readings"].extend(results.values())
1271
+ decisions.update(
1272
+ {
1273
+ key: {**answer, "raw_json": answer["raw"]}
1274
+ for (key, answer) in results.items()
1275
+ }
1276
+ )
1277
+ checked = receipt_totals.validate_result(packet, decisions)
1278
+ if (
1279
+ not checked["valid"]
1280
+ or checked["value"] is None
1281
+ or (not checked.get("selection_scores"))
1282
+ or (checked["value"] == predictions[name]["value"])
1283
+ ):
1284
+ continue
1285
+ updates[name] = {
1286
+ "value": checked["value"],
1287
+ "valid": True,
1288
+ "complete": True,
1289
+ "decoder": "source_receipt_block_sum_v1",
1290
+ "span": None,
1291
+ "raw": checked["decimal_sum"],
1292
+ **checked["selection_scores"],
1293
+ "p_null": predictions[name]["p_null"],
1294
+ "p_null_method": "primary_numeric_ar_first_token_null_probability",
1295
+ "source_receipt_operands": [
1296
+ {key: item[key] for key in ("span", "printed")}
1297
+ for item in checked["operands"]
1298
+ ],
1299
+ "tokens": sum((answer["tokens"] for answer in decisions.values())),
1300
+ }
1301
+ return (updates, progress["tasks"], progress["readings"])
1302
+
1303
+ def _encode_request(self, request: PredictRequest) -> EncodedRequest:
1304
+ source: Any
1305
+ previous = self._image_cache
1306
+ cache = ImageCache(
1307
+ max_bytes=previous.max_bytes, max_entries=previous.max_entries
1308
+ )
1309
+ cache._share_image_row_description = (
1310
+ type(self) is ClairicFlashModel
1311
+ and len(getattr(request, "images", ())) == 1
1312
+ and (not getattr(request, "documents", ()))
1313
+ )
1314
+ self._image_cache = cache
1315
+ try:
1316
+ encoded = self.encode(request)
1317
+ fields = {
1318
+ name: spec
1319
+ for (name, spec) in getattr(request, "fields", {}).items()
1320
+ if source_dates.eligible(spec)
1321
+ }
1322
+ if fields and (not request.images) and (not request.documents):
1323
+ record = encoded[0]
1324
+ fields = {
1325
+ name: spec
1326
+ for (name, spec) in fields.items()
1327
+ if name not in record.get("_meta", {}).get("printed_temporal", {})
1328
+ }
1329
+ source = source_dates.DateSource(request.state)
1330
+ names = [name for (name, spec) in fields.items() if source.allows(spec)]
1331
+ if names:
1332
+ internal_fields = {
1333
+ name: {
1334
+ "type": "text",
1335
+ "nullable": fields[name].get("nullable", True),
1336
+ "instructions": source_dates.INSTRUCTION
1337
+ + "\n"
1338
+ + fields[name].get("instructions", ""),
1339
+ }
1340
+ for name in names
1341
+ }
1342
+ internal = request.model_copy(update={"fields": internal_fields})
1343
+ try:
1344
+ (dated, _, _, _, date_eos) = self.encode(internal)
1345
+ except ValueError:
1346
+ return encoded
1347
+ dated["_ar_constraints"].update(
1348
+ {
1349
+ name: source.constraint(
1350
+ nullable=internal_fields[name]["nullable"]
1351
+ )
1352
+ for name in names
1353
+ }
1354
+ )
1355
+ dated.update(
1356
+ _ar_source=source,
1357
+ _ar_sources=dict.fromkeys(names, source),
1358
+ _null_recovery=True,
1359
+ )
1360
+ record["_date_supplement"] = (dated, source, names, date_eos)
1361
+ if (
1362
+ type(self) is ClairicFlashModel
1363
+ and (not getattr(request, "images", ()))
1364
+ and (not getattr(request, "documents", ()))
1365
+ ):
1366
+ source = {
1367
+ "input": getattr(request, "state", ""),
1368
+ "fields": getattr(request, "fields", {}),
1369
+ }
1370
+ names = [
1371
+ name
1372
+ for name in source["fields"]
1373
+ if receipt_totals.eligible(source, name)
1374
+ ]
1375
+ if names:
1376
+ encoded[0]["_receipt_sum_fields"] = names
1377
+ return encoded
1378
+ finally:
1379
+ cache.clear()
1380
+ cache._share_image_row_description = False
1381
+
1382
+ async def predict_async(self, request: PredictRequest) -> PredictOutput:
1383
+ if self._in_flight >= self.max_concurrency:
1384
+ raise ClairQueueFull("Clairic inference queue is full")
1385
+ self._in_flight += 1
1386
+ loop = asyncio.get_running_loop()
1387
+ deadline = loop.time() + self.REQUEST_TIMEOUT_SECONDS
1388
+ encoding: asyncio.Future[EncodedRequest] | None = None
1389
+ work: list[asyncio.Task[Any]] = []
1390
+ auxiliary: asyncio.Task[Any]
1391
+ receipt_progress: dict[str, list[Any]] = {
1392
+ "encodings": [],
1393
+ "tasks": [],
1394
+ "readings": [],
1395
+ }
1396
+ try:
1397
+ self.engine.begin_request()
1398
+ try:
1399
+ encoding = loop.run_in_executor(
1400
+ self._encoder, self._encode_request, request
1401
+ )
1402
+ (record, forecasts, tasks, item, eos) = await asyncio.wait_for(
1403
+ asyncio.shield(encoding), timeout=max(0, deadline - loop.time())
1404
+ )
1405
+ except ValueError as error:
1406
+ raise ClairRequestError(str(error)) from error
1407
+ work = [asyncio.create_task(self._ar(record, task, eos)) for task in tasks]
1408
+ if item is not None:
1409
+ work.append(
1410
+ asyncio.create_task(
1411
+ self._typed(request, item, record.get("_media_payload"))
1412
+ )
1413
+ )
1414
+ outputs: list[Any] = await asyncio.wait_for(
1415
+ asyncio.gather(*work), timeout=max(0, deadline - loop.time())
1416
+ )
1417
+ predictions: dict[str, dict[str, Any]] = (
1418
+ outputs[-1] if item is not None else {}
1419
+ )
1420
+ for name, value in outputs[: len(tasks)]:
1421
+ predictions[name] = value
1422
+ predictions = printed_temporal.normalize_predictions(record, predictions)
1423
+ predictions = printed_numbers.normalize_predictions(record, predictions)
1424
+ predictions = identifier_spelling.normalize_predictions(record, predictions)
1425
+ fallback = identifier_spelling.fallback_record(record, predictions)
1426
+ identifier_fallback_results = {}
1427
+ if fallback is not None:
1428
+ identifier_fallback_results = await asyncio.wait_for(
1429
+ self._ar_all(fallback, eos), timeout=max(0, deadline - loop.time())
1430
+ )
1431
+ predictions = identifier_spelling.merge_fallback(
1432
+ predictions, identifier_fallback_results, fallback
1433
+ )
1434
+ date_results = {}
1435
+ date_tasks = []
1436
+ if supplement := record.get("_date_supplement"):
1437
+ (dated, source, names, date_eos) = supplement
1438
+ names = [
1439
+ name
1440
+ for name in names
1441
+ if isinstance(predictions.get(name, {}).get("value"), str)
1442
+ and predictions[name]["value"] not in source.support
1443
+ ]
1444
+ if supplement and names:
1445
+ date_tasks = dated["_ar_tasks"]
1446
+ auxiliary = asyncio.create_task(self._ar_all(dated, date_eos))
1447
+ work.append(auxiliary)
1448
+ try:
1449
+ date_results = await asyncio.wait_for(
1450
+ auxiliary,
1451
+ timeout=max(
1452
+ 0,
1453
+ min(
1454
+ self.DATE_SUPPLEMENT_TIMEOUT_SECONDS,
1455
+ deadline - loop.time(),
1456
+ ),
1457
+ ),
1458
+ )
1459
+ date_results = source.annotate_predictions(date_results, names)
1460
+ predictions = source.merge_predictions(
1461
+ predictions, date_results, names
1462
+ )
1463
+ except Exception:
1464
+ (date_results, date_tasks) = ({}, [])
1465
+ receipt_tasks: list[ARTask]
1466
+ receipt_readings: list[dict[str, Any]]
1467
+ (receipt_tasks, receipt_readings) = ([], [])
1468
+ if record.get("_receipt_sum_fields"):
1469
+ auxiliary = asyncio.create_task(
1470
+ self._complete_receipt_sums(
1471
+ request, record, predictions, eos, receipt_progress
1472
+ )
1473
+ )
1474
+ work.append(auxiliary)
1475
+ try:
1476
+ (updates, receipt_tasks, receipt_readings) = await asyncio.wait_for(
1477
+ auxiliary,
1478
+ timeout=max(
1479
+ 0,
1480
+ min(
1481
+ self.RECEIPT_SUPPLEMENT_TIMEOUT_SECONDS,
1482
+ deadline - loop.time(),
1483
+ ),
1484
+ ),
1485
+ )
1486
+ predictions = {**predictions, **updates}
1487
+ except Exception:
1488
+ pass
1489
+ (receipt_tasks, receipt_readings) = (
1490
+ receipt_progress["tasks"],
1491
+ receipt_progress["readings"],
1492
+ )
1493
+ predictions = source_rows.bounded_predictions(
1494
+ predictions,
1495
+ record["fields"],
1496
+ record.get("_list_source_bounds", {}),
1497
+ zs.list_item_name,
1498
+ )
1499
+ merged = zs.assemble_list_predictions(record, predictions)
1500
+ merged.update(image_rows.assemble(record, predictions))
1501
+ merged.update(image_table_rows.assemble(record, predictions))
1502
+ merged.update(image_ragged_rows.assemble(record, predictions))
1503
+ merged.update(image_financial_lines.assemble(record, predictions))
1504
+ annotations = record["_meta"]["extraction_contract"]["fields"]
1505
+ for name, annotation in annotations.items():
1506
+ if annotation.get("source_fields"):
1507
+ merged[name] = table_rows.assemble(
1508
+ predictions,
1509
+ annotation["source_rows"],
1510
+ annotation["source_fields"],
1511
+ eligibility=annotation.get("source_row_eligibility", False),
1512
+ )
1513
+ truncated = any(
1514
+ (
1515
+ not predictions[n].get("valid", False)
1516
+ for (n, _, _) in tasks
1517
+ if not annotations.get(n, {}).get("parent")
1518
+ )
1519
+ )
1520
+ truncated |= any(
1521
+ (
1522
+ not merged[name]["valid"] or not merged[name]["complete"]
1523
+ for name in record.get("_financial_line_plans", {})
1524
+ )
1525
+ )
1526
+ for name, annotation in record["_meta"]["extraction_contract"][
1527
+ "fields"
1528
+ ].items():
1529
+ if annotation.get("source_fields"):
1530
+ truncated |= not merged[name]["complete"]
1531
+ if (
1532
+ annotation.get("image_row_fields")
1533
+ or annotation.get("geometric_row_fields")
1534
+ or annotation.get("ragged_row_fields")
1535
+ ):
1536
+ truncated |= (
1537
+ not merged[name]["valid"] or not merged[name]["complete"]
1538
+ )
1539
+ queries = annotation.get("query_fields")
1540
+ if queries:
1541
+ used = []
1542
+ for child in queries:
1543
+ used.append(predictions[child])
1544
+ if predictions[child]["value"] is None:
1545
+ break
1546
+ valid = all((child.get("valid", True) for child in used))
1547
+ complete = (
1548
+ valid
1549
+ and used[-1]["value"] is None
1550
+ and used[-1].get("complete", True)
1551
+ )
1552
+ merged[name].update(valid=valid, complete=complete)
1553
+ merged[name].update(
1554
+ p_null=used[0]["p_null"],
1555
+ p_null_method="first_item_null_probability",
1556
+ p_nulls=[
1557
+ child["p_null"]
1558
+ for child in used
1559
+ if child["value"] is not None
1560
+ ],
1561
+ )
1562
+ if all((child.get("decoder") == ar.VERSION for child in used)):
1563
+ merged[name]["confidence"] = 0.0
1564
+ if all(("log_probability" in child for child in used)):
1565
+ log_probability = sum(
1566
+ (child["log_probability"] for child in used)
1567
+ )
1568
+ merged[name].update(
1569
+ confidence=math.exp(min(0.0, log_probability))
1570
+ if complete
1571
+ else 0.0,
1572
+ log_probability=log_probability,
1573
+ confidence_method="ar_sequence_probability_with_structural_end"
1574
+ if any(
1575
+ (
1576
+ child.get("grounding_method")
1577
+ == "source_row_bound"
1578
+ for child in used
1579
+ )
1580
+ )
1581
+ else "ar_sequence_probability",
1582
+ )
1583
+ merged[name]["spans"] = [
1584
+ child.get("span")
1585
+ for child in used
1586
+ if child["value"] is not None
1587
+ ]
1588
+ truncated |= not complete
1589
+ merged = cm.merge_forecasts(merged, forecasts) if forecasts else merged
1590
+ answers = {
1591
+ name: {"type": spec["type"], **merged[name]}
1592
+ for (name, spec) in request.fields.items()
1593
+ }
1594
+ state_tokens = len(
1595
+ self.tokenizer.encode(request.state, add_special_tokens=False)
1596
+ )
1597
+ input_tokens = sum((len(ids) for (_, ids, _) in tasks)) + (
1598
+ len(item.input_ids) if item is not None else 0
1599
+ )
1600
+ input_tokens += sum(
1601
+ (v.get("retry_input_tokens", 0) for (_, v) in outputs[: len(tasks)])
1602
+ )
1603
+ input_tokens += sum(
1604
+ (
1605
+ v.get("retry_input_tokens", 0)
1606
+ - v["identifier_spelling_attempt"].get("retry_input_tokens", 0)
1607
+ for v in predictions.values()
1608
+ if v.get("identifier_spelling_fallback")
1609
+ )
1610
+ )
1611
+ input_tokens += sum((len(ids) for (_, ids, _) in date_tasks))
1612
+ input_tokens += sum((len(ids) for (_, ids, _) in receipt_tasks))
1613
+ unexecuted = record.get("_unexecuted_list_items", {})
1614
+ input_tokens -= sum(unexecuted.values())
1615
+ input_work = (
1616
+ len(tasks)
1617
+ + (item is not None)
1618
+ - len(unexecuted)
1619
+ + len(identifier_fallback_results)
1620
+ + len(date_tasks)
1621
+ + len(receipt_tasks)
1622
+ )
1623
+ image_id: Any = getattr(self.processor, "image_token_id", None)
1624
+ image_tokens = (
1625
+ tasks[0][1].count(image_id)
1626
+ if record.get("_media_payload") and tasks
1627
+ else list(item.input_ids).count(image_id)
1628
+ if record.get("_media_payload") and item is not None
1629
+ else 0
1630
+ )
1631
+ return PredictOutput(
1632
+ answers=answers,
1633
+ truncated=truncated,
1634
+ state_tokens=state_tokens,
1635
+ image_tokens=image_tokens,
1636
+ schema_tokens=max(
1637
+ 0, input_tokens - (state_tokens + image_tokens) * input_work
1638
+ ),
1639
+ input_tokens=input_tokens,
1640
+ output_tokens=sum((v["tokens"] for (_, v) in outputs[: len(tasks)]))
1641
+ + sum((v["tokens"] for v in identifier_fallback_results.values()))
1642
+ + sum((v["tokens"] for v in date_results.values()))
1643
+ + sum((v["tokens"] for v in receipt_readings)),
1644
+ passes=max(
1645
+ [1]
1646
+ + [v["tokens"] for (_, v) in outputs[: len(tasks)]]
1647
+ + [
1648
+ predictions[name]["tokens"]
1649
+ for name in identifier_fallback_results
1650
+ ]
1651
+ + [v["tokens"] for v in date_results.values()]
1652
+ + [v["tokens"] for v in receipt_readings]
1653
+ ),
1654
+ state_text=request.state,
1655
+ )
1656
+ except (ClairRequestError, ClairQueueFull):
1657
+ raise
1658
+ except Exception as error:
1659
+ raise ClairInferenceError(
1660
+ "Clairic Transformers inference failed"
1661
+ ) from error
1662
+ finally:
1663
+ await asyncio.shield(
1664
+ asyncio.create_task(
1665
+ self._release_request(work, encoding, receipt_progress["encodings"])
1666
+ )
1667
+ )
1668
+
1669
+ async def _release_request(
1670
+ self,
1671
+ work: Sequence[asyncio.Task[Any]],
1672
+ encoding: asyncio.Future[Any] | None,
1673
+ extra_encodings: Sequence[asyncio.Future[Any]] = (),
1674
+ ) -> None:
1675
+ for task in work:
1676
+ if not task.done():
1677
+ task.cancel()
1678
+ if work:
1679
+ await asyncio.gather(*work, return_exceptions=True)
1680
+ await self.engine.end_request()
1681
+ if extra_encodings:
1682
+ encoding = asyncio.gather(
1683
+ *([encoding] if encoding is not None else []),
1684
+ *extra_encodings,
1685
+ return_exceptions=True,
1686
+ )
1687
+ if encoding is not None and (not encoding.done()):
1688
+ encoding.add_done_callback(self._release_encoding)
1689
+ else:
1690
+ self._in_flight -= 1
1691
+
1692
+ def _release_encoding(self, future: asyncio.Future[Any]) -> None:
1693
+ if not future.cancelled():
1694
+ future.exception()
1695
+ self._in_flight -= 1
1696
+
1697
+ def shutdown(self) -> None:
1698
+ self._encoder.shutdown(wait=False, cancel_futures=True)
1699
+ self.engine.shutdown()
1700
+
1701
+ @classmethod
1702
+ def load(
1703
+ cls,
1704
+ settings: RuntimeSettings,
1705
+ **model_kwargs: Any,
1706
+ ) -> ClairicFlashModel:
1707
+ # MLX port: the tokenizer is unchanged; the processor and engine are the torch-free MLX versions.
1708
+ from transformers import AutoTokenizer
1709
+ from .mlx_engine import MLXEngine
1710
+ from .processor import ClairicProcessor
1711
+
1712
+ path = Path(settings.model_path)
1713
+ tokenizer = AutoTokenizer.from_pretrained(path, local_files_only=True)
1714
+ validate_eos(path, tokenizer)
1715
+ for token in ("null", "false"):
1716
+ if tokenizer.encode(token, add_special_tokens=False) != [
1717
+ tokenizer.convert_tokens_to_ids(token)
1718
+ ]:
1719
+ raise ValueError(f"{token} must be one token for confidence scoring")
1720
+ processor = ClairicProcessor(path, tokenizer, 1600000)
1721
+ engine = MLXEngine(path, tokenizer, **model_kwargs)
1722
+ return cls(
1723
+ engine,
1724
+ tokenizer,
1725
+ processor,
1726
+ settings,
1727
+ json.loads((path / "clair_head_config.json").read_text()),
1728
+ )
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/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/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/mlx_engine.py ADDED
@@ -0,0 +1,918 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Clairic inference on Apple silicon with MLX.
2
+
3
+ Not part of the Cloudflare release: this module replaces its PyTorch engine (`native.py`, `math.py`,
4
+ `readout.py`, the typed head in `model.py` and the CUDA kernels). It keeps the same two entry points the request
5
+ pipeline calls, with the same inputs and outputs:
6
+
7
+ - `read_typed(item, media)`: one forward pass of the backbone over the typed-field prompt; the final hidden
8
+ states feed the typed head (dates, times, durations, computed numbers, estimates, forecasts);
9
+ - `async_generate(...)`: greedy decoding constrained by an xgrammar grammar (JSON schema, regex or EBNF), one
10
+ prompt per field or list item. Token log-probabilities are taken after the grammar mask, as upstream does.
11
+
12
+ The backbone is mlx-vlm's `qwen3_5` model (causal full attention every fourth layer, Gated DeltaNet linear
13
+ attention elsewhere) run through an explicit layer loop with a key/value cache for the attention layers and a
14
+ recurrent state plus convolution window for the linear layers.
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ import asyncio
20
+ import concurrent.futures
21
+ import hashlib
22
+ import json
23
+ import threading
24
+ from collections import defaultdict
25
+ from collections.abc import Callable
26
+ from dataclasses import dataclass, field
27
+ from pathlib import Path
28
+ from typing import Any
29
+
30
+ import mlx.core as mx
31
+ import mlx.nn as nn
32
+ import numpy as np
33
+ from mlx_vlm.models.qwen3_5 import Model, ModelConfig
34
+ from mlx_vlm.models.qwen3_5.gated_delta import gated_delta_update
35
+
36
+ from . import model as cm
37
+
38
+ ATTENTION_ELEMENTS = 1 << 27 # attention scores per call (batch x heads x queries x keys); bounds temporaries
39
+ SEGMENT_TOKENS = 1024 # tokens (rows x length) run through the layers at once; longer inputs go in segments
40
+ MEMORY_FRACTION = 0.75 # default ceiling on MLX memory, as a fraction of the machine's RAM
41
+ ROPE_MODES = ("mrope", "temporal")
42
+
43
+
44
+ class PreciseRMSNorm(nn.Module):
45
+ """RMSNorm computed in fp32 and cast back, as the reference does. The weight is stored as (1 + w) in fp32."""
46
+
47
+ def __init__(self, dims: int, eps: float) -> None:
48
+ super().__init__()
49
+ self.weight = mx.ones((dims,))
50
+ self.eps = eps
51
+
52
+ def __call__(self, x: mx.array) -> mx.array:
53
+ return mx.fast.rms_norm(x.astype(mx.float32), self.weight.astype(mx.float32), self.eps).astype(x.dtype)
54
+
55
+
56
+ @dataclass
57
+ class Cache:
58
+ """Per-layer state after a prefix: attention keys/values, or the linear layers' memory and conv window."""
59
+
60
+ keys: list[mx.array | None]
61
+ values: list[mx.array | None]
62
+ memory: list[mx.array | None]
63
+ window: list[mx.array | None]
64
+ valid: mx.array | None = None # [B, T] False on padding; None when no row is padded
65
+ length: int = 0
66
+ position: mx.array | None = None # [B] rotary position of the next token
67
+
68
+ @classmethod
69
+ def empty(cls, layers: int) -> Cache:
70
+ return cls([None] * layers, [None] * layers, [None] * layers, [None] * layers)
71
+
72
+ def arrays(self) -> list[mx.array]:
73
+ return [a for group in (self.keys, self.values, self.memory, self.window) for a in group if a is not None]
74
+
75
+
76
+ # ---------------------------------------------------------------------------------------------- typed head
77
+ def _normalize(x: mx.array) -> mx.array:
78
+ return x / mx.maximum(mx.sqrt((x * x).sum(axis=-1, keepdims=True)), 1e-12)
79
+
80
+
81
+ def _span_scores(start: mx.array, end: mx.array, length_bias: mx.array) -> mx.array:
82
+ """scores[q, s, l] = start[q, s] + end[q, s + l] + bias[l]; spans running past the input are -inf."""
83
+ width, tokens = length_bias.shape[0], end.shape[1]
84
+ padded = mx.concatenate([end, mx.full((end.shape[0], width - 1), -mx.inf, dtype=end.dtype)], axis=1)
85
+ index = mx.arange(tokens)[:, None] + mx.arange(width)[None, :]
86
+ return start[:, :, None] + padded[:, index] + length_bias
87
+
88
+
89
+ def _two_digits(slots: mx.array, values: range) -> mx.array:
90
+ tens = mx.array([value // 10 for value in values])
91
+ ones = mx.array([value % 10 for value in values])
92
+ return slots[:, 0, :][:, tens] + slots[:, 1, :][:, ones]
93
+
94
+
95
+ def _years(slots: mx.array) -> mx.array:
96
+ index = [[int(f"{year:04d}"[position]) for year in range(cm.YEAR_LOW, cm.YEAR_HIGH + 1)]
97
+ for position in range(cm.YEAR_DIGITS)]
98
+ inside = sum(slots[:, position, :][:, mx.array(index[position])] for position in range(cm.YEAR_DIGITS))
99
+ total = mx.logsumexp(slots, axis=-1).sum(axis=-1)
100
+ gap = mx.minimum(mx.logsumexp(inside, axis=-1) - total, -1e-06)
101
+ outside = total + mx.log(-mx.expm1(gap))
102
+ return mx.concatenate([inside, outside[:, None]], axis=-1)
103
+
104
+
105
+ class TypedHead:
106
+ """The Clairic typed head (`clair_head.safetensors`) with the lexical readout, evaluated in fp32.
107
+
108
+ A port of upstream `ClairicHead.forward_lexical` and `answer_slot_states`: field queries are routed through
109
+ two pre-norm transformer decoder layers that cross-attend the prompt, then read out as span pointers,
110
+ digit / month / sign slots, estimate bins and list-item states.
111
+ """
112
+
113
+ REQUIRED = {"readout": "lexical", "estimate_lexical": True, "span_trim": True, "answer_slots": True,
114
+ "answer_slot_routing": True, "number_groups": True, "number_pointer": True}
115
+
116
+ def __init__(self, path: Path, round_bf16: bool) -> None:
117
+ self.config = json.loads((path / "clair_head_config.json").read_text())
118
+ for name, value in self.REQUIRED.items():
119
+ if self.config.get(name) != value:
120
+ raise ValueError(f"unsupported typed head: {name} must be {value!r}")
121
+ if self.config.get("loop_feedback"):
122
+ raise ValueError("unsupported typed head: loop_feedback")
123
+ weights = mx.load(str(path / "clair_head.safetensors"))
124
+ if round_bf16:
125
+ # Upstream serving builds the head in bf16 before widening it to fp32 (the length bias excepted).
126
+ weights = {name: value if name == "length_bias" else value.astype(mx.bfloat16)
127
+ for name, value in weights.items()}
128
+ self.w = {name: value.astype(mx.float32) for name, value in weights.items()}
129
+ mx.eval(self.w)
130
+ self.bins = self.w["bins.weight"].shape[0]
131
+ self.pointer_width = int(self.config["pointer_width"])
132
+ self.heads = int(self.config["route_heads"])
133
+ self.layers = int(self.config["route_layers"])
134
+ self.slot_rank = int(self.config["slot_rank"])
135
+
136
+ def eval(self) -> TypedHead:
137
+ return self
138
+
139
+ # ---- building blocks
140
+ def linear(self, name: str, x: mx.array) -> mx.array:
141
+ y = x @ self.w[f"{name}.weight"].T
142
+ bias = self.w.get(f"{name}.bias")
143
+ return y if bias is None else y + bias
144
+
145
+ def norm(self, name: str, x: mx.array) -> mx.array:
146
+ return mx.fast.layer_norm(x, self.w[f"{name}.weight"], self.w[f"{name}.bias"], 1e-5)
147
+
148
+ def _project(self, prefix: str, part: int, x: mx.array) -> mx.array:
149
+ weight, bias = self.w[f"{prefix}.in_proj_weight"], self.w[f"{prefix}.in_proj_bias"]
150
+ width = weight.shape[1]
151
+ y = x @ weight[part * width:(part + 1) * width].T + bias[part * width:(part + 1) * width]
152
+ return y.reshape(*x.shape[:-1], self.heads, -1).transpose(0, 2, 1, 3)
153
+
154
+ def _attention(self, prefix: str, queries: mx.array, keys: mx.array, values: mx.array,
155
+ mask: mx.array | None) -> mx.array:
156
+ batch = queries.shape[0]
157
+ if keys.shape[0] != batch:
158
+ keys = mx.broadcast_to(keys, (batch, *keys.shape[1:]))
159
+ values = mx.broadcast_to(values, (batch, *values.shape[1:]))
160
+ out = mx.fast.scaled_dot_product_attention(queries, keys, values, scale=queries.shape[-1] ** -0.5, mask=mask)
161
+ out = out.transpose(0, 2, 1, 3).reshape(batch, queries.shape[2], -1)
162
+ return self.linear(f"{prefix}.out_proj", out)
163
+
164
+ def _memory(self, hidden: mx.array, stop: int) -> list[tuple[mx.array, mx.array]]:
165
+ """The prompt as cross-attention memory: each route layer's keys and values, computed once per read."""
166
+ memory = self.linear("memory_in", self.norm("token_norm", hidden[:stop]))[None]
167
+ projected = []
168
+ for layer in range(self.layers):
169
+ prefix = f"route_layers.{layer}.multihead_attn"
170
+ projected.append((self._project(prefix, 1, memory), self._project(prefix, 2, memory)))
171
+ mx.eval(projected)
172
+ return projected
173
+
174
+ def _route_layers(self, queries: mx.array, memory: list[tuple[mx.array, mx.array]],
175
+ padding: mx.array | None = None) -> mx.array:
176
+ """`nn.TransformerDecoderLayer(norm_first=True, activation="gelu")` stack; `padding` marks ignored keys."""
177
+ mask = None if padding is None else mx.logical_not(padding)[:, None, None, :]
178
+ for layer, (keys, values) in enumerate(memory):
179
+ prefix = f"route_layers.{layer}"
180
+ x = self.norm(f"{prefix}.norm1", queries)
181
+ queries = queries + self._attention(
182
+ f"{prefix}.self_attn", self._project(f"{prefix}.self_attn", 0, x),
183
+ self._project(f"{prefix}.self_attn", 1, x), self._project(f"{prefix}.self_attn", 2, x), mask)
184
+ x = self.norm(f"{prefix}.norm2", queries)
185
+ queries = queries + self._attention(
186
+ f"{prefix}.multihead_attn", self._project(f"{prefix}.multihead_attn", 0, x), keys, values, None)
187
+ x = self.norm(f"{prefix}.norm3", queries)
188
+ queries = queries + self.linear(f"{prefix}.linear2", nn.gelu(self.linear(f"{prefix}.linear1", x)))
189
+ return queries
190
+
191
+ # ---- readouts
192
+ def typed_logits(self, raw: mx.array, routed: mx.array) -> tuple[mx.array, mx.array, mx.array]:
193
+ count, slots = raw.shape[0], cm.DIGIT_SLOTS
194
+ scale = mx.exp(mx.minimum(self.w["lexical_scale"], float(np.log(100.0))))
195
+ unit = _normalize(raw)
196
+ down = (raw @ self.w["slot_down.weight"].T).reshape(count, slots + 2, self.slot_rank)
197
+ digit_prior = (unit @ _normalize(self.w["digit_rows"]).T)[:, None, :]
198
+ month_prior = unit @ _normalize(self.w["month_rows"]).T
199
+ sign_prior = unit @ _normalize(self.w["sign_rows"]).T
200
+ residual = mx.sigmoid(self.w["residual_gate"]) * self.linear("slot_residual", routed)
201
+ digit_residual = residual[:, : slots * 10].reshape(count, slots, 10)
202
+ month_residual, sign_residual = residual[:, slots * 10: slots * 10 + 12], residual[:, slots * 10 + 12:]
203
+ return (
204
+ scale[0] * digit_prior + mx.einsum("nsr,srd->nsd", down[:, :slots], self.w["slot_up"]) + digit_residual,
205
+ scale[1] * month_prior + down[:, slots] @ self.w["month_up"] + month_residual,
206
+ scale[2] * sign_prior + down[:, slots + 1] @ self.w["sign_up"] + sign_residual,
207
+ )
208
+
209
+ def typed_outputs(self, raw: mx.array, states: mx.array, routed: mx.array) -> dict[str, mx.array]:
210
+ digits, months, signs = self.typed_logits(raw, routed)
211
+ count = raw.shape[0]
212
+ year_slots = digits[:, cm.YEAR_SLOT: cm.YEAR_SLOT + cm.YEAR_DIGITS]
213
+ return {
214
+ "number": mx.concatenate([signs, self.linear("exponent", states),
215
+ digits[:, : cm.NUMBER_DIGITS].reshape(count, -1)], axis=-1),
216
+ "date": mx.concatenate([year_slots.reshape(count, -1), _years(year_slots), months,
217
+ _two_digits(digits[:, cm.DAY_SLOT: cm.DAY_SLOT + 2], range(1, 32))], axis=-1),
218
+ "time": mx.concatenate([_two_digits(digits[:, cm.HOUR_SLOT: cm.HOUR_SLOT + 2], range(24)),
219
+ _two_digits(digits[:, cm.MINUTE_SLOT: cm.MINUTE_SLOT + 2], range(60)),
220
+ _two_digits(digits[:, cm.SECOND_SLOT: cm.SECOND_SLOT + 2], range(60))], axis=-1),
221
+ }
222
+
223
+ def group_scores(self, states: mx.array) -> mx.array:
224
+ return self.linear("number_group_up", nn.gelu(self.linear("number_group_down", states))).reshape(
225
+ -1, cm.NUMBER_GROUPS, cm.GROUP_CLASSES)
226
+
227
+ def temper_number(self, logits: mx.array, spread: mx.array) -> mx.array:
228
+ classes, digits = cm.EXPONENT_CLASSES, cm.NUMBER_DIGITS
229
+ sign, exponent = logits[:, :2], logits[:, 2: 2 + classes]
230
+ slots = logits[:, 2 + classes:].reshape(-1, digits, 10)
231
+ limit = cm.ESTIMATE_SPREAD_LIMIT
232
+ temperature = mx.exp(limit * mx.tanh(spread / limit))
233
+ slots = mx.concatenate([slots[:, : cm.LEXICAL_DIGITS] / temperature[:, 1:, None], slots[:, cm.LEXICAL_DIGITS:]], axis=1)
234
+ return mx.concatenate([sign, exponent / temperature[:, :1], slots.reshape(slots.shape[0], -1)], axis=-1)
235
+
236
+ def forward(self, hidden: mx.array, start: int, stop: int, views: dict[str, np.ndarray],
237
+ memory: list[tuple[mx.array, mx.array]]) -> dict[str, mx.array]:
238
+ """Upstream `forward_lexical`: `hidden` is [tokens, width] in fp32, `views` the index arrays."""
239
+ if any(name.endswith("_prefix_length") for name in views):
240
+ raise ValueError("prefixed number readouts are not supported")
241
+ rows = {name: np.asarray(value) for name, value in views.items()}
242
+ queries = rows["query_positions"]
243
+ item_kinds = [kind for kind in cm.LIST_KINDS if rows[f"{kind}_rows"].shape[0]]
244
+ positions = np.concatenate([queries] + [rows[f"{kind}_items"].reshape(-1) for kind in item_kinds])
245
+ kinds = np.zeros(positions.shape[0], dtype=np.int64)
246
+ for index, group in enumerate(cm.ROUTE_KINDS):
247
+ kinds[rows[f"{group}_rows"]] = index
248
+ offset = queries.shape[0]
249
+ for kind in item_kinds:
250
+ size = rows[f"{kind}_items"].size
251
+ kinds[offset: offset + size] = len(cm.ROUTE_KINDS) + cm.LIST_KINDS.index(kind)
252
+ offset += size
253
+
254
+ def take(values: mx.array, index: np.ndarray) -> mx.array:
255
+ return values[mx.array(index.astype(np.int32))]
256
+
257
+ raw = take(hidden, positions)
258
+ routed = self._route_layers(
259
+ (self.linear("route_in", self.norm("norm", raw)) + take(self.w["kind_embedding.weight"], kinds))[None], memory)
260
+ routed = self.norm("route_norm", routed[0])
261
+ states = self.norm("norm", raw) + mx.sigmoid(self.w["route_gate"]) * self.linear("route_out", routed)
262
+ count = queries.shape[0]
263
+ output: dict[str, mx.array] = {"null": self.linear("null", states[:count])[:, 0]}
264
+ field_states, field_raw, field_routed = states[:count], raw[:count], routed[:count]
265
+ text, tags, numbers = rows["text_rows"], rows["tags_rows"], rows["number_rows"]
266
+ scale = 1.0 / float(np.sqrt(self.pointer_width))
267
+ tokens = None
268
+ if text.shape[0] or tags.shape[0] or numbers.shape[0]:
269
+ tokens = self.norm("token_norm", hidden[start:stop])
270
+ if text.shape[0] or tags.shape[0]:
271
+ output["trim"] = self.linear("trim", tokens).reshape(-1, 2, cm.TRIM_CLASSES)
272
+
273
+ def pointer(query: str, selected: mx.array) -> mx.array:
274
+ query_start, query_end = mx.split(self.linear(query, selected), 2, axis=-1)
275
+ key_start, key_end = mx.split(self.linear("span_key", tokens), 2, axis=-1)
276
+ return _span_scores(query_start @ key_start.T * scale, query_end @ key_end.T * scale, self.w["length_bias"])
277
+
278
+ if numbers.shape[0]:
279
+ number_states = take(field_states, numbers)
280
+ output["number_copy"] = pointer("copy_query", number_states)
281
+ output["number_copy_gate"] = self.linear("copy_gate", number_states)[:, 0]
282
+ if text.shape[0]:
283
+ output["text"] = pointer("span_query", take(field_states, text))
284
+ if tags.shape[0]:
285
+ query_begin, query_inside = mx.split(self.linear("tag_query", take(field_states, tags)), 2, axis=-1)
286
+ keys = self.linear("tag_key", tokens)
287
+ begin = query_begin @ keys.T * scale + self.w["tag_bias"][0]
288
+ inside = query_inside @ keys.T * scale + self.w["tag_bias"][1]
289
+ output["tags"] = mx.stack([mx.zeros_like(begin), begin, inside], axis=-1)
290
+ typed_rows = [rows[f"{group}_rows"] for group in ("number", "date", "time")]
291
+ if any(selected.shape[0] for selected in typed_rows):
292
+ selected = np.concatenate(typed_rows)
293
+ typed = self.typed_outputs(take(field_raw, selected), take(field_states, selected), take(field_routed, selected))
294
+ offset = 0
295
+ for group, selected in zip(("number", "date", "time"), typed_rows):
296
+ if selected.shape[0]:
297
+ output[group] = typed[group][offset: offset + selected.shape[0]]
298
+ offset += selected.shape[0]
299
+ if "number" in output:
300
+ output["number_groups"] = self.group_scores(take(field_states, numbers))
301
+ estimates = rows["estimate_rows"]
302
+ if estimates.shape[0]:
303
+ estimate_states = take(field_states, estimates)
304
+ output["estimate"] = self.linear("bins", estimate_states)
305
+ output["estimate_offset"] = self.linear("offset", estimate_states)
306
+ output["estimate_overflow"] = self.linear("overflow", estimate_states)
307
+ number_logits = self.typed_outputs(take(field_raw, estimates), estimate_states, take(field_routed, estimates))["number"]
308
+ output["estimate_number_raw"] = number_logits
309
+ output["estimate_number"] = self.temper_number(number_logits, self.linear("estimate_spread", estimate_states))
310
+ output["estimate_gate"] = self.linear("estimate_gate", estimate_states)[:, 0]
311
+ offset = count
312
+ for kind in item_kinds:
313
+ shape = rows[f"{kind}_items"].shape
314
+ size = shape[0] * shape[1]
315
+ item_states, item_raw, item_routed = (
316
+ states[offset: offset + size], raw[offset: offset + size], routed[offset: offset + size])
317
+ offset += size
318
+ output[f"{kind}_end"] = self.linear("item_end", item_states)[:, 0].reshape(shape)
319
+ group = "number" if kind == "number_list" else "date"
320
+ output[kind] = self.typed_outputs(item_raw, item_states, item_routed)[group].reshape(*shape, -1)
321
+ if kind == "number_list":
322
+ output["number_list_groups"] = self.group_scores(item_states).reshape(
323
+ *shape, cm.NUMBER_GROUPS, cm.GROUP_CLASSES)
324
+ return output
325
+
326
+ def answer_slot_states(self, hidden: mx.array, field_queries: np.ndarray, kinds: np.ndarray, positions: np.ndarray,
327
+ lengths: np.ndarray, stop: int, memory: list[tuple[mx.array, mx.array]],
328
+ chunk: int = 256) -> mx.array:
329
+ """Upstream `answer_slot_states`: each answer-slot position corrected by evidence routed from the prompt."""
330
+ width = positions.shape[1]
331
+ if (width < 1 or positions.shape[0] != field_queries.shape[0] or (lengths < 1).any() or (lengths > width).any()
332
+ or not 0 < stop <= hidden.shape[0]):
333
+ raise ValueError("invalid answer-slot routing layout")
334
+ gate = mx.sigmoid(self.w["route_gate"])
335
+ output = []
336
+ field_batch = max(1, min(chunk // (width + 1), 262144 // stop))
337
+ for first in range(0, positions.shape[0], field_batch):
338
+ last = first + field_batch
339
+ slot_positions = mx.array(positions[first:last].astype(np.int32))
340
+ query_positions = mx.concatenate([mx.array(field_queries[first:last, None].astype(np.int32)), slot_positions], axis=1)
341
+ row_lengths = mx.array(lengths[first:last].astype(np.int32))
342
+ row_kinds = mx.array(kinds[first:last].astype(np.int32))
343
+ padding = mx.arange(width + 1)[None, :] > row_lengths[:, None]
344
+ queries = self.linear("route_in", self.norm("norm", hidden[query_positions]))
345
+ queries = self._route_layers(queries + self.w["kind_embedding.weight"][row_kinds][:, None, :], memory, padding)
346
+ evidence = self.linear("route_out", self.norm("route_norm", queries[:, 1:]))
347
+ scale = mx.tanh(self.w["slot_route_scale"][row_kinds])[:, None, None]
348
+ corrected = hidden[slot_positions] + scale * gate * evidence
349
+ index = mx.minimum(mx.arange(width)[None, :], row_lengths[:, None] - 1)
350
+ output.append(mx.take_along_axis(corrected, index[:, :, None], axis=1))
351
+ mx.eval(output[-1])
352
+ return mx.concatenate(output, axis=0)
353
+
354
+
355
+ # ---------------------------------------------------------------------------------------------- engine
356
+ @dataclass
357
+ class _Rows:
358
+ """One right-padded batch: token ids, which positions are real, and the rows' image inputs in order."""
359
+
360
+ ids: np.ndarray
361
+ valid: np.ndarray
362
+ media: list[dict[str, Any]] = field(default_factory=list)
363
+
364
+ @property
365
+ def lengths(self) -> np.ndarray:
366
+ return self.valid.sum(axis=1)
367
+
368
+
369
+ def _common_prefix(sequences: list[list[int]]) -> int:
370
+ first, last = min(sequences), max(sequences)
371
+ return next((i for i, (a, b) in enumerate(zip(first, last)) if a != b), min(len(first), len(last)))
372
+
373
+
374
+ class MLXEngine:
375
+ """Share one MLX backbone between grammar-constrained extraction and typed readouts."""
376
+
377
+ def __init__(self, path: Path, tokenizer: Any, *, batch_size: int = 8, batch_token_budget: int = 8192,
378
+ rope: str = "temporal", device: str = "gpu", memory_limit_gb: float | None = None) -> None:
379
+ import xgrammar as xgr
380
+
381
+ if rope not in ROPE_MODES:
382
+ raise ValueError(f"rope must be one of {ROPE_MODES}")
383
+ self.path, self.tokenizer, self.rope = Path(path), tokenizer, rope
384
+ self.batch_size, self.batch_token_budget = max(1, int(batch_size)), max(1, int(batch_token_budget))
385
+ self.text_batch_size = self.batch_size
386
+ self.device = device # "gpu", or "cpu" for bit-accurate float32 checks (slow)
387
+ self.capture: Callable[[str, Any], None] | None = None # test hook: receives intermediate arrays
388
+ # A request that would need more memory than this fails with an error instead of exhausting the machine.
389
+ self.memory_cap = int((memory_limit_gb * 1e9) if memory_limit_gb else MEMORY_FRACTION * mx.device_info()["memory_size"])
390
+ self._worker = concurrent.futures.ThreadPoolExecutor(max_workers=1, thread_name_prefix="clairic-model")
391
+ self._features: dict[str, mx.array] = {}
392
+ self._prefixes: dict[tuple, Cache] = {}
393
+ self.prefix_cache = True # read a request's images once and continue every prompt from that state
394
+ # Every MLX call happens on the worker thread, including loading the weights.
395
+ self._worker.submit(self._load).result()
396
+ self.eos = tokenizer.convert_tokens_to_ids("<|im_end|>")
397
+ self.pad = tokenizer.pad_token_id if tokenizer.pad_token_id is not None else self.eos
398
+ self.vocab = self.lm.lm_head.weight.shape[0]
399
+ info = xgr.TokenizerInfo.from_huggingface(tokenizer, vocab_size=self.vocab, stop_token_ids=[self.eos])
400
+ self.compiler = xgr.GrammarCompiler(info, max_threads=2)
401
+ self._xgr = xgr
402
+
403
+ # ---- loading
404
+ def _load(self) -> None:
405
+ path = self.path
406
+ if self.device == "cpu":
407
+ mx.set_default_device(mx.cpu)
408
+ config = json.loads((path / "config.json").read_text())
409
+ self.model = Model(ModelConfig.from_dict(config))
410
+ self.lm = self.model.language_model
411
+ text = self.lm.model
412
+ hidden, eps = config["text_config"]["hidden_size"], config["text_config"]["rms_norm_eps"]
413
+ text.norm = PreciseRMSNorm(hidden, eps)
414
+ for layer in text.layers:
415
+ layer.input_layernorm = PreciseRMSNorm(hidden, eps)
416
+ layer.post_attention_layernorm = PreciseRMSNorm(hidden, eps)
417
+ if not layer.is_linear:
418
+ layer.self_attn.q_norm = PreciseRMSNorm(layer.self_attn.head_dim, eps)
419
+ layer.self_attn.k_norm = PreciseRMSNorm(layer.self_attn.head_dim, eps)
420
+ weights: dict[str, mx.array] = {}
421
+ for shard in sorted(path.glob("model*.safetensors")):
422
+ weights.update(mx.load(str(shard)))
423
+ if quantization := config.get("quantization"):
424
+ def quantized(path: str, module: nn.Module) -> bool | dict:
425
+ if not hasattr(module, "to_quantized") or f"{path}.scales" not in weights:
426
+ return False
427
+ settings = quantization.get(path) # modules with their own bit width
428
+ return settings if isinstance(settings, dict) else True
429
+
430
+ nn.quantize(self.model, group_size=quantization["group_size"], bits=quantization["bits"],
431
+ mode=quantization.get("mode", "affine"), class_predicate=quantized)
432
+ self.model.load_weights(list(weights.items()), strict=True)
433
+ self.model.eval()
434
+ mx.eval(self.model.parameters())
435
+ self.image_token = int(config["image_token_id"])
436
+ self.vision_end = int(config["vision_end_token_id"])
437
+ self.dtype = text.layers[0].linear_attn.conv1d.weight.dtype # never quantized: bf16 (release) or fp32
438
+ self.backbone = self.model
439
+ self.head = TypedHead(path, round_bf16=self.dtype != mx.float32)
440
+
441
+ # ---- request scope (image features are kept for one request)
442
+ def begin_request(self) -> None:
443
+ self._features, self._prefixes = {}, {}
444
+
445
+ async def end_request(self) -> None:
446
+ await asyncio.get_running_loop().run_in_executor(self._worker, self._clear)
447
+
448
+ def _clear(self) -> None:
449
+ self._features, self._prefixes = {}, {}
450
+ mx.clear_cache()
451
+
452
+ def shutdown(self) -> None:
453
+ self._worker.shutdown(wait=True, cancel_futures=True)
454
+ self._features, self._prefixes = {}, {}
455
+
456
+ def _check_memory(self) -> None:
457
+ if mx.get_active_memory() > self.memory_cap:
458
+ mx.clear_cache()
459
+ if mx.get_active_memory() > self.memory_cap:
460
+ raise MemoryError(
461
+ f"this request needs more than the {self.memory_cap / 1e9:.0f} GB memory limit; "
462
+ "shorten the input, lower batch_token_budget, or raise memory_limit_gb")
463
+
464
+ # ---- backbone
465
+ def _image_features(self, mapping: dict[str, Any]) -> mx.array:
466
+ key = mapping.get("clair_pixels_key")
467
+ if key is None:
468
+ pixels = np.asarray(mapping["pixel_values"])
469
+ key = hashlib.sha1(pixels.tobytes() + np.asarray(mapping["image_grid_thw"]).tobytes()).hexdigest()
470
+ if key not in self._features:
471
+ tower = self.model.vision_tower
472
+ pixels = mx.array(mapping["pixel_values"]).astype(tower.patch_embed.proj.weight.dtype)
473
+ features, _ = tower(pixels, mx.array(np.asarray(mapping["image_grid_thw"])))
474
+ mx.eval(features)
475
+ self._features[key] = features
476
+ return self._features[key]
477
+
478
+ def _rows(self, sequences: list[list[int]], media: list[Any]) -> _Rows:
479
+ width = max(map(len, sequences))
480
+ ids = np.full((len(sequences), width), self.pad, dtype=np.int32)
481
+ valid = np.zeros((len(sequences), width), dtype=bool)
482
+ for row, sequence in enumerate(sequences):
483
+ ids[row, : len(sequence)] = sequence
484
+ valid[row, : len(sequence)] = True
485
+ return _Rows(ids, valid, [mapping for payload in media if payload for mapping in payload])
486
+
487
+ def _embed(self, rows: _Rows) -> tuple[mx.array, mx.array]:
488
+ """Input embeddings (image features merged in) and rotary positions [3, B, L] of a right-padded batch."""
489
+ tokens, mask = mx.array(rows.ids), mx.array(rows.valid.astype(np.int32))
490
+ if rows.media:
491
+ features = mx.concatenate([self._image_features(mapping) for mapping in rows.media], axis=0)
492
+ grids = mx.array(np.concatenate([np.asarray(mapping["image_grid_thw"]) for mapping in rows.media]))
493
+ embedded = self.model.get_input_embeddings(
494
+ tokens, features, image_grid_thw=grids, mask=mask, cached_image_features=features)
495
+ else:
496
+ embedded = self.model.get_input_embeddings(tokens, None, mask=mask)
497
+ positions = embedded.position_ids
498
+ if positions.ndim == 2: # text only: the same position on the three rotary axes
499
+ positions = mx.broadcast_to(positions[None], (3, *positions.shape))
500
+ return embedded.inputs_embeds, positions
501
+
502
+ def _rotary(self, positions: mx.array) -> mx.array:
503
+ # "temporal" (default) is what the upstream runtime does in bfloat16, its serving configuration: the
504
+ # rotary table is indexed by the first (temporal) position axis for every frequency, so the tokens of an
505
+ # image share one rotary position. "mrope" is the stock Transformers 3-axis rotary, which upstream runs
506
+ # in float32. Text tokens are identical in both.
507
+ if self.rope == "temporal":
508
+ return mx.broadcast_to(positions[:1], positions.shape)
509
+ return positions
510
+
511
+ def _linear(self, attention: nn.Module, x: mx.array, valid: mx.array | None, window: mx.array | None,
512
+ memory: mx.array | None, lengths: mx.array | None = None) -> tuple[mx.array, mx.array, mx.array]:
513
+ """A Gated DeltaNet layer continuing from a convolution window and recurrent memory (padding skipped)."""
514
+ batch, length, _ = x.shape
515
+ mixed = attention.in_proj_qkv(x)
516
+ z = attention.in_proj_z(x).reshape(batch, length, -1, attention.head_v_dim)
517
+ b, a = attention.in_proj_b(x), attention.in_proj_a(x)
518
+ if valid is not None:
519
+ mixed = mx.where(valid[..., None], mixed, 0)
520
+ if window is None:
521
+ window = mx.zeros((batch, attention.conv_kernel_size - 1, attention.conv_dim), dtype=mixed.dtype)
522
+ conv_input = mx.concatenate([window.astype(mixed.dtype), mixed], axis=1)
523
+ conv = nn.silu(attention.conv1d(conv_input))
524
+ q, k, v = (
525
+ t.reshape(batch, length, heads, width)
526
+ for t, heads, width in zip(
527
+ mx.split(conv, [attention.key_dim, 2 * attention.key_dim], -1),
528
+ [attention.num_k_heads, attention.num_k_heads, attention.num_v_heads],
529
+ [attention.head_k_dim, attention.head_k_dim, attention.head_v_dim], strict=True)
530
+ )
531
+ q, k = attention._normalize_qk(q, k)
532
+ out, memory = gated_delta_update(q, k, v, a, b, attention.A_log, attention.dt_bias, state=memory, mask=valid,
533
+ use_kernel=True)
534
+ out = attention.out_proj(attention.norm(out, z).reshape(batch, length, -1))
535
+ taps = attention.conv_kernel_size - 1
536
+ if lengths is None:
537
+ return out, memory, conv_input[:, -taps:]
538
+ # Right-padded rows: keep the last real inputs of each row, not the padding after them.
539
+ index = lengths[:, None] + mx.arange(taps)[None, :]
540
+ index = mx.broadcast_to(index[:, :, None], (batch, taps, conv_input.shape[-1]))
541
+ return out, memory, mx.take_along_axis(conv_input, index, axis=1)
542
+
543
+ def _attention(self, attention: nn.Module, x: mx.array, positions: mx.array, keys: mx.array | None,
544
+ values: mx.array | None, valid: mx.array | None, offset: int) -> tuple[mx.array, mx.array, mx.array]:
545
+ """Causal attention of new tokens over the cached and new keys; padded keys are masked."""
546
+ batch, length, _ = x.shape
547
+ queries, new_keys, new_values, gate, _ = attention._prepare_projected_qkv(
548
+ attention.q_proj(x), attention.k_proj(x), attention.v_proj(x), None, positions, None, None)
549
+ if keys is not None:
550
+ new_keys = mx.concatenate([keys, new_keys], axis=2)
551
+ new_values = mx.concatenate([values, new_values], axis=2)
552
+ total = new_keys.shape[2]
553
+ # The score matrix is queries x keys per head. Long inputs are attended in slices of query rows so its
554
+ # size stays bounded (a slice's output depends only on its own rows); unsliced, a 40k-token input needs
555
+ # tens of GB per layer.
556
+ rows = max(1, ATTENTION_ELEMENTS // (batch * attention.num_attention_heads * total))
557
+ outputs = []
558
+ for start in range(0, length, rows):
559
+ stop = min(length, start + rows)
560
+ mask = None
561
+ if length > 1:
562
+ key_index = mx.arange(total)[None, :]
563
+ row_index = mx.arange(offset + start, offset + stop)[:, None]
564
+ mask = (key_index <= row_index)[None, None]
565
+ if valid is not None: # a padded query still sees itself, so no row is fully masked
566
+ mask = mask & (valid[:, None, None, :] | (key_index == row_index)[None, None])
567
+ elif valid is not None:
568
+ mask = valid[:, None, None, :]
569
+ outputs.append(mx.fast.scaled_dot_product_attention(
570
+ queries[:, :, start:stop], new_keys, new_values, scale=attention.scale, mask=mask))
571
+ if rows < length:
572
+ mx.eval(outputs[-1])
573
+ self._check_memory()
574
+ output = outputs[0] if len(outputs) == 1 else mx.concatenate(outputs, axis=2)
575
+ output = output.transpose(0, 2, 1, 3).reshape(batch, length, -1)
576
+ return attention.o_proj(output * mx.sigmoid(gate)), new_keys, new_values
577
+
578
+ def _forward(self, h: mx.array, positions: mx.array, lengths: np.ndarray | None, cache: Cache | None,
579
+ keep: bool = True) -> tuple[mx.array, Cache | None]:
580
+ """Run the layers over new tokens, optionally continuing from a cache.
581
+
582
+ `lengths` gives each row's number of real tokens when the batch is right-padded (None: no padding).
583
+ Returns the hidden states before the final norm and, with `keep`, the cache after each row's last real
584
+ token (padded positions stay in the attention cache, marked invalid).
585
+ """
586
+ layers = self.lm.model.layers
587
+ cache = cache or Cache.empty(len(layers))
588
+ batch, length, _ = h.shape
589
+ valid = row_lengths = None
590
+ if lengths is not None and (lengths < length).any():
591
+ row_lengths = mx.array(lengths.astype(np.int32))
592
+ valid = mx.arange(length)[None, :] < row_lengths[:, None]
593
+ all_valid = None
594
+ if cache.valid is not None or valid is not None:
595
+ before = cache.valid if cache.valid is not None else mx.ones((batch, cache.length), dtype=mx.bool_)
596
+ new = valid if valid is not None else mx.ones((batch, length), dtype=mx.bool_)
597
+ all_valid = mx.concatenate([before, new], axis=1)
598
+ rotary = self._rotary(positions)
599
+ updated = Cache.empty(len(layers)) if keep else None
600
+ stepwise = batch * length > 4096 # keep the lazy graph small on long inputs
601
+ for index, layer in enumerate(layers):
602
+ x = layer.input_layernorm(h)
603
+ if layer.is_linear:
604
+ r, memory, window = self._linear(layer.linear_attn, x, valid, cache.window[index], cache.memory[index],
605
+ row_lengths)
606
+ if keep:
607
+ updated.memory[index], updated.window[index] = memory, window
608
+ else:
609
+ r, keys, values = self._attention(layer.self_attn, x, rotary, cache.keys[index], cache.values[index],
610
+ all_valid, cache.length)
611
+ if keep:
612
+ updated.keys[index], updated.values[index] = keys, values
613
+ h = h + r
614
+ h = h + layer.mlp(layer.post_attention_layernorm(h))
615
+ if stepwise:
616
+ mx.eval(h, *(updated.arrays() if keep else []))
617
+ self._check_memory()
618
+ if keep:
619
+ updated.valid, updated.length = all_valid, cache.length + length
620
+ return h, updated
621
+
622
+ def _run(self, h: mx.array, positions: mx.array, lengths: np.ndarray | None, cache: Cache | None,
623
+ keep: bool = True) -> tuple[mx.array, Cache | None]:
624
+ """`_forward` over a whole input. Long inputs go through the layers in segments, each continuing from
625
+ the cache of the previous one, so working memory depends on the segment size rather than the input
626
+ length (attention is causal and the linear layers are recurrent, so the result is the same). With
627
+ `keep`, the returned cache has `position` set to each row's next rotary position."""
628
+ batch, length, _ = h.shape
629
+ segment = max(256, SEGMENT_TOKENS // batch)
630
+ if length <= segment:
631
+ out, cache = self._forward(h, positions, lengths, cache, keep)
632
+ else:
633
+ outputs = []
634
+ for start in range(0, length, segment):
635
+ stop = min(length, start + segment)
636
+ inside = None if lengths is None else np.clip(lengths - start, 0, stop - start)
637
+ part, cache = self._forward(h[:, start:stop], positions[:, :, start:stop], inside, cache)
638
+ mx.eval(part, *cache.arrays())
639
+ self._check_memory()
640
+ outputs.append(part)
641
+ out = mx.concatenate(outputs, axis=1)
642
+ cache = cache if keep else None
643
+ if keep:
644
+ last = mx.array((lengths if lengths is not None else np.full(batch, length)).astype(np.int32)) - 1
645
+ index = mx.broadcast_to(last[None, :, None], (positions.shape[0], batch, 1))
646
+ cache.position = mx.take_along_axis(positions, index, axis=2)[:, :, 0].max(axis=0) + 1
647
+ return out, cache
648
+
649
+ def _hidden(self, sequences: list[list[int]], media: list[Any]) -> mx.array:
650
+ """Final-norm hidden states of an unpadded single sequence."""
651
+ rows = self._rows(sequences, media)
652
+ h, positions = self._embed(rows)
653
+ h, _ = self._run(h, positions, None, None, keep=False)
654
+ return self.lm.model.norm(h)
655
+
656
+ # ---- typed readout (upstream `read_record`)
657
+ def _read_record(self, states: mx.array, item: Any) -> dict[str, np.ndarray]:
658
+ start, length, kinds, queries, items, slot_fields, slots = cm.parse_prediction_layout(
659
+ cm.prediction_layout(item), len(item.input_ids), with_slots=True)
660
+ views = cm.prediction_views(kinds, queries, items, None)
661
+ hidden = states.astype(mx.float32)
662
+ stop = start + length
663
+ memory = self.head._memory(hidden, stop)
664
+ output = self.head.forward(hidden, start, stop, views, memory)
665
+ mx.eval(output)
666
+ values: dict[str, np.ndarray] = {name: np.array(value) for name, value in output.items()}
667
+ if slots:
668
+ width = max(map(len, slots))
669
+ positions = np.array([row + [row[-1]] * (width - len(row)) for row in slots], dtype=np.int64)
670
+ field_queries = np.asarray(views["query_positions"])[slot_fields]
671
+ slot_kinds = np.array([cm.ROUTE_KINDS.index("tags" if kinds[row] == "text_list" else kinds[row])
672
+ for row in slot_fields], dtype=np.int64)
673
+ lengths = np.array([len(row) for row in slots], dtype=np.int64)
674
+ slot_states = self.head.answer_slot_states(hidden, field_queries, slot_kinds, positions, lengths, stop, memory)
675
+ slot_states = slot_states.reshape(-1, slot_states.shape[-1]).astype(states.dtype)
676
+ ids, logprobs = [], []
677
+ for first in range(0, slot_states.shape[0], 256):
678
+ logits = self.lm.lm_head(slot_states[first: first + 256]).astype(mx.float32)
679
+ best = mx.argmax(logits, axis=-1)
680
+ ids.append(best)
681
+ logprobs.append(mx.take_along_axis(logits, best[:, None], axis=-1)[:, 0] - mx.logsumexp(logits, axis=-1))
682
+ mx.eval(ids[-1], logprobs[-1])
683
+ values["slot_ids"] = np.array(mx.concatenate(ids)).reshape(positions.shape)
684
+ values["slot_log_probs"] = np.array(mx.concatenate(logprobs)).reshape(positions.shape)
685
+ return values
686
+
687
+ def _read_typed(self, item: Any, media: Any, _cancelled: threading.Event | None = None) -> dict[str, dict[str, Any]]:
688
+ if _cancelled is not None and _cancelled.is_set():
689
+ raise RuntimeError("Inference cancelled")
690
+ states = self._hidden([list(item.input_ids)], [media])[0]
691
+ mx.eval(states)
692
+ if _cancelled is not None and _cancelled.is_set():
693
+ raise RuntimeError("Inference cancelled")
694
+ values = self._read_record(states, item)
695
+ compact = cm.compact_output(values)
696
+ if self.capture is not None:
697
+ self.capture("hidden", np.array(states.astype(mx.float32)))
698
+ self.capture("compact", np.asarray(compact, dtype=np.float32))
699
+ if "slot_ids" in values:
700
+ self.capture("slots", values["slot_ids"])
701
+ if media:
702
+ self.capture("pixels", np.asarray(media[0]["pixel_values"]).astype(np.float16))
703
+ self.capture("grid", np.asarray(media[0]["image_grid_thw"]))
704
+ values = cm.expand_output(compact, item, bins=self.head.bins, estimate_lexical=True, span_trim=True,
705
+ number_groups=True, number_pointer=True)
706
+ return cm.decode_record(values, item, self.tokenizer)
707
+
708
+ async def read_typed(self, item: Any, media: Any = None) -> dict[str, dict[str, Any]]:
709
+ return await self._submit(lambda cancelled: self._read_typed(item, media, _cancelled=cancelled))
710
+
711
+ # ---- constrained generation
712
+ def _grammar(self, parameters: dict[str, Any]) -> Any:
713
+ if "json_schema" in parameters:
714
+ value = parameters["json_schema"]
715
+ return self.compiler.compile_json_schema(json.loads(value) if isinstance(value, str) else value,
716
+ any_whitespace=True)
717
+ if "regex" in parameters:
718
+ return self.compiler.compile_regex(parameters["regex"])
719
+ if "ebnf" in parameters:
720
+ return self.compiler.compile_grammar(parameters["ebnf"])
721
+ raise ValueError("Extraction continuations require a JSON schema, regex, or grammar")
722
+
723
+ def _logits(self, h: mx.array) -> np.ndarray:
724
+ """Vocabulary logits (fp32) from hidden states [B, 1, width] before the final norm."""
725
+ return np.array(self.lm.lm_head(self.lm.model.norm(h))[:, 0].astype(mx.float32))
726
+
727
+ @staticmethod
728
+ def _media_key(payload: Any) -> tuple | None:
729
+ return tuple(mapping.get("clair_pixels_key") or id(mapping["pixel_values"]) for mapping in payload) if payload else None
730
+
731
+ def _image_prefix(self, sequences: list[list[int]], media: list[Any]) -> tuple[Cache | None, int]:
732
+ """The state after the images shared by every prompt of a batch, computed once per request.
733
+
734
+ Image prompts start with the same image tokens and differ only afterwards. The shared part, up to the
735
+ last `<|vision_end|>` common to all rows, is run once and each row continues from its cache; attention
736
+ is causal and the linear layers are recurrent, so this equals running every full prompt.
737
+ """
738
+ if not self.prefix_cache or not media[0] or any(self._media_key(m) != self._media_key(media[0]) for m in media):
739
+ return None, 0
740
+ common = sequences[0][: _common_prefix(sequences)]
741
+ if self.vision_end not in common:
742
+ return None, 0
743
+ cut = len(common) - common[::-1].index(self.vision_end)
744
+ if any(self.image_token in sequence[cut:] for sequence in sequences):
745
+ return None, 0
746
+ key = (self._media_key(media[0]), hashlib.sha1(np.asarray(common[:cut], dtype=np.int32).tobytes()).hexdigest())
747
+ if key not in self._prefixes:
748
+ rows = self._rows([common[:cut]], [media[0]])
749
+ h, positions = self._embed(rows)
750
+ _, cache = self._run(h, positions, None, None)
751
+ mx.eval(cache.position, *cache.arrays())
752
+ self._prefixes[key] = cache
753
+ return self._prefixes[key], cut
754
+
755
+ def _prefill(self, sequences: list[list[int]], media: list[Any]) -> tuple[mx.array, Cache]:
756
+ """Run the prompts of one batch. Returns each row's last hidden state [B, 1, width] and the cache."""
757
+ size = len(sequences)
758
+ prefix, cut = self._image_prefix(sequences, media)
759
+ if prefix is None:
760
+ rows = self._rows(sequences, media)
761
+ h, positions = self._embed(rows)
762
+ cache = None
763
+ else:
764
+ rows = self._rows([sequence[cut:] for sequence in sequences], [None] * size)
765
+ h = self.lm.model.embed_tokens(mx.array(rows.ids))
766
+ positions = prefix.position[0] + mx.arange(rows.ids.shape[1])
767
+ positions = mx.broadcast_to(positions[None, None, :], (3, size, rows.ids.shape[1]))
768
+
769
+ def spread(array: mx.array | None) -> mx.array | None:
770
+ return None if array is None else mx.broadcast_to(array, (size, *array.shape[1:]))
771
+
772
+ cache = Cache([spread(a) for a in prefix.keys], [spread(a) for a in prefix.values],
773
+ [spread(a) for a in prefix.memory], [spread(a) for a in prefix.window], None, prefix.length)
774
+ lengths = rows.lengths
775
+ h, cache = self._run(h, positions, lengths, cache)
776
+ last = mx.array((lengths - 1).astype(np.int32))
777
+ index = mx.broadcast_to(last[:, None, None], (size, 1, h.shape[-1]))
778
+ return mx.take_along_axis(h, index, axis=1), cache
779
+
780
+ def _decode(self, sequences: list[list[int]], media: list[Any], grammars: list[Any], maximum: int,
781
+ stop_ids: tuple[int, ...], score_ids: list[int], cancelled: threading.Event | None,
782
+ ) -> list[tuple[list[int], list[float], list[float]]]:
783
+ """Greedy decoding of one batch under per-row grammars. Returns (tokens, log-probabilities, first-step
784
+ log-probabilities of `score_ids`) per row; tokens end with the stop token when one was produced."""
785
+ size = len(sequences)
786
+ h, cache = self._prefill(sequences, media)
787
+ mx.eval(h, cache.position, *cache.arrays())
788
+ scores = self._logits(h)
789
+ matchers = [self._xgr.GrammarMatcher(grammar) for grammar in grammars]
790
+ bitmask = np.zeros(self._xgr.get_bitmask_shape(size, self.vocab), dtype=np.int32)
791
+ tokens: list[list[int]] = [[] for _ in range(size)]
792
+ logprobs: list[list[float]] = [[] for _ in range(size)]
793
+ first: list[list[float]] = [[] for _ in range(size)]
794
+ done = [False] * size
795
+ for step in range(maximum):
796
+ for row, matcher in enumerate(matchers):
797
+ if not matcher.is_terminated():
798
+ matcher.fill_next_token_bitmask(bitmask, row)
799
+ allowed = np.unpackbits(bitmask.view(np.uint8), axis=-1, bitorder="little")[:, : self.vocab].astype(bool)
800
+ masked = np.where(allowed, scores, -np.inf).astype(np.float32)
801
+ peak = masked.max(axis=-1, keepdims=True)
802
+ with np.errstate(divide="ignore"):
803
+ log_probabilities = masked - peak - np.log(np.exp(masked - peak).sum(axis=-1, keepdims=True, dtype=np.float32))
804
+ choices = masked.argmax(axis=-1)
805
+ for row in range(size):
806
+ if step == 0:
807
+ first[row] = [float(log_probabilities[row, token]) for token in score_ids]
808
+ if done[row]:
809
+ continue
810
+ token = int(choices[row])
811
+ tokens[row].append(token)
812
+ logprobs[row].append(float(log_probabilities[row, token]))
813
+ if token in stop_ids:
814
+ done[row] = True
815
+ if not matchers[row].is_terminated() and not matchers[row].accept_token(token):
816
+ raise RuntimeError("Generated token rejected by its grammar")
817
+ if all(done) or step + 1 == maximum:
818
+ break
819
+ if cancelled is not None and cancelled.is_set():
820
+ raise RuntimeError("Inference cancelled")
821
+ feed = mx.array([[self.pad if done[row] else tokens[row][-1]] for row in range(size)])
822
+ position = cache.position
823
+ h, cache = self._forward(self.lm.model.embed_tokens(feed), mx.broadcast_to(position[None, :, None], (3, size, 1)),
824
+ None, cache)
825
+ cache.position = position + 1
826
+ mx.eval(h, cache.position, *cache.arrays())
827
+ scores = self._logits(h)
828
+ return list(zip(tokens, logprobs, first, strict=True))
829
+
830
+ def _generate(self, *, input_ids: list[int] | list[list[int]], image_data: Any = None,
831
+ sampling_params: dict[str, Any] | list[dict[str, Any]], rid: Any = None,
832
+ token_ids_logprob: list[int] | None = None, _cancelled: threading.Event | None = None,
833
+ **kwargs: Any) -> Any:
834
+ if _cancelled is not None and _cancelled.is_set():
835
+ raise RuntimeError("Inference cancelled")
836
+ if not input_ids:
837
+ return []
838
+ single = isinstance(input_ids[0], int)
839
+ sequences = [input_ids] if single else input_ids
840
+ size = len(sequences)
841
+ parameters = [sampling_params] * size if isinstance(sampling_params, dict) else sampling_params
842
+ media = [image_data] if single else (image_data or [None] * size)
843
+ ids = [rid] if single else (rid or [None] * size)
844
+ if not (len(parameters) == len(media) == len(ids) == size):
845
+ raise ValueError("Extraction batch arguments have inconsistent lengths")
846
+ results: list[Any] = [None] * size
847
+ groups: dict[tuple[int, tuple[int, ...]], list[int]] = defaultdict(list)
848
+ for index, params in enumerate(parameters):
849
+ if params.get("temperature", 0) != 0:
850
+ raise ValueError("Clairic extraction uses deterministic decoding")
851
+ groups[(int(params.get("max_new_tokens", 256)), tuple(params.get("stop_token_ids", [self.eos])))].append(index)
852
+ for (maximum, stop_ids), indices in groups.items():
853
+ # Rows with the same images and similar length share a batch; a row's result does not depend on
854
+ # its batch. Rows that share images are charged for the image prefix once.
855
+ indices = sorted(indices, key=lambda index: (str(self._media_key(media[index])), len(sequences[index])))
856
+ chunks: list[list[int]] = []
857
+ pending: list[int] = []
858
+ for index in indices:
859
+ if pending and (len(pending) >= self.batch_size
860
+ or self._media_key(media[index]) != self._media_key(media[pending[0]])
861
+ or self._cost([sequences[i] for i in (*pending, index)], media[index]) > self.batch_token_budget):
862
+ chunks.append(pending)
863
+ pending = []
864
+ pending.append(index)
865
+ if pending:
866
+ chunks.append(pending)
867
+ for chunk in chunks:
868
+ if _cancelled is not None and _cancelled.is_set():
869
+ raise RuntimeError("Inference cancelled")
870
+ decoded = self._decode([sequences[i] for i in chunk], [media[i] for i in chunk],
871
+ [self._grammar(parameters[i]) for i in chunk], maximum, stop_ids,
872
+ list(token_ids_logprob or []), _cancelled)
873
+ for index, (output, logprobs, first) in zip(chunk, decoded, strict=True):
874
+ stopped = bool(output) and output[-1] in stop_ids
875
+ results[index] = {
876
+ "output_ids": output,
877
+ "text": self.tokenizer.decode(output[:-1] if stopped else output, skip_special_tokens=False,
878
+ clean_up_tokenization_spaces=False),
879
+ "meta_info": {
880
+ "id": ids[index],
881
+ "completion_tokens": len(output),
882
+ "finish_reason": {"type": "stop", "matched": output[-1]} if stopped else {"type": "length"},
883
+ "output_token_logprobs": [(value, token, None) for value, token in zip(logprobs, output, strict=True)],
884
+ "output_token_ids_logprobs": [[(value, token, None) for value, token in
885
+ zip(first, token_ids_logprob or [], strict=True)]],
886
+ },
887
+ }
888
+ return results[0] if single else results
889
+
890
+ def _cost(self, sequences: list[list[int]], payload: Any) -> int:
891
+ """Tokens a batch runs through the model: the padded width times its rows (shared image tokens once)."""
892
+ shared = 0
893
+ if payload and self.prefix_cache and len(sequences) > 1:
894
+ common = sequences[0][: _common_prefix(sequences)]
895
+ shared = len(common) - common[::-1].index(self.vision_end) if self.vision_end in common else 0
896
+ return (max(map(len, sequences)) - shared) * len(sequences)
897
+
898
+ async def async_generate(self, **kwargs: Any) -> Any:
899
+ return await self._submit(lambda cancelled: self._generate(_cancelled=cancelled, **kwargs))
900
+
901
+ async def _submit(self, operation: Callable[[threading.Event], Any]) -> Any:
902
+ cancelled = threading.Event()
903
+ future = asyncio.get_running_loop().run_in_executor(self._worker, lambda: operation(cancelled))
904
+ try:
905
+ return await asyncio.shield(future)
906
+ except asyncio.CancelledError:
907
+ cancelled.set()
908
+ # Admission stays occupied until the worker has actually stopped.
909
+ while not future.done():
910
+ try:
911
+ await asyncio.shield(future)
912
+ except asyncio.CancelledError:
913
+ continue
914
+ except Exception:
915
+ break
916
+ if not future.cancelled():
917
+ future.exception()
918
+ raise
clairic_runtime/model.py ADDED
@@ -0,0 +1,2424 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Modified from the Cloudflare Clairic release (Apache-2.0).
2
+ # Changes: the typed head (ClairicHead) was moved to a separate MLX module, and
3
+ # the tensor code in this file was ported from PyTorch to NumPy.
4
+ from __future__ import annotations
5
+ import calendar
6
+ import datetime
7
+ import functools
8
+ import math
9
+ import os
10
+ import re
11
+ from bisect import bisect_left, bisect_right
12
+ from dataclasses import dataclass, field
13
+ from decimal import ROUND_HALF_UP, Decimal
14
+ from typing import Any, cast
15
+ import numpy as np
16
+ from . import schema as zs
17
+
18
+ SYSTEM_PREFIX = "<|im_start|>system\n" + zs.SYSTEM_PREAMBLE + "\nFields:\n"
19
+ EVIDENCE_SYSTEM_PREFIX = (
20
+ "<|im_start|>system\n" + zs.EVIDENCE_SYSTEM_PREAMBLE + "\nFields:\n"
21
+ )
22
+ USER_PREFIX = "<|im_end|>\n<|im_start|>user\n"
23
+ ASSISTANT_SUFFIX = "<|im_end|>\n<|im_start|>assistant\n<think>\n\n</think>\n"
24
+ ANSWER_CUE = "\nAnswer:"
25
+
26
+
27
+ @dataclass(frozen=True)
28
+ class PromptLayout:
29
+ schema_header: str
30
+ query_header: str
31
+ answer_cue: str
32
+ slot_header: str
33
+
34
+
35
+ PROMPT_LAYOUTS = (
36
+ PromptLayout("", "", ANSWER_CUE, ""),
37
+ PromptLayout(
38
+ "Field definition:\n", "\nField query:", "\nValue:", "\nAnswer field:"
39
+ ),
40
+ PromptLayout(
41
+ "Requested field:\n", "\nRequested field:", "\nResult:", "\nResult for field:"
42
+ ),
43
+ )
44
+ PROMPT_VARIANTS = (0, 1, 2)
45
+
46
+
47
+ def prompt_layout(
48
+ template_variant: int = 0, complete_field: bool = True
49
+ ) -> PromptLayout:
50
+ if (
51
+ not isinstance(template_variant, int)
52
+ or isinstance(template_variant, bool)
53
+ or template_variant not in PROMPT_VARIANTS
54
+ ):
55
+ raise ValueError("template_variant must be 0, 1, or 2")
56
+ if template_variant and (not complete_field):
57
+ raise ValueError("alternative layouts require the evidence construction")
58
+ return PROMPT_LAYOUTS[template_variant]
59
+
60
+
61
+ QUERY_TOKENS = 256
62
+ MAX_SPAN = 64
63
+ TRIM_CLASSES = 8
64
+ TRIM_INIT = 2.0
65
+ MIN_INPUT_TOKENS = 16
66
+ BINS = 256
67
+ POINTER_WIDTH = 256
68
+ NUMBER_DIGITS = 12
69
+ (MIN_EXPONENT, MAX_EXPONENT) = (-12, 15)
70
+ EXPONENT_CLASSES = MAX_EXPONENT - MIN_EXPONENT + 2
71
+ YEAR_DIGITS = 4
72
+ (YEAR_LOW, YEAR_HIGH) = (1800, 2199)
73
+ YEAR_OUTSIDE = YEAR_HIGH - YEAR_LOW + 1
74
+ YEAR_CLASSES = YEAR_OUTSIDE + 1
75
+ LIST_SLOTS = zs.MAX_LIST_ITEMS
76
+ ITEM_CUES = tuple((f"\n{index}." for index in range(1, LIST_SLOTS + 1)))
77
+ (INSIDE, BELOW, ABOVE) = (0, 1, 2)
78
+ OVERFLOW_INIT = -5.0
79
+ QUERY_ORDER_RATE = 0.8
80
+ LOOP_RANK = 256
81
+ LEXICAL_DIGITS = 4
82
+ ESTIMATE_GATE_INIT = 0.0
83
+ ESTIMATE_SPREAD_LIMIT = 2.0
84
+ (EDGE_NEGATIVE, EDGE_ZERO, EDGE_POSITIVE) = (0, 1, 2)
85
+ (TAG_OUTSIDE, TAG_BEGIN, TAG_INSIDE) = (0, 1, 2)
86
+ NUMBER_WIDTH = 2 + EXPONENT_CLASSES + NUMBER_DIGITS * 10
87
+ GROUP_DIGITS = 3
88
+ GROUP_CLASSES = 10**GROUP_DIGITS
89
+ (GROUP_LOW, GROUP_HIGH) = (MIN_EXPONENT // GROUP_DIGITS, MAX_EXPONENT // GROUP_DIGITS)
90
+ NUMBER_GROUPS = GROUP_HIGH - GROUP_LOW + 1
91
+ GROUP_RANK = 256
92
+ COPY_CATEGORIES: tuple[str | None, ...] | None = ("extraction", None)
93
+ COPY_GATE_INIT = -3.0
94
+ NUMERAL_RUN = re.compile(
95
+ "(?:(?<![\\d.])\\.(?=\\d))?\\d+(?:[,.'\\u00a0\\u202f\\u2009\\u2007 \\u066b\\u066c]\\d+)*"
96
+ )
97
+ NUMERAL_SEPARATORS = ",.'\xa0\u202f\u2009\u2007 ٫٬"
98
+ NUMERAL_READINGS = (
99
+ (re.compile("\\d{1,3}(?:,\\d{3})+(?:\\.\\d+)?|\\d+(?:\\.\\d+)?|\\.\\d+"), ",", "."),
100
+ (
101
+ re.compile(
102
+ "\\d{1,3}(?:[.\\u00a0\\u202f\\u2009\\u2007' ]\\d{3})+(?:,\\d+)?|\\d+(?:,\\d+)?"
103
+ ),
104
+ ".\xa0\u202f\u2009\u2007' ",
105
+ ",",
106
+ ),
107
+ (
108
+ re.compile("\\d{1,3}(?:[\\u00a0\\u202f\\u2009\\u2007' ]\\d{3})+(?:\\.\\d+)?"),
109
+ "\xa0\u202f\u2009\u2007' ",
110
+ ".",
111
+ ),
112
+ (re.compile("\\d{1,2}(?:,\\d{2})+,\\d{3}(?:\\.\\d+)?"), ",", "."),
113
+ (
114
+ re.compile("\\d{1,3}(?:\\u066c\\d{3})+(?:\\u066b\\d+)?|\\d+\\u066b\\d+"),
115
+ "٬",
116
+ "٫",
117
+ ),
118
+ (re.compile("\\d{1,2}(?:\\u066c\\d{2})+\\u066c\\d{3}(?:\\u066b\\d+)?"), "٬", "٫"),
119
+ )
120
+ NUMERAL_SCALES = {
121
+ "thousand": 3,
122
+ "thousands": 3,
123
+ "k": 3,
124
+ "K": 3,
125
+ "million": 6,
126
+ "millions": 6,
127
+ "mn": 6,
128
+ "mln": 6,
129
+ "M": 6,
130
+ "MM": 6,
131
+ "billion": 9,
132
+ "billions": 9,
133
+ "bn": 9,
134
+ "B": 9,
135
+ "trillion": 12,
136
+ "tn": 12,
137
+ "lakh": 5,
138
+ "lakhs": 5,
139
+ "lac": 5,
140
+ "lacs": 5,
141
+ "crore": 7,
142
+ "crores": 7,
143
+ "cr": 7,
144
+ "Cr": 7,
145
+ "Mn": 6,
146
+ "Bn": 9,
147
+ "Lakh": 5,
148
+ "Lakhs": 5,
149
+ "Crore": 7,
150
+ "Crores": 7,
151
+ "Million": 6,
152
+ "Billion": 9,
153
+ "Thousand": 3,
154
+ "Trillion": 12,
155
+ "MILLION": 6,
156
+ "BILLION": 9,
157
+ "ألف": 3,
158
+ "مليون": 6,
159
+ "مليار": 9,
160
+ "हज़ार": 3,
161
+ "लाख": 5,
162
+ "करोड़": 7,
163
+ }
164
+ NUMERAL_SCALE = re.compile(
165
+ "(?:[ \\u00a0\\u202f\\u2009]?("
166
+ + "|".join(
167
+ sorted(
168
+ (
169
+ word
170
+ for word in NUMERAL_SCALES
171
+ if len(word) > 2
172
+ or word in ("mn", "bn", "tn", "cr", "Cr", "Mn", "Bn", "MM")
173
+ ),
174
+ key=len,
175
+ reverse=True,
176
+ )
177
+ )
178
+ + ")|(k|K|M|B))(?![^\\W\\d_])"
179
+ )
180
+ NUMERAL_SPAN = 48
181
+ CONVENTION_LANGUAGE = re.compile(
182
+ "\\b(?:Rechnung|Gesamtbetrag|Betrag|Lieferschein|Factuur|Bedrag|Totaal|Pakbon|Fattura|Importo|Totale|Fatura|Nota fiscal|Factura|Importe|Albar\\u00e1n|Facture|Montant)\\b"
183
+ )
184
+ CONVENTION_LANGUAGE_US = re.compile("\\b(?:M\\u00e9xico|Mexico|MXN|CFDI|RFC)\\b")
185
+ CONVENTION_STATED = {
186
+ "eu": re.compile(
187
+ "european (?:number )?(?:notation|format)|(?:dot|period|point)s? (?:separates?|for|marks?) (?:the )?thousands|comma (?:separates?|for|marks?|as) (?:the )?decimal|comma decimals?|decimal comma|dot thousands|1\\.234,56|1 234,56",
188
+ re.IGNORECASE,
189
+ ),
190
+ "us": re.compile(
191
+ "comma (?:separates?|for|marks?) (?:the )?thousands|(?:dot|period|point) (?:separates?|for|marks?|as) (?:the )?decimal|comma thousands|dot decimals?|1,234\\.56",
192
+ re.IGNORECASE,
193
+ ),
194
+ }
195
+ COPY_CONFIDENT = 0.9
196
+ COPY_MIN_CONFIDENCE = 0.5
197
+ SLOT_TEXT = "_"
198
+ SLOT_COUNTS = {"text": 80, "text_list": 64, "number": 32}
199
+ SLOT_CUE_TOKENS = 32
200
+ DATE_WIDTH = YEAR_DIGITS * 10 + YEAR_CLASSES + 12 + 31
201
+ TIME_WIDTH = 24 + 60 + 60
202
+ MASKED = -1000000000.0
203
+ SCALAR_KINDS = ("text", "number", "date", "time", "datetime")
204
+ IMAGE_PLACEHOLDER = "<|vision_start|><|image_pad|><|vision_end|>"
205
+ MEDIA_BATCH_KEYS = ("pixel_values", "image_grid_thw")
206
+ MEDIA_TOKEN_KEYS = ("mm_token_type_ids",)
207
+ LIST_KINDS = ("number_list", "date_list")
208
+
209
+
210
+ def head_kind(spec: dict[str, Any]) -> str:
211
+ kind = spec["type"]
212
+ if kind == "duration":
213
+ return "number"
214
+ if kind == "list":
215
+ return f"{spec['items']}_list"
216
+ return kind
217
+
218
+
219
+ def number_components(value: float) -> tuple[int, int, list[int]] | None:
220
+ value = float(value)
221
+ if not math.isfinite(value):
222
+ return None
223
+ if value == 0:
224
+ return (0, 0, [0] * NUMBER_DIGITS)
225
+ (mantissa, exponent) = f"{abs(value):.{NUMBER_DIGITS - 1}e}".split("e")
226
+ power = int(exponent)
227
+ if not MIN_EXPONENT <= power <= MAX_EXPONENT:
228
+ return None
229
+ return (
230
+ int(value < 0),
231
+ power - MIN_EXPONENT + 1,
232
+ [int(digit) for digit in mantissa.replace(".", "")],
233
+ )
234
+
235
+
236
+ def edge_number(value: float) -> tuple[int, int, list[int], float]:
237
+ if value == 0 or not math.isfinite(value):
238
+ return (EDGE_ZERO, 1, [0] * LEXICAL_DIGITS, 0.0)
239
+ (mantissa, exponent) = f"{abs(value):.{LEXICAL_DIGITS + 8}e}".split("e")
240
+ (power, digits) = (int(exponent), mantissa.replace(".", ""))
241
+ sign = EDGE_NEGATIVE if value < 0 else EDGE_POSITIVE
242
+ if power < MIN_EXPONENT:
243
+ return (sign, 1, [0] * LEXICAL_DIGITS, 0.0)
244
+ if power > MAX_EXPONENT:
245
+ return (sign, EXPONENT_CLASSES - 1, [9] * LEXICAL_DIGITS, 1.0)
246
+ return (
247
+ sign,
248
+ power - MIN_EXPONENT + 1,
249
+ [int(digit) for digit in digits[:LEXICAL_DIGITS]],
250
+ float("0." + digits[LEXICAL_DIGITS:]),
251
+ )
252
+
253
+
254
+ @functools.lru_cache(maxsize=8192)
255
+ def _edge_parts(
256
+ low: float, high: float, scale: str, bins: int
257
+ ) -> tuple[tuple[int, ...], tuple[int, ...], tuple[int, ...], tuple[float, ...]]:
258
+ parts = [
259
+ edge_number(zs.from_unit(index / bins, low, high, scale))
260
+ for index in range(bins + 1)
261
+ ]
262
+ return (
263
+ tuple((part[0] for part in parts)),
264
+ tuple((part[1] for part in parts)),
265
+ tuple((digit for part in parts for digit in part[2])),
266
+ tuple((part[3] for part in parts)),
267
+ )
268
+
269
+
270
+ def lexical_estimate(spec: dict[str, Any]) -> bool:
271
+ return not zs.is_date_estimate(spec) or zs.date_granularity(spec) == "year"
272
+
273
+
274
+ def estimate_edge_parts(
275
+ spec: dict[str, Any], bins: int = BINS
276
+ ) -> tuple[tuple[int, ...], tuple[int, ...], tuple[int, ...], tuple[float, ...]] | None:
277
+ if not lexical_estimate(spec):
278
+ return None
279
+ (low, high, scale) = zs.estimate_range(spec)
280
+ return _edge_parts(float(low), float(high), scale, bins)
281
+
282
+
283
+ @dataclass
284
+ class EncodedField:
285
+ name: str
286
+ kind: str
287
+ query: int
288
+ items: list[int] = field(default_factory=list)
289
+ prefix: tuple[int, int, tuple[int, ...]] | None = None
290
+ window: tuple[int, int] | None = None
291
+ answer_slots: list[int] = field(default_factory=list)
292
+
293
+
294
+ @dataclass(frozen=True)
295
+ class Commit:
296
+ text: str
297
+ done: bool = False
298
+ prefix: tuple[int, int, tuple[int, ...]] | None = None
299
+ probability: float = 1.0
300
+
301
+
302
+ @dataclass
303
+ class EncodedRecord:
304
+ input_ids: list[int]
305
+ input_start: int
306
+ offsets: list[tuple[int, int]]
307
+ fields: list[EncodedField]
308
+ text: str
309
+ record: dict[str, Any]
310
+ media: dict[str, Any] | None = None
311
+ image_expansion: int = 0
312
+
313
+
314
+ @dataclass
315
+ class EncodedMedia:
316
+ ids: list[int]
317
+ media: dict[str, Any] | None = None
318
+ expansion: int = 0
319
+
320
+ @property
321
+ def length(self) -> int:
322
+ return len(self.ids) + self.expansion
323
+
324
+
325
+ def configure_image_processor(processor: Any, max_pixels: int) -> dict[str, Any]:
326
+ image_processor = getattr(processor, "image_processor", None)
327
+ if image_processor is None or max_pixels <= 0:
328
+ raise ValueError("an image processor and positive pixel budget are required")
329
+ legacy = hasattr(image_processor, "max_pixels")
330
+ size = getattr(image_processor, "size", {})
331
+ sized = "longest_edge" in size
332
+ if not legacy and (not sized):
333
+ raise ValueError(
334
+ f"unsupported image pixel configuration: {type(image_processor).__name__}"
335
+ )
336
+ if legacy:
337
+ image_processor.max_pixels = max_pixels
338
+ if sized:
339
+ size["longest_edge"] = max_pixels
340
+ actual = size["longest_edge"] if sized else image_processor.max_pixels
341
+ if actual != max_pixels or (legacy and image_processor.max_pixels != max_pixels):
342
+ raise ValueError(
343
+ "the image processor did not retain its requested pixel budget"
344
+ )
345
+ return {"class": type(image_processor).__name__, "max_pixels": actual}
346
+
347
+
348
+ def encode_media(
349
+ tokenizer: Any,
350
+ images: list[Any],
351
+ processor: Any = None,
352
+ image_token_counts: list[int] | None = None,
353
+ ) -> EncodedMedia:
354
+ if not images:
355
+ return EncodedMedia([])
356
+ text = IMAGE_PLACEHOLDER * len(images) + "\n"
357
+ if image_token_counts is not None:
358
+ if len(image_token_counts) != len(images) or any(
359
+ (count < 1 for count in image_token_counts)
360
+ ):
361
+ raise ValueError("every image needs a positive token count")
362
+ return EncodedMedia(
363
+ _tokens(tokenizer, text),
364
+ None,
365
+ sum((count - 1 for count in image_token_counts)),
366
+ )
367
+ if processor is None:
368
+ raise ValueError("records with images need the model processor")
369
+ encoded = processor(text=[text], images=list(images), return_tensors="pt")
370
+ media = {key: encoded[key] for key in MEDIA_BATCH_KEYS if key in encoded}
371
+ for key in MEDIA_TOKEN_KEYS:
372
+ if key in encoded:
373
+ media[key] = encoded[key][0].tolist()
374
+ return EncodedMedia(encoded["input_ids"][0].tolist(), media)
375
+
376
+
377
+ def _tokens(tokenizer: Any, text: str) -> list[int]:
378
+ return tokenizer(text, add_special_tokens=False).input_ids
379
+
380
+
381
+ def _input_tokens(tokenizer: Any, text: str) -> tuple[list[int], list[tuple[int, int]]]:
382
+ try:
383
+ encoding = tokenizer(
384
+ text,
385
+ add_special_tokens=False,
386
+ return_offsets_mapping=True,
387
+ split_special_tokens=True,
388
+ )
389
+ except TypeError:
390
+ encoding = tokenizer(
391
+ text, add_special_tokens=False, return_offsets_mapping=True
392
+ )
393
+ return (list(encoding.input_ids), [tuple(pair) for pair in encoding.offset_mapping])
394
+
395
+
396
+ def schema_line(name: str, spec: dict[str, Any], complete_field: bool = False) -> str:
397
+ return "- " + zs.field_line(name, spec, preserve_instructions=complete_field) + "\n"
398
+
399
+
400
+ def reference_line(record: dict[str, Any]) -> str:
401
+ reference = record.get("reference_date")
402
+ return f"Reference date: {reference}\n" if reference else ""
403
+
404
+
405
+ def query_block(
406
+ tokenizer: Any,
407
+ name: str,
408
+ spec: dict[str, Any],
409
+ commit: Commit | None = None,
410
+ complete_field: bool = False,
411
+ template_variant: int = 0,
412
+ ) -> tuple[list[int], int, list[int]]:
413
+ layout = prompt_layout(template_variant, complete_field)
414
+ line = _tokens(
415
+ tokenizer,
416
+ "\n" + zs.field_line(name, spec, preserve_instructions=complete_field),
417
+ )
418
+ ids = (
419
+ _tokens(tokenizer, layout.query_header)
420
+ + (line if complete_field else line[:QUERY_TOKENS])
421
+ + _tokens(tokenizer, layout.answer_cue)
422
+ )
423
+ if commit is not None:
424
+ ids.extend(_tokens(tokenizer, " " + commit.text))
425
+ query = len(ids) - 1
426
+ items: list[int] = []
427
+ if head_kind(spec) in LIST_KINDS and commit is None:
428
+ for cue in ITEM_CUES:
429
+ ids.extend(_tokens(tokenizer, cue))
430
+ items.append(len(ids) - 1)
431
+ return (ids, query, items)
432
+
433
+
434
+ def clean_cut(
435
+ text: str, offsets: list[tuple[int, int]], budget: int, lookback: int = 32
436
+ ) -> int:
437
+ lowest = max(0, budget - lookback)
438
+ for keep in range(budget, lowest, -1):
439
+ end = offsets[keep - 1][1]
440
+ if end >= len(text) or (
441
+ end > 0 and text[end].isspace() and (not text[end - 1].isspace())
442
+ ):
443
+ return keep
444
+ for keep in range(budget, lowest, -1):
445
+ end = offsets[keep - 1][1]
446
+ if end > 0 and (text[end].isspace() or text[end - 1].isspace()):
447
+ return keep
448
+ return budget
449
+
450
+
451
+ def char_span_to_tokens(
452
+ starts: list[int], ends: list[int], char_start: int, char_end: int
453
+ ) -> tuple[int, int] | None:
454
+ first = bisect_right(ends, char_start)
455
+ last = bisect_left(starts, char_end) - 1
456
+ if first >= len(starts) or last < first:
457
+ return None
458
+ return (first, last)
459
+
460
+
461
+ def numeral_values(printed: str, convention: str | None = None) -> list[Decimal]:
462
+ values: list[Decimal] = []
463
+ both = convention is not None and all(
464
+ (form.fullmatch(printed) for (form, _, _) in NUMERAL_READINGS[:2])
465
+ )
466
+ for index, (form, separators, mark) in enumerate(NUMERAL_READINGS):
467
+ if both and index == (1 if convention == "us" else 0):
468
+ continue
469
+ if form.fullmatch(printed):
470
+ plain = printed.translate(
471
+ {ord(character): None for character in separators}
472
+ ).replace(mark, ".")
473
+ try:
474
+ value = Decimal(plain)
475
+ except ArithmeticError:
476
+ continue
477
+ if value not in values:
478
+ values.append(value)
479
+ return values
480
+
481
+
482
+ @functools.lru_cache(maxsize=256)
483
+ def numeral_convention(text: str) -> str | None:
484
+ stated = {
485
+ name
486
+ for (name, pattern) in CONVENTION_STATED.items()
487
+ if pattern.search(text or "")
488
+ }
489
+ if len(stated) == 1:
490
+ return stated.pop()
491
+ shown: list[str] = []
492
+ for run in NUMERAL_RUN.finditer(text or ""):
493
+ printed = run.group()
494
+ if not any((mark in printed for mark in ",.")):
495
+ continue
496
+ (us, eu) = (
497
+ bool(form.fullmatch(printed)) for (form, _, _) in NUMERAL_READINGS[:2]
498
+ )
499
+ if us != eu:
500
+ shown.append("us" if us else "eu")
501
+ if len(shown) >= 2 and len(set(shown)) == 1:
502
+ return shown[0]
503
+ if (
504
+ not shown
505
+ and CONVENTION_LANGUAGE.search(text or "")
506
+ and (not CONVENTION_LANGUAGE_US.search(text or ""))
507
+ ):
508
+ return "eu"
509
+ return None
510
+
511
+
512
+ @functools.lru_cache(maxsize=256)
513
+ def _numeral_candidates(text: str) -> tuple[tuple[list[Decimal], int, int, bool], ...]:
514
+ found: list[tuple[list[Decimal], int, int, bool]] = []
515
+ for run in NUMERAL_RUN.finditer(text or ""):
516
+ (begin, finish) = (run.start(), run.end())
517
+ cuts = [
518
+ index
519
+ for index in range(begin, finish)
520
+ if text[index] in NUMERAL_SEPARATORS and index > begin
521
+ ]
522
+ starts = [begin] + [index + 1 for index in cuts]
523
+ ends = cuts + [finish]
524
+ convention = numeral_convention(text)
525
+ scale = NUMERAL_SCALE.match(text, finish)
526
+ exponent = (
527
+ None if scale is None else NUMERAL_SCALES[scale.group(1) or scale.group(2)]
528
+ )
529
+ run_found = []
530
+ for start in starts:
531
+ for end in ends[bisect_left(ends, start + 1) :]:
532
+ if end - start > NUMERAL_SPAN:
533
+ break
534
+ values = numeral_values(text[start:end], convention)
535
+ if not values:
536
+ continue
537
+ if end == finish and exponent is not None:
538
+ scaled = [value.scaleb(exponent) for value in values]
539
+ run_found.append(
540
+ (
541
+ scaled + [value for value in values if value not in scaled],
542
+ start,
543
+ cast(re.Match[str], scale).end(),
544
+ )
545
+ )
546
+ else:
547
+ run_found.append((values, start, end))
548
+ by_start: dict[int, tuple[list[Decimal], int, int]] = {}
549
+ for item in run_found:
550
+ if item[1] not in by_start or item[2] > by_start[item[1]][2]:
551
+ by_start[item[1]] = item
552
+ (position, whole) = (begin, set())
553
+ while True:
554
+ longest = by_start.get(position)
555
+ following = bisect_left(
556
+ starts, position + 1 if longest is None else longest[2]
557
+ )
558
+ if longest is not None:
559
+ whole.add((longest[1], longest[2]))
560
+ if following >= len(starts):
561
+ break
562
+ position = starts[following]
563
+ found.extend(
564
+ (
565
+ (values, start, end, (start, end) in whole)
566
+ for (values, start, end) in run_found
567
+ )
568
+ )
569
+ return tuple(found)
570
+
571
+
572
+ def read_numerals(
573
+ text: str, every: bool = False
574
+ ) -> list[tuple[list[Decimal], int, int]]:
575
+ found = [
576
+ (values, start, end)
577
+ for (values, start, end, whole) in _numeral_candidates(text)
578
+ if every or whole
579
+ ]
580
+ return sorted(found, key=lambda item: (item[1], -item[2]))
581
+
582
+
583
+ def numeral_spans(text: str, value: Any, every: bool = True) -> list[tuple[int, int]]:
584
+ try:
585
+ target = abs(Decimal(str(value)))
586
+ except ArithmeticError:
587
+ return []
588
+ candidates = _numeral_candidates(text)
589
+ whole = [
590
+ (start, end)
591
+ for (values, start, end, longest) in candidates
592
+ if longest and target in values
593
+ ]
594
+ if whole or not every:
595
+ return sorted(whole)
596
+ return sorted(
597
+ {(start, end) for (values, start, end, _) in candidates if target in values},
598
+ key=lambda item: (item[0], -item[1]),
599
+ )
600
+
601
+
602
+ def slot_token_id(tokenizer: Any) -> int:
603
+ ids = _tokens(tokenizer, SLOT_TEXT)
604
+ if len(ids) != 1:
605
+ raise ValueError(f"answer slots need {SLOT_TEXT!r} to be one token")
606
+ return ids[0]
607
+
608
+
609
+ def slot_block(
610
+ tokenizer: Any,
611
+ name: str,
612
+ spec: dict[str, Any],
613
+ complete_field: bool = False,
614
+ template_variant: int = 0,
615
+ ) -> list[int]:
616
+ count = SLOT_COUNTS.get(head_kind(spec))
617
+ layout = prompt_layout(template_variant, complete_field)
618
+ if count is None:
619
+ return []
620
+ cue = _tokens(tokenizer, "\n" + name + ":")
621
+ return (
622
+ _tokens(tokenizer, layout.slot_header)
623
+ + (cue if complete_field else cue[:SLOT_CUE_TOKENS])
624
+ + [slot_token_id(tokenizer)] * count
625
+ )
626
+
627
+
628
+ def system_prefix(record: dict[str, Any], text_answer_slots: bool = False) -> str:
629
+ return (
630
+ EVIDENCE_SYSTEM_PREFIX
631
+ if evidence_construction(record, text_answer_slots)
632
+ else SYSTEM_PREFIX
633
+ )
634
+
635
+
636
+ def evidence_construction(
637
+ record: dict[str, Any], text_answer_slots: bool = False
638
+ ) -> bool:
639
+ return (
640
+ text_answer_slots
641
+ or (record.get("_meta") or {}).get("construction") == zs.EVIDENCE_CONSTRUCTION
642
+ )
643
+
644
+
645
+ def encode_record(
646
+ tokenizer: Any,
647
+ record: dict[str, Any],
648
+ max_length: int = 8192,
649
+ media: EncodedMedia | None = None,
650
+ commits: dict[str, Commit] | None = None,
651
+ answer_slots: bool = False,
652
+ text_answer_slots: bool = False,
653
+ template_variant: int = 0,
654
+ ) -> EncodedRecord | None:
655
+ if text_answer_slots and (not answer_slots):
656
+ raise ValueError("text_answer_slots needs answer_slots")
657
+ commits = commits or {}
658
+ if record.get("images") and media is None:
659
+ raise ValueError("records with images need their encoded media")
660
+ media = media or EncodedMedia([])
661
+ items = list(record["fields"].items())
662
+ complete_field = evidence_construction(record, text_answer_slots)
663
+ layout = prompt_layout(template_variant, complete_field)
664
+ ids = _tokens(tokenizer, system_prefix(record, text_answer_slots))
665
+ for name, spec in items:
666
+ ids.extend(_tokens(tokenizer, layout.schema_header))
667
+ ids.extend(_tokens(tokenizer, schema_line(name, spec, complete_field)))
668
+ ids.extend(_tokens(tokenizer, reference_line(record)))
669
+ ids.extend(_tokens(tokenizer, USER_PREFIX))
670
+ media_start = len(ids)
671
+ ids.extend(media.ids)
672
+ input_start = len(ids)
673
+ suffix = _tokens(tokenizer, ASSISTANT_SUFFIX)
674
+ blocks = [
675
+ query_block(
676
+ tokenizer, name, spec, commits.get(name), complete_field, template_variant
677
+ )
678
+ for (name, spec) in items
679
+ ]
680
+ slot_blocks: dict[int, list[int]] = {}
681
+ if answer_slots and (media.ids or text_answer_slots):
682
+ for index, (name, spec) in enumerate(items):
683
+ if not (name in commits and commits[name].done):
684
+ block = slot_block(
685
+ tokenizer, name, spec, complete_field, template_variant
686
+ )
687
+ if block:
688
+ slot_blocks[index] = block
689
+ budget = (
690
+ max_length
691
+ - len(ids)
692
+ - media.expansion
693
+ - len(suffix)
694
+ - sum((len(block[0]) for block in blocks))
695
+ - sum((len(block) for block in slot_blocks.values()))
696
+ )
697
+ if budget < MIN_INPUT_TOKENS:
698
+ return None
699
+ text = record["input"]
700
+ if media.ids and (not text.strip()):
701
+ text = ""
702
+ (input_ids, offsets) = (_tokens(tokenizer, "\n"), [(0, 0)])
703
+ else:
704
+ (input_ids, offsets) = _input_tokens(tokenizer, text)
705
+ if len(input_ids) > budget:
706
+ keep = clean_cut(text, offsets, budget)
707
+ text = text[: offsets[keep - 1][1]]
708
+ (input_ids, offsets) = _input_tokens(tokenizer, text)
709
+ if len(input_ids) > budget:
710
+ (input_ids, offsets) = (input_ids[:budget], offsets[:budget])
711
+ text = text[: offsets[-1][1]]
712
+ if not input_ids:
713
+ return None
714
+ ids.extend(input_ids)
715
+ ids.extend(suffix)
716
+ order = list(range(len(items)))
717
+ done = {
718
+ index
719
+ for (index, (name, _)) in enumerate(items)
720
+ if name in commits and commits[name].done
721
+ }
722
+ if done:
723
+ order = [index for index in order if index in done] + [
724
+ index for index in order if index not in done
725
+ ]
726
+ queries: dict[int, int] = {}
727
+ slots: dict[int, list[int]] = {}
728
+ for index in order:
729
+ (block, query, item_offsets) = blocks[index]
730
+ start = len(ids)
731
+ ids.extend(block)
732
+ queries[index] = start + query
733
+ slots[index] = [start + offset for offset in item_offsets]
734
+ answer_positions: dict[int, list[int]] = {}
735
+ for index in order:
736
+ if index in slot_blocks:
737
+ ids.extend(slot_blocks[index])
738
+ count = SLOT_COUNTS[head_kind(items[index][1])]
739
+ answer_positions[index] = list(range(len(ids) - count, len(ids)))
740
+ fields: list[EncodedField] = []
741
+ for index, (name, spec) in enumerate(items):
742
+ if index in done:
743
+ continue
744
+ encoded = EncodedField(name, head_kind(spec), queries[index], slots[index])
745
+ if index in answer_positions:
746
+ encoded.answer_slots = answer_positions[index]
747
+ commit = commits.get(name)
748
+ if (
749
+ commit is not None
750
+ and commit.prefix is not None
751
+ and (encoded.kind in ("number", "estimate"))
752
+ ):
753
+ encoded.prefix = commit.prefix
754
+ if encoded.kind == "estimate":
755
+ encoded.window = prefix_window(spec, commit.prefix)
756
+ fields.append(encoded)
757
+ if not fields:
758
+ return None
759
+ record_media = None
760
+ if media.media is not None:
761
+ record_media = {**media.media, "token_offset": media_start}
762
+ return EncodedRecord(
763
+ ids, input_start, offsets, fields, text, record, record_media, media.expansion
764
+ )
765
+
766
+
767
+ def span_base(text: str, starts: list[int], ends: list[int], first: int) -> int:
768
+ base = starts[first]
769
+ while base < ends[first] - 1 and text[base].isspace():
770
+ base += 1
771
+ return base
772
+
773
+
774
+ def trimmed_span(
775
+ text: str,
776
+ offsets: list[tuple[int, int]],
777
+ first: int,
778
+ last: int,
779
+ trims: list[list[int]] | None,
780
+ ) -> tuple[int, int]:
781
+ (char_start, char_end) = (offsets[first][0], offsets[last][1])
782
+ while char_start < offsets[first][1] - 1 and text[char_start].isspace():
783
+ char_start += 1
784
+ if trims is not None:
785
+ start = max(
786
+ char_start, min(char_start + int(trims[first][0]), offsets[first][1] - 1)
787
+ )
788
+ end = min(char_end, max(char_end - int(trims[last][1]), offsets[last][0] + 1))
789
+ if start < end:
790
+ (char_start, char_end) = (start, end)
791
+ while char_start < char_end - 1 and text[char_start].isspace():
792
+ char_start += 1
793
+ return (char_start, char_end)
794
+
795
+
796
+ def plain_number(value: Any) -> str:
797
+ number = Decimal(str(value))
798
+ if not number.is_finite():
799
+ raise ValueError("A plain number must be finite.")
800
+ text = format(number, "f")
801
+ return text.rstrip("0").rstrip(".") if "." in text else text
802
+
803
+
804
+ def prefix_window(
805
+ spec: dict[str, Any], prefix: tuple[int, int, tuple[int, ...]], bins: int = BINS
806
+ ) -> tuple[int, int] | None:
807
+ (sign, exponent_class, digits) = prefix
808
+ power = exponent_class - 1 + MIN_EXPONENT
809
+ unit = Decimal(1).scaleb(power - len(digits) + 1)
810
+ start = Decimal(int("".join((str(digit) for digit in digits)))) * unit
811
+ (first, last) = (float(start), float(start + unit))
812
+ if sign:
813
+ (first, last) = (-last, -first)
814
+ (low, high, scale) = zs.estimate_range(spec)
815
+ (lower, upper) = sorted(
816
+ (zs.raw_unit(first, low, high, scale), zs.raw_unit(last, low, high, scale))
817
+ )
818
+ if upper <= 0.0 or lower >= 1.0:
819
+ return None
820
+ first_bin = max(0, min(bins - 1, math.floor(lower * bins)))
821
+ last_bin = max(first_bin, min(bins - 1, math.ceil(upper * bins) - 1))
822
+ return (first_bin, last_bin)
823
+
824
+
825
+ def _masked_fill(values: np.ndarray, mask: Any, fill: float) -> np.ndarray:
826
+ filled = np.array(values, copy=True)
827
+ filled[np.broadcast_to(np.asarray(mask, dtype=bool), filled.shape)] = fill
828
+ return filled
829
+
830
+
831
+ def _log_softmax(values: Any, axis: int = -1) -> np.ndarray:
832
+ values = np.asarray(values)
833
+ shifted = values - values.max(axis=axis, keepdims=True)
834
+ return shifted - np.log(np.exp(shifted).sum(axis=axis, keepdims=True))
835
+
836
+
837
+ def _softmax(values: Any, axis: int = -1) -> np.ndarray:
838
+ values = np.asarray(values)
839
+ exps = np.exp(values - values.max(axis=axis, keepdims=True))
840
+ return exps * (1 / exps.sum(axis=axis, keepdims=True))
841
+
842
+
843
+ def _logsumexp(values: Any, axis: int = -1) -> np.ndarray:
844
+ values = np.asarray(values)
845
+ maxes = values.max(axis=axis, keepdims=True)
846
+ maxes = np.where(np.abs(maxes) == np.inf, np.zeros_like(maxes), maxes)
847
+ summed = np.exp(values - maxes).sum(axis=axis)
848
+ return np.log(summed) + np.squeeze(maxes, axis=axis)
849
+
850
+
851
+ def _sigmoid(values: Any) -> np.ndarray:
852
+ values = np.asarray(values)
853
+ with np.errstate(over="ignore"):
854
+ return 1 / (1 + np.exp(-values))
855
+
856
+
857
+ def _log_sigmoid(values: Any) -> np.ndarray:
858
+ values = np.asarray(values)
859
+ return np.minimum(values, 0) - np.log1p(np.exp(-np.abs(values)))
860
+
861
+
862
+ def _cumsum(values: Any, axis: int = -1) -> np.ndarray:
863
+ # torch's CPU cumsum accumulates float32 in double precision.
864
+ values = np.asarray(values)
865
+ if values.dtype == np.float32:
866
+ return np.cumsum(values.astype(np.float64), axis=axis).astype(np.float32)
867
+ return np.cumsum(values, axis=axis)
868
+
869
+
870
+ def _f32(values: Any) -> np.ndarray:
871
+ return np.asarray(values, dtype=np.float32)
872
+
873
+
874
+ def _flatten1(values: np.ndarray) -> np.ndarray:
875
+ return values.reshape(values.shape[0], math.prod(values.shape[1:]))
876
+
877
+
878
+ def span_scores(
879
+ start: np.ndarray, end: np.ndarray, length_bias: np.ndarray
880
+ ) -> np.ndarray:
881
+ (start, end, length_bias) = (
882
+ np.asarray(start),
883
+ np.asarray(end),
884
+ np.asarray(length_bias),
885
+ )
886
+ width = length_bias.shape[0]
887
+ pad = [(0, 0)] * (end.ndim - 1) + [(0, width - 1)]
888
+ padded = np.pad(end, pad, constant_values=float("-inf"))
889
+ windows = np.lib.stride_tricks.sliding_window_view(padded, width, axis=-1)
890
+ return start[..., None] + windows + length_bias
891
+
892
+
893
+ DIGIT_SLOTS = NUMBER_DIGITS + YEAR_DIGITS + 2 + 2 + 2 + 2
894
+ (YEAR_SLOT, DAY_SLOT, HOUR_SLOT, MINUTE_SLOT, SECOND_SLOT) = (
895
+ NUMBER_DIGITS,
896
+ NUMBER_DIGITS + YEAR_DIGITS,
897
+ NUMBER_DIGITS + YEAR_DIGITS + 2,
898
+ NUMBER_DIGITS + YEAR_DIGITS + 4,
899
+ NUMBER_DIGITS + YEAR_DIGITS + 6,
900
+ )
901
+ MONTH_WORDS = tuple((" " + name for name in calendar.month_name[1:]))
902
+ SIGN_WORDS = (" ", " -")
903
+ ROUTE_KINDS = (
904
+ "text",
905
+ "tags",
906
+ "number",
907
+ "date",
908
+ "time",
909
+ "estimate",
910
+ "number_list",
911
+ "date_list",
912
+ )
913
+
914
+
915
+ def two_digit_index(values: range) -> np.ndarray:
916
+ return np.array(
917
+ [[value // 10 for value in values], [value % 10 for value in values]],
918
+ dtype=np.int64,
919
+ )
920
+
921
+
922
+ def compose_two_digits(slots: np.ndarray, index: np.ndarray) -> np.ndarray:
923
+ slots = np.asarray(slots)
924
+ return np.take(slots[..., 0, :], index[0], axis=-1) + np.take(
925
+ slots[..., 1, :], index[1], axis=-1
926
+ )
927
+
928
+
929
+ def compose_years(slots: np.ndarray, index: np.ndarray) -> np.ndarray:
930
+ slots = np.asarray(slots)
931
+ inside = cast(
932
+ np.ndarray,
933
+ sum(
934
+ (
935
+ np.take(slots[..., position, :], index[position], axis=-1)
936
+ for position in range(YEAR_DIGITS)
937
+ )
938
+ ),
939
+ )
940
+ total = _logsumexp(slots, axis=-1).sum(axis=-1)
941
+ gap = np.minimum(_logsumexp(inside, axis=-1) - total, -1e-06)
942
+ outside = total + np.log(-np.expm1(gap))
943
+ return np.concatenate([inside, outside[..., None]], axis=-1)
944
+
945
+
946
+ SPELL_END = "\n"
947
+ SPELL_SEPARATOR = " | "
948
+ SPELL_MIN_CONFIDENCE = 0.3
949
+
950
+
951
+ def spelled_answer(
952
+ ids: list[int], log_probs: list[float], tokenizer: Any, end_id: int
953
+ ) -> tuple[str, float, list[tuple[str, float]]]:
954
+ stop = ids.index(end_id) if end_id in ids else len(ids)
955
+ pieces = [tokenizer.decode([token]) for token in ids[:stop]]
956
+ items: list[tuple[list[int], list[float]]] = []
957
+ current: list[int] = []
958
+ scores: list[float] = []
959
+ for token, piece, score in zip(ids[:stop], pieces, log_probs[:stop]):
960
+ if piece.strip() == SPELL_SEPARATOR.strip():
961
+ items.append((current, scores))
962
+ (current, scores) = ([], [])
963
+ else:
964
+ current.append(token)
965
+ scores.append(score)
966
+ items.append((current, scores))
967
+ parts = []
968
+ for item_ids, item_scores in items:
969
+ words = tokenizer.decode(item_ids).split()
970
+ if words:
971
+ parts.append(
972
+ (" ".join(words), math.exp(sum(item_scores) / len(item_scores)))
973
+ )
974
+ text = SPELL_SEPARATOR.join((part for (part, _) in parts))
975
+ return (text, math.exp(sum(log_probs[: min(stop + 1, len(ids))])), parts)
976
+
977
+
978
+ def evidence_text_answer(
979
+ prediction: dict[str, Any],
980
+ ids: list[int],
981
+ log_probs: list[float],
982
+ tokenizer: Any,
983
+ end_id: int,
984
+ text: str,
985
+ spec: dict[str, Any],
986
+ has_images: bool = False,
987
+ ) -> dict[str, Any]:
988
+ if end_id not in ids:
989
+ return prediction
990
+ stop = ids.index(end_id)
991
+ value = tokenizer.decode(ids[:stop]).strip()
992
+ confidence = math.exp(sum(log_probs[: stop + 1]))
993
+ exact = (
994
+ [
995
+ span
996
+ for span in zs.find_spans(text, value)
997
+ if text[span[0] : span[1]] == value
998
+ ]
999
+ if value
1000
+ else []
1001
+ )
1002
+ present = prediction["p_null"] < zs.null_threshold(spec)
1003
+ return {
1004
+ **prediction,
1005
+ "guess": value or None,
1006
+ "value": value if value and present else None,
1007
+ "span": list(exact[0]) if exact else None,
1008
+ "confidence": confidence,
1009
+ "source": "input" if exact else "image" if has_images else "readout",
1010
+ }
1011
+
1012
+
1013
+ def _simple(value: Any) -> str:
1014
+ return "".join(
1015
+ (character for character in str(value).lower() if character.isalnum())
1016
+ )
1017
+
1018
+
1019
+ def _similarity(left: Any, right: Any) -> float:
1020
+ import difflib
1021
+
1022
+ (left, right) = (_simple(left), _simple(right))
1023
+ return difflib.SequenceMatcher(None, left, right).ratio() if left and right else 0.0
1024
+
1025
+
1026
+ def _state_match(
1027
+ text: str, value: str, threshold: float = 0.8, max_words: int = 4000
1028
+ ) -> tuple[int, int] | None:
1029
+ if not text or not value:
1030
+ return None
1031
+ spans = zs.find_spans(text, value)
1032
+ if spans:
1033
+ return spans[0]
1034
+ import re
1035
+
1036
+ words = [match.span() for match in re.finditer("\\S+", text)][:max_words]
1037
+ size = len(value.split())
1038
+ (best, best_span) = (threshold, None)
1039
+ for width in range(max(1, size - 1), size + 2):
1040
+ for first in range(max(0, len(words) - width + 1)):
1041
+ (start, end) = (words[first][0], words[first + width - 1][1])
1042
+ score = _similarity(text[start:end].strip(".,;:()[]\"'"), value)
1043
+ if score >= best:
1044
+ (best, best_span) = (score, (start, end))
1045
+ return best_span
1046
+
1047
+
1048
+ def _stutters(value: Any) -> bool:
1049
+ import re
1050
+
1051
+ simple = _simple(value)
1052
+ return bool(re.search("(.)\\1\\1", simple) or re.search("([a-z]{4,})\\1", simple))
1053
+
1054
+
1055
+ def _digit_code(value: Any) -> bool:
1056
+ simple = _simple(value)
1057
+ return bool(simple) and 2 * sum(
1058
+ (character.isdigit() for character in simple)
1059
+ ) >= len(simple)
1060
+
1061
+
1062
+ PLACEHOLDER_WORDS = frozenset(
1063
+ (
1064
+ "a",
1065
+ "above",
1066
+ "an",
1067
+ "app",
1068
+ "attach",
1069
+ "attached",
1070
+ "attachment",
1071
+ "below",
1072
+ "doc",
1073
+ "document",
1074
+ "documents",
1075
+ "file",
1076
+ "heic",
1077
+ "here",
1078
+ "image",
1079
+ "images",
1080
+ "is",
1081
+ "jpeg",
1082
+ "jpg",
1083
+ "mobile",
1084
+ "page",
1085
+ "pdf",
1086
+ "photo",
1087
+ "photos",
1088
+ "pic",
1089
+ "picture",
1090
+ "please",
1091
+ "png",
1092
+ "scan",
1093
+ "scanned",
1094
+ "screenshot",
1095
+ "see",
1096
+ "the",
1097
+ "this",
1098
+ "upload",
1099
+ "uploaded",
1100
+ "via",
1101
+ )
1102
+ )
1103
+
1104
+
1105
+ def _placeholder_text(value: Any) -> bool:
1106
+ import re
1107
+
1108
+ words = re.findall("[a-z0-9]+", str(value or "").lower())
1109
+ return bool(words) and all((word in PLACEHOLDER_WORDS for word in words))
1110
+
1111
+
1112
+ def _defers(pointer_value: Any, spelled: str) -> bool:
1113
+ if pointer_value is None:
1114
+ return False
1115
+ return _stutters(spelled) or (
1116
+ _digit_code(spelled)
1117
+ and any((character.isdigit() for character in str(pointer_value)))
1118
+ )
1119
+
1120
+
1121
+ def route_spelled(
1122
+ prediction: dict[str, Any],
1123
+ kind: str,
1124
+ spelled: str,
1125
+ items: list[tuple[str, float]],
1126
+ text: str,
1127
+ defer_lists: bool = False,
1128
+ ) -> dict[str, Any]:
1129
+ if kind == "text":
1130
+ if _placeholder_text(prediction.get("guess")):
1131
+ prediction = {
1132
+ **prediction,
1133
+ "value": None,
1134
+ "guess": None,
1135
+ "span": None,
1136
+ "confidence": 0.0,
1137
+ }
1138
+ items = [
1139
+ (item, score) for (item, score) in items if not _placeholder_text(item)
1140
+ ]
1141
+ if not items:
1142
+ return prediction
1143
+ (value, confidence) = (
1144
+ items[0][0] if len(items) == 1 else spelled,
1145
+ min((score for (_, score) in items)),
1146
+ )
1147
+ routed = {**prediction, "spell_confidence": confidence}
1148
+ if _similarity(prediction.get("guess"), value) >= 0.6:
1149
+ if (
1150
+ routed.get("value") is None
1151
+ and prediction.get("guess")
1152
+ and (confidence >= SPELL_MIN_CONFIDENCE)
1153
+ ):
1154
+ return {**routed, "value": prediction["guess"]}
1155
+ return routed
1156
+ span = _state_match(text, value)
1157
+ if span is not None:
1158
+ return {
1159
+ **routed,
1160
+ "value": text[span[0] : span[1]],
1161
+ "guess": text[span[0] : span[1]],
1162
+ "span": list(span),
1163
+ }
1164
+ if confidence >= SPELL_MIN_CONFIDENCE and (
1165
+ not _defers(prediction.get("value"), value)
1166
+ ):
1167
+ return {
1168
+ **routed,
1169
+ "value": value,
1170
+ "guess": value,
1171
+ "span": None,
1172
+ "confidence": confidence,
1173
+ "source": "image",
1174
+ }
1175
+ return routed
1176
+ (pointer_values, pointer_spans) = (
1177
+ list(prediction.get("value") or []),
1178
+ list(prediction.get("spans") or []),
1179
+ )
1180
+ if any((_placeholder_text(value) for value in pointer_values)):
1181
+ kept = [
1182
+ (value, pointer_spans[index] if index < len(pointer_spans) else None)
1183
+ for (index, value) in enumerate(pointer_values)
1184
+ if not _placeholder_text(value)
1185
+ ]
1186
+ (pointer_values, pointer_spans) = (
1187
+ [value for (value, _) in kept],
1188
+ [span for (_, span) in kept],
1189
+ )
1190
+ items = [(item, score) for (item, score) in items if not _placeholder_text(item)]
1191
+ (values, spans, used) = ([], [], set())
1192
+ for item, confidence in items:
1193
+ match = max(
1194
+ range(len(pointer_values)),
1195
+ key=lambda index: _similarity(pointer_values[index], item),
1196
+ default=None,
1197
+ )
1198
+ if (
1199
+ match is not None
1200
+ and match not in used
1201
+ and (_similarity(pointer_values[match], item) >= 0.6)
1202
+ ):
1203
+ used.add(match)
1204
+ values.append(pointer_values[match])
1205
+ spans.append(pointer_spans[match] if match < len(pointer_spans) else None)
1206
+ continue
1207
+ span = _state_match(text, item)
1208
+ if span is not None:
1209
+ value = text[span[0] : span[1]]
1210
+ if not any((_simple(value) == _simple(other) for other in values)):
1211
+ values.append(value)
1212
+ spans.append(list(span))
1213
+ elif (
1214
+ confidence >= SPELL_MIN_CONFIDENCE
1215
+ and (
1216
+ not (
1217
+ pointer_values and (defer_lists or _defers(pointer_values[0], item))
1218
+ )
1219
+ )
1220
+ and (not any((_simple(item) == _simple(other) for other in values)))
1221
+ ):
1222
+ values.append(item)
1223
+ spans.append(None)
1224
+ for index, (value, span) in enumerate(zip(pointer_values, pointer_spans)):
1225
+ if index not in used and (
1226
+ not any((_simple(value) == _simple(other) for other in values))
1227
+ ):
1228
+ values.append(value)
1229
+ spans.append(span)
1230
+ routed = {**prediction, "value": values, "spans": spans}
1231
+ if any((span is None for span in spans)):
1232
+ routed["source"] = "image"
1233
+ return routed
1234
+
1235
+
1236
+ def number_parts(
1237
+ logits: np.ndarray,
1238
+ ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
1239
+ logits = np.asarray(logits)
1240
+ sign = logits[..., :2]
1241
+ exponent = logits[..., 2 : 2 + EXPONENT_CLASSES]
1242
+ digits = logits[..., 2 + EXPONENT_CLASSES :]
1243
+ if logits.shape[-1] != 2 + EXPONENT_CLASSES + NUMBER_DIGITS * 10:
1244
+ raise RuntimeError("number logits do not match the number layout")
1245
+ return (sign, exponent, digits.reshape(*digits.shape[:-1], NUMBER_DIGITS, 10))
1246
+
1247
+
1248
+ def group_class_digits(device: Any = None) -> np.ndarray:
1249
+ classes = np.arange(GROUP_CLASSES, dtype=np.int64)
1250
+ return np.stack(
1251
+ [
1252
+ classes // 10 ** (GROUP_DIGITS - 1 - place) % 10
1253
+ for place in range(GROUP_DIGITS)
1254
+ ],
1255
+ axis=-1,
1256
+ )
1257
+
1258
+
1259
+ def group_slots(exponent_class: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
1260
+ exponent_class = np.asarray(exponent_class).astype(np.int64)
1261
+ power = (exponent_class - 1 + MIN_EXPONENT).reshape(-1, 1, 1)
1262
+ groups = np.arange(GROUP_LOW, GROUP_HIGH + 1, dtype=np.int64).reshape(1, -1, 1)
1263
+ places = np.arange(GROUP_DIGITS - 1, -1, -1, dtype=np.int64).reshape(1, 1, -1)
1264
+ slots = power - (groups * GROUP_DIGITS + places)
1265
+ inside = (
1266
+ (slots >= 0)
1267
+ & (slots < NUMBER_DIGITS)
1268
+ & (exponent_class > 0).reshape(-1, 1, 1)
1269
+ )
1270
+ return (
1271
+ np.where(inside, slots, np.full_like(slots, NUMBER_DIGITS)),
1272
+ inside.any(axis=-1),
1273
+ )
1274
+
1275
+
1276
+ def number_group_logits(
1277
+ digit_logits: np.ndarray,
1278
+ exponent_class: np.ndarray,
1279
+ learned: np.ndarray | None = None,
1280
+ ) -> tuple[np.ndarray, np.ndarray]:
1281
+ digit_logits = np.asarray(digit_logits)
1282
+ count = digit_logits.shape[0]
1283
+ leading_zero = np.zeros((NUMBER_DIGITS, 10), dtype=bool)
1284
+ leading_zero[0, 0] = True
1285
+ log = _masked_fill(_log_softmax(_f32(digit_logits), axis=-1), leading_zero, MASKED)
1286
+ held = np.full((count, 1, 10), MASKED, dtype=log.dtype)
1287
+ held[..., 0] = 0.0
1288
+ padded = np.concatenate([log, held], axis=1)
1289
+ (slots, groups) = group_slots(exponent_class)
1290
+ picked = padded[np.arange(count)[:, None], _flatten1(slots)]
1291
+ picked = picked.reshape(count, NUMBER_GROUPS, GROUP_DIGITS, 10)
1292
+ table = group_class_digits()
1293
+ scores = cast(
1294
+ np.ndarray,
1295
+ sum(
1296
+ (
1297
+ np.take(picked[:, :, place, :], table[:, place], axis=-1)
1298
+ for place in range(GROUP_DIGITS)
1299
+ )
1300
+ ),
1301
+ )
1302
+ if learned is not None:
1303
+ scores = scores + _f32(learned)
1304
+ return (scores, groups)
1305
+
1306
+
1307
+ def temper_number(logits: np.ndarray, spread: np.ndarray) -> np.ndarray:
1308
+ (sign, exponent, digits) = number_parts(logits)
1309
+ temperature = np.exp(
1310
+ ESTIMATE_SPREAD_LIMIT * np.tanh(_f32(spread) / ESTIMATE_SPREAD_LIMIT)
1311
+ )
1312
+ exponent = exponent / temperature[:, :1]
1313
+ digits = np.concatenate(
1314
+ [
1315
+ digits[:, :LEXICAL_DIGITS] / temperature[:, 1:][..., None],
1316
+ digits[:, LEXICAL_DIGITS:],
1317
+ ],
1318
+ axis=1,
1319
+ )
1320
+ return np.concatenate(
1321
+ [sign, exponent, _flatten1(digits)], axis=-1
1322
+ )
1323
+
1324
+
1325
+ def apply_prefix(
1326
+ logits: np.ndarray, views: dict[str, np.ndarray], group: str
1327
+ ) -> np.ndarray:
1328
+ length = views.get(f"{group}_prefix_length")
1329
+ logits = np.asarray(logits)
1330
+ if length is None or not logits.shape[0]:
1331
+ return logits
1332
+ (sign_logits, exponent_logits, digit_logits) = number_parts(logits)
1333
+ slots = np.arange(NUMBER_DIGITS, dtype=np.int64)
1334
+ length = np.asarray(length).astype(np.int64)
1335
+ relative = np.maximum(slots[None, :] - length[:, None], 0)
1336
+ shifted = digit_logits[np.arange(digit_logits.shape[0])[:, None], relative]
1337
+ forced_digits = np.where(
1338
+ np.arange(10, dtype=np.int64)
1339
+ == np.asarray(views[f"{group}_prefix_digits"]).astype(np.int64)[..., None],
1340
+ 0.0,
1341
+ MASKED,
1342
+ ).astype(logits.dtype)
1343
+ digit_logits = np.where(
1344
+ (slots[None, :] < length[:, None])[..., None], forced_digits, shifted
1345
+ )
1346
+ written = (length > 0)[:, None]
1347
+ forced_sign = np.where(
1348
+ np.arange(2, dtype=np.int64)
1349
+ == np.asarray(views[f"{group}_prefix_sign"]).astype(np.int64)[:, None],
1350
+ 0.0,
1351
+ MASKED,
1352
+ ).astype(logits.dtype)
1353
+ forced_exponent = np.where(
1354
+ np.arange(EXPONENT_CLASSES, dtype=np.int64)
1355
+ == np.asarray(views[f"{group}_prefix_exponent"]).astype(np.int64)[:, None],
1356
+ 0.0,
1357
+ MASKED,
1358
+ ).astype(logits.dtype)
1359
+ return np.concatenate(
1360
+ [
1361
+ np.where(written, forced_sign, sign_logits),
1362
+ np.where(written, forced_exponent, exponent_logits),
1363
+ _flatten1(digit_logits),
1364
+ ],
1365
+ axis=-1,
1366
+ )
1367
+
1368
+
1369
+ def window_log_probs(
1370
+ log_probs: np.ndarray, window: np.ndarray
1371
+ ) -> tuple[np.ndarray, np.ndarray]:
1372
+ log_probs = np.asarray(log_probs)
1373
+ bins = np.arange(log_probs.shape[-1], dtype=np.int64)
1374
+ window = np.asarray(window).astype(np.int64)
1375
+ inside = (bins >= window[:, :1]) & (bins <= window[:, 1:])
1376
+ return (_log_softmax(_masked_fill(log_probs, ~inside, MASKED), axis=-1), inside)
1377
+
1378
+
1379
+ def date_parts(
1380
+ logits: np.ndarray,
1381
+ ) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
1382
+ logits = np.asarray(logits)
1383
+ if logits.shape[-1] != YEAR_DIGITS * 10 + YEAR_CLASSES + 12 + 31:
1384
+ raise RuntimeError("date logits do not match the date layout")
1385
+ (digits, year, month, day) = np.split(
1386
+ logits,
1387
+ np.cumsum([YEAR_DIGITS * 10, YEAR_CLASSES, 12]).tolist(),
1388
+ axis=-1,
1389
+ )
1390
+ return (digits.reshape(*digits.shape[:-1], YEAR_DIGITS, 10), year, month, day)
1391
+
1392
+
1393
+ def time_parts(logits: np.ndarray) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
1394
+ logits = np.asarray(logits)
1395
+ if logits.shape[-1] != 24 + 60 + 60:
1396
+ raise RuntimeError("time logits do not match the time layout")
1397
+ (hour, minute, second) = np.split(logits, [24, 84], axis=-1)
1398
+ return (hour, minute, second)
1399
+
1400
+
1401
+ def lexical_bin_log_probs(
1402
+ number_logits: np.ndarray,
1403
+ edge_sign: np.ndarray,
1404
+ edge_class: np.ndarray,
1405
+ edge_digits: np.ndarray,
1406
+ edge_frac: np.ndarray,
1407
+ ) -> np.ndarray:
1408
+ (sign, exponent, digits) = number_parts(
1409
+ np.asarray(number_logits).astype(np.float64)
1410
+ )
1411
+ (edge_sign, edge_class, edge_digits) = (
1412
+ np.asarray(edge_sign),
1413
+ np.asarray(edge_class).astype(np.int64),
1414
+ np.asarray(edge_digits).astype(np.int64),
1415
+ )
1416
+ sign_probs = _softmax(sign, axis=-1)
1417
+ exponent_probs = _softmax(exponent, axis=-1)
1418
+ zero = exponent_probs[:, :1]
1419
+ nonzero = exponent_probs[:, 1:] / np.maximum(1.0 - zero, 1e-300)
1420
+ below_class = _cumsum(nonzero, axis=-1) - nonzero
1421
+ leading = _masked_fill(digits[:, :1], np.arange(10) == 0, float("-inf"))
1422
+ digit_probs = _softmax(
1423
+ np.concatenate([leading, digits[:, 1:LEXICAL_DIGITS]], axis=1), axis=-1
1424
+ )
1425
+ below_digit = _cumsum(digit_probs, axis=-1) - digit_probs
1426
+ classes = np.clip(edge_class - 1, 0, nonzero.shape[1] - 1)
1427
+ within = np.asarray(edge_frac).astype(np.float64)
1428
+ for position in reversed(range(LEXICAL_DIGITS)):
1429
+ index = edge_digits[..., position]
1430
+ within = (
1431
+ np.take_along_axis(below_digit[:, position], index, axis=1)
1432
+ + np.take_along_axis(digit_probs[:, position], index, axis=1) * within
1433
+ )
1434
+ magnitude = (
1435
+ np.take_along_axis(below_class, classes, axis=1)
1436
+ + np.take_along_axis(nonzero, classes, axis=1) * within
1437
+ )
1438
+ negative = sign_probs[:, 1:] * (1.0 - zero)
1439
+ positive = sign_probs[:, :1] * (1.0 - zero)
1440
+ cdf = np.where(
1441
+ edge_sign == EDGE_NEGATIVE,
1442
+ negative * (1.0 - magnitude),
1443
+ np.where(
1444
+ edge_sign == EDGE_ZERO,
1445
+ np.broadcast_to(negative, magnitude.shape),
1446
+ negative + zero + positive * magnitude,
1447
+ ),
1448
+ )
1449
+ mass = np.maximum(cdf[:, 1:] - cdf[:, :-1], 0.0) + 1e-30
1450
+ return (np.log(mass) - np.log(mass.sum(axis=-1, keepdims=True))).astype(
1451
+ np.float32
1452
+ )
1453
+
1454
+
1455
+ def estimate_log_probs(
1456
+ range_logits: np.ndarray,
1457
+ number_logits: np.ndarray | None = None,
1458
+ gate: np.ndarray | None = None,
1459
+ lexical: np.ndarray | None = None,
1460
+ edge_sign: np.ndarray | None = None,
1461
+ edge_class: np.ndarray | None = None,
1462
+ edge_digits: np.ndarray | None = None,
1463
+ edge_frac: np.ndarray | None = None,
1464
+ ) -> np.ndarray:
1465
+ range_part = _log_softmax(_f32(range_logits), axis=-1)
1466
+ if number_logits is None or not np.asarray(number_logits).shape[0]:
1467
+ return range_part
1468
+ lexical_part = lexical_bin_log_probs(
1469
+ number_logits,
1470
+ cast(np.ndarray, edge_sign),
1471
+ cast(np.ndarray, edge_class),
1472
+ cast(np.ndarray, edge_digits),
1473
+ cast(np.ndarray, edge_frac),
1474
+ )
1475
+ use = np.asarray(cast(np.ndarray, lexical)).astype(bool)[:, None]
1476
+ gate = _f32(cast(np.ndarray, gate))[:, None]
1477
+ mixed = np.logaddexp(
1478
+ _log_sigmoid(gate) + lexical_part,
1479
+ _log_sigmoid(-gate) + range_part,
1480
+ )
1481
+ return np.where(use, mixed, range_part)
1482
+
1483
+
1484
+ def decode_number(
1485
+ logits: np.ndarray, spec: dict[str, Any], groups: np.ndarray | None = None
1486
+ ) -> tuple[float | int, float]:
1487
+ (sign_logits, exponent_logits, digit_logits) = number_parts(_f32(logits))
1488
+ decimals = zs.allowed_decimals(spec)
1489
+ exponent_log = _log_softmax(exponent_logits, axis=-1)
1490
+ exponent_class = int(exponent_log.argmax())
1491
+ log_probability = float(exponent_log[exponent_class])
1492
+ if exponent_class == 0:
1493
+ return (0, math.exp(log_probability))
1494
+ power = exponent_class - 1 + MIN_EXPONENT
1495
+ kept = NUMBER_DIGITS if decimals is None else power + decimals + 1
1496
+ if kept < 0:
1497
+ return (0, math.exp(log_probability))
1498
+ leading_zero = np.zeros((NUMBER_DIGITS, 10), dtype=bool)
1499
+ leading_zero[0, 0] = True
1500
+ digit_log = _masked_fill(_log_softmax(digit_logits, axis=-1), leading_zero, MASKED)
1501
+ digits = digit_log.argmax(axis=-1).tolist()
1502
+ sign_log = _log_softmax(sign_logits, axis=-1)
1503
+ sign = int(sign_log.argmax())
1504
+ kept = min(kept, NUMBER_DIGITS)
1505
+ log_probability += float(sign_log[sign])
1506
+ if groups is None:
1507
+ log_probability += sum(
1508
+ (float(digit_log[position, digits[position]]) for position in range(kept))
1509
+ )
1510
+ if kept < NUMBER_DIGITS:
1511
+ rounding = digit_log[kept, 5:] if digits[kept] >= 5 else digit_log[kept, :5]
1512
+ log_probability += float(_logsumexp(rounding, axis=0))
1513
+ else:
1514
+ exponent_tensor = np.array([exponent_class], dtype=np.int64)
1515
+ (scores, present) = number_group_logits(
1516
+ digit_logits[None],
1517
+ exponent_tensor,
1518
+ _f32(groups)[None],
1519
+ )
1520
+ group_log = _log_softmax(scores[0], axis=-1)
1521
+ slots = group_slots(exponent_tensor)[0][0].tolist()
1522
+ table = group_class_digits()
1523
+ counted = set()
1524
+ for group in range(NUMBER_GROUPS):
1525
+ if not bool(present[0, group]):
1526
+ continue
1527
+ best = int(group_log[group].argmax())
1528
+ for place, slot in enumerate(slots[group]):
1529
+ if slot < NUMBER_DIGITS:
1530
+ digits[slot] = int(table[best, place])
1531
+ if any((slot < kept for slot in slots[group])):
1532
+ counted.add(group)
1533
+ log_probability += float(group_log[group, best])
1534
+ if kept < NUMBER_DIGITS:
1535
+ for group in range(NUMBER_GROUPS):
1536
+ if kept in slots[group]:
1537
+ if group not in counted:
1538
+ place = slots[group].index(kept)
1539
+ same = (
1540
+ table[:, place] >= 5
1541
+ if digits[kept] >= 5
1542
+ else table[:, place] < 5
1543
+ )
1544
+ log_probability += float(
1545
+ _logsumexp(group_log[group][same], axis=0)
1546
+ )
1547
+ break
1548
+ else:
1549
+ rounding = (
1550
+ digit_log[kept, 5:] if digits[kept] >= 5 else digit_log[kept, :5]
1551
+ )
1552
+ log_probability += float(_logsumexp(rounding, axis=0))
1553
+ magnitude = Decimal(int("".join((str(digit) for digit in digits)))).scaleb(
1554
+ power - NUMBER_DIGITS + 1
1555
+ )
1556
+ if decimals is not None:
1557
+ magnitude = magnitude.quantize(
1558
+ Decimal(1).scaleb(-decimals), rounding=ROUND_HALF_UP
1559
+ )
1560
+ if magnitude == 0:
1561
+ return (0, math.exp(log_probability))
1562
+ value = -magnitude if sign else magnitude
1563
+ if decimals == 0 or (value == value.to_integral_value() and abs(value) < 2**53):
1564
+ return (int(value), math.exp(log_probability))
1565
+ return (float(value), math.exp(log_probability))
1566
+
1567
+
1568
+ def number_from_numeral(
1569
+ magnitude: Decimal,
1570
+ logits: np.ndarray,
1571
+ spec: dict[str, Any],
1572
+ check_exponent: bool = True,
1573
+ ) -> float | int | None:
1574
+ (sign_logits, exponent_logits, _) = number_parts(_f32(logits))
1575
+ if check_exponent:
1576
+ target = number_components(float(magnitude))
1577
+ if target is None or int(exponent_logits.argmax()) != target[1]:
1578
+ return None
1579
+ decimals = zs.allowed_decimals(spec)
1580
+ if decimals is not None:
1581
+ magnitude = magnitude.quantize(
1582
+ Decimal(1).scaleb(-decimals), rounding=ROUND_HALF_UP
1583
+ )
1584
+ if magnitude == 0:
1585
+ return 0
1586
+ value = -magnitude if int(sign_logits.argmax()) else magnitude
1587
+ if decimals == 0 or (value == value.to_integral_value() and abs(value) < 2**53):
1588
+ return int(value)
1589
+ return float(value)
1590
+
1591
+
1592
+ def number_from_numerals(
1593
+ values: list[Decimal],
1594
+ logits: np.ndarray,
1595
+ spec: dict[str, Any],
1596
+ readout: float | None,
1597
+ confident: bool = False,
1598
+ ) -> float | int | None:
1599
+ agreeing = [
1600
+ value
1601
+ for value in (
1602
+ number_from_numeral(magnitude, logits, spec) for magnitude in values
1603
+ )
1604
+ if value is not None
1605
+ ]
1606
+ if not agreeing and confident and values:
1607
+
1608
+ def distance(magnitude: Decimal) -> float:
1609
+ if readout is None or not readout or (not magnitude):
1610
+ return 0.0
1611
+ return abs(math.log10(float(magnitude)) - math.log10(abs(float(readout))))
1612
+
1613
+ agreeing = [
1614
+ value
1615
+ for value in (
1616
+ number_from_numeral(min(values, key=distance), logits, spec, False),
1617
+ )
1618
+ if value is not None
1619
+ ]
1620
+ if not agreeing:
1621
+ return None
1622
+ if readout is None:
1623
+ return agreeing[0]
1624
+ return min(agreeing, key=lambda value: abs(float(value) - float(readout)))
1625
+
1626
+
1627
+ def copied_number(
1628
+ output: dict[str, Any],
1629
+ row: int,
1630
+ record: EncodedRecord,
1631
+ spec: dict[str, Any],
1632
+ readout: float | None = None,
1633
+ ) -> tuple[float | int, float, list[int]] | None:
1634
+ if (
1635
+ "number_copy_gate" not in output
1636
+ or record.record.get("images")
1637
+ or (not record.text)
1638
+ ):
1639
+ return None
1640
+ if os.environ.get("SZ_DISABLE_NUMBER_COPY") == "1":
1641
+ return None
1642
+ gate = float(_sigmoid(_f32(output["number_copy_gate"][row])))
1643
+ if gate < 0.5:
1644
+ return None
1645
+ if "number_copy_best" in output:
1646
+ (best, probability) = (
1647
+ output["number_copy_best"][row],
1648
+ output["number_copy_probability"][row],
1649
+ )
1650
+ else:
1651
+ scores = _f32(output["number_copy"][row]).flatten()
1652
+ (best, probability) = (
1653
+ int(scores.argmax()),
1654
+ float(_softmax(scores, axis=0).max()),
1655
+ )
1656
+ (start, length) = divmod(int(best), MAX_SPAN)
1657
+ last = min(start + length, len(record.offsets) - 1)
1658
+ if start >= len(record.offsets):
1659
+ return None
1660
+ (char_start, char_end) = (record.offsets[start][0], record.offsets[last][1])
1661
+ while char_start < char_end and (not record.text[char_start].isalnum()):
1662
+ char_start += 1
1663
+ around = [
1664
+ found
1665
+ for found in read_numerals(record.text, every=True)
1666
+ if found[1] < char_end and found[2] > char_start
1667
+ ]
1668
+ if not around:
1669
+ return None
1670
+ nearest = min(
1671
+ around,
1672
+ key=lambda found: (
1673
+ abs(found[1] - char_start) + abs(found[2] - char_end),
1674
+ -(found[2] - found[1]),
1675
+ ),
1676
+ )
1677
+ whole = [
1678
+ found
1679
+ for found in read_numerals(record.text)
1680
+ if found[1] <= char_start
1681
+ and found[2] >= char_end
1682
+ and (found[2] - found[1] > nearest[2] - nearest[1])
1683
+ ]
1684
+ choices = whole[:1] + [nearest]
1685
+ if gate * probability < COPY_MIN_CONFIDENCE:
1686
+ return None
1687
+ sure = gate >= COPY_CONFIDENT
1688
+ (value, numeral_start, numeral_end) = (None, nearest[1], nearest[2])
1689
+ for values, start, end in choices:
1690
+ run = NUMERAL_RUN.match(record.text, start)
1691
+ printed = record.text[start : min(end, run.end())] if run else ""
1692
+ settled = (
1693
+ numeral_convention(record.text) is not None
1694
+ and len(numeral_values(printed)) > 1
1695
+ )
1696
+ enclosing = bool(whole) and (start, end) == (whole[0][1], whole[0][2])
1697
+ value = number_from_numerals(
1698
+ values,
1699
+ output["number"][row],
1700
+ spec,
1701
+ readout,
1702
+ confident=settled or (sure and enclosing and (len(values) == 1)),
1703
+ )
1704
+ if value is not None:
1705
+ (numeral_start, numeral_end) = (start, end)
1706
+ break
1707
+ if value is None and sure:
1708
+ (values, numeral_start, numeral_end) = choices[0]
1709
+ value = number_from_numerals(
1710
+ values, output["number"][row], spec, readout, confident=True
1711
+ )
1712
+ if value is None or (readout is not None and rescaled(readout, value)):
1713
+ return None
1714
+ return (value, gate * probability, [numeral_start, numeral_end])
1715
+
1716
+
1717
+ def rescaled(readout: float, copied: float) -> bool:
1718
+ try:
1719
+ (first, second) = (
1720
+ abs(Decimal(str(readout))).normalize(),
1721
+ abs(Decimal(str(copied))).normalize(),
1722
+ )
1723
+ except ArithmeticError:
1724
+ return False
1725
+ if not first or not second or first == second:
1726
+ return False
1727
+ return first.as_tuple().digits == second.as_tuple().digits
1728
+
1729
+
1730
+ def decode_date(logits: np.ndarray) -> tuple[str, float]:
1731
+ (digit_logits, year_logits, month_logits, day_logits) = date_parts(_f32(logits))
1732
+ class_log = _log_softmax(year_logits, axis=-1)
1733
+ year_class = int(class_log.argmax())
1734
+ log_probability = float(class_log[year_class])
1735
+ if year_class < YEAR_OUTSIDE:
1736
+ year = YEAR_LOW + year_class
1737
+ else:
1738
+ digit_log = _log_softmax(digit_logits, axis=-1)
1739
+ digits = digit_log.argmax(axis=-1).tolist()
1740
+ if digits == [0, 0, 0, 0]:
1741
+ masked = digit_log[3].copy()
1742
+ masked[0] = MASKED
1743
+ digits[3] = int(masked.argmax())
1744
+ year = int("".join((str(digit) for digit in digits)))
1745
+ log_probability += float(
1746
+ sum((digit_log[position, digit] for (position, digit) in enumerate(digits)))
1747
+ )
1748
+ (month_log, day_log) = (
1749
+ _log_softmax(month_logits, axis=-1),
1750
+ _log_softmax(day_logits, axis=-1),
1751
+ )
1752
+ joint = month_log[:, None] + day_log[None, :]
1753
+ lengths = np.array(
1754
+ [calendar.monthrange(year, month)[1] for month in range(1, 13)],
1755
+ dtype=np.int64,
1756
+ )
1757
+ joint = _masked_fill(joint, np.arange(31)[None, :] >= lengths[:, None], MASKED)
1758
+ best = int(joint.flatten().argmax())
1759
+ (month, day) = divmod(best, 31)
1760
+ log_probability += float(joint.flatten()[best])
1761
+ return (
1762
+ datetime.date(year, month + 1, day + 1).isoformat(),
1763
+ math.exp(log_probability),
1764
+ )
1765
+
1766
+
1767
+ def decode_time(logits: np.ndarray) -> tuple[str, float]:
1768
+ parts = [_log_softmax(part, axis=-1) for part in time_parts(_f32(logits))]
1769
+ values = [int(part.argmax()) for part in parts]
1770
+ return (
1771
+ zs.format_time(*values),
1772
+ math.exp(sum((float(part[value]) for (part, value) in zip(parts, values)))),
1773
+ )
1774
+
1775
+
1776
+ def decode_spans(
1777
+ labels: list[int],
1778
+ offsets: list[tuple[int, int]],
1779
+ text: str,
1780
+ trims: list[list[int]] | None = None,
1781
+ ) -> tuple[list[str], list[list[int]]]:
1782
+ spans: list[list[int]] = []
1783
+ current: list[int] | None = None
1784
+ for position, label in enumerate(labels):
1785
+ if label == TAG_BEGIN:
1786
+ if current is not None:
1787
+ spans.append(current)
1788
+ current = [position, position]
1789
+ elif label == TAG_INSIDE and current is not None:
1790
+ current[1] = position
1791
+ elif current is not None:
1792
+ spans.append(current)
1793
+ current = None
1794
+ if current is not None:
1795
+ spans.append(current)
1796
+ values: list[str] = []
1797
+ char_spans: list[list[int]] = []
1798
+ for first, last in spans:
1799
+ (char_start, char_end) = trimmed_span(text, offsets, first, last, trims)
1800
+ if not text[char_start:char_end].strip():
1801
+ continue
1802
+ char_spans.append([char_start, char_end])
1803
+ if text[char_start:char_end] not in values:
1804
+ values.append(text[char_start:char_end])
1805
+ return (values, char_spans)
1806
+
1807
+
1808
+ def quantile_from_cdf(
1809
+ cdf: list[float], probabilities: list[float], fraction: float, bins: int
1810
+ ) -> float:
1811
+ index = min(bisect_left(cdf, fraction), bins - 1)
1812
+ previous = cdf[index - 1] if index > 0 else 0.0
1813
+ inside = (
1814
+ (fraction - previous) / probabilities[index]
1815
+ if probabilities[index] > 0
1816
+ else 0.5
1817
+ )
1818
+ return (index + min(1.0, max(0.0, inside))) / bins
1819
+
1820
+
1821
+ def decode_estimate(
1822
+ logits: np.ndarray,
1823
+ offsets: np.ndarray,
1824
+ overflow: np.ndarray,
1825
+ spec: dict[str, Any],
1826
+ ) -> dict[str, Any]:
1827
+ probabilities = _softmax(_f32(logits), axis=-1)
1828
+ cdf = _cumsum(probabilities, axis=-1).tolist()
1829
+ row = probabilities.tolist()
1830
+ bins = len(row)
1831
+ shift = _sigmoid(_f32(offsets)).tolist()
1832
+ (low, high, scale) = zs.estimate_range(spec)
1833
+ centers = [(index + shift[index]) / bins for index in range(bins)]
1834
+ mean = sum(
1835
+ (
1836
+ probability * zs.from_unit(center, low, high, scale)
1837
+ for (probability, center) in zip(row, centers)
1838
+ )
1839
+ )
1840
+ quantiles: list[Any] = [
1841
+ zs.from_unit(
1842
+ quantile_from_cdf(cdf, row, fraction / 100.0, bins), low, high, scale
1843
+ )
1844
+ for fraction in range(1, 100)
1845
+ ]
1846
+ value = (
1847
+ zs.from_unit(
1848
+ sum((probability * center for (probability, center) in zip(row, centers))),
1849
+ low,
1850
+ high,
1851
+ scale,
1852
+ )
1853
+ if scale == "log"
1854
+ else mean
1855
+ )
1856
+ step = zs.estimate_step(spec)
1857
+ if step > 0:
1858
+ quantiles = [
1859
+ zs.snap_quantile(quantile, step, low, high) for quantile in quantiles
1860
+ ]
1861
+ value = zs.snap(mean, step, low, high)
1862
+ if zs.is_date_estimate(spec):
1863
+ (value, mean) = (zs.estimate_value(spec, value), zs.estimate_value(spec, mean))
1864
+ quantiles = [zs.estimate_value(spec, quantile) for quantile in quantiles]
1865
+ prediction = {
1866
+ "value": value,
1867
+ "mean": mean,
1868
+ "median": quantiles[49],
1869
+ "p10": quantiles[9],
1870
+ "p90": quantiles[89],
1871
+ "quantiles": quantiles,
1872
+ }
1873
+ if not zs.is_date_estimate(spec):
1874
+ overflow = np.asarray(overflow)
1875
+ sides = _softmax(
1876
+ np.concatenate([np.zeros(1, dtype=overflow.dtype), _f32(overflow)]), axis=0
1877
+ ).tolist()
1878
+ (prediction["p_below"], prediction["p_above"]) = (sides[BELOW], sides[ABOVE])
1879
+ return prediction
1880
+
1881
+
1882
+ def estimate_row_log_probs(
1883
+ output: dict[str, Any],
1884
+ row: int,
1885
+ spec: dict[str, Any],
1886
+ window: tuple[int, int] | None = None,
1887
+ ) -> np.ndarray:
1888
+ log_probs = _estimate_row_log_probs(output, row, spec)
1889
+ if window is None:
1890
+ return log_probs
1891
+ return window_log_probs(log_probs[None], np.array([window], dtype=np.int64))[0][0]
1892
+
1893
+
1894
+ def _estimate_row_log_probs(
1895
+ output: dict[str, Any], row: int, spec: dict[str, Any]
1896
+ ) -> np.ndarray:
1897
+ logits = _f32(output["estimate"][row])
1898
+ parts = (
1899
+ estimate_edge_parts(spec, logits.shape[-1])
1900
+ if "estimate_number" in output
1901
+ else None
1902
+ )
1903
+ if parts is None:
1904
+ return _log_softmax(logits, axis=-1)
1905
+ (sign, classes, digits, fractions) = parts
1906
+ count = len(sign)
1907
+ return estimate_log_probs(
1908
+ logits[None],
1909
+ _f32(output["estimate_number"][row])[None],
1910
+ _f32(output["estimate_gate"][row]).reshape(1),
1911
+ np.ones(1, dtype=np.float32),
1912
+ np.array([sign], dtype=np.int64),
1913
+ np.array([classes], dtype=np.int64),
1914
+ np.array(digits, dtype=np.int64).reshape(1, count, LEXICAL_DIGITS),
1915
+ np.array([fractions], dtype=np.float64),
1916
+ )[0]
1917
+
1918
+
1919
+ def decode_record(
1920
+ output: dict[str, Any],
1921
+ record: EncodedRecord,
1922
+ tokenizer: Any = None,
1923
+ end_id: int | None = None,
1924
+ ) -> dict[str, dict[str, Any]]:
1925
+ fields = record.fields
1926
+ specs = {item.name: record.record["fields"][item.name] for item in fields}
1927
+ p_null = _sigmoid(_f32(output["null"])).tolist()
1928
+ predictions: dict[str, dict[str, Any]] = {}
1929
+ value: Any
1930
+ rows_of = {
1931
+ group: [
1932
+ position for (position, item) in enumerate(fields) if item.kind in kinds
1933
+ ]
1934
+ for (group, kinds) in (
1935
+ ("text", ("text",)),
1936
+ ("tags", ("text_list",)),
1937
+ ("number", ("number",)),
1938
+ ("date", ("date", "datetime")),
1939
+ ("time", ("time", "datetime")),
1940
+ ("estimate", ("estimate",)),
1941
+ ("number_list", ("number_list",)),
1942
+ ("date_list", ("date_list",)),
1943
+ )
1944
+ }
1945
+ index_of = {
1946
+ group: {position: row for (row, position) in enumerate(rows)}
1947
+ for (group, rows) in rows_of.items()
1948
+ }
1949
+ if rows_of["text"] and "text_best" in output:
1950
+ (best, probabilities) = (output["text_best"], output["text_probability"])
1951
+ elif rows_of["text"]:
1952
+ scores = _f32(output["text"])
1953
+ scores = _flatten1(scores)
1954
+ best = scores.argmax(axis=1).tolist()
1955
+ probabilities = _softmax(scores, axis=1).max(axis=1).tolist()
1956
+ if rows_of["tags"]:
1957
+ labels = (
1958
+ output["tags_labels"]
1959
+ if "tags_labels" in output
1960
+ else np.asarray(output["tags"]).argmax(axis=-1).tolist()
1961
+ )
1962
+ trims = output.get("trim_labels")
1963
+ if trims is None and "trim" in output:
1964
+ trims = np.asarray(output["trim"]).argmax(axis=-1).tolist()
1965
+ for position, item in enumerate(fields):
1966
+ spec = specs[item.name]
1967
+ kind = item.kind
1968
+ if kind == "estimate":
1969
+ row = index_of["estimate"][position]
1970
+ predictions[item.name] = decode_estimate(
1971
+ estimate_row_log_probs(output, row, spec, item.window),
1972
+ output["estimate_offset"][row],
1973
+ output["estimate_overflow"][row],
1974
+ spec,
1975
+ )
1976
+ continue
1977
+ if kind == "text_list":
1978
+ row = index_of["tags"][position]
1979
+ (values, spans) = decode_spans(
1980
+ labels[row], record.offsets, record.text, trims
1981
+ )
1982
+ predictions[item.name] = {"value": values, "spans": spans}
1983
+ if "tags_log_probability" in output:
1984
+ predictions[item.name]["confidence"] = math.exp(
1985
+ output["tags_log_probability"][row]
1986
+ )
1987
+ elif "tags" in output:
1988
+ label_log = _log_softmax(_f32(output["tags"][row]), axis=-1)
1989
+ predictions[item.name]["confidence"] = math.exp(
1990
+ float(label_log.max(axis=-1).sum())
1991
+ )
1992
+ continue
1993
+ if kind in LIST_KINDS:
1994
+ row = index_of[kind][position]
1995
+ ends = _sigmoid(_f32(output[f"{kind}_end"][row])).tolist()
1996
+ (values, confidences) = ([], [])
1997
+ log_probability = 0.0
1998
+ for slot in range(LIST_SLOTS):
1999
+ if ends[slot] >= 0.5:
2000
+ log_probability += math.log(max(ends[slot], 1e-12))
2001
+ break
2002
+ log_probability += math.log(max(1.0 - ends[slot], 1e-12))
2003
+ if kind == "number_list":
2004
+ (value, confidence) = decode_number(
2005
+ output[kind][row, slot],
2006
+ spec,
2007
+ output["number_list_groups"][row, slot]
2008
+ if "number_list_groups" in output
2009
+ else None,
2010
+ )
2011
+ else:
2012
+ (value, confidence) = decode_date(output[kind][row, slot])
2013
+ values.append(value)
2014
+ confidences.append(confidence)
2015
+ log_probability += math.log(max(confidence, 1e-12))
2016
+ predictions[item.name] = {
2017
+ "value": values,
2018
+ "confidences": confidences,
2019
+ "confidence": math.exp(log_probability),
2020
+ }
2021
+ continue
2022
+ prediction: dict[str, Any] = {"p_null": p_null[position]}
2023
+ if kind == "text":
2024
+ row = index_of["text"][position]
2025
+ (start, length) = divmod(best[row], MAX_SPAN)
2026
+ last = min(start + length, len(record.offsets) - 1)
2027
+ (char_start, char_end) = trimmed_span(
2028
+ record.text, record.offsets, start, last, trims
2029
+ )
2030
+ (value, confidence) = (record.text[char_start:char_end], probabilities[row])
2031
+ prediction["span"] = [char_start, char_end]
2032
+ if not record.text:
2033
+ (value, prediction["span"]) = (None, None)
2034
+ elif kind == "number":
2035
+ number_row = index_of["number"][position]
2036
+ (value, confidence) = decode_number(
2037
+ output["number"][number_row],
2038
+ spec,
2039
+ output["number_groups"][number_row]
2040
+ if "number_groups" in output
2041
+ else None,
2042
+ )
2043
+ copied = copied_number(output, number_row, record, spec, value)
2044
+ if (
2045
+ copied is not None
2046
+ and value is not None
2047
+ and (os.environ.get("SZ_NUMBER_COPY_VETO", "1") == "1")
2048
+ and numeral_spans(record.text, value, every=False)
2049
+ ):
2050
+ copied = None
2051
+ if copied is not None:
2052
+ (value, confidence, prediction["span"]) = copied
2053
+ prediction["source"] = "input"
2054
+ if spec["type"] == "duration":
2055
+ prediction["unit"] = zs.duration_unit(spec)
2056
+ elif kind == "date":
2057
+ (value, confidence) = decode_date(
2058
+ output["date"][index_of["date"][position]]
2059
+ )
2060
+ elif kind == "time":
2061
+ (value, confidence) = decode_time(
2062
+ output["time"][index_of["time"][position]]
2063
+ )
2064
+ else:
2065
+ (day, day_confidence) = decode_date(
2066
+ output["date"][index_of["date"][position]]
2067
+ )
2068
+ (clock, clock_confidence) = decode_time(
2069
+ output["time"][index_of["time"][position]]
2070
+ )
2071
+ (value, confidence) = (f"{day}T{clock}", day_confidence * clock_confidence)
2072
+ prediction["guess"] = value
2073
+ prediction["confidence"] = confidence
2074
+ prediction["value"] = (
2075
+ None if p_null[position] >= zs.null_threshold(spec) else value
2076
+ )
2077
+ predictions[item.name] = prediction
2078
+ if tokenizer is not None and end_id is not None and ("spell_ids" in output):
2079
+ (ids, log_probs) = (
2080
+ np.asarray(output["spell_ids"]).tolist(),
2081
+ _f32(output["spell_log_probs"]).tolist(),
2082
+ )
2083
+ for position, item in enumerate(fields):
2084
+ if item.kind == "text":
2085
+ row = index_of["text"][position]
2086
+ elif item.kind == "text_list":
2087
+ row = len(rows_of["text"]) + index_of["tags"][position]
2088
+ else:
2089
+ continue
2090
+ (spelled, _, parts) = spelled_answer(
2091
+ ids[row], log_probs[row], tokenizer, end_id
2092
+ )
2093
+ predictions[item.name] = route_spelled(
2094
+ predictions[item.name], item.kind, spelled, parts, record.text
2095
+ )
2096
+ if tokenizer is not None and "slot_ids" in output:
2097
+ slot_end = _tokens(tokenizer, SPELL_END)[0]
2098
+ (slot_ids, slot_log_probs) = (
2099
+ np.asarray(output["slot_ids"]).tolist(),
2100
+ _f32(output["slot_log_probs"]).tolist(),
2101
+ )
2102
+ slot_rows = [
2103
+ position for (position, item) in enumerate(fields) if item.answer_slots
2104
+ ]
2105
+ for row, position in enumerate(slot_rows):
2106
+ item = fields[position]
2107
+ if item.kind not in ("text", "text_list"):
2108
+ continue
2109
+ count = len(item.answer_slots)
2110
+ (spelled, _probability, parts) = spelled_answer(
2111
+ slot_ids[row][:count], slot_log_probs[row][:count], tokenizer, slot_end
2112
+ )
2113
+ prediction = predictions[item.name]
2114
+ if (record.record.get("_meta") or {}).get(
2115
+ "construction"
2116
+ ) == zs.EVIDENCE_CONSTRUCTION and item.kind == "text":
2117
+ predictions[item.name] = evidence_text_answer(
2118
+ prediction,
2119
+ slot_ids[row][:count],
2120
+ slot_log_probs[row][:count],
2121
+ tokenizer,
2122
+ slot_end,
2123
+ record.text,
2124
+ specs[item.name],
2125
+ bool(record.record.get("images")),
2126
+ )
2127
+ continue
2128
+ if item.kind in ("text", "text_list"):
2129
+ predictions[item.name] = route_spelled(
2130
+ prediction, item.kind, spelled, parts, record.text, defer_lists=True
2131
+ )
2132
+ continue
2133
+ return predictions
2134
+
2135
+
2136
+ FIELD_KINDS = SCALAR_KINDS + ("estimate", "text_list") + LIST_KINDS
2137
+ VIEW_GROUPS = (
2138
+ ("text", ("text",)),
2139
+ ("tags", ("text_list",)),
2140
+ ("number", ("number",)),
2141
+ ("date", ("date", "datetime")),
2142
+ ("time", ("time", "datetime")),
2143
+ ("estimate", ("estimate",)),
2144
+ )
2145
+ COMPACT_KEYS = (
2146
+ "number",
2147
+ "date",
2148
+ "time",
2149
+ "estimate",
2150
+ "estimate_offset",
2151
+ "estimate_overflow",
2152
+ "number_list_end",
2153
+ "number_list",
2154
+ "date_list_end",
2155
+ "date_list",
2156
+ "estimate_number",
2157
+ "estimate_gate",
2158
+ "number_groups",
2159
+ "number_list_groups",
2160
+ "number_copy_gate",
2161
+ )
2162
+ COMPACT_GROUPS = {
2163
+ "number": "number",
2164
+ "date": "date",
2165
+ "time": "time",
2166
+ "estimate": "estimate",
2167
+ "estimate_offset": "estimate",
2168
+ "estimate_overflow": "estimate",
2169
+ "number_list_end": "number_list",
2170
+ "number_list": "number_list",
2171
+ "date_list_end": "date_list",
2172
+ "date_list": "date_list",
2173
+ "estimate_number": "estimate",
2174
+ "estimate_gate": "estimate",
2175
+ "number_groups": "number",
2176
+ "number_list_groups": "number_list",
2177
+ "number_copy_gate": "number",
2178
+ }
2179
+
2180
+
2181
+ def prediction_layout(record: EncodedRecord) -> list[int]:
2182
+ layout = [
2183
+ len(record.input_ids),
2184
+ record.input_start,
2185
+ len(record.offsets),
2186
+ len(record.fields),
2187
+ ]
2188
+ for item in record.fields:
2189
+ layout += [
2190
+ FIELD_KINDS.index(item.kind),
2191
+ item.query,
2192
+ len(item.items),
2193
+ *item.items,
2194
+ ]
2195
+ slotted = [
2196
+ (index, item.answer_slots)
2197
+ for (index, item) in enumerate(record.fields)
2198
+ if item.answer_slots
2199
+ ]
2200
+ if slotted:
2201
+ layout.append(len(slotted))
2202
+ for index, slots in slotted:
2203
+ layout += [index, len(slots), *slots]
2204
+ return layout
2205
+
2206
+
2207
+ def parse_prediction_layout(
2208
+ layout: list[int], num_tokens: int, with_slots: bool = False
2209
+ ) -> tuple[Any, ...]:
2210
+ if len(layout) < 4 or any((type(value) is not int for value in layout)):
2211
+ raise ValueError("prediction_layout must be a list of ints")
2212
+ (prompt_length, input_start, input_length, count) = layout[:4]
2213
+ shift = num_tokens - prompt_length
2214
+ if (
2215
+ shift < 0
2216
+ or count < 1
2217
+ or input_length < 1
2218
+ or (not 0 <= input_start < input_start + input_length <= prompt_length)
2219
+ ):
2220
+ raise ValueError("prediction_layout does not match the prompt")
2221
+ kinds: list[str] = []
2222
+ queries: list[int] = []
2223
+ items: list[list[int]] = []
2224
+ cursor = 4
2225
+ for _ in range(count):
2226
+ if cursor + 3 > len(layout):
2227
+ raise ValueError("prediction_layout is truncated")
2228
+ (kind, query, size) = layout[cursor : cursor + 3]
2229
+ cursor += 3
2230
+ if (
2231
+ not 0 <= kind < len(FIELD_KINDS)
2232
+ or not input_start + input_length <= query < prompt_length
2233
+ ):
2234
+ raise ValueError("prediction_layout has an invalid field")
2235
+ expected = LIST_SLOTS if FIELD_KINDS[kind] in LIST_KINDS else 0
2236
+ slots = layout[cursor : cursor + size]
2237
+ cursor += size
2238
+ if (
2239
+ size != expected
2240
+ or len(slots) != size
2241
+ or any((not query < slot < prompt_length for slot in slots))
2242
+ ):
2243
+ raise ValueError("prediction_layout has invalid item positions")
2244
+ kinds.append(FIELD_KINDS[kind])
2245
+ queries.append(query + shift)
2246
+ items.append([slot + shift for slot in slots])
2247
+ slot_fields: list[int] = []
2248
+ answer_slots: list[list[int]] = []
2249
+ if cursor < len(layout):
2250
+ slotted = layout[cursor]
2251
+ cursor += 1
2252
+ if not 0 < slotted <= count:
2253
+ raise ValueError("prediction_layout has invalid answer slots")
2254
+ for _ in range(slotted):
2255
+ if cursor + 2 > len(layout):
2256
+ raise ValueError("prediction_layout is truncated")
2257
+ (index, size) = layout[cursor : cursor + 2]
2258
+ cursor += 2
2259
+ positions = layout[cursor : cursor + size]
2260
+ cursor += size
2261
+ if (
2262
+ not 0 <= index < count
2263
+ or (slot_fields and index <= slot_fields[-1])
2264
+ or size < 1
2265
+ or (len(positions) != size)
2266
+ or any(
2267
+ (
2268
+ not queries[index] - shift < slot < prompt_length
2269
+ for slot in positions
2270
+ )
2271
+ )
2272
+ ):
2273
+ raise ValueError("prediction_layout has invalid answer slots")
2274
+ slot_fields.append(index)
2275
+ answer_slots.append([slot + shift for slot in positions])
2276
+ if cursor != len(layout):
2277
+ raise ValueError("prediction_layout has trailing values")
2278
+ parsed = (input_start + shift, input_length, kinds, queries, items)
2279
+ return (*parsed, slot_fields, answer_slots) if with_slots else parsed
2280
+
2281
+
2282
+ def prediction_views(
2283
+ kinds: list[str], queries: list[int], items: list[list[int]], device: Any = None
2284
+ ) -> dict[str, np.ndarray]:
2285
+ views = {"query_positions": np.array(queries, dtype=np.int64)}
2286
+ for group, members in VIEW_GROUPS:
2287
+ views[f"{group}_rows"] = np.array(
2288
+ [row for (row, kind) in enumerate(kinds) if kind in members],
2289
+ dtype=np.int64,
2290
+ )
2291
+ for kind in LIST_KINDS:
2292
+ rows = [row for (row, field_kind) in enumerate(kinds) if field_kind == kind]
2293
+ views[f"{kind}_rows"] = np.array(rows, dtype=np.int64)
2294
+ views[f"{kind}_items"] = np.array(
2295
+ [slot for row in rows for slot in items[row]],
2296
+ dtype=np.int64,
2297
+ ).reshape(len(rows), LIST_SLOTS)
2298
+ return views
2299
+
2300
+
2301
+ def compact_output(output: dict[str, Any]) -> np.ndarray:
2302
+ parts = [_f32(output["null"]).flatten()]
2303
+ if "text" in output:
2304
+ scores = _f32(output["text"])
2305
+ scores = _flatten1(scores)
2306
+ parts += [
2307
+ scores.argmax(axis=1).astype(np.float32),
2308
+ _softmax(scores, axis=1).max(axis=1),
2309
+ ]
2310
+ if "tags" in output:
2311
+ tag_log = _log_softmax(_f32(output["tags"]), axis=-1)
2312
+ parts.append(tag_log.argmax(axis=-1).astype(np.float32).flatten())
2313
+ parts.append(tag_log.max(axis=-1).sum(axis=-1))
2314
+ if "trim" in output:
2315
+ parts.append(np.asarray(output["trim"]).argmax(axis=-1).astype(np.float32).flatten())
2316
+ if "number_copy" in output:
2317
+ scores = _f32(output["number_copy"])
2318
+ scores = _flatten1(scores)
2319
+ parts += [
2320
+ scores.argmax(axis=1).astype(np.float32),
2321
+ _softmax(scores, axis=1).max(axis=1),
2322
+ ]
2323
+ parts += [_f32(output[key]).flatten() for key in COMPACT_KEYS if key in output]
2324
+ if "slot_ids" in output:
2325
+ parts += [
2326
+ _f32(output["slot_ids"]).flatten(),
2327
+ _f32(output["slot_log_probs"]).flatten(),
2328
+ ]
2329
+ return np.concatenate(parts).astype(np.float32, copy=False)
2330
+
2331
+
2332
+ def expand_output(
2333
+ flat: np.ndarray,
2334
+ record: EncodedRecord,
2335
+ bins: int = BINS,
2336
+ estimate_lexical: bool = False,
2337
+ span_trim: bool = False,
2338
+ number_groups: bool = False,
2339
+ number_pointer: bool = False,
2340
+ ) -> dict[str, Any]:
2341
+ flat = _f32(flat).reshape(-1)
2342
+ kinds = [item.kind for item in record.fields]
2343
+ rows = {
2344
+ group: sum((kind in members for kind in kinds))
2345
+ for (group, members) in VIEW_GROUPS
2346
+ }
2347
+ rows.update({kind: kinds.count(kind) for kind in LIST_KINDS})
2348
+ cursor = 0
2349
+
2350
+ def take(*shape: int) -> np.ndarray:
2351
+ nonlocal cursor
2352
+ size = math.prod(shape)
2353
+ if cursor + size > flat.size:
2354
+ raise ValueError("compact output is shorter than the layout needs")
2355
+ value = flat[cursor : cursor + size].reshape(*shape)
2356
+ cursor += size
2357
+ return value
2358
+
2359
+ output: dict[str, Any] = {"null": take(len(kinds))}
2360
+ if rows["text"]:
2361
+ output["text_best"] = take(rows["text"]).round().astype(np.int64).tolist()
2362
+ output["text_probability"] = take(rows["text"]).tolist()
2363
+ if rows["tags"]:
2364
+ output["tags_labels"] = (
2365
+ take(rows["tags"], len(record.offsets)).round().astype(np.int64).tolist()
2366
+ )
2367
+ output["tags_log_probability"] = take(rows["tags"]).tolist()
2368
+ if span_trim and (rows["text"] or rows["tags"]):
2369
+ output["trim_labels"] = take(len(record.offsets), 2).round().astype(np.int64).tolist()
2370
+ if number_pointer and rows["number"]:
2371
+ output["number_copy_best"] = take(rows["number"]).round().astype(np.int64).tolist()
2372
+ output["number_copy_probability"] = take(rows["number"]).tolist()
2373
+ widths = {
2374
+ "number": (NUMBER_WIDTH,),
2375
+ "date": (DATE_WIDTH,),
2376
+ "time": (TIME_WIDTH,),
2377
+ "estimate": (bins,),
2378
+ "estimate_offset": (bins,),
2379
+ "estimate_overflow": (2,),
2380
+ "number_list_end": (LIST_SLOTS,),
2381
+ "number_list": (LIST_SLOTS, NUMBER_WIDTH),
2382
+ "date_list_end": (LIST_SLOTS,),
2383
+ "date_list": (LIST_SLOTS, DATE_WIDTH),
2384
+ "estimate_number": (NUMBER_WIDTH,),
2385
+ "estimate_gate": (),
2386
+ "number_groups": (NUMBER_GROUPS, GROUP_CLASSES),
2387
+ "number_list_groups": (LIST_SLOTS, NUMBER_GROUPS, GROUP_CLASSES),
2388
+ "number_copy_gate": (),
2389
+ }
2390
+ for key in COMPACT_KEYS:
2391
+ if key in ("estimate_number", "estimate_gate") and (not estimate_lexical):
2392
+ continue
2393
+ if key in ("number_groups", "number_list_groups") and (not number_groups):
2394
+ continue
2395
+ if key == "number_copy_gate" and (not number_pointer):
2396
+ continue
2397
+ count = rows[COMPACT_GROUPS[key]]
2398
+ if count:
2399
+ output[key] = take(count, *widths[key])
2400
+ slotted = [len(item.answer_slots) for item in record.fields if item.answer_slots]
2401
+ if slotted:
2402
+ output["slot_ids"] = take(len(slotted), max(slotted)).round().astype(np.int64)
2403
+ output["slot_log_probs"] = take(len(slotted), max(slotted))
2404
+ if cursor != flat.size:
2405
+ raise ValueError("compact output is longer than the layout needs")
2406
+ return output
2407
+
2408
+
2409
+ def merge_forecasts(
2410
+ predictions: dict[str, dict[str, Any]], groups: dict[str, list[str]]
2411
+ ) -> dict[str, dict[str, Any]]:
2412
+ merged = {
2413
+ name: prediction
2414
+ for (name, prediction) in predictions.items()
2415
+ if not any((name in names for names in groups.values()))
2416
+ }
2417
+ for name, names in groups.items():
2418
+ steps = [predictions[step] for step in names]
2419
+ merged[name] = {
2420
+ key: [step[key] for step in steps]
2421
+ for key in ("value", "median", "p10", "p90")
2422
+ }
2423
+ merged[name]["steps"] = steps
2424
+ return merged
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/processor.py ADDED
@@ -0,0 +1,65 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """A torch-free stand-in for the Transformers `Qwen3VLProcessor` used by the Clairic request pipeline.
2
+
3
+ Not part of the Cloudflare release. The upstream pipeline calls four things on its processor: the chat
4
+ template, `replace_image_token`, `get_text_with_replacements`, and `processor(text=..., images=...)`. This
5
+ class provides exactly those on top of the tokenizer and mlx-vlm's NumPy image processor, so Transformers'
6
+ torchvision-based image and video processors are not needed.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import json
12
+ from pathlib import Path
13
+ from typing import Any
14
+
15
+ import numpy as np
16
+
17
+ MIN_PIXELS = 65_536
18
+
19
+
20
+ class ClairicProcessor:
21
+ image_token = "<|image_pad|>"
22
+
23
+ def __init__(self, path: Path, tokenizer: Any, max_pixels: int) -> None:
24
+ from mlx_vlm.models.qwen3_vl.processing_qwen3_vl import Qwen3VLImageProcessor
25
+
26
+ config = json.loads((path / "preprocessor_config.json").read_text())
27
+ self.tokenizer = tokenizer
28
+ self.image_token_id = tokenizer.convert_tokens_to_ids(self.image_token)
29
+ self.image_processor = Qwen3VLImageProcessor(
30
+ patch_size=config["patch_size"], temporal_patch_size=config["temporal_patch_size"],
31
+ merge_size=config["merge_size"], min_pixels=config["size"].get("shortest_edge", MIN_PIXELS),
32
+ max_pixels=max_pixels, image_mean=config["image_mean"], image_std=config["image_std"])
33
+
34
+ def apply_chat_template(self, messages: list[dict[str, Any]], **kwargs: Any) -> Any:
35
+ return self.tokenizer.apply_chat_template(messages, **kwargs)
36
+
37
+ def replace_image_token(self, image_inputs: dict[str, Any], image_idx: int) -> str:
38
+ merge = self.image_processor.merge_size ** 2
39
+ return self.image_token * (int(np.prod(np.asarray(image_inputs["image_grid_thw"])[image_idx])) // merge)
40
+
41
+ def get_text_with_replacements(self, text: list[str], images_replacements: list[str] = (),
42
+ videos_replacements: list[str] = (), audio_replacements: list[str] = ()) -> tuple[list[str], list]:
43
+ """Replace each image placeholder, in order across the batch, with its expanded run of placeholders."""
44
+ if videos_replacements or audio_replacements:
45
+ raise ValueError("Clairic accepts images only")
46
+ replacements = iter(images_replacements)
47
+ expanded = []
48
+ for sample in text:
49
+ pieces = sample.split(self.image_token)
50
+ if len(images_replacements) == 0:
51
+ expanded.append(sample)
52
+ continue
53
+ expanded.append("".join(piece + (next(replacements) if index < len(pieces) - 1 else "")
54
+ for index, piece in enumerate(pieces)))
55
+ return expanded, []
56
+
57
+ def __call__(self, text: list[str], images: list[Any], return_tensors: str | None = None) -> dict[str, Any]:
58
+ processed = self.image_processor(list(images))
59
+ media = {"pixel_values": np.asarray(processed["pixel_values"], dtype=np.float32),
60
+ "image_grid_thw": np.asarray(processed["image_grid_thw"], dtype=np.int64)}
61
+ expanded, _ = self.get_text_with_replacements(
62
+ list(text), [self.replace_image_token(media, index) for index in range(len(images))])
63
+ ids = np.asarray(self.tokenizer(expanded, add_special_tokens=False)["input_ids"], dtype=np.int64)
64
+ return {"input_ids": ids, "attention_mask": np.ones_like(ids), **media,
65
+ "mm_token_type_ids": (ids == self.image_token_id).astype(np.int64)}
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/row_omission.py ADDED
@@ -0,0 +1,190 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Recover unresolved image rows backed by a completed row inventory."""
2
+
3
+ from copy import deepcopy
4
+ import json
5
+ from typing import Any
6
+
7
+ from . import ar, image_rows
8
+ from .schema import MAX_LIST_ITEMS
9
+
10
+
11
+ def prepare(
12
+ record: dict[str, Any], predictions: dict[str, dict[str, Any]]
13
+ ) -> tuple[dict[str, Any], list[dict[str, Any]]] | None:
14
+ if record.get("_null_recovery") or record.get("_row_omission_recovery"):
15
+ return None
16
+ annotations = (
17
+ record.get("_meta", {}).get("extraction_contract", {}).get("fields", {})
18
+ )
19
+ tasks = {name: (name, ids, media) for name, ids, media in record["_ar_tasks"]}
20
+ if len(tasks) != len(record["_ar_tasks"]):
21
+ return None
22
+ contexts, retry_tasks = [], []
23
+ constraints = dict(record.get("_ar_constraints", {}))
24
+ for parent, annotation in annotations.items():
25
+ queries = annotation.get("image_row_fields")
26
+ spec, inventory = record["fields"].get(parent, {}), predictions.get(parent, {})
27
+ value = inventory.get("value")
28
+ if (
29
+ set(annotation) != {"image_row_fields"}
30
+ or not isinstance(queries, list)
31
+ or len(queries) != len(set(queries))
32
+ or not queries
33
+ or not image_rows.is_inventory(spec)
34
+ or spec.get("knowledge")
35
+ or not inventory.get("valid")
36
+ or not inventory.get("complete")
37
+ or not isinstance(value, list)
38
+ or not value
39
+ or len(value) > min(spec.get("max_items", MAX_LIST_ITEMS), len(queries))
40
+ or any(
41
+ not isinstance(row, dict)
42
+ or set(row) != {"label"}
43
+ or not isinstance(row["label"], str)
44
+ or not row["label"].strip()
45
+ for row in value
46
+ )
47
+ or any(child not in predictions for child in queries)
48
+ ):
49
+ continue
50
+ properties = spec.get("items", {}).get("properties", {})
51
+ text_keys = [
52
+ key
53
+ for key, child in properties.items()
54
+ if child.get("type") == "text" and not child.get("knowledge")
55
+ ]
56
+ if not text_keys:
57
+ continue
58
+ labels = [row["label"] for row in value]
59
+ proposals = [predictions[child] for child in queries]
60
+ selected, conflicts = image_rows._select(labels, proposals, text_keys)
61
+ if not conflicts or any(
62
+ row is not None and (not row.get("valid") or not row.get("complete"))
63
+ for row in selected
64
+ ):
65
+ continue
66
+ children, local_constraints = [], {}
67
+ for index in conflicts:
68
+ child = queries[index]
69
+ row, child_spec = predictions[child], record["fields"].get(child, {})
70
+ row_value = row.get("value")
71
+ task = tasks.get(child)
72
+ native = constraints.get(child, {})
73
+ if (
74
+ annotations.get(child) != {"parent": parent, "index": index + 1}
75
+ or child_spec.get("type") != "object"
76
+ or not child_spec.get("_image_row_proposal")
77
+ or child_spec.get("knowledge")
78
+ or not row.get("valid")
79
+ or not row.get("complete")
80
+ or not isinstance(row_value, dict)
81
+ or not row_value
82
+ or any(cell is not None for cell in row_value.values())
83
+ or any(row is previous for previous in selected if previous is not None)
84
+ or task is None
85
+ or task[2] is None
86
+ or set(native) != {"json_schema"}
87
+ ):
88
+ break
89
+ schema = json.loads(native["json_schema"])
90
+ if schema != ar.schema(child_spec) or not set(text_keys) <= set(
91
+ schema.get("properties", {})
92
+ ):
93
+ break
94
+ # A completed inventory requires a matching textual cell; the
95
+ # original selector remains the acceptance test for that label.
96
+ # Full branches retain required fields with the native grammar compiler.
97
+ branches = []
98
+ for key in text_keys:
99
+ branch = deepcopy(schema)
100
+ branch["properties"][key]["type"] = "string"
101
+ branches.append(branch)
102
+ local_constraints[child] = {"json_schema": json.dumps({"anyOf": branches})}
103
+ children.append(child)
104
+ else:
105
+ constraints.update(local_constraints)
106
+ retry_tasks.extend(tasks[child] for child in children)
107
+ contexts.append(
108
+ {
109
+ "parent": parent,
110
+ "queries": queries,
111
+ "labels": labels,
112
+ "text_keys": text_keys,
113
+ "selected": selected,
114
+ "conflicts": conflicts,
115
+ "children": children,
116
+ }
117
+ )
118
+ if not retry_tasks:
119
+ return None
120
+ repair = {
121
+ **record,
122
+ "_ar_tasks": retry_tasks,
123
+ "_ar_constraints": constraints,
124
+ "_ar_prefix": None,
125
+ "_ar_group_prefixes": [],
126
+ "_ar_media_groups": [],
127
+ "_null_recovery": True,
128
+ "_row_omission_recovery": True,
129
+ }
130
+ return repair, contexts
131
+
132
+
133
+ def merge(
134
+ record: dict[str, Any],
135
+ predictions: dict[str, dict[str, Any]],
136
+ alternatives: dict[str, dict[str, Any]],
137
+ plan: tuple[dict[str, Any], list[dict[str, Any]]],
138
+ ) -> tuple[dict[str, dict[str, Any]], list[dict[str, Any]]]:
139
+ repair, contexts = plan
140
+ lengths = {name: len(ids) for name, ids, _ in repair["_ar_tasks"]}
141
+ result = dict(predictions)
142
+ evidence = []
143
+ for context in contexts:
144
+ candidates = {}
145
+ for child in context["children"]:
146
+ original, alternative = predictions[child], alternatives.get(child, {})
147
+ account = {
148
+ "tokens": original["tokens"] + alternative.get("tokens", 0),
149
+ "retry_input_tokens": original.get("retry_input_tokens", 0)
150
+ + lengths[child],
151
+ }
152
+ result[child] = {**original, **account}
153
+ value = alternative.get("value")
154
+ if (
155
+ alternative.get("valid")
156
+ and alternative.get("complete")
157
+ and isinstance(value, dict)
158
+ and any(cell is not None for cell in value.values())
159
+ ):
160
+ candidates[child] = {
161
+ **alternative,
162
+ **account,
163
+ "image_row_omission_recovered": True,
164
+ }
165
+ trial = {**result, **candidates}
166
+ selected, conflicts = image_rows._select(
167
+ context["labels"],
168
+ [trial[name] for name in context["queries"]],
169
+ context["text_keys"],
170
+ )
171
+ unchanged = all(
172
+ previous is None or selected[index] is previous
173
+ for index, previous in enumerate(context["selected"])
174
+ )
175
+ accepted = (
176
+ not conflicts and unchanged and len(candidates) == len(context["children"])
177
+ )
178
+ if accepted:
179
+ result.update(candidates)
180
+ evidence.append(
181
+ {
182
+ "parent": context["parent"],
183
+ "original_conflicts": context["conflicts"],
184
+ "retry_children": context["children"],
185
+ "conflicts_after_retry": conflicts,
186
+ "previously_matched_proposals_preserved_exactly": unchanged,
187
+ "accepted": accepted,
188
+ }
189
+ )
190
+ return result, evidence
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")