CLEF v04 fixed-data FT checkpoint (JointSchemaHead, epoch 3)

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+tokenizer/tokenizer.json filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,32 @@
+---
+language:
+- en
+license: other
+tags:
+- security
+- prompt-injection
+- litert
+---
+
+# CLEF-Screen-V2
+
+Redo fine-tune of the CLEF-Flash `JointSchemaHead` (121,762,820 parameters,
+122 tensors) on frozen Cloudflare CLEF-Flash LiteRT backbone hidden states.
+Only the head is trained; the backbone is unmodified. This repository root
+is a complete CLEF LiteRT checkpoint directory with the fine-tuned head.
+
+## Training
+
+- Compute: DigitalOcean GPU droplet jev-retrain (AMD MI355X 288GB, gpu-mi355x1-288gb-spot), train+eval 90 min (plus 44 min backbone encode).
+- Method: `ft_clef.py --cache-only (backbone hidden states pre-encoded with pinned PyTorch clef-flash)`, 3 epoch(s), lr 3e-05, batch 16,
+  pos_weight 1.0. Training details and hashes: `redo-provenance.json`;
+  full log: `redo-training-log.jsonl` when present.
+- Head dtype in this repo: BF16 (deployment contract). Trained head was already BF16; no conversion.
+
+## Evaluation status
+
+Run clef_v04 (fixed-data retrain). Training set rebuilt 1:1 balanced: 16,322 rows (8,232 positive / 8,090 negative, SHA-256 e3916d4946cbe6e4787579ba73a82485f1e9ee186c241444586aeafa26e3bb87), replacing the 92%-positive frozen-v0.3 train split (94,864 pos / 8,026 neg); includes +86 mined real-world technique-catalog rows and +184 synthetic tool-spoof rows (labelled synthetic in provenance); pos_weight 1.0 (was 3.0). Frozen dev/test splits unchanged. Epoch 3 selected on dev AUC only (per-epoch dev AUCs 0.9635 / 0.9811 / 0.9840; untrained-head dev baseline 0.7516). Dev (n=21,977; 20,282 pos / 1,695 neg): AUC 0.9840, TPR@0.5 0.939, FPR@0.5 0.050. Frozen test (n=21,965; 20,271 pos / 1,694 neg), evaluated once at end of training: AUC 0.9833, TPR@0.5 0.940, FPR@0.5 0.054. Per-row scores ship in this repo (redo-dev-scores.jsonl, redo-test-scores.jsonl, redo-final-results.json) and reproduce these numbers exactly. Caveats: dev/test are ~92% positive so FPR rests on ~1,700 negatives; this run trains and evaluates the tool_output_filter task only (action_authorization_guard n=0); no adaptive-attack evaluation or independent replication yet. Uploaded on owner direction ahead of the Tuesday-v2 frozen-chain replication gate; see redo-provenance.json.
+
+No frozen-test, adaptive-attack, or independent-replication result exists yet
+for this checkpoint unless stated above. Treat all numbers as development
+measurements, not deployment guarantees.

clef-flash_rowprefill_embeds_L4096_fp16fc.tflite

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:43a638f2976f8bd8e885bdd7d41b1a342bb583c41c81f4528b1379ad4dee823b
+size 13936871792

contract.json

@@ -0,0 +1,789 @@
+{
+ "what": "clef-flash on LiteRT: the contract between the graphs and a host",
+ "model": {
+  "repo": "Cloudflare/clef-flash",
+  "revision": "f0b7d3cd65296abfe459e6c228b618f5d8b26d2f",
+  "joint_schema_model_sha256": "0e304cf7c6500e8bb59bef7e2afd2c6373f82596dfb3b57d1aa93c175e2dc3a3",
+  "hidden_size": 4096,
+  "vocab_rows": 248320,
+  "tie_word_embeddings": "false (embed_tokens and lm_head are two tables)"
+ },
+ "host": {
+  "package": "host/clef_litert",
+  "version": "0.2.0",
+  "requirements": "host/requirements-host.txt (Python 3.14.6, macOS 27.0): numpy, tokenizers, pillow and ai-edge-litert (imported when a graph is compiled); no torch, no transformers",
+  "files_sha256": {
+   "__init__.py": "4bc079245c456d5ef34b21c3cfd6614e367d5173a2fbf95d95a778279d9e80a2",
+   "_erf.py": "cf6a894a8d65d069f64fb4f0f0175d969bd2947c31be89eb0992ab3435a4e66d",
+   "errors.py": "43893807154cfa7822cdaabf2eb8db3650b9ccc615e2b4231f9437f527e94744",
+   "head.py": "7fe0940018882ab7a83b12e78b884e194c332d5a7fcde9a93419f4bdec57f861",
+   "host.py": "b4e39b9f525f2f7fd83ad29c8cb301acfcda3780c4484f577a16fdcd5a50627a",
+   "pixels.py": "d87420187e422ff35299f5028236954fbbe63f6653e0d8a90a2ccfb0a500abf2",
+   "positions.py": "44a86a2843c550fab76d6e9754518e07e1f142ba252ebe6e584825a2870915d4",
+   "request.py": "991a3300bf9240d80b30a886f3d96cb77551840ed53d2af4221a5eaa0e118ab0",
+   "response.py": "5658ca395deef7ee20c68e8244f5b1dd42af7c8021c6a8138acd685d89d91445",
+   "runtime.py": "11ee9dc121b9c224a693d8c9eab244bde5b0bfb4baa10dcd9499167423f8ee7a",
+   "tables.py": "6db98e0069162a8a0d9bbc56111f3676d382b34e0b2a1c4a86794f287fe2a521"
+  },
+  "entry": "ClefLiteRT.from_dir(folder, accelerator='gpu' | 'cpu').decide(request, tile=448 | 256)",
+  "steps": "host/clef_litert/__init__.py docstring 1-6; ClefHost.decide(request, row_graph, tower)"
+ },
+ "folder": {
+  "layout": {
+   "row": "clef-flash_rowprefill_embeds_L{length}_fp16fc.tflite",
+   "tower": "clef-flash_vision_tower_g{tile}_fp16fc.tflite",
+   "tower_pos": "tables/vision_pos_g{tile}.safetensors",
+   "embed_tokens": "tables/embed_tokens.safetensors",
+   "lm_head": "tables/lm_head.safetensors",
+   "joint_head": "head/joint_head.safetensors",
+   "joint_head_config": "head/joint_head_config.json",
+   "tokenizer": "tokenizer/tokenizer.json"
+  },
+  "lengths": [
+   256,
+   512,
+   1024,
+   2048,
+   4096
+  ],
+  "tiles": [
+   256,
+   448
+  ],
+  "rule": "a request runs on the smallest present row graph that holds it; longer than the largest present one = RequestTooLong; one row graph compiled at a time, the towers stay compiled",
+  "accelerators": {
+   "gpu": "HardwareAccelerator.GPU, GpuOptions(enforce_f32=True) (Metal on a Mac)",
+   "cpu": "HardwareAccelerator.CPU, CpuOptions(num_threads=8) (XNNPACK), no weight cache file"
+  },
+  "not_supported": "the GPU's default precision (fp16 storage): the row graphs' norms overflow and the towers' rows are wrong (measured, not shipped)"
+ },
+ "row_graphs": [
+  {
+   "length": 256,
+   "file": "clef-flash_rowprefill_embeds_L256_fp16fc.tflite",
+   "bytes": 13847841008,
+   "sha256": "97d64beb2ec0a57e1e9f17a2c89096f6a44ed8b13c85216b9641d11f0195e6c7",
+   "source": "out/r2/clef_rowprefill_L256_v2_fp16fc.tflite",
+   "inputs": {
+    "embeds": [
+     1,
+     256,
+     4096
+    ],
+    "valid": [
+     1,
+     256
+    ],
+    "cos": [
+     1,
+     256,
+     64
+    ],
+    "sin": [
+     1,
+     256,
+     64
+    ]
+   },
+   "outputs": {
+    "hidden": [
+     1,
+     256,
+     4096
+    ]
+   }
+  },
+  {
+   "length": 512,
+   "file": "clef-flash_rowprefill_embeds_L512_fp16fc.tflite",
+   "bytes": 13850105024,
+   "sha256": "cbff9eab565f921b762875d7e92ff6aadccb4b87b1c1e2c536b48318f130f09e",
+   "source": "out/r2/clef_rowprefill_L512_v2_fp16fc.tflite",
+   "inputs": {
+    "embeds": [
+     1,
+     512,
+     4096
+    ],
+    "valid": [
+     1,
+     512
+    ],
+    "cos": [
+     1,
+     512,
+     64
+    ],
+    "sin": [
+     1,
+     512,
+     64
+    ]
+   },
+   "outputs": {
+    "hidden": [
+     1,
+     512,
+     4096
+    ]
+   }
+  },
+  {
+   "length": 1024,
+   "file": "clef-flash_rowprefill_embeds_L1024_fp16fc.tflite",
+   "bytes": 13856205536,
+   "sha256": "b8eff74efec3b2f3d2b289d62f5a5f66721f0926e88790f791fe8b4170834dc5",
+   "source": "out/r2/clef_rowprefill_L1024_v2_fp16fc.tflite",
+   "inputs": {
+    "embeds": [
+     1,
+     1024,
+     4096
+    ],
+    "valid": [
+     1,
+     1024
+    ],
+    "cos": [
+     1,
+     1024,
+     64
+    ],
+    "sin": [
+     1,
+     1024,
+     64
+    ]
+   },
+   "outputs": {
+    "hidden": [
+     1,
+     1024,
+     4096
+    ]
+   }
+  },
+  {
+   "length": 2048,
+   "file": "clef-flash_rowprefill_embeds_L2048_fp16fc.tflite",
+   "bytes": 13874698016,
+   "sha256": "6ecdbb68d48a9406aaf0c3c9d789c631abe23c605484f9f34746944cb87ff7a3",
+   "source": "out/r2/clef_rowprefill_L2048_v2_fp16fc.tflite",
+   "inputs": {
+    "embeds": [
+     1,
+     2048,
+     4096
+    ],
+    "valid": [
+     1,
+     2048
+    ],
+    "cos": [
+     1,
+     2048,
+     64
+    ],
+    "sin": [
+     1,
+     2048,
+     64
+    ]
+   },
+   "outputs": {
+    "hidden": [
+     1,
+     2048,
+     4096
+    ]
+   }
+  },
+  {
+   "length": 4096,
+   "file": "clef-flash_rowprefill_embeds_L4096_fp16fc.tflite",
+   "bytes": 13936871792,
+   "sha256": "43a638f2976f8bd8e885bdd7d41b1a342bb583c41c81f4528b1379ad4dee823b",
+   "source": "out/r2/clef_rowprefill_L4096_v2_fp16fc.tflite",
+   "inputs": {
+    "embeds": [
+     1,
+     4096,
+     4096
+    ],
+    "valid": [
+     1,
+     4096
+    ],
+    "cos": [
+     1,
+     4096,
+     64
+    ],
+    "sin": [
+     1,
+     4096,
+     64
+    ]
+   },
+   "outputs": {
+    "hidden": [
+     1,
+     4096,
+     4096
+    ]
+   }
+  }
+ ],
+ "tower_graphs": [
+  {
+   "tile": 256,
+   "file": "clef-flash_vision_tower_g256_fp16fc.tflite",
+   "bytes": 907587008,
+   "sha256": "c4272400890fa479b6d51792dd51e5e93cb74291a0fca90f94b38a248e57e994",
+   "source": "out/r3/clef_tower_g256_v2_fp16fc.tflite",
+   "inputs": {
+    "patches": [
+     1,
+     256,
+     1536
+    ],
+    "pos": [
+     1,
+     256,
+     1152
+    ]
+   },
+   "outputs": {
+    "rows": [
+     1,
+     64,
+     4096
+    ]
+   },
+   "position_rows": {
+    "file": "tables/vision_pos_g256.safetensors",
+    "key": "pos",
+    "dtype": "F32",
+    "shape": [
+     256,
+     1152
+    ],
+    "sha256": "ecd2eba829853f233b9f71f05da81c459e0ecb5ba7fbf5f5986bf42857c5efe9",
+    "source": "cache/r3/consts_g256.npz pos_embeds"
+   }
+  },
+  {
+   "tile": 448,
+   "file": "clef-flash_vision_tower_g448_fp16fc.tflite",
+   "bytes": 907891136,
+   "sha256": "f18f8d2eefc7241bcfacf93fee9a8c725c1ad9696c63e215ee5aa5167b2308a6",
+   "source": "out/r3/clef_tower_g448_v2_fp16fc.tflite",
+   "inputs": {
+    "patches": [
+     1,
+     784,
+     1536
+    ],
+    "pos": [
+     1,
+     784,
+     1152
+    ]
+   },
+   "outputs": {
+    "rows": [
+     1,
+     196,
+     4096
+    ]
+   },
+   "position_rows": {
+    "file": "tables/vision_pos_g448.safetensors",
+    "key": "pos",
+    "dtype": "F32",
+    "shape": [
+     784,
+     1152
+    ],
+    "sha256": "65f76c320150de7d3e53c6fa0ff7ffd048079153a8d6e114b6d48141c6f9ae26",
+    "source": "cache/r3/consts_g448.npz pos_embeds"
+   }
+  }
+ ],
+ "files": {
+  "tokenizer/tokenizer.json": {
+   "sha256": "06b9509352d2af50381ab2247e083b80d32d5c0aba91c272ca9ff729b6a0e523",
+   "bytes": 19989325,
+   "source": "the repository's own file, unchanged"
+  },
+  "head/joint_head.safetensors": {
+   "sha256": "19cdcec8c81dc9212be320fff47462ab342fbc1278be4368fb3da71241cf5ba0",
+   "bytes": 243538016,
+   "source": "the repository's own file, unchanged (122 BF16 tensors)"
+  },
+  "head/joint_head_config.json": {
+   "sha256": "77efe959a38b5b17b241543e129e695f3c77465ece55a25985279bd8176279a0",
+   "bytes": 119,
+   "content": {
+    "hidden_size": 4096,
+    "width": 1024,
+    "routing_layers": 2,
+    "layers": 4,
+    "heads": 16,
+    "feedforward": 4096
+   }
+  },
+  "tables/embed_tokens.safetensors": {
+   "sha256": "48586a2af482671b5ca781a761957e296295a7fd0950af241705cb01ad2079fc",
+   "bytes": 2034237544,
+   "key": "embed_tokens.weight",
+   "dtype": "BF16",
+   "shape": [
+    248320,
+    4096
+   ],
+   "metadata": null,
+   "source": {
+    "file": "model-00001-of-00004.safetensors",
+    "key": "model.language_model.embed_tokens.weight",
+    "byte_range": [
+     2034242120,
+     4068479560
+    ],
+    "data_sha256": "d87d444a38822588c6c1ed07dec4404ccd8d526f57d58565cbbbf60acc758afe"
+   },
+   "made_by": "conversion/r5a_tables.py (clef_litert.copy_bf16_tensor): the checkpoint's bytes, new name",
+   "role": "the row graph's embeds: the rows of the ids, widened to float32 by the host"
+  },
+  "tables/lm_head.safetensors": {
+   "sha256": "106ec926c62c1aac2c8ab808833db89012a9132c53f767fa7609ec69e377d4ab",
+   "bytes": 2034237536,
+   "key": "lm_head.weight",
+   "dtype": "BF16",
+   "shape": [
+    248320,
+    4096
+   ],
+   "metadata": null,
+   "source": {
+    "file": "model-00001-of-00004.safetensors",
+    "key": "lm_head.weight",
+    "byte_range": [
+     4680,
+     2034242120
+    ],
+    "data_sha256": "6d6ff4dbf261f833246d32e7c6088f87f4ab40ddb58516d90c931aa6ae61d5e7"
+   },
+   "made_by": "conversion/r5a_tables.py (clef_litert.copy_bf16_tensor): the checkpoint's bytes, new name",
+   "role": "the joint head's lexical vectors: the mean of the rows of each option span's ids"
+  }
+ },
+ "token_ids": {
+  "vision_start": 248053,
+  "vision_end": 248054,
+  "image_pad": 248056,
+  "processor_pad": 248044
+ },
+ "request": {
+  "shape": "SystemOne-compatible request shape: {model: str, state: any JSON, questions: {id: {type, instructions, criteria}}, images: [one picture] (optional)}",
+  "question_types": {
+   "noul": 0,
+   "choice": 1,
+   "score": 2
+  },
+  "checks": "the author's systemone() checks, in order (request.validate_request), then the host's",
+  "refusals": {
+   "MissingModelOrState": "model is not a string or state is absent: 'model and state are required'",
+   "NoQuestions": "questions is not a non-empty object: 'at least one question is required'",
+   "BadQuestionType": "type not noul / choice / score: '<id>: type must be noul, choice, or score'",
+   "EmptyCriteria": "choice or score without criteria: '<id>: criteria must not be empty'",
+   "SchemaTooLong": "prefix + picture + schema + suffix > max_length (16384), encode_record's message",
+   "EmptyRecord": "no ids or no questions, encode_record's message",
+   "UnsupportedMedia": "host only: more than one picture, videos, media_kwargs, an unreadable picture or URL, a tile other than 256 / 448",
+   "RequestTooLong": "host only: more than 4096 tokens (refused, never truncated)",
+   "base": "every refusal is clef_litert.RequestError, a ValueError"
+  }
+ },
+ "ids": {
+  "encode": "tokenizers.Tokenizer.from_file(tokenizer.json).encode(piece, add_special_tokens=False), pieces concatenated (the author's encode_record)",
+  "prefix": "<|im_start|>system\nRead the complete state and schema. Decide every field jointly. Each answer must be exactly one of that field's allowed options.<|im_end|>\n<|im_start|>user\nSTATE:\n",
+  "prefix_ids": 36,
+  "suffix": "\n<|im_end|>\n<|im_start|>assistant\n<think>\n\n</think>\n\nJOINT SCHEMA DECISIONS:",
+  "suffix_ids": 18,
+  "schema_header": "\n\nSCHEMA FIELDS:\n",
+  "question_piece": "\\nFIELD {i}\\nID: {id}\\nTYPE: {type}\\nINSTRUCTION: [render(instructions or id)]\\nALLOWED OPTIONS:\\n + per option 'OPTION {j}: [render({option_id, description})]\\n' + 'END FIELD\\n' ([..] = the spans)",
+  "render": "a string as is, else json.dumps(ensure_ascii=False, separators=(',', ':'), sort_keys=True)",
+  "option_order": "noul (true, false); choice: ids sorted as strings; score: levels 0..n-1",
+  "noul_default_criteria": {
+   "true": "The proposition is true or the answer is yes.",
+   "false": "The proposition is false or the answer is no."
+  },
+  "picture_block": "<|vision_start|> + N x <|image_pad|> + <|vision_end|> + '\\n' right after the prefix (token_offset = the <|vision_start|> index)",
+  "state_cut": "to max_length 16384 exactly as encode_record (the row graphs refuse past 4096 first)",
+  "usage_input_tokens": "len(ids)"
+ },
+ "row_graph": {
+  "signature": "serving_default",
+  "inputs": [
+   {
+    "name": "embeds",
+    "dtype": "float32",
+    "shape": [
+     1,
+     "L",
+     4096
+    ],
+    "meaning": "the bf16 embed_tokens rows of the ids widened to float32; the picture rows at the <|image_pad|> positions; 0 after the record"
+   },
+   {
+    "name": "valid",
+    "dtype": "float32",
+    "shape": [
+     1,
+     "L"
+    ],
+    "meaning": "1 on the record, 0 after it"
+   },
+   {
+    "name": "cos",
+    "dtype": "float32",
+    "shape": [
+     1,
+     "L",
+     64
+    ],
+    "meaning": "M-RoPE cos of the record's position planes (positions.py)"
+   },
+   {
+    "name": "sin",
+    "dtype": "float32",
+    "shape": [
+     1,
+     "L",
+     64
+    ],
+    "meaning": "M-RoPE sin"
+   }
+  ],
+  "outputs": [
+   {
+    "name": "hidden",
+    "dtype": "float32",
+    "shape": [
+     1,
+     "L",
+     4096
+    ],
+    "meaning": "after the final RMSNorm, every position; the host reads rows 0..T-1"
+   }
+  ],
+  "buckets": [
+   256,
+   512,
+   1024,
+   2048,
+   4096
+  ],
+  "bucket_rule": "the smallest L >= T; T > 4096 refused (RequestTooLong)",
+  "padding": "right; embeds 0, valid 0; pad positions continue max + 1, + 2, ... on all three planes",
+  "files": [
+   "clef-flash_rowprefill_embeds_L256_fp16fc.tflite",
+   "clef-flash_rowprefill_embeds_L512_fp16fc.tflite",
+   "clef-flash_rowprefill_embeds_L1024_fp16fc.tflite",
+   "clef-flash_rowprefill_embeds_L2048_fp16fc.tflite",
+   "clef-flash_rowprefill_embeds_L4096_fp16fc.tflite"
+  ]
+ },
+ "positions": {
+  "planes": "text-only (i, i, i); picture of H x W merged tokens at token_offset P: i <= P -> (i, i, i), k-th picture token -> (P+1, P+1 + k // W, P+1 + k % W), i >= P+N+1 -> i - (N - max(H, W))",
+  "rope": {
+   "theta": 10000000.0,
+   "rotary_dim": 64,
+   "mrope_section": [
+    11,
+    11,
+    10
+   ],
+   "interleave": "j % 3 == 1 and j < 33 -> h, j % 3 == 2 and j < 30 -> w, else t",
+   "tables": "angle = float32(inv_freq * pos); cos / sin of cat(angle, angle) in float64, rounded to float32"
+  }
+ },
+ "picture": {
+  "tiles": {
+   "256": {
+    "merged_grid": [
+     8,
+     8
+    ],
+    "picture_tokens": 64,
+    "patches": [
+     256,
+     1536
+    ]
+   },
+   "448": {
+    "merged_grid": [
+     14,
+     14
+    ],
+    "picture_tokens": 196,
+    "patches": [
+     784,
+     1536
+    ]
+   }
+  },
+  "default_tile": 448,
+  "preprocess": "PIL open -> convert('RGB') -> resize((tile, tile), BICUBIC) -> /255 -> (x - 0.5) / 0.5 (float64) -> float32 -> merge-block-major patches (C, T=2, 16, 16)",
+  "tower_graph": "patches [1, 4 G^2, 1536] and the position rows pos [1, 4 G^2, 1152] float32 in -> picture rows [1, G^2, 4096] float32 out (tower_graphs)",
+  "not_read": "the author's native resolution, more than one picture, videos, media_kwargs, URLs"
+ },
+ "head": {
+  "weights": "joint_head.safetensors (BF16 -> float32)",
+  "config": {
+   "hidden_size": 4096,
+   "width": 1024,
+   "routing_layers": 2,
+   "layers": 4,
+   "heads": 16,
+   "feedforward": 4096
+  },
+  "tensors": 122,
+  "parameters": 121762820,
+  "compute": "NumPy float32 (head.py docstring); GELU exact (erf in float64, FreeBSD s_erf.c)",
+  "lexical": "mean of the lm_head.safetensors rows of each option span's ids (not normalized)"
+ },
+ "response": {
+  "probabilities": "per question float32 softmax in NumPy's order (exp(z - max), float32 sum, float32 division), then Python floats",
+  "answer": "the author's systemone_answer (round(x, 4); choice = first maximum in criteria order; score = Python's left-to-right sum of level * p)",
+  "body": {
+   "model": "request.model",
+   "answers": "{question id: answer} in request order",
+   "usage": {
+    "input_tokens": "len(ids)",
+    "output_tokens": 0
+   }
+  }
+ },
+ "status": "the graphs, the host package and the folder of this repository",
+ "checks": {
+  "reference": "the provider's own code (joint_schema_model.py systemone() at the revision above) in float32 on the CPU: 243 runs of fixtures/ (text, and pictures at the 256 / 448 px tiles), fixtures/reference_probs.json",
+  "line": "on every question that is not a near-tie (top-2 margin <= 0.02) the most likely option is the reference's; every probability within 0.02; the mean over runs of each run's mean |dp| <= 0.002",
+  "end_to_end": {
+   "gpu": {
+    "complete": true,
+    "line": {
+     "runs": 243,
+     "argmax_equal_non_near_tie": "545/545",
+     "near_tie": "5/5",
+     "max_abs_dp": 0.0016525983810424805,
+     "mean_of_run_means": 7.334260193875453e-06,
+     "pass": true
+    },
+    "red_arms": "3/3",
+    "pass": true
+   },
+   "cpu": {
+    "complete": true,
+    "line": {
+     "runs": 69,
+     "argmax_equal_non_near_tie": "207/207",
+     "near_tie": "3/3",
+     "max_abs_dp": 0.0016247034072875977,
+     "mean_of_run_means": 1.3047657266541098e-05,
+     "pass": true
+    },
+    "red_arms": "3/3",
+    "pass": true
+   }
+  },
+  "example": {
+   "gpu": true,
+   "cpu": true
+  },
+  "delegation_as_compiled": {
+   "cpu:clef-flash_rowprefill_embeds_L1024_fp16fc.tflite": {
+    "compile_seconds": 82.362,
+    "fully_accelerated": false,
+    "one_partition_all_nodes": false,
+    "replacing": [
+     {
+      "delegated": 18112,
+      "total": 18160,
+      "delegate": "TfLiteXNNPackDelegate",
+      "partitions": 97
+     }
+    ]
+   },
+   "cpu:clef-flash_rowprefill_embeds_L2048_fp16fc.tflite": {
+    "compile_seconds": 94.098,
+    "fully_accelerated": false,
+    "one_partition_all_nodes": false,
+    "replacing": [
+     {
+      "delegated": 31552,
+      "total": 31600,
+      "delegate": "TfLiteXNNPackDelegate",
+      "partitions": 97
+     }
+    ]
+   },
+   "cpu:clef-flash_rowprefill_embeds_L256_fp16fc.tflite": {
+    "compile_seconds": 3.553,
+    "fully_accelerated": false,
+    "one_partition_all_nodes": false,
+    "replacing": [
+     {
+      "delegated": 8056,
+      "total": 8080,
+      "delegate": "TfLiteXNNPackDelegate",
+      "partitions": 49
+     }
+    ]
+   },
+   "cpu:clef-flash_rowprefill_embeds_L4096_fp16fc.tflite": {
+    "compile_seconds": 107.976,
+    "fully_accelerated": false,
+    "one_partition_all_nodes": false,
+    "replacing": [
+     {
+      "delegated": 58432,
+      "total": 58480,
+      "delegate": "TfLiteXNNPackDelegate",
+      "partitions": 97
+     }
+    ]
+   },
+   "cpu:clef-flash_rowprefill_embeds_L512_fp16fc.tflite": {
+    "compile_seconds": 81.079,
+    "fully_accelerated": false,
+    "one_partition_all_nodes": false,
+    "replacing": [
+     {
+      "delegated": 11392,
+      "total": 11440,
+      "delegate": "TfLiteXNNPackDelegate",
+      "partitions": 97
+     }
+    ]
+   },
+   "cpu:clef-flash_vision_tower_g256_fp16fc.tflite": {
+    "compile_seconds": 0.247,
+    "fully_accelerated": true,
+    "one_partition_all_nodes": true,
+    "replacing": [
+     {
+      "delegated": 1940,
+      "total": 1940,
+      "delegate": "TfLiteXNNPackDelegate",
+      "partitions": 1
+     }
+    ]
+   },
+   "cpu:clef-flash_vision_tower_g448_fp16fc.tflite": {
+    "compile_seconds": 0.401,
+    "fully_accelerated": true,
+    "one_partition_all_nodes": true,
+    "replacing": [
+     {
+      "delegated": 1940,
+      "total": 1940,
+      "delegate": "TfLiteXNNPackDelegate",
+      "partitions": 1
+     }
+    ]
+   },
+   "gpu:clef-flash_rowprefill_embeds_L1024_fp16fc.tflite": {
+    "compile_seconds": 138.695,
+    "fully_accelerated": true,
+    "one_partition_all_nodes": true,
+    "replacing": [
+     {
+      "delegated": 18160,
+      "total": 18160,
+      "delegate": "LITERT_METAL",
+      "partitions": 1
+     }
+    ]
+   },
+   "gpu:clef-flash_rowprefill_embeds_L2048_fp16fc.tflite": {
+    "compile_seconds": 146.108,
+    "fully_accelerated": true,
+    "one_partition_all_nodes": true,
+    "replacing": [
+     {
+      "delegated": 31600,
+      "total": 31600,
+      "delegate": "LITERT_METAL",
+      "partitions": 1
+     }
+    ]
+   },
+   "gpu:clef-flash_rowprefill_embeds_L256_fp16fc.tflite": {
+    "compile_seconds": 172.478,
+    "fully_accelerated": true,
+    "one_partition_all_nodes": true,
+    "replacing": [
+     {
+      "delegated": 8080,
+      "total": 8080,
+      "delegate": "LITERT_METAL",
+      "partitions": 1
+     }
+    ]
+   },
+   "gpu:clef-flash_rowprefill_embeds_L4096_fp16fc.tflite": {
+    "compile_seconds": 187.062,
+    "fully_accelerated": true,
+    "one_partition_all_nodes": true,
+    "replacing": [
+     {
+      "delegated": 58480,
+      "total": 58480,
+      "delegate": "LITERT_METAL",
+      "partitions": 1
+     }
+    ]
+   },
+   "gpu:clef-flash_rowprefill_embeds_L512_fp16fc.tflite": {
+    "compile_seconds": 135.683,
+    "fully_accelerated": true,
+    "one_partition_all_nodes": true,
+    "replacing": [
+     {
+      "delegated": 11440,
+      "total": 11440,
+      "delegate": "LITERT_METAL",
+      "partitions": 1
+     }
+    ]
+   },
+   "gpu:clef-flash_vision_tower_g256_fp16fc.tflite": {
+    "compile_seconds": 4.983,
+    "fully_accelerated": true,
+    "one_partition_all_nodes": true,
+    "replacing": [
+     {
+      "delegated": 1940,
+      "total": 1940,
+      "delegate": "LITERT_METAL",
+      "partitions": 1
+     }
+    ]
+   },
+   "gpu:clef-flash_vision_tower_g448_fp16fc.tflite": {
+    "compile_seconds": 4.709,
+    "fully_accelerated": true,
+    "one_partition_all_nodes": true,
+    "replacing": [
+     {
+      "delegated": 1940,
+      "total": 1940,
+      "delegate": "LITERT_METAL",
+      "partitions": 1
+     }
+    ]
+   }
+  }
+ }
+}

