# Build AI SDK

Applies to `apps/buildai-sdk/`.

Read first:

- [../../CLAUDE.md](../../CLAUDE.md)
- [../../docs/api-reference.md](../../docs/api-reference.md)

## Hard Rules

1. Public method names and model fields are part of the SDK contract.
2. SDK models must match API shapes.
3. Retry logic stays in the transport layer.
4. The SDK talks to the API, not the DB.
5. Use `uv`, not raw `pip`.

## Verify Instead Of Infer

- Verify whether a resource is public or internal-only.
- Verify the API response shape before changing models.
- Verify whether a behavior belongs in `HttpTransport` or `AsyncHttpTransport`.

## Canonical Commands

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

## Common Traps

- Renaming a model field is a breaking change.
- Optional extras may not be installed.
- Internal resources should fail cleanly in public mode.
- `mode="internal"` is an auth/exposure distinction, not a separate URL namespace.

## Done Means

- API and SDK shapes still match
- contract changes were explicit and documented
- transport behavior was changed in one place only

## Related Docs

- [../../docs/api-reference.md](../../docs/api-reference.md)
- [../buildai-api/CLAUDE.md](../buildai-api/CLAUDE.md)
