@prestyj/editor 0.7.1

package/dist/core/viral-moments.js

@@ -0,0 +1,192 @@
+/**
+ * Long-form → multi-shorts orchestrator.
+ *
+ * The "1 hour podcast → 10 shorts" pipeline. Slides a window across a
+ * transcript, asks the LLM to nominate up to 3 candidate clips inside
+ * each window, then `score_clip`'s every nominee, dedups overlaps, and
+ * returns the top-N.
+ *
+ * Pure helpers + the LLM proposal step live here so the tool wrapper
+ * can stay thin. The ranking + dedup pass is plain TS — easy to unit
+ * test without the network.
+ */
+import { resolveApiKey } from "./auth/api-keys.js";
+/**
+ * Slice the transcript into overlapping windows. Each window covers
+ * `windowSec` seconds with `overlapSec` spillover into the next so a
+ * clip straddling a boundary can still be proposed by at least one
+ * window. The dedup step later collapses duplicates.
+ *
+ * Pure — exported for unit testing.
+ */
+export function buildSlidingWindows(t, windowSec, overlapSec) {
+    if (windowSec <= 0)
+        throw new Error("windowSec must be > 0");
+    if (overlapSec < 0 || overlapSec >= windowSec) {
+        throw new Error("overlapSec must be in [0, windowSec)");
+    }
+    const total = t.durationSec;
+    if (!Number.isFinite(total) || total <= 0)
+        return [];
+    const step = windowSec - overlapSec;
+    const out = [];
+    for (let s = 0; s < total; s += step) {
+        const e = Math.min(total, s + windowSec);
+        const text = collectText(t, s, e);
+        if (text)
+            out.push({ startSec: s, endSec: e, text });
+        if (e >= total)
+            break;
+    }
+    return out;
+}
+function collectText(t, startSec, endSec) {
+    const parts = [];
+    for (const seg of t.segments) {
+        if (seg.end <= startSec || seg.start >= endSec)
+            continue;
+        parts.push(seg.text.trim());
+    }
+    return parts.join(" ").trim();
+}
+/**
+ * Dedup overlapping candidates: when two candidates overlap > 50% (of
+ * the smaller), keep the higher-scoring one. Stable / sort-agnostic —
+ * the function sorts internally before walking.
+ *
+ * Pure — exported for testing.
+ */
+export function dedupCandidates(cands) {
+    // Sort by score desc; for each, drop subsequent ones that overlap > 50%.
+    const sorted = [...cands].sort((a, b) => b.score - a.score);
+    const kept = [];
+    for (const c of sorted) {
+        const conflict = kept.some((k) => overlapFraction(c, k) > 0.5);
+        if (!conflict)
+            kept.push(c);
+    }
+    return kept;
+}
+function overlapFraction(a, b) {
+    const lo = Math.max(a.startSec, b.startSec);
+    const hi = Math.min(a.endSec, b.endSec);
+    const overlap = Math.max(0, hi - lo);
+    if (overlap === 0)
+        return 0;
+    const minLen = Math.min(a.endSec - a.startSec, b.endSec - b.startSec);
+    if (minLen <= 0)
+        return 0;
+    return overlap / minLen;
+}
+/**
+ * Clamp candidate ranges to [0, totalSec] and to the requested duration
+ * range. Drops candidates that fall outside or are degenerate.
+ */
+export function normalizeCandidates(cands, totalSec, minSec, maxSec) {
+    const out = [];
+    for (const c of cands) {
+        const s = Math.max(0, Math.min(totalSec, c.startSec));
+        let e = Math.max(0, Math.min(totalSec, c.endSec));
+        if (e <= s)
+            continue;
+        const dur = e - s;
+        if (dur < minSec)
+            continue;
+        if (dur > maxSec)
+            e = s + maxSec;
+        out.push({ ...c, startSec: s, endSec: e });
+    }
+    return out;
+}
+// ── LLM proposal step ───────────────────────────────────────
+const PROPOSAL_SYSTEM = `You are a short-form-video selector. Find up to 3 distinct moments inside the given transcript window that would make great standalone Shorts / Reels / TikToks.
+
+Each candidate must satisfy:
+- duration is within the requested range (the user will tell you the seconds bounds)
+- hookLine = the FIRST SENTENCE of the clip (verbatim from transcript)
+- suggestedTitle ≤ 60 chars, hook-driven (a question, a claim, or a number)
+- suggestedCaption ≤ 220 chars, social-ready (hook + payoff tease, ≤2 hashtags)
+- why ≤ 140 chars, names what makes this moment work
+
+Return JSON: {"candidates":[{"startSec":number,"endSec":number,"hookLine":string,"suggestedTitle":string,"suggestedCaption":string,"why":string}, ...]}
+
+Return at most 3 candidates. If nothing in the window is strong enough, return {"candidates":[]}. Be ruthless — bad clips waste compute downstream.`;
+export async function proposeCandidates(window, opts) {
+    const apiKey = opts.apiKey ?? resolveApiKey("OPENAI_API_KEY", "openai");
+    if (!apiKey)
+        throw new Error("OPENAI_API_KEY required for find_viral_moments.");
+    const model = opts.model ?? "gpt-4o-mini";
+    const [minSec, maxSec] = opts.durationRange;
+    const userText = `Window: ${window.startSec.toFixed(2)}s → ${window.endSec.toFixed(2)}s.\n` +
+        `Duration range: ${minSec}s..${maxSec}s.\n\n` +
+        `TRANSCRIPT:\n${window.text}`;
+    const body = {
+        model,
+        messages: [
+            { role: "system", content: PROPOSAL_SYSTEM },
+            { role: "user", content: userText },
+        ],
+        response_format: { type: "json_object" },
+        temperature: 0,
+    };
+    const res = await fetch("https://api.openai.com/v1/chat/completions", {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+        signal: opts.signal,
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`OpenAI HTTP ${res.status}: ${text.slice(0, 200)}`);
+    }
+    const data = (await res.json());
+    const content = data.choices[0]?.message?.content ?? "";
+    return parseProposalResponse(content);
+}
+/**
+ * Tolerant parser. Drops malformed entries silently (we'd rather skip a
+ * bad candidate than blow up the whole window).
+ */
+export function parseProposalResponse(content) {
+    const start = content.indexOf("{");
+    const end = content.lastIndexOf("}");
+    if (start < 0 || end < start)
+        return [];
+    let obj;
+    try {
+        obj = JSON.parse(content.slice(start, end + 1));
+    }
+    catch {
+        return [];
+    }
+    if (typeof obj !== "object" || obj === null)
+        return [];
+    const cands = obj.candidates;
+    if (!Array.isArray(cands))
+        return [];
+    const out = [];
+    for (const c of cands) {
+        if (typeof c !== "object" || c === null)
+            continue;
+        const r = c;
+        const startSec = Number(r.startSec);
+        const endSec = Number(r.endSec);
+        if (!Number.isFinite(startSec) || !Number.isFinite(endSec))
+            continue;
+        if (endSec <= startSec)
+            continue;
+        out.push({
+            startSec,
+            endSec,
+            hookLine: String(r.hookLine ?? "").slice(0, 240),
+            suggestedTitle: String(r.suggestedTitle ?? "").slice(0, 80),
+            suggestedCaption: String(r.suggestedCaption ?? "").slice(0, 280),
+            why: String(r.why ?? "").slice(0, 200),
+        });
+    }
+    return out.slice(0, 3);
+}
+//# sourceMappingURL=viral-moments.js.map

