videopython 0.55.2__tar.gz → 0.55.3__tar.gz

{videopython-0.55.2 → videopython-0.55.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: videopython
-Version: 0.55.2
+Version: 0.55.3
 Summary: Minimal video generation and processing library.
 Project-URL: Homepage, https://videopython.com
 Project-URL: Repository, https://github.com/bartwojtowicz/videopython/

{videopython-0.55.2 → videopython-0.55.3}/pyproject.toml

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

{videopython-0.55.2 → videopython-0.55.3}/src/videopython/ai/_ollama.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import re
 from typing import Any
 
 import numpy as np
@@ -16,6 +17,45 @@ class OllamaError(AiError, RuntimeError):
     """Ollama returned unusable output (non-JSON or an unexpected shape)."""
 
 
+# Ollama's own default context window is 4096 tokens, and an oversized request
+# *fails* (``exceed_context_size_error``) instead of being truncated -- so a call
+# carrying images has to size the window before sending. A vision model spends
+# roughly this many tokens per image. Deliberately generous: underestimating
+# fails the request outright, overestimating only costs KV-cache memory.
+_TOKENS_PER_IMAGE = 1024
+# Headroom for the system prompt, the user text, and the generated answer.
+_TEXT_TOKEN_ALLOWANCE = 2048
+# Never ask for less than Ollama's own default.
+_MIN_NUM_CTX = 4096
+_CONTEXT_OVERFLOW_RE = re.compile(r"request \((\d+) tokens\) exceeds the available context size")
+
+
+def _round_num_ctx(token_count: int) -> int:
+    return max(_MIN_NUM_CTX, 1 << (token_count - 1).bit_length())
+
+
+def _num_ctx_for_images(image_count: int) -> int:
+    """Estimate the initial context window for ``image_count`` images.
+
+    Rounded up to a power of two so a run over scenes with differing frame counts
+    reuses a handful of window sizes instead of a new one per call -- ``num_ctx``
+    is a runner-level setting, so varying it every call risks reloading the model
+    between scenes.
+    """
+    needed = image_count * _TOKENS_PER_IMAGE + _TEXT_TOKEN_ALLOWANCE
+    return _round_num_ctx(needed)
+
+
+def _num_ctx_after_overflow(error: str, current: int) -> int | None:
+    """Return a larger context after Ollama reports a context overflow."""
+    match = _CONTEXT_OVERFLOW_RE.search(error)
+    if match:
+        return _round_num_ctx(int(match.group(1)) + _TEXT_TOKEN_ALLOWANCE)
+    if "exceed_context_size_error" in error:
+        return current * 2
+    return None
+
+
 class OllamaStructuredClient:
     """Generate schema-constrained JSON from text + optional images via Ollama.
 
@@ -30,6 +70,10 @@ class OllamaStructuredClient:
     budget thinking, stops on ``length``, and returns empty content. None of these
     callers want the chain-of-thought, so thinking is disabled on models that
     support it.
+
+    Image requests start with a context estimate based on the image count. If a
+    model uses more visual tokens, the request retries once with the token count
+    reported by Ollama. An explicit ``num_ctx`` in ``options`` always wins.
     """
 
     def __init__(self, model: str, *, host: str | None = None, options: dict[str, Any] | None = None) -> None:
@@ -69,12 +113,23 @@ class OllamaStructuredClient:
         if images:
             user["images"] = [encode_png_b64(image) for image in images]
         messages = [{"role": "system", "content": system}, user]
+        options = self.options
+        image_count = len(images) if images else 0
+        auto_num_ctx = image_count > 0 and "num_ctx" not in options
+        if auto_num_ctx:
+            options = {**options, "num_ctx": _num_ctx_for_images(image_count)}
         kwargs: dict[str, Any] = {}
         if self._supports_thinking():
             kwargs["think"] = False
-        response = self._get_client().chat(
-            model=self.model, messages=messages, format=schema, options=self.options, **kwargs
-        )
+        client = self._get_client()
+        try:
+            response = client.chat(model=self.model, messages=messages, format=schema, options=options, **kwargs)
+        except Exception as exc:
+            retry_num_ctx = _num_ctx_after_overflow(str(exc), options["num_ctx"]) if auto_num_ctx else None
+            if retry_num_ctx is None:
+                raise
+            options = {**options, "num_ctx": retry_num_ctx}
+            response = client.chat(model=self.model, messages=messages, format=schema, options=options, **kwargs)
         content = response.message.content
         try:
             data = json.loads(content)

{videopython-0.55.2 → videopython-0.55.3}/src/videopython/ai/effects.py

@@ -43,7 +43,11 @@ class ObjectDetectionOverlay(Effect):
     confidence_threshold: float = Field(0.5, ge=0, le=1, description="Minimum detection confidence to draw a box, 0-1.")
     class_filter: list[str] | None = Field(
         None,
-        description='Only draw these COCO class names, e.g. ["person", "car", "dog"]. Null draws all classes.',
+        description=(
+            'Only draw these COCO class names, e.g. ["person", "car", "motorcycle"]. '
+            "Null draws all classes. Standard COCO names and D-FINE's alternate spellings "
+            "(motorbike, aeroplane, sofa, pottedplant, diningtable, tvmonitor) are accepted."
+        ),
     )
     show_confidence: bool = Field(True, description="Append the detection confidence as a percentage to each label.")
     box_color: tuple[int, int, int] | None = Field(

{videopython-0.55.2 → videopython-0.55.3}/src/videopython/ai/understanding/audio.py

@@ -333,7 +333,16 @@ class AudioToText(ManagedPredictor):
         )
 
         all_words = self._assign_speakers_to_words(all_words, diarization_result)
-        return Transcription(words=all_words, language=transcription.language)
+
+        # Rebuilding from words regroups by speaker and drops the per-segment
+        # confidence the supplied transcription carried, exactly as it does on the
+        # combined path -- so re-attach it the same way. Without this, splitting
+        # transcription and diarization into two calls silently loses confidence
+        # that running them as one keeps.
+        source_segments = transcription.segments
+        rebuilt = Transcription(words=all_words, language=transcription.language)
+        _attach_confidence_by_overlap(rebuilt.segments, source_segments)
+        return rebuilt
 
     def _run_vad(self, audio_mono: Audio) -> list[tuple[float, float]]:
         """Return voiced spans in seconds using Silero VAD.

{videopython-0.55.2 → videopython-0.55.3}/src/videopython/ai/understanding/image.py

@@ -41,6 +41,11 @@ class SceneVLM(ManagedPredictor):
     The model must be vision-capable and support Ollama's structured-output
     ``format``; ``ollama pull <model>`` first. ``options`` are extra Ollama
     generation options merged over ``temperature=0``.
+
+    A scene's frames are sent as one multi-image request, so the context window
+    is sized to the frame count automatically -- Ollama's 4096-token default
+    fits only one or two frames and *fails* anything larger. Pass an explicit
+    ``num_ctx`` in ``options`` to override that sizing.
     """
 
     def __init__(

{videopython-0.55.2 → videopython-0.55.3}/src/videopython/ai/understanding/objects.py

@@ -10,8 +10,12 @@ two stay one mental model. Consumed by
 per-frame object analysis.
 
 D-FINE (Apache-2.0) replaced the AGPL-licensed Ultralytics YOLO weights. Its COCO
-labels use VOC-style spellings (``motorbike``, ``aeroplane``, ``sofa``, ``pottedplant``,
-``diningtable``, ``tvmonitor``) -- ``class_filter`` must use the model's exact names.
+labels use VOC-style spellings for six classes (``motorbike``, ``aeroplane``,
+``sofa``, ``pottedplant``, ``diningtable``, ``tvmonitor``) where the standard COCO
+names are ``motorcycle``, ``airplane``, ``couch``, ``potted plant``,
+``dining table`` and ``tv``. ``class_filter`` accepts either spelling: names are
+normalized through :data:`CLASS_ALIASES` before matching, and any name the model
+does not emit is logged once the class list is known.
 """
 
 from __future__ import annotations
@@ -19,6 +23,9 @@ from __future__ import annotations
 import logging
 from typing import TYPE_CHECKING, Any
 
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
 from videopython.ai._revisions import pinned
 from videopython.ai.understanding._detector import Backend, DetectorBase
 from videopython.base.description import BoundingBox, DetectedObject
@@ -28,7 +35,31 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
-__all__ = ["ObjectDetector", "MODEL_SIZES"]
+__all__ = ["ObjectDetector", "MODEL_SIZES", "CLASS_ALIASES", "normalize_class_names"]
+
+# D-FINE emits VOC-style spellings for six COCO classes. Callers -- and LLMs asked
+# to name a class -- reach for the standard COCO spelling, which would match
+# nothing and draw nothing, with no error to explain the silence. Accept both.
+CLASS_ALIASES: dict[str, str] = {
+    "motorcycle": "motorbike",
+    "airplane": "aeroplane",
+    "couch": "sofa",
+    "potted plant": "pottedplant",
+    "dining table": "diningtable",
+    "tv": "tvmonitor",
+}
+
+
+def normalize_class_names(names: "Iterable[str]") -> tuple[str, ...]:
+    """Map COCO-standard class names onto the VOC-style spellings D-FINE emits.
+
+    Case and surrounding whitespace are normalized first, so ``"Potted Plant"``
+    and ``"potted  plant"`` both reach ``pottedplant``. A name with no alias is
+    passed through unchanged (lowercased) -- this translates spellings, it does
+    not validate them; see :meth:`ObjectDetector.unknown_filter_classes`.
+    """
+    return tuple(CLASS_ALIASES.get(key, key) for key in (" ".join(n.lower().split()) for n in names))
+
 
 # D-FINE COCO checkpoints (Apache-2.0), in ascending size/quality. ``model_size``
 # on ``ObjectDetectionOverlay`` maps onto these; pinned in ``_revisions.py``.
@@ -46,7 +77,9 @@ class ObjectDetector(DetectorBase[DetectedObject]):
     The D-FINE weights (default ``ustc-community/dfine-nano-coco``) download from
     HuggingFace on first real use; class names come from the model config.
     Detection is gated by ``confidence_threshold`` and optionally restricted to
-    ``class_filter`` (COCO class names; YOLO-style spellings are normalized).
+    ``class_filter``, which accepts either D-FINE's VOC-style spellings or the
+    standard COCO ones (``motorcycle``, ``airplane``, ``couch``, ``potted plant``,
+    ``dining table``, ``tv``) -- see :func:`normalize_class_names`.
     """
 
     DEFAULT_CONFIDENCE_THRESHOLD = 0.5
@@ -68,14 +101,18 @@ class ObjectDetector(DetectorBase[DetectedObject]):
                 ``ustc-community/dfine-nano-coco``, ``...-small-coco``,
                 ``...-medium-coco``, ``...-large-coco``). Downloaded on first use.
             confidence_threshold: Minimum detection confidence in ``[0, 1]``.
-            class_filter: If non-empty, only these COCO class names are kept
-                (D-FINE's VOC-style spelling, e.g. ``motorbike``/``tvmonitor``).
+            class_filter: If non-empty, only these COCO class names are kept.
+                Either spelling works -- ``motorcycle`` and ``motorbike`` both
+                match -- and names are normalized via
+                :func:`normalize_class_names`. A name the model never emits is
+                logged as a warning once the model loads, since it would
+                otherwise just silently match nothing.
             backend: Detection device - ``"cpu"``, ``"gpu"``, or ``"auto"``.
         """
         super().__init__(backend=backend)
         self.model_name = model_name
         self.confidence_threshold = confidence_threshold
-        self.class_filter = tuple(class_filter)
+        self.class_filter = normalize_class_names(class_filter)
         self._model: Any = None
         self._processor: Any = None
         self._class_names: dict[int, str] = {}
@@ -93,6 +130,26 @@ class ObjectDetector(DetectorBase[DetectedObject]):
             model = model.to("cuda")
         self._model = model
         self._class_names = {int(k): v for k, v in model.config.id2label.items()}
+        self._warn_unknown_filter_classes()
+
+    def unknown_filter_classes(self) -> tuple[str, ...]:
+        """``class_filter`` names this model never emits (empty until it loads)."""
+        if not self._class_names:
+            return ()
+        known = set(self._class_names.values())
+        return tuple(name for name in self.class_filter if name not in known)
+
+    def _warn_unknown_filter_classes(self) -> None:
+        """Log filter names that cannot match, which would otherwise draw nothing."""
+        unknown = self.unknown_filter_classes()
+        if unknown:
+            logger.warning(
+                "class_filter names not emitted by %s: %s. Nothing will be detected for them; "
+                "the model's classes are %s.",
+                self.model_name,
+                ", ".join(unknown),
+                ", ".join(sorted(set(self._class_names.values()))),
+            )
 
     def _infer(self, images: list[np.ndarray]) -> list[list[DetectedObject]]:
         import torch