@mevdragon/vidfarm-devcli 0.7.0 → 0.8.0

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

@@ -0,0 +1,342 @@
+// Model client shared by devcli + cloud. Multi-provider: the TAGGING model
+// (vision + optional audio ASR) is swappable across gemini / openai / openrouter
+// so users pick their cost/quality tradeoff; EMBEDDINGS ride on a resolvable
+// embedding provider (gemini or openai — OpenRouter has no /embeddings) so a
+// library stays in ONE vector space. BYOK: the caller passes provider keys.
+//
+// One place for the prompt templates so every provider produces byte-identical
+// clip metadata (same taxonomy, same schema).
+import { readFile } from "node:fs/promises";
+import { embedMany, generateObject } from "ai";
+import { createGoogleGenerativeAI } from "@ai-sdk/google";
+import { createOpenAI } from "@ai-sdk/openai";
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import { z } from "zod";
+import { ACTIVE_TAXONOMY_VERSION, getTaxonomy, sanitizeTagValues, taxonomyForPrompt } from "./taxonomy.js";
+// Tag model per provider/tier. Overridable via env so pinned models can move
+// forward without a code change. Handoff: gemini flash-lite (cheap, low media_resolution).
+function resolveTagModel(provider, tier) {
+    switch (provider) {
+        case "openai":
+            return process.env.VIDFARM_CLIP_TAG_MODEL_OPENAI ?? "gpt-5.4-nano";
+        case "openrouter":
+            return process.env.VIDFARM_CLIP_TAG_MODEL_OPENROUTER ?? "google/gemini-2.5-flash";
+        case "gemini":
+        default:
+            return tier === "flash"
+                ? process.env.VIDFARM_CLIP_TAG_MODEL_FLASH ?? "gemini-2.5-flash"
+                : process.env.VIDFARM_CLIP_TAG_MODEL_LITE ?? "gemini-2.5-flash-lite";
+    }
+}
+export const EMBEDDING_MODELS = {
+    gemini: process.env.VIDFARM_CLIP_EMBEDDING_MODEL ?? "gemini-embedding-001",
+    openai: process.env.VIDFARM_CLIP_EMBEDDING_MODEL_OPENAI ?? "text-embedding-3-small"
+};
+// gemini-embedding-001 and text-embedding-3-small both support reducing to 768
+// dims, so every provider's vectors fit the same fixed-width index. Cosine is
+// dimension-agnostic; still, vectors from DIFFERENT models are NOT comparable —
+// a library should stay on one embedding model (callers store embedding_model
+// and warn on mismatch).
+export const EMBEDDING_DIM = Number(process.env.VIDFARM_CLIP_EMBEDDING_DIM ?? 768);
+export class ClipModelClient {
+    provider;
+    tier;
+    taxonomyVersion;
+    tagModelId;
+    embeddingProvider;
+    embeddingModelId;
+    tagModel;
+    embedModel;
+    constructor(opts) {
+        if (!opts.apiKey)
+            throw new Error(`A ${opts.provider ?? "gemini"} API key is required.`);
+        this.provider = opts.provider ?? "gemini";
+        this.tier = opts.tier ?? "flash-lite";
+        this.taxonomyVersion = opts.taxonomyVersion ?? ACTIVE_TAXONOMY_VERSION;
+        this.tagModelId = resolveTagModel(this.provider, this.tier);
+        this.tagModel = buildLanguageModel(this.provider, opts.apiKey, this.tagModelId, opts.publicBaseUrl);
+        const embedding = resolveEmbeddingConfig(this.provider, opts.apiKey, opts.embedding);
+        if (embedding) {
+            this.embeddingProvider = embedding.provider;
+            this.embeddingModelId = EMBEDDING_MODELS[embedding.provider];
+            this.embedModel = buildEmbeddingModel(embedding.provider, embedding.apiKey, this.embeddingModelId);
+        }
+        else {
+            this.embeddingProvider = null;
+            this.embeddingModelId = null;
+            this.embedModel = null;
+        }
+    }
+    /** True when this client can produce embeddings (semantic search available). */
+    get canEmbed() {
+        return this.embedModel !== null;
+    }
+    /** The underlying tagging LanguageModel — used by the guided-segmentation pass. */
+    get taggingModel() {
+        return this.tagModel;
+    }
+    tagSchema() {
+        const cats = getTaxonomy(this.taxonomyVersion).categories;
+        const enumArray = (values) => z.array(z.enum(values)).default([]);
+        return z.object({
+            subject: enumArray(cats.subject),
+            action: enumArray(cats.action),
+            emotion: enumArray(cats.emotion),
+            setting: enumArray(cats.setting),
+            composition: enumArray(cats.composition),
+            motion: enumArray(cats.motion),
+            energy: z.enum(cats.energy),
+            audio_type: enumArray(cats.audio_type),
+            transcript: z.string().default(""),
+            description: z.string()
+        });
+    }
+    /**
+     * Tag one scene from its keyframes (+ audio on Gemini, which transcribes in
+     * the same call). OpenAI/OpenRouter get frames only — their chat models don't
+     * take raw audio, so transcript stays empty unless supplied. Degrades to an
+     * empty-but-valid tag set on error so one bad scene never kills a scan.
+     */
+    async tagScene(input) {
+        const supportsAudio = this.provider === "gemini";
+        const hasAudio = supportsAudio && Boolean(input.audioPath);
+        const prompt = buildTaggingPrompt(input.transcript, this.taxonomyVersion, hasAudio, input.guidancePrompt);
+        const images = await Promise.all(input.keyframePaths.map((p) => readFile(p)));
+        const audio = hasAudio && input.audioPath ? await readFile(input.audioPath).catch(() => null) : null;
+        try {
+            const { object } = await generateObject({
+                model: this.tagModel,
+                schema: this.tagSchema(),
+                maxOutputTokens: this.provider === "openai" ? 1500 : 500,
+                providerOptions: this.taggingProviderOptions(),
+                messages: [
+                    {
+                        role: "user",
+                        content: [
+                            { type: "text", text: prompt },
+                            ...images.map((image) => this.imagePart(image)),
+                            ...(audio ? [{ type: "file", data: audio, mediaType: "audio/mpeg" }] : [])
+                        ]
+                    }
+                ]
+            });
+            const sanitized = sanitizeTagValues(object, this.taxonomyVersion);
+            const tags = {
+                ...sanitized,
+                transcript: (input.transcript || object.transcript || "").trim()
+            };
+            return { tags, description: String(object.description ?? "").trim() };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            // eslint-disable-next-line no-console
+            console.warn(`[clips] tag failed (${this.provider}) @${input.scene.start_time_sec.toFixed(1)}s: ${message}`);
+            return {
+                tags: {
+                    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) : ""
+            };
+        }
+    }
+    taggingProviderOptions() {
+        if (this.provider === "gemini") {
+            return { google: { mediaResolution: "MEDIA_RESOLUTION_LOW", structuredOutputs: true } };
+        }
+        return undefined;
+    }
+    imagePart(image) {
+        // Low image detail on OpenAI keeps the token cost near the Gemini low-res target.
+        if (this.provider === "openai") {
+            return { type: "image", image, providerOptions: { openai: { imageDetail: "low" } } };
+        }
+        return { type: "image", image };
+    }
+    async embedDocuments(texts) {
+        return this.embed(texts, "RETRIEVAL_DOCUMENT");
+    }
+    async embedQuery(text) {
+        const [vec] = await this.embed([text], "RETRIEVAL_QUERY");
+        return vec;
+    }
+    /** Batch-embed many retrieval queries (e.g. one per scene annotation) in a single call. */
+    async embedQueries(texts) {
+        return this.embed(texts, "RETRIEVAL_QUERY");
+    }
+    async embed(texts, taskType) {
+        if (texts.length === 0 || !this.embedModel)
+            return [];
+        const providerOptions = this.embeddingProvider === "gemini"
+            ? { google: { taskType, outputDimensionality: EMBEDDING_DIM } }
+            : { openai: { dimensions: EMBEDDING_DIM } };
+        const { embeddings } = await embedMany({
+            model: this.embedModel,
+            values: texts.map((t) => (t.trim() ? t.trim() : " ")),
+            providerOptions
+        });
+        return embeddings.map((e) => normalize(e));
+    }
+    /** Convert a natural-language query into a structured SplicingCriteria (categoricals constrained to the taxonomy). */
+    async naturalLanguageToCriteria(query) {
+        const cats = getTaxonomy(this.taxonomyVersion).categories;
+        const opt = (values) => z.array(z.enum(values)).optional();
+        const schema = z.object({
+            subject: opt(cats.subject),
+            action: opt(cats.action),
+            emotion: opt(cats.emotion),
+            setting: opt(cats.setting),
+            composition: opt(cats.composition),
+            motion: opt(cats.motion),
+            audio_type: opt(cats.audio_type),
+            energy: z.array(z.enum(cats.energy)).optional(),
+            min_duration_sec: z.number().optional(),
+            max_duration_sec: z.number().optional(),
+            has_dialogue: z.boolean().optional(),
+            has_subject: z.boolean().optional()
+        });
+        try {
+            const { object } = await generateObject({
+                model: this.tagModel,
+                schema,
+                maxOutputTokens: this.provider === "openai" ? 1200 : 300,
+                prompt: buildQueryPrompt(query, this.taxonomyVersion)
+            });
+            return { ...pruneUndefined(object), semantic_text: query };
+        }
+        catch {
+            return { semantic_text: query };
+        }
+    }
+}
+/** Back-compat alias — the client used to be Gemini-only. */
+export const ClipGeminiClient = ClipModelClient;
+function buildLanguageModel(provider, apiKey, modelId, publicBaseUrl) {
+    switch (provider) {
+        case "openai":
+            return createOpenAI({ apiKey })(modelId);
+        case "openrouter":
+            return createOpenAICompatible({
+                name: "openrouter",
+                apiKey,
+                baseURL: "https://openrouter.ai/api/v1",
+                headers: { "HTTP-Referer": publicBaseUrl ?? "https://vidfarm.cc", "X-Title": "Vidfarm Clips" }
+            }).chatModel(modelId);
+        case "gemini":
+        default:
+            return createGoogleGenerativeAI({ apiKey })(modelId);
+    }
+}
+function buildEmbeddingModel(provider, apiKey, modelId) {
+    return provider === "openai"
+        ? createOpenAI({ apiKey }).textEmbeddingModel(modelId)
+        : createGoogleGenerativeAI({ apiKey }).textEmbeddingModel(modelId);
+}
+function resolveEmbeddingConfig(provider, apiKey, explicit) {
+    if (explicit === null)
+        return null; // caller explicitly disabled embeddings
+    if (explicit)
+        return explicit;
+    if (provider === "gemini")
+        return { provider: "gemini", apiKey };
+    if (provider === "openai")
+        return { provider: "openai", apiKey };
+    return null; // openrouter: no embeddings unless an explicit config is given
+}
+/** The document text embedded for a clip: description + transcript + salient tags. */
+export function buildClipEmbeddingText(tags, description) {
+    const parts = [];
+    if (description)
+        parts.push(description);
+    if (tags.transcript)
+        parts.push(`Transcript: ${tags.transcript}`);
+    const tagBits = [
+        ...tags.subject,
+        ...tags.action,
+        ...tags.emotion,
+        ...tags.setting,
+        ...tags.composition,
+        ...tags.motion,
+        ...tags.audio_type,
+        `energy:${tags.energy}`
+    ];
+    if (tagBits.length)
+        parts.push(tagBits.join(", "));
+    return parts.join("\n").trim() || "video clip";
+}
+function buildTaggingPrompt(transcript, version, hasAudio = false, guidancePrompt) {
+    const speech = transcript?.trim()
+        ? `The scene's spoken audio (ASR transcript) is: "${transcript.trim()}"`
+        : hasAudio
+            ? `An audio clip of the scene is attached — transcribe any speech into the transcript field (use "" if there is no speech).`
+            : `There is no clear speech in this scene (no dialogue).`;
+    const guidance = guidancePrompt?.trim()
+        ? `\nThe user is curating clips for this goal: "${guidancePrompt.trim()}". Bias the description and tags toward what matters for that goal (stay accurate — never invent tags not visible in the scene).\n`
+        : "";
+    return [
+        "You are tagging one short video scene for a searchable clip library.",
+        "You are given 1-3 keyframes from the scene and its audio transcript.",
+        speech,
+        guidance,
+        "",
+        "Return JSON matching the schema. Use ONLY values from this controlled vocabulary:",
+        taxonomyForPrompt(version),
+        "",
+        "Rules:",
+        "- Pick only tags you are confident about from the keyframes/audio. Omit a category (empty list) rather than guess.",
+        "- If there is no clear person/subject, use subject: [\"no_subject\"].",
+        "- If there is no speech, set audio_type appropriately (e.g. music/ambient/silence) and leave transcript empty.",
+        "- `energy` is a single value: low | medium | high.",
+        "- `transcript` should echo the spoken words verbatim (or \"\" if none).",
+        "- `description`: one short factual sentence (<= 20 words) describing what happens — this drives semantic search, so be concrete.",
+        "Keep the whole response under ~200 tokens."
+    ].join("\n");
+}
+function buildQueryPrompt(query, version) {
+    return [
+        "Convert this clip-search request into a structured filter.",
+        `Request: "${query}"`,
+        "",
+        "Use ONLY values from this controlled vocabulary (omit a field if the request doesn't constrain it):",
+        taxonomyForPrompt(version),
+        "",
+        "Only include fields the request clearly implies. Prefer fewer, high-precision constraints.",
+        "Set has_dialogue/has_subject only when the request is explicit about speech or a subject.",
+        "Durations are in seconds."
+    ].join("\n");
+}
+function pruneUndefined(obj) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v === undefined)
+            continue;
+        if (Array.isArray(v) && v.length === 0)
+            continue;
+        out[k] = v;
+    }
+    return out;
+}
+/** L2-normalize a vector so cosine == dot product (and reduced-dim embeddings compare correctly). */
+export function normalize(vec) {
+    let sum = 0;
+    for (const v of vec)
+        sum += v * v;
+    const norm = Math.sqrt(sum);
+    if (norm === 0)
+        return vec;
+    return vec.map((v) => v / norm);
+}
+// Legacy export kept for callers that referenced the old constant.
+export const TAG_MODEL_BY_TIER = {
+    "flash-lite": resolveTagModel("gemini", "flash-lite"),
+    flash: resolveTagModel("gemini", "flash")
+};
+export const EMBEDDING_MODEL = EMBEDDING_MODELS.gemini;
+//# sourceMappingURL=gemini.js.map

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

