Metadata-Version: 2.4
Name: buildai-sdk
Version: 2.3.0
Summary: Build AI Python SDK
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.6
Provides-Extra: all
Requires-Dist: buildai[gcs,torch]; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: gcs
Requires-Dist: gcsfs>=2023.12; extra == 'gcs'
Provides-Extra: torch
Requires-Dist: torch>=2.1; extra == 'torch'
Requires-Dist: webdataset>=0.2.86; extra == 'torch'
Description-Content-Type: text/markdown

# 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_TOKEN` (or `BUILDAI_API_KEY`), then falls back to the CLI credential stored by `buildai login` in `~/.buildai/credentials.json`.

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