@simfinity/constellation-ui 1.0.0 → 1.0.2

package/README.md

@@ -1,9 +1,209 @@
-# @simfinity/constellation-client
+# @simfinity/constellation-ui
 
-## Installation
+React bindings for Simfinity Constellation — persistent real-time LLM chat rooms (text + audio).
+
+## Overview
+
+Constellation provides:
+* Persistent server-side sessions
+* WebSocket real-time streaming
+* Text + audio conversations
+* Configurable system instructions
+* Reconnectable chat rooms
+
+This package is a React wrapper around:
 
+@simfinity/constellation-client
+
+It provides context + hooks for lifecycle management.
+
+## Installation
 ```bash
+npm install @simfinity/constellation-ui
+# or
+yarn add @simfinity/constellation-ui
+
+# Dependency:
 npm install @simfinity/constellation-client
 # or
 yarn add @simfinity/constellation-client
 ```
+
+## Architecture
+
+Session lifecycle:
+```
+startSession()  → REST call
+joinSession()   → WebSocket connection
+
+configureSession() (optional)   → WebSocket messages
+sendText() / sendAudioChunk()   → WebSocket messages
+
+endSession()    → REST call
+```
+
+⚠️ A session MUST be started before it can be joined.
+
+⚠️ A session SHOULD be ended when finished.
+
+## Minimal Working Example (Text-Only)
+
+```Typescript
+import React, { useEffect } from "react";
+import WebClient from "@simfinity/constellation-client";
+import {
+    ConstellationProvider,
+    useConstellationClient
+} from "@simfinity/constellation-ui";
+
+const client = new WebClient({
+    sessionEndpoint: "https://your-api",
+    streamingEndpoint: "wss://your-stream",
+    key: "YOUR_SECRET_KEY",
+    llm: "openai",
+    model: "gpt-4o-realtime-preview-2024-12-17"
+});
+
+function Chat() {
+    const {
+        startSession,
+        joinSession,
+        sendText,
+        endSession
+    } = useConstellationClient();
+    
+    useEffect(() => {
+    async function init() {
+    await startSession(false);
+    
+          await joinSession(false, {
+            onStreamClosed: console.log,
+            onTranscriptResponse: (msg) => {
+              console.log("Model:", msg);
+            }
+          });
+    
+          sendText("Hello!");
+        }
+    
+        init();
+    
+        return () => {
+          endSession();
+        };
+    }, []);
+    
+    return <div>Chat running...</div>;
+}
+
+export default function App() {
+    return (
+        <ConstellationProvider client={client}>
+          /* Chat display components */
+        </ConstellationProvider>
+    );
+}
+```
+
+## Audio Mode
+
+To enable audio:
+
+```Typescript
+// Create a audio-enabled session
+await startSession(true, "alloy");
+
+// Join a stream subscribing to audio events
+await joinSession(true, {
+    onStreamClosed: console.log,
+    onAudioResponseStart: () => console.log("Speaking..."),
+    onAudioResponseChunk: (chunk) => audioPlayer.enqueue(chunk),
+    onAudioResponseEnd: () => console.log("Done")
+});
+```
+
+Audio requirements:
+
+* Format: PCM16
+* Encoding: Base64
+* Transcription: handled server-side
+
+Send audio:
+
+```Typescript
+sendAudioChunk(base64PcmChunk);
+commitAudio();
+```
+
+commitAudio() is optional (silence auto-flushes).
+
+⚠️ There is server-side silence detection to trigger a model response, however for optimal use,
+the client should implement audio-input noise detection to avoid continuously streaming audio data.
+
+## Text and Transcript
+
+Text is always enabled in a session. However, the client must provide the appropriate handlers to receive events:
+```Typescript
+interface EventHandlers {
+  // ...
+  onTranscriptInput?: (transcript: string) => void;
+  onTranscriptResponse?: (transcript: string) => void;
+}
+```
+⚠️ These events serve both the text exchanges AND transcript of audio exchanges:
+
+```Typescript
+// Pseudo-code:
+
+// Text:
+constellationClient.sendText("Hello");
+
+// Triggers:
+// 1) onTranscriptInput(transcript) -> transcript is "Hello"
+// 2) onTranscriptResponse(transcript) -> transcript is the response from the LLM
+
+// Audio:
+constellationClient.sendAudioChunk("... audio data for 'Hello'...");
+constellationClient.commitAudio();
+
+// Triggers:
+// 1) onTranscriptInput(transcript) -> transcript is "Hello"
+// 2) onTranscriptResponse(transcript) -> transcript is the response from the LLM
+```
+
+## Session Configuration
+
+You can update system behavior dynamically:
+
+```Typescript
+configureSession({
+    temperature: 0.2,
+    instructions: "You are a helpful coding assistant.",
+    maxResponseToken: 500
+});
+```
+
+
+This does NOT trigger a response.
+
+## Event Handlers
+
+joinSession() requires at least:
+
+```Typescript
+{
+  onStreamClosed: (reason: string) => void
+}
+```
+
+Optional handlers:
+
+* onSessionConfigured
+* onAudioResponseStart
+* onAudioResponseChunk
+* onAudioResponseEnd
+* onTranscriptInput
+* onTranscriptResponse
+* onTechnicalError
+
+If omitted, events are ignored safely.

