Skip to main content

​
synth_ai.sdk.api.train.sft

Experimental First-class SDK API for SFT (Supervised Fine-Tuning). This module provides high-level abstractions for running SFT jobs both via CLI (uvx synth-ai train) and programmatically in Python scripts. Example CLI usage: 
uvx synth-ai train --type sft --config my_config.toml --poll
Example SDK usage: 
from synth_ai.sdk.api.train.sft import SFTJob

job = SFTJob.from_config("my_config.toml")
job.submit()
result = job.poll_until_complete()
print(f"Fine-tuned model: {result['fine_tuned_model']}")

​
synth_ai.sdk.api.train.configs.sft

SFT (Supervised Fine-Tuning) configuration models. This module defines the configuration schema for SFT training jobs. Paper: Beyond Human Data: Scaling Self-Training for Problem-Solving with Language Models (ReST-EM)

​
When to Use SFT

  • Cloning successful AI generations (ReST-EM style self-training)
  • Distilling from a larger model to a smaller one
  • Training on domain-specific data (code, medical, legal, etc.)
  • Teaching specific output formats or styles
  • Vision fine-tuning with image-text pairs
Example TOML configuration: 
[algorithm]
type = "offline"              # Required: "offline" for SFT
method = "sft"                # Required: "sft" or "supervised_finetune"

[job]
model = "Qwen/Qwen3-4B"       # Required: HuggingFace model identifier
data_path = "training_data.jsonl"  # Required: path to JSONL training data

[compute]
gpu_type = "H100"             # Required: GPU type (H100, H200, A100, etc.)
gpu_count = 1                 # Required: number of GPUs

[training]
mode = "lora"                 # "full", "lora", or "qlora"

[training.lora]
r = 16                        # LoRA rank
alpha = 32                    # LoRA alpha scaling
dropout = 0.1                 # LoRA dropout

[hyperparameters]
n_epochs = 3                  # Number of training epochs
batch_size = 4                # Training batch size
learning_rate = 2e-5          # Optimizer learning rate
sequence_length = 2048        # Maximum sequence length
See Also:
  • Training reference: /training/sft
  • Quickstart: /quickstart/supervised-fine-tuning

​
Job API

​
SFTJobConfig

Configuration for an SFT job.

​
SFTJob

High-level SDK class for running SFT jobs. This class provides a clean API for:
  1. Submitting SFT jobs
  2. Polling job status
  3. Retrieving results
Methods:

​
from_config

from_config(cls, config_path: str | Path, backend_url: Optional[str] = None, api_key: Optional[str] = None, dataset_override: Optional[str | Path] = None, allow_experimental: Optional[bool] = None, overrides: Optional[Dict[str, Any]] = None) -> SFTJob
Create a job from a TOML config file. Args:
  • config_path: Path to TOML config file
  • backend_url: Backend API URL (defaults to env or production)
  • api_key: API key (defaults to SYNTH_API_KEY env var)
  • dataset_override: Override dataset path from config
  • allow_experimental: Allow experimental models
  • overrides: Config overrides
Returns:
  • SFTJob instance
Raises:
  • ValueError: If required config is missing
  • FileNotFoundError: If config file doesn’t exist

​
from_job_id

from_job_id(cls, job_id: str, backend_url: Optional[str] = None, api_key: Optional[str] = None) -> SFTJob
Resume an existing job by ID. Args:
  • job_id: Existing job ID
  • backend_url: Backend API URL (defaults to env or production)
  • api_key: API key (defaults to SYNTH_API_KEY env var)
Returns:
  • SFTJob instance for the existing job

​
submit

submit(self) -> str
Submit the job to the backend. Returns:
  • Job ID
Raises:
  • RuntimeError: If job submission fails

​
job_id

job_id(self) -> Optional[str]
Get the job ID (None if not yet submitted).

​
get_status

get_status(self) -> Dict[str, Any]
Get current job status. Returns:
  • Job status dictionary
Raises:
  • RuntimeError: If job hasn’t been submitted yet

​
poll_until_complete

poll_until_complete(self) -> Dict[str, Any]
Poll job until it reaches a terminal state. Args:
  • timeout: Maximum seconds to wait
  • interval: Seconds between poll attempts
  • on_status: Optional callback called on each status update
Returns:
  • Final job status dictionary
Raises:
  • RuntimeError: If job hasn’t been submitted yet
  • TimeoutError: If timeout is exceeded

​
get_fine_tuned_model

