Skip to content

World's first open-source, agentic video production system. 12 production pipelines, 100+ tools, 700+ agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.

Add documentary-montage pipeline for retrieval-first motion-clip montage

calesthio44baede67fbb
diff --git a/README.md b/README.md
index 0a830932..ab99259e 100644
--- a/README.md
+++ b/README.md
@@ -248,6 +248,7 @@ Each pipeline is a complete production workflow, from idea to finished video.
| **Avatar Spokesperson** | Avatar-driven presenter videos | Corporate comms, training, announcements |
| **Cinematic** | Trailer, teaser, and mood-driven edits | Brand films, teasers, promotional content |
| **Clip Factory** | Batch of ranked short-form clips from one long source | Repurposing long content for social media |
+| **Documentary Montage** | Thematic montage cut from a CLIP-indexed corpus of free stock footage (Pexels, Archive.org, NASA) | Video essays, mood pieces, retrieval-first B-roll edits |
| **Hybrid** | Source footage + AI-generated support visuals | Enhancing existing footage with graphics |
| **Localization & Dub** | Subtitle, dub, and translate existing video | Multi-language distribution |
| **Podcast Repurpose** | Podcast highlights to video | Podcast marketing, audiogram videos |
@@ -272,7 +273,7 @@ Most AI video tools give you a single clip from a prompt. OpenMontage gives you
Edit your own talking-head footage. Generate a fully animated explainer from scratch. Cut a 2-hour podcast into a dozen social clips. Translate and dub your content into 10 languages. Build a cinematic brand teaser from stock footage and AI-generated scenes. **If a production team can make it, OpenMontage can orchestrate it.**
-- **11 production pipelines** — explainers, talking heads, screen demos, cinematic trailers, animations, podcasts, localization, and more
+- **12 production pipelines** — explainers, talking heads, screen demos, cinematic trailers, animations, podcasts, localization, documentary montages, and more
- **52 production tools** — spanning video generation, image creation, text-to-speech, music, audio mixing, subtitles, enhancement, and analysis
- **400+ agent skills** — production skills, pipeline directors, creative techniques, quality checklists, and deep technology knowledge packs that teach the agent how to use every tool like an expert
- **Reference-driven creation** — paste a video you like and the agent turns it into a grounded, differentiated production plan instead of forcing you to invent the perfect prompt from scratch
diff --git a/lib/clip_embedder.py b/lib/clip_embedder.py
new file mode 100644
index 00000000..b9ee82eb
--- /dev/null
+++ b/lib/clip_embedder.py
@@ -0,0 +1,136 @@
+"""CLIP embedder: thin wrapper around openai/clip-vit-base-patch32 for
+corpus indexing and text-to-visual similarity ranking.
+
+Design notes
+------------
+This module intentionally does ONE thing: turn images and text into
+normalised 512-d float32 vectors that can be cosine-compared.
+
+- Single shared model instance, lazy-loaded on first call, so the 350 MB
+ weights only load once per process regardless of how many places in
+ the codebase embed something.
+- CPU by default, GPU if available. The ViT-B/32 variant runs at
+ ~150-300 ms per image on a modern CPU — fast enough for corpora of
+ a few hundred candidates without needing FAISS.
+- Output vectors are L2-normalised so cosine similarity reduces to a
+ dot product — downstream code can `embeddings @ query_vec.T` and
+ interpret it as cosine similarity directly.
+- Batched at the caller's request count; no internal mini-batching.
+ For corpora > a few hundred items, the caller should chunk.
+
+This file does NOT decide what to embed or how to use the embeddings.
+That intelligence lives in the corpus manager and retrieval skills.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable, Sequence, Union
+
+import numpy as np
+
+# Import heavy deps lazily inside methods so importing this module does
+# not pull torch/transformers unless someone actually uses it.
+
+
+_MODEL = None
+_PROCESSOR = None
+_DEVICE: str = "cpu"
+_MODEL_ID = "openai/clip-vit-base-patch32"
+
+
+def _load() -> None:
+ """Load CLIP model and processor exactly once per process."""
+ global _MODEL, _PROCESSOR, _DEVICE
+ if _MODEL is not None:
+ return
+ import torch # type: ignore
+ from transformers import CLIPModel, CLIPProcessor # type: ignore
+
+ _DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
+ _PROCESSOR = CLIPProcessor.from_pretrained(_MODEL_ID)
+ _MODEL = CLIPModel.from_pretrained(_MODEL_ID).to(_DEVICE)
+ _MODEL.eval()
+
+
+def model_info() -> dict:
+ """Return metadata about the loaded model (for index provenance)."""
+ return {
+ "model_id": _MODEL_ID,
+ "device": _DEVICE,
+ "dim": 512,
+ }
+
+
+def embed_images(image_paths: Sequence[Union[str, Path]]) -> np.ndarray:
+ """Embed a list of image files into a (N, 512) float32 matrix.
+
+ Each row is L2-normalised.
+ """
+ if not image_paths:
+ return np.zeros((0, 512), dtype=np.float32)
+
+ import torch # type: ignore
+ from PIL import Image # type: ignore
+
+ _load()
+ assert _MODEL is not None and _PROCESSOR is not None
+
+ images = []
+ for p in image_paths:
+ img = Image.open(str(p)).convert("RGB")
+ images.append(img)
+
+ inputs = _PROCESSOR(images=images, return_tensors="pt").to(_DEVICE)
+ with torch.no_grad():
+ features = _MODEL.get_image_features(**inputs)
+ features = features / features.norm(dim=-1, keepdim=True).clamp_min(1e-8)
+ arr = features.cpu().numpy().astype(np.float32, copy=False)
+ # Close PIL handles to avoid leaking file handles on Windows
+ for img in images:
+ img.close()
+ return arr
+
+
+def embed_texts(texts: Sequence[str]) -> np.ndarray:
+ """Embed a list of text strings into a (N, 512) float32 matrix.
+
+ Each row is L2-normalised.
+ """
+ if not texts:
+ return np.zeros((0, 512), dtype=np.float32)
+
+ import torch # type: ignore
+
+ _load()
+ assert _MODEL is not None and _PROCESSOR is not None
+
+ # Empty strings break the processor — substitute a placeholder so
+ # the alignment with caller indices stays intact.
+ safe_texts = [t if t and t.strip() else "untitled" for t in texts]
+
+ inputs = _PROCESSOR(
+ text=safe_texts,
+ return_tensors="pt",
+ padding=True,
+ truncation=True,
+ max_length=77,
+ ).to(_DEVICE)
+ with torch.no_grad():
+ features = _MODEL.get_text_features(**inputs)
+ features = features / features.norm(dim=-1, keepdim=True).clamp_min(1e-8)
+ return features.cpu().numpy().astype(np.float32, copy=False)
+
+
+def pool_frames(frame_embeddings: np.ndarray) -> np.ndarray:
+ """Average a (K, 512) stack of frame embeddings into a (512,) clip vector.
+
+ Re-normalises after the mean. This is the simplest temporal pooling
+ that still respects the L2 assumption the rest of the pipeline makes.
+ """
+ if frame_embeddings.size == 0:
+ return np.zeros(512, dtype=np.float32)
+ mean = frame_embeddings.mean(axis=0)
+ norm = np.linalg.norm(mean)
+ if norm < 1e-8:
+ return np.zeros(512, dtype=np.float32)
+ return (mean / norm).astype(np.float32, copy=False)
diff --git a/lib/corpus.py b/lib/corpus.py
new file mode 100644
index 00000000..4aefd52b
--- /dev/null
+++ b/lib/corpus.py
@@ -0,0 +1,424 @@
+"""Local clip corpus: project-scoped index of candidate video/image assets.
+
+The corpus is the heart of the documentary-montage pipeline. Instead of
+hitting stock APIs every time the agent changes its mind, we download
+once into a project-local corpus and query it offline.
+
+Directory layout
+----------------
+ <corpus_dir>/
+ clips/ # downloaded assets, named <clip_id>.<ext>
+ thumbnails/
+ <clip_id>/
+ frame_00.jpg # 5 evenly-spaced frames per video (or the
+ frame_01.jpg # image itself as frame_00 for still assets)
+ ...
+ embeddings.npy # (N, 512) float32, L2-normalised visual
+ tag_embeddings.npy # (N, 512) float32, L2-normalised text
+ index.jsonl # one row per clip, metadata + provenance
+
+The JSONL + .npy split is intentional: the index is human-readable
+(git-diffable, debuggable) while the embeddings are a contiguous array
+for fast vector math. Row N in the JSONL aligns with row N in both .npy
+files.
+
+The Corpus class owns add/load/save + all retrieval math. It's pure
+infrastructure — no judgment calls, no creative decisions. The agent
+picks WHAT to search for and WHICH results to accept; this class only
+implements the operations the agent names.
+"""
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Iterable, Optional
+
+import numpy as np
+
+
+EMBED_DIM = 512
+
+
+@dataclass
+class ClipRecord:
+ """One row in the corpus index.
+
+ Fields mirror everything we want to query or attribute. Missing
+ fields default to None/empty so adapters can populate only what
+ they know.
+ """
+ clip_id: str # unique within corpus: "<source>_<source_id>"
+ source: str # "pexels", "archive_org", "nasa", ...
+ source_id: str
+ source_url: str
+ local_path: str # relative to corpus_dir
+ kind: str = "video" # "video" or "image"
+ thumb_dir: str = "" # relative to corpus_dir
+ query: str = "" # the search query that surfaced this clip
+ creator: str = ""
+ license: str = ""
+ duration: float = 0.0 # seconds (0 for images)
+ width: int = 0
+ height: int = 0
+ motion_score: float = 0.0 # residual optical flow magnitude
+ dominant_colors: list[list[int]] = field(default_factory=list)
+ source_tags: str = "" # raw tags/description from the API
+ shot_type: str = "" # wide/medium/close (optional, may be empty)
+ time_of_day: str = "" # day/golden/night (optional)
+ added_at: float = 0.0 # unix timestamp
+
+
+class Corpus:
+ """Append-only local clip corpus with vector search.
+
+ Usage::
+
+ corp = Corpus(Path("projects/foo/corpus"))
+ corp.load()
+ corp.add(record, clip_embedding, tag_embedding)
+ corp.save()
+ ranked = corp.rank_by_text("a lonely figure walking home")
+ neighbours = corp.knn(clip_id="pexels_12345", k=5)
+
+ Append-only is by design — deleting rows would break the row-to-
+ embedding alignment. The agent hides a clip by filtering at query
+ time, not by removing it from the corpus.
+ """
+
+ def __init__(self, corpus_dir: Path):
+ self.corpus_dir = Path(corpus_dir)
+ self.records: list[ClipRecord] = []
+ self.clip_embeddings: np.ndarray = np.zeros((0, EMBED_DIM), dtype=np.float32)
+ self.tag_embeddings: np.ndarray = np.zeros((0, EMBED_DIM), dtype=np.float32)
+ self._id_to_row: dict[str, int] = {}
+
+ # ------------------------------------------------------------------
+ # Paths
+ # ------------------------------------------------------------------
+
+ @property
+ def clips_dir(self) -> Path:
+ return self.corpus_dir / "clips"
+
+ @property
+ def thumbs_dir(self) -> Path:
+ return self.corpus_dir / "thumbnails"
+
+ @property
+ def index_path(self) -> Path:
+ return self.corpus_dir / "index.jsonl"
+
+ @property
+ def embed_path(self) -> Path:
+ return self.corpus_dir / "embeddings.npy"
+
+ @property
+ def tag_embed_path(self) -> Path:
+ return self.corpus_dir / "tag_embeddings.npy"
+
+ def ensure_dirs(self) -> None:
+ self.corpus_dir.mkdir(parents=True, exist_ok=True)
+ self.clips_dir.mkdir(exist_ok=True)
+ self.thumbs_dir.mkdir(exist_ok=True)
+
+ # ------------------------------------------------------------------
+ # Persistence
+ # ------------------------------------------------------------------
+
+ def load(self) -> None:
+ """Load existing corpus from disk. Silently starts empty if absent."""
+ self.records = []
+ self._id_to_row = {}
+ if self.index_path.is_file():
+ with open(self.index_path, encoding="utf-8") as f:
+ for i, line in enumerate(f):
+ line = line.strip()
+ if not line:
+ continue
+ data = json.loads(line)
+ rec = ClipRecord(**data)
+ self.records.append(rec)
+ self._id_to_row[rec.clip_id] = i
+
+ if self.embed_path.is_file():
+ self.clip_embeddings = np.load(self.embed_path)
+ else:
+ self.clip_embeddings = np.zeros((0, EMBED_DIM), dtype=np.float32)
+
+ if self.tag_embed_path.is_file():
+ self.tag_embeddings = np.load(self.tag_embed_path)
+ else:
+ self.tag_embeddings = np.zeros((0, EMBED_DIM), dtype=np.float32)
+
+ # Sanity check: if JSONL and .npy drifted out of sync (e.g. crash
+ # mid-add), we truncate to the shorter length so subsequent adds
+ # don't alias to the wrong rows.
+ n = min(len(self.records), self.clip_embeddings.shape[0], self.tag_embeddings.shape[0])
+ if n != len(self.records):
+ self.records = self.records[:n]
+ self._id_to_row = {r.clip_id: i for i, r in enumerate(self.records)}
+ if self.clip_embeddings.shape[0] != n:
+ self.clip_embeddings = self.clip_embeddings[:n]
+ if self.tag_embeddings.shape[0] != n:
+ self.tag_embeddings = self.tag_embeddings[:n]
+
+ def save(self) -> None:
+ """Persist index + both embedding stacks atomically-ish."""
+ self.ensure_dirs()
+
+ # JSONL first — if a crash interrupts the .npy writes the JSONL
+ # is the source of truth for what exists, and load() will
+ # auto-truncate the embeddings to match.
+ tmp_index = self.index_path.with_suffix(".jsonl.tmp")
+ with open(tmp_index, "w", encoding="utf-8") as f:
+ for rec in self.records:
+ f.write(json.dumps(asdict(rec)) + "\n")
+ tmp_index.replace(self.index_path)
+
+ np.save(self.embed_path, self.clip_embeddings)
+ np.save(self.tag_embed_path, self.tag_embeddings)
+
+ # ------------------------------------------------------------------
+ # Mutation
+ # ------------------------------------------------------------------
+
+ def has(self, clip_id: str) -> bool:
+ return clip_id in self._id_to_row
+
+ def add(
+ self,
+ record: ClipRecord,
+ clip_embedding: np.ndarray,
+ tag_embedding: np.ndarray,
+ ) -> None:
+ """Append a new clip to the corpus. Idempotent by clip_id."""
+ if record.clip_id in self._id_to_row:
+ return
+ if clip_embedding.shape != (EMBED_DIM,):
+ raise ValueError(
+ f"clip_embedding must be ({EMBED_DIM},), got {clip_embedding.shape}"
+ )
+ if tag_embedding.shape != (EMBED_DIM,):
+ raise ValueError(
+ f"tag_embedding must be ({EMBED_DIM},), got {tag_embedding.shape}"
+ )
+ if record.added_at == 0.0:
+ record.added_at = time.time()
+
+ idx = len(self.records)
+ self.records.append(record)
+ self._id_to_row[record.clip_id] = idx
+
+ self.clip_embeddings = np.vstack(
+ [self.clip_embeddings, clip_embedding.reshape(1, -1).astype(np.float32)]
+ )
+ self.tag_embeddings = np.vstack(
+ [self.tag_embeddings, tag_embedding.reshape(1, -1).astype(np.float32)]
+ )
+
+ def get(self, clip_id: str) -> Optional[ClipRecord]:
+ idx = self._id_to_row.get(clip_id)
+ if idx is None:
+ return None
+ return self.records[idx]
+
+ def __len__(self) -> int:
+ return len(self.records)
+
+ # ------------------------------------------------------------------
+ # Vector math (the named retrieval operations)
+ # ------------------------------------------------------------------
+
+ def _fused_sims(self, query_vec: np.ndarray, tag_weight: float) -> np.ndarray:
+ """Cosine similarity fused across visual and tag channels.
+
+ Both embedding banks are L2-normalised, so `bank @ query` is
+ cosine similarity directly. Fused score = (1 - w) * visual +
+ w * tag, where w is the tag weight (default 0.3 at call sites).
+ """
+ if self.clip_embeddings.shape[0] == 0:
+ return np.zeros(0, dtype=np.float32)
+ visual = self.clip_embeddings @ query_vec.astype(np.float32)
+ tag = self.tag_embeddings @ query_vec.astype(np.float32)
+ return (1.0 - tag_weight) * visual + tag_weight * tag
+
+ def rank_by_text(
+ self,
+ query_embedding: np.ndarray,
+ k: int = 20,
+ tag_weight: float = 0.3,
+ motion_min: Optional[float] = None,
+ kind: Optional[str] = None,
+ exclude_ids: Optional[Iterable[str]] = None,
+ ) -> list[tuple[ClipRecord, float]]:
+ """Return the top-k records scored against an embedded text query.
+
+ Args:
+ query_embedding: (512,) L2-normalised text embedding.
+ k: how many results to return.
+ tag_weight: blend between visual (1-w) and tag (w) channels.
+ motion_min: if set, reject records with motion_score below this.
+ Use for "no dead clips" at the retrieval step.
+ kind: filter to "video" or "image" only.
+ exclude_ids: clip_ids to skip (already used in the current edit).
+ """
+ if len(self.records) == 0:
+ return []
+
+ scores = self._fused_sims(query_embedding, tag_weight)
+ exclude = set(exclude_ids or [])
+
+ ranked: list[tuple[int, float]] = []
+ for i, s in enumerate(scores):
+ rec = self.records[i]
+ if rec.clip_id in exclude:
+ continue
+ if kind and rec.kind != kind:
+ continue
+ if motion_min is not None and rec.motion_score < motion_min:
+ continue
+ ranked.append((i, float(s)))
+
+ ranked.sort(key=lambda x: x[1], reverse=True)
+ top = ranked[:k]
+ return [(self.records[i], s) for i, s in top]
+
+ def knn(
+ self,
+ clip_id: str,
+ k: int = 5,
+ exclude_ids: Optional[Iterable[str]] = None,
+ ) -> list[tuple[ClipRecord, float]]:
+ """Pure k-nearest-neighbours against the visual channel only.
+
+ Used as a building block for `find_similar_set` via MMR.
+ """
+ if clip_id not in self._id_to_row:
+ return []
+ seed_idx = self._id_to_row[clip_id]
+ seed_vec = self.clip_embeddings[seed_idx]
+
+ sims = self.clip_embeddings @ seed_vec
+ exclude = set(exclude_ids or [])
+ exclude.add(clip_id) # never return the seed itself
+
+ ranked: list[tuple[int, float]] = []
+ for i, s in enumerate(sims):
+ if self.records[i].clip_id in exclude:
+ continue
+ ranked.append((i, float(s)))
+
+ ranked.sort(key=lambda x: x[1], reverse=True)
+ top = ranked[:k]
+ return [(self.records[i], s) for i, s in top]
+
+ def find_similar_set(
+ self,
+ seed_clip_id: str,
+ n: int = 5,
+ diversity: float = 0.3,
+ candidate_pool: int = 30,
+ exclude_ids: Optional[Iterable[str]] = None,
+ ) -> list[tuple[ClipRecord, float]]:
+ """Collection-style retrieval: `n` clips that share the seed's
+ visual register but don't duplicate each other.
+
+ Uses Maximal Marginal Relevance:
+
+ score(c) = (1 - lambda) * sim(c, seed)
+ - lambda * max(sim(c, already_picked))
+
+ where `lambda = diversity`. At diversity=0 the result is pure
+ k-NN; at diversity=1 it picks the most-different-from-each-other
+ clips regardless of seed similarity. Default 0.3 keeps the set
+ tight but avoids duplicates.
+ """
+ if seed_clip_id not in self._id_to_row:
+ return []
+ seed_idx = self._id_to_row[seed_clip_id]
+ seed_vec = self.clip_embeddings[seed_idx]
+
+ exclude = set(exclude_ids or [])
+ exclude.add(seed_clip_id)
+
+ # Narrow to the top-`candidate_pool` by raw similarity first.
+ sims_to_seed = self.clip_embeddings @ seed_vec
+ candidate_idxs = np.argsort(-sims_to_seed).tolist()
+ pool: list[int] = []
+ for i in candidate_idxs:
+ if self.records[i].clip_id in exclude:
+ continue
+ pool.append(int(i))
+ if len(pool) >= candidate_pool:
+ break
+
+ if not pool:
+ return []
+
+ picked: list[int] = []
+ picked_scores: list[float] = []
+
+ while pool and len(picked) < n:
+ best_i = -1
+ best_score = -1e9
+ for i in pool:
+ sim_seed = float(sims_to_seed[i])
+ if picked:
+ # max similarity to already-picked set
+ picked_vecs = self.clip_embeddings[np.array(picked)]
+ sim_picked = float(np.max(self.clip_embeddings[i] @ picked_vecs.T))
+ else:
+ sim_picked = 0.0
+ mmr = (1.0 - diversity) * sim_seed - diversity * sim_picked
+ if mmr > best_score:
+ best_score = mmr
+ best_i = i
+ picked.append(best_i)
+ picked_scores.append(best_score)
+ pool.remove(best_i)
+
+ return [(self.records[i], s) for i, s in zip(picked, picked_scores)]
+
+ def diversify(
+ self,
+ candidate_ids: list[str],
+ n: int,
+ diversity: float = 0.5,
+ ) -> list[str]:
+ """Given a pre-selected candidate list, greedily pick `n` that
+ are mutually dissimilar.
+
+ Used at edit-arrangement time to make sure no two adjacent slots
+ are visually redundant. Returns the ordered clip_ids to keep;
+ order matches pick order.
+ """
+ if not candidate_ids:
+ return []
+ idxs = [self._id_to_row[c] for c in candidate_ids if c in self._id_to_row]
+ if not idxs:
+ return []
+
+ picked: list[int] = [idxs[0]]
+ remaining = idxs[1:]
+
+ while remaining and len(picked) < n:
+ best_i = -1
+ best_score = -1e9
+ picked_mat = self.clip_embeddings[np.array(picked)]
+ for i in remaining:
+ sim_picked = float(np.max(self.clip_embeddings[i] @ picked_mat.T))
+ # We want LOW similarity, so we negate.
+ score = -sim_picked
+ # Diversity weights how hard we penalize similarity. At
+ # diversity=1 we always pick the most different; at
+ # diversity=0 we just take them in input order.
+ score = diversity * score + (1.0 - diversity) * (-remaining.index(i))
+ if score > best_score:
+ best_score = score
+ best_i = i
+ picked.append(best_i)
+ remaining.remove(best_i)
+
+ return [self.records[i].clip_id for i in picked]
diff --git a/pipeline_defs/documentary-montage.yaml b/pipeline_defs/documentary-montage.yaml
new file mode 100644
index 00000000..25bc3f41
--- /dev/null
+++ b/pipeline_defs/documentary-montage.yaml
@@ -0,0 +1,165 @@
+name: documentary-montage
+version: "1.0"
+description: >
+ Retrieval-first thematic montage pipeline. Builds a semantic corpus of real-world
+ footage from Pexels, Archive.org (Prelinger et al.), and NASA, then uses CLIP-based
+ retrieval to fill slot descriptions from a thematic brief. The edit arranges clips
+ by narrative beat with music sync and uniform color grade across mixed-era footage.
+ Inspired by Adam Curtis / Chris Marker / Errol Morris tone poems.
+category: documentary
+stability: beta
+default_checkpoint_policy: guided
+
+# Reference video input support
+reference_input:
+ supported: false
+
+orchestration:
+ mode: executive-producer
+ skill: pipelines/documentary-montage/executive-producer
+ budget_default_usd: 1.00
+ max_revisions_per_stage: 3
+ max_send_backs: 2
+ max_wall_time_minutes: 60
+
+extensions:
+ custom_scripts: true
+ custom_playbooks: true
+ custom_skills: true
+ custom_tools: false
+
+required_skills:
+ - pipelines/documentary-montage/executive-producer
+ - pipelines/documentary-montage/idea-director
+ - pipelines/documentary-montage/scene-director
+ - pipelines/documentary-montage/asset-director
+ - pipelines/documentary-montage/edit-director
+ - pipelines/documentary-montage/compose-director
+ - meta/reviewer
+ - meta/checkpoint-protocol
+
+compatible_playbooks:
+ custom_allowed: true
+
+stages:
+ - name: idea
+ skill: pipelines/documentary-montage/idea-director
+ produces:
+ - brief
+ tools_available: []
+ checkpoint_required: true
+ human_approval_default: true
+ review_focus:
+ - Thematic question is ONE sentence
+ - Tone register is ONE value from the fixed list
+ - Duration and shape are concrete
+ - Music plan is resolved or explicitly silent
+ success_criteria:
+ - Schema-valid brief artifact
+ - thematic_question present in metadata
+ - music_plan present in metadata
+
+ - name: scene_plan
+ skill: pipelines/documentary-montage/scene-director
+ required_artifacts_in:
+ - brief
+ produces:
+ - scene_plan
+ tools_available: []
+ checkpoint_required: true
+ human_approval_default: true
+ review_focus:
+ - Slot descriptions use concrete noun-and-adjective language
+ - Every slot has 2-3 short search queries
+ - At least 2 slots are marked hero
+ - Slot count and target holds match the tone/duration math
+ - era_mix is reflected in preferred_sources distribution
+ success_criteria:
+ - Schema-valid scene_plan artifact
+ - metadata.slots[] present with per-slot queries and preferred_sources
+ - Sum of target_hold_seconds within 10% of brief.duration_seconds
+
+ - name: assets
+ skill: pipelines/documentary-montage/asset-director
+ required_artifacts_in:
+ - scene_plan
+ - brief
+ produces:
+ - asset_manifest
+ required_tools:
+ - corpus_builder
+ - clip_search
+ optional_tools:
+ - music_gen
+ tools_available:
+ - corpus_builder
+ - clip_search
+ - music_gen
+ checkpoint_required: true
+ human_approval_default: false
+ review_focus:
+ - Corpus size is at least 8x the slot count
+ - Every slot has exactly one picked clip with score >= 0.22
+ - No clip_id is picked for two slots (exclude_ids enforced)
+ - diversify ran clean on the final timeline
+ - rejected_picks log has reasons for passes
+ - Provenance (provider, original_url, license) present on every asset
+ success_criteria:
+ - Schema-valid asset_manifest artifact
+ - One video asset per scene slot
+ - metadata.corpus_stats present
+
+ - name: edit
+ skill: pipelines/documentary-montage/edit-director
+ required_artifacts_in:
+ - scene_plan
+ - asset_manifest
+ produces:
+ - edit_decisions
+ tools_available: []
+ checkpoint_required: true
+ human_approval_default: true
+ review_focus:
+ - Hero slots hold longest; mid-sequence cutaways shortest
+ - No two adjacent cuts share subject AND scale
+ - Transition vocabulary is at most 4 distinct values
+ - Music config is present OR brief explicitly says no music
+ - total_duration_seconds matches sum of cut durations
+ - Every cut has a reason
+ success_criteria:
+ - Schema-valid edit_decisions artifact
+ - Timeline duration within 10% of brief.duration_seconds
+
+ - name: compose
+ skill: pipelines/documentary-montage/compose-director
+ required_artifacts_in:
+ - edit_decisions
+ - asset_manifest
+ - brief
+ produces:
+ - render_report
+ required_tools:
+ - video_compose
+ optional_tools:
+ - audio_mixer
+ - color_grade
+ - video_trimmer
+ - video_stitch
+ tools_available:
+ - video_compose
+ - audio_mixer
+ - color_grade
+ - video_trimmer
+ - video_stitch
+ checkpoint_required: true
+ human_approval_default: false
+ review_focus:
+ - Output duration matches planned within 1s
+ - Resolution matches target_platform canvas
+ - Uniform LUT applied across the timeline
+ - Music present iff brief planned for it
+ - First and last frames verified
+ - No silent fallback from a motion-led promise
+ success_criteria:
+ - Schema-valid render_report artifact
+ - Output file exists and passes ffprobe validation
diff --git a/skills/pipelines/documentary-montage/asset-director.md b/skills/pipelines/documentary-montage/asset-director.md
new file mode 100644
index 00000000..7c3fe593
--- /dev/null
+++ b/skills/pipelines/documentary-montage/asset-director.md
@@ -0,0 +1,365 @@
+# Asset Director - Documentary Montage Pipeline
+
+## When To Use
+
+The shot list exists. You now have to actually go out and find the
+clips that fill each slot. This is a two-step operation:
+
+1. **Build the corpus** — fan the scene director's queries out across
+ Pexels / Archive.org / NASA and download/embed the candidates.
+2. **Pick per slot** — run CLIP retrieval against the corpus with each
+ slot description and choose one winner per slot.
+
+The output is an `asset_manifest` mapping every slot to exactly one
+clip with full provenance.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/asset_manifest.schema.json` | Artifact validation |
+| Prior artifact | `state.artifacts["scene_plan"]["scene_plan"]` | Slot descriptions + queries + preferred_sources |
+| Prior artifact | `state.artifacts["idea"]["brief"]` | `era_mix`, `sources_allowed`, `music_plan` |
+| Tool | `corpus_builder` | Populates the retrieval index |
+| Tool | `clip_search` | Ranks clips against slot descriptions |
+| Tool (optional) | `music_gen`, user's `music_library/` | Score bed |
+
+## Mental Model
+
+The corpus is NOT a stock library. It is a search index the agent
+builds on demand. You do not scroll through it — you query it.
+
+Three rules that follow from that:
+
+1. **Build before picking.** Never call `clip_search.rank_for_slot`
+ on a corpus that doesn't contain candidates for that slot's query
+ family. The ranking will return junk and you'll waste the slot.
+2. **Grow, don't replace.** The corpus is append-only. If a slot's
+ retrieval is weak, add more queries and rebuild — don't start over.
+3. **Pick per slot, not per clip.** Every clip only belongs to one
+ slot in the final edit. Use `exclude_ids` to prevent double-use.
+
+## Process
+
+### 1. Resolve The Corpus Directory
+
+Decide where the corpus lives. Convention:
+
+```
+projects/<project-name>/corpus/
+```
+
+The same `corpus_dir` is passed to every `corpus_builder` and
+`clip_search` call. The corpus is reusable across re-runs — if the
+scene director adds slots later, you can grow the same corpus instead
+of rebuilding from scratch.
+
+### 2. Fan Out The Queries Into `corpus_builder`
+
+Read `scene_plan.metadata.slots[]`. Collect every `queries[]` array
+across every slot. De-duplicate. Group by `preferred_sources`.
+
+Call `corpus_builder.execute(...)` with one fan-out per source set:
+
+```python
+# Example shape. The agent constructs this from the shot list.
+corpus_builder.execute({
+ "corpus_dir": "projects/<name>/corpus",
+ "queries": [
+ {"query": "raindrop on asphalt slow motion", "kind": "video", "per_source": 8},
+ {"query": "wet city street night neon", "kind": "video", "per_source": 8},
+ {"query": "taxi heavy rain yellow", "kind": "video", "per_source": 6},
+ # ... one entry per unique slot query
+ ],
+ "sources": ["pexels", "archive_org"], # from preferred_sources union
+ "filters": {
+ "min_duration": 3,
+ "max_duration": 40,
+ "orientation": "landscape",
+ "min_width": 1280,
+ },
+ "max_new_clips": 150, # enlarge the search space
+ "thumbs_per_video": 5,
+})
+```
+
+**Rules for the fan-out:**
+
+- Budget the corpus for 8-12x the slot count. A 15-slot montage wants
+ ~150 candidates so retrieval has real choices.
+- `per_source` of 4-8 per query is usually enough. Pushing to 20+
+ mostly adds noise.
+- If `era_mix = "vintage"`, run a separate fan-out restricted to
+ `["archive_org"]` with period-appropriate queries. Prelinger search
+ is slow — don't interleave it with the modern Pexels batch.
+- If any slot has `nasa` in `preferred_sources`, run ONE small
+ `nasa`-only batch. NASA is slow and its results are niche.
+
+### 3. Sanity-Check The Corpus Before Retrieval
+
+Before spending tokens on slot picks, call `clip_search` with
+`operation=stats`:
+
+```python
+clip_search.execute({
+ "operation": "stats",
+ "corpus_dir": "projects/<name>/corpus",
+})
+```
+
+Look at `rows`, `per_source`, `per_kind`, `mean_motion_score`. You're
+checking for three failure modes:
+
+- `rows < 50` — corpus is too small. Grow it.
+- `per_source` heavily skewed (e.g. 98% pexels, 2% archive_org) on a
+ vintage brief — run a targeted archive_org fan-out.
+- `mean_motion_score < 1.0` — corpus is full of static clips and will
+ make for a slideshow. Rerun with different queries, or apply
+ `motion_min` at rank time.
+
+### 4. Rank Candidates Per Slot
+
+For each slot in `scene_plan.metadata.slots[]`, call `clip_search`
+with `operation=rank_for_slot`:
+
+```python
+clip_search.execute({
+ "operation": "rank_for_slot",
+ "corpus_dir": "projects/<name>/corpus",
+ "query_text": slot["description"], # NOT slot["queries"] — the description is richer
+ "k": 30 if slot.get("hero") else 12,
+ "tag_weight": 0.3,
+ "motion_min": 1.5,
+ "kind": "video",
+ "exclude_ids": already_picked_ids, # global accumulator
+})
+```
+
+Key points:
+
+- Use the slot **description**, not the queries. The description is
+ the rich noun-and-adjective string the scene director wrote. CLIP
+ ranks it better than short search phrases.
+- `tag_weight=0.3` blends visual embedding (70%) with source-tag
+ embedding (30%). Raise to 0.5 when Pexels URL tags are strong and
+ the visual channel is noisy. Lower to 0.15 for Prelinger where tags
+ are long prose.
+- Always pass `exclude_ids` with every clip already locked to a slot,
+ so the same key-in-door clip doesn't win two slots.
+
+### 5. Pick With Judgement, Not By Score
+
+The top result is not always the right pick. Look at the top 3-5 and
+judge each one against:
+
+- **Era fit.** Does a 2022 4K Pexels shot belong in an elegiac list
+ montage about home? Maybe. Maybe not.
+- **Motion fit.** The tone table from the scene director tells you
+ how long the hold will be. If the clip has a 4.0s hold target and
+ the clip is 2s long with a fast whip pan, it won't stretch.
+- **Compositional carry.** Will this clip work NEXT to the clips
+ picked for the adjacent slots? You don't know yet — but if slot_02
+ is a wide rooftop-in-rain and the top hit for slot_03 is also a
+ wide rooftop-in-rain, pick the #2 instead.
+- **Emotional register.** CLIP will happily match "empty city
+ sidewalk at night" to a bright neon Vegas cutaway. The neon shot is
+ WRONG for an elegiac brief. Score 0.42 does not override tone.
+
+**Acceptable-score rules of thumb (CLIP ViT-B/32 cosine):**
+
+- `>= 0.30` — strong match, usually usable.
+- `0.22-0.30` — plausible, needs human judgement.
+- `< 0.22` — the corpus doesn't contain what you need. Grow it,
+ don't force a pick.
+
+### 6. Grow The Corpus When Retrieval Is Weak
+
+If a slot's top score is below 0.22, do NOT pick the best-of-a-bad-
+bunch. Instead:
+
+1. Rewrite the slot's queries — maybe too abstract, maybe wrong
+ vocabulary for the era.
+2. Run another `corpus_builder.execute(...)` pass with just the new
+ queries for that one slot. The builder skips clips already in the
+ index, so this is cheap.
+3. Re-rank.
+
+Two growth passes per slot is plenty. If three passes can't find a
+score above 0.22, tell the idea director the slot is unfilmable from
+open corpora and recommend either dropping the slot or letting the
+user supply the footage.
+
+### 7. Diversify Adjacent Picks
+
+Once you have one candidate per slot, you have a list of clip_ids in
+timeline order. Visually-redundant adjacent shots kill the edit. Run
+`clip_search.diversify` across the list:
+
+```python
+clip_search.execute({
+ "operation": "diversify",
+ "corpus_dir": "projects/<name>/corpus",
+ "candidate_ids": picked_ids_in_timeline_order,
+ "n": len(picked_ids_in_timeline_order),
+ "diversity": 0.5,
+})
+```
+
+If `diversify` drops a clip, it's telling you two of your picks are
+visually identical. Re-rank the slot whose clip got dropped with
+`exclude_ids` including the surviving twin.
+
+### 8. Handle The Music Plan
+
+Read `brief.music_plan`. Execute exactly the plan the idea director
+recorded — do not invent a new source here:
+
+- **`source=library`**: Verify the file at `music_plan.path` exists.
+ Record it in the asset manifest as `type=music`, `subtype=library`.
+- **`source=user`**: Same, with `subtype=provided`.
+- **`source=generated`**: Call the named music tool with the seed
+ prompt from the brief. Sample first, batch only after confirming
+ mood. Record provider and cost.
+- **`source=none`**: Do not generate silence. Do not swap in a track
+ because the edit feels thin. If the user approved "no music", run
+ with no music.
+
+**Never switch music source at this stage.** That's a Decision
+Communication Contract violation — changing music mode is a major
+production change and needs user approval at proposal time.
+
+### 9. Record The Asset Manifest
+
+Emit one asset per slot using the canonical schema. Documentary-
+montage-specific fields live in `metadata`:
+
+```json
+{
+ "version": "1.0",
+ "assets": [
+ {
+ "id": "asset_slot_01",
+ "type": "video",
+ "path": "projects/<name>/corpus/clips/pexels_12345/video.mp4",
+ "source_tool": "corpus_builder",
+ "scene_id": "slot_01",
+ "duration_seconds": 7.2,
+ "resolution": "1920x1080",
+ "format": "mp4",
+ "provider": "pexels",
+ "license": "Pexels License (free, no attribution required)",
+ "original_url": "https://www.pexels.com/video/12345",
+ "subtype": "stock",
+ "generation_summary": "Retrieved via CLIP rank for slot 'raindrop on asphalt slow motion...'. Score 0.38."
+ },
+ {
+ "id": "asset_music_bed",
+ "type": "music",
+ "path": "music_library/dawn_04.mp3",
+ "source_tool": "music_library",
+ "scene_id": "global",
+ "subtype": "library",
+ "license": "user-provided"
+ }
+ ],
+ "metadata": {
+ "pipeline": "documentary-montage",
+ "corpus_dir": "projects/<name>/corpus",
+ "corpus_stats": { "rows": 157, "per_source": {"pexels": 98, "archive_org": 52, "nasa": 7} },
+ "rejected_picks": [
+ {
+ "slot_id": "slot_03",
+ "clip_id": "pexels_99921",
+ "score": 0.41,
+ "reason": "wrong era — 2022 4K kitchen, brief is vintage"
+ }
+ ]
+ }
+}
+```
+
+The `rejected_picks` log matters. The edit director reads it when a
+pick feels wrong and needs to reach for the #2 option.
+
+### 10. Quality Gate
+
+- Every slot in the scene plan has exactly one asset mapped to it.
+- Every picked clip has `score >= 0.22` in the rejected-picks log
+ (or a logged "user-approved override" note).
+- No clip_id appears as the primary pick for two slots.
+- `diversify` ran clean on the final list (no dropped picks, or all
+ dropped picks were re-filled).
+- `corpus_stats` shows at least 8x the slot count in rows.
+- Music asset exists OR `music_plan.source = "none"` with explicit
+ acknowledgement.
+- For vintage briefs, at least 60% of picks come from `archive_org`.
+- All file paths resolve.
+
+## Common Pitfalls
+
+- **Running `clip_search.rank_for_slot` against an empty corpus.**
+ You will get an empty `results` list or a cryptic shape error.
+ Always call `stats` after a build, before ranking.
+- **Picking by score alone.** Score is an input to judgement, not the
+ judgement. An elegiac piece full of top-scored Pexels HD sunshine
+ will feel wrong regardless of scores.
+- **Forgetting `exclude_ids`.** Without it, the same amazing clip
+ wins every slot and the montage becomes a slideshow of one image.
+- **Quiet music substitution.** User said "none", agent generated
+ anyway because "the edit felt thin". This is a major change and
+ needs approval — see `skills/pipelines/documentary-montage/executive-producer.md`
+ cross-stage rules.
+- **Growing the corpus unboundedly.** Two growth passes per weak slot
+ is the limit. Beyond that, the footage probably doesn't exist in
+ the open corpora and the slot needs to change.
+- **Using slot queries as the rank text.** Queries are search phrases
+ for stock APIs; descriptions are semantic text for CLIP. They are
+ different. Rank on descriptions.
+- **Losing provenance.** Every clip must carry `provider`,
+ `original_url`, and `license` in the manifest. These are the
+ non-negotiables for any downstream publishing step.
+
+## Retrieval Recipes
+
+A few retrieval moves that come up often:
+
+### "Find N variants of this one clip I love"
+
+```python
+clip_search.execute({
+ "operation": "find_similar_set",
+ "corpus_dir": "projects/<name>/corpus",
+ "seed_clip_id": "pexels_12345",
+ "n": 5,
+ "diversity": 0.4,
+ "candidate_pool": 40,
+})
+```
+
+Used when a slot wants "five more shots like this one" — e.g. a
+catalogue of doorways all filmed in the same register.
+
+### "I have 20 candidates, trim to 8 non-redundant picks"
+
+```python
+clip_search.execute({
+ "operation": "diversify",
+ "corpus_dir": "projects/<name>/corpus",
+ "candidate_ids": [...],
+ "n": 8,
+ "diversity": 0.5,
+})
+```
+
+### "Look up one clip's full metadata"
+
+```python
+clip_search.execute({
+ "operation": "get",
+ "corpus_dir": "projects/<name>/corpus",
+ "clip_id": "archive_org_Prelinger_HomeMovies_0042",
+})
+```
+
+Used when the edit director wants to confirm the provider/URL before
+locking the cut.
diff --git a/skills/pipelines/documentary-montage/compose-director.md b/skills/pipelines/documentary-montage/compose-director.md
new file mode 100644
index 00000000..1e20b134
--- /dev/null
+++ b/skills/pipelines/documentary-montage/compose-director.md
@@ -0,0 +1,277 @@
+# Compose Director - Documentary Montage Pipeline
+
+## When To Use
+
+The timeline exists. Every cut has an in/out, transitions are
+chosen, the music bed is locked. You now have to render the piece
+and apply the register-smoothing pass (uniform crop + LUT + audio
+mix) that makes a mixed-era corpus feel like one film.
+
+The output is a single mp4 plus a `render_report` artifact.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/render_report.schema.json` | Artifact validation |
+| Prior artifact | `state.artifacts["edit"]["edit_decisions"]` | Cuts, transitions, music, metadata hints |
+| Prior artifact | `state.artifacts["assets"]["asset_manifest"]` | File paths, durations, providers |
+| Tool | `video_compose` (FFmpeg + Remotion) | Primary render engine |
+| Tool | `audio_mixer` | Music fade, silence window, L-cuts |
+| Tool (optional) | `color_grade` | Uniform LUT across mixed-era clips |
+| Tool (optional) | `video_trimmer`, `video_stitch` | Lower-level helpers if needed |
+
+## Mental Model
+
+Most pipelines treat compose as a boring export step. For
+documentary montage it is a creative step: the last pass where grade
+and mix reconcile footage from radically different sources into one
+piece.
+
+Three things must happen here that cannot happen earlier:
+
+1. **Uniform aspect and letterbox.** Pexels 1920x1080, Prelinger
+ 640x480 4:3, NASA 1280x720 all need to land on one canvas.
+2. **Uniform color grade.** A single LUT across the whole timeline
+ is what makes the 1962 home movie sit next to the 2023 kitchen
+ without jumping out.
+3. **Audio mix.** Music level, silence window, L-cut ambient
+ carries, final fade — done in one pass with the timeline in hand.
+
+## Process
+
+### 0. Hard Requirement Check
+
+Read `brief` and `edit_decisions.metadata` for any hard requirements.
+If the brief said "no narration" and a narration track somehow
+appeared in the edit, STOP and ask. Do not render over a contract
+violation.
+
+Also confirm the render engine you intend to use is actually
+available — `video_compose` in FFmpeg-only mode is fine for this
+pipeline (the whole piece is footage-led, no Remotion scenes needed
+unless the user asked for title cards). FFmpeg alone can render this
+pipeline end to end.
+
+### 1. Resolve The Canvas
+
+Read `brief.target_platform`:
+
+| Target | Canvas | Letterbox |
+|--------|--------|-----------|
+| `social_short` (Instagram/TikTok) | 1080x1920 (9:16) | Top/bottom crop; center-anchor each clip |
+| `youtube` / `generic` | 1920x1080 (16:9) | None; optionally 2.35:1 top/bottom bars for cinematic feel |
+| `linkedin` | 1920x1080 (16:9) | None |
+
+Every clip in the timeline must be scaled/cropped to this canvas.
+For `social_short`, this usually means center-cropping 16:9 footage.
+For `youtube` with the cinematic 2.35:1 bar treatment, pad 140px
+black top and bottom on a 1920x1080 canvas.
+
+Commit this in `render_report.metadata.canvas` and
+`render_report.metadata.letterbox`.
+
+### 2. Build The Concat Plan For `video_compose`
+
+The edit artifact gives you a list of cuts with in/out, transitions,
+and source asset_ids. Walk the asset_manifest to resolve each
+asset_id to a real file path. Then build the render plan.
+
+For a pipeline this simple, the cleanest path is:
+
+```python
+video_compose.execute({
+ "operation": "render",
+ "output_path": "projects/<name>/renders/final.mp4",
+ "canvas": { "width": 1920, "height": 1080, "fps": 24 },
+ "cuts": [
+ {
+ "source": "<resolved file path>",
+ "in": 1.2,
+ "out": 5.2,
+ "scale": "fit_canvas_center_crop",
+ "transition_in": "fade",
+ "transition_in_duration": 0.8,
+ },
+ # ... more cuts
+ ],
+ "audio": {
+ "music_path": "<resolved music path>",
+ "music_volume": 0.7,
+ "music_fade_in": 1.0,
+ "music_fade_out": 4.0,
+ "silence_windows": [{"start": 54.0, "end": 56.0}],
+ "sfx_layers": [
+ {"source": "<rain carry clip>", "start": 20.8, "duration": 1.2, "volume": 0.6}
+ ],
+ },
+ "frame_treatment": {
+ "lut_path": "styles/luts/warm_film_100.cube",
+ "letterbox": "2.35:1"
+ }
+})
+```
+
+The exact field names come from the live `video_compose` schema at
+render time — consult the tool's `agent_skills` if available before
+writing the call. Do not invent parameters.
+
+### 3. Apply Grade Via LUT, Not Per Clip
+
+Read `edit_decisions.metadata.grade_profile`. Map it to a LUT file:
+
+| Profile | LUT | Suits |
+|---------|-----|-------|
+| `warm_film_100` | vintage film warmth, slight lift | elegiac, dreamlike |
+| `cool_archive_60` | cool highlights, crushed blacks | urgent, wry |
+| `neutral_doc_20` | barely-there neutral balance | reverent |
+| `bleach_bypass_80` | desaturated, high contrast | wry, documentary-harsh |
+
+If the profile isn't in the styles library, use `neutral_doc_20` and
+note it in `warnings`. Do not try to auto-grade — the LUT is the
+whole point of the register-smoothing pass.
+
+Apply the LUT at the composition level, not per clip. One LUT, one
+timeline, one consistent look. This is what makes a 1962 Prelinger
+clip and a 2023 Pexels clip feel like the same film.
+
+### 4. Mix The Audio Once, In Compose
+
+The edit artifact already decided volumes, fades, silence windows,
+and L-cut sfx layers. Your job is to execute them faithfully:
+
+- Music bed at `edit_decisions.audio.music.volume` (default 0.7).
+- Fade in per `fade_in_seconds`, fade out per `fade_out_seconds`.
+- Silence window = ducked to 0.0 for the window's duration, ramp
+ back up with a 0.2s hold-off.
+- L-cut SFX layers = mix at 0.5-0.7 volume, under music.
+- No narration unless explicitly present in `edit_decisions.audio.narration`.
+
+If the brief says "no music" and the edit correctly has no music
+entry, render silent. Do NOT add ambient noise "to fill the gap".
+
+### 5. Render At Documentary Spec
+
+Recommended encoder settings for doc montage:
+
+| Field | Value | Why |
+|-------|-------|-----|
+| Codec | `libx264` (H.264) | Universal, small |
+| Pixel format | `yuv420p` | Universal compatibility |
+| CRF | `18` | Visually lossless for final deliverables |
+| FPS | `24` | Cinematic. Do NOT upconvert 24->30. |
+| Audio codec | `aac` | Universal |
+| Audio bitrate | `192k` | Music-bed friendly |
+
+If the source clips are 30fps and the canvas is 24fps, let FFmpeg
+drop frames evenly — don't blend. Motion interpolation on
+mixed-source footage looks awful.
+
+### 6. Post-Render Verification
+
+After the render succeeds, actually probe the output file and check:
+
+- **Duration.** Should match `sum(out - in for cut in cuts) + fade
+ in/out` within ±0.5s.
+- **Resolution.** Should match the canvas.
+- **Audio presence.** If music was in the plan, the output must
+ have an audio stream. If silence was planned, confirm.
+- **First and last frame.** Open the file, seek to 0s and to
+ duration-0.1s. The first frame should be a fade-in. The last
+ frame should be (or be fading to) black.
+- **Silence window.** Seek to the silence_window start. Audio level
+ should drop visibly in the waveform.
+
+Record verifications in `render_report.verification_notes`.
+
+### 7. Emit The Render Report
+
+```json
+{
+ "version": "1.0",
+ "outputs": [
+ {
+ "path": "projects/<name>/renders/final.mp4",
+ "format": "mp4",
+ "codec": "h264",
+ "audio_codec": "aac",
+ "resolution": "1920x1080",
+ "fps": 24,
+ "duration_seconds": 89.8,
+ "file_size_bytes": 18234112,
+ "platform_target": "youtube"
+ }
+ ],
+ "render_time_seconds": 42.3,
+ "warnings": [],
+ "verification_notes": [
+ "Duration within +0.2s of planned",
+ "First frame is black fade-in as specified",
+ "Silence window 54-56s confirmed (music -60dB)",
+ "Last frame fades to black at 89.0s"
+ ],
+ "render_grammar": "cinematic-trailer",
+ "metadata": {
+ "pipeline": "documentary-montage",
+ "canvas": { "width": 1920, "height": 1080 },
+ "letterbox": "2.35:1",
+ "lut": "warm_film_100",
+ "music_present": true
+ }
+}
+```
+
+### 8. Quality Gate
+
+- Output file exists and plays.
+- Duration within ±1s of `brief.duration_seconds`.
+- Resolution matches `target_platform` canvas.
+- LUT was applied (or a warning logged).
+- Music is present iff the brief planned for it.
+- First and last frames verified.
+- Silence window (if any) verified in the waveform.
+- No narration unless brief-approved.
+- `render_report.warnings` lists every substitution.
+
+## Common Pitfalls
+
+- **Letting mixed-era clips render un-graded.** The piece will look
+ like a PowerPoint slideshow of internet clips. The LUT is
+ non-negotiable.
+- **Upscaling to match the canvas instead of letterboxing.**
+ Prelinger 640x480 upscaled to 1920x1080 looks pixelated and wrong.
+ Center it with letterbox bars, or embrace the squared crop as a
+ design choice.
+- **Narration or ambient SFX added "to fill the gap".** Major
+ change, needs user approval.
+- **Per-clip color grading.** One LUT across the whole piece. Do
+ not try to balance each clip individually — it takes 10x the time
+ and makes the register LESS consistent, not more.
+- **Quiet render engine swap.** If `video_compose` routes through
+ Remotion for some reason and the aesthetic changes, stop and
+ surface. This pipeline is FFmpeg-friendly and shouldn't need
+ Remotion unless the user asked for title cards.
+- **Overriding edit decisions at render time.** If you find yourself
+ adjusting volumes, fades, or trims in the render call, you're
+ editing during compose. Go back to the edit stage, fix the
+ decisions, re-emit the artifact, then re-render.
+- **Skipping verification.** A render that "succeeded" but is
+ actually silent, or fades wrong, or clips the last hero frame, is
+ worse than a failure. Open the file.
+
+## When The Render Fails
+
+If `video_compose` returns an error:
+
+1. Check the error category per the Decision Communication Contract
+ (auth / provider / tool bug / plan quality).
+2. If it's a path error, validate every asset_id → path resolution
+ in the asset manifest. A single missing file fails the whole render.
+3. If it's a codec error, the input clips may have exotic containers
+ (Archive.org sometimes serves Matroska). Try running each input
+ through `video_trimmer` first to normalize to mp4/h264.
+4. If it's a memory or timeout error, split the render into halves
+ with `video_stitch` at the end.
+5. Surface to the user before swapping to a lower-fidelity path.
+ This pipeline is footage-led; there is no generated-stills
+ fallback.
diff --git a/skills/pipelines/documentary-montage/edit-director.md b/skills/pipelines/documentary-montage/edit-director.md
new file mode 100644
index 00000000..a6fbc96f
--- /dev/null
+++ b/skills/pipelines/documentary-montage/edit-director.md
@@ -0,0 +1,335 @@
+# Edit Director - Documentary Montage Pipeline
+
+## When To Use
+
+Every slot has a clip. You now have to turn a pile of clips into a
+piece. This stage decides in-points, out-points, transitions, music
+sync, and the order the clips actually run. The output is an
+`edit_decisions` artifact with a concrete timeline.
+
+This is where documentary technique lives. If the asset director did
+its job, you have the raw material. The edit is the thinking.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/edit_decisions.schema.json` | Artifact validation |
+| Prior artifact | `state.artifacts["assets"]["asset_manifest"]` | Picked clips + music bed |
+| Prior artifact | `state.artifacts["scene_plan"]["scene_plan"]` | Slot order, hero flags, target holds |
+| Prior artifact | `state.artifacts["idea"]["brief"]` | Tone register, duration, shape |
+| Tool (optional) | `video_analyzer` | Probe a clip's motion if you need to re-check |
+
+## Mental Model
+
+Documentary montage lives in four dimensions you have to balance:
+
+1. **Rhythm** — how long each hold lasts and how the holds relate.
+2. **Juxtaposition** — which image follows which, and what it means.
+3. **Music sync** — cuts landing on beats, dropouts earning weight.
+4. **Continuity of register** — the grain, color, and era don't swing
+ wildly unless the swing is the point.
+
+The enemy is "slideshow" — a sequence of clips played back-to-back
+with the same hold length and no sound design. If it feels like a
+slideshow, the edit has failed, regardless of how good the clips are.
+
+## Process
+
+### 0. Guardrails — No Silent Major Changes
+
+Before touching the timeline, re-read the brief. If any of these are
+true, STOP and surface to the user per the Decision Communication
+Contract:
+
+- The brief approved "no narration" but the edit feels like it needs
+ voice-over. Narration is a MAJOR change.
+- The brief approved a music track that the edit director now wants
+ to replace. Music swap is a MAJOR change.
+- The brief approved a 90s duration but the natural cut wants 2m30s.
+ Duration stretch is a MAJOR change.
+
+Fix the edit, don't paper over it. If the edit genuinely needs
+one of these, ask.
+
+### 1. Set The Rhythm Grid
+
+Read `brief.tone` and `brief.duration_seconds`. Compute the hold
+table from the scene director's tone chart:
+
+| Tone | Base hold | Min hold | Max hold |
+|------|-----------|----------|----------|
+| elegiac | 4.0s | 2.5s | 7.0s |
+| reverent | 3.5s | 2.0s | 6.0s |
+| dreamlike | 3.0s | 1.5s | 5.5s |
+| wry | 2.0s | 1.0s | 4.0s |
+| urgent | 1.2s | 0.5s | 2.5s |
+
+**Hero slots get max hold.** Mid-sequence cutaways get base. Quick
+transitions get min.
+
+Total hold time must sum to within ±10% of `brief.duration_seconds`.
+If you overshoot, compress non-hero holds first — never cut heroes
+short to fit duration.
+
+### 2. Arrange By Narrative Beat, Not By Score
+
+The scene director gave you a slot order. That order is the intent.
+Don't rearrange it by CLIP score, motion score, or resolution.
+
+You MAY reorder slots when:
+
+- The music bed has a downbeat at a known timestamp and reordering
+ two slots lands a hero on the beat (see step 4).
+- Two adjacent slots are visually identical and swapping one breaks
+ the monotony (but see step 7 — diversify should have caught this
+ already).
+- The final image isn't landing. The last 5-10s carries
+ disproportionate weight; if the scene director's choice dies, move
+ a stronger candidate to the tail.
+
+Always log the reorder in `edit_decisions.metadata.reorder_notes`
+with the reason.
+
+### 3. Trim Each Clip To Its Beat
+
+For every picked clip, decide `in_seconds` and `out_seconds`. Three
+rules:
+
+- **Find the best sub-window, not the whole clip.** A 12-second Pexels
+ clip usually contains one 3-second moment that earns the hold and
+ 9 seconds of setup/settle. Find the moment.
+- **Cut BEFORE the action's natural end.** End on a look, not on a
+ move-off. The cut feels intentional instead of exhausted.
+- **Leave a handle at both ends.** 4-6 frames of headroom so the
+ composer can apply a fade or dissolve without clipping the moment.
+
+If a clip is too short to fill its target hold, either:
+
+- slow it down (speed 0.5-0.75, fine on static-ish footage, bad on
+ anything with sync motion or faces talking),
+- let it cut early and borrow the remaining duration from the next
+ slot's hold,
+- or swap to the #2 candidate from the rejected-picks log.
+
+Do NOT hold on the last frozen frame. A freeze-frame in a doc montage
+reads as a technical mistake.
+
+### 4. Sync To The Music Bed
+
+Read `asset_manifest` for the music asset and load its duration.
+Documentary montages earn their emotional weight from cuts landing
+on musical events. Three sync moves:
+
+- **Downbeat cuts.** If you have bars and beats metadata (from a
+ provided track) or can hear them, place hero cuts on downbeats.
+ If not, evenly-spaced cuts on 4s intervals for a 60bpm bed are a
+ safe default.
+- **One held silence.** Drop the music out for ~2s at the piece's
+ emotional center. Silence is a tool. Use it once. Use it hard.
+- **Tail fade.** Music fades under the last 3-5s so the final image
+ can breathe without a musical resolution fighting it.
+
+Record the music config in `edit_decisions.audio.music` with:
+
+```json
+{
+ "asset_id": "asset_music_bed",
+ "volume": 0.7,
+ "fade_in_seconds": 1.0,
+ "fade_out_seconds": 4.0,
+ "ducking": false
+}
+```
+
+`ducking: false` is the default for this pipeline — there's no
+narration to duck under. If the user approved a narration track, set
+ducking to true and let it dip during segments.
+
+### 5. Choose Transitions From A Small Vocabulary
+
+Documentary montage uses maybe four transitions total across the
+entire piece:
+
+| Transition | Use |
+|------------|-----|
+| `cut` (hard) | Default. Most cuts are hard cuts. |
+| `dissolve` (0.5-1.0s) | Emotional sibling clips, time passage |
+| `fade_to_black` (0.5s, then back up) | Act breaks in 3-act shape, or once near the end |
+| `fade_in` (first shot) / `fade_out` (last shot) | 0.5-1.0s bookends |
+
+**Do not use:**
+
+- wipes,
+- push/slide transitions,
+- zoom blurs,
+- RGB splits,
+- light leaks,
+- glitch effects.
+
+These read as social-media edit language and will break the
+documentary register. If the piece is getting boring, fix the clip
+choices or the pacing, don't add transition flash.
+
+Record each cut's `transition_in` / `transition_out` per the schema.
+Default `transition_in: "cut"` on most cuts.
+
+### 6. Apply Register Continuity
+
+Mixed-era corpora look wildly different. Pexels 2023 is clean, sharp,
+color-graded. Prelinger 1962 is grainy, warm, squared-off aspect.
+NASA archival is often low-res with text overlays. If you mash them
+together raw, the piece looks like a Wikipedia article.
+
+You have two tools to smooth this:
+
+1. **Crop to a uniform aspect ratio.** Pick one: 16:9 cinematic
+ (`2.35:1` letterbox on top/bottom) for hero pieces, 9:16 for
+ social. Enforce in the `transform.crop` field of each cut.
+2. **Flag the piece for a uniform color grade at compose time.** Put
+ a `grade_profile` hint in `edit_decisions.metadata`. The compose
+ director will apply a LUT across the whole timeline.
+
+Don't try to color-grade individual clips here. That's the compose
+stage. Your job is to flag the need.
+
+### 7. Enforce Adjacent Diversity One More Time
+
+Walk the timeline in pairs. For each consecutive (cut_n, cut_n+1):
+
+- Are they the same subject at the same scale? If yes, you have a
+ slideshow moment. Swap one for a clip at a different scale (wide
+ vs close).
+- Are they the same color palette (two night-blue clips back to
+ back)? If yes, break the pattern at least every 4 cuts.
+- Are they the same motion direction (two left-to-right pans)? If
+ yes, flip the second's horizontal axis or reorder.
+
+Log any swaps you made in `metadata.diversity_swaps`.
+
+### 8. The L-Cut Move (Optional But Powerful)
+
+For any transition between two clips where the outgoing clip has
+strong ambient audio (rain, footsteps, traffic), carry the audio
+under the incoming clip for 0.5-1.5s. This is an L-cut and it
+welds two shots together more tightly than any visual transition.
+
+Implement via the schema by using a short `dissolve` transition OR
+by layering the outgoing clip's audio as an SFX entry in
+`edit_decisions.audio.sfx` with a delayed end.
+
+Documentary montages with L-cuts feel 50% more coherent than ones
+without. Use them on the 3-4 hardest transitions in the piece.
+
+### 9. Emit The Edit Decisions
+
+Canonical shape for this pipeline:
+
+```json
+{
+ "version": "1.0",
+ "cuts": [
+ {
+ "id": "cut_01",
+ "source": "asset_slot_01",
+ "in_seconds": 1.2,
+ "out_seconds": 5.2,
+ "layer": "primary",
+ "transform": { "scale": 1.0, "position": "center" },
+ "transition_in": "fade_in",
+ "transition_out": "cut",
+ "transition_duration": 0.8,
+ "reason": "opening hero — raindrop on asphalt, 4s hold, slow-motion streetlamp glow"
+ },
+ {
+ "id": "cut_02",
+ "source": "asset_slot_02",
+ "in_seconds": 2.0,
+ "out_seconds": 5.5,
+ "layer": "primary",
+ "transition_in": "cut",
+ "transition_out": "cut",
+ "reason": "umbrella opening in doorway, hard cut from raindrop → street"
+ }
+ ],
+ "audio": {
+ "music": {
+ "asset_id": "asset_music_bed",
+ "volume": 0.7,
+ "fade_in_seconds": 1.0,
+ "fade_out_seconds": 4.0,
+ "ducking": false
+ }
+ },
+ "metadata": {
+ "pipeline": "documentary-montage",
+ "tone": "elegiac",
+ "shape": "list",
+ "total_duration_seconds": 90.0,
+ "hold_table_used": { "base": 4.0, "min": 2.5, "max": 7.0 },
+ "grade_profile": "warm_film_100",
+ "reorder_notes": [],
+ "diversity_swaps": [
+ { "at": "cut_07-cut_08", "reason": "two wide rooftops-in-rain adjacent, swapped 08 for #2 pick" }
+ ],
+ "silence_window": { "start_seconds": 54.0, "end_seconds": 56.0 },
+ "l_cuts": [
+ { "from_cut": "cut_05", "to_cut": "cut_06", "carry_seconds": 1.2, "channel": "ambient_rain" }
+ ]
+ }
+}
+```
+
+### 10. Quality Gate
+
+- `sum(out - in for cut in cuts)` is within ±10% of
+ `brief.duration_seconds`.
+- Hero slots have the longest holds.
+- No two adjacent cuts share subject AND scale.
+- The transition vocabulary is at most 4 distinct values.
+- Music config exists (or brief explicitly says no music).
+- At least one `silence_window` entry for pieces >= 60s.
+- Every cut has a one-line `reason` — if you can't write one, the
+ cut is arbitrary and should be reconsidered.
+- `metadata.total_duration_seconds` matches the sum of cut durations.
+
+## Common Pitfalls
+
+- **Cutting by information density instead of rhythm.** A doc
+ montage is not a Wikipedia article. "But I need to show this" is
+ not a reason — if the image doesn't sustain a hold, it doesn't
+ belong.
+- **Over-using dissolves.** A dissolve on every cut says "I couldn't
+ commit". Commit.
+- **Ignoring the music bed until the end.** Music is not a sweetener
+ you add at compose time. It is a timing grid you cut TO.
+- **Letting the final image be a weak one.** The last frame is
+ disproportionately remembered. If it's weak, swap it — the scene
+ director's slot ordering is a strong suggestion, not a contract.
+- **Freeze-frame endings.** Reads as technical error. End on a
+ fade-to-black instead.
+- **Silently adding a narration because the edit feels thin.** Major
+ change. Ask.
+- **Hiding clip provider in the cuts.** Every `cut.source` must be
+ an `asset_manifest` asset_id so provenance survives.
+- **Three different transition types in the first 15 seconds.**
+ Readers will feel the edit working. Restraint is the brand.
+
+## Worked Pacing Example — "A Minute in the Rain"
+
+90 seconds, elegiac, list shape, 15 hero-flagged slots.
+
+- Base hold 4.0s × 15 = 60s. Short by 30s.
+- Add 30s across 3 hero slots (1, 11, 15) at +10s each:
+ hero_1 = 5.5s, hero_11 = 6.0s, hero_15 = 7.0s.
+- Tighten slots 4, 7, 13 to 3.0s each (small cutaways).
+- Insert silence_window 54.0-56.0s (right before hero_11).
+- L-cut slot_10 (boot in puddle) → slot_11 (lit window across
+ street), carry rain-on-glass ambient 1.2s.
+- First cut `fade_in` 1.0s, last cut `fade_out` 1.5s.
+- All other cuts hard.
+- Music fades in 1.0s, fades out 4.0s under hero_15 + black.
+
+This gives a 90s piece with 3 breathing points (fade_in, silence,
+fade_out), a clear hero arc (slots 1 → 11 → 15), and no adjacent
+scale collisions.
diff --git a/skills/pipelines/documentary-montage/executive-producer.md b/skills/pipelines/documentary-montage/executive-producer.md
new file mode 100644
index 00000000..86a70abc
--- /dev/null
+++ b/skills/pipelines/documentary-montage/executive-producer.md
@@ -0,0 +1,89 @@
+# Executive Producer - Documentary Montage Pipeline
+
+## When To Use
+
+The user wants a short (30-180s) non-narrative piece built from existing
+footage — a thematic collage, essay film, or Adam-Curtis-style tone
+poem. The piece is NOT a narrated explainer, NOT a talking head, NOT a
+single extended scene. It is an arranged sequence of real-world clips
+whose meaning emerges from juxtaposition (Kuleshov effect,
+Eisenstein's intellectual montage).
+
+This is the right pipeline when the brief includes phrases like:
+
+- "a montage about...",
+- "show me the feeling of...",
+- "like a tone poem",
+- "documentary-style collage",
+- "everyone who has ever..." / "the life of..." / "a portrait of...",
+- "cut together from stock footage",
+- "Adam Curtis", "Errol Morris", "Chris Marker",
+- "no narration, just images".
+
+If the user asks for an explainer, a trailer with generated clips, or
+a talking-head video, pick a different pipeline.
+
+## Philosophy
+
+Documentary montage is retrieval-first, not generation-first.
+The corpus is the raw material; the edit is the thinking. Your job
+across all stages is to:
+
+1. **Enlarge the search space before committing**. Build a corpus
+ bigger than you think you need so the edit has room to breathe.
+2. **Let juxtaposition do the talking**. Two mundane clips next to
+ each other can mean something neither one means alone.
+3. **Trust the footage**. If a clip shows a thing plainly, don't
+ explain it with text or voice-over.
+4. **Pace is the message**. Cut on beat. Hold on images that earn it.
+ Short cuts = urgency, long holds = grief/weight/awe.
+
+## Stages
+
+| Stage | Director skill | Produces |
+|-------|----------------|----------|
+| `idea` | `idea-director.md` | brief (topic, tone, duration, shape) |
+| `scene` | `scene-director.md` | shot_list (slot descriptions + queries) |
+| `assets` | `asset-director.md` | asset_manifest (corpus built + per-slot picks) |
+| `edit` | `edit-director.md` | edit_decisions (timeline + transitions + music) |
+| `compose` | `compose-director.md` | render_report (final mp4) |
+
+Each director skill has its own quality gate. Read the director skill
+before starting the stage.
+
+## Core Tools
+
+| Tool | Role |
+|------|------|
+| `corpus_builder` | Fans out across Pexels/Archive.org/NASA, downloads + embeds + indexes |
+| `clip_search` | Ranks clips for a slot, finds similar sets, diversifies selections |
+| `video_compose` / Remotion | Renders the final timeline |
+
+The agent talks to the stock sources through `corpus_builder` — never
+call adapter classes directly from a skill or director.
+
+## Cross-Stage Rules
+
+- **No generated clips** unless the user explicitly asks. This pipeline
+ is about REAL footage, real texture, real grain. Generated B-roll
+ breaks the aesthetic.
+- **No narration** unless the user explicitly asks. The brief should
+ default to image-only + music. Adding voice is a MAJOR change and
+ requires user approval per the Decision Communication Contract.
+- **Build the corpus before picking clips**. Do not run clip_search
+ against an empty or half-built corpus. If retrieval results are
+ weak (all scores < 0.25), grow the corpus with new queries.
+- **Keep a decision log of rejected picks**. When you pass on a clip
+ with a high score, note why (wrong era, overlit, wrong emotional
+ register). This helps the review stage.
+
+## Common Pitfalls
+
+- Treating the corpus as a stock library to pick from sequentially
+ instead of as a search index to query per slot.
+- Arranging clips by score rather than by narrative beat.
+- Letting visually-repetitive clips sit adjacent. Use
+ `clip_search` with `operation=diversify` before locking the edit.
+- Over-cutting. Documentary montage lives in the hold, not the jump.
+- Quietly inserting a narration track because the edit feels "thin".
+ Fix the edit; don't paper over it.
diff --git a/skills/pipelines/documentary-montage/idea-director.md b/skills/pipelines/documentary-montage/idea-director.md
new file mode 100644
index 00000000..d340750b
--- /dev/null
+++ b/skills/pipelines/documentary-montage/idea-director.md
@@ -0,0 +1,126 @@
+# Idea Director - Documentary Montage Pipeline
+
+## When To Use
+
+You are turning a user prompt into the brief artifact that every
+downstream stage will read. For this pipeline, the brief is the
+thematic core: what the montage is ABOUT, what it should feel like,
+and how long it should run.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/brief.schema.json` | Artifact validation |
+| User input | Conversation history | The raw ask |
+| Meta | `skills/meta/reviewer.md` | Self-review pass |
+
+## Process
+
+### 1. Extract The Thematic Question
+
+A documentary montage answers a question the user could not put into
+a sentence. Your job is to name that question in ONE line.
+
+Good thematic questions:
+
+- "What does it feel like to come home?"
+- "How did the 20th century think about the future?"
+- "What happens in a city at 4am?"
+- "What do all the footprints on Earth look like?"
+
+Bad thematic questions (too abstract or too concrete):
+
+- "A video about cities" (too abstract — no feeling)
+- "A montage with 8 specific shots of the moon" (too concrete — that's
+ a shot list, not a theme)
+
+### 2. Fix The Tone
+
+Choose ONE emotional register. Write it down. Everything downstream
+keys off this.
+
+Common registers for this pipeline:
+
+- **elegiac** — long holds, muted color, slow cuts (loss, memory, home)
+- **urgent** — short cuts, hard sync, motion-heavy (crisis, cities, now)
+- **reverent** — stately, symmetrical, patient (nature, ritual, scale)
+- **wry** — ironic juxtaposition, cut on absurdity (consumer culture,
+ politics, mid-century optimism)
+- **dreamlike** — slow dissolves, repeated motifs, non-linear (childhood,
+ grief, memory)
+
+### 3. Pick A Duration And A Shape
+
+Duration matters because it caps the number of beats.
+
+| Duration | Beats | Use |
+|----------|-------|-----|
+| 30-45s | 8-12 cuts | Social/Instagram/reel — one feeling, no arc |
+| 60-90s | 15-25 cuts | Standard short — mini arc with a turn |
+| 2-3 min | 30-50 cuts | Proper essay montage — 3-act arc possible |
+
+Shape options:
+
+- **single-image expansion** — one idea, held from many angles (good
+ for elegiac pieces under 60s)
+- **before/after** — first half establishes, second half turns (good
+ for wry or urgent registers)
+- **three-act** — setup → turn → release (the Adam Curtis move, needs
+ >90s)
+- **list/catalogue** — "everyone who..." structure, no arc, just
+ accumulation (good for reverent or elegiac)
+
+### 4. Note Music Intent
+
+Documentary montage is inseparable from its music bed. Decide now:
+
+- user-provided track (put path in `music_plan.source_path`),
+- music library pick (list what's in `music_library/`),
+- generated (name the tool and prompt seed),
+- or none (silence).
+
+**Warn the user if no music source is available.** Do not silently
+defer this — it becomes an expensive surprise at the asset stage.
+
+### 5. Record The Brief
+
+Minimum fields the brief must carry:
+
+```json
+{
+ "topic": "A minute in the rain",
+ "thematic_question": "What does rain show you about a city?",
+ "tone": "elegiac",
+ "duration_seconds": 90,
+ "shape": "list",
+ "sources_allowed": ["pexels", "archive_org", "nasa"],
+ "generated_clips_allowed": false,
+ "narration": "none",
+ "music_plan": { "source": "library", "path": "music_library/dawn_04.mp3" },
+ "era_mix": "any",
+ "target_platform": "social_short"
+}
+```
+
+`era_mix` is a documentary-specific field: "modern" biases toward
+Pexels, "vintage" biases toward Archive.org Prelinger, "any" leaves it
+open for the scene director to decide per slot.
+
+### 6. Quality Gate
+
+- Thematic question is ONE sentence.
+- Tone is ONE register from the fixed list.
+- Duration and shape are concrete numbers / enum values.
+- Music source is named OR the brief explicitly says "no music".
+- Sources list is non-empty and at least one is `available` per the
+ tool registry.
+
+## Common Pitfalls
+
+- Stating multiple themes ("it's about cities AND technology AND loss").
+ Pick one. The others become downstream associations.
+- Jumping to shot lists. The brief is about MEANING. Shots come next.
+- Ignoring duration. A 45s piece with 50 cuts is nausea. A 3-minute
+ piece with 12 cuts is a slideshow.
+- Forgetting to ask about music. The user usually has an opinion.
diff --git a/skills/pipelines/documentary-montage/scene-director.md b/skills/pipelines/documentary-montage/scene-director.md
new file mode 100644
index 00000000..50c0730a
--- /dev/null
+++ b/skills/pipelines/documentary-montage/scene-director.md
@@ -0,0 +1,301 @@
+# Scene Director - Documentary Montage Pipeline
+
+## When To Use
+
+The brief exists. You now have to turn a thematic question into a
+concrete list of SLOTS the retrieval layer can fill. Each slot is an
+intention ("a silhouette at a doorway at dusk") plus the queries that
+will find it in the real world (Pexels/Archive.org/NASA).
+
+This is the most creative stage in the pipeline. Retrieval is only as
+good as the slot descriptions you write.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/scene_plan.schema.json` | Artifact validation |
+| Prior artifact | `state.artifacts["idea"]["brief"]` | Thematic question, tone, duration, shape |
+| Reference | `skills/pipelines/documentary-montage/executive-producer.md` | Cross-stage rules |
+| Tools | none yet — this stage is pure planning | — |
+
+## Mental Model
+
+The scene director's job is NOT "pick clips". It is "describe what the
+clips need to be plainly enough that CLIP can find them".
+
+Think like a location scout, not a stock librarian.
+
+- A stock librarian says: *"rain in the city montage, 15 clips"*.
+- A location scout says: *"rain streaking sideways across a bus
+ window at blue hour, passengers' faces in soft focus, traffic
+ lights bleeding red and green through the glass"*.
+
+The second one is what CLIP can actually rank. The first one is a
+category label CLIP will match weakly and indiscriminately.
+
+## Process
+
+### 1. Turn The Shape Into A Beat Count
+
+Read the brief's `duration_seconds` and `shape`. Derive the number of
+slots. Use these defaults unless the tone says otherwise:
+
+| Tone | Average hold | Slots per 60s |
+|------|--------------|---------------|
+| elegiac | 4.0s | ~15 |
+| reverent | 3.5s | ~17 |
+| dreamlike | 3.0s | ~20 |
+| wry | 2.0s | ~30 |
+| urgent | 1.2s | ~50 |
+
+Then plan the arc according to shape:
+
+- **list**: N uniform slots, no inflection.
+- **before/after**: N/2 before slots + 1 pivot slot + N/2 after slots.
+- **three-act**: setup (30%) → turn (40%) → release (30%).
+- **single-image expansion**: 1 anchor image + N variations around it.
+
+Write the beat count down before writing any slot.
+
+### 2. Decompose The Thematic Question Into Concrete Beats
+
+Take the ONE thematic question from the brief and answer it in
+sensory language. Not themes — textures.
+
+**Example — "What does rain show you about a city?"**
+
+Bad decomposition (abstract, unsearchable):
+
+- "establishing the mood of the city"
+- "the feeling of being caught in weather"
+- "the universality of rain"
+
+Good decomposition (concrete, searchable):
+
+- a single raindrop hitting dry asphalt in slow motion
+- an umbrella opening in a doorway, a hand visible
+- neon signs reflected upside-down in a puddle
+- rain streaking across a bus window, passengers soft
+- a taxi roof light pushing through heavy rain, long lens
+- a storm drain swallowing leaves and water, overhead
+- a street vendor pulling plastic over a produce cart
+- steam rising off wet cobblestones under tungsten streetlight
+- a child's rubber boot stamping into a puddle
+- a lit apartment window seen through sheets of rain
+
+Each of those is a SHOT. Each is CLIP-rankable. Each is also *a
+different angle on the same idea*, which is what gives a list-shaped
+montage its weight.
+
+### 3. Write The Slot Description
+
+Every slot carries a `description` field. This is the text CLIP will
+embed and rank against. Write it like a good stock-footage tag string
+— nouns and adjectives, no verbs of intention, no emotion words.
+
+**Template:**
+
+```
+<subject>, <action/pose>, <environment>, <lighting>, <era/texture hint>
+```
+
+**Good:**
+
+- `"a single raindrop hitting dry asphalt, close up, slow motion,
+ warm streetlamp glow"`
+- `"empty city sidewalk at night after rain, reflected neon,
+ handheld, 1970s grain"`
+- `"an umbrella opening in a doorway, hand visible, diffused
+ afternoon light, shallow focus"`
+
+**Bad:**
+
+- `"the feeling of arriving home"` — emotion word, no subject
+- `"a warm welcoming moment"` — adjective soup, no image
+- `"someone going through a door in a symbolic way"` — intent, no shot
+
+Rule of thumb: if you can't imagine a specific photograph from the
+description, CLIP can't either.
+
+### 4. Write 2-3 Queries Per Slot
+
+The slot description is what CLIP ranks against. The queries are what
+the `corpus_builder` uses to populate the candidate pool. These are
+different jobs, so write them differently.
+
+Give each slot a `queries` array with 2-3 entries:
+
+1. **Literal query** — the most direct stock-search phrase. This is
+ what a Pexels user would type. `"raindrop on asphalt slow motion"`.
+2. **Lateral query** — the same idea from a different angle or scale.
+ `"wet pavement close up"`.
+3. **Association query** (optional, for hero slots) — an adjacent
+ concept that might surface texture clips the literal query misses.
+ `"first rain city street"`.
+
+Short queries beat long queries for stock search engines. 2-5 words
+each. No filler words.
+
+### 5. Target Sources Per Slot (Era-Aware)
+
+Read `brief.era_mix`. Assign each slot one or more `preferred_sources`
+based on what footage lives where:
+
+| Source | Strengths | Use when |
+|--------|-----------|----------|
+| `pexels` | Modern HD footage, clean shots, people, cities, nature | Default for modern/any era |
+| `archive_org` | Prelinger home movies, mid-century educational film, 1940s-1980s texture | Vintage, wry, dreamlike, anything nostalgic |
+| `nasa` | Earth-from-orbit, astronomy, flight, scale imagery | Reverent, anything about scale, space, planet, flight |
+
+If `era_mix = "vintage"`, bias slots toward `archive_org` and write
+queries in period-appropriate vocabulary ("commuter", "housewife",
+"suburb" not "influencer", "wfh", "coworking").
+
+If `era_mix = "any"`, mix sources per slot — the scene director
+decides which slot gets which source based on the beat's meaning.
+
+### 6. Mark Hero Slots
+
+Every montage has 2-3 slots the whole piece depends on: the opening
+image, the turn, the final image. Mark these with `hero: true` in the
+slot metadata.
+
+Hero slots get:
+
+- longer holds (2-4s instead of the tone's default),
+- bigger candidate pools at asset time (k=30 instead of k=10),
+- more queries (3 instead of 2).
+
+### 7. Leave Headroom For The Asset Stage
+
+Don't over-specify. The asset director's job is to rank candidates
+against your description. If you nail down the description AND the
+exact clip, you've done the asset director's job badly and pre-empted
+its creative choices.
+
+Rule: describe the slot the way you would describe it to a research
+assistant over the phone — specific enough to recognise, loose enough
+to surprise you.
+
+### 8. Record The Shot List
+
+Use the `scene_plan.schema.json` artifact with one `scene` per slot.
+For this pipeline, put documentary-montage-specific fields inside
+`metadata` on each scene. The canonical shape:
+
+```json
+{
+ "version": "1.0",
+ "scenes": [
+ {
+ "id": "slot_01",
+ "type": "broll",
+ "description": "a single raindrop hitting dry asphalt, close up, slow motion, warm streetlamp glow",
+ "start_seconds": 0.0,
+ "end_seconds": 3.5,
+ "narrative_role": "establish_context",
+ "hero_moment": true,
+ "texture_keywords": ["wet", "slow motion", "streetlamp"],
+ "required_assets": [
+ { "type": "video", "description": "raindrop on asphalt", "source": "source" }
+ ]
+ }
+ ],
+ "metadata": {
+ "pipeline": "documentary-montage",
+ "shape": "list",
+ "tone": "elegiac",
+ "thematic_question": "What does rain show you about a city?",
+ "slots": [
+ {
+ "id": "slot_01",
+ "description": "a single raindrop hitting dry asphalt, close up, slow motion, warm streetlamp glow",
+ "hero": true,
+ "preferred_sources": ["pexels", "archive_org"],
+ "queries": [
+ "raindrop on asphalt slow motion",
+ "wet pavement close up",
+ "first rain city street"
+ ],
+ "min_duration": 3.0,
+ "target_hold_seconds": 3.5,
+ "era_hint": "any"
+ }
+ ]
+ }
+}
+```
+
+The `scenes[]` array satisfies the schema. The `metadata.slots[]`
+array is what the asset director actually reads — it carries the
+retrieval-specific fields (`queries`, `preferred_sources`, `hero`,
+`era_hint`) that `scene_plan.schema.json` doesn't know about.
+
+### 9. Quality Gate
+
+- Slot count matches the beat-count math from step 1.
+- Every slot `description` follows the noun-and-adjective template —
+ no emotion words, no verbs of intention.
+- Every slot has 2-3 short queries (5 words or fewer each).
+- At least 2 slots are marked `hero`.
+- Sum of `target_hold_seconds` is within ±10% of `brief.duration_seconds`.
+- If `era_mix = "vintage"`, at least 60% of slots list `archive_org`
+ in `preferred_sources`.
+- `metadata.thematic_question` echoes the brief verbatim (sanity check
+ that you didn't drift).
+
+## Common Pitfalls
+
+- **Writing slot descriptions as intentions instead of images.** "A
+ moment of hesitation before entering" is a screenplay direction, not
+ a CLIP query. "A woman standing still on a porch, hand near the
+ knob" is.
+- **Category queries.** `"home"` and `"family"` match everything and
+ nothing. Push for concrete nouns: door, mat, key, hall, shoe.
+- **One-query slots.** The second query is cheap insurance — if the
+ first query returns junk, the corpus still has something usable.
+- **Forgetting duration math.** 90 elegiac seconds is ~15 holds of
+ ~6s. If you wrote 40 slots, you've drafted an urgent piece by
+ accident.
+- **Skipping `era_hint` on a vintage brief.** Pexels will flood the
+ corpus with 2020s HD footage and bury the Prelinger material.
+- **Letting the thematic question drift.** If the brief says "coming
+ home" and your slot list has three shots of airplanes, the piece
+ will be about travel, not home. Re-read the brief after drafting.
+
+## Worked Example — "A Minute in the Rain"
+
+- Duration: 90s, elegiac tone → ~15 slots at ~6s each.
+- Shape: list (catalogue of weather + city).
+- Thematic question: "What does rain show you about a city?"
+
+Sketch of slots (abbreviated):
+
+1. **hero** single raindrop hitting dry asphalt, slow motion
+2. umbrella opening in a doorway, diffused afternoon light
+3. neon sign reflected upside-down in a puddle, handheld
+4. rain streaking across a bus window, passengers soft focus
+5. a taxi roof light pushing through heavy rain, long lens
+6. storm drain swallowing leaves and water, overhead
+7. a street vendor pulling plastic over a produce cart
+8. wet cobblestone alley, steam rising, tungsten streetlamp
+9. rooftop antennae against a grey sky, wide shot
+10. a child's rubber boot stamping a puddle, low angle
+11. **hero** a lit apartment window seen through sheets of rain
+12. windshield wipers at night, colored city lights beyond
+13. rain beading on a parked bicycle seat, macro
+14. footprints filling with water on a tiled station floor
+15. **hero** first patch of blue sky breaking through grey clouds
+
+Each slot gets:
+
+- `description` in the noun-and-adjective template,
+- 2-3 short queries (e.g. slot 5: `"taxi heavy rain", "yellow cab
+ wet street night", "city traffic downpour"`),
+- `preferred_sources` (slots 1-6 → pexels+archive_org, slot 8 →
+ archive_org for period texture, slot 11 → pexels),
+- `hero: true` on slots 1, 11, 15,
+- `target_hold_seconds` summing to ~90.
+
+This is the artifact the asset director will run retrieval against.
diff --git a/tools/video/clip_search.py b/tools/video/clip_search.py
new file mode 100644
index 00000000..a141a6d3
--- /dev/null
+++ b/tools/video/clip_search.py
@@ -0,0 +1,356 @@
+"""Clip search: unified retrieval interface over a local clip corpus.
+
+This is the tool the documentary-montage director calls at edit time.
+It loads a corpus built by `corpus_builder` and exposes every
+retrieval operation the agent needs through a single dispatch
+interface.
+
+Operations
+----------
+- **rank_for_slot**: embed a text description of a scene slot and
+ return the top-k clips by fused visual+tag similarity. The agent's
+ main building block — "for this slot in the montage, what clips
+ match?"
+- **find_similar_set**: given one seed clip, return N clips that share
+ the seed's visual register but are diverse from each other (MMR).
+ Used for "collection" shots — all the doorways, all the footsteps,
+ all the keys-in-locks.
+- **diversify**: given a pre-selected list of clip_ids, greedily keep
+ the most mutually-dissimilar subset. Used at arrangement time to
+ prevent visually-redundant adjacent cuts.
+- **get**: look up one clip_id and return its full provenance dict.
+- **stats**: summary counts (rows, per-source breakdown, mean motion).
+
+All operations return JSON-serialisable dicts so the tool contract
+stays clean across process boundaries. ClipRecords are converted via
+`dataclasses.asdict`.
+
+The corpus is loaded fresh on every call. This keeps the tool
+stateless — the agent can call it from multiple stages without
+worrying about caches drifting out of sync. For a 1000-row corpus
+the load cost is <50 ms.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any, Optional
+
+from tools.base_tool import (
+ BaseTool,
+ Determinism,
+ ExecutionMode,
+ ResourceProfile,
+ ToolResult,
+ ToolRuntime,
+ ToolStability,
+ ToolStatus,
+ ToolTier,
+)
+
+
+class ClipSearch(BaseTool):
+ name = "clip_search"
+ version = "0.1.0"
+ tier = ToolTier.ANALYZE
+ capability = "clip_retrieval"
+ provider = "openmontage"
+ stability = ToolStability.EXPERIMENTAL
+ execution_mode = ExecutionMode.SYNC
+ determinism = Determinism.DETERMINISTIC
+ runtime = ToolRuntime.LOCAL
+
+ dependencies = [
+ "python:numpy",
+ "python:transformers",
+ "python:torch",
+ ]
+ install_instructions = (
+ "pip install numpy transformers torch\n"
+ "Requires a corpus built by corpus_builder at <corpus_dir>."
+ )
+ agent_skills = []
+
+ capabilities = [
+ "text_to_clip_ranking",
+ "visual_knn",
+ "mmr_diversification",
+ "provenance_lookup",
+ ]
+ supports = {
+ "fused_visual_tag_scoring": True,
+ "motion_filter": True,
+ "kind_filter": True,
+ "exclude_list": True,
+ }
+ best_for = [
+ "picking clips for a specific slot in a montage",
+ "finding collection-style sets from one seed clip",
+ "de-duplicating a candidate list before edit arrangement",
+ ]
+ not_good_for = [
+ "searching the internet (use corpus_builder to populate first)",
+ "editing or composing video (use video_compose)",
+ ]
+
+ input_schema = {
+ "type": "object",
+ "required": ["operation", "corpus_dir"],
+ "properties": {
+ "operation": {
+ "type": "string",
+ "enum": [
+ "rank_for_slot",
+ "find_similar_set",
+ "diversify",
+ "get",
+ "stats",
+ ],
+ },
+ "corpus_dir": {
+ "type": "string",
+ "description": "Path to the corpus built by corpus_builder.",
+ },
+ # rank_for_slot
+ "query_text": {
+ "type": "string",
+ "description": "Text description of the scene slot. "
+ "Embedded by CLIP for similarity ranking.",
+ },
+ "k": {"type": "integer", "default": 10, "minimum": 1},
+ "tag_weight": {
+ "type": "number",
+ "default": 0.3,
+ "minimum": 0.0,
+ "maximum": 1.0,
+ "description": "Blend between visual (1-w) and tag (w) channels.",
+ },
+ "motion_min": {
+ "type": "number",
+ "description": "Reject clips with motion_score below this. "
+ "Use ~1.5 to filter dead-still clips.",
+ },
+ "kind": {
+ "type": "string",
+ "enum": ["video", "image"],
+ "description": "Filter to only one media type.",
+ },
+ "exclude_ids": {
+ "type": "array",
+ "items": {"type": "string"},
+ "description": "Clip ids to skip (already used in this edit).",
+ },
+ # find_similar_set
+ "seed_clip_id": {"type": "string"},
+ "n": {"type": "integer", "default": 5, "minimum": 1},
+ "diversity": {
+ "type": "number",
+ "default": 0.3,
+ "minimum": 0.0,
+ "maximum": 1.0,
+ },
+ "candidate_pool": {"type": "integer", "default": 30},
+ # diversify
+ "candidate_ids": {"type": "array", "items": {"type": "string"}},
+ # get
+ "clip_id": {"type": "string"},
+ },
+ }
+
+ resource_profile = ResourceProfile(
+ cpu_cores=1, ram_mb=1024, vram_mb=0, disk_mb=50, network_required=False
+ )
+ side_effects = []
+ user_visible_verification = [
+ "Inspect returned clip_ids and visit thumb_dir/frame_02.jpg "
+ "to verify the retrieval matches the slot description.",
+ ]
+
+ def get_status(self) -> ToolStatus:
+ try:
+ import numpy # noqa: F401
+ import torch # noqa: F401
+ import transformers # noqa: F401
+ except ImportError:
+ return ToolStatus.UNAVAILABLE
+ return ToolStatus.AVAILABLE
+
+ def estimate_cost(self, inputs: dict[str, Any]) -> float:
+ return 0.0
+
+ # ------------------------------------------------------------------
+ # Execute
+ # ------------------------------------------------------------------
+
+ def execute(self, inputs: dict[str, Any]) -> ToolResult:
+ start = time.time()
+ try:
+ from lib.corpus import Corpus
+
+ operation = inputs["operation"]
+ corpus_dir = Path(inputs["corpus_dir"])
+
+ corp = Corpus(corpus_dir)
+ corp.load()
+
+ if operation == "stats":
+ payload = _op_stats(corp)
+ elif operation == "rank_for_slot":
+ payload = _op_rank_for_slot(corp, inputs)
+ elif operation == "find_similar_set":
+ payload = _op_find_similar_set(corp, inputs)
+ elif operation == "diversify":
+ payload = _op_diversify(corp, inputs)
+ elif operation == "get":
+ payload = _op_get(corp, inputs)
+ else:
+ return ToolResult(
+ success=False,
+ error=f"Unknown operation: {operation!r}",
+ )
+
+ return ToolResult(
+ success=True,
+ data={
+ "operation": operation,
+ "corpus_dir": str(corpus_dir),
+ "corpus_size": len(corp),
+ **payload,
+ },
+ duration_seconds=round(time.time() - start, 3),
+ cost_usd=0.0,
+ )
+ except Exception as e:
+ import traceback
+ return ToolResult(
+ success=False,
+ error=f"{type(e).__name__}: {e}\n{traceback.format_exc()[-800:]}",
+ )
+
+
+# ----------------------------------------------------------------------
+# Operations
+# ----------------------------------------------------------------------
+
+
+def _op_stats(corp) -> dict[str, Any]:
+ """Summary counts and per-source breakdown.
+
+ Useful as a sanity check before running expensive retrieval loops —
+ "does the corpus I loaded actually have enough clips to satisfy the
+ edit plan?"
+ """
+ import numpy as np
+
+ if len(corp) == 0:
+ return {
+ "rows": 0,
+ "per_source": {},
+ "per_kind": {},
+ "mean_motion_score": 0.0,
+ "mean_duration": 0.0,
+ }
+
+ per_source: dict[str, int] = {}
+ per_kind: dict[str, int] = {}
+ motion_scores: list[float] = []
+ durations: list[float] = []
+ for rec in corp.records:
+ per_source[rec.source] = per_source.get(rec.source, 0) + 1
+ per_kind[rec.kind] = per_kind.get(rec.kind, 0) + 1
+ motion_scores.append(rec.motion_score)
+ durations.append(rec.duration)
+
+ return {
+ "rows": len(corp),
+ "per_source": per_source,
+ "per_kind": per_kind,
+ "mean_motion_score": float(np.mean(motion_scores)) if motion_scores else 0.0,
+ "mean_duration": float(np.mean(durations)) if durations else 0.0,
+ }
+
+
+def _op_rank_for_slot(corp, inputs: dict[str, Any]) -> dict[str, Any]:
+ """Embed `query_text` and return top-k clips by fused similarity.
+
+ This is the agent's main retrieval move. The returned list is
+ ordered best-first and every entry carries a score so the agent
+ can decide whether the match is strong enough (>= 0.25 is a rough
+ "acceptable" threshold for CLIP ViT-B/32).
+ """
+ from lib.clip_embedder import embed_texts
+
+ query_text = inputs.get("query_text", "").strip()
+ if not query_text:
+ raise ValueError("rank_for_slot requires 'query_text'")
+
+ q_vec = embed_texts([query_text])[0]
+
+ results = corp.rank_by_text(
+ query_embedding=q_vec,
+ k=int(inputs.get("k", 10)),
+ tag_weight=float(inputs.get("tag_weight", 0.3)),
+ motion_min=inputs.get("motion_min"),
+ kind=inputs.get("kind"),
+ exclude_ids=inputs.get("exclude_ids") or [],
+ )
+ return {
+ "query_text": query_text,
+ "results": [
+ {"score": score, "record": asdict(rec)}
+ for rec, score in results
+ ],
+ }
+
+
+def _op_find_similar_set(corp, inputs: dict[str, Any]) -> dict[str, Any]:
+ """MMR-based similar-set retrieval from one seed clip."""
+ seed = inputs.get("seed_clip_id")
+ if not seed:
+ raise ValueError("find_similar_set requires 'seed_clip_id'")
+
+ results = corp.find_similar_set(
+ seed_clip_id=seed,
+ n=int(inputs.get("n", 5)),
+ diversity=float(inputs.get("diversity", 0.3)),
+ candidate_pool=int(inputs.get("candidate_pool", 30)),
+ exclude_ids=inputs.get("exclude_ids") or [],
+ )
+ return {
+ "seed_clip_id": seed,
+ "results": [
+ {"score": score, "record": asdict(rec)}
+ for rec, score in results
+ ],
+ }
+
+
+def _op_diversify(corp, inputs: dict[str, Any]) -> dict[str, Any]:
+ """Pick the most mutually-dissimilar subset of a candidate list."""
+ candidate_ids = inputs.get("candidate_ids") or []
+ if not candidate_ids:
+ raise ValueError("diversify requires 'candidate_ids'")
+
+ kept = corp.diversify(
+ candidate_ids=list(candidate_ids),
+ n=int(inputs.get("n", 5)),
+ diversity=float(inputs.get("diversity", 0.5)),
+ )
+ return {
+ "input_count": len(candidate_ids),
+ "kept_count": len(kept),
+ "kept_ids": kept,
+ }
+
+
+def _op_get(corp, inputs: dict[str, Any]) -> dict[str, Any]:
+ """Look up one clip_id and return its full record."""
+ clip_id = inputs.get("clip_id")
+ if not clip_id:
+ raise ValueError("get requires 'clip_id'")
+
+ rec = corp.get(clip_id)
+ if rec is None:
+ return {"clip_id": clip_id, "found": False, "record": None}
+ return {"clip_id": clip_id, "found": True, "record": asdict(rec)}
diff --git a/tools/video/corpus_builder.py b/tools/video/corpus_builder.py
new file mode 100644
index 00000000..28f7717c
--- /dev/null
+++ b/tools/video/corpus_builder.py
@@ -0,0 +1,553 @@
+"""Corpus builder: fan out across stock sources, download, thumb, embed, index.
+
+This is the tool the agent calls to populate a local clip corpus for
+the documentary-montage pipeline. It is deliberately the ONLY place
+where adapters, embedding, and the `Corpus` class meet — everything
+downstream (retrieval, selection, edit planning) reads from the corpus
+on disk and never touches sources directly.
+
+What it does, per query, per source, per candidate
+---------------------------------------------------
+1. Call `source.search(query, filters)` to get a flat list of
+ `Candidate`s normalised across sources.
+2. Skip candidates whose `clip_id` is already in the corpus (unless
+ `skip_existing=false`).
+3. Download the file to ``<corpus_dir>/clips/<clip_id>.<ext>``.
+4. For videos: extract N evenly-spaced frames to
+ ``<corpus_dir>/thumbnails/<clip_id>/frame_NN.jpg``, probe real
+ dimensions and duration, and compute a cheap motion score
+ (mean-abs-diff between first and middle frame).
+5. For images: copy the image as ``frame_00.jpg`` in the same thumb
+ directory so the embedder has a consistent input.
+6. Run CLIP on the thumbnails, pool frames to one 512-d vector for the
+ visual channel. Run CLIP on `source_tags` (falling back to the
+ query itself) for the tag channel.
+7. Materialise a `ClipRecord` with every provenance field and append
+ it to the corpus via `Corpus.add()`.
+8. After ALL candidates are processed, call `Corpus.save()` once. Per-
+ add saves would burn disk I/O for large runs.
+
+Caps
+----
+- `max_new_clips` halts the whole run once that many new rows have
+ been added. The remaining candidates in the current loop iteration
+ are discarded.
+- Per-source search errors and per-candidate processing errors are
+ caught and collected into `errors` in the return payload. One flaky
+ URL or one broken codec must not poison the whole run.
+
+Idempotence
+-----------
+Re-running with the same inputs is safe. `skip_existing=True` (default)
+causes the tool to short-circuit on any `clip_id` already in the
+corpus JSONL. Crash-recovery is handled by `Corpus.load()`, which
+truncates the in-memory state to the shorter of the JSONL and the
+`.npy` lengths.
+
+Agent surface
+-------------
+Input schema keeps the agent's decisions at the top: WHAT to search
+for (`queries`), WHERE to search (`sources`), WHAT to filter
+(`filters`), and HOW MUCH (`max_new_clips`). Everything else has
+sensible defaults.
+"""
+from __future__ import annotations
+
+import time
+import urllib.parse
+from pathlib import Path
+from typing import Any, Optional
+
+from tools.base_tool import (
+ BaseTool,
+ Determinism,
+ ExecutionMode,
+ ResourceProfile,
+ ToolResult,
+ ToolRuntime,
+ ToolStability,
+ ToolStatus,
+ ToolTier,
+)
+
+
+class CorpusBuilder(BaseTool):
+ name = "corpus_builder"
+ version = "0.1.0"
+ tier = ToolTier.SOURCE
+ capability = "corpus_population"
+ provider = "openmontage"
+ stability = ToolStability.EXPERIMENTAL
+ execution_mode = ExecutionMode.SYNC
+ determinism = Determinism.DETERMINISTIC
+ runtime = ToolRuntime.HYBRID # local compute + network APIs
+
+ dependencies = [
+ "python:cv2",
+ "python:numpy",
+ "python:requests",
+ "python:PIL",
+ "python:transformers",
+ "python:torch",
+ ]
+ install_instructions = (
+ "pip install opencv-python numpy requests pillow transformers torch\n"
+ "At least one stock source must be configured:\n"
+ " PEXELS_API_KEY for Pexels (free at https://www.pexels.com/api/)\n"
+ " archive.org and nasa work without API keys"
+ )
+ agent_skills = []
+
+ capabilities = [
+ "stock_fanout_search",
+ "corpus_population",
+ "clip_indexing",
+ "clip_embedding",
+ ]
+ supports = {
+ "multi_source": True,
+ "video_and_image": True,
+ "append_only": True,
+ "resumable": True,
+ }
+ best_for = [
+ "documentary-montage retrieval corpora",
+ "topic-based offline clip indexing",
+ "collecting candidate B-roll without repeated API calls per edit",
+ ]
+ not_good_for = [
+ "single-clip downloads (use pexels_video instead)",
+ "semantic retrieval itself (use clip_search)",
+ ]
+ fallback_tools = []
+
+ input_schema = {
+ "type": "object",
+ "required": ["corpus_dir", "queries"],
+ "properties": {
+ "corpus_dir": {
+ "type": "string",
+ "description": "Project-local corpus directory, e.g. projects/foo/corpus",
+ },
+ "queries": {
+ "type": "array",
+ "minItems": 1,
+ "items": {
+ "type": "object",
+ "required": ["query"],
+ "properties": {
+ "query": {"type": "string"},
+ "kind": {
+ "type": "string",
+ "enum": ["video", "image", "any"],
+ "default": "video",
+ },
+ "per_source": {
+ "type": "integer",
+ "default": 10,
+ "minimum": 1,
+ "maximum": 80,
+ },
+ },
+ },
+ },
+ "sources": {
+ "type": "array",
+ "items": {"type": "string"},
+ "description": "Source names to use (e.g. ['pexels','archive_org']). "
+ "Defaults to all available.",
+ },
+ "filters": {
+ "type": "object",
+ "properties": {
+ "min_duration": {"type": "number"},
+ "max_duration": {"type": "number"},
+ "orientation": {
+ "type": "string",
+ "enum": ["landscape", "portrait", "square"],
+ },
+ "min_width": {"type": "integer"},
+ },
+ },
+ "max_new_clips": {
+ "type": "integer",
+ "default": 100,
+ "minimum": 1,
+ "description": "Halt after this many NEW rows have been added.",
+ },
+ "skip_existing": {"type": "boolean", "default": True},
+ "thumbs_per_video": {
+ "type": "integer",
+ "default": 5,
+ "minimum": 1,
+ "maximum": 20,
+ },
+ },
+ }
+
+ resource_profile = ResourceProfile(
+ cpu_cores=2, ram_mb=2048, vram_mb=0, disk_mb=4000, network_required=True
+ )
+ side_effects = [
+ "downloads clips to <corpus_dir>/clips",
+ "writes thumbnails under <corpus_dir>/thumbnails",
+ "appends rows to <corpus_dir>/index.jsonl + embedding .npy files",
+ "calls external stock APIs",
+ ]
+ user_visible_verification = [
+ "Open <corpus_dir>/index.jsonl and inspect a few added rows",
+ "Open <corpus_dir>/thumbnails/<some_clip_id>/frame_02.jpg visually",
+ ]
+
+ def get_status(self) -> ToolStatus:
+ try:
+ from tools.video.stock_sources import available_sources
+ except Exception:
+ return ToolStatus.UNAVAILABLE
+ return ToolStatus.AVAILABLE if available_sources() else ToolStatus.UNAVAILABLE
+
+ def estimate_cost(self, inputs: dict[str, Any]) -> float:
+ return 0.0 # all sources are free-tier
+
+ # ------------------------------------------------------------------
+ # Execute
+ # ------------------------------------------------------------------
+
+ def execute(self, inputs: dict[str, Any]) -> ToolResult:
+ start = time.time()
+ try:
+ from lib.corpus import Corpus
+ from tools.video.stock_sources import (
+ SearchFilters,
+ available_sources,
+ get_source,
+ )
+
+ corpus_dir = Path(inputs["corpus_dir"])
+ queries: list[dict] = list(inputs["queries"])
+ source_names: Optional[list[str]] = inputs.get("sources")
+ filters_in: dict = inputs.get("filters") or {}
+ max_new = int(inputs.get("max_new_clips", 100))
+ skip_existing = bool(inputs.get("skip_existing", True))
+ thumbs_per_video = int(inputs.get("thumbs_per_video", 5))
+
+ # Resolve sources. If the caller passed an explicit list we
+ # respect it even if some are unavailable — their search
+ # calls will simply fail and be logged.
+ if source_names:
+ requested: list = []
+ for name in source_names:
+ try:
+ s = get_source(name)
+ except KeyError as e:
+ return ToolResult(success=False, error=str(e))
+ if s.is_available():
+ requested.append(s)
+ sources = requested
+ else:
+ sources = available_sources()
+
+ if not sources:
+ return ToolResult(
+ success=False,
+ error="No stock sources available. " + self.install_instructions,
+ )
+
+ corp = Corpus(corpus_dir)
+ corp.load()
+ corp.ensure_dirs()
+
+ per_source_counts: dict[str, int] = {s.name: 0 for s in sources}
+ added_ids: list[str] = []
+ errors: list[dict] = []
+ skipped = 0
+ failed = 0
+ candidates_seen = 0
+
+ def filters_for(q_spec: dict) -> SearchFilters:
+ return SearchFilters(
+ kind=q_spec.get("kind", "video"),
+ per_page=int(q_spec.get("per_source", 10)),
+ min_duration=filters_in.get("min_duration"),
+ max_duration=filters_in.get("max_duration"),
+ orientation=filters_in.get("orientation"),
+ min_width=filters_in.get("min_width"),
+ )
+
+ for q_spec in queries:
+ if len(added_ids) >= max_new:
+ break
+ query = q_spec["query"]
+ f = filters_for(q_spec)
+
+ for src in sources:
+ if len(added_ids) >= max_new:
+ break
+ try:
+ cands = src.search(query, f)
+ except Exception as e:
+ errors.append({
+ "phase": "search",
+ "source": src.name,
+ "query": query,
+ "error": f"{type(e).__name__}: {e}",
+ })
+ continue
+
+ candidates_seen += len(cands)
+ for cand in cands:
+ if len(added_ids) >= max_new:
+ break
+
+ if skip_existing and corp.has(cand.clip_id):
+ skipped += 1
+ continue
+
+ try:
+ rec = self._process_candidate(
+ cand=cand,
+ src=src,
+ corp=corp,
+ query=query,
+ thumbs_per_video=thumbs_per_video,
+ )
+ except Exception as e:
+ failed += 1
+ errors.append({
+ "phase": "process",
+ "clip_id": cand.clip_id,
+ "error": f"{type(e).__name__}: {e}",
+ })
+ continue
+
+ if rec is None:
+ failed += 1
+ continue
+ added_ids.append(rec.clip_id)
+ per_source_counts[src.name] = per_source_counts.get(src.name, 0) + 1
+
+ # Single save at the end. Corpus.save() writes JSONL first
+ # (source of truth) then both .npy files, so a crash mid-save
+ # still leaves a loadable corpus.
+ corp.save()
+
+ elapsed = time.time() - start
+ return ToolResult(
+ success=True,
+ data={
+ "corpus_dir": str(corpus_dir),
+ "queries_run": len(queries),
+ "candidates_seen": candidates_seen,
+ "clips_added": len(added_ids),
+ "clips_skipped_existing": skipped,
+ "clips_failed": failed,
+ "per_source_counts": per_source_counts,
+ "added_ids": added_ids,
+ "total_corpus_size": len(corp),
+ "errors": errors[:25], # cap log noise
+ },
+ cost_usd=0.0,
+ duration_seconds=round(elapsed, 2),
+ )
+ except Exception as e:
+ import traceback
+ return ToolResult(
+ success=False,
+ error=f"{type(e).__name__}: {e}\n{traceback.format_exc()[-800:]}",
+ )
+
+ # ------------------------------------------------------------------
+ # Per-candidate pipeline
+ # ------------------------------------------------------------------
+
+ def _process_candidate(
+ self,
+ cand,
+ src,
+ corp,
+ query: str,
+ thumbs_per_video: int,
+ ):
+ """Download → thumb → embed → add one Candidate to the corpus.
+
+ Returns the created `ClipRecord` on success, None if the clip
+ was rejected (download empty, thumb extraction failed, etc.).
+ Raises on unexpected errors (the caller logs them).
+ """
+ import cv2
+
+ from lib.clip_embedder import embed_images, embed_texts, pool_frames
+ from lib.corpus import ClipRecord
+
+ # Pick file extension from the URL path (sources give us
+ # stable .mp4/.jpg/.png URLs) with a kind-aware fallback.
+ ext = _guess_ext(cand)
+ local_rel = Path("clips") / f"{cand.clip_id}{ext}"
+ local_abs = corp.corpus_dir / local_rel
+
+ # Download. Any HTTP/IO exception propagates up to the
+ # per-candidate try in execute().
+ src.download(cand, local_abs)
+ if not local_abs.exists() or local_abs.stat().st_size < 1024:
+ # Empty / near-empty file = bad download. Clean up so a
+ # retry doesn't mistake it for success.
+ try:
+ if local_abs.exists():
+ local_abs.unlink()
+ except OSError:
+ pass
+ return None
+
+ thumb_dir_rel = Path("thumbnails") / cand.clip_id
+ thumb_dir_abs = corp.corpus_dir / thumb_dir_rel
+ thumb_dir_abs.mkdir(parents=True, exist_ok=True)
+
+ width = cand.width
+ height = cand.height
+ duration = cand.duration
+ motion_score = 0.0
+
+ if cand.kind == "video":
+ thumb_paths, probe = _extract_video_thumbs(
+ local_abs, thumb_dir_abs, thumbs_per_video
+ )
+ if not thumb_paths:
+ return None
+ if probe:
+ width = probe.get("width") or width
+ height = probe.get("height") or height
+ duration = probe.get("duration") or duration
+ motion_score = float(probe.get("motion_score", 0.0))
+ else:
+ dst = thumb_dir_abs / "frame_00.jpg"
+ if not _save_as_jpeg(local_abs, dst):
+ return None
+ thumb_paths = [dst]
+ img = cv2.imread(str(local_abs))
+ if img is not None:
+ height, width = img.shape[:2]
+
+ # CLIP embeddings. embed_images loads the model lazily on
+ # first call; subsequent candidates reuse the cached model.
+ clip_frames = embed_images(thumb_paths)
+ clip_vec = pool_frames(clip_frames)
+
+ # Tag channel: prefer source-supplied tags/description,
+ # fall back to the query so the row still carries SOME text
+ # signal. pool_frames returns zeros if empty so this never
+ # breaks the fused ranking math.
+ tag_text = cand.source_tags or query
+ tag_vec = embed_texts([tag_text])[0]
+
+ rec = ClipRecord(
+ clip_id=cand.clip_id,
+ source=cand.source,
+ source_id=cand.source_id,
+ source_url=cand.source_url,
+ local_path=str(local_rel).replace("\\", "/"),
+ kind=cand.kind,
+ thumb_dir=str(thumb_dir_rel).replace("\\", "/"),
+ query=query,
+ creator=cand.creator,
+ license=cand.license,
+ duration=float(duration or 0.0),
+ width=int(width or 0),
+ height=int(height or 0),
+ motion_score=motion_score,
+ dominant_colors=[],
+ source_tags=cand.source_tags,
+ )
+ corp.add(rec, clip_vec, tag_vec)
+ return rec
+
+
+# ----------------------------------------------------------------------
+# Module-level helpers (kept outside the class so tests can hit them)
+# ----------------------------------------------------------------------
+
+
+def _guess_ext(cand) -> str:
+ """Extract a sensible file extension from a candidate's URL."""
+ known = {".mp4", ".mov", ".mkv", ".webm", ".ogv", ".m4v",
+ ".jpg", ".jpeg", ".png", ".tif", ".tiff"}
+ path = urllib.parse.urlparse(cand.download_url).path
+ ext = Path(path).suffix.lower()
+ if ext in known:
+ # Normalise .jpeg→.jpg for consistent clip paths
+ return ".jpg" if ext == ".jpeg" else ext
+ return ".mp4" if cand.kind == "video" else ".jpg"
+
+
+def _extract_video_thumbs(
+ video_path: Path, out_dir: Path, n_frames: int
+) -> tuple[list[Path], dict]:
+ """Extract `n` evenly-spaced JPEG thumbnails from a video.
+
+ Returns ``(thumb_paths, probe_dict)``. The probe dict carries the
+ real dimensions, duration, and a cheap motion score (mean abs
+ pixel diff between frame 0 and the middle frame). Used to backfill
+ `ClipRecord` fields that the source API didn't give us.
+ """
+ import cv2
+
+ cap = cv2.VideoCapture(str(video_path))
+ if not cap.isOpened():
+ return [], {}
+
+ total = int(cap.get(cv2.CAP_PROP_FRAME_COUNT) or 0)
+ fps = float(cap.get(cv2.CAP_PROP_FPS) or 0)
+ width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH) or 0)
+ height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT) or 0)
+ duration = total / fps if fps > 0 else 0.0
+
+ if total < 2:
+ cap.release()
+ return [], {}
+
+ n = max(1, min(n_frames, total))
+ # Space positions at the midpoints of equal segments so we skip the
+ # first/last frame (often black or a splash).
+ positions = [int(round((i + 0.5) * total / n)) for i in range(n)]
+
+ thumb_paths: list[Path] = []
+ captured: list = []
+ for idx, pos in enumerate(positions):
+ cap.set(cv2.CAP_PROP_POS_FRAMES, max(0, min(pos, total - 1)))
+ ok, frame = cap.read()
+ if not ok or frame is None:
+ continue
+ dst = out_dir / f"frame_{idx:02d}.jpg"
+ cv2.imwrite(str(dst), frame, [int(cv2.IMWRITE_JPEG_QUALITY), 88])
+ thumb_paths.append(dst)
+ captured.append(frame)
+ cap.release()
+
+ motion = 0.0
+ if len(captured) >= 2:
+ import numpy as np
+ a = cv2.cvtColor(captured[0], cv2.COLOR_BGR2GRAY).astype(np.float32)
+ b = cv2.cvtColor(captured[len(captured) // 2], cv2.COLOR_BGR2GRAY).astype(np.float32)
+ motion = float(np.abs(a - b).mean())
+
+ return thumb_paths, {
+ "width": width,
+ "height": height,
+ "duration": duration,
+ "motion_score": motion,
+ }
+
+
+def _save_as_jpeg(src_path: Path, dst_path: Path) -> bool:
+ """Load an arbitrary image file and re-save as JPEG.
+
+ Handles PNG/JPEG/TIFF/WebP inputs — anything cv2.imread understands.
+ Returns True on success, False on unreadable input (so the caller
+ can reject the candidate cleanly).
+ """
+ import cv2
+
+ img = cv2.imread(str(src_path))
+ if img is None:
+ return False
+ cv2.imwrite(str(dst_path), img, [int(cv2.IMWRITE_JPEG_QUALITY), 88])
+ return True
diff --git a/tools/video/stock_sources/__init__.py b/tools/video/stock_sources/__init__.py
new file mode 100644
index 00000000..e4b3bf99
--- /dev/null
+++ b/tools/video/stock_sources/__init__.py
@@ -0,0 +1,80 @@
+"""Stock media source adapters.
+
+Unified-protocol wrappers around free stock APIs (Pexels, Archive.org,
+NASA, ...) used by `corpus_builder` to populate the local clip corpus.
+See `base.py` for the protocol contract and the "adding a new source"
+checklist.
+
+Registry
+--------
+`all_sources()` returns one instance of every adapter known to the
+package, in a stable order. `available_sources()` filters to the ones
+whose `is_available()` returns True right now. The corpus builder
+queries the latter during fan-out; it never imports adapters directly.
+
+To register a new adapter: add its class to the `_REGISTRY` tuple
+below. Order matters only as a tiebreak when two sources return
+matching clips.
+"""
+from __future__ import annotations
+
+from .archive_org import ArchiveOrgSource
+from .base import Candidate, SearchFilters, StockSource
+from .nasa import NasaSource
+from .pexels import PexelsSource
+
+__all__ = [
+ "Candidate",
+ "SearchFilters",
+ "StockSource",
+ "PexelsSource",
+ "ArchiveOrgSource",
+ "NasaSource",
+ "all_sources",
+ "available_sources",
+ "get_source",
+]
+
+# Explicit, ordered list of every adapter class the package exposes.
+# The corpus builder iterates this (filtered by availability) during
+# fan-out. Order matters only as a tiebreak for identical clip ids.
+_REGISTRY: tuple[type, ...] = (
+ PexelsSource,
+ ArchiveOrgSource,
+ NasaSource,
+)
+
+
+def all_sources() -> list[StockSource]:
+ """Instantiate every registered adapter, whether available or not.
+
+ Returned instances are cheap — adapters keep no state beyond env
+ var reads, so constructing them has no cost. Use this when you
+ want to show the user what sources exist regardless of whether
+ their credentials are configured.
+ """
+ return [cls() for cls in _REGISTRY]
+
+
+def available_sources() -> list[StockSource]:
+ """Return only the adapters whose `is_available()` is True.
+
+ This is what the corpus builder uses during a normal run. An empty
+ list means no sources are configured — the caller should surface
+ that to the user with install instructions, not silently produce
+ an empty corpus.
+ """
+ return [s for s in all_sources() if s.is_available()]
+
+
+def get_source(name: str) -> StockSource:
+ """Look up a single adapter by its `name` attribute.
+
+ Raises `KeyError` if no registered adapter claims that name. Useful
+ for tests and for agents that want to pin to a specific source
+ (e.g. "only Archive.org for this topic").
+ """
+ for s in all_sources():
+ if s.name == name:
+ return s
+ raise KeyError(f"No stock source registered with name={name!r}")
diff --git a/tools/video/stock_sources/archive_org.py b/tools/video/stock_sources/archive_org.py
new file mode 100644
index 00000000..3ca9ca3f
--- /dev/null
+++ b/tools/video/stock_sources/archive_org.py
@@ -0,0 +1,368 @@
+"""Archive.org stock video adapter.
+
+Targets public-domain film and home-movie collections on archive.org:
+
+ - **prelinger**: Rick Prelinger's archive of ephemeral films
+ (industrial, educational, advertising, 1920s-1980s). The single
+ best source of documentary-grade B-roll for 20th century themes.
+ - **opensource_movies**: broader public-domain and CC-licensed film
+ uploads — a grab bag but useful when Prelinger is thin on a topic.
+ - **home_movies**: anonymous personal footage. The soul of any
+ nostalgic or observational documentary montage lives here.
+
+Archive.org requires no API key. Everything is open.
+
+Fetch pattern
+-------------
+The search API (``advancedsearch.php``) returns metadata records with
+identifiers but not file lists. To get downloadable URLs we need a
+second call to ``/metadata/<identifier>`` per hit. This adapter pays
+that round-trip cost during `search()` so the `Candidate` it returns
+carries a ready-to-use `download_url`. For a per_page of 20, expect
+~21 HTTP calls per search — slow but fully serial and cache-friendly.
+
+Dimensions are sometimes missing from file metadata. When they are,
+the `Candidate` carries `width=0, height=0` and the corpus builder is
+expected to probe the clip with ffprobe post-download.
+
+Licence
+-------
+Prelinger collection items are public domain. Broader
+`opensource_movies` items are usually CC0 or CC-BY. We record the
+collection and `licenseurl` (when present) so the agent can attribute
+correctly if it wants to, but no attribution is legally required.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any, Optional
+
+from .base import Candidate, SearchFilters
+
+
+_SEARCH_URL = "https://archive.org/advancedsearch.php"
+_METADATA_URL = "https://archive.org/metadata"
+_DOWNLOAD_URL = "https://archive.org/download"
+
+# Default collections to bias toward. Overridable via SearchFilters.extra
+# in a future refinement; for now these are baked in because they give
+# the best documentary-montage hit rate.
+_DEFAULT_COLLECTIONS = ("prelinger", "opensource_movies", "home_movies")
+
+# File formats we accept, in preference order. Archive.org runs every
+# upload through a derivative pipeline so most items have multiple
+# renditions — we want the best mp4.
+_VIDEO_FORMAT_PRIORITY = (
+ "h.264", # mp4, usually 480p or 720p
+ "MPEG4", # older mp4 encoding
+ "h.264 HD", # less common, but best quality
+ "512Kb MPEG4", # last resort — lowest quality derivative
+ "Matroska", # mkv
+ "WebM", # webm
+)
+
+
+class ArchiveOrgSource:
+ """Adapter for public-domain video on archive.org.
+
+ Satisfies `StockSource`. Stateless, no credentials.
+ """
+
+ name = "archive_org"
+
+ def is_available(self) -> bool:
+ # No API key, no config. As long as the network is up, we're
+ # available. The corpus builder will catch network errors in
+ # the per-source try block.
+ return True
+
+ # ------------------------------------------------------------------
+ # Public protocol
+ # ------------------------------------------------------------------
+
+ def search(self, query: str, filters: SearchFilters) -> list[Candidate]:
+ """Search Archive.org for matching video items.
+
+ Two-stage: (1) advancedsearch for identifiers, (2) per-item
+ metadata fetch for file lists. Images are not supported — this
+ adapter returns an empty list for `kind="image"` since
+ Archive.org's image collections are a separate ecosystem (see
+ `nasa.py` for astronomy imagery instead).
+ """
+ kind = (filters.kind or "video").lower()
+ if kind not in ("video", "any"):
+ return []
+
+ import requests # lazy
+
+ q = self._build_query(query)
+ params = [
+ ("q", q),
+ ("fl[]", "identifier"),
+ ("fl[]", "title"),
+ ("fl[]", "description"),
+ ("fl[]", "creator"),
+ ("fl[]", "date"),
+ ("fl[]", "subject"),
+ ("fl[]", "licenseurl"),
+ ("fl[]", "collection"),
+ ("rows", str(max(1, min(filters.per_page, 50)))),
+ ("page", str(max(1, filters.page))),
+ ("output", "json"),
+ ]
+
+ r = requests.get(_SEARCH_URL, params=params, timeout=30)
+ r.raise_for_status()
+ data = r.json()
+ docs = (data.get("response") or {}).get("docs", []) or []
+
+ out: list[Candidate] = []
+ for doc in docs:
+ cand = self._hydrate_candidate(doc, filters)
+ if cand is not None:
+ out.append(cand)
+ return out
+
+ def download(self, candidate: Candidate, out_path: Path) -> Path:
+ """Stream the candidate's file to `out_path`.
+
+ Same pattern as the Pexels adapter — no caching, corpus builder
+ decides.
+ """
+ import requests # lazy
+
+ if not candidate.download_url:
+ raise ValueError(
+ f"Candidate {candidate.clip_id} has no download_url"
+ )
+
+ out_path = Path(out_path)
+ out_path.parent.mkdir(parents=True, exist_ok=True)
+
+ with requests.get(
+ candidate.download_url, stream=True, timeout=300
+ ) as r:
+ r.raise_for_status()
+ with open(out_path, "wb") as f:
+ for chunk in r.iter_content(chunk_size=1 << 16):
+ if chunk:
+ f.write(chunk)
+ return out_path
+
+ # ------------------------------------------------------------------
+ # Internals
+ # ------------------------------------------------------------------
+
+ def _build_query(self, user_query: str) -> str:
+ """Wrap the user's query with mediatype + collection filters.
+
+ Archive.org's query language is Solr-style — parentheses and
+ booleans work, and spaces default to AND. We quote the user
+ query so multi-word phrases stay intact.
+ """
+ coll = " OR ".join(f"collection:{c}" for c in _DEFAULT_COLLECTIONS)
+ user = user_query.strip()
+ if not user:
+ return f"mediatype:movies AND ({coll})"
+ # Quote the user query as a phrase AND a loose-term search so
+ # we get both precise matches and relevance-ranked hits.
+ return f'mediatype:movies AND ({coll}) AND ({user})'
+
+ def _hydrate_candidate(
+ self, doc: dict, filters: SearchFilters
+ ) -> Optional[Candidate]:
+ """Turn a search-doc identifier into a full Candidate.
+
+ Fetches the item's file list and picks the best playable
+ rendition. Returns None if the item has no usable files or if
+ the item's duration falls outside the filter range.
+ """
+ import requests # lazy
+
+ identifier = doc.get("identifier")
+ if not identifier:
+ return None
+
+ try:
+ r = requests.get(f"{_METADATA_URL}/{identifier}", timeout=30)
+ r.raise_for_status()
+ meta = r.json()
+ except Exception:
+ # Swallow per-item fetch failures — one bad item shouldn't
+ # poison the whole search. Alternative would be to raise and
+ # have corpus_builder catch per-source, but at this layer we
+ # can keep going.
+ return None
+
+ files = meta.get("files") or []
+ picked = _pick_video_file(files)
+ if picked is None:
+ return None
+
+ duration = _parse_length(picked.get("length"))
+ if filters.min_duration is not None and duration < filters.min_duration:
+ return None
+ if filters.max_duration is not None and 0 < duration < filters.max_duration:
+ # 0 means "unknown" — keep those, reject only known-too-long
+ pass
+ if filters.max_duration is not None and duration > filters.max_duration:
+ return None
+
+ width = _safe_int(picked.get("width"))
+ height = _safe_int(picked.get("height"))
+ if filters.min_width is not None and width and width < filters.min_width:
+ return None
+
+ # Build the direct download URL. archive.org/download/<id>/<file>
+ # is the stable public pattern and works without auth.
+ file_name = picked.get("name", "")
+ download_url = f"{_DOWNLOAD_URL}/{identifier}/{file_name}"
+
+ # Tags: flatten title + description + subject. Archive.org is
+ # verbose, so we truncate to keep the CLIP text encoder focused
+ # on the most important tokens (77-token limit anyway).
+ title = _to_text(doc.get("title"))
+ description = _to_text(doc.get("description"))
+ subject = _to_text(doc.get("subject"))
+ source_tags = " ".join(
+ s for s in (title, description, subject) if s
+ ).strip()
+ if len(source_tags) > 500:
+ source_tags = source_tags[:500]
+
+ creator = _to_text(doc.get("creator"))
+ collection = _to_text(doc.get("collection"))
+ license_url = _to_text(doc.get("licenseurl"))
+ license_text = license_url or _license_from_collection(collection)
+
+ return Candidate(
+ source=self.name,
+ source_id=identifier,
+ source_url=f"https://archive.org/details/{identifier}",
+ download_url=download_url,
+ kind="video",
+ width=width,
+ height=height,
+ duration=duration,
+ creator=creator,
+ license=license_text,
+ source_tags=source_tags,
+ thumbnail_url=f"https://archive.org/services/img/{identifier}",
+ extra={
+ "collection": collection,
+ "date": _to_text(doc.get("date")),
+ "format": picked.get("format"),
+ "file_name": file_name,
+ "file_size_bytes": _safe_int(picked.get("size")),
+ },
+ )
+
+
+# ----------------------------------------------------------------------
+# Module-level helpers
+# ----------------------------------------------------------------------
+
+
+def _pick_video_file(files: list[dict]) -> Optional[dict]:
+ """Pick the best playable video file from an Archive.org files list.
+
+ Preference order is defined by `_VIDEO_FORMAT_PRIORITY`. Within a
+ format, we prefer the largest file (size as a quality proxy), and
+ reject obvious thumbnails / derivative animations.
+ """
+ if not files:
+ return None
+
+ by_format: dict[str, list[dict]] = {}
+ for f in files:
+ fmt = (f.get("format") or "").strip()
+ name = (f.get("name") or "").lower()
+ # Skip non-video
+ if fmt not in _VIDEO_FORMAT_PRIORITY:
+ continue
+ # Skip degenerate renditions and thumbnails regardless of format
+ if any(tag in name for tag in ("thumb", "preview", ".gif")):
+ continue
+ by_format.setdefault(fmt, []).append(f)
+
+ for fmt in _VIDEO_FORMAT_PRIORITY:
+ bucket = by_format.get(fmt)
+ if not bucket:
+ continue
+ bucket.sort(key=lambda f: _safe_int(f.get("size")), reverse=True)
+ return bucket[0]
+ return None
+
+
+_HMS_RE = re.compile(r"^(\d+):(\d+):(\d+(?:\.\d+)?)$")
+_MS_RE = re.compile(r"^(\d+):(\d+(?:\.\d+)?)$")
+
+
+def _parse_length(value: Any) -> float:
+ """Parse Archive.org's `length` field into seconds.
+
+ The field is usually "HH:MM:SS.ss" or "MM:SS.ss" or a bare float
+ as a string. Missing / unparseable values return 0.0 which the
+ caller interprets as "unknown, pass any duration filter".
+ """
+ if value is None:
+ return 0.0
+ if isinstance(value, (int, float)):
+ return float(value)
+ s = str(value).strip()
+ if not s:
+ return 0.0
+ m = _HMS_RE.match(s)
+ if m:
+ h, mn, sec = m.groups()
+ return int(h) * 3600 + int(mn) * 60 + float(sec)
+ m = _MS_RE.match(s)
+ if m:
+ mn, sec = m.groups()
+ return int(mn) * 60 + float(sec)
+ try:
+ return float(s)
+ except ValueError:
+ return 0.0
+
+
+def _safe_int(value: Any) -> int:
+ """Parse a value to int, tolerating strings, None, and garbage."""
+ if value is None:
+ return 0
+ try:
+ return int(value)
+ except (TypeError, ValueError):
+ try:
+ return int(float(value))
+ except (TypeError, ValueError):
+ return 0
+
+
+def _to_text(value: Any) -> str:
+ """Flatten Archive.org's sometimes-list-sometimes-string fields.
+
+ The search API returns `creator`, `subject`, and `description` as
+ either a string or a list of strings depending on the item. We
+ always join with spaces so the caller sees a single str.
+ """
+ if value is None:
+ return ""
+ if isinstance(value, list):
+ return " ".join(str(x) for x in value if x is not None).strip()
+ return str(value).strip()
+
+
+def _license_from_collection(collection: str) -> str:
+ """Infer licence text from a collection name when no licenseurl is set.
+
+ Prelinger items are universally public domain; broader opensource
+ collections usually are too but we're less sure, so we hedge.
+ """
+ col = collection.lower()
+ if "prelinger" in col:
+ return "Public Domain (Prelinger Archives)"
+ if "home_movies" in col:
+ return "Public Domain (archive.org home movies)"
+ return "Public Domain / CC (archive.org — verify per item)"
diff --git a/tools/video/stock_sources/base.py b/tools/video/stock_sources/base.py
new file mode 100644
index 00000000..15891051
--- /dev/null
+++ b/tools/video/stock_sources/base.py
@@ -0,0 +1,140 @@
+"""Unified protocol for stock media source adapters.
+
+Every source (Pexels, Archive.org, NASA, Wikimedia, Unsplash, ...)
+implements the same small interface. The corpus builder fans out across
+all enabled sources, normalises their results into `Candidate` objects,
+downloads what it decides to keep, and writes everything to the local
+corpus. During selection the agent never sees which source a clip came
+from — it only sees `ClipRecord` rows retrieved by similarity.
+
+Design intent
+-------------
+- **Separation of concerns.** Adapters handle API shape, licensing
+ metadata, and downloading. `lib/corpus.py` handles indexing and
+ retrieval math. The agent handles WHAT to search for and WHICH
+ results to accept.
+- **Interchangeable.** Any adapter satisfies the same protocol, so the
+ corpus builder can iterate `for src in sources: src.search(q, f)`
+ without branching on source type.
+- **Dumb by design.** No ranking, no de-dup, no filtering beyond what
+ the API itself accepts. Judgment work happens after embedding, in
+ the agent. Adapters just convert "API JSON" → "normalised Candidate".
+
+Adding a new source
+-------------------
+1. Create `tools/video/stock_sources/<name>.py` with a class that
+ satisfies `StockSource` — a `name` attribute plus `is_available`,
+ `search`, and `download` methods.
+2. Normalise the API's response into `Candidate` objects. Keep every
+ field the corpus might later want to display or attribute (creator,
+ licence, source URL, description/tags for the text channel of the
+ CLIP fused ranking).
+3. Register the class so `corpus_builder` can discover it. The
+ registration pattern lives alongside the first concrete adapter.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional, Protocol, runtime_checkable
+
+
+@dataclass
+class Candidate:
+ """One pre-download search result, normalised across sources.
+
+ A `Candidate` is what a source adapter returns from `search()`. It
+ carries everything the corpus builder needs to decide whether to
+ download, plus the provenance fields that later get copied into the
+ `ClipRecord`.
+
+ Fields that don't apply to a given kind default to zero/empty — for
+ an image, `duration` is 0.0; for a source that doesn't expose fps,
+ `extra` may hold it or it may be absent entirely. Adapters should
+ populate as much as they cheaply can and leave the rest alone.
+ """
+
+ source: str # adapter name, e.g. "pexels"
+ source_id: str # unique within that source
+ source_url: str # landing page (human readable)
+ download_url: str # direct file URL
+ kind: str # "video" or "image"
+ width: int = 0
+ height: int = 0
+ duration: float = 0.0 # seconds (0 for images)
+ creator: str = "" # attribution name
+ license: str = "" # licence string or URL
+ source_tags: str = "" # title + description + tags joined
+ thumbnail_url: str = "" # for previews and image-fallback embeds
+ extra: dict[str, Any] = field(default_factory=dict) # source-specific junk
+
+ @property
+ def clip_id(self) -> str:
+ """Stable ID used as the corpus row key.
+
+ Format is ``"<source>_<source_id>"``. Matches the convention in
+ `lib/corpus.ClipRecord`, so the corpus builder can copy this
+ directly when it materialises the row.
+ """
+ return f"{self.source}_{self.source_id}"
+
+
+@dataclass
+class SearchFilters:
+ """Filters a source adapter applies when searching.
+
+ Not every source supports every filter — adapters MAY ignore fields
+ they don't understand. The corpus builder sets these liberally and
+ trusts each source to do the best it can with what it has. The
+ missing filters are caught later by the agent at retrieval time.
+ """
+
+ kind: str = "video" # "video", "image", or "any"
+ min_duration: Optional[float] = None # seconds; None = no floor
+ max_duration: Optional[float] = None # seconds; None = no ceiling
+ orientation: Optional[str] = None # "landscape" | "portrait" | "square"
+ min_width: Optional[int] = None # resolution floor in pixels
+ per_page: int = 20
+ page: int = 1
+
+
+@runtime_checkable
+class StockSource(Protocol):
+ """Protocol every stock source adapter must satisfy.
+
+ Attributes
+ ----------
+ name:
+ Stable key used in the corpus (becomes the prefix of each
+ `ClipRecord.clip_id`) and in any agent-facing source list. Do
+ NOT change it after a corpus has been built against it —
+ existing rows would orphan.
+
+ Methods
+ -------
+ is_available:
+ Cheap, non-network check. Answers "does the environment have
+ the keys / dependencies this source needs?" The corpus builder
+ silently skips unavailable sources during fan-out.
+
+ search:
+ Returns a flat list of `Candidate` objects in whatever order
+ the source's own relevance ranking gave them. An empty list is
+ legal (and common for niche queries). Network errors should be
+ raised — the corpus builder catches and logs per-source so one
+ flaky API doesn't poison the whole run.
+
+ download:
+ Saves the candidate's file to `out_path` (creating parent
+ directories if needed) and returns the final path. This is a
+ blocking call; any caching is the corpus builder's
+ responsibility, not the adapter's.
+ """
+
+ name: str
+
+ def is_available(self) -> bool: ...
+
+ def search(self, query: str, filters: SearchFilters) -> list[Candidate]: ...
+
+ def download(self, candidate: Candidate, out_path: Path) -> Path: ...
diff --git a/tools/video/stock_sources/nasa.py b/tools/video/stock_sources/nasa.py
new file mode 100644
index 00000000..282d91bd
--- /dev/null
+++ b/tools/video/stock_sources/nasa.py
@@ -0,0 +1,330 @@
+"""NASA Image and Video Library adapter.
+
+Wraps ``images-api.nasa.gov`` behind the `StockSource` protocol. NASA's
+catalogue is the best free source of space, mission, Earth-observation,
+and scientific-visualisation footage and stills. Everything on
+images.nasa.gov is free to use (public domain / NASA-created), with the
+caveat that third-party material occasionally sneaks in via partner
+missions — we record that caveat in the licence field and trust the
+user to vet before publishing.
+
+No API key required. An optional `NASA_API_KEY` increases rate limits
+but is not part of this adapter's availability check — the default
+`DEMO_KEY` path handles typical corpus-building loads.
+
+Fetch pattern
+-------------
+Like `archive_org`, this is a two-stage fetch. The search endpoint
+returns items with an `href` pointing at a per-item asset manifest (a
+plain JSON array of file URLs). We follow that manifest to pick the
+best rendition and build a `Candidate` with a ready-to-use
+`download_url`. One extra HTTP call per hit.
+
+What NASA is good for
+---------------------
+- space missions, rockets, astronauts,
+- Earth observation (weather, city lights, glaciers, hurricanes),
+- planetary-science animation,
+- historical aeronautics (NACA, shuttle era),
+- any "tiny human on a big planet" interstitial.
+
+What it is *not* good for: most documentary subjects that live on
+Earth at human scale. For a "walking home" montage this adapter will
+contribute atmosphere shots at best (sunrise over Earth, city lights
+from orbit) — the core material comes from Pexels and Archive.org.
+"""
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any, Optional
+from urllib.parse import quote, urlparse, urlunparse
+
+from .base import Candidate, SearchFilters
+
+
+_SEARCH_URL = "https://images-api.nasa.gov/search"
+_UNSAFE_ID_CHARS = re.compile(r"[^A-Za-z0-9._\-]+")
+
+
+class NasaSource:
+ """Adapter for images.nasa.gov.
+
+ Satisfies `StockSource`. Stateless, no required credentials.
+ """
+
+ name = "nasa"
+
+ def is_available(self) -> bool:
+ # The public API is unauthenticated; as long as the network is
+ # reachable we're available. `NASA_API_KEY` is optional and
+ # only affects rate limiting.
+ return True
+
+ # ------------------------------------------------------------------
+ # Public protocol
+ # ------------------------------------------------------------------
+
+ def search(self, query: str, filters: SearchFilters) -> list[Candidate]:
+ """Search NASA's media library for images and/or videos.
+
+ Routes by `filters.kind`:
+ "video" → `media_type=video`
+ "image" → `media_type=image`
+ "any" → both (NASA accepts repeated ``media_type`` params)
+ """
+ import requests # lazy
+
+ kind = (filters.kind or "video").lower()
+ media_types: list[str] = []
+ if kind in ("video", "any"):
+ media_types.append("video")
+ if kind in ("image", "any"):
+ media_types.append("image")
+ if not media_types:
+ return []
+
+ params: list[tuple[str, str]] = [("q", query)]
+ for mt in media_types:
+ params.append(("media_type", mt))
+ # NASA uses `page_size` (max 100) and `page` (1-indexed).
+ params.append(("page_size", str(max(1, min(filters.per_page, 100)))))
+ params.append(("page", str(max(1, filters.page))))
+
+ r = requests.get(_SEARCH_URL, params=params, timeout=30)
+ r.raise_for_status()
+ data = r.json()
+ items = ((data.get("collection") or {}).get("items") or [])
+
+ out: list[Candidate] = []
+ for item in items:
+ cand = self._hydrate_candidate(item, filters)
+ if cand is not None:
+ out.append(cand)
+ return out
+
+ def download(self, candidate: Candidate, out_path: Path) -> Path:
+ """Stream the candidate's file to `out_path`.
+
+ Same pattern as the other adapters.
+ """
+ import requests # lazy
+
+ if not candidate.download_url:
+ raise ValueError(
+ f"Candidate {candidate.clip_id} has no download_url"
+ )
+
+ out_path = Path(out_path)
+ out_path.parent.mkdir(parents=True, exist_ok=True)
+
+ with requests.get(
+ candidate.download_url, stream=True, timeout=300
+ ) as r:
+ r.raise_for_status()
+ with open(out_path, "wb") as f:
+ for chunk in r.iter_content(chunk_size=1 << 16):
+ if chunk:
+ f.write(chunk)
+ return out_path
+
+ # ------------------------------------------------------------------
+ # Internals
+ # ------------------------------------------------------------------
+
+ def _hydrate_candidate(
+ self, item: dict, filters: SearchFilters
+ ) -> Optional[Candidate]:
+ """Turn a search-result item into a Candidate with a download URL.
+
+ Fetches the per-item asset manifest (``item['href']`` is a
+ plain JSON array of file URLs) and picks the best rendition.
+ Returns None if the manifest is empty or no playable file
+ exists.
+ """
+ import requests # lazy
+
+ data_list = item.get("data") or []
+ if not data_list:
+ return None
+ meta = data_list[0]
+
+ nasa_id = meta.get("nasa_id")
+ media_type = (meta.get("media_type") or "").lower()
+ if not nasa_id or media_type not in ("video", "image"):
+ return None
+
+ asset_href = item.get("href")
+ if not asset_href:
+ return None
+
+ try:
+ r = requests.get(asset_href, timeout=30)
+ r.raise_for_status()
+ file_urls = r.json()
+ except Exception:
+ return None
+
+ if not isinstance(file_urls, list) or not file_urls:
+ return None
+
+ if media_type == "video":
+ download_url = _pick_video_url(file_urls)
+ else:
+ download_url = _pick_image_url(file_urls)
+ if not download_url:
+ return None
+ # NASA asset URLs sometimes contain unencoded spaces and other
+ # characters (especially older items whose nasa_id is a title).
+ # URL-encode the path component so `requests.get` handles them.
+ download_url = _encode_url_path(download_url)
+
+ # NASA doesn't give us dimensions or duration on the search
+ # result. Width/height default to 0 and the corpus builder is
+ # expected to probe post-download. Duration is 0 for both
+ # images and (unfortunately) videos.
+ width = 0
+ height = 0
+ duration = 0.0
+
+ # Filters that need dims/duration can't apply here. Skipping
+ # them is the honest thing — "unknown" should not be rejected.
+
+ title = (meta.get("title") or "").strip()
+ description = (meta.get("description") or "").strip()
+ keywords = meta.get("keywords") or []
+ if isinstance(keywords, list):
+ kw_text = " ".join(str(k) for k in keywords if k)
+ else:
+ kw_text = str(keywords)
+ source_tags = " ".join(
+ s for s in (title, description, kw_text) if s
+ ).strip()
+ if len(source_tags) > 500:
+ source_tags = source_tags[:500]
+
+ # Thumbnail: NASA exposes a "preview" link in item["links"]
+ thumbnail_url = ""
+ for link in item.get("links") or []:
+ if (link or {}).get("rel") == "preview":
+ thumbnail_url = link.get("href", "") or ""
+ break
+
+ creator = (meta.get("photographer") or meta.get("center") or "").strip()
+
+ safe_id = _sanitize_source_id(nasa_id)
+ return Candidate(
+ source=self.name,
+ source_id=safe_id,
+ source_url=f"https://images.nasa.gov/details/{quote(nasa_id, safe='')}",
+ download_url=download_url,
+ kind=media_type,
+ width=width,
+ height=height,
+ duration=duration,
+ creator=creator,
+ license="NASA Media Usage Guidelines (public domain with caveats)",
+ source_tags=source_tags,
+ thumbnail_url=thumbnail_url,
+ extra={
+ "center": meta.get("center"),
+ "date_created": meta.get("date_created"),
+ "secondary_creator": meta.get("secondary_creator"),
+ },
+ )
+
+
+# ----------------------------------------------------------------------
+# Module-level helpers
+# ----------------------------------------------------------------------
+
+
+def _pick_video_url(file_urls: list[str]) -> str:
+ """Pick the best video rendition from a NASA asset manifest.
+
+ NASA file URLs follow a ``<nasa_id>~<tag>.<ext>`` naming convention
+ where tag is one of: ``orig``, ``large``, ``medium``, ``small``,
+ ``preview``, ``thumb``. Preference order (best quality first):
+ orig → large → medium → small. We skip previews and thumbnails.
+ """
+ priority = ("orig", "large", "medium", "small")
+ buckets: dict[str, list[str]] = {p: [] for p in priority}
+ for url in file_urls:
+ lower = url.lower()
+ if not lower.endswith((".mp4", ".mov", ".m4v")):
+ continue
+ for p in priority:
+ if f"~{p}." in lower:
+ buckets[p].append(url)
+ break
+ for p in priority:
+ if buckets[p]:
+ return buckets[p][0]
+ # Fallback: any mp4 at all
+ for url in file_urls:
+ if url.lower().endswith(".mp4"):
+ return url
+ return ""
+
+
+def _pick_image_url(file_urls: list[str]) -> str:
+ """Pick the best image rendition from a NASA asset manifest.
+
+ Same pattern as videos but for .jpg/.png/.tif. Prefer ``orig``,
+ fall back to ``large``. We skip ``thumb`` and ``small`` because
+ they're too low-res for CLIP embedding quality.
+ """
+ priority = ("orig", "large", "medium")
+ buckets: dict[str, list[str]] = {p: [] for p in priority}
+ for url in file_urls:
+ lower = url.lower()
+ if not lower.endswith((".jpg", ".jpeg", ".png", ".tif", ".tiff")):
+ continue
+ for p in priority:
+ if f"~{p}." in lower:
+ buckets[p].append(url)
+ break
+ for p in priority:
+ if buckets[p]:
+ return buckets[p][0]
+ # Fallback: any jpg/png
+ for url in file_urls:
+ if url.lower().endswith((".jpg", ".jpeg", ".png")):
+ return url
+ return ""
+
+
+def _sanitize_source_id(raw: str) -> str:
+ """Collapse arbitrary NASA nasa_ids into a filesystem-safe token.
+
+ Some older items use their title as the nasa_id, which means the
+ raw string contains spaces, apostrophes, en-dashes, and other
+ characters that break file paths and command-line tooling. We
+ replace anything outside ``[A-Za-z0-9._-]`` with an underscore,
+ collapse runs, and strip edges. Length is capped at 120 chars so
+ the resulting clip_id stays well under filesystem limits.
+ """
+ if not raw:
+ return "unknown"
+ cleaned = _UNSAFE_ID_CHARS.sub("_", raw.strip())
+ cleaned = re.sub(r"_+", "_", cleaned).strip("_.")
+ if not cleaned:
+ return "unknown"
+ return cleaned[:120]
+
+
+def _encode_url_path(url: str) -> str:
+ """URL-encode the path component of a URL, leaving the host alone.
+
+ NASA occasionally returns asset URLs whose path literally contains
+ spaces and unicode — those will 400 if passed unquoted to
+ ``requests.get``. We use ``urllib.parse`` to surgically re-encode
+ only the path segment without double-encoding the scheme/host.
+ """
+ try:
+ parts = urlparse(url)
+ except Exception:
+ return url
+ safe_path = quote(parts.path, safe="/")
+ return urlunparse(parts._replace(path=safe_path))
diff --git a/tools/video/stock_sources/pexels.py b/tools/video/stock_sources/pexels.py
new file mode 100644
index 00000000..7386a156
--- /dev/null
+++ b/tools/video/stock_sources/pexels.py
@@ -0,0 +1,289 @@
+"""Pexels stock media source adapter.
+
+Wraps the Pexels video and image search APIs behind the unified
+`StockSource` protocol. Pexels is the workhorse for the
+documentary-montage pipeline: large catalogue, fast API, free, no
+attribution required, and stable URLs for cacheable downloads.
+
+Pexels exposes videos and images on two separate endpoints
+(``/videos/search`` and ``/v1/search``), so this adapter fans out
+internally and normalises both into the same `Candidate` shape. The
+corpus builder never branches on kind.
+
+Uses `PEXELS_API_KEY` from the environment. `.env` is loaded at process
+start by `tools.base_tool._load_dotenv`.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Optional
+
+from .base import Candidate, SearchFilters
+
+
+_VIDEO_SEARCH_URL = "https://api.pexels.com/videos/search"
+_IMAGE_SEARCH_URL = "https://api.pexels.com/v1/search"
+_PEXELS_LICENSE = "Pexels License (free, no attribution required)"
+
+
+class PexelsSource:
+ """Unified Pexels adapter for videos and images.
+
+ Satisfies `StockSource`. Stateless — all config comes from the
+ environment, so the corpus builder can instantiate one per run
+ without caching the instance.
+ """
+
+ name = "pexels"
+
+ def is_available(self) -> bool:
+ return bool(os.environ.get("PEXELS_API_KEY"))
+
+ # ------------------------------------------------------------------
+ # Public protocol
+ # ------------------------------------------------------------------
+
+ def search(self, query: str, filters: SearchFilters) -> list[Candidate]:
+ """Search Pexels, routing to video/image endpoints by `filters.kind`.
+
+ `kind="video"` hits only the videos endpoint, `kind="image"`
+ only the images endpoint, `kind="any"` queries both and
+ concatenates the results (videos first). The caller decides
+ ordering semantics downstream — this adapter does not re-rank.
+ """
+ kind = (filters.kind or "video").lower()
+ out: list[Candidate] = []
+ if kind in ("video", "any"):
+ out.extend(self._search_videos(query, filters))
+ if kind in ("image", "any"):
+ out.extend(self._search_images(query, filters))
+ return out
+
+ def download(self, candidate: Candidate, out_path: Path) -> Path:
+ """Stream the candidate's file to `out_path`.
+
+ Creates parent directories as needed. Uses streamed chunks so
+ large 1080p clips don't blow RAM. No caching — the corpus
+ builder is responsible for deciding whether to call this at
+ all.
+ """
+ import requests # lazy — avoid pulling requests at import time
+
+ if not candidate.download_url:
+ raise ValueError(
+ f"Candidate {candidate.clip_id} has no download_url"
+ )
+
+ out_path = Path(out_path)
+ out_path.parent.mkdir(parents=True, exist_ok=True)
+
+ with requests.get(
+ candidate.download_url, stream=True, timeout=120
+ ) as r:
+ r.raise_for_status()
+ with open(out_path, "wb") as f:
+ for chunk in r.iter_content(chunk_size=1 << 16):
+ if chunk:
+ f.write(chunk)
+ return out_path
+
+ # ------------------------------------------------------------------
+ # Internals
+ # ------------------------------------------------------------------
+
+ def _headers(self) -> dict[str, str]:
+ key = os.environ.get("PEXELS_API_KEY")
+ if not key:
+ raise RuntimeError(
+ "PEXELS_API_KEY not set. Get a free key at "
+ "https://www.pexels.com/api/ and add it to .env."
+ )
+ return {"Authorization": key}
+
+ def _search_videos(
+ self, query: str, filters: SearchFilters
+ ) -> list[Candidate]:
+ import requests # lazy
+
+ params: dict[str, Any] = {
+ "query": query,
+ "per_page": max(1, min(filters.per_page, 80)),
+ "page": max(1, filters.page),
+ }
+ if filters.orientation:
+ params["orientation"] = filters.orientation
+
+ r = requests.get(
+ _VIDEO_SEARCH_URL,
+ headers=self._headers(),
+ params=params,
+ timeout=30,
+ )
+ r.raise_for_status()
+ data = r.json()
+ videos = data.get("videos", []) or []
+
+ out: list[Candidate] = []
+ for v in videos:
+ # Duration filter. Pexels doesn't expose this server-side,
+ # so we filter client-side and accept that per_page may be
+ # partially consumed by clips we throw away.
+ duration = float(v.get("duration", 0) or 0)
+ if filters.min_duration is not None and duration < filters.min_duration:
+ continue
+ if filters.max_duration is not None and duration > filters.max_duration:
+ continue
+
+ rend = _pick_video_rendition(
+ v.get("video_files", []) or [],
+ min_width=filters.min_width or 0,
+ max_width=1920,
+ )
+ if rend is None:
+ continue
+
+ user = v.get("user") or {}
+ tag_text = _slug_tags_from_url(v.get("url", "") or "")
+
+ out.append(
+ Candidate(
+ source=self.name,
+ source_id=str(v.get("id")),
+ source_url=v.get("url", "") or "",
+ download_url=rend.get("link", "") or "",
+ kind="video",
+ width=int(rend.get("width") or v.get("width") or 0),
+ height=int(rend.get("height") or v.get("height") or 0),
+ duration=duration,
+ creator=user.get("name", "") or "",
+ license=_PEXELS_LICENSE,
+ source_tags=tag_text,
+ thumbnail_url=v.get("image", "") or "",
+ extra={
+ "fps": rend.get("fps"),
+ "rendition_quality": rend.get("quality"),
+ "user_url": user.get("url"),
+ },
+ )
+ )
+ return out
+
+ def _search_images(
+ self, query: str, filters: SearchFilters
+ ) -> list[Candidate]:
+ import requests # lazy
+
+ params: dict[str, Any] = {
+ "query": query,
+ "per_page": max(1, min(filters.per_page, 80)),
+ "page": max(1, filters.page),
+ }
+ if filters.orientation:
+ params["orientation"] = filters.orientation
+
+ r = requests.get(
+ _IMAGE_SEARCH_URL,
+ headers=self._headers(),
+ params=params,
+ timeout=30,
+ )
+ r.raise_for_status()
+ data = r.json()
+ photos = data.get("photos", []) or []
+
+ out: list[Candidate] = []
+ for p in photos:
+ width = int(p.get("width", 0) or 0)
+ height = int(p.get("height", 0) or 0)
+ if filters.min_width is not None and width < filters.min_width:
+ continue
+
+ src = p.get("src") or {}
+ # "large2x" is the sweet spot between detail and filesize
+ # for montage use — usually 1.5-2 MP. Fall back to
+ # "original" if the CDN gave us something weird.
+ download_url = src.get("large2x") or src.get("original") or ""
+ if not download_url:
+ continue
+
+ alt = (p.get("alt") or "").strip()
+
+ out.append(
+ Candidate(
+ source=self.name,
+ source_id=str(p.get("id")),
+ source_url=p.get("url", "") or "",
+ download_url=download_url,
+ kind="image",
+ width=width,
+ height=height,
+ duration=0.0,
+ creator=p.get("photographer", "") or "",
+ license=_PEXELS_LICENSE,
+ source_tags=alt,
+ thumbnail_url=src.get("medium", "") or "",
+ extra={
+ "photographer_url": p.get("photographer_url"),
+ "avg_color": p.get("avg_color"),
+ },
+ )
+ )
+ return out
+
+
+# ----------------------------------------------------------------------
+# Module-level helpers (also used by tests)
+# ----------------------------------------------------------------------
+
+
+def _pick_video_rendition(
+ video_files: list[dict],
+ min_width: int = 0,
+ max_width: int = 1920,
+) -> Optional[dict]:
+ """Pick the largest mp4/mov rendition within [min_width, max_width].
+
+ Pexels returns HLS, SD, HD, and sometimes UHD renditions per video.
+ We want the biggest file that fits our cap — "biggest" as a quality
+ proxy, "cap" so we don't waste bandwidth downloading 4K when we'll
+ scale to 720p anyway.
+ """
+ candidates = [
+ f for f in video_files
+ if (f.get("file_type", "") or "").startswith("video/")
+ and min_width <= int(f.get("width") or 0) <= max_width
+ and f.get("link")
+ ]
+ if not candidates:
+ return None
+ candidates.sort(key=lambda f: int(f.get("width") or 0), reverse=True)
+ return candidates[0]
+
+
+def _slug_tags_from_url(url: str) -> str:
+ """Extract a readable tag string from a Pexels video landing URL.
+
+ Pexels video JSON does not expose tags or descriptions reliably,
+ but the landing URL is a slug like::
+
+ https://www.pexels.com/video/aerial-view-of-city-at-night-3571264/
+
+ The slug is the closest thing to keywords the API gives us, and it
+ matches what the uploader described the clip as. We strip the
+ trailing numeric id and rejoin on spaces so the CLIP text encoder
+ can work with it.
+
+ Returns an empty string if the URL cannot be parsed — the caller
+ should treat that as "no tag signal for this clip".
+ """
+ if not url:
+ return ""
+ tail = url.rstrip("/").rsplit("/", 1)
+ if len(tail) != 2:
+ return ""
+ slug = tail[1]
+ parts = slug.rsplit("-", 1)
+ if len(parts) == 2 and parts[1].isdigit():
+ slug = parts[0]
+ return slug.replace("-", " ").strip()
diff --git a/tools/video/video_compose.py b/tools/video/video_compose.py
index b886a34b..7aa9100c 100644
--- a/tools/video/video_compose.py
+++ b/tools/video/video_compose.py
@@ -247,6 +247,32 @@ class VideoCompose(BaseTool):
"""Check if a file is a still image (routes to Remotion, not FFmpeg)."""
return path.suffix.lower() in VideoCompose._IMAGE_EXTENSIONS
+ @staticmethod
+ def _has_audio_stream(path: Path) -> bool:
+ """Return True iff ffprobe reports at least one audio stream.
+
+ Many stock video clips (especially from Pexels) ship with no audio
+ stream at all. If we blindly tell ffmpeg to transcode the 0:a stream
+ on such a file it errors out. This helper lets the segment builder
+ branch on stream presence so it can synthesize a silent track when
+ needed, keeping the concat segment layout consistent.
+ """
+ try:
+ out = subprocess.check_output(
+ [
+ "ffprobe", "-v", "error",
+ "-select_streams", "a",
+ "-show_entries", "stream=codec_type",
+ "-of", "default=nw=1:nk=1",
+ str(path),
+ ],
+ stderr=subprocess.STDOUT,
+ text=True,
+ )
+ return "audio" in out
+ except Exception:
+ return False
+
def _compose(self, inputs: dict[str, Any]) -> ToolResult:
"""FFmpeg composition: concat video cuts, add audio, burn subtitles.
@@ -326,23 +352,98 @@ class VideoCompose(BaseTool):
)
else:
# Video source: trim to segment.
- # -ss before -i for input-level seeking — more reliable
- # with -c copy when stream order is non-standard (e.g.
- # audio-first containers from Kling/fal.ai).
+ #
+ # Semantics:
+ # -ss BEFORE -i → fast input-level seek to in_s
+ # -t AFTER -i → "play for `duration` seconds"
+ # (unambiguous regardless of seek mode)
+ #
+ # We MUST re-encode here — `-c copy` cannot do frame-accurate
+ # cuts because it snaps to keyframes. With sparse GOPs (common
+ # in Pexels / AI-generated clips), stream-copy can produce
+ # segments significantly longer than `duration`, breaking the
+ # target timeline. Re-encoding with libx264/AAC is slower but
+ # gives exact cut boundaries. Same resolution in → same
+ # resolution out, so same-res inputs concat cleanly.
cmd = [
"ffmpeg", "-y",
"-ss", str(in_s),
+ "-t", str(duration),
"-i", str(source),
- "-to", str(out_s - in_s),
]
+ # Normalize every segment to a consistent container so the
+ # concat-copy step is always safe. The concat demuxer with
+ # `-c copy` requires identical codec / resolution / fps /
+ # pix_fmt / sar across ALL segments — otherwise it throws
+ # "Non-monotonous DTS" or silently produces corrupt output.
+ #
+ # Default target is 1920x1080 @ 30fps, yuv420p, sar=1. If the
+ # source is smaller it letterboxes; if larger it downscales.
+ # Callers can override via edit_decisions.metadata.compose_target
+ # (future extension) but the defaults match the most common
+ # delivery profile (YouTube landscape).
+ vf_parts: list[str] = [
+ "scale=1920:1080:force_original_aspect_ratio=decrease",
+ "pad=1920:1080:(ow-iw)/2:(oh-ih)/2:color=black",
+ "setsar=1",
+ "fps=30",
+ ]
+ af_parts: list[str] = []
if speed != 1.0:
- vf = f"setpts={1.0/speed}*PTS"
- af = self._build_atempo(speed)
- cmd.extend(["-filter:v", vf, "-filter:a", af])
- cmd.extend(["-c:v", codec, "-crf", str(crf), "-c:a", "aac"])
+ vf_parts.append(f"setpts={1.0/speed}*PTS")
+ af_parts.append(self._build_atempo(speed))
+
+ cmd.extend(["-filter:v", ",".join(vf_parts)])
+ if af_parts:
+ cmd.extend(["-filter:a", ",".join(af_parts)])
+
+ cmd.extend([
+ "-c:v", codec,
+ "-crf", str(crf),
+ "-preset", preset,
+ "-pix_fmt", "yuv420p",
+ "-r", "30",
+ ])
+
+ # Audio handling: some source clips have no audio stream
+ # (Pexels stock often ships silent). If we unconditionally
+ # ask ffmpeg to copy/encode the 0:a stream it errors out.
+ # Probe for an audio stream first — if present, transcode
+ # to AAC; if absent, synthesize a silent stereo track so
+ # concat segments have a consistent stream layout.
+ has_audio = self._has_audio_stream(source)
+ if has_audio:
+ cmd.extend(["-c:a", "aac", "-b:a", "192k", "-ar", "48000", "-ac", "2"])
else:
- cmd.extend(["-c", "copy"])
+ # Inject silent audio via lavfi before the output.
+ # We have to rebuild cmd to add the lavfi input
+ # before the output path and map streams explicitly.
+ cmd = [
+ "ffmpeg", "-y",
+ "-ss", str(in_s),
+ "-t", str(duration),
+ "-i", str(source),
+ "-f", "lavfi",
+ "-t", str(duration),
+ "-i", "anullsrc=channel_layout=stereo:sample_rate=48000",
+ "-filter:v", ",".join(vf_parts),
+ ]
+ if af_parts:
+ cmd.extend(["-filter:a", ",".join(af_parts)])
+ cmd.extend([
+ "-map", "0:v:0",
+ "-map", "1:a:0",
+ "-c:v", codec,
+ "-crf", str(crf),
+ "-preset", preset,
+ "-pix_fmt", "yuv420p",
+ "-r", "30",
+ "-c:a", "aac",
+ "-b:a", "192k",
+ "-ar", "48000",
+ "-ac", "2",
+ ])
cmd.append(str(seg_path))
self.run_command(cmd)