package/dist/index.d.cts

@@ -1,24 +1,163 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
-import { WebClient, EventHandlers, SessionConfig } from '@simfinity/constellation-client';
+import { WebClient } from '@simfinity/constellation-client';
 
+/**
+ * React context provider wrapping a Constellation WebClient instance.
+ *
+ * This component exposes session lifecycle state and client control
+ * functions to its descendant components.
+ *
+ * A ConstellationProvider MUST wrap any component that calls:
+ *  - useConstellationClient()
+ *  - useConstellationSession()
+ *
+ * @param client A pre-configured WebClient instance from
+ *               "@simfinity/constellation-client".
+ * @param children The DOM descendant components
+ *
+ * @example
+ * ```tsx
+ * import WebClient from "@simfinity/constellation-client";
+ * import { ConstellationProvider } from "@simfinity/constellation-ui";
+ *
+ * const client = new WebClient({
+ *   sessionEndpoint: "https://your-api",
+ *   streamingEndpoint: "wss://your-stream",
+ *   key: "YOUR_SECRET_KEY",
+ *   llm: "openai",
+ *   model: "gpt-4o-realtime-preview-2024-12-17"
+ * });
+ *
+ * function App() {
+ *   return (
+ *     <ConstellationProvider client={client}>
+ *       <Chat />
+ *     </ConstellationProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @remarks
+ * This provider does NOT automatically start or join sessions.
+ * The lifecycle must be controlled explicitly via useConstellationClient().
+ */
 declare function ConstellationProvider({ client, children, }: {
     client: WebClient;
     children: React.ReactNode;
 }): react_jsx_runtime.JSX.Element;