head/joint_head.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c7375d6f2044ab67880dcee327283fc6ef16e15055fe2d39354852eb48bb7b2a
+size 243537984

head/joint_head_config.json

@@ -0,0 +1,8 @@
+{
+  "hidden_size": 4096,
+  "width": 1024,
+  "routing_layers": 2,
+  "layers": 4,
+  "heads": 16,
+  "feedforward": 4096
+}

host/clef_litert/__init__.py

@@ -0,0 +1,62 @@
+"""clef-flash on LiteRT: the host in plain Python.
+
+Dependencies: NumPy, `tokenizers` and Pillow, and ai-edge-litert for the graphs (requirements-host.txt; the
+safetensors format is read here, the `safetensors` library only checks the table files). No PyTorch, no transformers
+and none of the provider's code at run time. The host answers a request of the SystemOne-compatible request shape the way
+the checkpoint's own `systemone()` does (Cloudflare/clef-flash at f0b7d3cd, joint_schema_model.py sha256 0e304cf7...),
+around two kinds of LiteRT graph that are the caller's: a row graph per length (the Qwen3.5-9B text stack, embeds in,
+final-norm hidden states out) and a tower graph per picture tile. The vocabulary tables and the joint schema head stay
+on the host.
+
+1. Request: {"model": str, "state": any JSON value, "questions": {id: {"type": "noul" | "choice" | "score",
+   "instructions": ..., "criteria": ...}}, "images": [one picture] (optional)}. Choice criteria are an object
+   {option id: description}, score criteria a list of level descriptions (lowest first), noul criteria an optional
+   object overriding the "true" / "false" descriptions. Checked as `systemone()` checks it (request.validate_request;
+   the named refusals of errors.py carry the author's messages).
+2. Ids (request.encode_record): the author's encode_record on the repository's tokenizer.json, every piece tokenized
+   on its own without special tokens; with a picture, its block (<|vision_start|>, N x <|image_pad|>, <|vision_end|>,
+   "\\n") right after the 36-id prefix. usage.input_tokens = the number of ids.
+3. Picture (pixels.py): one per request, read at a fixed square tile, 448 (default, 14 x 14 = 196 picture tokens) or
+   256 (8 x 8 = 64): RGB, Pillow BICUBIC to the tile, (x/255 - 0.5) / 0.5, merge-block-major patches [4 G^2, 1536]
+   -> the tower graph of that tile -> [G^2, 4096] picture rows. More pictures, videos and media_kwargs are refused
+   (`UnsupportedMedia`); the author's native resolution is not a tower graph.
+4. Row graph inputs (host.ClefHost.row_inputs, at L = the smallest of 256 / 512 / 1024 / 2048 / 4096 that holds the
+   record; longer records are refused, `RequestTooLong`, never cut):
+       embeds float32 [1, L, 4096]  the bf16 embed_tokens rows of the ids widened to float32, the picture rows at the
+                                    <|image_pad|> positions, zeros after the record
+       valid  float32 [1, L]        1 on the record, 0 after it
+       cos    float32 [1, L, 64]    the M-RoPE tables of the record's three position planes (positions.py)
+       sin    float32 [1, L, 64]
+   -> hidden float32 [1, L, 4096] (every position, after the final RMSNorm); the host reads the first T rows.
+5. Head (head.py): the author's JointSchemaHead in NumPy float32 on those T rows, the ids, the spans and the bf16
+   lm_head rows of the option spans -> one logit per option.
+6. Response (response.py): per question the float32 softmax, then the author's systemone_answer ->
+   {"model", "answers": {id: answer}, "usage": {"input_tokens", "output_tokens": 0}}.
+
+Files: tokenizer.json (the repository's, sha256 06b95093...), embed_tokens.safetensors and lm_head.safetensors (one BF16
+[248320, 4096] tensor each, the checkpoint's bytes, no metadata), joint_head.safetensors and joint_head_config.json
+(the checkpoint's own). contract.json next to this package records names, shapes, files and checks.
+
+The graphs (runtime.py, ai-edge-litert's CompiledModel; imported only when a graph is compiled):
+    with ClefLiteRT.from_dir("<folder>", accelerator="gpu") as clef:     # "gpu" = float32 precision, "cpu" = XNNPACK
+        body = clef.decide(request, tile=448)"""
+from .errors import (BadQuestionType, EmptyCriteria, EmptyRecord, MissingModelOrState, NoQuestions, RequestError,
+                     RequestTooLong, SchemaTooLong, UnsupportedMedia)
+from .head import JointHead
+from .host import FILES, HIDDEN, ClefHost, Encoded
+from .pixels import TILES, tile_patches
+from .positions import BUCKETS, mrope_tables, padded_positions, pick_length, record_positions
+from .request import EncodedQuestion, EncodedRecord, encode_record, question_options, render, validate_request
+from .response import question_probs, response, systemone_answer
+from .runtime import FOLDER, ClefGraphs, ClefLiteRT, LiteRTGraph, load_f32_tensor
+from .tables import Bf16Table, copy_bf16_tensor, load_bf16_tensors
+
+__version__ = "0.2.0"
+__all__ = [
+    "BUCKETS", "FILES", "FOLDER", "HIDDEN", "TILES", "BadQuestionType", "Bf16Table", "ClefGraphs", "ClefHost",
+    "ClefLiteRT", "EmptyCriteria", "EmptyRecord", "Encoded", "EncodedQuestion", "EncodedRecord", "JointHead",
+    "LiteRTGraph", "MissingModelOrState", "NoQuestions", "RequestError", "RequestTooLong", "SchemaTooLong",
+    "UnsupportedMedia", "copy_bf16_tensor", "encode_record", "load_bf16_tensors", "load_f32_tensor", "mrope_tables",
+    "padded_positions", "pick_length", "question_options", "question_probs", "record_positions", "render", "response",
+    "systemone_answer", "tile_patches", "validate_request",
+]

