@simfinity/constellation-client 1.0.7 → 1.0.8

package/dist/index.cjs

@@ -37,20 +37,20 @@ var WebClient = class {
    * be closed to release the context on server side. See endSession().
    *
    * @remarks
-   * A session MUST exist to connect the stream.
+   * A session MUST exist first in order to connect the stream next.
    *
-   * @param instructions to the model, added to its context. This is the "system" input instructions.
-   * @param audio whether to allow audio streaming or text-only
+   * @param audioEnabled whether this session can receive & produce audio as well as text
+   * @param voiceName LLM specific voice name e.g. with OpenAI this could be 'alloy'
    *
    * @exception
    * This method throws new Error(...) if unable to execute successfully for any reason.
-   *
-   * @example
-   * ```TypeScript
-   * await startSession("You are useful assistant", true)
-   * ```
    */
-  async startSession(instructions = "", audio = false) {
+  async startSession(audioEnabled, voiceName) {
+    const prepareBody = {
+      llmProvider: this.config.llm,
+      audioEnabled,
+      voiceName
+    };
     const response = await fetch(`${this.config.sessionEndpoint}/prepare_session`, {
       method: "POST",
       headers: {
@@ -58,11 +58,7 @@ var WebClient = class {
         "Content-Type": "application/json",
         "Accept": "application/json"
       },
-      body: JSON.stringify({
-        llmProvider: this.config.llm,
-        systemPrompt: instructions,
-        audio
-      })
+      body: JSON.stringify(prepareBody)
     });
     if (!response.ok) {
       throw new Error(`Could not create a new chat session
@@ -116,7 +112,7 @@ var WebClient = class {
    * This method not only opens a websocket connection with the server but also initiates a
    * handshake, where the server explicitly acknowledges and accepts the client connection.
    *
-   * @param audio for a session that created with audio capabilities, allows this streaming to include audio
+   * @param audio for an audio-enabled session, request this streaming connection to include audio events
    * @param handlers callback functions to handle every possible communication events coming from the server
    *
    * @exception
@@ -125,7 +121,7 @@ var WebClient = class {
    * @example
    * ```TypeScript
    * // Open an audio connection: in this example we choose to handle only audio data, and ignore text.
-   * await connect(true, {
+   * await joinSession(true, {
    *     onStreamClosed: (reason: string) => { console.log("Stream connection lost"); },
    *     onAudioResponseStart: () => { console.log("The model is talking"); },
    *     onAudioResponseChunk: (audioChunk: string) => { audioPlayer.enqueue(audioChunk); },
@@ -187,7 +183,7 @@ var WebClient = class {
     this.ws = ws;
   }
   /**
-   * With an opened streaming connection: send a "system" update of the session settings.
+   * Once a session is joined: send a "system" update of the session settings.
    * Allows to change some behavioral parameters like the temperature or system instructions.
    * This does not trigger a model response.
    *
@@ -195,16 +191,16 @@ var WebClient = class {
    * With openai for example, this triggers (pseudo-code):
    * webSocket.send({ type: "session.update", session: { ... }})
    *
-   * @param settings complete definition of the settings. Same values must be re-provided for unchanged parameters.
+   * @param settings new system settings to apply. Omitted values will remain unchanged
    *
    * @exception
    * This method throws new Error(...) if unable to execute successfully for any reason.
    */
-  async configureSession(settings) {
+  configureSession(settings) {
     this.send("session.configure", settings);
   }
   /**
-   * With an opened streaming connection: send a text input message to the LLM. This will trigger a
+   * Once a session is joined: send a text input message to the LLM. This will trigger a
    * text response as well as an audio response if the session was opened with audio mode active.
    *
    * @remarks
@@ -221,7 +217,7 @@ var WebClient = class {
     this.send("text.input.message", { text });
   }
   /**
-   * With an opened streaming connection: send a chunk of raw audio data to the LLM.
+   * Once a session is joined: send a chunk of raw audio data to the LLM.
    * Audio data chunks do not systematically & immediately trigger a model response:
    * They get accumulated by the model to form a single input message, until:
    * - commitAudioChunksSent is called, which flushes the accumulated audio and triggers a response
@@ -240,8 +236,8 @@ var WebClient = class {
     this.send("audio.input.append", { audioData: chunk });
   }
   /**
-   * With an opened streaming connection: triggers the processing of the accumulated audio data since
-   * the last model response. This effectively flushes the audio buffer and triggers a new model response.
+   * Once a session is joined: triggers the processing of the accumulated audio data since
+   * the last model response. This effectively flushes the audio buffer and triggers a model response.
    *
    * @remarks
    * With openai for example, this triggers (pseudo-code):
@@ -279,14 +275,22 @@ var WebClient = class {
       ws.onopen = () => {
         const eventSubs = audio ? [0 /* Text */, 1 /* Audio */] : [0 /* Text */];
         ws.send(JSON.stringify({
-          type: "connection.request",
-          data: { subscription: eventSubs }
+          type: "connection.initiate",
+          data: {
+            subscription: eventSubs,
+            settings: {
+              audio: true,
+              voice: "alloy",
+              temperature: 0.8,
+              instructions: ""
+            }
+          }
         }));
       };
       ws.onmessage = (event) => {
         try {
           const data = JSON.parse(event.data);
-          if (data.type === "connection.accepted")
+          if (data.type === "connection.initiated")
             resolve(true);
           else
             reject(new Error(`Received unexpected event: ${data.type}`));

package/dist/index.d.cts

@@ -31,17 +31,13 @@ interface WebClientConfig {
 }
 /**
  * System settings influencing the model behavior:
- * @audio: to activate voice conversation
- * @voice: depending on the LLM solution, this is the voice name to be used in audio
  * @temperature: LLM creativity factor in 0-1 range
  * @instructions: system instructions giving context, rules and directions to guide the LLM behavior
  * @maxResponseToken: 1-4096 value, maximum number of token used for a single response. Undefined means unlimited.
  */
-interface SessionSettings {
-    audio: boolean;
-    voice: string;
-    temperature: number;
-    instructions: string;
+interface SessionConfig {
+    temperature?: number;
+    instructions?: string;
     maxResponseToken?: number;
 }
 /**
@@ -66,7 +62,7 @@ interface SessionSettings {
  */
 interface EventHandlers {
     onStreamClosed: (reason: string) => void;
-    onSessionConfigured?: (settings: SessionSettings) => void;
+    onSessionConfigured?: (settings: SessionConfig) => void;
     onAudioResponseStart?: () => void;
     onAudioResponseChunk?: (audioChunk: string) => void;
     onAudioResponseEnd?: () => void;
@@ -93,20 +89,15 @@ declare class WebClient {
      * be closed to release the context on server side. See endSession().
      *
      * @remarks
-     * A session MUST exist to connect the stream.
+     * A session MUST exist first in order to connect the stream next.
      *
-     * @param instructions to the model, added to its context. This is the "system" input instructions.
-     * @param audio whether to allow audio streaming or text-only
+     * @param audioEnabled whether this session can receive & produce audio as well as text
+     * @param voiceName LLM specific voice name e.g. with OpenAI this could be 'alloy'
      *
      * @exception
      * This method throws new Error(...) if unable to execute successfully for any reason.
-     *
-     * @example
-     * ```TypeScript
-     * await startSession("You are useful assistant", true)
-     * ```
      */
-    startSession(instructions?: string, audio?: boolean): Promise<void>;
+    startSession(audioEnabled: boolean, voiceName?: string): Promise<void>;
     /**
      * Close an opened, persistent chat room, effectively killing the streaming as well if still opened.
      * If there is no active session, this method does nothing.
@@ -128,7 +119,7 @@ declare class WebClient {
      * This method not only opens a websocket connection with the server but also initiates a
      * handshake, where the server explicitly acknowledges and accepts the client connection.
      *
-     * @param audio for a session that created with audio capabilities, allows this streaming to include audio
+     * @param audio for an audio-enabled session, request this streaming connection to include audio events
      * @param handlers callback functions to handle every possible communication events coming from the server
      *
      * @exception
@@ -137,7 +128,7 @@ declare class WebClient {
      * @example
      * ```TypeScript
      * // Open an audio connection: in this example we choose to handle only audio data, and ignore text.
-     * await connect(true, {
+     * await joinSession(true, {
      *     onStreamClosed: (reason: string) => { console.log("Stream connection lost"); },
      *     onAudioResponseStart: () => { console.log("The model is talking"); },
      *     onAudioResponseChunk: (audioChunk: string) => { audioPlayer.enqueue(audioChunk); },
@@ -147,7 +138,7 @@ declare class WebClient {
      */
     joinSession(audio: boolean | undefined, handlers: EventHandlers): Promise<void>;
     /**
-     * With an opened streaming connection: send a "system" update of the session settings.
+     * Once a session is joined: send a "system" update of the session settings.
      * Allows to change some behavioral parameters like the temperature or system instructions.
      * This does not trigger a model response.
      *
@@ -155,14 +146,14 @@ declare class WebClient {
      * With openai for example, this triggers (pseudo-code):
      * webSocket.send({ type: "session.update", session: { ... }})
      *
-     * @param settings complete definition of the settings. Same values must be re-provided for unchanged parameters.
+     * @param settings new system settings to apply. Omitted values will remain unchanged
      *
      * @exception
      * This method throws new Error(...) if unable to execute successfully for any reason.
      */
-    configureSession(settings: SessionSettings): Promise<void>;
+    configureSession(settings: SessionConfig): void;
     /**
-     * With an opened streaming connection: send a text input message to the LLM. This will trigger a
+     * Once a session is joined: send a text input message to the LLM. This will trigger a
      * text response as well as an audio response if the session was opened with audio mode active.
      *
      * @remarks
@@ -177,7 +168,7 @@ declare class WebClient {
      */
     sendText(text: string): void;
     /**
-     * With an opened streaming connection: send a chunk of raw audio data to the LLM.
+     * Once a session is joined: send a chunk of raw audio data to the LLM.
      * Audio data chunks do not systematically & immediately trigger a model response:
      * They get accumulated by the model to form a single input message, until:
      * - commitAudioChunksSent is called, which flushes the accumulated audio and triggers a response
@@ -194,8 +185,8 @@ declare class WebClient {
      */
     sendAudioChunk(chunk: string): void;
     /**
-     * With an opened streaming connection: triggers the processing of the accumulated audio data since
-     * the last model response. This effectively flushes the audio buffer and triggers a new model response.
+     * Once a session is joined: triggers the processing of the accumulated audio data since
+     * the last model response. This effectively flushes the audio buffer and triggers a model response.
      *
      * @remarks
      * With openai for example, this triggers (pseudo-code):
@@ -215,4 +206,4 @@ declare class WebClient {
     private send;
 }
 
-export { type EventHandlers, type LlmType, type SessionSettings, WebClient, type WebClientConfig };
+export { type EventHandlers, type LlmType, type SessionConfig, WebClient, type WebClientConfig };

package/dist/index.d.ts

@@ -31,17 +31,13 @@ interface WebClientConfig {
 }
 /**
  * System settings influencing the model behavior:
- * @audio: to activate voice conversation
- * @voice: depending on the LLM solution, this is the voice name to be used in audio
  * @temperature: LLM creativity factor in 0-1 range
  * @instructions: system instructions giving context, rules and directions to guide the LLM behavior
  * @maxResponseToken: 1-4096 value, maximum number of token used for a single response. Undefined means unlimited.
  */
-interface SessionSettings {
-    audio: boolean;
-    voice: string;
-    temperature: number;
-    instructions: string;
+interface SessionConfig {
+    temperature?: number;
+    instructions?: string;
     maxResponseToken?: number;
 }
 /**
@@ -66,7 +62,7 @@ interface SessionSettings {
  */
 interface EventHandlers {
     onStreamClosed: (reason: string) => void;
-    onSessionConfigured?: (settings: SessionSettings) => void;
+    onSessionConfigured?: (settings: SessionConfig) => void;
     onAudioResponseStart?: () => void;
     onAudioResponseChunk?: (audioChunk: string) => void;
     onAudioResponseEnd?: () => void;
@@ -93,20 +89,15 @@ declare class WebClient {
      * be closed to release the context on server side. See endSession().
      *
      * @remarks
-     * A session MUST exist to connect the stream.
+     * A session MUST exist first in order to connect the stream next.
      *
-     * @param instructions to the model, added to its context. This is the "system" input instructions.
-     * @param audio whether to allow audio streaming or text-only
+     * @param audioEnabled whether this session can receive & produce audio as well as text
+     * @param voiceName LLM specific voice name e.g. with OpenAI this could be 'alloy'
      *
      * @exception
      * This method throws new Error(...) if unable to execute successfully for any reason.
-     *
-     * @example
-     * ```TypeScript
-     * await startSession("You are useful assistant", true)
-     * ```
      */
-    startSession(instructions?: string, audio?: boolean): Promise<void>;
+    startSession(audioEnabled: boolean, voiceName?: string): Promise<void>;
     /**
      * Close an opened, persistent chat room, effectively killing the streaming as well if still opened.
      * If there is no active session, this method does nothing.
@@ -128,7 +119,7 @@ declare class WebClient {
      * This method not only opens a websocket connection with the server but also initiates a
      * handshake, where the server explicitly acknowledges and accepts the client connection.
      *
-     * @param audio for a session that created with audio capabilities, allows this streaming to include audio
+     * @param audio for an audio-enabled session, request this streaming connection to include audio events
      * @param handlers callback functions to handle every possible communication events coming from the server
      *
      * @exception
@@ -137,7 +128,7 @@ declare class WebClient {
      * @example
      * ```TypeScript
      * // Open an audio connection: in this example we choose to handle only audio data, and ignore text.
-     * await connect(true, {
+     * await joinSession(true, {
      *     onStreamClosed: (reason: string) => { console.log("Stream connection lost"); },
      *     onAudioResponseStart: () => { console.log("The model is talking"); },
      *     onAudioResponseChunk: (audioChunk: string) => { audioPlayer.enqueue(audioChunk); },
@@ -147,7 +138,7 @@ declare class WebClient {
      */
     joinSession(audio: boolean | undefined, handlers: EventHandlers): Promise<void>;
     /**
-     * With an opened streaming connection: send a "system" update of the session settings.
+     * Once a session is joined: send a "system" update of the session settings.
      * Allows to change some behavioral parameters like the temperature or system instructions.
      * This does not trigger a model response.
      *
@@ -155,14 +146,14 @@ declare class WebClient {
      * With openai for example, this triggers (pseudo-code):
      * webSocket.send({ type: "session.update", session: { ... }})
      *
-     * @param settings complete definition of the settings. Same values must be re-provided for unchanged parameters.
+     * @param settings new system settings to apply. Omitted values will remain unchanged
      *
      * @exception
      * This method throws new Error(...) if unable to execute successfully for any reason.
      */
-    configureSession(settings: SessionSettings): Promise<void>;
+    configureSession(settings: SessionConfig): void;
     /**
-     * With an opened streaming connection: send a text input message to the LLM. This will trigger a
+     * Once a session is joined: send a text input message to the LLM. This will trigger a
      * text response as well as an audio response if the session was opened with audio mode active.
      *
      * @remarks
@@ -177,7 +168,7 @@ declare class WebClient {
      */
     sendText(text: string): void;
     /**
-     * With an opened streaming connection: send a chunk of raw audio data to the LLM.
+     * Once a session is joined: send a chunk of raw audio data to the LLM.
      * Audio data chunks do not systematically & immediately trigger a model response:
      * They get accumulated by the model to form a single input message, until:
      * - commitAudioChunksSent is called, which flushes the accumulated audio and triggers a response
@@ -194,8 +185,8 @@ declare class WebClient {
      */
     sendAudioChunk(chunk: string): void;
     /**
-     * With an opened streaming connection: triggers the processing of the accumulated audio data since
-     * the last model response. This effectively flushes the audio buffer and triggers a new model response.
+     * Once a session is joined: triggers the processing of the accumulated audio data since
+     * the last model response. This effectively flushes the audio buffer and triggers a model response.
      *
      * @remarks
      * With openai for example, this triggers (pseudo-code):
@@ -215,4 +206,4 @@ declare class WebClient {
     private send;
 }
 
-export { type EventHandlers, type LlmType, type SessionSettings, WebClient, type WebClientConfig };
+export { type EventHandlers, type LlmType, type SessionConfig, WebClient, type WebClientConfig };

package/dist/index.js

@@ -11,20 +11,20 @@ var WebClient = class {
    * be closed to release the context on server side. See endSession().
    *
    * @remarks
-   * A session MUST exist to connect the stream.
+   * A session MUST exist first in order to connect the stream next.
    *
-   * @param instructions to the model, added to its context. This is the "system" input instructions.
-   * @param audio whether to allow audio streaming or text-only
+   * @param audioEnabled whether this session can receive & produce audio as well as text
+   * @param voiceName LLM specific voice name e.g. with OpenAI this could be 'alloy'
    *
    * @exception
    * This method throws new Error(...) if unable to execute successfully for any reason.
-   *
-   * @example
-   * ```TypeScript
-   * await startSession("You are useful assistant", true)
-   * ```
    */
-  async startSession(instructions = "", audio = false) {
+  async startSession(audioEnabled, voiceName) {
+    const prepareBody = {
+      llmProvider: this.config.llm,
+      audioEnabled,
+      voiceName
+    };
     const response = await fetch(`${this.config.sessionEndpoint}/prepare_session`, {
       method: "POST",
       headers: {
@@ -32,11 +32,7 @@ var WebClient = class {
         "Content-Type": "application/json",
         "Accept": "application/json"
       },
-      body: JSON.stringify({
-        llmProvider: this.config.llm,
-        systemPrompt: instructions,
-        audio
-      })
+      body: JSON.stringify(prepareBody)
     });
     if (!response.ok) {
       throw new Error(`Could not create a new chat session
@@ -90,7 +86,7 @@ var WebClient = class {
    * This method not only opens a websocket connection with the server but also initiates a
    * handshake, where the server explicitly acknowledges and accepts the client connection.
    *
-   * @param audio for a session that created with audio capabilities, allows this streaming to include audio
+   * @param audio for an audio-enabled session, request this streaming connection to include audio events
    * @param handlers callback functions to handle every possible communication events coming from the server
    *
    * @exception
@@ -99,7 +95,7 @@ var WebClient = class {
    * @example
    * ```TypeScript
    * // Open an audio connection: in this example we choose to handle only audio data, and ignore text.
-   * await connect(true, {
+   * await joinSession(true, {
    *     onStreamClosed: (reason: string) => { console.log("Stream connection lost"); },
    *     onAudioResponseStart: () => { console.log("The model is talking"); },
    *     onAudioResponseChunk: (audioChunk: string) => { audioPlayer.enqueue(audioChunk); },
@@ -161,7 +157,7 @@ var WebClient = class {
     this.ws = ws;
   }
   /**
-   * With an opened streaming connection: send a "system" update of the session settings.
+   * Once a session is joined: send a "system" update of the session settings.
    * Allows to change some behavioral parameters like the temperature or system instructions.
    * This does not trigger a model response.
    *
@@ -169,16 +165,16 @@ var WebClient = class {
    * With openai for example, this triggers (pseudo-code):
    * webSocket.send({ type: "session.update", session: { ... }})
    *
-   * @param settings complete definition of the settings. Same values must be re-provided for unchanged parameters.
+   * @param settings new system settings to apply. Omitted values will remain unchanged
    *
    * @exception
    * This method throws new Error(...) if unable to execute successfully for any reason.
    */
-  async configureSession(settings) {
+  configureSession(settings) {
     this.send("session.configure", settings);
   }
   /**
-   * With an opened streaming connection: send a text input message to the LLM. This will trigger a
+   * Once a session is joined: send a text input message to the LLM. This will trigger a
    * text response as well as an audio response if the session was opened with audio mode active.
    *
    * @remarks
@@ -195,7 +191,7 @@ var WebClient = class {
     this.send("text.input.message", { text });
   }
   /**
-   * With an opened streaming connection: send a chunk of raw audio data to the LLM.
+   * Once a session is joined: send a chunk of raw audio data to the LLM.
    * Audio data chunks do not systematically & immediately trigger a model response:
    * They get accumulated by the model to form a single input message, until:
    * - commitAudioChunksSent is called, which flushes the accumulated audio and triggers a response
@@ -214,8 +210,8 @@ var WebClient = class {
     this.send("audio.input.append", { audioData: chunk });
   }
   /**
-   * With an opened streaming connection: triggers the processing of the accumulated audio data since
-   * the last model response. This effectively flushes the audio buffer and triggers a new model response.
+   * Once a session is joined: triggers the processing of the accumulated audio data since
+   * the last model response. This effectively flushes the audio buffer and triggers a model response.
    *
    * @remarks
    * With openai for example, this triggers (pseudo-code):
@@ -253,14 +249,22 @@ var WebClient = class {
       ws.onopen = () => {
         const eventSubs = audio ? [0 /* Text */, 1 /* Audio */] : [0 /* Text */];
         ws.send(JSON.stringify({
-          type: "connection.request",
-          data: { subscription: eventSubs }
+          type: "connection.initiate",
+          data: {
+            subscription: eventSubs,
+            settings: {
+              audio: true,
+              voice: "alloy",
+              temperature: 0.8,
+              instructions: ""
+            }
+          }
         }));
       };
       ws.onmessage = (event) => {
         try {
           const data = JSON.parse(event.data);
-          if (data.type === "connection.accepted")
+          if (data.type === "connection.initiated")
             resolve(true);
           else
             reject(new Error(`Received unexpected event: ${data.type}`));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simfinity/constellation-client",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "type": "module",
   "exports": {
     ".": {