@mevdragon/vidfarm-devcli 0.7.1 → 0.9.0

package/dist/src/services/clip-records.js

@@ -0,0 +1,209 @@
+// Cloud clip records — DynamoDB single-table store for clip curation, mirroring
+// the serverless-records / serverless-jobs conventions (pk/sk + gsi1 overload,
+// entity_type tag, local-dynamo shim in `serve` mode). Same Clip shape as the
+// devcli SQLite store so users move between local and cloud without lock-in.
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { DeleteCommand, DynamoDBDocumentClient, GetCommand, PutCommand, QueryCommand } from "@aws-sdk/lib-dynamodb";
+import { config } from "../config.js";
+import { createLocalDynamoClient } from "./local-dynamo.js";
+import { BUILTIN_PRESETS } from "./clip-curation/index.js";
+// Same client construction as serverless-records.ts: disk shim locally, real
+// client when deployed. Call sites are identical either way.
+const dynamodb = config.RECORDS_DRIVER === "local"
+    ? createLocalDynamoClient()
+    : DynamoDBDocumentClient.from(new DynamoDBClient({}), {
+        marshallOptions: { removeUndefinedValues: true }
+    });
+function requireMainTableName() {
+    if (config.RECORDS_DRIVER === "local") {
+        return config.VIDFARM_SERVERLESS_MAIN_TABLE_NAME || "vidfarm-local-main";
+    }
+    if (!config.VIDFARM_SERVERLESS_MAIN_TABLE_NAME) {
+        throw new Error("Clip record store requires VIDFARM_SERVERLESS_MAIN_TABLE_NAME.");
+    }
+    return config.VIDFARM_SERVERLESS_MAIN_TABLE_NAME;
+}
+const ENTITY_CLIP = "clip_curation_clip";
+const ENTITY_PRESET = "clip_curation_preset";
+const ENTITY_SOURCE = "clip_curation_source";
+const ENTITY_SCAN = "clip_curation_scan";
+// Key scheme (one owner partition, sk-prefixed by entity; gsi1 lists by recency).
+const clipPk = (owner) => `USER#${owner}`;
+const clipSk = (clipId) => `CLIP#${clipId}`;
+const clipListPk = (owner) => `USER#${owner}#CLIPS`;
+const clipSourceListPk = (owner, sourceId) => `USER#${owner}#CLIPS#SRC#${sourceId}`;
+const presetSk = (presetId) => `CLIPPRESET#${presetId}`;
+const presetListPk = (owner) => `USER#${owner}#CLIPPRESETS`;
+const sourceSk = (sourceId) => `CLIPSRC#${sourceId}`;
+const sourceListPk = (owner) => `USER#${owner}#CLIPSRCS`;
+const scanSk = (scanId) => `CLIPSCAN#${scanId}`;
+export class ClipRecordsService {
+    // ── Clips ────────────────────────────────────────────────────────────────
+    async putClip(clip) {
+        const owner = requireOwner(clip.owner_id);
+        await dynamodb.send(new PutCommand({
+            TableName: requireMainTableName(),
+            Item: {
+                pk: clipPk(owner),
+                sk: clipSk(clip.clip_id),
+                entity_type: ENTITY_CLIP,
+                gsi1pk: clipListPk(owner),
+                gsi1sk: `${clip.created_at}#${clip.clip_id}`,
+                gsi2pk: clipSourceListPk(owner, clip.source_video_id),
+                gsi2sk: `${clip.start_time_sec.toFixed(3)}#${clip.clip_id}`,
+                ...clip
+            }
+        }));
+    }
+    async getClip(owner, clipId) {
+        const res = await dynamodb.send(new GetCommand({ TableName: requireMainTableName(), Key: { pk: clipPk(owner), sk: clipSk(clipId) } }));
+        return res.Item ? stripKeys(res.Item) : null;
+    }
+    /** List a user's clips (newest first), optionally scoped to a source video. */
+    async listClips(owner, opts = {}) {
+        const limit = opts.limit ?? 200;
+        if (opts.sourceVideoId) {
+            const res = await dynamodb.send(new QueryCommand({
+                TableName: requireMainTableName(),
+                IndexName: "gsi2",
+                KeyConditionExpression: "gsi2pk = :pk",
+                ExpressionAttributeValues: { ":pk": clipSourceListPk(owner, opts.sourceVideoId) },
+                Limit: limit
+            }));
+            return (res.Items ?? []).map(stripKeys);
+        }
+        const res = await dynamodb.send(new QueryCommand({
+            TableName: requireMainTableName(),
+            IndexName: "gsi1",
+            KeyConditionExpression: "gsi1pk = :pk",
+            ExpressionAttributeValues: { ":pk": clipListPk(owner) },
+            ScanIndexForward: false,
+            Limit: limit
+        }));
+        return (res.Items ?? []).map(stripKeys);
+    }
+    /** All embeddings for a user's clips — feeds the brute-force vector search. */
+    async listClipsWithEmbeddings(owner) {
+        const clips = await this.listClips(owner, { limit: 5000 });
+        return clips.filter((c) => Array.isArray(c.embedding) && c.embedding.length > 0);
+    }
+    /**
+     * The embedding model the library was built with (from the newest embedded
+     * clip). A match query must be embedded with the SAME model to be comparable.
+     */
+    async getLibraryEmbeddingModel(owner) {
+        const clips = await this.listClips(owner, { limit: 20 });
+        for (const c of clips) {
+            if (c.embedding_model && Array.isArray(c.embedding) && c.embedding.length > 0)
+                return c.embedding_model;
+        }
+        return null;
+    }
+    async deleteClip(owner, clipId) {
+        await dynamodb.send(new DeleteCommand({ TableName: requireMainTableName(), Key: { pk: clipPk(owner), sk: clipSk(clipId) } }));
+    }
+    // ── Presets ──────────────────────────────────────────────────────────────
+    async listPresets(owner) {
+        const res = await dynamodb.send(new QueryCommand({
+            TableName: requireMainTableName(),
+            KeyConditionExpression: "pk = :pk AND begins_with(sk, :sk)",
+            ExpressionAttributeValues: { ":pk": clipPk(owner), ":sk": "CLIPPRESET#" }
+        }));
+        const saved = (res.Items ?? []).map((i) => stripKeys(i));
+        return [...BUILTIN_PRESETS, ...saved];
+    }
+    async putPreset(owner, preset) {
+        await dynamodb.send(new PutCommand({
+            TableName: requireMainTableName(),
+            Item: {
+                pk: clipPk(owner),
+                sk: presetSk(preset.preset_id),
+                entity_type: ENTITY_PRESET,
+                gsi1pk: presetListPk(owner),
+                gsi1sk: preset.created_at,
+                ...preset,
+                owner_id: owner
+            }
+        }));
+    }
+    async deletePreset(owner, presetId) {
+        await dynamodb.send(new DeleteCommand({ TableName: requireMainTableName(), Key: { pk: clipPk(owner), sk: presetSk(presetId) } }));
+    }
+    // ── Source videos ──────────────────────────────────────────────────────────
+    async putSource(record) {
+        await dynamodb.send(new PutCommand({
+            TableName: requireMainTableName(),
+            Item: {
+                pk: clipPk(record.owner_id),
+                sk: sourceSk(record.source_video_id),
+                entity_type: ENTITY_SOURCE,
+                gsi1pk: sourceListPk(record.owner_id),
+                gsi1sk: record.created_at,
+                ...record
+            }
+        }));
+    }
+    async getSource(owner, sourceId) {
+        const res = await dynamodb.send(new GetCommand({ TableName: requireMainTableName(), Key: { pk: clipPk(owner), sk: sourceSk(sourceId) } }));
+        return res.Item ? stripKeys(res.Item) : null;
+    }
+    async listSources(owner) {
+        const res = await dynamodb.send(new QueryCommand({
+            TableName: requireMainTableName(),
+            IndexName: "gsi1",
+            KeyConditionExpression: "gsi1pk = :pk",
+            ExpressionAttributeValues: { ":pk": sourceListPk(owner) },
+            ScanIndexForward: false
+        }));
+        return (res.Items ?? []).map((i) => stripKeys(i));
+    }
+    // ── Scan jobs ──────────────────────────────────────────────────────────────
+    async putScan(record) {
+        await dynamodb.send(new PutCommand({
+            TableName: requireMainTableName(),
+            Item: {
+                pk: clipPk(record.owner_id),
+                sk: scanSk(record.scan_id),
+                entity_type: ENTITY_SCAN,
+                ...record
+            }
+        }));
+    }
+    async getScan(owner, scanId) {
+        const res = await dynamodb.send(new GetCommand({ TableName: requireMainTableName(), Key: { pk: clipPk(owner), sk: scanSk(scanId) } }));
+        return res.Item ? stripKeys(res.Item) : null;
+    }
+}
+export const clipRecords = new ClipRecordsService();
+/** Build a user-saved preset record from raw criteria. */
+export function makeUserPreset(input) {
+    return {
+        preset_id: `preset_${Date.now().toString(36)}_${Math.floor(Math.random() * 1e6).toString(36)}`,
+        name: input.name,
+        description: input.description,
+        criteria: input.criteria,
+        builtin: false,
+        owner_id: input.owner,
+        created_at: new Date().toISOString()
+    };
+}
+function requireOwner(owner) {
+    if (!owner)
+        throw new Error("Clip records require an owner_id.");
+    return owner;
+}
+// Drop the DynamoDB key/index attributes so callers get back a clean record.
+function stripKeys(item) {
+    const { pk, sk, entity_type, gsi1pk, gsi1sk, gsi2pk, gsi2sk, gsi3pk, gsi3sk, ...rest } = item;
+    void pk;
+    void sk;
+    void entity_type;
+    void gsi1pk;
+    void gsi1sk;
+    void gsi2pk;
+    void gsi2sk;
+    void gsi3pk;
+    void gsi3sk;
+    return rest;
+}
+//# sourceMappingURL=clip-records.js.map

