# BuildAI Python SDK

Python client for Build AI services.

## Install

```bash
cd apps/buildai-sdk
uv pip install -e .
```

## Quick Start

```python
import buildai

client = buildai.Client(api_key="bai_...")

# Search
hits = client.search("person welding")
for h in hits.data:
    print(h.clip_id, h.score)

# Browse
factories = client.factories.list()
clip = client.clips.get("clip-uuid")
streams = client.sessions.streams("session-uuid")

datasets = client.datasets.list()

client.close()
```

If `api_key=` is omitted, the SDK first checks `BUILDAI_API_KEY`, then falls back to the CLI credential stored by `buildai auth login-device` in `~/.buildai/config.toml`.

## Modes

The SDK has two modes:

- `mode="public"` is the default and targets the public `/v1` contract
- `mode="internal"` unlocks internal-only resources when your credential is allowed to use them

Important:

- both modes use the same `/v1` API prefix
- the distinction is authorization and exposed resource set, not a separate base URL

## Dataset Surface

Use `client.datasets` for the canonical public dataset surface.
For the underlying storage model, read [../../docs/data-model.md](../../docs/data-model.md).

## Package Layout

- `buildai/client.py` — Client entry point
- `buildai/resources/v1/` — Resource namespaces
- `buildai/models/v1/` — Response models
- `buildai/ids.py` — Deterministic UUID helpers
