hugpy-video 0.2.3__tar.gz

hugpy_video-0.2.3/LICENSE

@@ -0,0 +1,41 @@
+hugpy — Source-Available License
+
+Copyright (c) 2026 putkoff (hugpy.ai). All rights reserved.
+
+Permission is granted, free of charge, to use this software ("hugpy") for
+personal and non-commercial purposes, and for time-limited commercial
+evaluation, subject to the following conditions:
+
+1. Non-commercial use means use by an individual for personal purposes, or
+   use by a non-profit or educational institution for its own internal
+   purposes. Any use by, for, or on behalf of a for-profit business or in
+   connection with revenue-generating activity is commercial use — including
+   internal business use, use in producing goods or services, and use on
+   paid engagements.
+
+2. Commercial use requires a commercial license from the copyright holder.
+   Exception: a business may evaluate the software internally for up to
+   thirty (30) days free of charge; continued use after that requires a
+   commercial license.
+
+3. Redistribution of this software, in source or binary form, modified or
+   unmodified, is not permitted without prior written permission from the
+   copyright holder. Downloading the software from an official distribution
+   channel (PyPI, npm, hugpy.ai) is not redistribution.
+
+4. Modification for personal use or internal evaluation is permitted;
+   distribution of modified versions is not.
+
+5. This notice must be retained in all copies or substantial portions of
+   the software.
+
+6. Any use outside these terms automatically terminates this license.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
+
+For commercial licensing or redistribution permission: https://hugpy.ai

