@livekit/agents-plugin-lemonslice 1.0.40

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,66 @@
+# LemonSlice plugin for LiveKit Agents
+
+Support for avatar generation and animation with [LemonSlice](https://lemonslice.com/).
+
+See [https://docs.livekit.io/agents/models/avatar/plugins/lemonslice/](https://docs.livekit.io/agents/models/avatar/plugins/lemonslice/) for more information.
+
+## Installation
+
+```bash
+npm install @livekit/agents-plugin-lemonslice
+# or
+pnpm add @livekit/agents-plugin-lemonslice
+# or
+yarn add @livekit/agents-plugin-lemonslice
+```
+
+## Pre-requisites
+
+You'll need an API key from LemonSlice. It can be set as an environment variable: `LEMONSLICE_API_KEY`
+Manage your LemonSlice API key through the [LemonSlice API Dashboard](https://lemonslice.com/agents/api)
+
+## Usage
+
+```typescript
+import { AvatarSession } from '@livekit/agents-plugin-lemonslice';
+
+// Create an avatar session with an image URL
+const avatar = new AvatarSession({
+  agentImageUrl: 'publicly-accessible-image-url',
+  apiKey: 'your-lemonslice-api-key', // or set LEMONSLICE_API_KEY env var
+});
+
+// Start the avatar session after creating your agent session
+await avatar.start(agentSession, room);
+```
+
+### Full Example
+
+Find a complete working example [here](../../examples/src/lemonslice_realtime_avatar.ts).
+
+Set `LEMONSLICE_API_KEY` and `LEMONSLICE_IMAGE_URL` to get up and running.
+
+
+## Configuration Options
+
+### AvatarSessionOptions
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `agentId` | `string` | The LemonSlice agent ID to use. Either `agentId` or `agentImageUrl` must be provided. |
+| `agentImageUrl` | `AvatarImage` | A publicly accessible url to your avatar image. Either `agentId` or `agentImageUrl` must be provided. |
+| `apiUrl` | `string` | The LemonSlice API URL. Defaults to `LEMONSLICE_API_URL` env var or the default LemonSlice API endpoint. |
+| `apiKey` | `string` | The LemonSlice API key. Defaults to `LEMONSLICE_API_KEY` env var. |
+| `avatarParticipantIdentity` | `string` | The identity of the avatar participant in the room. Defaults to `'lemonslice-avatar-agent'`. |
+| `avatarParticipantName` | `string` | The name of the avatar participant in the room. Defaults to `'lemonslice-avatar-agent'`. |
+| `connOptions` | `APIConnectOptions` | Connection options for API requests (retry count, timeout, etc.). |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `LEMONSLICE_API_KEY` | Your LemonSlice API key |
+| `LEMONSLICE_API_URL` | Custom LemonSlice API URL (optional) |
+| `LIVEKIT_URL` | Your LiveKit server URL |
+| `LIVEKIT_API_KEY` | Your LiveKit API key |
+| `LIVEKIT_API_SECRET` | Your LiveKit API secret |

package/dist/avatar.cjs

@@ -0,0 +1,205 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var avatar_exports = {};
+__export(avatar_exports, {
+  AvatarSession: () => AvatarSession,
+  LemonSliceException: () => LemonSliceException
+});
+module.exports = __toCommonJS(avatar_exports);
+var import_agents = require("@livekit/agents");
+var import_rtc_node = require("@livekit/rtc-node");
+var import_livekit_server_sdk = require("livekit-server-sdk");
+var import_log = require("./log.cjs");
+const ATTRIBUTE_PUBLISH_ON_BEHALF = "lk.publish_on_behalf";
+const DEFAULT_API_URL = "https://lemonslice.com/api/liveai/sessions";
+const SAMPLE_RATE = 16e3;
+const AVATAR_AGENT_IDENTITY = "lemonslice-avatar-agent";
+const AVATAR_AGENT_NAME = "lemonslice-avatar-agent";
+class LemonSliceException extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "LemonSliceException";
+  }
+}
+class AvatarSession {
+  agentId;
+  agentImageUrl;
+  agentPrompt;
+  idleTimeout;
+  apiUrl;
+  apiKey;
+  avatarParticipantIdentity;
+  avatarParticipantName;
+  connOptions;
+  #logger = (0, import_log.log)();
+  /**
+   * Creates a new AvatarSession.
+   *
+   * @param options - Configuration options for the avatar session
+   * @throws LemonSliceException if invalid agentId or agentImageUrl is provided, or if LemonSlice API key is not set
+   */
+  constructor(options = {}) {
+    this.agentId = options.agentId ?? null;
+    this.agentImageUrl = options.agentImageUrl ?? null;
+    if (!this.agentId && !this.agentImageUrl) {
+      throw new LemonSliceException("Missing agentId or agentImageUrl");
+    }
+    if (this.agentId && this.agentImageUrl) {
+      throw new LemonSliceException("Only one of agentId or agentImageUrl can be provided");
+    }
+    this.agentPrompt = options.agentPrompt ?? null;
+    this.idleTimeout = options.idleTimeout ?? null;
+    this.apiUrl = options.apiUrl || process.env.LEMONSLICE_API_URL || DEFAULT_API_URL;
+    this.apiKey = options.apiKey || process.env.LEMONSLICE_API_KEY || "";
+    if (!this.apiKey) {
+      throw new LemonSliceException(
+        "The api_key must be set either by passing apiKey to the client or by setting the LEMONSLICE_API_KEY environment variable"
+      );
+    }
+    this.avatarParticipantIdentity = options.avatarParticipantIdentity || AVATAR_AGENT_IDENTITY;
+    this.avatarParticipantName = options.avatarParticipantName || AVATAR_AGENT_NAME;
+    this.connOptions = options.connOptions || import_agents.DEFAULT_API_CONNECT_OPTIONS;
+  }
+  /**
+   * Starts the avatar session and connects it to the agent.
+   *
+   * This method:
+   * 1. Creates a LiveKit token for the avatar participant
+   * 2. Calls the LemonSlice API to start the avatar session
+   * 3. Configures the agent's audio output to stream to the avatar
+   *
+   * @param agentSession - The agent session to connect to the avatar
+   * @param room - The LiveKit room where the avatar will join
+   * @param options - Optional LiveKit credentials (falls back to environment variables)
+   * @throws LemonSliceException if LiveKit credentials are not available or if the avatar session fails to start
+   */
+  async start(agentSession, room, options = {}) {
+    var _a;
+    const livekitUrl = options.livekitUrl || process.env.LIVEKIT_URL;
+    const livekitApiKey = options.livekitApiKey || process.env.LIVEKIT_API_KEY;
+    const livekitApiSecret = options.livekitApiSecret || process.env.LIVEKIT_API_SECRET;
+    if (!livekitUrl || !livekitApiKey || !livekitApiSecret) {
+      throw new LemonSliceException(
+        "livekitUrl, livekitApiKey, and livekitApiSecret must be set by arguments or environment variables"
+      );
+    }
+    let localParticipantIdentity;
+    try {
+      const jobCtx = (0, import_agents.getJobContext)();
+      localParticipantIdentity = ((_a = jobCtx.agent) == null ? void 0 : _a.identity) || "";
+      if (!localParticipantIdentity && room.localParticipant) {
+        localParticipantIdentity = room.localParticipant.identity;
+      }
+    } catch {
+      if (!room.isConnected || !room.localParticipant) {
+        throw new LemonSliceException("failed to get local participant identity");
+      }
+      localParticipantIdentity = room.localParticipant.identity;
+    }
+    if (!localParticipantIdentity) {
+      throw new LemonSliceException("failed to get local participant identity");
+    }
+    const at = new import_livekit_server_sdk.AccessToken(livekitApiKey, livekitApiSecret, {
+      identity: this.avatarParticipantIdentity,
+      name: this.avatarParticipantName
+    });
+    at.kind = "agent";
+    at.addGrant({
+      roomJoin: true,
+      room: room.name
+    });
+    at.attributes = {
+      [ATTRIBUTE_PUBLISH_ON_BEHALF]: localParticipantIdentity
+    };
+    const livekitToken = await at.toJwt();
+    this.#logger.debug("starting avatar session");
+    await this.startAgent(livekitUrl, livekitToken);
+    agentSession.output.audio = new import_agents.voice.DataStreamAudioOutput({
+      room,
+      destinationIdentity: this.avatarParticipantIdentity,
+      sampleRate: SAMPLE_RATE,
+      waitRemoteTrack: import_rtc_node.TrackKind.KIND_VIDEO
+    });
+  }
+  async startAgent(livekitUrl, livekitToken) {
+    for (let i = 0; i <= this.connOptions.maxRetry; i++) {
+      try {
+        const payload = {
+          transport_type: "livekit",
+          properties: {
+            livekit_url: livekitUrl,
+            livekit_token: livekitToken
+          }
+        };
+        if (this.agentId) {
+          payload.agent_id = this.agentId;
+        }
+        if (this.agentImageUrl) {
+          payload.agent_image_url = this.agentImageUrl;
+        }
+        if (this.agentPrompt) {
+          payload.agent_prompt = this.agentPrompt;
+        }
+        if (this.idleTimeout !== null) {
+          payload.idle_timeout = this.idleTimeout;
+        }
+        const response = await fetch(this.apiUrl, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "X-API-Key": this.apiKey
+          },
+          body: JSON.stringify(payload),
+          signal: AbortSignal.timeout(this.connOptions.timeoutMs)
+        });
+        if (!response.ok) {
+          const text = await response.text();
+          throw new import_agents.APIStatusError({
+            message: "Server returned an error",
+            options: { statusCode: response.status, body: { error: text } }
+          });
+        }
+        return;
+      } catch (e) {
+        if (e instanceof import_agents.APIStatusError && !e.retryable) {
+          throw e;
+        }
+        if (e instanceof import_agents.APIConnectionError) {
+          this.#logger.warn({ error: String(e) }, "failed to call lemonslice api");
+        } else {
+          this.#logger.error({ error: e }, "failed to call lemonslice api");
+        }
+        if (i <= this.connOptions.maxRetry - 1) {
+          await new Promise(
+            (resolve) => setTimeout(resolve, (0, import_agents.intervalForRetry)(this.connOptions, i))
+          );
+        }
+      }
+    }
+    throw new import_agents.APIConnectionError({
+      message: "Failed to start LemonSlice Avatar Session after all retries"
+    });
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AvatarSession,
+  LemonSliceException
+});
+//# sourceMappingURL=avatar.cjs.map

