@mevdragon/vidfarm-devcli 0.9.0 → 0.11.0

package/dist/src/devcli/clips.js

@@ -1,35 +1,55 @@
-// devcli `vidfarm clips …` — the local clip-curation surface. Uses local
-// ffmpeg (near-zero compute) + BYOK Gemini, persisting to a SQLite clip library
-// (~/.vidfarm). Every scan shows an estimated cost first; scans over $1 require
-// --yes or an interactive confirm. Mirrors the cloud REST surface 1:1.
-import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+// devcli `vidfarm clips …` — the local clip-curation surface. LOCAL-FIRST:
+// local ffmpeg for compute and, by default, the user's local agent CLI
+// subscription (claude/codex) for scene evaluation — no API key needed. BYOK
+// provider keys are the first fallback, and `--cloud` is the explicit backup
+// that runs the hunt on the deployed pipeline instead (never the default).
+// Persists to a SQLite clip library (~/.vidfarm). Every keyed scan shows an
+// estimated cost first; scans over $1 require --yes or an interactive confirm.
+// Mirrors the cloud REST surface 1:1.
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync } from "node:fs";
 import path from "node:path";
 import { homedir } from "node:os";
 import { parseArgs } from "node:util";
 import { createInterface } from "node:readline/promises";
 import { createIdV7 } from "../lib/ids.js";
-import { ClipModelClient, estimateScanCostFromScenes, formatCostEstimate, detectScenes, hasFfmpeg, probeVideo, scanVideo, searchClips } from "../services/clip-curation/index.js";
+import { buildEffectiveGuidance, ClipModelClient, detectLocalAgent, detectScenes, estimateScanCostFromScenes, fitScenesToDurationBand, formatCostEstimate, hasFfmpeg, LocalAgentClipClient, normalizeAspect, normalizeCropFocus, normalizeWindows, parseClipHuntPrompt, parseTimeRanges, probeVideo, resolveDurationBand, scanVideo, searchClips } from "../services/clip-curation/index.js";
 import { ClipStore } from "./clip-store.js";
-export const CLIPS_HELP = `vidfarm clips — build & search a local clip library (local ffmpeg + BYOK Gemini)
+export const CLIPS_HELP = `vidfarm clips — build & search a local clip library (local ffmpeg + local agent by default)
 
   clips scan <video-path>          Mine a long-form video into tagged, searchable clips
-    --provider <p>                 gemini | openai | openrouter (default: gemini)
-                                   gemini→gemini-2.5-flash-lite, openai→gpt-5.4-nano,
-                                   openrouter→google/gemini-2.5-flash
-    --tier flash|flash-lite        Gemini tier (default: flash-lite; ignored for openai/openrouter)
+    --provider <p>                 agent | gemini | openai | openrouter
+                                   Default: agent when a local claude/codex CLI is installed
+                                   (your subscription, no API key), else gemini.
+    --agent claude|codex           Which local agent CLI to use for --provider agent (default: auto)
+    --tier flash|flash-lite        Gemini tier (default: flash-lite; ignored for openai/openrouter/agent)
     --prompt "<guidance>"          Reshape clipping toward your goal: an LLM pass
-                                   keeps/drops/merges scenes, and tags are biased to it
+                                   keeps/drops/merges scenes, and tags are biased to it.
+                                   Inline hints are honored too: "between 12:30 and 15:45",
+                                   "30 sec clips", "vertical", "no captions".
+    --range "MM:SS-MM:SS"          Only hunt inside this source range (repeatable / comma-separated)
+    --duration <sec>               Target clip length as a SOFT band (10→5-20s, 30→20-40s, …)
+    --aspect <a>                   Crop clips to 9:16 | 16:9 | 4:3 | 1:1 (or vertical/horizontal/square)
+    --crop-focus <f>               center | top | bottom | left | right (default: center)
+    --no-text                      Prefer scenes WITHOUT burned-in captions/on-screen text
+                                   (scene selection — NEVER GhostCut on the long-form source)
     --no-refine                    Keep prompt tag-bias but skip the keep/drop/merge pass
