vidspotai-shared 1.0.82 → 1.0.83

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/socialAI/captionGen.d.ts

@@ -0,0 +1,81 @@
+import { ESocialProvider } from "../../globals/types";
+/**
+ * X8 Social Suite — E1: AI caption / hashtag / title generation (Phase 6 AI
+ * growth layer). Pure, dependency-free core: builds the LLM prompt, parses +
+ * clamps the model's JSON, and exposes `generateSocialSuggestionsCore(llm, ctx)`
+ * with the LLM injected so it's unit-/eval-testable away from the OpenAI client
+ * (planner-style `*Core(llm,…)` convention — see L-3/L-5).
+ *
+ * One round-trip produces a platform-agnostic BASE (caption + hashtags + title)
+ * that fills the composer's main fields, PLUS per-platform VARIANTS tailored to
+ * each requested provider's norms (char limits, hashtag conventions, title use)
+ * that pre-seed the composer's per-platform overrides. The composer applies the
+ * base by default and reveals the variants progressively (pro depth, beginner
+ * surface — plan §B1/§E1).
+ */
+/** Input context for a suggestion request (no secrets — safe to log). */
+export interface ISocialSuggestionContext {
+    /** Providers to tailor per-platform variants for (the composer's targets). */
+    providers: ESocialProvider[];
+    /** Title of the source video, if any. */
+    videoTitle?: string;
+    /** What the video is about — prompt / script summary that grounds the copy. */
+    videoSummary?: string;
+    /** ISO-639-1 / locale to WRITE the copy in (defaults to English). */
+    language?: string;
+    /** Optional brand-voice / tone steer (e.g. "playful, no emojis"). */
+    tone?: string;
+}
+/** A per-platform tailored caption + hashtag set. */
+export interface ISocialSuggestionVariant {
+    provider: ESocialProvider;
+    caption: string;
+    hashtags: string[];
+}
+/** The full suggestion the composer renders. */
+export interface ISocialSuggestion {
+    /** Platform-agnostic caption the composer fills into the main field. */
+    caption: string;
+    /** Platform-agnostic hashtag set (no leading '#', deduped). */
+    hashtags: string[];
+    /** Title (used by YouTube; harmless to ignore on caption-only platforms). */
+    title: string;
+    /** Per-platform variants for the requested providers (best-effort). */
+    variants: ISocialSuggestionVariant[];
+}
+/** A minimal LLM call: take chat messages, return the raw text completion. */
+export type SuggestionLlm = (messages: Array<{
+    role: "system" | "user";
+    content: string;
+}>) => Promise<string>;
+/**
+ * Per-platform copy norms. `maxChars` clamps the caption; `maxHashtags` caps the
+ * tag list; `note` is fed to the model so each variant reads native to the
+ * platform. Hard limits (X = 280) are real product constraints, not style.
+ */
+interface PlatformCopyHint {
+    maxChars: number;
+    maxHashtags: number;
+    note: string;
+}
+export declare const PLATFORM_COPY_HINTS: Record<ESocialProvider, PlatformCopyHint>;
+/** Build the chat prompt for a suggestion request. Pure — no I/O. */
+export declare function buildSuggestionPrompt(ctx: ISocialSuggestionContext): Array<{
+    role: "system" | "user";
+    content: string;
+}>;
+/**
+ * Parse + validate + clamp the model's JSON into an `ISocialSuggestion`.
+ * Defensive: malformed JSON degrades to a plain caption (the raw text) with no
+ * hashtags/variants rather than throwing, so the composer always gets something
+ * usable. Variants are kept only for providers the caller actually requested.
+ */
+export declare function parseSocialSuggestion(raw: string, ctx: ISocialSuggestionContext): ISocialSuggestion;
+/**
+ * Generate social suggestions with the LLM injected (testable). Builds the
+ * prompt, calls the model, parses + clamps the result. Never throws on a bad
+ * model response — it degrades to a usable caption (see `parseSocialSuggestion`).
+ */
+export declare function generateSocialSuggestionsCore(llm: SuggestionLlm, ctx: ISocialSuggestionContext): Promise<ISocialSuggestion>;
+export {};
+//# sourceMappingURL=captionGen.d.ts.map

package/lib/services/socialAI/captionGen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"captionGen.d.ts","sourceRoot":"","sources":["../../../src/services/socialAI/captionGen.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;;;;;;;;;;;GAaG;AAEH,yEAAyE;AACzE,MAAM,WAAW,wBAAwB;IACvC,8EAA8E;IAC9E,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qDAAqD;AACrD,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,eAAe,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,gDAAgD;AAChD,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,QAAQ,EAAE,wBAAwB,EAAE,CAAC;CACtC;AAED,8EAA8E;AAC9E,MAAM,MAAM,aAAa,GAAG,CAC1B,QAAQ,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,KAC1D,OAAO,CAAC,MAAM,CAAC,CAAC;AAErB;;;;GAIG;AACH,UAAU,gBAAgB;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,eAAe,EAAE,gBAAgB,CAyCzE,CAAC;AAqCF,qEAAqE;AACrE,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,wBAAwB,GAC5B,KAAK,CAAC;IAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAkDrD;AAYD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,wBAAwB,GAC5B,iBAAiB,CA2DnB;AAED;;;;GAIG;AACH,wBAAsB,6BAA6B,CACjD,GAAG,EAAE,aAAa,EAClB,GAAG,EAAE,wBAAwB,GAC5B,OAAO,CAAC,iBAAiB,CAAC,CAI5B"}