Skip to content

Configuration ​

SUMMARY

Model configs own architecture, augmentation, optimizer, scheduler, and family-specific training behavior. The shared Trainer owns the training loop, device, precision, batching, evaluation, logging, and checkpoints.

Trainer Reference ​

python
from telekinesis.iris import trainer

model_trainer = trainer.Trainer(
    model=model,
    training_dataset=training_dataset,
    output_dir="results/run",
    validation_dataset=validation_dataset,
    epochs=100,
    batch_size=4,
)
history = model_trainer.train(resume_from=None)

Constructor Options ​

OptionDefaultDescription
modelrequiredIris TrainableModel
training_datasetrequiredPyTorch dataset used for optimization
output_dirrequiredDirectory for checkpoints, the manifest, and training outputs
run_nameoutput directory nameHuman-readable run and exported-artifact name
validation_datasetNoneOptional validation dataset
optimizerNoneCustom optimizer; when omitted, the model adapter uses its model config
schedulerNoneOptional custom scheduler; overrides the adapter-built scheduler
epochs10Total epoch count, including restored epochs
batch_size4Samples per micro-batch
deviceNoneExplicit device; CUDA is selected automatically when available
num_workers0DataLoader worker count
gradient_clip_norm0.1Maximum gradient norm; None disables clipping
precisionPrecision.AUTO ("auto")Arithmetic mode: "auto", "fp32", "fp16", or "bf16". Auto uses BF16 on supported CUDA devices, FP16 on other CUDA devices, and FP32 on CPU.
gradient_accumulation_steps1Micro-batches accumulated per optimizer update
evaluation_interval1Epochs between validation runs; the final epoch is always evaluated
checkpoint_interval1Epochs between numbered checkpoints
training_images_to_log4Augmented training previews logged each epoch
validation_images_to_log4Validation previews logged per evaluation
seed42Python, NumPy, and PyTorch random seed
metric_loggerNoneOptional TensorBoardMetricLogger
on_epoch_endNoneCallback receiving (epoch, metrics) after every epoch

Methods ​

MethodReturnsDescription
train(resume_from=None, reset_best_metric=False)list[dict[str, float]]Runs training; optionally restores a checkpoint and resets best-model selection
resume(checkpoint_path)list[dict[str, float]]Convenience wrapper around train(resume_from=...)
evaluate(dataset=None)dict[str, float]Evaluates a supplied dataset or the configured validation dataset
save_checkpoint(path, epoch=..., monitored_metric=None, monitored_value=None)NoneSaves model, adapter, optimizer, scheduler, scaler, history, and metadata
load_checkpoint(path)NoneRestores training state and advances the starting epoch

precision accepts either a string or the corresponding trainer.Precision enum member: AUTO, FP32, FP16, or BF16.

Optimization Configuration ​

When no custom optimizer is passed to Trainer, the model adapter builds one from the model config. RF-DETR and SAM3-LoRA expose the fields directly; YOLOX accepts an OptimizationConfig object.

python
from telekinesis.iris import models
from telekinesis.iris.optimizer import OptimizationConfig

sam3_config = models.SAM3LoRAConfig(
    class_names={1: "part"},
    learning_rate=5e-5,
    weight_decay=0.01,
    scheduler="cosine",
    scheduler_interval="step",
)

yolox_config = models.YOLOXConfig(
    num_classes=1,
    category_ids=(1,),
    optimization=OptimizationConfig(
        optimizer="sgd",
        learning_rate=0.01,
        weight_decay=5e-4,
        optimizer_options={"momentum": 0.9, "nesterov": True},
        scheduler="cosine",
        scheduler_options={"min_factor": 0.05},
        scheduler_interval="step",
    ),
)

OptimizationConfig supports adam, adamw, and sgd; step, cosine, and plateau schedulers; optimizer/scheduler option dictionaries; scheduler_interval; an optional scheduler_monitor; and warmup_steps.

Model Configuration

See Train RF-DETR, Train SAM3-LoRA, and Train YOLOX for model-specific configuration options.