Add model references, feature guide and executable selective-routing example

Documentation and synthetic usage extension; frozen utility-router weights, config and original code remain byte-identical; no verifier weights or real dataset examples.

MODEL_MANIFEST.json

@@ -1,5 +1,5 @@
 {
-  "schema": "FACTCASCADE_PUBLIC_ROUTER_MANIFEST_V1",
+  "schema": "FACTCASCADE_PUBLIC_ROUTER_MANIFEST_V2",
   "model": "FactCascade",
   "license": "Apache-2.0",
   "checkpoint": "router.json",
@@ -9,36 +9,31 @@
   "pickle_or_verifier_weights_included": false,
   "dataset_examples_or_gold_included": false,
   "members_exclude_manifest_itself": true,
-  "file_count_including_manifest": 22,
+  "file_count_including_manifest": 27,
   "files": [
     {
-      "path": "LICENSE",
-      "bytes": 11358,
-      "C_E_direct_byte_equal": true
-    },
-    {
-      "path": "NOTICE",
-      "bytes": 218,
+      "path": "config.json",
+      "bytes": 2929,
       "C_E_direct_byte_equal": true
     },
     {
-      "path": "README.md",
-      "bytes": 4248,
+      "path": "docs/FEATURES.md",
+      "bytes": 4016,
       "C_E_direct_byte_equal": true
     },
     {
-      "path": "VALIDATION.json",
-      "bytes": 738,
+      "path": "docs/USAGE.md",
+      "bytes": 4069,
       "C_E_direct_byte_equal": true
     },
     {
-      "path": "config.json",
-      "bytes": 2929,
+      "path": "example.py",
+      "bytes": 385,
       "C_E_direct_byte_equal": true
     },
     {
-      "path": "example.py",
-      "bytes": 385,
+      "path": "examples/selective_replacement.py",
+      "bytes": 2768,
       "C_E_direct_byte_equal": true
     },
     {
@@ -106,6 +101,26 @@
       "bytes": 3886,
       "C_E_direct_byte_equal": true
     },
+    {
+      "path": "LICENSE",
+      "bytes": 11358,
+      "C_E_direct_byte_equal": true
+    },
+    {
+      "path": "MODEL_REFERENCE.md",
+      "bytes": 2483,
+      "C_E_direct_byte_equal": true
+    },
+    {
+      "path": "NOTICE",
+      "bytes": 218,
+      "C_E_direct_byte_equal": true
+    },
+    {
+      "path": "README.md",
+      "bytes": 5934,
+      "C_E_direct_byte_equal": true
+    },
     {
       "path": "requirements.txt",
       "bytes": 14,
@@ -115,7 +130,20 @@
       "path": "router.json",
       "bytes": 140644,
       "C_E_direct_byte_equal": true
+    },
+    {
+      "path": "USAGE_VALIDATION.json",
+      "bytes": 939,
+      "C_E_direct_byte_equal": true
+    },
+    {
+      "path": "VALIDATION.json",
+      "bytes": 738,
+      "C_E_direct_byte_equal": true
     }
   ],
-  "validation": "VALIDATION.json"
+  "validation": "VALIDATION.json",
+  "synthetic_usage_example_included": true,
+  "real_dataset_examples_or_gold_included": false,
+  "original_frozen_weight_revision": "08bd580bb9f81908295354a678b4c048ac72e40a"
 }

MODEL_REFERENCE.md

