Python API

These pages are generated from the source with mkdocstrings by static analysis. The signatures and docstrings you read here are the ones in the release the site was built from.

The top-level package

Fine-tune small language models to answer bounded decisions by logit readout.

A decision here is one question about one state with a closed set of options. The model never writes the answer: the options are rendered as lettered slots and the answer is a softmax over the token ids of those letters at a single position. That makes a malformed answer structurally impossible and the result deterministic.

from typedecide import load_decisions, validate, group_split, finetune, evaluate

decisions = load_decisions("tickets.csv")
report = validate(decisions)
if not report.ok:
    raise SystemExit(report.render())

train, held = group_split(decisions, eval_fraction=0.2, seed=0)
config = TrainConfig(base_model="Qwen/Qwen3-0.6B", output_dir=Path("runs/lora"))
result = finetune(train, config)
print(evaluate(held, "Qwen/Qwen3-0.6B", adapter=result.adapter_dir, debias="cyclic").render())

Score with debias="cyclic" unless you have a reason not to. Small models carry a strong preference for whichever option is listed first, and plain accuracy hides it completely -- see order_consistency in the result, which is the number that shows it.

Heavy dependencies are optional extras. import typedecide pulls in neither torch nor transformers; the module that needs one imports it, and says which extra to install if it is missing.

What import typedecide gives you

Imported eagerly (standard library only):

Name	From
Option, Criterion, Decision, LETTERS, MIN_OPTIONS, MAX_OPTIONS	typedecide.schema
decision_from_dict, decision_to_dict, fingerprint	typedecide.schema
INSTRUCTION, head_text, tail_text, full_prompt, answer_slots	typedecide.prompt
TypeDecideError and its subclasses	typedecide.errors
__version__	the package

Resolved lazily on first attribute access, so that import typedecide never imports a heavy dependency:

Name	Resolves to
load_decisions, write_decisions	typedecide.data.loaders
validate	typedecide.data.validate
group_split	typedecide.data.split
finetune	typedecide.training.trainer
TrainConfig	typedecide.training.config
evaluate, EvalResult	typedecide.evaluation.runner
export_onnx, ExportConfig	typedecide.export.onnx

import typedecide
from typedecide import load_decisions            # works: resolved lazily
from typedecide.data import FieldMapping          # subpackage imports always work

Subpackages

Package	Public names (__all__)
typedecide.data	FieldMapping, load_decisions, write_decisions, validate, DataReport, Finding, estimate_tokens, DEFAULT_MAX_STATE_TOKENS, group_split, randomise_option_order, all_rotations, all_permutations
typedecide.training	TrainConfig, finetune, TrainResult, DecisionDataset, AnswerTokenCollator, build_example, answer_slots_for, labelled_only, pad_batch, reorder_options, build_manifest, write_manifest, library_versions, seed_everything, IGNORE_INDEX, MANIFEST_NAME, LORA_TARGET_MODULES, LR_SCHEDULER_TYPE, WARMUP_RATIO, LOGGING_STEPS
typedecide.evaluation	evaluate, evaluate_with_scorer, EvalResult, orderings, DEBIAS_MODES, NULL_STATE, ScoreFn, ScoreRequest, TorchReadout, load_readout, accuracy, balanced_accuracy, mean_group_balanced_accuracy, expected_calibration_error, brier_score, order_consistency, letter_distribution, chance_accuracy
typedecide.export	ExportConfig, export_onnx, trim_logits_to_last_position, prune_lm_head, answer_letter_token_ids, answer_letter_slots, SlotMap, build_slot_map, read_slot_map, write_slot_map, select_rows, validate_keep, lm_head_savings, SLOT_MAP_FILENAME, quantize, resolve_mode, QuantizationTier, QUANTIZATION_MODES

Names beginning with an underscore are private and may change in any release. See Versioning and deprecation for what counts as public.

Typing

The package is fully annotated and checked with mypy --strict in CI.