+    --cloud                        BACKUP: run the hunt on the deployed pipeline instead of this
+                                   machine (uploads to your temp folder — auto-deletes in 30 days —
+                                   or pass --url; needs VIDFARM_API_KEY; bills AWS compute only)
+    --url <video-url>              With --cloud: hunt a YouTube/TikTok/IG/X URL without uploading
+    --tracer <id>                  With --cloud: tag the hunt's billing/observability rollup
+    --api-url <base>               With --cloud: deployment base URL (or VIDFARM_API_URL)
+    --api-key <key>                With --cloud: API key (or VIDFARM_API_KEY)
     --dry-run                      Print the estimated cost and exit
     --yes                          Skip the >$1 confirmation prompt
     --frames <n>                   Keyframes per scene for tagging (1-3, default 2)
     --no-audio                     Skip per-scene audio (Gemini only; no transcripts; cheaper)
-    --concurrency <n>              Parallel scenes (default 3; respect rate limits)
+    --concurrency <n>              Parallel scenes (default 3; agent default 2)
     --threshold <0..1>             Scene-cut sensitivity (default 0.3; lower = more cuts)
     --min-scene <sec>              Merge scenes shorter than this (default 0.6)
-    --max-scene <sec>              Split scenes longer than this (default 8)
+    --max-scene <sec>              Split scenes longer than this (default 8; --duration overrides)
     --gemini-key / --openai-key / --openrouter-key <key>   Provider key (or *_API_KEY env)
-    --embed-provider gemini|openai --embed-key <key>       Embeddings when using openrouter
+    --embed-provider gemini|openai --embed-key <key>       Embeddings for agent/openrouter scans
     --home <dir>                   Library dir (default: ~/.vidfarm or VIDFARM_HOME)
 
   clips list                       List clips in the library
@@ -97,9 +117,20 @@ async function runScan(argv) {
         allowPositionals: true,
         options: {
             provider: { type: "string" },
+            agent: { type: "string" },
             tier: { type: "string" },
             prompt: { type: "string" },
+            range: { type: "string", multiple: true },
+            duration: { type: "string" },
+            aspect: { type: "string" },
+            "crop-focus": { type: "string" },
+            "no-text": { type: "boolean" },
             "no-refine": { type: "boolean" },
+            cloud: { type: "boolean" },
+            url: { type: "string" },
+            tracer: { type: "string" },
+            "api-url": { type: "string" },
+            "api-key": { type: "string" },
             "dry-run": { type: "boolean" },
             yes: { type: "boolean" },
             frames: { type: "string" },
@@ -116,67 +147,146 @@ async function runScan(argv) {
             home: { type: "string" }
         }
     });
+    // ── Hunt spec: explicit flags win; inline prompt hints fill the gaps ──────
+    const guidancePromptRaw = values.prompt?.trim() || undefined;
+    const parsedPrompt = parseClipHuntPrompt(guidancePromptRaw);
+    const rawWindows = values.range?.length
+        ? parseTimeRanges(values.range)
+        : parsedPrompt.windows;
+    const durationBand = values.duration
+        ? resolveDurationBand(Number(values.duration))
+        : parsedPrompt.target_duration_sec != null
+            ? resolveDurationBand(parsedPrompt.target_duration_sec)
+            : null;
+    const aspect = values.aspect
+        ? (normalizeAspect(values.aspect) ?? (() => { throw new Error(`--aspect must be 9:16 | 16:9 | 4:3 | 1:1 (or vertical/horizontal/square), got "${values.aspect}"`); })())
+        : parsedPrompt.aspect;
+    const cropFocus = normalizeCropFocus(values["crop-focus"]);
+    const avoidText = Boolean(values["no-text"]) || parsedPrompt.avoid_text;
+    const guidance = buildEffectiveGuidance({ contentPrompt: guidancePromptRaw, avoidText }) || undefined;
+    // ── BACKUP path: run the hunt on the deployed pipeline (--cloud) ──────────
+    if (values.cloud) {
+        return runScanCloud({
+            videoArg: positionals[0],
+            sourceUrl: values.url?.trim() || undefined,
+            apiUrl: values["api-url"],
+            apiKey: values["api-key"],
+            tracer: values.tracer,
+            prompt: guidancePromptRaw,
+            windows: rawWindows,
+            durationBand,
+            aspect,
+            cropFocus,
+            avoidText
+        });
+    }
     const videoArg = positionals[0];
     if (!videoArg)
