splitsmith 0.2.0__py3-none-any.whl

splitsmith/__init__.py

@@ -0,0 +1,3 @@
+"""splitsmith: extract IPSC shot splits from head-mounted camera footage."""
+
+__version__ = "0.2.0"

splitsmith/audit.py

@@ -0,0 +1,87 @@
+"""Helpers for the hand-audit workflow.
+
+Audit flow:
+1. ``audit-prep`` (or the ad-hoc fixture script) emits ``<name>.wav``,
+   ``<name>.json`` (empty ``shots[]`` ground truth), and
+   ``<name>-candidates.csv`` with an ``audit_keep`` column.
+2. The user opens the CSV, marks rows they want to keep, saves.
+3. ``audit-apply`` reads the marked CSV and rewrites the JSON's ``shots[]``.
+
+This module exposes the read/merge primitives. The CLI wraps them.
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+from pathlib import Path
+
+# Anything in this set (case-insensitive, trimmed) marks a candidate as kept.
+_KEEP_TRUTHY: frozenset[str] = frozenset({"y", "yes", "1", "x", "true", "keep", "t"})
+
+
+def is_kept(value: str | None) -> bool:
+    if value is None:
+        return False
+    return value.strip().lower() in _KEEP_TRUTHY
+
+
+def read_kept_candidate_numbers(candidates_csv: Path) -> list[int]:
+    """Return the candidate_numbers from rows whose ``audit_keep`` cell is truthy.
+
+    Order is preserved from the CSV, which is the natural shot order.
+    """
+    with candidates_csv.open("r", newline="", encoding="utf-8") as f:
+        reader = csv.DictReader(f)
+        if reader.fieldnames is None or "audit_keep" not in reader.fieldnames:
+            raise ValueError(
+                f"{candidates_csv}: missing 'audit_keep' column. Expected the audit-prep "
+                f"format (audit_keep, candidate_number, ...). Got: {reader.fieldnames}"
+            )
+        if "candidate_number" not in reader.fieldnames:
+            raise ValueError(f"{candidates_csv}: missing 'candidate_number' column")
+        kept: list[int] = []
+        for row in reader:
+            if is_kept(row.get("audit_keep")):
+                kept.append(int(row["candidate_number"]))
+    return kept
+
+
+def apply_audit_to_fixture(candidates_csv: Path, fixture_json: Path) -> int:
+    """Merge marked-keep candidates into ``fixture_json``'s ``shots[]`` array.
+
+    Returns the number of shots written. The JSON is rewritten in place; the
+    ``_candidates_pending_audit`` block is preserved unchanged so the audit can
+    be re-run from the same source if the user changes their mind.
+    """
+    kept_numbers = read_kept_candidate_numbers(candidates_csv)
+    data = json.loads(fixture_json.read_text())
+
+    candidates = data.get("_candidates_pending_audit", {}).get("candidates")
+    if not candidates:
+        raise ValueError(
+            f"{fixture_json}: no candidates block found. Expected " f"'_candidates_pending_audit.candidates'."
+        )
+    by_num = {c["candidate_number"]: c for c in candidates}
+
+    missing = sorted(n for n in kept_numbers if n not in by_num)
+    if missing:
+        raise ValueError(
+            f"{candidates_csv}: candidate_number(s) marked keep but not present in "
+            f"{fixture_json}: {missing}"
+        )
+
+    shots: list[dict] = []
+    for kept_idx, cand_num in enumerate(kept_numbers, start=1):
+        c = by_num[cand_num]
+        shots.append(
+            {
+                "shot_number": kept_idx,
+                "candidate_number": cand_num,
+                "time": c["time"],
+                "ms_after_beep": c["ms_after_beep"],
+            }
+        )
+    data["shots"] = shots
+    fixture_json.write_text(json.dumps(data, indent=2) + "\n")
+    return len(shots)

splitsmith/automation.py

@@ -0,0 +1,238 @@
+"""Layered automation settings (issue #215).
+
+Splitsmith chains certain follow-up jobs automatically -- the canonical
+example is "user marks beep reviewed -> shot detection fires." Some
+users want the rich auto-pipeline; others (CLI / agent flows) want
+manual gates so they can decide each step. This module provides the
+layered settings stack that lets a global default, a project-level
+override, and a per-invocation CLI flag resolve cleanly into one
+effective set of toggles -- with provenance so the UI can show *why*
+a value is what it is.
+
+Resolution order, top wins: **CLI > project > global > field default**.
+
+The schema is one ``automation`` sub-object so siblings (for example
+``overlay_render_on_audit``, ``beep_detect_on_ingest``) can land later
+without re-shaping the on-disk format.
+
+Backed by ``pydantic-settings`` so the global layer composes cleanly
+with the rest of the codebase: YAML loading, env-var overrides
+(``SPLITSMITH_AUTOMATION_*``), and the standard pydantic validation
+story all come for free. The override types and the resolver are
+plain pydantic / dataclasses because they aren't loaded from any
+single source -- they're computed merges.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+from pydantic import BaseModel
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from . import user_config
+
+logger = logging.getLogger(__name__)
+
+
+# Field name in the YAML and on the project model. Centralised so a
+# rename touches one place.
+AUTOMATION_KEY = "automation"
+
+
+class AutomationSettings(BaseSettings):
+    """The effective set of automation toggles.
+
+    Default values are the *global fallback* applied when nothing
+    else weighs in. The same model is used as the resolved object
+    after layering -- both shapes are identical (every field has a
+    concrete value at the end), which keeps callers from juggling
+    two near-duplicate types.
+
+    Loaded from the user-config ``config.yaml`` (under the
+    ``automation`` block) and from ``SPLITSMITH_AUTOMATION_*`` env
+    vars; init args win over both.
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="SPLITSMITH_AUTOMATION_",
+        extra="ignore",
+        # We do the YAML load explicitly via :func:`load_global` so the
+        # settings_customise_sources hook stays simple and the test
+        # suite can construct AutomationSettings without a disk read.
+    )
+
+    shot_detect_on_beep_verified: bool = True
+    """When the user marks a beep reviewed, fire shot detection."""
+
+    beep_low_confidence_threshold: float = 0.95
+    """Minimum auto-detector confidence in [0, 1] required to auto-trust a beep.
+
+    Joins issue #219: an auto-detected beep with confidence at or above
+    this threshold pre-sets ``beep_reviewed=True`` (the user is offered
+    a one-click confirm but the chain doesn't wait), so shot detection
+    fires immediately. Below the threshold the beep lands in the HITL
+    queue and the user (or an agent driving the workflow) is asked to
+    pick the right candidate from the ranked list.
+
+    Manual entries always clamp confidence to 1.0 and bypass this gate.
+
+    History: the original default was 0.6, calibrated against the
+    labelled fixture set (~95% top-1 precision in the ``>= 0.7`` band).
+    Field use surfaced too many incorrectly-auto-trusted beeps on
+    recursive-scan ingests, so the default was raised to 0.95 pending
+    a re-calibration with more data.
+    """
+
+
+class AutomationOverride(BaseModel):
+    """Layer override -- ``None`` on a field means "inherit from below".
+
+    Used for the project-state and CLI-flag layers. Not loaded from
+    disk by pydantic-settings: project overrides ride on the project
+    JSON; CLI overrides come from typer.
+    """
+
+    shot_detect_on_beep_verified: bool | None = None
+    beep_low_confidence_threshold: float | None = None
+
+
+# Where each resolved field came from. The UI uses this for the
+# provenance badge (#216).
+ProvenanceSource = Literal["cli", "project", "global", "default"]
+
+
+@dataclass(frozen=True)
+class FieldProvenance:
+    """One resolved field's source + the layer values that fed in.
+
+    ``source`` is the layer that supplied the effective value.
+    ``cli_value`` / ``project_value`` are ``None`` when that layer
+    stayed silent. ``global_value`` is always present because the
+    global settings always have a default.
+
+    Field types are union-typed (``bool | float``) because the
+    automation block is now mixed (toggles + thresholds). The UI
+    provenance widget renders the values via JSON.stringify so the
+    union is invisible on the wire.
+    """
+
+    source: ProvenanceSource
+    cli_value: bool | float | None
+    project_value: bool | float | None
+    global_value: bool | float
+
+
+@dataclass(frozen=True)
+class ResolvedAutomation:
+    """Resolved settings + per-field provenance."""
+
+    settings: AutomationSettings
+    provenance: dict[str, FieldProvenance]
+
+
+def _yaml_block(path: Path) -> dict[str, Any]:
+    """Read the ``automation`` block from ``path``. Empty dict on
+    missing file / parse error / missing block -- callers fall back
+    to the field defaults."""
+    if not path.exists():
+        return {}
+    try:
+        with path.open("r", encoding="utf-8") as f:
+            data = yaml.safe_load(f) or {}
+    except (OSError, yaml.YAMLError) as exc:
+        logger.warning("Ignoring unreadable automation block at %s: %s", path, exc)
+        return {}
+    block = data.get(AUTOMATION_KEY) if isinstance(data, dict) else None
+    if not isinstance(block, dict):
+        return {}
+    return block
+
+
+def load_global(config_path: Path | None = None) -> AutomationSettings:
+    """Load the global automation settings.
+
+    ``config_path`` defaults to the user-config ``config.yaml``; pass
+    an explicit path in tests. Env-var overrides
+    (``SPLITSMITH_AUTOMATION_*``) layer on top of the YAML and below
+    init args, mirroring pydantic-settings' standard precedence.
+    """
+    if user_config.is_disabled() and config_path is None:
+        return AutomationSettings()
+    path = config_path or (user_config.user_config_dir() / user_config.CONFIG_FILENAME)
+    block = _yaml_block(path)
+    try:
+        # Pass the YAML block as init kwargs; pydantic-settings will
+        # still let env vars override missing keys.
+        return AutomationSettings(**block)
+    except Exception as exc:  # noqa: BLE001 -- log then fall back so a malformed config doesn't break the app
+        logger.warning("Discarding malformed automation block at %s: %s", path, exc)
+        return AutomationSettings()
+
+
+def resolve_automation(
+    *,
+    global_settings: AutomationSettings | None = None,
+    project_override: AutomationOverride | None = None,
+    cli_override: AutomationOverride | None = None,
+) -> ResolvedAutomation:
+    """Layer the three sources into one resolved set of toggles.
+
+    Resolution per field, top wins:
+
+    1. CLI override (init args from typer flags).
+    2. Project override (``MatchProject.automation``).
+    3. Global setting (loaded from ``config.yaml`` + env vars).
+    4. Field default on :class:`AutomationSettings` (only reached
+       when ``global_settings`` is None and the field isn't set
+       anywhere).
+
+    Returns a :class:`ResolvedAutomation` carrying the effective
+    settings and per-field provenance for the UI.
+    """
+    if global_settings is None:
+        global_settings = load_global()
+
+    resolved_kwargs: dict[str, Any] = {}
+    provenance: dict[str, FieldProvenance] = {}
+    for field_name in AutomationSettings.model_fields:
+        cli_val = getattr(cli_override, field_name) if cli_override is not None else None
+        proj_val = getattr(project_override, field_name) if project_override is not None else None
+        global_val = getattr(global_settings, field_name)
+        if cli_val is not None:
+            effective = cli_val
+            source: ProvenanceSource = "cli"
+        elif proj_val is not None:
+            effective = proj_val
+            source = "project"
+        else:
+            effective = global_val
+            source = "global"
+        resolved_kwargs[field_name] = effective
+        provenance[field_name] = FieldProvenance(
+            source=source,
+            cli_value=cli_val,
+            project_value=proj_val,
+            global_value=global_val,
+        )
+
+    return ResolvedAutomation(
+        settings=AutomationSettings(**resolved_kwargs),
+        provenance=provenance,
+    )
+
+
+__all__ = [
+    "AUTOMATION_KEY",
+    "AutomationOverride",
+    "AutomationSettings",
+    "FieldProvenance",
+    "ProvenanceSource",
+    "ResolvedAutomation",
+    "load_global",
+    "resolve_automation",
+]

splitsmith/backup.py

@@ -0,0 +1,298 @@
+"""Project export/import.
+
+Tars the non-regeneratable parts of a :class:`MatchProject` into a single
+``.tar.gz`` so a project can be moved between machines or stashed as a
+disaster-recovery copy.
+
+Inclusion policy:
+
+* Always: ``project.json``.
+* Default: ``audit/`` (hand-labeled shot corrections) and ``scoreboard/``
+  (cached SSI data). Together these are the only artefacts that are
+  *truly* irreplaceable.
+* Optional via flags: ``trimmed/``, ``exports/``, ``raw/``, ``audio/`` -- all
+  regeneratable from the raw footage, so the user opts in when they
+  actually need them in the archive.
+* Never: ``probes/`` and ``thumbs/`` -- pure caches, trivially regenerated.
+
+Subdirectories whose path resolves outside the project root (via the absolute
+override fields on :class:`MatchProject`) are skipped: the archive intentionally
+only captures project-local data, so an import on a different machine has a
+chance of working.
+
+The archive contains a single top-level directory whose name matches the
+project directory's name, plus a ``BACKUP_MANIFEST.json`` describing what was
+included and which splitsmith version produced the archive.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import shutil
+import tarfile
+import tempfile
+from collections.abc import Iterable
+from datetime import UTC, datetime
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from . import __version__
+from .ui.project import PROJECT_FILE, MatchProject
+
+DEFAULT_DIRS: tuple[str, ...] = ("audit", "scoreboard")
+OPTIONAL_DIRS: frozenset[str] = frozenset({"raw", "audio", "trimmed", "exports"})
+NEVER_DIRS: frozenset[str] = frozenset({"probes", "thumbs"})
+
+MANIFEST_NAME = "BACKUP_MANIFEST.json"
+
+
+class SkippedDir(BaseModel):
+    name: str
+    reason: str
+    resolved_path: str | None = None
+
+
+class ExportResult(BaseModel):
+    archive_path: Path
+    bytes_written: int
+    included: list[str]
+    skipped: list[SkippedDir]
+
+
+class ImportResult(BaseModel):
+    project_root: Path
+    project_name: str
+    manifest: dict[str, object] | None = Field(default=None)
+
+
+class BackupError(Exception):
+    """Raised when an export or import cannot proceed."""
+
+
+def _resolve_subdir(project: MatchProject, root: Path, name: str) -> Path:
+    """Resolve ``name`` against ``root`` using the project's override fields."""
+    if name == "raw":
+        return project.raw_path(root)
+    if name == "audio":
+        return project.audio_path(root)
+    if name == "trimmed":
+        return project.trimmed_path(root)
+    if name == "exports":
+        return project.exports_path(root)
+    if name == "audit":
+        return project.audit_path(root)
+    # No override field for scoreboard; always project-local.
+    return root / name
+
+
+def export_project(
+    project_root: Path,
+    output: Path,
+    *,
+    include_trimmed: bool = False,
+    include_exports: bool = False,
+    include_raw: bool = False,
+    include_audio: bool = False,
+) -> ExportResult:
+    """Write a ``.tar.gz`` archive of ``project_root`` to ``output``.
+
+    ``output`` may be a directory (the archive filename is derived from the
+    project name + today's date) or a file path. Returns an :class:`ExportResult`
+    describing what was included and which subdirectories were skipped.
+    """
+    project_root = project_root.expanduser().resolve()
+    if not (project_root / PROJECT_FILE).exists():
+        raise BackupError(f"no {PROJECT_FILE} in {project_root}")
+    project = MatchProject.load(project_root)
+
+    output = output.expanduser()
+    if output.is_dir():
+        stamp = datetime.now(UTC).strftime("%Y%m%d")
+        slug = _slug(project.name) or project_root.name
+        output = output / f"{slug}-backup-{stamp}.tar.gz"
+    output.parent.mkdir(parents=True, exist_ok=True)
+
+    wanted = list(DEFAULT_DIRS)
+    if include_trimmed:
+        wanted.append("trimmed")
+    if include_exports:
+        wanted.append("exports")
+    if include_raw:
+        wanted.append("raw")
+    if include_audio:
+        wanted.append("audio")
+
+    arc_root = project_root.name  # top-level dir inside the archive
+    included: list[str] = []
+    skipped: list[SkippedDir] = []
+
+    with tarfile.open(output, "w:gz") as tf:
+        tf.add(project_root / PROJECT_FILE, arcname=f"{arc_root}/{PROJECT_FILE}")
+        for name in wanted:
+            src = _resolve_subdir(project, project_root, name)
+            try:
+                src_resolved = src.resolve()
+            except OSError:
+                skipped.append(SkippedDir(name=name, reason="missing"))
+                continue
+            if not src_resolved.exists():
+                skipped.append(SkippedDir(name=name, reason="missing", resolved_path=str(src_resolved)))
+                continue
+            if not _is_inside(src_resolved, project_root):
+                skipped.append(
+                    SkippedDir(
+                        name=name,
+                        reason="outside_project_root",
+                        resolved_path=str(src_resolved),
+                    )
+                )
+                continue
+            tf.add(src_resolved, arcname=f"{arc_root}/{name}")
+            included.append(name)
+
+        manifest = {
+            "splitsmith_version": __version__,
+            "created_at": datetime.now(UTC).isoformat(),
+            "project_name": project.name,
+            "project_root_name": project_root.name,
+            "included": ["project.json", *included],
+            "skipped": [s.model_dump() for s in skipped],
+            "options": {
+                "include_trimmed": include_trimmed,
+                "include_exports": include_exports,
+                "include_raw": include_raw,
+                "include_audio": include_audio,
+            },
+        }
+        _add_bytes(tf, f"{arc_root}/{MANIFEST_NAME}", json.dumps(manifest, indent=2).encode())
+
+    size = output.stat().st_size
+    return ExportResult(
+        archive_path=output,
+        bytes_written=size,
+        included=["project.json", *included],
+        skipped=skipped,
+    )
+
+
+def import_project(
+    archive: Path,
+    dest_root: Path,
+    *,
+    overwrite: bool = False,
+) -> ImportResult:
+    """Extract ``archive`` into ``dest_root``.
+
+    The archive must contain exactly one top-level directory holding a
+    ``project.json``. Returns an :class:`ImportResult` pointing at the new
+    project root.
+    """
+    archive = archive.expanduser().resolve()
+    dest_root = dest_root.expanduser().resolve()
+    if not archive.exists():
+        raise BackupError(f"archive not found: {archive}")
+    dest_root.mkdir(parents=True, exist_ok=True)
+
+    with tempfile.TemporaryDirectory(prefix="splitsmith-import-") as staging_str:
+        staging = Path(staging_str)
+        with tarfile.open(archive, "r:*") as tf:
+            _safe_extract(tf, staging)
+
+        top = _single_top_dir(staging)
+        if top is None:
+            raise BackupError("archive must contain exactly one top-level directory")
+        if not (top / PROJECT_FILE).exists():
+            raise BackupError(f"archive is missing {PROJECT_FILE}")
+
+        # Validate project.json parses before we move anything.
+        try:
+            MatchProject.load(top)
+        except Exception as exc:  # noqa: BLE001 - surface the underlying failure
+            raise BackupError(f"invalid project.json in archive: {exc}") from exc
+
+        manifest: dict[str, object] | None = None
+        manifest_path = top / MANIFEST_NAME
+        if manifest_path.exists():
+            try:
+                manifest = json.loads(manifest_path.read_text())
+            except json.JSONDecodeError:
+                manifest = None
+
+        target = dest_root / top.name
+        if target.exists():
+            if not overwrite:
+                raise BackupError(f"destination already exists: {target}")
+            shutil.rmtree(target)
+        shutil.move(str(top), str(target))
+
+    project = MatchProject.load(target)
+    return ImportResult(project_root=target, project_name=project.name, manifest=manifest)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _is_inside(child: Path, parent: Path) -> bool:
+    try:
+        child.relative_to(parent)
+        return True
+    except ValueError:
+        return False
+
+
+def _add_bytes(tf: tarfile.TarFile, arcname: str, data: bytes) -> None:
+    info = tarfile.TarInfo(name=arcname)
+    info.size = len(data)
+    info.mtime = int(datetime.now(UTC).timestamp())
+    tf.addfile(info, io.BytesIO(data))
+
+
+def _safe_extract(tf: tarfile.TarFile, dest: Path) -> None:
+    """Extract guarding against path-traversal entries."""
+    dest_resolved = dest.resolve()
+    members: list[tarfile.TarInfo] = []
+    for m in tf.getmembers():
+        target = (dest_resolved / m.name).resolve()
+        if not _is_inside(target, dest_resolved):
+            raise BackupError(f"archive contains unsafe path: {m.name!r}")
+        # Block symlinks/hardlinks pointing outside the staging dir.
+        if m.issym() or m.islnk():
+            link_target = (dest_resolved / m.name).parent / (m.linkname or "")
+            try:
+                link_resolved = link_target.resolve()
+            except OSError as exc:
+                raise BackupError(f"unsafe link in archive: {m.name!r}") from exc
+            if not _is_inside(link_resolved, dest_resolved):
+                raise BackupError(f"unsafe link in archive: {m.name!r}")
+        members.append(m)
+    tf.extractall(dest_resolved, members=members)
+
+
+def _single_top_dir(staging: Path) -> Path | None:
+    entries = [p for p in staging.iterdir() if not p.name.startswith(".")]
+    if len(entries) != 1 or not entries[0].is_dir():
+        return None
+    return entries[0]
+
+
+def _slug(name: str) -> str:
+    out = "".join(c if c.isalnum() or c in "-_" else "-" for c in name.strip())
+    return out.strip("-").lower()
+
+
+__all__: Iterable[str] = (
+    "BackupError",
+    "ExportResult",
+    "ImportResult",
+    "SkippedDir",
+    "DEFAULT_DIRS",
+    "OPTIONAL_DIRS",
+    "NEVER_DIRS",
+    "MANIFEST_NAME",
+    "export_project",
+    "import_project",
+)