package/dist/core/viral-moments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"viral-moments.js","sourceRoot":"","sources":["../../src/core/viral-moments.ts"],"names":[],"mappings":"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"}

package/dist/core/viral-moments.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=viral-moments.test.d.ts.map

package/dist/core/viral-moments.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viral-moments.test.d.ts","sourceRoot":"","sources":["../../src/core/viral-moments.test.ts"],"names":[],"mappings":""}

package/dist/core/viral-moments.test.js

@@ -0,0 +1,153 @@
+import { describe, expect, it } from "vitest";
+import { buildSlidingWindows, dedupCandidates, normalizeCandidates, parseProposalResponse, } from "./viral-moments.js";
+describe("buildSlidingWindows", () => {
+    it("emits non-overlapping windows when overlap=0", () => {
+        const t = {
+            language: "en",
+            durationSec: 100,
+            segments: [
+                { start: 0, end: 50, text: "first half" },
+                { start: 50, end: 100, text: "second half" },
+            ],
+        };
+        const windows = buildSlidingWindows(t, 50, 0);
+        expect(windows).toHaveLength(2);
+        expect(windows[0].startSec).toBe(0);
+        expect(windows[0].endSec).toBe(50);
+        expect(windows[1].startSec).toBe(50);
+    });
+    it("emits overlapping windows when overlap>0", () => {
+        const t = {
+            language: "en",
+            durationSec: 120,
+            segments: [{ start: 0, end: 120, text: "all" }],
+        };
+        const windows = buildSlidingWindows(t, 60, 30);
+        // step=30 → starts at 0, 30, 60, 90; last window clipped to 120
+        expect(windows.length).toBeGreaterThanOrEqual(3);
+    });
+    it("returns [] for zero-duration transcripts", () => {
+        expect(buildSlidingWindows({ language: "en", durationSec: 0, segments: [] }, 60, 0)).toEqual([]);
+    });
+    it("rejects invalid args", () => {
+        const t = { language: "en", durationSec: 100, segments: [] };
+        expect(() => buildSlidingWindows(t, 0, 0)).toThrow();
+        expect(() => buildSlidingWindows(t, 30, 30)).toThrow();
+        expect(() => buildSlidingWindows(t, 30, 40)).toThrow();
+    });
+});
+describe("dedupCandidates", () => {
+    const make = (startSec, endSec, score) => ({
+        startSec,
+        endSec,
+        durationSec: endSec - startSec,
+        score,
+        hook: 0,
+        flow: 0,
+        engagement: 0,
+        trend: 0,
+        hookLine: "",
+        suggestedTitle: "",
+        suggestedCaption: "",
+        why: "",
+    });
+    it("keeps the higher-scored of two heavy overlaps", () => {
+        const out = dedupCandidates([make(0, 30, 70), make(5, 32, 80)]);
+        expect(out).toHaveLength(1);
+        expect(out[0].score).toBe(80);
+    });
+    it("keeps non-overlapping candidates", () => {
+        const out = dedupCandidates([make(0, 30, 70), make(60, 90, 65)]);
+        expect(out).toHaveLength(2);
+    });
+    it("keeps both when overlap is <= 50%", () => {
+        // a: 0-30, b: 25-55, overlap=5, min length=30, fraction=5/30 ≈ 0.17 → keep both
+        const out = dedupCandidates([make(0, 30, 70), make(25, 55, 65)]);
+        expect(out).toHaveLength(2);
+    });
+    it("returns sorted desc by score", () => {
+        const out = dedupCandidates([make(0, 30, 70), make(60, 90, 90), make(120, 150, 50)]);
+        expect(out.map((c) => c.score)).toEqual([90, 70, 50]);
+    });
+});
+describe("normalizeCandidates", () => {
+    it("clamps to [0, total] and drops too-short", () => {
+        const out = normalizeCandidates([
+            {
+                startSec: -5,
+                endSec: 25,
+                hookLine: "",
+                suggestedTitle: "",
+                suggestedCaption: "",
+                why: "",
+            },
+            {
+                startSec: 50,
+                endSec: 51,
+                hookLine: "",
+                suggestedTitle: "",
+                suggestedCaption: "",
+                why: "",
+            },
+        ], 100, 20, 60);
+        expect(out).toHaveLength(1);
+        expect(out[0].startSec).toBe(0);
+        expect(out[0].endSec).toBe(25);
+    });
+    it("trims overlong clips to maxSec", () => {
+        const out = normalizeCandidates([
+            {
+                startSec: 10,
+                endSec: 200,
+                hookLine: "",
+                suggestedTitle: "",
+                suggestedCaption: "",
+                why: "",
+            },
+        ], 300, 20, 60);
+        expect(out[0].endSec).toBe(70);
+    });
+});
+describe("parseProposalResponse", () => {
+    it("parses well-formed proposals", () => {
+        const r = parseProposalResponse(JSON.stringify({
+            candidates: [
+                {
+                    startSec: 10,
+                    endSec: 40,
+                    hookLine: "let me tell you something",
+                    suggestedTitle: "Why X",
+                    suggestedCaption: "Watch this",
+                    why: "tight payoff",
+                },
+            ],
+        }));
+        expect(r).toHaveLength(1);
+        expect(r[0].startSec).toBe(10);
+        expect(r[0].suggestedTitle).toBe("Why X");
+    });
+    it("drops malformed entries silently", () => {
+        const r = parseProposalResponse(JSON.stringify({
+            candidates: [
+                { startSec: "bad", endSec: 30 },
+                { startSec: 10, endSec: 5 }, // end <= start
+                { startSec: 0, endSec: 10, hookLine: "ok" },
+            ],
+        }));
+        expect(r).toHaveLength(1);
+        expect(r[0].hookLine).toBe("ok");
+    });
+    it("returns [] on absent JSON", () => {
+        expect(parseProposalResponse("plain prose")).toEqual([]);
+    });
+    it("caps to 3 candidates", () => {
+        const r = parseProposalResponse(JSON.stringify({
+            candidates: Array.from({ length: 10 }, (_, i) => ({
+                startSec: i * 10,
+                endSec: i * 10 + 5,
+            })),
+        }));
+        expect(r).toHaveLength(3);
+    });
+});
+//# sourceMappingURL=viral-moments.test.js.map

