videopython 0.50.1__tar.gz → 0.52.0__tar.gz

{videopython-0.50.1 → videopython-0.52.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: videopython
-Version: 0.50.1
+Version: 0.52.0
 Summary: Minimal video generation and processing library.
 Project-URL: Homepage, https://videopython.com
 Project-URL: Repository, https://github.com/bartwojtowicz/videopython/
@@ -128,11 +128,13 @@ Putting an LLM in the loop works three ways:
 2. **`AutoEditor`** — a local Ollama vision model is the planner (see [Automatic editing](#automatic-editing-local-llm) above).
 3. **MCP server** — `videopython-mcp` exposes the pipeline as [Model Context Protocol](https://modelcontextprotocol.io) tools, so an agent like Claude drives editing with its own model. Install `[ai,mcp]`, run `videopython-mcp`, and point your MCP client at it. See the [MCP Server Guide](https://videopython.com/guides/mcp/).
 
-For mode 1: every operation is a Pydantic model whose fields ARE the JSON wire format. `VideoEdit.json_schema()` returns a JSON Schema with a discriminated union over every LLM-exposed `Operation` (server-only ops like `image_overlay` are excluded by default) — pass it straight to Anthropic tool use, OpenAI function calling, or any structured-output API. Pass `strict=True` for a provider strict-mode grammar that prevents simple bound violations at decode time.
+**Mode 1** in brief: every operation is a Pydantic model whose fields *are* the JSON wire format, so `VideoEdit.json_schema()` hands your model a ready-made tool schema — a discriminated union over every LLM-exposed op (pass `strict=True` for provider grammar modes). Plans parse permissively and own their numeric bounds at validation, so a refine loop converges fast:
 
-The plan parses permissively (shape only) and owns numeric bounds at validation, so a refine loop converges fast: `edit.check(meta)` collects **every** structured `PlanError` in one pass, `edit.repair(meta)` auto-clamps the mechanical violations (window/timestamp overruns, negatives) with a reported changelog, and `edit.normalize_dimensions(meta, target)` makes heterogeneous segments concat-compatible by construction. `edit.validate()` still raises a typed `PlanValidationError` (a `ValueError` with structured `.errors`) for the single-error path.
+- **`edit.check(meta)`** — collect *every* structured error in one pass, not just the first
+- **`edit.repair(meta)`** — auto-clamp mechanical violations (overruns, negatives) with a changelog
+- **`edit.normalize_dimensions(meta, target)`** — make heterogeneous segments concat-compatible
 
-See the [LLM Integration Guide](https://videopython.com/guides/llm-integration/) for end-to-end examples, the collect/repair/normalize refine loop, and operation discovery patterns.
+See the [LLM Integration Guide](https://videopython.com/guides/llm-integration/) for end-to-end examples (Anthropic / OpenAI tool use), the refine loop, and operation discovery.
 
 ## Features
 

{videopython-0.50.1 → videopython-0.52.0}/README.md

@@ -84,11 +84,13 @@ Putting an LLM in the loop works three ways:
 2. **`AutoEditor`** — a local Ollama vision model is the planner (see [Automatic editing](#automatic-editing-local-llm) above).
 3. **MCP server** — `videopython-mcp` exposes the pipeline as [Model Context Protocol](https://modelcontextprotocol.io) tools, so an agent like Claude drives editing with its own model. Install `[ai,mcp]`, run `videopython-mcp`, and point your MCP client at it. See the [MCP Server Guide](https://videopython.com/guides/mcp/).
 
-For mode 1: every operation is a Pydantic model whose fields ARE the JSON wire format. `VideoEdit.json_schema()` returns a JSON Schema with a discriminated union over every LLM-exposed `Operation` (server-only ops like `image_overlay` are excluded by default) — pass it straight to Anthropic tool use, OpenAI function calling, or any structured-output API. Pass `strict=True` for a provider strict-mode grammar that prevents simple bound violations at decode time.
+**Mode 1** in brief: every operation is a Pydantic model whose fields *are* the JSON wire format, so `VideoEdit.json_schema()` hands your model a ready-made tool schema — a discriminated union over every LLM-exposed op (pass `strict=True` for provider grammar modes). Plans parse permissively and own their numeric bounds at validation, so a refine loop converges fast:
 
-The plan parses permissively (shape only) and owns numeric bounds at validation, so a refine loop converges fast: `edit.check(meta)` collects **every** structured `PlanError` in one pass, `edit.repair(meta)` auto-clamps the mechanical violations (window/timestamp overruns, negatives) with a reported changelog, and `edit.normalize_dimensions(meta, target)` makes heterogeneous segments concat-compatible by construction. `edit.validate()` still raises a typed `PlanValidationError` (a `ValueError` with structured `.errors`) for the single-error path.
+- **`edit.check(meta)`** — collect *every* structured error in one pass, not just the first
+- **`edit.repair(meta)`** — auto-clamp mechanical violations (overruns, negatives) with a changelog
+- **`edit.normalize_dimensions(meta, target)`** — make heterogeneous segments concat-compatible
 
-See the [LLM Integration Guide](https://videopython.com/guides/llm-integration/) for end-to-end examples, the collect/repair/normalize refine loop, and operation discovery patterns.
+See the [LLM Integration Guide](https://videopython.com/guides/llm-integration/) for end-to-end examples (Anthropic / OpenAI tool use), the refine loop, and operation discovery.
 
 ## Features
 

{videopython-0.50.1 → videopython-0.52.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "videopython"
-version = "0.50.1"
+version = "0.52.0"
 description = "Minimal video generation and processing library."
 authors = [
     { name = "Bartosz Wójtowicz", email = "bartoszwojtowicz@outlook.com" },

{videopython-0.50.1 → videopython-0.52.0}/src/videopython/ai/__init__.py

@@ -2,12 +2,13 @@
 
 Every public symbol is re-exported lazily via PEP 562 ``__getattr__`` so that
 ``import videopython.ai`` (or ``from videopython.ai import X``) loads ONLY the
-leaf module backing the requested symbol — not every sibling. This is what
-makes the granular extras (``asr``, ``vision``, ``tts``, ``generation``,
-``dub``, ...) usable: with only ``[asr]`` installed, ``from videopython.ai
-import AudioToText`` works, while touching ``TextToSpeech`` raises a clear
-``[tts]``-pointing ``ImportError`` at attribute access instead of failing the
-whole package import.
+leaf module backing the requested symbol — not every sibling. All AI capabilities
+ship in the single ``[ai]`` extra; the laziness keeps ``import videopython`` (and
+importing one leaf class) light by deferring the heavy ML imports (torch /
+transformers / diffusers / ultralytics) until a symbol is actually used. When
+``[ai]`` is not installed, touching a symbol raises a clear
+``pip install 'videopython[ai]'``-pointing ``ImportError`` at attribute access
+instead of failing the whole package import.
 
 The ``TYPE_CHECKING`` block below keeps the eager imports visible to mypy and
 IDEs (static autocompletion / re-export checking) without executing them at
@@ -28,13 +29,12 @@ if TYPE_CHECKING:
     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 .errors import AiError as AiError
     from .generation import ImageToVideo as ImageToVideo
     from .generation import TextToImage as TextToImage
     from .generation import TextToMusic as TextToMusic
@@ -43,7 +43,8 @@ if TYPE_CHECKING:
     from .transforms import FaceTrackingCrop as FaceTrackingCrop
     from .understanding import AudioClassifier as AudioClassifier
     from .understanding import AudioToText as AudioToText
-    from .understanding import FaceTracker as FaceTracker
+    from .understanding import FaceShotTracker as FaceShotTracker
+    from .understanding import FaceSmoothingTracker as FaceSmoothingTracker
     from .understanding import ObjectDetector as ObjectDetector
     from .understanding import SceneVLM as SceneVLM
     from .understanding import SemanticSceneDetector as SemanticSceneDetector
@@ -64,7 +65,8 @@ _exports: dict[str, str] = {
     # Understanding
     "AudioToText": ".understanding",
     "AudioClassifier": ".understanding",
-    "FaceTracker": ".understanding",
+    "FaceShotTracker": ".understanding",
+    "FaceSmoothingTracker": ".understanding",
     "ObjectDetector": ".understanding",
     "SceneVLM": ".understanding",
     "SemanticSceneDetector": ".understanding",
@@ -76,14 +78,14 @@ _exports: dict[str, str] = {
     "VideoAnalysis": ".video_analysis",
     "VideoAnalysisConfig": ".video_analysis",
     "VideoAnalyzer": ".video_analysis",
+    # Errors
+    "AiError": ".errors",
     # 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",

{videopython-0.50.1 → videopython-0.52.0}/src/videopython/ai/_ollama.py

@@ -2,19 +2,17 @@
 
 from __future__ import annotations
 
-import base64
-import io
 import json
 from typing import Any
 
-import cv2
 import numpy as np
-from PIL import Image
 
 from videopython.ai._optional import require
+from videopython.ai.errors import AiError
+from videopython.ai.keyframe import encode_png_b64
 
 
-class OllamaError(RuntimeError):
+class OllamaError(AiError, RuntimeError):
     """Ollama returned unusable output (non-JSON or an unexpected shape)."""
 
 
@@ -35,7 +33,7 @@ class OllamaStructuredClient:
 
     def _get_client(self) -> Any:
         if self._client is None:
-            ollama = require("ollama", "ai", feature="Ollama")
+            ollama = require("ollama", feature="Ollama")
             self._client = ollama.Client(host=self.host)
         return self._client
 
@@ -50,7 +48,7 @@ class OllamaStructuredClient:
         """Return the parsed JSON object Ollama generates under ``schema``."""
         user: dict[str, Any] = {"role": "user", "content": text}
         if images:
-            user["images"] = [_encode_png_b64(image) for image in images]
+            user["images"] = [encode_png_b64(image) for image in images]
         messages = [{"role": "system", "content": system}, user]
         response = self._get_client().chat(model=self.model, messages=messages, format=schema, options=self.options)
         content = response.message.content
@@ -64,23 +62,3 @@ class OllamaStructuredClient:
 
     def unload(self) -> None:
         self._client = None
-
-
-# Used only on the MCP keyframe path (videopython.mcp). SceneVLM captioning and the local
-# planner deliberately encode full-resolution frames via _encode_png_b64.
-KEYFRAME_MAX_DIM = 768  # bound a keyframe's longest side before PNG-encoding for the MCP payload
-
-
-def _downscale(frame: np.ndarray, max_dim: int = KEYFRAME_MAX_DIM) -> np.ndarray:
-    """Shrink an RGB frame so its longest side is at most ``max_dim`` (aspect preserved; never upscales)."""
-    h, w = frame.shape[:2]
-    scale = max_dim / max(h, w)
-    if scale >= 1.0:
-        return frame
-    return cv2.resize(frame, (max(1, round(w * scale)), max(1, round(h * scale))), interpolation=cv2.INTER_AREA)
-
-
-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")

{videopython-0.50.1 → videopython-0.52.0}/src/videopython/ai/_optional.py

@@ -6,12 +6,11 @@ method that needs it (there are no top-level ``import torch``/``transformers``/
 importable on a slim install: importing ``ai.understanding.objects`` only needs
 core deps until a detector is actually constructed.
 
-The granular extras (``asr``, ``vision``, ``tts``, ...) partition those heavy
-deps. When a user installs only one extra and reaches a code path needing a dep
-from another, the bare ``import`` would raise a stock ``ModuleNotFoundError``
-with no hint about which extra restores it. :func:`require` wraps the import and
-turns that into an actionable ``ImportError`` pointing at the right
-``pip install 'videopython[<extra>]'``.
+All those heavy deps ship in the single ``[ai]`` extra. When it isn't installed
+and a code path reaches one of them, the bare ``import`` would raise a stock
+``ModuleNotFoundError`` with no hint about how to fix it. :func:`require` wraps
+the import and turns that into an actionable ``ImportError`` pointing at
+``pip install 'videopython[ai]'``.
 """
 
 from __future__ import annotations
@@ -21,15 +20,13 @@ from types import ModuleType
 from typing import Callable
 
 
-def require(module: str, extra: str, *, feature: str | None = None) -> ModuleType:
-    """Import ``module`` or raise a clear, extra-pointing ``ImportError``.
+def require(module: str, *, feature: str | None = None) -> ModuleType:
+    """Import ``module`` or raise a clear, ``[ai]``-pointing ``ImportError``.
 
     Args:
         module: Dotted module name to import (e.g. ``"chatterbox.mtl_tts"``,
             ``"torch"``). The fully-imported module object is returned so the
             call site can bind the symbols it needs.
-        extra: The videopython extra that ships ``module`` (e.g. ``"tts"``,
-            ``"asr"``). Surfaced verbatim in the install hint.
         feature: Optional human-readable feature name for the message head. When
             omitted the top-level package of ``module`` is used.
 
@@ -38,14 +35,14 @@ def require(module: str, extra: str, *, feature: str | None = None) -> ModuleTyp
 
     Raises:
         ImportError: If ``module`` cannot be imported. The message always
-            contains the extra name and a ``pip install 'videopython[<extra>]'``
-            hint so the caller knows exactly how to fix it.
+            contains a ``pip install 'videopython[ai]'`` hint so the caller
+            knows exactly how to fix it.
     """
     try:
         return importlib.import_module(module)
     except ImportError as exc:
         label = feature or module.split(".")[0]
-        raise ImportError(f"{label} requires the '{extra}' extra: pip install 'videopython[{extra}]'") from exc
+        raise ImportError(f"{label} requires the 'ai' extra: pip install 'videopython[ai]'") from exc
 
 
 def lazy_exports(package: str, exports: dict[str, str]) -> tuple[Callable[[str], object], Callable[[], list[str]]]:
@@ -53,8 +50,9 @@ def lazy_exports(package: str, exports: dict[str, str]) -> tuple[Callable[[str],
 
     Re-exports a set of public symbols lazily: the submodule backing a symbol is
     imported only on first attribute access, so importing the package does not
-    pull in any sibling leaf module (this is what keeps the granular ``ai``
-    extras independently installable).
+    pull in any sibling leaf module. This keeps ``import videopython`` (and
+    importing a single leaf class) light by deferring the heavy ML imports
+    (torch / transformers / diffusers / ultralytics) until a symbol is used.
 
     Args:
         package: The ``__name__`` of the package defining the re-exports. Used

videopython-0.52.0/src/videopython/ai/_predictor.py

@@ -0,0 +1,70 @@
+"""Context-manager base with a default VRAM-releasing ``unload()``.
+
+Every predictor under ``videopython.ai`` holds a lazily-loaded model (and
+sometimes a processor / pipeline / VAD field) on the selected device, and needs
+to drop those references and free the allocator cache when done. That teardown
+is mechanical and identical across predictors: set the model field(s) to
+``None`` and call :func:`videopython.ai._device.release_device_memory`.
+
+:class:`ManagedPredictor` provides that as a default ``unload()`` driven by two
+class attributes -- ``_model_attrs`` (the fields holding model state) and
+``_device_attr`` (the field holding the device) -- and turns any predictor into
+a context manager::
+
+    with SceneVLM(...) as vlm:
+        ...  # use vlm
+    # vlm.unload() has fired here, releasing VRAM
+
+Subclasses with non-default model fields just declare ``_model_attrs``; those
+whose teardown isn't "null the fields + release" (e.g. delegating to a client's
+own ``unload()``) override ``unload()`` instead.
+
+The base imports no torch / transformers / ultralytics (``release_device_memory``
+defers its torch import), so it stays safe to mix into any predictor regardless
+of how it is constructed.
+"""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import TYPE_CHECKING, Literal
+
+from videopython.ai._device import release_device_memory
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+
+class ManagedPredictor:
+    """Adds a default ``unload()`` plus ``with``-statement support.
+
+    ``unload()`` clears each attribute named in ``_model_attrs`` to ``None`` and
+    releases the cache for the device named by ``_device_attr``. It is idempotent
+    (safe before the model is loaded and on repeated calls). ``__exit__`` always
+    returns ``False`` so exceptions inside the ``with`` block propagate --
+    ``unload()`` runs on both the success and failure paths.
+    """
+
+    # Attributes holding model state, cleared to None on unload. Override per
+    # predictor (e.g. ("_model", "_processor")).
+    _model_attrs: tuple[str, ...] = ("_model",)
+    # Attribute holding the resolved device passed to release_device_memory.
+    _device_attr: str = "device"
+
+    def unload(self) -> None:
+        """Drop the model reference(s) and release device memory. Idempotent."""
+        for attr in self._model_attrs:
+            setattr(self, attr, None)
+        release_device_memory(getattr(self, self._device_attr, None))
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> Literal[False]:
+        self.unload()
+        return False

{videopython-0.50.1 → videopython-0.52.0}/src/videopython/ai/_revisions.py

@@ -65,7 +65,7 @@ MODEL_REVISIONS: dict[str, str] = {
     # Speaker diarization (ai/understanding/audio.py: PYANNOTE_DIARIZATION_MODEL).
     # Gated repo (auto-approved); from_pretrained needs an accepted HF token.
     "pyannote/speaker-diarization-community-1": "3533c8cf8e369892e6b79ff1bf80f7b0286a54ee",
-    # Audio event classifier (ai/understanding/audio.py: AudioClassifier)
+    # Audio event classifier (ai/understanding/classification.py: AudioClassifier)
     "MIT/ast-finetuned-audioset-10-10-0.4593": "f826b80d28226b62986cc218e5cec390b1096902",
     # Face detection checkpoint (ai/understanding/faces.py: hf_hub_download)
     "arnabdhar/YOLOv8-Face-Detection": "52fa54977207fa4f021de949b515fb19dcab4488",

{videopython-0.50.1 → videopython-0.52.0}/src/videopython/ai/auto_edit/__init__.py

@@ -1,8 +1,16 @@
-"""LLM-authored editing: build a scene catalog and plan a VideoEdit from it."""
+"""LLM-authored editing: build a scene catalog and plan a VideoEdit from it.
+
+Uses eager imports (unlike the leaf packages): it is a thin orchestration
+package whose submodules load together, and it MUST eagerly import
+``videopython.ai.ops`` so the AI editing ops are registered before any
+``EditPlan.json_schema()`` call. Heavy ML deps it pulls in stay lazy.
+"""
 
 from __future__ import annotations
 
-from .backend import ImagePart, Part, PlannerError, StructuredVisionLLM, TextPart
+import videopython.ai.ops  # noqa: F401  -- registers the AI ops (face_crop, object_detection_overlay)
+
+from .backend import PlannerError, StructuredVisionLLM
 from .catalog import build_catalog
 from .editor import AutoEditError, AutoEditor
 from .local import OllamaVisionLLM
@@ -16,13 +24,10 @@ __all__ = [
     "CatalogScene",
     "EditCatalog",
     "EditPlan",
-    "ImagePart",
     "OllamaVisionLLM",
-    "Part",
     "PlanSegment",
     "PlannerError",
     "StructuredVisionLLM",
-    "TextPart",
     "UnknownSceneIdsError",
     "build_catalog",
     "resolve_plan",

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

@@ -0,0 +1,30 @@
+"""The SDK-free seam between the editor and a structured-vision model."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+from videopython.ai.errors import AiError
+
+if TYPE_CHECKING:
+    import numpy as np
+
+
+class PlannerError(AiError, RuntimeError):
+    """A backend produced unusable output; the editor retries (infra errors should propagate instead)."""
+
+
+@runtime_checkable
+class StructuredVisionLLM(Protocol):
+    """Returns schema-shaped JSON from a system prompt + text + optional keyframes.
+
+    The signature mirrors
+    :meth:`videopython.ai._ollama.OllamaStructuredClient.generate_json`, so any
+    structured-generation client satisfies it structurally. Implementations
+    raise :class:`PlannerError` on unusable output (the editor retries those);
+    infra errors should propagate so they are not silently retried.
+    """
+
+    def generate_json(
+        self, *, system: str, text: str, images: list[np.ndarray] | None, schema: dict[str, Any]
+    ) -> dict[str, Any]: ...

{videopython-0.50.1 → videopython-0.52.0}/src/videopython/ai/auto_edit/editor.py

@@ -8,12 +8,16 @@ from typing import TYPE_CHECKING, Any, Literal
 
 from pydantic import ValidationError
 
-from .backend import ImagePart, Part, PlannerError, StructuredVisionLLM, TextPart
+from videopython.ai.errors import AiError
+
+from .backend import PlannerError, StructuredVisionLLM
 from .catalog import build_catalog
 from .models import CatalogBundle, CatalogScene, EditPlan
 from .resolve import UnknownSceneIdsError, resolve_plan
 
 if TYPE_CHECKING:
+    import numpy as np
+
     from videopython.ai.video_analysis import VideoAnalysis, VideoAnalyzer
     from videopython.base.video import VideoMetadata
     from videopython.editing import VideoEdit
@@ -28,7 +32,7 @@ _SYSTEM_PROMPT = (
 _NormalizeTarget = tuple[int, int] | Literal["first", "largest", "match"]
 
 
-class AutoEditError(RuntimeError):
+class AutoEditError(AiError, RuntimeError):
     """The planner could not produce a valid edit within the retry budget."""
 
 
@@ -61,13 +65,13 @@ class AutoEditor:
         metadata = _metadata_by_source(analyses)
         run_context = _merge_context(analyses, context)
         schema = EditPlan.json_schema(strict=True)
-        base_parts = _build_parts(brief, bundle)
+        base_text, images = _build_prompt(brief, bundle)
 
         feedback: str | None = None
         for _ in range(self.max_rounds):
-            parts = base_parts if feedback is None else [*base_parts, TextPart(feedback)]
+            text = base_text if feedback is None else f"{base_text}\n\n{feedback}"
             try:
-                raw = self.planner.generate_json(system=_SYSTEM_PROMPT, parts=parts, schema=schema)
+                raw = self.planner.generate_json(system=_SYSTEM_PROMPT, text=text, images=images or None, schema=schema)
                 edit = resolve_plan(EditPlan.model_validate(raw), bundle.catalog)
             except (PlannerError, ValidationError, UnknownSceneIdsError) as exc:
                 feedback = _shape_feedback(exc)
@@ -89,14 +93,16 @@ class AutoEditor:
         return self._analyzer
 
 
-def _build_parts(brief: str, bundle: CatalogBundle) -> list[Part]:
-    parts: list[Part] = [TextPart(f"Brief: {brief}\n\nCandidate scenes:")]
+def _build_prompt(brief: str, bundle: CatalogBundle) -> tuple[str, list[np.ndarray]]:
+    """The planner prompt: scene-line text plus the keyframes, in catalog order."""
+    lines = [f"Brief: {brief}\n\nCandidate scenes:"]
+    images: list[np.ndarray] = []
     for scene in bundle.catalog.scenes:
-        parts.append(TextPart(_scene_line(scene)))
+        lines.append(_scene_line(scene))
         frame = bundle.keyframes.get(scene.id)
         if frame is not None:
-            parts.append(ImagePart(image=frame, label=scene.id))
-    return parts
+            images.append(frame)
+    return "\n\n".join(lines), images
 
 
 def _scene_line(scene: CatalogScene) -> str:

{videopython-0.50.1 → videopython-0.52.0}/src/videopython/ai/auto_edit/local.py

@@ -2,11 +2,14 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from videopython.ai._ollama import OllamaError, OllamaStructuredClient
 
-from .backend import ImagePart, Part, PlannerError, TextPart
+from .backend import PlannerError
+
+if TYPE_CHECKING:
+    import numpy as np
 
 DEFAULT_OLLAMA_MODEL = "gemma3:27b"
 
@@ -19,6 +22,10 @@ class OllamaVisionLLM:
     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``.
+
+    Thin wrapper over the shared :class:`OllamaStructuredClient`: its only job is
+    to translate :class:`OllamaError` into the :class:`PlannerError` the editor
+    retries on.
     """
 
     def __init__(
@@ -30,9 +37,9 @@ class OllamaVisionLLM:
     ) -> None:
         self._client = OllamaStructuredClient(model=model, host=host, options=options)
 
-    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 = [part.image for part in parts if isinstance(part, ImagePart)]
+    def generate_json(
+        self, *, system: str, text: str, images: list[np.ndarray] | None, schema: dict[str, Any]
+    ) -> dict[str, Any]:
         try:
             return self._client.generate_json(system=system, text=text, schema=schema, images=images or None)
         except OllamaError as exc:

{videopython-0.50.1 → videopython-0.52.0}/src/videopython/ai/auto_edit/resolve.py

@@ -2,12 +2,13 @@
 
 from __future__ import annotations
 
+from videopython.ai.errors import AiError
 from videopython.editing import SegmentConfig, VideoEdit
 
 from .models import EditCatalog, EditPlan
 
 
-class UnknownSceneIdsError(ValueError):
+class UnknownSceneIdsError(AiError, ValueError):
     """An EditPlan referenced scene ids absent from the catalog."""
 
     def __init__(self, ids: list[str]) -> None:

{videopython-0.50.1 → videopython-0.52.0}/src/videopython/ai/dubbing/__init__.py

@@ -29,7 +29,6 @@ if TYPE_CHECKING:
     from videopython.ai.dubbing.quality import TranscriptQuality as TranscriptQuality
     from videopython.ai.dubbing.quality import assess_transcript as assess_transcript
     from videopython.ai.dubbing.timing import TimingSynchronizer as TimingSynchronizer
-    from videopython.ai.generation.translation import UnsupportedLanguageError as UnsupportedLanguageError
 
 # Public symbol -> fully-qualified module that defines it.
 _exports: dict[str, str] = {
@@ -45,7 +44,6 @@ _exports: dict[str, str] = {
     "GarbageTranscriptError": "videopython.ai.dubbing.quality",
     "TranscriptQuality": "videopython.ai.dubbing.quality",
     "assess_transcript": "videopython.ai.dubbing.quality",
-    "UnsupportedLanguageError": "videopython.ai.generation.translation",
 }
 
 __all__ = list(_exports)

{videopython-0.50.1/src/videopython/ai/generation → videopython-0.52.0/src/videopython/ai/dubbing}/_tts_backend.py

@@ -1,18 +1,17 @@
 """Pluggable speech-synthesis backend protocol for the dubbing pipeline.
 
-Mirrors :class:`videopython.ai.generation.translation.TranslationBackend`: a
-dependency-free, ``runtime_checkable`` Protocol that the dubbing pipeline
+A dependency-free, ``runtime_checkable`` Protocol that the dubbing pipeline
 depends on instead of binding directly to the local
 :class:`videopython.ai.generation.audio.TextToSpeech` implementation.
 
-This is the seam that lets dubbing run WITHOUT chatterbox in the process. The
-local ``TextToSpeech`` (which pulls ``chatterbox-tts`` via the ``[tts]`` extra)
+This is the seam that lets a consumer run speech synthesis out-of-process. The
+local ``TextToSpeech`` (which pulls ``chatterbox-tts`` from the ``[ai]`` extra)
 satisfies this protocol structurally — no changes needed there. A consumer that
-can't or won't install chatterbox (e.g. a service running synthesis in a
+can't or won't load chatterbox in-process (e.g. a service running synthesis in a
 separate process or on a remote/Modal function) supplies its own object
-implementing :meth:`SpeechBackend.generate_audio` and injects it; the pipeline never
-imports chatterbox in that case. videopython ships ONLY this protocol plus the
-local backend — no reference remote/HTTP backend.
+implementing :meth:`SpeechBackend.generate_audio` and injects it; the pipeline
+never imports chatterbox in that case. videopython ships ONLY this protocol plus
+the local backend — no reference remote/HTTP backend.
 """
 
 from __future__ import annotations

videopython-0.50.1/src/videopython/ai/dubbing/loudness.py → videopython-0.52.0/src/videopython/ai/dubbing/audio_ops.py

@@ -1,4 +1,11 @@
-"""LUFS / peak loudness matching for dubbed audio."""
+"""Audio DSP helpers for the dubbing pipeline.
+
+Merges the former ``expressiveness`` and ``loudness`` leaf modules: RMS,
+source-prosody -> Chatterbox expressiveness mapping, and LUFS/peak loudness
+matching. These are the small numpy/DSP helpers the pipeline composes; keeping
+them in one file (rather than two ~50-line files) makes the audio-side toolkit
+legible.
+"""
 
 from __future__ import annotations
 
@@ -6,10 +13,48 @@ from typing import TYPE_CHECKING
 
 import numpy as np
 
+from videopython.ai.dubbing.models import Expressiveness
+
 if TYPE_CHECKING:
     from videopython.audio import Audio
 
 
+def rms(data: np.ndarray) -> float:
+    """RMS over samples; ``0.0`` for empty input. float64 reduction so a
+    long slice can't overflow the squared accumulator."""
+    if data.size == 0:
+        return 0.0
+    return float(np.sqrt(np.mean(np.square(data, dtype=np.float64))))
+
+
+# --- Source-prosody-driven expressiveness (Chatterbox TTS knobs) -----------
+# Source-segment RMS / whole-vocals RMS below CALM lands in the calm bucket;
+# above DRAMATIC in the dramatic bucket; in between gets Chatterbox's defaults.
+# Knob values picked by-ear on cam1_1min.mp4 -- see RELEASE_NOTES 0.29.0.
+CALM_RATIO_THRESHOLD = 0.7
+DRAMATIC_RATIO_THRESHOLD = 1.3
+_CALM = Expressiveness(exaggeration=0.3, cfg_weight=0.7)
+_DRAMATIC = Expressiveness(exaggeration=0.85, cfg_weight=0.35)
+
+
+def expressiveness_for(source_slice: Audio, baseline_rms: float) -> Expressiveness:
+    """Map a source vocals slice to a Chatterbox expressiveness profile
+    by RMS ratio. Falls back to the no-knobs default for empty or silent
+    inputs."""
+    if baseline_rms <= 0.0:
+        return Expressiveness()
+    segment_rms = rms(source_slice.data)
+    if segment_rms <= 0.0:
+        return Expressiveness()
+    ratio = segment_rms / baseline_rms
+    if ratio < CALM_RATIO_THRESHOLD:
+        return _CALM
+    if ratio > DRAMATIC_RATIO_THRESHOLD:
+        return _DRAMATIC
+    return Expressiveness()
+
+
+# --- LUFS / peak loudness matching -----------------------------------------
 # BS.1770 integrated-loudness measurement requires at least 400 ms of audio
 # (one gating block). Below this, fall back to peak match -- pyloudnorm
 # returns -inf or warns, neither of which gives a usable gain.
@@ -64,7 +109,7 @@ def loudness_match(target: Audio, reference: Audio) -> Audio:
 
     from videopython.ai._optional import require
 
-    pyloudnorm = require("pyloudnorm", "ai", feature="loudness matching")
+    pyloudnorm = require("pyloudnorm", feature="loudness matching")
 
     target_lufs = pyloudnorm.Meter(target.metadata.sample_rate).integrated_loudness(target.data)
     reference_lufs = pyloudnorm.Meter(reference.metadata.sample_rate).integrated_loudness(reference.data)