host/clef_litert/_erf.py

@@ -0,0 +1,95 @@
+"""erf in float64 over NumPy arrays (NumPy has none): FreeBSD msun s_erf.c as ported by musl and Rust `libm`,
+vectorized region by region. Used by the head's GELU (the author's torch.nn.GELU / F.gelu, the exact erf form).
+
+ * ====================================================
+ * Copyright (C) 1993 by Sun Microsystems, Inc. All rights reserved.
+ *
+ * Developed at SunPro, a Sun Microsystems, Inc. business.
+ * Permission to use, copy, modify, and distribute this
+ * software is freely granted, provided that this notice
+ * is preserved.
+ * ===================================================="""
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+ERX = 8.45062911510467529297e-01
+EFX8 = 1.02703333676410069053e+00
+PP = (1.28379167095512558561e-01, -3.25042107247001499370e-01, -2.84817495755985104766e-02,
+      -5.77027029648944159157e-03, -2.37630166566501626084e-05)
+QQ = (3.97917223959155352819e-01, 6.50222499887672944485e-02, 5.08130628187576562776e-03,
+      1.32494738004321644526e-04, -3.96022827877536812320e-06)
+PA = (-2.36211856075265944077e-03, 4.14856118683748331666e-01, -3.72207876035701323847e-01,
+      3.18346619901161753674e-01, -1.10894694282396677476e-01, 3.54783043256182359371e-02,
+      -2.16637559486879084300e-03)
+QA = (1.06420880400844228286e-01, 5.40397917702171048937e-01, 7.18286544141962662868e-02,
+      1.26171219808761642112e-01, 1.36370839120290507362e-02, 1.19844998467991074170e-02)
+RA = (-9.86494403484714822705e-03, -6.93858572707181764372e-01, -1.05586262253232909814e+01,
+      -6.23753324503260060396e+01, -1.62396669462573470355e+02, -1.84605092906711035994e+02,
+      -8.12874355063065934246e+01, -9.81432934416914548592e+00)
+SA = (1.96512716674392571292e+01, 1.37657754143519042600e+02, 4.34565877475229228821e+02,
+      6.45387271733267880336e+02, 4.29008140027567833386e+02, 1.08635005541779435134e+02,
+      6.57024977031928170135e+00, -6.04244152148580987438e-02)
+RB = (-9.86494292470009928597e-03, -7.99283237680523006574e-01, -1.77579549177547519889e+01,
+      -1.60636384855821916062e+02, -6.37566443368389627722e+02, -1.02509513161107724954e+03,
+      -4.83519191608651397019e+02)
+SB = (3.03380607434824582924e+01, 3.25792512996573918826e+02, 1.53672958608443695994e+03,
+      3.19985821950859553908e+03, 2.55305040643316442583e+03, 4.74528541206955367215e+02,
+      -2.24409524465858183362e+01)
+SQRT1_2 = math.sqrt(0.5)
+
+
+def _poly(z, c):
+    """c[0] + z * (c[1] + z * (... + z * c[-1])), Horner from the last coefficient (the C source's nesting)."""
+    r = np.full_like(z, c[-1])
+    for a in c[-2::-1]:
+        r = a + z * r
+    return r
+
+
+def _one_plus_z_poly(z, c):
+    """1 + z * (c[0] + z * (c[1] + ...)) (the denominators Q / S)."""
+    return 1.0 + z * _poly(z, c)
+
+
+def erf(x) -> np.ndarray:
+    """Elementwise erf of a float64 array (NaN -> NaN, +-inf -> +-1)."""
+    x = np.asarray(x, dtype=np.float64)
+    out = np.empty_like(x)
+    ax = np.abs(x)
+    hi = (ax.view(np.uint64) >> np.uint64(32)).astype(np.uint32)       # high word of |x|
+    sign = np.signbit(x)
+
+    m = hi < 0x3e300000                                                 # |x| < 2**-28
+    out[m] = 0.125 * (8.0 * x[m] + EFX8 * x[m])
+    m = (hi >= 0x3e300000) & (hi < 0x3feb0000)                          # |x| < 0.84375
+    xm = x[m]
+    z = xm * xm
+    out[m] = xm + xm * (_poly(z, PP) / _one_plus_z_poly(z, QQ))
+    m = (hi >= 0x3feb0000) & (hi < 0x3ff40000)                          # 0.84375 <= |x| < 1.25
+    s = ax[m] - 1.0
+    erfc1 = 1.0 - ERX - _poly(s, PA) / _one_plus_z_poly(s, QA)
+    out[m] = np.where(sign[m], -(1.0 - erfc1), 1.0 - erfc1)
+    m = (hi >= 0x3ff40000) & (hi < 0x40180000)                          # 1.25 <= |x| < 6
+    if m.any():
+        a = ax[m]
+        h = hi[m]
+        s = 1.0 / (a * a)
+        near = h < 0x4006db6d                                           # |x| < 1 / 0.35
+        r = np.where(near, _poly(s, RA), _poly(s, RB))
+        big_s = np.where(near, _one_plus_z_poly(s, SA), _one_plus_z_poly(s, SB))
+        zz = (a.view(np.uint64) & np.uint64(0xFFFFFFFF00000000)).view(np.float64)   # low word cleared
+        erfc2 = np.exp(-zz * zz - 0.5625) * np.exp((zz - a) * (zz + a) + r / big_s) / a
+        out[m] = np.where(sign[m], -(1.0 - erfc2), 1.0 - erfc2)
+    m = hi >= 0x40180000                                                # |x| >= 6, inf, NaN
+    y = 1.0 - math.ldexp(1.0, -1022)
+    out[m] = np.where(np.isnan(x[m]), np.nan, np.where(sign[m], -y, y))
+    return out
+
+
+def gelu(x: np.ndarray) -> np.ndarray:
+    """GELU, the exact form x / 2 * (1 + erf(x / sqrt 2)), evaluated in float64 and rounded to x's float32."""
+    xd = np.asarray(x, dtype=np.float64)
+    return (0.5 * xd * (1.0 + erf(xd * SQRT1_2))).astype(np.float32)

host/clef_litert/errors.py

@@ -0,0 +1,44 @@
+"""Named refusals of the clef-flash host.
+
+Every refusal is a `RequestError`, itself a `ValueError`: code that catches the ValueError the checkpoint's own
+`systemone()` raises catches these too, and the first six carry the author's message word for word. The last two are
+the host's own: it reads one picture at a fixed tile and runs row graphs of at most 4,096 tokens."""
+from __future__ import annotations
+
+
+class RequestError(ValueError):
+    """The request cannot be answered as given."""
+
+
+class MissingModelOrState(RequestError):
+    """`model` is not a string or `state` is absent ("model and state are required")."""
+
+
+class NoQuestions(RequestError):
+    """`questions` is not a non-empty object ("at least one question is required")."""
+
+
+class BadQuestionType(RequestError):
+    """A question's `type` is not noul, choice or score ("<id>: type must be noul, choice, or score")."""
+
+
+class EmptyCriteria(RequestError):
+    """A choice or score question without criteria ("<id>: criteria must not be empty")."""
+
+
+class SchemaTooLong(RequestError):
+    """The prefix, picture, schema and suffix alone exceed max_length (encode_record: "schema requires N tokens
+    before state; maximum is M")."""
+
+
+class EmptyRecord(RequestError):
+    """The record gives no ids or no questions (encode_record: "record produced no model input or questions")."""
+
+
+class UnsupportedMedia(RequestError):
+    """Host only: more than one picture, `videos`, `media_kwargs`, a picture the host cannot open, or a tile other
+    than 256 / 448 (the two tower graphs)."""
+
+
+class RequestTooLong(RequestError):
+    """Host only: the record is longer than the largest row graph (4,096 tokens). It is refused, never truncated."""

host/clef_litert/head.py

@@ -0,0 +1,231 @@
+"""The checkpoint's joint schema head (joint_schema_model.py `JointSchemaHead.forward`, one record) in NumPy float32.
+
+Weights: joint_head.safetensors (bfloat16, 122 tensors, widened to float32 exactly; `load_state_dict(strict=True)` names)
+and joint_head_config.json {hidden_size 4096, width 1024, routing_layers 2, layers 4, heads 16, feedforward 4096}.
+Inputs: the row graph's hidden states at the record's T real positions (after the final RMSNorm), the record's ids
+(processor form) and spans, and the lm_head table (`lm_head.weight` rows, for the lexical vectors).
+
+    x        = hidden_norm(hidden)                          LayerNorm(4096); memory = memory_projection(x) [T, 1024]
+    global   = x[T - 1];  q_i = mean of x over question i's span;  ctx_o = mean of x over option o's span
+    lexical_o = mean of the lm_head rows of option o's span ids              (not normalized)
+    queries_o = option_context_projection(ctx_o) + option_lexical_projection(lexical_o)
+                + option_question_projection(q_i)                               i = the question of option o
+    2 x evidence routing: queries += MHA(query_norm(queries), memory_norm(memory)); queries += FFN(feedforward_norm(.))
+                          (pre-LN, 16 heads of 64, FFN = Linear 1024->4096, GELU, Linear 4096->1024)
+    per question: w = softmax over its options of routed . question_projection(q_i) / 32;  summary_i = sum w * routed
+    fields   = question_projection(q) + option_summary_norm(summary) + global_projection(global) + type_embedding(type)
+    4 x TransformerDecoderLayer (norm_first, GELU): self-attention over the questions, cross-attention to the memory
+              (not normalized), FFN;  fields = field_norm(fields)
+    prior_o  = e^min(prior_logit_scale, ln 100) * cos(lexical_o, q_i + global)
+    joint_o  = e^min(joint_logit_scale, ln 100) * cos(field_i, option_norm(routed_o)) + residual_scorer([f, o, f*o, |f-o|])
+    logit_o  = prior_o + sigmoid(residual_gate) * joint_o
+
+Every tensor is float32 as in the author's float32 module; LayerNorm eps 1e-5; attention = softmax(q k^T / 8) v per
+head in float32; GELU = the exact erf form (evaluated in float64, rounded to float32); F.normalize eps 1e-12 and
+F.cosine_similarity eps 1e-8 (each side divided by max(norm, eps), then the dot product, as torch computes it).
+Dropout is the identity (eval). The per-question softmax of the logits is the response's (response.py)."""
+from __future__ import annotations
+
+import json
+import math
+from pathlib import Path
+
+import numpy as np
+
+from ._erf import gelu
+from .tables import load_bf16_tensors
+
+CONFIG = {"hidden_size": 4096, "width": 1024, "routing_layers": 2, "layers": 4, "heads": 16, "feedforward": 4096}
+LN_EPS = 1e-5
+F32 = np.float32
+
+
+def layer_norm(x: np.ndarray, w: np.ndarray, b: np.ndarray, eps: float = LN_EPS) -> np.ndarray:
+    mean = x.mean(axis=-1, keepdims=True, dtype=F32)
+    xc = x - mean
+    var = (xc * xc).mean(axis=-1, keepdims=True, dtype=F32)
+    return (xc * (F32(1.0) / np.sqrt(var + F32(eps)))) * w + b
+
+
+def normalize(x: np.ndarray, eps: float) -> np.ndarray:
+    """x / max(||x||_2, eps) over the last axis (F.normalize)."""
+    n = np.sqrt((x * x).sum(axis=-1, keepdims=True, dtype=F32))
+    return x / np.maximum(n, F32(eps))
+
+
+def softmax(x: np.ndarray, axis: int = -1) -> np.ndarray:
+    e = np.exp(x - x.max(axis=axis, keepdims=True))
+    return e / e.sum(axis=axis, keepdims=True, dtype=F32)
+
+
+class _Linear:
+    def __init__(self, w: np.ndarray, b: np.ndarray | None = None):
+        self.wt = np.ascontiguousarray(w.T, dtype=F32)        # [in, out]
+        self.b = None if b is None else np.ascontiguousarray(b, dtype=F32)
+
+    def __call__(self, x: np.ndarray) -> np.ndarray:
+        y = x @ self.wt
+        return y if self.b is None else y + self.b
+
+
+class _LayerNorm:
+    def __init__(self, w: np.ndarray, b: np.ndarray):
+        self.w, self.b = w.astype(F32), b.astype(F32)
+
+    def __call__(self, x: np.ndarray) -> np.ndarray:
+        return layer_norm(x, self.w, self.b)
+
+
+class _Attention:
+    """nn.MultiheadAttention (batch_first, eval, no masks) for one sequence: q_in [Lq, E], kv_in [Lk, E] -> [Lq, E]."""
+
+    def __init__(self, t: dict, prefix: str, heads: int):
+        w, b = t[prefix + "in_proj_weight"], t[prefix + "in_proj_bias"]
+        e = w.shape[1]
+        self.q = _Linear(w[:e], b[:e])
+        self.k = _Linear(w[e:2 * e], b[e:2 * e])
+        self.v = _Linear(w[2 * e:], b[2 * e:])
+        self.out = _Linear(t[prefix + "out_proj.weight"], t[prefix + "out_proj.bias"])
+        self.heads, self.dim = heads, e // heads
+        self.scale = F32(1.0 / math.sqrt(self.dim))
+
+    def __call__(self, q_in: np.ndarray, kv_in: np.ndarray) -> np.ndarray:
+        h, d = self.heads, self.dim
+        q = self.q(q_in).reshape(q_in.shape[0], h, d).transpose(1, 0, 2)          # [H, Lq, D]
+        k = self.k(kv_in).reshape(kv_in.shape[0], h, d).transpose(1, 0, 2)        # [H, Lk, D]
+        v = self.v(kv_in).reshape(kv_in.shape[0], h, d).transpose(1, 0, 2)
+        p = softmax((q @ k.transpose(0, 2, 1)) * self.scale)                     # [H, Lq, Lk]
+        o = (p @ v).transpose(1, 0, 2).reshape(q_in.shape[0], h * d)
+        return self.out(o)
+
+
+class _Tracked(dict):
+    """The weights by name, recording which names were read (load_state_dict(strict=True): none missing, none unused)."""
+
+    def __init__(self, *a):
+        super().__init__(*a)
+        self.read = set()
+
+    def __getitem__(self, key):
+        self.read.add(key)
+        return super().__getitem__(key)
+
+
+class JointHead:
+    """The author's JointSchemaHead for one record. `scores(hidden, ids, questions, lm_head)` -> one float32 logit
+    array per question, in the author's option order."""
+
+    def __init__(self, tensors: dict[str, np.ndarray], config: dict | None = None):
+        cfg = dict(CONFIG if config is None else config)
+        if cfg != CONFIG:
+            raise ValueError(f"head config {cfg} is not the release's {CONFIG}")
+        self.config = cfg
+        t = _Tracked({k: np.asarray(v, dtype=F32) for k, v in tensors.items()})
+        heads = cfg["heads"]
+        ln = lambda p: _LayerNorm(t[p + ".weight"], t[p + ".bias"])                # noqa: E731
+        lin = lambda p, bias=True: _Linear(t[p + ".weight"], t[p + ".bias"] if bias else None)  # noqa: E731
+        self.hidden_norm = ln("hidden_norm")
+        self.memory_projection = lin("memory_projection", False)
+        self.question_projection = lin("question_projection", False)
+        self.option_question_projection = lin("option_question_projection", False)
+        self.global_projection = lin("global_projection", False)
+        self.option_context_projection = lin("option_context_projection", False)
+        self.option_lexical_projection = lin("option_lexical_projection", False)
+        self.type_embedding = t["type_embedding.weight"]
+        self.evidence = [{"query_norm": ln(f"evidence_layers.{i}.query_norm"),
+                          "memory_norm": ln(f"evidence_layers.{i}.memory_norm"),
+                          "attention": _Attention(t, f"evidence_layers.{i}.attention.", heads),
+                          "feedforward_norm": ln(f"evidence_layers.{i}.feedforward_norm"),
+                          "ff0": lin(f"evidence_layers.{i}.feedforward.0"),
+                          "ff3": lin(f"evidence_layers.{i}.feedforward.3")}
+                         for i in range(cfg["routing_layers"])]
+        self.option_summary_norm = ln("option_summary_norm")
+        self.layers = [{"norm1": ln(f"layers.{i}.norm1"), "norm2": ln(f"layers.{i}.norm2"),
+                        "norm3": ln(f"layers.{i}.norm3"),
+                        "self_attn": _Attention(t, f"layers.{i}.self_attn.", heads),
+                        "multihead_attn": _Attention(t, f"layers.{i}.multihead_attn.", heads),
+                        "linear1": lin(f"layers.{i}.linear1"), "linear2": lin(f"layers.{i}.linear2")}
+                       for i in range(cfg["layers"])]
+        self.field_norm = ln("field_norm")
+        self.option_norm = ln("option_norm")
+        self.scorer0 = lin("residual_scorer.0")
+        self.scorer3 = lin("residual_scorer.3")
+        cap = F32(math.log(100.0))
+        self.prior_scale = np.exp(np.minimum(t["prior_logit_scale"].reshape(()), cap)).astype(F32)
+        self.joint_scale = np.exp(np.minimum(t["joint_logit_scale"].reshape(()), cap)).astype(F32)
+        g = t["residual_gate"].reshape(())
+        self.gate = (F32(1.0) / (F32(1.0) + np.exp(-g))).astype(F32)
+        unused = set(t) - t.read                     # a missing name already raised KeyError when it was read
+        if unused:
+            raise ValueError(f"head weights not used: {sorted(unused)}")
+        self.n_tensors = len(t)
+        self.n_params = int(sum(v.size for v in dict.values(t)))
+
+    @classmethod
+    def from_files(cls, weights: str | Path, config: str | Path | None = None) -> "JointHead":
+        cfg = json.loads(Path(config).read_text()) if config is not None else None
+        return cls(load_bf16_tensors(weights), cfg)
+
+    @staticmethod
+    def lexical_rows(lm_head, ids, questions) -> list[np.ndarray]:
+        """Per question, [n_options, 4096]: the mean of the lm_head rows of each option span's ids (float32)."""
+        ids = np.asarray(ids, dtype=np.int64)
+        out = []
+        for q in questions:
+            rows = [lm_head.rows(ids[a:b]).mean(axis=0, dtype=F32) for a, b in q.option_spans]
+            out.append(np.stack(rows).astype(F32))
+        return out
+
+    def scores(self, hidden: np.ndarray, ids, questions, lm_head=None, lexical: list | None = None) -> list[np.ndarray]:
+        """hidden [T, 4096] (the record's real positions), ids (len T), questions (request.EncodedQuestion or
+        anything with question_span / option_spans / type_id) -> [float32 logits per question].
+        `lexical` (one [n_options, 4096] array per question) replaces the lm_head gather (controls)."""
+        hidden = np.asarray(hidden, dtype=F32)
+        if hidden.ndim != 2 or hidden.shape[0] != len(ids):
+            raise ValueError(f"hidden {hidden.shape} for {len(ids)} ids")
+        if lexical is None:
+            lexical = self.lexical_rows(lm_head, ids, questions)
+        x = self.hidden_norm(hidden)                                            # [T, 4096]
+        memory = self.memory_projection(x)                                      # [T, 1024]
+        global_vector = x[-1]
+        question_vectors = np.stack([x[a:b].mean(axis=0, dtype=F32) for a, b in (q.question_span for q in questions)])
+        type_rows = self.type_embedding[[q.type_id for q in questions]]
+        counts = [len(q.option_spans) for q in questions]
+        context = [np.stack([x[a:b].mean(axis=0, dtype=F32) for a, b in q.option_spans]) for q in questions]
+
+        queries = np.concatenate([
+            self.option_context_projection(ctx) + self.option_lexical_projection(lex)
+            + self.option_question_projection(question_vectors[i])[None]
+            for i, (ctx, lex) in enumerate(zip(context, lexical))])             # [O, 1024]
+        for layer in self.evidence:
+            routed = layer["attention"](layer["query_norm"](queries), layer["memory_norm"](memory))
+            queries = queries + routed
+            queries = queries + layer["ff3"](gelu(layer["ff0"](layer["feedforward_norm"](queries))))
+        split = np.split(queries, np.cumsum(counts)[:-1])
+
+        base = self.question_projection(question_vectors)                       # [Q, 1024]
+        summaries = []
+        for field, options in zip(base, split):
+            w = softmax((options @ field) / F32(math.sqrt(options.shape[-1])), axis=0)
+            summaries.append((w[:, None] * options).sum(axis=0, dtype=F32))
+        fields = (base + self.option_summary_norm(np.stack(summaries)) + self.global_projection(global_vector)[None]
+                  + type_rows)
+        for layer in self.layers:
+            f1 = layer["norm1"](fields)
+            fields = fields + layer["self_attn"](f1, f1)
+            fields = fields + layer["multihead_attn"](layer["norm2"](fields), memory)
+            fields = fields + layer["linear2"](gelu(layer["linear1"](layer["norm3"](fields))))
+        fields = self.field_norm(fields)
+
+        out = []
+        for i, (field, lex, routed) in enumerate(zip(fields, lexical, split)):
+            anchor = normalize(question_vectors[i] + global_vector, 1e-12)
+            prior = self.prior_scale * (normalize(lex, 1e-12) @ anchor)
+            options = self.option_norm(routed)
+            f = np.broadcast_to(field, options.shape)
+            cosine = (normalize(f, 1e-8) * normalize(options, 1e-8)).sum(axis=-1, dtype=F32)
+            features = np.concatenate([f, options, f * options, np.abs(f - options)], axis=-1)
+            residual = self.scorer3(gelu(self.scorer0(features)))[:, 0]
+            joint = self.joint_scale * cosine + residual
+            out.append((prior + self.gate * joint).astype(F32))
+        return out

