@larkup/tool-video-intelligence 0.2.0

package/runtime/app/utils/timing.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def normalized_important_ranges(
+    brief: dict[str, Any], duration_secs: float
+) -> list[tuple[float, float]]:
+    """Clamps a brief's requested ranges to the source duration, sorted and merged."""
+    ranges: list[tuple[float, float]] = []
+    for candidate in brief.get("importantRanges") or []:
+        try:
+            start = max(0.0, float(candidate.get("startSecs")))
+            end = min(duration_secs, float(candidate.get("endSecs")))
+        except (AttributeError, TypeError, ValueError):
+            continue
+        if end > start:
+            ranges.append((start, end))
+    ranges.sort()
+    merged: list[tuple[float, float]] = []
+    for start, end in ranges:
+        if merged and start <= merged[-1][1]:
+            merged[-1] = (merged[-1][0], max(merged[-1][1], end))
+        else:
+            merged.append((start, end))
+    return merged
+
+
+def visual_sampling_interval(mode: str, duration_seconds: float) -> float:
+    """Seconds between sampled frames for a given indexing mode and source length."""
+    base_intervals = {"fast": 5.0, "balanced": 2.0, "thorough": 0.75}
+    max_samples = {"fast": 360, "balanced": 720, "thorough": 1_800}
+    return max(base_intervals[mode], duration_seconds / max_samples[mode])
+
+
+def rebase_result_timestamps(result: dict[str, Any], offset_secs: float) -> None:
+    """Translates clip-relative evidence (a bounded/rebased inspection) to the source clock."""
+    offset_ms = round(offset_secs * 1_000)
+
+    def shift(item: dict[str, Any], *keys: str) -> None:
+        for key in keys:
+            if isinstance(item.get(key), (int, float)):
+                item[key] = round(float(item[key])) + offset_ms
+
+    for segment in result.get("transcript", []):
+        if not isinstance(segment, dict):
+            continue
+        shift(segment, "startMs", "endMs")
+        for word in segment.get("words", []):
+            if isinstance(word, dict):
+                shift(word, "startMs", "endMs")
+    for observation in result.get("visualObservations", []):
+        if isinstance(observation, dict):
+            shift(observation, "timeMs")
+    for track in result.get("tracks", []):
+        if isinstance(track, dict):
+            shift(track, "startMs", "endMs")
+    for overlay in result.get("recurringOverlayText", []):
+        if not isinstance(overlay, dict):
+            continue
+        shift(overlay, "firstSeenMs", "lastSeenMs")
+        if isinstance(overlay.get("timestampsMs"), list):
+            overlay["timestampsMs"] = [
+                round(float(timestamp)) + offset_ms
+                for timestamp in overlay["timestampsMs"]
+                if isinstance(timestamp, (int, float))
+            ]
+    for observation in result.get("semanticObservations", []):
+        if isinstance(observation, dict):
+            shift(observation, "startMs", "endMs")
+    for embedding in result.get("videoEmbeddings", []):
+        if isinstance(embedding, dict):
+            shift(embedding, "startMs", "endMs")
+    for entity in result.get("entities", []):
+        if not isinstance(entity, dict) or not isinstance(entity.get("timestampsMs"), list):
+            continue
+        entity["timestampsMs"] = [
+            round(float(timestamp)) + offset_ms
+            for timestamp in entity["timestampsMs"]
+            if isinstance(timestamp, (int, float))
+        ]
+
+    # Knowledge synthesis runs while a bounded source is still on its local
+    # clip clock. Its citations are persisted alongside raw evidence, so they
+    # must be translated by the same offset before a refinement is searchable.
+    summary = result.get("knowledgeSummary")
+    if not isinstance(summary, dict):
+        return
+    for key in ("stateHistory", "keyEvents"):
+        for item in summary.get(key, []):
+            if isinstance(item, dict):
+                shift(item, "startMs", "endMs")
+    for key in ("participants", "context"):
+        for item in summary.get(key, []):
+            if not isinstance(item, dict):
+                continue
+            for evidence in item.get("evidence", []):
+                if isinstance(evidence, dict):
+                    shift(evidence, "startMs", "endMs")