get_fine_tuned_model(self) -> Optional[str]
Get the fine-tuned model ID from completed job. Returns:
  • Fine-tuned model ID or None if not available

​
Configuration Reference

​
JobConfig

Core job configuration for SFT. Attributes:
  • model: Base model to fine-tune (e.g., “Qwen/Qwen3-4B”, “meta-llama/Llama-3-8B”).
  • data: Dataset identifier (if using registered datasets).
  • data_path: Path to JSONL training data file.
  • poll_seconds: Polling interval for job status. Default: 10.

​
SFTDataConfig

Data configuration for SFT training. Attributes:
  • topology: Data loading topology configuration.
  • validation_path: Path to validation JSONL file for eval during training.

​
TrainingValidationConfig

Validation configuration during training. Attributes:
  • enabled: Enable validation during training. Default: False.
  • evaluation_strategy: When to evaluate - “steps” or “epoch”.
  • eval_steps: Evaluate every N steps (if strategy is “steps”).
  • save_best_model_at_end: Save only the best model checkpoint.
  • metric_for_best_model: Metric to use for best model selection (e.g., “eval_loss”).
  • greater_is_better: Whether higher metric is better. Default: False for loss.

​
TrainingConfig

Training mode configuration. Attributes:
  • mode: Training mode - “lora”, “qlora”, or “full”.
  • use_qlora: Enable QLoRA (4-bit quantized LoRA). Default: False.
  • validation: Validation configuration.
  • lora: LoRA hyperparameters (r, alpha, dropout, target_modules).

​
HyperparametersParallelism

Parallelism configuration for distributed training. Attributes:
  • use_deepspeed: Enable DeepSpeed. Default: False.
  • deepspeed_stage: DeepSpeed ZeRO stage (1, 2, or 3).
  • fsdp: Enable PyTorch FSDP. Default: False.
  • bf16: Use bfloat16 precision. Default: True on supported hardware.
  • fp16: Use float16 precision. Default: False.
  • activation_checkpointing: Enable gradient checkpointing. Default: False.
  • tensor_parallel_size: Tensor parallelism degree.
  • pipeline_parallel_size: Pipeline parallelism degree.

​
HyperparametersConfig

Training hyperparameters for SFT. Attributes:
  • n_epochs: Number of training epochs. Default: 1.
  • batch_size: Training batch size (alias for global_batch).
  • global_batch: Global batch size across all GPUs.
  • per_device_batch: Per-device batch size.
  • gradient_accumulation_steps: Steps to accumulate gradients. Default: 1.
  • sequence_length: Maximum sequence length. Default: 2048.
  • learning_rate: Optimizer learning rate (e.g., 2e-5).
  • warmup_ratio: Fraction of steps for LR warmup. Default: 0.1.
  • train_kind: Training variant (advanced).
  • weight_decay: Weight decay coefficient. Default: 0.01.
  • parallelism: Distributed training configuration.

​
SFTConfig

Root configuration for SFT (Supervised Fine-Tuning) jobs. This is the top-level config loaded from a TOML file. Attributes:
  • algorithm: Algorithm configuration (type=“offline”, method=“sft”).
  • job: Core job configuration (model, data_path).
  • policy: Policy configuration (preferred over job.model).
  • compute: GPU and compute configuration.
  • data: Data loading configuration.
  • training: Training mode (lora, full) and LoRA config.
  • hyperparameters: Training hyperparameters.
  • lora: Deprecated - use training.lora instead.
  • tags: Optional metadata tags.
Returns:
  • After training completes, you receive a result dict:
  • { “status”: “succeeded”, “model_id”: “ft:Qwen/Qwen3-4B:sft_abc123”, “final_loss”: 0.42, “checkpoints”: [ {“epoch”: 1, “loss”: 0.65, “path”: ”…”}, {“epoch”: 2, “loss”: 0.52, “path”: ”…”}, {“epoch”: 3, “loss”: 0.42, “path”: ”…”}, ],
  • }
Methods:

​
to_dict

to_dict(self) -> dict[str, Any]
Convert config to a dictionary.

​
from_mapping

from_mapping(cls, data: Mapping[str, Any]) -> SFTConfig
Load SFT config from dict/TOML mapping. Args:
  • data: Dictionary or TOML mapping with configuration.
Returns:
  • Validated SFTConfig instance.

​
from_path

from_path(cls, path: Path) -> SFTConfig
Load SFT config from a TOML file. Args:
  • path: Path to the TOML configuration file.
Returns:
  • Validated SFTConfig instance.