vidspotai-shared 1.0.82-dev.0 → 1.0.83

package/lib/services/promptEnhancer/profiles/index.d.ts

@@ -0,0 +1,12 @@
+import { EnhanceTarget } from "../types";
+import { EnhancerProfile } from "./base";
+export { EnhancerProfile, BASE_PRESERVATION_CONTRACT } from "./base";
+export { VIDEO_PROFILE } from "./video.profile";
+export { IMAGE_PROFILE } from "./image.profile";
+export { AVATAR_PROFILE } from "./avatar.profile";
+export { AGENT_PROFILE } from "./agent.profile";
+/** Registry of every target profile, keyed by target. */
+export declare const ENHANCER_PROFILES: Record<EnhanceTarget, EnhancerProfile>;
+/** Resolve the profile for a target. Throws on an unknown target. */
+export declare function getProfile(target: EnhanceTarget): EnhancerProfile;
+//# sourceMappingURL=index.d.ts.map

package/lib/services/promptEnhancer/profiles/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/services/promptEnhancer/profiles/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAMzC,OAAO,EAAE,eAAe,EAAE,0BAA0B,EAAE,MAAM,QAAQ,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,yDAAyD;AACzD,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,aAAa,EAAE,eAAe,CAKpE,CAAC;AAEF,qEAAqE;AACrE,wBAAgB,UAAU,CAAC,MAAM,EAAE,aAAa,GAAG,eAAe,CAMjE"}

package/lib/services/promptEnhancer/profiles/index.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENHANCER_PROFILES = exports.AGENT_PROFILE = exports.AVATAR_PROFILE = exports.IMAGE_PROFILE = exports.VIDEO_PROFILE = exports.BASE_PRESERVATION_CONTRACT = void 0;
+exports.getProfile = getProfile;
+const video_profile_1 = require("./video.profile");
+const image_profile_1 = require("./image.profile");
+const avatar_profile_1 = require("./avatar.profile");
+const agent_profile_1 = require("./agent.profile");
+var base_1 = require("./base");
+Object.defineProperty(exports, "BASE_PRESERVATION_CONTRACT", { enumerable: true, get: function () { return base_1.BASE_PRESERVATION_CONTRACT; } });
+var video_profile_2 = require("./video.profile");
+Object.defineProperty(exports, "VIDEO_PROFILE", { enumerable: true, get: function () { return video_profile_2.VIDEO_PROFILE; } });
+var image_profile_2 = require("./image.profile");
+Object.defineProperty(exports, "IMAGE_PROFILE", { enumerable: true, get: function () { return image_profile_2.IMAGE_PROFILE; } });
+var avatar_profile_2 = require("./avatar.profile");
+Object.defineProperty(exports, "AVATAR_PROFILE", { enumerable: true, get: function () { return avatar_profile_2.AVATAR_PROFILE; } });
+var agent_profile_2 = require("./agent.profile");
+Object.defineProperty(exports, "AGENT_PROFILE", { enumerable: true, get: function () { return agent_profile_2.AGENT_PROFILE; } });
+/** Registry of every target profile, keyed by target. */
+exports.ENHANCER_PROFILES = {
+    video: video_profile_1.VIDEO_PROFILE,
+    image: image_profile_1.IMAGE_PROFILE,
+    avatar: avatar_profile_1.AVATAR_PROFILE,
+    agent: agent_profile_1.AGENT_PROFILE,
+};
+/** Resolve the profile for a target. Throws on an unknown target. */
+function getProfile(target) {
+    const profile = exports.ENHANCER_PROFILES[target];
+    if (!profile) {
+        throw new Error(`[promptEnhancer] no profile registered for target "${target}"`);
+    }
+    return profile;
+}

package/lib/services/promptEnhancer/profiles/video.profile.d.ts

@@ -0,0 +1,15 @@
+import { EnhancerProfile } from "./base";
+/**
+ * VIDEO profile — cinematic text-to-video / image-to-video prompts.
+ *
+ * The structure below is distilled from a set of gold-standard production
+ * prompts (aerial dogfight, Brooklyn tsunami, neutron-star flyby, Nike golf
+ * commercial). Those share a recognisable anatomy: a Style&Mood header, named
+ * subjects with stable descriptors + reference-image bindings, a Dynamic
+ * description of the action, a Static description of the unchanging set, a
+ * shot/timestamp breakdown, and explicit native-audio design. We teach that
+ * anatomy here so a sparse user prompt comes out at that level — without ever
+ * overriding what the user already specified.
+ */
+export declare const VIDEO_PROFILE: EnhancerProfile;
+//# sourceMappingURL=video.profile.d.ts.map

