vidspotai-shared 1.0.95 → 1.0.96

package/lib/services/agent/tools/generateAvatarVideo.tool.js

@@ -4,79 +4,177 @@ exports.generateAvatarVideoTool = void 0;
 const zod_1 = require("zod");
 const aiModels_1 = require("../../../globals/aiModels");
 const firebase_1 = require("../../../libs/firebase");
-const aiGenFactory_service_1 = require("../../aiGen/aiGenFactory.service");
+const avatarProviderFactory_1 = require("../../avatarGen/avatarProviderFactory");
 const types_1 = require("../../aiGen/types");
 const rateLimiter_1 = require("../../rateLimiter");
 const ttsFactory_service_1 = require("../../tts/ttsFactory.service");
 const toolRegistry_1 = require("../toolRegistry");
 /**
- * generate_avatar_video — wraps the existing kling-avatar pipeline so the
- * planner's `talking-head-avatar` scene strategy is executable. Accepts a
- * presenter face image URL plus either a pre-uploaded audio URL or raw TTS
- * text (in which case the tool synthesizes via ElevenLabs and uploads to GCS
- * before handing off, since Kling avatar requires a public sound_file URL).
+ * generate_avatar_video — drives avatar generation through the dedicated avatar
+ * provider seam (getAvatarVideoProvider / IAvatarVideoProvider), so the planner's
+ * `talking-head-avatar` scene strategy is executable. Avatar gen is handled by
+ * the avatar provider — NOT the generic video-gen provider. Two engine families:
  *
- * Returns a provider task id; the executor / monitor layer polls completion
- * exactly as it does for generate_video.
+ *  - byo-media (default kling-avatar): caller supplies a presenter face image
+ *    plus either a pre-uploaded audio URL or raw TTS text (the tool synthesizes
+ *    via ElevenLabs + uploads to GCS first, since the engine needs a public
+ *    audio URL).
+ *  - hosted (heygen-avatar / tavus-avatar, via `model`): caller supplies a
+ *    provider-hosted avatar id + a script; the engine runs its own TTS/lipsync,
+ *    so the tool does NO TTS and passes no audio.
+ *
+ * Returns a provider task id; the executor's TaskPoller polls completion — it
+ * routes hosted models through the avatar seam and everything else through the
+ * generic video factory, so this works for both families.
  */
 const InputSchema = zod_1.z
     .object({
+    model: zod_1.z
+        .nativeEnum(aiModels_1.EVideoGenModels)
+        .optional()
+        .describe("Avatar engine. Default kling-avatar (byo-media: animate a face image). heygen-avatar / tavus-avatar are hosted (animate a provider-hosted avatar + native TTS)."),
     inputImageUrl: zod_1.z
         .string()
         .url()
-        .describe("Presenter face still — Kling animates this image to lipsync the audio."),
+        .optional()
+        .describe("byo-media: presenter face still the engine animates to lipsync the audio. Required for byo-media; omit for hosted."),
+    hostedAvatarId: zod_1.z
+        .string()
+        .optional()
+        .describe("hosted: provider-hosted avatar id (HeyGen) or replica_id (Tavus) to animate. Required for hosted engines."),
+    hostedVoiceId: zod_1.z
+        .string()
+        .optional()
+        .describe("hosted: provider-hosted voice id (HeyGen). Unused for Tavus (the replica owns its voice)."),
     ttsText: zod_1.z
         .string()
         .min(1)
         .optional()
-        .describe("VO line to synthesize. Either ttsText or inputAudioUrl must be set; if both are set, inputAudioUrl wins."),
+        .describe("VO line / script. byo-media: synthesized to audio (or use inputAudioUrl; if both set, inputAudioUrl wins). hosted: spoken natively by the engine (required)."),
     inputAudioUrl: zod_1.z
         .string()
         .url()
         .optional()
-        .describe("Pre-uploaded audio URL (mp3/wav). Skips internal TTS+upload."),
+        .describe("byo-media only: pre-uploaded audio URL (mp3/wav). Skips internal TTS+upload."),
     voiceId: zod_1.z.string().optional(),
     languageCode: zod_1.z.string().optional(),
     mode: zod_1.z.enum(["std", "pro"]).default("std"),
     prompt: zod_1.z
         .string()
         .optional()
-        .describe("Optional motion/emotion hint passed through to Kling."),
+        .describe("byo-media only: optional motion/emotion hint passed through to the engine."),
 })
     .superRefine((v, ctx) => {
-    if (!v.ttsText && !v.inputAudioUrl) {
-        ctx.addIssue({
-            code: zod_1.z.ZodIssueCode.custom,
-            message: "Either ttsText or inputAudioUrl is required.",
-        });
+    if (v.model && (0, avatarProviderFactory_1.isHostedAvatarModel)(v.model)) {
+        if (!v.hostedAvatarId) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: "hostedAvatarId is required for hosted avatar engines.",
+                path: ["hostedAvatarId"],
+            });
+        }
+        if (!v.ttsText) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: "ttsText (the script) is required for hosted avatar engines.",
+                path: ["ttsText"],
+            });
+        }
+    }
+    else {
+        if (!v.inputImageUrl) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: "inputImageUrl is required for byo-media avatar engines.",
+                path: ["inputImageUrl"],
+            });
+        }
+        if (!v.ttsText && !v.inputAudioUrl) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: "Either ttsText or inputAudioUrl is required.",
+            });
+        }
     }
 });
 const OutputSchema = zod_1.z.object({
     status: zod_1.z.literal("triggered"),
     taskId: zod_1.z.string(),
-    audioUrl: zod_1.z.string().url().describe("Audio URL fed to Kling — host can reuse for caption sync."),
+    audioUrl: zod_1.z
+        .string()
+        .url()
+        .optional()
+        .describe("byo-media: audio URL fed to the engine — host can reuse for caption sync. Absent for hosted engines (native TTS)."),
 });
 exports.generateAvatarVideoTool = {
     name: "generate_avatar_video",
     description: [
-        "Generate a talking-head avatar video by animating a presenter face still",
-        "to lipsync a voiceover. Wraps the kling-avatar provider.",
+        "Generate a talking-head avatar video that lipsyncs a voiceover. Routed",
+        "through the dedicated avatar provider seam. Two engine families: byo-media",
+        "(default kling-avatar) animates a presenter face still you supply; hosted",
+        "(heygen-avatar / tavus-avatar, via `model`) animates a provider-hosted",
+        "avatar and runs its own TTS from a script.",
         "Use this for the `talking-head-avatar` scene strategy. Do NOT use it for",
         "general motion shots — generate_video is cheaper and more flexible there.",
         "Examples:",
         '  { inputImageUrl: "https://.../face.png", ttsText: "Hi, today we\'re testing the new serum." }',
         '  { inputImageUrl: "https://.../face.png", inputAudioUrl: "https://.../vo.mp3", mode: "pro" }',
+        '  { model: "heygen-avatar", hostedAvatarId: "Daisy-inskirt-20220818", hostedVoiceId: "2d5b0e6cf36f460aa7fc47e3eee4ba54", ttsText: "Welcome back!" }',
     ].join(" "),
     inputSchema: InputSchema,
     outputSchema: OutputSchema,
     idempotent: false,
     estimateCost: async (input) => {
-        // Kling avatar bills per audio second. Without a length we assume 6s (typical scene).
+        // Without a length we assume 6s (typical scene).
         const approxSec = input.ttsText ? Math.max(2, Math.ceil(input.ttsText.length / 15)) : 6;
+        const modelKey = input.model ?? aiModels_1.EVideoGenModels.KLING_AVATAR;
+        if ((0, avatarProviderFactory_1.isHostedAvatarModel)(modelKey)) {
+            // Hosted engines bill per generated MINUTE (min 1 minute).
+            const perMinute = aiModels_1.aiModelConfigs[modelKey]?.cost?.perMinute ?? 0.5;
+            const billedMinutes = Math.max(1, Math.ceil(approxSec / 60));
+            return Math.ceil(perMinute * billedMinutes * 100); // rough credit conversion
+        }
+        // byo-media (Kling) bills per audio second.
         const perSec = input.mode === "pro" ? 0.028 : 0.014;
-        return Math.ceil(approxSec * perSec * 100); // rough credit conversion
+        return Math.ceil(approxSec * perSec * 100);
     },
     handler: async (input, ctx) => {
+        const modelKey = input.model ?? aiModels_1.EVideoGenModels.KLING_AVATAR;
+        const renderMode = input.mode === "pro" ? types_1.EVideoMode.PROFESSIONAL : types_1.EVideoMode.STANDARD;
+        // ── Hosted engines (HeyGen/Tavus) ────────────────────────────────────────
+        // The engine does its own TTS + lipsync from the script, so there's no TTS
+        // synthesis / GCS upload here. Submit and hand the task id to the poller,
+        // which routes hosted models through the avatar seam.
+        if ((0, avatarProviderFactory_1.isHostedAvatarModel)(modelKey)) {
+            const limiter = (0, rateLimiter_1.getAiGenModelRateLimiter)(modelKey);
+            await limiter.waitUntilAvailable();
+            let heldSlot = true;
+            try {
+                const provider = (0, avatarProviderFactory_1.getAvatarVideoProvider)(modelKey);
+                const result = await provider.generate({
+                    mode: "hosted",
+                    hostedAvatarId: input.hostedAvatarId,
+                    hostedVoiceId: input.hostedVoiceId ?? "",
+                    script: input.ttsText,
+                    locale: input.languageCode,
+                    renderMode,
+                });
+                const taskId = result.providerTaskId?.taskId ??
+                    result.providerTaskId?.id ??
+                    (typeof result.providerTaskId === "string" ? result.providerTaskId : "unknown");
+                if (taskId === "unknown") {
+                    limiter.releaseSlot();
+                    heldSlot = false;
+                }
+                return { status: "triggered", taskId };
+            }
+            catch (err) {
+                if (heldSlot)
+                    limiter.releaseSlot();
+                throw err;
+            }
+        }
+        // ── byo-media engines (Kling) ─────────────────────────────────────────────
         let audioUrl = input.inputAudioUrl;
         if (!audioUrl) {
             const ttsLimiter = (0, rateLimiter_1.getTtsProviderRateLimiter)("elevenlabs");
@@ -100,29 +198,27 @@ exports.generateAvatarVideoTool = {
             const [signedUrl] = await file.getSignedUrl({ action: "read", expires: "03-09-2491" });
             audioUrl = signedUrl;
         }
-        // Hold the Kling-avatar slot through return — host's TaskPoller releases
+        // Hold the byo-media model slot through return — host's TaskPoller releases
         // when the task settles. Release here on submit error.
-        const limiter = (0, rateLimiter_1.getAiGenModelRateLimiter)(aiModels_1.EVideoGenModels.KLING_AVATAR);
+        const limiter = (0, rateLimiter_1.getAiGenModelRateLimiter)(modelKey);
         await limiter.waitUntilAvailable();
         let heldSlot = true;
         try {
-            const provider = (0, aiGenFactory_service_1.getAiGenProviderService)(aiModels_1.EVideoGenModels.KLING_AVATAR);
-            // No `type` — kling-avatar's modelConfig.type is ["avatar-video"], which is
-            // outside the VideoGenerationParams.type union. Setting type:"image-to-video"
-            // here trips validateParams (image-to-video branch requires the model's
-            // config.type to include "image-to-video", which avatar's doesn't). The
-            // kling provider routes by modelKey === "kling-avatar" before any
-            // type-based dispatch, so omitting type is correct.
-            const result = await provider.generateVideo({
-                modelKey: aiModels_1.EVideoGenModels.KLING_AVATAR,
+            // byo-media avatar request: a face still + the audio we just resolved. The
+            // avatar provider owns endpoint/type dispatch internally (Kling routes on
+            // modelKey === "kling-avatar"), so no generic-video `type` is passed here.
+            // inputImageUrl presence is guaranteed by the byo-media superRefine branch.
+            const provider = (0, avatarProviderFactory_1.getAvatarVideoProvider)(modelKey);
+            const result = await provider.generate({
+                mode: "byo-media",
+                faceImageUrl: input.inputImageUrl,
+                audioUrl,
                 prompt: input.prompt,
-                inputImageUrl: input.inputImageUrl,
-                inputAudioUrl: audioUrl,
-                mode: input.mode === "pro" ? types_1.EVideoMode.PROFESSIONAL : types_1.EVideoMode.STANDARD,
+                renderMode,
             });
-            const taskId = result.task?.taskId ??
-                result.task?.id ??
-                (typeof result.task === "string" ? result.task : "unknown");
+            const taskId = result.providerTaskId?.taskId ??
+                result.providerTaskId?.id ??
+                (typeof result.providerTaskId === "string" ? result.providerTaskId : "unknown");
             if (taskId === "unknown") {
                 limiter.releaseSlot();
                 heldSlot = false;

package/lib/services/aiGen/aiGenFactory.service.d.ts

@@ -1,7 +1,7 @@
 import { BaseAiGenProviderService } from "./providers/baseAiGenProvider.service";
 import { EImageGenModelKey, EMusicGenModels, ESfxGenModels, ETextGenModels, EVideoGenModels, TAiGenModel } from "../../globals/aiModels";
 type AiGenServiceConstructor = new () => BaseAiGenProviderService;
-export declare const videoServicesMap: Record<EVideoGenModels, AiGenServiceConstructor>;
+export declare const videoServicesMap: Partial<Record<EVideoGenModels, AiGenServiceConstructor>>;
 /**
  * Image-gen factory. Each provider service implements `generateImage()` (sync;
  * returns a URL or base64 in a single API roundtrip — no BullMQ worker needed).

package/lib/services/aiGen/aiGenFactory.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aiGenFactory.service.d.ts","sourceRoot":"","sources":["../../../src/services/aiGen/aiGenFactory.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AACjF,OAAO,EACL,iBAAiB,EAEjB,eAAe,EACf,aAAa,EACb,cAAc,EACd,eAAe,EACf,WAAW,EACZ,MAAM,wBAAwB,CAAC;AAchC,KAAK,uBAAuB,GAAG,UAAU,wBAAwB,CAAC;AAElE,eAAO,MAAM,gBAAgB,EAAE,MAAM,CACnC,eAAe,EACf,uBAAuB,CA+DxB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CACnC,iBAAiB,EACjB,uBAAuB,CA2CxB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CACnC,eAAe,EACf,uBAAuB,CAMxB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CACjC,aAAa,EACb,uBAAuB,CAGxB,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,cAAc,EAAE,uBAAuB,CAsBzE,CAAC;AAEJ,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,WAAW,GACpB,wBAAwB,CAkB1B"}
+{"version":3,"file":"aiGenFactory.service.d.ts","sourceRoot":"","sources":["../../../src/services/aiGen/aiGenFactory.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AACjF,OAAO,EACL,iBAAiB,EAEjB,eAAe,EACf,aAAa,EACb,cAAc,EACd,eAAe,EACf,WAAW,EACZ,MAAM,wBAAwB,CAAC;AAchC,KAAK,uBAAuB,GAAG,UAAU,wBAAwB,CAAC;AASlE,eAAO,MAAM,gBAAgB,EAAE,OAAO,CACpC,MAAM,CAAC,eAAe,EAAE,uBAAuB,CAAC,CA+DjD,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CACnC,iBAAiB,EACjB,uBAAuB,CA2CxB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CACnC,eAAe,EACf,uBAAuB,CAMxB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CACjC,aAAa,EACb,uBAAuB,CAGxB,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,cAAc,EAAE,uBAAuB,CAsBzE,CAAC;AAEJ,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,WAAW,GACpB,wBAAwB,CAmB1B"}

package/lib/services/aiGen/aiGenFactory.service.js

@@ -14,6 +14,13 @@ const pixverse_service_1 = require("./providers/pixverse/pixverse.service");
 const bytedance_service_1 = require("./providers/bytedance/bytedance.service");
 const elevenlabs_service_1 = require("./providers/elevenlabs/elevenlabs.service");
 const anthropic_service_1 = require("./providers/anthropic/anthropic.service");
+// Partial, intentionally: hosted avatar engines (heygen-avatar, tavus-avatar)
+// are NOT generic video models — they're handled by the dedicated avatar seam
+// (getAvatarVideoProvider / IAvatarVideoProvider). getAiGenProviderService gates
+// on `modelKey in videoServicesMap` and throws for anything absent, so these
+// keys correctly resolve through the avatar factory instead. (kling-avatar stays
+// here because KlingService still backs both its generic-credit path and the
+// KlingAvatarProvider adapter.)
 exports.videoServicesMap = {
     // --- Pixverse ---
     "pixverse-v6": pixverse_service_1.PixVerseService,
@@ -157,8 +164,9 @@ exports.textServicesMap = {
     // "openai-gpt-3.5-turbo": OpenaiService,
 };
 function getAiGenProviderService(modelKey) {
-    if (modelKey in exports.videoServicesMap) {
-        return new exports.videoServicesMap[modelKey]();
+    const VideoService = exports.videoServicesMap[modelKey];
+    if (VideoService) {
+        return new VideoService();
     }
     if (modelKey in exports.imageServicesMap) {
         return new exports.imageServicesMap[modelKey]();

package/lib/services/avatarGen/IAvatarVideoProvider.d.ts

@@ -0,0 +1,136 @@
+import { EVideoSceneStatus, TVideoJobTask } from "../../globals/types";
+import { EVideoMode } from "../aiGen/types";
+/**
+ * Avatar video generation — a first-class provider abstraction, deliberately
+ * SEPARATE from the generic `BaseAiGenProviderService` (text/image → video).
+ *
+ * Why its own seam (SOLID):
+ *  - SRP: animating a presenter/script into a talking video is a different
+ *    responsibility from text/image→video generation. Each gets its own contract.
+ *  - ISP: avatar engines have different capabilities (hosted avatar catalogs,
+ *    trained replicas, dubbing). Those are NARROW optional interfaces below, so
+ *    no engine has to no-op methods it doesn't support.
+ *  - DIP: the worker's `AvatarJobProcessor` and the agent's avatar tool depend on
+ *    THIS interface, not on any concrete engine (Kling/HeyGen/Tavus).
+ *  - OCP: adding an engine = add a class + register it in the avatar factory,
+ *    with zero edits to the processor.
+ *
+ * Today `kling-avatar` is the only implementation (it adapts the shared Kling
+ * transport via `KlingAvatarProvider`). HeyGen/Tavus/Synthesia plug in here next.
+ */
+export declare enum EAvatarEngine {
+    KLING = "kling",
+    HEYGEN = "heygen",
+    TAVUS = "tavus",
+    SYNTHESIA = "synthesia"
+}
+/**
+ * Declares HOW an engine produces a talking video, so the orchestrator
+ * (AvatarJobProcessor) knows what to do around the call:
+ *  - inputMode "byo-media": caller supplies a face image; the AUDIO is produced
+ *    by us (TTS stays its own concern) and passed in. (Kling)
+ *  - inputMode "hosted": caller supplies a provider-hosted avatar + voice + a
+ *    script; the engine does its own TTS/lip-sync. (HeyGen/Tavus)
+ *  - nativeTts: false => the processor must run TTS first and pass `audioUrl`.
+ *  - multiSceneSplit: true => long audio is split into scenes + stitched (Kling);
+ *    false => the engine renders the whole script in one shot (HeyGen/Tavus).
+ */
+export interface AvatarCapabilities {
+    inputMode: "byo-media" | "hosted";
+    nativeTts: boolean;
+    multiSceneSplit: boolean;
+}
+/**
+ * Discriminated request. A provider accepts exactly one `mode` (the one its
+ * `capabilities.inputMode` declares); passing the other is a programmer error
+ * and providers throw.
+ */
+export type AvatarGenerateRequest = {
+    mode: "byo-media";
+    /** Presenter face still — the engine animates this image to lipsync the audio. */
+    faceImageUrl: string;
+    /** Public audio URL (we generated it via TTS, or the caller supplied it). */
+    audioUrl: string;
+    /** Optional motion/emotion hint passed through to the engine. */
+    prompt?: string;
+    /** std / pro etc. — maps to the engine's render quality mode. */
+    renderMode?: EVideoMode;
+} | {
+    mode: "hosted";
+    /** Provider-hosted avatar id (or trained replica id). */
+    hostedAvatarId: string;
+    /** Provider-hosted voice id. */
+    hostedVoiceId: string;
+    /** Script the engine will synthesize + lipsync natively. */
+    script: string;
+    /** BCP-47 locale for native TTS / dubbing. */
+    locale?: string;
+    renderMode?: EVideoMode;
+};
+export interface AvatarSubmitResult {
+    /** Provider-internal task id, polled via `checkStatus`. */
+    providerTaskId: TVideoJobTask;
+}
+export interface AvatarStatusQuery {
+    providerTaskId: TVideoJobTask;
+    /** Filename (no extension) used when stashing the finished video to storage. */
+    outputFilename: string;
+    /** Storage sub-path; defaults to the avatar bucket folder. */
+    outputFilePath?: string;
+}
+export interface AvatarStatusResult {
+    status: EVideoSceneStatus;
+    /** Present when status is COMPLETED. */
+    videoUrl?: string;
+    /** Present when status is FAILED. */
+    errorMessage?: string;
+}
+/**
+ * Core contract every avatar engine implements. Submit + poll only — TTS,
+ * scene-splitting, stitching, credits and retries live in the orchestrator.
+ */
+export interface IAvatarVideoProvider {
+    readonly engine: EAvatarEngine;
+    readonly capabilities: AvatarCapabilities;
+    generate(req: AvatarGenerateRequest): Promise<AvatarSubmitResult>;
+    checkStatus(query: AvatarStatusQuery): Promise<AvatarStatusResult>;
+}
+export interface AvatarOption {
+    id: string;
+    name: string;
+    previewUrl?: string;
+}
+export interface VoiceOption {
+    id: string;
+    name: string;
+    gender?: "male" | "female" | "neutral";
+    accent?: string;
+    previewUrl?: string;
+}
+export interface ConsentRecord {
+    /** Who consented (user id). */
+    userId: string;
+    /** Free-text or signed consent reference for likeness training. */
+    statement: string;
+    /** ISO timestamp the consent was captured. */
+    capturedAt: string;
+}
+/** Engine exposes a catalog of hosted avatars/voices (HeyGen, Tavus, Synthesia). */
+export interface ISupportsHostedCatalog {
+    listAvatars(): Promise<AvatarOption[]>;
+    listVoices(): Promise<VoiceOption[]>;
+}
+/** Engine can train a likeness replica from user media (HeyGen instant avatar, Tavus replica). */
+export interface ISupportsReplica {
+    createReplica(trainingMediaUrl: string, consent: ConsentRecord): Promise<{
+        replicaId: string;
+    }>;
+}
+/** Engine can dub an existing video into another language (Tavus — our multilingual wedge). */
+export interface ISupportsDubbing {
+    dub(videoUrl: string, targetLocale: string): Promise<AvatarSubmitResult>;
+}
+export declare function supportsHostedCatalog(p: IAvatarVideoProvider): p is IAvatarVideoProvider & ISupportsHostedCatalog;
+export declare function supportsReplica(p: IAvatarVideoProvider): p is IAvatarVideoProvider & ISupportsReplica;
+export declare function supportsDubbing(p: IAvatarVideoProvider): p is IAvatarVideoProvider & ISupportsDubbing;
+//# sourceMappingURL=IAvatarVideoProvider.d.ts.map

package/lib/services/avatarGen/IAvatarVideoProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IAvatarVideoProvider.d.ts","sourceRoot":"","sources":["../../../src/services/avatarGen/IAvatarVideoProvider.ts"],"names":[],"mappings":"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"}

package/lib/services/avatarGen/IAvatarVideoProvider.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EAvatarEngine = void 0;
+exports.supportsHostedCatalog = supportsHostedCatalog;
+exports.supportsReplica = supportsReplica;
+exports.supportsDubbing = supportsDubbing;
+/**
+ * Avatar video generation — a first-class provider abstraction, deliberately
+ * SEPARATE from the generic `BaseAiGenProviderService` (text/image → video).
+ *
+ * Why its own seam (SOLID):
+ *  - SRP: animating a presenter/script into a talking video is a different
+ *    responsibility from text/image→video generation. Each gets its own contract.
+ *  - ISP: avatar engines have different capabilities (hosted avatar catalogs,
+ *    trained replicas, dubbing). Those are NARROW optional interfaces below, so
+ *    no engine has to no-op methods it doesn't support.
+ *  - DIP: the worker's `AvatarJobProcessor` and the agent's avatar tool depend on
+ *    THIS interface, not on any concrete engine (Kling/HeyGen/Tavus).
+ *  - OCP: adding an engine = add a class + register it in the avatar factory,
+ *    with zero edits to the processor.
+ *
+ * Today `kling-avatar` is the only implementation (it adapts the shared Kling
+ * transport via `KlingAvatarProvider`). HeyGen/Tavus/Synthesia plug in here next.
+ */
+var EAvatarEngine;
+(function (EAvatarEngine) {
+    EAvatarEngine["KLING"] = "kling";
+    EAvatarEngine["HEYGEN"] = "heygen";
+    EAvatarEngine["TAVUS"] = "tavus";
+    EAvatarEngine["SYNTHESIA"] = "synthesia";
+})(EAvatarEngine || (exports.EAvatarEngine = EAvatarEngine = {}));
+// ─── Type guards ─────────────────────────────────────────────────────────────
+function supportsHostedCatalog(p) {
+    return (typeof p.listAvatars === "function" &&
+        typeof p.listVoices === "function");
+}
+function supportsReplica(p) {
+    return typeof p.createReplica === "function";
+}
+function supportsDubbing(p) {
+    return typeof p.dub === "function";
+}

package/lib/services/avatarGen/avatarProviderFactory.d.ts

@@ -0,0 +1,18 @@
+import { EVideoGenModels } from "../../globals/aiModels";
+import { AvatarCapabilities, IAvatarVideoProvider } from "./IAvatarVideoProvider";
+/** True if `modelKey` is an avatar model handled by a dedicated avatar provider. */
+export declare function isAvatarModel(modelKey: EVideoGenModels): boolean;
+/** Capabilities for an avatar model, or undefined if it isn't an avatar model. */
+export declare function getAvatarCapabilities(modelKey: EVideoGenModels): AvatarCapabilities | undefined;
+/**
+ * True for "hosted" avatar engines (HeyGen/Tavus) — the engine owns TTS + lipsync
+ * from a script, so the orchestrator skips the byo-media (face image + audio)
+ * path. False for byo-media engines (Kling) and non-avatar models.
+ */
+export declare function isHostedAvatarModel(modelKey: EVideoGenModels): boolean;
+/**
+ * Resolve the avatar provider for a model key. Throws if the model isn't an
+ * avatar model (callers should gate on `isAvatarModel` or know the model type).
+ */
+export declare function getAvatarVideoProvider(modelKey: EVideoGenModels): IAvatarVideoProvider;
+//# sourceMappingURL=avatarProviderFactory.d.ts.map

package/lib/services/avatarGen/avatarProviderFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"avatarProviderFactory.d.ts","sourceRoot":"","sources":["../../../src/services/avatarGen/avatarProviderFactory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AA4ClF,oFAAoF;AACpF,wBAAgB,aAAa,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAEhE;AAED,kFAAkF;AAClF,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,eAAe,GACxB,kBAAkB,GAAG,SAAS,CAEhC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAEtE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,eAAe,GACxB,oBAAoB,CAMtB"}

package/lib/services/avatarGen/avatarProviderFactory.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAvatarModel = isAvatarModel;
+exports.getAvatarCapabilities = getAvatarCapabilities;
+exports.isHostedAvatarModel = isHostedAvatarModel;
+exports.getAvatarVideoProvider = getAvatarVideoProvider;
+const aiModels_1 = require("../../globals/aiModels");
+const heygenAvatarProvider_1 = require("./providers/heygenAvatarProvider");
+const klingAvatarProvider_1 = require("./providers/klingAvatarProvider");
+const tavusAvatarProvider_1 = require("./providers/tavusAvatarProvider");
+const avatarProviderMap = {
+    [aiModels_1.EVideoGenModels.KLING_AVATAR]: (modelKey) => new klingAvatarProvider_1.KlingAvatarProvider(modelKey),
+    [aiModels_1.EVideoGenModels.HEYGEN_AVATAR]: (modelKey) => new heygenAvatarProvider_1.HeyGenAvatarProvider(modelKey),
+    [aiModels_1.EVideoGenModels.TAVUS_AVATAR]: (modelKey) => new tavusAvatarProvider_1.TavusAvatarProvider(modelKey),
+};
+/**
+ * Static capability lookup, keyed off each provider's `CAPABILITIES` constant —
+ * so orchestrators (the worker, controllers) can branch on input mode WITHOUT
+ * constructing a provider (construction needs the engine's API key, which would
+ * make a simple "is this hosted?" check fail when keys are absent). Single
+ * source of truth: each entry references the provider class's own static.
+ */
+const avatarCapabilityMap = {
+    [aiModels_1.EVideoGenModels.KLING_AVATAR]: klingAvatarProvider_1.KlingAvatarProvider.CAPABILITIES,
+    [aiModels_1.EVideoGenModels.HEYGEN_AVATAR]: heygenAvatarProvider_1.HeyGenAvatarProvider.CAPABILITIES,
+    [aiModels_1.EVideoGenModels.TAVUS_AVATAR]: tavusAvatarProvider_1.TavusAvatarProvider.CAPABILITIES,
+};
+/** True if `modelKey` is an avatar model handled by a dedicated avatar provider. */
+function isAvatarModel(modelKey) {
+    return modelKey in avatarProviderMap;
+}
+/** Capabilities for an avatar model, or undefined if it isn't an avatar model. */
+function getAvatarCapabilities(modelKey) {
+    return avatarCapabilityMap[modelKey];
+}
+/**
+ * True for "hosted" avatar engines (HeyGen/Tavus) — the engine owns TTS + lipsync
+ * from a script, so the orchestrator skips the byo-media (face image + audio)
+ * path. False for byo-media engines (Kling) and non-avatar models.
+ */
+function isHostedAvatarModel(modelKey) {
+    return avatarCapabilityMap[modelKey]?.inputMode === "hosted";
+}
+/**
+ * Resolve the avatar provider for a model key. Throws if the model isn't an
+ * avatar model (callers should gate on `isAvatarModel` or know the model type).
+ */
+function getAvatarVideoProvider(modelKey) {
+    const factory = avatarProviderMap[modelKey];
+    if (!factory) {
+        throw new Error(`No avatar provider registered for model: ${modelKey}`);
+    }
+    return factory(modelKey);
+}

package/lib/services/avatarGen/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./IAvatarVideoProvider";
+export * from "./avatarProviderFactory";
+export * from "./providers/klingAvatarProvider";
+export * from "./providers/heygenAvatarProvider";
+export * from "./providers/tavusAvatarProvider";
+//# sourceMappingURL=index.d.ts.map

package/lib/services/avatarGen/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/avatarGen/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,iCAAiC,CAAC;AAChD,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC"}

package/lib/services/avatarGen/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./IAvatarVideoProvider"), exports);
+__exportStar(require("./avatarProviderFactory"), exports);
+__exportStar(require("./providers/klingAvatarProvider"), exports);
+__exportStar(require("./providers/heygenAvatarProvider"), exports);
+__exportStar(require("./providers/tavusAvatarProvider"), exports);

package/lib/services/avatarGen/providers/heygenAvatarProvider.d.ts

@@ -0,0 +1,45 @@
+import { EVideoGenModels } from "../../../globals/aiModels";
+import { AvatarCapabilities, AvatarGenerateRequest, AvatarOption, AvatarStatusQuery, AvatarStatusResult, AvatarSubmitResult, EAvatarEngine, IAvatarVideoProvider, ISupportsHostedCatalog, VoiceOption } from "../IAvatarVideoProvider";
+/**
+ * HeyGen avatar engine — a HOSTED engine (the caller picks a HeyGen-hosted
+ * avatar + voice and supplies a script; HeyGen does its own TTS + lipsync).
+ *
+ * Contract (HeyGen API, verified 2026-06-26 against developers.heygen.com +
+ * the published OpenAPI spec; v2 endpoints supported through 2026-10-31):
+ *   • submit : POST  /v2/video/generate   → { data: { video_id } }
+ *   • status : GET   /v1/video_status.get?video_id=…  → { data: { status, video_url } }
+ *   • avatars: GET   /v2/avatars           → { data: { avatars: [...] } }
+ *   • voices : GET   /v2/voices            → { data: { voices: [...] } }
+ *   • auth   : X-Api-Key header
+ *
+ * This is a STANDALONE class (not an adapter over an existing service) because
+ * HeyGen has no representation in the generic video factory — avatar gen is its
+ * own concern (see IAvatarVideoProvider). Transport (auth + timeout + retry) is
+ * owned here, mirroring the per-provider pattern KlingService uses.
+ *
+ * Capabilities: inputMode "hosted", nativeTts true (HeyGen synthesizes), no
+ * multi-scene split (one render per script). It also exposes the hosted catalog
+ * (ISupportsHostedCatalog) so the UI / agent can list pickable avatars + voices.
+ */
+export declare class HeyGenAvatarProvider implements IAvatarVideoProvider, ISupportsHostedCatalog {
+    private readonly modelKey;
+    /** Static so callers can branch on capability without constructing (which
+     *  would require HEYGEN_API_KEY just to read the input mode). */
+    static readonly CAPABILITIES: AvatarCapabilities;
+    readonly engine = EAvatarEngine.HEYGEN;
+    readonly capabilities: AvatarCapabilities;
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly submitTimeout;
+    private readonly statusTimeout;
+    constructor(modelKey?: EVideoGenModels);
+    generate(req: AvatarGenerateRequest): Promise<AvatarSubmitResult>;
+    checkStatus(query: AvatarStatusQuery): Promise<AvatarStatusResult>;
+    listAvatars(): Promise<AvatarOption[]>;
+    listVoices(): Promise<VoiceOption[]>;
+    private normalizeGender;
+    private request;
+    /** Retries transient network/timeout/429 failures with a small backoff. */
+    private requestWithRetry;
+}
+//# sourceMappingURL=heygenAvatarProvider.d.ts.map

package/lib/services/avatarGen/providers/heygenAvatarProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heygenAvatarProvider.d.ts","sourceRoot":"","sources":["../../../../src/services/avatarGen/providers/heygenAvatarProvider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAI5D,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,EACb,oBAAoB,EACpB,sBAAsB,EACtB,WAAW,EACZ,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,oBACX,YAAW,oBAAoB,EAAE,sBAAsB;IAmBrD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAjB3B;qEACiE;IACjE,MAAM,CAAC,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAI9C;IAEF,QAAQ,CAAC,MAAM,wBAAwB;IACvC,QAAQ,CAAC,YAAY,qBAAqC;IAE1D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAW;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;gBAGrB,QAAQ,GAAE,eAA+C;IAQtE,QAAQ,CAAC,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA6CjE,WAAW,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAgClE,WAAW,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAYtC,UAAU,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAwB1C,OAAO,CAAC,eAAe;YAOT,OAAO;IA0BrB,2EAA2E;YAC7D,gBAAgB;CAmD/B"}