continuityguard-cli 0.1.0__py3-none-any.whl

continuityguard/report/types.py

@@ -0,0 +1,64 @@
+"""
+CG04 -- shared report shape consumed by both the JSON writer
+(continuityguard/report/json_report.py) and the terminal writer
+(continuityguard/report/terminal.py). Every flagged shot carries a
+timestamp/frame index, a numeric score, and a plain-language reason --
+never a bare pass/fail -- so a human reviewer or a parsing agent knows
+*why* a shot was flagged.
+
+Ported field-for-field from src/report/types.ts. Field names use
+snake_case (not the TS camelCase) since that's the Python-idiomatic
+convention and this matches the JSON keys the TS side already serializes
+(the TS `ScanReport` interface itself uses snake_case JSON field names,
+e.g. `scanned_directory`, `character_consistency`) -- so the JSON report
+produced by this Python port is structurally identical to the TS one.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List
+
+
+@dataclass(frozen=True)
+class ConsistencyFlagReport:
+    clip: str
+    character: str
+    reference_clip: str
+    similarity_score: float
+    reason: str
+
+
+@dataclass(frozen=True)
+class PhysicsFlagReport:
+    clip: str
+    frame_index_a: int
+    frame_index_b: int
+    discontinuity_ratio: float
+    reason: str
+
+
+@dataclass(frozen=True)
+class CharacterConsistencyReport:
+    characters_tracked: int
+    similarity_threshold: float
+    flagged_shots: List[ConsistencyFlagReport] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class PhysicsPlausibilityReport:
+    discontinuity_multiplier: float
+    flagged_shots: List[PhysicsFlagReport] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class ScanReport:
+    scan_id: str
+    scanned_directory: str
+    clips_scanned: int
+    frames_extracted: int
+    character_consistency: CharacterConsistencyReport
+    physics_plausibility: PhysicsPlausibilityReport
+    generated_at: str
+    tool_version: str
+    scan_duration_seconds: float
+    network_calls_made: int = 0

continuityguard/scan.py

@@ -0,0 +1,147 @@
+"""
+Top-level library entry point: CG01 ingestion -> CG02 character-consistency
+scoring -> CG03 physics-plausibility heuristic -> a structured ScanReport.
+
+This is the agent-native path: `from continuityguard import scan` gives a
+CI script or an agent an in-process `ScanReport` object with no CLI
+subprocess involved. `continuityguard/cli.py` is a thin argparse wrapper
+around this same function, so the CLI and the library never drift.
+
+Ported from the orchestration logic in src/cli.ts's `runScan`, split out
+into its own importable module since the TypeScript CLI does not expose a
+separate library entry point the way this Python port does.
+"""
+from __future__ import annotations
+
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import List, Optional
+
+from .ingest.ffmpeg import (
+    ExtractedFrames,
+    cleanup_frames,
+    extract_frames_from_directory,
+    list_clips,
+)
+from .report.types import (
+    CharacterConsistencyReport,
+    ConsistencyFlagReport,
+    PhysicsFlagReport,
+    PhysicsPlausibilityReport,
+    ScanReport,
+)
+from .score.consistency import CONSISTENCY_SIMILARITY_THRESHOLD, ShotInput, score_consistency
+from .score.physics import DISCONTINUITY_MULTIPLIER, PhysicsShotInput, score_physics
+
+TOOL_VERSION = "0.1.0"
+
+
+class NoClipsFoundError(Exception):
+    """Raised when the target directory contains no supported video clips.
+
+    Deliberately NOT a subclass of FileNotFoundError -- the directory
+    itself does exist and was read successfully; it just contains no
+    supported clip files. Callers (see cli.py) need to tell this apart
+    from "the directory path itself is wrong," which does raise a plain
+    FileNotFoundError from list_clips().
+    """
+
+
+def scan(
+    directory: str,
+    fps: Optional[float] = None,
+) -> ScanReport:
+    """
+    Scans a directory of generated clips for character-consistency and
+    physics-plausibility flags, and returns a structured ScanReport.
+
+    Raises FileNotFoundError if the directory does not exist,
+    NotADirectoryError if the path is not a directory, NoClipsFoundError if
+    the directory contains no supported clips, and RuntimeError if ffmpeg
+    fails to decode a clip. Callers that want the CLI's clean
+    stderr-message-plus-exit-code behavior instead of raised exceptions
+    should use `continuityguard.cli.run_scan`.
+    """
+    target_dir = str(Path(directory).resolve())
+    clips = list_clips(target_dir)
+    if not clips:
+        raise NoClipsFoundError(
+            f"No supported video clips found in {target_dir}. "
+            "Supported extensions: .mp4 .mov .mkv .webm .avi"
+        )
+
+    started_at = time.time()
+    extracted: List[ExtractedFrames] = []
+    try:
+        extracted = extract_frames_from_directory(target_dir, fps=fps)
+        frames_extracted = sum(len(e.frame_paths) for e in extracted)
+
+        consistency_result = score_consistency(
+            [ShotInput(clip=e.clip.name, frame_paths=e.frame_paths) for e in extracted]
+        )
+        physics_result = score_physics(
+            [PhysicsShotInput(clip=e.clip.name, frame_paths=e.frame_paths) for e in extracted]
+        )
+
+        duration_seconds = time.time() - started_at
+        started_dt = datetime.fromtimestamp(started_at, tz=timezone.utc)
+        # Matches the TS side's `cg-${isoString.replace(/[:.]/g, '-')}`.
+        started_iso = (
+            started_dt.strftime("%Y-%m-%dT%H:%M:%S.")
+            + f"{int(started_dt.microsecond / 1000):03d}Z"
+        )
+        scan_id = "cg-" + started_iso.replace(":", "-").replace(".", "-")
+
+        report = ScanReport(
+            scan_id=scan_id,
+            scanned_directory=target_dir,
+            clips_scanned=len(clips),
+            frames_extracted=frames_extracted,
+            character_consistency=CharacterConsistencyReport(
+                characters_tracked=consistency_result.characters_tracked,
+                similarity_threshold=CONSISTENCY_SIMILARITY_THRESHOLD,
+                flagged_shots=[
+                    ConsistencyFlagReport(
+                        clip=f.clip,
+                        character=f.character,
+                        reference_clip=f.reference_clip,
+                        similarity_score=f.similarity_score,
+                        reason=f.reason,
+                    )
+                    for f in consistency_result.flagged_shots
+                ],
+            ),
+            physics_plausibility=PhysicsPlausibilityReport(
+                discontinuity_multiplier=DISCONTINUITY_MULTIPLIER,
+                flagged_shots=[
+                    PhysicsFlagReport(
+                        clip=f.clip,
+                        frame_index_a=f.frame_index_a,
+                        frame_index_b=f.frame_index_b,
+                        discontinuity_ratio=f.discontinuity_ratio,
+                        reason=f.reason,
+                    )
+                    for f in physics_result.flagged_shots
+                ],
+            ),
+            generated_at=datetime.now(tz=timezone.utc).isoformat().replace("+00:00", "Z"),
+            tool_version=TOOL_VERSION,
+            scan_duration_seconds=duration_seconds,
+            network_calls_made=0,
+        )
+        return report
+    finally:
+        cleanup_frames(extracted)
+
+
+async def scan_async(directory: str, fps: Optional[float] = None) -> ScanReport:
+    """Async wrapper around `scan`, run in a thread so it does not block an
+    event loop -- useful for callers already inside `asyncio` (e.g. an
+    agent framework's async tool-call handler). ffmpeg decode and ONNX
+    inference are both CPU/subprocess-bound work, not natively async, so
+    this offloads to a worker thread rather than reimplementing an async
+    ffmpeg/onnxruntime pipeline."""
+    import asyncio
+
+    return await asyncio.to_thread(scan, directory, fps)

continuityguard/score/__init__.py

@@ -0,0 +1,2 @@
+"""CG02/CG03 -- scoring. Ported from src/score/consistency.ts and
+src/score/physics.ts."""

continuityguard/score/consistency.py

@@ -0,0 +1,226 @@
+"""
+CG02 -- character-consistency scoring.
+
+Computes a per-shot visual embedding and flags cross-shot pairs (claiming
+to be the same named character) whose cosine similarity falls below a
+threshold derived from this repo's own fixture run (see
+src/score/testdata/ and the root CHANGELOG.md's "CG02 fixture
+calibration" entry -- never an invented number; the Python port reuses
+the exact same threshold since it uses the exact same bundled model file
+and the same fixture clips).
+
+IMPORTANT, stated plainly and repeated in the CLI output, the JSON
+`reason` field, and the README: this technique is best-validated on
+photorealistic/live-action content. Its accuracy on stylized or
+anime-adjacent character designs -- the dominant visual style in the
+short-drama category this tool targets -- is UNVERIFIED. Treat a flag on
+stylized footage as "worth a second look," never as a confirmed defect.
+
+Runtime note: this port uses `onnxruntime` (the Python package), the same
+ONNX Runtime project as the TS side's `onnxruntime-node`, loading the
+identical bundled `mobilenetv2-7.onnx` file the npm package ships (see
+models/NOTICE.md for the model's provenance and the honest limitations of
+using a generic ImageNet feature extractor instead of a dedicated face/CLIP
+embedding model). Same model file, same runtime family, same preprocessing
+-> same embeddings and the same flagged shots as the TypeScript CLI on
+identical input.
+
+Ported from src/score/consistency.ts.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional, Sequence
+
+import numpy as np
+import onnxruntime as ort
+
+from ..ingest.ffmpeg import FRAME_SIZE, read_raw_frame
+
+_MODEL_PATH = Path(__file__).resolve().parent / "models" / "mobilenetv2-7.onnx"
+
+# ImageNet normalization constants used by the bundled MobileNetV2 model's
+# documented preprocessing (see continuityguard/score/models/NOTICE.md).
+_IMAGENET_MEAN = (0.485, 0.456, 0.406)
+_IMAGENET_STD = (0.229, 0.224, 0.225)
+
+# Cross-shot cosine-similarity threshold below which a shot is flagged as a
+# likely character-consistency break. Derived from this repo's own fixture
+# run -- see the root CHANGELOG.md "CG02 fixture calibration" entry for the
+# exact command and raw numbers this value came from, not an illustrative
+# placeholder. Identical to the TS side's CONSISTENCY_SIMILARITY_THRESHOLD.
+CONSISTENCY_SIMILARITY_THRESHOLD = 0.88
+
+_cached_session: Optional[ort.InferenceSession] = None
+
+
+def get_embedding_session() -> ort.InferenceSession:
+    """Loads (and caches) the bundled ONNX embedding session. Never fetches
+    anything over the network -- the model file ships inside this package."""
+    global _cached_session
+    if _cached_session is None:
+        _cached_session = ort.InferenceSession(
+            str(_MODEL_PATH), providers=["CPUExecutionProvider"]
+        )
+    return _cached_session
+
+
+def preprocess_frame(raw: bytes) -> np.ndarray:
+    """Converts a raw HWC RGB24 frame buffer into the CHW, ImageNet-normalized
+    float32 array MobileNetV2 expects, shape (3, FRAME_SIZE, FRAME_SIZE)."""
+    size = FRAME_SIZE
+    pixels = np.frombuffer(raw, dtype=np.uint8).reshape(size, size, 3).astype(np.float32) / 255.0
+    mean = np.array(_IMAGENET_MEAN, dtype=np.float32)
+    std = np.array(_IMAGENET_STD, dtype=np.float32)
+    normalized = (pixels - mean) / std
+    # HWC -> CHW
+    return np.transpose(normalized, (2, 0, 1))
+
+
+def embed_frame(raw: bytes, session: ort.InferenceSession) -> np.ndarray:
+    """Runs one frame through the embedding model and returns its raw
+    1000-d output vector (see models/NOTICE.md for why this is the raw
+    classifier-logit vector rather than a dedicated embedding-layer
+    output)."""
+    input_array = preprocess_frame(raw)
+    tensor = input_array.reshape(1, 3, FRAME_SIZE, FRAME_SIZE)
+    input_name = session.get_inputs()[0].name
+    output_name = session.get_outputs()[0].name
+    results = session.run([output_name], {input_name: tensor})
+    return np.asarray(results[0], dtype=np.float32).reshape(-1)
+
+
+def embed_shot(frame_paths: Sequence[str], session: ort.InferenceSession) -> np.ndarray:
+    """Computes one embedding per shot by averaging the embeddings of every
+    sampled frame in that shot -- smooths single-frame noise into a more
+    stable per-shot signal than picking any single frame would."""
+    if not frame_paths:
+        raise ValueError("Cannot embed a shot with zero extracted frames")
+    total: Optional[np.ndarray] = None
+    for frame_path in frame_paths:
+        raw = read_raw_frame(frame_path)
+        embedding = embed_frame(raw, session)
+        total = embedding.copy() if total is None else total + embedding
+    assert total is not None
+    return total / len(frame_paths)
+
+
+def cosine_similarity(a: np.ndarray, b: np.ndarray) -> float:
+    if a.shape != b.shape:
+        raise ValueError("Cannot compare embeddings of different dimensionality")
+    norm_a = float(np.linalg.norm(a))
+    norm_b = float(np.linalg.norm(b))
+    if norm_a == 0 or norm_b == 0:
+        return 0.0
+    return float(np.dot(a, b) / (norm_a * norm_b))
+
+
+_CHARACTER_NAME_RE = re.compile(r"^([a-zA-Z][a-zA-Z0-9]*)_")
+
+
+def parse_character_name(clip_file_name: str) -> Optional[str]:
+    """
+    Infers the named character a clip belongs to from its filename, using
+    a `<character>_<shot-id>.<ext>` convention (e.g. "mei_shot01.mp4" ->
+    "mei"). This is a deliberate v0.1 simplification: there is no
+    industry-standard character-tagging metadata format across AI
+    short-drama pipelines, so ContinuityGuard reads it from the filename
+    rather than requiring a separate manifest. Clips that don't match the
+    convention return None and are never compared to each other for
+    consistency (no named-character claim to check them against).
+    """
+    without_ext = re.sub(r"\.[^.]+$", "", clip_file_name)
+    match = _CHARACTER_NAME_RE.match(without_ext)
+    return match.group(1).lower() if match else None
+
+
+@dataclass(frozen=True)
+class ShotInput:
+    clip: str
+    frame_paths: List[str]
+
+
+@dataclass(frozen=True)
+class ConsistencyFlag:
+    clip: str
+    character: str
+    reference_clip: str
+    similarity_score: float
+    reason: str
+
+
+@dataclass(frozen=True)
+class ConsistencyResult:
+    characters_tracked: int
+    flagged_shots: List[ConsistencyFlag] = field(default_factory=list)
+
+
+def build_consistency_reason(similarity: float) -> str:
+    """Builds the honest, unverified-content-labeled reason string for a
+    flagged shot -- kept as its own function so every call site (CLI, JSON
+    report) uses identical, never-drifting wording."""
+    return (
+        f"Cross-shot embedding similarity {similarity:.2f} is below the "
+        f"{CONSISTENCY_SIMILARITY_THRESHOLD:.2f} threshold. Best-validated on "
+        "photorealistic content; accuracy on stylized/anime-adjacent character designs "
+        "is unverified -- treat this as a prompt for human review, not a confirmed defect."
+    )
+
+
+def flag_inconsistent_shots(
+    shots: Sequence[Dict], threshold: float = CONSISTENCY_SIMILARITY_THRESHOLD
+) -> ConsistencyResult:
+    """
+    Pure grouping + flagging logic, independent of the embedding model --
+    given already-computed per-shot embeddings, groups by character and
+    flags any shot whose similarity to that character's first-seen
+    ("reference") shot falls below threshold. Split out from
+    `score_consistency` so this logic has fast, deterministic unit-test
+    coverage without depending on real ONNX inference for every test case.
+
+    Each item in `shots` is a dict with keys "clip" (str) and "embedding"
+    (np.ndarray).
+    """
+    by_character: "Dict[str, List[Dict]]" = {}
+    for shot in shots:
+        character = parse_character_name(shot["clip"])
+        if not character:
+            continue
+        by_character.setdefault(character, []).append(shot)
+
+    flagged_shots: List[ConsistencyFlag] = []
+    for character, bucket in by_character.items():
+        if len(bucket) < 2:
+            continue
+        reference = bucket[0]
+        for candidate in bucket[1:]:
+            similarity = cosine_similarity(reference["embedding"], candidate["embedding"])
+            if similarity < threshold:
+                flagged_shots.append(
+                    ConsistencyFlag(
+                        clip=candidate["clip"],
+                        character=character,
+                        reference_clip=reference["clip"],
+                        similarity_score=round(similarity, 4),
+                        reason=build_consistency_reason(similarity),
+                    )
+                )
+
+    return ConsistencyResult(characters_tracked=len(by_character), flagged_shots=flagged_shots)
+
+
+def score_consistency(
+    shots: Sequence[ShotInput],
+    session: Optional[ort.InferenceSession] = None,
+    threshold: float = CONSISTENCY_SIMILARITY_THRESHOLD,
+) -> ConsistencyResult:
+    """End-to-end CG02 entry point: computes embeddings for every shot (via
+    the real ONNX model) and flags cross-shot consistency breaks."""
+    active_session = session or get_embedding_session()
+    embedded: List[Dict] = []
+    for shot in shots:
+        embedding = embed_shot(shot.frame_paths, active_session)
+        embedded.append({"clip": shot.clip, "embedding": embedding})
+    return flag_inconsistent_shots(embedded, threshold)

