TwinkleClient

TwinkleClient is the Python client for interacting with the Twinkle REST API. It manages sessions, training runs, and checkpoints.

Initialization

from twinkle_client.manager import TwinkleClient

client = TwinkleClient(
    base_url='http://localhost:8000',   # Or TWINKLE_SERVER_URL env var
    api_key='your-api-key',             # Or TWINKLE_SERVER_TOKEN env var
    route_prefix='/twinkle',            # API route prefix
    session_heartbeat_interval=10,      # Heartbeat interval in seconds
    session_metadata={'user': 'alice'}, # Optional session metadata
)

On init, the client:

  1. Sets base_url and api_key into shared context (used by all client objects)

  2. Creates a server-side session

  3. Starts a background heartbeat thread to keep the session alive

Health Check

is_healthy = client.health_check()  # Returns True/False
capabilities = client.get_server_capabilities()  # Supported models

Training Runs

# List runs
runs = client.list_training_runs(limit=20, offset=0)

# List with pagination cursor
runs, cursor = client.list_training_runs_with_cursor(limit=20)

# Get specific run
run = client.get_training_run(run_id='run_abc123')

# Find by base model
qwen_runs = client.find_training_run_by_model('Qwen/Qwen3.5-4B')

Checkpoints

# List checkpoints for a run
checkpoints = client.list_checkpoints(run_id='run_abc123')

# Get checkpoint path
parsed = client.get_checkpoint_path(run_id, checkpoint_id)
# parsed.path         → filesystem path
# parsed.twinkle_path → twinkle:// URI

# Get latest checkpoint (useful for resume training)
latest_path = client.get_latest_checkpoint_path(run_id)

# Delete checkpoint
client.delete_checkpoint(run_id, checkpoint_id)

Capacity & Weights Info

# LoRA capacity
capacity = client.get_capacity_info()
# capacity.max_loras, capacity.used_loras, capacity.free_loras

# Weights metadata
info = client.get_weights_info('twinkle://run_id/weights/checkpoint')
# info.base_model, info.is_lora, info.lora_rank

Cleanup

client.close()  # Stops heartbeat thread (also registered via atexit)