davinci-resolve-mcp 2.43.0 → 2.45.0

package/CHANGELOG.md

@@ -2,6 +2,73 @@
 
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
 
+## What's New in v2.45.0
+
+The edit engine — Phase E, the final phase of the analysis + edit-engine
+program. Three evidence-driven loops on one shared skeleton: evidence query
+→ dry-run plan with per-decision rationale → confirm token → versioned
+timeline ops → metric readback → brain_edits rows.
+
+- **Added** a new `edit_engine` MCP tool (compound tool count: 34):
+  - `plan_selects` / `execute_selects` — ranks shots by deep-tier
+    `editorial.select_potential` and best moments (clip-level fallback for
+    standard-analyzed clips), story-spine order, duration budget; execution
+    builds a NEW selects timeline from per-shot source ranges. Additive.
+  - `plan_tighten` / `execute_tighten` — dead-air lifts from transcript-gap
+    evidence per timeline item (no transcript → reported in `skipped`,
+    never silently trimmed); execution assembles a tightened VARIANT
+    timeline from keep ranges (true partial trims via the range-copy
+    kernel) — the original timeline is never mutated.
+  - `plan_swap` / `execute_swap` — alternates for a timeline item via the
+    visual-similarity index, filtered to shots that can fill the slot
+    exactly; execution replaces the item in place (lift + positioned
+    append) on the version-archived timeline.
+  - `list_plans` / `get_plan` — plans persist under `memory/edit_plans/`
+    with content fingerprints; a stale or tampered plan refuses to execute.
+- **Added** `src/utils/edit_engine.py` (DB-only planning/evidence layer) and
+  `tests/live_edit_engine_validation.py` (disposable-project live harness).
+  execute_* actions are confirm-token gated and registered with the
+  version-on-mutate hook (archive + brain_edits come from the same
+  machinery as every other destructive op).
+- **Fixed** frame→shot mapping in the analysis store: frames now fall back
+  to time-containment when a report's shots don't record
+  `frame_indices_used` (commit paths that omit it previously produced no
+  shot-level visual vectors).
+- **Validation**: full offline suite (1118 tests; 13 new). Live pilot on a
+  disposable synthetic-media Resolve project (ffmpeg + spoken audio):
+  20/20 checks — selects timeline assembled (2 decisions), tighten variant
+  removed exactly the 15.2s of transcript dead air while keeping the
+  spoken 4.8s (original untouched), swap replaced the item with a 0.92
+  cosine alternate, brain_edits rationale rows present for all three
+  loops, timeline versions archived.
+
+## What's New in v2.44.0
+
+Cross-clip entities + bin briefing v2 — Phase D of the analysis +
+edit-engine program. Recurring people/places/props found by clustering the
+visual embeddings, confirmed with one vision call per cluster.
+
+- **Added** schema v11 (`entities` + `entity_appearances`) and
+  `src/utils/entities.py`: union-find clustering over the v10 CLIP frame
+  vectors (cosine threshold, no new deps), representative-frame selection,
+  ghost pruning across re-runs (labeled entities persist), and a
+  detection-state stash so `entity_index` always resolves against the exact
+  ordering the payload was issued with.
+- **Added** `media_analysis` actions: `detect_entities` (clusters + deferred
+  one-frame-per-cluster confirmation payload, caps pre-checked),
+  `commit_entities` (kind/label/description with conservative-label rules;
+  `merge_with` collapses duplicate clusters), `list_entities`,
+  `prepare_bin_briefing` (entities + per-clip summaries, text-only), and
+  `commit_bin_summary` (host-synthesized briefing written above the v2.0
+  aggregate in `memory/bin_summary.md`).
+- **Added** a "Recurring across this bin" card on the panel's Review page
+  (`/api/entities`), shown once labeled entities exist.
+- **Validation**: full offline suite (1105 tests; 10 new). Live on the real
+  sample root: 3 clusters detected from 16 CLIP vectors; host-chat
+  confirmation labeled the shattered-windshield POV and the white rental
+  sedan and merged the sedan's two clusters; bin briefing synthesized and
+  committed; panel card verified and screenshots regenerated.
+
 ## What's New in v2.43.0
 
 Embeddings + similarity search — Phase C of the analysis + edit-engine

package/README.md