-        throw new Error("Usage: vidfarm clips scan <video-path> [--tier flash|flash-lite] [--dry-run]");
+        throw new Error("Usage: vidfarm clips scan <video-path> [--range MM:SS-MM:SS] [--duration 30] [--aspect 9:16] [--dry-run]");
     const videoPath = path.resolve(process.cwd(), videoArg);
     if (!existsSync(videoPath))
         throw new Error(`No such video: ${videoPath}`);
     if (!(await hasFfmpeg())) {
         throw new Error("ffmpeg is required for `clips scan` but was not found (bundled ffmpeg-static missing and none on PATH).");
     }
-    const provider = normalizeProvider(values.provider);
+    // ── Model resolution: LOCAL-FIRST ─────────────────────────────────────────
+    // 1. --provider agent (or no --provider + a local claude/codex CLI installed)
+    //    → the user's local agent subscription evaluates scenes; no API key.
+    // 2. --provider gemini|openai|openrouter (or a key in env/config) → BYOK API.
+    // 3. --cloud (handled above) → the deployed pipeline, as an explicit backup.
+    const provider = resolveScanProvider(values);
     const tier = normalizeTier(values.tier);
     const framesPerScene = clampInt(values.frames, 2, 1, 3);
-    // Audio is Gemini-only (chat models on openai/openrouter don't take the clip).
+    // Audio is Gemini-only (chat models on openai/openrouter — and CLI agents — don't take the clip).
     const includeAudio = !values["no-audio"] && provider === "gemini";
-    const guidancePrompt = values.prompt?.trim() || undefined;
-    const concurrency = clampInt(values.concurrency, 3, 1, 12);
+    // Local agents run one process per call — keep parallelism modest by default.
+    const concurrency = clampInt(values.concurrency, provider === "agent" ? 2 : 3, 1, 12);
     const sceneOptions = {
         threshold: values.threshold ? Number(values.threshold) : undefined,
         minSceneSec: values["min-scene"] ? Number(values["min-scene"]) : undefined,
-        maxSceneSec: values["max-scene"] ? Number(values["max-scene"]) : undefined
+        // A duration band lifts the split ceiling; an explicit --max-scene still wins.
+        maxSceneSec: values["max-scene"] ? Number(values["max-scene"]) : durationBand?.max_sec
     };
     // Resolve the tagging key + optional embedding config. Optional here so
-    // --dry-run can show the cost without a key; the key is required below to scan.
-    const apiKey = resolveProviderKey(provider, values, { optional: true });
-    const embedding = apiKey ? resolveEmbeddingConfig(provider, apiKey, values) : null;
+    // --dry-run can show the cost without a key; required below to scan (API providers).
+    const apiKey = provider === "agent" ? "" : resolveProviderKey(provider, values, { optional: true });
+    const embedding = provider === "agent"
+        ? resolveAgentEmbeddingConfig(values)
+        : apiKey ? resolveEmbeddingConfig(provider, apiKey, values) : null;
     console.log(`[clips] probing ${path.basename(videoPath)} …`);
     const probe = await probeVideo(videoPath);
     console.log(`[clips] ${fmtDuration(probe.duration_sec)} · ${probe.width ?? "?"}x${probe.height ?? "?"} · ${probe.codec ?? "?"}`);
+    const windows = normalizeWindows(rawWindows, probe.duration_sec);
+    if (rawWindows.length && !windows.length) {
+        throw new Error("--range produced no usable window inside the video's duration.");
+    }
+    if (windows.length) {
+        console.log(`[clips] hunting only ${windows.map((w) => `${fmtClock(w.start_sec)}–${fmtClock(w.end_sec)}`).join(", ")} (${fmtDuration(windows.reduce((a, w) => a + w.end_sec - w.start_sec, 0))} of ${fmtDuration(probe.duration_sec)}).`);
+    }
+    if (durationBand) {
+        console.log(`[clips] target clip length ~${durationBand.target_sec}s (soft range ${durationBand.min_sec}–${durationBand.max_sec}s).`);
+    }
+    if (aspect && aspect !== "original")
+        console.log(`[clips] cropping clips to ${aspect} (${cropFocus}).`);
+    if (avoidText)
+        console.log(`[clips] preferring scenes without on-screen text/captions (selection only — GhostCut is never run on the source).`);
     console.log(`[clips] detecting scenes …`);
