Metadata-Version: 2.5
Name: strangeworks-aura-sdk
Version: 0.2.0
Summary: Async Python SDK for the Strangeworks Aura /api/v1 surface (API-key auth).
Project-URL: Homepage, https://docs.aura.strangeworks.com
Project-URL: Documentation, https://docs.aura.strangeworks.com/python/
Author: Strangeworks
Keywords: aura,operations-research,optimization,sdk,strangeworks
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.5
Requires-Dist: websockets>=14
Description-Content-Type: text/markdown

# strangeworks-aura-sdk

An **async** Python SDK for the Strangeworks Aura public API (`/api/v1`). It embeds Aura in a
Python backend — deployments, projects, conversations, chat, snapshots — with company **API-key**
auth. The import package is `aura_sdk`.

```bash
pip install strangeworks-aura-sdk
```

```python
import os
from aura_sdk import AuraClient

async with AuraClient(api_key=os.environ["AURA_API_KEY"]) as aura:
    project = await aura.create_project(name="vrp demo", from_deployment="acme/vrp")
    reply = await aura.chat(project.id, "Solve this and summarize the result.")
```

Async-only: every call is a coroutine and there is no synchronous twin, so it drops into an async
service without a thread pool in the middle. A synchronous entry point wraps it once with
`asyncio.run(...)`.

📖 **[docs.aura.strangeworks.com/python](https://docs.aura.strangeworks.com/python/)** — the full
guide and API reference. Documentation for this package lives there, not here:
[`clients/docs`](../docs) is its one home, so a change to the public surface updates that site in
the same commit. Method docstrings stay the exception — they are what `help()` renders, and the
published reference is generated from them, so they document their own args, returns and
exceptions in place.

The TypeScript counterparts are [`@strangeworks-inc/strangeworks-aura-sdk`](../aura-sdk-ts) and, for the terminal,
[`@strangeworks-inc/strangeworks-aura-cli`](../aura-cli). There is no Python CLI — the `aura` command ships from
TypeScript only. Why both SDKs are shaped the way they are is recorded in
[ADR-024](../../wiki/decisions/2026-07-30-client-sdk-public-surface.md).

## Developing it in this repo

From `clients/aura-sdk-python`:

```bash
uv sync          # its own venv — this package never resolves against backend/
uv run pytest
```

Point a client at a local `just dev` stack with `base_url="http://localhost:3000"` (Caddy routes
`/api/*` to the backend; its own 8080 is container-internal). **No minting needed locally**: any
`sk-aura-…` value set as `AURA_API_KEY` in the repo-root `.env` is registered by the backend seed
on startup as a valid key for the Strangeworks company, and survives `just reset-db` since it's
re-seeded from the same env value.

Request and response models under `src/aura_sdk/models.py` are pydantic models generated from the
backend's OpenAPI spec, filtered to the public `/api/v1` surface. `api.json` alongside them is the
public surface extracted for the docs site. Do not edit either by hand — regenerate from the repo
root with `just sync-openapi`. CI (`api-types-drift`) fails if they drift.

## No backend coupling

This package is a customer artifact: it has its own `pyproject.toml`, its own `uv.lock` and its own
`.venv`, and it is **not** installed into the shared backend venv the way `packages/aura-compute`
is. It must never import from `workflows_prototype`, `modeling_phase` or `aura_compute`, and
`tests/test_no_backend_coupling.py` asserts that in a clean subprocess rather than trusting
convention.
