# Aura

> Aura turns an optimization problem into a running solver you can talk to. You publish a **deployment** (solver code under `run/`, its dataset under `data/`), create a **project** from it, and drive that project by chatting with Aura from TypeScript, Python, or the `aura` CLI. Every call authenticates with a company API key (`sk-aura-…`) as `Authorization: Bearer <key>`.

The CLI administers Aura and is how you try a deployment out by hand; the SDKs are for embedding Aura in software you ship.

Notes that are easy to get wrong:

- `chat()` delivers a turn live over the project WebSocket and returns the completed reply,
  falling back to polling `/chat/sync` where a socket cannot be held open.
- A timeout or an abort stops **your wait**, not the turn — the agent keeps working until it
  finishes or you call `cancel()`.
- Four error types, not one: `AuraApiError` (the call was rejected), `AuraResponseError`
  (the answer was unreadable), `AuraTurnCancelledError` (the turn stopped early; carries the
  partial content), and `AuraTurnTimeoutError` (your wait elapsed; the turn is still running).
- The Python SDK is async-only — every call is a coroutine.
- Agent instructions **steer, they do not enforce**. They are appended to the prompt, so the
  agent normally follows a rule and cites it when declining — never rely on one to protect
  something that must not happen.
- A `project*` config method only ever changes that project. It holds its own copy of what it
  pulled, so deleting there leaves the deployment and every sibling project untouched;
  `pullAgentConfig` / `pull_agent_config` is how a project takes a revision.
- Agent config is separate from the workspace. A snapshot or tag checkout leaves it alone; a
  deployment checkout pulls it, as does an explicit `agent-config/pull`.
- One checkout at a time per project: a checkout replaces the whole workspace, so the server
  refuses a second one — and a snapshot taken during one — with a `409` rather than letting
  them interleave. `getWorkspace` / `get_workspace` says whether one is in flight.
- A snapshot's `label` is a title, a tag is an address. Only a tag resolves as a ref, so a
  label passed where a snapshot id or `source` is expected will not find it.
- The CLI acts on a *selected* project: `aura project use <id>` stores it, `AURA_PROJECT`
  overrides it for a shell, `--project` for one command. `--project` is not required on any
  command. The project is a positional only where it is what the verb acts on —
  `aura project use <id>` and `aura project delete <id>`, not `aura project checkout <ref>`.
- Every client defaults to the **EU** deployment, whose API host is
  `https://aura-api-eu.strangeworks.com` (`https://aura-api.strangeworks.com` for US). A key works only in the region
  it was minted in, so a key from the wrong region fails as a 401. `region: "us"` /
  `region="us"` / `--region us` switches; an explicit `baseUrl` / `base_url` overrides it.
- `aura skill install` installs a skill for the coding agent the reader runs, in their repo.
  `aura deployment skills` and `aura project skills` are the unrelated pair, shipping skills to
  Aura's own agent.
- `aura deploy` **syncs**: remote files missing locally are pruned. The SDK helpers
  `deployFromFolder` / `deploy_from_folder` only upload — nothing remote is deleted.
- Python: `AuraClient(...)` takes keyword arguments only, needs Python 3.11+, and `chat`'s
  `timeout` is in seconds (`timeoutMs` in TypeScript). Network failures surface as `httpx`
  exceptions (`httpx.ConnectError`, `httpx.ReadTimeout`), not as `AuraError`. Enums such as
  `SnapshotKind` are imported from `aura_sdk.models`.
- `uploadFile` / `upload_file` send one file in one PUT, up to 100 MiB. 100–250 MiB is refused
  with a `501` before any bytes move (the server would plan a multipart upload the SDKs do not
  implement); above 250 MiB the server refuses the plan with `413`.
- `deployFromFolder` / `deploy_from_folder` exclude nothing by default, and the server refuses
  dot-prefixed paths (`.git`, `.venv`, `.DS_Store`, `.env`) with a `400` — pass `filter` /
  `include` to skip them. The solution a solver writes is `solutions/out.json` by convention;
  a snapshot's `solution_path` is the path that run actually recorded.

## Documentation Sets

- [Abridged documentation](https://docs.aura.strangeworks.com/llms-small.txt): a compact version of the documentation for Aura, with non-essential content removed
- [Complete documentation](https://docs.aura.strangeworks.com/llms-full.txt): the full documentation for Aura

## Notes

- The complete documentation includes all content from the official documentation
- The content is automatically generated from the same source as the official documentation

## Optional

- [Aura](https://aura-eu.strangeworks.com): the app itself (EU, the default region)