package/runtime/app/worker.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import argparse
+
+from app.config import Settings
+from app.db.store import Store
+from app.services.jobs import JobService
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Run one queued video intelligence job")
+    parser.add_argument("job_id")
+    args = parser.parse_args()
+    settings = Settings.from_env()
+    store = Store(settings.data_dir / "video-intelligence.sqlite3")
+    JobService(settings, store).run(args.job_id)
+
+
+if __name__ == "__main__":
+    main()

package/runtime/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=80"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "larkup-video-intelligence-runtime"
+version = "0.1.0"
+description = "Portable FastAPI runtime for Larkup Video Intelligence"
+readme = "README.md"
+requires-python = ">=3.12,<3.14"
+license = "Apache-2.0"
+authors = [{ name = "Larkup" }]
+dependencies = [
+  "boto3==1.40.1",
+  "cryptography>=46.0.7",
+  "fastapi>=0.115.6",
+  "numpy==1.26.4",
+  "opencv-python-headless==4.11.0.86",
+  "pydantic==2.11.7",
+  "python-multipart==0.0.32",
+  "requests==2.33.0",
+  "scenedetect==0.6.5",
+  "starlette>=0.49.1",
+  "uvicorn[standard]==0.35.0",
+]
+
+[project.optional-dependencies]
+cpu = [
+  "faster-whisper==1.1.1",
+  "onnxruntime==1.22.0",
+  "pyclipper==1.4.0",
+  "rapidocr-onnxruntime==1.4.4",
+  "Shapely==2.1.2",
+  "six==1.17.0",
+]
+gpu = [
+  "faster-whisper==1.1.1",
+  "onnxruntime-gpu==1.22.0",
+  "paddleocr==3.0.3",
+  "rapidocr-onnxruntime==1.4.4",
+  "runpod>=1.7.14",
+]
+test = ["httpx==0.28.1"]
+
+[project.scripts]
+larkup-video-runtime = "app.__main__:main"
+larkup-video-runtime-worker = "app.worker:main"
+
+[project.urls]
+Repository = "https://github.com/Larkup-AI/larkup/tree/main/packages/marketplace-tools/video-intelligence"
+
+[tool.setuptools]
+packages = ["app", "app.api", "app.db", "app.services", "app.utils"]
+
+[tool.uv]
+package = true

package/runtime/requirements-cpu.txt

@@ -0,0 +1,15 @@
+fastapi==0.116.1
+faster-whisper==1.1.1
+numpy==1.26.4
+onnxruntime==1.22.0
+opencv-python-headless==4.11.0.86
+Pillow==12.3.0
+pyclipper==1.4.0
+pydantic==2.11.7
+python-multipart==0.0.32
+PyYAML==6.0.3
+requests==2.33.0
+scenedetect==0.6.5
+Shapely==2.1.2
+six==1.17.0
+uvicorn[standard]==0.35.0

package/runtime/requirements-smoke.txt

@@ -0,0 +1,7 @@
+fastapi==0.116.1
+numpy==1.26.4
+opencv-python-headless==4.11.0.86
+pydantic==2.11.7
+python-multipart==0.0.32
+requests==2.33.0
+uvicorn[standard]==0.35.0

package/runtime/requirements.txt

@@ -0,0 +1,14 @@
+boto3==1.40.1
+fastapi==0.116.1
+faster-whisper==1.1.1
+numpy==1.26.4
+onnxruntime-gpu==1.22.0
+opencv-python-headless==4.11.0.86
+paddleocr==3.0.3
+pydantic==2.11.7
+rapidocr-onnxruntime==1.4.4
+python-multipart==0.0.32
+requests==2.33.0
+runpod==1.7.10
+scenedetect==0.6.5
+uvicorn[standard]==0.35.0