Install and connect

This guide takes you from zero to a working LabeltyClient session.

Prerequisites

• Python 3.10 or newer
• Access to a Labelty project
• Permission to create a project API key

Step 1 — Install the package

pip install labelty-sdk

What this does: downloads the published SDK and its dependency (httpx) into your current Python environment.

Why it is needed: your scripts import labelty_sdk; without the package, Python raises ModuleNotFoundError.

Expected output: pip reports a successful install. You can verify with:

python -c "import labelty_sdk; print('ok')"

Common errors:

Error	Fix
pip: command not found	Install Python/pip or use python -m pip install labelty-sdk
Wrong Python version	Create a 3.10+ virtual environment and install there
Corporate proxy / TLS errors	Configure pip trusted hosts / certs with your IT team

Notebooks

SageMaker notebooks managed by Labelty may install the SDK from TestPyPI via a lifecycle script. Prefer production PyPI (pip install labelty-sdk) on your laptop unless your team says otherwise. See Open questions.

Step 2 — Create and store an API key

Follow Authentication to create a key in Project → API Key, copy the lty_… secret once, and export:

export LABELTY_API_URL="https://api.development.labelty.ai/api/v1"
export LABELTY_API_KEY="lty_..."

Step 3 — Connect

import os
from labelty_sdk import LabeltyClient
from labelty_sdk.exceptions import LabeltyHTTPError

with LabeltyClient(
    api_url=os.environ["LABELTY_API_URL"],
    api_key=os.environ["LABELTY_API_KEY"],
    timeout=60.0,  # optional; default is 30.0
) as client:
    project = client.project  # or client.projects.current()
    print(project.id, project.name, project.asset_type)

What this does:

1. Opens an authenticated HTTP client to the Labelty API.
2. Loads the project bound to your API key (GET /projects/current).
3. Prints basic project fields.

Why use a context manager: it closes the underlying HTTP client cleanly. If you do not use with, call client.close().

Constructor options:

Argument	Meaning
api_url	Base URL including /api/v1
api_key	Project key lty_…
timeout	Request timeout in seconds
verify_ssl	TLS verification (default True)

Step 4 — Handle errors

try:
    other = client.projects.get("00000000-0000-0000-0000-000000000000")
except LabeltyHTTPError as e:
    print(e.status_code, e.payload)

LabeltyHTTPError exposes status_code and payload from the API error body.

Escape hatch for unwrapped endpoints

client.request(
    "POST",
    f"/assets/{asset_id}/annotations",
    json={
        "points": [[0.1, 0.2], [0.3, 0.2]],
        "label_id": "uuid-of-label-schema",
    },
)

Use this when a feature exists in the HTTP API but not yet as a typed SDK resource.

Best practices

• Keep keys in environment variables or a secret store — never hard-code them in source.
• Prefer client.project over hard-coding project UUIDs.
• Use longer timeout values for large downloads or cold inference calls.

Next step

Work with labels and files: Schema and assets.