Decision training contract
Decision Forge produces supervision for four organizational judgments: work allocation, information sharing, action selection, and outcome acceptance. Each training example asks the model to choose among explicit candidates using the available state and organizational policy.
Export candidate probabilities
uv run decision-forge build examples/customer_support/project.yaml --output runs/decisions
uv run decision-forge export runs/decisions --output runs/decision-training --format decision
uv run python scripts/finetune_evaluation.py prepare runs/decisions \
--output runs/training-plan --budget-examples 2000 --base-model your-base-model
The decision format exports JSONL with objective: candidate_readout:
| Field | Meaning |
|---|---|
id |
Stable episode identity |
system, input |
Model-visible task, state, and policy context |
options |
Ordered {key, description} candidates; descriptions include candidate IDs and decision-relevant attributes |
target_probs |
Probability target aligned with the original option order |
root_id, normalized_group |
Organization-scoped family identity shared by related variants |
scope, provenance |
Supervision basis, source hashes, rule references, and dataset digest |
weight |
Unit row weight |
A unique policy-verified best choice yields a one-hot target. Multiple best choices remain set-valued
in the canonical export and are skipped in decision export, with per-split counts in export.json.
Rule priority and rule scores determine policy decisions; they have no probability interpretation.
DecisionRow.model_validate(row) also accepts existing candidate-readout rows with explicit soft
probabilities. It preserves those probabilities, history, and additional metadata. Importers remain
responsible for verifying the original supervision and maintaining family splits. Validation checks
the schema and target alignment; it does not certify an external label's correctness.
Native candidate-label encoding
from decision_forge.training import DecisionRow, encode_decision
DecisionRow.model_validate(row)
encoded = encode_decision(row, tokenizer, seed=1015, max_tokens=8192)
The tokenizer supplies distinct single-token labels from A–Z, then AA–ZZ. A deterministic
per-row permutation moves candidate descriptions and their target probabilities together. The encoder
uses the tokenizer's native chat template with enable_thinking=False and an assistant generation
prefix. It appends no answer token. label_to_key maps the selected label back to the original option.
The tokenizer must support this template setting and be kept unchanged during encoding.
At the last prompt position, gather logits for candidate_token_ids and minimize:
loss = -sum(target_probs * log_softmax(candidate_logits))
The returned labels are all -100; the candidate-readout trainer computes the objective explicitly.
A trainer that only uses ordinary answer-token SFT loss cannot consume this encoding as a training
objective. Overlong prompts and insufficient distinct single-token labels produce errors. The encoder
never silently truncates policy context or candidates.
Only system, input, and candidate descriptions enter the prompt. Targets, family identifiers,
source references, and verification records stay outside model inputs. Exported policy context contains
the rules needed to decide, while per-example verdicts and the verified answer remain supervision.
Budgets and evaluation
prepare writes a decision export, an auditable plan.json, and handoff instructions. The budget
limits actual training file rows after eligibility checks, using deterministic episode-ID order.
Development and test splits retain their original eligible rows. The plan records selected IDs,
export file digests, actual counts, and the candidate-readout objective. It records status: prepared
and training_launched: false; a compatible trainer must execute the run.
Evaluate the trained checkpoint with candidate NLL, candidate accuracy, per-surface and per-stratum
accuracy, and held-out family performance. Preserve reference soft targets when calculating NLL.
The existing endpoint evaluate/compare commands separately measure generated-choice accuracy;
they do not measure candidate NLL or execute training. Use the same cases and prompt for both arms.
The production data path stays focused on organizational decisions. Workflow execution supplies states and feedback for those decisions. World-observation targets are excluded from this contract.