Skip to main content

Lium SDK

The lium.io package ships both the CLI and a Python SDK for managing GPU pods programmatically. Install it once and use whichever interface fits the job.

SDK Reference

The generated Python SDK reference covers the public client, data models, exceptions, configuration, and decorators.

Open SDK Reference

Installation​

pip install lium.io

Authentication​

For local development, authenticate once with the CLI:

lium init

This saves your API key to ~/.lium/config.ini, which is shared by both the CLI and SDK. After that, Lium() can authenticate automatically:

from lium.sdk import Lium

lium = Lium()

For CI, scripts, or temporary overrides, set LIUM_API_KEY instead:

export LIUM_API_KEY="sk_..."

LIUM_API_KEY takes precedence over the saved config file.

Two Entry Points​

The SDK exposes two ways to run work on Lium GPUs:

  • @lium.machine decorator — annotate a Python function and offload it to a GPU pod. Best for quickly running isolated workloads.
  • Lium() client — a direct client for long-lived orchestration code that manages pod lifecycles.

@lium.machine decorator​

Annotate a function with the machine type and dependencies, then call it like a normal Python function. The SDK handles provisioning, code upload, execution, and teardown.

import lium

@lium.machine(machine="A100", requirements=["torch", "transformers", "accelerate"])
def infer(prompt: str) -> str:
    from transformers import AutoTokenizer, AutoModelForCausalLM
    model_id = "HuggingFaceTB/SmolLM2-135M-Instruct"
    tokenizer = AutoTokenizer.from_pretrained(model_id)
    model = AutoModelForCausalLM.from_pretrained(model_id, device_map="cuda")
    tokens = tokenizer.apply_chat_template(
        [{"role": "user", "content": prompt}],
        return_tensors="pt",
        add_generation_prompt=True,
    ).to("cuda")
    out = model.generate(
        tokens,
        max_new_tokens=64,
        do_sample=False,
        pad_token_id=tokenizer.eos_token_id,
    )
    return tokenizer.decode(out[0][tokens.shape[-1]:], skip_special_tokens=True).strip()

print(infer("Who discovered penicillin?"))

For a complete remote inference workflow, see Remote Inference with @lium.machine.

Lium() client​

The client mirrors the CLI's pod lifecycle — list nodes, bring a pod up, wait until it's ready, execute commands, and tear it down.

from lium.sdk import Lium

lium = Lium()
ready = None

try:
    executor = lium.ls(gpu_type="A100", gpu_count=1)[0]
    pod = lium.up(executor_id=executor.id, name="demo")
    ready = lium.wait_ready(pod, timeout=600)
    if ready is None:
        raise RuntimeError("Pod did not become ready before the timeout")
    print(lium.exec(ready, command="nvidia-smi")["stdout"])
finally:
    if ready is not None:
        lium.down(ready)

For the complete CLI-equivalent workflow, see Pod Lifecycle with Lium().

Next Steps​

Ready to go deeper? Open the generated SDK reference for signatures, arguments, return types, data models, and exceptions, or follow the SDK examples for complete workflows.