package/lib/services/promptEnhancer/profiles/video.profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"video.profile.d.ts","sourceRoot":"","sources":["../../../../src/services/promptEnhancer/profiles/video.profile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAEzC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,EAAE,eAiE3B,CAAC"}

package/lib/services/promptEnhancer/profiles/video.profile.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VIDEO_PROFILE = void 0;
+/**
+ * VIDEO profile — cinematic text-to-video / image-to-video prompts.
+ *
+ * The structure below is distilled from a set of gold-standard production
+ * prompts (aerial dogfight, Brooklyn tsunami, neutron-star flyby, Nike golf
+ * commercial). Those share a recognisable anatomy: a Style&Mood header, named
+ * subjects with stable descriptors + reference-image bindings, a Dynamic
+ * description of the action, a Static description of the unchanging set, a
+ * shot/timestamp breakdown, and explicit native-audio design. We teach that
+ * anatomy here so a sparse user prompt comes out at that level — without ever
+ * overriding what the user already specified.
+ */
+exports.VIDEO_PROFILE = {
+    target: "video",
+    defaultTemperature: 0.45,
+    defaultMaxTokens: 2200,
+    systemPrompt: [
+        "MEDIUM: text-to-video / image-to-video. The model generates a moving shot (or short",
+        "sequence of shots) from your prompt. It cannot read your mind about camera, light, lens, or",
+        "sound — so describe them. Quality comes from concrete, physically coherent cinematic detail.",
+        "",
+        "Compose the enhanced prompt using these sections, in this order. Include a section only when",
+        "it adds value; never output an empty heading. Use the user's own content to fill them and add",
+        "craft where they were silent.",
+        "",
+        "1. STYLE & MOOD — lead with it. Name the medium and realism level (e.g. 'photoreal cinematic',",
+        "   'stylised 2D'), the color grade / palette, the camera + lens + film-stock feel (e.g. 'ARRI",
+        "   ALEXA, 35mm, filmic grain'), the overall mood, and continuity (how many shots / cuts, or",
+        "   'one continuous handheld take'). Keep the user's chosen look if they gave one.",
+        "",
+        "2. SUBJECTS — define each recurring subject ONCE with stable, distinctive descriptors so the",
+        "   model keeps them consistent across the shot. When the user supplied reference images, bind",
+        "   each subject to its token exactly as given (e.g. 'PILOT: face exactly from @image 3'). When",
+        "   two subjects could be confused, add a disambiguator ('never confuse the two planes').",
+        "",
+        "3. DYNAMIC DESCRIPTION — the action as it unfolds: what moves, what changes, and the camera",
+        "   language driving it (locked-off, slow push-in, whip-pan, tracking, handheld micro-shake,",
+        "   focus hunt, banking). Keep the user's described events and their ORDER intact; render them",
+        "   in vivid, physically plausible motion.",
+        "",
+        "4. STATIC DESCRIPTION — the unchanging environment / set: location, time of day, weather,",
+        "   light direction, atmosphere. Include explicit exclusions when they matter ('no ground",
+        "   visible', 'only these two subjects exist in this space').",
+        "",
+        "5. SHOT / TIME BREAKDOWN — when the duration warrants more than one beat, break it into",
+        "   timestamped segments ('00:00–00:03 …') or numbered shots ('Shot 1 …'), each stating camera",
+        "   + subject + action. Budget the number of beats to the duration: roughly one distinct beat",
+        "   per 2–4 seconds; do not over-cut a short clip. Respect any cut count the user specified.",
+        "",
+        "6. NATIVE AUDIO — describe the diegetic sound design (impacts, ambience, foley, dialogue",
+        "   energy) or state 'No music.' if the user asked for none. Honour the user's audio wishes",
+        "   exactly. Omit this section entirely for silent / audio-less models.",
+        "",
+        "7. ASPECT RATIO — state it if known (e.g. '2.39:1', '9:16').",
+        "",
+        "RULES OF THE CRAFT:",
+        "- Concrete nouns over adjectives; describe light physically (key/fill/rim, color temperature,",
+        "  how it interacts with surfaces).",
+        "- One coherent world: do not stack contradictory styles or add subjects/props the user didn't",
+        "  ask for.",
+        "- Preserve every reference-image token and the role it was bound to. Never reassign a token.",
+        "- If the user's prompt is already detailed and well-structured, enhance lightly and keep their",
+        "  structure — do not rewrite a strong prompt into your template for its own sake.",
+        "",
+        "SHAPE OF A GREAT RESULT (illustrative — a sparse input lifted to production grade):",
+        "  User: 'a knight fights a dragon in a castle'",
+        "  Enhanced (abridged): 'Style & Mood: photoreal dark-fantasy cinematic, ARRI-style, cold",
+        "  steel-blue grade with ember-orange firelight, anamorphic 2.39:1, handheld with controlled",
+        "  micro-shake. SUBJECT — KNIGHT: battered plate armor, dented helm, longsword. SUBJECT —",
+        "  DRAGON: 12m wingspan, charcoal scales, molten throat-glow. Dynamic: low tracking shot as the",
+        "  knight charges across the courtyard, the dragon rears and unleashes a fire breath, the knight",
+        "  rolls behind a stone pillar that scorches black, then drives the sword up into the dragon's",
+        "  jaw. Static: ruined torch-lit castle courtyard at night, smoke and floating embers, rain",
+        "  catching the firelight. Native audio: roar, sword scrape, fire whoosh, rain, no music.'",
+        "  — note how every user element (knight, dragon, castle, fight) is preserved and only the",
+        "  silent gaps (grade, lens, light, camera, audio) were filled.",
+    ].join("\n"),
+};