package/dist/core/viral-moments.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"viral-moments.test.js","sourceRoot":"","sources":["../../src/core/viral-moments.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,oBAAoB,CAAC;AAE5B,QAAQ,CAAC,qBAAqB,EAAE,GAAG,EAAE;IACnC,EAAE,CAAC,8CAA8C,EAAE,GAAG,EAAE;QACtD,MAAM,CAAC,GAAG;YACR,QAAQ,EAAE,IAAI;YACd,WAAW,EAAE,GAAG;YAChB,QAAQ,EAAE;gBACR,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE;gBACzC,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,aAAa,EAAE;aAC7C;SACF,CAAC;QACF,MAAM,OAAO,GAAG,mBAAmB,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;QAC9C,MAAM,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QAChC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACpC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACnC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAClD,MAAM,CAAC,GAAG;YACR,QAAQ,EAAE,IAAI;YACd,WAAW,EAAE,GAAG;YAChB,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;SAChD,CAAC;QACF,MAAM,OAAO,GAAG,mBAAmB,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;QAC/C,gEAAgE;QAChE,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAClD,MAAM,CAAC,mBAAmB,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAC1F,EAAE,CACH,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sBAAsB,EAAE,GAAG,EAAE;QAC9B,MAAM,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;QAC7D,MAAM,CAAC,GAAG,EAAE,CAAC,mBAAmB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QACrD,MAAM,CAAC,GAAG,EAAE,CAAC,mBAAmB,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QACvD,MAAM,CAAC,GAAG,EAAE,CAAC,mBAAmB,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IACzD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,iBAAiB,EAAE,GAAG,EAAE;IAC/B,MAAM,IAAI,GAAG,CACX,QAAgB,EAChB,MAAc,EACd,KAAa,EACkC,EAAE,CAAC,CAAC;QACnD,QAAQ;QACR,MAAM;QACN,WAAW,EAAE,MAAM,GAAG,QAAQ;QAC9B,KAAK;QACL,IAAI,EAAE,CAAC;QACP,IAAI,EAAE,CAAC;QACP,UAAU,EAAE,CAAC;QACb,KAAK,EAAE,CAAC;QACR,QAAQ,EAAE,EAAE;QACZ,cAAc,EAAE,EAAE;QAClB,gBAAgB,EAAE,EAAE;QACpB,GAAG,EAAE,EAAE;KACR,CAAC,CAAC;IAEH,EAAE,CAAC,+CAA+C,EAAE,GAAG,EAAE;QACvD,MAAM,GAAG,GAAG,eAAe,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;QAChE,MAAM,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QAC5B,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kCAAkC,EAAE,GAAG,EAAE;QAC1C,MAAM,GAAG,GAAG,eAAe,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;QACjE,MAAM,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAC9B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mCAAmC,EAAE,GAAG,EAAE;QAC3C,gFAAgF;QAChF,MAAM,GAAG,GAAG,eAAe,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;QACjE,MAAM,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAC9B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8BAA8B,EAAE,GAAG,EAAE;QACtC,MAAM,GAAG,GAAG,eAAe,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;QACrF,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,qBAAqB,EAAE,GAAG,EAAE;IACnC,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAClD,MAAM,GAAG,GAAG,mBAAmB,CAC7B;YACE;gBACE,QAAQ,EAAE,CAAC,CAAC;gBACZ,MAAM,EAAE,EAAE;gBACV,QAAQ,EAAE,EAAE;gBACZ,cAAc,EAAE,EAAE;gBAClB,gBAAgB,EAAE,EAAE;gBACpB,GAAG,EAAE,EAAE;aACR;YACD;gBACE,QAAQ,EAAE,EAAE;gBACZ,MAAM,EAAE,EAAE;gBACV,QAAQ,EAAE,EAAE;gBACZ,cAAc,EAAE,EAAE;gBAClB,gBAAgB,EAAE,EAAE;gBACpB,GAAG,EAAE,EAAE;aACR;SACF,EACD,GAAG,EACH,EAAE,EACF,EAAE,CACH,CAAC;QACF,MAAM,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QAC5B,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAChC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gCAAgC,EAAE,GAAG,EAAE;QACxC,MAAM,GAAG,GAAG,mBAAmB,CAC7B;YACE;gBACE,QAAQ,EAAE,EAAE;gBACZ,MAAM,EAAE,GAAG;gBACX,QAAQ,EAAE,EAAE;gBACZ,cAAc,EAAE,EAAE;gBAClB,gBAAgB,EAAE,EAAE;gBACpB,GAAG,EAAE,EAAE;aACR;SACF,EACD,GAAG,EACH,EAAE,EACF,EAAE,CACH,CAAC;QACF,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,uBAAuB,EAAE,GAAG,EAAE;IACrC,EAAE,CAAC,8BAA8B,EAAE,GAAG,EAAE;QACtC,MAAM,CAAC,GAAG,qBAAqB,CAC7B,IAAI,CAAC,SAAS,CAAC;YACb,UAAU,EAAE;gBACV;oBACE,QAAQ,EAAE,EAAE;oBACZ,MAAM,EAAE,EAAE;oBACV,QAAQ,EAAE,2BAA2B;oBACrC,cAAc,EAAE,OAAO;oBACvB,gBAAgB,EAAE,YAAY;oBAC9B,GAAG,EAAE,cAAc;iBACpB;aACF;SACF,CAAC,CACH,CAAC;QACF,MAAM,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QAC1B,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC/B,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kCAAkC,EAAE,GAAG,EAAE;QAC1C,MAAM,CAAC,GAAG,qBAAqB,CAC7B,IAAI,CAAC,SAAS,CAAC;YACb,UAAU,EAAE;gBACV,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE;gBAC/B,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,eAAe;gBAC5C,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;aAC5C;SACF,CAAC,CACH,CAAC;QACF,MAAM,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QAC1B,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2BAA2B,EAAE,GAAG,EAAE;QACnC,MAAM,CAAC,qBAAqB,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC3D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sBAAsB,EAAE,GAAG,EAAE;QAC9B,MAAM,CAAC,GAAG,qBAAqB,CAC7B,IAAI,CAAC,SAAS,CAAC;YACb,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;gBAChD,QAAQ,EAAE,CAAC,GAAG,EAAE;gBAChB,MAAM,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC;aACnB,CAAC,CAAC;SACJ,CAAC,CACH,CAAC;QACF,MAAM,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAC5B,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/core/vision.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Vision shot scoring via OpenAI's chat completions API.
+ *
+ * Self-contained on purpose — ai is for streaming agent loops; this is a
+ * one-shot batch call. Keeps the dependency surface small and lets us tune
+ * the structured-output prompt independently.
+ *
+ * Why OpenAI: gpt-4o-mini is cost-effective (~$0.15/1M tokens) and follows
+ * strict JSON output reliably. Anthropic vision is comparable and could be
+ * added as an alternate backend later.
+ */
+export interface FrameToScore {
+    /** Path to a JPEG/PNG file on disk. */
+    path: string;
+    /** Time in seconds where this frame was sampled. */
+    atSec: number;
+}
+export interface ShotScore {
+    atSec: number;
+    /** 0-10. Higher = better composition / focus / subject clarity. */
+    score: number;
+    /** One-line reason. ≤ 80 chars. */
+    why: string;
+}
+export interface ScoreOptions {
+    apiKey?: string;
+    model?: string;
+    /** "low" = ~85 tokens/image (cheap), "high" = ~700 tokens/image (more accurate). */
+    detail?: "low" | "high";
+    /** Override the system prompt used to instruct the scorer. */
+    systemPrompt?: string;
+    signal?: AbortSignal;
+}
+/**
+ * Score a batch of frames. Splits into requests of ≤20 frames each (OpenAI
+ * vision practical limit). Returns ShotScore[] in the same order as input.
+ */
+export declare function scoreFrames(frames: FrameToScore[], opts?: ScoreOptions): Promise<ShotScore[]>;
+/**
+ * Parse the model's JSON response. Robust to:
+ *   - Array-of-objects: `[{score, why}, ...]`
+ *   - Object-wrapped:   `{"shots": [...]}` or `{"results": [...]}`
+ *   - Stray prose around the JSON (extracts first array)
+ */
+export declare function parseScoreResponse(content: string, expected: number): Array<{
+    score?: unknown;
+    why?: unknown;
+}>;
+/** Clamp a score value to the 0-10 grading scale. Exposed for testing. */
+export declare function clampScore(v: unknown): number;
+/** Truncate the rationale to 80 chars; non-strings collapse to "". Exposed for testing. */
+export declare function clampWhy(v: unknown): string;
+//# sourceMappingURL=vision.d.ts.map

package/dist/core/vision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision.d.ts","sourceRoot":"","sources":["../../src/core/vision.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACxB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAoBD;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,YAAY,EAAE,EACtB,IAAI,GAAE,YAAiB,GACtB,OAAO,CAAC,SAAS,EAAE,CAAC,CAsBtB;AAuED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,KAAK,CAAC;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,CAwB3C;AAUD,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAI7C;AAED,2FAA2F;AAC3F,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAG3C"}

package/dist/core/vision.js

@@ -0,0 +1,151 @@
+import { readFileSync } from "node:fs";
+import { resolveApiKey } from "./auth/api-keys.js";
+/**
+ * Default scoring rubric. Compact, structured, gives the model a clear
+ * grading scale and forbids chatty output.
+ */
+const DEFAULT_SYSTEM = `You are a video shot grader. For each frame, output a JSON object with:
+- score: 0-10 (composition + focus + subject clarity + visual energy combined)
+- why: ONE short reason (≤80 chars), specific (e.g. "subject centered, sharp eyes" not "looks good")
+
+Return ONLY a JSON array, one entry per frame in order. No prose.
+
+Grading scale:
+  9-10: hero frame — sharp, well-composed, strong subject, eye-catching
+  6-8:  usable — focused, clear subject, decent composition
+  4-5:  weak — soft focus, awkward framing, or low energy
+  0-3:  unusable — blurry, subject obscured, mid-blink, mid-word`;
+const MAX_FRAMES_PER_REQUEST = 20;
+/**
+ * Score a batch of frames. Splits into requests of ≤20 frames each (OpenAI
+ * vision practical limit). Returns ShotScore[] in the same order as input.
+ */
+export async function scoreFrames(frames, opts = {}) {
+    const apiKey = opts.apiKey ?? resolveApiKey("OPENAI_API_KEY", "openai");
+    if (!apiKey)
+        throw new Error("OPENAI_API_KEY required for vision scoring.");
+    if (frames.length === 0)
+        return [];
+    const model = opts.model ?? "gpt-4o-mini";
+    const detail = opts.detail ?? "low";
+    const system = opts.systemPrompt ?? DEFAULT_SYSTEM;
+    const results = [];
+    for (let i = 0; i < frames.length; i += MAX_FRAMES_PER_REQUEST) {
+        const batch = frames.slice(i, i + MAX_FRAMES_PER_REQUEST);
+        const batchResults = await scoreBatch(batch, {
+            apiKey,
+            model,
+            detail,
+            system,
+            signal: opts.signal,
+        });
+        results.push(...batchResults);
+    }
+    return results;
+}
+async function scoreBatch(frames, opts) {
+    const userContent = [
+        {
+            type: "text",
+            text: `Score these ${frames.length} frames in order. Return a JSON array of ` +
+                `${frames.length} entries, each {score, why}. Frame timestamps for context: ` +
+                frames.map((f, i) => `[${i}]=${f.atSec.toFixed(2)}s`).join(", "),
+        },
+    ];
+    for (const f of frames) {
+        const mime = f.path.toLowerCase().endsWith(".png") ? "image/png" : "image/jpeg";
+        const b64 = readFileSync(f.path).toString("base64");
+        userContent.push({
+            type: "image_url",
+            image_url: { url: `data:${mime};base64,${b64}`, detail: opts.detail },
+        });
+    }
+    const res = await fetch("https://api.openai.com/v1/chat/completions", {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${opts.apiKey}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+            model: opts.model,
+            messages: [
+                { role: "system", content: opts.system },
+                { role: "user", content: userContent },
+            ],
+            // Force JSON output. Some smaller models follow this strictly; 4o-mini does.
+            response_format: { type: "json_object" },
+            max_tokens: 2000,
+        }),
+        signal: opts.signal,
+    });
+    if (!res.ok) {
+        const errText = await res.text().catch(() => "");
+        throw new Error(`OpenAI vision HTTP ${res.status}: ${errText.slice(0, 300)}`);
+    }
+    const body = (await res.json());
+    const content = body.choices?.[0]?.message?.content ?? "";
+    const parsed = parseScoreResponse(content, frames.length);
+    return frames.map((f, i) => ({
+        atSec: f.atSec,
+        score: clampScore(parsed[i]?.score),
+        why: clampWhy(parsed[i]?.why),
+    }));
+}
+/**
+ * Parse the model's JSON response. Robust to:
+ *   - Array-of-objects: `[{score, why}, ...]`
+ *   - Object-wrapped:   `{"shots": [...]}` or `{"results": [...]}`
+ *   - Stray prose around the JSON (extracts first array)
+ */
+export function parseScoreResponse(content, expected) {
+    // Try direct parse first.
+    let arr;
+    try {
+        const obj = JSON.parse(content);
+        arr = Array.isArray(obj) ? obj : extractArray(obj);
+    }
+    catch {
+        // Fall back: regex-extract the first JSON array in the text.
+        const m = content.match(/\[[\s\S]*\]/);
+        if (m) {
+            try {
+                arr = JSON.parse(m[0]);
+            }
+            catch {
+                arr = [];
+            }
+        }
+        else {
+            arr = [];
+        }
+    }
+    if (!Array.isArray(arr))
+        arr = [];
+    // Pad / truncate to expected length so callers always get N entries.
+    const out = arr;
+    while (out.length < expected)
+        out.push({});
+    return out.slice(0, expected);
+}
+function extractArray(obj) {
+    if (typeof obj !== "object" || obj === null)
+        return [];
+    for (const v of Object.values(obj)) {
+        if (Array.isArray(v))
+            return v;
+    }
+    return [];
+}
+/** Clamp a score value to the 0-10 grading scale. Exposed for testing. */
+export function clampScore(v) {
+    const n = typeof v === "number" ? v : Number(v);
+    if (!Number.isFinite(n))
+        return 0;
+    return Math.max(0, Math.min(10, Math.round(n * 10) / 10));
+}
+/** Truncate the rationale to 80 chars; non-strings collapse to "". Exposed for testing. */
+export function clampWhy(v) {
+    const s = typeof v === "string" ? v : "";
+    return s.slice(0, 80);
+}
+//# sourceMappingURL=vision.js.map

package/dist/core/vision.js.map

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

package/dist/core/vision.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=vision.test.d.ts.map

package/dist/core/vision.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision.test.d.ts","sourceRoot":"","sources":["../../src/core/vision.test.ts"],"names":[],"mappings":""}