@simfinity/constellation-client 1.0.2 → 1.0.4

package/README.md

@@ -39,8 +39,8 @@ try {
     /* ... */
     
     // Start a chat session
-    await startSession("You are a useful assistant", true);
-    await connect(true, {
+    await client.startSession("You are a useful assistant", true);
+    await client.connect(true, {
         onStreamClosed: (reason: string) => {
             console.log("Stream connection lost");
         },
@@ -57,8 +57,8 @@ try {
 
     /* ... */
     
-    sendAudioChunk("{PCM16 Base64-encoded data}");
-    commitAudioChunksSent();
+    client.sendAudioChunk("{PCM16 Base64-encoded data}");
+    client.commitAudioChunksSent();
     
     /* ... */
 }

package/dist/index.cjs

@@ -133,12 +133,12 @@ var WebClient = class {
    * })
    * ```
    */
-  async connect(audio = false, handlers) {
+  async joinSession(audio = false, handlers) {
     if (!this.sessionId) {
       throw new Error("No open session");
     }
     const ws = new WebSocket(
-      `${this.config.streamingEndpoint}/web/${this.sessionId}`,
+      `${this.config.streamingEndpoint}/player/${this.sessionId}`,
       ["key", this.config.key]
     );
     if (!await this.serverHandShake(ws, audio)) {
@@ -183,6 +183,23 @@ var WebClient = class {
     };
     this.ws = ws;
   }
+  /**
+   * With an opened streaming connection: 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.
+   *
+   * @remarks
+   * 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.
+   *
+   * @exception
+   * This method throws new Error(...) if unable to execute successfully for any reason.
+   */
+  async configureSession(settings) {
+    this.send("session.configure", settings);
+  }
   /**
    * With an opened streaming connection: 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.

package/dist/index.d.cts

@@ -29,10 +29,26 @@ interface WebClientConfig {
     llm: LlmType;
     model: string;
 }
+/**
+ * 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;
+    maxResponseToken?: number;
+}
 /**
  * Callback functions to catch all the propagated server events.
  *
  * @onStreamClosed the streaming session (web socket) shut down
+ * @onSessionConfigured received in response to a session settings update from the client
  * @onAudioResponseStart the LLM service is about to respond with streaming audio data
  * @onAudioResponseChunk a new chunk of response audio data was received
  * @onAudioResponseEnd the model has finished responding. Audio response has been entirely streamed
@@ -50,6 +66,7 @@ interface WebClientConfig {
  */
 interface EventHandlers {
     onStreamClosed: (reason: string) => void;
+    onSessionConfigured?: (settings: SessionSettings) => void;
     onAudioResponseStart?: () => void;
     onAudioResponseChunk?: (audioChunk: string) => void;
     onAudioResponseEnd?: () => void;
@@ -128,7 +145,22 @@ declare class WebClient {
      * })
      * ```
      */
-    connect(audio: boolean | undefined, handlers: EventHandlers): Promise<void>;
+    joinSession(audio: boolean | undefined, handlers: EventHandlers): Promise<void>;
+    /**
+     * With an opened streaming connection: 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.
+     *
+     * @remarks
+     * 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.
+     *
+     * @exception
+     * This method throws new Error(...) if unable to execute successfully for any reason.
+     */
+    configureSession(settings: SessionSettings): Promise<void>;
     /**
      * With an opened streaming connection: 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.

package/dist/index.d.ts

@@ -29,10 +29,26 @@ interface WebClientConfig {
     llm: LlmType;
     model: string;
 }
+/**
+ * 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;
+    maxResponseToken?: number;
+}
 /**
  * Callback functions to catch all the propagated server events.
  *
  * @onStreamClosed the streaming session (web socket) shut down
+ * @onSessionConfigured received in response to a session settings update from the client
  * @onAudioResponseStart the LLM service is about to respond with streaming audio data
  * @onAudioResponseChunk a new chunk of response audio data was received
  * @onAudioResponseEnd the model has finished responding. Audio response has been entirely streamed
@@ -50,6 +66,7 @@ interface WebClientConfig {
  */
 interface EventHandlers {
     onStreamClosed: (reason: string) => void;
+    onSessionConfigured?: (settings: SessionSettings) => void;
     onAudioResponseStart?: () => void;
     onAudioResponseChunk?: (audioChunk: string) => void;
     onAudioResponseEnd?: () => void;
@@ -128,7 +145,22 @@ declare class WebClient {
      * })
      * ```
      */
-    connect(audio: boolean | undefined, handlers: EventHandlers): Promise<void>;
+    joinSession(audio: boolean | undefined, handlers: EventHandlers): Promise<void>;
+    /**
+     * With an opened streaming connection: 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.
+     *
+     * @remarks
+     * 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.
+     *
+     * @exception
+     * This method throws new Error(...) if unable to execute successfully for any reason.
+     */
+    configureSession(settings: SessionSettings): Promise<void>;
     /**
      * With an opened streaming connection: 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.

package/dist/index.js

@@ -107,12 +107,12 @@ var WebClient = class {
    * })
    * ```
    */
-  async connect(audio = false, handlers) {
+  async joinSession(audio = false, handlers) {
     if (!this.sessionId) {
       throw new Error("No open session");
     }
     const ws = new WebSocket(
-      `${this.config.streamingEndpoint}/web/${this.sessionId}`,
+      `${this.config.streamingEndpoint}/player/${this.sessionId}`,
       ["key", this.config.key]
     );
     if (!await this.serverHandShake(ws, audio)) {
@@ -157,6 +157,23 @@ var WebClient = class {
     };
     this.ws = ws;
   }
+  /**
+   * With an opened streaming connection: 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.
+   *
+   * @remarks
+   * 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.
+   *
+   * @exception
+   * This method throws new Error(...) if unable to execute successfully for any reason.
+   */
+  async configureSession(settings) {
+    this.send("session.configure", settings);
+  }
   /**
    * With an opened streaming connection: 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.

package/package.json

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