tlmtc 0.4.2

tlmtc (Transfer Learning for Multi-label Text Classification) is an opinionated Python package that provides production-ready, end-to-end workflows for fine-tuning pretrained encoder-only transformer models for robust multi-label text classification.

In applied settings, text classification is rarely a simple single-label task or a mutually exclusive multiclass problem. A clinical note may map to several ICD codes at once. A customer-support ticket can span multiple issue categories for routing, prioritization, and analytics. A contract may contain several clause types, and a litigation document can raise multiple legal issues. In RAG and LLM evaluation, a single answer may need several concurrent quality labels. A threat-intelligence report can mention multiple tactics, techniques, and vulnerabilities in the same document. Across domains, useful text labels often overlap, co-occur, and vary in prevalence.

tlmtc turns these use cases into repeatable training and prediction workflows. It prepares multi-label text data, fine-tunes transformer classifiers, tunes hyperparameters and decision thresholds, evaluates model performance, writes reports, and applies trained models to new data — all exposed through a small workflow-oriented API.

Key features

• Parameter-efficient fine-tuning via LoRA (PEFT), with optional full fine-tuning
• Automatic detection of single-text and paired-text inputs for encoder and cross-encoder-style classification
• Customizable Optuna-based hyperparameter tuning, optionally on a smaller proxy model for efficiency
• Carry-over from proxy to larger target model with optional automatic learning-rate scaling
• Global and label-specific threshold optimization for calibrated multi-label decisions
• Iterative stratified data splitting for multi-label datasets, with automatic group-aware splitting
• Custom class-weighted loss for handling label imbalance
• Comprehensive evaluation suite with global and label-specific multi-label metrics
• Publication-ready reporting through tables and graphs
• End-to-end prediction workflow that reloads trained models, metadata, labels, and thresholds automatically
• Optional ONNX export and ONNX Runtime prediction backend for production inference deployment
• Automatic persistence and reuse of data splits, Optuna studies, trained models, thresholds, and run metadata
• Highly configurable through a small workflow-oriented Python API and CLI
• CPU and DDP-safe multi-GPU training and prediction support

Installation

Install tlmtc into your active Python environment with the train extra:

pip install "tlmtc[train]"

The train extra installs the dependencies required for the full training workflow and includes the Torch-backed prediction runtime.

Quickstart

This quickstart uses a small synthetic paired-text dataset included in the repository. It mimics a requirements-engineering setting, where requirement records are paired with validation, commissioning, configuration, or field-service evidence and labeled for multiple concurrent issues. You will fine-tune a multi-label classifier and then apply the trained model to unlabeled examples.

Create a working directory and download the example data:

mkdir tlmtc-quickstart
cd tlmtc-quickstart

curl -L -o paired_example.csv \
  https://raw.githubusercontent.com/saschagobel/tlmtc/main/examples/paired_example.csv

curl -L -o paired_example_unlabeled.csv \
  https://raw.githubusercontent.com/saschagobel/tlmtc/main/examples/paired_example_unlabeled.csv

The code below assumes that both CSV files are in your current working directory. If you save them somewhere else, adjust the file paths accordingly.

Fine-tune a model:

from tlmtc import train_tlmtc

train_tlmtc(
    labeled_data="paired_example.csv",
    target_name="Requirements Evidence Alignment",
    checkpoint="google/bert_uncased_L-2_H-128_A-2",
    tuning_trials=5,
    use_cpu=True,
)

This quickstart intentionally uses a tiny model and only five HPO trials to keep the demo lightweight.

Use your fine-tuned model to run prediction on unlabeled data:

from tlmtc import predict_tlmtc

predict_tlmtc(
    "paired_example_unlabeled.csv",
    use_cpu=True,
)

tlmtc writes training artifacts to train_outputs/ and prediction artifacts to prediction_outputs/. Evaluation reports are written to train_outputs/<run_id>/evaluation/.

For production inference, the optional onnx-export and onnx-runtime installation extras provide the dependencies for exporting trained models to ONNX and running the ONNX Runtime prediction backend, respectively.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening an issue or pull request.