package/dist/avatar.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/avatar.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2025 LiveKit, Inc.\n//\n// SPDX-License-Identifier: Apache-2.0\nimport {\n  type APIConnectOptions,\n  APIConnectionError,\n  APIStatusError,\n  DEFAULT_API_CONNECT_OPTIONS,\n  getJobContext,\n  intervalForRetry,\n  voice,\n} from '@livekit/agents';\nimport type { Room } from '@livekit/rtc-node';\nimport { TrackKind } from '@livekit/rtc-node';\nimport type { VideoGrant } from 'livekit-server-sdk';\nimport { AccessToken } from 'livekit-server-sdk';\nimport { log } from './log.js';\n\nconst ATTRIBUTE_PUBLISH_ON_BEHALF = 'lk.publish_on_behalf';\nconst DEFAULT_API_URL = 'https://lemonslice.com/api/liveai/sessions';\nconst SAMPLE_RATE = 16000;\nconst AVATAR_AGENT_IDENTITY = 'lemonslice-avatar-agent';\nconst AVATAR_AGENT_NAME = 'lemonslice-avatar-agent';\n\n/**\n * Exception thrown when there are errors with the LemonSlice API.\n */\nexport class LemonSliceException extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'LemonSliceException';\n  }\n}\n\n/**\n * Options for configuring an AvatarSession.\n */\nexport interface AvatarSessionOptions {\n  /**\n   * The ID of the LemonSlice agent to add to the session.\n   * Either agentId or agentImageUrl must be provided.\n   */\n  agentId?: string | null;\n  /**\n   * The URL of the image to use as the agent's avatar.\n   * Either agentId or agentImageUrl must be provided.\n   */\n  agentImageUrl?: string | null;\n  /**\n   * A prompt that subtly influences the avatar's movements and expressions.\n   */\n  agentPrompt?: string | null;\n  /**\n   * The idle timeout, in seconds. Defaults to 60 seconds.\n   */\n  idleTimeout?: number | null;\n  /**\n   * The LemonSlice API URL. Defaults to https://lemonslice.com/api/liveai/sessions\n   * or LEMONSLICE_API_URL environment variable.\n   */\n  apiUrl?: string;\n  /**\n   * The LemonSlice API key. Can also be set via LEMONSLICE_API_KEY environment variable.\n   */\n  apiKey?: string;\n  /**\n   * The identity of the avatar participant in the room. Defaults to 'lemonslice-avatar-agent'.\n   */\n  avatarParticipantIdentity?: string;\n  /**\n   * The name of the avatar participant in the room. Defaults to 'lemonslice-avatar-agent'.\n   */\n  avatarParticipantName?: string;\n  /**\n   * Connection options for API requests.\n   */\n  connOptions?: APIConnectOptions;\n}\n\n/**\n * Options for starting an avatar session.\n */\nexport interface StartOptions {\n  /**\n   * LiveKit server URL. Falls back to LIVEKIT_URL environment variable.\n   */\n  livekitUrl?: string;\n  /**\n   * LiveKit API key. Falls back to LIVEKIT_API_KEY environment variable.\n   */\n  livekitApiKey?: string;\n  /**\n   * LiveKit API secret. Falls back to LIVEKIT_API_SECRET environment variable.\n   */\n  livekitApiSecret?: string;\n}\n\n/**\n * A LemonSlice avatar session.\n *\n * This class manages the connection between a LiveKit agent and a LemonSlice avatar,\n * routing agent audio output to the avatar for visual representation.\n *\n * @example\n * ```typescript\n * // Using an agent ID\n * const avatar = new AvatarSession({\n *   agentId: 'your-agent-id',\n *   apiKey: 'your-lemonslice-api-key',\n * });\n * await avatar.start(agentSession, room);\n *\n * // Using a custom avatar image\n * const avatar = new AvatarSession({\n *   agentImageUrl: 'your-image-url',\n *   apiKey: 'your-lemonslice-api-key',\n * });\n * await avatar.start(agentSession, room);\n * ```\n */\nexport class AvatarSession {\n  private agentId: string | null;\n  private agentImageUrl: string | null;\n  private agentPrompt: string | null;\n  private idleTimeout: number | null;\n  private apiUrl: string;\n  private apiKey: string;\n  private avatarParticipantIdentity: string;\n  private avatarParticipantName: string;\n  private connOptions: APIConnectOptions;\n\n  #logger = log();\n\n  /**\n   * Creates a new AvatarSession.\n   *\n   * @param options - Configuration options for the avatar session\n   * @throws LemonSliceException if invalid agentId or agentImageUrl is provided, or if LemonSlice API key is not set\n   */\n  constructor(options: AvatarSessionOptions = {}) {\n    this.agentId = options.agentId ?? null;\n    this.agentImageUrl = options.agentImageUrl ?? null;\n\n    if (!this.agentId && !this.agentImageUrl) {\n      throw new LemonSliceException('Missing agentId or agentImageUrl');\n    }\n    if (this.agentId && this.agentImageUrl) {\n      throw new LemonSliceException('Only one of agentId or agentImageUrl can be provided');\n    }\n\n    this.agentPrompt = options.agentPrompt ?? null;\n    this.idleTimeout = options.idleTimeout ?? null;\n\n    this.apiUrl = options.apiUrl || process.env.LEMONSLICE_API_URL || DEFAULT_API_URL;\n    this.apiKey = options.apiKey || process.env.LEMONSLICE_API_KEY || '';\n\n    if (!this.apiKey) {\n      throw new LemonSliceException(\n        'The api_key must be set either by passing apiKey to the client or ' +\n          'by setting the LEMONSLICE_API_KEY environment variable',\n      );\n    }\n\n    this.avatarParticipantIdentity = options.avatarParticipantIdentity || AVATAR_AGENT_IDENTITY;\n    this.avatarParticipantName = options.avatarParticipantName || AVATAR_AGENT_NAME;\n    this.connOptions = options.connOptions || DEFAULT_API_CONNECT_OPTIONS;\n  }\n\n  /**\n   * Starts the avatar session and connects it to the agent.\n   *\n   * This method:\n   * 1. Creates a LiveKit token for the avatar participant\n   * 2. Calls the LemonSlice API to start the avatar session\n   * 3. Configures the agent's audio output to stream to the avatar\n   *\n   * @param agentSession - The agent session to connect to the avatar\n   * @param room - The LiveKit room where the avatar will join\n   * @param options - Optional LiveKit credentials (falls back to environment variables)\n   * @throws LemonSliceException if LiveKit credentials are not available or if the avatar session fails to start\n   */\n  async start(\n    agentSession: voice.AgentSession,\n    room: Room,\n    options: StartOptions = {},\n  ): Promise<void> {\n    const livekitUrl = options.livekitUrl || process.env.LIVEKIT_URL;\n    const livekitApiKey = options.livekitApiKey || process.env.LIVEKIT_API_KEY;\n    const livekitApiSecret = options.livekitApiSecret || process.env.LIVEKIT_API_SECRET;\n\n    if (!livekitUrl || !livekitApiKey || !livekitApiSecret) {\n      throw new LemonSliceException(\n        'livekitUrl, livekitApiKey, and livekitApiSecret must be set ' +\n          'by arguments or environment variables',\n      );\n    }\n\n    let localParticipantIdentity: string;\n    try {\n      const jobCtx = getJobContext();\n      localParticipantIdentity = jobCtx.agent?.identity || '';\n      if (!localParticipantIdentity && room.localParticipant) {\n        localParticipantIdentity = room.localParticipant.identity;\n      }\n    } catch {\n      if (!room.isConnected || !room.localParticipant) {\n        throw new LemonSliceException('failed to get local participant identity');\n      }\n      localParticipantIdentity = room.localParticipant.identity;\n    }\n\n    if (!localParticipantIdentity) {\n      throw new LemonSliceException('failed to get local participant identity');\n    }\n\n    const at = new AccessToken(livekitApiKey, livekitApiSecret, {\n      identity: this.avatarParticipantIdentity,\n      name: this.avatarParticipantName,\n    });\n    at.kind = 'agent';\n\n    at.addGrant({\n      roomJoin: true,\n      room: room.name,\n    } as VideoGrant);\n\n    // allow the avatar agent to publish audio and video on behalf of your local agent\n    at.attributes = {\n      [ATTRIBUTE_PUBLISH_ON_BEHALF]: localParticipantIdentity,\n    };\n\n    const livekitToken = await at.toJwt();\n\n    this.#logger.debug('starting avatar session');\n    await this.startAgent(livekitUrl, livekitToken);\n\n    agentSession.output.audio = new voice.DataStreamAudioOutput({\n      room,\n      destinationIdentity: this.avatarParticipantIdentity,\n      sampleRate: SAMPLE_RATE,\n      waitRemoteTrack: TrackKind.KIND_VIDEO,\n    });\n  }\n\n  private async startAgent(livekitUrl: string, livekitToken: string): Promise<void> {\n    for (let i = 0; i <= this.connOptions.maxRetry; i++) {\n      try {\n        const payload: Record<string, any> = {\n          transport_type: 'livekit',\n          properties: {\n            livekit_url: livekitUrl,\n            livekit_token: livekitToken,\n          },\n        };\n\n        if (this.agentId) {\n          payload.agent_id = this.agentId;\n        }\n\n        if (this.agentImageUrl) {\n          payload.agent_image_url = this.agentImageUrl;\n        }\n\n        if (this.agentPrompt) {\n          payload.agent_prompt = this.agentPrompt;\n        }\n\n        if (this.idleTimeout !== null) {\n          payload.idle_timeout = this.idleTimeout;\n        }\n\n        const response = await fetch(this.apiUrl, {\n          method: 'POST',\n          headers: {\n            'Content-Type': 'application/json',\n            'X-API-Key': this.apiKey,\n          },\n          body: JSON.stringify(payload),\n          signal: AbortSignal.timeout(this.connOptions.timeoutMs),\n        });\n\n        if (!response.ok) {\n          const text = await response.text();\n          throw new APIStatusError({\n            message: 'Server returned an error',\n            options: { statusCode: response.status, body: { error: text } },\n          });\n        }\n        return;\n      } catch (e) {\n        if (e instanceof APIStatusError && !e.retryable) {\n          throw e;\n        }\n        if (e instanceof APIConnectionError) {\n          this.#logger.warn({ error: String(e) }, 'failed to call lemonslice api');\n        } else {\n          this.#logger.error({ error: e }, 'failed to call lemonslice api');\n        }\n\n        if (i <= this.connOptions.maxRetry - 1) {\n          await new Promise((resolve) =>\n            setTimeout(resolve, intervalForRetry(this.connOptions, i)),\n          );\n        }\n      }\n    }\n\n    throw new APIConnectionError({\n      message: 'Failed to start LemonSlice Avatar Session after all retries',\n    });\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/avatar.d.cts