host/clef_litert/host.py

@@ -0,0 +1,134 @@
+"""ClefHost: one request through the host steps around the graphs (the graphs themselves are the caller's callables).
+
+    host = ClefHost.from_dir("<folder>")       # tokenizer.json, embed_tokens.safetensors, lm_head.safetensors,
+                                               # joint_head.safetensors, joint_head_config.json
+    enc = host.encode(request, tile=448)       # checks, ids, spans, bucket L; a picture -> enc.patches
+    rows = tower(enc.tile, enc.patches)        # the tower graph: [G^2, 4096] picture rows (requests with a picture)
+    x = host.row_inputs(enc, rows)             # {"embeds", "valid", "cos", "sin"} at length enc.length
+    hidden = row_graph(enc.length, x)          # the row graph of that length: [1, L, 4096] after the final norm
+    logits = host.scores(enc, hidden)          # the joint head, NumPy float32: one array per question
+    body = host.respond(request, enc, logits)  # the SystemOne-compatible response
+
+or `host.decide(request, row_graph, tower)` for all of it. Refusals: errors.py (the author's ValueError conditions
+by name, plus the host's own: one picture at a 256 / 448 tile, at most 4,096 tokens)."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+
+import numpy as np
+
+from .errors import UnsupportedMedia
+from .head import JointHead
+from .pixels import tile_grid, tile_patches
+from .positions import BUCKETS, mrope_tables, padded_positions, pick_length, record_positions
+from .request import MAX_LENGTH, EncodedRecord, encode_record, validate_request
+from .response import question_probs, response
+from .tables import Bf16Table
+
+HIDDEN = 4096
+FILES = {"tokenizer": "tokenizer.json", "embed_tokens": "embed_tokens.safetensors", "lm_head": "lm_head.safetensors",
+         "joint_head": "joint_head.safetensors", "joint_head_config": "joint_head_config.json"}
+
+
+@dataclass(frozen=True)
+class Encoded:
+    record: EncodedRecord
+    length: int                          # the row graph length: the smallest bucket >= record.tokens
+    tile: int | None = None              # 256 | 448 for a request with a picture
+    patches: np.ndarray | None = None    # the tower graph's input [4 G^2, 1536] float32
+
+
+def media_of(request: dict) -> list:
+    """The request's one picture as a list ([] or [picture]); UnsupportedMedia for what the host does not read."""
+    if request.get("videos"):
+        raise UnsupportedMedia("videos are not read by this host")
+    if request.get("media_kwargs"):
+        raise UnsupportedMedia("media_kwargs are not read by this host (one picture at a fixed tile)")
+    images = list(request.get("images") or [])
+    if len(images) > 1:
+        raise UnsupportedMedia(f"{len(images)} pictures: this host reads one picture per request")
+    return images
+
+
+class ClefHost:
+    def __init__(self, tokenizer, embed_tokens: Bf16Table, lm_head: Bf16Table, head: JointHead,
+                 buckets=BUCKETS, max_length: int = MAX_LENGTH):
+        if embed_tokens.shape[1] != HIDDEN or lm_head.shape[1] != HIDDEN:
+            raise ValueError(f"tables {embed_tokens.shape} / {lm_head.shape}: expected [V, {HIDDEN}]")
+        self.tokenizer, self.embed_tokens, self.lm_head, self.head = tokenizer, embed_tokens, lm_head, head
+        self.buckets, self.max_length = tuple(sorted(buckets)), max_length
+
+    @classmethod
+    def from_files(cls, tokenizer: str | Path, embed_tokens: str | Path, lm_head: str | Path, joint_head: str | Path,
+                   joint_head_config: str | Path, **kw) -> "ClefHost":
+        from tokenizers import Tokenizer
+
+        return cls(Tokenizer.from_file(str(tokenizer)), Bf16Table(embed_tokens), Bf16Table(lm_head),
+                   JointHead.from_files(joint_head, joint_head_config), **kw)
+
+    @classmethod
+    def from_dir(cls, folder: str | Path, **kw) -> "ClefHost":
+        folder = Path(folder)
+        return cls.from_files(**{k: folder / v for k, v in FILES.items()}, **kw)
+
+    def encode(self, request: dict, tile: int = 448) -> Encoded:
+        """The author's checks, the host's media checks, encode_record, the bucket (RequestTooLong past 4,096)."""
+        validate_request(request)
+        images = media_of(request)
+        grid = None
+        if images:
+            g = tile_grid(tile)
+            grid = (g, g)
+        record = encode_record(self.tokenizer, request, max_length=self.max_length, image_grid=grid)
+        length = pick_length(record.tokens, self.buckets)
+        if not images:
+            return Encoded(record, length)
+        return Encoded(record, length, tile, tile_patches(images[0], tile))
+
+    def row_inputs(self, enc: Encoded, image_rows: np.ndarray | None = None) -> dict[str, np.ndarray]:
+        """The row graph's inputs at enc.length: embeds = the float32 rows of the bf16 table at the ids, the picture's
+        rows (the tower's output, [H * W, 4096]) at the <|image_pad|> positions; valid = 1 on the record; the pad
+        positions after it: embeds 0, valid 0; cos / sin of the record's planes (positions.py)."""
+        rec, length = enc.record, enc.length
+        t = rec.tokens
+        embeds = np.zeros((1, length, HIDDEN), np.float32)
+        embeds[0, :t] = self.embed_tokens.rows(rec.ids)
+        if rec.image_grid is not None:
+            h, w = rec.image_grid
+            if image_rows is None:
+                raise ValueError("a request with a picture needs the tower's rows")
+            image_rows = np.asarray(image_rows, dtype=np.float32)
+            if image_rows.shape != (h * w, HIDDEN):
+                raise ValueError(f"picture rows {image_rows.shape}, expected {(h * w, HIDDEN)}")
+            p = rec.token_offset
+            embeds[0, p + 1:p + 1 + h * w] = image_rows
+        elif image_rows is not None:
+            raise ValueError("picture rows for a request without a picture")
+        valid = np.zeros((1, length), np.float32)
+        valid[0, :t] = 1.0
+        cos, sin = mrope_tables(padded_positions(record_positions(t, rec.token_offset, rec.image_grid), length))
+        return {"embeds": embeds, "valid": valid, "cos": cos, "sin": sin}
+
+    def scores(self, enc: Encoded, hidden: np.ndarray, lexical: list | None = None) -> list[np.ndarray]:
+        """The row graph's hidden ([1, L, 4096] or [T, 4096]) -> the head's logits, one float32 array per question."""
+        hidden = np.asarray(hidden, dtype=np.float32)
+        if hidden.ndim == 3:
+            hidden = hidden[0]
+        t = enc.record.tokens
+        return self.head.scores(hidden[:t], enc.record.ids, enc.record.questions, self.lm_head, lexical=lexical)
+
+    def respond(self, request: dict, enc: Encoded, logits: list[np.ndarray]) -> dict:
+        return response(request, enc.record.questions, [question_probs(z) for z in logits], enc.record.tokens)
+
+    def decide(self, request: dict, row_graph: Callable[[int, dict], np.ndarray],
+               tower: Callable[[int, np.ndarray], np.ndarray] | None = None, tile: int = 448) -> dict:
+        enc = self.encode(request, tile=tile)
+        rows = None
+        if enc.patches is not None:
+            if tower is None:
+                raise UnsupportedMedia("a request with a picture needs a tower")
+            rows = tower(enc.tile, enc.patches)
+        hidden = row_graph(enc.length, self.row_inputs(enc, rows))
+        return self.respond(request, enc, self.scores(enc, hidden))

host/clef_litert/pixels.py

