Video Captioning Agent — Multi-Style AI Captions

This project tackles automated video captioning with a focus on efficiency, accuracy, and production-grade robustness. Single-pass inference. Instead of one API call per caption style, the pipeline extracts frames once and sends them to Gemini 2.5 Flash exactly once, receiving structured JSON with both video-understanding metadata (subjects, setting, camera motion, apparent emotion) and all four captions simultaneously — fewer API calls, one network round-trip instead of a waterfall, and video context transmitted only once. Hybrid frame extraction. extract_frames.py combines three evenly-spaced anchor frames for temporal coverage with FPS-scaled histogram-based scene-change detection, adapting sampling density correctly across frame rates from 12fps to 60fps. Production hardening. The pipeline never crashes a batch on one bad task: malformed JSON triggers an automatic repair-prompt retry before falling back to a graceful empty result; every dictionary access uses safe defaults; exponential backoff with Retry-After handling covers transient API errors; output verification enforces word limits, single-sentence structure, and clean text before a caption is accepted. Anti-hallucination guarantees. The prompt forbids inventing objects, people, locations, or actions not visible in frames — uncertain elements are labeled "unknown." All four styles must describe the same underlying facts; only tone varies. Humorous captions must ground their joke in a specific visible object or action rather than generic filler. Batch orchestration. run_all.py processes tasks concurrently via ThreadPoolExecutor, validates every requested style is present and non-empty, and exits with a status code reflecting overall batch success.