@@ -0,0 +1,127 @@
+import { type APIConnectOptions, voice } from '@livekit/agents';
+import type { Room } from '@livekit/rtc-node';
+/**
+ * Exception thrown when there are errors with the LemonSlice API.
+ */
+export declare class LemonSliceException extends Error {
+    constructor(message: string);
+}
+/**
+ * Options for configuring an AvatarSession.
+ */
+export interface AvatarSessionOptions {
+    /**
+     * The ID of the LemonSlice agent to add to the session.
+     * Either agentId or agentImageUrl must be provided.
+     */
+    agentId?: string | null;
+    /**
+     * The URL of the image to use as the agent's avatar.
+     * Either agentId or agentImageUrl must be provided.
+     */
+    agentImageUrl?: string | null;
+    /**
+     * A prompt that subtly influences the avatar's movements and expressions.
+     */
+    agentPrompt?: string | null;
+    /**
+     * The idle timeout, in seconds. Defaults to 60 seconds.
+     */
+    idleTimeout?: number | null;
+    /**
+     * The LemonSlice API URL. Defaults to https://lemonslice.com/api/liveai/sessions
+     * or LEMONSLICE_API_URL environment variable.
+     */
+    apiUrl?: string;
+    /**
+     * The LemonSlice API key. Can also be set via LEMONSLICE_API_KEY environment variable.
+     */
+    apiKey?: string;
+    /**
+     * The identity of the avatar participant in the room. Defaults to 'lemonslice-avatar-agent'.
+     */
+    avatarParticipantIdentity?: string;
+    /**
+     * The name of the avatar participant in the room. Defaults to 'lemonslice-avatar-agent'.
+     */
+    avatarParticipantName?: string;
+    /**
+     * Connection options for API requests.
+     */
+    connOptions?: APIConnectOptions;
+}
+/**
+ * Options for starting an avatar session.
+ */
+export interface StartOptions {
+    /**
+     * LiveKit server URL. Falls back to LIVEKIT_URL environment variable.
+     */
+    livekitUrl?: string;
+    /**
+     * LiveKit API key. Falls back to LIVEKIT_API_KEY environment variable.
+     */
+    livekitApiKey?: string;
+    /**
+     * LiveKit API secret. Falls back to LIVEKIT_API_SECRET environment variable.
+     */
+    livekitApiSecret?: string;
+}
+/**
+ * A LemonSlice avatar session.
+ *
+ * This class manages the connection between a LiveKit agent and a LemonSlice avatar,
+ * routing agent audio output to the avatar for visual representation.
+ *
+ * @example
+ * ```typescript
+ * // Using an agent ID
+ * const avatar = new AvatarSession({
+ *   agentId: 'your-agent-id',
+ *   apiKey: 'your-lemonslice-api-key',
+ * });
+ * await avatar.start(agentSession, room);
+ *
+ * // Using a custom avatar image
+ * const avatar = new AvatarSession({
+ *   agentImageUrl: 'your-image-url',
+ *   apiKey: 'your-lemonslice-api-key',
+ * });
+ * await avatar.start(agentSession, room);
+ * ```
+ */
+export declare class AvatarSession {
+    #private;
+    private agentId;
+    private agentImageUrl;
+    private agentPrompt;
+    private idleTimeout;
+    private apiUrl;
+    private apiKey;
+    private avatarParticipantIdentity;
+    private avatarParticipantName;
+    private connOptions;
+    /**
+     * Creates a new AvatarSession.
+     *
+     * @param options - Configuration options for the avatar session
+     * @throws LemonSliceException if invalid agentId or agentImageUrl is provided, or if LemonSlice API key is not set
+     */
+    constructor(options?: AvatarSessionOptions);
+    /**
+     * Starts the avatar session and connects it to the agent.
+     *
+     * This method:
+     * 1. Creates a LiveKit token for the avatar participant
+     * 2. Calls the LemonSlice API to start the avatar session
+     * 3. Configures the agent's audio output to stream to the avatar
+     *
+     * @param agentSession - The agent session to connect to the avatar
+     * @param room - The LiveKit room where the avatar will join
+     * @param options - Optional LiveKit credentials (falls back to environment variables)
+     * @throws LemonSliceException if LiveKit credentials are not available or if the avatar session fails to start
+     */
+    start(agentSession: voice.AgentSession, room: Room, options?: StartOptions): Promise<void>;
+    private startAgent;
+}
+//# sourceMappingURL=avatar.d.ts.map