Add VLM-based semantic footage rating tools

[abdel-darwish-27]

Summary

Adds semantic video understanding to the footage pipeline using a local
vision-language model (Ollama served, e.g. Gemma 4 12B, Gemma 3n, or
Qwen-VL). CLIP tells you what a frame looks like; these tools tell you
what is actually happening in the clip, how well it was shot, and where
the good moments are.

This came out of a real project: rating 101 dog-walk clips for a product
campaign, where static CLIP retrieval got the context right but could not
tell pulling from calm walking, could not score camera stability, and
could not give cut-precise timestamps. The four tools below solve those
gaps, and are generic enough for any footage library.

What is included

Four new tools in tools/video/, one shared plumbing module, a skill,
and tests:

Tool	What it does
vlm_clip_rating	Coarse pass over a clip folder: behavior, energy, camera stability, shot type, composition, subject (product) visibility, timestamped segments and highlights. Configurable focus_prompt for what the edit cares about.
vlm_zoom_rating	Re-examines flagged windows at 4 fps and produces frame-accurate sub-beats: precise start/end seconds, camera angle, subject facing direction (for match cuts), deep-dive descriptions, and vibe.
vlm_editorial_ranking	Builds composite scores (stability, quality, subject, composition, vibe with tunable weights), per-purpose leaderboards, best-moment extraction, and match-cut chains.
vlm_comparative_rank	Optional second-opinion pass: shows 4 candidate clips in one context, asks for a relative ranking, calibrated scores, and reasons for best/worst. Use to break ties.
vlm-footage-rating skill	Documents the workflow, schemas, and editing recipes.
Tests	29 unit tests covering all four tools. Ollama HTTP calls are mocked, frame extraction uses synthetic ffmpeg clips, so the suite runs with no model, no network, no GPU.

Design notes

• Fully local: requires only ffmpeg and an Ollama vision model. No API keys.
• Every stage is idempotent: it reads the existing JSONL output and skips
  clips already processed, so re-runs after adding footage only do the new
  clips.
• VLM output is parsed defensively (prose-wrapped JSON, field-name drift,
  non-numeric timestamps are all tolerated) so one bad response never
  kills a batch.
• The tools register through the standard BaseTool pattern and are picked
  up automatically by the registry.

Testing

make lint        # passes (py_compile on all targets + new files)
make test        # full suite: 991 passed, 11 skipped

One pre-existing test is deselected locally because it hangs in the
project's own video_compose._mux_external_audio (times out at 180s).
That file is untouched by this PR. Flagging it in case you want a
separate look.

Example flow

from tools.video.vlm_clip_rating import VlmClipRating
from tools.video.vlm_zoom_rating import VlmZoomRating
from tools.video.vlm_editorial_ranking import VlmEditorialRanking

VlmClipRating().execute({
    "input_dir": "/path/to/clips",
    "output_path": "/path/to/clip_tags.jsonl",
    "focus_prompt": "a black collar (the product)",
})
VlmZoomRating().execute({
    "ratings_path": "/path/to/clip_tags.jsonl",
    "output_path": "/path/to/clip_zooms.jsonl",
})
VlmEditorialRanking().execute({
    "ratings_path": "/path/to/clip_tags.jsonl",
    "zooms_path": "/path/to/clip_zooms.jsonl",
    "output_path": "/path/to/editorial_rankings.json",
})

Then the editor (or an agent) can ask "which clips show the product in a
stable close-up?" and get a ranked, timestamped answer.

Model support and testing

The tools were built and validated against Gemma 4 12B (via Ollama,
gemma4:12b, ~8GB VRAM). That is the recommended model and the default.

Smaller vision models (gemma3n e2b/e4b, qwen2.5vl 3b/7b) are NOT yet
tested. They are listed with approximate VRAM figures in the skill so
users on smaller GPUs can try them, with the caveat that JSON conformance
and rating quality may differ. The defensive parsing in
vlm_rating_common is designed to absorb that drift. Contributions
validating a smaller model would be very welcome.

[calesthio]

Thank you for building a thoughtful local-first footage analysis workflow. I reviewed this against docs/PR_REVIEW_GUIDE.md and ran the focused suite (tests/tools/test_vlm_rating_common.py and tests/tools/test_vlm_rating_tools.py): 29 passed.

I found two runtime-contract blockers before this is merge-ready:

1. Failed clips are treated as successfully processed forever. vlm_clip_rating appends an error record containing clip, while load_rated_ids() treats every record with a clip as complete. A transient Ollama/ffmpeg failure is therefore skipped on every rerun, contrary to the advertised resumability. The zoom pass has the same issue when a clip is written with only failed windows. Please distinguish successful records from retryable failures and add a fail-then-rerun test.

2. Availability and locality metadata do not reflect the real runtime. The VLM-backed tools report AVAILABLE when ffmpeg exists even if Ollama is not running or the requested/default vision model is absent. That makes unavailable tools look configured, which the review guide explicitly calls out. Also, supports.local_only / network_required=False conflict with accepting an arbitrary ollama_url that receives base64-encoded user frames. Please either constrain the endpoint to loopback or represent the network/privacy behavior accurately, and make status/setup checks cover the Ollama service/model. (pip install requests should also be removed unless it is actually required.)

Please add the guide's registry discovery/status coverage for these four new tools as part of the fix. Once those contracts are accurate, the core implementation and focused test coverage look strong.

[calesthio]

Thank you for the local VLM footage-rating workflow. Failure records remain retryable, local-only privacy/status contracts are accurate, registry coverage is complete, and CI passes. This is merge-ready.