davinci-resolve-mcp 2.40.0 → 2.42.0

package/src/utils/media_analysis.py

@@ -2230,6 +2230,21 @@ def _read_json(path: str) -> Dict[str, Any]:
         return json.load(f)
 
 
+def _ingest_report_into_db(project_root: str, report: Dict[str, Any], clip_dir: Optional[str]) -> Dict[str, Any]:
+    """C1 — write a report into the DB-canonical store (rows in a transaction).
+
+    Best-effort by design: a DB failure must never break the analysis run,
+    because the JSON export still lands on disk and every reader falls back
+    to it. The failure is surfaced in the result for the caller to report.
+    """
+    try:
+        from src.utils import analysis_store
+
+        return analysis_store.ingest_report(project_root, report, clip_dir=clip_dir)
+    except Exception as exc:  # noqa: BLE001 — DB trouble must not kill analysis
+        return {"success": False, "error": f"{type(exc).__name__}: {exc}"}
+
+
 def _fraction_to_float(value: Any) -> Optional[float]:
     if value in (None, "", "0/0"):
         return None
@@ -4250,7 +4265,7 @@ def build_host_chat_paths_payload(
     if refusal is not None:
         return refusal
 
-    return {
+    payload: Dict[str, Any] = {
         "success": True,
         "status": "pending_host_analysis",
         "provider": HOST_CHAT_PATHS_PROVIDER,
@@ -4312,6 +4327,21 @@ def build_host_chat_paths_payload(
             "the clip's analysis directory; commit_vision finishes the run."
         ),
     }
+    # Phase B — deep depth: each shot_descriptions entry must additionally
+    # carry the per-shot field groups. The extra keys flow through
+    # commit_vision → canonical blob → subjective_fields rows unchanged.
+    if str(options.get("depth") or "").lower() == "deep":
+        from src.utils import deep_vision as _deep_vision
+
+        payload["deep_shot_schema"] = _deep_vision.deep_shot_schema()
+        payload["deep_schema_reference"] = _deep_vision.DEEP_SHOT_SCHEMA_REFERENCE
+        payload["instructions"] += (
+            " DEEP PASS: in addition to `description`, every shot_descriptions "
+            "entry MUST include the field groups in `deep_shot_schema` (visual, "
+            "content, production, editorial, cuttability, confidence), using the "
+            "enum values verbatim and 'unknown'/null when frame evidence is thin."
+        )
+    return payload
 
 
 def _vision_analysis(record: Dict[str, Any], motion: Dict[str, Any], options: Dict[str, Any], artifacts: Dict[str, Any], capabilities: Dict[str, Any]) -> Dict[str, Any]:
@@ -5081,6 +5111,9 @@ async def execute_plan_async(
         # Same for project_root — caps recording needs it to address the per-
         # project usage DB; falling back to the plan's output_root is fine.
         "project_root": params.get("project_root") or output_root,
+        # Phase B — depth threads into the vision payload builder so deep runs
+        # carry the per-shot field-group schema.
+        "depth": plan.get("depth", DEFAULT_DEPTH),
     }
     keep_frame_artifacts_for_vision = vision_uses_chat_context(options, caps)
     depth = plan.get("depth", DEFAULT_DEPTH)
@@ -5099,6 +5132,37 @@ async def execute_plan_async(
     }
     _write_json(os.path.join(output_root, "capabilities.json"), caps)
 
+    # Phase B — deep depth is opt-in with an explicit cost estimate first.
+    # The per-shot field-group pass multiplies vision spend, so the first call
+    # returns the estimate; re-call with confirm_deep=true to run. Caps still
+    # apply downstream — confirmation does not bypass budgets.
+    if (
+        depth == "deep"
+        and vision_uses_chat_context(options, caps)
+        and not _coerce_bool(params.get("confirm_deep") or params.get("confirmDeep"), default=False)
+    ):
+        executing = [
+            clip for clip in plan.get("clips", [])
+            if not (clip.get("skip_execution") and (clip.get("existing_report") or {}).get("path"))
+        ]
+        estimated_frames = sum(int(c.get("analysis_keyframe_budget") or 0) for c in executing)
+        return {
+            "success": True,
+            "status": "confirmation_required",
+            "reason": "deep_depth_cost_estimate",
+            "estimate": {
+                "clip_count": len(executing),
+                "estimated_frames": estimated_frames,
+                "estimated_vision_tokens": estimated_frames * AVG_VISION_TOKENS_PER_FRAME,
+                "tokens_per_frame_assumption": AVG_VISION_TOKENS_PER_FRAME,
+            },
+            "note": (
+                "Deep analysis fills per-shot Visual/Content/Editorial field groups "
+                "and costs vision tokens accordingly. Re-call the same analyze action "
+                "with confirm_deep=true to proceed, or drop depth to 'standard'."
+            ),
+        }
+
     for clip_plan in plan.get("clips", []):
         record = clip_plan["record"]
         artifacts = clip_plan["artifacts"]
@@ -5199,6 +5263,15 @@ async def execute_plan_async(
         if vision_pending:
             analysis["vision_status"] = "pending_host_analysis"
             analysis["vision_token"] = vision.get("vision_token")
+        # C1 — DB rows first (canonical), then the derived JSON export. The DB
+        # lives under output_root (same root as clips/), not the caps root.
+        db_ingest = _ingest_report_into_db(
+            output_root,
+            analysis,
+            os.path.dirname(artifacts["analysis_json"]),
+        )
+        if not db_ingest.get("success"):
+            clip_result["db_ingest_error"] = db_ingest.get("error")
         _write_json(artifacts["analysis_json"], analysis)
         cleanup_frames_requested = _coerce_bool(params.get("cleanup_frames"), default=False)
         if cleanup_frames_requested and not vision_pending and artifacts.get("frames_dir"):
@@ -5773,6 +5846,8 @@ def commit_visual_analysis(
     report.pop("vision_status", None)
     report.pop("vision_token", None)
     report["vision_committed_at"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+    # C1 — DB rows first (canonical), then the derived JSON export.
+    db_ingest = _ingest_report_into_db(root, report, clip_dir_path)
     _write_json(analysis_json_path, report)
 
     index_status_info: Dict[str, Any] = {}
@@ -5813,6 +5888,7 @@ def commit_visual_analysis(
         "index": index_status_info,
         "analysis_registry": registry_status,
         "corrections": corrections_metrics,
+        "db_ingest": db_ingest,
     })
 
 

package/src/utils/timeline_brain_db.py

@@ -29,7 +29,7 @@ from typing import Callable, Dict, Iterator, Optional, Tuple
 
 logger = logging.getLogger("resolve-mcp.timeline-brain-db")
 
-SCHEMA_VERSION = 8
+SCHEMA_VERSION = 9
 DB_FILENAME = "timeline_brain.sqlite"
 SOUL_DIRNAME = "_soul"
 
@@ -509,6 +509,184 @@ def _migrate_v5_analysis_token_usage(conn: sqlite3.Connection) -> None:
     )
 
 
+@register_migration(9)
+def _migrate_v9_analysis_core(conn: sqlite3.Connection) -> None:
+    """C1 — DB-canonical clip analysis (Phase A of the analysis/edit-engine program).
+
+    The DB becomes the source of truth for clip analysis; analysis.json becomes
+    a derived export written in lockstep. Shape is hybrid: a canonical
+    full-report blob per clip (`analysis_reports`) plus normalized tables for
+    what downstream phases query (shots, subjective fields with per-field
+    provenance, transcript segments, sampled frames, QC observations).
+    Computed layers (technical/motion/cuts/audio) stay inside the blob — they
+    re-derive cleanly from source media and nothing queries them row-wise.
+    """
+    conn.executescript(
+        """
+        CREATE TABLE IF NOT EXISTS clips (
+            clip_uuid TEXT PRIMARY KEY,          -- rename-stable canonical hash (12-hex)
+            clip_dir TEXT,                       -- report folder name under clips/
+            resolve_clip_id TEXT,
+            media_id TEXT,
+            clip_name TEXT,
+            file_path TEXT,
+            bin_path TEXT,
+            duration_seconds REAL,
+            fps REAL,
+            resolution TEXT,
+            media_type TEXT,
+            summary TEXT,
+            overall_motion_level TEXT,
+            cut_count INTEGER,
+            shot_count INTEGER,
+            analysis_version TEXT,
+            depth TEXT,
+            signature_hash TEXT,
+            analyzed_at TEXT,
+            vision_status TEXT,
+            vision_committed_at TEXT,
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL
+        );
+
+        CREATE INDEX IF NOT EXISTS ix_clips_clip_name ON clips(clip_name);
+        CREATE INDEX IF NOT EXISTS ix_clips_file_path ON clips(file_path);
+
+        -- Every stable id a clip is known by (legacy hashes, clip_id, media_id,
+        -- folder hash, normalized file path) → clip_uuid. Lookup table only.
+        CREATE TABLE IF NOT EXISTS clip_aliases (
+            alias TEXT NOT NULL,
+            clip_uuid TEXT NOT NULL,
+            kind TEXT,
+            PRIMARY KEY (alias, clip_uuid)
+        );
+
+        CREATE INDEX IF NOT EXISTS ix_clip_aliases_clip ON clip_aliases(clip_uuid);
+
+        -- Canonical full analysis payload. analysis.json is exported FROM this.
+        CREATE TABLE IF NOT EXISTS analysis_reports (
+            clip_uuid TEXT PRIMARY KEY,
+            report_json TEXT NOT NULL,
+            signature_hash TEXT,
+            analyzed_at TEXT,
+            written_at TEXT NOT NULL,
+            FOREIGN KEY (clip_uuid) REFERENCES clips(clip_uuid) ON DELETE CASCADE
+        );
+
+        CREATE TABLE IF NOT EXISTS shots (
+            shot_uuid TEXT PRIMARY KEY,          -- short_hash(clip_uuid + rounded time region)
+            clip_uuid TEXT NOT NULL,
+            shot_index INTEGER NOT NULL,
+            time_seconds_start REAL,
+            time_seconds_end REAL,
+            description TEXT,
+            qc_flags_json TEXT,
+            frame_indices_json TEXT,
+            extra_json TEXT,                     -- forward-compat: any other shot keys
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL,
+            UNIQUE(clip_uuid, shot_index),
+            FOREIGN KEY (clip_uuid) REFERENCES clips(clip_uuid) ON DELETE CASCADE
+        );
+
+        CREATE INDEX IF NOT EXISTS ix_shots_clip ON shots(clip_uuid, shot_index);
+
+        -- Per-field provenance for subjective (vision/human) values.
+        -- Current value = the row with superseded_at IS NULL.
+        CREATE TABLE IF NOT EXISTS subjective_fields (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            entity_type TEXT NOT NULL CHECK(entity_type IN ('clip', 'shot')),
+            entity_uuid TEXT NOT NULL,
+            field_path TEXT NOT NULL,
+            value_json TEXT NOT NULL,
+            confidence TEXT,
+            source TEXT NOT NULL,                -- 'vision_v0.2' | 'human' | ...
+            source_model TEXT,
+            author TEXT NOT NULL,
+            timestamp TEXT NOT NULL,
+            superseded_at TEXT
+        );
+
+        CREATE INDEX IF NOT EXISTS ix_sf_entity
+            ON subjective_fields(entity_type, entity_uuid, field_path);
+        CREATE INDEX IF NOT EXISTS ix_sf_current
+            ON subjective_fields(entity_type, entity_uuid, field_path)
+            WHERE superseded_at IS NULL;
+
+        CREATE TABLE IF NOT EXISTS field_changelog (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            entity_type TEXT NOT NULL,
+            entity_uuid TEXT NOT NULL,
+            field_path TEXT NOT NULL,
+            previous_value_json TEXT,
+            new_value_json TEXT NOT NULL,
+            previous_source TEXT,
+            new_source TEXT NOT NULL,
+            previous_author TEXT,
+            new_author TEXT NOT NULL,
+            change_reason TEXT,
+            timestamp TEXT NOT NULL
+        );
+
+        CREATE INDEX IF NOT EXISTS ix_changelog_entity
+            ON field_changelog(entity_type, entity_uuid, timestamp);
+
+        CREATE TABLE IF NOT EXISTS transcript_segments (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            clip_uuid TEXT NOT NULL,
+            segment_index INTEGER NOT NULL,
+            start_seconds REAL,
+            end_seconds REAL,
+            text TEXT,
+            speaker_id TEXT,
+            UNIQUE(clip_uuid, segment_index),
+            FOREIGN KEY (clip_uuid) REFERENCES clips(clip_uuid) ON DELETE CASCADE
+        );
+
+        CREATE INDEX IF NOT EXISTS ix_transcript_segments_clip
+            ON transcript_segments(clip_uuid, start_seconds);
+
+        CREATE TABLE IF NOT EXISTS frames (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            clip_uuid TEXT NOT NULL,
+            shot_uuid TEXT,
+            frame_index INTEGER NOT NULL,
+            time_seconds REAL,
+            frame_path TEXT,
+            selection_reason TEXT,
+            motion_peak INTEGER NOT NULL DEFAULT 0,
+            UNIQUE(clip_uuid, frame_index),
+            FOREIGN KEY (clip_uuid) REFERENCES clips(clip_uuid) ON DELETE CASCADE
+        );
+
+        CREATE INDEX IF NOT EXISTS ix_frames_clip ON frames(clip_uuid, frame_index);
+        CREATE INDEX IF NOT EXISTS ix_frames_shot ON frames(shot_uuid);
+
+        CREATE TABLE IF NOT EXISTS qc_observations (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            clip_uuid TEXT NOT NULL,
+            shot_uuid TEXT,
+            observation_type TEXT NOT NULL,
+            severity TEXT NOT NULL DEFAULT 'info',
+            message TEXT NOT NULL,
+            related_shot_indices_json TEXT,
+            confidence TEXT,
+            source TEXT NOT NULL,
+            resolved INTEGER NOT NULL DEFAULT 0,
+            resolved_by TEXT,
+            resolved_at TEXT,
+            resolution_note TEXT,
+            created_at TEXT NOT NULL,
+            FOREIGN KEY (clip_uuid) REFERENCES clips(clip_uuid) ON DELETE CASCADE
+        );
+
+        CREATE INDEX IF NOT EXISTS ix_qc_clip ON qc_observations(clip_uuid);
+        CREATE INDEX IF NOT EXISTS ix_qc_unresolved
+            ON qc_observations(clip_uuid, resolved) WHERE resolved = 0;
+        """
+    )
+
+
 def latest_version(conn: sqlite3.Connection, timeline_name: str) -> Optional[int]:
     """Return the highest archived version number for `timeline_name`, or None."""
     row = conn.execute(