@officexapp/vidfarm-devcli 0.21.10

package/dist/src/services/clip-curation/local-agent.js

@@ -0,0 +1,248 @@
+// Local-agent model client — devcli-only. Runs scene tagging, prompt-guided
+// keep/drop/merge, and NL→criteria through the user's LOCAL agent CLI
+// subscription (claude or codex) instead of a provider API key, so `vidfarm
+// clips scan` works out of the box on a machine that has Claude Code or Codex
+// installed: local ffmpeg for compute, local agent for evaluation. Cloud is the
+// explicit backup (devcli `--cloud`), never the default. Embeddings cannot ride
+// on a CLI agent — pair with a gemini/openai key (embedding-only) or the
+// library stays structured-searchable, the same degraded mode as
+// openrouter-without-embed-key. NEVER constructed in Lambda.
+import { spawn } from "node:child_process";
+import { spawnSync } from "node:child_process";
+import { ACTIVE_TAXONOMY_VERSION, getTaxonomy, sanitizeTagValues } from "./taxonomy.js";
+import { buildQueryPrompt, buildTaggingPrompt, ClipEmbeddingClient } from "./gemini.js";
+/** Find a usable local agent CLI on PATH. Returns null when none is installed. */
+export function detectLocalAgent(preferred) {
+    const candidates = preferred === "claude" ? ["claude"]
+        : preferred === "codex" ? ["codex"]
+            : ["claude", "codex"];
+    for (const kind of candidates) {
+        const found = spawnSync("which", [kind], { encoding: "utf8" });
+        const bin = (found.stdout || "").trim();
+        if (found.status === 0 && bin)
+            return { kind, bin };
+    }
+    return null;
+}
+export class LocalAgentClipClient {
+    provider = "local-agent";
+    tier;
+    taxonomyVersion;
+    tagModelId;
+    embeddingProvider;
+    embeddingModelId;
+    kind;
+    bin;
+    embedder;
+    timeoutMs;
+    constructor(opts = {}) {
+        const detected = opts.bin
+            ? { kind: (opts.agent === "codex" ? "codex" : "claude"), bin: opts.bin }
+            : detectLocalAgent(opts.agent === "auto" ? undefined : opts.agent);
+        if (!detected) {
+            throw new Error("No local agent CLI found. Install Claude Code (`claude`) or Codex (`codex`), pass a provider key (--gemini-key / GEMINI_API_KEY), or run with --cloud.");
+        }
+        this.kind = detected.kind;
+        this.bin = detected.bin;
+        this.tagModelId = `${this.kind}-cli`;
+        this.tier = opts.tier ?? "flash-lite";
+        this.taxonomyVersion = opts.taxonomyVersion ?? ACTIVE_TAXONOMY_VERSION;
+        this.embedder = opts.embedding ? new ClipEmbeddingClient(opts.embedding) : null;
+        this.embeddingProvider = this.embedder ? this.embedder.provider : null;
+        this.embeddingModelId = this.embedder ? this.embedder.modelId : null;
+        this.timeoutMs = Math.max(30_000, opts.timeoutMs ?? 300_000);
+    }
+    get canEmbed() {
+        return this.embedder !== null;
+    }
+    /** Tag one scene: the agent Reads the keyframe files itself, then emits the tag JSON. */
+    async tagScene(input) {
+        // No audio path — CLI agents can't transcribe the mp3; transcript stays
+        // whatever the caller supplied (usually empty on local-agent scans).
+        const base = buildTaggingPrompt(input.transcript, this.taxonomyVersion, false, input.guidancePrompt);
+        const prompt = [
+            base,
+            "",
+            `The scene's keyframe image files are on disk — open and inspect EVERY one of these ${input.keyframePaths.length} file(s) before answering:`,
+            ...input.keyframePaths.map((p) => `- ${p}`),
+            "",
+            "Respond with ONLY the JSON object (no prose, no markdown fence) with keys:",
+            `content_type, subject, action, emotion, setting, composition, motion (string arrays), energy (string), audio_type (string array), transcript (string), description (string).`,
+            `content_type is the KIND of shot — pick 1-2 of: talking_head, b_roll, product_shot, screen_recording, demo, reaction, interview, establishing, lifestyle, text_graphic.`
+        ].join("\n");
+        try {
+            const raw = await this.runAgent(prompt);
+            const parsed = extractJsonObject(raw);
+            if (!parsed)
+                throw new Error("local agent returned no JSON");
+            const withDefaults = {
+                content_type: [], subject: [], action: [], emotion: [], setting: [], composition: [], motion: [],
+                energy: "medium", audio_type: [], transcript: "", description: "",
+                ...parsed
+            };
+            const sanitized = sanitizeTagValues(withDefaults, this.taxonomyVersion);
+            const tags = {
+                ...sanitized,
+                transcript: (input.transcript || String(withDefaults.transcript ?? "")).trim()
+            };
+            return { tags, description: String(withDefaults.description ?? "").trim() };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            // eslint-disable-next-line no-console
+            console.warn(`[clips] tag failed (local-agent/${this.kind}) @${input.scene.start_time_sec.toFixed(1)}s: ${message}`);
+            return {
+                tags: {
+                    content_type: [], subject: [], action: [], emotion: [], setting: [], composition: [], motion: [],
+                    energy: "medium",
+                    audio_type: input.transcript ? ["dialogue"] : ["silence"],
+                    transcript: input.transcript || ""
+                },
+                description: input.transcript ? input.transcript.slice(0, 120) : ""
+            };
+        }
+    }
+    /** Keep/drop/merge for prompt-guided segmentation via the local agent. */
+    async decideScenes(input) {
+        const prompt = [
+            input.prompt,
+            "",
+            `The candidate scenes' keyframe image files are on disk, in timeline order — open and inspect EVERY one of these ${input.imagePaths.length} file(s) before deciding:`,
+            ...input.imagePaths.map((p, i) => `- scene ${i}: ${p}`),
+            "",
+            `Respond with ONLY a JSON object (no prose, no markdown fence): {"decisions":[{"keep":true|false,"merge_with_previous":true|false}, …]} with exactly ${input.imagePaths.length} entries in scene order.`
+        ].join("\n");
+        try {
+            const raw = await this.runAgent(prompt);
+            const parsed = extractJsonObject(raw);
+            if (!parsed || !Array.isArray(parsed.decisions))
+                return null;
+            return parsed.decisions.map((d) => ({
+                keep: Boolean(d?.keep),
+                merge_with_previous: Boolean(d?.merge_with_previous)
+            }));
+        }
+        catch (error) {
+            if (process.env.VIDFARM_DEBUG_LOGS === "true") {
+                // eslint-disable-next-line no-console
+                console.warn(`[clips] local-agent refine failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            return null;
+        }
+    }
+    async embedDocuments(texts) {
+        return this.embedder ? this.embedder.embed(texts, "RETRIEVAL_DOCUMENT") : [];
+    }
+    async embedQuery(text) {
+        if (!this.embedder)
+            return undefined;
+        const [vec] = await this.embedder.embed([text], "RETRIEVAL_QUERY");
+        return vec;
+    }
+    async embedQueries(texts) {
+        return this.embedder ? this.embedder.embed(texts, "RETRIEVAL_QUERY") : [];
+    }
+    /** NL → structured criteria (text-only, so a clean fit for a CLI agent). */
+    async naturalLanguageToCriteria(query) {
+        const prompt = [
+            buildQueryPrompt(query, this.taxonomyVersion),
+            "",
+            "Respond with ONLY the JSON object (no prose, no markdown fence)."
+        ].join("\n");
+        try {
+            const raw = await this.runAgent(prompt);
+            const parsed = extractJsonObject(raw);
+            if (!parsed)
+                return { semantic_text: query };
+            return { ...sanitizeCriteria(parsed, this.taxonomyVersion), semantic_text: query };
+        }
+        catch {
+            return { semantic_text: query };
+        }
+    }
+    // ── CLI plumbing ──────────────────────────────────────────────────────────
+    runAgent(prompt) {
+        const args = this.kind === "claude"
+            ? [
+                "-p", prompt,
+                "--output-format", "text",
+                // Reading N keyframes = N tool turns; leave headroom.
+                "--max-turns", "50",
+                "--allowedTools", "Read",
+                ...(process.env.VIDFARM_LOCAL_AGENT_MODEL ? ["--model", process.env.VIDFARM_LOCAL_AGENT_MODEL] : [])
+            ]
+            : [
+                "exec",
+                "--skip-git-repo-check",
+                ...(process.env.VIDFARM_LOCAL_AGENT_MODEL ? ["--model", process.env.VIDFARM_LOCAL_AGENT_MODEL] : []),
+                prompt
+            ];
+        return new Promise((resolve, reject) => {
+            const child = spawn(this.bin, args, { stdio: ["ignore", "pipe", "pipe"] });
+            let stdout = "";
+            let stderr = "";
+            const timer = setTimeout(() => {
+                child.kill("SIGKILL");
+                reject(new Error(`${this.kind} CLI timed out after ${Math.round(this.timeoutMs / 1000)}s`));
+            }, this.timeoutMs);
+            timer.unref?.();
+            child.stdout.on("data", (d) => (stdout += d.toString()));
+            child.stderr.on("data", (d) => (stderr += d.toString()));
+            child.on("error", (error) => {
+                clearTimeout(timer);
+                reject(error);
+            });
+            child.on("close", (code) => {
+                clearTimeout(timer);
+                if (code === 0)
+                    resolve(stdout);
+                else
+                    reject(new Error(`${this.kind} CLI exited ${code}: ${(stderr || stdout).slice(0, 400)}`));
+            });
+        });
+    }
+}
+/** Pull the first parseable JSON object out of agent output (fenced block, or outermost braces). */
+export function extractJsonObject(text) {
+    const trimmed = (text ?? "").trim();
+    if (!trimmed)
+        return null;
+    const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(trimmed);
+    for (const candidate of [fenced?.[1], trimmed]) {
+        if (!candidate)
+            continue;
+        const start = candidate.indexOf("{");
+        const end = candidate.lastIndexOf("}");
+        if (start < 0 || end <= start)
+            continue;
+        try {
+            return JSON.parse(candidate.slice(start, end + 1));
+        }
+        catch {
+            /* try the next candidate */
+        }
+    }
+    return null;
+}
+/** Constrain agent-produced criteria to the controlled vocabulary + known fields. */
+function sanitizeCriteria(raw, version) {
+    const cats = getTaxonomy(version).categories;
+    const out = {};
+    const arrayFields = ["subject", "action", "emotion", "setting", "composition", "motion", "audio_type", "energy"];
+    for (const field of arrayFields) {
+        const allowed = new Set(cats[field] ?? []);
+        const values = Array.isArray(raw[field]) ? raw[field].map(String).filter((v) => allowed.has(v)) : [];
+        if (values.length)
+            out[field] = values;
+    }
+    if (Number.isFinite(Number(raw.min_duration_sec)))
+        out.min_duration_sec = Number(raw.min_duration_sec);
+    if (Number.isFinite(Number(raw.max_duration_sec)))
+        out.max_duration_sec = Number(raw.max_duration_sec);
+    if (typeof raw.has_dialogue === "boolean")
+        out.has_dialogue = raw.has_dialogue;
+    if (typeof raw.has_subject === "boolean")
+        out.has_subject = raw.has_subject;
+    return out;
+}
+//# sourceMappingURL=local-agent.js.map

package/dist/src/services/clip-curation/media-select.js

@@ -0,0 +1,152 @@
+// Resolution-aware media selection for the RapidAPI social-video downloader.
+// The lookup returns several renditions per source (e.g. 360p / 720p / 1080p,
+// sometimes audio-only or HLS playlists). The clip library's quality is capped
+// by whatever source we ingest, so we must pick the HIGHEST-resolution playable
+// MP4 — not just the first one. Shared by the clip-scan Lambda (infra/lambda)
+// and the in-process serve/import path (src/app.ts) so both stay in lock-step.
+/** True when a candidate is a directly-downloadable MP4 (not HLS/DASH/audio). */
+function isPlayableMp4(m) {
+    if (!m.url)
+        return false;
+    if (m.videoAvailable === false)
+        return false;
+    if (m.type && !/video/i.test(m.type))
+        return false;
+    // HLS/DASH playlists can't be fetched as a single file — skip them.
+    if (/\.(m3u8|mpd)(\?|$)/i.test(m.url))
+        return false;
+    const ext = (m.extension ?? "").toLowerCase();
+    return ext === "mp4" || /\.mp4(\?|$)/i.test(m.url);
+}
+/** Any playable video (mp4 preferred, but a non-HLS fallback still beats nothing). */
+function isPlayableVideo(m) {
+    if (!m.url)
+        return false;
+    if (m.videoAvailable === false)
+        return false;
+    if (m.type && !/video/i.test(m.type))
+        return false;
+    if (/\.(m3u8|mpd)(\?|$)/i.test(m.url))
+        return false;
+    // Skip audio-only renditions (some resolvers list mp3/m4a alongside the video).
+    const ext = (m.extension ?? "").toLowerCase();
+    if (/^(mp3|m4a|aac|wav|ogg|opus)$/.test(ext) || /\.(mp3|m4a|aac|wav|ogg|opus)(\?|$)/i.test(m.url))
+        return false;
+    if (m.audioAvailable === true && m.videoAvailable !== true && !ext) {
+        // audio flagged, video not flagged, and no extension to prove otherwise
+        return false;
+    }
+    return true;
+}
+/**
+ * Estimate a rendition's vertical resolution (used as the ranking key). Reads an
+ * explicit height first, then parses the quality/label string. Returns 0 when
+ * nothing is parseable so labelled renditions always outrank unknown ones.
+ */
+export function estimateMediaHeight(m) {
+    const h = Number(m.height);
+    if (Number.isFinite(h) && h > 0)
+        return h;
+    const w = Number(m.width);
+    // Assume ~16:9 when only width is known (a coarse but monotonic proxy).
+    if (Number.isFinite(w) && w > 0)
+        return Math.round((w * 9) / 16);
+    const label = `${m.quality ?? ""} ${m.label ?? ""}`.toLowerCase();
+    // "1080p", "720 p", "2160p60", "1440P" → the leading pixel-height number.
+    const pMatch = label.match(/(\d{3,4})\s*p/);
+    if (pMatch)
+        return Number(pMatch[1]);
+    // "4k"/"2k" shorthand.
+    if (/\b4k|uhd\b/.test(label))
+        return 2160;
+    if (/\b2k\b/.test(label))
+        return 1440;
+    // Named tiers.
+    if (/full\s*hd|fhd/.test(label))
+        return 1080;
+    if (/\bhd\b/.test(label))
+        return 720;
+    if (/\bsd\b|low|small/.test(label))
+        return 360;
+    // A bare number (some providers give just "1080" / "720").
+    const nMatch = label.match(/\b(\d{3,4})\b/);
+    if (nMatch)
+        return Number(nMatch[1]);
+    return 0;
+}
+/**
+ * Rank every playable rendition best-first: highest-resolution MP4s, then any
+ * non-MP4 playable video as a fallback tier. Ranking is stable so ties keep the
+ * provider's own ordering (usually its preferred rendition first). This is the
+ * candidate order the download fallback walks — pickBestVideoMedia is just its
+ * head.
+ */
+export function rankPlayableVideoMedias(medias) {
+    const list = Array.isArray(medias) ? medias : [];
+    const rankByHeight = (pool) => pool
+        // Decorate-sort-undecorate to keep it a stable sort by descending height.
+        .map((m, index) => ({ m, index, h: estimateMediaHeight(m) }))
+        .sort((a, b) => b.h - a.h || a.index - b.index)
+        .map((entry) => entry.m);
+    const mp4s = rankByHeight(list.filter(isPlayableMp4));
+    const others = rankByHeight(list.filter((m) => !isPlayableMp4(m) && isPlayableVideo(m)));
+    return [...mp4s, ...others];
+}
+/**
+ * Pick the best rendition to ingest: the highest-resolution playable MP4, with a
+ * non-MP4 playable video as a last resort, else null.
+ */
+export function pickBestVideoMedia(medias) {
+    return rankPlayableVideoMedias(medias)[0] ?? null;
+}
+// A browser-ish UA + Accept: the RapidAPI-hosted copies (snapvideo.co) can reject
+// bare programmatic fetches, and the top-res server-side "merge" rendition
+// transiently 403s while the merge runs or when rate-limited.
+const MEDIA_DOWNLOAD_UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36";
+const RETRYABLE_DOWNLOAD_STATUS = new Set([403, 408, 425, 429, 500, 502, 503, 504]);
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Download the first playable rendition that actually responds, walking the
+ * ranked candidates highest-res first. The RapidAPI resolver returns SEVERAL
+ * copies it hosts itself (e.g. a progressive 360p plus server-side-merged
+ * 720p/1080p); the merge renditions can transiently 403 while merging or when
+ * rate-limited, so we retry a rendition once and then fall back to the next copy
+ * rather than hard-failing the whole ingest. Returns the live Response (caller
+ * streams `response.body` to disk/S3) plus the winning candidate. Throws only if
+ * EVERY rendition is unreachable, with each failure in the message.
+ */
+export async function fetchFirstDownloadableMedia(medias) {
+    const ranked = rankPlayableVideoMedias(medias);
+    if (!ranked.length) {
+        throw new Error("Video download lookup returned no playable MP4 media URL.");
+    }
+    const failures = [];
+    for (const media of ranked) {
+        const url = media.url;
+        if (!url)
+            continue;
+        const label = media.quality ?? media.label ?? "?";
+        for (let attempt = 0; attempt < 2; attempt++) {
+            if (attempt > 0)
+                await delay(750);
+            try {
+                const response = await fetch(url, { headers: { "user-agent": MEDIA_DOWNLOAD_UA, accept: "*/*" } });
+                if (response.ok && response.body) {
+                    return { response, media };
+                }
+                failures.push(`${label}:HTTP ${response.status}`);
+                await response.body?.cancel?.().catch(() => { });
+                // A non-transient status won't fix itself on retry — move to the next copy.
+                if (!RETRYABLE_DOWNLOAD_STATUS.has(response.status))
+                    break;
+            }
+            catch (error) {
+                failures.push(`${label}:${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    throw new Error(`Source video download failed; all ${ranked.length} rendition(s) unavailable (${failures.join("; ")}).`);
+}
+//# sourceMappingURL=media-select.js.map

package/dist/src/services/clip-curation/presets.js

@@ -0,0 +1,20 @@
+// Starter preset criteria library. Presets are just saved SplicingCriteria
+// (see types.ts). The shipped ones are `builtin: true`; users save their own
+// with `builtin: false` (persisted per-store in devcli/cloud).
+import presetsV1 from "./presets.v1.json" with { type: "json" };
+const SEED = presetsV1;
+/** The shipped built-in presets. Frozen so callers can't mutate the shared array. */
+export const BUILTIN_PRESETS = SEED.presets.map((p) => ({
+    preset_id: p.preset_id,
+    name: p.name,
+    description: p.description,
+    criteria: p.criteria,
+    builtin: true,
+    created_at: "1970-01-01T00:00:00.000Z"
+}));
+/** Look up a built-in preset by its id or (case-insensitive) name. */
+export function findBuiltinPreset(nameOrId) {
+    const needle = nameOrId.trim().toLowerCase();
+    return BUILTIN_PRESETS.find((p) => p.preset_id.toLowerCase() === needle || p.name.toLowerCase() === needle);
+}
+//# sourceMappingURL=presets.js.map

package/dist/src/services/clip-curation/presets.v1.json

@@ -0,0 +1,59 @@
+{
+    "version": "v1",
+    "presets": [
+        {
+            "preset_id": "preset_funny_reactions",
+            "name": "funny reaction gifs",
+            "description": "Short single-subject reactions facing the camera — the raw material for reaction cutaways.",
+            "criteria": {
+                "emotion": ["surprised", "amused", "deadpan", "exasperated"],
+                "subject": ["person", "single_speaker"],
+                "composition": ["close_up", "medium_shot", "centered"],
+                "max_duration_sec": 2.5,
+                "has_subject": true,
+                "semantic_text": "funny reaction, person reacting to the camera"
+            }
+        },
+        {
+            "preset_id": "preset_broll_transitions",
+            "name": "b-roll transitions",
+            "description": "Quiet low-motion cutaways with no talking — good glue between beats.",
+            "criteria": {
+                "motion": ["static", "low"],
+                "max_duration_sec": 1.5,
+                "has_dialogue": false,
+                "semantic_text": "short b-roll transition, no dialogue"
+            }
+        },
+        {
+            "preset_id": "preset_establishing_shots",
+            "name": "establishing shots",
+            "description": "Wide scene-setters with no clear subject.",
+            "criteria": {
+                "composition": ["wide_shot"],
+                "has_subject": false,
+                "semantic_text": "wide establishing shot of a location"
+            }
+        },
+        {
+            "preset_id": "preset_typing_hands",
+            "name": "typing hands",
+            "description": "Close-ups of hands on a keyboard — classic productivity b-roll.",
+            "criteria": {
+                "action": ["typing", "hands_on_keyboard"],
+                "composition": ["close_up"],
+                "semantic_text": "close up of hands typing on a keyboard"
+            }
+        },
+        {
+            "preset_id": "preset_money_shots",
+            "name": "money shots",
+            "description": "High-energy hero shots — the payoff frames.",
+            "criteria": {
+                "composition": ["close_up", "medium_shot"],
+                "energy": ["high"],
+                "semantic_text": "high energy hero product money shot"
+            }
+        }
+    ]
+}

package/dist/src/services/clip-curation/query.js

@@ -0,0 +1,167 @@
+// Structured filter + hybrid semantic re-rank. Same logic on devcli and cloud
+// so a preset or NL query returns the same clips regardless of target.
+//
+// Search flow (handoff): structured filter FIRST (cheap, exact), then semantic
+// re-rank the survivors by embedding similarity. If the structured filter
+// matches nothing but the query carries semantic intent, we relax to a
+// semantic-only pass so natural-language queries still return their best guess.
+const DIALOGUE_AUDIO = new Set(["dialogue", "voiceover"]);
+/** How many categorical facets `criteria` constrains (used for the match-ratio soft score). */
+function constraintCount(criteria) {
+    let n = 0;
+    for (const key of ["content_type", "subject", "action", "emotion", "setting", "composition", "motion", "audio_type", "energy"]) {
+        if (Array.isArray(criteria[key]) && criteria[key].length)
+            n++;
+    }
+    if (criteria.min_duration_sec != null || criteria.max_duration_sec != null)
+        n++;
+    if (criteria.has_dialogue != null)
+        n++;
+    if (criteria.has_subject != null)
+        n++;
+    return n;
+}
+function hasSubject(tags) {
+    return tags.subject.length > 0 && !(tags.subject.length === 1 && tags.subject[0] === "no_subject");
+}
+function hasDialogue(tags) {
+    return tags.audio_type.some((a) => DIALOGUE_AUDIO.has(a)) || Boolean(tags.transcript.trim());
+}
+/** Hard structured filter: does this clip satisfy every constraint in `criteria`? */
+export function matchesCriteria(clip, criteria) {
+    const t = clip.tags;
+    const anyOf = (have, want) => !want || want.length === 0 || want.some((w) => have.includes(w));
+    if (!anyOf(t.content_type ?? [], criteria.content_type))
+        return false;
+    if (!anyOf(t.subject, criteria.subject))
+        return false;
+    if (!anyOf(t.action, criteria.action))
+        return false;
+    if (!anyOf(t.emotion, criteria.emotion))
+        return false;
+    if (!anyOf(t.setting, criteria.setting))
+        return false;
+    if (!anyOf(t.composition, criteria.composition))
+        return false;
+    if (!anyOf(t.motion, criteria.motion))
+        return false;
+    if (!anyOf(t.audio_type, criteria.audio_type))
+        return false;
+    if (criteria.energy && criteria.energy.length && !criteria.energy.includes(t.energy))
+        return false;
+    if (criteria.min_duration_sec != null && clip.duration_sec < criteria.min_duration_sec)
+        return false;
+    if (criteria.max_duration_sec != null && clip.duration_sec > criteria.max_duration_sec)
+        return false;
+    if (criteria.has_dialogue === true && !hasDialogue(t))
+        return false;
+    if (criteria.has_dialogue === false && hasDialogue(t))
+        return false;
+    if (criteria.has_subject === true && !hasSubject(t))
+        return false;
+    if (criteria.has_subject === false && hasSubject(t))
+        return false;
+    return true;
+}
+/** Fraction of constrained facets this clip satisfies (0..1); 1 when there are no constraints. */
+export function structuredMatchRatio(clip, criteria) {
+    const total = constraintCount(criteria);
+    if (total === 0)
+        return 1;
+    const t = clip.tags;
+    let hit = 0;
+    const anyOf = (have, want) => Boolean(want && want.length && want.some((w) => have.includes(w)));
+    if (anyOf(t.content_type ?? [], criteria.content_type))
+        hit++;
+    if (anyOf(t.subject, criteria.subject))
+        hit++;
+    if (anyOf(t.action, criteria.action))
+        hit++;
+    if (anyOf(t.emotion, criteria.emotion))
+        hit++;
+    if (anyOf(t.setting, criteria.setting))
+        hit++;
+    if (anyOf(t.composition, criteria.composition))
+        hit++;
+    if (anyOf(t.motion, criteria.motion))
+        hit++;
+    if (anyOf(t.audio_type, criteria.audio_type))
+        hit++;
+    if (criteria.energy && criteria.energy.length && criteria.energy.includes(t.energy))
+        hit++;
+    if ((criteria.min_duration_sec != null || criteria.max_duration_sec != null) &&
+        (criteria.min_duration_sec == null || clip.duration_sec >= criteria.min_duration_sec) &&
+        (criteria.max_duration_sec == null || clip.duration_sec <= criteria.max_duration_sec))
+        hit++;
+    if (criteria.has_dialogue != null && hasDialogue(t) === criteria.has_dialogue)
+        hit++;
+    if (criteria.has_subject != null && hasSubject(t) === criteria.has_subject)
+        hit++;
+    return hit / total;
+}
+/** Cosine similarity of two vectors (safe on unnormalized input). */
+export function cosineSimilarity(a, b) {
+    if (!a || !b || a.length === 0 || a.length !== b.length)
+        return 0;
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+/**
+ * Run the two-stage search over an in-memory clip set. Cloud can push the
+ * structured part into DynamoDB and the semantic part into a vector index; this
+ * pure function is the reference implementation devcli uses directly.
+ */
+export function searchClips(clips, opts) {
+    const { criteria, queryEmbedding } = opts;
+    const limit = opts.limit ?? 20;
+    const relax = opts.relaxWhenEmpty ?? true;
+    let candidates = clips.filter((c) => matchesCriteria(c, criteria));
+    let relaxed = false;
+    if (candidates.length === 0 && relax && (queryEmbedding || criteria.semantic_text)) {
+        candidates = clips.slice();
+        relaxed = true;
+    }
+    const hits = candidates.map((clip) => scoreClip(clip, criteria, queryEmbedding, relaxed));
+    return rankHits(hits, limit);
+}
+/**
+ * Score a single clip against a query. `relaxed` = the structured filter was
+ * bypassed (semantic-only pass), so factor in how well it still matches the
+ * criteria; when not relaxed the clip already passed the hard filter (ratio 1).
+ * Exported so the devcli SQLite store can reuse the exact scoring after doing
+ * the structured filter / KNN prefilter in SQL.
+ */
+export function scoreClip(clip, criteria, queryEmbedding, relaxed) {
+    const similarity = queryEmbedding ? cosineSimilarity(clip.embedding, queryEmbedding) : undefined;
+    const ratio = relaxed ? structuredMatchRatio(clip, criteria) : 1;
+    let score;
+    if (similarity != null) {
+        // Blend: mostly semantic, with a structured-match boost. Normalize cosine
+        // (-1..1) into 0..1 so scores read sensibly.
+        const sim01 = (similarity + 1) / 2;
+        score = 0.8 * sim01 + 0.2 * ratio;
+    }
+    else {
+        score = ratio;
+    }
+    return { clip, score, similarity };
+}
+/** Sort hits by score (newer clips break ties) and take the top `limit`. */
+export function rankHits(hits, limit) {
+    hits.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        return (b.clip.created_at || "").localeCompare(a.clip.created_at || "");
+    });
+    return hits.slice(0, limit);
+}
+//# sourceMappingURL=query.js.map