hci-atrium 0.1.0 → 0.3.0

package/README.md

@@ -57,6 +57,36 @@ function Dashboard() {
 Atrium" button otherwise (pass `fallback` for your own landing page). The callback that Atrium
 redirects back to is handled automatically — no route or effect to wire up.
 
+### useRoomConnection
+
+`useRoomConnection(code, { identity, baseUrl?, onRoom? })` is the connect/reconnect skeleton for a
+component that consumes a [room](#live-rooms) by connect code — loginless, so it needs no provider
+and no sign-in. It joins, classifies failures, and tears the handle down on unmount, returning
+`{ status, room }`: `status` is `"connecting"` → `"connected"`, `"unreachable"` for a join/connect
+failure, or a typed terminal end (`"bad-code"` / `"code-rotated"` / `"room-gone"`); `room` is the
+`Room` handle, `null` before it exists and again after a terminal end. Register signal handlers in
+`onRoom` — it runs the moment the handle exists, **before** `connect()`, so a replayed durable signal
+isn't missed — and return a cleanup from it if you need one. `identity` is the presence name (e.g.
+`"viewer:web"`); `baseUrl` defaults to `location.origin`.
+
+```tsx
+import { useState } from "react"
+import { useRoomConnection } from "hci-atrium/react"
+
+function Scene({ code }: { code: string }) {
+  const [name, setName] = useState("—")
+  const { status, room } = useRoomConnection(code, {
+    identity: "viewer:web",
+    onRoom: (room) => {
+      room.on("scene.change", (e) => setName(String(e.payload.name)))
+    },
+  })
+
+  if (status !== "connected") return <p>{status}</p>
+  return <button onClick={() => void room?.send("applause")}>{name}</button>
+}
+```
+
 ## Core API (no framework)
 
 ```ts
@@ -89,10 +119,10 @@ const atrium = new Atrium({ baseUrl, clientId })
   (retry once) on a 401, and concurrent callers share one refresh. If refresh fails, the SDK drops
   to a signed-out state and emits a change.
 
-## Phase-1 surface
+## The client surface
 
-Beyond auth, the client exposes the library / assets / sources / sessions / rooms namespaces plus
-`chat` and `embed`. Every method takes an **options object** with `filters` kept nested
+Beyond auth, the client exposes the library / assets / sources / sessions / rooms / surveys
+namespaces plus `chat`, `agent` and `embed`. Every method takes an **options object** with `filters` kept nested
 (`search("rain", { modality, filters: { … } })`); names are **camelCase**, translated to the wire's
 snake_case in one place (the shaping layer). Authenticate with an OAuth `clientId` **or** an
 `apiKey` — the latter works in the browser too (a one-time console note points at PKCE for hosted
@@ -108,7 +138,10 @@ apps).
 | `sources.list()` / `sources.search(query, opts?)` / `sources.import(opts)` | External-provider gateway — read-only fan-out search, then import a `Candidate`. |
 | `sessions.start(opts?)` / `sessions.resume(id)` / `sessions.event(id, type, opts?)` | Durable, append-only session logs. |
 | `rooms.open(opts?)` / `rooms.get(id)` / `rooms.list()` / `rooms.join(code)` | Live [`Room`](#live-rooms) handles — `open`/`get`/`list` are authenticated, `join(code)` is a loginless participant. |
-| `chat(messages, opts?)` | Chat completion. Pass `responseFormat` a **Zod** schema for validated structured output (Zod is an optional peer dep). |
+| `surveys.start(template?, opts)` / `surveys.template(name, body, opts?)` / … | [Surveys](#surveys) on a session, and the project's survey templates. |
+| `chat(messages, opts?)` | Chat completion. Pass `responseFormat` a **Zod** schema for validated structured output (Zod is an optional peer dep), or `stream: true` for an [`AsyncIterable<string>`](#streaming-chat) of deltas. |
+| `agent(prompt, { tools, … })` | A [tool-calling loop](#agents-and-tools) over explicit tool descriptors. |
+| `addDirectModel(name, { baseUrl, apiKey? })` | Route one model name straight to an OpenAI-compatible endpoint ([direct models](#direct-models)) instead of Atrium. |
 | `embed(opts)` | Embed exactly one of `text` / `image` / `audio` / `video` into a vector; `model` is required. |
 | `transcribe(audio, opts?)` | Speech-to-text over a multipart audio upload; `opts.verbose` fills `.language` / `.duration` / `.segments`. |
 | `by.*` | Operand grammar for `searchByExamples` / `compare`: `by.asset` / `by.text` / `by.file` / `by.concept`, and `by.vector([…])` — the only way to pass a raw vector. |
@@ -125,15 +158,172 @@ a matching `room.request(...)`); `room.send(type, payload, { to })` fans out; pl
 loudness/spectrum/beat stream. `connect()` opens the socket (every wire method calls it for you);
 `close()` / `await using` / a passed `AbortSignal` tears it down.
 
-Not yet ported (environment- or broker-bound, tracked as parity exceptions): `record(into=session)`
-host bridging, and `audioVectors` / `audioScores` (the embed/chat-broker protocol). Audio-signal
-*consumption* is complete. In Node <22 pass a `WebSocketCtor` (e.g. from `ws`); browsers and Node ≥22
-use the global.
+Host-side surfaces on an **owned** room (`atrium.rooms.open/get/join`, not the loginless `joinRoom`):
+
+| Member | Description |
+| --- | --- |
+| `room.record(into)` / `room.transcribe(opts?)` | Bridge the room into a durable session; run live transcription into `transcript.*` signals. |
+| `room.audioVectors(opts?)` / `room.audioScores(anchors, opts?)` / `room.audioClips()` | Embed / score / take raw the live ~10s audio windows. |
+| `room.audioTranscripts(opts?)` | The raw per-snippet transcript iterator — the speech-to-text sibling of `audioVectors`. Streaming when the backend offers it, per-clip batch otherwise (then each transcript carries its source window under `raw.snippet`). Takes `{ model, language, partials, skipEmpty, signal }`; `break` (or abort) ends the subscription. |
+| `room.dashboard(opts?)` → [`Dashboard`](#observation-dashboard) | Host-side state for the hosted observation dashboard (`/tools/dashboard`). |
+| `room.trace()` → `RoomTrace` | Mirror the SDK's own activity into the room as `trace.*` signals (default off). |
+| `room.offerTranscription()` / `offerAudioCapture()` / `offerEmbeds()` / `offerChat()` | Standing services + capability brokers for code-joined peers. |
+
+This SDK now covers every Python-SDK surface except the documented parity exceptions — the CLI, the
+Home Assistant bridge, a sync surface, and raw-PCM mic input — each with its reason in
+[`PARITY.md`](PARITY.md), alongside the handful of deliberate micro-divergences. In Node <22 pass a
+`WebSocketCtor` (e.g. from `ws`); browsers and Node ≥22 use the global.
+
+### Observation dashboard
+
+`room.dashboard({ title })` returns a `Dashboard`: the app owns its state as a grid of **tiles** and
+retells it — each joining dashboard gets a full `dash.snapshot`, every mutation broadcasts a
+`dash.delta`. All `dash.*` traffic is ephemeral (the room stores nothing — the durable record is the
+session). Tiles: `status(id, label, value, { style })` · `text(id, text)` · `image(id, { assetId,
+url, caption })` · `sound(id, { assetId, playing })` · `decision(id, candidates, { picked,
+reasoning })`, each taking `{ title, colSpan, rowSpan, group }` (spans 1..3). `error(message,
+detail?)` pins the dashboard's sticky error strip — it is *not* a tile. Controls ride the snapshot:
+`button(id, label, handler, { variant, confirm })`, `textInput(id, handler, { label, placeholder })`
+(the handler's `{ ok?, message? }` is toasted), and `onNote(handler)` for researcher notes.
+
+```ts
+const dash = room.dashboard({ title: "Reactive Soundscape" })
+await dash.status("phase", "Phase", "Calibration", { style: "good" })
+await dash.decision("pick", ["Forest Rain", "City Drizzle"], { picked: "Forest Rain" })
+dash.button("advance", "Start next phase", async () => {
+  await dash.status("phase", "Phase", "Running")
+  return { message: "Phase advanced" }
+})
+```
+
+### Tracing
+
+`room.trace()` mirrors what the SDK is doing into the room, so a dashboard shows it without any
+app-side plumbing. Library/model calls on the same client (`library.search` / `searchByExamples` /
+`enrich` / `chat`) and `room.play` surface a `trace.<label>` (a one-line summary plus a capped
+detail); recorder / transcriber / standing-offer transitions surface a `trace.state.<label>`. It is
+**off by default** (it broadcasts app internals to anyone holding the connect code), costs nothing
+while off, never breaks the traced call, and stops with `t.stop()`, `using t = room.trace()`, or the
+room's teardown.
+
+```ts
+using t = room.trace()
+await atrium.library.search("rain") // → trace.library.search on the dashboard
+```
 
 Errors derive from `AtriumError`: HTTP failures are `APIError` (401/403 → `AuthError`, 429/5xx →
 `TransientAuthError`), and caller mistakes (mutually-exclusive inputs, unsupported filters) are
 `InvalidArgumentError`.
 
+### Surveys
+
+A **survey** is a data object on a session, guarded by a per-object capability token: whoever holds
+it can read and write exactly that object, nothing else. `surveys.start()` creates it — pinning the
+template's *current* version, so later edits never change a running survey — and returns the token
+plus the hosted tool's `url`. Hand either to the participant-facing environment, or `survey.open()`
+a tab on the machine itself.
+
+`surveys.template(name, body)` is the code-first **ensure** flow: run it on every start-up. It
+creates the template if it's missing, appends a new immutable version only when the body actually
+changed, and flips `default` when asked — so your templates live in your repo, not in a UI.
+
+```ts
+await atrium.surveys.template("post-study", postStudyBody, { default: true })
+
+const session = await atrium.sessions.start({ participantRef: "p-07" })
+const survey = await atrium.surveys.start("post-study", {
+  into: session,
+  returnTo: "https://study.example/next",
+})
+survey.open() // …or send survey.url / survey.token to the participant's device
+
+const rows = await atrium.surveys.responses("post-study", { submittedOnly: true })
+const csv = await atrium.surveys.responsesCsv("post-study") // Uint8Array, one row per response
+```
+
+Everything project-scoped (`template` / `templates` / `responses` / `responsesCsv` / `uploadFile`)
+takes `project` per call, or inherits the client's. `uploadFile(blob)` stores a write-once project
+file (survey imagery) and returns the `id` a template body's `image` field references.
+
+### Streaming chat
+
+`chat(messages, { stream: true })` returns an `AsyncIterable<string>` of content deltas — **not** a
+promise, so there is nothing to `await` before the loop. It works the same on a direct endpoint, and
+can't be combined with a schema `responseFormat` (structured output validates a complete reply).
+
+```ts
+for await (const piece of atrium.chat("describe a rainy street", { stream: true })) {
+  process.stdout.write(piece)
+}
+```
+
+### Agents and tools
+
+`agent(prompt, { tools })` runs the tool-calling loop: the model may call your tools until it
+answers, or until `maxTurns` (default 6). A tool is an explicit descriptor — TypeScript has no
+runtime signatures or docstrings to derive a schema from, so what you write is what the model sees.
+Pass `responseFormat` a Zod schema to structure the **final** answer (it applies after the loop —
+json-mode conflicts with the tool-calling turns).
+
+```ts
+const reply = await atrium.agent("what should I play for a storm scene?", {
+  tools: [
+    {
+      name: "search_library",
+      description: "Find sounds in the Atrium library.",
+      parameters: {
+        type: "object",
+        properties: { query: { type: "string" } },
+        required: ["query"],
+      },
+      execute: async ({ query }) => {
+        const hits = await atrium.library.search(String(query), { modality: "audio", limit: 3 })
+        return hits.map((h) => h.asset.title)
+      },
+    },
+  ],
+})
+```
+
+`parameters` is plain JSON Schema. To validate the model's arguments as well, pass
+`{ jsonSchema, validate }` where `validate` is any [Standard Schema](https://standardschema.dev)
+object (Zod ≥3.24, Valibot, ArkType): its parsed output is what `execute` receives. A *bare* schema
+object is rejected — deriving JSON Schema from it would mean depending on that library, and this
+package has no runtime dependencies.
+
+```ts
+import { z } from "zod"
+
+const city = z.object({ city: z.string() })
+const tool = {
+  name: "get_weather",
+  parameters: {
+    jsonSchema: { type: "object", properties: { city: { type: "string" } }, required: ["city"] },
+    validate: city,
+  },
+  execute: ({ city }) => forecastFor(String(city)),
+}
+```
+
+### Direct models
+
+Register a model name to route its `chat` / `agent` calls **straight** to an OpenAI-compatible
+endpoint — a local Ollama or LM Studio, or any remote server — instead of Atrium. A registered name
+shadows an Atrium model of the same name (that's the point), and only chat is intercepted:
+embeddings, search, sessions and rooms always go to Atrium.
+
+```ts
+atrium.addDirectModel("gemma3", { baseUrl: "http://localhost:11434/v1" })
+await atrium.chat("hi", { model: "gemma3" }) // → localhost, not Atrium
+
+await atrium.discoverModels("http://localhost:11434/v1") // what's installed? (registers nothing)
+```
+
+Direct calls carry **only** that endpoint's own key (or none) — your Atrium credential is never sent
+to a third-party endpoint. `discoverModels` is subject to browser CORS: a local server that sends no
+`Access-Control-Allow-Origin` blocks the read before the SDK sees it (that's the endpoint's policy to
+change, e.g. Ollama's `OLLAMA_ORIGINS`); from Node it just works.
+
 ## Quickstart (search + play)
 
 ```ts
@@ -164,6 +354,72 @@ room.audioSignals((sig) => {
 })
 ```
 
+## Player
+
+The `hci-atrium/player` subpath ships the audio-layers engine (`LayerEngine`), the headless
+[`PlayerRuntime`](#playerruntime), and the `play` / `layer.*` dialect helpers that back the hosted
+[Player tool](../../tools) — named, independently mixed WebAudio layers (music/ambient/SFX) with
+crossfades, reverb/echo/distance effects, and 3D positioning. It's the code an embedding app drives
+from resolved room signals; it owns the per-layer WebAudio graph and nothing about React or
+transport.
+
+```ts
+import { LayerEngine } from "hci-atrium/player"
+
+const engine = new LayerEngine({ context: audioContext, destination: masterGain, loadBuffer })
+engine.configure([{ id: "music", volume: 0.8 }])
+engine.enqueue("music", [{ url: trackUrl }], "now")
+```
+
+See [`docs/reference/audio-layers-dialect.md`](../../docs/reference/audio-layers-dialect.md) for the
+full wire dialect.
+
+### PlayerRuntime
+
+`PlayerRuntime` is the headless Player — the dialect brain of the hosted tool, lifted out of its
+page. It owns the master chain (gain → limiter) *and* a `LayerEngine`, and dispatches the whole
+`play` / `layer.*` dialect: hand it room frames via `handleSignal(frame)` and give it a `send` sink
+for its outbound traffic (`layer.query` replies and `layer.state` broadcasts to `layer.subscribe`rs).
+It never opens a socket, touches the DOM, or imports React — transport, UI, and
+the intents it can't play itself (Spotify, "open link") stay with the host, the latter arriving
+through the `unhandled` hook.
+
+```ts
+import { joinRoom } from "hci-atrium"
+import { PlayerRuntime } from "hci-atrium/player"
+
+const baseUrl = "https://atrium.example.edu"
+const room = await joinRoom("ABC12345", { baseUrl })
+const context = new AudioContext() // create it on the user's Start gesture — autoplay policy
+
+const runtime = new PlayerRuntime({
+  context,
+  baseUrl, // asset-resolution root for the `asset_id`-only play shape
+  send: (type, payload, opts) => void room.send(type, payload as Record<string, unknown>, opts),
+  onLog: (line) => console.log(line),
+  onSnapshot: (layers) => renderLayers(layers), // engine snapshot → your UI
+})
+
+// Every inbound frame goes to the runtime; types outside the dialect fall through to `unhandled`.
+room.onAny((e) =>
+  runtime.handleSignal({
+    type: e.type,
+    payload: e.payload,
+    from: e.from ?? undefined,
+    ack_id: e.ackId ?? undefined,
+  }),
+)
+await room.connect()
+```
+
+`LayerEngine` is the mixer; `PlayerRuntime` is the mixer *plus* the dialect. It exposes
+`runtime.engine` for listener-side controls (per-layer / master volume, normalization, device-change
+resume) and `runtime.masterGain` as an analyzer tap (pre-limiter); `dispose()` tears down the engine,
+its timers, and the master chain it built, leaving the host's `AudioContext` alone. One caveat on the
+`send` sink: `Room.send` carries `to` and `ephemeral` but not `replyTo`, so a host that must answer a
+peer's `layer.query` builds the envelope itself — `buildSignalEnvelope` from the same subpath does
+exactly that for a `POST /v1/rooms/{id}/signal` transport, which is what the hosted Player runs on.
+
 ## Honest caveat: the guard is UX, not secrecy
 
 For a static single-page app the client-side guard is **user experience, not a security boundary**
@@ -180,3 +436,5 @@ pnpm build   # tsc → dist/ (.js + .d.ts)
 pnpm test    # vitest (mocked fetch, no live server)
 pnpm lint    # biome check
 ```
+
+Releases are published to npm by hand from the maintainer's account — there is no CI publish job.

package/dist/asset-meta.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Single-asset metadata fetch — the public content-by-id capability.
+ *
+ * ``GET /v1/assets/{id}`` needs no auth (asset bytes + metadata are public by id), so this is a
+ * plain ``httpFetch`` against the public shape. Used by the browser tools (Viewer, Player) to recover a
+ * video mime + a name fallback for a bare ``show``/``play`` that only carried an asset id, and to
+ * read extracted ``facts`` (e.g. ``bpm`` for the analyzer's tempo prior). A failed request or an
+ * aborted one (superseded by a newer show/play) resolves to ``null`` — no error surfaces.
+ */
+/** The public fields the browser tools read from an asset (mirrors ``AssetPublicRead``). */
+export interface AssetMeta {
+    /** Human name from an external source; the UI falls back to ``filename`` when null. */
+    title?: string | null;
+    filename?: string;
+    content_type?: string;
+    /** Extracted Tier-1 facts (duration, loudness, dimensions, bpm, …) — an opaque passthrough. */
+    facts?: {
+        bpm?: number;
+        loudness?: number;
+        [k: string]: unknown;
+    };
+}
+/**
+ * Fetch an asset's public metadata by id. Returns ``null`` on a non-OK response, a network error,
+ * or an aborted request (via ``opts.signal``). ``baseUrl`` is the resolution root (``""`` for
+ * same-origin).
+ */
+export declare function fetchAssetMeta(baseUrl: string, assetId: string, opts?: {
+    signal?: AbortSignal;
+}): Promise<AssetMeta | null>;
+//# sourceMappingURL=asset-meta.d.ts.map

package/dist/asset-meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-meta.d.ts","sourceRoot":"","sources":["../src/asset-meta.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,4FAA4F;AAC5F,MAAM,WAAW,SAAS;IACxB,uFAAuF;IACvF,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,+FAA+F;IAC/F,KAAK,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAA;CAClE;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAC9B,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAU3B"}

package/dist/asset-meta.js

@@ -0,0 +1,25 @@
+/**
+ * Single-asset metadata fetch — the public content-by-id capability.
+ *
+ * ``GET /v1/assets/{id}`` needs no auth (asset bytes + metadata are public by id), so this is a
+ * plain ``httpFetch`` against the public shape. Used by the browser tools (Viewer, Player) to recover a
+ * video mime + a name fallback for a bare ``show``/``play`` that only carried an asset id, and to
+ * read extracted ``facts`` (e.g. ``bpm`` for the analyzer's tempo prior). A failed request or an
+ * aborted one (superseded by a newer show/play) resolves to ``null`` — no error surfaces.
+ */
+import { httpFetch } from "./http.js";
+/**
+ * Fetch an asset's public metadata by id. Returns ``null`` on a non-OK response, a network error,
+ * or an aborted request (via ``opts.signal``). ``baseUrl`` is the resolution root (``""`` for
+ * same-origin).
+ */
+export async function fetchAssetMeta(baseUrl, assetId, opts) {
+    try {
+        const res = await httpFetch(`${baseUrl}/v1/assets/${encodeURIComponent(assetId)}`, opts?.signal ? { signal: opts.signal } : undefined);
+        return res.ok ? (await res.json()) : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=asset-meta.js.map

package/dist/asset-meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-meta.js","sourceRoot":"","sources":["../src/asset-meta.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAYrC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAAe,EACf,OAAe,EACf,IAA+B;IAE/B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,SAAS,CACzB,GAAG,OAAO,cAAc,kBAAkB,CAAC,OAAO,CAAC,EAAE,EACrD,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CACnD,CAAA;QACD,OAAO,GAAG,CAAC,EAAE,CAAC,CAAC,CAAE,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAe,CAAC,CAAC,CAAC,IAAI,CAAA;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC"}