@@ -0,0 +1,80 @@
+"""Picture -> the tower graph's patches, at one fixed square tile per tower graph (256 -> 8 x 8 = 64 picture tokens,
+448 -> 14 x 14 = 196).
+
+    open -> convert("RGB") -> resize((tile, tile), BICUBIC)        Pillow's own integer resampler; the aspect is NOT kept
+    -> /255 -> (x - 0.5) / 0.5 in float64 -> float32
+    -> merge-block-major patches [4 G^2, 1536], G = tile // 32, each vector (C, T=2, 16, 16)
+
+This is what the reference's g256 / g448 arms fed the author's processor (the picture resized with Pillow before the
+processor, whose own resize is the identity at multiples of 32), and the patches are the processor's `pixel_values`
+bit for bit. The author's native arm (the processor's dynamic resolution) is not a tower graph here. EXIF orientation
+is not applied (the reference passed opened PIL images, which the processor takes as they are)."""
+from __future__ import annotations
+
+import base64
+import io
+from pathlib import Path
+
+import numpy as np
+
+from .errors import UnsupportedMedia
+
+PATCH, MERGE, TEMPORAL = 16, 2, 2
+IMAGE_MEAN, IMAGE_STD = 0.5, 0.5
+TILES = (256, 448)
+
+
+def tile_grid(tile: int) -> int:
+    """Merged rows per side of a square tile (256 -> 8, 448 -> 14)."""
+    if tile not in TILES:
+        raise UnsupportedMedia(f"tile {tile}: the tower graphs read {' or '.join(map(str, TILES))} px tiles")
+    return tile // (PATCH * MERGE)
+
+
+def open_image(image):
+    """A PIL image, a uint8 [H, W, 3] array, the bytes of an image file, a local path, or a base64 data URI -> PIL."""
+    from PIL import Image
+
+    if isinstance(image, Image.Image):
+        return image
+    if isinstance(image, np.ndarray):
+        return Image.fromarray(np.asarray(image, dtype=np.uint8))
+    try:
+        if isinstance(image, (bytes, bytearray)):
+            return Image.open(io.BytesIO(bytes(image)))
+        if isinstance(image, str) and image.startswith("data:image/"):
+            return Image.open(io.BytesIO(base64.b64decode(image.split(",", 1)[1])))
+        if isinstance(image, (str, Path)) and Path(image).is_file():
+            return Image.open(image)
+    except Exception as e:                          # Pillow's UnidentifiedImageError, a bad base64 string, ...
+        raise UnsupportedMedia(f"the picture could not be opened: {e}") from e
+    raise UnsupportedMedia("a picture is a PIL image, a uint8 array, image file bytes, a local path or a data URI "
+                           "(the host does not fetch URLs)")
+
+
+def patchify(x: np.ndarray) -> np.ndarray:
+    """Normalized [H, W, C] -> [gh*gw, C*T*P*P] in Qwen's merge-block-major order: patches iterate
+    (block_row, block_col, y-in-block, x-in-block), channel outermost inside the vector, the still frame repeated at
+    both temporal slots (the Qwen2VLImageProcessor reshape / permute)."""
+    h, w, c = x.shape
+    if h % (PATCH * MERGE) or w % (PATCH * MERGE):
+        raise ValueError(f"{h}x{w} is not divisible by patch * merge = {PATCH * MERGE}")
+    gh, gw = h // PATCH, w // PATCH
+    t = x.transpose(2, 0, 1).reshape(c, gh // MERGE, MERGE, PATCH, gw // MERGE, MERGE, PATCH)
+    t = t.transpose(1, 4, 2, 5, 0, 3, 6).reshape(gh * gw, 1, c, PATCH, PATCH)
+    t = np.broadcast_to(t[:, :, :, None], (gh * gw, 1, c, TEMPORAL, PATCH, PATCH))
+    return t.reshape(gh * gw, c * TEMPORAL * PATCH * PATCH)
+
+
+def tile_pixels(image, tile: int) -> np.ndarray:
+    """Picture -> uint8 [tile, tile, 3]: RGB, Pillow BICUBIC to the tile."""
+    from PIL import Image
+
+    tile_grid(tile)
+    return np.asarray(open_image(image).convert("RGB").resize((tile, tile), Image.Resampling.BICUBIC))
+
+
+def tile_patches(image, tile: int) -> np.ndarray:
+    """Picture -> patches [4 G^2, 1536] float32, G = tile // 32 (the tower graph's input)."""
+    x = (tile_pixels(image, tile).astype(np.float64) / 255.0 - IMAGE_MEAN) / IMAGE_STD
+    return np.ascontiguousarray(patchify(x).astype(np.float32))

host/clef_litert/positions.py

@@ -0,0 +1,96 @@
+"""Row lengths and positions: the bucket of a record, its three M-RoPE position planes and the cos / sin tables the row
+graph takes as inputs (the graph holds no COS / SIN / position table of its own).
+
+Buckets: one row graph per length L in BUCKETS; a record of T tokens runs on the smallest L >= T, right-padded. A
+record longer than the largest graph is refused (`RequestTooLong`), never truncated.
+
+Position planes [3, T] (t, h, w) of the author's model (transformers Qwen3_5Model.get_rope_index; closed form recorded
+with the reference, P = token_offset = the <|vision_start|> index, one picture of H x W merged tokens, N = H * W):
+    text-only record: (i, i, i)
+    i <= P -> (i, i, i);  picture token k at P+1+k -> (P+1, P+1 + k // W, P+1 + k % W);
+    i >= P+N+1 -> i - (N - max(H, W)) on all three planes
+Pad positions (right of the record) continue the planes' maximum + 1, + 2, ... on all three planes; their outputs are
+never read and the graph's `valid` mask hides them as keys.
+
+cos / sin (the author's Qwen3_5TextRotaryEmbedding: default rope, theta 1e7, rotary dim 64 of the 256-wide heads,
+attention scaling 1, interleaved mrope_section [11, 11, 10]):
+    inv_freq[j] = 1 / theta^(2j / 64)                    j = 0..31, every step in float32 as the author's code
+    angle[p][i, j] = float32(inv_freq[j] * pos[p][i])    p = t, h, w
+    interleave: j % 3 == 1 and j < 33 -> h plane, j % 3 == 2 and j < 30 -> w plane, every other j -> t plane
+    cos = cos(cat(angle, angle)), sin = sin(cat(angle, angle))      float32 [1, L, 64]
+The cosine and sine are taken in float64 on the float32 angle and rounded to float32 (torch's float32 cos / sin sit
+within 1 ulp of these)."""
+from __future__ import annotations
+
+import numpy as np
+
+from .errors import RequestTooLong
+
+BUCKETS = (256, 512, 1024, 2048, 4096)
+ROTARY_DIM = 64
+ROPE_THETA = 10000000.0
+MROPE_SECTION = (11, 11, 10)
+
+
+def pick_length(tokens: int, buckets=BUCKETS) -> int:
+    """The smallest row graph length that holds `tokens`; RequestTooLong past the largest."""
+    for length in sorted(buckets):
+        if tokens <= length:
+            return length
+    raise RequestTooLong(f"the record has {tokens} tokens; the largest row graph holds {max(buckets)}")
+
+
+def text_positions(tokens: int) -> np.ndarray:
+    """[3, T] int64 planes of a record without a picture: (i, i, i)."""
+    return np.broadcast_to(np.arange(tokens, dtype=np.int64), (3, tokens)).copy()
+
+
+def image_positions(tokens: int, token_offset: int, h: int, w: int) -> np.ndarray:
+    """[3, T] int64 planes of a record with one picture of h x w merged tokens right after the prefix."""
+    p, n = int(token_offset), int(h) * int(w)
+    if not p + 1 + n < tokens:
+        raise ValueError(f"a picture of {n} tokens at {p} does not fit a record of {tokens} tokens")
+    pos = text_positions(tokens)
+    k = np.arange(n, dtype=np.int64)
+    pos[0, p + 1:p + 1 + n] = p + 1
+    pos[1, p + 1:p + 1 + n] = p + 1 + k // w
+    pos[2, p + 1:p + 1 + n] = p + 1 + k % w
+    pos[:, p + n + 1:] = np.arange(p + n + 1, tokens, dtype=np.int64) - (n - max(h, w))
+    return pos
+
+
+def record_positions(tokens: int, token_offset: int | None = None, image_grid=None) -> np.ndarray:
+    """[3, T] planes of a record (text-only when `image_grid` is None)."""
+    if image_grid is None:
+        return text_positions(tokens)
+    return image_positions(tokens, token_offset, *image_grid)
+
+
+def padded_positions(pos3: np.ndarray, length: int) -> np.ndarray:
+    """[3, L]: the record's planes, then maximum + 1, + 2, ... on all three planes for the pad positions."""
+    n = pos3.shape[1]
+    if n > length:
+        raise ValueError(f"{n} positions do not fit length {length}")
+    out = np.empty((3, length), dtype=np.int64)
+    out[:, :n] = pos3
+    out[:, n:] = int(pos3.max()) + 1 + np.arange(length - n, dtype=np.int64)[None, :]
+    return out
+
+
+def inv_freq(theta: float = ROPE_THETA, rotary_dim: int = ROTARY_DIM) -> np.ndarray:
+    """float32 [rotary_dim / 2] = 1 / theta^(arange(0, dim, 2) / dim), every step in float32."""
+    expo = np.arange(0, rotary_dim, 2, dtype=np.float32) / np.float32(rotary_dim)
+    return (np.float32(1.0) / np.power(np.float32(theta), expo, dtype=np.float32)).astype(np.float32)
+
+
+def mrope_tables(pos3: np.ndarray, freq: np.ndarray | None = None,
+                 section: tuple[int, int, int] = MROPE_SECTION) -> tuple[np.ndarray, np.ndarray]:
+    """[3, L] position planes -> cos, sin float32 [1, L, 2 * len(freq)]."""
+    freq = inv_freq() if freq is None else freq
+    ang = (pos3.astype(np.float32)[:, :, None] * freq[None, None, :]).astype(np.float32)        # [3, L, d/2]
+    a = ang[0].copy()
+    for plane, offset in ((1, 1), (2, 2)):
+        stop = section[plane] * 3
+        a[:, offset:stop:3] = ang[plane][:, offset:stop:3]
+    emb = np.concatenate([a, a], axis=-1).astype(np.float64)
+    return np.cos(emb).astype(np.float32)[None], np.sin(emb).astype(np.float32)[None]

host/clef_litert/request.py

@@ -0,0 +1,175 @@
+"""Request -> ids and spans: the checks of the checkpoint's own `systemone()` and its `encode_record()`
+(joint_schema_model.py at Cloudflare/clef-flash f0b7d3cd, sha256 0e304cf7...), written out on a `tokenizers.Tokenizer`
+built from the repository's own tokenizer.json (sha256 06b95093...).
+
+Each piece is tokenized on its own without special tokens and the pieces are concatenated (the author's `_tokens`):
+
+    prefix   "<|im_start|>system\\n{SYSTEM_PROMPT}<|im_end|>\\n<|im_start|>user\\nSTATE:\\n"                    36 ids
+    [image]  "<|vision_start|>" + N x "<|image_pad|>" + "<|vision_end|>\\n"                                 N + 3 ids
+    state    render(state): a string as is, anything else compact JSON (sorted keys, ensure_ascii off)
+    schema   "\\n\\nSCHEMA FIELDS:\\n", then per question
+             "\\nFIELD {i}\\nID: {id}\\nTYPE: {type}\\nINSTRUCTION: " + [render(instructions or id)]
+             + "\\nALLOWED OPTIONS:\\n" + per option "OPTION {j}: " + [render({"option_id", "description"})] + "\\n",
+             and "END FIELD\\n"                                         [..] = the head's spans, [start, end)
+    suffix   "\\n<|im_end|>\\n<|im_start|>assistant\\n<think>\\n\\n</think>\\n\\nJOINT SCHEMA DECISIONS:"         18 ids
+
+Option order (the head scores options in this order): noul = (true, false), the author's default descriptions
+overridable by `criteria`; choice = option ids sorted as strings; score = levels 0..n-1. The image block (one picture,
+N = H x W merged tokens) sits right after the prefix, where the processor's media ids go; its index is the
+`token_offset`. The state is cut to fit `max_length` (the author's 16384) exactly as encode_record cuts it; the row
+graphs' own limit (4,096) is the host's check (host.py), never a cut.
+
+Malformed requests: the author's ValueError conditions raise the named subclasses of errors.py with the author's
+messages; anything the author's code would stop on otherwise (a question that is not an object, choice criteria that
+are not an object, unsortable state keys) stops here the same way (AttributeError, TypeError, ...)."""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from .errors import BadQuestionType, EmptyCriteria, EmptyRecord, MissingModelOrState, NoQuestions, SchemaTooLong
+
+SYSTEM_PROMPT = (
+    "Read the complete state and schema. Decide every field jointly. Each answer "
+    "must be exactly one of that field's allowed options."
+)
+PREFIX = f"<|im_start|>system\n{SYSTEM_PROMPT}<|im_end|>\n<|im_start|>user\nSTATE:\n"
+SUFFIX = "\n<|im_end|>\n<|im_start|>assistant\n<think>\n\n</think>\n\nJOINT SCHEMA DECISIONS:"
+SCHEMA_HEADER = "\n\nSCHEMA FIELDS:\n"
+QUESTION_TYPES = {"noul": 0, "choice": 1, "score": 2}
+NOUL_CRITERIA = {
+    "true": "The proposition is true or the answer is yes.",
+    "false": "The proposition is false or the answer is no.",
+}
+MAX_LENGTH = 16384                    # encode_record / systemone default
+VISION_START, VISION_END, IMAGE_PAD = 248053, 248054, 248056
+PAD_ID = 248044                       # <|endoftext|>, the processor's pad (never written into a row: pads are zeros)
+
+
+def render(value: Any) -> str:
+    """A string as is; anything else compact JSON (the author's `render`)."""
+    if isinstance(value, str):
+        return value
+    return json.dumps(value, ensure_ascii=False, separators=(",", ":"), sort_keys=True)
+
+
+def question_options(question: dict) -> list[tuple[str, Any]]:
+    """(option id, description) in the order the head scores them (the author's `question_options`)."""
+    question_type = str(question["type"])
+    if question_type == "noul":
+        criteria = dict(NOUL_CRITERIA)
+        criteria.update(question.get("criteria") or {})
+        return [(key, criteria[key]) for key in ("true", "false")]
+    if question_type == "choice":
+        return sorted((str(key), value) for key, value in question["criteria"].items())
+    return [(str(index), value) for index, value in enumerate(question["criteria"])]
+
+
+def validate_request(request: dict) -> None:
+    """The checks `systemone()` makes before it encodes, in its order and with its messages."""
+    questions = request.get("questions")
+    if not isinstance(request.get("model"), str) or "state" not in request:
+        raise MissingModelOrState("model and state are required")
+    if not isinstance(questions, dict) or not questions:
+        raise NoQuestions("at least one question is required")
+    for question_id, question in questions.items():
+        if question.get("type") not in QUESTION_TYPES:
+            raise BadQuestionType(f"{question_id}: type must be noul, choice, or score")
+        if question["type"] != "noul" and not question.get("criteria"):
+            raise EmptyCriteria(f"{question_id}: criteria must not be empty")
+
+
+def tokens(tok, text: str) -> list[int]:
+    """`text` -> ids without special tokens (`tokenizers.Tokenizer`)."""
+    return list(tok.encode(text, add_special_tokens=False).ids)
+
+
+def image_block(tok, n: int) -> list[int]:
+    """The processor's media ids of one picture of n merged tokens: <|vision_start|>, n pads, <|vision_end|>, "\\n"."""
+    ids = tokens(tok, "<|vision_start|>" + "<|image_pad|>" * n + "<|vision_end|>\n")
+    if not (ids[:1] == [VISION_START] and ids[1:n + 1] == [IMAGE_PAD] * n and ids[n + 1:n + 2] == [VISION_END]
+            and len(ids) == n + 3):
+        raise ValueError("the tokenizer does not keep the image placeholder tokens whole")
+    return ids
+
+
+@dataclass(frozen=True)
+class EncodedQuestion:
+    question_id: str
+    type: str                                   # noul | choice | score
+    type_id: int                                # 0 | 1 | 2 (the head's type embedding)
+    question_span: tuple[int, int]              # [start, end) in ids
+    option_spans: tuple[tuple[int, int], ...]
+    option_ids: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class EncodedRecord:
+    ids: tuple[int, ...]                        # the processor-form ids (N x <|image_pad|> for a picture)
+    questions: tuple[EncodedQuestion, ...]
+    token_offset: int | None = None             # index of <|vision_start|> (= len(prefix)), None without a picture
+    image_grid: tuple[int, int] | None = None   # merged (H, W) of the picture, None without one
+
+    @property
+    def tokens(self) -> int:
+        return len(self.ids)
+
+
+def encode_record(tok, record: dict, max_length: int = MAX_LENGTH, max_state_tokens: int | None = None,
+                  image_grid: tuple[int, int] | None = None) -> EncodedRecord:
+    """The author's encode_record. `image_grid` = the merged (H, W) of one picture (its block goes right after the
+    prefix), None for a record without one."""
+    schema_ids = tokens(tok, SCHEMA_HEADER)
+    questions = []
+    for question_index, (question_id, question) in enumerate(record["questions"].items()):
+        schema_ids += tokens(tok, f"\nFIELD {question_index + 1}\nID: {question_id}\nTYPE: {question['type']}"
+                                  f"\nINSTRUCTION: ")
+        question_start = len(schema_ids)
+        instructions = question.get("instructions")
+        if instructions is None or instructions == "":
+            instructions = str(question_id)
+        schema_ids += tokens(tok, render(instructions))
+        question_end = len(schema_ids)
+        schema_ids += tokens(tok, "\nALLOWED OPTIONS:\n")
+        option_spans, option_ids = [], []
+        for option_index, (option_id, description) in enumerate(question_options(question)):
+            schema_ids += tokens(tok, f"OPTION {option_index + 1}: ")
+            option_start = len(schema_ids)
+            semantics = {"option_id": option_id}
+            if description is not None:
+                semantics["description"] = description
+            schema_ids += tokens(tok, render(semantics))
+            option_spans.append((option_start, len(schema_ids)))
+            option_ids.append(option_id)
+            schema_ids += tokens(tok, "\n")
+        schema_ids += tokens(tok, "END FIELD\n")
+        questions.append((str(question_id), str(question["type"]), QUESTION_TYPES[str(question["type"])],
+                          (question_start, question_end), tuple(option_spans), tuple(option_ids)))
+
+    prefix_ids = tokens(tok, PREFIX)
+    suffix_ids = tokens(tok, SUFFIX)
+    token_offset = None
+    if image_grid is not None:
+        h, w = (int(v) for v in image_grid)
+        token_offset = len(prefix_ids)
+        prefix_ids = prefix_ids + image_block(tok, h * w)
+        image_grid = (h, w)
+    state_ids = tokens(tok, render(record["state"]))
+    if max_state_tokens is not None:
+        state_ids = state_ids[:max_state_tokens]
+    fixed_length = len(prefix_ids) + len(schema_ids) + len(suffix_ids)
+    if fixed_length > max_length:
+        raise SchemaTooLong(f"schema requires {fixed_length} tokens before state; maximum is {max_length}")
+    state_ids = state_ids[: max_length - fixed_length]
+    shift = len(prefix_ids) + len(state_ids)
+    shifted = tuple(
+        EncodedQuestion(question_id=qid, type=qtype, type_id=type_id,
+                        question_span=(span[0] + shift, span[1] + shift),
+                        option_spans=tuple((a + shift, b + shift) for a, b in option_spans),
+                        option_ids=option_ids)
+        for qid, qtype, type_id, span, option_spans, option_ids in questions)
+    ids = tuple(prefix_ids + state_ids + schema_ids + suffix_ids)
+    if not ids or not shifted:
+        raise EmptyRecord("record produced no model input or questions")
+    return EncodedRecord(ids=ids, questions=shifted, token_offset=token_offset, image_grid=image_grid)

host/clef_litert/response.py

@@ -0,0 +1,56 @@
+"""Head logits -> the SystemOne-compatible response body, as the checkpoint's own `systemone()` builds it.
+
+Probabilities: per question, the float32 softmax of its option logits, in NumPy's order (exp of z - max z, a float32
+sum, a float32 division); the author's `question_logits.float().softmax(-1)` is the same computation in torch. They
+enter Python as floats (`.tolist()`), as in the author's code, and `systemone_answer` is the author's function:
+
+    noul    {"type": "noul", "noul": round(p(true), 4)}
+    choice  {"type": "choice", "choice": the most probable option in the request's criteria order (first on a tie),
+             "confidence": round(p(choice), 4), "probabilities": {option: round(p, 4)} in the criteria order}
+    score   {"type": "score", "score": round(sum(level * p(level)), 4) (Python's left-to-right sum),
+             "confidence": round(max p, 4), "legend": {level: criterion}, "probabilities": {level: round(p, 4)}}
+
+Body: {"model": request["model"], "answers": {question id: answer} in the request's order,
+       "usage": {"input_tokens": the record's tokens, "output_tokens": 0}}."""
+from __future__ import annotations
+
+import numpy as np
+
+
+def question_probs(logits) -> np.ndarray:
+    """float32 softmax over one question's option logits."""
+    z = np.asarray(logits, dtype=np.float32)
+    e = np.exp(z - z.max())
+    return e / e.sum(dtype=np.float32)
+
+
+def systemone_answer(question: dict, probabilities: dict) -> dict:
+    """Per-option probabilities of one question -> its SystemOne answer (the author's function)."""
+    if question["type"] == "noul":
+        return {"type": "noul", "noul": round(probabilities["true"], 4)}
+    if question["type"] == "choice":
+        options = [str(option) for option in question["criteria"]]
+        choice = max(options, key=probabilities.__getitem__)
+        return {
+            "type": "choice",
+            "choice": choice,
+            "confidence": round(probabilities[choice], 4),
+            "probabilities": {option: round(probabilities[option], 4) for option in options},
+        }
+    levels = [str(index) for index in range(len(question["criteria"]))]
+    return {
+        "type": "score",
+        "score": round(sum(index * probabilities[level] for index, level in enumerate(levels)), 4),
+        "confidence": round(max(probabilities[level] for level in levels), 4),
+        "legend": dict(zip(levels, question["criteria"])),
+        "probabilities": {level: round(probabilities[level], 4) for level in levels},
+    }
+
+
+def response(request: dict, questions, probs, input_tokens: int) -> dict:
+    """The response body from the encoded questions (request.EncodedQuestion) and their float32 probabilities."""
+    answers = {q.question_id: systemone_answer(request["questions"][q.question_id],
+                                               dict(zip(q.option_ids, np.asarray(p, np.float32).tolist())))
+               for q, p in zip(questions, probs)}
+    return {"model": request["model"], "answers": answers,
+            "usage": {"input_tokens": int(input_tokens), "output_tokens": 0}}

host/clef_litert/runtime.py

@@ -0,0 +1,273 @@
+"""The LiteRT graphs of a clef-flash folder on ai-edge-litert's CompiledModel, and the host around them.
+
+    with ClefLiteRT.from_dir("<folder>", accelerator="gpu") as clef:     # "gpu" = float32 precision, "cpu" = XNNPACK
+        body = clef.decide(request, tile=448)                           # the SystemOne-compatible response
+
+Folder layout (FOLDER below; every path relative to the folder):
+    clef-flash_rowprefill_embeds_L{256,512,1024,2048,4096}_fp16fc.tflite   row graphs: embeds, valid, cos, sin -> hidden
+    clef-flash_vision_tower_g{256,448}_fp16fc.tflite                        tower + merger: patches, pos -> rows
+    tables/vision_pos_g{256,448}.safetensors                                the towers' position rows (float32, key "pos")
+    tables/embed_tokens.safetensors, tables/lm_head.safetensors             the bf16 vocabulary tables
+    head/joint_head.safetensors, head/joint_head_config.json                the checkpoint's joint schema head
+    tokenizer/tokenizer.json                                                the checkpoint's tokenizer
+
+Only the row graphs present are used: a request runs on the smallest present length that holds it, and a request
+longer than the largest present one is refused (RequestTooLong), never cut. Graphs are compiled when a request first
+needs them. One row graph stays compiled at a time (its fp16 weights are about 13.9 GB; on a Mac GPU at float32
+precision a compiled row graph held about 37 GB): a request of another length closes it and compiles the next one.
+The towers (about 0.9 GB each) stay compiled once used.
+
+Accelerators: "gpu" = HardwareAccelerator.GPU with GpuOptions(enforce_f32=True) (Metal on a Mac; the graphs are
+checked at float32 precision only: at the default precision (fp16 storage) the row graphs' norms overflow and the
+towers' rows are wrong); "cpu" = HardwareAccelerator.CPU with CpuOptions(num_threads=threads) (XNNPACK; no weight
+cache file is written). No other runtime option is set."""
+from __future__ import annotations
+
+import json
+import struct
+from pathlib import Path
+
+import numpy as np
+
+from .head import JointHead
+from .host import HIDDEN, ClefHost
+from .pixels import TILES, tile_grid
+from .positions import BUCKETS
+from .tables import Bf16Table, read_header
+
+SIGNATURE = "serving_default"
+ACCELERATORS = ("gpu", "cpu")
+FOLDER = {
+    "row": "clef-flash_rowprefill_embeds_L{length}_fp16fc.tflite",
+    "tower": "clef-flash_vision_tower_g{tile}_fp16fc.tflite",
+    "tower_pos": "tables/vision_pos_g{tile}.safetensors",
+    "embed_tokens": "tables/embed_tokens.safetensors",
+    "lm_head": "tables/lm_head.safetensors",
+    "joint_head": "head/joint_head.safetensors",
+    "joint_head_config": "head/joint_head_config.json",
+    "tokenizer": "tokenizer/tokenizer.json",
+}
+ROW_INPUTS = ("embeds", "valid", "cos", "sin")
+TOWER_INPUTS = ("patches", "pos")
+
+
+def load_f32_tensor(path: str | Path, key: str | None = None) -> np.ndarray:
+    """One float32 tensor of a safetensors file (the towers' position rows), read without a tensor framework."""
+    header, data_start = read_header(path)
+    names = [k for k in header if k != "__metadata__"]
+    if key is None:
+        if len(names) != 1:
+            raise ValueError(f"{Path(path).name} holds {len(names)} tensors; name the key")
+        key = names[0]
+    e = header[key]
+    if e["dtype"] != "F32":
+        raise ValueError(f"{key}: dtype {e['dtype']}, expected F32")
+    start, end = e["data_offsets"]
+    n = int(np.prod(e["shape"], dtype=np.int64))
+    if end - start != 4 * n:
+        raise ValueError(f"{key}: {end - start} bytes for {n} F32 values")
+    with open(path, "rb") as f:
+        f.seek(data_start + start)
+        data = f.read(end - start)
+    return np.frombuffer(data, dtype="<f4").reshape(e["shape"]).astype(np.float32)
+
+
+def write_f32_tensor(path: str | Path, key: str, array: np.ndarray) -> dict:
+    """A one-key safetensors file of a float32 array, header without __metadata__ (padded with spaces to 8 bytes, as the
+    safetensors writer pads). Refuses to overwrite."""
+    path = Path(path)
+    if path.exists():
+        raise FileExistsError(f"refusing to overwrite {path}")
+    a = np.ascontiguousarray(array, dtype="<f4")
+    hdr = json.dumps({key: {"dtype": "F32", "shape": list(a.shape), "data_offsets": [0, a.nbytes]}},
+                     separators=(",", ":")).encode()
+    hdr += b" " * (-len(hdr) % 8)
+    tmp = path.with_name(path.name + ".part")
+    with open(tmp, "wb") as f:
+        f.write(struct.pack("<Q", len(hdr)) + hdr)
+        f.write(a.tobytes())
+    tmp.rename(path)
+    return {"file": path.name, "key": key, "dtype": "F32", "shape": list(a.shape), "bytes": path.stat().st_size}
+
+
+def compile_options(accelerator: str, threads: int = 8):
+    """-> (CompiledModel options, a plain description of them)."""
+    from ai_edge_litert.compiled_model import CpuOptions, GpuOptions, HardwareAccelerator, Options
+
+    if accelerator == "cpu":
+        cpu = CpuOptions(num_threads=threads)
+        return (Options(hardware_accelerators=HardwareAccelerator.CPU, cpu_options=cpu),
+                {"accelerator": "cpu", "backend": "CPU (XNNPACK)", "num_threads": threads})
+    if accelerator == "gpu":
+        gpu = GpuOptions(enforce_f32=True)
+        return (Options(hardware_accelerators=HardwareAccelerator.GPU, gpu_options=gpu),
+                {"accelerator": "gpu", "backend": "GPU, float32 precision", "enforce_f32": True})
+    raise ValueError(f"accelerator {accelerator!r}: one of {ACCELERATORS}")
+
+
+class LiteRTGraph:
+    """One .tflite file with one signature, compiled on `accelerator`; call it with its inputs by name."""
+
+    def __init__(self, path: str | Path, accelerator: str = "gpu", threads: int = 8):
+        from ai_edge_litert.compiled_model import CompiledModel
+
+        self.path, self.accelerator = Path(path), accelerator
+        opts, self.options = compile_options(accelerator, threads)
+        self.model = CompiledModel.from_file(str(self.path), options=opts)
+        signatures = list(self.model.get_signature_list())
+        if signatures != [SIGNATURE]:
+            self.model.close()
+            raise ValueError(f"{self.path.name}: signatures {signatures}, expected [{SIGNATURE!r}]")
+        self.input_shapes = {n: tuple(int(x) for x in d["shape"])
+                             for n, d in self.model.get_input_tensor_details(SIGNATURE).items()}
+        self.output_shapes = {n: tuple(int(x) for x in d["shape"])
+                              for n, d in self.model.get_output_tensor_details(SIGNATURE).items()}
+        self.inputs = {n: self.model.create_input_buffer_by_name(SIGNATURE, n) for n in self.input_shapes}
+        self.outputs = {n: self.model.create_output_buffer_by_name(SIGNATURE, n) for n in self.output_shapes}
+
+    def fully_accelerated(self) -> bool:
+        return bool(self.model.is_fully_accelerated())
+
+    def __call__(self, **feeds: np.ndarray) -> dict[str, np.ndarray]:
+        if sorted(feeds) != sorted(self.input_shapes):
+            raise ValueError(f"{self.path.name}: inputs {sorted(feeds)}, expected {sorted(self.input_shapes)}")
+        for name, value in feeds.items():
+            value = np.ascontiguousarray(value, dtype=np.float32)
+            if value.shape != self.input_shapes[name]:
+                raise ValueError(f"{self.path.name}: {name} {value.shape}, expected {self.input_shapes[name]}")
+            self.inputs[name].write(value)
+        self.model.run_by_name(SIGNATURE, self.inputs, self.outputs)
+        return {name: np.asarray(self.outputs[name].read(int(np.prod(shape)), np.float32),
+                                 dtype=np.float32).reshape(shape)
+                for name, shape in self.output_shapes.items()}
+
+    def close(self) -> None:
+        for buffer in list(self.inputs.values()) + list(self.outputs.values()):
+            try:
+                buffer.destroy()
+            except Exception:
+                pass
+        self.inputs, self.outputs = {}, {}
+        self.model.close()
+
+
+class ClefGraphs:
+    """The row graphs (one file per length) and the tower graphs (one per tile), compiled when first needed.
+    row_graph(length, inputs) and tower(tile, patches) are the callables ClefHost.decide takes."""
+
+    def __init__(self, row_files: dict, tower_files: dict | None = None, tower_pos: dict | None = None,
+                 accelerator: str = "gpu", threads: int = 8):
+        if accelerator not in ACCELERATORS:
+            raise ValueError(f"accelerator {accelerator!r}: one of {ACCELERATORS}")
+        self.row_files = {int(L): Path(p) for L, p in row_files.items()}
+        if not self.row_files:
+            raise ValueError("no row graph")
+        self.tower_files = {int(t): Path(p) for t, p in (tower_files or {}).items()}
+        self.tower_pos = {}
+        for t, pos in (tower_pos or {}).items():
+            self.tower_pos[int(t)] = load_f32_tensor(pos) if isinstance(pos, (str, Path)) else np.asarray(pos, np.float32)
+        missing = sorted(set(self.tower_files) - set(self.tower_pos))
+        if missing:
+            raise ValueError(f"tower(s) {missing} without position rows")
+        self.accelerator, self.threads = accelerator, threads
+        self.row = None                     # (length, LiteRTGraph): the one compiled row graph
+        self.towers: dict[int, LiteRTGraph] = {}
+        self.compiled: list[dict] = []      # what was compiled, in order (file, accelerator)
+
+    @classmethod
+    def from_dir(cls, folder: str | Path, accelerator: str = "gpu", threads: int = 8, lengths=None) -> "ClefGraphs":
+        """The graphs of a folder laid out as FOLDER (only the files present; `lengths` limits the row graphs)."""
+        folder = Path(folder)
+        rows = {L: folder / FOLDER["row"].format(length=L) for L in BUCKETS if lengths is None or L in lengths}
+        rows = {L: p for L, p in rows.items() if p.is_file()}
+        towers = {t: folder / FOLDER["tower"].format(tile=t) for t in TILES}
+        towers = {t: p for t, p in towers.items() if p.is_file()}
+        pos = {t: folder / FOLDER["tower_pos"].format(tile=t) for t in towers}
+        return cls(rows, towers, pos, accelerator, threads)
+
+    @property
+    def lengths(self) -> tuple[int, ...]:
+        return tuple(sorted(self.row_files))
+
+    @property
+    def tiles(self) -> tuple[int, ...]:
+        return tuple(sorted(self.tower_files))
+
+    def _row_graph(self, length: int) -> LiteRTGraph:
+        if self.row is not None and self.row[0] == length:
+            return self.row[1]
+        if length not in self.row_files:
+            raise ValueError(f"no row graph of length {length} (present: {list(self.lengths)})")
+        if self.row is not None:            # one row graph at a time
+            self.row[1].close()
+            self.row = None
+        graph = LiteRTGraph(self.row_files[length], self.accelerator, self.threads)
+        if graph.input_shapes["embeds"] != (1, length, HIDDEN):
+            graph.close()
+            raise ValueError(f"{self.row_files[length].name}: embeds {graph.input_shapes['embeds']}")
+        self.row = (length, graph)
+        self.compiled.append({"file": self.row_files[length].name, "accelerator": self.accelerator})
+        return graph
+
+    def row_graph(self, length: int, inputs: dict) -> np.ndarray:
+        """The row graph of `length` on the host's row_inputs -> hidden [1, L, 4096]."""
+        graph = self._row_graph(int(length))
+        return graph(**{n: inputs[n] for n in ROW_INPUTS})["hidden"]
+
+    def _tower(self, tile: int) -> LiteRTGraph:
+        if tile not in self.towers:
+            if tile not in self.tower_files:
+                raise ValueError(f"no tower graph for a {tile} px tile (present: {list(self.tiles)})")
+            self.towers[tile] = LiteRTGraph(self.tower_files[tile], self.accelerator, self.threads)
+            self.compiled.append({"file": self.tower_files[tile].name, "accelerator": self.accelerator})
+        return self.towers[tile]
+
+    def tower(self, tile: int, patches: np.ndarray) -> np.ndarray:
+        """The tower of `tile` on the host's patches [4 G^2, 1536] -> picture rows [G^2, 4096]."""
+        g = tile_grid(tile)
+        rows = self._tower(tile)(patches=np.asarray(patches, np.float32)[None], pos=self.tower_pos[tile][None])["rows"]
+        if rows.shape != (1, g * g, HIDDEN):
+            raise ValueError(f"tower rows {rows.shape}, expected {(1, g * g, HIDDEN)}")
+        return rows[0]
+
+    def close(self) -> None:
+        if self.row is not None:
+            self.row[1].close()
+            self.row = None
+        for graph in self.towers.values():
+            graph.close()
+        self.towers = {}
+
+
+class ClefLiteRT:
+    """The host (tokenizer, tables, joint head, response) and the graphs of one folder."""
+
+    def __init__(self, host: ClefHost, graphs: ClefGraphs):
+        self.host, self.graphs = host, graphs
+
+    @classmethod
+    def from_dir(cls, folder: str | Path, accelerator: str = "gpu", threads: int = 8, lengths=None) -> "ClefLiteRT":
+        from tokenizers import Tokenizer
+
+        folder = Path(folder)
+        graphs = ClefGraphs.from_dir(folder, accelerator, threads, lengths)
+        host = ClefHost(Tokenizer.from_file(str(folder / FOLDER["tokenizer"])),
+                        Bf16Table(folder / FOLDER["embed_tokens"]), Bf16Table(folder / FOLDER["lm_head"]),
+                        JointHead.from_files(folder / FOLDER["joint_head"], folder / FOLDER["joint_head_config"]),
+                        buckets=graphs.lengths)
+        return cls(host, graphs)
+
+    def decide(self, request: dict, tile: int = 448) -> dict:
+        """request -> the SystemOne-compatible response (ClefHost.decide on this folder's graphs). A picture at a tile
+        whose tower file is not in the folder is refused (UnsupportedMedia)."""
+        tower = self.graphs.tower if tile in self.graphs.tiles else None
+        return self.host.decide(request, self.graphs.row_graph, tower, tile=tile)
+
+    def close(self) -> None:
+        self.graphs.close()
+
+    def __enter__(self) -> "ClefLiteRT":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()

host/clef_litert/tables.py

@@ -0,0 +1,125 @@
+"""bfloat16 tensors from safetensors files, read without a tensor framework.
+
+A safetensors file is an 8-byte little-endian header length, a JSON header ({name: {dtype, shape, data_offsets}},
+optional "__metadata__") and the data. bfloat16 is the top 16 bits of the float32 with the same value, so a row widens
+to float32 exactly by a 16-bit shift (NumPy has no bfloat16: the safetensors 0.8.0 NumPy reader stops on a BF16 tensor
+with "TypeError: data type 'bfloat16' not understood").
+
+    Bf16Table(path)              one [rows, dim] BF16 tensor, memory-mapped; `rows(ids)` -> float32 [n, dim]
+    load_bf16_tensors(path)      every tensor of a BF16 file -> {name: float32 array} (the joint head, 243 MB)
+    copy_bf16_tensor(...)        one tensor's bytes copied into a new one-key file without __metadata__ (the tables)"""
+from __future__ import annotations
+
+import hashlib
+import json
+import struct
+from pathlib import Path
+
+import numpy as np
+
+
+def read_header(path: str | Path) -> tuple[dict, int]:
+    """-> (header dict, file offset of the data region)."""
+    with open(path, "rb") as f:
+        n = struct.unpack("<Q", f.read(8))[0]
+        header = json.loads(f.read(n))
+    return header, 8 + n
+
+
+def widen_bf16(u16: np.ndarray) -> np.ndarray:
+    """uint16 bfloat16 bits -> float32 (exact)."""
+    return (np.asarray(u16, dtype=np.uint32) << 16).view(np.float32)
+
+
+class Bf16Table:
+    """One BF16 [rows, dim] tensor of a safetensors file, memory-mapped (nothing is read until a row is asked for).
+    `key` = the tensor's name (default: the file's only tensor)."""
+
+    def __init__(self, path: str | Path, key: str | None = None):
+        self.path = Path(path)
+        header, data_start = read_header(self.path)
+        names = [k for k in header if k != "__metadata__"]
+        if key is None:
+            if len(names) != 1:
+                raise ValueError(f"{self.path.name} holds {len(names)} tensors; name the key")
+            key = names[0]
+        e = header[key]
+        if e["dtype"] != "BF16" or len(e["shape"]) != 2:
+            raise ValueError(f"{key}: expected a 2-D BF16 tensor, got {e['dtype']} {e['shape']}")
+        start, end = e["data_offsets"]
+        rows, dim = e["shape"]
+        if end - start != rows * dim * 2:
+            raise ValueError(f"{key}: {end - start} bytes for {rows} x {dim} BF16")
+        self.key, self.shape = key, (rows, dim)
+        self.u16 = np.memmap(self.path, dtype=np.uint16, mode="r", offset=data_start + start, shape=(rows, dim))
+        self.info = {"file": self.path.name, "key": key, "dtype": "BF16", "shape": [rows, dim],
+                     "data_offset": data_start + start, "bytes": end - start}
+
+    def rows(self, ids) -> np.ndarray:
+        """float32 [len(ids), dim]: the rows of `ids`, widened exactly."""
+        return widen_bf16(self.u16[np.asarray(ids, dtype=np.int64)])
+
+
+def load_bf16_tensors(path: str | Path) -> dict[str, np.ndarray]:
+    """Every tensor of a safetensors file whose tensors are all BF16 -> {name: float32 array of its shape}."""
+    header, data_start = read_header(path)
+    raw = np.memmap(path, dtype=np.uint8, mode="r")
+    out = {}
+    for name, e in header.items():
+        if name == "__metadata__":
+            continue
+        if e["dtype"] != "BF16":
+            raise ValueError(f"{name}: dtype {e['dtype']}, expected BF16")
+        start, end = e["data_offsets"]
+        n = int(np.prod(e["shape"], dtype=np.int64))
+        if end - start != 2 * n:
+            raise ValueError(f"{name}: {end - start} bytes for {n} BF16 values")
+        u16 = np.frombuffer(raw[data_start + start:data_start + end].tobytes(), dtype="<u2")
+        out[name] = widen_bf16(u16).reshape(e["shape"])
+    return out
+
+
+def sha256_file(path: str | Path, block: int = 1 << 24) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(block), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def copy_bf16_tensor(src: str | Path, src_key: str, dst: str | Path, dst_key: str, block: int = 1 << 24) -> dict:
+    """Write `dst` = a safetensors file with the one tensor `dst_key` whose bytes are `src_key`'s bytes in `src`,
+    copied by seek + block reads (the source is never loaded whole), header without __metadata__ (padded with spaces
+    to 8 bytes, as the safetensors writer pads). Refuses to overwrite. -> record of what was copied."""
+    dst = Path(dst)
+    if dst.exists():
+        raise FileExistsError(f"refusing to overwrite {dst}")
+    header, data_start = read_header(src)
+    e = header[src_key]
+    if e["dtype"] != "BF16":
+        raise ValueError(f"{src_key}: dtype {e['dtype']}")
+    start, end = e["data_offsets"]
+    n = end - start
+    if n != 2 * int(np.prod(e["shape"], dtype=np.int64)):
+        raise ValueError(f"{src_key}: {n} bytes for shape {e['shape']}")
+    hdr = json.dumps({dst_key: {"dtype": "BF16", "shape": list(e["shape"]), "data_offsets": [0, n]}},
+                     separators=(",", ":")).encode()
+    hdr += b" " * (-len(hdr) % 8)
+    tmp = dst.with_name(dst.name + ".part")
+    h_src = hashlib.sha256()
+    copied = 0
+    with open(src, "rb") as f, open(tmp, "wb") as g:
+        g.write(struct.pack("<Q", len(hdr)) + hdr)
+        f.seek(data_start + start)
+        while copied < n:
+            chunk = f.read(min(block, n - copied))
+            if not chunk:
+                raise IOError(f"{src}: short read at {copied} of {n} bytes")
+            h_src.update(chunk)
+            g.write(chunk)
+            copied += len(chunk)
+    tmp.rename(dst)
+    return {"source": {"file": Path(src).name, "key": src_key, "dtype": e["dtype"], "shape": list(e["shape"]),
+                       "byte_range": [data_start + start, data_start + end], "data_sha256": h_src.hexdigest()},
+            "file": dst.name, "key": dst_key, "header_bytes": len(hdr), "data_offset": 8 + len(hdr),
+            "bytes": dst.stat().st_size, "bytes_copied": copied}

joint_schema_model.py

@@ -0,0 +1,576 @@
+"""Clef: a multimodal Qwen backbone with a joint schema head for typed decisions.
+
+A record provides a ``state`` (any JSON value), optional ``images`` and ``videos``,
+and ``questions``. Each question has a ``type`` (``noul``, ``choice``, or ``score``),
+``instructions``, and, for ``choice`` and ``score``, ``criteria`` describing the
+allowed options. The model returns one logit per allowed option for every question.
+``systemone`` answers a Jev/SystemOne ``/v1/systemone`` request body with the same
+response body.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import dataclass
+from dataclasses import field as dataclass_field
+from pathlib import Path
+from typing import Any
+
+import torch
+import torch.nn.functional as functional
+
+
+SYSTEM_PROMPT = (
+    "Read the complete state and schema. Decide every field jointly. Each answer "
+    "must be exactly one of that field's allowed options."
+)
+IMAGE_PLACEHOLDER = "<|vision_start|><|image_pad|><|vision_end|>"
+VIDEO_PLACEHOLDER = "<|vision_start|><|video_pad|><|vision_end|>"
+MEDIA_BATCH_KEYS = ("pixel_values", "image_grid_thw", "pixel_values_videos", "video_grid_thw")
+MEDIA_TOKEN_KEYS = ("mm_token_type_ids",)
+QUESTION_TYPES = {"noul": 0, "choice": 1, "score": 2}
+
+
+def render(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    return json.dumps(
+        value,
+        ensure_ascii=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    )
+
+
+def question_options(question: dict[str, Any]) -> list[tuple[str, Any]]:
+    question_type = str(question["type"])
+    if question_type == "noul":
+        criteria = {
+            "true": "The proposition is true or the answer is yes.",
+            "false": "The proposition is false or the answer is no.",
+        }
+        criteria.update(question.get("criteria") or {})
+        return [(key, criteria[key]) for key in ("true", "false")]
+    if question_type == "choice":
+        return sorted((str(key), value) for key, value in question["criteria"].items())
+    return [(str(index), value) for index, value in enumerate(question["criteria"])]
+
+
+@dataclass(frozen=True)
+class EncodedQuestion:
+    question_id: str
+    question_type: int
+    question_span: tuple[int, int]
+    option_spans: tuple[tuple[int, int], ...]
+    option_ids: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class EncodedRecord:
+    input_ids: tuple[int, ...]
+    questions: tuple[EncodedQuestion, ...]
+    record_id: str
+    media: dict[str, Any] | None = dataclass_field(default=None, compare=False, repr=False)
+
+
+def _tokens(tokenizer: Any, text: str) -> list[int]:
+    return tokenizer(text, add_special_tokens=False).input_ids
+
+
+def _encode_media(processor: Any, record: dict[str, Any]) -> tuple[list[int], dict[str, Any] | None]:
+    images = list(record.get("images") or [])
+    videos = list(record.get("videos") or [])
+    if not images and not videos:
+        return [], None
+    if processor is None:
+        raise ValueError("records with images or videos require a processor")
+    text = IMAGE_PLACEHOLDER * len(images) + VIDEO_PLACEHOLDER * len(videos) + "\n"
+    encoded = processor(
+        text=[text],
+        images=images or None,
+        videos=videos or None,
+        return_tensors="pt",
+        **(record.get("media_kwargs") or {}),
+    )
+    media = {key: encoded[key] for key in MEDIA_BATCH_KEYS if key in encoded}
+    for key in MEDIA_TOKEN_KEYS:
+        if key in encoded:
+            media[key] = encoded[key][0].tolist()
+    return encoded["input_ids"][0].tolist(), media
+
+
+def encode_record(
+    tokenizer: Any,
+    record: dict[str, Any],
+    max_length: int = 16384,
+    max_state_tokens: int | None = None,
+    processor: Any | None = None,
+) -> EncodedRecord:
+    schema_ids = _tokens(tokenizer, "\n\nSCHEMA FIELDS:\n")
+    questions: list[EncodedQuestion] = []
+    for question_index, (question_id, question) in enumerate(record["questions"].items()):
+        schema_ids.extend(
+            _tokens(
+                tokenizer,
+                f"\nFIELD {question_index + 1}\nID: {question_id}\nTYPE: {question['type']}\nINSTRUCTION: ",
+            )
+        )
+        question_start = len(schema_ids)
+        instructions = question.get("instructions")
+        if instructions is None or instructions == "":
+            instructions = str(question_id)
+        schema_ids.extend(_tokens(tokenizer, render(instructions)))
+        question_end = len(schema_ids)
+        schema_ids.extend(_tokens(tokenizer, "\nALLOWED OPTIONS:\n"))
+
+        option_spans: list[tuple[int, int]] = []
+        option_ids: list[str] = []
+        for option_index, (option_id, description) in enumerate(question_options(question)):
+            schema_ids.extend(_tokens(tokenizer, f"OPTION {option_index + 1}: "))
+            option_start = len(schema_ids)
+            semantics = {"option_id": option_id}
+            if description is not None:
+                semantics["description"] = description
+            schema_ids.extend(_tokens(tokenizer, render(semantics)))
+            option_spans.append((option_start, len(schema_ids)))
+            option_ids.append(option_id)
+            schema_ids.extend(_tokens(tokenizer, "\n"))
+        schema_ids.extend(_tokens(tokenizer, "END FIELD\n"))
+        questions.append(
+            EncodedQuestion(
+                question_id=str(question_id),
+                question_type=QUESTION_TYPES[str(question["type"])],
+                question_span=(question_start, question_end),
+                option_spans=tuple(option_spans),
+                option_ids=tuple(option_ids),
+            )
+        )
+
+    prefix_ids = _tokens(
+        tokenizer,
+        f"<|im_start|>system\n{SYSTEM_PROMPT}<|im_end|>\n<|im_start|>user\nSTATE:\n",
+    )
+    suffix_ids = _tokens(
+        tokenizer,
+        "\n<|im_end|>\n<|im_start|>assistant\n<think>\n\n</think>\n\nJOINT SCHEMA DECISIONS:",
+    )
+    media_ids, media = _encode_media(processor, record)
+    if media is not None:
+        media["token_offset"] = len(prefix_ids)
+        prefix_ids = prefix_ids + media_ids
+    state_ids = _tokens(tokenizer, render(record["state"]))
+    if max_state_tokens is not None:
+        state_ids = state_ids[:max_state_tokens]
+    fixed_length = len(prefix_ids) + len(schema_ids) + len(suffix_ids)
+    if fixed_length > max_length:
+        raise ValueError(
+            f"schema requires {fixed_length} tokens before state; maximum is {max_length}"
+        )
+    state_ids = state_ids[: max_length - fixed_length]
+    schema_offset = len(prefix_ids) + len(state_ids)
+    shifted_questions = tuple(
+        EncodedQuestion(
+            question_id=question.question_id,
+            question_type=question.question_type,
+            question_span=(
+                question.question_span[0] + schema_offset,
+                question.question_span[1] + schema_offset,
+            ),
+            option_spans=tuple(
+                (start + schema_offset, end + schema_offset)
+                for start, end in question.option_spans
+            ),
+            option_ids=question.option_ids,
+        )
+        for question in questions
+    )
+    input_ids = tuple(prefix_ids + state_ids + schema_ids + suffix_ids)
+    if not input_ids or not shifted_questions:
+        raise ValueError("record produced no model input or questions")
+    return EncodedRecord(
+        input_ids=input_ids,
+        questions=shifted_questions,
+        record_id=str(record.get("id", "unknown")),
+        media=media,
+    )
+
+
+def collate_records(
+    records: list[EncodedRecord],
+    pad_token_id: int,
+    device: torch.device,
+) -> dict[str, Any]:
+    maximum_length = max(len(record.input_ids) for record in records)
+    input_ids = torch.full(
+        (len(records), maximum_length),
+        pad_token_id,
+        dtype=torch.long,
+        device=device,
+    )
+    attention_mask = torch.zeros(
+        (len(records), maximum_length),
+        dtype=torch.long,
+        device=device,
+    )
+    for index, record in enumerate(records):
+        length = len(record.input_ids)
+        input_ids[index, :length] = torch.tensor(record.input_ids, device=device)
+        attention_mask[index, :length] = 1
+    media: dict[str, torch.Tensor] = {}
+    for key in MEDIA_BATCH_KEYS:
+        values = [record.media[key] for record in records if record.media and key in record.media]
+        if values:
+            media[key] = torch.cat(values, dim=0).to(device)
+    for key in MEDIA_TOKEN_KEYS:
+        if any(record.media and key in record.media for record in records):
+            token_values = torch.zeros((len(records), maximum_length), dtype=torch.long, device=device)
+            for index, record in enumerate(records):
+                if record.media and key in record.media:
+                    offset = record.media["token_offset"]
+                    values = torch.tensor(record.media[key], dtype=torch.long, device=device)
+                    token_values[index, offset : offset + len(values)] = values
+            media[key] = token_values
+    return {
+        "input_ids": input_ids,
+        "attention_mask": attention_mask,
+        "records": records,
+        "media": media,
+    }
+
+
+class EvidenceRoutingLayer(torch.nn.Module):
+    def __init__(
+        self,
+        width: int,
+        heads: int,
+        feedforward: int,
+        dropout: float = 0.0,
+    ) -> None:
+        super().__init__()
+        self.query_norm = torch.nn.LayerNorm(width)
+        self.memory_norm = torch.nn.LayerNorm(width)
+        self.attention = torch.nn.MultiheadAttention(
+            width,
+            heads,
+            dropout=dropout,
+            batch_first=True,
+        )
+        self.attention_dropout = torch.nn.Dropout(dropout)
+        self.feedforward_norm = torch.nn.LayerNorm(width)
+        self.feedforward = torch.nn.Sequential(
+            torch.nn.Linear(width, feedforward),
+            torch.nn.GELU(),
+            torch.nn.Dropout(dropout),
+            torch.nn.Linear(feedforward, width),
+            torch.nn.Dropout(dropout),
+        )
+
+    def forward(self, queries: torch.Tensor, memory: torch.Tensor) -> torch.Tensor:
+        normalized_queries = self.query_norm(queries)
+        routed, _ = self.attention(
+            normalized_queries,
+            self.memory_norm(memory),
+            self.memory_norm(memory),
+            need_weights=False,
+        )
+        queries = queries + self.attention_dropout(routed)
+        return queries + self.feedforward(self.feedforward_norm(queries))
+
+
+class JointSchemaHead(torch.nn.Module):
+    def __init__(
+        self,
+        hidden_size: int,
+        width: int,
+        routing_layers: int,
+        layers: int,
+        heads: int,
+        feedforward: int,
+        dropout: float = 0.0,
+    ) -> None:
+        super().__init__()
+        self.hidden_norm = torch.nn.LayerNorm(hidden_size)
+        self.memory_projection = torch.nn.Linear(hidden_size, width, bias=False)
+        self.question_projection = torch.nn.Linear(hidden_size, width, bias=False)
+        self.option_question_projection = torch.nn.Linear(hidden_size, width, bias=False)
+        self.global_projection = torch.nn.Linear(hidden_size, width, bias=False)
+        self.option_context_projection = torch.nn.Linear(hidden_size, width, bias=False)
+        self.option_lexical_projection = torch.nn.Linear(hidden_size, width, bias=False)
+        self.type_embedding = torch.nn.Embedding(3, width)
+        self.evidence_layers = torch.nn.ModuleList(
+            [
+                EvidenceRoutingLayer(
+                    width=width,
+                    heads=heads,
+                    feedforward=feedforward,
+                    dropout=dropout,
+                )
+                for _ in range(routing_layers)
+            ]
+        )
+        self.option_summary_norm = torch.nn.LayerNorm(width)
+        self.layers = torch.nn.ModuleList(
+            [
+                torch.nn.TransformerDecoderLayer(
+                    d_model=width,
+                    nhead=heads,
+                    dim_feedforward=feedforward,
+                    dropout=dropout,
+                    activation="gelu",
+                    batch_first=True,
+                    norm_first=True,
+                )
+                for _ in range(layers)
+            ]
+        )
+        self.field_norm = torch.nn.LayerNorm(width)
+        self.option_norm = torch.nn.LayerNorm(width)
+        self.residual_scorer = torch.nn.Sequential(
+            torch.nn.Linear(width * 4, width),
+            torch.nn.GELU(),
+            torch.nn.Dropout(dropout),
+            torch.nn.Linear(width, 1),
+        )
+        self.prior_logit_scale = torch.nn.Parameter(torch.zeros(()))
+        self.joint_logit_scale = torch.nn.Parameter(torch.zeros(()))
+        self.residual_gate = torch.nn.Parameter(torch.zeros(()))
+
+    @staticmethod
+    def _mean_span(values: torch.Tensor, span: tuple[int, int]) -> torch.Tensor:
+        start, end = span
+        return values[start:end].mean(dim=0)
+
+    def forward(
+        self,
+        hidden_states: torch.Tensor,
+        input_ids: torch.Tensor,
+        attention_mask: torch.Tensor,
+        records: list[EncodedRecord],
+        output_embedding_weight: torch.Tensor,
+    ) -> list[list[torch.Tensor]]:
+        results: list[list[torch.Tensor]] = []
+        normalized_hidden = self.hidden_norm(hidden_states)
+        for batch_index, record in enumerate(records):
+            sequence_length = int(attention_mask[batch_index].sum().item())
+            sequence_hidden = normalized_hidden[batch_index, :sequence_length]
+            memory = self.memory_projection(sequence_hidden).unsqueeze(0)
+            global_vector = sequence_hidden[-1]
+            question_vectors = torch.stack(
+                [
+                    self._mean_span(sequence_hidden, question.question_span)
+                    for question in record.questions
+                ]
+            )
+            type_ids = torch.tensor(
+                [question.question_type for question in record.questions],
+                device=hidden_states.device,
+            )
+            option_contexts: list[torch.Tensor] = []
+            lexical_options: list[torch.Tensor] = []
+            option_counts = []
+            for question in record.questions:
+                context_vectors = torch.stack(
+                    [
+                        self._mean_span(sequence_hidden, span)
+                        for span in question.option_spans
+                    ]
+                )
+                lexical_vectors = []
+                for start, end in question.option_spans:
+                    token_ids = input_ids[batch_index, start:end]
+                    lexical_vectors.append(output_embedding_weight[token_ids].mean(dim=0))
+                lexical = torch.stack(lexical_vectors)
+                option_contexts.append(context_vectors)
+                lexical_options.append(lexical)
+                option_counts.append(len(question.option_spans))
+
+            option_queries = []
+            for question_index, (context_vectors, lexical) in enumerate(
+                zip(option_contexts, lexical_options)
+            ):
+                option_queries.append(
+                    self.option_context_projection(context_vectors)
+                    + self.option_lexical_projection(lexical)
+                    + self.option_question_projection(
+                        question_vectors[question_index]
+                    ).unsqueeze(0)
+                )
+            routed_options = torch.cat(option_queries, dim=0).unsqueeze(0)
+            for layer in self.evidence_layers:
+                routed_options = layer(routed_options, memory)
+            routed_options = routed_options[0]
+            split_options = list(torch.split(routed_options, option_counts, dim=0))
+
+            base_fields = self.question_projection(question_vectors)
+            option_summaries = []
+            for field, options in zip(base_fields, split_options):
+                routing_weights = torch.softmax(
+                    torch.matmul(options, field) / math.sqrt(options.shape[-1]),
+                    dim=0,
+                )
+                option_summaries.append(
+                    torch.sum(routing_weights.unsqueeze(-1) * options, dim=0)
+                )
+            fields = (
+                base_fields
+                + self.option_summary_norm(torch.stack(option_summaries))
+                + self.global_projection(global_vector).unsqueeze(0)
+                + self.type_embedding(type_ids)
+            )
+            fields = fields.unsqueeze(0)
+            for layer in self.layers:
+                fields = layer(fields, memory)
+            fields = self.field_norm(fields[0])
+
+            record_logits: list[torch.Tensor] = []
+            for field, question, lexical, routed in zip(
+                fields,
+                record.questions,
+                lexical_options,
+                split_options,
+            ):
+                anchor = functional.normalize(
+                    question_vectors[len(record_logits)] + global_vector,
+                    dim=-1,
+                )
+                lexical_anchor = functional.normalize(lexical, dim=-1)
+                prior_scale = self.prior_logit_scale.clamp(max=math.log(100.0)).exp()
+                prior = prior_scale * torch.matmul(lexical_anchor, anchor)
+                options = self.option_norm(routed)
+                repeated_field = field.unsqueeze(0).expand_as(options)
+                cosine = functional.cosine_similarity(repeated_field, options, dim=-1)
+                features = torch.cat(
+                    [
+                        repeated_field,
+                        options,
+                        repeated_field * options,
+                        torch.abs(repeated_field - options),
+                    ],
+                    dim=-1,
+                )
+                residual = self.residual_scorer(features).squeeze(-1)
+                joint_scale = self.joint_logit_scale.clamp(max=math.log(100.0)).exp()
+                joint = joint_scale * cosine + residual
+                record_logits.append(
+                    prior + torch.sigmoid(self.residual_gate) * joint
+                )
+            results.append(record_logits)
+        return results
+
+
+class ClefModel(torch.nn.Module):
+    def __init__(self, language_model: Any, head: JointSchemaHead) -> None:
+        super().__init__()
+        self.language_model = language_model
+        self.head = head
+
+    def forward(self, batch: dict[str, Any]) -> list[list[torch.Tensor]]:
+        base_model = (
+            self.language_model.get_base_model()
+            if hasattr(self.language_model, "get_base_model")
+            else self.language_model
+        )
+        media = batch.get("media") or {}
+        text_model = base_model.model
+        if not media and hasattr(text_model, "language_model"):
+            text_model = text_model.language_model
+        outputs = text_model(
+            input_ids=batch["input_ids"],
+            attention_mask=batch["attention_mask"],
+            use_cache=False,
+            return_dict=True,
+            **media,
+        )
+        return self.head(
+            outputs.last_hidden_state,
+            batch["input_ids"],
+            batch["attention_mask"],
+            batch["records"],
+            base_model.get_output_embeddings().weight,
+        )
+
+
+def load_release_model(
+    model_path: str | Path,
+    device: str | torch.device = "cuda",
+    dtype: torch.dtype = torch.bfloat16,
+    **from_pretrained_kwargs: Any,
+) -> tuple[ClefModel, Any]:
+    """Load a Clef release (merged backbone, joint schema head, and processor)."""
+    from huggingface_hub import snapshot_download
+    from safetensors.torch import load_file
+    from transformers import AutoProcessor, Qwen3_5ForConditionalGeneration
+
+    path = Path(model_path)
+    if not path.is_dir():
+        path = Path(snapshot_download(str(model_path)))
+    backbone = Qwen3_5ForConditionalGeneration.from_pretrained(
+        path,
+        dtype=dtype,
+        device_map={"": str(device)},
+        **from_pretrained_kwargs,
+    )
+    backbone.config.use_cache = False
+    head_config = json.loads((path / "joint_head_config.json").read_text())
+    head = JointSchemaHead(**head_config)
+    head.load_state_dict(load_file(path / "joint_head.safetensors"), strict=True)
+    head = head.to(device=device, dtype=dtype)
+    processor = AutoProcessor.from_pretrained(path)
+    return ClefModel(backbone, head).eval(), processor
+
+
+def systemone_answer(question: dict[str, Any], probabilities: dict[str, float]) -> dict[str, Any]:
+    """Convert per-option probabilities for one question into a SystemOne answer."""
+    if question["type"] == "noul":
+        return {"type": "noul", "noul": round(probabilities["true"], 4)}
+    if question["type"] == "choice":
+        options = [str(option) for option in question["criteria"]]
+        choice = max(options, key=probabilities.__getitem__)
+        return {
+            "type": "choice",
+            "choice": choice,
+            "confidence": round(probabilities[choice], 4),
+            "probabilities": {option: round(probabilities[option], 4) for option in options},
+        }
+    levels = [str(index) for index in range(len(question["criteria"]))]
+    return {
+        "type": "score",
+        "score": round(sum(index * probabilities[level] for index, level in enumerate(levels)), 4),
+        "confidence": round(max(probabilities[level] for level in levels), 4),
+        "legend": dict(zip(levels, question["criteria"])),
+        "probabilities": {level: round(probabilities[level], 4) for level in levels},
+    }
+
+
+@torch.inference_mode()
+def systemone(model: ClefModel, processor: Any, request: dict[str, Any], max_length: int = 16384) -> dict[str, Any]:
+    """Answer a Jev/SystemOne ``/v1/systemone`` request body with a SystemOne response body.
+
+    The request has ``model``, ``state``, and ``questions``, plus optional ``images`` and ``videos``.
+    """
+    questions = request.get("questions")
+    if not isinstance(request.get("model"), str) or "state" not in request:
+        raise ValueError("model and state are required")
+    if not isinstance(questions, dict) or not questions:
+        raise ValueError("at least one question is required")
+    for question_id, question in questions.items():
+        if question.get("type") not in QUESTION_TYPES:
+            raise ValueError(f"{question_id}: type must be noul, choice, or score")
+        if question["type"] != "noul" and not question.get("criteria"):
+            raise ValueError(f"{question_id}: criteria must not be empty")
+    encoded = encode_record(processor.tokenizer, request, max_length=max_length, processor=processor)
+    device = next(model.parameters()).device
+    logits = model(collate_records([encoded], processor.tokenizer.pad_token_id, device))[0]
+    answers = {
+        question.question_id: systemone_answer(
+            questions[question.question_id],
+            dict(zip(question.option_ids, question_logits.float().softmax(-1).tolist())),
+        )
+        for question, question_logits in zip(encoded.questions, logits)
+    }
+    return {
+        "model": request["model"],
+        "answers": answers,
+        "usage": {"input_tokens": len(encoded.input_ids), "output_tokens": 0},
+    }

provenance_ft.json

@@ -0,0 +1,40 @@
+{
+  "epoch": 3,
+  "step": 3047,
+  "dev_eval": {
+    "event": "eval",
+    "split": "dev",
+    "epoch": 3,
+    "step": 3047,
+    "loss": 0.1932,
+    "tool_output_filter": {
+      "n": 21977,
+      "pos": 20282,
+      "neg": 1695,
+      "auc": 0.984,
+      "tpr@0.5": 0.9392,
+      "fpr@0.5": 0.0501,
+      "tpr@0.9": 0.8749,
+      "fpr@0.9": 0.0206,
+      "tpr@0.99": 0.7009,
+      "fpr@0.99": 0.0035
+    },
+    "action_authorization_guard": {
+      "n": 0,
+      "pos": 0,
+      "neg": 0,
+      "auc": 0.0,
+      "tpr@0.35": 0.0,
+      "fpr@0.35": 0.0,
+      "tpr@0.5": 0.0,
+      "fpr@0.5": 0.0,
+      "tpr@0.9": 0.0,
+      "fpr@0.9": 0.0
+    },
+    "elapsed_min": 58.51,
+    "ts": 1793861879.97
+  },
+  "lr": 3e-05,
+  "pos_weight": 1.0,
+  "seed": 20261101
+}

redo-final-results.json

@@ -0,0 +1,104 @@
+{
+  "dev_baseline": {
+    "event": "eval",
+    "split": "dev",
+    "epoch": 0,
+    "step": 0,
+    "loss": 0.6314,
+    "tool_output_filter": {
+      "n": 21977,
+      "pos": 20282,
+      "neg": 1695,
+      "auc": 0.7516,
+      "tpr@0.5": 0.7605,
+      "fpr@0.5": 0.3687,
+      "tpr@0.9": 0.3445,
+      "fpr@0.9": 0.1493,
+      "tpr@0.99": 0.0,
+      "fpr@0.99": 0.0
+    },
+    "action_authorization_guard": {
+      "n": 0,
+      "pos": 0,
+      "neg": 0,
+      "auc": 0.0,
+      "tpr@0.35": 0.0,
+      "fpr@0.35": 0.0,
+      "tpr@0.5": 0.0,
+      "fpr@0.5": 0.0,
+      "tpr@0.9": 0.0,
+      "fpr@0.9": 0.0
+    },
+    "elapsed_min": 8.46,
+    "ts": 1793858877.13
+  },
+  "dev_best": {
+    "event": "eval",
+    "split": "dev_best",
+    "epoch": 3,
+    "step": 3047,
+    "loss": 0.1934,
+    "tool_output_filter": {
+      "n": 21977,
+      "pos": 20282,
+      "neg": 1695,
+      "auc": 0.984,
+      "tpr@0.5": 0.9391,
+      "fpr@0.5": 0.0501,
+      "tpr@0.9": 0.8745,
+      "fpr@0.9": 0.0206,
+      "tpr@0.99": 0.6972,
+      "fpr@0.99": 0.0029
+    },
+    "action_authorization_guard": {
+      "n": 0,
+      "pos": 0,
+      "neg": 0,
+      "auc": 0.0,
+      "tpr@0.35": 0.0,
+      "fpr@0.35": 0.0,
+      "tpr@0.5": 0.0,
+      "fpr@0.5": 0.0,
+      "tpr@0.9": 0.0,
+      "fpr@0.9": 0.0
+    }
+  },
+  "test_banking_slack": {
+    "event": "eval",
+    "split": "test_banking_slack",
+    "epoch": 3,
+    "step": 3047,
+    "loss": 0.1888,
+    "tool_output_filter": {
+      "n": 21965,
+      "pos": 20271,
+      "neg": 1694,
+      "auc": 0.9833,
+      "tpr@0.5": 0.9402,
+      "fpr@0.5": 0.0543,
+      "tpr@0.9": 0.8821,
+      "fpr@0.9": 0.0201,
+      "tpr@0.99": 0.7055,
+      "fpr@0.99": 0.0041
+    },
+    "action_authorization_guard": {
+      "n": 0,
+      "pos": 0,
+      "neg": 0,
+      "auc": 0.0,
+      "tpr@0.35": 0.0,
+      "fpr@0.35": 0.0,
+      "tpr@0.5": 0.0,
+      "fpr@0.5": 0.0,
+      "tpr@0.9": 0.0,
+      "fpr@0.9": 0.0
+    },
+    "elapsed_min": 75.4,
+    "checkpoint": {
+      "path": "/root/work/checkpoints/clef-flash-LiteRT-ft-v04",
+      "epoch": 3,
+      "step": 3047
+    },
+    "ts": 1793862893.37
+  }
+}

redo-provenance.json

@@ -0,0 +1,68 @@
+{
+  "host": "jev-retrain (DigitalOcean gpu-mi355x1-288gb-spot, 168.144.60.186)",
+  "method": "ft_clef.py --cache-only (backbone hidden states pre-encoded with pinned PyTorch clef-flash)",
+  "wall": "train+eval 90 min (plus 44 min backbone encode)",
+  "epochs": 3,
+  "lr": 3e-05,
+  "batch": 16,
+  "pos_weight": 1.0,
+  "checks": {
+    "head_tensors": 122,
+    "head_params": 121762820,
+    "source_head_dtypes": [
+      "BF16"
+    ],
+    "bf16_converted_in_staging": false,
+    "source_head_sha256": "c7375d6f2044ab67880dcee327283fc6ef16e15055fe2d39354852eb48bb7b2a",
+    "staged_head_sha256": "c7375d6f2044ab67880dcee327283fc6ef16e15055fe2d39354852eb48bb7b2a",
+    "tflite": [
+      {
+        "name": "clef-flash_rowprefill_embeds_L4096_fp16fc.tflite",
+        "bytes": 13936871792
+      }
+    ]
+  },
+  "run_name": "clef_v04",
+  "train_data": {
+    "file": "clef_train_fixed.jsonl",
+    "rows": 16322,
+    "pos": 8232,
+    "neg": 8090,
+    "sha256": "e3916d4946cbe6e4787579ba73a82485f1e9ee186c241444586aeafa26e3bb87",
+    "added": {
+      "catalog_real_world_rows": 86,
+      "synthetic_spoof_pos": 120,
+      "synthetic_spoof_neg": 64
+    }
+  },
+  "seed": 20261101,
+  "epoch_selected": 3,
+  "selection": "dev AUC only (epochs 0.9635/0.9811/0.9840)",
+  "metrics": {
+    "dev": {
+      "n": 21977,
+      "pos": 20282,
+      "neg": 1695,
+      "auc": 0.984,
+      "tpr@0.5": 0.9391,
+      "fpr@0.5": 0.0501
+    },
+    "test_once": {
+      "n": 21965,
+      "pos": 20271,
+      "neg": 1694,
+      "auc": 0.9833,
+      "tpr@0.5": 0.9402,
+      "fpr@0.5": 0.0543
+    },
+    "dev_baseline_untrained_head_auc": 0.7516,
+    "evidence": [
+      "redo-final-results.json",
+      "redo-dev-scores.jsonl",
+      "redo-test-scores.jsonl",
+      "redo-training-log.jsonl"
+    ]
+  },
+  "load_check": "fresh-process LiteRT load of staged artifact + strict head load (121,762,820 params) + end-to-end scoring of 6 bench rows: PASS",
+  "tuesday_gate": "BYPASSED on explicit owner direction to publish droplet FT weights on completion; Tuesday-v2 frozen-chain replication (G3-G7) still outstanding"
+}

tables/embed_tokens.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:48586a2af482671b5ca781a761957e296295a7fd0950af241705cb01ad2079fc
+size 2034237544

tables/lm_head.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:106ec926c62c1aac2c8ab808833db89012a9132c53f767fa7609ec69e377d4ab
+size 2034237536

tables/vision_pos_g256.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ecd2eba829853f233b9f71f05da81c459e0ecb5ba7fbf5f5986bf42857c5efe9
+size 1179728

tables/vision_pos_g448.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:65f76c320150de7d3e53c6fa0ff7ffd048079153a8d6e114b6d48141c6f9ae26
+size 3612752

tokenizer/tokenizer.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:06b9509352d2af50381ab2247e083b80d32d5c0aba91c272ca9ff729b6a0e523
+size 19989325