@@ -1,9 +1,9 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.43.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.45.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
-[![Tools](https://img.shields.io/badge/MCP%20Tools-33%20(341%20full)-blue.svg)](#server-modes)
+[![Tools](https://img.shields.io/badge/MCP%20Tools-34%20(341%20full)-blue.svg)](#server-modes)
 [![Tested](https://img.shields.io/badge/Live%20Tested-98.5%25-green.svg)](docs/reference/api-coverage.md#test-results)
 [![DaVinci Resolve](https://img.shields.io/badge/DaVinci%20Resolve-18.5+-darkred.svg)](https://www.blackmagicdesign.com/products/davinciresolve)
 [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
@@ -49,7 +49,7 @@ The command starts a localhost server and opens the control panel in your browse
 
 | Mode | Entry point | Tools | Best for |
 |------|-------------|-------|----------|
-| Compound | `src/server.py` | 33 | Default mode for most assistants. Related Resolve operations are grouped behind action parameters to keep context usage low. |
+| Compound | `src/server.py` | 34 | Default mode for most assistants. Related Resolve operations are grouped behind action parameters to keep context usage low. |
 | Full / granular | `src/server.py --full` or `src/resolve_mcp_server.py` | 341 | Power users who want one MCP tool per Resolve API method. |
 
 The compound server is recommended unless you specifically need the granular one-tool-per-method surface.

package/docs/SKILL.md

@@ -496,7 +496,27 @@ Key actions: `capabilities`, `install_guidance`, `resolve_output_root`, `plan`,
 `set_panel_state`, `session_start_context`, `update_clip_field`,
 `update_shot_field`, `get_field_history`, `revert_field`,
 `list_corrections`, `deepen`, `commit_shot_vision`, `vision_pending_sweep`,
-`build_embeddings`, and `find_similar`.
+`build_embeddings`, `find_similar`, `detect_entities`, `commit_entities`,
+`list_entities`, `prepare_bin_briefing`, and `commit_bin_summary`.
+
+**Cross-clip entities + bin briefing v2 (v2.44.0+).** Recurring
+people/places/props across a project's media, found cheaply and confirmed
+with ONE vision call per cluster:
+- `detect_entities(threshold?, min_cluster_size?)` clusters the v10 CLIP
+  frame vectors (build visual embeddings first), writes provisional entity
+  rows + appearances, and returns a deferred payload with one
+  representative frame per cluster (caps pre-checked, estimate inlined).
+  The host chat reads those frames and calls
+  `commit_entities(entities=[{entity_index, kind, label, description,
+  confidence, merge_with?}], vision_token)` — conservative labels only
+  (describe what's visible; never guess names). `merge_with` collapses
+  clusters that show the same entity.
+- `list_entities` returns labeled entities with per-clip/shot appearances;
+  the panel's Review page shows a "Recurring across this bin" card.
+- `prepare_bin_briefing` returns entities + per-clip summaries (text-only,
+  no vision cost); the host writes a colleague-style markdown briefing and
+  calls `commit_bin_summary(briefing, briefing_token)`, which lands in
+  `memory/bin_summary.md` above the v2.0 aggregate.
 
 **Embeddings + similarity (v2.43.0+).** Local-compute semantic search; no
 vendor tokens, so nothing here touches the caps ledger. Backends are
@@ -651,6 +671,41 @@ only when that mutation is intentional.
 
 ### Timelines
 
+**`edit_engine`** — Evidence-driven edit loops (v2.45.0+): selects assembly,
+tighten, swap.
+
+Every loop is plan → confirm → execute. plan_* actions are dry-run by
+construction: they query the DB-canonical analysis store and return a
+per-decision rationale plus a stored `plan_id` (plans persist under
+`memory/edit_plans/` with a content fingerprint, so a stale plan cannot run
+against a changed project). execute_* actions require a `confirm_token`, run
+under the version-on-mutate hook, and return before/after duration and
+clip-count readback plus `brain_edits` rationale rows.
+
+- `plan_selects(min_select_potential?, max_duration_seconds?, max_shots?,
+  timeline_name?, analysis_root?)` — ranks shots by deep-tier
+  `editorial.select_potential` / best moments (clip-level fallback for
+  standard-analyzed clips), story-spine order.
+  `execute_selects(plan_id)` creates a NEW selects timeline from the plan's
+  per-shot source ranges — additive; nothing existing is touched.
+- `plan_tighten(timeline_name?, target_ratio?, min_pause_seconds?,
+  handle_seconds?)` — dead-air lifts from transcript-gap evidence for each
+  timeline item (items without transcripts are reported in `skipped`, never
+  silently trimmed). `execute_tighten(plan_id)` assembles a tightened
+  VARIANT timeline from the plan's keep ranges — true partial trims; the
+  original timeline is never mutated.
+- `plan_swap(timeline_start_frame | item_name, kind="visual"|"text",
+  limit?)` — alternates for one timeline item via the similarity index,
+  filtered to shots long enough to fill the slot exactly.
+  `execute_swap(plan_id, alternate_index)` replaces the item in place
+  (lift + positioned append at the same record frame) on the
+  version-archived timeline.
+- `list_plans(limit?)` / `get_plan(plan_id)`.
+
+The engine needs the analysis substrate: analyzed clips in the DB (run
+`db_ingest` on older roots), transcripts for tighten, and visual embeddings
+(`build_embeddings(kinds=['visual'])`) for swap.
+
 **`timeline_versioning`** — Version-on-mutate, archive, rollback, brain-edit history (C6).
 
 Every destructive timeline op (compound, captions, ripple delete, gap close,

package/docs/guides/control-panel.md

@@ -82,7 +82,10 @@ transcripts once the search index is built. When a local text-embedding
 backend is detected (ollama with `nomic-embed-text`, or
 sentence-transformers), a `Semantic` toggle appears next to the search box —
 it searches by meaning instead of exact words, ranking clips, shots, and
-transcript lines by similarity to your query.
+transcript lines by similarity to your query. Once cross-clip entity
+detection has run (`detect_entities` + a one-frame-per-cluster confirmation
+in chat), a `Recurring across this bin` card lists the labeled people,
+places, and objects with their shot counts.
 
 ### Clip detail
 

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.43.0"
+VERSION = "2.45.0"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.43.0",
+  "version": "2.45.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/analysis_dashboard.py

@@ -2114,6 +2114,30 @@ HTML = r"""<!doctype html>
       margin-bottom: var(--space-3);
       flex-wrap: wrap;
     }
+    .review-semantic-toggle {
+      display: inline-flex;
+      gap: 6px;
+      align-items: center;
+      color: var(--text-secondary);
+      font-size: var(--ops-text-label);
+      white-space: nowrap;
+    }
+    .review-entities {
+      margin-bottom: var(--space-3);
+      padding: var(--space-2) var(--space-3);
+      border: 1px solid var(--border-default);
+      border-radius: var(--radius-md);
+    }
+    .review-entities-title {
+      color: var(--text-secondary);
+      font-size: var(--ops-text-label);
+      margin-bottom: 6px;
+    }
+    .review-entities-chips {
+      display: flex;
+      gap: var(--space-2);
+      flex-wrap: wrap;
+    }
     .review-bin-filters input[type="search"] {
       flex: 1 1 280px;
       min-width: 200px;
@@ -4077,6 +4101,7 @@ HTML = r"""<!doctype html>
           </div>
         </div>
         <div id="reviewBinSummary" class="review-bin-summary">Loading analyzed clips…</div>
+        <div id="reviewEntitiesCard" class="review-entities" style="display:none"></div>
         <div id="reviewBinGrid" class="review-grid"></div>
         <div id="reviewSearchResults" class="review-search-results" style="display:none"></div>
       </div>
@@ -8093,6 +8118,22 @@ HTML = r"""<!doctype html>
       renderReviewBin();
       // Coverage runs in parallel — failures here must not block the clip grid.
       refreshReadinessCard().catch(() => {});
+      refreshEntitiesCard().catch(() => {});
+    }
+
+    // Recurring people/places/props detected across the bin (Phase D).
+    // Hidden until at least one labeled entity exists.
+    async function refreshEntitiesCard() {
+      const card = $('reviewEntitiesCard');
+      if (!card) return;
+      const data = await api('/api/entities').catch(() => null);
+      const labeled = (data?.entities || []).filter(e => e.label);
+      if (!labeled.length) { card.style.display = 'none'; return; }
+      card.style.display = '';
+      card.innerHTML = `<div class="review-entities-title">Recurring across this bin</div>
+        <div class="review-entities-chips">${labeled.map(e =>
+          `<span class="review-chip" title="${escapeHtml(e.description || '')}">${escapeHtml(e.label)} · ${e.kind || 'unknown'} · ${e.shot_count || e.cluster_size || 0} shots</span>`
+        ).join('')}</div>`;
     }
 
     async function refreshReadinessCard() {
@@ -14386,6 +14427,14 @@ class Handler(BaseHTTPRequestHandler):
                 payload["results"] = _v2_enrich_search_results(self.state.project_root, payload["results"])
             self._json(payload)
             return
+        if path == "/api/entities":
+            try:
+                from src.utils import entities as _entities
+
+                self._json(_entities.list_entities(self.state.project_root))
+            except Exception as exc:  # noqa: BLE001 — panel reads fail soft
+                self._json({"success": False, "error": f"{type(exc).__name__}: {exc}"})
+            return
         if path == "/api/search/semantic":
             q = (query.get("q") or [""])[0]
             try:

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.43.0"
+VERSION = "2.45.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")