hci-atrium 0.4.0 → 0.6.0

package/GUIDE.md

@@ -0,0 +1,1215 @@
+# hci-atrium — Student & AI-assistant guide
+
+A complete, task-oriented reference for the `hci_atrium` Python SDK — the client for the Atrium
+multimodal asset library. It's written to be pasted into a coding assistant verbatim: every
+signature below is checked against `clients/python/src/hci_atrium/`. If you're new to the SDK,
+start with [`README.md`](README.md) for the 60-second overview; this file is the reference you
+come back to while building.
+
+Everything here works with either client:
+
+```python
+from hci_atrium import Atrium          # sync — the default for scripts
+from hci_atrium import AsyncAtrium     # asyncio — same surface, `await` everything
+```
+
+The two mirror each other method-for-method. Examples below use the sync client unless a feature
+(rooms driven by `on`/`serve`, the Home Assistant bridge) needs asyncio — those are marked **async**.
+
+## Reading this from TypeScript
+
+The same SDK is published on npm as `hci-atrium` (`pnpm add hci-atrium`), at parity with the
+Python surface below apart from the deliberate gaps noted at the end of this section. This guide
+stays the reference for both — translate it mechanically:
+
+- **Names**: `snake_case` → `camelCase`. `library.search_by_examples` → `library.searchByExamples`,
+  `add_direct_model` → `addDirectModel`, `content_kind` → `contentKind`.
+- **Keyword arguments** become one trailing `params` object:
+  `client.library.search("rain", modality="audio", limit=10)` →
+  `client.library.search("rain", { modality: "audio", limit: 10 })`.
+- **`None` → `null`**, `True`/`False` → `true`/`false`, dicts → plain objects.
+- **Async everywhere.** There is no sync/async split — every call returns a `Promise`, so the
+  `AsyncAtrium` examples are the ones to follow (`await` the sync ones too).
+
+Deliberate gaps: the full `atrium` CLI (`login`, `whoami`, `search`, …) and the Home Assistant
+bridge are **Python-only**. The npm package ships exactly one command, `atrium guide`, which prints
+this file (`pnpm exec atrium guide`). Everything else is ported.
+
+For the per-surface specifics — the parity ledger, the browser-side differences (API keys, capture),
+and the React bindings — see `PARITY.md` and `README.md`, which ship alongside this file in the npm
+package (`clients/typescript/` in the repo).
+
+---
+
+## 1. Setup + auth
+
+### Install
+
+**Fresh project with uv (recommended):**
+
+```sh
+uv init my-study-app
+cd my-study-app
+uv add hci-atrium
+```
+
+Run scripts with `uv run python main.py` (or `uv run <script.py>`) — uv creates the venv and syncs
+automatically, no activation. The CLI comes along: `uv run atrium --help`. The SDK needs Python
+>=3.10; if the pinned version is older, `uv python pin 3.12`.
+
+**Existing project:** `uv add hci-atrium` in a uv-managed project; for a plain venv/pip project:
+
+```sh
+pip install hci-atrium
+```
+
+**Throwaway try-out:** `uv run --with hci-atrium python` opens a REPL with the SDK importable, no
+project needed.
+
+SDK developers working against a checkout: `uv add --editable path/to/clients/python` overrides the
+published package with your local source.
+
+### Connect
+
+```python
+from hci_atrium import Atrium
+
+client = Atrium()   # defaults to the deployed instance (or ATRIUM_BASE_URL)
+```
+
+| What | Argument | Environment variable | Default |
+|---|---|---|---|
+| Instance URL | `Atrium(base_url=...)` | `ATRIUM_BASE_URL` | the deployed instance |
+| Credential | `Atrium(api_key="atr_...")` | `ATRIUM_API_KEY` | cached OAuth → browser sign-in |
+
+**Zero-config sign-in.** With no `api_key`, the first authenticated call opens a browser
+(Authorization Code + PKCE, out-of-band code). Tokens are cached in `~/.atrium/credentials.json`
+(mode `0600`) and refreshed silently — later runs and later scripts don't prompt again.
+`client.login()` forces this now instead of lazily; `client.logout()` forgets the cached session;
+`client.token()` returns a live bearer token (for pointing another OpenAI-compatible tool at the
+same instance).
+
+**API keys (CI / headless / a fixed identity).** A key looks like `atr_...` and is minted in the
+Atrium web app under a project's *Settings → API keys*. Two shapes:
+
+- **Project-scoped key** — acts as that project; every call is scoped to it automatically, no
+  `project=` needed. The right shape for a study app that only ever writes to one project.
+- **Account-wide key** — acts as your user across every project you can see.
+
+Pass it as `Atrium(api_key="atr_...")` or set `ATRIUM_API_KEY` — either skips the browser flow
+entirely.
+
+```python
+me = client.me()                        # GET /v1/users/me
+me.email, me.role
+me.key_project_id                       # set when a project-scoped key is in use
+me.effective_project_id                 # the project data ops target (scoped key, else your Personal project)
+```
+
+### Projects & scope
+
+A **project** is identified by a `p_...` short id (e.g. `p_4mD2qX`) — a base58, URL-safe id that
+doubles as the API "connect target" for that project. Scope any call to a project (and optionally
+a collection within it) three ways:
+
+```python
+client.library.search("rain", project="p_4mD2qX")            # per call
+client = Atrium(project="p_4mD2qX")                           # default for a whole client
+photos = client.collection("c_7Bq3Xk")                        # a reusable scoped view
+photos.library.search("rain")                                 # every call on `photos` is scoped
+```
+
+`client.project(id)` / `client.collection(id)` return a scoped view that shares the same
+authenticated session (cheap — no re-auth). A project-scoped API key scopes everything
+automatically; you never need `project=` with one.
+
+### The CLI
+
+Installing the package puts an `atrium` command on `PATH`. From inside the monorepo:
+
+```sh
+uv run --project clients/python atrium login
+uv run --project clients/python atrium whoami
+uv run --project clients/python atrium search "calm rainy afternoon" --modality audio
+```
+
+Once installed into your own project, just `atrium ...` (or `python -m hci_atrium ...`). Full
+command list: `login`, `logout`, `whoami`, `search`, `assets`, `upload`, `enrich`, `chat`,
+`survey pull`, `survey push`, `ha-bridge` — every command takes `--base-url`;
+`search`/`assets`/`upload` also take `--project`/`--collection`. Run `atrium <command> --help` for
+flags.
+
+Survey templates round-trip through files, so they can live in git next to your study code:
+
+```sh
+atrium survey pull onboarding --project p_4mD2qX -o onboarding.survey.json
+atrium survey push onboarding.survey.json --project p_4mD2qX
+```
+
+`pull` writes the same export envelope the SPA's "Export to file…" produces
+(`{"atrium_survey_template": 1, "name", "description", "body"}`) — to stdout without `-o`. It omits
+the SPA's `exported_at`/`source` stamps, so re-pulling an unchanged template gives an unchanged file.
+Unlike the SPA export (which inlines images so the file survives the source project's deletion),
+`pull` keeps bare project-file refs — an `image` in the body stays bound to the source project.
+
+`push` first checks whether the template is published (a template that isn't there yet counts as
+unpublished); pushing to a PUBLISHED one prints a warning, because the write changes the live survey.
+It then checks the body against the dialect (`survey-templates:validate`): any issue is printed to
+stderr and the push is refused (non-zero exit) unless you pass `--force`, which downgrades them to
+warnings — but on a PUBLISHED template dialect issues are refused even with `--force`. It then runs
+the same idempotent ensure as `client.surveys.template(...)` — a write only when the body actually
+changed, reported as `version N written`, otherwise `already at version N, no change`. N may be the
+same number either way: the server is copy-on-write and overwrites the current version in place while
+no response is pinned to it. An envelope's `description` is applied only when the push *creates* the
+template (a notice goes to stderr when it's ignored). Publication and the default flag are never
+touched. The file may also be a *bare* template body (no envelope), in which case `--name` is
+required; `--name` overrides an envelope's own name.
+
+### Errors
+
+Every exception the SDK raises derives from `hci_atrium.AtriumError`:
+
+```python
+from hci_atrium import AtriumError, AuthError, APIError
+
+try:
+    client.library.search("rain")
+except APIError as exc:          # a non-2xx HTTP response
+    exc.status_code, exc.body    # int, str (truncated)
+except AuthError:                 # sign-in / token exchange / refresh failed
+    ...
+except AtriumError:               # catch-all for everything the SDK raises
+    ...
+```
+
+---
+
+## 2. Core concepts, in one screen
+
+- **Project** — the top-level scope for data (`p_...` short id). Every asset, room, and session
+  lives in exactly one project. A study is usually one project.
+- **Collection** — a node in a project's recursive collection tree (`c_...` short id); `Library` =
+  the project's root. Used to scope search/listing to a subtree. The SDK only *scopes to* an
+  existing collection id (`client.collection(id)`) — creating/managing the tree is a web-app task,
+  not exposed here.
+- **Asset** — one library item. Three independent things it can carry:
+  - **bytes** (`sha256` set) — decodable content, served at `asset.content_url`.
+  - **link** (`source_url` set) — an external/attribution URL (e.g. a Spotify playlist).
+    An asset can have *both* (uploaded audio with a source link) or *neither* (a description-only
+    asset, e.g. "the smell of rain").
+  - **description** — always present as metadata; it *is* the content when there are no bytes.
+  - `asset.facts` — a server-owned JSON bag (analysis results, the `link` discriminator, etc.);
+    never write to it yourself.
+  - `asset.data` — an app-owned JSON bag the server never touches — your study's own structured
+    metadata on the asset.
+- **Rooms vs sessions** — deliberately decoupled:
+  - A **room** is pure live transport: `room.send(...)` fans a message to everyone connected,
+    nothing is stored. Anyone can join by a short **connect code**, no account needed
+    (`join_room(code)`). No replay — if you weren't listening, you missed it.
+  - A **session** is a durable, append-only, gapless log (`session.event(...)`). No running/ended
+    lifecycle — it's simply the record, always appendable. A session doesn't need a room.
+  - To keep what happens live, a host **bridges** the two: `room.record(into=session)`.
+- **Surveys** — a durable *data object* on a session, guarded by a one-time capability token
+  (`session.token`); a project-scoped, versioned template drives what it asks.
+
+---
+
+## 3. Library
+
+### Search
+
+```python
+client.library.search(
+    query: str = "",
+    *,
+    like=None,                             # rank "more like this" — an Asset, SearchHit, or id
+    like_by: str | None = None,            # which of the liked asset's signals seeds it (default: native)
+    modality: str | None = None,          # desired result kind, e.g. "audio", "image"
+    space: str | None = None,              # force a specific embedding space (id or name)
+    limit: int = 20,
+    tags: list[str] | None = None,         # results must carry ALL of these tags
+    any_tags: list[str] | None = None,     # …and at least one of these
+    exclude_tags: list[str] | None = None, # …and none of these
+    provider: str | list[str] | None = None,  # who provides the content — see below
+    filters: Filters | None = None,        # the long tail: content_kind, statuses, ranges, exclude_ids, …
+    image=None, audio=None, video=None,    # search BY a media file instead of text (cross-modal)
+    vector: list[float] | None = None,     # rank by a raw vector (pass space= with it)
+    include_vectors: bool | str = False,   # inline one vector per hit onto hit.vector
+    project: str | None = None,
+    collection: str | None = None,
+) -> list[SearchHit]
+```
+
+```python
+for hit in client.library.search("calm rainy afternoon", modality="audio", limit=5):
+    print(round(hit.score, 3), hit.asset.title or hit.asset.filename)
+    print("   ", hit.asset.content_url)
+
+playlists = client.library.search("lofi beats", modality="audio", provider="spotify:playlist")
+
+# "More like this" — pass an asset (or a SearchHit straight from a previous search) as like=
+similar = client.library.search(like=hit, modality="audio")
+```
+
+- Pass **exactly one** query input: a text `query`, an example asset (`like=`), a media source
+  (`image=`/`audio=`/`video=`), or a raw `vector=`. `modality` means "what kind of result I want":
+  results OF that kind, **provided by the library's own storage and matched by their native
+  content** (the server's media-intent defaults — text-about-content and byteless links don't
+  compete unless you opt in). For a text query it also picks that modality's space; for a media
+  query the query embeds in the cross-modal joint space.
+- `like=` ranks "more like this": an `Asset`, a `SearchHit`, or a bare id. `modality` still filters
+  the results (cross-modal: an image can fetch its fitting audio, ranked in the cross-modal default
+  space); the source asset must be embedded in the ranking `space`. `like_by=` picks which of the
+  asset's stored signals seeds the query (`"native"`, `"manual"`, `"bridge:<modality>"`,
+  `"view:N"`/`"seg:<id>"`) — default is the native-first auto pick.
+- `provider` selects where results come from: `"library"` (stored bytes — the implied default
+  for a media `modality`), a streaming provider (`"spotify"`, entity-qualified
+  `"spotify:playlist"` / `"spotify:track"` / `"spotify:album"`), `"link"` (anything with a URL,
+  recognized or not), `"none"` (neither bytes nor URL — e.g. a fileless asset you hand-tagged
+  "audio"), `"any"` (everything), or a list to mix. Non-library classes match by their
+  description text — mixing classes ranks text-matches against content-matches, which is only
+  score-comparable on a fully calibrated space; and a provider link with no description holds no
+  vectors at all, so ranked search can't surface it (keyword search can). Unknown values → 422
+  listing the vocabulary.
+- `hit.asset` is an `Asset`; `hit.score`/`hit.raw_score`/`hit.calibrated`/`hit.matched_by`/
+  `hit.match_label` describe the match.
+- `include_vectors=True` inlines onto `hit.vector` the one vector that scored each hit (its identity
+  is `hit.matched_by`); a space id/name instead returns that space's vector per hit, which can
+  differ from the one that ranked it. Off by default — vectors are large and never leave Postgres in
+  the search path; `hit.vector` is `None` unless you asked.
+- `filters=Filters(...)` carries full library-filter power: `content_kind` (the immutable kind
+  sniffed from the file's bytes — `"image"`, `"audio"`, …, unlike `modality` which matches the
+  editable label, so it finds a JPEG even after it's retagged `"product"`), `statuses`, numeric
+  fact `ranges` (`{"bpm": (90, 120), "duration_s": (None, 30)}`), `uploader`, extra kind/label
+  facets (`all_kinds`/`any_kinds`/`none_kinds`/`all_labels`/`any_labels`/`none_labels`),
+  `max_seconds`, `match_by` (the Match-by override: an explicit list — e.g. `["native", "manual"]`,
+  or `[]` for every signal — applies globally, replacing the per-class default that comes with a
+  `provider` filter), `data_match={"kind": "field"}` (a JSONB containment filter on the app-owned
+  `asset.data`, `data @> data_match` — retrieval of what you wrote, not derivation), and
+  `exclude_ids` (drop these asset ids — dedup for a prefetch loop; capped at 512).
+
+Other `Library` methods, same scoping conventions (`project=`/`collection=`, `space=`):
+
+| Method | Purpose |
+|---|---|
+| `library.add(file=None, *, modality=, description=, collection=)` | add an asset to the library — a file, or (omit `file`) a fileless asset whose `description` *is* its content. See [Add to the library](#add-to-the-library) |
+| `library.compare(a, b, *, space=, breakdown=False)` | pairwise similarity of two operands — `Asset`, `str`, `list[float]`, or `by.file(...)`/`by.asset(id)`/`by.concept(name_or_id, collection=)`; `breakdown=True` adds the per-feature terms (see below) |
+| `library.search_by_examples(positives, negatives=, *, method="cav"/"centroid"/"probe", match_by=, filters=, ...)` | "mood board" — rank by a set of example assets (default `method="cav"`). `match_by=["native"]` picks the signals by class — same meaning as `search`'s `filters.match_by`. `match_by={"native": 1.0, "manual": 0.3}` also weights them (only a set query can: search picks one best signal, this blends every one). An allowlist either way; no space ids. `probe` fits its own weights, so pass `method="cav"` to set them by hand. `filters=` narrows by kind/label facets + `content_kind`; a Filters field with no set-query slot (`statuses`/`ranges`/`uploader`/`max_seconds`/`data_match`/`exclude_ids`) raises |
+| `library.enrich(query, modality, *, tags=, total=, preview=, wait=)` | pull external candidates (Freesound/Openverse/…) into the library |
+| `library.vectors(ids, *, space, match_by=None, strict=False)` | bulk-read stored vectors for many assets — see [Reading an asset back](#reading-an-asset-back) |
+| `library.spaces()` | list the searchable embedding spaces |
+| `library.default_space(modality)` | the deployment's default space for that modality (a `spaces()` dict, or `None`) |
+
+`by.concept(...)` can only be one side of a `compare` call — it scores the *other* operand's vector
+against that tag's materialized concept snapshot (calibrated to the concept's own boundary, not the
+usual search calibration), 404 if the concept doesn't resolve, 422 if it has none. `breakdown=True`
+then fills `result.features` with the per-`(space, matched_by)` terms behind that score (it stays
+`None` for a plain asset/vector compare, which has no per-feature structure):
+
+```python
+result = client.library.compare(asset, by.concept("cozy"), breakdown=True)
+for f in result.features or []:
+    print(f.space, f.matched_by, f.weight, f.raw_score, f.score)   # which signals carried the match
+```
+
+Read those as **raw per-feature terms, not additive contributions** — they cover only the scored
+space's features and do not sum to `result.score`.
+
+`default_space` keeps deployment space ids out of your code — the deployment declares its defaults,
+the app just asks:
+
+```python
+space = client.library.default_space("audio")     # e.g. {"id": "clap", "name": "CLAP", ...} or None
+rows = client.library.vectors(ids, space=space["id"])
+```
+
+### Asset views
+
+```python
+asset = client.assets.get("a_123")
+
+asset.capabilities     # set[str] ⊆ {"bytes", "link"} — independent flags, both can hold
+asset.link              # AssetLink(provider, entity, uri) | None — present iff "link" in capabilities
+asset.playback          # PlaybackIntent — ALWAYS present
+asset.content_url       # public URL for the bytes (fingerprinted ?v=sha when known)
+asset.thumbnail_url     # public URL for an image/video poster (404 if none)
+```
+
+`asset.playback` normalizes the asset into one play intent, mirroring the room `play` signal's
+`{source, ref, mode?}` shape 1:1 — a host can forward it as-is:
+
+```python
+intent = asset.playback          # PlaybackIntent(source=..., ref=..., mode=...)
+intent.as_signal()                # {"source": ..., "ref": ..., "mode": ...} — mode omitted if unset
+room.send("play", {"playback": intent.as_signal()})
+```
+
+Priority: `source="bytes"` whenever the asset has decodable content (even if it also has a link);
+else the recognized link provider's name (currently only `"spotify"`) with `ref` a
+`provider:entity:id` URI, `mode="shuffle"` for a playlist; else `source="link"` with the raw URL
+for an unrecognized provider; else `source="description"` with `ref` = the asset id (nothing to
+fetch, but a host can still look it up).
+
+<a name="reading-an-asset-back"></a>
+### Reading an asset back: vectors, segments, index
+
+What the library stored *for* an asset — its embeddings, its cut sound events, and the processing
+state of each signal. All three are bound on the asset itself:
+
+```python
+asset = client.assets.get("a_123")
+
+for v in asset.vectors():                       # every stored vector; list[AssetVector]
+    print(v.space, v.matched_by, len(v.vector))  # matched_by: "native" / "manual" / "bridge:text" / "seg:<id>"
+asset.vectors(space="CLAP", match_by="native")  # narrow: space (id or name, one or a list) + signal
+
+for seg in asset.segments():                    # the sound events cut out of an audio asset
+    print(seg.ordinal, seg.start_s, seg.end_s, seg.content_url)   # just that slice's pre-cut bytes
+
+for entry in asset.index():                     # one row per stored signal — the processing state
+    print(entry.space, entry.matched_by, entry.active, entry.status, entry.error)
+```
+
+`client.assets.vectors(asset, space=, match_by=)` / `.segments(asset)` / `.index(asset)` are the
+unbound forms — each takes an `Asset`, a `SearchHit`, or a bare id. Vectors and segments are public
+by id (like `content_url`); the index map is authenticated. On the async client the bound methods are
+awaitable (`await asset.vectors()`).
+
+For many assets at once, `library.vectors(ids, *, space, match_by=None, strict=False)` is the bulk
+read — `space` is **required** here (one id/name, or a list):
+
+```python
+rows = client.library.vectors([h.asset for h in hits], space="CLAP")
+{r.asset: r.vector for r in rows}     # each AssetVector carries its owning asset id
+```
+
+With `match_by=None` the signal is resolved per asset, so one call can return **mixed** `matched_by`
+values — read `r.matched_by` to see which each row is. Ids that don't exist or aren't visible to your
+key land in the server's `missing` list: `strict=False` (default) omits them, `strict=True` raises
+listing them.
+
+### Browse, add to the library
+
+```python
+page = client.assets.list(
+    modality="audio",              # editable label
+    content_kind=None,              # or ["image", "audio"] — the bytes-sniffed kind instead
+    limit=48, cursor=None, project=None, collection=None,
+)
+page.items          # list[Asset]
+page.next_cursor    # pass back as cursor= for the next page, or None
+```
+
+<a name="add-to-the-library"></a>
+`library.add(...)` is the front door for putting an asset into the library — with a file, or fileless:
+
+```python
+asset = client.library.add(
+    "path/to/rain.wav",             # path, Path, bytes, open file, or an http(s) URL
+    modality=None,                   # override the modality *label* (a search/display facet;
+                                     # embedding follows the bytes, never this)
+    description="rain on a tin roof",
+    collection=None,                 # home it in a collection, else the default scope
+)
+
+# Fileless — no file, the description *is* the content (the web UI's "Add other"):
+note = client.library.add(description="a warm, relaxed evening mood")
+```
+
+A positional string is always a file path/URL, never a description — pass `description=` as a
+keyword; a fileless add requires it. `client.assets.upload(file, ...)` is the same call for a file.
+
+Every media argument across the SDK (`image=`, `audio=`, `video=`, `library.add(file)`) accepts a
+path, `Path`, raw `bytes`, an open binary file, or an `http(s)` URL — normalized by
+`hci_atrium._files`.
+
+### Bulk import
+
+For importing many assets at once from a manifest (JSON/CSV) instead of one-by-one uploads,
+`POST /v1/library/import` is a raw multipart endpoint, not (yet) wrapped by the SDK; call it with
+`httpx` directly or `client._request("POST", "/v1/library/import", ...)`.
+
+### Searching external sources
+
+Search external providers (Freesound, Openverse, …) for media the library doesn't have yet, then
+import the ones you want. The search is **read-only** — nothing is imported until you call
+`import_`, and every result carries the licence + attribution you need to honour.
+
+```python
+sources = client.sources.list()         # which providers are registered
+
+result = client.sources.search(
+    "rain on a tin roof",
+    providers=None,                        # None = every source; or "freesound" / ["freesound", …]
+    k=12,                                   # per-provider cap
+    modality="audio",                       # narrow to sources serving this kind
+)
+
+for c in result.results:                   # provider-tagged Candidates (not yet imported)
+    print(c.provider, c.title, c.license, c.preview_url)   # c.duration / c.size / c.content_type too
+
+for skip in result.skipped:                # a source that couldn't answer, and why
+    print("skipped", skip.provider, "—", skip.reason)      # e.g. missing credentials
+
+asset = client.sources.import_(result.results[0])   # pull that candidate into the library
+# or name it yourself: client.sources.import_(source_id="freesound", external_id="12345")
+```
+
+- `search` fans out over every registered source by default; a source that's missing credentials,
+  is down, or doesn't serve the ask lands in `result.skipped` (with a reason) instead of failing the
+  whole call — so you always get the sources that *did* answer.
+- Each `Candidate` is external-only until imported: `provider` + `external_id` are what
+  `import_(candidate)` re-resolves to fetch the bytes. `import_` returns the library `Asset`;
+  re-importing the same candidate is a no-op that returns the existing one.
+- `import_` takes an optional `modality=` / `description=` to override what the source reports.
+
+### Chat & agents
+
+```python
+reply = client.chat("what's a good rainy-day soundscape?", model="gpt-4o-mini", temperature=0.7)
+print(reply)             # a str with .model / .raw
+for chunk in client.chat("hi", stream=True):
+    print(chunk, end="")
+
+reply = client.agent("find a calm track and tell me its title", tools=[my_search_tool])
+```
+
+`chat(messages, *, model=, stream=False, strict_params=False, **params)` posts to
+`/v1/chat/completions`; `**params` are extra OpenAI parameters (`temperature`, `max_tokens`,
+`tools`, …) forwarded verbatim. `agent(prompt, *, tools, model=, max_turns=6, **params)` runs a
+tool-using loop, forwarding `**params` to every `chat` call it makes.
+
+> **Provider-unsupported params are silently dropped by default.** Atrium routes chat through
+> LiteLLM, which drops a sampling param a model doesn't support (e.g. a non-default `temperature`
+> on an OpenAI "gpt-5"-family model) rather than erroring — matched by **model-name pattern**, so a
+> self-hosted model named like a known family inherits that family's quirks. Pass
+> `strict_params=True` to error instead, with the provider's own message. This only applies to
+> models routed through Atrium/LiteLLM — a model registered via `add_direct_model` bypasses all of
+> it: its request body goes verbatim to the endpoint.
+
+---
+
+## 4. Rooms & sessions
+
+**Two kinds of traffic flow through a room.** *Messages* are the named things on the wire — react to
+them by name with `room.on("play")`, `room.on("presence.join")`, `room.on("mood.switch")`; the
+vocabulary is open, anyone can `room.send` any type. *Audio* is the live sound in the room — process
+it with `async for` over the `audio_*` family (`audio_vectors` / `audio_scores` / `audio_transcripts`
+/ `audio_clips`), streams the SDK assembles for you from the room's raw `audio.snippet` windows, with
+any refinement (embedding, transcription) running on *your* credentials. Transcripts show the duality
+directly: `room.on("transcript.final")` **consumes** a caption someone else is already broadcasting
+(free — you read the wire), while `room.audio_transcripts()` **computes** your own from the audio.
+
+### Sync: host a room
+
+```python
+from hci_atrium import Atrium
+
+client = Atrium()
+room = client.rooms.open(name="living room")   # named → stable connect code across runs
+print(room.connect_code)
+
+with client, room:                              # on exit: delete anonymous / leave a named room standing
+    for event in room.receive():                # blocks; SSE stream
+        if event.source != "host":
+            print(event.type, event.payload)
+```
+
+`rooms.open(*, name=None, project=None, embedding_space=None)` — give it a `name` to reuse the same
+room (and connect code) across runs; the `name → room id` mapping is cached in
+`~/.atrium/rooms.json`. Anonymous (`name=None`) opens a fresh room every call. `rooms.get(id)` /
+`rooms.list()` fetch existing rooms.
+
+`room.send(type, payload=None, *, to=None, include_self=False, source=None, ephemeral=False,
+ack_id=None, reply_to=None)` — fire-and-forget, never stored. `to` (a connection id, an
+`identity`, or a list) unicasts/multicasts; default fan-out is everyone else. `ephemeral=True`
+marks throwaway noise (beats, cursors) that a recorder skips.
+
+`room.receive(*, identity=None, announce=None)` — blocking SSE iterator of `Event`s; sets
+`room.connection_id` from the first `connection.ready` frame. Reconnect yourself on drop (rooms
+have no replay).
+
+### Join without an account
+
+```python
+from hci_atrium import join_room
+
+with join_room("ABC123") as room:      # connect code, no account, no full client
+    room.send("message", {"text": "hi"})
+    for event in room.receive():
+        ...
+```
+
+### Sessions (durable log)
+
+```python
+session = client.sessions.start(name="P07 · pilot", participant_ref="P07")
+session.event("note", {"text": "participant arrived"})
+
+session = client.sessions.resume(session_id)   # continue an existing session by id — raises if unknown
+print(session.last_seq)   # last_seq reflects the session as of the fetch — re-`resume()` to refresh it
+```
+
+### Recording a room into a session
+
+```python
+session = client.sessions.start(name="studio take")
+room = client.rooms.open(name="studio")
+
+with room.record(into=session):        # starts a background capture thread immediately
+    room.send("note", {"text": "session started"})
+    room.send("beat", {"bpm": 120}, ephemeral=True)   # skipped — ephemeral
+    ...
+```
+
+`ephemeral=True` events, presence, and non-`signal` frames are skipped; everything else is
+appended with `via={"room_id", "room_name", "from", "to"}`. A dropped stream reconnects with
+backoff (gaps are lost — rooms have no replay); check `rec.alive` / `rec.error`.
+
+### Reading sessions back (analysis)
+
+The write side (`sessions.start`/`resume`, `session.event`) has a read-model twin for analysis:
+
+```python
+for info in client.sessions.list(phase="pilot"):    # newest first; phase: a string or a list
+    print(info.id, info.participant_ref, info.condition, info.last_seq)
+
+info = client.sessions.get(session_id)               # one session — has_transcript populated here
+for row in client.sessions.events(session_id, after=0, limit=500):
+    print(row.seq, row.type, row.payload, row.source, row.via)
+
+client.sessions.export(session_id, "csv", path="out/")           # "jsonl"|"csv"|"transcript"|"bundle"
+client.sessions.export_bundle([id_a, id_b], path="out/study.zip")  # several sessions, one zip
+```
+
+- `sessions.list(*, project=None, phase=None)` returns `SessionInfo` rows for your default project
+  (a scoped key's project, else Personal); `""` as a phase matches sessions with no phase set.
+  `has_transcript` is `None` in list results — only `sessions.get(id)` populates it. There is **no
+  participant filter server-side**: filter the rows on `participant_ref` yourself.
+- `sessions.get(id)` is the read model; `sessions.resume(id)` hits the same endpoint but returns the
+  live `Session` handle for continued logging.
+- `sessions.events(id, *, after=None, limit=None)` pages the durable log as flat, pandas-friendly
+  `SessionEvent` rows. `after` is a **sequence number**, not a timestamp (there is no time filter
+  server-side); `limit` is 1..500 (server default 100).
+- `export(id, format="jsonl", *, path=None)` returns the raw `bytes` — or, with `path=` (a file, or a
+  directory to derive the filename in), writes them and returns the written `Path`. Each format is a
+  distinct server route, not a `?format=` param; `"transcript"` 404s when the session has none.
+- `export_bundle(ids, *, path=None)` zips several sessions. `ids` is required (no "all sessions"
+  mode) and capped at 100 **distinct** ids — more raises `ValueError` rather than truncating.
+
+### Mirror your app's own activity: `room.trace()`
+
+One call mirrors what the SDK is doing on this client into the room as `trace.*` signals — so an
+observation dashboard, or any code-joined peer, can watch the app think:
+
+```python
+with room.trace():                                            # or: t = room.trace(); …; t.stop()
+    client.library.search("calm rain", modality="audio")      # -> trace.library.search
+    room.play(hit, layer="music", mode="queue")               # -> trace.play
+```
+
+- A traced call sends `trace.<label>` (`trace.library.search` / `trace.chat` / `trace.play`) carrying
+  a one-line summary plus a capped detail; a recorder starting/stopping sends `trace.state.<label>`.
+- **Default off** — it broadcasts app internals to anyone holding the connect code. Tracing stops on
+  `t.stop()` or when the room's `with` exits, and a trace failure never breaks the traced call.
+- Ephemerality is per-signal: `trace.library.*` / `trace.chat` are **durable** (they happen outside
+  the room, so the trace is their only record — a recorder captures them into the session), while
+  `trace.play` and `trace.state.*` are ephemeral (the underlying `play` already rides the room).
+- Async: `room.trace()` is still a plain call, but scope it with `async with room.trace(): …`.
+
+### Async: `on`/`serve`, presence, targeted request/reply
+
+The async room adds an event-dispatch style on top of the same transport — register a handler per
+signal type, then `serve()` to run until cancelled:
+
+```python
+import asyncio
+from hci_atrium import AsyncAtrium
+
+async def main() -> None:
+    async with AsyncAtrium() as client:
+        room = await client.rooms.open(name="lab")
+        print(room.connect_code)
+
+        @room.on("presence.join")
+        def on_join(event):
+            print("joined:", event.payload.get("identity"))
+
+        @room.on("ping")
+        async def on_ping(event):
+            return {"pong": True}          # only sent back if the ping was a `request(...)`
+
+        await room.connect(identity="host")
+        await room.serve()                 # blocks; reconnects transient drops with backoff
+
+asyncio.run(main())
+```
+
+- `await room.connect(*, identity=None, announce=None)` joins live and starts the dispatcher,
+  returning the connection id. `presence.join`/`presence.leave` arrive as ordinary signals — just
+  register handlers for them.
+- `await room.request(type, payload=None, *, to, timeout=None)` sends to one peer and awaits its
+  single reply (the peer's handler return value) — `to` is required. Raises `TimeoutError` on no
+  reply within `timeout` (default: the room's request timeout).
+- A handler's return value becomes the auto-reply when the *incoming* signal itself was a
+  `request(...)` (carried an `ack_id`) — a responder never touches correlation plumbing.
+- Don't mix `on`/`serve` with `receive()` on the same room — each opens its own stream (a second
+  connection, a second presence join).
+
+### Live audio vectors (async)
+
+If a Player in the room has its **"Share audio clips"** toggle on (default off — it shares actual
+audio, so consent lives on the device making sound), you can get a live semantic embedding of what
+the room currently sounds like — ~10 s windows, embedded in the deployment's default audio search
+space, so each vector is directly comparable against library-derived vectors:
+
+```python
+async for v in room.audio_vectors():        # zero-args: default audio space, that space's model
+    score = cosine(v.vector, tense_anchor)  # v: AudioVector(vector, space, sequence,
+    await room.send("mood.update", {"score": score})  #    window_seconds, timestamp)
+```
+
+- Subscribing **is** the demand signal: while no consumer is subscribed, an armed Player captures
+  nothing. Break out of the loop to end the subscription.
+- **The loop blocks until a Player shares audio.** If no participant is already announcing the
+  snippet-producer role at subscribe time, one warning is logged and the loop keeps waiting (no
+  timeout) — nothing yields until someone turns their Player's "Share audio clips" toggle on.
+- `space=` pins a different space; `model=` overrides the embedder (rarely needed — by default the
+  space's own model is resolved once at subscribe). Embedding runs on *your* credentials/compute.
+- Vectors are ephemeral room signals, never stored. Record the room into a session if a study
+  needs a durable trace.
+- `relay=True` also relays each vector into the room as an `audio.vector` signal
+  (`ephemeral=True`, recorder-skipped) — so a loginless, code-joined peer (e.g. a Unity scene) can
+  read the room's live mood vector without credentials of its own
+  (`docs/reference/rooms-sessions-protocol.md`).
+
+`room.audio_scores(anchors, *, space=None, model=None, top_n=1, relay=False)` fuses
+`audio_vectors()` with per-anchor `library.compare` scoring — a live "which anchor does the room
+sound like right now" signal, no manual cosine math:
+
+```python
+async for frame in room.audio_scores({"tense": "a tense, anxious atmosphere", "calm": "calm and peaceful"}):
+    print(frame.scores)   # {"tense": 0.71, "calm": 0.22} — calibrated per-anchor compare scores
+    print(frame.mix)      # scores normalized to sum 1 (uniform when every score is 0 — gate on
+                           #    max(frame.scores) to tell "no match" from "anchors tied")
+```
+
+- `anchors` maps a name to anything the `by.*` grammar accepts (bare `str`/`Asset`/`list[float]`,
+  `by.file(...)`/`by.asset(...)`/`by.concept(...)`) — **or a list** of those, a few-shot category
+  (e.g. `"tense": ["a tense, anxious atmosphere", "a horror movie soundtrack"]`) scored as the mean
+  of its **top-`top_n`** members (default `top_n=1` — the nearest member wins, so spread-out
+  examples don't blur into an average; pass a larger `top_n` to widen back toward the plain mean —
+  `top_n >= len(members)` averages every member).
+- Every window scores its anchors concurrently (`asyncio.gather`); a handful of `compare` calls per
+  ~10 s window is cheap.
+- Every anchor is validated once, before waiting on any frame: a typo'd/unresolvable `by.concept(…)`
+  anchor raises `AtriumError` naming it immediately, rather than only failing mid-stream.
+- `relay=True` forwards straight to `audio_vectors` — it relays each window's raw
+  `audio.vector` signal (see above), **not** the computed `scores`/`mix` (peers compare via the
+  embed broker instead).
+- No smoothing: every `ScoredAudio` frame is independent. Ease/debounce the stream yourself —
+  `hci_atrium.reactive.Decider` is a small, framework-free helper for turning a live score dict into
+  a stable "current winner":
+
+```python
+from hci_atrium import Decider
+
+decider = Decider(margin=0.1, dwell=2.0)   # a new winner must beat the current one by 0.1,
+                                            # and stay switched for at least 2s
+async for frame in room.audio_scores(anchors):
+    winner = decider.update(frame.scores)  # the new winner's name, or None if unchanged
+    if winner is not None:
+        await room.send("mood.switch", {"to": winner})
+```
+
+`decider.current` holds the standing winner between updates; with two anchors this is a plain
+binary hysteresis switch.
+
+### Live transcripts (async)
+
+`room.audio_transcripts()` is the speech-to-text counterpart of `audio_vectors()` — it consumes the
+same Player-shared `audio.snippet` stream, but transcribes the audio into **live captions** instead
+of embedding it, yielding a `Transcript` (a `str` subclass) per **finalized sentence**:
+
+```python
+async for t in room.audio_transcripts():                 # zero-args: deployment default model
+    print(str(t))                                        # a settled sentence; t.raw has start/end
+```
+
+- Same demand gate as `audio_vectors`: subscribing announces the `audio-snippet-consumer` role, so
+  an armed Player only captures while a consumer is subscribed; break out of the loop to end it (the
+  stream tears down deterministically on `break`). The same one-time "no Player is sharing audio"
+  warning fires if nobody is producing yet.
+- **Streaming by default.** When the deployment offers the live transcription route, snippets flow
+  through it and you get per-sentence finals as the speech settles — each with `.final == True` and
+  `t.raw` carrying the sentence's `start`/`end`. Pass `partials=True` to *also* get the revisable
+  live hypothesis (`.final == False`); a partial **replaces** the previous one wholesale, so render
+  the latest, don't append.
+- `model=` / `language=` pick the transcription model and language hint (omit `language` to
+  autodetect; omit `model` for the deployment default). Transcription runs on *your*
+  credentials/compute. An empty-text sentence is dropped unless `skip_empty=False`; a snippet the
+  server can't transcribe is skipped so one bad frame can't kill the stream, but a rejected
+  credential (401/4401) raises `AuthError`.
+- **Degradation ladder.** If the streaming route can't be reached — an old deploy, a proxy that
+  strips the WebSocket upgrade, a refused connection — this degrades to per-clip batch
+  transcription: one independent transcript per ~10 s window, **no partials**, the clip's format
+  taken from each frame's own MIME type (the Player ships Opus-in-WebM). On *this* fallback path
+  each transcript carries its source frame's `sequence` and `window_seconds` under
+  `t.raw["snippet"]` — a cheap ordering handle that has no equivalent on the streaming path (there's
+  no 1:1 snippet↔sentence correlation). The fallback is **connect-time only**: once streaming is
+  live a mid-session drop *raises* rather than silently degrading.
+
+**Rooms-free — `client.transcribe_live(chunks, ...)`.** Not everything lives in a room. This runs
+the same streaming engine over any async iterable of audio byte-chunks (a mic, a file, a socket),
+yielding the same finals (and `partials=True` partials):
+
+```python
+async for t in client.transcribe_live(mic_chunks(), format="pcm16", sample_rate=16000):
+    print(str(t))
+```
+
+- **Container clips** (`format="wav"` default, or `"webm"`/`"ogg"`/…): each chunk is a
+  self-contained, decodable clip — the browser `MediaRecorder` / room-snippet shape.
+- **Raw PCM** (`format="pcm16"`): a continuous PCM16LE **mono** byte stream, the shape native mic
+  libraries (`sounddevice`/`pyaudio`) yield. This **requires** `sample_rate=` — raw PCM is
+  headerless, so the SDK can't sniff the capture rate. Passing `sample_rate=` with a container
+  format is an error (containers carry their own rate).
+
+**In-room broker — `room.transcribe()`.** The broker form consumes the room's snippet stream on
+**your** credentials and publishes the transcript back into the room as signals, so any consumer —
+including a loginless, code-joined tool — reads captions without transcription access of its own:
+
+```python
+async with room.transcribe():          # a side effect: starts immediately, stops on room exit
+    ...
+
+# any consumer, even a code-joined peer with no credentials of its own:
+@room.on("transcript.final")
+def on_line(event):
+    print(event.payload["seq"], event.payload["text"])
+```
+
+- `transcript.partial` — `{"text": …}`, **ephemeral** (a live caption the recorder skips).
+  Wholesale-replaced — render the latest, don't append.
+- `transcript.final` — `{"text": …, "start": …, "end": …, "seq": n}`, durable. `seq` is a per-handle
+  counter from 0; the signal's `source` is `"transcriber"`. Bridge the room into a session
+  (`room.record(into=session)`) and each final is persisted — no new recording API, the `ephemeral`
+  flag alone drives the recorder split.
+- Like `record`, it's a side effect: started in the background, stopped when the room's `async with`
+  exits — or `await handle.stop()` / scope it with `async with room.transcribe(): …`. See
+  `examples/live_transcript.py` for the manual live-test recipe.
+
+### Live audio clips (async)
+
+`room.audio_clips()` is the rawest member of the family — it hands you each ~10 s window decoded and
+nothing else (no embedding, no transcription — cost: none), for custom processing:
+
+```python
+async for clip in room.audio_clips():                    # zero-args
+    do_something(clip.data, clip.mime)                   # AudioClip(data, mime, sequence,
+                                                          #   window_seconds, source, source_name)
+```
+
+Same demand gate and one-time warning as `audio_vectors`. Producer-agnostic: a Player (v1 frames,
+`clip.source is None`) or a Capture tool (v2 frames — `clip.source` is the sender's connection id,
+`clip.source_name` its announced name, resolved from the subscribe-time roster).
+
+### Share your embedding / chat access: `offer_embeds` / `offer_chat` (async)
+
+Let other room participants use your embedding/chat access — they ask, your client answers. A
+loginless, code-joined peer (e.g. a Unity scene) has no Atrium credentials of its own. Register one
+of these on an already-authed room **before** `connect()`/`serve()` — the offer is only advertised
+when the connection opens, so calling either after connecting raises `AtriumError`. Once registered,
+it answers that peer's requests over the room — riding the ordinary `on`/`request` machinery, no new
+transport:
+
+```python
+room.offer_embeds(spaces=["clip"])       # spaces=None (default): unrestricted
+room.offer_chat(model="gpt-4o-mini", max_tokens=200)   # model=None: the deployment/client default
+await room.connect(identity="broker")
+await room.serve()
+```
+
+- `offer_embeds` handles `embed.resolve`: `{anchors: {name: <descriptor>}, space?}` →
+  `{space, vectors: {name: [floats]}, errors?}`. A descriptor is `{"text": "…"}` /
+  `{"concept": "name", "collection"?: "…"}` / `{"vector": [...]}` — the same shapes the `by.*`
+  operand grammar builds for `compare`. **The requester chooses `space`** (omitted → the
+  deployment's default text space); `spaces=` optionally allowlists what this broker serves. A
+  failing anchor (unknown concept, an unsupported `asset` descriptor) lands in `errors` without
+  failing the rest; a malformed/oversized request or a disallowed space gets a whole-request
+  `{"error": "…"}` reply. Text is embedded with *this* client's own credentials; repeated
+  text/concept anchors are cached.
+- `offer_chat` handles `chat.generate`: `{messages: [{role, content}, …]}` → `{text, model}`.
+  Stateless (no history kept). The **broker** pins `model` (cost control — the requester can't
+  choose it) and caps `max_tokens`; malformed/empty/over-sized `messages` get `{"error": "…"}`.
+  **Billing**: any peer holding the connect code can trigger a reply on your model billing (there's
+  a per-call `max_tokens` cap, but no aggregate limit across calls) — rotate the code for an open
+  study, or prefer a local model, if that's a concern.
+- Both announce a discoverable role in the presence roster (`announce.roles`) —
+  `"embed-broker"` / `"chat-broker"` — so a code-joined peer can find them. The full wire dialect
+  (including the `audio.vector` info signal from `relay=True` above) is in
+  `docs/reference/rooms-sessions-protocol.md`.
+
+### Offer live captions + recording to a Capture tool: `offer_transcription` / `offer_audio_capture` (async)
+
+The Capture tool (`/tools/capture/?code=…`) is a loginless voice surface. The host publishes two
+standing-service offers; the tool's toggles turn them on/off over the room (`<service>.start` /
+`<service>.stop`, each replied `{"ok": True}` / `{"error": …}`). Register both **before**
+`connect()`/`serve()` (like the brokers above):
+
+```python
+async with room.record(into=session):    # the single durable binding — see below
+    room.offer_transcription()           # "Live captions" toggle → transcript.* signals
+    room.offer_audio_capture()           # "Save recording" toggle → audio into the session
+    await room.serve()
+```
+
+- `offer_transcription(model=None, language=None)` runs the same engine as `room.transcribe()` on
+  *your* credentials while on, publishing `transcript.partial` (ephemeral) / `transcript.final`
+  (durable) — each stamped with the producer's `source` (connection id) and roster-resolved
+  `source_name`. Bare call is the happy path (deployment default model, language autodetect).
+- `offer_audio_capture()` is **session-less**: `room.record(into=session)` is the single durable
+  binding, and the capture bridge writes recordings into **the active recorder's** session. So the
+  "Save recording" toggle is meaningful only while the room is being recorded, and availability
+  rides the wire so the tool can show it accordingly:
+  - a `capture.status` request replies `{"ok": True, "available": <bool>}` — available ⇔ ≥1 recorder
+    is active on this room handle;
+  - every recorder start/stop broadcasts an ephemeral `capture.available` `{"available": <bool>}`;
+  - `capture.start` with **no** active recorder replies
+    `{"error": "no active recorder — call room.record(into=session) first"}`.
+  On `capture.start` it binds the **first** active recorder's session and bridges each `audio.snippet`
+  frame into one recording per source (keyed by announced `name`, else connection id — a same-name
+  reconnect continues the same recording). When that recorder stops (explicit stop, the room's
+  `async with` exit, or room close) every open recording is finalized, the bridge disengages, and
+  `capture.available: false` is broadcast. **Exactly one recorder feeds audio** — a second concurrent
+  recorder warns once and is not double-written.
+- See `examples/capture_session.py` for the whole shape (recording off until you flip the toggle).
+
+### Driving the Player's audio layers
+
+The hosted Player (`/tools/player/?code=…`) plays sustained, mixable **layers** — background music,
+ambient beds, SFX. A layer is just a named, independently-mixed channel (its own volume + effects);
+every layer can hold both a single-track **queue** and overlapping **one-shots** at once — the
+difference is `mode`, not the layer. `Room` and `RoomParticipant` carry the app side of the
+`play` / `layer.*` dialect (`docs/reference/audio-layers-dialect.md`):
+
+```python
+room.configure_layers([                          # optional — layers auto-vivify on first use
+    {"id": "music", "label": "Music", "volume": 0.5},
+    {"id": "ambient", "crossfade_ms": 3000},
+    {"id": "sfx"},
+])
+# play() takes an Asset / SearchHit, a content-URL or asset-id string, a track dict, or a list:
+room.play(tavern_song, layer="music", mode="queue", transition="now")     # crossfade a song in
+room.play({"asset_id": rain.id, "loop": True}, layer="ambient", mode="queue")  # looping bed
+room.play(beds, layer="ambient", mode="queue", repeat=True, shuffle=True)  # endless shuffled ambience
+room.play(clang, layer="sfx")                                             # one-shot (mode defaults to oneshot)
+room.play([hit_a, hit_b], layer="music", mode="queue", transition="queued")    # queue several
+room.play({"asset_id": clang.id, "delay_seconds": 0.2, "spatial": {"x": -1, "y": 0, "z": 0}}, layer="sfx")
+
+room.clear_layer(layer="ambient", fade_out_ms=2000)                       # one layer (queue + one-shots)
+room.clear_all(fade_out_ms=1000)                                          # stop all audio
+room.set_layer_effects("music", {"lowpass": {"hz": 700}}, fade_ms=600)   # backroom muffle
+room.set_layer_effects("ambient", {"reverb": {"mix": 0.4, "ir": "cave"},          # wet convolution send
+                                    "echo": {"time_ms": 330, "feedback": 0.35}})   # + a slapback
+room.set_layer_effects("*", {}, fade_ms=800)     # every existing layer back to neutral
+room.set_layer_position("music", 0, 0, -2, fade_ms=800)   # place the whole layer 2 m in front (HRTF)
+state = room.query_layers(timeout=10.0)          # {"layers": {"music": {...}, ...}} — blocking pull
+
+for snap in room.watch_layers():                 # subscribe: a fresh snapshot on every change
+    music = snap["layers"].get("music", {})
+    if music.get("remaining_ms", 0) < 60_000 and music.get("queued_count", 0) < 2:
+        room.play(next_track, layer="music", mode="queue", transition="queued")  # refill ahead of silence
+```
+
+`play(source, *, layer=None, mode="oneshot", transition="now", repeat=False, shuffle=False)`.
+`repeat`/`shuffle` are queue-mode modes — `repeat` loops the whole queue, `shuffle` randomizes its
+order (combinable). A track dict carries per-sound options — `loop` (a single sustained track,
+distinct from queue `repeat`), `segment` (a stored sound-event id),
+`clip_start_seconds`/`clip_end_seconds`, `gain`, `spatial`, and (one-shot)
+`delay_seconds`/`max_duration_seconds`/`fade_in_ms`/`fade_out_ms`.
+
+`set_layer_effects(layer, effects, *, fade_ms=None)` sets the layer's whole effect bus at once —
+`lowpass`/`highpass` (filters), `reverb` (a **wet send**: `{"mix": 0.4, "ir": "hall"}`, `ir` one of
+`room`/`hall`/`cave`/`outdoor`, or `ir_asset` an asset id to convolve with your own impulse
+response), and `echo` (`{"time_ms": 330, "feedback": 0.35, "mix": 0.25}`). It's the state, not a
+patch: an **absent** implemented key ramps that effect back to neutral, so `{}` clears the bus.
+`layer="*"` applies the same state to **every existing** layer (it doesn't auto-vivify new ones), the
+same wildcard `clear_all` uses.
+
+`set_layer_position(layer, x, y, z=0.0, *, fade_ms=None, distance=None)` places a whole layer in 3D
+(HRTF panning of everything on it) — the listener sits at the origin, `+x` is right, `+y` up, and
+**negative `z` is in front**. The panner is created lazily on the first call, so a layer you never
+position keeps the plain, unpanned graph. `distance=` opts into distance attenuation
+(`{"model": "inverse", "ref": 1, "max": 40, "rolloff": 1}`; `model` one of
+`linear`/`inverse`/`exponential`) and is **sticky** — a later move that omits it keeps the model, and
+`{"rolloff": 0}` goes back to direction-only. There is no `"*"` wildcard: position is per-layer. A
+per-sound `spatial` (`{"x", "y", "z", "distance"?}` on a track dict) composes *within* a positioned
+layer — a placed sound inside a placed group — and a per-sound `effects` dict stacks in front of the
+layer's bus rather than exempting the sound from it (for a sound that must stay dry, play it on its
+own clean layer). Full dialect: `docs/reference/audio-layers-dialect.md`.
+
+The Player **loudness-normalizes** library audio to a consistent level by default (a per-track gain
+from the asset's measured loudness toward −18 LUFS, plus a master limiter). Playing an `Asset` /
+`SearchHit` attaches the measured loudness automatically, so it just works; the listener can turn it
+off (Settings / `?normalize=off`).
+`query_layers` opens a short-lived room connection (peers see a presence join/leave) and returns the
+Player's real snapshot — current track, queue, one-shot count, elapsed/remaining per layer.
+`watch_layers` subscribes and yields that same snapshot on every change (plus a ~1 s heartbeat while
+playing) until you break out — so a soundscape loop refills a low queue before it runs dry. The
+low-water threshold is yours to pick off the snapshot; the Player pushes raw state. The **async**
+client has identical signatures — `await room.play(...)`, `await room.clear_all()`,
+`await room.query_layers()` (a broadcast request, no `to=` needed; first Player to reply wins), and
+`async for snap in room.watch_layers():`.
+
+Need a Player to drive? Launch the hosted one and only open a tab if none is connected:
+
+```python
+if not room.has(identity_prefix="player:"):   # per-worker roster check (best-effort)
+    room.open_player()             # opens the hosted Player tab
+print(room.player_url())           # the plain launch URL — print / hand out / QR-encode
+room.open_player(analysis=False, clips=True)   # bake the room-sharing opt-ins into the URL
+url = room.player_url(clips=True)  # …or just build the URL with those params
+```
+
+`room.participants()` reads the room's current presence roster (a short observe stream) as typed
+`Participant`s — `connection_id`, `identity`, `name`, `roles` (the announce's `role`/`roles` shapes
+merged), `connected_at`, and the original `raw` dict. `room.has(role=None, *, name=None,
+identity_prefix=None)` is the boolean sugar over it: give at least one predicate (several are ANDed)
+— `role` matches the merged roles, `name` the announced name, `identity_prefix` the identity's
+leading segment. A hosted Player announces identity `player:web` (no role), so
+`room.has(identity_prefix="player:")` is the launch-once guard. Both are best-effort per web worker.
+
+`player_url(*, analysis=None, clips=None)` and `open_player(*, analysis=None, clips=None)` take the
+Player's URL settings as typed kwargs (`bool` → `on`/`off`; `None` omits, keeping the Player default).
+(async: `await room.participants()` / `if not await room.has(identity_prefix="player:"):
+room.open_player()` — `open_player`/`player_url` stay sync.)
+
+The observation dashboard has the symmetric pair: `room.dashboard_url()` builds
+`<base>/tools/dashboard?code=<code>` (the dashboard takes only the connect code) and
+`room.open_dashboard()` opens it in a tab — both sync, on the sync and async clients alike.
+
+The hosted Viewer is the visual sibling — put an image (or video) on a shared screen over the room:
+
+```python
+room.show(asset_id="…", caption="Rainy market")   # or url="https://…", projection="360"
+room.clear_view()                                  # blank the stage
+room.open_viewer()                                 # launch a viewer tab (or print room.viewer_url())
+```
+
+`show` takes exactly one of `asset_id` / `url`; `viewer_url()` / `open_viewer()` mirror the Player
+pair (both sync).
+
+---
+
+## 5. Surveys
+
+A survey is a durable data object on a session, guarded by a one-time capability token:
+
+```python
+survey = client.surveys.start(into=session)          # uses the project's DEFAULT template
+# or: client.surveys.start("onboarding-v2", into=session, name="intro survey", return_to="https://...")
+
+survey.token     # once-only capability: read+write exactly this object
+survey.url       # hosted survey tool URL, token in the fragment — hand to the participant
+survey.open()    # open `survey.url` in the local browser (same-machine delivery)
+```
+
+`Surveys.start(template=None, *, into, name=None, return_to=None, link_params=None)` —
+`template=None` pins the project's default template; naming one pins *that* template's current
+version, so later edits to the template never change an already-started survey. `return_to` seeds an
+`app`-controlled return button on the survey's end page. `link_params` (a dict) is appended to
+`survey.url` as query parameters — inserted before its `#token=` fragment — for the template's page
+modules (`{"modules": "build,test"}`) or any question's `param` binding.
+
+Manage templates (project-scoped, numbered versions) — safe to rerun every script start:
+
+```python
+client.surveys.template(
+    "onboarding-v2",
+    {"pages": [...]},          # dialect: docs/reference/survey-template-dialect.md
+    project="p_4mD2qX",        # or rely on the client's default project scope
+    default=False,
+    description="the intro survey",   # applied on CREATE only, like the SPA's import
+)                              # -> {"name", "version", "is_default", "changed", "created"} —
+                               #    idempotent, writes only if the body actually changed. The
+                               #    server is copy-on-write (it overwrites the current version in
+                               #    place while no response is pinned to it), so read `changed`,
+                               #    not the version number, to tell a write from a no-op
+
+client.surveys.templates(project="p_4mD2qX")     # list: name, current_version, is_default
+client.surveys.upload_file("logo.png", project="p_4mD2qX", role="attachment")
+                               # -> {"id", "url", "filename", "content_type"} — reference `id` from
+                               #    a template body's `image` field
+```
+
+Read the answers back for analysis, by template **name** (not a started `Survey`), across the
+project's sessions:
+
+```python
+rows = client.surveys.responses("onboarding-v2", phase="post", submitted_only=True, limit=500)
+for r in rows:
+    print(r.participant_ref, r.session_id, r.status, r.version, r.contents)   # contents = raw answers
+
+csv = client.surveys.responses("onboarding-v2", format="csv")   # bytes: one row per response
+```
+
+`responses(template, *, project=None, phase=None, submitted_only=False, limit=200, format="rows")` —
+newest first, resolved with `project=` exactly like `template`/`templates`. `phase` (a string or a
+list; `""` matches unset) filters by the response's session phase; `submitted_only` drops drafts;
+`limit`'s server ceiling is 500. `format="rows"` gives `SurveyResponse` rows (`contents` stays a free
+dict — the survey dialect is your app's); `format="csv"` gives the CSV export as `bytes` with
+question-id columns.
+
+`start_survey(template=None, *, into, name=None, return_to=None, link_params=None)` (module-level) is sugar for
+`into._client.surveys.start(...)` — handy when you only have the session in hand.
+
+**Async** mirrors every method 1:1 (`await client.surveys.start(...)`, `await async_start_survey(...)`).
+
+---
+
+## 6. Home Assistant bridge
+
+`hci_atrium.ha.HomeAssistantBridge` runs near your HA instance, joins an already-open room, and
+declaratively wires room signals to HA services (and HA state back into the room). It's
+**async-only**. `websockets` ships as a core dependency — nothing extra to install.
+
+```python
+import asyncio
+from hci_atrium import async_join_room
+from hci_atrium.ha import HomeAssistantBridge
+
+async def main() -> None:
+    room = await async_join_room("ABC123")
+    bridge = (
+        HomeAssistantBridge("ws://homeassistant.local:8123/api/websocket", "***token***")
+        .media_sink("media_player.living_room", "media_player.kitchen")   # play `play` intents
+        .on_signal(                                                        # any other signal -> any HA service
+            "plate.pulse", domain="number", service="set_value",
+            entity_id="number.plate_intensity", data=lambda p: {"value": p["strength"]},
+        )
+    )
+    try:
+        await bridge.run(room)     # blocks until cancelled
+    finally:
+        await room.aclose()
+
+asyncio.run(main())
+```
+
+- **`media_sink(*entity_ids, forward_state=True)`** — plays the room's `play` intent (the typed
+  `{playback: {source, ref, mode?}}` shape, or the legacy `content_url`/`asset_id` shapes) via
+  `media_player.play_media` (+ `.shuffle_set` for a shuffled playlist) on each entity. Also
+  forwards those entities' state back as `media.state` unless `forward_state=False`.
+- **`on_signal(type, *, domain, service, entity_id=None, data=None)`** — maps one room signal type
+  to one HA service call; `data` is a static dict or `callable(payload) -> dict`. Several
+  registrations for the same `type` all fire.
+- **`forward_state(entity_ids, *, as_type="media.state", debounce=True)`** — forwards HA
+  `state_changed` on these entities into the room. Call it directly for entities outside
+  `media_sink`, or to change `as_type`/`debounce`.
+- **`await bridge.run(room)`** — wires everything, announces the bridge's identity, and runs both
+  legs (room dispatcher + HA connection) until cancelled. Raises only on a terminal room refusal
+  (a 4xx); the HA leg reconnects with backoff on its own.
+
+**Zero-code CLI**, once the room exists:
+
+```sh
+atrium ha-bridge --code ABC123 \
+    --ha-url ws://homeassistant.local:8123/api/websocket --ha-token *** \
+    --media-player media_player.living_room media_player.kitchen
+```
+
+Every flag also reads an env var fallback: `ATRIUM_ROOM_CODE`, `HA_URL`, `HA_TOKEN`,
+`HA_MEDIA_PLAYERS` (comma-separated).
+
+---
+
+## 7. Recipes
+
+### Search the library and play the top hit into a room (sync)
+
+```python
+from hci_atrium import Atrium
+
+client = Atrium()
+
+with client, client.rooms.open(name="living room") as room:
+    print(f"connect code: {room.connect_code}")
+    hits = client.library.search("calm rainy afternoon", modality="audio", limit=1)
+    if hits:
+        asset = hits[0].asset
+        room.send("play", {"playback": asset.playback.as_signal()})
+        print(f"playing: {asset.title or asset.filename}")
+# on exit: leaves the named room standing (code kept for next run), then closes the client
+```
+
+### Record a study session with a survey
+
+```python
+from hci_atrium import Atrium
+
+client = Atrium()
+session = client.sessions.start(name="P07 · pilot", participant_ref="P07")
+session.event("phase", {"name": "intro"})
+
+survey = client.surveys.start(into=session)   # the project's default template
+print(f"send this to the participant:\n  {survey.url}")
+survey.open()   # or: hand survey.token / survey.url to a participant-facing device
+
+session.event("phase", {"name": "survey_sent"})
+print(f"session {session.id} — {client.sessions.resume(session.id).last_seq} events so far")
+```
+
+### A room consumer that reacts to signals and replies to requests (async)
+
+```python
+import asyncio
+from hci_atrium import async_join_room
+
+async def main() -> None:
+    async with await async_join_room("ABC123") as room:
+
+        @room.on("play")
+        async def on_play(event):
+            intent = event.payload.get("playback")
+            print("play:", intent)
+
+        @room.on("ping")
+        async def on_ping(event):
+            return {"pong": True}          # answers a room.request("ping", to=...)
+
+        await room.connect(identity="visuals")
+        await room.serve()                  # blocks; reconnects transient drops
+
+asyncio.run(main())
+```
+
+### Record a room into a session, skipping the noise
+
+```python
+import time
+from hci_atrium import Atrium
+
+client = Atrium()
+room = client.rooms.open(name="studio")
+session = client.sessions.start(name="studio take")
+print(f"connect code: {room.connect_code}  session: {session.id}")
+
+with room.record(into=session):
+    room.send("note", {"text": "session started"})
+    room.send("beat", {"bpm": 120}, ephemeral=True)   # not recorded — ephemeral
+    time.sleep(30)   # capture whatever participants send
+
+print(f"recorded {client.sessions.resume(session.id).last_seq} events")
+```
+
+---
+
+## Left out / not verified here
+
+- Bulk import (`POST /v1/library/import`) has no SDK wrapper; only the raw endpoint is documented.
+- Collection *creation/management* (the tree itself) is not an SDK operation — only scoping to an
+  existing collection id.
+- `hci_atrium.dash.Dashboard` (the observation-dashboard helper) and the SFX/agent-tooling pieces
+  (`client.tool`, `client.agent`, direct-model routing) exist in the SDK but are out of scope for
+  this guide — see the source docstrings and `README.md` for those.