-declare function useConstellationClient(): {
-    startSession: (audio: boolean, voice?: string) => Promise<void>;
-    endSession: () => Promise<void>;
-    joinSession: (audio: boolean, handlers: EventHandlers) => Promise<void>;
-    configureSession: (settings: SessionConfig) => void;
-    sendText: (text: string) => void;
-    sendAudioChunk: (chunk: string) => void;
-    commitAudio: () => void;
-};
-declare function useConstellationSession(): {
-    sessionId: string | null;
-    connected: boolean;
-    audioEnabled: boolean;
-};
+/**
+ * Hook exposing all lifecycle control functions required to
+ * interact with a Constellation session.
+ *
+ * IMPORTANT SESSION ORDER:
+ *
+ * 1) startSession(audioEnabled, voice?)
+ *    → Creates a persistent server-side session (REST)
+ *    → A session remains alive and can be re-joined within 5 minutes of inactivity
+ *    → audioEnabled makes the session capable of receiving and producing audio stream
+ *    → voice is an LLM specific name of a voice e.g. for OpenAI 'alloy' is a valid value
+ *    → Once a session has started, audio & voice options cannot be changed
+ *
+ * 2) joinSession(audioEnabled, handlers)
+ *    → Opens WebSocket stream and begins event flow
+ *    → audioEnabled (along with an audioEnabled session) to subscribe to audio events
+ *    → handlers are the callback functions to receive server events
+ *
+ * 3) configureSession(settings?) (optional)
+ *    → Update of the settings affecting the LLM behaviour/context
+ *    → This can be done at any time mid-stream
+ *
+ * 4) sendText(...) OR sendAudioChunk(...) + commitAudio()
+ *    → Input-sending methods text & audio
+ *
+ * 5) endSession()
+ *    → Closes the persistent server-side session
+ *    → For a clean implementation the client should close the stream first
+ *
+ * This hook does NOT expose the underlying WebClient directly.
+ * It provides a controlled abstraction safe for React usage.
+ *
+ * @throws Error if used outside ConstellationProvider.
+ *
+ * @returns
+ * Lifecycle control methods:
+ *
+ * startSession(audioEnabled: boolean, voice?: string)
+ *   - Creates a new persistent session on the server.
+ *   - Must be called before joinSession().
+ *
+ * joinSession(audioEnabled: boolean, handlers: EventHandlers)
+ *   - Opens the WebSocket stream.
+ *   - Handlers are required to receive model responses.
+ *
+ * configureSession(settings: SessionConfig)
+ *   - Updates temperature, instructions, max tokens.
+ *   - Does NOT trigger a response.
+ *
+ * sendText(text: string)
+ *   - Sends a user text message.
+ *   - Triggers model response.
+ *
+ * sendAudioChunk(chunk: string)
+ *   - Sends base64 PCM16 audio chunk.
+ *   - Accumulates until commitAudio() or silence detection.
+ *
+ * commitAudio()
+ *   - Forces model to process accumulated audio.
+ *
+ * endSession()
+ *   - Closes session and frees server resources.
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   startSession,
+ *   joinSession,
+ *   sendText,
+ *   endSession
+ * } = useConstellationClient();
+ *
+ * await startSession(false);
+ *
+ * await joinSession(false, {
+ *   onStreamClosed: console.log,
+ *   onTranscriptResponse: (text) => console.log(text),
+ * });
+ *
+ * sendText("Hello world");
+ * ```
+ */
+declare function useConstellationClient(): any;
+/**
+ * Hook exposing reactive session state.
+ *
+ * This hook does NOT control the session.
+ * It only reflects the current state managed by ConstellationProvider.
+ *
+ * @returns
+ * {
+ *   sessionId: string | null
+ *   connected: boolean
+ *   audioEnabled: boolean
+ * }
+ *
+ * sessionId
+ *   - Null until startSession() succeeds.
+ *
+ * connected
+ *   - True after successful joinSession().
+ *
+ * audioEnabled
+ *   - Reflects whether session was started in audio mode.
+ *
+ * @example
+ * ```tsx
+ * const { connected, sessionId } = useConstellationSession();
+ *
+ * if (!connected) return <p>Disconnected</p>;
+ * ```
+ */
+declare function useConstellationSession(): any;
 
 export { ConstellationProvider, useConstellationClient, useConstellationSession };

package/dist/index.d.ts

@@ -1,24 +1,163 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
-import { WebClient, EventHandlers, SessionConfig } from '@simfinity/constellation-client';
+import { WebClient } from '@simfinity/constellation-client';
 
+/**
+ * React context provider wrapping a Constellation WebClient instance.
+ *
+ * This component exposes session lifecycle state and client control
+ * functions to its descendant components.
+ *
+ * A ConstellationProvider MUST wrap any component that calls:
+ *  - useConstellationClient()
+ *  - useConstellationSession()
+ *
+ * @param client A pre-configured WebClient instance from
+ *               "@simfinity/constellation-client".
+ * @param children The DOM descendant components
+ *
+ * @example
+ * ```tsx
+ * import WebClient from "@simfinity/constellation-client";
+ * import { ConstellationProvider } from "@simfinity/constellation-ui";
+ *
+ * const client = new WebClient({
+ *   sessionEndpoint: "https://your-api",
+ *   streamingEndpoint: "wss://your-stream",
+ *   key: "YOUR_SECRET_KEY",
+ *   llm: "openai",
+ *   model: "gpt-4o-realtime-preview-2024-12-17"
+ * });
+ *
+ * function App() {
+ *   return (
+ *     <ConstellationProvider client={client}>
+ *       <Chat />
+ *     </ConstellationProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @remarks
+ * This provider does NOT automatically start or join sessions.
+ * The lifecycle must be controlled explicitly via useConstellationClient().
+ */
 declare function ConstellationProvider({ client, children, }: {
     client: WebClient;
     children: React.ReactNode;
 }): react_jsx_runtime.JSX.Element;
