@simfinity/constellation-client 1.0.20 → 1.0.22

package/dist/index.cjs

@@ -39,17 +39,20 @@ var WebClient = class {
    * @remarks
    * A session MUST exist first in order to connect the stream next.
    *
-   * @param voiceEnabled whether this Model-session can receive & produce audio as well as text
-   * @param voiceName LLM specific voice name e.g. with OpenAI this could be 'alloy'
+   * @param params the configuration options to start this new session
    *
    * @exception
    * This method throws new Error(...) if unable to execute successfully for any reason.
    */
-  async startSession(voiceEnabled, voiceName) {
+  async startSession(params) {
+    var _a, _b, _c;
     const prepareBody = {
-      llmProvider: this.config.llm,
-      audioEnabled: voiceEnabled,
-      voiceName
+      llmProvider: params.llmProvider,
+      audioEnabled: params.voiceEnabled,
+      voiceName: params.voiceName,
+      temperature: (_a = params.behaviour) == null ? void 0 : _a.temperature,
+      instructions: (_b = params.behaviour) == null ? void 0 : _b.instructions,
+      maxResponseToken: (_c = params.behaviour) == null ? void 0 : _c.maxResponseToken
     };
     const response = await fetch(`${this.config.sessionEndpoint}/prepare_session`, {
       method: "POST",

package/dist/index.d.cts

@@ -1,44 +1,81 @@
 /**
- * Available server-side LLM types
+ * Supported server-side LLM types
  */
-type LlmType = "openai" | "gemini";
+type LlmName = "openai" | "gemini";
 /**
  * Configuration required to initiate a connection with the stream server:
  *
- * @sessionEndpoint : REST base URL to the constellation API for managing sessions
- * @streamingEndpoint : WebSocket endpoint to the constellation server
- * @key : Simfinity API secret key granting access to the server API
- * @llm : which LLM service to connect to
- * @model : depends on the LLM service. This is the model name as define by the LLM service
- *
  * @example
  * ```TypeScript
  * {
  *     sessionEndpoint: "https://simfinity.constellation.com",
  *     streamingEndpoint: "wss://simfinity.constellation.com:30003",
  *     key: "some-secret-key"
- *     llm: "openai",
- *     model: "gpt-4o-realtime-preview-2024-12-17",
  * }
  * ```
  */
 interface WebClientConfig {
+    /**
+     * HTTP REST base URL to the constellation API for managing sessions.
+     */
     sessionEndpoint: string;
+    /**
+     * WebSocket endpoint to the constellation server.
+     */
     streamingEndpoint: string;
+    /**
+     * Simfinity API secret key granting access to the server API.
+     */
     key: string;
-    llm: LlmType;
 }
 /**
- * System settings influencing the model behavior:
- * @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.
+ * System settings influencing how the model thinks and responds.
  */
 interface SessionConfig {
+    /**
+     * LLM creativity factor in 0-1 range
+     */
     temperature?: number;
+    /**
+     * System instructions giving context, rules and directions to drive the LLM behavior
+     */
     instructions?: string;
+    /**
+     * 1-4096 value, maximum number of token used for a single response. Undefined or 0 means unlimited.
+     */
     maxResponseToken?: number;
 }
+/**
+ * Options when starting a new session. Some properties are immutable once
+ * the session has started, however the SessionConfig settings may, depending on
+ * the LLM provider chosen, be modified mid-session.
+ */
+interface SessionStartParameters {
+    /**
+     * Name of one of the supported LLM.
+     */
+    llmProvider: LlmName;
+    /**
+     * When voiceEnabled is set to true, the LLM session is configured to
+     * receive and send audio stream and produce transcript of the audio conversation.
+     */
+    voiceEnabled: boolean;
+    /**
+     * Optional, the name of a voice supported by the LLM.
+     * Default values are 'Alloy' for OpenAI and 'Aoede' for Gemini.
+     * WARNING: constellation will accept any value, it belongs to the client to choose
+     * a valid voice name for the LLM provider chosen.
+     */
+    voiceName?: string;
+    /**
+     * Behavioral options affecting how the model thinks and responds.
+     * These options may be modified mid-session with configureSession(), but only
+     * if the chosen LLM provider allows it!
+     * WARNING: some LLMs like Gemini may not support mid-session updates, thus it is
+     * advised and preferred to provide them here at startSession time.
+     */
+    behaviour?: SessionConfig;
+}
 /**
  * Snapshot of the current settings run by the model.
  */
@@ -155,13 +192,12 @@ declare class WebClient {
      * @remarks
      * A session MUST exist first in order to connect the stream next.
      *
-     * @param voiceEnabled whether this Model-session can receive & produce audio as well as text
-     * @param voiceName LLM specific voice name e.g. with OpenAI this could be 'alloy'
+     * @param params the configuration options to start this new session
      *
      * @exception
      * This method throws new Error(...) if unable to execute successfully for any reason.
      */
-    startSession(voiceEnabled: boolean, voiceName?: string): Promise<void>;
+    startSession(params: SessionStartParameters): 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.
@@ -270,4 +306,4 @@ declare class WebClient {
     private send;
 }
 
-export { type EventHandlers, type LlmType, type SessionConfig, WebClient, type WebClientConfig };
+export { type EventHandlers, type LlmName, type SessionConfig, type SessionSettings, type SessionStartParameters, WebClient, type WebClientConfig };

package/dist/index.d.ts

@@ -1,44 +1,81 @@
 /**
- * Available server-side LLM types
+ * Supported server-side LLM types
  */
-type LlmType = "openai" | "gemini";
+type LlmName = "openai" | "gemini";
 /**
  * Configuration required to initiate a connection with the stream server:
  *
- * @sessionEndpoint : REST base URL to the constellation API for managing sessions
- * @streamingEndpoint : WebSocket endpoint to the constellation server
- * @key : Simfinity API secret key granting access to the server API
- * @llm : which LLM service to connect to
- * @model : depends on the LLM service. This is the model name as define by the LLM service
- *
  * @example
  * ```TypeScript
  * {
  *     sessionEndpoint: "https://simfinity.constellation.com",
  *     streamingEndpoint: "wss://simfinity.constellation.com:30003",
  *     key: "some-secret-key"
- *     llm: "openai",
- *     model: "gpt-4o-realtime-preview-2024-12-17",
  * }
  * ```
  */
 interface WebClientConfig {
+    /**
+     * HTTP REST base URL to the constellation API for managing sessions.
+     */
     sessionEndpoint: string;
+    /**
+     * WebSocket endpoint to the constellation server.
+     */
     streamingEndpoint: string;
+    /**
+     * Simfinity API secret key granting access to the server API.
+     */
     key: string;
-    llm: LlmType;
 }
 /**
- * System settings influencing the model behavior:
- * @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.
+ * System settings influencing how the model thinks and responds.
  */
 interface SessionConfig {
+    /**
+     * LLM creativity factor in 0-1 range
+     */
     temperature?: number;
+    /**
+     * System instructions giving context, rules and directions to drive the LLM behavior
+     */
     instructions?: string;
+    /**
+     * 1-4096 value, maximum number of token used for a single response. Undefined or 0 means unlimited.
+     */
     maxResponseToken?: number;
 }
+/**
+ * Options when starting a new session. Some properties are immutable once
+ * the session has started, however the SessionConfig settings may, depending on
+ * the LLM provider chosen, be modified mid-session.
+ */
+interface SessionStartParameters {
+    /**
+     * Name of one of the supported LLM.
+     */
+    llmProvider: LlmName;
+    /**
+     * When voiceEnabled is set to true, the LLM session is configured to
+     * receive and send audio stream and produce transcript of the audio conversation.
+     */
+    voiceEnabled: boolean;
+    /**
+     * Optional, the name of a voice supported by the LLM.
+     * Default values are 'Alloy' for OpenAI and 'Aoede' for Gemini.
+     * WARNING: constellation will accept any value, it belongs to the client to choose
+     * a valid voice name for the LLM provider chosen.
+     */
+    voiceName?: string;
+    /**
+     * Behavioral options affecting how the model thinks and responds.
+     * These options may be modified mid-session with configureSession(), but only
+     * if the chosen LLM provider allows it!
+     * WARNING: some LLMs like Gemini may not support mid-session updates, thus it is
+     * advised and preferred to provide them here at startSession time.
+     */
+    behaviour?: SessionConfig;
+}
 /**
  * Snapshot of the current settings run by the model.
  */
@@ -155,13 +192,12 @@ declare class WebClient {
      * @remarks
      * A session MUST exist first in order to connect the stream next.
      *
-     * @param voiceEnabled whether this Model-session can receive & produce audio as well as text
-     * @param voiceName LLM specific voice name e.g. with OpenAI this could be 'alloy'
+     * @param params the configuration options to start this new session
      *
      * @exception
      * This method throws new Error(...) if unable to execute successfully for any reason.
      */
-    startSession(voiceEnabled: boolean, voiceName?: string): Promise<void>;
+    startSession(params: SessionStartParameters): 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.
@@ -270,4 +306,4 @@ declare class WebClient {
     private send;
 }
 
-export { type EventHandlers, type LlmType, type SessionConfig, WebClient, type WebClientConfig };
+export { type EventHandlers, type LlmName, type SessionConfig, type SessionSettings, type SessionStartParameters, WebClient, type WebClientConfig };

package/dist/index.js

@@ -13,17 +13,20 @@ var WebClient = class {
    * @remarks
    * A session MUST exist first in order to connect the stream next.
    *
-   * @param voiceEnabled whether this Model-session can receive & produce audio as well as text
-   * @param voiceName LLM specific voice name e.g. with OpenAI this could be 'alloy'
+   * @param params the configuration options to start this new session
    *
    * @exception
    * This method throws new Error(...) if unable to execute successfully for any reason.
    */
-  async startSession(voiceEnabled, voiceName) {
+  async startSession(params) {
+    var _a, _b, _c;
     const prepareBody = {
-      llmProvider: this.config.llm,
-      audioEnabled: voiceEnabled,
-      voiceName
+      llmProvider: params.llmProvider,
+      audioEnabled: params.voiceEnabled,
+      voiceName: params.voiceName,
+      temperature: (_a = params.behaviour) == null ? void 0 : _a.temperature,
+      instructions: (_b = params.behaviour) == null ? void 0 : _b.instructions,
+      maxResponseToken: (_c = params.behaviour) == null ? void 0 : _c.maxResponseToken
     };
     const response = await fetch(`${this.config.sessionEndpoint}/prepare_session`, {
       method: "POST",

package/package.json

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