videopython 0.46.0__tar.gz → 0.48.0__tar.gz

{videopython-0.46.0 → videopython-0.48.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: videopython
-Version: 0.46.0
+Version: 0.48.0
 Summary: Minimal video generation and processing library.
 Project-URL: Homepage, https://videopython.com
 Project-URL: Repository, https://github.com/bartwojtowicz/videopython/
@@ -29,6 +29,7 @@ Requires-Dist: demucs>=4.0.0; extra == 'ai'
 Requires-Dist: diffusers>=0.30.0; extra == 'ai'
 Requires-Dist: imagehash>=4.3; extra == 'ai'
 Requires-Dist: llama-cpp-python>=0.3.0; extra == 'ai'
+Requires-Dist: ollama>=0.5.0; extra == 'ai'
 Requires-Dist: openai-whisper>=20240930; extra == 'ai'
 Requires-Dist: pyannote-audio>=4.0.0; extra == 'ai'
 Requires-Dist: pyloudnorm>=0.1.1; extra == 'ai'
@@ -40,48 +41,6 @@ Requires-Dist: torchaudio>=2.8.0; extra == 'ai'
 Requires-Dist: transformers>=5.2.0; extra == 'ai'
 Requires-Dist: transnetv2-pytorch>=1.0.5; extra == 'ai'
 Requires-Dist: ultralytics>=8.0.0; extra == 'ai'
-Provides-Extra: asr
-Requires-Dist: openai-whisper>=20240930; extra == 'asr'
-Requires-Dist: pyannote-audio>=4.0.0; extra == 'asr'
-Requires-Dist: silero-vad>=5.1; extra == 'asr'
-Requires-Dist: torch>=2.8.0; extra == 'asr'
-Requires-Dist: torchaudio>=2.8.0; extra == 'asr'
-Provides-Extra: dub
-Requires-Dist: demucs>=4.0.0; extra == 'dub'
-Requires-Dist: llama-cpp-python>=0.3.0; extra == 'dub'
-Requires-Dist: openai-whisper>=20240930; extra == 'dub'
-Requires-Dist: pyannote-audio>=4.0.0; extra == 'dub'
-Requires-Dist: pyloudnorm>=0.1.1; extra == 'dub'
-Requires-Dist: sentencepiece>=0.1.99; extra == 'dub'
-Requires-Dist: silero-vad>=5.1; extra == 'dub'
-Requires-Dist: torch>=2.8.0; extra == 'dub'
-Requires-Dist: torchaudio>=2.8.0; extra == 'dub'
-Requires-Dist: transformers>=5.2.0; extra == 'dub'
-Provides-Extra: generation
-Requires-Dist: accelerate>=0.29.2; extra == 'generation'
-Requires-Dist: diffusers>=0.30.0; extra == 'generation'
-Requires-Dist: torch>=2.8.0; extra == 'generation'
-Requires-Dist: torchaudio>=2.8.0; extra == 'generation'
-Requires-Dist: transformers>=5.2.0; extra == 'generation'
-Provides-Extra: separation
-Requires-Dist: demucs>=4.0.0; extra == 'separation'
-Requires-Dist: torch>=2.8.0; extra == 'separation'
-Requires-Dist: torchaudio>=2.8.0; extra == 'separation'
-Provides-Extra: translation
-Requires-Dist: llama-cpp-python>=0.3.0; extra == 'translation'
-Requires-Dist: sentencepiece>=0.1.99; extra == 'translation'
-Requires-Dist: torch>=2.8.0; extra == 'translation'
-Requires-Dist: transformers>=5.2.0; extra == 'translation'
-Provides-Extra: tts
-Requires-Dist: chatterbox-tts>=0.1.7; extra == 'tts'
-Provides-Extra: vision
-Requires-Dist: imagehash>=4.3; extra == 'vision'
-Requires-Dist: qwen-vl-utils>=0.0.10; extra == 'vision'
-Requires-Dist: torch>=2.8.0; extra == 'vision'
-Requires-Dist: torchaudio>=2.8.0; extra == 'vision'
-Requires-Dist: transformers>=5.2.0; extra == 'vision'
-Requires-Dist: transnetv2-pytorch>=1.0.5; extra == 'vision'
-Requires-Dist: ultralytics>=8.0.0; extra == 'vision'
 Description-Content-Type: text/markdown
 
 # videopython
@@ -104,8 +63,6 @@ pip install videopython          # core video/audio editing
 pip install "videopython[ai]"    # + ALL local AI features (GPU recommended)
 ```
 
-AI deps are also split into granular extras so you can install only what you need: `[asr]` (transcription), `[vision]` (detection/scene/VLM), `[separation]`, `[translation]`, `[tts]` (voice cloning), `[generation]` (image/video/music), and `[dub]` (the dubbing pipeline). `[dub]` excludes chatterbox — add `[tts]` for local synthesis (`pip install "videopython[dub,tts]"`) or inject a `SpeechBackend`. See the [Installation Guide](https://videopython.com/getting-started/installation/) for the full table.
-
 Python `>=3.11, <3.14`. AI features run locally — no cloud API keys required, but model weights are downloaded on first use.
 
 ## Quick Start

{videopython-0.46.0 → videopython-0.48.0}/README.md

@@ -18,8 +18,6 @@ pip install videopython          # core video/audio editing
 pip install "videopython[ai]"    # + ALL local AI features (GPU recommended)
 ```
 
-AI deps are also split into granular extras so you can install only what you need: `[asr]` (transcription), `[vision]` (detection/scene/VLM), `[separation]`, `[translation]`, `[tts]` (voice cloning), `[generation]` (image/video/music), and `[dub]` (the dubbing pipeline). `[dub]` excludes chatterbox — add `[tts]` for local synthesis (`pip install "videopython[dub,tts]"`) or inject a `SpeechBackend`. See the [Installation Guide](https://videopython.com/getting-started/installation/) for the full table.
-
 Python `>=3.11, <3.14`. AI features run locally — no cloud API keys required, but model weights are downloaded on first use.
 
 ## Quick Start

{videopython-0.46.0 → videopython-0.48.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "videopython"
-version = "0.46.0"
+version = "0.48.0"
 description = "Minimal video generation and processing library."
 authors = [
     { name = "Bartosz Wójtowicz", email = "bartoszwojtowicz@outlook.com" },
@@ -53,90 +53,46 @@ dev = [
     "mkdocstrings>=1.0.0",
     "mkdocstrings-python>=2.0.1",
 ]
-# Thin dev-workflow group so `uv sync` / uv.lock keep working. Resolves the
-# SAME set as the aggregate `[ai]` extra below via a PEP 508 self-reference, so
-# there is a single source of truth (the granular extras) and no hand-sync.
-# `test_packaging_extras.py` asserts this stays consistent with the extra.
+# Thin dev-workflow group so `uv sync` / uv.lock keep working. References the
+# `[ai]` extra so dev installs every AI capability (single source of truth).
 ai = ["videopython[ai]"]
 
-# pip install videopython[<extra>] - pip uses optional-dependencies, not dependency-groups.
+# pip install "videopython[ai]" - pip uses optional-dependencies, not dependency-groups.
 #
-# Granular extras partition the heavy ML deps by the leaf module that imports
-# them, so consumers install only what a capability needs. `ai` is a convenience
-# aggregate that installs EVERYTHING via PEP 685 self-references (no hand-sync).
-# `test_packaging_extras.py` enforces union(granular) == ai as a drift guard.
+# A single [ai] extra installs every AI capability. The heavy ML deps still load
+# lazily at first use (no top-level imports under ai/), so importing videopython
+# stays light even with [ai] installed.
 [project.optional-dependencies]
-# Speech recognition / diarization (understanding/audio.py).
-asr = [
+ai = [
+    # Speech recognition / diarization (understanding/audio.py)
     "openai-whisper>=20240930",
     "pyannote-audio>=4.0.0",
-    # Voice activity detection (used by AudioToText to gate Whisper language detection)
     "silero-vad>=5.1",
-    "torch>=2.8.0",
-    "torchaudio>=2.8.0",
-]
-# Visual understanding: detection, scene/temporal, VLM (understanding/{faces,
-# objects,temporal,image}.py + video_analysis). transformers also backs the AST
-# AudioClassifier and the SceneVLM; qwen-vl-utils is the SceneVLM preprocessor;
-# imagehash is the SceneVLM frame-dedup; transnetv2 is scene detection.
-vision = [
+    # Visual understanding: detection, scene/temporal, VLM (understanding/*, video_analysis)
     "ultralytics>=8.0.0",
     "transnetv2-pytorch>=1.0.5",
     "transformers>=5.2.0",
     "qwen-vl-utils>=0.0.10",
     "imagehash>=4.3",
-    "torch>=2.8.0",
-    "torchaudio>=2.8.0",
-]
-# Audio source separation (understanding/separation.py).
-separation = [
+    # Audio source separation (understanding/separation.py)
     "demucs>=4.0.0",
-    "torch>=2.8.0",
-    "torchaudio>=2.8.0",
-]
-# Text translation backends (generation/translation.py MarianMT +
-# generation/qwen3.py Qwen3 GGUF). MarianTokenizer requires sentencepiece.
-translation = [
-    "transformers>=5.2.0",
+    # Translation backends (generation/translation.py MarianMT, generation/qwen3.py GGUF)
     "sentencepiece>=0.1.99",
     "llama-cpp-python>=0.3.0",
-    "torch>=2.8.0",
-]
-# Voice cloning TTS (generation/audio.py — Chatterbox Multilingual by Resemble
-# AI). ISOLATED: chatterbox-tts 0.1.7 carries the strict pins that force the
-# [tool.uv].override-dependencies block. This is the ONLY extra that drags them.
-# Left to chatterbox's own torch==2.6.0 / torchaudio==2.6.0 pins (no floors
-# here) so `pip install videopython[tts]` resolves STANDALONE in its own
-# image/Modal function -- the whole point of running TTS behind SpeechBackend.
-# The all-in [ai] resolve forces torch>=2.8.0 over this via override-dependencies.
-tts = [
+    # Voice cloning TTS (generation/audio.py — Chatterbox); its strict pins drive
+    # the [tool.uv].override-dependencies block below.
     "chatterbox-tts>=0.1.7",
-]
-# Local media generation: SDXL/CogVideoX (generation/{image,video}.py) +
-# MusicGen (generation/audio.py TextToMusic, via transformers).
-generation = [
+    # Local media generation: SDXL/CogVideoX + MusicGen (generation/*)
     "diffusers>=0.30.0",
-    "transformers>=5.2.0",
     "accelerate>=0.29.2",
+    # Dubbing loudness matching (dubbing/loudness.py)
+    "pyloudnorm>=0.1.1",
+    # LLM-authored editing planner (auto_edit/local.py OllamaVisionLLM)
+    "ollama>=0.5.0",
+    # Shared torch stack
     "torch>=2.8.0",
     "torchaudio>=2.8.0",
 ]
-# Dubbing pipeline's hard top-level deps: transcription (asr) + source
-# separation (separation) + translation, plus BS.1770 loudness matching
-# (dubbing/loudness.py). Deliberately EXCLUDES tts/chatterbox: local synthesis
-# runs through the SpeechBackend protocol against a separately-installed [tts]
-# extra or an injected remote backend, so a [dub] image co-resolves WITHOUT
-# chatterbox's override-forcing pin. A bare [dub] install that hits local
-# synthesis raises a clear [tts]-pointing ImportError.
-dub = [
-    "videopython[asr,separation,translation]",
-    # Loudness measurement (BS.1770) for dub-vs-source loudness matching (M3)
-    "pyloudnorm>=0.1.1",
-]
-# Convenience aggregate: installs every capability. PEP 685 self-references make
-# this the single "everything" install with no hand-duplicated dep list. This
-# combined resolve is what the [tool.uv].override-dependencies block exists for.
-ai = ["videopython[asr,vision,separation,translation,tts,generation,dub]"]
 
 [project.urls]
 Homepage = "https://videopython.com"
@@ -172,16 +128,10 @@ module = [
 ignore_missing_imports = true
 
 [tool.uv]
-# LOAD-BEARING ONLY for the all-in `[ai]` resolve (every extra installed
-# together, as in dev/CI and `uv sync`). chatterbox-tts 0.1.7 (the `[tts]`
-# extra) pins strict torch/torchaudio/numpy/diffusers that conflict with
-# pyannote-audio (torch>=2.8, `[asr]`) and CogVideoX (diffusers>=0.30,
-# `[generation]`). This override lets the combined resolver pick compatible
-# versions. A consumer installing a SUBSET that excludes chatterbox — notably
-# `[dub]` (asr+separation+translation+pyloudnorm, no tts) — co-resolves cleanly
-# WITHOUT this override; that clean `[dub]` resolve is the whole point of
-# isolating `[tts]`. The ai dependency floors are aligned with these overrides
-# to keep pip and uv resolving similar versions.
+# chatterbox-tts 0.1.7 (in [ai]) pins strict torch/torchaudio/numpy/diffusers
+# that conflict with pyannote-audio (torch>=2.8) and CogVideoX (diffusers>=0.30).
+# These overrides let the combined [ai] resolve pick compatible versions; the
+# floors in [ai] are aligned with them so pip and uv resolve similar versions.
 override-dependencies = [
     "torch>=2.8.0", "torchaudio>=2.8.0", "numpy>=2.0.0", "diffusers>=0.30.0",
     # ultralytics depends on opencv-python which conflicts with our

{videopython-0.46.0 → videopython-0.48.0}/src/videopython/ai/__init__.py

@@ -24,6 +24,16 @@ if TYPE_CHECKING:
     # Redundant aliases mark these as intentional re-exports (mypy/IDE see the
     # symbols; ruff doesn't flag them as unused). Runtime resolution is lazy via
     # __getattr__ below.
+    from .auto_edit import AutoEditError as AutoEditError
+    from .auto_edit import AutoEditor as AutoEditor
+    from .auto_edit import EditCatalog as EditCatalog
+    from .auto_edit import EditPlan as EditPlan
+    from .auto_edit import ImagePart as ImagePart
+    from .auto_edit import OllamaVisionLLM as OllamaVisionLLM
+    from .auto_edit import PlannerError as PlannerError
+    from .auto_edit import StructuredVisionLLM as StructuredVisionLLM
+    from .auto_edit import TextPart as TextPart
+    from .auto_edit import build_catalog as build_catalog
     from .effects import ObjectDetectionOverlay as ObjectDetectionOverlay
     from .generation import ImageToVideo as ImageToVideo
     from .generation import TextToImage as TextToImage
@@ -66,6 +76,17 @@ _exports: dict[str, str] = {
     "VideoAnalysis": ".video_analysis",
     "VideoAnalysisConfig": ".video_analysis",
     "VideoAnalyzer": ".video_analysis",
+    # Auto-editing (LLM-authored edits)
+    "AutoEditor": ".auto_edit",
+    "AutoEditError": ".auto_edit",
+    "OllamaVisionLLM": ".auto_edit",
+    "StructuredVisionLLM": ".auto_edit",
+    "PlannerError": ".auto_edit",
+    "TextPart": ".auto_edit",
+    "ImagePart": ".auto_edit",
+    "EditCatalog": ".auto_edit",
+    "EditPlan": ".auto_edit",
+    "build_catalog": ".auto_edit",
 }
 
 __all__ = list(_exports)

videopython-0.48.0/src/videopython/ai/auto_edit/__init__.py

@@ -0,0 +1,29 @@
+"""LLM-authored editing: build a scene catalog and plan a VideoEdit from it."""
+
+from __future__ import annotations
+
+from .backend import ImagePart, Part, PlannerError, StructuredVisionLLM, TextPart
+from .catalog import build_catalog
+from .editor import AutoEditError, AutoEditor
+from .local import OllamaVisionLLM
+from .models import CatalogBundle, CatalogScene, EditCatalog, EditPlan, PlanSegment
+from .resolve import UnknownSceneIdsError, resolve_plan
+
+__all__ = [
+    "AutoEditError",
+    "AutoEditor",
+    "CatalogBundle",
+    "CatalogScene",
+    "EditCatalog",
+    "EditPlan",
+    "ImagePart",
+    "OllamaVisionLLM",
+    "Part",
+    "PlanSegment",
+    "PlannerError",
+    "StructuredVisionLLM",
+    "TextPart",
+    "UnknownSceneIdsError",
+    "build_catalog",
+    "resolve_plan",
+]

videopython-0.48.0/src/videopython/ai/auto_edit/backend.py

@@ -0,0 +1,37 @@
+"""The SDK-free seam between the editor and a structured-vision model."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+import numpy as np
+
+
+@dataclass
+class TextPart:
+    """A text chunk in a planner prompt."""
+
+    text: str
+
+
+@dataclass
+class ImagePart:
+    """A keyframe in a planner prompt: an RGB (H, W, 3) uint8 array."""
+
+    image: np.ndarray
+    label: str | None = None
+
+
+Part = TextPart | ImagePart
+
+
+class PlannerError(RuntimeError):
+    """A backend produced unusable output; the editor retries (infra errors should propagate instead)."""
+
+
+@runtime_checkable
+class StructuredVisionLLM(Protocol):
+    """Returns schema-shaped JSON from interleaved text + images; raises PlannerError on bad output."""
+
+    def generate_json(self, *, system: str, parts: list[Part], schema: dict[str, Any]) -> dict[str, Any]: ...

videopython-0.48.0/src/videopython/ai/auto_edit/catalog.py

@@ -0,0 +1,90 @@
+"""Build the LLM-facing edit catalog from VideoAnalysis results."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from videopython.base.video import extract_frames_at_times
+
+from .models import CatalogBundle, CatalogScene, EditCatalog
+
+if TYPE_CHECKING:
+    from videopython.ai.video_analysis import SceneAnalysisSample, VideoAnalysis
+    from videopython.base.transcription import Transcription
+
+DEFAULT_TRANSCRIPT_CHARS = 280
+
+
+def build_catalog(
+    analyses: Sequence[VideoAnalysis],
+    *,
+    keyframes: bool = True,
+    max_transcript_chars: int = DEFAULT_TRANSCRIPT_CHARS,
+) -> CatalogBundle:
+    """Project VideoAnalysis results into a flat scene catalog with one midpoint keyframe per scene."""
+    scenes: list[CatalogScene] = []
+    frames: dict[str, np.ndarray] = {}
+    used_ids: set[str] = set()
+
+    for analysis in analyses:
+        source_path = analysis.source.path
+        samples = analysis.scenes.samples if analysis.scenes else []
+        transcription = analysis.audio.transcription if analysis.audio else None
+        stem = Path(source_path).stem if source_path else "clip"
+
+        for sample in samples:
+            scene_id = _unique_id(stem, sample.scene_index, used_ids)
+            caption, shot_type = _description(sample)
+            transcript = _transcript_excerpt(
+                transcription, sample.start_second, sample.end_second, max_transcript_chars
+            )
+            scenes.append(
+                CatalogScene(
+                    id=scene_id,
+                    source=Path(source_path) if source_path else Path(stem),
+                    start=sample.start_second,
+                    end=sample.end_second,
+                    duration=max(0.0, sample.end_second - sample.start_second),
+                    shot_type=shot_type,
+                    caption=caption,
+                    transcript=transcript,
+                    has_speech=bool(transcript),
+                    has_faces=bool(sample.faces),
+                )
+            )
+            if keyframes:
+                if source_path is None:
+                    raise ValueError(f"Scene {scene_id!r} has no source path to extract a keyframe from.")
+                midpoint = (sample.start_second + sample.end_second) / 2.0
+                frames[scene_id] = extract_frames_at_times(source_path, [midpoint])[0]
+
+    return CatalogBundle(catalog=EditCatalog(scenes=scenes), keyframes=frames)
+
+
+def _unique_id(stem: str, scene_index: int, used: set[str]) -> str:
+    base = f"{stem}#{scene_index}"
+    candidate, suffix = base, 2
+    while candidate in used:
+        candidate = f"{base}-{suffix}"
+        suffix += 1
+    used.add(candidate)
+    return candidate
+
+
+def _description(sample: SceneAnalysisSample) -> tuple[str, str | None]:
+    desc = sample.scene_description
+    return (desc.caption or "", desc.shot_type) if desc else ("", None)
+
+
+def _transcript_excerpt(transcription: Transcription | None, start: float, end: float, max_chars: int) -> str:
+    sliced = transcription.slice(start, end) if transcription else None
+    if sliced is None:
+        return ""
+    text = " ".join(" ".join(segment.text.split()) for segment in sliced.segments).strip()
+    if len(text) > max_chars:
+        text = text[: max_chars - 3].rstrip() + "..."
+    return text

videopython-0.48.0/src/videopython/ai/auto_edit/editor.py

@@ -0,0 +1,140 @@
+"""AutoEditor: turn source videos + a brief into a runnable VideoEdit."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal
+
+from pydantic import ValidationError
+
+from .backend import ImagePart, Part, PlannerError, StructuredVisionLLM, TextPart
+from .catalog import build_catalog
+from .models import CatalogBundle, CatalogScene, EditPlan
+from .resolve import UnknownSceneIdsError, resolve_plan
+
+if TYPE_CHECKING:
+    from videopython.ai.video_analysis import VideoAnalysis, VideoAnalyzer
+    from videopython.base.video import VideoMetadata
+    from videopython.editing import VideoEdit
+
+_SYSTEM_PROMPT = (
+    "You are a video editor. You are given a creative brief and a catalog of candidate scenes "
+    "from one or more source videos, each shown with its keyframe. Select and order scenes into "
+    "an edit that fulfils the brief. Reference scenes only by their catalog id via 'scene_id'; "
+    "never invent timestamps or sources."
+)
+
+_NormalizeTarget = tuple[int, int] | Literal["first", "largest", "match"]
+
+
+class AutoEditError(RuntimeError):
+    """The planner could not produce a valid edit within the retry budget."""
+
+
+class AutoEditor:
+    """Plan a VideoEdit from source videos using a structured-vision planner."""
+
+    def __init__(
+        self,
+        planner: StructuredVisionLLM,
+        *,
+        analyzer: VideoAnalyzer | None = None,
+        max_rounds: int = 3,
+        normalize_target: _NormalizeTarget = "largest",
+    ) -> None:
+        self.planner = planner
+        self._analyzer = analyzer
+        self.max_rounds = max_rounds
+        self.normalize_target = normalize_target
+
+    def edit(self, sources: Sequence[str | Path], brief: str, *, context: dict[str, Any] | None = None) -> VideoEdit:
+        """Analyze ``sources`` and plan an edit for ``brief`` (runs the analyzer)."""
+        analyses = [self._get_analyzer().analyze_path(source) for source in sources]
+        return self.edit_from_analyses(analyses, brief, context=context)
+
+    def edit_from_analyses(
+        self, analyses: Sequence[VideoAnalysis], brief: str, *, context: dict[str, Any] | None = None
+    ) -> VideoEdit:
+        """Plan an edit from precomputed VideoAnalysis results (no model download)."""
+        bundle = build_catalog(analyses)
+        metadata = _metadata_by_source(analyses)
+        run_context = _merge_context(analyses, context)
+        schema = EditPlan.json_schema(strict=True)
+        base_parts = _build_parts(brief, bundle)
+
+        feedback: str | None = None
+        for _ in range(self.max_rounds):
+            parts = base_parts if feedback is None else [*base_parts, TextPart(feedback)]
+            try:
+                raw = self.planner.generate_json(system=_SYSTEM_PROMPT, parts=parts, schema=schema)
+                edit = resolve_plan(EditPlan.model_validate(raw), bundle.catalog)
+            except (PlannerError, ValidationError, UnknownSceneIdsError) as exc:
+                feedback = _shape_feedback(exc)
+                continue
+            edit, _ = edit.repair(metadata, context=run_context, clamp_segment_end=True)
+            edit, _ = edit.normalize_dimensions(metadata, self.normalize_target, context=run_context)
+            errors = edit.check(metadata, context=run_context)
+            if not errors:
+                return edit
+            feedback = "The previous plan had these problems:\n" + "\n".join(e.to_prompt_line() for e in errors)
+
+        raise AutoEditError(f"No valid edit after {self.max_rounds} round(s). Last feedback:\n{feedback}")
+
+    def _get_analyzer(self) -> VideoAnalyzer:
+        if self._analyzer is None:
+            from videopython.ai.video_analysis import VideoAnalyzer
+
+            self._analyzer = VideoAnalyzer()
+        return self._analyzer
+
+
+def _build_parts(brief: str, bundle: CatalogBundle) -> list[Part]:
+    parts: list[Part] = [TextPart(f"Brief: {brief}\n\nCandidate scenes:")]
+    for scene in bundle.catalog.scenes:
+        parts.append(TextPart(_scene_line(scene)))
+        frame = bundle.keyframes.get(scene.id)
+        if frame is not None:
+            parts.append(ImagePart(image=frame, label=scene.id))
+    return parts
+
+
+def _scene_line(scene: CatalogScene) -> str:
+    bits = [f"[{scene.id}] {scene.duration:.1f}s"]
+    if scene.shot_type:
+        bits.append(scene.shot_type)
+    if scene.caption:
+        bits.append(scene.caption)
+    line = " | ".join(bits)
+    if scene.transcript:
+        line += f"\n  speech: {scene.transcript}"
+    return line
+
+
+def _metadata_by_source(analyses: Sequence[VideoAnalysis]) -> dict[str, VideoMetadata]:
+    from videopython.base.video import VideoMetadata
+
+    paths: set[str] = set()
+    for analysis in analyses:
+        if analysis.source.path is not None:
+            paths.add(analysis.source.path)
+    return {str(Path(p)): VideoMetadata.from_path(p) for p in paths}
+
+
+def _merge_context(analyses: Sequence[VideoAnalysis], context: dict[str, Any] | None) -> dict[str, Any] | None:
+    transcriptions: dict[str, Any] = {}
+    for analysis in analyses:
+        src = analysis.source
+        if src.path is not None and analysis.audio is not None and analysis.audio.transcription is not None:
+            transcriptions[str(Path(src.path))] = analysis.audio.transcription
+    if not transcriptions:
+        return context
+    return {"transcription": transcriptions, **(context or {})}
+
+
+def _shape_feedback(exc: PlannerError | ValidationError | UnknownSceneIdsError) -> str:
+    if isinstance(exc, UnknownSceneIdsError):
+        return f"Plan used scene ids not in the catalog: {sorted(set(exc.ids))}. Use only listed ids."
+    if isinstance(exc, PlannerError):
+        return f"Your previous response was not usable JSON ({exc}). Return one matching JSON object."
+    return f"The previous plan did not match the schema: {exc.errors()!r}"

videopython-0.48.0/src/videopython/ai/auto_edit/local.py

@@ -0,0 +1,67 @@
+"""A local, model-agnostic planner backed by an Ollama server."""
+
+from __future__ import annotations
+
+import base64
+import io
+import json
+from typing import Any
+
+import numpy as np
+from PIL import Image
+
+from videopython.ai._optional import require
+
+from .backend import ImagePart, Part, PlannerError, TextPart
+
+DEFAULT_OLLAMA_MODEL = "llama3.2-vision"
+
+
+class OllamaVisionLLM:
+    """A StructuredVisionLLM backed by a local Ollama server.
+
+    The model must be vision-capable (it is sent keyframes) AND support Ollama's
+    structured-output ``format`` (the EditPlan schema constrains the decode). Not
+    every model supports schema conditioning -- ``gemma3:27b`` is verified working;
+    some builds (e.g. certain MLX ones) fail it. ``ollama pull <model>`` first;
+    ``options`` are extra generation options merged over ``temperature=0``.
+    """
+
+    def __init__(
+        self,
+        model: str = DEFAULT_OLLAMA_MODEL,
+        *,
+        host: str | None = None,
+        options: dict[str, Any] | None = None,
+    ) -> None:
+        self.model = model
+        self.host = host
+        self.options: dict[str, Any] = {"temperature": 0.0, **(options or {})}
+        self._client: Any = None
+
+    def _get_client(self) -> Any:
+        if self._client is None:
+            ollama = require("ollama", "ai", feature="OllamaVisionLLM")
+            self._client = ollama.Client(host=self.host)
+        return self._client
+
+    def generate_json(self, *, system: str, parts: list[Part], schema: dict[str, Any]) -> dict[str, Any]:
+        text = "\n\n".join(part.text for part in parts if isinstance(part, TextPart))
+        images = [_encode_png_b64(part.image) for part in parts if isinstance(part, ImagePart)]
+        user: dict[str, Any] = {"role": "user", "content": text}
+        if images:
+            user["images"] = images
+        messages = [{"role": "system", "content": system}, user]
+        # Ollama's structured output: the schema constrains the decode to valid JSON.
+        response = self._get_client().chat(model=self.model, messages=messages, format=schema, options=self.options)
+        content = response.message.content
+        try:
+            return json.loads(content)
+        except (ValueError, TypeError) as exc:
+            raise PlannerError(f"Ollama returned non-JSON output: {content!r}") from exc
+
+
+def _encode_png_b64(frame: np.ndarray) -> str:
+    buffer = io.BytesIO()
+    Image.fromarray(frame).save(buffer, format="PNG")
+    return base64.b64encode(buffer.getvalue()).decode("ascii")