Release frozen FactCascade utility router checkpoint and loading code

Original trained parameters exported to portable JSON; exact serialization/synthetic prediction parity; no dataset examples or verifier weights.

LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

MODEL_MANIFEST.json

@@ -0,0 +1,121 @@
+{
+  "schema": "FACTCASCADE_PUBLIC_ROUTER_MANIFEST_V1",
+  "model": "FactCascade",
+  "license": "Apache-2.0",
+  "checkpoint": "router.json",
+  "feature_count": 31,
+  "tree_count": 100,
+  "trained_parameters_included": true,
+  "pickle_or_verifier_weights_included": false,
+  "dataset_examples_or_gold_included": false,
+  "members_exclude_manifest_itself": true,
+  "file_count_including_manifest": 22,
+  "files": [
+    {
+      "path": "LICENSE",
+      "bytes": 11358,
+      "C_E_direct_byte_equal": true
+    },
+    {
+      "path": "NOTICE",
+      "bytes": 218,
+      "C_E_direct_byte_equal": true
+    },
+    {
+      "path": "README.md",
+      "bytes": 4248,
+      "C_E_direct_byte_equal": true
+    },
+    {
+      "path": "VALIDATION.json",
+      "bytes": 738,
+      "C_E_direct_byte_equal": true
+    },
+    {
+      "path": "config.json",
+      "bytes": 2929,
+      "C_E_direct_byte_equal": true
+    },
+    {
+      "path": "example.py",
+      "bytes": 385,
+      "C_E_direct_byte_equal": true
+    },
+    {
+      "path": "factcascade/__init__.py",
+      "bytes": 192,
+      "C_E_direct_byte_equal": true
+    },
+    {
+      "path": "factcascade/_frozen_numpy.py",
+      "bytes": 7178,
+      "C_E_direct_byte_equal": true
+    },
+    {
+      "path": "factcascade/adapters/__init__.py",
+      "bytes": 343,
+      "C_E_direct_byte_equal": true
+    },
+    {
+      "path": "factcascade/adapters/aggrefact.py",
+      "bytes": 202,
+      "C_E_direct_byte_equal": true
+    },
+    {
+      "path": "factcascade/adapters/begin.py",
+      "bytes": 182,
+      "C_E_direct_byte_equal": true
+    },
+    {
+      "path": "factcascade/adapters/check_covid.py",
+      "bytes": 195,
+      "C_E_direct_byte_equal": true
+    },
+    {
+      "path": "factcascade/adapters/hover.py",
+      "bytes": 387,
+      "C_E_direct_byte_equal": true
+    },
+    {
+      "path": "factcascade/features.py",
+      "bytes": 11300,
+      "C_E_direct_byte_equal": true
+    },
+    {
+      "path": "factcascade/metrics.py",
+      "bytes": 1790,
+      "C_E_direct_byte_equal": true
+    },
+    {
+      "path": "factcascade/quota.py",
+      "bytes": 438,
+      "C_E_direct_byte_equal": true
+    },
+    {
+      "path": "factcascade/rank_fusion.py",
+      "bytes": 1011,
+      "C_E_direct_byte_equal": true
+    },
+    {
+      "path": "factcascade/routing.py",
+      "bytes": 2845,
+      "C_E_direct_byte_equal": true
+    },
+    {
+      "path": "factcascade/utility_model.py",
+      "bytes": 3886,
+      "C_E_direct_byte_equal": true
+    },
+    {
+      "path": "requirements.txt",
+      "bytes": 14,
+      "C_E_direct_byte_equal": true
+    },
+    {
+      "path": "router.json",
+      "bytes": 140644,
+      "C_E_direct_byte_equal": true
+    }
+  ],
+  "validation": "VALIDATION.json"
+}

NOTICE

@@ -0,0 +1,2 @@
+FactCascade frozen utility router and accompanying own code are released under Apache-2.0.
+Verifier weights are not included. Upstream verifier models and any datasets remain subject to their own licenses and notices.

README.md

