videopython 0.37.0__tar.gz → 0.38.0__tar.gz

{videopython-0.37.0 → videopython-0.38.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: videopython
-Version: 0.37.0
+Version: 0.38.0
 Summary: Minimal video generation and processing library.
 Project-URL: Homepage, https://videopython.com
 Project-URL: Repository, https://github.com/bartwojtowicz/videopython/
@@ -109,9 +109,11 @@ video.add_audio(audio).save("ai_video.mp4")
 
 ## LLM & AI Agent Integration
 
-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. Then `edit.validate()` dry-runs the plan via metadata before any frames are loaded, raising a typed `PlanValidationError` (with structured `.errors`) that can be fed back to the LLM and retried cheaply.
+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.
 
-See the [LLM Integration Guide](https://videopython.com/guides/llm-integration/) for end-to-end examples, validation error loops, and operation discovery patterns.
+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.
+
+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.
 
 ## Features
 

{videopython-0.37.0 → videopython-0.38.0}/README.md

@@ -60,9 +60,11 @@ video.add_audio(audio).save("ai_video.mp4")
 
 ## LLM & AI Agent Integration
 
-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. Then `edit.validate()` dry-runs the plan via metadata before any frames are loaded, raising a typed `PlanValidationError` (with structured `.errors`) that can be fed back to the LLM and retried cheaply.
+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.
 
-See the [LLM Integration Guide](https://videopython.com/guides/llm-integration/) for end-to-end examples, validation error loops, and operation discovery patterns.
+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.
+
+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.
 
 ## Features
 

{videopython-0.37.0 → videopython-0.38.0}/pyproject.toml

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

{videopython-0.37.0 → videopython-0.38.0}/src/videopython/base/__init__.py

@@ -15,6 +15,10 @@ from .exceptions import (
     AudioError,
     AudioLoadError,
     OutOfBoundsError,
+    PlanError,
+    PlanErrorCode,
+    PlanRepair,
+    PlanValidationError,
     TextRenderError,
     TransformError,
     VideoError,
@@ -41,6 +45,11 @@ __all__ = [
     "TransformError",
     "TextRenderError",
     "OutOfBoundsError",
+    # Structured plan validation / repair
+    "PlanError",
+    "PlanErrorCode",
+    "PlanValidationError",
+    "PlanRepair",
     # Text rendering primitives
     "ImageText",
     "TextAlign",

{videopython-0.37.0 → videopython-0.38.0}/src/videopython/base/exceptions.py

@@ -85,12 +85,26 @@ class PlanErrorCode(str, Enum):
     instead of substring-matching the human message text.
     """
 
+    # Segment range vs source / shape.
     SEGMENT_END_EXCEEDS_SOURCE = "segment_end_exceeds_source"
+    SEGMENT_NEGATIVE = "segment_negative"
+    SEGMENT_RANGE = "segment_range"
+    # Effect windows.
     EFFECT_WINDOW_EXCEEDS_DURATION = "effect_window_exceeds_duration"
+    WINDOW_NEGATIVE = "window_negative"
+    WINDOW_ORDER = "window_order"
+    # Operation-level, metadata-relative checks.
     CUT_EXCEEDS_DURATION = "cut_exceeds_duration"
+    OP_TIMESTAMP_OUT_OF_RANGE = "op_timestamp_out_of_range"
+    CROP_EXCEEDS_SOURCE = "crop_exceeds_source"
+    DEGENERATE_DURATION = "degenerate_duration"
+    SOURCE_UNREADABLE = "source_unreadable"
+    OP_PREDICTION_FAILED = "op_prediction_failed"
+    # Assembly / structural.
     UNKNOWN_OP = "unknown_op"
     CONCAT_MISMATCH = "concat_mismatch"
     SUBTITLE_UNFITTABLE = "subtitle_unfittable"
+    POST_OP_REQUIRES_CONTEXT = "post_op_requires_context"
 
 
 @dataclass
@@ -110,12 +124,37 @@ class PlanError:
     predicted_duration: float | None = None
 
 
+@dataclass
+class PlanRepair:
+    """A single change a repair/normalize pass made to a plan.
+
+    The structured changelog returned by :meth:`VideoEdit.repair` and
+    :meth:`VideoEdit.normalize_dimensions`. ``location`` is a path into the
+    plan (e.g. ``'segments[0].operations[1]'``); ``field`` is the changed
+    field (``'window.stop'``, ``'timestamp'``, ``'dimensions'``, ...). ``old``
+    and ``new`` carry the before/after values -- a ``float`` for numeric
+    clamps, a ``str`` for composite values like ``'768x432'``. ``code`` is the
+    :class:`PlanErrorCode` of the violation that was repaired, so a consumer
+    can surface "we trimmed your effect to fit" wording keyed on the class.
+    """
+
+    location: str
+    field: str
+    old: float | str | None
+    new: float | str | None
+    code: PlanErrorCode
+
+
 class PlanValidationError(ValueError):
     """Typed plan-validation failure carrying structured :class:`PlanError`s.
 
     Subclasses ``ValueError`` so ``str(e)`` stays byte-identical to the bare
     ``ValueError`` prose emitted before this type existed -- existing
     ``pytest.raises(match=...)`` and consumer substring fallbacks keep working.
+
+    ``str(e)`` is the first error's human message; ``.errors`` carries every
+    structured :class:`PlanError`. The non-raising :meth:`VideoEdit.check`
+    returns the same ``PlanError`` list directly.
     """
 
     def __init__(self, message: str, errors: list[PlanError]):

{videopython-0.37.0 → videopython-0.38.0}/src/videopython/editing/effects.py

@@ -29,6 +29,7 @@ from pydantic import Field, PrivateAttr, model_validator
 from tqdm import tqdm
 
 from videopython.base.description import BoundingBox
+from videopython.base.exceptions import PlanError, PlanErrorCode, PlanValidationError
 from videopython.base.fonts import load_font
 from videopython.editing._easing import ease, ease_out
 from videopython.editing.operation import Effect
@@ -860,7 +861,11 @@ class ImageOverlay(_AnchoredOverlay):
                 with Image.open(self.source) as im:
                     im.verify()
         except (OSError, ValueError) as exc:
-            raise ValueError(f"image_overlay source {str(self.source)!r} is not a readable image: {exc}") from exc
+            message = f"image_overlay source {str(self.source)!r} is not a readable image: {exc}"
+            raise PlanValidationError(
+                message,
+                [PlanError(code=PlanErrorCode.SOURCE_UNREADABLE, op=self.op, field="source")],
+            ) from exc
         return meta
 
     def _rasterize_svg(self, target_w: int) -> np.ndarray:

{videopython-0.37.0 → videopython-0.38.0}/src/videopython/editing/operation.py

@@ -30,12 +30,13 @@ Subclass contract::
 
 from __future__ import annotations
 
+import copy
 from dataclasses import dataclass
 from enum import Enum
-from typing import TYPE_CHECKING, Annotated, Any, ClassVar, Literal, Union, get_args, get_origin
+from typing import TYPE_CHECKING, Annotated, Any, ClassVar, Literal, NamedTuple, Union, get_args, get_origin
 
 import numpy as np
-from pydantic import BaseModel, ConfigDict, Discriminator, Field, TypeAdapter, model_validator
+from pydantic import BaseModel, ConfigDict, Discriminator, Field, TypeAdapter
 from tqdm import tqdm
 
 if TYPE_CHECKING:
@@ -44,6 +45,7 @@ if TYPE_CHECKING:
 __all__ = [
     "OpCategory",
     "TimeRange",
+    "BoundedTimeField",
     "FilterCtx",
     "Operation",
     "Effect",
@@ -63,18 +65,36 @@ class TimeRange(BaseModel):
 
     Either endpoint may be ``None``, meaning "from the beginning" / "to the
     end" respectively. Used by :class:`Effect.window` and elsewhere.
+
+    Parsing is deliberately permissive: ``start``/``stop`` are plain floats
+    with no ``ge=0`` or ordering constraint. The plan skeleton accepts the
+    *shape*; the numeric bounds (``>= 0``, ``stop >= start``, in-duration) are
+    owned by :meth:`VideoEdit.validate` / :meth:`VideoEdit.check`, which report
+    them as structured, collectable, repairable :class:`PlanError`s instead of
+    aborting at ``from_dict``. :meth:`Effect._resolved_window` still clamps at
+    run time, so a plan run without validation degrades rather than crashes.
     """
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
-    start: float | None = Field(None, ge=0, description="Start time in seconds. None means 0.")
-    stop: float | None = Field(None, ge=0, description="Stop time in seconds. None means end of video.")
+    start: float | None = Field(None, description="Start time in seconds. None means 0.")
+    stop: float | None = Field(None, description="Stop time in seconds. None means end of video.")
+
+
+class BoundedTimeField(NamedTuple):
+    """Declares a time-valued (seconds) op field that :meth:`VideoEdit.repair` clamps.
+
+    ``name`` is the field; the lower bound is always ``0``. ``exclusive_end``
+    distinguishes how the upper bound is enforced so repair clamps exactly what
+    validation rejects: ``False`` permits the clip duration (reject ``value >
+    total_seconds``, clamp to the duration); ``True`` is for a field that indexes
+    a frame and so must be *strictly* less than the duration (reject ``value >=
+    total_seconds``, clamp to the last addressable frame ``(frame_count - 1) /
+    fps``) -- e.g. ``freeze_frame.timestamp``.
+    """
 
-    @model_validator(mode="after")
-    def _validate_order(self) -> TimeRange:
-        if self.start is not None and self.stop is not None and self.stop < self.start:
-            raise ValueError(f"TimeRange.stop ({self.stop}) must be >= start ({self.start})")
-        return self
+    name: str
+    exclusive_end: bool
 
 
 @dataclass(frozen=True)
@@ -117,6 +137,60 @@ def _strip_llm_hidden(schema: dict[str, Any]) -> dict[str, Any]:
     return schema
 
 
+def _to_strict_schema(schema: dict[str, Any]) -> dict[str, Any]:
+    """Rewrite a generated JSON schema into a provider strict-mode grammar.
+
+    Strict structured-output modes (OpenAI/OpenRouter ``json_schema``) require:
+    every object closed (``additionalProperties: false``); every declared
+    property listed in ``required``; and unions expressed as ``anyOf`` without a
+    ``discriminator`` keyword. The ``default`` keyword (which strict mode
+    rejects, and which is moot once every field is required) is dropped. Numeric
+    constraints already emitted by Pydantic are kept verbatim.
+
+    Optionality is taken verbatim from what Pydantic emitted, *not* synthesized:
+    strict mode represents an optional field as a nullable required field, and
+    Pydantic already encodes exactly that -- an ``Optional`` field carries a
+    ``{"type": "null"}`` branch while a defaulted-but-non-``Optional`` field
+    (e.g. ``operations: list = []``, ``match_to_lowest_fps: bool = True``) does
+    not. So we force every property into ``required`` without adding null
+    branches: synthesizing null for a non-``Optional`` field would let a grammar
+    emit a null the Pydantic model then rejects -- reintroducing the very
+    re-prompt strict mode exists to remove. The union discriminator ``op`` is a
+    defaulted ``const`` and is likewise kept required and non-nullable for free.
+
+    Returns a new schema; the input is not mutated. Pydantic ``$ref``/``$defs``
+    indirection is left intact (providers resolve it); the per-``$defs`` object
+    bodies are rewritten in place of their definitions.
+    """
+
+    def walk(node: Any) -> Any:
+        if isinstance(node, list):
+            return [walk(item) for item in node]
+        if not isinstance(node, dict):
+            return node
+
+        out = {k: walk(v) for k, v in node.items()}
+
+        # A discriminated union: Pydantic emits `oneOf` + `discriminator`.
+        # Strict mode wants a plain `anyOf` of variants and no discriminator.
+        if "oneOf" in out:
+            out["anyOf"] = out.pop("oneOf")
+        # Drop keywords strict mode rejects (or that are moot once everything is
+        # required): the discriminator tag, `default`, custom `format`s like
+        # "path", and any `$schema`/`$id` envelope.
+        for key in ("discriminator", "default", "format", "$schema", "$id"):
+            out.pop(key, None)
+
+        # Close every object and require all of its properties. Nullability is
+        # left exactly as Pydantic emitted it (see the docstring) -- no synthesis.
+        if isinstance(out.get("properties"), dict):
+            out["additionalProperties"] = False
+            out["required"] = list(out["properties"].keys())
+        return out
+
+    return walk(copy.deepcopy(schema))
+
+
 class Operation(BaseModel):
     """Pydantic base for every editing primitive.
 
@@ -137,6 +211,15 @@ class Operation(BaseModel):
     streamable: ClassVar[bool] = False
     requires: ClassVar[tuple[str, ...]] = ()
     llm_exposed: ClassVar[bool] = True
+    time_fields: ClassVar[tuple[BoundedTimeField, ...]] = ()
+    """Time-valued (seconds) fields :meth:`VideoEdit.repair` may clamp into range.
+
+    Declaring a :class:`BoundedTimeField` here lets ``repair`` clamp an
+    out-of-range timestamp (e.g. ``freeze_frame.timestamp`` past the clip end)
+    without per-op special-casing -- the repair pass reads the declaration,
+    clamps to ``[0, bound]``, and records a :class:`PlanRepair`. Empty by
+    default; ops with no time-valued params declare nothing.
+    """
 
     _registry: ClassVar[dict[str, type[Operation]]] = {}
 
@@ -196,7 +279,7 @@ class Operation(BaseModel):
             raise KeyError(f"Unknown op_id {op_id!r}. Known ops: [{known}]") from exc
 
     @classmethod
-    def json_schema(cls, include_server_only: bool = False) -> dict[str, Any]:
+    def json_schema(cls, include_server_only: bool = False, *, strict: bool = False) -> dict[str, Any]:
         """Discriminated-union JSON schema over registered Operations.
 
         ``op`` is the discriminator tag. This is the LLM-facing schema for
@@ -204,13 +287,33 @@ class Operation(BaseModel):
         LLM-exposed ops (:meth:`llm_registry`); pass ``include_server_only=True``
         to build the union from the full :meth:`registry`. Fields marked
         ``llm_hidden`` (advanced overrides like raw font paths) are stripped.
+
+        With ``strict=True`` the schema is rewritten for use as a provider
+        structured-output **grammar** (OpenAI/OpenRouter ``json_schema`` strict
+        mode): every object is closed (``additionalProperties: false``), every
+        property is listed in ``required`` with its optionality kept exactly as
+        Pydantic emitted it (an ``Optional`` field keeps its nullable branch; a
+        defaulted non-``Optional`` field -- including the ``op`` discriminator --
+        stays required and non-nullable), and the discriminated union is
+        expressed as a plain ``anyOf`` of closed variants (``discriminator``,
+        ``default``, custom ``format``, and ``$schema`` -- all unsupported or moot
+        in strict mode -- are dropped). Numeric constraints
+        (``minimum``/``maximum``/``exclusiveMinimum``) are preserved, so an
+        entire class of bound violations becomes impossible at decode time.
+
+        Note: the strict result is a *root-level* ``anyOf`` union -- an embeddable
+        schema fragment, not a submittable strict root (providers require the root
+        to be a closed object). It is consumed inside
+        :meth:`VideoEdit.json_schema(strict=True) <VideoEdit.json_schema>`, which
+        *is* a submittable object root; use that to constrain a whole plan.
         """
         source = Operation._registry if include_server_only else cls.llm_registry()
         if not source:
             return {"type": "object"}
         ops = sorted(source.values(), key=lambda c: c.__name__)
         annotated = Annotated[Union[tuple(ops)], Discriminator("op")]  # type: ignore[valid-type]  # noqa: UP007
-        return _strip_llm_hidden(TypeAdapter(annotated).json_schema())
+        schema = _strip_llm_hidden(TypeAdapter(annotated).json_schema())
+        return _to_strict_schema(schema) if strict else schema
 
     @classmethod
     def llm_json_schema(cls) -> dict[str, Any]:

{videopython-0.37.0 → videopython-0.38.0}/src/videopython/editing/transforms.py

@@ -19,7 +19,7 @@ from tqdm import tqdm
 from videopython.base._dimensions import floor_to_even, round_to_even
 from videopython.base.exceptions import PlanError, PlanErrorCode, PlanValidationError
 from videopython.base.video import Video
-from videopython.editing.operation import FilterCtx, OpCategory, Operation
+from videopython.editing.operation import BoundedTimeField, FilterCtx, OpCategory, Operation
 
 if TYPE_CHECKING:
     from videopython.base.transcription import Transcription
@@ -281,7 +281,19 @@ class Crop(Operation):
     def predict_metadata(self, meta: VideoMetadata) -> VideoMetadata:
         _, _, cw, ch = self._resolve_box(meta.width, meta.height)
         if cw > meta.width or ch > meta.height:
-            raise ValueError(f"Crop {cw}x{ch} exceeds source {meta.width}x{meta.height}")
+            message = f"Crop {cw}x{ch} exceeds source {meta.width}x{meta.height}"
+            raise PlanValidationError(
+                message,
+                [
+                    PlanError(
+                        code=PlanErrorCode.CROP_EXCEEDS_SOURCE,
+                        op=self.op,
+                        field="width" if cw > meta.width else "height",
+                        value=float(cw if cw > meta.width else ch),
+                        limit=float(meta.width if cw > meta.width else meta.height),
+                    )
+                ],
+            )
         if self.mode == CropMode.CENTER:
             # Mirror apply()'s `mid - cw//2 : mid + cw//2` slice, which
             # produces 2 * (cw // 2) pixels — odd targets round down.
@@ -368,7 +380,18 @@ class SpeedChange(Operation):
     def predict_metadata(self, meta: VideoMetadata) -> VideoMetadata:
         new_count = self._new_frame_count(meta.frame_count)
         if new_count == 0:
-            raise ValueError(f"Speed {self.speed}x would result in 0 frames!")
+            message = f"Speed {self.speed}x would result in 0 frames!"
+            raise PlanValidationError(
+                message,
+                [
+                    PlanError(
+                        code=PlanErrorCode.DEGENERATE_DURATION,
+                        op=self.op,
+                        field="speed",
+                        value=self.speed,
+                    )
+                ],
+            )
         from videopython.base.video import VideoMetadata as _Meta
 
         return _Meta(
@@ -400,6 +423,9 @@ class FreezeFrame(Operation):
 
     op: Literal["freeze_frame"] = "freeze_frame"
     category: ClassVar[OpCategory] = OpCategory.TRANSFORM
+    # `timestamp` indexes a frame, so it must be strictly < the clip duration;
+    # repair clamps an out-of-range value to the last frame.
+    time_fields: ClassVar[tuple[BoundedTimeField, ...]] = (BoundedTimeField("timestamp", exclusive_end=True),)
 
     timestamp: float = Field(ge=0, description="Time in seconds at which to capture the frame.")
     duration: float = Field(2.0, gt=0, description="How long to hold the frozen frame, in seconds.")
@@ -453,7 +479,20 @@ class FreezeFrame(Operation):
 
     def predict_metadata(self, meta: VideoMetadata) -> VideoMetadata:
         if self.timestamp >= meta.total_seconds:
-            raise ValueError(f"timestamp ({self.timestamp}) must be less than video duration ({meta.total_seconds})")
+            message = f"timestamp ({self.timestamp}) must be less than video duration ({meta.total_seconds})"
+            raise PlanValidationError(
+                message,
+                [
+                    PlanError(
+                        code=PlanErrorCode.OP_TIMESTAMP_OUT_OF_RANGE,
+                        op=self.op,
+                        field="timestamp",
+                        value=self.timestamp,
+                        limit=meta.total_seconds,
+                        predicted_duration=meta.total_seconds,
+                    )
+                ],
+            )
         freeze_count = round(self.duration * meta.fps)
         if self.position in ("after", "before"):
             new_count = meta.frame_count + freeze_count