hugpy_video-0.2.3/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: hugpy-video
+Version: 0.2.3
+Summary: Hugpy video: media library and job bus, ffmpeg, synthetic and studio runners, reservations and studio sessions for video intelligence
+Author-email: putkoff <support@hugpy.ai>
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://hugpy.ai
+Project-URL: Documentation, https://github.com/hugpy/hugpy/blob/main/py/cinema/hugpy_video/README.md
+Project-URL: Repository, https://github.com/hugpy/hugpy
+Project-URL: Source, https://github.com/hugpy/hugpy/tree/main/py/cinema/hugpy_video
+Project-URL: Issues, https://github.com/hugpy/hugpy/issues
+Project-URL: Changelog, https://github.com/hugpy/hugpy/releases
+Project-URL: Architecture, https://github.com/hugpy/hugpy/blob/main/PARTITION.md
+Keywords: hugpy,llm,self-hosted,video,ffmpeg,video-generation,media-intelligence
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: hugpy-platform
+Requires-Dist: hugpy-control
+Requires-Dist: hugpy-engine
+Requires-Dist: hugpy-media
+Requires-Dist: pydantic>=2
+Requires-Dist: abstract-essentials
+Provides-Extra: render
+Requires-Dist: numpy; extra == "render"
+Requires-Dist: Pillow; extra == "render"
+Requires-Dist: requests; extra == "render"
+Provides-Extra: studio
+Requires-Dist: torch; extra == "studio"
+Requires-Dist: diffusers; extra == "studio"
+Requires-Dist: transformers; extra == "studio"
+Requires-Dist: numpy; extra == "studio"
+Requires-Dist: Pillow; extra == "studio"
+Requires-Dist: opencv-python-headless; extra == "studio"
+Requires-Dist: imageio; extra == "studio"
+Requires-Dist: imageio-ffmpeg; extra == "studio"
+Requires-Dist: requests; extra == "studio"
+Provides-Extra: identity
+Requires-Dist: abstract-identity; extra == "identity"
+Requires-Dist: requests; extra == "identity"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-timeout; extra == "test"
+Dynamic: license-file
+
+# hugpy-video
+
+Execution and artifacts for Hugpy video work, extracted from the monolith's
+`abstract_hugpy_dev.video_intel` (+ `managers/video`, `managers/video_gen`,
+`comms/studio_assist_log`). Import name `hugpy_video`.
+
+**Status: extracted.** Runtime code lives here; the package imports with the
+monolith blocked and with no optional stack (torch/diffusers/ffmpeg bindings)
+installed. Allowed ecosystem imports: `hugpy_platform`, `hugpy_control`,
+`hugpy_engine`, `hugpy_media`. Never `hugpy_oracle`, `hugpy_fleet`,
+`hugpy_server` (see `py/partition.toml`, `PARTITION.md`).
+
+## Layout
+- `intel/` — media references + jail (`media_store`), sqlite media job bus
+  (`media_bus`) and its control-plane bridge (`job_bridge`), frozen job specs
+  and registry (`job_schema`), presets, GPU reservation engine
+  (`reservation/`), runners (ffmpeg, diffusers plane, studio, identity relays,
+  MLT), the studio spine (`studio/`).
+- `chat_video/` — chat-side frame analysis over a `hugpy_media` vision runner.
+- `video_gen/` — `StudioVideoRunner` / `VideoGenRequest`: the engine task
+  runner for text-to-video / image-to-video.
+- `plugin.py` — `hugpy_engine.tasks` entry point (`hugpy_video.plugin:register`);
+  import-light, runner resolved lazily.
+- `hooks.py` — `PromptCoordinator` protocol (oracle installs its implementation;
+  no-op default). `jobs.py` — public bus API incl. `register_job` for
+  upper-layer jobs (the oracle's `video_performance`).
+- `state.py` — injectable state roots (`HUGPY_VIDEO_STATE_DIR`,
+  `HUGPY_MEDIA_JOBS_DB`, `HUGPY_RESERVATIONS_DB`, platform storage roots).
+- `intel/plane.py` — the one seam onto the engine's `execute_prompt`.
+- `cli.py` — `hugpy-video --help | jobs list | jobs registry | selftest | state`.
+- `hugpy-video models audit [--json]` inventories every declared model's
+  runner gaps, weight pin and minimum VRAM without loading weights.
+- `config.py` — canonical `HUGPY_API_KEY` / `HUGPY_BASE` loader.
+
+Extras: `render` (numpy/Pillow/requests), `studio` (torch/diffusers zoo),
+`identity` (abstract-identity client), `test`.
+
+The `identity` extra installs the separate `abstract-identity` distribution.
+The central video runner relays mesh and char360 jobs to its service using
+`IDENTITY_RENDER_URL` and `IDENTITY_RENDER_TOKEN`; installing the extra alone
+does not start a GPU service. Studio model sweeps use
+`POST /video/studio/tester`; each attempt records its model, input image,
+sampler settings, frame count and negative prompt in the battery log.
+
+## Rules (inherited from char360 / hugpy-agent)
+- Heavy imports lazy — must import on a CPU-only box.
+- Version single-sourced from pyproject (importlib.metadata; no hardcoded `__version__`).
+- Credentials only via `hugpy_video.config.load_config` — canonical names
+  `HUGPY_API_KEY` / `HUGPY_BASE`; legacy aliases accepted but recorded in
+  `Config.deprecations`.
+- Build: `python -m build`; publish = copy dists (console dir needs the sha256
+  sidecar; the pypi index computes hashes itself, dir name must be the
+  normalized dashed name `hugpy-video`).

hugpy_video-0.2.3/README.md

@@ -0,0 +1,53 @@
+# hugpy-video
+
+Execution and artifacts for Hugpy video work, extracted from the monolith's
+`abstract_hugpy_dev.video_intel` (+ `managers/video`, `managers/video_gen`,
+`comms/studio_assist_log`). Import name `hugpy_video`.
+
+**Status: extracted.** Runtime code lives here; the package imports with the
+monolith blocked and with no optional stack (torch/diffusers/ffmpeg bindings)
+installed. Allowed ecosystem imports: `hugpy_platform`, `hugpy_control`,
+`hugpy_engine`, `hugpy_media`. Never `hugpy_oracle`, `hugpy_fleet`,
+`hugpy_server` (see `py/partition.toml`, `PARTITION.md`).
+
+## Layout
+- `intel/` — media references + jail (`media_store`), sqlite media job bus
+  (`media_bus`) and its control-plane bridge (`job_bridge`), frozen job specs
+  and registry (`job_schema`), presets, GPU reservation engine
+  (`reservation/`), runners (ffmpeg, diffusers plane, studio, identity relays,
+  MLT), the studio spine (`studio/`).
+- `chat_video/` — chat-side frame analysis over a `hugpy_media` vision runner.
+- `video_gen/` — `StudioVideoRunner` / `VideoGenRequest`: the engine task
+  runner for text-to-video / image-to-video.
+- `plugin.py` — `hugpy_engine.tasks` entry point (`hugpy_video.plugin:register`);
+  import-light, runner resolved lazily.
+- `hooks.py` — `PromptCoordinator` protocol (oracle installs its implementation;
+  no-op default). `jobs.py` — public bus API incl. `register_job` for
+  upper-layer jobs (the oracle's `video_performance`).
+- `state.py` — injectable state roots (`HUGPY_VIDEO_STATE_DIR`,
+  `HUGPY_MEDIA_JOBS_DB`, `HUGPY_RESERVATIONS_DB`, platform storage roots).
+- `intel/plane.py` — the one seam onto the engine's `execute_prompt`.
+- `cli.py` — `hugpy-video --help | jobs list | jobs registry | selftest | state`.
+- `hugpy-video models audit [--json]` inventories every declared model's
+  runner gaps, weight pin and minimum VRAM without loading weights.
+- `config.py` — canonical `HUGPY_API_KEY` / `HUGPY_BASE` loader.
+
+Extras: `render` (numpy/Pillow/requests), `studio` (torch/diffusers zoo),
+`identity` (abstract-identity client), `test`.
+
+The `identity` extra installs the separate `abstract-identity` distribution.
+The central video runner relays mesh and char360 jobs to its service using
+`IDENTITY_RENDER_URL` and `IDENTITY_RENDER_TOKEN`; installing the extra alone
+does not start a GPU service. Studio model sweeps use
+`POST /video/studio/tester`; each attempt records its model, input image,
+sampler settings, frame count and negative prompt in the battery log.
+
+## Rules (inherited from char360 / hugpy-agent)
+- Heavy imports lazy — must import on a CPU-only box.
+- Version single-sourced from pyproject (importlib.metadata; no hardcoded `__version__`).
+- Credentials only via `hugpy_video.config.load_config` — canonical names
+  `HUGPY_API_KEY` / `HUGPY_BASE`; legacy aliases accepted but recorded in
+  `Config.deprecations`.
+- Build: `python -m build`; publish = copy dists (console dir needs the sha256
+  sidecar; the pypi index computes hashes itself, dir name must be the
+  normalized dashed name `hugpy-video`).

hugpy_video-0.2.3/pyproject.toml

@@ -0,0 +1,81 @@
+[build-system]
+requires = ["setuptools>=77", "setuptools-scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hugpy-video"
+dynamic = ["version"]
+description = "Hugpy video: media library and job bus, ffmpeg, synthetic and studio runners, reservations and studio sessions for video intelligence"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+authors = [{ name = "putkoff", email = "support@hugpy.ai" }]
+keywords = [
+    "hugpy",
+    "llm",
+    "self-hosted",
+    "video",
+    "ffmpeg",
+    "video-generation",
+    "media-intelligence",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+# Heavy engine deps (torch, wan, ltx, rife, opencv, ...) are deliberately NOT
+# listed: declare only what import-time needs and keep every heavy import
+# lazy inside the function that uses it so the package imports on a CPU-only box.
+dependencies = [
+    "hugpy-platform",
+    "hugpy-control",
+    "hugpy-engine",
+    "hugpy-media",
+    "pydantic>=2",
+    "abstract-essentials",
+]
+
+[project.urls]
+Homepage = "https://hugpy.ai"
+Documentation = "https://github.com/hugpy/hugpy/blob/main/py/cinema/hugpy_video/README.md"
+Repository = "https://github.com/hugpy/hugpy"
+Source = "https://github.com/hugpy/hugpy/tree/main/py/cinema/hugpy_video"
+Issues = "https://github.com/hugpy/hugpy/issues"
+Changelog = "https://github.com/hugpy/hugpy/releases"
+Architecture = "https://github.com/hugpy/hugpy/blob/main/PARTITION.md"
+
+[project.optional-dependencies]
+# ffmpeg/diffusers-plane runners and the identity relays (HTTP).
+render = ["numpy", "Pillow", "requests"]
+# The studio spine's GPU zoo (Wan / VACE / LTX / RIFE).
+studio = ["torch", "diffusers", "transformers", "numpy", "Pillow", "opencv-python-headless", "imageio", "imageio-ffmpeg", "requests"]
+# Identity rendering stays behind the external abstract-identity service client.
+identity = ["abstract-identity", "requests"]
+test = ["pytest>=8", "pytest-timeout"]
+
+[project.scripts]
+hugpy-video = "hugpy_video.cli:main"
+
+[project.entry-points."hugpy_engine.tasks"]
+video = "hugpy_video.plugin:register"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+hugpy_video = ["py.typed", "**/*.json", "**/*.md", "**/*.txt"]
+
+# ---------------------------------------------------------------------------
+# Lockstep workspace version (2026-09-22): every in-tree hugpy-* distribution
+# takes ONE version from the workspace git tag (vX.Y.Z at the repo root), so a
+# release is a tag and a build always carries the commit it came from
+# (X.Y.Z.devN+g<sha>[.dirty] between tags). A checkout without git metadata
+# builds as 0.0.0+unknown, which central refuses to advertise to workers.
+[tool.setuptools_scm]
+root = "../../.."
+fallback_version = "0.0.0+unknown"

hugpy_video-0.2.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hugpy_video-0.2.3/src/hugpy_video/__init__.py

@@ -0,0 +1,33 @@
+"""hugpy-video: execution and artifacts for Hugpy video work.
+
+Owns the media library jail, the sqlite media job bus and its lifecycle
+bridge, the frozen job specs and presets, the GPU reservation engine, the
+ffmpeg/diffusers/studio/identity runners and the studio spine
+(``intel``), the chat-side video analyzer (``chat_video``), the engine
+task runner for text-/image-to-video (``video_gen``) and the studio assist
+log. Decisions and plans belong to ``hugpy_oracle``, which plugs in through
+``hugpy_video.hooks`` (prompt coordination) and ``hugpy_video.jobs``
+(``register_job``) — this package never imports the oracle, the fleet or
+the server.
+
+Import-light: nothing here pulls torch/ffmpeg/studio stacks. Sub-modules are
+imported explicitly by callers (``hugpy_video.jobs``, ``hugpy_video.hooks``,
+``hugpy_video.plugin``, ``hugpy_video.state``, ``hugpy_video.config``).
+
+Version is single-sourced from pyproject.toml via importlib.metadata.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("hugpy-video")
+except PackageNotFoundError:  # running from a checkout without install
+    __version__ = "0.0.0+unknown"
+
+from hugpy_video.config import Config, load_config  # stdlib-only, cheap
+
+__all__ = [
+    "__version__",
+    "Config",
+    "load_config",
+]

hugpy_video-0.2.3/src/hugpy_video/chat_video/__init__.py

@@ -0,0 +1 @@
+"""Chat-side video helpers (old ``managers/video``). Import-light; see ``video_analyzer``."""

hugpy_video-0.2.3/src/hugpy_video/chat_video/video_analyzer.py

@@ -0,0 +1,174 @@
+"""Frame-by-frame video analysis over a vision runner (chat-side helper).
+
+Import-light: the vision runner/schemas come from ``hugpy_media`` (allowed),
+the no-think helpers from ``hugpy_engine`` (lazy, inside the loop).
+"""
+from __future__ import annotations
+
+import copy
+import os.path as osp
+import time
+import uuid
+from typing import Any, Union
+
+from abstract_essentials import safe_dump_to_file, safe_load_from_json
+from hugpy_media.vision.schemas import VisionRequest
+from hugpy_media.vision.vision_runner import VisionRunner
+from hugpy_platform.utils import get_base_64_image, require_file
+
+from hugpy_video.schemas.video_schemas import (
+    FrameAnalysis,
+    VideoAnalysisConfig,
+    VideoAnalysisSummary,
+)
+
+def _resolve_manifest_path(source: Union[str, Any]) -> str:
+    if isinstance(source, str):
+        return source
+    p = getattr(source, "manifest_path", None)
+    if isinstance(p, str):
+        return p
+    raise TypeError(
+        f"expected manifest path str or object with .manifest_path, "
+        f"got {type(source).__name__}"
+    )
+
+def _build_prompt(user_prompt: str, frame_context: dict) -> str:
+    return (
+        "-----------prompt---------\n"
+        f"{user_prompt}\n"
+        "-----------frame context---------\n"
+        f"{frame_context}\n"
+    )
+
+
+async def analyze_video(
+    source: Union[str, Any],
+    runner: VisionRunner,
+    config: VideoAnalysisConfig,
+) -> VideoAnalysisSummary:
+    manifest_path = require_file(_resolve_manifest_path(source), "manifest_path")
+    manifest_data = safe_load_from_json(manifest_path)
+    if not isinstance(manifest_data, dict):
+        raise ValueError(f"manifest is not a dict: {manifest_path}")
+
+    workspace_dir = manifest_data.get("workspace_dir")
+    if not workspace_dir or not osp.isdir(workspace_dir):
+        raise FileNotFoundError(f"workspace_dir invalid: {workspace_dir!r}")
+
+    files = manifest_data.get("files") or {}
+    frame_context_path = require_file(files.get("frame_context"), "files.frame_context")
+
+    frame_contexts = safe_load_from_json(frame_context_path)
+    if not isinstance(frame_contexts, list) or not frame_contexts:
+        raise ValueError(
+            f"frame_context must be a non-empty list, "
+            f"got {type(frame_contexts).__name__}"
+        )
+
+    total_frames = len(frame_contexts)
+    last = frame_contexts[-1]
+    total_video_length = last.get("timestamp") if isinstance(last, dict) else None
+
+    analysis_json_path = osp.join(workspace_dir, "analysis.json")
+    manifest_data.setdefault("files", {})["analysis_json"] = analysis_json_path
+    safe_dump_to_file(data=manifest_data, file_path=manifest_path)
+
+    # Resume keyed by frame_path so reruns are idempotent.
+    done_by_frame: dict[str, dict] = {}
+    if config.resume and osp.isfile(analysis_json_path):
+        prior = safe_load_from_json(analysis_json_path) or []
+        for entry in prior:
+            fp = entry.get("frame_path")
+            if fp and entry.get("error") is None:
+                done_by_frame[fp] = entry
+
+    records: list[dict] = list(done_by_frame.values())
+    model_key = runner.cfg.model_key  # runner is the source of truth
+
+    for i, raw_ctx in enumerate(frame_contexts):
+        if not isinstance(raw_ctx, dict):
+            records.append({
+                "frame_index": i,
+                "error": f"frame_context[{i}] is not a dict",
+            })
+            continue
+
+        ctx = copy.deepcopy(raw_ctx)  # never mutate caller's data
+        frame_path = ctx.get("frame_path")
+
+        if not frame_path or not osp.isfile(frame_path):
+            err = f"frame_path missing or not found: {frame_path!r}"
+            if config.raise_on_frame_error:
+                raise FileNotFoundError(err)
+            ctx.update({"frame_index": i, "error": err})
+            records.append(ctx)
+            continue
+
+        if frame_path in done_by_frame:
+            continue
+
+        ctx["frame_index"] = i
+        ctx["total_frames"] = total_frames
+        ctx["total_video_length"] = total_video_length
+        # NO-THINK (utils/no_think.py). Every frame's `analysis` is VALIDATED and
+        # PERSISTED to analysis.json — a monologue here poisons the whole dataset,
+        # and nothing downstream re-reads the frame to notice. The reasoning is
+        # kept alongside (FrameAnalysis is extra="allow") rather than discarded.
+        from hugpy_engine.utils.no_think import with_no_think, strip_think
+        rendered_prompt = with_no_think(_build_prompt(config.prompt, ctx))
+        image_b64 = get_base_64_image(frame_path)
+        req = VisionRequest(
+            request_id=f"frame-{i}-{uuid.uuid4().hex[:8]}",
+            model_key=model_key,
+            prompt=rendered_prompt,
+            max_new_tokens=config.max_new_tokens,
+            max_tokens=config.max_tokens,
+            image_b64=image_b64,
+        )
+
+        t0 = time.time()
+        try:
+            vresult = await runner.run(req)
+            text, err = vresult.text, vresult.error
+        except Exception as e:
+            if config.raise_on_frame_error:
+                raise
+            text, err = None, f"{type(e).__name__}: {e}"
+        duration = time.time() - t0
+
+        reasoning = ""
+        if text:
+            text, reasoning = strip_think(text)
+            if not text:
+                # Nothing but thinking — record it as an error rather than
+                # persisting an empty analysis that reads like a clean run.
+                err = err or ("model returned only reasoning and no analysis "
+                              "(ignored the no-think directive)")
+
+        ctx.update({
+            "analysis_prompt": rendered_prompt,
+            "analysis": text,
+            "analysis_reasoning": reasoning,
+            "model_key": model_key,
+            "analysis_duration": duration,
+            "error": err,
+        })
+
+        # Validate-on-write: schema drift fails fast, not three days from now
+        FrameAnalysis.model_validate(ctx)
+        records.append(ctx)
+
+        if (i + 1) % config.save_every == 0 or (i + 1) == total_frames:
+            safe_dump_to_file(data=records, file_path=analysis_json_path)
+
+    succeeded = sum(1 for r in records if r.get("error") is None)
+    failed = sum(1 for r in records if r.get("error") is not None)
+
+    return VideoAnalysisSummary(
+        manifest_path=manifest_path,
+        analysis_json_path=analysis_json_path,
+        frames_total=total_frames,
+        frames_succeeded=succeeded,
+        frames_failed=failed,
+    )

hugpy_video-0.2.3/src/hugpy_video/cli.py

@@ -0,0 +1,130 @@
+"""``hugpy-video`` command line (minimal; the console script in pyproject).
+
+    hugpy-video --help
+    hugpy-video jobs list [--all] [--limit N] [--json]
+    hugpy-video jobs registry
+    hugpy-video selftest            # in-process checks, no GPU/service
+    hugpy-video models audit --json # declared model roster and readiness gates
+
+Everything heavy is imported inside the sub-command that needs it.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import List, Optional
+
+
+def _cmd_jobs_list(args) -> int:
+    from hugpy_video import jobs
+
+    rows = jobs.list_jobs(include_terminal=args.all, limit=args.limit)
+    if args.json:
+        print(json.dumps(rows, indent=2, default=str))
+        return 0
+    if not rows:
+        print("no jobs")
+        return 0
+    for r in rows:
+        print(f"{r.get('job_id','?'):34} {r.get('name','?'):26} {r.get('status','?')}")
+    return 0
+
+
+def _cmd_jobs_registry(args) -> int:
+    from hugpy_video import jobs
+
+    for name, spec in sorted(jobs.registered_jobs().items()):
+        print(f"{name:26} {spec.runner_key[0]}/{spec.runner_key[1]:18} "
+              f"queue={spec.queue} timeout={spec.timeout_s}s")
+    return 0
+
+
+def _cmd_selftest(args) -> int:
+    from hugpy_video.selftest import run_selftest
+
+    failures = run_selftest(verbose=True)
+    return 1 if failures else 0
+
+
+def _cmd_state(args) -> int:
+    from dataclasses import asdict
+
+    from hugpy_video.state import get_state_roots
+
+    print(json.dumps(asdict(get_state_roots()), indent=2))
+    return 0
+
+
+def _cmd_models_audit(args) -> int:
+    """Inventory every declared model without loading weights or allocating a GPU."""
+    from hugpy_video.intel.studio.registry import MODEL_REGISTRY, model_gate_reasons
+
+    rows = []
+    for model_id, cfg in sorted(MODEL_REGISTRY.items()):
+        precision_gb = {precision.value: gb for precision, gb in cfg.vram.per_precision}
+        rows.append({
+            "model_id": model_id,
+            "family": cfg.family.value,
+            "capabilities": sorted(cap.value for cap in cfg.capabilities),
+            "tasks": sorted(task.value for task in cfg.tasks),
+            "minimum_vram_gb": min(precision_gb.values()) if precision_gb else None,
+            "vram_by_precision_gb": precision_gb,
+            "weights_pinned": cfg.weight_hash is not None,
+            "runner_gaps": model_gate_reasons(model_id),
+        })
+    if args.json:
+        print(json.dumps({"models": rows}, indent=2, sort_keys=True))
+    else:
+        for row in rows:
+            status = ", ".join(row["runner_gaps"].values()) or "runner present"
+            pin = "pinned" if row["weights_pinned"] else "unpinned"
+            print(f"{row['model_id']:32} {row['minimum_vram_gb']!s:>6} GB  {pin:8}  {status}")
+        print(f"{len(rows)} declared models; audit does not prove installed weights or GPU readiness")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    from hugpy_video import __version__
+
+    p = argparse.ArgumentParser(prog="hugpy-video",
+                                description="Hugpy video: media job bus, runners, studio.")
+    p.add_argument("--version", action="version", version=f"hugpy-video {__version__}")
+    sub = p.add_subparsers(dest="cmd")
+
+    jobs = sub.add_parser("jobs", help="media job bus")
+    jsub = jobs.add_subparsers(dest="jobs_cmd")
+    ls = jsub.add_parser("list", help="list jobs")
+    ls.add_argument("--all", action="store_true", help="include terminal jobs")
+    ls.add_argument("--limit", type=int, default=50)
+    ls.add_argument("--json", action="store_true")
+    ls.set_defaults(func=_cmd_jobs_list)
+    reg = jsub.add_parser("registry", help="registered job names and runner keys")
+    reg.set_defaults(func=_cmd_jobs_registry)
+
+    st = sub.add_parser("selftest", help="in-process self checks (no GPU, no service)")
+    st.set_defaults(func=_cmd_selftest)
+
+    state = sub.add_parser("state", help="print the resolved state roots")
+    state.set_defaults(func=_cmd_state)
+    models = sub.add_parser("models", help="studio model inventory")
+    msub = models.add_subparsers(dest="models_cmd")
+    audit = msub.add_parser("audit", help="report runner, pin and VRAM requirements")
+    audit.add_argument("--json", action="store_true")
+    audit.set_defaults(func=_cmd_models_audit)
+    return p
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    func = getattr(args, "func", None)
+    if func is None:
+        parser.print_help()
+        return 0
+    return int(func(args) or 0)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())