USAGE.txt

MATILDA-jev v1 — MATILDA configuration edition

This is a packaging revision of the existing uploaded v1 checkpoint, not the newer augmented-data training run.
Repository: https://huggingface.co/Maincode/matilda-jev-v1
For download and installation instructions, see README.md.

The model weights, decision readout, answer vocabulary, tokenizer vocabulary,
preprocessing and calibration are unchanged. Configurations expose MATILDA
class names.

Tested environment: Python 3.12, Transformers 5.17.0, PyTorch 2.14.0, AMD MI355X.
Use a PyTorch build matching the accelerator (torch 2.14.0, torchvision 0.29.0),
plus requirements-runtime.txt.

LOAD THE BACKBONE AND PROCESSOR

  import torch
  from transformers import AutoModel, AutoProcessor

  path = "./matilda-jev-v1"   # hf download Maincode/matilda-jev-v1 --local-dir ./matilda-jev-v1
  processor = AutoProcessor.from_pretrained(
      path, trust_remote_code=True, local_files_only=True)
  backbone = AutoModel.from_pretrained(
      path, trust_remote_code=True, local_files_only=True,
      dtype=torch.bfloat16, attn_implementation="sdpa").to("cuda")

AutoModel returns the backbone hidden states. For JEV choice/noul/score decisions,
use the bundled runtime below, which also loads readout.safetensors and calibration.
This checkpoint is a decision model and does not have a text-generation LM head.

START THE DECISION API

  MODEL_DIR=./matilda-jev-v1
  PYTHONPATH="$MODEL_DIR/runtime" PYTHONNOUSERSITE=1 \
    python -m maincode_jev_serve.server \
    --checkpoint "$MODEL_DIR" --model-name matilda-jev-v1 \
    --host 127.0.0.1 --port 8083

The bundled runtime is adapted to the new custom loading classes. Use it in place
of the older installed runtime for this edition. The API still accepts the same
POST /v1/systemone requests.

CONTINUED TRAINING

With MODEL_DIR/runtime on PYTHONPATH:

  from maincode_jev_serve.model import DecisionModel
  model = DecisionModel(checkpoint=path, train=True, device="cuda",
                        gradient_checkpointing=True)

Keep using the JEV decision loss/readout, not a causal-language-model trainer.
Use a NEW output directory when saving to preserve this validated release.

LOCAL VALIDATION

TEST_REPORT.json records configuration serialization, processor parity, real GPU
inference parity and a forward/backward training check without an optimizer update.
The 25-question smoke suite is not a full benchmark evaluation.