package/dist/src/services/clip-search.js

@@ -0,0 +1,47 @@
+// Cloud clip search — the two-stage flow (structured filter → semantic re-rank)
+// wired over DynamoDB records + the configured vector index. Same result shape
+// as the devcli store so the API mirrors the CLI (success criterion #4).
+import { matchesCriteria, rankHits, scoreClip, searchClips } from "./clip-curation/index.js";
+import { clipRecords } from "./clip-records.js";
+import { resolveClipVectorIndex } from "./clip-vectors.js";
+const vectorIndex = resolveClipVectorIndex((owner) => clipRecords.listClipsWithEmbeddings(owner));
+export async function searchUserClips(owner, input) {
+    const limit = input.limit ?? 20;
+    const all = await clipRecords.listClips(owner, { limit: 5000 });
+    const structured = all.filter((c) => matchesCriteria(c, input.criteria));
+    if (structured.length > 0) {
+        // Semantic re-rank the survivors (embeddings already ride on the records).
+        const hits = structured.map((c) => scoreClip(c, input.criteria, input.queryEmbedding, false));
+        return rankHits(hits, limit);
+    }
+    // No structured match — relax to a semantic-only pass via the vector index.
+    if (input.queryEmbedding) {
+        const knn = await vectorIndex.query(owner, input.queryEmbedding, Math.max(limit * 5, 50));
+        const byId = new Map(all.map((c) => [c.clip_id, c]));
+        const pool = knn.map((h) => byId.get(h.clip_id)).filter((c) => Boolean(c));
+        const hits = pool.map((c) => scoreClip(c, input.criteria, input.queryEmbedding, true));
+        return rankHits(hits, limit);
+    }
+    return [];
+}
+export { vectorIndex };
+/**
+ * Match many scene annotations against the owner's clip library at once. Loads
+ * the library ONCE (embeddings ride on the records) and runs each scene's
+ * structured filter + semantic re-rank in memory — so a whole decomposed video
+ * costs one library read plus M cheap in-memory ranks.
+ */
+export async function matchScenesToClips(owner, queries) {
+    const all = await clipRecords.listClips(owner, { limit: 5000 });
+    return queries.map((q) => ({
+        id: q.id,
+        meta: q.meta,
+        matches: searchClips(all, {
+            criteria: q.criteria,
+            queryEmbedding: q.queryEmbedding,
+            limit: q.limit ?? 5,
+            relaxWhenEmpty: true
+        })
+    }));
+}
+//# sourceMappingURL=clip-search.js.map

