watch-skill 1.2.0__py3-none-any.whl

watch_skill/__init__.py

@@ -0,0 +1,19 @@
+"""Watch Skill — give any agent a video input.
+
+Core engine: acquisition, perception, transcription, indexing, vision, and
+the autonomous watch-critique-iterate loop. Surfaces (MCP, CLI, REST) are
+thin wrappers around this package and live outside it.
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+# Read the version from installed metadata instead of restating it here.
+# v1.0.0 shipped reporting "0.6.0" because the release bumped every manifest
+# and missed this line; deriving it removes the chance of a second drift.
+try:
+    __version__ = _pkg_version("watch-skill")
+except PackageNotFoundError:  # running from a source tree with no install
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

watch_skill/acquire/__init__.py

@@ -0,0 +1,12 @@
+"""Source acquisition: resolve ANY input to a local video file.
+
+Self-healing chain: yt-dlp -> auto-update + retry -> self-hosted cobalt
+(opt-in) -> direct ffmpeg pull. Content-addressed cache with LRU eviction.
+Privacy invariants: no cookies/logins, video files never leave the machine.
+"""
+
+from watch_skill.acquire.resolver import acquire, fetch_captions_only
+from watch_skill.acquire.sources import SourceKind, classify_source
+from watch_skill.acquire.types import AcquireResult
+
+__all__ = ["AcquireResult", "SourceKind", "acquire", "classify_source", "fetch_captions_only"]

watch_skill/acquire/cache.py

@@ -0,0 +1,150 @@
+"""Content-addressed download cache: never re-download an unchanged video.
+
+Layout: ``<data_dir>/cache/<key>/`` where ``key`` is a hash of the normalized
+source URL. Each entry holds the media file(s), optional subtitles, and an
+``entry.json`` with source metadata. Access time is tracked by touching
+``entry.json`` so LRU eviction can order entries without OS atime support.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from watch_skill.config import get_settings
+
+ENTRY_FILE = "entry.json"
+
+
+@dataclass
+class CacheEntry:
+    """One cached download."""
+
+    key: str
+    dir: Path
+    video_path: Path | None
+    subtitle_path: Path | None
+    info: dict[str, Any]
+
+
+def cache_key(source: str) -> str:
+    """Stable key for a source URL (case-preserved, whitespace-trimmed)."""
+    return hashlib.sha256(source.strip().encode("utf-8")).hexdigest()[:24]
+
+
+def entry_dir(source: str, create: bool = False) -> Path:
+    """Directory where this source's download lives (created on demand)."""
+    directory = get_settings().cache_dir / cache_key(source)
+    if create:
+        directory.mkdir(parents=True, exist_ok=True)
+    return directory
+
+
+def _load_entry(directory: Path) -> CacheEntry | None:
+    meta_path = directory / ENTRY_FILE
+    if not meta_path.is_file():
+        return None
+    try:
+        meta = json.loads(meta_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    video = directory / meta["video"] if meta.get("video") else None
+    subs = directory / meta["subtitle"] if meta.get("subtitle") else None
+    if video is not None and not video.is_file():
+        return None
+    return CacheEntry(
+        key=directory.name,
+        dir=directory,
+        video_path=video,
+        subtitle_path=subs if subs and subs.is_file() else None,
+        info=meta.get("info", {}),
+    )
+
+
+def lookup(source: str) -> CacheEntry | None:
+    """Return the cached entry for ``source`` and mark it recently used."""
+    directory = entry_dir(source)
+    entry = _load_entry(directory)
+    if entry is not None:
+        try:
+            os.utime(directory / ENTRY_FILE)
+        except OSError:
+            pass
+    return entry
+
+
+def commit(
+    source: str,
+    video_path: Path | None,
+    subtitle_path: Path | None = None,
+    info: dict[str, Any] | None = None,
+) -> CacheEntry:
+    """Record a completed download that already lives inside the entry dir.
+
+    Acquirers download *into* :func:`entry_dir` so committing is just writing
+    the manifest — no copy of a multi-GB file.
+    """
+    directory = entry_dir(source, create=True)
+    meta = {
+        "source": source,
+        "video": video_path.name if video_path else None,
+        "subtitle": subtitle_path.name if subtitle_path else None,
+        "info": info or {},
+        "committed_at": time.time(),
+    }
+    (directory / ENTRY_FILE).write_text(
+        json.dumps(meta, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+    evict_lru()
+    return CacheEntry(
+        key=directory.name,
+        dir=directory,
+        video_path=video_path,
+        subtitle_path=subtitle_path,
+        info=info or {},
+    )
+
+
+def _dir_size(directory: Path) -> int:
+    return sum(p.stat().st_size for p in directory.rglob("*") if p.is_file())
+
+
+def evict_lru(max_bytes: int | None = None) -> int:
+    """Delete least-recently-used entries until the cache fits the cap.
+
+    Returns the number of evicted entries. Recency = mtime of ``entry.json``
+    (touched on every :func:`lookup` hit).
+    """
+    cap = max_bytes if max_bytes is not None else get_settings().cache_max_bytes
+    cache_dir = get_settings().cache_dir
+    if not cache_dir.is_dir():
+        return 0
+
+    entries: list[tuple[float, Path, int]] = []
+    total = 0
+    for directory in cache_dir.iterdir():
+        meta = directory / ENTRY_FILE
+        if not directory.is_dir() or not meta.is_file():
+            continue
+        size = _dir_size(directory)
+        total += size
+        entries.append((meta.stat().st_mtime, directory, size))
+
+    evicted = 0
+    entries.sort()  # oldest first
+    while total > cap and entries:
+        _, directory, size = entries.pop(0)
+        shutil.rmtree(directory, ignore_errors=True)
+        total -= size
+        evicted += 1
+    return evicted
+
+
+def clear() -> None:
+    """Remove the entire cache (used by `watch-skill cache clear`)."""
+    shutil.rmtree(get_settings().cache_dir, ignore_errors=True)

watch_skill/acquire/cobalt.py

@@ -0,0 +1,96 @@
+"""cobalt fallback acquirer (self-hosted instances only).
+
+Used only after yt-dlp (and its self-update retry) failed, and only when the
+user configured ``WATCHSKILL_COBALT_API_URL``. The public api.cobalt.tools
+now requires JWT auth (verified 2026-07-05: anonymous POST returns
+``error.api.auth.jwt.missing``), so without a configured self-hosted
+instance the chain skips straight to the direct-URL fallback instead of
+burning a doomed network round-trip.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from watch_skill.errors import AcquisitionError
+
+
+def _api_url() -> str | None:
+    return os.environ.get("WATCHSKILL_COBALT_API_URL") or None
+
+
+def is_configured() -> bool:
+    """cobalt participates in the fallback chain only when an instance is set."""
+    return _api_url() is not None
+
+
+def _request_media_url(url: str, timeout: float = 60.0) -> str:
+    """Ask the cobalt instance to resolve ``url`` to a downloadable media URL."""
+    api_url = _api_url()
+    if api_url is None:
+        raise AcquisitionError(
+            "no cobalt instance configured",
+            code="acquire.cobalt_not_configured",
+            fix="set WATCHSKILL_COBALT_API_URL to a self-hosted cobalt instance "
+            "(the public API requires auth); the chain continues without it",
+            details={"url": url},
+        )
+    try:
+        response = httpx.post(
+            api_url,
+            json={"url": url, "videoQuality": "720", "filenameStyle": "basic"},
+            headers={"Accept": "application/json", "Content-Type": "application/json"},
+            timeout=timeout,
+            follow_redirects=True,
+        )
+        payload: dict[str, Any] = response.json()
+    except (httpx.HTTPError, ValueError) as exc:
+        raise AcquisitionError(
+            f"cobalt API unreachable or returned non-JSON: {exc}",
+            code="acquire.cobalt_unreachable",
+            fix="set WATCHSKILL_COBALT_API_URL to a working cobalt instance, or skip",
+            details={"url": url, "api": _api_url()},
+        ) from exc
+
+    status = payload.get("status")
+    if status in ("tunnel", "redirect", "stream") and payload.get("url"):
+        return str(payload["url"])
+    raise AcquisitionError(
+        f"cobalt could not resolve this URL (status={status!r})",
+        code="acquire.cobalt_failed",
+        fix="the resolver will continue down the fallback chain",
+        details={"url": url, "response": {k: payload.get(k) for k in ("status", "error")}},
+    )
+
+
+def download(url: str, dest: Path, timeout: float = 1800.0) -> Path:
+    """Resolve via cobalt and stream the media to ``dest``."""
+    media_url = _request_media_url(url)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    tmp = dest.with_suffix(dest.suffix + ".part")
+    try:
+        with httpx.stream("GET", media_url, follow_redirects=True, timeout=timeout) as resp:
+            resp.raise_for_status()
+            with tmp.open("wb") as fh:
+                for chunk in resp.iter_bytes(1024 * 256):
+                    fh.write(chunk)
+        tmp.replace(dest)
+    except httpx.HTTPError as exc:
+        tmp.unlink(missing_ok=True)
+        raise AcquisitionError(
+            f"cobalt media download failed: {exc}",
+            code="acquire.cobalt_download_failed",
+            fix="the resolver will continue down the fallback chain",
+            details={"url": url},
+        ) from exc
+    if not dest.is_file() or dest.stat().st_size == 0:
+        raise AcquisitionError(
+            "cobalt returned an empty file",
+            code="acquire.cobalt_empty",
+            fix="the resolver continues down the fallback chain on its own",
+            details={"url": url},
+        )
+    return dest

watch_skill/acquire/direct.py

@@ -0,0 +1,50 @@
+"""Direct ffmpeg pull: media URLs and HLS/DASH manifests, incl. bounded live capture."""
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+from watch_skill.errors import AcquisitionError
+from watch_skill.health.binaries import require_binary
+
+
+def ffmpeg_pull(
+    url: str,
+    dest: Path,
+    duration_seconds: float | None = None,
+    timeout: float = 3600.0,
+) -> Path:
+    """Fetch a direct media URL or HLS/DASH manifest into a local mp4.
+
+    ``duration_seconds`` bounds the capture — required for live streams,
+    which would otherwise download forever. Stream-copies when possible and
+    falls back to transcoding only if the container rejects the codecs.
+    """
+    ffmpeg = require_binary("ffmpeg")
+    dest.parent.mkdir(parents=True, exist_ok=True)
+
+    base: list[str] = [str(ffmpeg), "-hide_banner", "-loglevel", "error", "-y", "-i", url]
+    if duration_seconds is not None:
+        base += ["-t", f"{duration_seconds:.3f}"]
+
+    copy_cmd = base + ["-c", "copy", "-movflags", "+faststart", str(dest)]
+    result = subprocess.run(
+        copy_cmd, capture_output=True, text=True, timeout=timeout,
+        encoding="utf-8", errors="replace",
+    )
+    if result.returncode != 0 or not dest.is_file() or dest.stat().st_size == 0:
+        print("[watch-skill] stream copy failed — transcoding…", file=sys.stderr)
+        transcode_cmd = base + ["-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", str(dest)]
+        result = subprocess.run(
+            transcode_cmd, capture_output=True, text=True, timeout=timeout,
+            encoding="utf-8", errors="replace",
+        )
+    if result.returncode != 0 or not dest.is_file() or dest.stat().st_size == 0:
+        raise AcquisitionError(
+            "ffmpeg could not fetch the media URL",
+            code="acquire.ffmpeg_pull_failed",
+            fix="check the URL is reachable and actually points at media/a manifest",
+            details={"url": url, "stderr_tail": result.stderr[-2000:]},
+        )
+    return dest

watch_skill/acquire/resolver.py

@@ -0,0 +1,176 @@
+"""Resolve ANY input to a local video file, with cache and fallback chain.
+
+Chain for network sources (each hop logs why the previous one failed):
+yt-dlp -> (auto-update + retry, inside ytdlp.download) -> self-hosted cobalt
+(only when WATCHSKILL_COBALT_API_URL is set — the public instance requires
+auth) -> direct ffmpeg pull. Direct/manifest URLs try yt-dlp first too (it handles
+both), with ffmpeg as the reliable second step. Screen/window capture is
+provided by ``watch_skill.loop.capture`` (Milestone 3) — the resolver returns
+a structured error pointing there until then.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from watch_skill.acquire import cache, cobalt, direct, ytdlp
+from watch_skill.acquire.sources import SourceKind, classify_source, is_url_kind
+from watch_skill.acquire.types import AcquireResult
+from watch_skill.errors import AcquisitionError
+from watch_skill.health.log import record_incident
+
+VIDEO_EXTS = ytdlp.VIDEO_EXTS
+
+
+def _resolve_local(source: str) -> AcquireResult:
+    path = Path(source).expanduser().resolve()
+    if path.is_dir():
+        # "file not found" is wrong and unhelpful here: the path exists, and
+        # a folder of recordings is what `batch` is for.
+        raise AcquisitionError(
+            f"{path} is a directory, not a video file",
+            code="acquire.is_a_directory",
+            fix=f'watch every video in it with: watch-skill batch "{path}"',
+            details={"source": source},
+        )
+    if not path.is_file():
+        raise AcquisitionError(
+            f"file not found: {path}",
+            code="acquire.file_not_found",
+            fix="check the path; remember to quote paths containing spaces",
+            details={"source": source},
+        )
+    if path.suffix.lower() not in VIDEO_EXTS:
+        print(
+            f"[watch-skill] warning: {path.suffix} is not a known video extension — proceeding",
+            file=sys.stderr,
+        )
+    return AcquireResult(
+        source=source,
+        kind=SourceKind.LOCAL_FILE,
+        video_path=path,
+        info={"title": path.name, "url": str(path)},
+        acquirer="local",
+    )
+
+
+def _from_cache(source: str, kind: SourceKind) -> AcquireResult | None:
+    entry = cache.lookup(source)
+    if entry is None or entry.video_path is None:
+        return None
+    print(f"[watch-skill] cache hit: {entry.dir}", file=sys.stderr)
+    return AcquireResult(
+        source=source,
+        kind=kind,
+        video_path=entry.video_path,
+        subtitle_path=entry.subtitle_path,
+        info=entry.info,
+        from_cache=True,
+        acquirer="cache",
+    )
+
+
+def _try_chain(
+    source: str, kind: SourceKind, out_dir: Path,
+    audio_only: bool, duration_cap: float | None,
+) -> AcquireResult:
+    """Walk the fallback chain, recording each hop's failure."""
+    failures: list[str] = []
+
+    try:
+        dl = ytdlp.download(source, out_dir, audio_only=audio_only)
+        return AcquireResult(
+            source=source, kind=kind, video_path=Path(dl["video_path"]),
+            subtitle_path=dl["subtitle_path"], info=dl["info"], acquirer="yt-dlp",
+        )
+    except AcquisitionError as exc:
+        failures.append(f"yt-dlp: {exc.message}")
+        record_incident("acquire_fallback", "yt-dlp failed, trying fallbacks", url=source)
+        print(f"[watch-skill] yt-dlp failed ({exc.code}) — trying fallbacks…", file=sys.stderr)
+
+    if kind == SourceKind.PAGE_URL and cobalt.is_configured():
+        try:
+            video = cobalt.download(source, out_dir / "media.mp4")
+            return AcquireResult(
+                source=source, kind=kind, video_path=video, acquirer="cobalt",
+                info={"url": source},
+            )
+        except AcquisitionError as exc:
+            failures.append(f"cobalt: {exc.message}")
+            record_incident("acquire_fallback", "cobalt failed, trying ffmpeg", url=source)
+            print(f"[watch-skill] cobalt failed ({exc.code}) — trying direct ffmpeg…", file=sys.stderr)
+
+    try:
+        video = direct.ffmpeg_pull(source, out_dir / "media.mp4", duration_seconds=duration_cap)
+        return AcquireResult(
+            source=source, kind=kind, video_path=video, acquirer="ffmpeg",
+            info={"url": source},
+        )
+    except AcquisitionError as exc:
+        failures.append(f"ffmpeg: {exc.message}")
+
+    raise AcquisitionError(
+        "every acquirer in the fallback chain failed",
+        code="acquire.chain_exhausted",
+        fix="check the URL; if it needs login or is region-locked, Watch Skill "
+        "will not bypass that (privacy invariant: no cookies, no logins)",
+        details={"source": source, "failures": failures},
+    )
+
+
+def acquire(
+    source: str,
+    audio_only: bool = False,
+    duration_cap: float | None = None,
+    use_cache: bool = True,
+) -> AcquireResult:
+    """Resolve ``source`` (URL / manifest / local path / capture spec) to local files.
+
+    Network downloads land in the content-addressed cache and are reused on
+    the next call. ``duration_cap`` bounds live-stream capture.
+    """
+    kind = classify_source(source)
+
+    if kind in (SourceKind.SCREEN, SourceKind.WINDOW):
+        raise AcquisitionError(
+            "screen/window capture is provided by the loop module",
+            code="acquire.capture_required",
+            fix="use `watch-skill capture` / the capture() API (Milestone 3)",
+            details={"source": source, "kind": kind.value},
+        )
+
+    if kind == SourceKind.LOCAL_FILE:
+        return _resolve_local(source)
+
+    assert is_url_kind(kind)
+    if use_cache:
+        cached = _from_cache(source, kind)
+        if cached is not None:
+            return cached
+
+    out_dir = cache.entry_dir(source, create=True)
+    result = _try_chain(source, kind, out_dir, audio_only, duration_cap)
+    # Audio-only fetches are not committed: a later full fetch must not be
+    # shadowed by a cache entry that has no video frames in it.
+    if use_cache and not audio_only:
+        cache.commit(source, result.video_path, result.subtitle_path, result.info)
+    return result
+
+
+def fetch_captions_only(source: str) -> AcquireResult:
+    """Probe captions + metadata for a URL without downloading media."""
+    kind = classify_source(source)
+    if not is_url_kind(kind):
+        raise AcquisitionError(
+            "captions probe only applies to URLs",
+            code="acquire.not_a_url",
+            fix="local files have no platform captions; transcription falls "
+            "back to local whisper automatically",
+            details={"source": source},
+        )
+    out_dir = cache.entry_dir(source, create=True)
+    probe = ytdlp.fetch_captions(source, out_dir)
+    return AcquireResult(
+        source=source, kind=kind, video_path=None,
+        subtitle_path=probe["subtitle_path"], info=probe["info"], acquirer="yt-dlp",
+    )

watch_skill/acquire/sources.py

@@ -0,0 +1,54 @@
+"""Classify any input string into a source kind the resolver can act on."""
+from __future__ import annotations
+
+from enum import Enum
+from pathlib import Path
+from urllib.parse import urlparse
+
+MEDIA_EXTS = {
+    ".mp4", ".mkv", ".webm", ".mov", ".m4v", ".avi", ".flv", ".wmv",
+    ".ts", ".m4a", ".mp3", ".opus", ".ogg", ".wav",
+}
+MANIFEST_EXTS = {".m3u8", ".mpd"}
+
+
+class SourceKind(str, Enum):  # noqa: UP042 — StrEnum needs 3.11+, str+Enum reads the same
+    """What kind of input the user handed us."""
+
+    PAGE_URL = "page_url"        # any website; yt-dlp's 1800+ extractors
+    DIRECT_URL = "direct_url"    # URL pointing straight at a media file
+    MANIFEST_URL = "manifest_url"  # HLS (.m3u8) / DASH (.mpd) manifest
+    LOCAL_FILE = "local_file"
+    SCREEN = "screen"            # `screen:` — capture the screen (Milestone 3)
+    WINDOW = "window"            # `window:<title>` — capture one window (Milestone 3)
+
+
+def classify_source(source: str) -> SourceKind:
+    """Map a raw source string to a :class:`SourceKind`.
+
+    Rules: ``screen:`` / ``window:`` prefixes are capture requests; http(s)
+    URLs are split by path suffix into manifest / direct-media / page URLs;
+    everything else is treated as a local file path.
+    """
+    stripped = source.strip()
+    lowered = stripped.lower()
+    if lowered == "screen:" or lowered.startswith("screen:"):
+        return SourceKind.SCREEN
+    if lowered.startswith("window:"):
+        return SourceKind.WINDOW
+
+    parsed = urlparse(stripped)
+    if parsed.scheme in ("http", "https") and parsed.netloc:
+        suffix = Path(parsed.path).suffix.lower()
+        if suffix in MANIFEST_EXTS:
+            return SourceKind.MANIFEST_URL
+        if suffix in MEDIA_EXTS:
+            return SourceKind.DIRECT_URL
+        return SourceKind.PAGE_URL
+
+    return SourceKind.LOCAL_FILE
+
+
+def is_url_kind(kind: SourceKind) -> bool:
+    """True for any source that must be fetched over the network."""
+    return kind in (SourceKind.PAGE_URL, SourceKind.DIRECT_URL, SourceKind.MANIFEST_URL)

watch_skill/acquire/types.py

@@ -0,0 +1,26 @@
+"""Shared acquisition data types."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from watch_skill.acquire.sources import SourceKind
+
+
+@dataclass
+class AcquireResult:
+    """A source resolved to local files.
+
+    ``video_path`` is ``None`` only for captions-only probes (no media was
+    needed). ``info`` carries whatever metadata the acquirer learned (title,
+    uploader, duration, webpage URL).
+    """
+
+    source: str
+    kind: SourceKind
+    video_path: Path | None
+    subtitle_path: Path | None = None
+    info: dict[str, Any] = field(default_factory=dict)
+    from_cache: bool = False
+    acquirer: str = "unknown"  # which chain step produced this: yt-dlp | cobalt | ffmpeg | local