@@ -0,0 +1,19 @@
+# Model reference and exact frozen dependencies
+
+System: **FactCascade: Utility-Guided Routing for Selective Factuality Verification**.
+
+| Component | Checkpoint | Frozen revision | Link |
+|---|---|---|---|
+| FactCascade utility router | `router.json` | Original weight release `08bd580bb9f81908295354a678b4c048ac72e40a` | [Pinned router](https://huggingface.co/nhnk/FactCascade/blob/08bd580bb9f81908295354a678b4c048ac72e40a/router.json) |
+| FT5 | `lytang/MiniCheck-Flan-T5-Large` | `a496016e7b493686ed6e1c52250b9b9d39b0dcb2` | [Hugging Face](https://huggingface.co/lytang/MiniCheck-Flan-T5-Large/tree/a496016e7b493686ed6e1c52250b9b9d39b0dcb2) |
+| B192 / DeBERTa | `lytang/MiniCheck-DeBERTa-v3-Large` | `2f2d01a54fa022a7ffadb76260e1ea8bc88c82bb` | [Hugging Face](https://huggingface.co/lytang/MiniCheck-DeBERTa-v3-Large/tree/2f2d01a54fa022a7ffadb76260e1ea8bc88c82bb) |
+| Bespoke | `bespokelabs/Bespoke-MiniCheck-7B` | `17b48556b0a54218e8fc2f0dbf0c50fa65a0cfba` | [Hugging Face](https://huggingface.co/bespokelabs/Bespoke-MiniCheck-7B/tree/17b48556b0a54218e8fc2f0dbf0c50fa65a0cfba) |
+
+
+The original trained utility checkpoint is a portable JSON NumPy histogram gradient booster:31 ordered features,100 trees,maximum depth2. Learning recipe:learning_rate0.05,min_samples_leaf30,max_bins255,random_state0; full-DEV3337rows/1397groups. Learned tree/bin/preprocessing parameters are already included; no fit is needed.
+
+`config.json` is authoritative for feature order, threshold operators, component-wise quota920/3337,midrank equal-weight fusion and stable row-key ties. FT5 fallback>0.763,FT5 standalone>0.5,B192>=0.398,Bespoke>0.5. A router output estimates signed correctness change; it is not a support probability.
+
+The pinned original weight revision remains a stable reference after documentation changes. No verifier weights are mirrored here. Use each upstream publisher's native adapter and license; the pinned Bespoke model card states CC BY-NC4.0. The FactCascade router/own-code Apache-2.0 license does not relicense any dependency. Config checkpoint dtype/context metadata are not verified deployment precision/capacity guarantees.
+
+This full-DEV frozen router is distinct from later diagnostic OOF/source-heldout fits and saved FCE predicted-correctness baseline heads. Those heads are not included. `VALIDATION.json` describes original parameter serialization parity; [USAGE_VALIDATION.json](USAGE_VALIDATION.json) documents the additional synthetic usage example only.

README.md

@@ -17,6 +17,29 @@ This repository provides the **trained frozen utility-router checkpoint** and th
 
 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.
 
+## Repository contents and quick start
+
+| Files | Purpose |
+|---|---|
+| `router.json` | Existing trained utility-router weights and DEV-only preprocessing |
+| `config.json` | Frozen31feature order,policy,thresholds and upstream verifier revisions |
+| `factcascade/` | NumPy feature,checkpoint loading,rank fusion,quota,replacement,metrics and adapter code |
+| [MODEL_REFERENCE.md](MODEL_REFERENCE.md) | Model names,exact checkpoint revisions,pinned Hugging Face links and license scope |
+| [docs/USAGE.md](docs/USAGE.md) | Download/setup,inputs,batch routing and selective replacement integration |
+| [docs/FEATURES.md](docs/FEATURES.md) | All31slot definitions and DEV/external adapter differences |
+| [examples/selective_replacement.py](examples/selective_replacement.py) | Runnable synthetic feature-to-routing-to-replacement example |
+| `VALIDATION.json`, `USAGE_VALIDATION.json` | Original serialization parity and synthetic usage checks,respectively |
+
+```bash
+hf download nhnk/FactCascade --local-dir FactCascade
+cd FactCascade
+python -m pip install -r requirements.txt
+python -B example.py
+python -B examples/selective_replacement.py
+```
+
+The synthetic example uses invented scores/text and executes no verifier. Real deployment supplies the pinned native FT5/B192 observations and then calls Bespoke on the selected rows. Changing packet segmentation or batch boundaries changes the scientific operation;see the usage guide. The original checkpoint revision remains `08bd580bb9f81908295354a678b4c048ac72e40a`;this extension changes documentation/examples,not trained parameters.
+
 ## Load the existing trained checkpoint
 
 Download the repository files, install `numpy==1.26.4`, and run:
@@ -49,4 +72,4 @@ This checkpoint is the original frozen full-DEV utility model. It is distinct fr
 
 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.
+Only model parameters, own code, frozen configuration and aggregate validation metadata are released. No real dataset claim/evidence text, gold labels, dataset rows, saved real example scores, private paths or credentials are included. The usage example contains explicitly invented toy text and observations.

USAGE_VALIDATION.json

@@ -0,0 +1,28 @@
+{
+  "schema": "FACTCASCADE_SYNTHETIC_USAGE_VALIDATION_V1",
+  "frozen_checkpoint_revision": "08bd580bb9f81908295354a678b4c048ac72e40a",
+  "router_config_existing_code_bytes_unchanged": true,
+  "synthetic_example": {
+    "features_shape": [
+      8,
+      31
+    ],
+    "components": 2,
+    "selected_rows": 2,
+    "selective_replacement_pass": true,
+    "unrouted_fallback_unchanged": true,
+    "native_verifier_calls": 0,
+    "fitting_calls": 0,
+    "benchmark_rows": 0
+  },
+  "demo_purpose": "API integration/synthetic semantics only; no quality/generalization/runtime claims",
+  "real_dataset_rows_labels_or_verifier_weights": 0,
+  "new_fits_native_verifier_inference_GPU_hash_operations": 0,
+  "edge_semantics": {
+    "stable_ties_in_two_components": "PASS",
+    "singleton_half_up_quota": "PASS",
+    "strict_and_inclusive_threshold_boundaries": "PASS",
+    "incorrect_feature_count_rejected": "PASS",
+    "synthetic_only": true
+  }
+}

docs/FEATURES.md

@@ -0,0 +1,45 @@
+# Exact ordered feature schema
+
+`build_features` returns31float64 slots in the following order. `UtilityModel.load` validates that order against the saved checkpoint; preprocessing uses the saved DEV-only medians,means and scales. Never reorder columns or fit a new scaler on an evaluation cohort.
+
+Here s=selected FT5 score,f=full FT5 score,d=B192 score. The implementation `factcascade/features.py` is authoritative for regex/token/overlap details and missing-data behavior.
+
+| Slot | Name | Meaning |
+|---|---|---|
+| 1 | `ft5_score` | Selected FT5 support score s. |
+| 2 | `ft5_abs_distance_to_calibrated_threshold` | abs(s-0.763). |
+| 3 | `b192_score` | B192 support score d. |
+| 4 | `ft5_b192_delta` | s-d. |
+| 5 | `ft5_b192_disagreement` | Indicator of (s>0.763) differing from (d>=0.398). |
+| 6 | `table_or_mixed_indicator` | TABLE_OR_MIXED modality flag. |
+| 7 | `ft5_margin_x_table` | abs(s-0.763) multiplied by table flag. |
+| 8 | `ft5_full_score` | Full-packet FT5 support score f. |
+| 9 | `selected_full_score_delta` | f-s. |
+| 10 | `selected_full_disagreement` | Indicator of (f>0.763) differing from (s>0.763). |
+| 11 | `log_ft5_selected_chunks` | log1p(selected FT5 chunk count). |
+| 12 | `log_ft5_full_chunks` | log1p(full FT5 chunk count). |
+| 13 | `log_claim_word_count` | log1p(claim whitespace word count). |
+| 14 | `log_selected_evidence_words` | log1p(selected-evidence whitespace word count). |
+| 15 | `log_full_evidence_words` | log1p(full-evidence whitespace word count). |
+| 16 | `log_selected_source_count` | log1p(selected-source count). |
+| 17 | `selected_source_coverage_ratio` | Supplied selected-source coverage ratio. |
+| 18 | `ft5_selected_margin_to_050` | abs(s-0.5). |
+| 19 | `ft5_selected_margin_to_0763` | abs(s-0.763). |
+| 20 | `ft5_full_minus_selected` | f-s. |
+| 21 | `b192_minus_ft5_selected` | d-s. |
+| 22 | `b192_ft5_decision_disagreement` | Historical extra-block disagreement: DEV uses s>0.763, external uses s>0.5, against d>=0.398. |
+| 23 | `full_only_support_signal` | Indicator of f>0.763 and s<=0.763. |
+| 24 | `b192_disagreement_x_table_or_mixed` | Slot22 disagreement multiplied by table flag. |
+| 25 | `selected_full_discrepancy_x_evidence_length_ratio` | abs(f-s)*log1p(full words)/max(1,log1p(selected words)). |
+| 26 | `claim_negation_proxy_count` | Negation matches plus bounded content terms in negation scope; surface proxy. |
+| 27 | `claim_comparator_quantifier_count` | Comparator/quantifier regex match count. |
+| 28 | `claim_numeral_unit_count` | Numeral/unit regex match count. |
+| 29 | `claim_titlecase_entity_proxy_count` | Titlecase entity surface-proxy count,capped at20; no NER model. |
+| 30 | `claim_selected_number_overlap_ratio` | Claim numeric strings shared with selected evidence / claim numeric-string count;0 if empty. |
+| 31 | `claim_entity_selected_minus_full_overlap` | Claim-entity overlap with selected evidence minus overlap with full evidence;0 for empty claim entity set. |
+
+Some original names use "disagreement" for a label-derived indicator:slot5 uses the calibrated fallback convention,while slot22 uses the adapter-specific historical convention. Allocation independently uses the raw score gap abs(s-d) in equal-weight rank fusion. These quantities must not be conflated or silently recalibrated.
+
+Required build_features keyword arguments:claim,selected_evidence,full_evidence,selected_ft5_score,full_ft5_score,deberta_score,selected_chunks,full_chunks. Optional values are selected_source_count,source_coverage,table_or_mixed,adapter;use registered source geometry and explicit adapter. `adapter="external"` is default,while "dev" preserves the historical extra-block convention. The trained loader supports saved missing-value imputation;the convenience constructor validates supplied scores/counts/text and returns a finite feature vector.
+
+This API consumes native verifier observations;it does not run inference,generate evidence,select a source protocol or infer that two adapters are scientifically interchangeable.

docs/USAGE.md

@@ -0,0 +1,58 @@
+# Using the frozen FactCascade router
+
+## Download the release
+
+Download this repository with the Hugging Face browser or CLI, then work from its root:
+
+```bash
+hf download nhnk/FactCascade --local-dir FactCascade
+cd FactCascade
+python -m pip install -r requirements.txt
+python -B example.py
+python -B examples/selective_replacement.py
+```
+
+The first example loads the existing trained JSON checkpoint. The second constructs synthetic31-slot features, routes two components under the frozen quota and replaces only selected rows. All verifier observations/text in that example are invented; no native verifier, real benchmark, gold label, fit or quality measurement is executed.
+
+The original router/config/code can also be retrieved at weight-release revision `08bd580bb9f81908295354a678b4c048ac72e40a`. Documentation/examples were extended in later commits while keeping those bytes unchanged. Use a pinned release revision when reproducing a workflow.
+
+## Supply the required observations
+
+For each row, obtain canonical selected-packet FT5, full-packet FT5 and B192 support scores using the native frozen adapters. Provide claim text,selected/full evidence,chunk counts,selected-source count,coverage ratio and modality. See [FEATURES.md](FEATURES.md) and `factcascade/features.py`.
+
+Scores must be finite support observations in[0,1]; they are not arbitrary logits. FT5 segmentation/full-packet aggregation, geometry/source-coverage definitions and component membership must match the intended source protocol. `build_features(adapter="external")` and `adapter="dev"` retain different historical conventions for one extra-feature disagreement signal; use the exact appropriate adapter. This repo does not reconstruct evidence packets or run upstream verifier inference.
+
+```python
+import numpy as np
+from factcascade.features import build_features
+from factcascade.utility_model import UtilityModel
+from factcascade.routing import route_batch, apply_replacement
+
+# observations is a caller-supplied list of canonical score/geometry/text mappings.
+X = np.vstack([build_features(**row) for row in observations])
+model = UtilityModel.load("router.json")
+routing = route_batch(
+    selected_ft5_scores=selected_scores,
+    deberta_scores=deberta_scores,
+    batch_ids=component_ids,
+    features=X, utility_model=model, row_keys=stable_row_keys,
+)
+
+# Caller executes the pinned native Bespoke verifier ONLY on selected indices.
+indices = np.flatnonzero(routing.route_mask)
+bespoke_scores = np.full(len(X), np.nan)
+bespoke_scores[indices] = run_native_bespoke_for_indices(indices)
+predictions = apply_replacement(selected_scores, bespoke_scores, routing.route_mask)
+```
+
+The second snippet is an integration sketch;caller-supplied observations and `run_native_bespoke_for_indices` are placeholders,not an included inference service. The executable self-contained synthetic version is `examples/selective_replacement.py`.
+
+## Allocation and replacement semantics
+
+Ranking is batch/component-relative. Equal utility/disagreement midranks are averaged,then top-k selected with integer half-up quota920/3337 and stable ascending row-key tie breaks. Changing component boundaries,online window size or tie keys changes routes. This is batch allocation,not independent per-row online threshold routing.
+
+Unrouted decisions remain `selected_FT5_score>0.763`. Routed decisions become `Bespoke_score>0.5`. Unrouted expensive scores may beNaN; the API does not require all-row Bespoke scoring. Selected rows may still receive harmful reversals; selection does not certify correctness.
+
+## Reproduction scope
+
+The released weights come from the historical unweighted signed-correctness target and full-DEV fit. They are not newly fitted diagnostics. Synthetically verified API/serialization behavior is not additional generalization evidence. No real examples/labels/verifierweights or complete inference environment are published;dataset licenses and upstreammodel terms remain separate. This lightweight router release is distinct from the cached reviewer reproduction capsule.

examples/selective_replacement.py

@@ -0,0 +1,55 @@
+"""Synthetic feature -> frozen router -> selected replacement example.
+
+No pretrained verifier is loaded. All observations/text are invented toy inputs;
+there is no benchmark data, gold label, metric evaluation or fitting.
+"""
+from pathlib import Path
+import sys
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+import numpy as np
+from factcascade.features import build_features
+from factcascade.utility_model import UtilityModel
+from factcascade.routing import route_batch, apply_replacement
+from factcascade.quota import half_up_quota
+
+def run_demo():
+    selected = np.array([0.80, 0.70, 0.95, 0.30, 0.65, 0.90, 0.55, 0.80])
+    full = np.array([0.90, 0.75, 0.95, 0.45, 0.70, 0.95, 0.80, 0.85])
+    deberta = np.array([0.70, 0.20, 0.80, 0.70, 0.60, 0.10, 0.40, 0.85])
+    batches = ['toy-a'] * 4 + ['toy-b'] * 4
+    keys = [f'toy-{i:02d}' for i in range(8)]
+    x = np.vstack([
+        build_features(
+            claim=f'Example Town has {i + 1} bridges.',
+            selected_evidence=f'The invented example lists {i + 1} bridges in Example Town.',
+            full_evidence=f'The invented example lists {i + 1} bridges in Example Town. This is synthetic.',
+            selected_ft5_score=float(selected[i]), full_ft5_score=float(full[i]),
+            deberta_score=float(deberta[i]), selected_chunks=1, full_chunks=1,
+            selected_source_count=1, source_coverage=1.0, adapter='external',
+        ) for i in range(8)
+    ])
+    model = UtilityModel.load(ROOT / 'router.json')
+    routed = route_batch(
+        selected_ft5_scores=selected, deberta_scores=deberta,
+        batch_ids=batches, features=x, utility_model=model, row_keys=keys,
+    )
+    # In a real application, call Bespoke only for these indices, using the
+    # frozen native input protocol. Here substitute invented observations.
+    idx = np.flatnonzero(routed.route_mask)
+    expensive = np.full(8, np.nan)
+    expensive[idx] = np.array([0.82, 0.28])
+    final = apply_replacement(selected, expensive, routed.route_mask)
+    for batch in set(batches):
+        member = np.array([b == batch for b in batches])
+        assert int(routed.route_mask[member].sum()) == half_up_quota(int(member.sum()))
+    assert np.array_equal(final[~routed.route_mask], (selected > 0.763)[~routed.route_mask])
+    assert np.array_equal(final[routed.route_mask], expensive[routed.route_mask] > 0.5)
+    assert x.shape == (8, 31) and len(idx) == 2
+    return dict(features_shape=list(x.shape), components=2, selected_rows=int(len(idx)),
+                selective_replacement_pass=True, unrouted_fallback_unchanged=True,
+                native_verifier_calls=0, fitting_calls=0, benchmark_rows=0)
+
+if __name__ == '__main__':
+    import json
+    print(json.dumps(run_demo(), indent=2))