-    const scenes = await detectScenes(videoPath, { durationSec: probe.duration_sec, ...sceneOptions });
+    const detected = await detectScenes(videoPath, { durationSec: probe.duration_sec, windows, ...sceneOptions });
+    const scenes = fitScenesToDurationBand(detected, durationBand);
     if (scenes.length === 0)
         throw new Error("No scenes detected (is the video readable / non-empty?).");
     const store = new ClipStore(values.home);
-    const client = apiKey ? new ClipModelClient({ provider, apiKey, tier, embedding }) : null;
+    let client = null;
+    if (provider === "agent") {
+        client = new LocalAgentClipClient({
+            agent: values.agent === "claude" || values.agent === "codex" ? values.agent : "auto",
+            embedding,
+            tier
+        });
+        console.log(`[clips] evaluating scenes with your local ${client.tagModelId} subscription (no API cost).`);
+    }
+    else if (apiKey) {
+        client = new ClipModelClient({ provider, apiKey, tier, embedding });
+    }
     if (client && !client.canEmbed) {
         console.warn(`[clips] no embedding provider for "${provider}" — clips will be structured-searchable only.`);
         console.warn(`        Add --embed-provider gemini|openai --embed-key <key> for semantic search.`);
     }
-    const estimate = estimateScanCostFromScenes(scenes, {
-        tier,
-        provider,
-        tagModelId: client?.tagModelId,
-        embedModelId: client ? client.embeddingModelId : defaultEmbedModelForEstimate(provider),
-        framesPerScene,
-        includeAudio
-    });
-    console.log(`\n  Cost estimate: ${formatCostEstimate(estimate)}`);
-    console.log(`  Target: $0.05–0.10 per source hour (${withinTarget(estimate.usd_per_source_hour) ? "on target" : "note"}).`);
-    if (guidancePrompt)
-        console.log(`  Guidance: "${guidancePrompt}"`);
+    // Cost estimate: local-agent scans ride the user's subscription, so only the
+    // optional embedding spend applies; API scans estimate the full BYOK cost.
+    const estimate = provider === "agent"
+        ? null
+        : estimateScanCostFromScenes(scenes, {
+            tier,
+            provider,
+            tagModelId: client?.tagModelId,
+            embedModelId: client ? client.embeddingModelId : defaultEmbedModelForEstimate(provider),
+            framesPerScene,
+            includeAudio
+        });
+    if (estimate) {
+        console.log(`\n  Cost estimate: ${formatCostEstimate(estimate)}`);
+        console.log(`  Target: $0.05–0.10 per source hour (${withinTarget(estimate.usd_per_source_hour) ? "on target" : "note"}).`);
+    }
+    else {
+        console.log(`\n  Cost: local agent subscription (${scenes.length} scenes; embeddings ${embedding ? `via ${embedding.provider}` : "off"}).`);
+    }
+    if (guidance)
+        console.log(`  Guidance: "${guidance.replace(/\n/g, " · ")}"`);
     console.log("");
     if (values["dry-run"]) {
         console.log("[clips] --dry-run: not scanning. Re-run without --dry-run to build the library.");
         return;
     }
-    // Actually scanning now — a key is required.
-    if (!client)
-        resolveProviderKey(provider, values); // throws the "No <provider> API key" error
+    // Actually scanning now — an evaluator is required.
+    if (!client) {
+        if (provider !== "agent")
+            resolveProviderKey(provider, values); // throws the "No <provider> API key" error
+        throw new Error("No scene evaluator available. Install Claude Code (`claude`) or Codex (`codex`), pass a provider key, or run with --cloud.");
+    }
     const activeClient = client;
