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
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
| Option | Default | Description |
|---|---|---|
model | required | Iris TrainableModel |
training_dataset | required | PyTorch dataset used for optimization |
output_dir | required | Directory for checkpoints, the manifest, and training outputs |
run_name | output directory name | Human-readable run and exported-artifact name |
validation_dataset | None | Optional validation dataset |
optimizer | None | Custom optimizer; when omitted, the model adapter uses its model config |
scheduler | None | Optional custom scheduler; overrides the adapter-built scheduler |
epochs | 10 | Total epoch count, including restored epochs |
batch_size | 4 | Samples per micro-batch |
device | None | Explicit device; CUDA is selected automatically when available |
num_workers | 0 | DataLoader worker count |
gradient_clip_norm | 0.1 | Maximum gradient norm; None disables clipping |
precision | Precision.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_steps | 1 | Micro-batches accumulated per optimizer update |
evaluation_interval | 1 | Epochs between validation runs; the final epoch is always evaluated |
checkpoint_interval | 1 | Epochs between numbered checkpoints |
training_images_to_log | 4 | Augmented training previews logged each epoch |
validation_images_to_log | 4 | Validation previews logged per evaluation |
seed | 42 | Python, NumPy, and PyTorch random seed |
metric_logger | None | Optional TensorBoardMetricLogger |
on_epoch_end | None | Callback receiving (epoch, metrics) after every epoch |
Methods
| Method | Returns | Description |
|---|---|---|
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) | None | Saves model, adapter, optimizer, scheduler, scaler, history, and metadata |
load_checkpoint(path) | None | Restores 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.
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.