-declare function useConstellationClient(): {
-    startSession: (audio: boolean, voice?: string) => Promise<void>;
-    endSession: () => Promise<void>;
-    joinSession: (audio: boolean, handlers: EventHandlers) => Promise<void>;
-    configureSession: (settings: SessionConfig) => void;
-    sendText: (text: string) => void;
-    sendAudioChunk: (chunk: string) => void;
-    commitAudio: () => void;
-};
-declare function useConstellationSession(): {
-    sessionId: string | null;
-    connected: boolean;
-    audioEnabled: boolean;
-};
+/**
+ * Hook exposing all lifecycle control functions required to
+ * interact with a Constellation session.
+ *
+ * IMPORTANT SESSION ORDER:
+ *
+ * 1) startSession(audioEnabled, voice?)
+ *    → Creates a persistent server-side session (REST)
+ *    → A session remains alive and can be re-joined within 5 minutes of inactivity
+ *    → audioEnabled makes the session capable of receiving and producing audio stream
+ *    → voice is an LLM specific name of a voice e.g. for OpenAI 'alloy' is a valid value
+ *    → Once a session has started, audio & voice options cannot be changed
+ *
+ * 2) joinSession(audioEnabled, handlers)
+ *    → Opens WebSocket stream and begins event flow
+ *    → audioEnabled (along with an audioEnabled session) to subscribe to audio events
+ *    → handlers are the callback functions to receive server events
+ *
+ * 3) configureSession(settings?) (optional)
+ *    → Update of the settings affecting the LLM behaviour/context
+ *    → This can be done at any time mid-stream
+ *
+ * 4) sendText(...) OR sendAudioChunk(...) + commitAudio()
+ *    → Input-sending methods text & audio
+ *
+ * 5) endSession()
+ *    → Closes the persistent server-side session
+ *    → For a clean implementation the client should close the stream first
+ *
+ * This hook does NOT expose the underlying WebClient directly.
+ * It provides a controlled abstraction safe for React usage.
+ *
+ * @throws Error if used outside ConstellationProvider.
+ *
+ * @returns
+ * Lifecycle control methods:
+ *
+ * startSession(audioEnabled: boolean, voice?: string)
+ *   - Creates a new persistent session on the server.
+ *   - Must be called before joinSession().
+ *
+ * joinSession(audioEnabled: boolean, handlers: EventHandlers)
+ *   - Opens the WebSocket stream.
+ *   - Handlers are required to receive model responses.
+ *
+ * configureSession(settings: SessionConfig)
+ *   - Updates temperature, instructions, max tokens.
+ *   - Does NOT trigger a response.
+ *
+ * sendText(text: string)
+ *   - Sends a user text message.
+ *   - Triggers model response.
+ *
+ * sendAudioChunk(chunk: string)
+ *   - Sends base64 PCM16 audio chunk.
+ *   - Accumulates until commitAudio() or silence detection.
+ *
+ * commitAudio()
+ *   - Forces model to process accumulated audio.
+ *
+ * endSession()
+ *   - Closes session and frees server resources.
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   startSession,
+ *   joinSession,
+ *   sendText,
+ *   endSession
+ * } = useConstellationClient();
+ *
+ * await startSession(false);
+ *
+ * await joinSession(false, {
+ *   onStreamClosed: console.log,
+ *   onTranscriptResponse: (text) => console.log(text),
+ * });
+ *
+ * sendText("Hello world");
+ * ```
+ */
+declare function useConstellationClient(): any;
+/**
+ * Hook exposing reactive session state.
+ *
+ * This hook does NOT control the session.
+ * It only reflects the current state managed by ConstellationProvider.
+ *
+ * @returns
+ * {
+ *   sessionId: string | null
+ *   connected: boolean
+ *   audioEnabled: boolean
+ * }
+ *
+ * sessionId
+ *   - Null until startSession() succeeds.
+ *
+ * connected
+ *   - True after successful joinSession().
+ *
+ * audioEnabled
+ *   - Reflects whether session was started in audio mode.
+ *
+ * @example
+ * ```tsx
+ * const { connected, sessionId } = useConstellationSession();
+ *
+ * if (!connected) return <p>Disconnected</p>;
+ * ```
+ */
+declare function useConstellationSession(): any;
 
 export { ConstellationProvider, useConstellationClient, useConstellationSession };

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@simfinity/constellation-ui",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "type": "module",
   "exports": {
     ".": {
-      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     }
   },