package/dist/src/services/clip-vectors.js

@@ -0,0 +1,125 @@
+// Vector index abstraction for cloud clip search. Two backends behind one
+// interface so the pipeline is portable and cloud infra cost stays deferrable:
+//
+//  • "dynamo" (default) — embeddings live on the clip records in DynamoDB;
+//    search brute-forces cosine in memory. Zero extra infra, works with the
+//    local-dynamo shim in `serve` mode. Fine to thousands of clips per user.
+//  • "s3vectors" — Amazon S3 Vectors index (handoff target). Best-effort:
+//    dynamically imports @aws-sdk/client-s3vectors and errors clearly if the
+//    dep/config is absent, so selecting it is opt-in.
+//
+// Both return the same {clip_id, similarity} shape; the caller applies the
+// structured filter + final scoring with the shared query builder.
+import { cosineSimilarity } from "./clip-curation/index.js";
+import { config } from "../config.js";
+/** Default backend: brute-force cosine over the owner's clip embeddings in DynamoDB. */
+export class DynamoVectorIndex {
+    loadEmbeddings;
+    backend = "dynamo";
+    constructor(loadEmbeddings) {
+        this.loadEmbeddings = loadEmbeddings;
+    }
+    async upsert() {
+        /* embedding is stored on the clip record itself */
+    }
+    async delete() {
+        /* removed with the clip record */
+    }
+    async query(owner, queryEmbedding, k) {
+        const clips = await this.loadEmbeddings(owner);
+        return clips
+            .map((c) => ({ clip_id: c.clip_id, similarity: cosineSimilarity(c.embedding, queryEmbedding) }))
+            .sort((a, b) => b.similarity - a.similarity)
+            .slice(0, k);
+    }
+}
+/**
+ * Amazon S3 Vectors backend. Vectors are keyed by clip_id within a per-owner
+ * partition; metadata carries source_video_id for filtering. Requires
+ * VIDFARM_CLIP_VECTORS_BUCKET + VIDFARM_CLIP_VECTORS_INDEX and the
+ * @aws-sdk/client-s3vectors package.
+ */
+export class S3VectorsIndex {
+    bucket;
+    indexName;
+    backend = "s3vectors";
+    clientPromise = null;
+    constructor(bucket, indexName) {
+        this.bucket = bucket;
+        this.indexName = indexName;
+    }
+    async client() {
+        if (!this.clientPromise) {
+            this.clientPromise = import("@aws-sdk/client-s3vectors").catch(() => {
+                throw new Error("S3 Vectors backend selected but @aws-sdk/client-s3vectors is not installed. `npm i @aws-sdk/client-s3vectors` or set VIDFARM_CLIP_VECTOR_BACKEND=dynamo.");
+            });
+        }
+        const mod = await this.clientPromise;
+        return { mod, client: new mod.S3VectorsClient({}) };
+    }
+    async upsert(owner, clip) {
+        if (!clip.embedding?.length)
+            return;
+        const { mod, client } = await this.client();
+        await client.send(new mod.PutVectorsCommand({
+            vectorBucketName: this.bucket,
+            indexName: this.indexName,
+            vectors: [
+                {
+                    key: vectorKey(owner, clip.clip_id),
+                    data: { float32: clip.embedding },
+                    metadata: { owner, source_video_id: clip.source_video_id, clip_id: clip.clip_id }
+                }
+            ]
+        }));
+    }
+    async delete(owner, clipId) {
+        const { mod, client } = await this.client();
+        await client.send(new mod.DeleteVectorsCommand({ vectorBucketName: this.bucket, indexName: this.indexName, keys: [vectorKey(owner, clipId)] }));
+    }
+    async query(owner, queryEmbedding, k) {
+        const { mod, client } = await this.client();
+        const res = await client.send(new mod.QueryVectorsCommand({
+            vectorBucketName: this.bucket,
+            indexName: this.indexName,
+            topK: k,
+            queryVector: { float32: queryEmbedding },
+            filter: { owner },
+            returnMetadata: true,
+            returnDistance: true
+        }));
+        const vectors = res.vectors ?? [];
+        return vectors.map((v) => ({
+            clip_id: v.metadata?.clip_id ?? stripVectorKey(v.key),
+            // S3 Vectors returns cosine DISTANCE (0..2); convert to similarity.
+            similarity: 1 - Number(v.distance ?? 0)
+        }));
+    }
+}
+function vectorKey(owner, clipId) {
+    return `${owner}/${clipId}`;
+}
+function stripVectorKey(key) {
+    const idx = key.lastIndexOf("/");
+    return idx >= 0 ? key.slice(idx + 1) : key;
+}
+let cached = null;
+/** Resolve the configured vector index (default: dynamo brute-force). */
+export function resolveClipVectorIndex(loadEmbeddings) {
+    if (cached)
+        return cached;
+    const backend = (process.env.VIDFARM_CLIP_VECTOR_BACKEND ?? "dynamo").toLowerCase();
+    if (backend === "s3vectors") {
+        const bucket = process.env.VIDFARM_CLIP_VECTORS_BUCKET;
+        const index = process.env.VIDFARM_CLIP_VECTORS_INDEX;
+        if (bucket && index) {
+            cached = new S3VectorsIndex(bucket, index);
+            return cached;
+        }
+        // Missing config → fall back to the always-available dynamo backend.
+    }
+    cached = new DynamoVectorIndex(loadEmbeddings);
+    void config; // config imported for parity with sibling services / future use
+    return cached;
+}
+//# sourceMappingURL=clip-vectors.js.map