vidspotai-shared 1.0.67 → 1.0.69-dev.0

package/lib/services/agent/planner/Planner.d.ts

@@ -0,0 +1,107 @@
+import { AgentPersona } from "../../../schemas/agentPersona.schema";
+import { VideoBrief } from "../../../schemas/brief.schema";
+import { AgentVisualBible, PlannedScene, TextOverlay, VideoPlan } from "../../../schemas/videoPlan.schema";
+import { IBrandKitModel, IStyleMemoryModel } from "../../../models/agent.model";
+import { LlmCaller } from "../llmCaller";
+import { ModelRouter } from "../modelRouter";
+/**
+ * Planner — turns a VideoBrief into a Zod-validated VideoPlan.
+ *
+ * Plan-then-execute architecture (not free-form ReAct): the planner runs in a
+ * single structured-output call, the executor runs the plan, the critic QA's
+ * after. This split is what makes Claude Code reliable and applies the same
+ * shape here.
+ *
+ * Validation strategy: structured-output is enforced at the LLM layer; this
+ * class additionally re-validates against VideoPlanSchema and retries up to
+ * `maxRetries` times feeding the validation errors back as correction context.
+ */
+export interface PlannerOptions {
+    llm: LlmCaller;
+    router?: ModelRouter;
+    maxRetries?: number;
+}
+export declare class Planner {
+    private readonly opts;
+    private readonly router;
+    private readonly maxRetries;
+    constructor(opts: PlannerOptions);
+    plan(brief: VideoBrief, opts?: {
+        persona?: AgentPersona;
+        brandKit?: IBrandKitModel | null;
+        styleMemory?: IStyleMemoryModel | null;
+        bible?: AgentVisualBible | null;
+        /**
+         * Enable Anthropic server-side `web_search` for real-world grounding.
+         * `auto` (default) flips it on when the brief mentions real-world
+         * entities (specific products, companies, people, places, events,
+         * statistics) via {@link briefNeedsWebResearch}. Pass `true` to force,
+         * `false` to disable.
+         */
+        useWebResearch?: boolean | "auto";
+    }): Promise<VideoPlan>;
+    /**
+     * Streaming variant of `plan()`. Yields raw token chunks from the model so
+     * the host (SSE endpoint) can forward them to the drawer for token-by-token
+     * rendering, then resolves to the validated VideoPlan once the structured
+     * payload is complete. Falls back to a single-shot call (one chunk = full
+     * text) when the LLM caller doesn't implement `structuredStream`.
+     *
+     * Retries are NOT streamed: only the first attempt is exposed to the UI;
+     * if validation fails we re-call `plan()` (non-streaming) and emit the
+     * final retry as a single chunk. Streaming retries would confuse callers
+     * who already painted partial JSON for the first attempt.
+     */
+    planStream(brief: VideoBrief, opts?: {
+        persona?: AgentPersona;
+        brandKit?: IBrandKitModel | null;
+        styleMemory?: IStyleMemoryModel | null;
+        bible?: AgentVisualBible | null;
+    }): {
+        tokens: AsyncIterable<string>;
+        result: Promise<VideoPlan>;
+    };
+    /**
+     * Stage 6 slice 4 — focused overlay regeneration for a single scene. The
+     * full `plan()` path is too expensive (and too lossy) for "I just want
+     * different headline / CTA copy on scene 3": it would re-validate every
+     * structural rule (duration / pacing / model capability / VO budget /
+     * narration density) against the unchanged scenes, then re-emit the
+     * whole plan — burning planner tokens and risking drift on fields the
+     * caller didn't ask to change.
+     *
+     * Instead we run a small structured-output call that ONLY emits
+     * `{ overlays: TextOverlay[] }` for one scene, keeping the prompt tight
+     * (just the scene context + the overlay-content rules + a free-form
+     * `instruction`) and the validator surface tiny (TextOverlaySchema +
+     * the style-leak sanity check). Caller is responsible for splicing the
+     * returned overlays into projectJson — this method is pure, no I/O
+     * beyond the LLM call.
+     */
+    regenerateOverlaysForScene(scene: PlannedScene, brief: VideoBrief, opts?: {
+        persona?: AgentPersona;
+        brandKit?: IBrandKitModel | null;
+        bible?: AgentVisualBible | null;
+        isClosingScene?: boolean;
+        /** Free-form caller hint, e.g. "punchier CTA" or "drop the watermark". */
+        instruction?: string;
+    }): Promise<TextOverlay[]>;
+    private buildMessages;
+}
+/**
+ * Heuristic — does the brief mention real-world entities that benefit from
+ * web grounding? A planner without research will happily invent fake app
+ * names, fabricate statistics, and miss real-world brand details. Triggers
+ * when the brief contains:
+ *   - explicit "top N / best / popular / list of" framings
+ *   - proper-noun-heavy briefs (≥2 capitalized non-sentence-start words)
+ *   - listicle/comparison/news/review keywords
+ *   - explicit time markers ("2026", "latest", "this year", "recent")
+ *   - statistics signals ("statistics", "data", "percent", "study")
+ *
+ * Deliberately conservative — false negatives are fine (we just skip the
+ * search), false positives waste $0.01 per planner call. Override via
+ * `useWebResearch: true|false` when the caller knows better.
+ */
+export declare function briefNeedsWebResearch(brief: VideoBrief): boolean;
+//# sourceMappingURL=Planner.d.ts.map

package/lib/services/agent/planner/Planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Planner.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/planner/Planner.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,WAAW,EAEX,SAAS,EAEV,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChF,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAGzC,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAwB7C;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,SAAS,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,OAAO;IAIN,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAEP,IAAI,EAAE,cAAc;IAK3C,IAAI,CACR,KAAK,EAAE,UAAU,EACjB,IAAI,GAAE;QACJ,OAAO,CAAC,EAAE,YAAY,CAAC;QACvB,QAAQ,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;QACjC,WAAW,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;QACvC,KAAK,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;QAChC;;;;;;WAMG;QACH,cAAc,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;KAC9B,GACL,OAAO,CAAC,SAAS,CAAC;IAmOrB;;;;;;;;;;;OAWG;IACH,UAAU,CACR,KAAK,EAAE,UAAU,EACjB,IAAI,GAAE;QACJ,OAAO,CAAC,EAAE,YAAY,CAAC;QACvB,QAAQ,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;QACjC,WAAW,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;QACvC,KAAK,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;KAC5B,GACL;QAAE,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;QAAC,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,CAAA;KAAE;IAqDhE;;;;;;;;;;;;;;;;OAgBG;IACG,0BAA0B,CAC9B,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,UAAU,EACjB,IAAI,GAAE;QACJ,OAAO,CAAC,EAAE,YAAY,CAAC;QACvB,QAAQ,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;QACjC,KAAK,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;QAChC,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,0EAA0E;QAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;KACjB,GACL,OAAO,CAAC,WAAW,EAAE,CAAC;IA0IzB,OAAO,CAAC,aAAa;CAuItB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAiChE"}