-    // $1 confirmation gate (handoff Target 1).
-    if (estimate.usd > 1 && !values.yes) {
+    // $1 confirmation gate (handoff Target 1) — keyed scans only.
+    if (estimate && estimate.usd > 1 && !values.yes) {
         const ok = await confirm(`This scan is estimated at $${estimate.usd.toFixed(2)}. Proceed? [y/N] `);
         if (!ok) {
             console.log("[clips] aborted.");
@@ -200,9 +310,10 @@ async function runScan(argv) {
         thumbsDir: store.paths.thumbsDir,
         framesPerScene,
         includeAudio,
-        guidancePrompt,
+        guidancePrompt: guidance,
         refineSegmentation: !values["no-refine"],
-        reencodeClips: true
+        reencodeClips: true,
+        crop: aspect && aspect !== "original" ? { aspect, focus: cropFocus } : undefined
     };
     console.log(`[clips] scanning ${scenes.length} scenes (${provider}/${activeClient.tagModelId}, ${concurrency}x) …`);
     let errors = 0;
@@ -212,6 +323,8 @@ async function runScan(argv) {
         videoPath,
         scenes,
         probe,
+        windows,
+        durationBand,
         sourceFilename: path.basename(videoPath),
         concurrency,
         onRefine: (r) => {
@@ -253,6 +366,139 @@ async function runScan(argv) {
     console.log(`  db    → ${store.paths.db}`);
     console.log(`  try:  vidfarm clips search "…"  |  vidfarm clips preset run "funny reaction gifs"`);
 }
+// ── clips scan --cloud (explicit backup: the deployed pipeline) ─────────────
+// Uploads the local file into the user's temp folder (30-day TTL, auto-removed)
+// — or passes --url straight through — then starts POST /clips/scan and polls.
+// The hunt bills AWS compute only; AI runs on the account's saved BYOK keys.
+async function runScanCloud(input) {
+    const baseUrl = (input.apiUrl || process.env.VIDFARM_API_URL || process.env.VIDFARM_UPSTREAM_HOST || "https://vidfarm.cc").replace(/\/$/, "");
+    const apiKey = input.apiKey || process.env.VIDFARM_API_KEY || "";
+    if (!apiKey)
+        throw new Error("--cloud needs an API key: pass --api-key or set VIDFARM_API_KEY.");
+    const headers = { "vidfarm-api-key": apiKey, "content-type": "application/json", accept: "application/json" };
+    let tempFileId;
+    let fileName;
+    if (!input.sourceUrl) {
+        if (!input.videoArg)
+            throw new Error("Usage: vidfarm clips scan --cloud <video-path> | --cloud --url <video-url>");
+        const videoPath = path.resolve(process.cwd(), input.videoArg);
+        if (!existsSync(videoPath))
+            throw new Error(`No such video: ${videoPath}`);
+        fileName = path.basename(videoPath);
+        const sizeBytes = statSync(videoPath).size;
+        console.log(`[clips] uploading ${fileName} (${(sizeBytes / (1024 * 1024)).toFixed(1)} MB) to your temp folder (auto-deletes in 30 days) …`);
+        const presignRes = await fetch(`${baseUrl}/api/v1/user/me/temporary-files/presign`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ file_name: fileName, content_type: "video/mp4", size_bytes: sizeBytes, folder_path: "clip-sources" })
+        });
+        const presign = await presignRes.json();
+        if (!presignRes.ok || !presign.upload || !presign.file_id) {
+            throw new Error(`Temp upload presign failed (${presignRes.status}): ${presign.error ?? "unexpected response"}`);
+        }
+        if (presign.transport !== "presigned") {
+            throw new Error("The deployment does not support presigned uploads — upload via the web UI, then re-run with --url or temp_file_id.");
+        }
+        const putRes = await fetch(presign.upload.url, {
+            method: presign.upload.method,
+            headers: presign.upload.headers,
+            body: readFileSync(path.resolve(process.cwd(), input.videoArg))
+        });
+        if (!putRes.ok)
+            throw new Error(`Upload failed (${putRes.status}).`);
+        const finalizeRes = await fetch(`${baseUrl}/api/v1/user/me/temporary-files`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({
+                file_id: presign.file_id,
+                file_name: fileName,
+                content_type: "video/mp4",
+                size_bytes: sizeBytes,
+                storage_key: presign.storage_key,
+                folder_path: "clip-sources"
+            })
+        });
+        if (!finalizeRes.ok) {
+            const body = await finalizeRes.text().catch(() => "");
+            throw new Error(`Temp upload finalize failed (${finalizeRes.status}): ${body.slice(0, 300)}`);
+        }
+        tempFileId = presign.file_id;
+    }
+    console.log(`[clips] starting cloud hunt …`);
+    const scanRes = await fetch(`${baseUrl}/clips/scan`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+            ...(input.sourceUrl ? { source_url: input.sourceUrl } : { temp_file_id: tempFileId, filename: fileName }),
+            prompt: input.prompt ?? "",
+            ...(input.tracer ? { tracer: input.tracer } : {}),
+            hunt_spec: {
+                ...(input.windows.length ? { windows: input.windows } : {}),
+                ...(input.durationBand ? { duration_band: input.durationBand } : {}),
+                ...(input.aspect ? { aspect: input.aspect } : {}),
+                crop_focus: input.cropFocus,
+                ...(input.avoidText ? { avoid_text: true } : {})
+            }
+        })
+    });
+    const scan = await scanRes.json();
+    if (!scanRes.ok || !scan.scan_id) {
+        throw new Error(`Cloud scan failed to start (${scanRes.status}): ${scan.error ?? "unexpected response"}`);
+    }
+    console.log(`[clips] scan ${scan.scan_id} ${scan.status ?? "queued"}${scan.tracer ? ` (tracer ${scan.tracer})` : ""}.`);
+    if (scan.compute_estimate?.estimated_charge_usd != null) {
+        console.log(`[clips] estimated AWS compute charge ~$${scan.compute_estimate.estimated_charge_usd.toFixed(4)} (AI runs on your saved provider keys).`);
+    }
+    // Async by design — poll until the pipeline finishes.
+    const started = timestamp();
+    for (;;) {
+        await new Promise((r) => setTimeout(r, 5000));
+        const pollRes = await fetch(`${baseUrl}/clips/scan/${encodeURIComponent(scan.scan_id)}`, { headers });
+        if (!pollRes.ok)
+            continue;
+        const poll = await pollRes.json();
+        const status = poll.source?.status ?? poll.scan?.status ?? "running";
+        if (status === "complete") {
+            console.log(`\n[clips] cloud hunt done in ${elapsed(started)}: ${poll.source?.clip_count ?? 0} clips.`);
+            console.log(`  browse → ${baseUrl}/clips`);
+            return;
+        }
+        if (status === "failed") {
+            throw new Error(`Cloud hunt failed: ${poll.scan?.error ?? "unknown error"}`);
+        }
+        process.stdout.write(`\r[clips] ${status} … ${elapsed(started)} `);
+    }
+}
+/**
+ * LOCAL-FIRST provider pick: an explicit --provider always wins; otherwise use
+ * the local agent CLI when one is installed (subscription-powered, keyless),
+ * else fall back to gemini BYOK. The cloud pipeline is never a silent default
+ * — it's the explicit `--cloud` backup.
+ */
+function resolveScanProvider(values) {
+    if (values.provider === "agent" || values.provider === "local" || values.provider === "local-agent")
+        return "agent";
+    if (values.provider)
+        return normalizeProvider(values.provider);
+    if (values.agent)
+        return "agent";
+    if (detectLocalAgent())
+        return "agent";
+    return "gemini";
+}
+/** Embeddings for a local-agent scan: any gemini/openai key found makes the library semantically searchable. */
+function resolveAgentEmbeddingConfig(flags) {
+    const explicit = flags["embed-provider"]?.trim();
+    const tryProvider = (p) => {
+        const key = flags["embed-key"]?.trim() || resolveProviderKey(p, flags, { optional: true });
+        return key ? { provider: p, apiKey: key } : null;
+    };
+    if (explicit === "gemini")
+        return tryProvider("gemini");
+    if (explicit === "openai")
+        return tryProvider("openai");
+    return tryProvider("gemini") ?? tryProvider("openai");
+}
 // ── clips list ──────────────────────────────────────────────────────────────
 async function runList(argv) {
     const { values } = parseArgs({
@@ -320,8 +566,15 @@ async function runSearch(argv) {
             queryEmbedding = await client.embedQuery(criteria.semantic_text ?? query);
         }
     }
+    else if (detectLocalAgent()) {
+        // Local-first: no key, but a local agent CLI can still turn the natural-
+        // language query into a structured filter (vector re-rank needs a key).
+        const agent = new LocalAgentClipClient({});
+        console.log(`[clips] structuring query with your local ${agent.tagModelId} …`);
+        criteria = await agent.naturalLanguageToCriteria(query);
+    }
     else {
-        console.warn(`[clips] no ${provider} key — structured/keyword search only (set the provider key for semantic search).`);
+        console.warn(`[clips] no ${provider} key or local agent CLI — structured/keyword search only.`);
     }
     const t0 = timestamp();
     const hits = store.search({ criteria, queryEmbedding, limit });
@@ -550,10 +803,20 @@ async function runPresetSave(argv) {
         criteria = asJson;
     }
     else {
-        // Treat as natural language → structured (needs a provider key).
+        // Natural language → structured: provider key when present, else the
+        // local agent CLI (local-first), else the usual missing-key error.
         const provider = normalizeProvider(values.provider);
-        const apiKey = resolveProviderKey(provider, values);
-        criteria = await new ClipModelClient({ provider, apiKey }).naturalLanguageToCriteria(fromQuery);
+        const apiKey = resolveProviderKey(provider, values, { optional: true });
+        if (apiKey) {
+            criteria = await new ClipModelClient({ provider, apiKey }).naturalLanguageToCriteria(fromQuery);
+        }
+        else if (detectLocalAgent()) {
+            criteria = await new LocalAgentClipClient({}).naturalLanguageToCriteria(fromQuery);
+        }
+        else {
+            resolveProviderKey(provider, values); // throws the "No <provider> API key" error
+            throw new Error("unreachable");
+        }
     }
     const store = new ClipStore(values.home);
     const preset = store.savePreset({ name, criteria, description: values.description });

package/dist/src/devcli/speech.js

@@ -0,0 +1,175 @@
+// Local speech engine — devcli-only. `vidfarm tts` / `vidfarm stt` run
+// LOCAL-FIRST on the user's own AI key (GEMINI_API_KEY / OPENAI_API_KEY /
+// OPENROUTER_API_KEY, or the --gemini-key/--openai-key/--openrouter-key flags)
+// by calling the shared speech provider layer (src/services/speech.ts)
+// directly: local ffmpeg for the video→audio demux, the user's key for the
+// model call — no cloud job, no wallet, no REST route. The REST primitive
+// routes (/api/v1/primitives/audio/speech|transcribe) are the explicit
+// `--cloud` BACKUP, mirroring `vidfarm clips scan`.
+//
+// Unlike clip tagging, speech can NOT ride on a claude/codex CLI agent — the
+// agent CLIs have no audio I/O (the same reason embeddings need a real key in
+// local-agent.ts) — so "local" here means a raw provider key, not the agent.
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { buildSrtFromSegments, defaultSpeechModelFor, generateSpeechWithKey, transcribeSpeechWithKey } from "../services/speech.js";
+import { resolveFfmpeg } from "../services/clip-curation/ffmpeg.js";
+// Mirrors the env-var fallbacks used by `vidfarm clips` so one exported key
+// powers every local-first devcli surface.
+const PROVIDER_ENV = {
+    gemini: ["GEMINI_API_KEY", "GOOGLE_GENERATIVE_AI_API_KEY"],
+    openai: ["OPENAI_API_KEY"],
+    openrouter: ["OPENROUTER_API_KEY"]
+};
+const PROVIDER_FLAG = {
+    gemini: "gemini-key",
+    openai: "openai-key",
+    openrouter: "openrouter-key"
+};
+// Same inline-audio ceiling as the cloud stt primitive (~40min of 64kbps mono).
+export const MAX_LOCAL_TRANSCRIBE_AUDIO_BYTES = 20 * 1024 * 1024;
+/**
+ * Find a usable local provider key: an explicit --provider narrows the search,
+ * otherwise the first provider (in `preference` order) with a flag/env key
+ * wins. Returns null when nothing local is configured (callers point the user
+ * at env keys or --cloud).
+ */
+export function resolveLocalSpeechAuth(values, preference, requestedProvider) {
+    const providers = requestedProvider
+        ? [normalizeSpeechProvider(requestedProvider)]
+        : preference;
+    for (const provider of providers) {
+        const flagged = values[PROVIDER_FLAG[provider]];
+        if (typeof flagged === "string" && flagged.trim()) {
+            return { provider, apiKey: flagged.trim() };
+        }
+        for (const envName of PROVIDER_ENV[provider]) {
+            const fromEnv = process.env[envName]?.trim();
+            if (fromEnv) {
+                return { provider, apiKey: fromEnv };
+            }
+        }
+    }
+    return null;
+}
+export function normalizeSpeechProvider(value) {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "gemini" || normalized === "openai" || normalized === "openrouter") {
+        return normalized;
+    }
+    throw new Error(`Unsupported speech provider "${value}". Use gemini, openai, or openrouter.`);
+}
+/** Local TTS: text → audio bytes on the user's own key. */
+export async function localGenerateSpeech(input) {
+    const model = input.model?.trim() || defaultSpeechModelFor("tts", input.auth.provider);
+    if (!model) {
+        throw new Error(`No TTS model available for provider ${input.auth.provider}.`);
+    }
+    const result = await generateSpeechWithKey({
+        provider: input.auth.provider,
+        model,
+        text: input.text,
+        voice: input.voice,
+        instructions: input.instructions,
+        responseFormat: input.responseFormat,
+        apiKey: input.auth.apiKey
+    });
+    return { ...result, provider: input.auth.provider, model };
+}
+/** Local STT: audio bytes → transcript (diarized on gemini) on the user's own key. */
+export async function localTranscribeSpeech(input) {
+    const model = input.model?.trim() || defaultSpeechModelFor("stt", input.auth.provider);
+    if (!model) {
+        throw new Error(`No STT model available for provider ${input.auth.provider}.`);
+    }
+    const result = await transcribeSpeechWithKey({
+        provider: input.auth.provider,
+        model,
+        audio: input.audio,
+        contentType: input.contentType,
+        prompt: input.prompt,
+        language: input.language,
+        diarize: input.diarize,
+        apiKey: input.auth.apiKey
+    });
+    return { ...result, provider: input.auth.provider, model, srt: buildSrtFromSegments(result.segments) };
+}
+const AUDIO_EXTENSION_CONTENT_TYPES = {
+    mp3: "audio/mpeg",
+    wav: "audio/wav",
+    m4a: "audio/mp4",
+    aac: "audio/mp4",
+    ogg: "audio/ogg",
+    oga: "audio/ogg",
+    flac: "audio/flac"
+};
+function audioExtensionOf(target) {
+    const match = /\.(mp3|wav|m4a|aac|ogg|oga|flac)(\?|#|$)/i.exec(target);
+    return match ? match[1].toLowerCase() : null;
+}
+/**
+ * Turn a local path OR http(s) URL — video or audio — into speech-provider
+ * ready audio bytes. Plain audio files pass through untouched; everything else
+ * (video, unknown containers) is demuxed to small mono mp3 by LOCAL ffmpeg
+ * (bundled ffmpeg-static, or PATH), which reads URLs directly.
+ */
+export async function loadSpeechAudioLocally(target) {
+    const isUrl = /^https?:\/\//i.test(target);
+    if (!isUrl && !existsSync(target)) {
+        throw new Error(`No such local file: ${target}`);
+    }
+    const audioExtension = audioExtensionOf(target);
+    if (audioExtension) {
+        if (isUrl) {
+            const response = await fetch(target);
+            if (!response.ok) {
+                throw new Error(`Could not fetch source audio (${response.status}).`);
+            }
+            const contentType = response.headers.get("content-type")?.split(";")[0]?.trim() || AUDIO_EXTENSION_CONTENT_TYPES[audioExtension];
+            return { bytes: new Uint8Array(await response.arrayBuffer()), contentType, demuxed: false };
+        }
+        return { bytes: readFileSync(target), contentType: AUDIO_EXTENSION_CONTENT_TYPES[audioExtension], demuxed: false };
+    }
+    const ffmpeg = await resolveFfmpeg();
+    const tempDir = await mkdtemp(path.join(os.tmpdir(), "vidfarm-stt-"));
+    const outputPath = path.join(tempDir, "audio.mp3");
+    try {
+        await runFfmpegDemux(ffmpeg, target, outputPath);
+        return { bytes: await readFile(outputPath), contentType: "audio/mpeg", demuxed: true };
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true });
+    }
+}
+function runFfmpegDemux(bin, input, outputPath) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(bin, [
+            "-hide_banner",
+            "-y",
+            "-i", input,
+            "-vn",
+            "-ac", "1",
+            "-b:a", "64k",
+            outputPath
+        ], { stdio: ["ignore", "ignore", "pipe"] });
+        let stderr = "";
+        child.stderr.on("data", (chunk) => (stderr += chunk.toString()));
+        child.on("error", (error) => {
+            rejectPromise(error.code === "ENOENT"
+                ? new Error("ffmpeg not found. Install ffmpeg (or `npm i ffmpeg-static`), or run with --cloud to demux on the platform.")
+                : error);
+        });
+        child.on("close", (code) => {
+            if (code === 0) {
+                resolvePromise();
+            }
+            else {
+                rejectPromise(new Error(`ffmpeg demux exited ${code}: ${stderr.slice(-400)}`));
+            }
+        });
+    });
+}
+//# sourceMappingURL=speech.js.map