package/lib/services/promptEnhancer/promptEnhancer.service.d.ts

@@ -0,0 +1,45 @@
+import { LlmCaller } from "../agent/llmCaller";
+import { EnhancerModelPolicy } from "./models";
+import { EnhanceRequest, EnhanceResult } from "./types";
+/** Dependencies the enhancer needs; defaulted to the shared singletons/policy. */
+export interface PromptEnhancerDeps {
+    /** LLM caller. Defaults to the host-wired singleton via getLlmCaller(). */
+    llm?: LlmCaller;
+    /** Model policy. Defaults to DEFAULT_ENHANCER_MODELS (gemini-2.5-flash primary). */
+    models?: EnhancerModelPolicy;
+}
+/**
+ * Modular, target-aware prompt enhancer. Reusable across the video, image,
+ * avatar, and agent pipelines — same engine, per-target profiles.
+ *
+ *   const enhancer = new PromptEnhancer();
+ *   const { enhancedPrompt } = await enhancer.enhance({
+ *     prompt: userPrompt,
+ *     target: "video",
+ *     context: { aspectRatio: "16:9", durationSec: 8 },
+ *   });
+ */
+export declare class PromptEnhancer {
+    private readonly deps;
+    constructor(deps?: PromptEnhancerDeps);
+    /**
+     * Enhance a prompt. Throws if the prompt is empty or the LLM call fails
+     * (transient errors already retried by the caller). Use `enhanceSafe` when a
+     * failure must not break the host pipeline.
+     */
+    enhance(req: EnhanceRequest): Promise<EnhanceResult>;
+    /**
+     * Pipeline-safe variant: on ANY failure (LLM unconfigured, transient errors
+     * exhausted, schema mismatch) it logs and returns the untouched original as
+     * `enhancedPrompt` with `degraded: true`. Wiring this into a hot path can
+     * never break generation — worst case the user's raw prompt is used as-is.
+     */
+    enhanceSafe(req: EnhanceRequest): Promise<EnhanceResult>;
+}
+/** Process-wide default instance; convenient for one-off calls. */
+export declare const promptEnhancer: PromptEnhancer;
+/** Convenience wrapper around the default instance. */
+export declare function enhancePrompt(req: EnhanceRequest): Promise<EnhanceResult>;
+/** Pipeline-safe convenience wrapper around the default instance. */
+export declare function enhancePromptSafe(req: EnhanceRequest): Promise<EnhanceResult>;
+//# sourceMappingURL=promptEnhancer.service.d.ts.map