continuityguard/score/models/NOTICE.md

@@ -0,0 +1,42 @@
+# Bundled model: MobileNetV2 (ONNX)
+
+`mobilenetv2-7.onnx` is the MobileNetV2-1.0 image classifier from the
+[ONNX Model Zoo](https://github.com/onnx/models), `validated/vision/classification/mobilenet`,
+opset 7. It is trained on ImageNet (ILSVRC2012) and licensed **Apache-2.0**
+(see the model directory's own `SPDX-License-Identifier: Apache-2.0` header
+in that repo), compatible with ContinuityGuard's own Apache-2.0 license.
+
+## Why this model, and not a face/CLIP embedding model
+
+Character-consistency scoring uses a pretrained ONNX embedding model via
+`onnxruntime-node`, with CLIP ViT-B/32 considered as one illustrative
+option before landing on MobileNetV2 below.
+`onnxruntime-node` itself works fine on this build's target
+platform (see the root README's "onnxruntime-node vs. WASM" note) -- the
+substitution here is the *model*, not the runtime.
+
+v0.1 ships MobileNetV2 instead of a dedicated face-recognition or CLIP
+embedding model for one practical reason: a specialized face/character
+embedding model that is both small enough to bundle directly in an npm
+package and unambiguously permissively licensed was not something this
+build could source, convert, and license-verify inside this session's
+scope. MobileNetV2 is small (14MB), Apache-2.0 licensed with no ambiguity,
+and works today.
+
+**What this means in practice, stated honestly:** ContinuityGuard's
+character-consistency score is a cosine-similarity comparison of
+MobileNetV2's final 1000-way ImageNet-logit vector between two character
+crops, used as a generic visual-similarity proxy -- not a specialized
+face-identity or CLIP embedding tuned for "is this the same character."
+It will respond to overall color, texture, and coarse-shape similarity
+between crops, which is a real but weaker signal than a dedicated
+face-recognition embedding would give you on photorealistic faces, and an
+even weaker, unvalidated signal on stylized/anime-adjacent character
+designs (see the main README's "Known limitations" section, which applies
+regardless of which embedding model is used underneath).
+
+This is disclosed here, in the CLI output, in the JSON report's `reason`
+field, and in the README -- not discovered later by a disappointed user.
+A future version can swap in a dedicated face-embedding ONNX model behind
+the same `computeEmbedding` interface in `src/score/consistency.ts` without
+changing the CLI or report shape.

continuityguard/score/physics.py

@@ -0,0 +1,170 @@
+"""
+CG03 -- physics-plausibility heuristic.
+
+This is a frame-to-frame motion-discontinuity proxy, computed as the mean
+absolute per-channel pixel difference between consecutive sampled frames
+of a shot (a frame-diff proxy, not optical-flow motion-vector extraction
+-- see the root README "Known limitations" for why this simpler proxy was
+chosen for v0.1). A shot is flagged when the diff between two consecutive
+frames exceeds a multiple of that shot's own local baseline (the median
+frame-to-frame diff across the whole shot).
+
+HARD RULE, enforced everywhere this feature is surfaced (CLI output, the
+JSON report's `reason` field, README copy): this heuristic never "detects"
+a physics violation. It only "flags a shot for human review." It has real
+false positives (legitimate fast motion, intentional stylized jump-cuts)
+and false negatives (subtly implausible motion that stays under the
+threshold) -- it is a proxy, not a ground-truth validator.
+
+Ported from src/score/physics.ts.
+"""
+from __future__ import annotations
+
+import statistics
+from dataclasses import dataclass, field
+from typing import List, Optional, Sequence
+
+import numpy as np
+
+from ..ingest.ffmpeg import FRAME_SIZE, read_raw_frame
+
+# A consecutive-frame diff is flagged when it exceeds this multiple of the
+# shot's own median frame-to-frame diff. Derived from this repo's own
+# fixture run -- see the root CHANGELOG.md "CG03 fixture calibration"
+# entry for the exact command and raw numbers this value came from, not an
+# illustrative placeholder. Identical to the TS side's
+# DISCONTINUITY_MULTIPLIER.
+DISCONTINUITY_MULTIPLIER = 3
+
+
+def compute_frame_diff(a: bytes, b: bytes) -> float:
+    """Mean absolute per-channel pixel difference between two same-sized
+    raw RGB24 frame buffers, normalized to [0, 1]. Uses numpy for speed
+    (numpy is already a transitive dependency via onnxruntime); the result
+    is numerically identical to a pure-Python sum of absolute differences."""
+    if len(a) != len(b):
+        raise ValueError("Cannot diff frames of different sizes")
+    arr_a = np.frombuffer(a, dtype=np.uint8).astype(np.int32)
+    arr_b = np.frombuffer(b, dtype=np.uint8).astype(np.int32)
+    total = int(np.abs(arr_a - arr_b).sum())
+    return total / len(a) / 255
+
+
+def compute_diff_sequence(frames: Sequence[bytes]) -> List[float]:
+    """Consecutive-frame diffs for an ordered sequence of frames. Length is
+    len(frames) - 1 (empty if fewer than 2 frames)."""
+    return [compute_frame_diff(frames[i - 1], frames[i]) for i in range(1, len(frames))]
+
+
+def _median(values: Sequence[float]) -> float:
+    return statistics.median(values)
+
+
+@dataclass(frozen=True)
+class Discontinuity:
+    frame_index_a: int
+    frame_index_b: int
+    diff: float
+    baseline: float
+    ratio: float
+
+
+def detect_discontinuities(
+    diffs: Sequence[float], multiplier: float = DISCONTINUITY_MULTIPLIER
+) -> List[Discontinuity]:
+    """Pure detection logic over an already-computed diff sequence -- split
+    out from `score_physics` so it has fast, deterministic unit-test
+    coverage independent of ffmpeg/frame extraction."""
+    if not diffs:
+        return []
+    baseline = _median(diffs)
+    found: List[Discontinuity] = []
+    for index, diff in enumerate(diffs):
+        if baseline == 0:
+            # A perfectly static baseline (e.g. an all-static shot) makes
+            # any ratio computation divide-by-zero/undefined; only flag if
+            # there is any motion at all against a genuinely zero baseline.
+            if diff > 0:
+                found.append(
+                    Discontinuity(
+                        frame_index_a=index,
+                        frame_index_b=index + 1,
+                        diff=diff,
+                        baseline=baseline,
+                        ratio=float("inf"),
+                    )
+                )
+            continue
+        ratio = diff / baseline
+        if ratio > multiplier:
+            found.append(
+                Discontinuity(
+                    frame_index_a=index,
+                    frame_index_b=index + 1,
+                    diff=diff,
+                    baseline=baseline,
+                    ratio=ratio,
+                )
+            )
+    return found
+
+
+def build_physics_reason(ratio: float) -> str:
+    ratio_text = f"{ratio:.1f}x" if ratio != float("inf") else "far above"
+    return (
+        f"Frame-to-frame motion discontinuity {ratio_text} this shot's local baseline. "
+        "This is a heuristic proxy, not a physics simulator -- it flags the shot for "
+        "human review, it does not detect a physics violation. Expect both false "
+        "positives (legitimate fast motion, stylized jump-cuts) and false negatives."
+    )
+
+
+@dataclass(frozen=True)
+class PhysicsShotInput:
+    clip: str
+    frame_paths: List[str]
+
+
+@dataclass(frozen=True)
+class PhysicsFlag:
+    clip: str
+    frame_index_a: int
+    frame_index_b: int
+    discontinuity_ratio: float
+    reason: str
+
+
+@dataclass(frozen=True)
+class PhysicsResult:
+    flagged_shots: List[PhysicsFlag] = field(default_factory=list)
+
+
+def score_physics(
+    shots: Sequence[PhysicsShotInput], multiplier: Optional[float] = None
+) -> PhysicsResult:
+    """End-to-end CG03 entry point: reads every shot's sampled raw frames
+    from disk, computes the diff sequence, and flags discontinuities."""
+    flagged_shots: List[PhysicsFlag] = []
+    active_multiplier = DISCONTINUITY_MULTIPLIER if multiplier is None else multiplier
+    for shot in shots:
+        if len(shot.frame_paths) < 2:
+            continue
+        frames = [read_raw_frame(frame_path) for frame_path in shot.frame_paths]
+        diffs = compute_diff_sequence(frames)
+        discontinuities = detect_discontinuities(diffs, active_multiplier)
+        for d in discontinuities:
+            flagged_shots.append(
+                PhysicsFlag(
+                    clip=shot.clip,
+                    frame_index_a=d.frame_index_a,
+                    frame_index_b=d.frame_index_b,
+                    discontinuity_ratio=round(d.ratio, 2) if d.ratio != float("inf") else -1,
+                    reason=build_physics_reason(d.ratio),
+                )
+            )
+    return PhysicsResult(flagged_shots=flagged_shots)
+
+
+# Re-exported so callers (CLI, tests) can reference the expected frame size
+# without importing from continuityguard.ingest directly.
+EXPECTED_FRAME_SIZE = FRAME_SIZE