ServiceClient creates a session, then creates training runs and samplers within that session on demand. Loops picks an availability mode for each and returns the TrainingClient and SamplingClient you use for the run.
Create a training run and get a TrainingClient:
ServiceClient
Construct a
ServiceClient and create a new TrainerSession on the Baseten control plane. All arguments are keyword-only. api_key defaults to the BASETEN_API_KEY environment variable, and base_url to LOOPS_BASE_URL (falling back to https://api.baseten.co).Pass team to create the session, trainers, and samplers inside a specific Baseten team instead of your organization’s default team. Give the team’s name, not its ID. ServiceClient resolves the name against your available teams when you construct it, and raises ValueError listing the teams you can use when none match. ServiceClient reads the LOOPS_TEAM environment variable when you don’t pass the kwarg. See Teams.availability_model sets the capacity type for trainer and sampler deployments. Paired samplers inherit their run’s capacity type. Pass an AvailabilityModel value or its string ("dedicated" or "spot"). If you omit it, ServiceClient reads LOOPS_AVAILABILITY_MODEL, then defaults to dedicated. The constructor argument takes precedence over the environment variable. This setting doesn’t choose the availability mode; set scope to deployment to make sure it applies. See Spot capacity.Pass reuse_from_run_id to request a prior dedicated run’s warm trainer and paired sampler instead of starting new ones. Reuse requires the same capacity type. Serverless runs don’t use reuse. ServiceClient reads the LOOPS_REUSE_FROM_RUN_ID environment variable when you don’t pass the kwarg; the kwarg wins when you set both.reuse_from_session_id (environment variable LOOPS_REUSE_FROM_SESSION_ID) is the deprecated session-based trainer equivalent; when both are set, the run ID wins and the session ID is ignored. Standalone sampler creation ignores session reuse and creates a new logical sampler.The named run or session must belong to the same team. Reuse is best-effort: if the earlier run’s trainer or sampler isn’t available, Loops starts a new one and the call still succeeds. See Reuse a warm run.ServiceClient
Bind to already-running local trainer and sampler processes without contacting the control plane. Pass
trainer_url and sampler_url as the base URLs of local server processes. Useful for end-to-end testing.TrainingClient
Create a run for the given Hugging Face
base_model and return a connected TrainingClient. Blocks until the trainer endpoint is ready, so you can use the returned client immediately. By default the run has no paired sampler; one is created the first time you request a sampling client from the returned TrainingClient. Pass a WandbConfig instance to stream training metrics to a Weights & Biases run.scope selects the availability mode. Pass "serverless" to require the serverless mode or "deployment" for the dedicated mode. If you omit it, Loops reads BASETEN_LOOPS_SCOPE, then chooses a mode automatically.replicas sets the number of data-parallel copies of a trainer deployment. More copies use more GPUs; they don’t change model size or sequence length. Must be at least 1. Values above 1 bypass reuse of deployments. See Scale the trainer for how batches shard across replicas.max_seq_len sets the longest sequence in tokens the run must handle. Omit it and Loops picks the default for the model and the accelerators available to you. In the dedicated mode, the paired sampler serves at this length too; a serverless sampler serves the sequence length serverless supports for the model.sampler_timeout sets the read timeout for a single sample() call on the run’s paired sampler. Omit it and a generation runs as long as it needs. Pass a number of seconds to bound it, and the sampler client raises SampleTimeoutError when a generation exceeds it.name sets the run’s display name. Omit it and the run takes the base model name.with_sampler creates the run’s paired sampler up front. In the dedicated mode, its deployment starts alongside the trainer. Leave it off for train-only workloads. If sampler creation fails, the run continues and the sampler falls back to being created on first use.sampler_num_replicas sets the replica count for the paired sampler in the dedicated mode, applied as both its minimum and maximum. Must be at least 1. The count takes effect when the sampler is created: eagerly with with_sampler, or at the first sampling request. Omit it and the backend default applies. Serverless samplers ignore this setting.base_checkpoint starts the run from a merged Hugging Face checkpoint instead of base_model’s weights. Pass an hf://<org>/<repo> URI, optionally with @<revision>. The checkpoint must share base_model’s architecture, which still selects the hardware and training setup. The SDK pins the revision to a commit when it creates the run and loads the tokenizer from that commit, so TrainingClient.base_checkpoint reports the pinned value. For a private repository, store a Hugging Face token in the hf_access_token team secret and authenticate the process that runs the SDK, with HF_TOKEN or hf auth login. You can’t combine it with run or session reuse.A serverless run also waits for room in the capacity pool Baseten manages. While the pool is fully committed, the call retries, then raises LoopsCapacityError. See capacity and quota errors.TrainingClient
Return a
TrainingClient initialized with the weights saved at path. The new run uses the checkpoint’s base model and LoRA configuration. The optimizer starts fresh. Use this to resume from a saved checkpoint when you don’t need the prior optimizer state. replicas works as in create_lora_training_client.TrainingClient
Return a
TrainingClient that resumes from path with the optimizer state and step count intact. The new run uses the checkpoint’s base model and LoRA configuration. Use this to continue a run exactly where it left off. replicas works as in create_lora_training_client.SamplingClient
Create a standalone sampler and return a connected
SamplingClient. A standalone sampler has no trainer or run behind it and receives no weight syncs. Loops places it in the serverless mode or on a sampler deployment. Pass exactly one of base_model or model_path (a bt://loops:<run_id>/sampler_weights/<name> checkpoint URI to serve); passing both or neither raises ValueError. For a sampler deployment, blocks until its deployment is ACTIVE. A serverless sampler has no deployment readiness check.max_seq_len sets the longest prompt in tokens a sampler deployment must handle. Omit it and Loops picks the default for the model and the accelerators available to you. Serverless samplers ignore this setting and serve the sequence length serverless supports for the model.timeout sets the read timeout for a single sample() call on the returned client. Omit it and a generation runs as long as it needs. Pass a number of seconds to bound it, and sample() raises SampleTimeoutError when a generation exceeds it.num_replicas sets the replica count for a standalone sampler in the dedicated mode, applied as both its minimum and maximum. Must be at least 1. Omit it and the backend default applies. Serverless samplers ignore this setting.To sample from a live run’s latest weights, use TrainingClient.save_weights_and_get_sampling_client instead. ServiceClient.local clients don’t support model_path.scope selects the standalone sampler’s availability mode, with the same values and environment-variable fallback as create_lora_training_client().A serverless standalone sampler also waits for room in that pool, and raises LoopsCapacityError while it stays fully committed. See capacity and quota errors.record_stability_info=True records every sample from the returned client and returns a sequence_id for each, for use with Datum.with_provenance(). For router replay, record from a run’s sampling client instead, so the run’s own sampler captures the routes.ServerCapabilities
Return the control plane’s view of supported base models and the GPU classes it can provision them on. Useful for confirming a base model is available before calling
create_lora_training_client. Returns ServerCapabilities.The SDK’s typed model entries don’t expose serverless availability. Use the capabilities API to inspect the serverless field in the HTTP response.list[Checkpoint]
List checkpoints saved by the run identified by
run_id. Calls the list checkpoints API, not the trainer directly. Returns a list of Checkpoint.CheckpointFilesResponse
Return presigned URLs for every file in an S3-backed checkpoint folder. Pass either
checkpoint_id (a Checkpoint.id) or name with run_id; target (a CheckpointTarget) picks one when a name was saved for both a trainer and a sampler checkpoint. The Loops stack writes checkpoints as unzipped directories rather than archives, so this returns a file list instead of a single archive URL. Volume-backed checkpoints can’t be fetched by URL; use download_checkpoint() instead. Wraps the get checkpoint files API.CheckpointDownload
Download a checkpoint to a local directory, whether its files live in S3 or a Baseten volume. Pass either
checkpoint_id (a Checkpoint.id) or name with run_id; target (a CheckpointTarget) picks one when a name was saved for both a trainer and a sampler checkpoint.dest_dir must be empty for an S3-backed checkpoint. A volume-backed checkpoint lands in a subdirectory under dest_dir, and that landing directory must be empty. The returned CheckpointDownload reports the actual destination, file count, and bytes written.list[Run]
List the runs this client created, active and inactive, by calling the List runs API filtered to this client’s session. Raises
RuntimeError for a local client. Use it to find a run whose create request lost its response, so you can deactivate it.list[Sampler]
List the samplers this client created, active and inactive, by calling the List samplers API filtered to this client’s session. The list includes samplers paired to a run. Raises
RuntimeError for a local client.None
Shut down a run and its paired sampler, which stops their billing. Saved checkpoints stay available. Succeeds if the run is already inactive. Same as
TrainingClient.deactivate(), for a run you have no client for. Raises RuntimeError for a local client.None
Shut down a standalone sampler, which stops its billing. Succeeds if the sampler is already inactive. A sampler paired to a run returns a 409 error that names the run; deactivate the run instead. Same as
SamplingClient.deactivate(), for a sampler you have no client for. Raises RuntimeError for a local client.str
Property. The session ID assigned by the control plane. Available after construction.