---

name: classification description: "Use Simple Transformers classification APIs for text, sentence-pair, multilabel, LayoutLM/document, multimodal, regression, ONNX, and reranking workflows." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Simple Transformers Classification Sub-skill

Use this sub-skill when the user wants discriminative classification or cross-encoder reranking with the public simpletransformers.classification APIs. It is self-contained: do not send future agents to the source checkout, repo docs, tests, or examples for routine usage.

Owns

• Binary text classification with ClassificationModel.
• Multiclass text classification with ClassificationModel(num_labels=N).
• Regression with ClassificationModel(num_labels=1) and ClassificationArgs(regression=True) or args={"regression": True}.
• Sentence-pair classification/regression using text_a, text_b, labels DataFrames and predict([[text_a, text_b], ...]).
• Multi-label text classification with MultiLabelClassificationModel and multi-hot list labels.
• LayoutLM/LayoutLMv2 document-style classification with text, labels, x0, y0, x1, y1 list columns and normalized 0-1000 boxes.
• Multimodal text+image classification with MultiModalClassificationModel.
• Cross-encoder reranker-style use of ClassificationModel.rerank() and sentence-pair predict() scores.
• Classification model conversion helpers such as convert_to_onnx() and shared CPU-safe args for output/cache handling.

Route elsewhere

• Named entity recognition and extractive question answering: token-and-qa.
• T5, Seq2Seq, language modeling, language generation, and text-to-text classification/question generation: generative-workflows.
• Dense retrieval, representation vectors, DPR, BEIR/MSMARCO data ownership, and retrieval-model reranking: retrieval-representation.
• Package installation, shared ModelArgs, Streamlit viewer, CUDA policy, and cross-task output/cache conventions belong to the root skill.

Read first

1. API reference for constructor signatures, methods, return shapes, supported model-type strings, and compatibility notes.
2. Data formats before preparing any DataFrame, lazy-loading file, LayoutLM box table, multimodal table, or reranking data.
3. Workflows for train/eval/predict recipes that do not require opening original examples.
4. Troubleshooting when imports fail, data is silently misread, model downloads start unexpectedly, ONNX conversion fails, or multimodal/LayoutLM inputs are rejected.

Safe defaults

Prefer explicit CPU-safe construction unless the user asks for GPU execution:

from simpletransformers.classification import ClassificationArgs, ClassificationModel

args = ClassificationArgs()
args.no_save = True                 # avoid writing checkpoints in smoke runs
args.overwrite_output_dir = True    # required if reusing an output_dir
args.reprocess_input_data = True    # avoid stale cached features while debugging
args.max_seq_length = 128
args.scheduler = "constant_schedule"  # small smoke runs often do not need warmup

model = ClassificationModel(
    "roberta",
    "roberta-base",
    args=args,
    use_cuda=False,
)

For real training, let the user choose a writable output_dir, remove no_save=True, and consider evaluate_during_training, save_best_model, and checkpoint retention settings from the root configuration reference.

Data validation helper

Before training or evaluating, validate tabular inputs with the bundled helper:

python scripts/validate_classification_data.py --help
python scripts/validate_classification_data.py --task single --input train.csv
python scripts/validate_classification_data.py --task sentence-pair --input pairs.csv
python scripts/validate_classification_data.py --task multilabel --input multilabel.jsonl --num-labels 6
python scripts/validate_classification_data.py --task layoutlm --input layout.jsonl
python scripts/validate_classification_data.py --task multimodal --input mm.csv --image-root images --check-image-exists

The script performs deterministic schema checks only. It does not import Simple Transformers, download models, train, evaluate, or contact the network. Use non-zero exits as data-preparation blockers.

Required decision points

• Single text vs sentence pair: choose text/labels or text_a/text_b/labels explicitly. If a DataFrame contains both shapes, Simple Transformers will prefer text/labels; fix ambiguous columns first.
• Label semantics: binary and multiclass labels are integer class ids; regression labels are floats; multi-label labels are list-like multi-hot vectors of only 0/1 values.
• Class count: pass num_labels for multiclass, multilabel, and regression (num_labels=1). For custom string labels, set labels_list/labels_map where supported and verify the mapped predictions.
• Long documents: ClassificationArgs.sliding_window=True avoids hard truncation for long single-text classification; it is not implemented for multi-label and cannot be combined with lazy loading.
• LayoutLM: box lists must align with whitespace word count and contain normalized integer coordinates in [0, 1000] with x0 <= x1 and y0 <= y1.
• Multimodal: the DataFrame path stores relative image filenames in images; image_path points to the directory containing those images. MultiModalClassificationModel only supports model_type="bert".
• Reranking: ClassificationModel.rerank() is for cross-encoder scoring; retrieval dataset construction and dense retrieval ownership are routed to retrieval-representation.

Minimal API map

• Text/sentence-pair/regression/LayoutLM: ClassificationModel, ClassificationArgs.
• Multi-label text: MultiLabelClassificationModel, MultiLabelClassificationArgs.
• Text+image multimodal: MultiModalClassificationModel, MultiModalClassificationArgs.
• Core methods: train_model(), eval_model(), predict(), rerank(), convert_to_onnx().
• Custom classification losses recognized by ClassificationModel through args.loss_type: "focal", "dice", or "tversky" with loss_args.

Verification status carried into this sub-skill

• The public signatures and dataclass fields in this sub-skill were checked against Simple Transformers 0.70.8 source and package-inspection evidence.
• A safe native candidate named test_custom_model_post_init is relevant to custom classification heads and Transformers compatibility.
• Full native classification tests and examples download Hugging Face models and run training; they are skipped by default unless the user explicitly approves time, network/model cache, and compute budget.

Common next steps

1. Identify which classification family the user wants.
2. Validate the data schema using data formats and the helper script.
3. Instantiate the right model class with use_cuda=False for CPU-only or smoke runs.
4. Run the smallest possible train_model()/eval_model()/predict() loop, then expand epochs, metrics, outputs, and backend settings only after schema and import issues are resolved.
5. If errors mention import aliases, MMBT, ONNX, cache reuse, pytrec, images, or LayoutLM boxes, consult troubleshooting before changing model architecture.