API reference

Public Python surface for TRLoom.

Quick usage

from trloom import FineTuneJob, load_config, run_from_yaml, available_methods

print(available_methods())

run_from_yaml("sft.yaml")

job = FineTuneJob.from_yaml("sft.yaml")
job.build()
job.run()

Job orchestration

trloom.job.FineTuneJob

FineTuneJob(config: FineTuneConfig)

Load a YAML config, build a TRL trainer, and run training end-to-end.

from_yaml classmethod

from_yaml(path: str | Path) -> FineTuneJob

Create a job from a YAML configuration file.

from_dict classmethod

from_dict(data: dict[str, Any]) -> FineTuneJob

Create a job from an in-memory configuration dictionary.

build

build() -> Any

Construct (but do not train) the underlying TRL trainer.

train

train() -> Any

Build the trainer if needed and run trainer.train().

run

run() -> Any

Alias for :meth:train — run the fine-tuning job end-to-end.

trloom.job.run_from_yaml

run_from_yaml(path: str | Path, *, use_modal: bool | None = None, use_kaggle: bool | None = None) -> Any

Load a YAML config and run the fine-tuning job.

Parameters

path: Path to a TRLoom YAML configuration file. use_modal: If True, force Modal execution. If False, never use Modal. If None, follow modal.enabled in the config (subject to Kaggle). use_kaggle: If True, force Kaggle execution. If False, never use Kaggle. If None, follow kaggle.enabled in the config (subject to Modal).

trloom.job.available_methods

available_methods(*, include_experimental: bool = True) -> list[str]

List training methods supported by the installed TRL version.

Configuration

trloom.config.schema.FineTuneConfig

Bases: BaseModel

Root configuration for a TRLoom fine-tuning job.

resolved_formatting_func

resolved_formatting_func() -> str | None

Trainer formatting_func import path (root overrides dataset).

resolved_backend

resolved_backend() -> Literal['local', 'modal', 'kaggle']

Return the execution backend implied by the config flags.

trloom.config.schema.ModelConfig

Bases: BaseModel

Model / PEFT / quantization settings (mirrors TRL ModelConfig fields).

trloom.config.schema.DatasetConfig

Bases: BaseModel

Dataset loading configuration.

Prefer path for a single Hub/local dataset, or datasets for a mixture.

Formatting (applied after load / rename, before training): - map_fn: import path applied via dataset.map - prompt_template: Jinja2 template rendered per row into prompt_output_column - formatting_func: import path forwarded to trainers that accept it (e.g. SFT)

trloom.config.schema.DatasetSourceConfig

Bases: BaseModel

A single dataset entry (Hub repo id or local path).

trloom.config.schema.WandbConfig

Bases: BaseModel

Weights & Biases logging settings.

trloom.config.schema.ModalConfig

Bases: BaseModel

Modal Labs remote execution settings.

trloom.config.schema.KaggleConfig

Bases: BaseModel

Kaggle Notebooks / GPU execution settings.

Modes: - auto: if already inside a Kaggle kernel, run inline; otherwise write a notebook - inline: run in the current process (intended for Kaggle kernels) - notebook: generate a Kaggle notebook (and optionally push via the API)

trloom.config.loader.load_config

load_config(source: str | Path | dict[str, Any]) -> FineTuneConfig

Load and validate a :class:FineTuneConfig from YAML or a dict.

When loading from a file, relative user_code paths are resolved against the YAML file's directory so Modal / local runs find the same modules.

Dataset formatting

trloom.data.formatting.format_dataset

format_dataset(dataset: Any, *, map_fn: str | Callable[..., Any] | None = None, map_kwargs: dict[str, Any] | None = None, prompt_template: str | None = None, prompt_output_column: str = 'text', prompt_remove_columns: list[str] | bool | None = None) -> Any

Run configured formatting steps on a single split.

Order: 1. map_fn (custom preprocess) 2. prompt_template (Jinja2 → prompt_output_column)

trloom.imports.resolve_callable

resolve_callable(spec: str, *, label: str = 'callable') -> Callable[..., Any]

Import and return a callable from an import-path string.

Accepted forms: - package.module:function - package.module.function

trloom.user_code.build_user_code_bundle

build_user_code_bundle(config: FineTuneConfig) -> dict[str, str]

Collect local Python sources referenced by the config for remote execution.

Kaggle

trloom.kaggle_support.run_on_kaggle

run_on_kaggle(config_path: str | Path, *, output_subdir: str | None = None) -> dict[str, Any]

Execute a YAML job on Kaggle (inline when in-kernel, else notebook / push).

trloom.kaggle_support.write_kaggle_notebook

write_kaggle_notebook(config_path: str | Path, destination: str | Path | None = None, *, write_metadata: bool = True) -> Path

Write a Kaggle notebook (and optional kernel-metadata.json) for a YAML job.

trloom.kaggle_support.is_kaggle_environment

is_kaggle_environment() -> bool

Return True when running inside a Kaggle Notebook / kernel.

Trainers

trloom.trainers.registry.list_trainers

list_trainers(*, include_experimental: bool = True) -> list[str]

Return sorted method names available from the installed TRL version.