@@ -0,0 +1,52 @@
+---
+license: apache-2.0
+language:
+- en
+tags:
+- factuality-verification
+- routing
+- cascading
+- gradient-boosting
+- numpy
+- factcascade
+---
+
+# FactCascade: Utility-Guided Routing for Selective Factuality Verification
+
+This repository provides the **trained frozen utility-router checkpoint** and the code/configuration needed to load it. It is a small NumPy histogram gradient booster (31 features, 100 trees, maximum depth 2), not a verifier language model. All learned tree splits/leaf values, histogram thresholds and train-only imputation/scaling parameters are in `router.json`.
+
+The router estimates the expected signed change in correctness when a Bespoke decision replaces a cheap-verifier fallback. The frozen FactCascade allocation combines equal-weight empirical midranks of this estimate and the raw FT5/DeBERTa score gap, then selects a half-up quota of `920/3337` per component, with stable row-key ties. `config.json` gives the exact feature order, thresholds, quota and pinned verifier revisions.
+
+## Load the existing trained checkpoint
+
+Download the repository files, install `numpy==1.26.4`, and run:
+
+```python
+import numpy as np
+from factcascade.utility_model import UtilityModel
+
+model = UtilityModel.load("router.json")
+# X must contain the exact ordered 31 frozen features; zeros only illustrate shape.
+X = np.zeros((1, 31), dtype=np.float64)
+utility = model.predict(X)
+```
+
+`example.py` runs this loading example. No fitting is needed. The JSON loader validates the schema, finite preprocessing parameters, feature order and tree structure. There is no executable pickle checkpoint in this public repository. This custom NumPy router does not use Transformers `AutoModel`.
+
+For full selective verification, callers must produce the canonical features from the frozen verifier scores and evidence geometry, combine utility/disagreement ranks within the intended component, and apply the saved replacement policy. A feature vector from a different adapter, chunking rule or score convention is not interchangeable. Included API/adapters explain the expected record fields; this lightweight release does not execute the three verifier models.
+
+## Training and evaluation scope
+
+The saved router was trained on 3,337 DEV rows in 1,397 natural groups. Its target is per-row signed correctness change under unweighted squared loss; this surrogate does not directly optimize component-macro balanced accuracy. The final fusion policy was selected after observing DEV and external results. Results on exposed cohorts must be treated as retrospective; this release makes no claim that fusion is optimal or generally superior to disagreement or predicted-correctness routing.
+
+This checkpoint is the original frozen full-DEV utility model. It is distinct from later diagnostic OOF/source-heldout fits and from the separate saved FCE predicted-correctness heads. Those baseline heads and verifier weights are not included.
+
+## Serialization validation
+
+`VALIDATION.json` records exact parameter-structure and CPU prediction parity with the original frozen checkpoint. Validation includes 1,024 synthetic rows, NaN/infinity imputation and every learned split boundary, plus equal fusion scores and selected synthetic routes. No training, real labels, new quality benchmark or GPU inference was performed. This verifies faithful export; it is not an additional generalization experiment.
+
+## Verifier dependencies and license
+
+FactCascade requires scores from [MiniCheck-Flan-T5-Large](https://huggingface.co/lytang/MiniCheck-Flan-T5-Large), [MiniCheck-DeBERTa-v3-Large](https://huggingface.co/lytang/MiniCheck-DeBERTa-v3-Large) and [Bespoke-MiniCheck-7B](https://huggingface.co/bespokelabs/Bespoke-MiniCheck-7B); exact revisions are in `config.json`. Obtain those models separately and follow their licenses. In particular, the pinned Bespoke model card specifies CC BY-NC 4.0. The Apache-2.0 license here covers the FactCascade router checkpoint and own code, and does not relicense upstream verifier models or datasets.
+
+Only model parameters, own code, frozen configuration and aggregate validation metadata are released. No claim/evidence text, labels, dataset rows, saved example scores, private paths or credentials are included.

VALIDATION.json

@@ -0,0 +1,21 @@
+{
+  "schema": "FACTCASCADE_PUBLIC_ROUTER_VALIDATION_V1",
+  "original_checkpoint_bytes": 48351,
+  "original_checkpoint_source_durable_equal": true,
+  "parameter_structure_exact": true,
+  "feature_order_exact": true,
+  "features": 31,
+  "trees": 100,
+  "synthetic_prediction_rows": 3997,
+  "learned_split_boundaries_exercised": 2973,
+  "prediction_exact": true,
+  "rank_fusion_exact": true,
+  "synthetic_routes_exact": true,
+  "NaN_positive_negative_infinity_imputation_checked": true,
+  "new_fits": 0,
+  "verifier_inference": 0,
+  "real_dataset_gold_reads": 0,
+  "new_benchmark_or_runtime": 0,
+  "cryptographic_hashes": 0,
+  "scope": "Checkpoint serialization and synthetic CPU prediction parity only; not a fresh generalization study."
+}

config.json

@@ -0,0 +1,96 @@
+{
+  "schema": "FACTCASCADE_HF_ROUTER_CONFIG_V1",
+  "name": "FactCascade",
+  "checkpoint": "router.json",
+  "feature_count": 31,
+  "feature_order": [
+    "ft5_score",
+    "ft5_abs_distance_to_calibrated_threshold",
+    "b192_score",
+    "ft5_b192_delta",
+    "ft5_b192_disagreement",
+    "table_or_mixed_indicator",
+    "ft5_margin_x_table",
+    "ft5_full_score",
+    "selected_full_score_delta",
+    "selected_full_disagreement",
+    "log_ft5_selected_chunks",
+    "log_ft5_full_chunks",
+    "log_claim_word_count",
+    "log_selected_evidence_words",
+    "log_full_evidence_words",
+    "log_selected_source_count",
+    "selected_source_coverage_ratio",
+    "ft5_selected_margin_to_050",
+    "ft5_selected_margin_to_0763",
+    "ft5_full_minus_selected",
+    "b192_minus_ft5_selected",
+    "b192_ft5_decision_disagreement",
+    "full_only_support_signal",
+    "b192_disagreement_x_table_or_mixed",
+    "selected_full_discrepancy_x_evidence_length_ratio",
+    "claim_negation_proxy_count",
+    "claim_comparator_quantifier_count",
+    "claim_numeral_unit_count",
+    "claim_titlecase_entity_proxy_count",
+    "claim_selected_number_overlap_ratio",
+    "claim_entity_selected_minus_full_overlap"
+  ],
+  "learner": {
+    "max_depth": 2,
+    "max_iter": 100,
+    "learning_rate": 0.05,
+    "min_samples_leaf": 30,
+    "max_bins": 255,
+    "random_state": 0
+  },
+  "training_target": "unweighted signed replacement utility: correctness(Bespoke)-correctness(fallback)",
+  "training_rows": 3337,
+  "training_groups": 1397,
+  "policy": {
+    "utility_weight": 0.5,
+    "disagreement_weight": 0.5,
+    "rank": "empirical midrank within evaluation component",
+    "disagreement": "abs(FT5_selected_score-B192_score)",
+    "quota_numerator": 920,
+    "quota_denominator": 3337,
+    "quota_rounding": "integer half-up per component",
+    "ties": "ascending existing row key"
+  },
+  "thresholds": {
+    "FT5_fallback": {
+      "operator": ">",
+      "value": 0.763
+    },
+    "FT5_standalone": {
+      "operator": ">",
+      "value": 0.5
+    },
+    "B192": {
+      "operator": ">=",
+      "value": 0.398
+    },
+    "Bespoke": {
+      "operator": ">",
+      "value": 0.5
+    }
+  },
+  "training_metric_alignment": "Per-row squared-loss surrogate; does not directly optimize component-macro balanced accuracy",
+  "selection_role": "Final fusion chosen after observed DEV and external results; retrospective for those exposed cohorts",
+  "verifier_dependencies": [
+    {
+      "repo": "lytang/MiniCheck-Flan-T5-Large",
+      "revision": "a496016e7b493686ed6e1c52250b9b9d39b0dcb2"
+    },
+    {
+      "repo": "lytang/MiniCheck-DeBERTa-v3-Large",
+      "revision": "2f2d01a54fa022a7ffadb76260e1ea8bc88c82bb"
+    },
+    {
+      "repo": "bespokelabs/Bespoke-MiniCheck-7B",
+      "revision": "17b48556b0a54218e8fc2f0dbf0c50fa65a0cfba"
+    }
+  ],
+  "verifier_weights_included": false,
+  "requires_native_verifier_input_geometry_for_full_pipeline": true
+}

example.py

@@ -0,0 +1,10 @@
+"""Load the trained router; X is the canonical ordered 31-feature matrix."""
+from pathlib import Path
+import numpy as np
+from factcascade.utility_model import UtilityModel
+
+root=Path(__file__).parent
+model=UtilityModel.load(root / "router.json")
+# Replace this synthetic vector with the frozen feature implementation output.
+X=np.zeros((1,31),dtype=np.float64)
+print(model.predict(X))

factcascade/__init__.py

@@ -0,0 +1,4 @@
+"""FactCascade frozen routing primitives; no verifier inference on import."""
+from .routing import route_batch, apply_replacement
+from .utility_model import UtilityModel
+__version__ = "0.1.0"

factcascade/_frozen_numpy.py

@@ -0,0 +1,148 @@
+"""Exact NumPy learner and preprocessing from the tested cached replay."""
+from __future__ import annotations
+from typing import Any
+import numpy as np
+
+class PerformanceError(ValueError):
+    """A fail-closed data or algorithm contract violation."""
+
+def _impute_and_scale(train_x: np.ndarray, test_x: np.ndarray, *, scale: bool) -> tuple[np.ndarray, np.ndarray, dict[str, np.ndarray]]:
+    train_x = np.asarray(train_x, dtype=np.float64)
+    test_x = np.asarray(test_x, dtype=np.float64)
+    if train_x.ndim != 2 or test_x.ndim != 2 or train_x.shape[1] != test_x.shape[1] or not len(train_x):
+        raise PerformanceError("TRAIN_TEST_FEATURE_SHAPE_INVALID")
+    medians = np.zeros(train_x.shape[1], dtype=np.float64)
+    for column in range(train_x.shape[1]):
+        finite = train_x[np.isfinite(train_x[:, column]), column]
+        medians[column] = float(np.median(finite)) if len(finite) else 0.0
+    train = np.where(np.isfinite(train_x), train_x, medians[None, :])
+    test = np.where(np.isfinite(test_x), test_x, medians[None, :])
+    means = train.mean(axis=0) if scale else np.zeros(train.shape[1], dtype=np.float64)
+    stds = train.std(axis=0) if scale else np.ones(train.shape[1], dtype=np.float64)
+    stds[stds < 1e-12] = 1.0
+    train = (train - means[None, :]) / stds[None, :]
+    test = (test - means[None, :]) / stds[None, :]
+    if not np.isfinite(train).all() or not np.isfinite(test).all():
+        raise PerformanceError("TRAIN_ONLY_FEATURE_TRANSFORM_NONFINITE")
+    return train, test, {"medians": medians, "means": means, "scales": stds}
+
+class _HistogramTreeRegressor:
+    """Small deterministic squared-loss histogram gradient booster using NumPy."""
+
+    engine = "d0403ck_b_numpy_histogram_gbr_v1"
+
+    def __init__(self, *, max_depth: int, max_iter: int, learning_rate: float,
+                 min_samples_leaf: int, random_state: int = 0, max_bins: int = 255):
+        self.max_depth = int(max_depth)
+        self.max_iter = int(max_iter)
+        self.learning_rate = float(learning_rate)
+        self.min_samples_leaf = int(min_samples_leaf)
+        self.random_state = int(random_state)
+        self.max_bins = int(max_bins)
+        self.thresholds: list[np.ndarray] = []
+        self.trees: list[Any] = []
+        self.initial_value = 0.0
+
+    def _bin_matrix(self, x: np.ndarray) -> np.ndarray:
+        return np.column_stack([
+            np.searchsorted(self.thresholds[column], x[:, column], side="right").astype(np.int16)
+            for column in range(x.shape[1])
+        ])
+
+    def _build_tree(self, bins: np.ndarray, residual: np.ndarray, indices: np.ndarray, depth: int) -> Any:
+        value = float(residual[indices].mean()) if len(indices) else 0.0
+        if depth >= self.max_depth or len(indices) < 2 * self.min_samples_leaf:
+            return {"value": value}
+        best_gain = 0.0
+        best: tuple[int, int] | None = None
+        for feature in range(bins.shape[1]):
+            bin_values = bins[indices, feature]
+            bin_count = int(self.thresholds[feature].size + 1)
+            counts = np.bincount(bin_values, minlength=bin_count).astype(np.int64)
+            sums = np.bincount(bin_values, weights=residual[indices], minlength=bin_count)
+            left_count = np.cumsum(counts)[:-1]
+            if not len(left_count):
+                continue
+            right_count = len(indices) - left_count
+            valid = (left_count >= self.min_samples_leaf) & (right_count >= self.min_samples_leaf)
+            if not np.any(valid):
+                continue
+            left_sum = np.cumsum(sums)[:-1]
+            total_sum = float(sums.sum())
+            gain = np.zeros(len(left_count), dtype=np.float64)
+            gain[valid] = (
+                (left_sum[valid] ** 2) / left_count[valid]
+                + ((total_sum - left_sum[valid]) ** 2) / right_count[valid]
+            )
+            threshold_bin = int(np.argmax(gain))
+            candidate_gain = float(gain[threshold_bin])
+            if candidate_gain > best_gain + 1e-12:
+                best_gain = candidate_gain
+                best = (feature, threshold_bin)
+        if best is None:
+            return {"value": value}
+        feature, threshold_bin = best
+        left_mask = bins[indices, feature] <= threshold_bin
+        left = indices[left_mask]
+        right = indices[~left_mask]
+        if len(left) < self.min_samples_leaf or len(right) < self.min_samples_leaf:
+            return {"value": value}
+        return {
+            "feature": feature,
+            "threshold_bin": threshold_bin,
+            "left": self._build_tree(bins, residual, left, depth + 1),
+            "right": self._build_tree(bins, residual, right, depth + 1),
+        }
+
+    def _predict_tree(self, bins: np.ndarray, tree: Any) -> np.ndarray:
+        output = np.zeros(len(bins), dtype=np.float64)
+
+        def apply(node: Any, indices: np.ndarray) -> None:
+            if not len(indices):
+                return
+            if "value" in node:
+                output[indices] = float(node["value"])
+                return
+            feature = int(node["feature"])
+            left_mask = bins[indices, feature] <= int(node["threshold_bin"])
+            apply(node["left"], indices[left_mask])
+            apply(node["right"], indices[~left_mask])
+
+        apply(tree, np.arange(len(bins), dtype=np.int64))
+        return output
+
+    def fit(self, x: np.ndarray, y: np.ndarray) -> "_HistogramTreeRegressor":
+        x = np.asarray(x, dtype=np.float64)
+        y = np.asarray(y, dtype=np.float64)
+        if x.ndim != 2 or y.shape != (len(x),) or not len(x) or not np.isfinite(x).all() or not np.isfinite(y).all():
+            raise PerformanceError("GBT_TRAINING_ARRAY_INVALID")
+        self.thresholds = []
+        for column in range(x.shape[1]):
+            unique = np.unique(x[:, column])
+            if len(unique) <= self.max_bins:
+                cuts = (unique[:-1] + unique[1:]) / 2.0
+            else:
+                quantiles = np.linspace(0.0, 1.0, self.max_bins + 1)[1:-1]
+                cuts = np.unique(np.quantile(x[:, column], quantiles))
+            self.thresholds.append(np.asarray(cuts, dtype=np.float64))
+        bins = self._bin_matrix(x)
+        self.initial_value = float(y.mean())
+        prediction = np.full(len(y), self.initial_value, dtype=np.float64)
+        self.trees = []
+        all_indices = np.arange(len(y), dtype=np.int64)
+        for _ in range(self.max_iter):
+            residual = y - prediction
+            tree = self._build_tree(bins, residual, all_indices, 0)
+            self.trees.append(tree)
+            prediction += self.learning_rate * self._predict_tree(bins, tree)
+        return self
+
+    def predict(self, x: np.ndarray) -> np.ndarray:
+        x = np.asarray(x, dtype=np.float64)
+        if x.ndim != 2 or x.shape[1] != len(self.thresholds) or not np.isfinite(x).all():
+            raise PerformanceError("GBT_PREDICTION_ARRAY_INVALID")
+        bins = self._bin_matrix(x)
+        prediction = np.full(len(x), self.initial_value, dtype=np.float64)
+        for tree in self.trees:
+            prediction += self.learning_rate * self._predict_tree(bins, tree)
+        return prediction

factcascade/adapters/__init__.py

@@ -0,0 +1,7 @@
+"""Numeric-cache adapters; no downloads or reconstruction of raw cohorts."""
+import csv,json
+from pathlib import Path
+def csv_rows(path,expected_rows):
+    with Path(path).open(encoding="utf-8",newline="") as f: rows=list(csv.DictReader(f))
+    if len(rows)!=expected_rows: raise ValueError("FROZEN_COHORT_ROW_COUNT_MISMATCH")
+    return rows

factcascade/adapters/aggrefact.py

@@ -0,0 +1,5 @@
+"""retrospective; original provider join required for labels/components."""
+from . import csv_rows
+ROWS=29320
+DEFAULT_CACHE="aggrefact_own_outputs.csv"
+def load_cached(path): return csv_rows(path,ROWS)

factcascade/adapters/begin.py

@@ -0,0 +1,5 @@
+"""post-freeze binary adaptation; equal3corpus macro BA."""
+from . import csv_rows
+ROWS=2000
+DEFAULT_CACHE="begin_eval_numeric.csv"
+def load_cached(path): return csv_rows(path,ROWS)

factcascade/adapters/check_covid.py

@@ -0,0 +1,5 @@
+"""post-freeze binary full-abstract adaptation;49abstract groups."""
+from . import csv_rows
+ROWS=151
+DEFAULT_CACHE="checkcovid_eval_numeric.csv"
+def load_cached(path): return csv_rows(path,ROWS)

factcascade/adapters/hover.py

@@ -0,0 +1,8 @@
+"""4000 balanced oracle-evidence claims;1592families;not retrieval-task scores."""
+from pathlib import Path
+import numpy as np
+def load_cached(path):
+    with np.load(Path(path),allow_pickle=False) as z: arrays={k:z[k] for k in z.files}
+    if not any(v.ndim and v.shape[0]==4000 for v in arrays.values()):
+        raise ValueError("FROZEN_HOVER_CARDINALITY_MISMATCH")
+    return arrays

factcascade/features.py

@@ -0,0 +1,174 @@
+"""Frozen 31-slot schema over supplied text and verifier observations.
+
+This does not reconstruct benchmark packets or run inference. The caller must
+supply the same segmentation/chunk counts and evidence-unit coverage.
+"""
+from __future__ import annotations
+from typing import Any, Mapping
+import math, re
+import numpy as np
+FT5_THRESHOLD=0.763
+FEATURE_NAMES=['ft5_score', 'ft5_abs_distance_to_calibrated_threshold', 'b192_score', 'ft5_b192_delta', 'ft5_b192_disagreement', 'table_or_mixed_indicator', 'ft5_margin_x_table', 'ft5_full_score', 'selected_full_score_delta', 'selected_full_disagreement', 'log_ft5_selected_chunks', 'log_ft5_full_chunks', 'log_claim_word_count', 'log_selected_evidence_words', 'log_full_evidence_words', 'log_selected_source_count', 'selected_source_coverage_ratio', 'ft5_selected_margin_to_050', 'ft5_selected_margin_to_0763', 'ft5_full_minus_selected', 'b192_minus_ft5_selected', 'b192_ft5_decision_disagreement', 'full_only_support_signal', 'b192_disagreement_x_table_or_mixed', 'selected_full_discrepancy_x_evidence_length_ratio', 'claim_negation_proxy_count', 'claim_comparator_quantifier_count', 'claim_numeral_unit_count', 'claim_titlecase_entity_proxy_count', 'claim_selected_number_overlap_ratio', 'claim_entity_selected_minus_full_overlap']
+F5_NAMES=('ft5_selected_margin_to_050', 'ft5_selected_margin_to_0763', 'ft5_full_minus_selected', 'b192_minus_ft5_selected', 'b192_ft5_decision_disagreement', 'full_only_support_signal', 'b192_disagreement_x_table_or_mixed', 'selected_full_discrepancy_x_evidence_length_ratio')
+F2_NAMES=('claim_negation_proxy_count', 'claim_comparator_quantifier_count', 'claim_numeral_unit_count', 'claim_titlecase_entity_proxy_count', 'claim_selected_number_overlap_ratio', 'claim_entity_selected_minus_full_overlap')
+def _finite_number(value: Any) -> float | None:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    value = float(value)
+    return value if math.isfinite(value) else None
+
+def _text(value: Any) -> str | None:
+    return value if isinstance(value, str) else None
+
+def _tokens(value: str) -> list[str]:
+    return [token.casefold() for token in re.findall(r"[A-Za-z0-9]+(?:['’][A-Za-z0-9]+)?", value)]
+
+def _content_terms(value: str) -> set[str]:
+    stop = {"a", "an", "the", "and", "or", "of", "to", "in", "on", "for", "by", "with", "is", "are", "was", "were", "be", "as", "at", "from"}
+    return {token for token in _tokens(value) if len(token) > 1 and token not in stop}
+
+def _numbers(value: str) -> set[str]:
+    return {
+        re.sub(r",(?=\d{3}(?:\D|$))", "", match.casefold())
+        for match in re.findall(r"(?<![A-Za-z])[-+]?\d[\d,]*(?:\.\d+)?%?(?![A-Za-z])", value)
+    }
+
+def _entities(value: str) -> set[str]:
+    # Deterministic surface proxy only; no NER model or external lookup.
+    matches = re.findall(r"\b[A-Z][a-z]{2,}(?:\s+[A-Z][a-z]{2,})*\b", value)
+    return {" ".join(_tokens(match)) for match in matches}
+
+def _overlap(left: set[str], right: set[str]) -> float:
+    return len(left & right) / len(left) if left else 0.0
+
+class RouterFitError(ValueError):
+    pass
+
+def _base_features(input_row: Mapping[str, Any], selected: Mapping[str, Any], full: Mapping[str, Any], b192: Mapping[str, Any], selected_geometry: Mapping[str, Any], full_geometry: Mapping[str, Any]) -> np.ndarray:
+    ft5 = float(selected["score"])
+    ft5_full = float(full["score"])
+    b192_score = float(b192["score"])
+    if not all(math.isfinite(value) and 0.0 <= value <= 1.0 for value in (ft5, ft5_full, b192_score)):
+        raise RouterFitError("CHEAP_MODEL_SCORE_INVALID")
+    table = float(input_row.get("modality") == "TABLE_OR_MIXED")
+    ft5_calibrated = ft5 > FT5_THRESHOLD
+    b192_prediction = b192.get("prediction")
+    selected_prediction = selected.get("prediction")
+    full_prediction = full.get("prediction")
+    if not all(isinstance(value, bool) for value in (b192_prediction, selected_prediction, full_prediction)):
+        raise RouterFitError("CHEAP_MODEL_PREDICTION_INVALID")
+    selected_full_delta = ft5_full - ft5
+    ft5_full_disagreement = int((ft5 > FT5_THRESHOLD) != (ft5_full > FT5_THRESHOLD))
+    features = [
+        ft5,
+        abs(ft5 - FT5_THRESHOLD),
+        b192_score,
+        ft5 - b192_score,
+        float(ft5_calibrated != b192_prediction),
+        table,
+        abs(ft5 - FT5_THRESHOLD) * table,
+        ft5_full,
+        selected_full_delta,
+        float(ft5_full_disagreement),
+        math.log1p(int(selected_geometry["chunk_count"])),
+        math.log1p(int(full_geometry["chunk_count"])),
+        math.log1p(len(str(input_row.get("claim", "")).split())),
+        math.log1p(len(str(input_row.get("selected_context", "")).split())),
+        math.log1p(len(str(input_row.get("full_fixed_evidence_packet", "")).split())),
+        math.log1p(int(input_row.get("selected_source_count", 0))),
+        float(input_row.get("selected_source_coverage_ratio", 0.0)),
+    ]
+    if len(features) != 17 or not np.isfinite(np.asarray(features, dtype=np.float64)).all():
+        raise RouterFitError("A2_FEATURE_VECTOR_INVALID")
+    return np.asarray(features, dtype=np.float64)
+
+def _extra_features(input_row: Mapping[str, Any], pair_row: Mapping[str, Any]) -> tuple[dict[str, float], dict[str, bool]]:
+    values: dict[str, float] = {}
+    available: dict[str, bool] = {}
+    cheap = pair_row.get("cheap_model_features")
+    cheap = cheap if isinstance(cheap, dict) else {}
+    ft5 = _finite_number(cheap.get("ft5_score"))
+    full = _finite_number(cheap.get("ft5_full_score"))
+    b192 = _finite_number(cheap.get("b192_score"))
+    full_words = _finite_number(cheap.get("full_document_word_count"))
+    selected_words = _finite_number(cheap.get("selected_document_word_count"))
+    table = float(str(input_row.get("modality", pair_row.get("modality", ""))) == "TABLE_OR_MIXED")
+    f5_raw: dict[str, float | None] = {
+        F5_NAMES[0]: abs(ft5 - 0.5) if ft5 is not None else None,
+        F5_NAMES[1]: abs(ft5 - FT5_THRESHOLD) if ft5 is not None else None,
+        F5_NAMES[2]: full - ft5 if full is not None and ft5 is not None else None,
+        F5_NAMES[3]: b192 - ft5 if b192 is not None and ft5 is not None else None,
+        F5_NAMES[4]: float(bool(cheap.get("ft5_b192_disagreement"))) if isinstance(cheap.get("ft5_b192_disagreement"), (bool, int)) else None,
+        F5_NAMES[5]: float(full > FT5_THRESHOLD and ft5 <= FT5_THRESHOLD) if full is not None and ft5 is not None else None,
+        F5_NAMES[6]: float(bool(cheap.get("ft5_b192_disagreement"))) * table if isinstance(cheap.get("ft5_b192_disagreement"), (bool, int)) else None,
+        F5_NAMES[7]: abs(full - ft5) * math.log1p(max(0.0, full_words)) / max(1.0, math.log1p(max(0.0, selected_words)))
+        if full is not None and ft5 is not None and full_words is not None and selected_words is not None else None,
+    }
+    for key, value in f5_raw.items():
+        available[key] = value is not None
+        values[key] = float(value) if value is not None else float("nan")
+
+    claim = _text(input_row.get("claim")) or _text(input_row.get("claim_text"))
+    selected = _text(input_row.get("selected_context"))
+    full_text = _text(input_row.get("full_fixed_evidence_packet"))
+    text_ready = claim is not None and selected is not None and full_text is not None
+    if text_ready:
+        claim_terms = _content_terms(claim)
+        selected_terms = _content_terms(selected)
+        full_terms = _content_terms(full_text)
+        claim_entities = _entities(claim)
+        selected_entities = _entities(selected)
+        full_entities = _entities(full_text)
+        claim_nums = _numbers(claim)
+        selected_nums = _numbers(selected)
+        negation_matches = list(re.finditer(
+            r"\b(?:no|not|never|neither|nor|without|cannot|can't|doesn't|don't|didn't|isn't|aren't|wasn't|weren't)\b",
+            claim, flags=re.IGNORECASE,
+        ))
+        negation_scope_terms = 0
+        for match in negation_matches:
+            # Count at most five content terms in the next punctuation-bounded scope window.
+            scope = re.split(r"[.!?;:]", claim[match.end():], maxsplit=1)[0]
+            negation_scope_terms += len(_content_terms(" ".join(_tokens(scope)[:5])))
+        comparators = re.findall(r"\b(?:more|less|greater|fewer|higher|lower|at least|at most|exactly|only|all|every|each|most|least|equal(?:s)?|between|than|over|under)\b", claim, flags=re.IGNORECASE)
+        numeric_units = re.findall(r"(?<![A-Za-z])[-+]?\d[\d,]*(?:\.\d+)?\s*(?:%|percent|km|miles?|meters?|kg|grams?|years?|months?|days?|hours?|million|billion)?", claim, flags=re.IGNORECASE)
+        f2 = {
+            F2_NAMES[0]: float(len(negation_matches) + negation_scope_terms),
+            F2_NAMES[1]: float(len(comparators)),
+            F2_NAMES[2]: float(len(numeric_units)),
+            F2_NAMES[3]: float(min(20, len(claim_entities))),
+            F2_NAMES[4]: _overlap(claim_nums, selected_nums),
+            F2_NAMES[5]: _overlap(claim_entities, selected_entities) - _overlap(claim_entities, full_entities),
+        }
+    else:
+        f2 = {name: None for name in F2_NAMES}
+    for key, value in f2.items():
+        available[key] = value is not None
+        values[key] = float(value) if value is not None else float("nan")
+
+    return values, available
+
+def build_features(*,claim,selected_evidence,full_evidence,selected_ft5_score,full_ft5_score,deberta_score,
+                   selected_chunks,full_chunks,selected_source_count=1,source_coverage=1.0,
+                   table_or_mixed=False,adapter="external"):
+    if adapter not in ("dev","external"): raise ValueError("UNKNOWN_FEATURE_ADAPTER")
+    if any(not isinstance(x,str) for x in (claim,selected_evidence,full_evidence)):
+        raise ValueError("SUPPLIED_TEXT_REQUIRED")
+    if any(type(x) is not int or x<0 for x in (selected_chunks,full_chunks,selected_source_count)):
+        raise ValueError("NONNEGATIVE_COUNTS_REQUIRED")
+    if not isinstance(source_coverage,(int,float)) or not math.isfinite(source_coverage) or not 0<=source_coverage<=1:
+        raise ValueError("SOURCE_COVERAGE_INVALID")
+    if type(table_or_mixed) is not bool: raise ValueError("MODALITY_FLAG_INVALID")
+    s,f,d=map(float,(selected_ft5_score,full_ft5_score,deberta_score))
+    inp=dict(claim=claim,selected_context=selected_evidence,full_fixed_evidence_packet=full_evidence,
+             modality="TABLE_OR_MIXED" if table_or_mixed else "TEXT",selected_source_count=selected_source_count,
+             selected_source_coverage_ratio=source_coverage)
+    base=_base_features(inp,dict(score=s,prediction=s>0.5),dict(score=f,prediction=f>0.5),
+                        dict(score=d,prediction=d>=0.398),dict(chunk_count=selected_chunks),dict(chunk_count=full_chunks))
+    delta_a=float((s>(0.763 if adapter=="dev" else 0.5))!=(d>=0.398))
+    cheap=dict(ft5_score=s,ft5_full_score=f,b192_score=d,ft5_b192_disagreement=int(delta_a),
+               selected_document_word_count=len(selected_evidence.split()),full_document_word_count=len(full_evidence.split()))
+    values,_=_extra_features(inp,dict(cheap_model_features=cheap))
+    x=np.asarray(list(base)+[values[n] for n in FEATURE_NAMES[17:]],dtype=float)
+    if x.shape!=(31,) or not np.isfinite(x).all(): raise ValueError("FEATURE_VECTOR_INVALID")
+    return x

factcascade/metrics.py

@@ -0,0 +1,30 @@
+"""Pooled and macro metrics are distinct; values are fractions, not percent."""
+import numpy as np
+def binary_metrics(labels,predictions,weights=None):
+    y,p=[np.asarray(v) for v in (labels,predictions)]
+    if y.dtype!=np.bool_ or p.dtype!=np.bool_ or y.ndim!=1 or y.shape!=p.shape or not len(y):
+        raise ValueError("BOOLEAN_NONEMPTY_PAIRED_ARRAYS_REQUIRED")
+    w=np.ones(len(y)) if weights is None else np.asarray(weights,dtype=float)
+    if w.shape!=y.shape or not np.isfinite(w).all() or np.any(w<=0): raise ValueError("POSITIVE_WEIGHTS_REQUIRED")
+    sr=float(w[y&p].sum()/w[y].sum()) if y.any() else None
+    nr=float(w[(~y)&(~p)].sum()/w[~y].sum()) if (~y).any() else None
+    return dict(balanced_accuracy=(sr+nr)/2 if sr is not None and nr is not None else None,
+                supported_recall=sr,false_supported_rate=1-nr if nr is not None else None,
+                ordinary_accuracy=float((y==p).mean()),weighted_accuracy=float(w[y==p].sum()/w.sum()),
+                correct=int((y==p).sum()),rows=len(y))
+
+def macro_balanced_accuracy(labels,predictions,strata,weights=None,single_class_accuracy=False):
+    y,p=[np.asarray(v) for v in (labels,predictions)]
+    binary_metrics(y,p,weights)
+    if len(strata)!=len(y): raise ValueError("STRATUM_LENGTH_MISMATCH")
+    w=np.ones(len(y)) if weights is None else np.asarray(weights,dtype=float)
+    groups={}
+    for i,s in enumerate(strata): groups.setdefault(s,[]).append(i)
+    values=[]
+    for ix in groups.values():
+        m=binary_metrics(y[ix],p[ix],w[ix]);score=m["balanced_accuracy"]
+        if score is None:
+            if not single_class_accuracy: raise ValueError("SINGLE_CLASS_STRATUM_BA_UNDEFINED")
+            score=m["weighted_accuracy"]
+        values.append(score)
+    return float(np.mean(values))

factcascade/quota.py

@@ -0,0 +1,7 @@
+"""Exact rational half-up quota, including large integer batch sizes."""
+def half_up_quota(size, numerator=920, denominator=3337):
+    if any(type(x) is not int for x in (size,numerator,denominator)):
+        raise ValueError("INTEGER_QUOTA_ARGUMENTS_REQUIRED")
+    if size<0 or denominator<=0 or not 0<=numerator<=denominator:
+        raise ValueError("QUOTA_ARGUMENT_INVALID")
+    return (2*numerator*size+denominator)//(2*denominator)

factcascade/rank_fusion.py

@@ -0,0 +1,21 @@
+"""Frozen normalized average midranks and equal-weight fusion."""
+import numpy as np
+
+def require(condition,code):
+    if not condition: raise ValueError(code)
+
+def midrank(values):
+    """Empirical ranks; equal values share their middle rank, including constants."""
+    values = np.asarray(values, float)
+    require(values.ndim == 1 and len(values) and np.isfinite(values).all(), "RANK_INPUT_INVALID")
+    if len(values) == 1:
+        return np.asarray([0.5])
+    _, inverse, counts = np.unique(values, return_inverse=True, return_counts=True)
+    left = np.cumsum(counts) - counts
+    return ((left + (counts - 1) / 2) / (len(values) - 1))[inverse]
+
+def fusion_score(utility, selected_ft5, deberta):
+    utility, selected_ft5, deberta = [np.asarray(x,dtype=float) for x in (utility,selected_ft5,deberta)]
+    if utility.shape != selected_ft5.shape or utility.shape != deberta.shape:
+        raise ValueError("SCORE_LENGTH_MISMATCH")
+    return 0.5*midrank(utility)+0.5*midrank(np.abs(selected_ft5-deberta))

factcascade/routing.py

@@ -0,0 +1,54 @@
+"""Allocation operates within declared batches and never reads evaluation labels."""
+from dataclasses import dataclass
+import numpy as np
+from .rank_fusion import fusion_score
+from .quota import half_up_quota
+
+@dataclass(frozen=True)
+class RoutingResult:
+    route_mask: np.ndarray
+    route_scores: np.ndarray
+    predicted_utility: np.ndarray
+
+def decisions(scores, verifier="fallback"):
+    x=np.asarray(scores,dtype=float)
+    if x.ndim!=1 or not np.isfinite(x).all() or np.any((x<0)|(x>1)):
+        raise ValueError("VERIFIER_SCORE_INVALID")
+    if verifier=="fallback": return x>0.763
+    if verifier in ("ft5","bespoke"): return x>0.5
+    if verifier=="deberta": return x>=0.398
+    raise ValueError("UNKNOWN_VERIFIER")
+
+def route_batch(*,selected_ft5_scores,deberta_scores,batch_ids,utility_scores=None,features=None,utility_model=None,row_keys=None):
+    s,d=[np.asarray(x,dtype=float) for x in (selected_ft5_scores,deberta_scores)]
+    decisions(s);decisions(d,"deberta")
+    n=len(s)
+    if n==0 or d.shape!=s.shape or len(batch_ids)!=n: raise ValueError("BATCH_INPUT_INVALID")
+    if any(not isinstance(x,str) or not x for x in batch_ids): raise ValueError("BATCH_IDS_MUST_BE_NONEMPTY_STRINGS")
+    if utility_scores is None:
+        if features is None or utility_model is None: raise ValueError("UTILITY_SCORES_OR_FEATURES_AND_MODEL_REQUIRED")
+        u=np.asarray(utility_model.predict(features),dtype=float)
+    else:
+        if features is not None or utility_model is not None: raise ValueError("UTILITY_INPUT_AMBIGUOUS")
+        u=np.asarray(utility_scores,dtype=float)
+    if u.shape!=s.shape or not np.isfinite(u).all(): raise ValueError("UTILITY_ARRAY_INVALID")
+    keys=list(row_keys) if row_keys is not None else [f"{i:020d}" for i in range(n)]
+    if len(keys)!=n or len(set(keys))!=n or any(not isinstance(k,str) or not k for k in keys):
+        raise ValueError("ROW_KEYS_MUST_BE_UNIQUE_NONEMPTY_STRINGS")
+    batches={}
+    for i,b in enumerate(batch_ids): batches.setdefault(b,[]).append(i)
+    mask=np.zeros(n,dtype=bool);scores=np.zeros(n,dtype=float)
+    for indices in batches.values():
+        ix=np.asarray(indices);scores[ix]=fusion_score(u[ix],s[ix],d[ix])
+        order=sorted(indices,key=lambda i:(-float(scores[i]),keys[i]))
+        mask[order[:half_up_quota(len(indices))]]=True
+    return RoutingResult(mask,scores,u)
+
+def apply_replacement(selected_ft5_scores,bespoke_scores,route_mask):
+    fallback=decisions(selected_ft5_scores);r=np.asarray(route_mask)
+    b=np.asarray(bespoke_scores,dtype=float)
+    if r.dtype!=np.bool_ or r.shape!=fallback.shape or b.shape!=fallback.shape:
+        raise ValueError("REPLACEMENT_ARRAY_INVALID")
+    # Unrouted expensive scores may be absent/NaN: no all-row Bespoke call is required.
+    final=fallback.copy();final[r]=decisions(b[r],"bespoke")
+    return final

factcascade/utility_model.py

@@ -0,0 +1,61 @@
+"""Frozen NumPy regression recipe; checkpoints are JSON, never executable pickle."""
+import json
+from pathlib import Path
+import numpy as np
+from .features import FEATURE_NAMES
+from ._frozen_numpy import _HistogramTreeRegressor, _impute_and_scale
+
+CONFIG=dict(max_depth=2,max_iter=100,learning_rate=0.05,min_samples_leaf=30,max_bins=255,random_state=0)
+class UtilityModel:
+    def fit(self,features,fallback,bespoke,labels):
+        x=np.asarray(features,dtype=float)
+        if x.ndim!=2 or x.shape[1]!=31: raise ValueError("EXACT_31_FEATURES_REQUIRED")
+        a,b,y=[np.asarray(v) for v in (fallback,bespoke,labels)]
+        if any(v.dtype!=np.bool_ or v.shape!=(len(x),) for v in (a,b,y)):
+            raise ValueError("BOOLEAN_PAIRED_LABELS_REQUIRED")
+        target=(b==y).astype(float)-(a==y).astype(float)
+        train,_,self.transform=_impute_and_scale(x,x,scale=True)
+        self.model=_HistogramTreeRegressor(**CONFIG).fit(train,target)
+        return self
+    def predict(self,features):
+        if not hasattr(self,"model"): raise ValueError("MODEL_NOT_FITTED")
+        x=np.asarray(features,dtype=float)
+        if x.ndim!=2 or x.shape[1]!=31: raise ValueError("EXACT_31_FEATURES_REQUIRED")
+        t=self.transform
+        filled=np.where(np.isfinite(x),x,t["medians"][None,:])
+        return self.model.predict((filled-t["means"][None,:])/t["scales"][None,:])
+    def to_dict(self):
+        if not hasattr(self,"model"): raise ValueError("MODEL_NOT_FITTED")
+        state=vars(self.model).copy();state["thresholds"]=[v.tolist() for v in state["thresholds"]]
+        return dict(schema="FACTCASCADE_UTILITY_JSON_V1",feature_order=FEATURE_NAMES,
+                    config=CONFIG,transform={k:v.tolist() for k,v in self.transform.items()},model=state)
+    @classmethod
+    def from_dict(cls,data):
+        if data.get("schema")!="FACTCASCADE_UTILITY_JSON_V1" or data.get("feature_order")!=FEATURE_NAMES or data.get("config")!=CONFIG:
+            raise ValueError("CHECKPOINT_SCHEMA_OR_CONFIG_MISMATCH")
+        result=cls();result.transform={k:np.asarray(data["transform"][k],dtype=float) for k in ["medians","means","scales"]}
+        if any(v.shape!=(31,) or not np.isfinite(v).all() for v in result.transform.values()) or np.any(result.transform["scales"]<=0):
+            raise ValueError("CHECKPOINT_TRANSFORM_INVALID")
+        model=data["model"]
+        if any(model[k]!=v for k,v in CONFIG.items()) or len(model["thresholds"])!=31 or len(model["trees"])!=100:
+            raise ValueError("CHECKPOINT_MODEL_INVALID")
+        result.model=_HistogramTreeRegressor(**CONFIG)
+        result.model.initial_value=float(model["initial_value"])
+        if not np.isfinite(result.model.initial_value): raise ValueError("CHECKPOINT_NONFINITE")
+        result.model.thresholds=[np.asarray(v,dtype=float) for v in model["thresholds"]]
+        if any(v.ndim!=1 or not np.isfinite(v).all() or np.any(np.diff(v)<=0) for v in result.model.thresholds):
+            raise ValueError("CHECKPOINT_THRESHOLDS_INVALID")
+        def tree(node,depth=0):
+            if set(node)=={"value"} and np.isfinite(node["value"]): return
+            if set(node)!={"feature","threshold_bin","left","right"} or depth>=2:
+                raise ValueError("CHECKPOINT_TREE_INVALID")
+            f,t=node["feature"],node["threshold_bin"]
+            if type(f) is not int or not 0<=f<31 or type(t) is not int or not 0<=t<len(result.model.thresholds[f]):
+                raise ValueError("CHECKPOINT_SPLIT_INVALID")
+            tree(node["left"],depth+1);tree(node["right"],depth+1)
+        for n in model["trees"]: tree(n)
+        result.model.trees=model["trees"]
+        return result
+    @classmethod
+    def load(cls,path): return cls.from_dict(json.loads(Path(path).read_bytes()))
+    def save(self,path): Path(path).write_text(json.dumps(self.to_dict(),allow_nan=False)+"\n",encoding="utf-8")

requirements.txt

@@ -0,0 +1 @@
+numpy==1.26.4