package/lib/services/promptEnhancer/promptEnhancer.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promptEnhancer.service.d.ts","sourceRoot":"","sources":["../../../src/services/promptEnhancer/promptEnhancer.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE5D,OAAO,EAEL,mBAAmB,EAEpB,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAkB,cAAc,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAIxE,kFAAkF;AAClF,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,oFAAoF;IACpF,MAAM,CAAC,EAAE,mBAAmB,CAAC;CAC9B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;gBAE9B,IAAI,GAAE,kBAAuB;IAIzC;;;;OAIG;IACG,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IA+C1D;;;;;OAKG;IACG,WAAW,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;CAmB/D;AA8DD,mEAAmE;AACnE,eAAO,MAAM,cAAc,gBAAuB,CAAC;AAEnD,uDAAuD;AACvD,wBAAgB,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAEzE;AAED,qEAAqE;AACrE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAE7E"}

package/lib/services/promptEnhancer/promptEnhancer.service.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.promptEnhancer = exports.PromptEnhancer = void 0;
+exports.enhancePrompt = enhancePrompt;
+exports.enhancePromptSafe = enhancePromptSafe;
+const logger_1 = require("../../utils/logger");
+const llmCallerRegistry_1 = require("../agent/llmCallerRegistry");
+const models_1 = require("./models");
+const profiles_1 = require("./profiles");
+const schema_1 = require("./schema");
+const log = (0, logger_1.createLogger)("promptEnhancer");
+/**
+ * Modular, target-aware prompt enhancer. Reusable across the video, image,
+ * avatar, and agent pipelines — same engine, per-target profiles.
+ *
+ *   const enhancer = new PromptEnhancer();
+ *   const { enhancedPrompt } = await enhancer.enhance({
+ *     prompt: userPrompt,
+ *     target: "video",
+ *     context: { aspectRatio: "16:9", durationSec: 8 },
+ *   });
+ */
+class PromptEnhancer {
+    constructor(deps = {}) {
+        this.deps = deps;
+    }
+    /**
+     * Enhance a prompt. Throws if the prompt is empty or the LLM call fails
+     * (transient errors already retried by the caller). Use `enhanceSafe` when a
+     * failure must not break the host pipeline.
+     */
+    async enhance(req) {
+        const original = (req.prompt ?? "").trim();
+        if (!original) {
+            throw new Error("[promptEnhancer] prompt is empty");
+        }
+        const profile = (0, profiles_1.getProfile)(req.target);
+        // Resolve deps lazily at call time so the host has had a chance to wire the
+        // LlmCaller singleton during boot.
+        const llm = this.deps.llm ?? (0, llmCallerRegistry_1.getLlmCaller)();
+        const policy = this.deps.models ?? models_1.DEFAULT_ENHANCER_MODELS;
+        // An explicit per-call model override bypasses the policy + premium flag.
+        const { model, fallbackModel } = req.options?.model
+            ? { model: req.options.model, fallbackModel: req.options.fallbackModel }
+            : (0, models_1.pickEnhancerModel)(policy, req.options?.premium);
+        const messages = buildMessages(profile, original, req.context);
+        const res = await llm.structured({
+            model,
+            fallbackModel,
+            schema: schema_1.EnhancedPromptSchema,
+            schemaName: "EnhancedPrompt",
+            messages,
+            temperature: req.options?.temperature ?? profile.defaultTemperature,
+            maxTokens: req.options?.maxTokens ?? profile.defaultMaxTokens,
+        });
+        const enhanced = (res.data.enhancedPrompt ?? "").trim();
+        // Defensive: if the model returned nothing usable, fall back to the original
+        // rather than handing an empty prompt to a generation model.
+        const enhancedPrompt = enhanced.length > 0 ? enhanced : original;
+        return {
+            enhancedPrompt,
+            originalPrompt: original,
+            preservedRequirements: res.data.preservedRequirements ?? [],
+            additions: res.data.additions ?? [],
+            target: req.target,
+            model: model.modelId,
+            usedFallback: res.usedFallback,
+            degraded: enhanced.length === 0,
+            usage: res.usage,
+        };
+    }
+    /**
+     * Pipeline-safe variant: on ANY failure (LLM unconfigured, transient errors
+     * exhausted, schema mismatch) it logs and returns the untouched original as
+     * `enhancedPrompt` with `degraded: true`. Wiring this into a hot path can
+     * never break generation — worst case the user's raw prompt is used as-is.
+     */
+    async enhanceSafe(req) {
+        const original = (req.prompt ?? "").trim();
+        try {
+            return await this.enhance(req);
+        }
+        catch (err) {
+            log.warn("enhance failed; falling back to original prompt", {
+                target: req.target,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return {
+                enhancedPrompt: original,
+                originalPrompt: original,
+                preservedRequirements: [],
+                additions: [],
+                target: req.target,
+                degraded: true,
+            };
+        }
+    }
+}
+exports.PromptEnhancer = PromptEnhancer;
+/** Build the system + context + user messages for one enhance call. */
+function buildMessages(profile, prompt, context) {
+    const system = `${profiles_1.BASE_PRESERVATION_CONTRACT}\n\n=== ${profile.target.toUpperCase()} MEDIUM ===\n${profile.systemPrompt}`;
+    const contextBlock = buildContextBlock(context);
+    const userContent = contextBlock
+        ? `${contextBlock}\n\nUSER PROMPT:\n${prompt}`
+        : `USER PROMPT:\n${prompt}`;
+    const userMessage = { role: "user", content: userContent };
+    // Attach reference images for vision only when explicitly requested and URLs
+    // are present — the host is responsible for routing to a vision-capable model.
+    if (context?.useVision && context.referenceImages?.length) {
+        const urls = context.referenceImages
+            .map((r) => r.url)
+            .filter((u) => typeof u === "string" && u.length > 0);
+        if (urls.length) {
+            userMessage.imageUrls = urls;
+        }
+    }
+    return [{ role: "system", content: system }, userMessage];
+}
+/** Render the optional context as a compact, labelled block. Empty fields are omitted. */
+function buildContextBlock(context) {
+    if (!context)
+        return "";
+    const lines = [];
+    if (context.modelKey)
+        lines.push(`TARGET MODEL: ${context.modelKey}`);
+    if (context.aspectRatio)
+        lines.push(`ASPECT RATIO: ${context.aspectRatio}`);
+    if (typeof context.durationSec === "number") {
+        lines.push(`DURATION: ${context.durationSec}s`);
+    }
+    if (context.persona)
+        lines.push(`PERSONA / NICHE: ${context.persona}`);
+    if (context.referenceImages?.length) {
+        const refs = context.referenceImages
+            .map((r, i) => {
+            const token = r.token ?? `@image ${i + 1}`;
+            return r.role ? `  - ${token} → ${r.role}` : `  - ${token}`;
+        })
+            .join("\n");
+        lines.push(`REFERENCE IMAGES (preserve these tokens and their roles exactly):\n${refs}`);
+    }
+    if (context.extraInstructions) {
+        lines.push(`ADDITIONAL HARD INSTRUCTIONS: ${context.extraInstructions}`);
+    }
+    return lines.length ? `CONTEXT:\n${lines.join("\n")}` : "";
+}
+/** Process-wide default instance; convenient for one-off calls. */
+exports.promptEnhancer = new PromptEnhancer();
+/** Convenience wrapper around the default instance. */
+function enhancePrompt(req) {
+    return exports.promptEnhancer.enhance(req);
+}
+/** Pipeline-safe convenience wrapper around the default instance. */
+function enhancePromptSafe(req) {
+    return exports.promptEnhancer.enhanceSafe(req);
+}

package/lib/services/promptEnhancer/schema.d.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+/**
+ * Structured output the enhancer LLM must return.
+ *
+ * The field ORDER matters: the model is asked to enumerate the user's
+ * requirements FIRST, then write the enhanced prompt, then list what it added.
+ * Forcing the enumeration up front is the core preservation guard — the model
+ * commits to the user's constraints before it starts embellishing, which makes
+ * it far less likely to silently drop or "improve" a stated requirement. The
+ * enumerated arrays also give callers a hook for a future verification pass
+ * (assert every preservedRequirement appears in enhancedPrompt).
+ */
+export declare const EnhancedPromptSchema: z.ZodObject<{
+    preservedRequirements: z.ZodArray<z.ZodString>;
+    enhancedPrompt: z.ZodString;
+    additions: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type EnhancedPromptOutput = z.infer<typeof EnhancedPromptSchema>;
+//# sourceMappingURL=schema.d.ts.map

package/lib/services/promptEnhancer/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/services/promptEnhancer/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB;;;;iBAiC/B,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/lib/services/promptEnhancer/schema.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnhancedPromptSchema = void 0;
+const zod_1 = require("zod");
+/**
+ * Structured output the enhancer LLM must return.
+ *
+ * The field ORDER matters: the model is asked to enumerate the user's
+ * requirements FIRST, then write the enhanced prompt, then list what it added.
+ * Forcing the enumeration up front is the core preservation guard — the model
+ * commits to the user's constraints before it starts embellishing, which makes
+ * it far less likely to silently drop or "improve" a stated requirement. The
+ * enumerated arrays also give callers a hook for a future verification pass
+ * (assert every preservedRequirement appears in enhancedPrompt).
+ */
+exports.EnhancedPromptSchema = zod_1.z.object({
+    preservedRequirements: zod_1.z
+        .array(zod_1.z.string())
+        .describe([
+        "Every concrete requirement stated or clearly implied by the user's original prompt.",
+        "Include: subjects and named entities, specific actions/events, style and mood words the",
+        "user chose, brand names, numbers (durations, counts, timestamps), reference-image",
+        "bindings (e.g. '@image 2', 'Person A'), aspect ratio, and explicit exclusions",
+        "(e.g. 'no music', 'no ground visible'). Each item here MUST appear, unchanged in meaning,",
+        "in enhancedPrompt. If the user's prompt is sparse, this list may be short — that is fine.",
+    ].join(" ")),
+    enhancedPrompt: zod_1.z
+        .string()
+        .min(1)
+        .describe([
+        "The final, ready-to-use prompt. It must (a) preserve every item in preservedRequirements",
+        "with its original meaning intact, and (b) layer production-grade detail on top following",
+        "the profile's structure. Output ONLY the prompt text itself — no preamble, no markdown",
+        "fences, no commentary about what you did.",
+    ].join(" ")),
+    additions: zod_1.z
+        .array(zod_1.z.string())
+        .describe([
+        "The specific details you ADDED where the user was silent or vague (e.g. color grade, lens,",
+        "lighting, camera movement, audio design, pacing). Do NOT list anything that changes or",
+        "contradicts a preserved requirement — additions only fill gaps, they never override the user.",
+    ].join(" ")),
+});

package/lib/services/promptEnhancer/types.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Public types for the modular Prompt Enhancer.
+ *
+ * The enhancer takes a user's raw prompt and rewrites it into a richer,
+ * production-grade prompt for a downstream generative model — while
+ * PRESERVING everything the user explicitly asked for and only ADDING detail
+ * where the user was silent. It is target-aware (video / image / avatar /
+ * agent) so the same engine produces the right idiom for each pipeline.
+ */
+import { ModelChoice } from "../agent/modelRouter";
+/**
+ * Which pipeline the enhanced prompt feeds. Each target has its own profile
+ * (system prompt + rules + model routing):
+ *   - "video"  : cinematic text-to-video / image-to-video prompt (the richest
+ *                profile — style+mood, named subjects, dynamic vs static
+ *                description, timestamped shot breakdown, native audio).
+ *   - "image"  : single still-frame prompt (composition, lens, lighting, grade;
+ *                no motion, no audio, no temporal beats).
+ *   - "avatar" : talking-head performance hint over a fixed portrait + audio
+ *                (expression, micro-gesture, delivery; never a new scene).
+ *   - "agent"  : creative-brief clarifier fed to the agent Planner (sharpens
+ *                concept/audience/tone/beats; does NOT pre-explode scenes — the
+ *                Planner owns scene decomposition).
+ */
+export type EnhanceTarget = "video" | "image" | "avatar" | "agent";
+/**
+ * A reference image the user supplied. Its token and role are user
+ * requirements and MUST survive into the enhanced prompt unchanged.
+ */
+export interface ReferenceImageHint {
+    /** Token the prompt uses to refer to this image, e.g. "@image 1", "@Image2". */
+    token?: string;
+    /** What the image depicts / its role, e.g. "the pilot's face", "Person A". */
+    role?: string;
+    /**
+     * Public URL. Only read by the enhancer when `EnhanceContext.useVision` is
+     * true and the routed model is vision-capable — otherwise it is ignored and
+     * only `token`/`role` are used.
+     */
+    url?: string;
+}
+/** Optional context that lets a profile tailor the enhancement. */
+export interface EnhanceContext {
+    /** Destination model key (e.g. "runway-gen4-turbo"). Lets profiles tune syntax/length. */
+    modelKey?: string;
+    /** Output aspect ratio, e.g. "16:9", "9:16", "2.39:1". Preserved verbatim. */
+    aspectRatio?: string;
+    /** Target duration in seconds (video/avatar). Drives shot count + timestamp budget. */
+    durationSec?: number;
+    /** Reference images the user supplied; their tokens/roles MUST be preserved. */
+    referenceImages?: ReferenceImageHint[];
+    /** Persona / niche hint (agent path), e.g. "ugc-ad". Free-form, advisory only. */
+    persona?: string;
+    /** Extra hard instructions from the caller that must also be honoured. */
+    extraInstructions?: string;
+    /**
+     * When true, attach `referenceImages[].url` to the LLM call so a
+     * vision-capable model can describe them faithfully. Host must ensure the
+     * routed model supports vision.
+     */
+    useVision?: boolean;
+}
+/** Knobs for a single enhance call. */
+export interface EnhanceOptions {
+    /** Use the premium enhancer model (higher quality, higher cost/latency). Default false. */
+    premium?: boolean;
+    /**
+     * Explicit model override. Bypasses the enhancer model policy (and the
+     * `premium` flag) entirely. Provider must have a native caller wired.
+     */
+    model?: ModelChoice;
+    /** Fallback used alongside `model`. Ignored unless `model` is set. */
+    fallbackModel?: ModelChoice;
+    /** Creativity. Defaults to the profile's value. Lower = more faithful. */
+    temperature?: number;
+    /** Max output tokens. Defaults to the profile's value. */
+    maxTokens?: number;
+}
+export interface EnhanceRequest {
+    /** The user's raw prompt. Required, non-empty after trim. */
+    prompt: string;
+    /** Which pipeline this prompt feeds. */
+    target: EnhanceTarget;
+    context?: EnhanceContext;
+    options?: EnhanceOptions;
+}
+export interface EnhanceResult {
+    /** The enhanced, ready-to-use prompt. Drop-in replacement for the raw prompt. */
+    enhancedPrompt: string;
+    /** The original prompt, verbatim (so callers can persist it as originalPrompt). */
+    originalPrompt: string;
+    /**
+     * Hard requirements the enhancer extracted from the user prompt and
+     * preserved. Useful for debugging/telemetry and a future verification pass.
+     */
+    preservedRequirements: string[];
+    /** Detail the enhancer added where the user was silent. */
+    additions: string[];
+    /** Target this was enhanced for. */
+    target: EnhanceTarget;
+    /** Logical model id that produced the result. */
+    model?: string;
+    /** True if the fallback model produced the result. */
+    usedFallback?: boolean;
+    /** True when enhancement failed and `enhancedPrompt` is the untouched original. */
+    degraded?: boolean;
+    usage?: {
+        promptTokens?: number;
+        completionTokens?: number;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/services/promptEnhancer/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/promptEnhancer/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEnE;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,mEAAmE;AACnE,MAAM,WAAW,cAAc;IAC7B,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uFAAuF;IACvF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,eAAe,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACvC,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,uCAAuC;AACvC,MAAM,WAAW,cAAc;IAC7B,2FAA2F;IAC3F,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,sEAAsE;IACtE,aAAa,CAAC,EAAE,WAAW,CAAC;IAC5B,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,iFAAiF;IACjF,cAAc,EAAE,MAAM,CAAC;IACvB,mFAAmF;IACnF,cAAc,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,2DAA2D;IAC3D,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,oCAAoC;IACpC,MAAM,EAAE,aAAa,CAAC;IACtB,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9D"}

package/lib/services/promptEnhancer/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/services/rateLimiter/distributedRateLimiter.service.d.ts

@@ -1,5 +1,18 @@
 import { TAiGenModel } from "../../globals/aiModels";
 import { TtsProvider } from "../../globals/ttsModels/types";
+/**
+ * Capacity-planning thresholds (used by previewCapacity + the bounded gate).
+ *
+ * MAX_ACCEPTABLE_WAIT_MS — a model whose projected wait for a submit slot
+ *   exceeds this is considered "not available" by previewCapacity, so the
+ *   job-start selector spills to a less-loaded model in the same tier chain.
+ * DAILY_NEAR_RESET_MS — when a model's per-day cap is exhausted, we only wait
+ *   it out if the UTC-midnight reset is within this window; otherwise the
+ *   bounded gate fast-fails (VIDEO_PROVIDER_RATE_LIMITED) so the caller can
+ *   fall back rather than block for hours.
+ */
+export declare const MAX_ACCEPTABLE_WAIT_MS = 180000;
+export declare const DAILY_NEAR_RESET_MS = 120000;
 /**
  * DistributedRateLimiter — three-tier provider quota gate.
  *
@@ -39,6 +52,29 @@ export interface LimiterSnapshot {
     perMinLimit?: number;
     perDayLimit?: number;
 }
+/**
+ * Read-only capacity estimate for a model — does NOT consume a slot. Used by
+ * the job-start model selector to decide whether to spill to another model in
+ * the tier chain before triggering. `available` folds the projected-wait and
+ * daily-reset thresholds into a single go/no-go.
+ */
+export interface CapacityPreview {
+    modelKey: string;
+    /** Rough estimate of how long until a NEW submit can proceed, in ms. */
+    projectedWaitMs: number;
+    /** Whether a new submission can proceed within the acceptable wait window. */
+    available: boolean;
+    /** Per-day cap is configured and currently exhausted. */
+    dailyExhausted: boolean;
+    secsUntilDayReset: number;
+    perMinUsed: number;
+    perMinLimit: number;
+    perDayUsed: number;
+    perDayLimit: number;
+    concurrentActive: number;
+    concurrentLimit: number;
+    concurrentQueueDepth: number;
+}
 export declare class DistributedRateLimiter {
     private readonly modelKey;
     private readonly concurrentLimit;
@@ -52,15 +88,34 @@ export declare class DistributedRateLimiter {
      * a slot in each. Caller MUST call releaseSlot() when the in-flight task
      * settles — per-min / per-day auto-expire but the concurrent counter does
      * not. Mirrors the old AiGenModelRateLimiter API.
+     *
+     * `opts.maxWaitMs` bounds the rate-budget wait: if satisfying the per-day /
+     * per-minute gate would take longer than this, the call throws a
+     * `UserFacingError(VIDEO_PROVIDER_RATE_LIMITED)` instead of sleep-looping for
+     * hours. This is the backstop that stops jobs from piling up in-process when
+     * a daily cap is hit — the submit path passes it; legacy callers that omit
+     * it keep the original (unbounded) behavior.
      */
-    waitUntilAvailable(): Promise<void>;
+    waitUntilAvailable(opts?: {
+        maxWaitMs?: number;
+    }): Promise<void>;
     /**
-     * Bumps per-min + per-day only — does NOT count toward the concurrent cap.
-     * Use for short-lived calls that share a provider's rate budget but aren't
-     * "in-flight tasks" (status polls, sync image/TTS gens that complete in the
-     * same call). No release is needed — Redis auto-expires the counters.
+     * Bumps per-MINUTE only — does NOT count toward the concurrent cap and does
+     * NOT consume/await the per-day gate. Use for short-lived calls that share a
+     * provider's per-minute budget but must not be blocked by the daily SUBMIT
+     * cap: status polls of already-running tasks (failing a poll on daily quota
+     * would abandon a video that's already generating), plus sync image/TTS gens
+     * (which have no per-day limit configured anyway). No release needed — Redis
+     * auto-expires the counters.
      */
     waitUntilAvailableForOneShot(): Promise<void>;
+    /**
+     * Read-only capacity estimate — does NOT consume a slot. Reads current
+     * per-minute / per-day usage and concurrency pressure from Redis and
+     * projects how long a new submission would wait. Fails open (available:true,
+     * wait:0) on Redis errors / no client, matching the gate's fail-open policy.
+     */
+    previewCapacity(maxAcceptableWaitMs?: number): Promise<CapacityPreview>;
     /** Free a concurrent slot acquired via waitUntilAvailable(). */
     releaseSlot(): void;
     get activeConcurrentCount(): number;