---
sidebar_position: 2.5
title: SDK
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lium.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Lium SDK

The `lium.io` package ships both the [CLI](./cli/overview) and a **Python SDK** for managing GPU pods programmatically. Install it once and use whichever interface fits the job.

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

**[Open SDK Reference](./sdk/reference)**
:::

## Installation

```bash
pip install lium.io
```

## Authentication

For local development, authenticate once with the CLI:

```bash
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:

```python
from lium.sdk import Lium

lium = Lium()
```

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

```bash
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.

```python
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`](./sdk/examples/machine-inference).

### `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.

```python
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()`](./sdk/examples/pod-lifecycle).

## Next Steps

Ready to go deeper? Open the **[generated SDK reference](./sdk/reference)** for signatures, arguments, return types, data models, and exceptions, or follow the **[SDK examples](./sdk/examples)** for complete workflows.

## Related

- [SDK Examples](./sdk/examples) — complete SDK workflows
- [CLI Installation](./cli/installation) — install the `lium.io` package
- [CLI Reference](./cli/reference) — per-command reference, grouped by category
- [CLI Quickstart](./cli/quickstart) — get started with the CLI