Upload folder using huggingface_hub

README.md

@@ -0,0 +1,72 @@
+---
+base_model: LiquidAI/LFM2.5-Encoder-350M
+base_model_relation: finetune
+library_name: transformers
+tags:
+- safetensors
+- custom_code
+- decision-making
+- classification
+- routing
+- scoring
+---
+# Pivot
+
+Pivot is a decision model developed by **Q1z**. It scores a supplied set of
+options and returns a choice with probabilities. It does not generate chat text.
+
+Built on [LiquidAI/LFM2.5-Encoder-350M](https://huggingface.co/LiquidAI/LFM2.5-Encoder-350M)
+with a trained DSBT option-set scorer. Context and options are encoded separately,
+mean-pooled, scored together, and normalized over the valid options.
+
+## Model details
+
+- Parameters: 357,631,745
+- Weight types: float32
+- Format: Safetensors, full model including the decision scorer
+- Outputs: choice, noul (Boolean choice), and discrete score distributions
+- Base revision: `b886781f7c6f10ca9b7096e21b83e30a073c2f39`
+- Saved checkpoint: epoch index 0, global step 3102
+- Export verification: exact weight round-trip and typed output agreement PASS
+
+## Quick start
+
+Install `torch`, `transformers`, `safetensors`, and `numpy` using the versions
+recorded in `requirements.txt`. Review the bundled custom code before trusting it.
+
+```python
+from transformers import AutoModel, AutoTokenizer
+
+repo = "Q1z/Pivot"
+tokenizer = AutoTokenizer.from_pretrained(repo, trust_remote_code=True)
+model = AutoModel.from_pretrained(repo, trust_remote_code=True).eval()
+result = model.choose(tokenizer,
+    context="My invoice has the wrong total.",
+    options=["billing", "technical support", "sales"])
+print(result)
+```
+
+For typed questions use `model.decide(tokenizer, state=..., questions=...)`;
+see `serving/example_request.json` and `predict_example.py`.
+CPU is supported. For CUDA, call `model.to("cuda")` before inference.
+After downloading the complete repository, use its local path with
+`local_files_only=True`; no base-model weights are fetched during loading.
+Private repository access requires an authorized Hugging Face token.
+
+## Evaluation and limitations
+
+JevBench results will be added after testing. This export runs no full benchmark.
+The smoke test verifies loading and output structure, not accuracy or calibration.
+Probabilities have not been independently validated for calibration.
+Multilingual quality and speed are not yet benchmarked. Supplied options determine
+the available answers; this is not an open-ended text generator.
+
+## Package
+
+`model.safetensors` is the only weight file. `config.json`, tokenizer files, and
+bundled Python modules implement loading and inference. `dsbt_config.yaml` records
+the saved training configuration. `provenance.json` records the checkpoint hash.
+Training backups and optimizer state are not included. Keep the source best.pt
+separately if further training is needed. ONNX is not exported.
+
+Project: https://trypivot.me

config.json

@@ -0,0 +1,192 @@
+{
+  "model_type": "pivot",
+  "architectures": [
+    "PivotModel"
+  ],
+  "auto_map": {
+    "AutoConfig": "configuration_pivot.PivotConfig",
+    "AutoModel": "modeling_pivot.PivotModel"
+  },
+  "dsbt_config": {
+    "backbone": {
+      "encoder": "huggingface",
+      "model_id": "LiquidAI/LFM2.5-Encoder-350M",
+      "revision": "b886781f7c6f10ca9b7096e21b83e30a073c2f39",
+      "trust_remote_code": true,
+      "pooling": "mean",
+      "hidden_size": 1024,
+      "max_position_embeddings": 8192,
+      "stub_hidden_size": 32,
+      "stub_vocab_size": 256
+    },
+    "scorer": {
+      "type": "mlp",
+      "hidden_size": 1024,
+      "dropout": 0.0
+    },
+    "data": {
+      "k_min": 2,
+      "k_max": 16,
+      "max_context_tokens": 512,
+      "max_option_tokens": 64,
+      "noul_true": "true",
+      "noul_false": "false",
+      "split_ratios": [
+        0.8,
+        0.1,
+        0.1
+      ],
+      "family_sample_caps": {
+        "casehold": 0.15
+      }
+    },
+    "train": {
+      "epochs": 4,
+      "warmup_epochs": 2,
+      "batch_size": 32,
+      "grad_accum": 1,
+      "lr_encoder": 1e-05,
+      "lr_scorer": 5e-05,
+      "weight_decay": 0.01,
+      "grad_clip": 1.0,
+      "precision": "bf16",
+      "gradient_checkpointing": true,
+      "seed": 42,
+      "decoupling": "pcgrad",
+      "log_every": 20,
+      "num_workers": 4,
+      "early_stop_patience": 2,
+      "checkpoint_dir": "checkpoints",
+      "log_dir": "logs",
+      "lora": {
+        "enabled": false,
+        "r": 16,
+        "alpha": 32,
+        "dropout": 0.05,
+        "target_modules": [
+          "q_proj",
+          "k_proj",
+          "v_proj",
+          "out_proj",
+          "in_proj"
+        ]
+      }
+    },
+    "eval": {
+      "k_strata": [
+        2,
+        4,
+        8,
+        16
+      ],
+      "option_mode": "resample_strata",
+      "ece_bins": 15,
+      "calibration_epsilon": 0.02,
+      "temperature_scaling": false,
+      "jev_baseline": null,
+      "latency_batches": 20,
+      "require_latency_vs_jev": true,
+      "win_on_overall_acc_only": false,
+      "mid_epoch_max_examples": 4096,
+      "full_frozen_eval_only_at_end": true,
+      "frozen_eval_path": null
+    },
+    "modal_contract": {
+      "softmax_dtype": "fp32",
+      "casehold_cap": 0.15,
+      "forbid_jev_softlabel_distill": true,
+      "win_requires": [
+        "k_stratified_acc_brier_ece",
+        "latency_p50_p95_vs_jev",
+        "live_brier_pcgrad",
+        "casehold_sample_cap_le_015"
+      ],
+      "gpu": "H100",
+      "expected_steps_batch64": "16878\u201322504 for 3\u20134 epochs; early-stop may cut short",
+      "budget_note": "~$8\u201316 expected at $3.95/h for 2\u20134h; keep \u2265$8 reserve"
+    },
+    "brier": {
+      "reduction": "mean_over_real_options"
+    }
+  },
+  "encoder_config": {
+    "transformers_version": "5.17.0",
+    "architectures": [
+      "Lfm2BidirectionalForMaskedLM"
+    ],
+    "output_hidden_states": false,
+    "return_dict": true,
+    "dtype": "float32",
+    "chunk_size_feed_forward": 0,
+    "is_encoder_decoder": false,
+    "id2label": {
+      "0": "LABEL_0",
+      "1": "LABEL_1"
+    },
+    "label2id": {
+      "LABEL_0": 0,
+      "LABEL_1": 1
+    },
+    "problem_type": null,
+    "vocab_size": 65536,
+    "hidden_size": 1024,
+    "intermediate_size": 6656,
+    "num_hidden_layers": 16,
+    "num_attention_heads": 16,
+    "num_key_value_heads": 8,
+    "max_position_embeddings": 128000,
+    "initializer_range": 0.02,
+    "norm_eps": 1e-05,
+    "use_cache": false,
+    "pad_token_id": 0,
+    "bos_token_id": 1,
+    "eos_token_id": 7,
+    "tie_word_embeddings": true,
+    "rope_parameters": {
+      "rope_theta": 1000000.0,
+      "rope_type": "default"
+    },
+    "conv_bias": false,
+    "conv_L_cache": 3,
+    "block_multiple_of": 256,
+    "block_ffn_dim_multiplier": 1.0,
+    "block_auto_adjust_ff_dim": true,
+    "full_attn_idxs": null,
+    "layer_types": [
+      "conv",
+      "conv",
+      "full_attention",
+      "conv",
+      "conv",
+      "full_attention",
+      "conv",
+      "conv",
+      "full_attention",
+      "conv",
+      "full_attention",
+      "conv",
+      "full_attention",
+      "conv",
+      "full_attention",
+      "conv"
+    ],
+    "_name_or_path": "LiquidAI/LFM2.5-Encoder-350M",
+    "block_dim": 1024,
+    "block_mlp_init_scale": 1.0,
+    "block_norm_eps": 1e-05,
+    "block_out_init_scale": 1.0,
+    "block_use_swiglu": true,
+    "block_use_xavier_init": true,
+    "conv_dim": 1024,
+    "conv_dim_out": 1024,
+    "conv_use_xavier_init": true,
+    "model_type": "lfm2",
+    "num_heads": 16,
+    "use_pos_enc": true,
+    "auto_map": {
+      "AutoModel": "modeling_lfm2_bidirectional.Lfm2BidirectionalModel",
+      "AutoModelForMaskedLM": "modeling_lfm2_bidirectional.Lfm2BidirectionalForMaskedLM"
+    },
+    "output_attentions": false
+  }
+}

configuration_pivot.py

@@ -0,0 +1,11 @@
+"""Configuration for the Pivot set-scored decision encoder."""
+from transformers import PretrainedConfig
+
+
+class PivotConfig(PretrainedConfig):
+    model_type = "pivot"
+
+    def __init__(self, dsbt_config=None, encoder_config=None, **kwargs):
+        super().__init__(**kwargs)
+        self.dsbt_config = dsbt_config or {}
+        self.encoder_config = encoder_config or {}

dsbt_config.yaml

@@ -0,0 +1,88 @@
+backbone:
+  encoder: huggingface
+  model_id: LiquidAI/LFM2.5-Encoder-350M
+  revision: b886781f7c6f10ca9b7096e21b83e30a073c2f39
+  trust_remote_code: true
+  pooling: mean
+  hidden_size: 1024
+  max_position_embeddings: 8192
+  stub_hidden_size: 32
+  stub_vocab_size: 256
+scorer:
+  type: mlp
+  hidden_size: 1024
+  dropout: 0.0
+data:
+  k_min: 2
+  k_max: 16
+  max_context_tokens: 512
+  max_option_tokens: 64
+  noul_true: 'true'
+  noul_false: 'false'
+  split_ratios:
+  - 0.8
+  - 0.1
+  - 0.1
+  family_sample_caps:
+    casehold: 0.15
+train:
+  epochs: 4
+  warmup_epochs: 2
+  batch_size: 32
+  grad_accum: 1
+  lr_encoder: 1.0e-05
+  lr_scorer: 5.0e-05
+  weight_decay: 0.01
+  grad_clip: 1.0
+  precision: bf16
+  gradient_checkpointing: true
+  seed: 42
+  decoupling: pcgrad
+  log_every: 20
+  num_workers: 4
+  early_stop_patience: 2
+  checkpoint_dir: checkpoints
+  log_dir: logs
+  lora:
+    enabled: false
+    r: 16
+    alpha: 32
+    dropout: 0.05
+    target_modules:
+    - q_proj
+    - k_proj
+    - v_proj
+    - out_proj
+    - in_proj
+eval:
+  k_strata:
+  - 2
+  - 4
+  - 8
+  - 16
+  option_mode: resample_strata
+  ece_bins: 15
+  calibration_epsilon: 0.02
+  temperature_scaling: false
+  jev_baseline: null
+  latency_batches: 20
+  require_latency_vs_jev: true
+  win_on_overall_acc_only: false
+  mid_epoch_max_examples: 4096
+  full_frozen_eval_only_at_end: true
+  frozen_eval_path: null
+modal_contract:
+  softmax_dtype: fp32
+  casehold_cap: 0.15
+  forbid_jev_softlabel_distill: true
+  win_requires:
+  - k_stratified_acc_brier_ece
+  - latency_p50_p95_vs_jev
+  - live_brier_pcgrad
+  - casehold_sample_cap_le_015
+  gpu: H100
+  expected_steps_batch64: "16878\u201322504 for 3\u20134 epochs; early-stop may cut\
+    \ short"
+  budget_note: "~$8\u201316 expected at $3.95/h for 2\u20134h; keep \u2265$8 reserve"
+brier:
+  reduction: mean_over_real_options

evaluation_status.json

@@ -0,0 +1,4 @@
+{
+  "status": "skipped",
+  "reason": "user_requested_export_only"
+}

export_verification.json

@@ -0,0 +1,8 @@
+{
+  "package_format": "pivot-hf-v1",
+  "reload_verified": true,
+  "parameters": 357631745,
+  "tensor_dtypes": [
+    "float32"
+  ]
+}

model.safetensors

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

modeling_pivot.py

@@ -0,0 +1,64 @@
+"""Pivot: load full fine-tuned weights without fetching base-model weights."""
+import torch
+from torch import nn
+from transformers import AutoConfig, AutoModel, PreTrainedModel
+from .configuration_pivot import PivotConfig
+from .pivot_model import (SetBrierEncoder, StubEncoder, HuggingFaceEncoder,
+                          MLPScorer, DotScorer, _wrap_lora)
+from .pivot_infer import decide_typed, predict
+from .pivot_data import DecisionCollator
+from .pivot_serving_schema import build_response
+
+
+class PivotModel(PreTrainedModel):
+    config_class = PivotConfig
+    base_model_prefix = "network"
+    _no_split_modules = ["SetBrierEncoder"]
+
+    def __init__(self, config):
+        super().__init__(config)
+        cfg = config.dsbt_config
+        backbone = cfg["backbone"]
+        if backbone.get("encoder") == "stub":
+            encoder = StubEncoder(int(backbone.get("stub_vocab_size", 256)),
+                                  int(backbone.get("stub_hidden_size", 32)))
+        else:
+            body_config = dict(config.encoder_config)
+            model_type = body_config.pop("model_type")
+            body = AutoModel.from_config(AutoConfig.for_model(model_type, **body_config))
+            encoder = HuggingFaceEncoder.__new__(HuggingFaceEncoder)
+            nn.Module.__init__(encoder)
+            encoder.hidden_size = int(body.config.hidden_size)
+            lora = cfg["train"].get("lora")
+            encoder.model = _wrap_lora(body, lora) if lora and lora.get("enabled") else body
+        hidden = encoder.hidden_size
+        sc = cfg["scorer"]
+        if sc.get("type", "mlp") == "mlp":
+            scorer = MLPScorer(hidden, int(sc.get("hidden_size", hidden)), float(sc.get("dropout", 0)))
+        elif sc["type"] == "dot":
+            scorer = DotScorer(hidden)
+        else:
+            raise ValueError("Unsupported scorer")
+        self.network = SetBrierEncoder(encoder, scorer)
+        self.post_init()
+
+    def forward(self, ctx_ids, ctx_mask, opt_ids, opt_mask, opt_attn):
+        return self.network(ctx_ids, ctx_mask, opt_ids, opt_mask, opt_attn)
+
+    @torch.no_grad()
+    def decide(self, tokenizer, state, questions):
+        self.eval()
+        data = self.config.dsbt_config["data"]
+        return decide_typed(self.network, tokenizer, state, questions,
+                            max_context_tokens=int(data["max_context_tokens"]),
+                            max_option_tokens=int(data["max_option_tokens"]),
+                            device=next(self.parameters()).device, model_id="Pivot")
+
+    @torch.no_grad()
+    def choose(self, tokenizer, context, options):
+        self.eval()
+        data = self.config.dsbt_config["data"]
+        return predict(self.network, tokenizer, context, options,
+                       max_context_tokens=int(data["max_context_tokens"]),
+                       max_option_tokens=int(data["max_option_tokens"]),
+                       device=next(self.parameters()).device)

pivot_data.py

@@ -0,0 +1,462 @@
+"""JSONL dataset, dynamic-K set augmentation, masks, and collate (§5).
+
+Each record:
+
+    {
+      "context": str,
+      "options": [str, ...],
+      "label": int,
+      "task_type": "choice" | "noul" | "score",
+      "meta": {"domain": ..., "source_family": ..., "pair_id": ..., "hard_negatives": [...]}
+    }
+
+On every training step (§5.3): sample K, keep gold, add hard negatives, fill
+distractors, shuffle option order, remap ``label`` to the new gold index, pad
+to Kmax with opt_mask=0.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import random
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Iterator, Optional, Sequence
+
+import torch
+from torch.utils.data import Dataset
+
+TASK_TYPES = {"choice", "noul", "score"}
+
+
+@dataclass
+class DecisionExample:
+    context: str
+    options: list[str]
+    label: int
+    task_type: str
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def gold_text(self) -> str:
+        return self.options[self.label]
+
+    @property
+    def source_family(self) -> str:
+        fam = self.meta.get("source_family")
+        if fam:
+            return str(fam)
+        # Unique singleton family so untagged rows cannot leak across splits.
+        key = json.dumps([self.context, self.options, self.label], ensure_ascii=True)
+        digest = hashlib.md5(key.encode("utf-8")).hexdigest()[:16]
+        return f"singleton::{digest}"
+
+    @property
+    def hard_negatives(self) -> list[str]:
+        raw = self.meta.get("hard_negatives") or []
+        return [str(x) for x in raw]
+
+
+def parse_record(obj: dict[str, Any], *, noul_true: str = "true", noul_false: str = "false") -> DecisionExample:
+    if "context" not in obj or "label" not in obj:
+        raise ValueError("record requires 'context' and 'label'")
+    task_type = str(obj.get("task_type", "choice"))
+    if task_type not in TASK_TYPES:
+        raise ValueError(f"task_type must be one of {sorted(TASK_TYPES)}")
+    options = obj.get("options")
+    if not options:
+        if task_type == "noul":
+            options = [noul_true, noul_false]
+        else:
+            raise ValueError("record requires a non-empty options list")
+    options = [str(x) for x in options]
+    label = int(obj["label"])
+    if not 0 <= label < len(options):
+        raise ValueError(f"label {label} out of range for {len(options)} options")
+    meta = dict(obj.get("meta") or {})
+    return DecisionExample(
+        context=str(obj["context"]),
+        options=options,
+        label=label,
+        task_type=task_type,
+        meta=meta,
+    )
+
+
+def load_jsonl(
+    path: str | Path,
+    *,
+    noul_true: str = "true",
+    noul_false: str = "false",
+) -> list[DecisionExample]:
+    path = Path(path)
+    rows: list[DecisionExample] = []
+    with path.open("r", encoding="utf-8") as f:
+        for line_no, line in enumerate(f, 1):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                obj = json.loads(line)
+            except json.JSONDecodeError as exc:
+                raise ValueError(f"{path}:{line_no} invalid JSON") from exc
+            rows.append(parse_record(obj, noul_true=noul_true, noul_false=noul_false))
+    return rows
+
+
+def split_by_source_family(
+    examples: Sequence[DecisionExample],
+    *,
+    seed: int,
+    ratios: Sequence[float] = (0.8, 0.1, 0.1),
+) -> tuple[list[DecisionExample], list[DecisionExample], list[DecisionExample]]:
+    """Assign whole source families to train / val / holdout (no family leakage)."""
+    if len(ratios) != 3:
+        raise ValueError("ratios must be (train, val, holdout)")
+    families: dict[str, list[DecisionExample]] = {}
+    for ex in examples:
+        families.setdefault(ex.source_family, []).append(ex)
+    keys = sorted(families)
+    rng = random.Random(seed)
+    rng.shuffle(keys)
+    n = len(keys)
+    n_train = int(round(n * ratios[0]))
+    n_val = int(round(n * ratios[1]))
+    n_train = min(n_train, n)
+    n_val = min(n_val, n - n_train)
+    train_k = keys[:n_train]
+    val_k = keys[n_train : n_train + n_val]
+    hold_k = keys[n_train + n_val :]
+    if not train_k and keys:
+        train_k, val_k, hold_k = keys[:1], keys[1:2], keys[2:]
+    def _take(ks: Sequence[str]) -> list[DecisionExample]:
+        out: list[DecisionExample] = []
+        for k in ks:
+            out.extend(families[k])
+        return out
+    return _take(train_k), _take(val_k), _take(hold_k)
+
+
+
+def family_counts(examples: Sequence[DecisionExample]) -> dict[str, int]:
+    counts: dict[str, int] = {}
+    for ex in examples:
+        fam = ex.source_family
+        counts[fam] = counts.get(fam, 0) + 1
+    return counts
+
+
+def compute_family_sample_weights(
+    examples: Sequence[DecisionExample],
+    caps: dict[str, float] | None,
+) -> list[float]:
+    """Per-example sample weights so capped families have train mass ≤ cap.
+
+    For a single capped family with raw fraction ``f > cap``, each of its rows
+    gets weight ``cap * (N - n_f) / (n_f * (1 - cap))`` so that
+    ``P(family) = cap`` under WeightedRandomSampler (with replacement).
+    Uncapped rows keep weight 1. Multiple caps are applied independently on the
+    uncapped pool (greedy): each capped family is solved against the current
+    non-capped mass. Empty caps → all ones.
+    """
+    n = len(examples)
+    if n == 0:
+        return []
+    weights = [1.0] * n
+    if not caps:
+        return weights
+    counts = family_counts(examples)
+    # Apply stricter caps first.
+    ordered = sorted(
+        ((str(fam), float(cap)) for fam, cap in caps.items() if float(cap) > 0),
+        key=lambda x: x[1],
+    )
+    for fam, cap in ordered:
+        if not 0 < cap < 1:
+            raise ValueError(f"family_sample_caps[{fam!r}]={cap} must be in (0, 1)")
+        n_f = counts.get(fam, 0)
+        if n_f == 0:
+            continue
+        frac = n_f / n
+        if frac <= cap:
+            continue
+        # Exact single-family solution vs current weight-1 mass outside the family.
+        outside = sum(weights[i] for i, ex in enumerate(examples) if ex.source_family != fam)
+        # P = (n_f * w) / (n_f * w + outside) = cap  =>  w = cap * outside / (n_f * (1-cap))
+        w = (cap * outside) / (n_f * (1.0 - cap))
+        for i, ex in enumerate(examples):
+            if ex.source_family == fam:
+                weights[i] = float(w)
+    return weights
+
+
+def expected_family_mass(weights: Sequence[float], examples: Sequence[DecisionExample], family: str) -> float:
+    """Expected draw fraction for ``family`` under the given sample weights."""
+    total = float(sum(weights))
+    if total <= 0:
+        return 0.0
+    mass = sum(w for w, ex in zip(weights, examples) if ex.source_family == family)
+    return mass / total
+
+
+def build_option_pool(examples: Sequence[DecisionExample]) -> list[str]:
+    seen: set[str] = set()
+    pool: list[str] = []
+    for ex in examples:
+        for opt in ex.options:
+            if opt not in seen:
+                seen.add(opt)
+                pool.append(opt)
+        for hn in ex.hard_negatives:
+            if hn not in seen:
+                seen.add(hn)
+                pool.append(hn)
+    if not pool:
+        pool = ["true", "false", "unknown", "not applicable"]
+    return pool
+
+
+def build_pair_gold_index(examples: Sequence[DecisionExample]) -> dict[str, list[str]]:
+    """Map pair_id -> gold texts of siblings (contrastive flips)."""
+    idx: dict[str, list[str]] = {}
+    for ex in examples:
+        pid = ex.meta.get("pair_id")
+        if not pid:
+            continue
+        idx.setdefault(str(pid), []).append(ex.gold_text)
+    return idx
+
+
+@dataclass
+class AugmentedSet:
+    options: list[str]
+    label: int
+    k: int
+
+
+class SetAugmenter:
+    """On-the-fly variable-K option sets with shuffle + label remap."""
+
+    def __init__(
+        self,
+        *,
+        k_min: int,
+        k_max: int,
+        pool: Sequence[str],
+        pair_golds: Optional[dict[str, list[str]]] = None,
+    ):
+        if k_min < 2:
+            raise ValueError("k_min must be >= 2")
+        if k_max < k_min:
+            raise ValueError("k_max must be >= k_min")
+        self.k_min = k_min
+        self.k_max = k_max
+        self.pool = list(pool)
+        self.pair_golds = pair_golds or {}
+
+    def sample_k(self, rng: random.Random) -> int:
+        return rng.randint(self.k_min, self.k_max)
+
+    def _hard_negatives(self, example: DecisionExample) -> list[str]:
+        gold = example.gold_text
+        out: list[str] = []
+        seen = {gold}
+        for text in example.hard_negatives:
+            if text not in seen:
+                out.append(text)
+                seen.add(text)
+        pid = example.meta.get("pair_id")
+        if pid:
+            for text in self.pair_golds.get(str(pid), []):
+                if text not in seen:
+                    out.append(text)
+                    seen.add(text)
+        return out
+
+    def build(
+        self,
+        example: DecisionExample,
+        rng: random.Random,
+        k: Optional[int] = None,
+    ) -> AugmentedSet:
+        k = int(k if k is not None else self.sample_k(rng))
+        k = max(self.k_min, min(self.k_max, k))
+        gold = example.gold_text
+        chosen = [gold]
+        chosen_set = {gold}
+
+        for text in self._hard_negatives(example):
+            if len(chosen) >= k:
+                break
+            if text not in chosen_set:
+                chosen.append(text)
+                chosen_set.add(text)
+
+        # Fill remaining slots from the distractor pool (other labels' texts, etc.).
+        candidates = [t for t in self.pool if t not in chosen_set]
+        rng.shuffle(candidates)
+        for text in candidates:
+            if len(chosen) >= k:
+                break
+            chosen.append(text)
+            chosen_set.add(text)
+
+        filler = 0
+        while len(chosen) < k:
+            dummy = f"[distractor {filler}]"
+            filler += 1
+            if dummy not in chosen_set:
+                chosen.append(dummy)
+                chosen_set.add(dummy)
+
+        chosen = chosen[:k]
+        # Gold is at index 0 of `chosen` before shuffle. Remap via the permutation,
+        # not str.index, so duplicate strings cannot attach the label to the wrong slot.
+        perm = list(range(k))
+        rng.shuffle(perm)
+        shuffled = [chosen[i] for i in perm]
+        new_label = perm.index(0)
+        return AugmentedSet(options=shuffled, label=new_label, k=k)
+
+
+class DecisionDataset(Dataset):
+    def __init__(
+        self,
+        examples: Sequence[DecisionExample],
+        augmenter: SetAugmenter,
+        *,
+        seed: int,
+        augment: bool = True,
+        fixed_k: Optional[int] = None,
+        epoch: int = 0,
+    ):
+        self.examples = list(examples)
+        self.augmenter = augmenter
+        self.seed = int(seed)
+        self.augment = augment
+        self.fixed_k = fixed_k
+        self.epoch = int(epoch)
+
+    def set_epoch(self, epoch: int) -> None:
+        self.epoch = int(epoch)
+
+    def __len__(self) -> int:
+        return len(self.examples)
+
+    def _rng(self, index: int) -> random.Random:
+        # Deterministic per (epoch, index) so a seeded DataLoader is reproducible.
+        return random.Random(self.seed + 1_000_003 * (self.epoch + 1) + index)
+
+    def __getitem__(self, index: int) -> dict[str, Any]:
+        ex = self.examples[index]
+        rng = self._rng(index)
+        if self.augment:
+            aug = self.augmenter.build(ex, rng, k=self.fixed_k)
+            options, label = aug.options, aug.label
+        else:
+            options, label = list(ex.options), int(ex.label)
+            if self.fixed_k is not None:
+                aug = self.augmenter.build(ex, rng, k=self.fixed_k)
+                options, label = aug.options, aug.label
+        return {
+            "context": ex.context,
+            "options": options,
+            "label": label,
+            "task_type": ex.task_type,
+            "k": len(options),
+            "gold_text": ex.gold_text,
+        }
+
+
+class DecisionCollator:
+    """Pad variable-K option lists to Kmax and tokenize."""
+
+    def __init__(
+        self,
+        tokenizer: Any,
+        *,
+        k_max: int,
+        max_context_tokens: int,
+        max_option_tokens: int,
+    ):
+        self.tokenizer = tokenizer
+        self.k_max = k_max
+        self.max_context_tokens = max_context_tokens
+        self.max_option_tokens = max_option_tokens
+
+    def _tok(self, texts: list[str], max_length: int) -> dict[str, torch.Tensor]:
+        if getattr(self.tokenizer, "is_hash_tokenizer", False):
+            return self.tokenizer(texts, max_length=max_length)
+        return self.tokenizer(
+            texts,
+            padding="max_length",
+            truncation=True,
+            max_length=max_length,
+            return_tensors="pt",
+        )
+
+    def __call__(self, batch: list[dict[str, Any]]) -> dict[str, torch.Tensor]:
+        bsz = len(batch)
+        kmax = self.k_max
+        contexts = [row["context"] for row in batch]
+        ctx = self._tok(contexts, self.max_context_tokens)
+
+        opt_ids = torch.full(
+            (bsz, kmax, self.max_option_tokens),
+            fill_value=int(getattr(self.tokenizer, "pad_token_id", 0) or 0),
+            dtype=torch.long,
+        )
+        opt_attn = torch.zeros(bsz, kmax, self.max_option_tokens, dtype=torch.long)
+        opt_mask = torch.zeros(bsz, kmax, dtype=torch.bool)
+        labels = torch.zeros(bsz, dtype=torch.long)
+
+        flat_opts: list[str] = []
+        coords: list[tuple[int, int]] = []
+        for b, row in enumerate(batch):
+            options = row["options"]
+            if len(options) > kmax:
+                raise ValueError(f"example has K={len(options)} > k_max={kmax}")
+            lab = int(row["label"])
+            if not 0 <= lab < len(options):
+                raise ValueError("label not in real option range after shuffle")
+            labels[b] = lab
+            for i, text in enumerate(options):
+                opt_mask[b, i] = True
+                flat_opts.append(text)
+                coords.append((b, i))
+
+        if flat_opts:
+            tok = self._tok(flat_opts, self.max_option_tokens)
+            for n, (b, i) in enumerate(coords):
+                opt_ids[b, i] = tok["input_ids"][n]
+                opt_attn[b, i] = tok["attention_mask"][n]
+
+        return {
+            "ctx_ids": ctx["input_ids"],
+            "ctx_mask": ctx["attention_mask"],
+            "opt_ids": opt_ids,
+            "opt_mask": opt_mask,
+            "opt_attn": opt_attn,
+            "y": labels,
+        }
+
+
+def iter_k_views(
+    examples: Sequence[DecisionExample],
+    augmenter: SetAugmenter,
+    k_values: Sequence[int],
+    *,
+    seed: int,
+) -> Iterator[tuple[int, DecisionDataset]]:
+    """Deterministic fixed-K holdout views for K-stratified eval."""
+    for k in k_values:
+        ds = DecisionDataset(
+            examples,
+            augmenter,
+            seed=seed + 17 * int(k),
+            augment=True,
+            fixed_k=int(k),
+            epoch=0,
+        )
+        yield int(k), ds

pivot_infer.py

@@ -0,0 +1,100 @@
+"""Serving contract (§8): context + option list → {choice, index, probs}."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from typing import Any, Optional
+
+import torch
+
+from .pivot_data import DecisionCollator
+from .pivot_model import SetBrierEncoder, build_tokenizer
+
+
+@torch.no_grad()
+def predict(
+    model: SetBrierEncoder,
+    tokenizer: Any,
+    context: str,
+    options: list[str],
+    *,
+    max_context_tokens: int,
+    max_option_tokens: int,
+    device: Optional[torch.device] = None,
+) -> dict[str, Any]:
+    """One-forward decision. ``probs`` has length K and sums to 1. No generation."""
+    if len(options) < 2:
+        raise ValueError("need at least two options")
+    device = device or next(model.parameters()).device
+    collator = DecisionCollator(
+        tokenizer,
+        k_max=len(options),
+        max_context_tokens=max_context_tokens,
+        max_option_tokens=max_option_tokens,
+    )
+    batch = collator(
+        [{"context": context, "options": options, "label": 0, "k": len(options), "gold_text": options[0]}]
+    )
+    batch = {k: v.to(device) for k, v in batch.items() if k != "y"}
+    return model.decide(
+        ctx_ids=batch["ctx_ids"],
+        ctx_mask=batch["ctx_mask"],
+        opt_ids=batch["opt_ids"],
+        opt_mask=batch["opt_mask"],
+        opt_attn=batch["opt_attn"],
+        option_texts=options,
+    )
+
+
+
+@torch.no_grad()
+def decide_typed(
+    model: SetBrierEncoder,
+    tokenizer: Any,
+    state: str,
+    questions: list[dict[str, Any]],
+    *,
+    max_context_tokens: int,
+    max_option_tokens: int,
+    device: Optional[torch.device] = None,
+    model_id: str = "Pivot-Alpha",
+) -> dict[str, Any]:
+    """Jev-style: one unstructured state → many typed probabilistic decisions.
+
+    Each question dict:
+      id: str
+      primitive: "choice" | "noul" | "score"
+      options: list[str]   (K>=2)
+      description: optional str
+    """
+    from .pivot_serving_schema import build_response, build_typed_decision
+
+    if not questions:
+        raise ValueError("need at least one typed question")
+    decisions = []
+    for q in questions:
+        prim = str(q.get("primitive", "choice"))
+        if prim not in {"choice", "noul", "score"}:
+            raise ValueError(f"bad primitive {prim}")
+        options = list(q["options"])
+        raw = predict(
+            model,
+            tokenizer,
+            state,
+            options,
+            max_context_tokens=max_context_tokens,
+            max_option_tokens=max_option_tokens,
+            device=device,
+        )
+        decisions.append(
+            build_typed_decision(
+                decision_id=str(q.get("id", f"d{len(decisions)}")),
+                primitive=prim,  # type: ignore[arg-type]
+                options=options,
+                index=int(raw["index"]),
+                probs=[float(x) for x in raw["probs"]],
+                description=q.get("description"),
+            )
+        )
+    return build_response(state=state, decisions=decisions, model_id=model_id)

pivot_model.py

@@ -0,0 +1,356 @@
+"""Set-Brier Encoder: LFM2.5 (or stub) + option-set scorer + masked softmax.
+
+The same probability vector ``p`` is used for training losses and inference.
+Padded option slots are filled with -inf before softmax and never receive
+softmax mass or loss. Pad option content is zeroed before the scorer so it
+cannot enter ``p``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from typing import Any, Optional
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+PAD_ID = 0
+
+
+def masked_mean_pool(last_hidden: torch.Tensor, attention_mask: torch.Tensor) -> torch.Tensor:
+    """Mean-pool non-padding tokens of last_hidden_state. Enc(·) ∈ R^d."""
+    mask = attention_mask.unsqueeze(-1).to(dtype=last_hidden.dtype)
+    summed = (last_hidden * mask).sum(dim=1)
+    denom = mask.sum(dim=1).clamp_min(1e-6)
+    return summed / denom
+
+
+def mask_option_logits(logits: torch.Tensor, opt_mask: torch.Tensor) -> torch.Tensor:
+    """Replace pad slots with dtype.min so they get zero softmax mass.
+
+    Uses ``masked_fill`` (not a post-softmax multiply) so pads do not affect
+    the partition function of real options.
+    """
+    fill = torch.finfo(logits.dtype).min
+    return logits.masked_fill(~opt_mask.bool(), fill)
+
+
+class HashTokenizer:
+    """Deterministic whitespace tokenizer for stub / smoke runs (no HF download)."""
+
+    def __init__(self, vocab_size: int = 256, pad_token_id: int = PAD_ID):
+        if vocab_size < 4:
+            raise ValueError("vocab_size must be >= 4")
+        self.vocab_size = vocab_size
+        self.pad_token_id = pad_token_id
+        self.unk_token_id = 1
+        self.is_hash_tokenizer = True
+
+    def token_id(self, token: str) -> int:
+        digest = hashlib.md5(token.encode("utf-8")).digest()
+        return 2 + (int.from_bytes(digest[:4], "little") % (self.vocab_size - 2))
+
+    def encode(self, text: str, max_length: int) -> tuple[list[int], list[int]]:
+        pieces = text.lower().split() or ["<empty>"]
+        ids = [self.token_id(p) for p in pieces][:max_length]
+        attn = [1] * len(ids)
+        while len(ids) < max_length:
+            ids.append(self.pad_token_id)
+            attn.append(0)
+        return ids, attn
+
+    def __call__(
+        self,
+        texts: list[str],
+        *,
+        max_length: int,
+        padding: str = "max_length",
+        truncation: bool = True,
+        return_tensors: Optional[str] = "pt",
+    ) -> dict[str, torch.Tensor]:
+        del padding, truncation
+        ids, attn = zip(*(self.encode(t, max_length) for t in texts))
+        out = {
+            "input_ids": torch.tensor(ids, dtype=torch.long),
+            "attention_mask": torch.tensor(attn, dtype=torch.long),
+        }
+        if return_tensors != "pt":
+            raise ValueError("HashTokenizer only supports return_tensors='pt'")
+        return out
+
+
+class StubEncoder(nn.Module):
+    """Tiny embedding encoder so CI/smoke never downloads the HF backbone."""
+
+    def __init__(self, vocab_size: int, hidden_size: int, pad_token_id: int = PAD_ID):
+        super().__init__()
+        self.hidden_size = hidden_size
+        self.embed = nn.Embedding(vocab_size, hidden_size, padding_idx=pad_token_id)
+
+    def forward(self, input_ids: torch.Tensor, attention_mask: torch.Tensor) -> torch.Tensor:
+        return masked_mean_pool(self.embed(input_ids), attention_mask)
+
+
+class HuggingFaceEncoder(nn.Module):
+    """LiquidAI LFM2.5-Encoder body + masked mean-pool."""
+
+    def __init__(
+        self,
+        model_id: str,
+        revision: str,
+        *,
+        trust_remote_code: bool = True,
+        torch_dtype: Optional[torch.dtype] = None,
+        lora: Optional[dict[str, Any]] = None,
+    ):
+        super().__init__()
+        from transformers import AutoModel
+
+        kwargs: dict[str, Any] = {
+            "revision": revision,
+            "trust_remote_code": trust_remote_code,
+        }
+        if torch_dtype is not None:
+            kwargs["torch_dtype"] = torch_dtype
+        self.model = AutoModel.from_pretrained(model_id, **kwargs)
+        self.hidden_size = int(getattr(self.model.config, "hidden_size", 1024))
+        if lora and lora.get("enabled"):
+            self.model = _wrap_lora(self.model, lora)
+
+    def forward(self, input_ids: torch.Tensor, attention_mask: torch.Tensor) -> torch.Tensor:
+        out = self.model(input_ids=input_ids, attention_mask=attention_mask)
+        hidden = out.last_hidden_state if hasattr(out, "last_hidden_state") else out[0]
+        return masked_mean_pool(hidden, attention_mask)
+
+
+def _wrap_lora(model: nn.Module, lora: dict[str, Any]) -> nn.Module:
+    try:
+        from peft import LoraConfig, get_peft_model
+    except ImportError as exc:
+        raise ImportError("LoRA requested but peft is not installed. pip install dsbt[lora]") from exc
+    cfg = LoraConfig(
+        r=int(lora.get("r", 16)),
+        lora_alpha=int(lora.get("alpha", 32)),
+        lora_dropout=float(lora.get("dropout", 0.05)),
+        target_modules=list(lora.get("target_modules") or ["q_proj", "v_proj"]),
+        bias="none",
+        task_type="FEATURE_EXTRACTION",
+    )
+    return get_peft_model(model, cfg)
+
+
+class MLPScorer(nn.Module):
+    """Default scorer: 2-layer MLP on [h_c; h_o; h_c ⊙ h_o]."""
+
+    def __init__(self, hidden_size: int, mlp_hidden: int, dropout: float = 0.0):
+        super().__init__()
+        in_dim = 3 * hidden_size
+        self.net = nn.Sequential(
+            nn.Linear(in_dim, mlp_hidden),
+            nn.GELU(),
+            nn.Dropout(dropout),
+            nn.Linear(mlp_hidden, 1),
+        )
+
+    def forward(self, h_c: torch.Tensor, h_o: torch.Tensor) -> torch.Tensor:
+        # h_c: [B, d], h_o: [B, K, d] -> scores [B, K]
+        # Align dtypes: HF encoder may be bf16 while scorer Linear defaults to fp32.
+        wdtype = next(self.net.parameters()).dtype
+        h_c = h_c.to(dtype=wdtype)
+        h_o = h_o.to(dtype=wdtype)
+        h_c_exp = h_c.unsqueeze(1).expand_as(h_o)
+        feat = torch.cat([h_c_exp, h_o, h_c_exp * h_o], dim=-1)
+        return self.net(feat).squeeze(-1)
+
+
+class DotScorer(nn.Module):
+    """Allowed simpler baseline: s_i = h_c^T h_{o,i} / sqrt(d)."""
+
+    def __init__(self, hidden_size: int):
+        super().__init__()
+        self.scale = hidden_size ** 0.5
+
+    def forward(self, h_c: torch.Tensor, h_o: torch.Tensor) -> torch.Tensor:
+        # Match dtype if encoder/scorer mix bf16/fp32
+        if h_c.dtype != h_o.dtype:
+            h_o = h_o.to(dtype=h_c.dtype)
+        return torch.einsum("bd,bkd->bk", h_c, h_o) / self.scale
+
+
+@dataclass
+class SetBrierOutput:
+    """Forward bundle. ``probs`` is the inference distribution (same p as train)."""
+
+    logits: torch.Tensor  # masked s [B, Kmax]
+    probs: torch.Tensor  # p = softmax(s) [B, Kmax]
+    pred_index: torch.Tensor  # argmax among real options [B]
+    h_c: torch.Tensor
+    h_o: torch.Tensor
+
+
+class SetBrierEncoder(nn.Module):
+    """Decision encoder: Enc(context), Enc(options), score, masked softmax."""
+
+    def __init__(self, encoder: nn.Module, scorer: nn.Module):
+        super().__init__()
+        self.encoder = encoder
+        self.scorer = scorer
+
+    @property
+    def hidden_size(self) -> int:
+        return int(self.encoder.hidden_size)
+
+    def encode(self, input_ids: torch.Tensor, attention_mask: torch.Tensor) -> torch.Tensor:
+        return self.encoder(input_ids=input_ids, attention_mask=attention_mask)
+
+    def score_options(
+        self,
+        h_c: torch.Tensor,
+        h_o: torch.Tensor,
+        opt_mask: torch.Tensor,
+    ) -> torch.Tensor:
+        """Score options. Pad embeddings are zeroed; pad logits are -inf.
+
+        Pads are never allowed to contribute to ``p``: zeroing removes pad
+        *content* from the scorer, and ``masked_fill`` removes pad *slots*
+        from the softmax partition.
+        """
+        mask = opt_mask.unsqueeze(-1).to(dtype=h_o.dtype)
+        h_o_real = h_o * mask
+        logits = self.scorer(h_c, h_o_real)
+        return mask_option_logits(logits, opt_mask)
+
+    def forward(
+        self,
+        ctx_ids: torch.Tensor,
+        ctx_mask: torch.Tensor,
+        opt_ids: torch.Tensor,
+        opt_mask: torch.Tensor,
+        opt_attn: torch.Tensor,
+    ) -> SetBrierOutput:
+        """
+        ctx_ids: [B, Lc]
+        ctx_mask: [B, Lc]
+        opt_ids: [B, Kmax, Lo]
+        opt_mask: [B, Kmax]
+        opt_attn: [B, Kmax, Lo]
+        """
+        h_c = self.encode(ctx_ids, ctx_mask)
+        bsz, kmax, lo = opt_ids.shape
+        flat_ids = opt_ids.reshape(bsz * kmax, lo)
+        flat_attn = opt_attn.reshape(bsz * kmax, lo)
+        h_o = self.encode(flat_ids, flat_attn).reshape(bsz, kmax, -1)
+        logits = self.score_options(h_c, h_o, opt_mask)
+        # Live softmax — this is the inference p and the Brier p. Do not detach.
+        # Research hard rule: compute p in fp32 even when logits are bf16
+        # (pad -inf / partition stability for calibration).
+        probs = F.softmax(logits.float(), dim=-1)
+        pred_index = probs.argmax(dim=-1)
+        return SetBrierOutput(
+            logits=logits,
+            probs=probs,
+            pred_index=pred_index,
+            h_c=h_c,
+            h_o=h_o,
+        )
+
+    @torch.no_grad()
+    def decide(
+        self,
+        ctx_ids: torch.Tensor,
+        ctx_mask: torch.Tensor,
+        opt_ids: torch.Tensor,
+        opt_mask: torch.Tensor,
+        opt_attn: torch.Tensor,
+        option_texts: list[str],
+    ) -> dict[str, Any]:
+        """Serving contract: {choice, index, probs} with probs over real options."""
+        self.eval()
+        out = self.forward(ctx_ids, ctx_mask, opt_ids, opt_mask, opt_attn)
+        # Packed real options occupy mask=1 slots (collate puts them at 0..K-1).
+        # CPU copy for JSON only; this is not a calibration map.
+        probs = out.probs[0][opt_mask[0].bool()].cpu().float()
+        probs = probs.clamp_min(0)
+        z = probs.sum().clamp_min(1e-12)
+        probs = probs / z
+        index = int(out.pred_index[0].item())
+        return {
+            "choice": option_texts[index],
+            "index": index,
+            "probs": probs.tolist(),
+        }
+
+    def encoder_parameters(self):
+        return self.encoder.parameters()
+
+    def scorer_parameters(self):
+        return self.scorer.parameters()
+
+
+def build_tokenizer(cfg: dict[str, Any]):
+    backbone = cfg["backbone"]
+    if backbone.get("encoder", "huggingface") == "stub":
+        return HashTokenizer(vocab_size=int(backbone.get("stub_vocab_size", 256)))
+    from transformers import AutoTokenizer
+
+    return AutoTokenizer.from_pretrained(
+        backbone["model_id"],
+        revision=backbone["revision"],
+        trust_remote_code=bool(backbone.get("trust_remote_code", True)),
+    )
+
+
+def _torch_dtype(precision: str, device: torch.device) -> Optional[torch.dtype]:
+    if precision == "bf16" and device.type == "cuda" and torch.cuda.is_bf16_supported():
+        return torch.bfloat16
+    return torch.float32
+
+
+def build_model(cfg: dict[str, Any], device: Optional[torch.device] = None) -> SetBrierEncoder:
+    """Build SetBrierEncoder from config. Stub path never touches HuggingFace weights."""
+    device = device or torch.device("cpu")
+    backbone = cfg["backbone"]
+    scorer_cfg = cfg["scorer"]
+    mode = backbone.get("encoder", "huggingface")
+    precision = cfg["train"].get("precision", "fp32")
+    dtype = _torch_dtype(precision, device)
+
+    if mode == "stub":
+        hidden = int(backbone.get("stub_hidden_size", backbone.get("hidden_size", 32)))
+        encoder: nn.Module = StubEncoder(
+            vocab_size=int(backbone.get("stub_vocab_size", 256)),
+            hidden_size=hidden,
+        )
+    elif mode == "huggingface":
+        encoder = HuggingFaceEncoder(
+            model_id=backbone["model_id"],
+            revision=backbone["revision"],
+            trust_remote_code=bool(backbone.get("trust_remote_code", True)),
+            torch_dtype=dtype if dtype != torch.float32 else None,
+            lora=cfg["train"].get("lora"),
+        )
+        hidden = encoder.hidden_size
+    else:
+        raise ValueError(f"unknown backbone.encoder {mode!r}")
+
+    stype = scorer_cfg.get("type", "mlp")
+    if stype == "mlp":
+        scorer: nn.Module = MLPScorer(
+            hidden_size=hidden,
+            mlp_hidden=int(scorer_cfg.get("hidden_size", hidden)),
+            dropout=float(scorer_cfg.get("dropout", 0.0)),
+        )
+    elif stype == "dot":
+        scorer = DotScorer(hidden_size=hidden)
+    else:
+        raise ValueError(f"unknown scorer.type {stype!r}; use 'mlp' or 'dot'")
+
+    model = SetBrierEncoder(encoder, scorer)
+    model.to(device)
+    # Keep encoder+scorer on the same compute dtype (bf16 on H100). Softmax p
+    # stays fp32 in forward() — that is the calibration contract.
+    if dtype == torch.bfloat16:
+        model.to(dtype=dtype)
+    return model

pivot_serving_schema.py

@@ -0,0 +1,68 @@
+"""Pivot-Alpha / Jev-aligned typed decision schema (English).
+
+Jev: unstructured state in → typed probabilistic decisions out.
+We are NOT a free-text generator. Each call returns structured decisions
+the host program can wire into a workflow.
+"""
+from __future__ import annotations
+
+from typing import Any, Literal, Optional
+
+Primitive = Literal["choice", "noul", "score"]
+
+
+def build_typed_decision(
+    *,
+    decision_id: str,
+    primitive: Primitive,
+    options: list[str],
+    index: int,
+    probs: list[float],
+    description: Optional[str] = None,
+) -> dict[str, Any]:
+    if len(options) != len(probs):
+        raise ValueError("options/probs length mismatch")
+    if not (0 <= index < len(options)):
+        raise ValueError("index out of range")
+    # named map for program consumption
+    prob_map = {str(opt): float(p) for opt, p in zip(options, probs)}
+    value = options[index]
+    out: dict[str, Any] = {
+        "id": decision_id,
+        "primitive": primitive,
+        "description": description,
+        "options": list(options),
+        "index": int(index),
+        "value": value,
+        "probs": prob_map,
+        "prob_vector": [float(p) for p in probs],
+        "confidence": float(max(probs) if probs else 0.0),
+    }
+    if primitive == "noul":
+        # binary probabilistic decision (yes-mass = prob of first true-like option if present)
+        true_aliases = {"true", "yes", "y", "1"}
+        true_idx = next((i for i, o in enumerate(options) if str(o).lower() in true_aliases), index)
+        out["p_true"] = float(probs[true_idx])
+    if primitive == "score":
+        # expected score if options are ordered numeric levels; else keep categorical
+        try:
+            levels = [float(o) for o in options]
+            out["expected"] = float(sum(l * p for l, p in zip(levels, probs)))
+        except ValueError:
+            out["expected"] = None
+    return out
+
+
+def build_response(
+    *,
+    state: str,
+    decisions: list[dict[str, Any]],
+    model_id: str = "Pivot-Alpha",
+) -> dict[str, Any]:
+    return {
+        "model": model_id,
+        "contract": "unstructured_state_in__typed_probabilistic_decisions_out",
+        "state": state,
+        "decisions": decisions,
+        "schema_version": "pivot-alpha-v1",
+    }

predict_example.py

@@ -0,0 +1,9 @@
+from pathlib import Path
+import json
+from transformers import AutoModel, AutoTokenizer
+
+root = Path(__file__).resolve().parent
+tokenizer = AutoTokenizer.from_pretrained(root, trust_remote_code=True, local_files_only=True)
+model = AutoModel.from_pretrained(root, trust_remote_code=True, local_files_only=True).eval()
+request = json.loads((root / "serving/example_request.json").read_text())
+print(json.dumps(model.decide(tokenizer, **request), indent=2))

provenance.json

@@ -0,0 +1,46 @@
+{
+  "source": {
+    "type": "huggingface_dataset",
+    "repo": "Yinhaoc/dsbt-cleared-corpus-v1",
+    "revision": "0afd5031a19ece346b3287b8804ebb6b7c5a276d",
+    "file": "best.pt"
+  },
+  "checkpoint_sha256": "73d1d2959409229825a39e5a0136cae38541cd5a22d7b4836061683da96d59c8",
+  "created_utc": "2026-09-20T21:55:59.682825+00:00",
+  "checkpoint": {
+    "epoch": 0,
+    "global_step": 3102,
+    "extra": {
+      "epoch": 0,
+      "warmup": true,
+      "steps_per_sec": 1.8812464419600063,
+      "train_L_dec": 0.5377311386806899,
+      "train_L_cal": 0.040688835784281306,
+      "train_acc": 0.7659171502256609,
+      "val_acc": 0.319091796875,
+      "val_brier": 0.11288549791788682,
+      "val_ece": 0.1171102523803711,
+      "seconds": 1648.9068133831024
+    },
+    "completed_epochs": 1,
+    "optimizer_present": true,
+    "base_model": "LiquidAI/LFM2.5-Encoder-350M",
+    "base_revision": "b886781f7c6f10ca9b7096e21b83e30a073c2f39",
+    "configured_epochs": 4,
+    "evaluation_batch_saved": false,
+    "note": "best.pt is the best epoch, not proof of the final training epoch or eval progress."
+  },
+  "source_sha256": {
+    "__init__.py": "0143657a43a2b1fe4bc7196971f4792087ed0d32ef426c248a2e2474863ea4d9",
+    "__main__.py": "df98998af529a0dc97c09725fe512169bdc6c4dd718c908cc381c16de6d904f0",
+    "config.py": "3970b69bb4893c5f113dbac75fee901c43c9905a8733789beaec40fe32f7e1df",
+    "data.py": "21919e9fd760df1665ac27cc1f63df86edaa312101ccc1c008a0770ce00593da",
+    "eval.py": "3e986c0ae827d9457ee1016dedf405cfd21f25b56bc209249427a8c1b62652e9",
+    "infer.py": "be72f8a76ac22a8a1cc93d946b61cad499e0c63dac5d54d4b671f7329b8176b5",
+    "losses.py": "01a7f50adb43b563cfc66d7bc5782a75e9a1cf7f9170dc86ffaee46a6c702c3d",
+    "model.py": "8b17e60eca7f2a54d8579fc88cff8eb70cd1202222e8872c7e3447772df61724",
+    "seed.py": "8549ad3cdf0cca42c777b50943101ebddf6bee02e336b5b7f43c4068916b3f5d",
+    "serving_schema.py": "8a777f03e595b675dd2d0eb6c12a9247990bb48dd794bb0a806d1c18e297159a",
+    "train.py": "8276a95b8d2b6d5f5dfe5cb9072c9b5ee4fa9fb8e401e8e2ebaaff4d5c0ce369"
+  }
+}

requirements.txt

@@ -0,0 +1,4 @@
+torch==2.8.0
+transformers==5.17.0
+safetensors==0.8.0
+numpy==1.26.4

run_metrics.json

@@ -0,0 +1,13 @@
+{
+  "mode": "export_only",
+  "training": "not_run",
+  "frozen_eval": {
+    "status": "skipped",
+    "reason": "user_requested_export_only"
+  },
+  "latency_benchmark": "not_run",
+  "typed_smoke": "passed",
+  "safetensors": true,
+  "onnx": "not_exported",
+  "jev_win_verified": false
+}

serving/example_request.json

@@ -0,0 +1,32 @@
+{
+  "state": "Customer dispute: invoice 120 vs PO 100, age=3d, region=US",
+  "questions": [
+    {
+      "id": "route",
+      "primitive": "choice",
+      "options": [
+        "billing",
+        "tech",
+        "sales"
+      ]
+    },
+    {
+      "id": "approve",
+      "primitive": "noul",
+      "options": [
+        "true",
+        "false"
+      ]
+    },
+    {
+      "id": "severity",
+      "primitive": "score",
+      "options": [
+        "0",
+        "1",
+        "2",
+        "3"
+      ]
+    }
+  ]
+}

serving/example_response.json

@@ -0,0 +1,79 @@
+{
+  "model": "Pivot",
+  "contract": "unstructured_state_in__typed_probabilistic_decisions_out",
+  "state": "Customer dispute: invoice 120 vs PO 100, age=3d, region=US",
+  "decisions": [
+    {
+      "id": "route",
+      "primitive": "choice",
+      "description": null,
+      "options": [
+        "billing",
+        "tech",
+        "sales"
+      ],
+      "index": 0,
+      "value": "billing",
+      "probs": {
+        "billing": 0.709779679775238,
+        "tech": 0.013995149172842503,
+        "sales": 0.27622511982917786
+      },
+      "prob_vector": [
+        0.709779679775238,
+        0.013995149172842503,
+        0.27622511982917786
+      ],
+      "confidence": 0.709779679775238
+    },
+    {
+      "id": "approve",
+      "primitive": "noul",
+      "description": null,
+      "options": [
+        "true",
+        "false"
+      ],
+      "index": 1,
+      "value": "false",
+      "probs": {
+        "true": 0.44199028611183167,
+        "false": 0.5580097436904907
+      },
+      "prob_vector": [
+        0.44199028611183167,
+        0.5580097436904907
+      ],
+      "confidence": 0.5580097436904907,
+      "p_true": 0.44199028611183167
+    },
+    {
+      "id": "severity",
+      "primitive": "score",
+      "description": null,
+      "options": [
+        "0",
+        "1",
+        "2",
+        "3"
+      ],
+      "index": 3,
+      "value": "3",
+      "probs": {
+        "0": 0.007189917378127575,
+        "1": 0.22580669820308685,
+        "2": 0.04488111659884453,
+        "3": 0.7221222519874573
+      },
+      "prob_vector": [
+        0.007189917378127575,
+        0.22580669820308685,
+        0.04488111659884453,
+        0.7221222519874573
+      ],
+      "confidence": 0.7221222519874573,
+      "expected": 2.4819356873631477
+    }
+  ],
+  "schema_version": "pivot-alpha-v1"
+}

serving/schema.json

@@ -0,0 +1,101 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Pivot typed decision response",
+  "type": "object",
+  "required": [
+    "model",
+    "contract",
+    "state",
+    "decisions",
+    "schema_version"
+  ],
+  "properties": {
+    "model": {
+      "const": "Pivot"
+    },
+    "state": {
+      "type": "string"
+    },
+    "contract": {
+      "const": "unstructured_state_in__typed_probabilistic_decisions_out"
+    },
+    "schema_version": {
+      "const": "pivot-alpha-v1"
+    },
+    "decisions": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "primitive",
+          "options",
+          "index",
+          "value",
+          "probs",
+          "prob_vector",
+          "confidence"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "primitive": {
+            "enum": [
+              "choice",
+              "noul",
+              "score"
+            ]
+          },
+          "options": {
+            "type": "array",
+            "minItems": 2,
+            "items": {
+              "type": "string"
+            }
+          },
+          "index": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "value": {
+            "type": "string"
+          },
+          "probs": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1
+            }
+          },
+          "prob_vector": {
+            "type": "array",
+            "items": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1
+            }
+          },
+          "confidence": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1
+          },
+          "p_true": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1
+          },
+          "expected": {
+            "type": [
+              "number",
+              "null"
+            ]
+          }
+        }
+      }
+    }
+  }
+}

tokenizer_config.json

@@ -0,0 +1,12 @@
+{
+  "backend": "tokenizers",
+  "bos_token": "<|startoftext|>",
+  "clean_up_tokenization_spaces": false,
+  "eos_token": "<|im_end|>",
+  "is_local": false,
+  "local_files_only": false,
+  "mask_token": "<|mask|>",
+  "model_max_length": 1000000000000000019884624838656,
+  "pad_token": "<|pad|>",
+  "tokenizer_class": "TokenizersBackend"
+}