@@ -0,0 +1,15 @@
+// vidfarm clip-curation core — the shared "third pillar" library consumed by
+// devcli (local), the Hono API (src/app.ts), and the cloud scan Lambdas. Build
+// once, use in both targets (handoff: Shared Components).
+export * from "./types.js";
+export { ACTIVE_TAXONOMY_VERSION, MULTI_VALUE_CATEGORIES, getTaxonomy, sanitizeTagValues, taxonomyForPrompt } from "./taxonomy.js";
+export { BUILTIN_PRESETS, findBuiltinPreset } from "./presets.js";
+export { ClipModelClient, ClipGeminiClient, EMBEDDING_DIM, EMBEDDING_MODEL, EMBEDDING_MODELS, TAG_MODEL_BY_TIER, buildClipEmbeddingText, normalize } from "./gemini.js";
+export { detectScenes, extractClip, extractKeyframes, extractSceneAudio, extractThumbnail, hasFfmpeg, probeVideo, resolveFfmpeg, resolveFfprobe } from "./ffmpeg.js";
+export { cosineSimilarity, matchesCriteria, rankHits, scoreClip, searchClips, structuredMatchRatio } from "./query.js";
+export { estimateScanCostFromDuration, estimateScanCostFromScenes, formatCostEstimate } from "./cost.js";
+export { processSceneToClip, scanVideo } from "./scan.js";
+export { refineScenesWithGuidance } from "./refine.js";
+// Re-export ClipPreset-related helpers already covered by ./presets and ./types
+// via the wildcard exports above; nothing extra needed here.
+//# sourceMappingURL=index.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,163 @@
+// 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 ["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.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.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