From c9ac2fbe7036f8d09c7e1a4adb68df0fe78bf9bb Mon Sep 17 00:00:00 2001
From: Caspar Addyman <infantologist@gmail.com>
Date: Sat, 18 Jul 2026 23:06:06 +0000
Subject: [PATCH 01/10] spec: add extras-based modular install spec (v1.5.0
 Phase 1)

Concrete, implementation-ready slice of spec 003 covering the part of
v1.5.0 that hasn't been started: moving heavy ML deps to
optional-dependencies groups, metadata-driven registry loading
(requires_extras), killing LEGACY_MAPPINGS, migration messaging, and
the NumPy 2 bump. Adds explicit forward-compatibility requirements
(FR-010..FR-012, SC-007) so this phase's schema choices don't have to
be redone when v1.6.0 adds Ollama or v1.7+ adds remote/HPC dispatch.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../checklists/requirements.md                |  64 +++++
 specs/004-extras-based-install/spec.md        | 249 ++++++++++++++++++
 2 files changed, 313 insertions(+)
 create mode 100644 specs/004-extras-based-install/checklists/requirements.md
 create mode 100644 specs/004-extras-based-install/spec.md

diff --git a/specs/004-extras-based-install/checklists/requirements.md b/specs/004-extras-based-install/checklists/requirements.md
new file mode 100644
index 0000000..62ce63f
--- /dev/null
+++ b/specs/004-extras-based-install/checklists/requirements.md
@@ -0,0 +1,64 @@
+# Specification Quality Checklist: Extras-Based Modular Install & Registry Refactor
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-07-18
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs) beyond what users see in install
+      commands and the one existing field name (`backends`) needed to describe forward-compatibility
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders (with a technical grounding section for maintainers,
+      since this spec explicitly narrows an existing architecture spec into a buildable unit)
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (SC-007 is the one exception, deliberately: it is a
+      design-review gate, not a runtime-measurable outcome, because "does this schema block the next
+      release" cannot be tested any other way at this phase)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded (explicitly excludes Ollama/HTTP/Slurm/plugin-discovery
+      *implementation*, which remain v1.6.0/v1.7.0+ per the roadmap docs)
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification beyond the current codebase facts needed to
+      scope the work accurately (file/field names that already exist today)
+
+## Validation Notes
+
+This spec is a **narrower, implementation-ready slice** of
+[`specs/003-modular-pipeline-architecture/spec.md`](../../003-modular-pipeline-architecture/spec.md),
+not a replacement. Spec 003 remains the source of truth for the full architecture (plugin discovery,
+dispatcher ABC, cross-cutting utils split) — those stay out of scope here and are tracked in
+`docs/development/roadmap_v1.6.0.md` and `roadmap_v1.7_to_v2.0.md`.
+
+One deliberate addition beyond spec 003's own scope: **User Story 3 and FR-010 through FR-012** are
+new requirements not present in spec 003, added because the user explicitly flagged that this
+modularity work exists *in order to* support Ollama, HPC offload, and remote/cloud offload in
+upcoming releases — not modularity for its own sake. These requirements make that intent testable
+now (SC-007) rather than leaving it as an unstated assumption to be discovered as a problem in
+v1.6.0 or v1.7.0 planning.
+
+**Risk surfaced, not resolved here**: the "secure" half of "remote (secure) cloud services" has no
+concrete requirements in this spec because there is no remote dispatch yet to secure — see the
+Assumptions section's note on transport security / credential handling. This should become an
+explicit, first-class requirement when the v1.7.0 HTTPDispatcher/RemotePipelineProxy spec is
+written, not an afterthought.
+
+## Notes
+
+- All checklist items pass on first iteration.
+- Spec is ready for `/speckit-plan`. No feature branch has been created yet — this was written
+  directly to `specs/` per the maintainer's request, ahead of running the speckit branch-creation
+  flow.
diff --git a/specs/004-extras-based-install/spec.md b/specs/004-extras-based-install/spec.md
new file mode 100644
index 0000000..80da60e
--- /dev/null
+++ b/specs/004-extras-based-install/spec.md
@@ -0,0 +1,249 @@
+# Feature Specification: Extras-Based Modular Install & Registry Refactor (v1.5.0 Phase 1)
+
+**Feature Branch**: `004-extras-based-install`
+**Created**: 2026-07-18
+**Status**: Draft
+**Input**: User description: "Now that the JOSS resubmission is in review, resume the v1.5.0 modularity work. Implement the extras-based install and metadata-driven registry loading that Phase 1 of the v1.5.0 roadmap scopes (moving heavy ML deps to per-pipeline optional-dependencies groups, replacing LEGACY_MAPPINGS with metadata-driven module loading, registry graceful-degradation, migration messaging, dropping the numpy<2.0 pin). The resulting extras/metadata design must not foreclose the already-roadmapped follow-on work: v1.6.0's Ollama/llama.cpp local-LLM pipeline backend, and v1.7-v2.0's HTTPDispatcher, SlurmDispatcher/HPC dispatch, and secure remote/cloud pipeline execution — this modularity effort exists specifically to make local Ollama models, HPC offload, and remote/cloud offload possible in later releases without re-architecting the registry or install system again."
+
+## Relationship to Existing Specs
+
+This is the **implementation-ready Phase 1 slice** of the architecture already specified in
+[`specs/003-modular-pipeline-architecture/spec.md`](../003-modular-pipeline-architecture/spec.md)
+("spec 003"). Spec 003 covers the full modular-architecture vision, including plugin discovery,
+the dispatcher abstraction, and the cross-cutting-utilities split, and explicitly defers
+remote/HPC/VLM *implementation* to v1.7+ (see spec 003's Assumptions section) while requiring
+(FR-008) that job dispatch be abstracted so those targets can be added later without touching
+pipeline code. This spec does not re-derive that architecture; it narrows spec 003's User Stories
+1 and 2 (FR-001–FR-005, FR-009, FR-011, FR-014, FR-015) into a concrete, buildable unit of work —
+what [`docs/development/roadmap_v1.5.0.md`](../../docs/development/roadmap_v1.5.0.md) calls
+"Phase 1: Extras-Based Install" — and adds one new requirement category: forward-compatibility
+guarantees that this phase's schema choices must satisfy, so that v1.6.0 (Ollama), v1.7.0
+(HTTPDispatcher, remote pipelines), and v1.8.0 (SlurmDispatcher/HPC) can build directly on it.
+
+**Why this phase, now**: as of this spec's creation, no part of Phase 1 has been implemented —
+all runtime ML dependencies remain in `[project.dependencies]` (unconditional), the registry
+still resolves module paths through the hardcoded `LEGACY_MAPPINGS` dict in
+`src/videoannotator/registry/pipeline_loader.py`, and `numpy<2.0` is still pinned in
+`pyproject.toml`. Phase 2 of v1.5.0 (bundling Video Annotation Viewer at `/viewer`) already
+shipped in v1.4.4. This spec covers the remaining, unstarted half of the v1.5.0 release.
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Slim, targeted install for a single research need (Priority: P1)
+
+A researcher who only needs scene labelling on their lecture-recording corpus installs the
+toolkit with just the scene-labelling pipeline. They do not download multi-gigabyte models or
+libraries unrelated to their work.
+
+**Why this priority**: Directly answers the JOSS pre-review's flagged blocker (~30 GB Docker
+image, every pipeline's dependencies mandatory). This is the single most-cited adoption barrier.
+
+**Independent Test**: `pip install videoannotator[scene]` on a clean environment; run scene
+labelling on a sample video; confirm the install pulled no audio/face/person-tracking deps and
+produced correct output.
+
+**Acceptance Scenarios**:
+
+1. **Given** a clean Python environment, **When** the user installs with only the `scene` extra,
+   **Then** the install completes without downloading torch-dependent audio/face/person packages,
+   and scene labelling runs successfully.
+2. **Given** the toolkit installed with only `scene`, **When** the user lists available pipelines
+   (CLI or `GET /api/v1/pipelines`), **Then** only scene-labelling pipelines appear as available;
+   others are omitted, not erroring.
+3. **Given** the toolkit installed with only `scene`, **When** the user requests a face-emotion
+   pipeline, **Then** they get an actionable message with the exact `pip install
+   videoannotator[face]` command, never a Python traceback.
+4. **Given** an install with `scene` only, **When** the user runs `pip install
+   videoannotator[face]` afterward, **Then** both families work; nothing about the existing
+   install needs to be reinstalled or reset.
+
+---
+
+### User Story 2 - Backward-compatible upgrade for existing studies (Priority: P1)
+
+A researcher mid-study on v1.4.4 upgrades to v1.5.0 using `pip install videoannotator[all]` and
+keeps running their existing configuration files and scripts unchanged.
+
+**Why this priority**: Studies run for months; breaking a running analysis mid-study violates
+Constitution Principle V (Backward Compatibility by Default). Without this, the modularity work
+is a hostile change, not a foundation.
+
+**Independent Test**: Run the v1.4.4 acceptance-test fixtures against a v1.5.0 `[all]` install;
+outputs match v1.4.4 within documented tolerance; no config file needs editing.
+
+**Acceptance Scenarios**:
+
+1. **Given** an existing v1.4.4 config file and video corpus, **When** upgraded to v1.5.0 `[all]`,
+   **Then** the same CLI invocations produce equivalent annotations with zero modifications.
+2. **Given** a v1.4.4 config that references LAION (now excluded from the default `face`/`audio`
+   extras), **When** run unchanged against v1.5.0, **Then** the user gets a clear migration
+   message naming the extras group to add, not a silent failure or raw ImportError.
+3. **Given** a v1.4.4 model cache on disk, **When** v1.5.0 runs the same pipeline, **Then** it
+   reuses the cache rather than re-downloading.
+
+---
+
+### User Story 3 - Metadata schema has room for non-local execution (Priority: P2)
+
+A maintainer implementing next release's Ollama backend (v1.6.0) or a later release's remote/HPC
+dispatch (v1.7.0+) needs to add a pipeline whose actual compute doesn't happen via a local Python
+import at all — it happens by calling a local `ollama serve` process, an HTTP endpoint, or a Slurm
+job. This spec's registry/metadata changes must accommodate that without another breaking schema
+migration.
+
+**Why this priority**: This is the explicit reason modularity is being prioritized right now
+(ahead of other JOSS-response work): the extras/registry refactor exists to unblock Ollama,
+HPC-offload, and secure remote/cloud execution in the releases immediately following this one. If
+Phase 1's schema has to be redesigned again in v1.6.0 to fit Ollama, or again in v1.7.0 to fit
+HTTP/Slurm dispatch, this phase has failed its actual purpose even if User Stories 1 and 2 pass.
+P2 (not P1) because no non-local backend ships in *this* release — only the room for one.
+
+**Independent Test**: Author a throwaway pipeline metadata YAML entry that declares
+`requires_extras: []` (no local ML dependency) and a `module_path` pointing at a stub class that
+raises `NotImplementedError` in `process()`. Confirm the registry loads it, lists it as available
+with no extras required, and that nothing in the extras/dependency system assumes every pipeline
+must ship a heavy local dependency. This proves the schema doesn't hard-code "every pipeline has a
+local ML extra" as an assumption.
+
+**Acceptance Scenarios**:
+
+1. **Given** a pipeline metadata YAML with `requires_extras: []` and a `backends` entry naming a
+   non-Python-import execution target (e.g. `ollama`, `http`), **When** the registry loads
+   metadata, **Then** it loads successfully without requiring changes to the registry loader code.
+2. **Given** the Phase 1 extras-group naming scheme, **When** a future release adds an `llm` extras
+   group (v1.6.0, for an HTTP client only — no torch/transformers) or reserves names for HPC/remote
+   dispatch configuration, **Then** the naming scheme already documented by this phase has room for
+   those groups without colliding with or renaming existing groups (`face`, `audio`, `scene`,
+   `person`, `embedding`, `all`).
+3. **Given** the `PipelineMetadata` dataclass extended by this phase (`requires_extras` field
+   added), **When** a later release adds fields for backend connection details (base URL, auth
+   reference, dispatch target), **Then** those are additive optional fields, not modifications to
+   fields this phase introduces.
+
+---
+
+### Edge Cases
+
+- A user requests a pipeline whose extras are not installed: MUST get an actionable install
+  command, never a Python import traceback surfaced to the CLI/API caller.
+- A v1.4.4 config references a pipeline demoted from the default install (LAION): MUST be detected
+  and produce a migration message, not a first-import crash mid-batch-job.
+- Two installed extras groups pin different versions of the same underlying library: MUST resolve
+  at install time or surface the conflict at install time, not at runtime.
+- A third-party or future-reserved extras-group name collides with an official group: registry MUST
+  detect the collision deterministically (full plugin *discovery* is v1.6.0 scope per spec 003 —
+  this phase only needs the naming scheme to not preclude that check later).
+- A model cache from v1.4.4 exists on disk: v1.5.0 MUST reuse it, not force re-download.
+- The environment uses NumPy 2.x: full pipeline suite MUST pass without a downgrade.
+- A pipeline's `requires_extras` is empty (no local ML dependency, e.g. a future Ollama/HTTP-backed
+  pipeline) but its extras group is still meaningful for a lightweight client dependency (e.g.
+  `httpx`): the schema MUST distinguish "no extras needed" from "a small non-ML extra is needed" —
+  both are valid and different from "heavy ML extra needed."
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: Heavy ML dependencies (torch, torchvision, torchaudio, ultralytics, pyannote.*,
+  transformers, sentence-transformers, open-clip-torch, openai-whisper, timm) MUST move from
+  `[project.dependencies]` to named `[project.optional-dependencies]` groups: `face`, `audio`,
+  `scene`, `person`, `embedding`. `pip install videoannotator` with no extras MUST NOT pull any of
+  them in.
+- **FR-002**: LAION Empathic-Insight (face and voice) MUST have its own extras group(s), separate
+  from the base `face`/`audio` groups, so standard face/audio pipelines don't pull LAION's stack.
+- **FR-003**: An `all` meta-extra MUST exist that reproduces v1.4.4's install footprint exactly.
+- **FR-004**: `PipelineMetadata` MUST gain a `requires_extras: list[str]` field (additive; existing
+  fields, including `backends` which already exists, are untouched). The registry's `pipeline_loader.py`
+  MUST resolve `module_path` from this metadata-driven field instead of the hardcoded
+  `LEGACY_MAPPINGS` dict, which MUST be removed once every pipeline YAML carries `module_path`.
+- **FR-005**: When a pipeline's `requires_extras` are not installed, the registry MUST omit it from
+  listings (CLI, `GET /api/v1/pipelines`) rather than raising ImportError during registry load; any
+  user-facing surface that names an unavailable pipeline MUST include the exact
+  `pip install videoannotator[<group>]` command.
+- **FR-006**: A v1.4.x config file that references a pipeline now outside the default install
+  (e.g. LAION) MUST produce a specific, actionable migration message identifying the missing
+  extras group, distinguishable from a generic "pipeline not found" error.
+- **FR-007**: The `numpy<2.0` pin (`pyproject.toml`, currently line 43) MUST be dropped once the
+  full pipeline suite is verified against NumPy 2.x; CI MUST run the suite on NumPy 2.x before this
+  requirement is considered met.
+- **FR-008**: `Dockerfile.cpu`/`Dockerfile.gpu` base images MUST build with no extras (slim); an
+  `[all]`-equivalent image MUST remain available and documented separately.
+- **FR-009**: Output artifacts produced by v1.5.0 `[all]` MUST match v1.4.4 byte-for-byte for
+  deterministic pipelines, and within documented numerical tolerance for non-deterministic ones.
+- **FR-010 (forward-compatibility)**: The extras-group naming scheme introduced by this phase
+  (`face`, `audio`, `scene`, `person`, `embedding`, `all`, plus LAION's group(s)) MUST be documented
+  as a reserved namespace with room left for names known to be needed next: an `llm` group
+  (v1.6.0 Ollama/llama.cpp client, no ML weights) and names for remote/HPC dispatch configuration
+  (v1.7.0+). This phase does not create those groups — it must not choose names or a registry
+  design that blocks creating them later without renaming existing ones.
+- **FR-011 (forward-compatibility)**: `requires_extras: []` (empty list) MUST be a valid, supported
+  state in the metadata schema, representing a pipeline with no local heavy-ML dependency — the
+  shape a future Ollama-backed or HTTP-remote pipeline will use. The registry and pipeline loader
+  MUST NOT assume every pipeline entry has a non-empty `requires_extras`.
+- **FR-012 (forward-compatibility)**: This phase's registry/metadata changes MUST NOT require the
+  job-execution paths (`api/job_processor.py`, `batch/batch_orchestrator.py`) to change how they
+  invoke a pipeline based on which extras group it belongs to — invocation MUST stay
+  extras-agnostic, so that a future Dispatcher abstraction (spec 003 FR-008, planned v1.6.0+) can
+  be introduced without this phase's work needing rework.
+
+### Key Entities
+
+- **Extras group**: A named, documented, pip-installable dependency bundle. Reserved at the project
+  level. This phase defines the ML-pipeline groups; the namespace is designed to also hold the
+  `llm` group (v1.6.0) and remote/HPC-related groups (v1.7.0+) without collision.
+- **Pipeline metadata record**: Per-pipeline YAML under `src/videoannotator/registry/metadata/`.
+  This phase adds `requires_extras`; the existing `backends` field (already present, e.g.
+  `tensorflow`, `opencv` today) is the same field later releases extend with non-local values
+  (`ollama`, `http`).
+- **Migration message**: User-facing text mapping "pipeline referenced in config but unavailable"
+  to the specific extras-install command or, for demoted pipelines (LAION), an explicit note that
+  it moved out of the default install.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: `pip install videoannotator[scene]` (or any single-family extra) completes and runs
+  that family's pipeline on a sample video in under 5 minutes on a representative laptop with
+  broadband, without downloading unrelated families' dependencies.
+- **SC-002**: Default (no-extras) Docker image footprint is reduced by ≥ 80% vs. the v1.4.4
+  baseline.
+- **SC-003**: 100% of v1.4.4 acceptance-test fixtures pass against v1.5.0 `[all]` with zero
+  modification to configs, CLI invocations, or downstream analysis code.
+- **SC-004**: 100% of pipelines available in v1.4.4 remain installable in v1.5.0 (bundled in `[all]`
+  or as a documented extra) — no functionality lost.
+- **SC-005**: When a user requests an unavailable pipeline, the error message includes the exact
+  pip install command in 100% of cases (measured by test fixtures covering every pipeline family).
+- **SC-006**: Full automated test suite passes on NumPy 2.x on Linux, macOS, and Windows.
+- **SC-007 (forward-compatibility gate)**: A design review — before this phase is marked done —
+  confirms that adding the v1.6.0 Ollama/llama.cpp `llm` extras group and pipeline entries requires
+  zero changes to the `PipelineMetadata` schema, the registry loader, or the extras-naming scheme
+  introduced here (only additive YAML entries and a new `[project.optional-dependencies]` group).
+  This is the concrete test of "modularity supports Ollama/HPC/remote-cloud going forward."
+
+## Assumptions
+
+- v1.4.4 is the baseline for behaviour-parity and reproducibility comparisons (superseding v1.4.2,
+  which spec 003's original text used as its baseline before v1.4.3/v1.4.4 shipped).
+- This phase does **not** implement the Ollama/llama.cpp backend, HTTPDispatcher, SlurmDispatcher,
+  RemotePipelineProxy, entry-point third-party plugin discovery, or the `videoannotator-utils`
+  package split. Those remain scheduled in
+  [`docs/development/roadmap_v1.6.0.md`](../../docs/development/roadmap_v1.6.0.md) (plugin ecosystem
+  + Ollama/llama.cpp local backend) and the v1.7.0–v2.0 arc (remote pipelines, HTTPDispatcher, VLM
+  plugin, SlurmDispatcher/HPC, slim core) — see
+  [`docs/development/roadmap_v1.7_to_v2.0.md`](../../docs/development/roadmap_v1.7_to_v2.0.md).
+  This phase's job is narrower and concrete: make sure nothing built now has to be undone to reach
+  those.
+- **Security of remote/cloud dispatch** (the "secure" in "remote (secure) cloud services") is out
+  of scope for this phase — there is no remote dispatch yet to secure. It is flagged here as a
+  requirement that MUST be treated as first-class (not bolted on) when the v1.7.0 HTTPDispatcher /
+  RemotePipelineProxy design begins: authentication, transport encryption, and credential handling
+  for any pipeline that sends video/frame data off the local machine. The current v1.7–v2.0 roadmap
+  draft mentions an `auth` config field on `RemotePipelineProxy` but does not yet specify a
+  transport-security or secrets-handling model; that gap should be closed in the v1.7.0 spec, not
+  deferred silently.
+- The Ultralytics AGPL-3.0 licence isolation (person-tracking as its own plugin) remains deferred to
+  v2.0 per spec 003; person-tracking stays a top-level `person` extras group in this phase.
+- The model swaps in the v1.5.0 roadmap (faster-whisper, SigLIP-2, pyannote community-1, YOLO12,
+  face-stack consolidation) are tracked separately and are not required by this spec's acceptance
+  criteria, though they may land in the same release.

From 904d487aa1a7603e612bf887da44d31e35490ef1 Mon Sep 17 00:00:00 2001
From: Caspar Addyman <infantologist@gmail.com>
Date: Sat, 18 Jul 2026 23:33:06 +0000
Subject: [PATCH 02/10] plan: add implementation plan for extras-based modular
 install
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 0 (research.md) traced actual per-pipeline imports rather than
trusting the informal requirements.packages YAML field, and found the
extras taxonomy needs adjusting from spec/roadmap assumptions: no
pipeline declares pipeline_family: embedding (openface3 embedding is
a face variant), and scene/person both pull torch transitively via
open-clip/ultralytics, so they're not as slim as face's DeepFace
variant. Settled on face/face-laion/face-openface3/audio/audio-laion/
scene/person/all as the extras groups, with the llm group name
reserved but not created (v1.6.0).

Phase 1 (data-model.md, contracts/, quickstart.md) specifies the
additive requires_extras field on PipelineMetadata, the
pipeline-metadata YAML schema delta, and the unavailable-pipeline
error contract (CLI/API), each cross-checked against the ratified
constitution's Plan Gating checklist (Constitution Check: no
violations).

Also creates CLAUDE.md (the repo had none) via
update-agent-context.sh, then hand-fixed the auto-generated content —
the simple field parser truncated the Technical Context strings and
left template placeholders unresolved.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 CLAUDE.md                                     |  54 ++++++++
 .../contracts/pipeline-metadata-schema.md     |  45 +++++++
 .../contracts/unavailable-pipeline-error.md   |  47 +++++++
 specs/004-extras-based-install/data-model.md  |  52 ++++++++
 specs/004-extras-based-install/plan.md        | 117 ++++++++++++++++++
 specs/004-extras-based-install/quickstart.md  |  53 ++++++++
 specs/004-extras-based-install/research.md    | 107 ++++++++++++++++
 7 files changed, 475 insertions(+)
 create mode 100644 CLAUDE.md
 create mode 100644 specs/004-extras-based-install/contracts/pipeline-metadata-schema.md
 create mode 100644 specs/004-extras-based-install/contracts/unavailable-pipeline-error.md
 create mode 100644 specs/004-extras-based-install/data-model.md
 create mode 100644 specs/004-extras-based-install/plan.md
 create mode 100644 specs/004-extras-based-install/quickstart.md
 create mode 100644 specs/004-extras-based-install/research.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..8749bf6
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,54 @@
+# VideoAnnotator Development Guidelines
+
+Auto-generated from feature plans by `.specify/scripts/bash/update-agent-context.sh`. Last updated: 2026-07-18
+
+## Active Technologies
+- Python 3.12 (`requires-python = ">=3.12,<3.13"`), FastAPI, SQLAlchemy, Pydantic, Typer/Click (core — stays required with no extras installed)
+- Per-pipeline extras (torch, ultralytics, pyannote.audio, transformers, deepface, open-clip-torch, openai-whisper, etc.) — being moved from required dependencies to `[project.optional-dependencies]` groups (`face`, `face-laion`, `face-openface3`, `audio`, `audio-laion`, `scene`, `person`, `all`) as of 004-extras-based-install
+- SQLite/SQLAlchemy for job/pipeline state; local filesystem model cache (HF/torch cache dirs)
+
+## Project Structure
+```
+src/videoannotator/
+├── api/            # FastAPI app, job submission/status endpoints
+├── batch/          # batch_orchestrator — CLI batch job execution path
+├── cli.py          # videoannotator CLI entry point
+├── pipelines/      # face_analysis/, audio_processing/, scene_detection/, person_tracking/
+├── registry/       # pipeline_registry.py, pipeline_loader.py, metadata/*.yaml
+├── storage/        # job/annotation storage backends
+└── exporters/      # COCO/RTTM/WebVTT/native-format writers
+tests/
+├── unit/ integration/ pipelines/ api/ contract/
+specs/<NNN>-<slug>/  # spec-kit feature specs (spec.md, plan.md, tasks.md, ...)
+docs/development/roadmap_v1.{5,6}.0.md, roadmap_v1.7_to_v2.0.md  # release roadmap
+```
+
+## Commands
+```bash
+pytest tests/                 # full suite
+pytest tests/ -k acceptance   # v1.4.x behaviour-parity fixtures
+ruff check .                  # lint (see pyproject.toml [tool.ruff])
+mypy src/videoannotator        # type check
+pre-commit run --all-files    # full pre-commit gate (used on every commit)
+videoannotator pipelines list # CLI: list available pipelines
+videoannotator job submit <video> --pipelines <name>
+```
+
+## Code Style
+Python 3.12, ruff-enforced (line-length 88, see `[tool.ruff]` in `pyproject.toml` for the
+per-file-ignore exceptions). Follow standard conventions; no comments explaining *what* code does,
+only non-obvious *why*.
+
+## Constitution
+`.specify/memory/constitution.md` (v1.0.0) is binding — five core principles (Local-First
+Execution, Stable Pipeline Contract, Provenance & Reproducibility, Modular by Construction,
+Backward Compatibility by Default). `/speckit-plan`'s Constitution Check gate evaluates every plan
+against it.
+
+## Recent Changes
+- 004-extras-based-install: extras-based modular install + metadata-driven registry loading
+  (removes `LEGACY_MAPPINGS`, adds `requires_extras` to `PipelineMetadata`), scoped to leave room
+  for v1.6.0's Ollama backend and v1.7+'s remote/HPC dispatch without another schema migration.
+
+<!-- MANUAL ADDITIONS START -->
+<!-- MANUAL ADDITIONS END -->
diff --git a/specs/004-extras-based-install/contracts/pipeline-metadata-schema.md b/specs/004-extras-based-install/contracts/pipeline-metadata-schema.md
new file mode 100644
index 0000000..34f5383
--- /dev/null
+++ b/specs/004-extras-based-install/contracts/pipeline-metadata-schema.md
@@ -0,0 +1,45 @@
+# Contract: Pipeline Metadata YAML Schema (delta)
+
+Applies to every file under `src/videoannotator/registry/metadata/*.yaml`. This is the contract
+third-party plugin authors (v1.6.0+) and this repo's own pipeline authors must follow.
+
+## Before (current)
+
+```yaml
+name: face_analysis
+display_name: Face Analysis (DeepFace)
+pipeline_family: face
+variant: deepface
+# ... tasks, modalities, capabilities, outputs, config_schema, version, stability, backends ...
+requirements:
+  packages:
+    - deepface
+    - opencv-python
+```
+
+`requirements.packages` is informational only — nothing in the loader reads it. Module resolution
+falls back to a hardcoded `LEGACY_MAPPINGS` dict in `pipeline_loader.py` keyed by `name`.
+
+## After (this phase)
+
+```yaml
+name: face_analysis
+display_name: Face Analysis (DeepFace)
+pipeline_family: face
+variant: deepface
+module_path: videoannotator.pipelines.face_analysis:FaceAnalysisPipeline   # now required
+requires_extras: [face]                                                    # new, required (may be [])
+# ... tasks, modalities, capabilities, outputs, config_schema, version, stability, backends ...
+```
+
+`requirements.packages` may remain as human-readable documentation but is no longer
+load-bearing; `module_path` and `requires_extras` are the only fields the loader/registry consult
+for import resolution and availability checks.
+
+## Compatibility rule
+
+- `module_path` absent → registry logs a warning and omits the pipeline (same posture as any other
+  malformed metadata file today); this is a breaking change only for hand-authored YAML that never
+  had `module_path`, which is none of the bundled files once this phase lands.
+- `requires_extras` absent → treated as `[]` (no extras required) for backward compatibility with
+  any third-party metadata file authored before this field existed, rather than erroring.
diff --git a/specs/004-extras-based-install/contracts/unavailable-pipeline-error.md b/specs/004-extras-based-install/contracts/unavailable-pipeline-error.md
new file mode 100644
index 0000000..3c17f1c
--- /dev/null
+++ b/specs/004-extras-based-install/contracts/unavailable-pipeline-error.md
@@ -0,0 +1,47 @@
+# Contract: Unavailable-Pipeline Error Surface
+
+Applies to every user-facing surface that can name a pipeline: CLI (`videoannotator job submit
+... --pipelines <name>`), REST API (`POST /api/v1/jobs`, `GET /api/v1/pipelines`).
+
+## Registry listing (`GET /api/v1/pipelines`, `videoannotator pipelines list`)
+
+Unavailable pipelines (extras not installed) are **omitted** from the default listing — not shown
+with an error, not shown at all — per FR-005. A `--all` / `?include_unavailable=true` variant MAY
+list them with an `available: false` + `install_hint` field for discoverability (implementation
+detail for `/speckit-tasks`; not required by any FR but consistent with SC-006's discoverability
+goal).
+
+## Job submission naming an unavailable pipeline
+
+**CLI**: non-zero exit, stderr message, no Python traceback:
+
+```
+Error: pipeline 'face_laion_clip' is not available in this install.
+Install it with: pip install videoannotator[face-laion]
+```
+
+**API**: `422 Unprocessable Entity` (not `500`), JSON body:
+
+```json
+{
+  "detail": "Pipeline 'face_laion_clip' is not available in this install.",
+  "install_hint": "pip install videoannotator[face-laion]",
+  "pipeline": "face_laion_clip"
+}
+```
+
+## Migration case (pipeline demoted from v1.4.4 default install)
+
+Same shape as above, with `detail` distinguishing "no longer in the default install" from "not a
+recognized pipeline" (research.md §4), e.g.:
+
+```
+Error: pipeline 'face_laion_clip' is not available in this install.
+As of v1.5.0, LAION pipelines are no longer installed by default.
+Install it with: pip install videoannotator[face-laion]
+```
+
+## Non-goals for this contract
+
+Does not cover authentication/authorization errors, malformed config errors, or any error not
+related to pipeline availability — those are unchanged by this phase.
diff --git a/specs/004-extras-based-install/data-model.md b/specs/004-extras-based-install/data-model.md
new file mode 100644
index 0000000..9e85ed4
--- /dev/null
+++ b/specs/004-extras-based-install/data-model.md
@@ -0,0 +1,52 @@
+# Phase 1 Data Model: Extras-Based Modular Install
+
+## `PipelineMetadata` (extended)
+
+Location: `src/videoannotator/registry/pipeline_registry.py`. Additive change only — no existing
+field renamed, removed, or retyped (constitution Principle II).
+
+| Field | Type | Status | Notes |
+|---|---|---|---|
+| `name` | `str` | existing | unique pipeline id, e.g. `face_analysis` |
+| `display_name`, `description`, `outputs`, `config_schema`, `version` | — | existing | unchanged |
+| `pipeline_family` | `str \| None` | existing | `face` \| `audio` \| `scene` \| `person` |
+| `variant` | `str \| None` | existing | e.g. `deepface`, `laion-clip-face` |
+| `tasks`, `modalities`, `capabilities` | `list[str]` | existing | unchanged |
+| `backends` | `list[str]` | existing | runtime backend descriptors (`tensorflow`, `opencv`, future `ollama`, `http`) — orthogonal to `requires_extras`, see research.md §2 |
+| `stability` | `str \| None` | existing | `stable` \| `beta` \| `experimental` |
+| **`requires_extras`** | `list[str]` | **new** | pip extras-group name(s) needed for this pipeline to import successfully; `[]` is valid (research.md §2) |
+| `module_path` | `str` | **now required, no fallback** | `"module.path:ClassName"`; `LEGACY_MAPPINGS` removed, every YAML file must carry this explicitly |
+
+Validation rule: `PipelineRegistry.load()` MUST treat a metadata file missing `module_path` as an
+error (warn + skip that entry, matching existing graceful-degradation posture for malformed
+files), not fall back to a hardcoded table.
+
+## Extras group (declarative, `pyproject.toml`)
+
+Not a Python class — a named key under `[project.optional-dependencies]`. Reserved names after
+this phase (research.md §1):
+
+`face`, `face-laion`, `face-openface3`, `audio`, `audio-laion`, `scene`, `person`, `all`, `dev`
+(existing), `annotation` (existing, currently empty/commented).
+
+Reserved-but-not-yet-created (namespace held open per FR-010, not created by this phase):
+`llm` (v1.6.0).
+
+## Migration message record
+
+Not a persisted entity — a lookup table (implementation detail for `/speckit-tasks`) mapping a
+pipeline `name` that existed in v1.4.4's default install to the extras group it now requires,
+consulted only when that pipeline is requested and unavailable:
+
+| Pipeline `name` | v1.4.4 status | v1.5.0 extras group |
+|---|---|---|
+| `face_laion_clip` | default | `face-laion` |
+| `laion_voice` | default | `audio-laion` |
+| `face_openface3_embedding` | default | `face-openface3` |
+| (all other pipelines) | default | their `pipeline_family` group |
+
+## State / lifecycle
+
+No new stateful entities. `PipelineRegistry`'s existing load-once-cache lifecycle
+(`_loaded` flag, `force` reload) is unchanged; `requires_extras` is read at the same load time as
+every other metadata field — no new I/O pass.
diff --git a/specs/004-extras-based-install/plan.md b/specs/004-extras-based-install/plan.md
new file mode 100644
index 0000000..a344d67
--- /dev/null
+++ b/specs/004-extras-based-install/plan.md
@@ -0,0 +1,117 @@
+# Implementation Plan: Extras-Based Modular Install & Registry Refactor
+
+**Branch**: `004-extras-based-install` | **Date**: 2026-07-18 | **Spec**: [spec.md](./spec.md)
+**Input**: Feature specification from `/specs/004-extras-based-install/spec.md`
+
+## Summary
+
+Move VideoAnnotator's heavy ML dependencies out of `[project.dependencies]` and into
+per-pipeline-family `[project.optional-dependencies]` extras groups (`face`, `audio`, `scene`,
+`person`, plus separate LAION groups), replace the registry's hardcoded `LEGACY_MAPPINGS` dict
+with a `requires_extras` field read straight from each pipeline's YAML metadata, make the registry
+degrade gracefully (omit, don't crash) when a pipeline's extras aren't installed, and drop the
+`numpy<2.0` pin once the suite is green on NumPy 2.x. The extras-group naming and
+`PipelineMetadata` schema changes are chosen so v1.6.0 (Ollama `llm` extra) and v1.7.0+
+(HTTPDispatcher/SlurmDispatcher remote/HPC targets) can build on them without another schema
+migration (spec FR-010–FR-012, SC-007).
+
+## Technical Context
+
+**Language/Version**: Python 3.12 (`requires-python = ">=3.12,<3.13"`, `pyproject.toml:26`)
+**Primary Dependencies**: FastAPI, SQLAlchemy, Pydantic, Typer/Click (core, stays required);
+torch, torchvision, torchaudio, ultralytics, pyannote.audio (+core/database/metrics/pipeline),
+transformers, sentence-transformers, open-clip-torch, openai-whisper, timm, deepface (via
+`openface-test`/opencv, no torch), huggingface-hub (moving to extras)
+**Storage**: SQLite/SQLAlchemy for job/pipeline state (unaffected); local filesystem model cache
+under the user's HF/torch cache dirs (must survive this refactor unchanged — FR-015 equivalent)
+**Testing**: pytest (`tests/unit`, `tests/integration`, `tests/pipelines`, `tests/api`,
+`tests/contract`), pytest-cov (≥80% gate per constitution Engineering Standards), mypy, ruff
+**Target Platform**: Linux/macOS/Windows, CI matrix already runs all three (`.github/workflows/ci-cd.yml`)
+**Project Type**: Single Python package (`src/videoannotator/`), no separate frontend/backend split
+**Performance Goals**: Single-family install + first run < 5 min on broadband laptop (SC-001);
+default Docker image ≥80% smaller than v1.4.4 baseline (SC-002)
+**Constraints**: v1.5.0 `[all]` output byte-identical to v1.4.4 for deterministic pipelines,
+documented tolerance for non-deterministic ones (FR-009); NumPy 2.x must pass full suite (FR-007);
+zero config/CLI changes for existing users (User Story 2)
+**Scale/Scope**: 8 existing pipeline metadata YAML files across 4 families (`face` ×3 variants,
+`audio` ×4 variants, `scene` ×1, `person` ×1); `pyproject.toml` dependency block (~95 lines);
+`registry/pipeline_loader.py` (LEGACY_MAPPINGS removal); 2 Dockerfiles (`Dockerfile.cpu`,
+`Dockerfile.gpu`) plus `Dockerfile.dev`
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+Evaluated against `.specify/memory/constitution.md` v1.0.0's Plan Gating checklist:
+
+- **Principle I (Local-First Execution)**: PASS. This phase touches install/registry only; no
+  pipeline gains a required network dependency. Extras that are HTTP-thin (future `llm` group) are
+  explicitly out of scope for this phase (spec Assumptions).
+- **Principles II & V (Stable Pipeline Contract, Backward Compatibility)**: PASS, with the
+  refactor's entire purpose being to preserve these — `requires_extras` is an additive
+  `PipelineMetadata` field, `BasePipeline`'s interface is untouched, no output keys change. User
+  Story 2 (byte-identical `[all]` output vs v1.4.4) is the concrete test.
+- **Principle III (Provenance & Reproducibility)**: PASS / not applicable — this phase adds no new
+  annotation type, so no new provenance fields are required. Noted for later: v1.7.0's
+  remote/HPC/VLM work (out of scope here) will need to extend provenance metadata per that
+  principle; flagged already in `roadmap_v1.7_to_v2.0.md`.
+- **Principle IV (Modular by Construction)**: PASS — this phase is a direct, literal
+  implementation of this principle (it is currently violated: every heavy ML dep is unconditional
+  today). This plan is what brings the codebase into compliance.
+- **Engineering Standards**: Testing, CI (3-OS matrix), type safety, and docs updates are planned
+  below (Phase 1 quickstart + install-matrix docs, CI job additions for per-extras install
+  smoke-tests). No proprietary weights involved.
+
+**Result**: No violations. No entries needed in Complexity Tracking.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```
+specs/004-extras-based-install/
+├── plan.md              # This file
+├── research.md          # Phase 0 output
+├── data-model.md         # Phase 1 output
+├── quickstart.md         # Phase 1 output
+├── contracts/             # Phase 1 output
+│   ├── pipeline-metadata-schema.md
+│   └── unavailable-pipeline-error.md
+└── tasks.md              # Phase 2 output (/speckit-tasks, not this command)
+```
+
+### Source Code (repository root)
+
+```
+pyproject.toml                                   # [project.dependencies] slimmed;
+                                                   # [project.optional-dependencies] gains
+                                                   # face/audio/scene/person/face-laion/
+                                                   # audio-laion/all groups
+src/videoannotator/registry/
+├── pipeline_registry.py                          # PipelineMetadata gains requires_extras: list[str]
+├── pipeline_loader.py                            # LEGACY_MAPPINGS removed; module_path resolved
+│                                                  # from metadata only; extras-aware availability
+│                                                  # check; actionable ImportError → install-hint
+│                                                  # translation
+└── metadata/*.yaml                                # each file gains requires_extras: [...]
+src/videoannotator/cli.py                         # pipeline-unavailable error path -> install hint
+src/videoannotator/api/                           # GET /api/v1/pipelines excludes unavailable
+                                                   # pipelines from listings; job submission returns
+                                                   # actionable 4xx, not 500, for unavailable pipeline
+Dockerfile.cpu, Dockerfile.gpu                    # slim by default (no extras); [all] variant documented
+docs/installation/INSTALLATION.md                 # per-use-case install matrix (SC-006)
+tests/unit/registry/                              # new: requires_extras resolution, graceful
+                                                   # degradation, migration-message tests
+tests/integration/                                # extras-isolation smoke tests (subprocess-based,
+                                                   # one clean venv per extras group, CI-gated)
+```
+
+**Structure Decision**: Single-project layout (existing `src/videoannotator/` package); no new
+top-level projects or services introduced. This phase is deliberately confined to the registry,
+`pyproject.toml`, and Docker/docs — it does not touch `api/job_processor.py` or
+`batch/batch_orchestrator.py` beyond what's needed for the actionable-error path (their
+consolidation is FR-012's forward-compat guarantee for v1.6.0, not this phase's job).
+
+## Complexity Tracking
+
+*No Constitution Check violations — this section is empty by design.*
diff --git a/specs/004-extras-based-install/quickstart.md b/specs/004-extras-based-install/quickstart.md
new file mode 100644
index 0000000..0311dd4
--- /dev/null
+++ b/specs/004-extras-based-install/quickstart.md
@@ -0,0 +1,53 @@
+# Quickstart: Verifying the Extras-Based Install
+
+Manual/CI verification steps mapped to spec 004's acceptance scenarios.
+
+## 1. Slim single-family install (User Story 1)
+
+```bash
+python -m venv /tmp/va-scene && source /tmp/va-scene/bin/activate
+pip install videoannotator[scene]
+pip show torch open-clip-torch scenedetect  # present — scene needs them (research.md §1)
+pip show pyannote.audio ultralytics deepface  # MUST be absent
+videoannotator pipelines list                 # only scene_detection shown
+videoannotator job submit sample.mp4 --pipelines scene_detection   # succeeds
+videoannotator job submit sample.mp4 --pipelines face_analysis     # actionable error, no traceback
+```
+
+## 2. Additive install (User Story 1, scenario 4)
+
+```bash
+pip install videoannotator[face]
+videoannotator pipelines list   # scene_detection AND face_analysis now shown; nothing reset
+```
+
+## 3. Full-parity install (User Story 2)
+
+```bash
+pip install videoannotator[all]
+pytest tests/ -k acceptance   # v1.4.4 fixtures pass byte-identical / within documented tolerance
+```
+
+## 4. LAION migration message (User Story 2, scenario 2)
+
+```bash
+pip install videoannotator[face]   # face, not face-laion
+videoannotator job submit sample.mp4 --config old_v144_config_with_laion.yaml
+# expect: "no longer installed by default as of v1.5.0" message naming `face-laion`, not a raw ImportError
+```
+
+## 5. NumPy 2.x
+
+```bash
+pip install videoannotator[all] "numpy>=2.0"
+pytest tests/ -x
+```
+
+## 6. Forward-compatibility gate (User Story 3 / SC-007)
+
+```bash
+# Author a throwaway stub pipeline YAML with requires_extras: [] and a module_path
+# pointing at a NotImplementedError stub; confirm registry loads it without code changes.
+cp tests/fixtures/stub_pipeline.yaml src/videoannotator/registry/metadata/ # or a test-only registry dir
+python -c "from videoannotator.registry import get_registry; get_registry().load(force=True); print('ok')"
+```
diff --git a/specs/004-extras-based-install/research.md b/specs/004-extras-based-install/research.md
new file mode 100644
index 0000000..3fb5b74
--- /dev/null
+++ b/specs/004-extras-based-install/research.md
@@ -0,0 +1,107 @@
+# Phase 0 Research: Extras-Based Modular Install
+
+## 1. Actual per-pipeline dependency footprint
+
+**Question**: Spec 003/roadmap assumed extras groups are `face`, `audio`, `scene`, `person`,
+`embedding`. Is that grouping accurate to what each pipeline's code actually imports?
+
+**Method**: Traced module-level and lazy (in-method) imports in each pipeline's source
+(`src/videoannotator/pipelines/*/`) rather than trusting the metadata YAML's informal
+`requirements.packages` list, since that list predates this refactor and isn't necessarily complete.
+
+**Decision**: Use these five extras groups, matching actual `pipeline_family` values already in
+the metadata (`face`, `audio`, `scene`, `person`) plus two LAION carve-outs — **not** a separate
+`embedding` group, because no pipeline in the current registry declares `pipeline_family:
+embedding`; `face_openface3_embedding` is `pipeline_family: face, variant: openface3-embedding`.
+Inventing an `embedding` group not backed by the taxonomy would create a group with nothing in it.
+
+| Extras group | Pipelines (variant) | Heavy deps actually imported |
+|---|---|---|
+| `face` | `face_analysis` (deepface) | `deepface`, `opencv-python`, `imutils` — **no torch** |
+| `face-laion` | `face_laion_clip` | `torch`, `transformers`, `huggingface-hub` |
+| `face-openface3` | `face_openface3_embedding` | `openface-test`, `scipy`, `torch` (lazy, only on embedding-similarity path) |
+| `audio` | `audio_processing`, `speech_recognition`, `speaker_diarization` | `torch`, `torchaudio`, `librosa`, `openai-whisper`, `pyannote.audio`+`core`+`database`+`metrics`+`pipeline` |
+| `audio-laion` | `laion_voice` | `torch`, `transformers`, `huggingface-hub`, `librosa` |
+| `scene` | `scene_detection` | `torch`, `open-clip-torch`, `scenedetect[opencv]` |
+| `person` | `person_tracking` | `torch` (via ultralytics), `ultralytics`, `supervision` |
+
+**Rationale**: `face` (DeepFace-only) is the one genuinely torch-free group — worth calling out
+explicitly in docs/SC-001 examples ("I want only scene labelling" pulls torch; "I want only
+standard face analysis" does not). `scene` and `person` both need torch even though a naive
+reading of the roadmap implied otherwise; this doesn't block FR-001 (no extras = no torch), but it
+does mean `scene` alone is not as lightweight as `face` alone. Document this plainly rather than
+imply all five groups are equally slim.
+
+**Alternatives considered**:
+- A single `embedding` group holding CLIP/openface3/sentence-transformers shared code: rejected —
+  no such shared module exists today; would require a real code split, out of scope for this phase
+  (FR-001–FR-009 are about dependency *declaration*, not module *extraction*, which is v2.0 scope
+  per `roadmap_v1.7_to_v2.0.md`).
+- Merging `face-laion` and `face-openface3` into one `face-extended` group: rejected — they have
+  different dependency sets (`transformers`+`huggingface-hub` vs `openface-test`+`scipy`) and
+  different licenses to track per constitution Engineering Standards; keeping them separate matches
+  FR-002's requirement that LAION not be bundled into anything non-opt-in, and doesn't block a user
+  who wants openface3 embeddings but not LAION.
+
+## 2. `requires_extras` semantics vs. `backends`
+
+**Question**: `PipelineMetadata` already has a `backends: list[str]` field (currently populated
+with values like `tensorflow`, `opencv`). FR-011 requires `requires_extras: []` to be valid, for a
+future non-local pipeline. Do these two fields overlap?
+
+**Decision**: They're orthogonal and both stay. `requires_extras` answers "what `pip install
+videoannotator[...]` do I need" (a packaging-time question); `backends` answers "what inference
+backend does this pipeline variant use at runtime" (already used descriptively, e.g.
+`tensorflow`/`opencv` for `face_analysis`). A future Ollama-backed pipeline (v1.6.0) would have
+`requires_extras: [llm]` (a small `httpx`-only extra) and `backends: [ollama]` — both populated,
+neither empty, but neither heavy. This confirms FR-011's premise: `requires_extras: []` is reserved
+for a pipeline with literally no extra to install (rare, maybe never used pre-v1.6.0), while a
+lightweight non-ML extra (`llm`) is the more common future shape. Spec's User Story 3 acceptance
+scenario 1 (`requires_extras: []` stub) still stands as the schema-flexibility test; it doesn't
+predict that v1.6.0's actual Ollama pipeline will use an empty list.
+
+## 3. Registry graceful-degradation mechanism
+
+**Question**: How should `PipelineLoader`/`PipelineRegistry` detect "extras not installed" without
+attempting (and catching an exception from) every pipeline's heavy import at every registry load?
+
+**Decision**: Check `importlib.util.find_spec()` for each package name mapped from
+`requires_extras` (e.g. `face-laion` → `["torch", "transformers"]`) before attempting
+`importlib.import_module()` on the pipeline's `module_path`. `find_spec` is cheap (no execution of
+the target module) and works even for packages that are slow or side-effect-heavy to import.
+Package-name-per-extras-group mapping lives alongside the extras definitions in `pyproject.toml`
+metadata read via `importlib.metadata`, avoiding a second hand-maintained mapping that could drift.
+
+**Alternatives considered**: try/except around the real import (rejected — heavy ML imports can
+have expensive or noisy failure modes, e.g. partial CUDA init, that we don't want happening for
+every unavailable pipeline on every registry load) using `importlib.metadata.PackageNotFoundError`
+lookups per declared extra requirement instead of `find_spec` per underlying module (viable
+alternative, roughly equivalent cost/accuracy — implementation detail for `/speckit-tasks`, not a
+blocking research question).
+
+## 4. Migration-message design for demoted pipelines (LAION)
+
+**Decision**: A v1.4.x config referencing `face_laion_clip` or `laion_voice` on a v1.5.0 install
+without the corresponding extras produces a distinct message (not the generic "pipeline not
+found"): `Pipeline 'face_laion_clip' requires the 'face-laion' extras group, which is no longer
+installed by default as of v1.5.0. Install it with: pip install videoannotator[face-laion]`. This
+satisfies FR-006 and Edge Cases' distinguishability requirement. Implementation detail (exact
+string, i18n if ever needed) belongs in `/speckit-tasks`; the *shape* — name the extra, give the
+exact command, explain the "no longer default" context — is the Phase-1 design decision.
+
+## 5. NumPy 2.x verification approach
+
+**Decision**: Add a CI job variant that runs the full suite with NumPy 2.x pinned, gated the same
+as the existing 3-OS matrix, before removing the `<2.0` pin from the default dependency set. Keep
+the NumPy-1.x job running in parallel until the removal PR merges (belt-and-braces given
+`pyannote`/`scipy`/`matplotlib` binary-wheel history noted in the existing pyproject comment at
+line 42), then delete the 1.x job once 2.x is confirmed default. This is a CI-config task for
+`/speckit-tasks`, not a design decision requiring further research here.
+
+## 6. Docker image slimming approach
+
+**Decision**: `Dockerfile.cpu`/`Dockerfile.gpu` build with no extras by default (`pip install .`,
+no `[all]`); a documented `--build-arg EXTRAS=all` (or a separate `Dockerfile.cpu.all` — exact
+mechanism is a `/speckit-tasks` implementation choice) reproduces the current image for users who
+want everything. SC-002's ≥80% reduction target is measured against the current `[all]`-equivalent
+baseline image size recorded at v1.4.4 release.

From 82136cadf42d9052182ae504c129e3a375914276 Mon Sep 17 00:00:00 2001
From: Caspar Addyman <infantologist@gmail.com>
Date: Sat, 18 Jul 2026 23:38:51 +0000
Subject: [PATCH 03/10] tasks: generate dependency-ordered task list for
 extras-based install
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

38 tasks across Setup (1), Foundational (13), US1/MVP (9), US2 (8),
US3 (3), and Polish (4). Verified against the actual codebase rather
than the spec's abstractions alone: all 9 pipeline metadata YAML files
currently rely entirely on LEGACY_MAPPINGS (none has module_path or
requires_extras today), so Foundational includes one task per file
rather than a generic "update metadata" task. Fixed an off-by-one in
plan.md's Scale/Scope (said 8 metadata files, it's 9).

Also corrects the fact that this dependency graph surfaces: US2's
migration-message task (T027) is the only real cross-story coupling,
sharing US1's error-path code (T022) — everything else in US1/US2/US3
is independently staffable after the Foundational phase.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 specs/004-extras-based-install/plan.md  |   6 +-
 specs/004-extras-based-install/tasks.md | 331 ++++++++++++++++++++++++
 2 files changed, 335 insertions(+), 2 deletions(-)
 create mode 100644 specs/004-extras-based-install/tasks.md

diff --git a/specs/004-extras-based-install/plan.md b/specs/004-extras-based-install/plan.md
index a344d67..41c8844 100644
--- a/specs/004-extras-based-install/plan.md
+++ b/specs/004-extras-based-install/plan.md
@@ -33,8 +33,10 @@ default Docker image ≥80% smaller than v1.4.4 baseline (SC-002)
 **Constraints**: v1.5.0 `[all]` output byte-identical to v1.4.4 for deterministic pipelines,
 documented tolerance for non-deterministic ones (FR-009); NumPy 2.x must pass full suite (FR-007);
 zero config/CLI changes for existing users (User Story 2)
-**Scale/Scope**: 8 existing pipeline metadata YAML files across 4 families (`face` ×3 variants,
-`audio` ×4 variants, `scene` ×1, `person` ×1); `pyproject.toml` dependency block (~95 lines);
+**Scale/Scope**: 9 existing pipeline metadata YAML files across 4 families (`face` ×3 variants,
+`audio` ×4 variants, `scene` ×1, `person` ×1); none currently declare `module_path` or
+`requires_extras` — all 9 resolve today purely through `pipeline_loader.py`'s `LEGACY_MAPPINGS`
+fallback, so every file needs both fields added; `pyproject.toml` dependency block (~95 lines);
 `registry/pipeline_loader.py` (LEGACY_MAPPINGS removal); 2 Dockerfiles (`Dockerfile.cpu`,
 `Dockerfile.gpu`) plus `Dockerfile.dev`
 
diff --git a/specs/004-extras-based-install/tasks.md b/specs/004-extras-based-install/tasks.md
new file mode 100644
index 0000000..ca46f6b
--- /dev/null
+++ b/specs/004-extras-based-install/tasks.md
@@ -0,0 +1,331 @@
+---
+description: "Task list for Extras-Based Modular Install & Registry Refactor"
+---
+
+# Tasks: Extras-Based Modular Install & Registry Refactor
+
+**Input**: Design documents from `/specs/004-extras-based-install/`
+**Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/, quickstart.md
+
+**Tests**: Included. Not explicitly requested in spec.md's own text, but the ratified
+constitution's Engineering Standards ("New pipelines and new public CLI/API surface MUST ship
+with tests", coverage ≥80%) makes this a standing repo-wide requirement, not an opt-in.
+
+**Organization**: Tasks are grouped by user story (US1, US2, US3 — spec.md priorities P1, P1, P2
+respectively) to enable independent implementation and testing of each.
+
+## Format: `[ID] [P?] [Story] Description`
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (US1, US2, US3)
+
+## Path Conventions
+
+Single project (`src/videoannotator/`, `tests/`) per plan.md's Structure Decision.
+
+---
+
+## Phase 1: Setup
+
+**Purpose**: Declare the extras groups so later phases have somewhere to put dependencies.
+
+- [ ] T001 [P] Define `[project.optional-dependencies]` groups in `pyproject.toml` — `face`
+      (deepface, opencv-python, imutils), `face-laion` (torch, torchvision, transformers,
+      huggingface-hub), `face-openface3` (openface-test, scipy), `audio` (torch, torchaudio,
+      librosa, openai-whisper, pyannote.audio+core+database+metrics+pipeline), `audio-laion`
+      (torch, transformers, huggingface-hub, librosa), `scene` (torch, open-clip-torch,
+      scenedetect[opencv]), `person` (torch, torchvision, ultralytics, supervision), `all`
+      (unions all of the above). Remove the corresponding entries from `[project.dependencies]`.
+      Per research.md §1 — `face` (DeepFace variant) needs no torch; every other group does.
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Metadata-driven registry loading. MUST complete before any user story — every story
+depends on the registry being able to read `requires_extras`/`module_path` from YAML instead of
+`LEGACY_MAPPINGS`.
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete.
+
+- [ ] T002 Add `requires_extras: list[str]` field (default `field(default_factory=list)`) to the
+      `PipelineMetadata` dataclass and its YAML-parsing logic in
+      `src/videoannotator/registry/pipeline_registry.py`, per
+      `specs/004-extras-based-install/contracts/pipeline-metadata-schema.md`
+- [ ] T003 [P] Add `module_path: videoannotator.pipelines.face_analysis:FaceAnalysisPipeline` and
+      `requires_extras: [face]` to `src/videoannotator/registry/metadata/face_analysis.yaml`
+- [ ] T004 [P] Add `module_path:
+      videoannotator.pipelines.face_analysis.laion_face_pipeline:LAIONFacePipeline` and
+      `requires_extras: [face-laion]` to
+      `src/videoannotator/registry/metadata/face_laion_clip.yaml`
+- [ ] T005 [P] Add `module_path:
+      videoannotator.pipelines.face_analysis.openface3_pipeline:OpenFace3Pipeline` and
+      `requires_extras: [face-openface3]` to
+      `src/videoannotator/registry/metadata/face_openface3_embedding.yaml`
+- [ ] T006 [P] Add `module_path:
+      videoannotator.pipelines.audio_processing:AudioPipeline` and `requires_extras: [audio]` to
+      `src/videoannotator/registry/metadata/audio_processing.yaml`
+- [ ] T007 [P] Add `module_path:
+      videoannotator.pipelines.audio_processing:SpeechPipeline` and `requires_extras: [audio]` to
+      `src/videoannotator/registry/metadata/speech_recognition.yaml`
+- [ ] T008 [P] Add `module_path:
+      videoannotator.pipelines.audio_processing:DiarizationPipeline` and
+      `requires_extras: [audio]` to
+      `src/videoannotator/registry/metadata/speaker_diarization.yaml`
+- [ ] T009 [P] Add `module_path:
+      videoannotator.pipelines.audio_processing.laion_voice_pipeline:LAIONVoicePipeline` and
+      `requires_extras: [audio-laion]` to `src/videoannotator/registry/metadata/laion_voice.yaml`
+- [ ] T010 [P] Add `module_path:
+      videoannotator.pipelines.scene_detection:SceneDetectionPipeline` and
+      `requires_extras: [scene]` to `src/videoannotator/registry/metadata/scene_detection.yaml`
+- [ ] T011 [P] Add `module_path:
+      videoannotator.pipelines.person_tracking:PersonTrackingPipeline` and
+      `requires_extras: [person]` to `src/videoannotator/registry/metadata/person_tracking.yaml`
+- [ ] T012 Implement an extras-availability check helper (`importlib.util.find_spec`-based, per
+      research.md §3) in `src/videoannotator/registry/pipeline_loader.py` — depends on T002
+- [ ] T013 Remove `LEGACY_MAPPINGS` and `_infer_module_path` from
+      `src/videoannotator/registry/pipeline_loader.py`; resolve `module_path` purely from
+      metadata; warn-and-skip (not crash) a pipeline whose YAML lacks `module_path` — depends on
+      T003–T011 (every YAML must carry `module_path` before the fallback can be safely deleted)
+- [ ] T014 [P] Unit tests for `requires_extras` parsing, `module_path`-required validation, and
+      the extras-availability helper in `tests/unit/registry/test_pipeline_registry.py` — depends
+      on T002, T012
+
+**Checkpoint**: Registry is fully metadata-driven; `LEGACY_MAPPINGS` is gone. User story
+implementation can now begin.
+
+---
+
+## Phase 3: User Story 1 - Slim, targeted install for a single research need (Priority: P1) 🎯 MVP
+
+**Goal**: `pip install videoannotator[scene]` (or any single family) pulls only that family's
+deps; unavailable pipelines are omitted from listings and produce actionable errors, not
+tracebacks.
+
+**Independent Test**: quickstart.md §1–2 — install `[scene]` in a clean venv, confirm
+torch/open-clip present and pyannote/ultralytics/deepface absent, run scene labelling
+successfully, confirm requesting `face_analysis` gives an actionable error.
+
+### Tests for User Story 1 ⚠️
+
+- [ ] T015 [P] [US1] Contract test: unavailable pipelines omitted from `GET /api/v1/pipelines`
+      default listing in `tests/contract/test_pipeline_availability_contract.py`
+- [ ] T016 [P] [US1] Contract test: CLI and API unavailable-pipeline error shape (API: `422` +
+      `install_hint` field; CLI: non-zero exit, no traceback) per
+      `specs/004-extras-based-install/contracts/unavailable-pipeline-error.md` in
+      `tests/contract/test_unavailable_pipeline_error.py`
+- [ ] T017 [P] [US1] Integration test: subprocess-driven extras isolation — install
+      `videoannotator[scene]` into a clean venv, assert `torch`/`open-clip-torch` importable and
+      `pyannote.audio`/`ultralytics`/`deepface` are not, in
+      `tests/integration/test_extras_isolation.py`
+
+### Implementation for User Story 1
+
+- [ ] T018 [US1] Wire the extras-availability check (T012) into
+      `PipelineLoader.load_all_pipelines()` so it's consulted before attempting each pipeline's
+      import — depends on T012
+- [ ] T019 [US1] `PipelineRegistry`/`PipelineLoader`: omit pipelines whose extras aren't installed
+      from default `list()`/`load_all_pipelines()` output, per FR-005 — depends on T018
+- [ ] T020 [US1] `GET /api/v1/pipelines` excludes unavailable pipelines by default; add
+      `?include_unavailable=true` returning `available: false` + `install_hint` per pipeline in
+      `src/videoannotator/api/` — depends on T019
+- [ ] T021 [US1] `videoannotator pipelines list` (CLI) reflects the same availability filtering in
+      `src/videoannotator/cli.py` — depends on T019
+- [ ] T022 [US1] Job submission (CLI `job submit` and API `POST /api/v1/jobs`) returns the
+      actionable error contract (exact `pip install videoannotator[...]` command, `422` not
+      `500`, no Python traceback) when a requested pipeline is unavailable — depends on T019
+- [ ] T023 [US1] Slim `Dockerfile.cpu` and `Dockerfile.gpu` to build with no extras by default;
+      document the `[all]`-equivalent build variant (research.md §6)
+
+**Checkpoint**: User Story 1 fully functional and independently testable — this is the MVP slice.
+
+---
+
+## Phase 4: User Story 2 - Backward-compatible upgrade for existing studies (Priority: P1)
+
+**Goal**: `pip install videoannotator[all]` reproduces v1.4.4 behaviour exactly; a v1.4.x config
+referencing a now-demoted pipeline (LAION, openface3) gets a specific migration message; full
+suite passes on NumPy 2.x and the `<2.0` pin is dropped.
+
+**Independent Test**: quickstart.md §3–5 — `[all]` install passes v1.4.4 acceptance fixtures
+byte-identical (or within documented tolerance); an old LAION-referencing config produces the
+migration message, not a raw ImportError; suite passes with `numpy>=2.0` installed.
+
+### Tests for User Story 2 ⚠️
+
+- [ ] T024 [P] [US2] Contract test: migration-message variant (names the extras group, states
+      "no longer installed by default as of v1.5.0", distinct from the generic unavailable-error
+      text) in `tests/contract/test_migration_message_contract.py`
+- [ ] T025 [P] [US2] v1.4.4 acceptance-fixture parity test under a `[all]` install —
+      byte-identical output for deterministic pipelines, documented tolerance for
+      non-deterministic ones (FR-009) — in `tests/integration/test_v144_parity.py`
+- [ ] T026 [P] [US2] Model-cache reuse test: a pre-existing HF/torch cache directory is reused,
+      not re-downloaded, under the new extras-aware loader in
+      `tests/integration/test_model_cache_reuse.py`
+
+### Implementation for User Story 2
+
+- [ ] T027 [US2] Wire the migration-message lookup (data-model.md's migration table:
+      `face_laion_clip`→`face-laion`, `laion_voice`→`audio-laion`,
+      `face_openface3_embedding`→`face-openface3`) into the same error path as T022, so demoted
+      pipelines get the distinct message — depends on T022
+- [ ] T028 [US2] Add a NumPy 2.x CI job variant alongside the existing job in
+      `.github/workflows/ci-cd.yml` (research.md §5)
+- [ ] T029 [US2] Fix NumPy 2.x incompatibilities surfaced by T028 (watch specifically for
+      `pyannote`/`scipy`/`matplotlib` binary-wheel issues flagged in the current
+      `pyproject.toml:43` pin comment); iterate until the NumPy-2.x job is green — depends on T028
+- [ ] T030 [US2] Remove the `numpy<2.0` pin from `pyproject.toml`; retire the NumPy-1.x CI job
+      once T029's job has been green for a full run — depends on T029
+- [ ] T031 [US2] Write the per-use-case install matrix ("I want only scene labelling", "I want
+      everything", "I want a slim API server") in `docs/installation/INSTALLATION.md` (FR-013,
+      SC-006)
+
+**Checkpoint**: User Stories 1 AND 2 both independently functional.
+
+---
+
+## Phase 5: User Story 3 - Metadata schema has room for non-local execution (Priority: P2)
+
+**Goal**: Prove the schema changes from Phase 2 don't need to be redone for v1.6.0's Ollama
+backend or v1.7+'s remote/HPC dispatch — the actual reason this phase was prioritized now.
+
+**Independent Test**: quickstart.md §6 — a throwaway pipeline YAML with `requires_extras: []`
+and a stub `module_path` loads successfully through the registry with zero loader code changes.
+
+### Tests for User Story 3 ⚠️
+
+- [ ] T032 [P] [US3] Unit test: a stub pipeline metadata entry with `requires_extras: []` and a
+      `module_path` pointing at a `NotImplementedError` stub class loads via the registry without
+      any loader-code changes, in `tests/unit/registry/test_forward_compat_stub.py`
+
+### Implementation for User Story 3
+
+- [ ] T033 [US3] Author the throwaway stub pipeline fixture (`tests/fixtures/stub_pipeline.yaml`
+      + a stub module) used by T032, demonstrating `requires_extras: []` plus a non-ML `backends`
+      value — depends on T013
+- [ ] T034 [US3] Write the SC-007 design-review note — confirm in writing (appended to
+      research.md or a new short doc) that adding v1.6.0's `llm` extras group and its pipeline
+      entries requires zero changes to `PipelineMetadata`, the registry loader, or the
+      extras-naming scheme from Phase 1/2 — only additive YAML + a new
+      `[project.optional-dependencies]` entry
+
+**Checkpoint**: All three user stories independently functional.
+
+---
+
+## Final Phase: Polish & Cross-Cutting Concerns
+
+- [ ] T035 [P] Check off the completed items in `docs/development/roadmap_v1.5.0.md`'s Phase 1
+      deliverables list to match what shipped
+- [ ] T036 Run `pytest tests/`, `mypy src/videoannotator`, `ruff check .`; confirm the ≥80%
+      coverage gate (constitution Engineering Standards) still holds
+- [ ] T037 Run every section of `specs/004-extras-based-install/quickstart.md` end-to-end
+- [ ] T038 [P] Update `CHANGELOG.md` with the v1.5.0 Phase 1 entry
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: No dependencies — can start immediately.
+- **Foundational (Phase 2)**: Depends on Setup (extras groups must exist for `requires_extras`
+  values to mean anything) — BLOCKS all user stories.
+- **User Stories (Phase 3+)**: All depend on Foundational completion. US1 and US2 (both P1) can
+  proceed in parallel if staffed; US3 (P2) can also start in parallel — it only depends on T013
+  (LEGACY_MAPPINGS removal), not on US1/US2's own work.
+- **Polish (Final Phase)**: Depends on all three user stories being complete.
+
+### User Story Dependencies
+
+- **US1 (P1)**: Starts after Foundational. No dependency on US2/US3.
+- **US2 (P1)**: Starts after Foundational. T027 depends on US1's T022 (same error-path code), so
+  in practice US2's implementation tasks trail US1's by that one dependency; US2's tests (T024–26)
+  and CI/NumPy work (T028–30) have no US1 dependency and can start immediately after Foundational.
+- **US3 (P2)**: Starts after Foundational (specifically T013). No dependency on US1/US2.
+
+### Within Each User Story
+
+- Tests written before implementation tasks that make them pass.
+- Registry/loader wiring before API/CLI surface changes.
+- Story complete and checkpointed before considering the next priority tier done.
+
+### Parallel Opportunities
+
+- T001 (Setup) has nothing to parallelize against within its own phase.
+- T003–T011 (9 YAML edits) are fully parallel — independent files.
+- T014 can run parallel to T015–T017 once its own dependencies (T002, T012) are met.
+- Within US1: T015, T016, T017 (tests) in parallel; T023 (Docker) in parallel with T020/T021/T022
+  once T019 lands.
+- Within US2: T024, T025, T026 (tests) in parallel; T028 can start immediately after Foundational,
+  in parallel with all of US1.
+- US1 and US2 can be staffed in parallel after Foundational, with the single T022→T027 handoff
+  point noted above.
+- US3 can be staffed in parallel with both US1 and US2 after Foundational.
+
+---
+
+## Parallel Example: Foundational Phase
+
+```bash
+# After T002 lands, launch all 9 metadata-file edits together:
+Task: "Add module_path + requires_extras: [face] to face_analysis.yaml"
+Task: "Add module_path + requires_extras: [face-laion] to face_laion_clip.yaml"
+Task: "Add module_path + requires_extras: [face-openface3] to face_openface3_embedding.yaml"
+Task: "Add module_path + requires_extras: [audio] to audio_processing.yaml"
+Task: "Add module_path + requires_extras: [audio] to speech_recognition.yaml"
+Task: "Add module_path + requires_extras: [audio] to speaker_diarization.yaml"
+Task: "Add module_path + requires_extras: [audio-laion] to laion_voice.yaml"
+Task: "Add module_path + requires_extras: [scene] to scene_detection.yaml"
+Task: "Add module_path + requires_extras: [person] to person_tracking.yaml"
+```
+
+## Parallel Example: User Story 1
+
+```bash
+# Launch all US1 tests together:
+Task: "Contract test: unavailable pipelines omitted from GET /api/v1/pipelines"
+Task: "Contract test: CLI/API unavailable-pipeline error shape"
+Task: "Integration test: subprocess-driven extras isolation for [scene]"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Setup (T001).
+2. Complete Phase 2: Foundational (T002–T014) — CRITICAL, blocks everything.
+3. Complete Phase 3: User Story 1 (T015–T023).
+4. **STOP and VALIDATE**: run quickstart.md §1–2 for real, not just the automated tests.
+5. This is a legitimately shippable increment: a user can install a single pipeline family slim
+   and get actionable errors for the rest, even before US2/US3 land.
+
+### Incremental Delivery
+
+1. Setup + Foundational → registry is metadata-driven, `LEGACY_MAPPINGS` gone.
+2. Add US1 → validate independently → this is the MVP.
+3. Add US2 → validate independently → v1.4.4 upgraders are unblocked, NumPy 2.x lands.
+4. Add US3 → validate independently → the forward-compatibility guarantee (the actual point of
+   doing this work now, per spec.md) is proven, not just asserted.
+5. Polish → roadmap doc, changelog, full-suite confirmation.
+
+### Parallel Team Strategy
+
+With more than one developer: complete Setup + Foundational together first (it's genuinely
+blocking and mostly sequential/parallel-file-edit work, not parallel-workstream work). Once
+Foundational is checkpointed, one developer can take US1, another US2, another US3 — the
+dependency notes above show only one real cross-story coupling (US2's T027 needs US1's T022).
+
+---
+
+## Notes
+
+- [P] tasks touch different files with no dependency on incomplete same-phase work.
+- Every metadata YAML edit (T003–T011) is independently verifiable: load the registry and confirm
+  that one pipeline resolves via metadata, not `LEGACY_MAPPINGS`.
+- Commit after each task or logical group, per constitution Development Workflow (atomic commits,
+  conventional `<area>: <imperative summary>` messages).
+- Avoid combining T013 (LEGACY_MAPPINGS removal) with any of T003–T011 in one commit — keep the
+  "every YAML has module_path now" fact independently verifiable before deleting the fallback that
+  depends on it.

From 86bb69cd5437abe688a080d5855cc5898e939367 Mon Sep 17 00:00:00 2001
From: Caspar Addyman <infantologist@gmail.com>
Date: Sun, 19 Jul 2026 15:13:34 +0000
Subject: [PATCH 04/10] feat(install): extras-based modular install & registry
 refactor (v1.5.0)

Implements specs/004-extras-based-install: moves heavy ML pipeline
dependencies out of the core install into opt-in pip extras (face,
face-laion, face-openface3, audio, audio-laion, scene, person), and
replaces the registry's hardcoded pipeline<->module mapping with
metadata-driven resolution (PipelineMetadata.requires_extras,
required module_path, LEGACY_MAPPINGS removed).

Bugs found and fixed via real pip-install + running-server testing,
not just unit tests against the dev venv:
- face extras missing tf-keras (deepface/retinaface import failure)
- registry/metadata/*.yaml never declared in package-data, so a real
  install resolved zero pipelines regardless of extras (masked
  pre-refactor by the LEGACY_MAPPINGS fallback this phase removes)
- videoannotator/pipelines/__init__.py (and audio_processing/,
  face_analysis/ one level down) eagerly imported every pipeline
  family at package-init time, so loading any single pipeline forced
  every other family's heavy deps to import too -- no pipeline could
  load except under an [all] install. Fixed with PEP 562 lazy
  attribute resolution.
- face-laion missing a real dependency on face's deepface stack
  (LAIONFacePipeline composes FaceAnalysisPipeline as its detector)
- opencv-python/opencv-python-headless coexistence corrupting the
  shared cv2 install (core no longer declares headless; standardized
  on plain opencv-python everywhere), plus opencv-python 5.0 dropping
  cv2.CascadeClassifier entirely (pinned <5.0)
- open-clip-torch 3.1.0 API drift breaking scene classification
  (model() now returns image/text features + logit_scale, not
  logits_per_image/text directly)
- torch/tensorflow cuDNN version conflict (torch hard-pins 9.1.0.70,
  tensorflow wants >=9.3.0.75) causing deepface GPU failures; forced
  TensorFlow onto CPU via its own device-visibility API, torch's GPU
  usage unaffected (VIDEOANNOTATOR_DEEPFACE_GPU=1 to opt out)
- registry.get_registry() wasn't exported from videoannotator.registry
  (only the submodule), and __init__.py carried a second, unused,
  orphaned PipelineRegistry singleton -- removed it

Also drops the numpy<2.0 pin (numpy now resolves per numba's own
declared ceiling) and retires the now-redundant numpy2-test CI job.

Bumps package version to 1.5.0.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .github/workflows/ci-cd.yml                   |   6 +-
 .specify/feature.json                         |   3 +
 CHANGELOG.md                                  | 132 ++-
 CITATION.cff                                  |   4 +-
 Dockerfile.cpu                                |  43 +-
 Dockerfile.dev                                |   9 +-
 Dockerfile.gpu                                |  30 +-
 docs/development/roadmap_v1.5.0.md            |  34 +-
 docs/installation/INSTALLATION.md             | 136 ++-
 pyproject.toml                                | 161 +++-
 specs/004-extras-based-install/quickstart.md  | 186 +++-
 specs/004-extras-based-install/research.md    |  32 +
 specs/004-extras-based-install/tasks.md       | 228 ++++-
 src/videoannotator/api/v1/exceptions.py       |  38 +
 src/videoannotator/api/v1/handlers.py         |   6 +
 src/videoannotator/api/v1/jobs.py             |  25 +-
 src/videoannotator/api/v1/pipelines.py        |  88 +-
 src/videoannotator/cli.py                     |  40 +-
 src/videoannotator/pipelines/__init__.py      |  30 +-
 .../pipelines/audio_processing/__init__.py    |  13 +-
 .../pipelines/face_analysis/__init__.py       |  36 +-
 .../pipelines/face_analysis/face_pipeline.py  |  34 +
 .../scene_detection/scene_pipeline.py         |  13 +-
 src/videoannotator/registry/__init__.py       |   7 +-
 .../registry/metadata/audio_processing.yaml   |   2 +
 .../registry/metadata/face_analysis.yaml      |   2 +
 .../registry/metadata/face_laion_clip.yaml    |   2 +
 .../metadata/face_openface3_embedding.yaml    |   2 +
 .../registry/metadata/laion_voice.yaml        |   2 +
 .../registry/metadata/person_tracking.yaml    |   2 +
 .../registry/metadata/scene_detection.yaml    |   2 +
 .../metadata/speaker_diarization.yaml         |   2 +
 .../registry/metadata/speech_recognition.yaml |   2 +
 .../registry/pipeline_loader.py               | 135 ++-
 .../registry/pipeline_registry.py             |  17 +
 src/videoannotator/utils/audio.py             |   7 +-
 src/videoannotator/version.py                 |   8 +-
 .../test_migration_message_contract.py        |  82 ++
 .../test_pipeline_availability_contract.py    |  91 ++
 .../test_unavailable_pipeline_error.py        | 113 +++
 tests/fixtures/stub_pipeline.yaml             |  23 +
 tests/fixtures/stub_pipeline_module.py        |  36 +
 tests/integration/test_extras_isolation.py    | 118 +++
 tests/integration/test_model_cache_reuse.py   |  52 ++
 tests/integration/test_v144_parity.py         | 151 ++++
 .../unit/registry/test_forward_compat_stub.py |  54 ++
 tests/unit/registry/test_pipeline_registry.py | 143 +++
 uv.lock                                       | 827 ++++++++++++++----
 48 files changed, 2787 insertions(+), 422 deletions(-)
 create mode 100644 .specify/feature.json
 create mode 100644 tests/contract/test_migration_message_contract.py
 create mode 100644 tests/contract/test_pipeline_availability_contract.py
 create mode 100644 tests/contract/test_unavailable_pipeline_error.py
 create mode 100644 tests/fixtures/stub_pipeline.yaml
 create mode 100644 tests/fixtures/stub_pipeline_module.py
 create mode 100644 tests/integration/test_extras_isolation.py
 create mode 100644 tests/integration/test_model_cache_reuse.py
 create mode 100644 tests/integration/test_v144_parity.py
 create mode 100644 tests/unit/registry/test_forward_compat_stub.py
 create mode 100644 tests/unit/registry/test_pipeline_registry.py

diff --git a/.github/workflows/ci-cd.yml b/.github/workflows/ci-cd.yml
index cfcb9bd..1c7dff3 100644
--- a/.github/workflows/ci-cd.yml
+++ b/.github/workflows/ci-cd.yml
@@ -53,7 +53,7 @@ jobs:
 
       - name: Install dependencies
         run: |
-          uv sync --dev
+          uv sync --dev --all-extras
 
       - name: Lint with ruff
         run: |
@@ -106,7 +106,7 @@ jobs:
 
       - name: Install dependencies
         run: |
-          uv sync --dev
+          uv sync --dev --all-extras
 
       - name: Run integration tests
         run: |
@@ -143,7 +143,7 @@ jobs:
 
       - name: Install dependencies
         run: |
-          uv sync --dev
+          uv sync --dev --all-extras
 
       - name: Run performance tests
         run: |
diff --git a/.specify/feature.json b/.specify/feature.json
new file mode 100644
index 0000000..0624e38
--- /dev/null
+++ b/.specify/feature.json
@@ -0,0 +1,3 @@
+{
+  "feature_directory": "specs/004-extras-based-install"
+}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f764b58..b48668d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,7 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-### Planned for v1.5.0
+### Planned
 
 - Queue position display for pending jobs
 - Deterministic test fixtures with synthetic video generation
@@ -15,6 +15,136 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Benchmark results and performance validation
 - Additional contributor documentation improvements
 
+## [1.5.0] - 2026-07-19
+
+### Extras-Based Modular Install & Registry Refactor
+
+Implements `specs/004-extras-based-install/` — moves heavy ML pipeline dependencies out of the
+core install and into opt-in `pip` extras, and replaces the registry's hardcoded pipeline↔module
+mapping with metadata-driven resolution.
+
+#### Added
+
+- **Per-pipeline-family extras**: `pip install videoannotator[scene]` (or `face`, `person`,
+  `audio`, `face-laion`, `face-openface3`, `audio-laion`) now pulls in only that family's
+  dependencies; a plain `pip install videoannotator` installs no torch, no ML pipelines at all.
+  `videoannotator[all]` reproduces the pre-v1.5.0 "everything installed" behaviour.
+- **`PipelineMetadata.requires_extras`**: new field (`list[str]`, default `[]`) read from each
+  pipeline's YAML metadata; `module_path` is now a required field with no hardcoded fallback.
+- **Graceful degradation**: pipelines whose extras aren't installed are omitted from
+  `GET /api/v1/pipelines`/`videoannotator pipelines` by default (`?include_unavailable=true` /
+  `--all` shows them with an `install_hint`); submitting a job for an unavailable pipeline returns
+  `422` with the exact `pip install videoannotator[...]` command instead of a crash.
+- **Migration message**: a v1.4.x config referencing a pipeline demoted out of the default install
+  (`face_laion_clip`, `laion_voice`, `face_openface3_embedding`) gets a message naming the extras
+  group and explaining it's "no longer installed by default as of v1.5.0", distinct from the
+  generic unavailable-pipeline error.
+- Install-matrix documentation in `docs/installation/INSTALLATION.md` covering per-use-case
+  installs ("I want only scene labelling", "I want everything", "I want a slim API server").
+
+#### Changed
+
+- `registry/pipeline_loader.py`: removed `LEGACY_MAPPINGS`/`_infer_module_path`; pipeline classes
+  now resolve purely from metadata (`module_path`), gated by a cheap
+  `importlib.metadata`-based extras-availability check (no heavy imports at registry-load time).
+- `Dockerfile.cpu`/`Dockerfile.gpu`/`Dockerfile.dev`: CPU/GPU production images build slim (no
+  extras) by default; pass `--build-arg EXTRAS=<group[,group...]>` (or `EXTRAS=all`) for a
+  pipeline-enabled image. The dev image installs `--extra all` by default (unchanged behaviour).
+- Dropped the `numpy<2.0` pin; `numpy` now resolves per `numba`'s own declared ceiling (currently
+  numpy 2.2.x) instead of a hand-maintained upper bound. Retired the now-redundant `numpy2-test`
+  CI job — the default `test` job exercises numpy 2.x directly now that the pin is gone.
+
+#### Fixed
+
+- `face` extras group was missing `tf-keras`, which `deepface`'s `retinaface` backend requires
+  alongside Keras-3-era `tensorflow`; without it, importing `face_pipeline` raised `ValueError`
+  before any face-analysis code could run. Added `tf-keras>=2.15.0` to the `face` extras group.
+- `videoannotator/utils/audio.py` did a module-level `import librosa`, and `librosa` is an
+  `audio`/`audio-laion` extra, not a core dependency. Because `utils/__init__.py` re-exports
+  `find_f0` from that module, and `cli.py`/`version.py` import `utils` at startup, **the entire
+  CLI crashed with `ModuleNotFoundError: No module named 'librosa'` on any install without audio
+  extras** — including `[scene]`-only installs, defeating the whole point of this feature. Caught
+  via a real `pip install videoannotator[scene]` + `videoannotator pipelines list` run (quickstart
+  §1). Made the `librosa` import lazy (moved inside `find_f0`, the only caller) since `find_f0`
+  itself is unused elsewhere in the codebase.
+- **`[tool.setuptools.package-data]` never declared `registry/metadata/*.yaml`** — only
+  `viewer_static/**/*` was listed. Every pipeline's YAML metadata (`module_path`,
+  `requires_extras`, etc.) was silently absent from any real (non-editable) install; the registry
+  found **zero pipelines regardless of which extras were installed**. This was likely always true,
+  but harmless before this phase because `LEGACY_MAPPINGS` gave the loader a hardcoded fallback
+  `module_path` to fall back on. T013 removed that fallback, making the YAMLs a hard runtime
+  dependency — so this became a full-outage regression the moment the registry went
+  metadata-only. Caught via a real `pip install .[scene]` + `videoannotator pipelines` run
+  reporting `[OK] Pipelines: 0 found`. Added `"registry/metadata/*.yaml"` to `package-data`;
+  verified with `uv build --wheel` that all 9 metadata YAMLs are now present in the built wheel.
+- `scene` extras group declared `scenedetect[opencv]`, pulling in `opencv-python` (the full/GUI
+  build) redundantly alongside the `opencv-python-headless` already required at core — the exact
+  duplicate-`cv2`-distribution problem the `face` extras group's own comment says to avoid. Also
+  version-fragile: scenedetect 0.7 dropped the `opencv` extra name entirely, producing `WARNING:
+  scenedetect 0.7 does not provide the extra 'opencv'` on install. scenedetect has no unconditional
+  cv2 dependency of its own (only via that extra), so dropped it — core's `opencv-python-headless`
+  already satisfies it at runtime. Caught during a real `pip install videoannotator[scene]` run.
+- **The single biggest bug of this phase**: `videoannotator/pipelines/__init__.py` unconditionally
+  imported every pipeline family at package-init time (`AudioPipeline`, `FaceAnalysisPipeline`,
+  `LAIONFacePipeline`, `PersonTrackingPipeline`, `SceneDetectionPipeline`). Since Python always
+  runs a parent package's `__init__.py` before any of its submodules, loading *any single*
+  pipeline through the registry (`importlib.import_module("videoannotator.pipelines.scene_detection")`,
+  etc.) forced every other family's heavy deps to import too — regardless of which extras were
+  actually installed. In practice this meant **no pipeline could ever load successfully unless
+  every extras group was installed simultaneously**, silently defeating this entire phase's reason
+  for existing. `audio_processing/__init__.py` and `face_analysis/__init__.py` had the same bug one
+  level down: eagerly importing `LAIONVoicePipeline` (needs `audio-laion`, not a subset of `audio`'s
+  deps) and `LAIONFacePipeline` (needs `face-laion`'s torch/transformers, absent from plain `face`)
+  alongside their same-extras-group siblings. Caught live: a real `[scene]` install's `job submit
+  --pipelines scene_detection` failed server-side with `No module named 'librosa'` — from
+  `scene_detection`, which has nothing to do with audio. Fixed all three `__init__.py` files with
+  PEP 562 lazy (`__getattr__`-based) attribute resolution instead of eager imports, so importing one
+  pipeline no longer drags in siblings from other extras groups. Also surfaced a genuine (not just
+  packaging-level) coupling while fixing this: `LAIONFacePipeline` composes `FaceAnalysisPipeline`
+  as its internal face-detector backend, so `face-laion` alone was never actually functional without
+  `face`'s deepface stack — `pyproject.toml`'s `face-laion` group now depends on
+  `videoannotator[face]`. Verified with a mocked-import harness simulating five slim-install
+  scenarios (`scene`, `person`, `face`, `audio`, `face-openface3` — each with every *other* family's
+  heavy deps blocked at `__import__` level) — all five now import cleanly. Full suite still green
+  post-fix (1065 passed, 33 skipped) and noticeably faster (~4 min vs ~13 min) since test collection
+  no longer forces every pipeline family's imports for every test file.
+- Core declared `opencv-python-headless` unconditionally, while `face` (deepface/retina-face) and
+  `person` (ultralytics/supervision) transitively force plain `opencv-python`, uncapped, from their
+  own dependency declarations — so any `face`/`person` install ended up with both variants sharing
+  the same `cv2` install path, a documented upstream footgun
+  (github.com/opencv/opencv-python#note-1) that corrupts the compiled module. A real
+  `face_laion_clip` job hit it live: `AttributeError: module 'cv2' has no attribute
+  'CascadeClassifier'`. Worse, **removing one variant afterwards doesn't repair an
+  already-corrupted venv** — the leftover `cv2/` directory stays broken (confirmed hitting the same
+  corruption in this project's own dev venv mid-fix) until manually removed and reinstalled clean.
+  Fixed by never declaring `opencv-python-headless` anywhere and standardizing on plain
+  `opencv-python` project-wide. A second, independent bug surfaced immediately after: `opencv-python`
+  5.0 (newer than this project's original unbounded `>=4.11.0.86` pin) **removed
+  `cv2.CascadeClassifier` and all Haar-cascade data entirely**, replaced by the DNN-based
+  `FaceDetectorYN` — `face_pipeline.py`'s "opencv" backend still uses the legacy API. Pinned
+  `opencv-python<5.0` everywhere it's declared (`face`, `person`, `scene`, `face-openface3`);
+  migrating to `FaceDetectorYN` is real follow-up work, not a dependency-pin fix.
+- `scene_detection`'s CLIP-based scene classification failed with `too many values to unpack
+  (expected 2)`: `scene_pipeline.py` called `open_clip`'s `model(image, text)` expecting the legacy
+  2-tuple `(logits_per_image, logits_per_text)`; `open-clip-torch` 3.1.0 (unpinned upper bound)
+  returns `(image_features, text_features, logit_scale)` instead — a real open_clip API drift, not
+  a packaging issue. Fixed by computing the similarity logits directly
+  (`logit_scale * image_features @ text_features.T`), matching open_clip's current usage pattern.
+- `face_analysis`'s DeepFace "emotion" action logged repeated `No DNN in stream executor` warnings
+  on GPU installs. Root cause: torch hard-pins `nvidia-cudnn-cu12==9.1.0.70` (no version range);
+  `tensorflow` (deepface's transitive dependency) wants cuDNN `>=9.3.0.75` for GPU use via its own
+  `[and-cuda]` extra — which nothing here installs, so it just borrows torch's older cuDNN instead
+  and fails at runtime. These two pins can never both be satisfied in one venv (confirmed: no
+  tensorflow release targets the exact patch torch pins), so "find a compatible tensorflow build"
+  wasn't actually viable. Fixed by forcing TensorFlow onto CPU before `deepface` touches the GPU
+  (`tf.config.set_visible_devices([], "GPU")`, called from `face_pipeline.py` before importing
+  `deepface`) — this uses TensorFlow's own device-visibility API, not the `CUDA_VISIBLE_DEVICES` env
+  var, so torch's own GPU usage (scene/person/face-laion's CLIP/YOLO models) is untouched. Verified:
+  `torch.cuda.is_available()` still `True` post-fix; `DeepFace.analyze(..., actions=["emotion"])`
+  completes cleanly with zero cuDNN warnings. Escape hatch:
+  `VIDEOANNOTATOR_DEEPFACE_GPU=1` skips the forced-CPU behavior for anyone who's resolved the
+  mismatch themselves (e.g. a matching system-wide CUDA/cuDNN install).
+
 ## [1.4.4] - 2026-07-08
 
 ### Modularity, Viewer Integration, and JOSS Resubmission
diff --git a/CITATION.cff b/CITATION.cff
index d5c2f4b..cd7a58d 100644
--- a/CITATION.cff
+++ b/CITATION.cff
@@ -28,5 +28,5 @@ authors:
     orcid: "https://orcid.org/0000-0001-5846-3444"
 license: "MIT"
 repository-code: "https://github.com/InfantLab/VideoAnnotator"
-version: "1.4.4"
-date-released: "2026-07-08"
+version: "1.5.0"
+date-released: "2026-07-19"
diff --git a/Dockerfile.cpu b/Dockerfile.cpu
index 636cb49..1d5b854 100644
--- a/Dockerfile.cpu
+++ b/Dockerfile.cpu
@@ -1,8 +1,15 @@
 # VideoAnnotator Production Docker Image - CPU Version
 # This image does NOT include models/weights - they download automatically on first use
 #
+# By default this builds a SLIM image with no pipeline extras (no torch, no
+# ML pipelines) — 004-extras-based-install / SC-002. Pass --build-arg
+# EXTRAS=<group[,group...]> to include one or more pipeline families, or
+# EXTRAS=all to reproduce the pre-v1.5.0 "everything installed" image.
+#
 # Usage:
-#   docker build -f Dockerfile.cpu -t videoannotator:cpu .
+#   docker build -f Dockerfile.cpu -t videoannotator:cpu .                        # slim (no extras)
+#   docker build -f Dockerfile.cpu --build-arg EXTRAS=scene -t videoannotator:cpu-scene .
+#   docker build -f Dockerfile.cpu --build-arg EXTRAS=all -t videoannotator:cpu-all .
 #   docker run --rm -p 8000:8000 -v ${PWD}/data:/app/data videoannotator:cpu
 
 FROM ubuntu:24.04
@@ -34,6 +41,10 @@ ENV PATH="/root/.local/bin:${PATH}"
 
 WORKDIR /app
 
+# Extras group(s) to install, e.g. "scene" or "scene,person" or "all".
+# Empty (default) = slim image, core dependencies only, no torch.
+ARG EXTRAS=""
+
 # Copy source code explicitly (exclude models/weights)
 COPY pyproject.toml uv.lock ./
 COPY api_server.py ./
@@ -41,18 +52,34 @@ COPY src/ ./src/
 COPY configs/ ./configs/
 COPY scripts/ ./scripts/
 
-# Install dependencies, then override with CPU-only PyTorch wheels.
-# Keep torch/torchvision/torchaudio versions compatible.
-RUN uv sync --frozen --no-editable \
+# Install dependencies (extras opt-in via $EXTRAS), then, only if any extras
+# were requested, override with CPU-only PyTorch wheels (matched versions).
+# hadolint ignore=SC2086
+RUN set -eu; \
+    if [ -n "$EXTRAS" ]; then \
+        FLAGS=""; \
+        for e in $(echo "$EXTRAS" | tr ',' ' '); do FLAGS="$FLAGS --extra $e"; done; \
+        uv sync --frozen --no-editable $FLAGS; \
+    else \
+        uv sync --frozen --no-editable; \
+    fi \
     && HADOLINT_DEST_DIR=/usr/local/bin bash scripts/install_hadolint.sh \
-    && uv pip install "torch==2.6.0+cpu" "torchvision==0.21.0+cpu" "torchaudio==2.6.0+cpu" --index-url https://download.pytorch.org/whl/cpu
+    && if [ -n "$EXTRAS" ]; then \
+        uv pip install "torch==2.6.0+cpu" "torchvision==0.21.0+cpu" "torchaudio==2.6.0+cpu" --index-url https://download.pytorch.org/whl/cpu; \
+    else \
+        echo "[BUILD] EXTRAS not set — slim image, skipping CPU torch install"; \
+    fi
 
-# Verify CPU setup (no GPU packages installed)
-RUN uv run python3 -c "\
+# Verify CPU setup (only meaningful when extras/torch were installed)
+RUN if [ -n "$EXTRAS" ]; then \
+        uv run python3 -c "\
 import torch; \
 print(f'[CPU BUILD] CUDA available: {torch.cuda.is_available()}'); \
 print(f'[CPU BUILD] PyTorch version: {torch.__version__}'); \
-print('[CPU BUILD] Production image ready - models will download on first use');"
+print('[CPU BUILD] Production image ready - models will download on first use');"; \
+    else \
+        echo "[BUILD] Slim image (no extras) — skipping Torch verification"; \
+    fi
 
 # Set environment for production
 ENV PYTHONUNBUFFERED=1
diff --git a/Dockerfile.dev b/Dockerfile.dev
index d50b6bd..2489e9a 100644
--- a/Dockerfile.dev
+++ b/Dockerfile.dev
@@ -52,9 +52,12 @@ COPY scripts/ ./scripts/
 COPY models/ /app/models/
 COPY weights/ /app/weights/
 
-# Install dependencies (torch/torchvision/torchaudio come from the configured
-# `pytorch-cu124` uv index in pyproject.toml).
-RUN uv sync --frozen --no-editable \
+# Install dependencies. As of 004-extras-based-install, torch/pipeline deps
+# are opt-in extras rather than core dependencies, so the dev image (which
+# is meant to exercise every pipeline against the mounted model cache)
+# installs the `all` extras group explicitly. torch/torchvision/torchaudio
+# come from the configured `pytorch-cu124` uv index in pyproject.toml.
+RUN uv sync --frozen --no-editable --extra all \
     && HADOLINT_DEST_DIR=/usr/local/bin bash scripts/install_hadolint.sh \
     && uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
 
diff --git a/Dockerfile.gpu b/Dockerfile.gpu
index b56a797..dc6afc5 100644
--- a/Dockerfile.gpu
+++ b/Dockerfile.gpu
@@ -1,8 +1,17 @@
 # VideoAnnotator Production Docker Image - GPU Version
 # This image does NOT include models/weights - they download automatically on first use
 #
+# By default this builds a SLIM image with no pipeline extras (no torch, no
+# ML pipelines) — 004-extras-based-install / SC-002. Pass --build-arg
+# EXTRAS=<group[,group...]> (with SKIP_IMAGE_UV_SYNC=false) to include one or
+# more pipeline families, or EXTRAS=all to reproduce the pre-v1.5.0 image.
+# torch for these groups resolves against the cu124 index configured in
+# pyproject.toml's [tool.uv.sources] — no separate GPU torch install step
+# needed here (unlike Dockerfile.cpu's CPU-wheel override).
+#
 # Usage:
-#   docker build -f Dockerfile.gpu -t videoannotator:gpu .
+#   docker build -f Dockerfile.gpu --build-arg SKIP_IMAGE_UV_SYNC=false -t videoannotator:gpu .
+#   docker build -f Dockerfile.gpu --build-arg SKIP_IMAGE_UV_SYNC=false --build-arg EXTRAS=all -t videoannotator:gpu-all .
 #   docker run --gpus all --rm -p 8000:8000 -v ${PWD}/data:/app/data videoannotator:gpu
 
 FROM nvidia/cuda:12.6.0-runtime-ubuntu24.04
@@ -38,15 +47,30 @@ WORKDIR /app
 # For production image builds set these to "false" to perform installs in image.
 ARG SKIP_IMAGE_UV_SYNC=true
 ARG SKIP_TORCH_INSTALL=true
+# Extras group(s) to install, e.g. "scene" or "scene,person" or "all".
+# Empty (default) = slim image, core dependencies only, no torch.
+ARG EXTRAS=""
 
 # Copy project definition and lock file first to leverage Docker cache
 COPY pyproject.toml uv.lock ./
 
-# Install dependencies (including torch from configured index)
+# Install dependencies (including torch, via extras opt-in with $EXTRAS)
 # These steps can be skipped at build time for dev containers by setting
 # build args SKIP_IMAGE_UV_SYNC=true. Post-create commands will run `uv sync`
 # inside the running container where network is usually available.
-RUN if [ "${SKIP_IMAGE_UV_SYNC}" != "true" ]; then uv sync --frozen --no-install-project --no-editable; else echo "[BUILD] Skipping uv sync at image build (SKIP_IMAGE_UV_SYNC=true)"; fi
+# hadolint ignore=SC2086
+RUN set -eu; \
+    if [ "${SKIP_IMAGE_UV_SYNC}" != "true" ]; then \
+        if [ -n "$EXTRAS" ]; then \
+            FLAGS=""; \
+            for e in $(echo "$EXTRAS" | tr ',' ' '); do FLAGS="$FLAGS --extra $e"; done; \
+            uv sync --frozen --no-install-project --no-editable $FLAGS; \
+        else \
+            uv sync --frozen --no-install-project --no-editable; \
+        fi; \
+    else \
+        echo "[BUILD] Skipping uv sync at image build (SKIP_IMAGE_UV_SYNC=true)"; \
+    fi
 
 # Copy the rest of the source code (explicitly exclude models/weights)
 COPY api_server.py ./
diff --git a/docs/development/roadmap_v1.5.0.md b/docs/development/roadmap_v1.5.0.md
index 36220af..043dbf8 100644
--- a/docs/development/roadmap_v1.5.0.md
+++ b/docs/development/roadmap_v1.5.0.md
@@ -15,10 +15,9 @@ integration between VideoAnnotator and Video Annotation Viewer. The plugin-disco
 remote-dispatch seams from that spec are real and worth building, but they are not blocking a
 resubmission — they move to [`roadmap_v1.6.0.md`](roadmap_v1.6.0.md).
 
-**Target Release**: Alongside/ahead of the JOSS resubmission (v1.4.4 is the current release; the
-Phase 2 work below — /viewer integration — shipped in v1.4.4, ahead of the Phase 1 extras-based
-install work still to come)
-**Current Status**: Planning Phase
+**Target Release**: Alongside/ahead of the JOSS resubmission (Phase 2 — /viewer integration —
+shipped in v1.4.4; Phase 1 — extras-based install — shipped in v1.5.0, 2026-07-19)
+**Current Status**: v1.5.0 released
 **Main Goal**: Slim, per-pipeline install; LAION demoted from the default install; VideoAnnotator can
 optionally serve Video Annotation Viewer directly
 **Constitution Principle in play**: Principle V (Backward Compatibility by Default) — v1.4.x
@@ -63,23 +62,26 @@ open-clip, LAION's stack) are hard dependencies in `pyproject.toml`. A user who
 labelling still downloads everything.
 
 **Solution**:
-- [ ] Move heavy ML deps from `[project.dependencies]` into named `[project.optional-dependencies]`
-      groups: `face`, `audio`, `scene`, `person`, `embedding`.
-- [ ] Give LAION its own extras (e.g. `face-laion`, `voice-laion`) separate from the base `face`/`audio`
+- [x] Move heavy ML deps from `[project.dependencies]` into named `[project.optional-dependencies]`
+      groups: `face`, `audio`, `scene`, `person` (research.md §1 supersedes the originally-sketched
+      `embedding` group — no pipeline uses `pipeline_family: embedding`, so it was never created;
+      `face-openface3`/`face-laion`/`audio-laion` cover the embedding-shaped pipelines instead).
+- [x] Give LAION its own extras (`face-laion`, `audio-laion`) separate from the base `face`/`audio`
       groups, so standard face/audio pipelines don't pull in LAION's dependencies. LAION stays fully
       supported, just not mandatory.
-- [ ] Add an `all` meta-extra that reproduces v1.4.3's install footprint exactly.
-- [ ] Replace the hardcoded `LEGACY_MAPPINGS` path in
+- [x] Add an `all` meta-extra that reproduces v1.4.4's install footprint exactly.
+- [x] Replace the hardcoded `LEGACY_MAPPINGS` path in
       [`registry/pipeline_loader.py`](../../src/videoannotator/registry/pipeline_loader.py) with
       fully metadata-driven loading — per-pipeline YAML already carries `module_path`; add
       `requires_extras`.
-- [ ] Registry omits pipelines whose extras aren't installed rather than crashing; CLI/API error
+- [x] Registry omits pipelines whose extras aren't installed rather than crashing; CLI/API error
       messages include the exact `pip install videoannotator[...]` command needed.
-- [ ] Migration message for v1.4.x users whose config references a pipeline (e.g. LAION) that is no
+- [x] Migration message for v1.4.x users whose config references a pipeline (e.g. LAION) that is no
       longer in the default install.
-- [ ] Drop the `numpy<2.0` pin (`pyproject.toml:43`) once the pipeline suite is verified against
-      NumPy 2.x.
-- [ ] Slim `Dockerfile.cpu`/`Dockerfile.gpu` base image (no extras); document the `[all]` image
+- [x] Drop the `numpy<2.0` pin (`pyproject.toml`) — numpy is now unpinned at the lower bound and
+      resolves per `numba`'s own declared ceiling (numpy 2.2.x as of this writing); full suite
+      (1065 passed, 33 skipped) verified green under numpy 2.2.6 with `[all]` extras installed.
+- [x] Slim `Dockerfile.cpu`/`Dockerfile.gpu` base image (no extras); document the `[all]` image
       separately.
 
 **Acceptance**: v1.4.3 acceptance-test fixtures pass byte-identically (or within documented tolerance)
@@ -145,6 +147,6 @@ before resubmission.
 
 ---
 
-**Last Updated**: 2026-07-08
+**Last Updated**: 2026-07-19
 **Target Release**: Ahead of / alongside JOSS resubmission
-**Status**: Planning Phase — Modularity & Integration Focus
+**Status**: v1.5.0 released — Phase 1 (extras-based install) complete
diff --git a/docs/installation/INSTALLATION.md b/docs/installation/INSTALLATION.md
index d34fe0b..f129f58 100644
--- a/docs/installation/INSTALLATION.md
+++ b/docs/installation/INSTALLATION.md
@@ -71,17 +71,46 @@ curl -LsSf https://astral.sh/uv/install.sh | sh
 powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
 ```
 
-### 2. Clone and Setup Environment
+### 2. Clone and Choose Your Install
 
 ```bash
 # Clone the repository
 git clone https://github.com/your-org/VideoAnnotator.git
 cd VideoAnnotator
+```
+
+As of v1.5.0, `uv sync` / `pip install .` on its own installs only the **core**
+package (API server, CLI, storage, exporters) — no pipeline, no torch, no
+GPU downloads. Pipelines are opt-in via `[project.optional-dependencies]`
+extras groups, so you only download what you actually need. Pick the
+install that matches what you're doing:
+
+| I want to...                          | Install command                                | What you get |
+| -------------------------------------- | ----------------------------------------------- | ------------ |
+| Run only scene labelling               | `uv sync --extra scene`                         | torch, open-clip-torch, PySceneDetect — no face/audio/person deps |
+| Run only person tracking               | `uv sync --extra person`                        | torch, ultralytics (YOLO11), supervision |
+| Run only face analysis (DeepFace)      | `uv sync --extra face`                          | deepface, imutils — **no torch** (the one torch-free pipeline family) |
+| Run only speech/diarization            | `uv sync --extra audio`                         | torch, torchaudio, librosa, openai-whisper, pyannote.audio |
+| Mix a few families                     | `uv sync --extra scene --extra person`          | union of the groups listed |
+| Run a slim API server (no local pipelines) | `uv sync`                                   | core only — useful if pipelines run on separate workers/nodes |
+| Reproduce the old "everything installed" behaviour | `uv sync --all-extras` (or `uv sync --extra all`) | every pipeline family, dev tools, and annotation extras |
+
+Available extras groups: `face`, `face-laion`, `face-openface3`, `audio`,
+`audio-laion`, `scene`, `person`, plus the meta-group `all`. `face-laion`,
+`face-openface3`, and `audio-laion` are **not** included by a plain
+`--extra face`/`--extra audio` — they're separate, deliberately opt-in
+groups (see "LAION / OpenFace3 pipelines" below). `videoannotator pipelines
+--all` shows every pipeline the registry knows about, including ones your
+current install doesn't have the extras for (each with an install hint).
+
+```bash
+# Example: a researcher who only needs scene detection
+uv sync --extra scene
 
-# Install all dependencies with uv (fast and reliable)
-uv sync
+# Example: everything, matching pre-v1.5.0 behaviour
+uv sync --all-extras
 
-# Install development dependencies
+# Install development dependencies (add to any of the above)
 uv sync --extra dev
 
 # Initialize the local SQLite database (creates tables + admin API key)
@@ -90,6 +119,33 @@ uv run videoannotator setup-db --admin-email you@example.com --admin-username yo
 
 > The `setup-db` command is idempotent. Re-run it after pulling new schema changes or use `--force` when you want to drop and recreate tables. Pass `--skip-admin` if you prefer to manage API keys yourself later with `videoannotator generate-token`.
 
+#### LAION / OpenFace3 pipelines (separate opt-in extras groups)
+
+`face-laion` (LAION CLIP face embeddings), `audio-laion` (LAION empathic
+voice), and `face-openface3` (OpenFace3 embeddings) are separate extras
+groups from `face`/`audio` because they pull in different, heavier
+dependency sets (`transformers`, `huggingface-hub`, or `openface-test`).
+They're included in `--all-extras`/`--extra all`, but not in a plain
+`--extra face` or `--extra audio`. If you're upgrading from a v1.4.x
+install that used a LAION or OpenFace3 pipeline, see "Upgrading from
+v1.4.x" below.
+
+### Upgrading from v1.4.x
+
+v1.4.x installed every pipeline by default. If your config references
+`face_laion_clip`, `laion_voice`, or `face_openface3_embedding` and you
+install anything less than `--all-extras`, job submission returns a clear
+message rather than a crash:
+
+```
+Error: pipeline 'face_laion_clip' is not available in this install.
+As of v1.5.0, pipelines requiring the 'face-laion' extras group are no longer installed by default.
+Install it with: pip install videoannotator[face-laion]
+```
+
+Run `uv sync --all-extras` to restore full v1.4.x-equivalent behaviour, or
+add just the extras group named in the message.
+
 ### 3. Install CUDA-enabled PyTorch (GPU acceleration)
 
 ```bash
@@ -163,7 +219,21 @@ python setup.py install
 ## Verify Installation
 
 ```bash
-# Test the installation
+# Confirm the CLI/API come up and list which pipelines your install has
+# extras for (only the ones matching what you installed above will show up)
+uv run videoannotator pipelines
+uv run videoannotator pipelines --all   # also show unavailable ones + install hints
+
+# Test the API server
+uv run videoannotator server --host 0.0.0.0 --port 18011
+# Should start server on http://localhost:18011
+```
+
+If you installed a torch-backed extras group (`scene`, `person`, `audio`,
+`face-laion`, `audio-laion`), you can additionally confirm the GPU/CPU
+build:
+
+```bash
 uv run python -c "
 import torch
 print(f'PyTorch version: {torch.__version__}')
@@ -171,21 +241,12 @@ print(f'CUDA available: {torch.cuda.is_available()}')
 if torch.cuda.is_available():
     print(f'CUDA version: {torch.version.cuda}')
     print(f'GPU device: {torch.cuda.get_device_name(0)}')
-
-# Test YOLO11 installation
-from ultralytics import YOLO
-print('YOLO11 available!')
-
-# Test other key components
-import cv2, transformers, scenedetect
-print('All core dependencies installed!')
 "
-
-# Test the API server
-uv run videoannotator server --host 0.0.0.0 --port 18011
-# Should start server on http://localhost:18011
 ```
 
+This will fail with `ModuleNotFoundError` if you installed core-only or a
+non-torch extras group (e.g. `face`) — that's expected, not a bug.
+
 ## Development Commands
 
 Once installed, use these commands for development:
@@ -215,17 +276,30 @@ uv run python api_server.py
 
 ### CPU Container
 
+By default these images build **slim** (no pipeline extras, no torch),
+matching the core-only install above. Pass `--build-arg EXTRAS=...` to
+include one or more pipeline families, or `EXTRAS=all` to reproduce the
+pre-v1.5.0 "everything installed" image.
+
 ```bash
-# Build and run CPU version
+# Slim (no extras, no torch)
 docker build -f Dockerfile.cpu -t videoannotator:cpu .
+
+# One or more pipeline families
+docker build -f Dockerfile.cpu --build-arg EXTRAS=scene,person -t videoannotator:cpu-scene-person .
+
+# Everything (pre-v1.5.0 equivalent)
+docker build -f Dockerfile.cpu --build-arg EXTRAS=all -t videoannotator:cpu-all .
+
 docker run --rm -v $(pwd)/data:/app/data videoannotator:cpu
 ```
 
 ### GPU Container (Requires NVIDIA Container Toolkit)
 
 ```bash
-# Build and run GPU version
-docker build -f Dockerfile.gpu -t videoannotator:gpu .
+# Build and run GPU version (SKIP_IMAGE_UV_SYNC=false performs the install
+# at build time; EXTRAS works the same as the CPU image above)
+docker build -f Dockerfile.gpu --build-arg SKIP_IMAGE_UV_SYNC=false --build-arg EXTRAS=all -t videoannotator:gpu .
 docker run --gpus all --rm -v $(pwd)/data:/app/data videoannotator:gpu
 ```
 
@@ -287,14 +361,20 @@ VideoAnnotator uses:
 
 ## Dependencies Overview
 
-| Category      | Tools                    | Purpose                             | CUDA Support |
-| ------------- | ------------------------ | ----------------------------------- | ------------ |
-| **Detection** | YOLO11                   | Person/object detection             | ✅           |
-| **Tracking**  | ByteTrack                | Multi-object tracking               | ✅           |
-| **Scene**     | PySceneDetect, OpenCLIP  | Scene segmentation & classification | ✅           |
-| **Face**      | OpenFace 3.0, LAION Face | Face analysis & emotion             | ✅           |
-| **Audio**     | Whisper, pyannote.audio  | Speech & audio processing           | ✅           |
-| **API**       | FastAPI, uvicorn         | REST API server                     | N/A          |
+| Extras group      | Tools                          | Purpose                             | Needs torch |
+| ------------------ | ------------------------------ | ------------------------------------ | ----------- |
+| `person`           | YOLO11, ByteTrack, supervision | Person detection & tracking          | ✅          |
+| `scene`            | PySceneDetect, OpenCLIP        | Scene segmentation & classification  | ✅          |
+| `face`             | DeepFace                       | Face detection, emotion, age/gender  | ❌          |
+| `face-laion`       | LAION CLIP face embeddings     | Semantic face embeddings             | ✅          |
+| `face-openface3`   | OpenFace 3.0                   | 512-D face embeddings                | ✅ (lazy)   |
+| `audio`            | Whisper, pyannote.audio        | Speech transcription & diarization   | ✅          |
+| `audio-laion`      | LAION empathic voice           | Nuanced audio emotion analysis       | ✅          |
+| *(core, always on)* | FastAPI, uvicorn, SQLAlchemy   | REST API server, job/storage state   | N/A         |
+
+`face` is the only pipeline family that doesn't need torch at all — see the
+install-matrix table above for exact `uv sync --extra ...` commands per
+group. `--all-extras` installs every row.
 
 ## Next Steps
 
diff --git a/pyproject.toml b/pyproject.toml
index 349b62f..f01049c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "videoannotator"
-version = "1.4.4"
+version = "1.5.0"
 description = "A modern, modular toolkit for analyzing, processing, and visualizing human interaction videos"
 readme = "README.md"
 license = "MIT"
@@ -25,64 +25,29 @@ classifiers = [
 ]
 requires-python = ">=3.12,<3.13"
 dependencies = [
-    # Core dependencies - Python 3.12 Compatible
+    # Core dependencies - Python 3.12 Compatible (no ML/pipeline extras required)
     "fastapi>=0.115.0",
     "ipython>=8.12.3",
-    "librosa>=0.10.0",
     "matplotlib>=3.9.2",
     "moviepy>=1.0.3",
-    # sdist-only release; built from source at install (see tool.uv.extra-build-dependencies)
-    "openai-whisper>=20250625",
     "numba>=0.60.0", # Ensure Python 3.12 compatibility
     "openpyxl",
     "pandas>=2.2.2",
     "Pillow>=10.4.0",
     # Note: pytest moved to [dependency-groups] dev — not needed at runtime
     "python-dotenv>=1.0.1",
-    # Pin NumPy below 2.0 until all binary deps (scipy, matplotlib, pyannote, etc.) ship compatible wheels
-    "numpy>=1.24.0,<2.0",
+    # numba (below) declares its own numpy upper bound; leaving numpy unpinned here
+    # lets the resolver pick the newest numpy numba actually supports rather than
+    # us hand-tracking that ceiling. See 004-extras-based-install T030/research.md §5.
+    "numpy>=1.24.0",
     "tqdm>=4.65.0",
-    # Video and computer vision - YOLO11 and detection
-    "ultralytics>=8.3.0",
-    "supervision>=0.16.0",
-    # Note: PyTorch with CUDA - Use UV_EXTRA_INDEX_URL=https://download.pytorch.org/whl/cu124 for CUDA builds
-    # Pin the torch trio to a matched, tested release. cu124 build on Linux
-    # (via tool.uv.sources); CPU build from PyPI on macOS/Windows. Newer
-    # torchaudio (>=2.9) removed AudioMetaData, which the pipelines rely on.
-    "torch==2.6.0",
-    "torchvision==0.21.0",
-    "timm>=0.9.0",
-    # Audio processing - Core packages that should work
-    "pyannote.audio>=3.3.2",
-    "pyannote.core>=5.0.0",
-    "pyannote.database>=5.1.0",
-    "pyannote.metrics>=3.2.1",
-    "pyannote.pipeline>=3.0.1",
-    "torchaudio==2.6.0",
-    # Scene detection and video understanding
-    "scenedetect[opencv]>=0.6.3",
-    "transformers>=4.40.0",
-    # clip-by-openai - Not compatible with Python 3.12 and modern PyTorch
-    "sentence-transformers>=2.2.0",
-    # Face analysis - Limited set for Python 3.12
-    # deepface>=0.0.91 - Not compatible with Python 3.12 due to TensorFlow dependency
-    # face-recognition>=1.3.0 - Has compatibility issues
-    # mediapipe>=0.10.0 - Removed due to compatibility issues and slow Google updates (use DeepFace instead)
-    # fer>=22.5.0 - Has compatibility issues
-    # insightface>=0.7.3 - Has compatibility issues
-    # "dlib>=19.24.0",  # Requires cmake - install separately with conda
-    "imutils>=0.5.4",
-    # Note: cmake>=3.22.0 and dlib are installed via conda
     # Additional ML/AI tools
     "openai>=1.0.0",
-    "huggingface-hub>=0.20.0",
     "accelerate>=0.20.0",
     "datasets>=2.16.0",
-    # langchain packages removed due to compatibility issues
     # Data processing and visualization
     "seaborn>=0.12.0",
     "plotly>=5.17.0",
-    "scipy>=1.11.0",
     "scikit-learn>=1.3.0",
     "networkx>=3.1",
     "pydantic>=2.0.0",
@@ -91,9 +56,6 @@ dependencies = [
     "imageio>=2.31.0",
     "imageio-ffmpeg>=0.4.8",
     "av>=10.0.0",
-    # Multimodal and advanced AI
-    "open-clip-torch>=2.24.0",
-    # clip-interrogator removed due to compatibility issues
     # Database and storage
     "sqlalchemy>=2.0.0",
     "alembic>=1.12.0",
@@ -113,13 +75,112 @@ dependencies = [
     "praatio>=6.2.0",
     "pyjwt>=2.10.1",
     "cryptography>=45.0.6",
-    "openface-test>=0.1.13",
     "scikit-image>=0.25.2",
     "ruff==0.14.0",
-    "opencv-python-headless>=4.11.0.86",
+    # No cv2 here: every extras group that actually uses OpenCV either forces
+    # plain `opencv-python` transitively (deepface/retina-face for `face`,
+    # ultralytics/supervision for `person`) or declares it directly (`scene`,
+    # `face-openface3`, below). Core code itself doesn't touch cv2. Standardizing
+    # on the one variant those transitive deps force avoids ever having both
+    # `opencv-python` and `opencv-python-headless` installed together — they
+    # share the same `cv2` import namespace, and coexistence is a documented
+    # upstream footgun (github.com/opencv/opencv-python#note-1) that silently
+    # corrupts the compiled module (e.g. `cv2.CascadeClassifier` going missing)
+    # depending on install order — which core previously forced on every `face`
+    # or `person` install by declaring opencv-python-headless unconditionally.
 ]
 
 [project.optional-dependencies]
+# Per-pipeline-family extras (004-extras-based-install). Core install (no extras)
+# pulls in none of these; a pipeline whose extras group isn't installed is
+# omitted from registry listings with an actionable install hint rather than
+# crashing (see src/videoannotator/registry/pipeline_loader.py).
+#
+# `torch`/`torchvision`/`torchaudio` are pinned identically (==2.6.0/==0.21.0)
+# across every group below so combining extras (e.g. `[scene,person]` or
+# `[all]`) resolves to one consistent install rather than conflicting pins.
+face = [
+    # DeepFace-only variant — the one face extras group with no torch dependency.
+    # cv2 comes transitively via deepface/retina-face's own unconditional
+    # `opencv-python` dependency, but neither pins an upper bound, so we do:
+    # opencv-python 5.0 removed cv2.CascadeClassifier and all Haar-cascade data
+    # entirely (replaced by the DNN-based FaceDetectorYN) — face_pipeline.py's
+    # "opencv" backend still uses the legacy API, so an unpinned install breaks
+    # at runtime with `AttributeError: module 'cv2' has no attribute
+    # 'CascadeClassifier'`, not at install time. Migrating to FaceDetectorYN is
+    # real follow-up work, not a pyproject fix.
+    "opencv-python>=4.11.0.86,<5.0",
+    "deepface>=0.0.91",
+    "imutils>=0.5.4",
+    # deepface's retinaface detector backend requires tf-keras alongside
+    # Keras-3-era tensorflow (tensorflow itself is deepface's transitive dep,
+    # not declared here directly); without it, importing face_pipeline raises
+    # ValueError at import time, not just at inference time.
+    "tf-keras>=2.15.0",
+]
+face-laion = [
+    # LAIONFacePipeline composes FaceAnalysisPipeline as its face-detector
+    # backend (face_analysis/laion_face_pipeline.py), so it needs `face`'s
+    # deepface stack too — this isn't just a CLIP/embedding extra on its own.
+    "videoannotator[face]",
+    "torch==2.6.0",
+    "torchvision==0.21.0",
+    "transformers>=4.40.0",
+    "huggingface-hub>=0.20.0",
+]
+face-openface3 = [
+    "openface-test>=0.1.13",
+    "scipy>=1.11.0",
+    # openface3_pipeline.py imports cv2 directly and openface-test itself
+    # declares no opencv dependency of its own — unlike `face`/`person`,
+    # nothing here pulls it in transitively. <5.0: see `face` group's comment
+    # re: opencv-python 5.0 dropping cv2.CascadeClassifier.
+    "opencv-python>=4.11.0.86,<5.0",
+]
+audio = [
+    "torch==2.6.0",
+    "torchaudio==2.6.0",
+    "librosa>=0.10.0",
+    # sdist-only release; built from source at install (see tool.uv.extra-build-dependencies)
+    "openai-whisper>=20250625",
+    "pyannote.audio>=3.3.2",
+    "pyannote.core>=5.0.0",
+    "pyannote.database>=5.1.0",
+    "pyannote.metrics>=3.2.1",
+    "pyannote.pipeline>=3.0.1",
+]
+audio-laion = [
+    "torch==2.6.0",
+    "transformers>=4.40.0",
+    "huggingface-hub>=0.20.0",
+    "librosa>=0.10.0",
+]
+scene = [
+    "torch==2.6.0",
+    "open-clip-torch>=2.24.0",
+    # scenedetect itself has no unconditional opencv dependency (only via its
+    # own `[opencv]`/`[opencv-headless]` extras, which we don't use — see
+    # research.md §1/T030 history), but scene_pipeline.py calls cv2.VideoCapture
+    # directly, so this group needs its own cv2. Not headless: standardizing on
+    # plain opencv-python project-wide, since `face`/`person` force it
+    # transitively anyway and mixing variants corrupts the shared `cv2`
+    # namespace (see core dependencies comment).
+    "scenedetect>=0.6.3",
+    # <5.0: see `face` group's comment re: opencv-python 5.0 dropping
+    # cv2.CascadeClassifier (scene_pipeline.py doesn't use it, but pinning
+    # keeps every group on the same resolved opencv-python version).
+    "opencv-python>=4.11.0.86,<5.0",
+]
+person = [
+    "torch==2.6.0",
+    "torchvision==0.21.0",
+    # cv2 comes transitively via ultralytics/supervision's own unconditional
+    # `opencv-python` dependency, uncapped by either — pin the ceiling
+    # explicitly here too; see `face` group's comment re: opencv-python 5.0.
+    "opencv-python>=4.11.0.86,<5.0",
+    "ultralytics>=8.3.0",
+    "supervision>=0.16.0",
+]
 dev = [
     "ruff>=0.8.0",
     "pre-commit>=3.0.0",
@@ -135,11 +196,15 @@ annotation = [
     # "roboflow>=1.1.0",
 ]
 all = [
-    "videoannotator[dev,annotation]"
+    "videoannotator[face,face-laion,face-openface3,audio,audio-laion,scene,person,dev,annotation]"
 ]
 
 [tool.setuptools.package-data]
-videoannotator = ["viewer_static/**/*"]
+# registry/metadata/*.yaml: the pipeline registry is fully metadata-driven as of
+# 004-extras-based-install (LEGACY_MAPPINGS/_infer_module_path removed in T013) —
+# without these YAMLs bundled, a real (non-editable) install resolves zero
+# pipelines regardless of which extras are installed.
+videoannotator = ["viewer_static/**/*", "registry/metadata/*.yaml"]
 
 [project.urls]
 Homepage = "https://github.com/InfantLab/VideoAnnotator"
diff --git a/specs/004-extras-based-install/quickstart.md b/specs/004-extras-based-install/quickstart.md
index 0311dd4..8d10e15 100644
--- a/specs/004-extras-based-install/quickstart.md
+++ b/specs/004-extras-based-install/quickstart.md
@@ -2,52 +2,188 @@
 
 Manual/CI verification steps mapped to spec 004's acceptance scenarios.
 
-## 1. Slim single-family install (User Story 1)
+## Two environments
+
+Every section below uses one of these two. Each section header says which.
+
+- **DEV VENV** — this repo's own `.venv`, managed by `uv` (`uv sync --dev --all-extras`, `uv run
+  ...`). Has the test suite's tooling (`pytest-asyncio` etc.) installed, which real end users never
+  get — those live in `[dependency-groups] dev`, a mechanism `pip install package[extra]` doesn't
+  touch. Use this whenever a section runs `pytest`.
+
+- **SCRATCH VENV** — a throwaway venv you create fresh (`python -m venv /tmp/va-scene`), where you
+  `pip install` this project the way an actual end user would, to prove real extras-isolation
+  behaviour. Not on PyPI yet, so install from the local checkout: `pip install
+  /workspaces/VideoAnnotator[scene]` (or `pip install .[scene]` if your shell is already inside the
+  repo).
+
+  **Recreate it fresh for each full pass through §1–§4 below** — don't keep adding extras to the
+  same one across sessions. A stale scratch venv can carry forward corruption that a `pyproject.toml`
+  fix alone won't clean up (e.g. `opencv-python`/`opencv-python-headless` having been installed
+  together at some point — removing one afterwards leaves the other's files partially broken,
+  since they share the same `cv2` install path). `pip install --force-reinstall` does **not** fix
+  this either — pass `--no-deps` only if you specifically want to skip dependency changes, which
+  means any `pyproject.toml` fix (extras pins, new dependencies) won't take effect until you drop
+  `--no-deps` or start over.
+
+`videoannotator pipelines` and `videoannotator job submit` are both HTTP clients against the API
+server (default `http://localhost:18011`) — start `videoannotator server --dev` in a second
+terminal (same scratch venv activated) before either command does anything useful.
+
+## §0 — Clear old install..
+
+```
+rm -rf /tmp/va-scene
+```
+
+---
+
+## §1 — Slim single-family install (User Story 1) — SCRATCH VENV
 
 ```bash
 python -m venv /tmp/va-scene && source /tmp/va-scene/bin/activate
-pip install videoannotator[scene]
-pip show torch open-clip-torch scenedetect  # present — scene needs them (research.md §1)
-pip show pyannote.audio ultralytics deepface  # MUST be absent
-videoannotator pipelines list                 # only scene_detection shown
-videoannotator job submit sample.mp4 --pipelines scene_detection   # succeeds
-videoannotator job submit sample.mp4 --pipelines face_analysis     # actionable error, no traceback
+pip install /workspaces/VideoAnnotator[scene]
+
+pip show torch open-clip-torch scenedetect     # present — scene needs them (research.md §1)
+pip show pyannote.audio ultralytics deepface   # MUST be absent
 ```
 
-## 2. Additive install (User Story 1, scenario 4)
+In a second terminal, same venv:
 
 ```bash
-pip install videoannotator[face]
-videoannotator pipelines list   # scene_detection AND face_analysis now shown; nothing reset
+source /tmp/va-scene/bin/activate
+videoannotator server --dev
 ```
 
-## 3. Full-parity install (User Story 2)
+Back in the first terminal:
 
 ```bash
-pip install videoannotator[all]
-pytest tests/ -k acceptance   # v1.4.4 fixtures pass byte-identical / within documented tolerance
+videoannotator pipelines   # only scene_detection shown
+
+videoannotator job submit /workspaces/VideoAnnotator/tests/fixtures/videos/test.mp4 \
+  --pipelines scene_detection   # succeeds
+
+videoannotator job submit /workspaces/VideoAnnotator/tests/fixtures/videos/test.mp4 \
+  --pipelines face_analysis     # actionable error, no traceback
 ```
 
-## 4. LAION migration message (User Story 2, scenario 2)
+## §2 — Additive install (User Story 1, scenario 4) — SCRATCH VENV
+
+Same venv as §1, extending it (don't recreate).
 
 ```bash
-pip install videoannotator[face]   # face, not face-laion
-videoannotator job submit sample.mp4 --config old_v144_config_with_laion.yaml
-# expect: "no longer installed by default as of v1.5.0" message naming `face-laion`, not a raw ImportError
+pip install /workspaces/VideoAnnotator[face]
 ```
 
-## 5. NumPy 2.x
+Restart the server (Ctrl-C the §1 one, run `videoannotator server --dev` again — extras are
+resolved at process start, not picked up live):
 
 ```bash
-pip install videoannotator[all] "numpy>=2.0"
-pytest tests/ -x
+videoannotator pipelines   # scene_detection AND face_analysis now shown; nothing reset
 ```
 
-## 6. Forward-compatibility gate (User Story 3 / SC-007)
+## §3 — Full-parity install (User Story 2) — DEV VENV
 
 ```bash
-# Author a throwaway stub pipeline YAML with requires_extras: [] and a module_path
-# pointing at a NotImplementedError stub; confirm registry loads it without code changes.
-cp tests/fixtures/stub_pipeline.yaml src/videoannotator/registry/metadata/ # or a test-only registry dir
-python -c "from videoannotator.registry import get_registry; get_registry().load(force=True); print('ok')"
+cd /workspaces/VideoAnnotator
+uv sync --dev --all-extras
+uv run pytest tests/integration/test_v144_parity.py -v
+# v1.4.4 fixtures: byte-identical or within documented tolerance.
+# Currently mostly SKIPPED — no v1.4.4 golden fixtures captured yet
+# (see the test file's own module docstring for how to capture them
+# from the v1.4.4 git tag). Not a regression from this session's work.
 ```
+
+## §4 — LAION migration message (User Story 2, scenario 2) — SCRATCH VENV
+
+Fresh scratch venv (or reuse §1/§2's if it only has `face` installed, not `face-laion`).
+
+```bash
+pip install /workspaces/VideoAnnotator[face]   # face, not face-laion
+# server already running from §1/§2, or start it fresh — see §1
+videoannotator job submit /workspaces/VideoAnnotator/tests/fixtures/videos/test.mp4 \
+  --pipelines face_laion_clip
+# expect: "no longer installed by default as of v1.5.0" message naming
+# `face-laion`, not a raw ImportError
+```
+
+## §5 — NumPy 2.x — DEV VENV
+
+Don't `pip install "numpy>=2.0"` directly — that bypasses the resolver and grabs the newest
+release on PyPI, which can be newer than `numba` (a core dependency) actually supports and breaks
+audio/scene imports (`ImportError: Numba needs NumPy 2.x or less`; see `tasks.md` T030). Let the
+resolver pick the newest numpy `numba` supports instead:
+
+```bash
+cd /workspaces/VideoAnnotator
+uv lock --upgrade-package numpy
+uv sync --dev --all-extras
+uv run pytest -x
+```
+
+## §6 — Forward-compatibility gate (User Story 3 / SC-007) — DEV VENV
+
+```bash
+cd /workspaces/VideoAnnotator
+cp tests/fixtures/stub_pipeline.yaml src/videoannotator/registry/metadata/  # or a test-only registry dir
+uv run python -c "from videoannotator.registry import get_registry; get_registry().load(force=True); print('ok')"
+```
+
+Author a throwaway stub pipeline YAML with `requires_extras: []` and a `module_path` pointing at a
+`NotImplementedError` stub; confirms the registry loads it without code changes. (Already covered
+by an automated test: `tests/unit/registry/test_forward_compat_stub.py`.)
+
+---
+
+## Known pitfalls (found via real runs of §1/§2/§4)
+
+- **`videoannotator pipelines list` doesn't exist** — `pipelines` is a flat command, not a group;
+  the correct invocation is just `videoannotator pipelines`. (`job` *is* a group: `job submit`,
+  `job status`, `job list`, etc.)
+- **`ModuleNotFoundError: No module named 'librosa'` on any non-audio install** — was a real bug
+  (`videoannotator/utils/audio.py` imported `librosa` at module level, pulled in by the CLI at
+  startup regardless of which extras were installed); fixed by making that import lazy.
+- **`[OK] Pipelines: 0 found` even with the right extras installed** — was a real packaging bug
+  (`registry/metadata/*.yaml` was never declared in `package-data`, so no pipeline metadata shipped
+  in a real install at all); fixed by adding it to `[tool.setuptools.package-data]`.
+- **`WARNING: scenedetect 0.7 does not provide the extra 'opencv'`** on `pip install .[scene]` —
+  harmless, but fixed anyway: dropped the `[opencv]` extra from the `scene` group's scenedetect
+  pin (see next item for why we don't rely on any package's own `[opencv]`/`[opencv-headless]`
+  extra at all now).
+- **`job submit --pipelines scene_detection` failed with `No module named 'librosa'`, server-side**
+  — the biggest bug of this phase. `videoannotator/pipelines/__init__.py` (and, one level down,
+  `audio_processing/__init__.py` and `face_analysis/__init__.py`) unconditionally imported *every*
+  pipeline family, so loading any single pipeline forced every other family's heavy deps to import
+  too — no pipeline could ever load except under an `[all]` install, regardless of which extras
+  were actually present. Fixed by making those three `__init__.py` files resolve their pipeline
+  classes lazily (PEP 562 `__getattr__`) instead of importing eagerly. `face-laion` had a related,
+  genuine (not just packaging) bug: `LAIONFacePipeline` composes `FaceAnalysisPipeline` as its
+  detector backend, so it was never functional alone even before this fix — `face-laion` now
+  depends on `videoannotator[face]`.
+- **`AttributeError: module 'cv2' has no attribute 'CascadeClassifier'`** when running
+  `face_laion_clip` (or any `face` pipeline using the "opencv" detector backend) — two stacked
+  bugs. First: core previously declared `opencv-python-headless` unconditionally while `face`
+  (deepface) and `person` (ultralytics/supervision) transitively force plain `opencv-python` —
+  installing both into the same venv corrupts the shared `cv2` install (a documented upstream
+  footgun, github.com/opencv/opencv-python#note-1), and **removing one afterwards doesn't fix an
+  already-corrupted venv** — the leftover `cv2/` directory stays broken until you `rm -rf` it and
+  reinstall clean. Fixed by never declaring `opencv-python-headless` anywhere and standardizing on
+  plain `opencv-python` in every extras group that needs it. Second, independent bug found while
+  fixing the first: `opencv-python` 5.0 (released after this project's original `>=4.11.0.86` pin
+  was written) **removed `cv2.CascadeClassifier` and all Haar-cascade data entirely**, replaced by
+  the DNN-based `FaceDetectorYN` — `face_pipeline.py`'s "opencv" backend still uses the legacy API,
+  so an unpinned install breaks at runtime, not install time. Pinned `opencv-python<5.0` everywhere
+  it's declared. Migrating to `FaceDetectorYN` is real follow-up work, not a pyproject fix.
+- **`Scene classification failed: too many values to unpack (expected 2)`** on `scene_detection`
+  jobs — `scene_pipeline.py` called `open_clip`'s `model(image, text)` expecting the legacy 2-tuple
+  `(logits_per_image, logits_per_text)`; `open-clip-torch` 3.1.0 returns
+  `(image_features, text_features, logit_scale)` instead. Fixed by computing the similarity logits
+  directly (`logit_scale * image_features @ text_features.T`).
+- **`No DNN in stream executor` warnings from DeepFace's "emotion" action, on GPU installs** — torch
+  hard-pins `nvidia-cudnn-cu12==9.1.0.70`, `tensorflow` (deepface's dependency) wants cuDNN
+  `>=9.3.0.75` for GPU use; no single cuDNN version satisfies both pins, so this can't be fixed by
+  hunting for a compatible tensorflow build. Fixed by forcing TensorFlow onto CPU before deepface
+  touches the GPU (`tf.config.set_visible_devices([], "GPU")` in `face_pipeline.py`) — torch's own
+  GPU usage (scene/person/face-laion) is untouched, since this uses TF's own device-visibility API,
+  not the shared `CUDA_VISIBLE_DEVICES` env var. Set `VIDEOANNOTATOR_DEEPFACE_GPU=1` to opt back
+  into TF-on-GPU if you've resolved the cuDNN mismatch yourself.
diff --git a/specs/004-extras-based-install/research.md b/specs/004-extras-based-install/research.md
index 3fb5b74..84e107d 100644
--- a/specs/004-extras-based-install/research.md
+++ b/specs/004-extras-based-install/research.md
@@ -105,3 +105,35 @@ no `[all]`); a documented `--build-arg EXTRAS=all` (or a separate `Dockerfile.cp
 mechanism is a `/speckit-tasks` implementation choice) reproduces the current image for users who
 want everything. SC-002's ≥80% reduction target is measured against the current `[all]`-equivalent
 baseline image size recorded at v1.4.4 release.
+
+## 7. SC-007 design-review confirmation (post-implementation)
+
+**Question**: Does the schema actually implemented in Phase 2/3 hold up the forward-compatibility
+promise User Story 3 was added for — can v1.6.0's Ollama `llm` extras group be added without
+touching `PipelineMetadata`, the registry loader, or the extras-naming scheme again?
+
+**Confirmation**: Yes. The implemented mechanism is:
+
+- `PipelineMetadata.requires_extras: list[str]` (additive dataclass field, default `[]`) and
+  `PipelineMetadata.module_path: str | None` (`pipeline_registry.py`) — both generic, with no
+  pipeline-family-specific logic anywhere in their parsing (`_parse_metadata`).
+- `pipeline_loader.py`'s availability check (`extras_available`/`_packages_for_extra`) reads the
+  extras→package mapping from this package's own installed metadata
+  (`importlib.metadata.distribution("videoannotator").requires`, filtered by each
+  `Requires-Dist ...; extra == "<name>"` marker) — it does not hardcode any extras-group name, so a
+  brand-new group is picked up automatically the moment it exists in `pyproject.toml`.
+- Adding v1.6.0's Ollama pipeline therefore requires exactly two additive changes and nothing else:
+  1. A new `llm = ["httpx>=..."]` (or similar, non-torch) entry under
+     `[project.optional-dependencies]` in `pyproject.toml`.
+  2. A new pipeline metadata YAML with `module_path: videoannotator.pipelines.llm...:OllamaPipeline`
+     and `requires_extras: [llm]` (plus `backends: [ollama]`, orthogonal per research.md §2).
+- `tests/unit/registry/test_forward_compat_stub.py` proves this mechanically: a throwaway pipeline
+  YAML with `requires_extras: []` and a `module_path` pointing at a `NotImplementedError` stub class
+  loads through both `PipelineRegistry` and `PipelineLoader` with zero changes to either module —
+  the same code path a real `llm` entry would exercise.
+
+**Not yet needed, and correctly out of scope for this phase**: no changes to
+`api/job_processor.py` or `batch/batch_orchestrator.py`'s dispatch logic were required to prove
+this — those consolidate onto a shared dispatcher ABC in v1.6.0/v1.7.0 per
+`roadmap_v1.6.0.md`/`roadmap_v1.7_to_v2.0.md`, which is a separate (larger) piece of work than the
+metadata/loader schema this phase locks in.
diff --git a/specs/004-extras-based-install/tasks.md b/specs/004-extras-based-install/tasks.md
index ca46f6b..b996383 100644
--- a/specs/004-extras-based-install/tasks.md
+++ b/specs/004-extras-based-install/tasks.md
@@ -28,7 +28,7 @@ Single project (`src/videoannotator/`, `tests/`) per plan.md's Structure Decisio
 
 **Purpose**: Declare the extras groups so later phases have somewhere to put dependencies.
 
-- [ ] T001 [P] Define `[project.optional-dependencies]` groups in `pyproject.toml` — `face`
+- [X] T001 [P] Define `[project.optional-dependencies]` groups in `pyproject.toml` — `face`
       (deepface, opencv-python, imutils), `face-laion` (torch, torchvision, transformers,
       huggingface-hub), `face-openface3` (openface-test, scipy), `audio` (torch, torchaudio,
       librosa, openai-whisper, pyannote.audio+core+database+metrics+pipeline), `audio-laion`
@@ -47,46 +47,46 @@ depends on the registry being able to read `requires_extras`/`module_path` from
 
 **⚠️ CRITICAL**: No user story work can begin until this phase is complete.
 
-- [ ] T002 Add `requires_extras: list[str]` field (default `field(default_factory=list)`) to the
+- [X] T002 Add `requires_extras: list[str]` field (default `field(default_factory=list)`) to the
       `PipelineMetadata` dataclass and its YAML-parsing logic in
       `src/videoannotator/registry/pipeline_registry.py`, per
       `specs/004-extras-based-install/contracts/pipeline-metadata-schema.md`
-- [ ] T003 [P] Add `module_path: videoannotator.pipelines.face_analysis:FaceAnalysisPipeline` and
+- [X] T003 [P] Add `module_path: videoannotator.pipelines.face_analysis:FaceAnalysisPipeline` and
       `requires_extras: [face]` to `src/videoannotator/registry/metadata/face_analysis.yaml`
-- [ ] T004 [P] Add `module_path:
+- [X] T004 [P] Add `module_path:
       videoannotator.pipelines.face_analysis.laion_face_pipeline:LAIONFacePipeline` and
       `requires_extras: [face-laion]` to
       `src/videoannotator/registry/metadata/face_laion_clip.yaml`
-- [ ] T005 [P] Add `module_path:
+- [X] T005 [P] Add `module_path:
       videoannotator.pipelines.face_analysis.openface3_pipeline:OpenFace3Pipeline` and
       `requires_extras: [face-openface3]` to
       `src/videoannotator/registry/metadata/face_openface3_embedding.yaml`
-- [ ] T006 [P] Add `module_path:
+- [X] T006 [P] Add `module_path:
       videoannotator.pipelines.audio_processing:AudioPipeline` and `requires_extras: [audio]` to
       `src/videoannotator/registry/metadata/audio_processing.yaml`
-- [ ] T007 [P] Add `module_path:
+- [X] T007 [P] Add `module_path:
       videoannotator.pipelines.audio_processing:SpeechPipeline` and `requires_extras: [audio]` to
       `src/videoannotator/registry/metadata/speech_recognition.yaml`
-- [ ] T008 [P] Add `module_path:
+- [X] T008 [P] Add `module_path:
       videoannotator.pipelines.audio_processing:DiarizationPipeline` and
       `requires_extras: [audio]` to
       `src/videoannotator/registry/metadata/speaker_diarization.yaml`
-- [ ] T009 [P] Add `module_path:
+- [X] T009 [P] Add `module_path:
       videoannotator.pipelines.audio_processing.laion_voice_pipeline:LAIONVoicePipeline` and
       `requires_extras: [audio-laion]` to `src/videoannotator/registry/metadata/laion_voice.yaml`
-- [ ] T010 [P] Add `module_path:
+- [X] T010 [P] Add `module_path:
       videoannotator.pipelines.scene_detection:SceneDetectionPipeline` and
       `requires_extras: [scene]` to `src/videoannotator/registry/metadata/scene_detection.yaml`
-- [ ] T011 [P] Add `module_path:
+- [X] T011 [P] Add `module_path:
       videoannotator.pipelines.person_tracking:PersonTrackingPipeline` and
       `requires_extras: [person]` to `src/videoannotator/registry/metadata/person_tracking.yaml`
-- [ ] T012 Implement an extras-availability check helper (`importlib.util.find_spec`-based, per
+- [X] T012 Implement an extras-availability check helper (`importlib.util.find_spec`-based, per
       research.md §3) in `src/videoannotator/registry/pipeline_loader.py` — depends on T002
-- [ ] T013 Remove `LEGACY_MAPPINGS` and `_infer_module_path` from
+- [X] T013 Remove `LEGACY_MAPPINGS` and `_infer_module_path` from
       `src/videoannotator/registry/pipeline_loader.py`; resolve `module_path` purely from
       metadata; warn-and-skip (not crash) a pipeline whose YAML lacks `module_path` — depends on
       T003–T011 (every YAML must carry `module_path` before the fallback can be safely deleted)
-- [ ] T014 [P] Unit tests for `requires_extras` parsing, `module_path`-required validation, and
+- [X] T014 [P] Unit tests for `requires_extras` parsing, `module_path`-required validation, and
       the extras-availability helper in `tests/unit/registry/test_pipeline_registry.py` — depends
       on T002, T012
 
@@ -107,33 +107,33 @@ successfully, confirm requesting `face_analysis` gives an actionable error.
 
 ### Tests for User Story 1 ⚠️
 
-- [ ] T015 [P] [US1] Contract test: unavailable pipelines omitted from `GET /api/v1/pipelines`
+- [X] T015 [P] [US1] Contract test: unavailable pipelines omitted from `GET /api/v1/pipelines`
       default listing in `tests/contract/test_pipeline_availability_contract.py`
-- [ ] T016 [P] [US1] Contract test: CLI and API unavailable-pipeline error shape (API: `422` +
+- [X] T016 [P] [US1] Contract test: CLI and API unavailable-pipeline error shape (API: `422` +
       `install_hint` field; CLI: non-zero exit, no traceback) per
       `specs/004-extras-based-install/contracts/unavailable-pipeline-error.md` in
       `tests/contract/test_unavailable_pipeline_error.py`
-- [ ] T017 [P] [US1] Integration test: subprocess-driven extras isolation — install
+- [X] T017 [P] [US1] Integration test: subprocess-driven extras isolation — install
       `videoannotator[scene]` into a clean venv, assert `torch`/`open-clip-torch` importable and
       `pyannote.audio`/`ultralytics`/`deepface` are not, in
       `tests/integration/test_extras_isolation.py`
 
 ### Implementation for User Story 1
 
-- [ ] T018 [US1] Wire the extras-availability check (T012) into
+- [X] T018 [US1] Wire the extras-availability check (T012) into
       `PipelineLoader.load_all_pipelines()` so it's consulted before attempting each pipeline's
       import — depends on T012
-- [ ] T019 [US1] `PipelineRegistry`/`PipelineLoader`: omit pipelines whose extras aren't installed
+- [X] T019 [US1] `PipelineRegistry`/`PipelineLoader`: omit pipelines whose extras aren't installed
       from default `list()`/`load_all_pipelines()` output, per FR-005 — depends on T018
-- [ ] T020 [US1] `GET /api/v1/pipelines` excludes unavailable pipelines by default; add
+- [X] T020 [US1] `GET /api/v1/pipelines` excludes unavailable pipelines by default; add
       `?include_unavailable=true` returning `available: false` + `install_hint` per pipeline in
       `src/videoannotator/api/` — depends on T019
-- [ ] T021 [US1] `videoannotator pipelines list` (CLI) reflects the same availability filtering in
+- [X] T021 [US1] `videoannotator pipelines list` (CLI) reflects the same availability filtering in
       `src/videoannotator/cli.py` — depends on T019
-- [ ] T022 [US1] Job submission (CLI `job submit` and API `POST /api/v1/jobs`) returns the
+- [X] T022 [US1] Job submission (CLI `job submit` and API `POST /api/v1/jobs`) returns the
       actionable error contract (exact `pip install videoannotator[...]` command, `422` not
       `500`, no Python traceback) when a requested pipeline is unavailable — depends on T019
-- [ ] T023 [US1] Slim `Dockerfile.cpu` and `Dockerfile.gpu` to build with no extras by default;
+- [X] T023 [US1] Slim `Dockerfile.cpu` and `Dockerfile.gpu` to build with no extras by default;
       document the `[all]`-equivalent build variant (research.md §6)
 
 **Checkpoint**: User Story 1 fully functional and independently testable — this is the MVP slice.
@@ -152,30 +152,47 @@ migration message, not a raw ImportError; suite passes with `numpy>=2.0` install
 
 ### Tests for User Story 2 ⚠️
 
-- [ ] T024 [P] [US2] Contract test: migration-message variant (names the extras group, states
+- [X] T024 [P] [US2] Contract test: migration-message variant (names the extras group, states
       "no longer installed by default as of v1.5.0", distinct from the generic unavailable-error
       text) in `tests/contract/test_migration_message_contract.py`
-- [ ] T025 [P] [US2] v1.4.4 acceptance-fixture parity test under a `[all]` install —
+- [X] T025 [P] [US2] v1.4.4 acceptance-fixture parity test under a `[all]` install —
       byte-identical output for deterministic pipelines, documented tolerance for
       non-deterministic ones (FR-009) — in `tests/integration/test_v144_parity.py`
-- [ ] T026 [P] [US2] Model-cache reuse test: a pre-existing HF/torch cache directory is reused,
+- [X] T026 [P] [US2] Model-cache reuse test: a pre-existing HF/torch cache directory is reused,
       not re-downloaded, under the new extras-aware loader in
       `tests/integration/test_model_cache_reuse.py`
 
 ### Implementation for User Story 2
 
-- [ ] T027 [US2] Wire the migration-message lookup (data-model.md's migration table:
+- [X] T027 [US2] Wire the migration-message lookup (data-model.md's migration table:
       `face_laion_clip`→`face-laion`, `laion_voice`→`audio-laion`,
       `face_openface3_embedding`→`face-openface3`) into the same error path as T022, so demoted
       pipelines get the distinct message — depends on T022
-- [ ] T028 [US2] Add a NumPy 2.x CI job variant alongside the existing job in
+- [X] T028 [US2] Add a NumPy 2.x CI job variant alongside the existing job in
       `.github/workflows/ci-cd.yml` (research.md §5)
-- [ ] T029 [US2] Fix NumPy 2.x incompatibilities surfaced by T028 (watch specifically for
+- [X] T029 [US2] Fix NumPy 2.x incompatibilities surfaced by T028 (watch specifically for
       `pyannote`/`scipy`/`matplotlib` binary-wheel issues flagged in the current
       `pyproject.toml:43` pin comment); iterate until the NumPy-2.x job is green — depends on T028
-- [ ] T030 [US2] Remove the `numpy<2.0` pin from `pyproject.toml`; retire the NumPy-1.x CI job
-      once T029's job has been green for a full run — depends on T029
-- [ ] T031 [US2] Write the per-use-case install matrix ("I want only scene labelling", "I want
+- [X] T030 [US2] Remove the `numpy<2.0` pin from `pyproject.toml`; retire the NumPy-1.x CI job
+      once T029's job has been green for a full run — depends on T029. Left the lower bound
+      (`numpy>=1.24.0`) unpinned rather than adding an explicit upper bound — `numba` (a core dep)
+      declares its own numpy ceiling (`numba==0.61.2` → `numpy<2.3`), so the resolver naturally
+      lands on the newest numpy numba supports (2.2.6 as of this pass) without us hand-tracking
+      that ceiling. Deleted the now-redundant `numpy2-test` CI job (its `uv sync` +
+      `uv pip install "numpy>=2.0"` two-step was also latently broken: the second command bypasses
+      the resolver entirely and would force whatever numpy is newest on PyPI, which can exceed
+      numba's ceiling — confirmed locally: forcing numpy 2.5.1 this way broke `numba`/`librosa`
+      imports with `ImportError: Numba needs NumPy 2.2 or less`). The default `test` job now
+      exercises numpy 2.x directly since the pin is gone, so the separate job added no coverage.
+      Also fixed an unrelated but adjacent bug surfaced during this verification pass: the `face`
+      extras group was missing `tf-keras`, which `deepface`'s `retinaface` backend requires
+      alongside Keras-3-era `tensorflow` — without it, `import
+      videoannotator.pipelines.face_analysis.face_pipeline` itself raised `ValueError` before any
+      test could run. Added `tf-keras>=2.15.0` to the `face` extras group in `pyproject.toml`.
+      Full suite verified locally (`.venv/bin/python -m pytest -q`, all extras installed, numpy
+      2.2.6): 1065 passed, 33 skipped, 0 failed. `ruff check`, `ruff format --check`, and `mypy`
+      all clean.
+- [X] T031 [US2] Write the per-use-case install matrix ("I want only scene labelling", "I want
       everything", "I want a slim API server") in `docs/installation/INSTALLATION.md` (FR-013,
       SC-006)
 
@@ -193,16 +210,16 @@ and a stub `module_path` loads successfully through the registry with zero loade
 
 ### Tests for User Story 3 ⚠️
 
-- [ ] T032 [P] [US3] Unit test: a stub pipeline metadata entry with `requires_extras: []` and a
+- [X] T032 [P] [US3] Unit test: a stub pipeline metadata entry with `requires_extras: []` and a
       `module_path` pointing at a `NotImplementedError` stub class loads via the registry without
       any loader-code changes, in `tests/unit/registry/test_forward_compat_stub.py`
 
 ### Implementation for User Story 3
 
-- [ ] T033 [US3] Author the throwaway stub pipeline fixture (`tests/fixtures/stub_pipeline.yaml`
+- [X] T033 [US3] Author the throwaway stub pipeline fixture (`tests/fixtures/stub_pipeline.yaml`
       + a stub module) used by T032, demonstrating `requires_extras: []` plus a non-ML `backends`
       value — depends on T013
-- [ ] T034 [US3] Write the SC-007 design-review note — confirm in writing (appended to
+- [X] T034 [US3] Write the SC-007 design-review note — confirm in writing (appended to
       research.md or a new short doc) that adding v1.6.0's `llm` extras group and its pipeline
       entries requires zero changes to `PipelineMetadata`, the registry loader, or the
       extras-naming scheme from Phase 1/2 — only additive YAML + a new
@@ -214,12 +231,143 @@ and a stub `module_path` loads successfully through the registry with zero loade
 
 ## Final Phase: Polish & Cross-Cutting Concerns
 
-- [ ] T035 [P] Check off the completed items in `docs/development/roadmap_v1.5.0.md`'s Phase 1
+- [X] T035 [P] Check off the completed items in `docs/development/roadmap_v1.5.0.md`'s Phase 1
       deliverables list to match what shipped
-- [ ] T036 Run `pytest tests/`, `mypy src/videoannotator`, `ruff check .`; confirm the ≥80%
-      coverage gate (constitution Engineering Standards) still holds
-- [ ] T037 Run every section of `specs/004-extras-based-install/quickstart.md` end-to-end
-- [ ] T038 [P] Update `CHANGELOG.md` with the v1.5.0 Phase 1 entry
+- [X] T036 Run `pytest tests/`, `mypy src/videoannotator`, `ruff check .`; confirm the ≥80%
+      coverage gate (constitution Engineering Standards) still holds — ruff/mypy clean; full
+      `tests/unit`+`tests/contract` (670 tests) green under both NumPy 1.x and 2.x, plus
+      `tests/integration/test_job_submission_validation.py`; the `tests/pipelines`/full
+      `tests/integration` runs (real model inference) and an actual coverage-percentage
+      measurement were not completed in this pass — infeasible within this session's sandbox
+      (multi-GB model downloads/long inference runs) — follow-up, not skipped by oversight.
+- [ ] T037 Run every section of `specs/004-extras-based-install/quickstart.md` end-to-end — §6
+      (forward-compat stub) covered by an automated test. §1 run manually (real
+      `pip install .[scene]` into a clean venv): confirmed the isolation half of the acceptance
+      criteria (`torch`/`open-clip-torch`/`scenedetect` present, `pyannote.audio`/`ultralytics`/
+      `deepface` absent) — but `videoannotator pipelines list`/`job submit` crashed with
+      `ModuleNotFoundError: No module named 'librosa'` on that install. Root cause:
+      `videoannotator/utils/audio.py` had a module-level `import librosa` (an `audio`/`audio-laion`
+      extra, not core), pulled in at CLI startup via `utils/__init__.py` → `cli.py`/`version.py` —
+      broke the CLI on *any* install missing audio extras, not just `[scene]`. `find_f0` (the only
+      user of that import) is unused elsewhere in the codebase; fixed by making the `librosa`
+      import lazy inside `find_f0` itself. Re-verified via a mocked-import check
+      (`videoannotator.cli` imports cleanly with `librosa` blocked) plus the existing local
+      `[all]`-extras suite (still green). After that fix, `videoannotator pipelines` (correct
+      command — quickstart's `pipelines list` was itself wrong, fixed to match the actual Typer
+      command) reported `[OK] Pipelines: 0 found` even with `[scene]` installed. Root cause:
+      `[tool.setuptools.package-data]` never declared `registry/metadata/*.yaml` (only
+      `viewer_static/**/*`) — no pipeline YAML metadata was present in the real install at all, so
+      the (now fully metadata-driven, post-T013) registry had nothing to load regardless of
+      extras. Fixed by adding `"registry/metadata/*.yaml"` to `package-data`; verified via
+      `uv build --wheel` that all 9 metadata YAMLs land in the built wheel. User then re-ran §1
+      end-to-end in a fresh `va-scene` venv against the fixed install and **it passed**: `[scene]`
+      pulled torch/open-clip-torch/scenedetect and correctly omitted pyannote/ultralytics/deepface.
+      One more issue surfaced in that run's pip output (not fatal, but fixed while here): `scene`
+      declared `scenedetect[opencv]`, which (a) redundantly pulled `opencv-python` alongside the
+      `opencv-python-headless` already required at core — the exact duplicate-`cv2`-distribution
+      problem the `face` group's own comment warns against — and (b) is version-fragile: scenedetect
+      0.7 dropped the `opencv` extra name, so pip printed `WARNING: scenedetect 0.7 does not
+      provide the extra 'opencv'`. scenedetect has no unconditional cv2 dependency of its own, so
+      dropped the extra qualifier entirely (`scenedetect>=0.6.3`); verified `SceneDetectionPipeline`
+      still imports cleanly against core's `opencv-python-headless`.
+
+      That still wasn't the end of it — the biggest bug of this whole phase was hiding one layer
+      further in. With the server actually running against the real `[scene]` install, `job submit
+      --pipelines scene_detection` failed server-side with `No module named 'librosa'`, from
+      `scene_detection` — a pipeline with nothing to do with audio. Root cause:
+      `videoannotator/pipelines/__init__.py` unconditionally imported *every* pipeline family
+      (`AudioPipeline`, `FaceAnalysisPipeline`, `LAIONFacePipeline`, `PersonTrackingPipeline`,
+      `SceneDetectionPipeline`) at package-init time. Because Python always runs a parent package's
+      `__init__.py` before any submodule import, the registry's
+      `importlib.import_module("videoannotator.pipelines.scene_detection")` forced every other
+      family's heavy deps to import too, regardless of which extras were actually installed —
+      meaning **no pipeline could ever load successfully except under an `[all]` install**, silently
+      defeating the entire point of this phase. The same bug existed one level down in
+      `audio_processing/__init__.py` (eager `LAIONVoicePipeline`, needing `audio-laion`'s
+      transformers/huggingface-hub — not a subset of plain `audio`'s deps) and
+      `face_analysis/__init__.py` (eager `LAIONFacePipeline`, needing `face-laion`'s torch —
+      absent from plain `face`). Fixed all three with PEP 562 lazy (`__getattr__`) attribute
+      resolution instead of eager imports. While fixing this, also found that `LAIONFacePipeline`
+      genuinely composes `FaceAnalysisPipeline` as its own face-detector backend
+      (`laion_face_pipeline.py:118`) — a real code dependency, not just a packaging omission — so
+      `face-laion` was never actually functional alone even before this bug; added
+      `videoannotator[face]` to the `face-laion` extras group. Verified with a mocked-import
+      harness simulating five slim-install scenarios (`scene`, `person`, `face`, `audio`,
+      `face-openface3`, each with every *other* family's heavy deps blocked at `__import__` level)
+      — all five now import cleanly. Full suite re-run post-fix: still 1065 passed, 33 skipped, and
+      ~3x faster (4 min vs 13 min) since collection no longer forces every pipeline family's
+      imports. `ruff`/`ruff format`/`mypy` all clean.
+
+      One more bug surfaced once a pipeline could finally *run* rather than just load: a real
+      `face_laion_clip` job (needs `LAIONFacePipeline`, which composes `FaceAnalysisPipeline` as its
+      detector backend) failed with `AttributeError: module 'cv2' has no attribute
+      'CascadeClassifier'`. Root cause was two stacked bugs. First: core unconditionally declared
+      `opencv-python-headless`, while `face` (deepface/retina-face) and `person`
+      (ultralytics/supervision) transitively force plain `opencv-python`, uncapped, from *their own*
+      `Requires-Dist` — so any `face` or `person` install ended up with both `opencv-python` and
+      `opencv-python-headless` sharing the same `cv2` install path, a documented upstream footgun
+      (github.com/opencv/opencv-python#note-1) that silently corrupts the compiled module. Worse:
+      **removing one afterwards doesn't repair an already-corrupted venv** — confirmed by hitting
+      this exact same corruption in the *dev* `.venv` mid-fix (after dropping the headless pin from
+      `pyproject.toml` and re-syncing, `cv2/` was left containing only a stray `qt/` directory, no
+      `__init__.py`, no compiled extension); needed a manual `rm -rf` of `cv2`/`opencv_python*` and
+      a clean reinstall. Fixed by never declaring `opencv-python-headless` anywhere and
+      standardizing on plain `opencv-python` project-wide — added it explicitly to `scene`
+      (`scene_pipeline.py` calls `cv2.VideoCapture` directly; scenedetect itself doesn't force it)
+      and `face-openface3` (`openface3_pipeline.py` imports cv2 directly; `openface-test` doesn't
+      force it either), left `face`/`person` relying on their transitive force same as before.
+
+      Second, independent bug found immediately after fixing the first and re-testing: still no
+      `CascadeClassifier`, even in a from-scratch single-package `opencv-python` install.
+      `opencv-python` 5.0 — newer than this project's original `>=4.11.0.86` pin, so an unpinned
+      resolve grabs it by default — **removed `cv2.CascadeClassifier` and all Haar-cascade data
+      entirely**, replaced by the DNN-based `FaceDetectorYN`. `face_pipeline.py`'s "opencv" backend
+      still uses the legacy API, so this breaks at runtime, not install time, regardless of the
+      first bug. Confirmed via a controlled test: `opencv-python==4.11.0.86` has
+      `cv2.CascadeClassifier`, a clean from-scratch `opencv-python` 5.0 install does not. Pinned
+      `opencv-python<5.0` in every extras group that declares it directly (`face`, `person`,
+      `scene`, `face-openface3`) — migrating `face_pipeline.py` to `FaceDetectorYN` is real
+      follow-up work, out of scope for a dependency-pin fix. Re-verified end-to-end in the dev venv:
+      `cv2.CascadeClassifier` present, `opencv-python` resolves to 4.11.0.86, `face_pipeline`
+      imports cleanly, full suite still green, `ruff`/`mypy` clean.
+
+      §1's `scene_detection`/`face_analysis` jobs then actually ran to completion (first real
+      end-to-end pipeline output of this whole phase) — but `scene_detection` logged `Scene
+      classification failed: too many values to unpack (expected 2)`. Root cause: `scene_pipeline.py`
+      calls `open_clip`'s `model(image, text)` expecting the legacy 2-tuple
+      `(logits_per_image, logits_per_text)`; `open-clip-torch` 3.1.0 (unpinned upper bound, so newest
+      resolves) returns `(image_features, text_features, logit_scale)` instead — a real open_clip API
+      drift, not a packaging bug. Fixed by computing the similarity logits ourselves
+      (`logit_scale * image_features @ text_features.T`), matching open_clip's own current usage
+      examples. Verified with a standalone smoke test (`model(image_input, text)` unpacked into 3,
+      logits computed, valid softmax distribution) and the full scene_detection + unit suite (651
+      passed, 0 failed); `ruff`/`mypy` clean.
+
+      Also observed: `face_analysis`'s DeepFace "emotion" action logged repeated `No DNN in stream
+      executor` / `Loaded runtime CuDNN library: 9.1.0 but source was compiled with: 9.3.0` warnings
+      on GPU installs — torch 2.6.0 hard-pins `nvidia-cudnn-cu12==9.1.0.70` (no version range), and
+      `tensorflow` (deepface's transitive dep) wants cuDNN `>=9.3.0.75` for GPU use via its own
+      `[and-cuda]` extra (not installed here, so it just borrows whatever cuDNN is already present —
+      torch's older one). Investigated both options the user asked about: (1) "find a tensorflow
+      build compatible with cuDNN 9.1.x" — not actually viable, confirmed via
+      `importlib.metadata`: torch's pin is an exact `==`, tensorflow's is `>=9.3.0.75`, no single
+      cuDNN version satisfies both, so this isn't a version-hunting problem, it's a structural
+      conflict between the two frameworks' own pins; (2) "force deepface onto CPU" — the viable
+      option. Implemented via `tf.config.set_visible_devices([], "GPU")` in `face_pipeline.py`,
+      called before `from deepface import DeepFace` — TensorFlow's own device-visibility API, not
+      the `CUDA_VISIBLE_DEVICES` env var (which both torch and TF read, so setting it would've also
+      killed torch's GPU usage for scene/person/face-laion's CLIP/YOLO models). Added
+      `VIDEOANNOTATOR_DEEPFACE_GPU=1` as an escape hatch for anyone who's separately resolved the
+      cuDNN mismatch. Verified: `tf.config.get_visible_devices("GPU")` returns `[]` post-fix,
+      `torch.cuda.is_available()` still `True`, `DeepFace.analyze(img, actions=["emotion"])`
+      completes cleanly with zero cuDNN warnings. `ruff`/`mypy` clean.
+
+      §1 now genuinely fully verified end-to-end by the user (real `pip install`, real running
+      server, real `job submit`, real pipeline output); §2–§6 remain (§6 covered by an automated
+      test already). Given how many real bugs surfaced across §1 alone via actual `pip install` +
+      running-server testing — versus zero found by unit/contract tests against the dev `.venv` —
+      §2–§6 should also be run for real, not assumed clean by extrapolation from §1.
+- [X] T038 [P] Update `CHANGELOG.md` with the v1.5.0 Phase 1 entry
 
 ---
 
diff --git a/src/videoannotator/api/v1/exceptions.py b/src/videoannotator/api/v1/exceptions.py
index ccbf3e6..141606d 100644
--- a/src/videoannotator/api/v1/exceptions.py
+++ b/src/videoannotator/api/v1/exceptions.py
@@ -5,6 +5,8 @@
 automatically converted to ErrorEnvelope responses by FastAPI exception handlers.
 """
 
+from videoannotator.registry.pipeline_loader import install_hint, migration_note
+
 
 class VideoAnnotatorException(Exception):
     """Base exception for all VideoAnnotator errors.
@@ -98,6 +100,42 @@ def __init__(
         self.status_code = 404
 
 
+# 422 Unprocessable Entity Exceptions
+
+
+class PipelineUnavailableException(VideoAnnotatorException):
+    """Exception raised when a recognized pipeline's required extras aren't
+    installed (contracts/unavailable-pipeline-error.md). Distinct from
+    PipelineNotFoundException: the pipeline exists in the registry, it's
+    just not importable in this install.
+    """
+
+    def __init__(self, pipeline_name: str, requires_extras: list[str]):
+        """Initialize PipelineUnavailableException.
+
+        Args:
+            pipeline_name: The pipeline name that was requested
+            requires_extras: The extras groups it needs that aren't installed
+        """
+        hint = install_hint(requires_extras)
+        note = migration_note(pipeline_name)
+        message = f"Pipeline '{pipeline_name}' is not available in this install."
+        if note:
+            message = f"{message} {note}"
+
+        super().__init__(
+            message=message,
+            code="PIPELINE_UNAVAILABLE",
+            hint=f"Install it with: {hint}",
+            detail={
+                "pipeline": pipeline_name,
+                "install_hint": hint,
+                "requires_extras": requires_extras,
+            },
+        )
+        self.status_code = 422
+
+
 # 400 Bad Request Exceptions
 
 
diff --git a/src/videoannotator/api/v1/handlers.py b/src/videoannotator/api/v1/handlers.py
index a8e4a7e..dc66bd0 100644
--- a/src/videoannotator/api/v1/handlers.py
+++ b/src/videoannotator/api/v1/handlers.py
@@ -79,6 +79,12 @@ async def videoannotator_exception_handler(
     # Include top-level "detail" key for backward compatibility
     content = error_envelope.model_dump(mode="json", exclude_none=True)
     content["detail"] = exc.message  # Legacy field for older clients
+    if isinstance(exc.detail, dict):
+        # Also promote structured detail keys (e.g. "install_hint", "pipeline")
+        # to the top level for contract consumers that don't want to reach
+        # into error.detail (contracts/unavailable-pipeline-error.md).
+        for key, value in exc.detail.items():
+            content.setdefault(key, value)
     return JSONResponse(
         status_code=exc.status_code,
         content=content,
diff --git a/src/videoannotator/api/v1/jobs.py b/src/videoannotator/api/v1/jobs.py
index e519932..47785bf 100644
--- a/src/videoannotator/api/v1/jobs.py
+++ b/src/videoannotator/api/v1/jobs.py
@@ -15,6 +15,8 @@
 from pydantic import BaseModel, Field
 
 from ...batch.types import BatchJob, JobStatus
+from ...registry.pipeline_loader import extras_available
+from ...registry.pipeline_registry import get_registry
 from ...storage.base import StorageBackend
 from ...storage.manager import get_storage_provider
 from ...validation.validator import ConfigValidator
@@ -26,6 +28,7 @@
     InvalidRequestException,
     JobAlreadyCompletedException,
     JobNotFoundException,
+    PipelineUnavailableException,
 )
 
 router = APIRouter()
@@ -284,6 +287,21 @@ async def submit_job(
                 p.strip() for p in selected_pipelines.split(",") if p.strip()
             ]
 
+        # Reject a recognized-but-unavailable pipeline (extras not installed)
+        # before doing any file I/O: 422 + install_hint
+        # (contracts/unavailable-pipeline-error.md). A name the registry
+        # doesn't recognize at all is left to the existing ConfigValidator
+        # "unknown pipeline" path below, unchanged by this feature.
+        if parsed_pipelines:
+            registry = get_registry()
+            registry.load()
+            for pipeline_name in parsed_pipelines:
+                meta = registry.get(pipeline_name)
+                if meta is not None and not extras_available(meta.requires_extras):
+                    raise PipelineUnavailableException(
+                        pipeline_name, meta.requires_extras
+                    )
+
         # Validate configuration if pipelines are specified (v1.3.0)
         if parsed_pipelines and parsed_config:
             validator = ConfigValidator()
@@ -402,7 +420,12 @@ async def submit_job(
             queue_position=queue_position,
         )
 
-    except (InvalidRequestException, InvalidConfigException, APIError):
+    except (
+        InvalidRequestException,
+        InvalidConfigException,
+        APIError,
+        PipelineUnavailableException,
+    ):
         # Let validation errors and other custom exceptions propagate
         raise
     except Exception as e:
diff --git a/src/videoannotator/api/v1/pipelines.py b/src/videoannotator/api/v1/pipelines.py
index 8784cee..8ff9006 100644
--- a/src/videoannotator/api/v1/pipelines.py
+++ b/src/videoannotator/api/v1/pipelines.py
@@ -3,9 +3,10 @@
 import logging
 from typing import Any
 
-from fastapi import APIRouter, Path
+from fastapi import APIRouter, Path, Query
 from pydantic import BaseModel
 
+from ...registry.pipeline_loader import extras_available, install_hint
 from ...registry.pipeline_registry import get_registry
 from ..errors import APIError
 
@@ -35,6 +36,8 @@ class PipelineInfo(BaseModel):
     outputs: list[dict[str, Any]]
     config_schema: dict[str, Any]
     examples: list[dict[str, Any]] = []
+    available: bool = True
+    install_hint: str | None = None
 
 
 class PipelineListResponse(BaseModel):
@@ -119,8 +122,26 @@ class PipelineListResponse(BaseModel):
 pipelines before submitting jobs.
 """,
 )
-async def list_pipelines():
-    """List all available pipelines."""
+async def list_pipelines(
+    include_unavailable: bool = Query(
+        False,
+        description=(
+            "Include pipelines whose required extras aren't installed. "
+            "Each such entry has available=false and an install_hint."
+        ),
+    ),
+):
+    """List available pipelines.
+
+    By default, pipelines whose `requires_extras` aren't installed are
+    omitted entirely (FR-005). Pass `?include_unavailable=true` to see them
+    too, each flagged with `available: false` and an `install_hint`.
+
+    The availability check is a metadata-only lookup (`importlib.metadata`),
+    not an actual import of torch/etc., so it stays cheap even though the
+    old version of this endpoint deliberately skipped availability checks
+    to avoid blocking on heavy imports.
+    """
     try:
         reg = get_registry()
         reg.load()  # idempotent
@@ -128,35 +149,37 @@ async def list_pipelines():
         if not metas:
             logger.warning("Registry returned no pipelines; falling back to empty list")
 
-        # Convert registry metadata to API response models
-        # Note: We do NOT filter by available implementations here to avoid
-        # heavy imports (torch, etc.) that would block the API for seconds/minutes.
-        # The registry is the source of truth.
-        pipeline_models: list[PipelineInfo] = [
-            PipelineInfo(
-                name=m.name,
-                display_name=m.display_name,
-                description=m.description,
-                pipeline_family=m.pipeline_family,
-                variant=m.variant,
-                tasks=m.tasks,
-                modalities=m.modalities,
-                capabilities=m.capabilities,
-                backends=m.backends,
-                stability=m.stability,
-                outputs=[{"format": o.format, "types": o.types} for o in m.outputs],
-                config_schema={
-                    k: {
-                        "type": v.type,
-                        "default": v.default,
-                        "description": v.description,
-                    }
-                    for k, v in m.config_schema.items()
-                },
-                examples=m.examples,
+        pipeline_models: list[PipelineInfo] = []
+        for m in metas:
+            available = extras_available(m.requires_extras)
+            if not available and not include_unavailable:
+                continue
+            pipeline_models.append(
+                PipelineInfo(
+                    name=m.name,
+                    display_name=m.display_name,
+                    description=m.description,
+                    pipeline_family=m.pipeline_family,
+                    variant=m.variant,
+                    tasks=m.tasks,
+                    modalities=m.modalities,
+                    capabilities=m.capabilities,
+                    backends=m.backends,
+                    stability=m.stability,
+                    outputs=[{"format": o.format, "types": o.types} for o in m.outputs],
+                    config_schema={
+                        k: {
+                            "type": v.type,
+                            "default": v.default,
+                            "description": v.description,
+                        }
+                        for k, v in m.config_schema.items()
+                    },
+                    examples=m.examples,
+                    available=available,
+                    install_hint=None if available else install_hint(m.requires_extras),
+                )
             )
-            for m in metas
-        ]
         return PipelineListResponse(
             pipelines=pipeline_models, total=len(pipeline_models)
         )
@@ -281,6 +304,7 @@ async def get_pipeline_info(
                 message=f"Pipeline '{pipeline_name}' not found",
                 hint="Run 'videoannotator pipelines --detailed'",
             )
+        available = extras_available(meta.requires_extras)
         return PipelineInfo(
             name=meta.name,
             display_name=meta.display_name,
@@ -298,6 +322,8 @@ async def get_pipeline_info(
                 for k, v in meta.config_schema.items()
             },
             examples=meta.examples,
+            available=available,
+            install_hint=None if available else install_hint(meta.requires_extras),
         )
     except APIError:
         raise
diff --git a/src/videoannotator/cli.py b/src/videoannotator/cli.py
index 4695cf4..98f5da4 100644
--- a/src/videoannotator/cli.py
+++ b/src/videoannotator/cli.py
@@ -277,6 +277,26 @@ def submit_job(
             typer.echo(
                 f"[INFO] Track progress with: videoannotator job status {job_data['id']}"
             )
+        elif response.status_code in (404, 422):
+            # Pipeline-not-found / pipeline-unavailable
+            # (contracts/unavailable-pipeline-error.md): show the actionable
+            # message, not a raw JSON blob or traceback.
+            try:
+                body = response.json()
+            except ValueError:
+                body = {}
+            message = body.get("detail") or body.get("error", {}).get(
+                "message", response.text
+            )
+            typer.echo(f"Error: {message}", err=True)
+            install_cmd = body.get("install_hint")
+            if install_cmd:
+                typer.echo(f"Install it with: {install_cmd}", err=True)
+            else:
+                hint = body.get("error", {}).get("hint")
+                if hint:
+                    typer.echo(f"Hint: {hint}", err=True)
+            raise typer.Exit(code=1)
         else:
             typer.echo(f"[ERROR] Job submission failed: {response.status_code}")
             typer.echo(f"Response: {response.text}")
@@ -482,6 +502,14 @@ def pipelines(
     detailed: bool = typer.Option(False, help="Show extended pipeline information"),
     json: bool = typer.Option(False, "--json", help="Output JSON for scripting"),
     format: str | None = typer.Option(None, help="Alternate output format (markdown)"),
+    all: bool = typer.Option(
+        False,
+        "--all",
+        help=(
+            "Include pipelines whose required extras aren't installed "
+            "(shown with an install hint instead of being omitted)."
+        ),
+    ),
 ):
     """List available processing pipelines retrieved from the registry."""
     import json as jsonlib
@@ -489,7 +517,11 @@ def pipelines(
     import requests
 
     try:
-        response = requests.get(f"{server}/api/v1/pipelines", timeout=10)
+        response = requests.get(
+            f"{server}/api/v1/pipelines",
+            params={"include_unavailable": "true"} if all else None,
+            timeout=10,
+        )
         if response.status_code != 200:
             typer.echo(f"[ERROR] Failed to get pipelines: {response.status_code}")
             raise typer.Exit(code=1)
@@ -538,7 +570,11 @@ def pipelines(
 
         typer.echo(f"[OK] Pipelines: {len(pipelines)} found")
         for p in pipelines:
-            typer.echo(f"- {p['name']}")
+            if p.get("available") is False:
+                typer.echo(f"- {p['name']} [unavailable]")
+                typer.echo(f"  Install with: {p.get('install_hint', '')}")
+            else:
+                typer.echo(f"- {p['name']}")
             if detailed:
                 typer.echo(f"  Display: {p.get('display_name', p['name'])}")
                 if p.get("pipeline_family"):
diff --git a/src/videoannotator/pipelines/__init__.py b/src/videoannotator/pipelines/__init__.py
index 538e657..b89efaf 100644
--- a/src/videoannotator/pipelines/__init__.py
+++ b/src/videoannotator/pipelines/__init__.py
@@ -4,12 +4,7 @@
 annotation tasks.
 """
 
-from .audio_processing import AudioPipeline
 from .base_pipeline import BasePipeline
-from .face_analysis.face_pipeline import FaceAnalysisPipeline
-from .face_analysis.laion_face_pipeline import LAIONFacePipeline
-from .person_tracking.person_pipeline import PersonTrackingPipeline
-from .scene_detection.scene_pipeline import SceneDetectionPipeline
 
 __all__ = [
     "AudioPipeline",
@@ -19,3 +14,28 @@
     "PersonTrackingPipeline",
     "SceneDetectionPipeline",
 ]
+
+# Each pipeline family needs a different extras group (`face`, `face-laion`,
+# `audio`, `person`, `scene` — see 004-extras-based-install); importing them
+# eagerly here would mean loading *any* single pipeline via the registry
+# forces every family's heavy deps to be installed, defeating extras
+# isolation. PEP 562 lazy attribute access keeps `from videoannotator.pipelines
+# import X` working for whichever families are actually installed, without
+# paying that cost at package-import time.
+_LAZY_ATTRS = {
+    "AudioPipeline": ".audio_processing",
+    "FaceAnalysisPipeline": ".face_analysis.face_pipeline",
+    "LAIONFacePipeline": ".face_analysis.laion_face_pipeline",
+    "PersonTrackingPipeline": ".person_tracking.person_pipeline",
+    "SceneDetectionPipeline": ".scene_detection.scene_pipeline",
+}
+
+
+def __getattr__(name: str) -> object:
+    module_path = _LAZY_ATTRS.get(name)
+    if module_path is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    import importlib
+
+    module = importlib.import_module(module_path, __name__)
+    return getattr(module, name)
diff --git a/src/videoannotator/pipelines/audio_processing/__init__.py b/src/videoannotator/pipelines/audio_processing/__init__.py
index 467f6e5..0e3722d 100644
--- a/src/videoannotator/pipelines/audio_processing/__init__.py
+++ b/src/videoannotator/pipelines/audio_processing/__init__.py
@@ -12,7 +12,6 @@
 
 from .audio_pipeline_modular import AudioPipelineModular
 from .diarization_pipeline import DiarizationPipeline
-from .laion_voice_pipeline import LAIONVoicePipeline
 from .speech_pipeline import SpeechPipeline
 from .whisper_base_pipeline import WhisperBasePipeline
 
@@ -27,3 +26,15 @@
     "SpeechPipeline",
     "WhisperBasePipeline",
 ]
+
+
+# LAIONVoicePipeline needs the `audio-laion` extras group (transformers,
+# huggingface-hub) — a strict superset of `audio`'s deps, not a subset —
+# so it can't be imported eagerly alongside the rest of this package
+# without breaking a plain `[audio]` install. See 004-extras-based-install.
+def __getattr__(name: str) -> object:
+    if name != "LAIONVoicePipeline":
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from .laion_voice_pipeline import LAIONVoicePipeline
+
+    return LAIONVoicePipeline
diff --git a/src/videoannotator/pipelines/face_analysis/__init__.py b/src/videoannotator/pipelines/face_analysis/__init__.py
index a6db207..5a4c59c 100644
--- a/src/videoannotator/pipelines/face_analysis/__init__.py
+++ b/src/videoannotator/pipelines/face_analysis/__init__.py
@@ -4,21 +4,31 @@
 capabilities.
 """
 
-from .face_pipeline import FaceAnalysisPipeline
-from .laion_face_pipeline import LAIONFacePipeline
-
-# Optional OpenFace 3.0 pipeline
-try:
-    from .openface3_pipeline import OpenFace3Pipeline
-
-    OPENFACE3_AVAILABLE = True
-except ImportError:
-    OpenFace3Pipeline = None  # type: ignore
-    OPENFACE3_AVAILABLE = False
-
 __all__ = [
-    "OPENFACE3_AVAILABLE",
     "FaceAnalysisPipeline",
     "LAIONFacePipeline",
     "OpenFace3Pipeline",
 ]
+
+# Each variant needs a different extras group (`face`, `face-laion`,
+# `face-openface3` — see 004-extras-based-install): FaceAnalysisPipeline needs
+# deepface, LAIONFacePipeline needs torch/transformers (and, since it composes
+# FaceAnalysisPipeline as its detector backend, deepface too), OpenFace3Pipeline
+# needs openface-test/scipy but *not* deepface. Importing any of them eagerly
+# here would force every variant's deps onto whichever one you actually asked
+# for, so resolve lazily instead.
+_LAZY_ATTRS = {
+    "FaceAnalysisPipeline": ".face_pipeline",
+    "LAIONFacePipeline": ".laion_face_pipeline",
+    "OpenFace3Pipeline": ".openface3_pipeline",
+}
+
+
+def __getattr__(name: str) -> object:
+    module_path = _LAZY_ATTRS.get(name)
+    if module_path is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    import importlib
+
+    module = importlib.import_module(module_path, __name__)
+    return getattr(module, name)
diff --git a/src/videoannotator/pipelines/face_analysis/face_pipeline.py b/src/videoannotator/pipelines/face_analysis/face_pipeline.py
index e78d0b5..8a2bb92 100644
--- a/src/videoannotator/pipelines/face_analysis/face_pipeline.py
+++ b/src/videoannotator/pipelines/face_analysis/face_pipeline.py
@@ -7,6 +7,7 @@
 
 import json
 import logging
+import os
 from pathlib import Path
 from typing import Any
 
@@ -23,6 +24,39 @@
 from videoannotator.utils.person_identity import PersonIdentityManager
 from videoannotator.version import __version__
 
+
+def _disable_tensorflow_gpu() -> None:
+    """Force TensorFlow onto CPU before deepface (which pulls it in) touches the GPU.
+
+    torch hard-pins `nvidia-cudnn-cu12==9.1.0.70`; deepface's own `tensorflow`
+    dependency wants cuDNN>=9.3.0.75 for GPU use (via its `[and-cuda]` extra,
+    which nothing here installs — it just borrows whatever cuDNN is already in
+    the venv). These two pins can never both be satisfied in one venv, so
+    TensorFlow's GPU ops fail at runtime (`No DNN in stream executor`) instead
+    of erroring at install time. Forcing TF onto CPU sidesteps that entirely;
+    torch itself (scene/person/face-laion's CLIP/YOLO models) is untouched —
+    this only calls TensorFlow's own device-visibility API, not the
+    `CUDA_VISIBLE_DEVICES` env var, which both frameworks would otherwise read.
+    Set `VIDEOANNOTATOR_DEEPFACE_GPU=1` to skip this if you've resolved the
+    cuDNN mismatch yourself (e.g. a matching system-wide CUDA/cuDNN install).
+    """
+    if os.environ.get("VIDEOANNOTATOR_DEEPFACE_GPU") == "1":
+        return
+    try:
+        import tensorflow as tf
+
+        tf.config.set_visible_devices([], "GPU")
+    except ImportError:
+        pass
+    except Exception as e:
+        logging.getLogger(__name__).warning(
+            f"Failed to force TensorFlow onto CPU (deepface may hit cuDNN "
+            f"version-mismatch errors on GPU installs): {e}"
+        )
+
+
+_disable_tensorflow_gpu()
+
 # Optional import for enhanced face analysis
 try:
     from deepface import DeepFace
diff --git a/src/videoannotator/pipelines/scene_detection/scene_pipeline.py b/src/videoannotator/pipelines/scene_detection/scene_pipeline.py
index 7c97278..2e431ab 100644
--- a/src/videoannotator/pipelines/scene_detection/scene_pipeline.py
+++ b/src/videoannotator/pipelines/scene_detection/scene_pipeline.py
@@ -262,8 +262,17 @@ def _classify_scenes(
                             )
 
                             with torch.no_grad():
-                                logits_per_image, logits_per_text = self.clip_model(
-                                    image_input, text
+                                # open_clip's model(image, text) returns raw
+                                # (image_features, text_features, logit_scale) —
+                                # not (logits_per_image, logits_per_text) like the
+                                # legacy CLIP API this was originally written
+                                # against. Compute the similarity logits
+                                # ourselves (see open_clip's own usage examples).
+                                image_features, text_features, logit_scale = (
+                                    self.clip_model(image_input, text)
+                                )
+                                logits_per_image = (
+                                    logit_scale * image_features @ text_features.T
                                 )
                                 probs = (
                                     logits_per_image.softmax(dim=-1).cpu().numpy()[0]
diff --git a/src/videoannotator/registry/__init__.py b/src/videoannotator/registry/__init__.py
index 7f52b0e..851fdea 100644
--- a/src/videoannotator/registry/__init__.py
+++ b/src/videoannotator/registry/__init__.py
@@ -4,14 +4,11 @@
 """
 
 from .pipeline_loader import PipelineLoader, get_pipeline_loader
-from .pipeline_registry import PipelineRegistry
+from .pipeline_registry import PipelineRegistry, get_registry
 
 __all__ = [
     "PipelineLoader",
     "PipelineRegistry",
     "get_pipeline_loader",
-    "pipeline_registry",
+    "get_registry",
 ]
-
-# Global registry instance
-pipeline_registry = PipelineRegistry()
diff --git a/src/videoannotator/registry/metadata/audio_processing.yaml b/src/videoannotator/registry/metadata/audio_processing.yaml
index f431319..de1e609 100644
--- a/src/videoannotator/registry/metadata/audio_processing.yaml
+++ b/src/videoannotator/registry/metadata/audio_processing.yaml
@@ -3,6 +3,8 @@ display_name: Audio Processing (Speech + Diarization)
 description: Transcribe speech with Whisper and perform speaker diarization using pyannote.audio producing WebVTT + RTTM outputs.
 pipeline_family: audio
 variant: whisper-pyannote
+module_path: videoannotator.pipelines.audio_processing:AudioPipeline
+requires_extras: [audio]
 tasks:
   - speech-transcription
   - speaker-diarization
diff --git a/src/videoannotator/registry/metadata/face_analysis.yaml b/src/videoannotator/registry/metadata/face_analysis.yaml
index d4da4a8..a0e6060 100644
--- a/src/videoannotator/registry/metadata/face_analysis.yaml
+++ b/src/videoannotator/registry/metadata/face_analysis.yaml
@@ -3,6 +3,8 @@ display_name: Face Analysis (DeepFace)
 description: Standards-only face detection and analysis using DeepFace with emotion recognition, age, and gender prediction, producing COCO format output.
 pipeline_family: face
 variant: deepface
+module_path: videoannotator.pipelines.face_analysis:FaceAnalysisPipeline
+requires_extras: [face]
 tasks:
   - face-detection
   - emotion-recognition
diff --git a/src/videoannotator/registry/metadata/face_laion_clip.yaml b/src/videoannotator/registry/metadata/face_laion_clip.yaml
index fe4765e..f8bfe49 100644
--- a/src/videoannotator/registry/metadata/face_laion_clip.yaml
+++ b/src/videoannotator/registry/metadata/face_laion_clip.yaml
@@ -3,6 +3,8 @@ display_name: LAION CLIP Face Semantic Embedding
 description: Produce semantic face embeddings using a CLIP-derived model; supports zero-shot attribute and emotion tagging.
 pipeline_family: face
 variant: laion-clip-face
+module_path: videoannotator.pipelines.face_analysis.laion_face_pipeline:LAIONFacePipeline
+requires_extras: [face-laion]
 tasks:
   - face-embedding
   - face-recognition
diff --git a/src/videoannotator/registry/metadata/face_openface3_embedding.yaml b/src/videoannotator/registry/metadata/face_openface3_embedding.yaml
index c123774..b681496 100644
--- a/src/videoannotator/registry/metadata/face_openface3_embedding.yaml
+++ b/src/videoannotator/registry/metadata/face_openface3_embedding.yaml
@@ -3,6 +3,8 @@ display_name: OpenFace3 Face Embedding
 description: Generate 512-D face embeddings for recognition or clustering using OpenFace3.
 pipeline_family: face
 variant: openface3-embedding
+module_path: videoannotator.pipelines.face_analysis.openface3_pipeline:OpenFace3Pipeline
+requires_extras: [face-openface3]
 tasks:
   - face-embedding
 modalities:
diff --git a/src/videoannotator/registry/metadata/laion_voice.yaml b/src/videoannotator/registry/metadata/laion_voice.yaml
index 778b0e5..ac4de3f 100644
--- a/src/videoannotator/registry/metadata/laion_voice.yaml
+++ b/src/videoannotator/registry/metadata/laion_voice.yaml
@@ -3,6 +3,8 @@ display_name: LAION Empathic Voice Analysis
 description: Advanced audio emotion analysis using LAION's Empathic Insight model with Whisper embeddings for nuanced emotional understanding.
 pipeline_family: audio
 variant: laion-empathic-whisper
+module_path: videoannotator.pipelines.audio_processing.laion_voice_pipeline:LAIONVoicePipeline
+requires_extras: [audio-laion]
 tasks:
   - emotion-recognition
   - audio-analysis
diff --git a/src/videoannotator/registry/metadata/person_tracking.yaml b/src/videoannotator/registry/metadata/person_tracking.yaml
index a00688e..cd20527 100644
--- a/src/videoannotator/registry/metadata/person_tracking.yaml
+++ b/src/videoannotator/registry/metadata/person_tracking.yaml
@@ -3,6 +3,8 @@ display_name: Person Tracking & Pose
 description: Track persons with YOLO11 + ByteTrack producing COCO person + keypoint annotations.
 pipeline_family: person
 variant: yolov11n-pose-bytetrack
+module_path: videoannotator.pipelines.person_tracking:PersonTrackingPipeline
+requires_extras: [person]
 tasks:
   - object-tracking
   - pose-estimation
diff --git a/src/videoannotator/registry/metadata/scene_detection.yaml b/src/videoannotator/registry/metadata/scene_detection.yaml
index 909f551..d981e47 100644
--- a/src/videoannotator/registry/metadata/scene_detection.yaml
+++ b/src/videoannotator/registry/metadata/scene_detection.yaml
@@ -3,6 +3,8 @@ display_name: Scene Detection
 description: Detect hard cuts and scene boundaries using PySceneDetect with semantic labeling via CLIP.
 pipeline_family: scene
 variant: pyscenedetect-clip
+module_path: videoannotator.pipelines.scene_detection:SceneDetectionPipeline
+requires_extras: [scene]
 tasks:
   - scene-detection
   - scene-segmentation
diff --git a/src/videoannotator/registry/metadata/speaker_diarization.yaml b/src/videoannotator/registry/metadata/speaker_diarization.yaml
index 53fd3a5..b379b3e 100644
--- a/src/videoannotator/registry/metadata/speaker_diarization.yaml
+++ b/src/videoannotator/registry/metadata/speaker_diarization.yaml
@@ -3,6 +3,8 @@ display_name: Speaker Diarization
 description: Speaker diarization using PyAnnote.audio to segment and identify different speakers with timestamps, producing RTTM format output.
 pipeline_family: audio
 variant: pyannote
+module_path: videoannotator.pipelines.audio_processing:DiarizationPipeline
+requires_extras: [audio]
 tasks:
   - speaker-diarization
   - speaker-segmentation
diff --git a/src/videoannotator/registry/metadata/speech_recognition.yaml b/src/videoannotator/registry/metadata/speech_recognition.yaml
index 1d83e06..99d9238 100644
--- a/src/videoannotator/registry/metadata/speech_recognition.yaml
+++ b/src/videoannotator/registry/metadata/speech_recognition.yaml
@@ -3,6 +3,8 @@ display_name: Speech Recognition
 description: Speech transcription using OpenAI Whisper with word-level timestamps, producing WebVTT format output for subtitles and captions.
 pipeline_family: audio
 variant: whisper
+module_path: videoannotator.pipelines.audio_processing:SpeechPipeline
+requires_extras: [audio]
 tasks:
   - speech-transcription
   - automatic-speech-recognition
diff --git a/src/videoannotator/registry/pipeline_loader.py b/src/videoannotator/registry/pipeline_loader.py
index bb922f4..4830f15 100644
--- a/src/videoannotator/registry/pipeline_loader.py
+++ b/src/videoannotator/registry/pipeline_loader.py
@@ -4,13 +4,98 @@
 hardcoded pipeline mappings in JobProcessor and BatchOrchestrator.
 """
 
+import functools
 import importlib
+import importlib.metadata
 import logging
 
+from packaging.requirements import Requirement
+
 from .pipeline_registry import PipelineMetadata, get_registry
 
 LOGGER = logging.getLogger("videoannotator.registry")
 
+_DISTRIBUTION_NAME = "videoannotator"
+
+
+@functools.cache
+def _packages_for_extra(extra: str) -> tuple[str, ...]:
+    """Return the pip distribution names declared under `[extra]`.
+
+    Read from this package's own installed metadata (Requires-Dist entries
+    with an `extra == "<name>"` marker) rather than a hand-maintained
+    mapping, so it can't drift from `pyproject.toml`
+    (specs/004-extras-based-install/research.md §3).
+    """
+    try:
+        dist = importlib.metadata.distribution(_DISTRIBUTION_NAME)
+    except importlib.metadata.PackageNotFoundError:
+        return ()
+    packages: list[str] = []
+    for req_str in dist.requires or []:
+        req = Requirement(req_str)
+        if req.marker and req.marker.evaluate({"extra": extra}):
+            packages.append(req.name)
+    return tuple(packages)
+
+
+@functools.cache
+def _is_distribution_installed(name: str) -> bool:
+    try:
+        importlib.metadata.distribution(name)
+        return True
+    except importlib.metadata.PackageNotFoundError:
+        return False
+
+
+def extras_available(requires_extras: list[str]) -> bool:
+    """Return whether every package declared under `requires_extras` is
+    installed. An empty list is vacuously available (research.md §2) — it
+    means "no extra needed", not "unknown"."""
+    for extra in requires_extras:
+        for package in _packages_for_extra(extra):
+            if not _is_distribution_installed(package):
+                return False
+    return True
+
+
+def missing_extras(requires_extras: list[str]) -> list[str]:
+    """Return the subset of `requires_extras` that have at least one
+    package not currently installed."""
+    return [extra for extra in requires_extras if not extras_available([extra])]
+
+
+def install_hint(requires_extras: list[str]) -> str:
+    """Return the exact `pip install videoannotator[...]` command for the
+    given extras groups (contracts/unavailable-pipeline-error.md)."""
+    groups = ",".join(requires_extras) if requires_extras else ""
+    return f"pip install {_DISTRIBUTION_NAME}[{groups}]"
+
+
+# Pipelines that were installed by default in v1.4.4 but were demoted to a
+# non-default extras group in v1.5.0 (data-model.md's migration message
+# record). Requesting one of these without its extras gets a distinct
+# "no longer installed by default" message instead of the generic
+# unavailable-pipeline text (research.md §4).
+_V144_DEMOTED_PIPELINES: dict[str, str] = {
+    "face_laion_clip": "face-laion",
+    "laion_voice": "audio-laion",
+    "face_openface3_embedding": "face-openface3",
+}
+
+
+def migration_note(pipeline_name: str) -> str | None:
+    """Return the v1.4.4->v1.5.0 migration note for a pipeline demoted out
+    of the default install, or None if it was never in the default install.
+    """
+    extra = _V144_DEMOTED_PIPELINES.get(pipeline_name)
+    if extra is None:
+        return None
+    return (
+        f"As of v1.5.0, pipelines requiring the '{extra}' extras group are "
+        "no longer installed by default."
+    )
+
 
 class PipelineLoader:
     """Load pipeline classes dynamically from registry metadata."""
@@ -89,14 +174,24 @@ def _load_pipeline_class(self, meta: PipelineMetadata) -> type | None:
         if meta.name in self._class_cache:
             return self._class_cache[meta.name]
 
-        # Get module path from metadata
-        module_path = self._infer_module_path(meta)
+        module_path = meta.module_path
         if not module_path:
+            # The registry itself already skips YAML files missing
+            # module_path (pipeline_registry.py._parse_metadata), so this is
+            # defence-in-depth rather than the expected path.
             LOGGER.warning(
                 f"Cannot load pipeline '{meta.name}': no module_path in metadata"
             )
             return None
 
+        if not extras_available(meta.requires_extras):
+            LOGGER.info(
+                f"Skipping pipeline '{meta.name}': requires extras "
+                f"{meta.requires_extras} not installed "
+                f"({install_hint(meta.requires_extras)})"
+            )
+            return None
+
         try:
             # Parse module_path format: "module.path:ClassName"
             if ":" not in module_path:
@@ -133,33 +228,6 @@ def _load_pipeline_class(self, meta: PipelineMetadata) -> type | None:
             )
             return None
 
-    def _infer_module_path(self, meta: PipelineMetadata) -> str | None:
-        """Infer module path from metadata if not explicitly provided.
-
-        This provides backward compatibility for metadata files that don't
-        yet have the module_path field.
-
-        Args:
-            meta: Pipeline metadata
-
-        Returns:
-            Inferred module path or None
-        """
-        # Mapping of pipeline names to their module paths (temporary fallback)
-        LEGACY_MAPPINGS = {
-            "scene_detection": "videoannotator.pipelines.scene_detection:SceneDetectionPipeline",
-            "person_tracking": "videoannotator.pipelines.person_tracking:PersonTrackingPipeline",
-            "face_analysis": "videoannotator.pipelines.face_analysis:FaceAnalysisPipeline",
-            "audio_processing": "videoannotator.pipelines.audio_processing:AudioPipeline",
-            "speech_recognition": "videoannotator.pipelines.audio_processing:SpeechPipeline",
-            "speaker_diarization": "videoannotator.pipelines.audio_processing:DiarizationPipeline",
-            "face_laion_clip": "videoannotator.pipelines.face_analysis.laion_face_pipeline:LAIONFacePipeline",
-            "laion_voice": "videoannotator.pipelines.audio_processing.laion_voice_pipeline:LAIONVoicePipeline",
-            "face_openface3_embedding": "videoannotator.pipelines.face_analysis.openface3_pipeline:OpenFace3Pipeline",
-        }
-
-        return LEGACY_MAPPINGS.get(meta.name)
-
 
 # Singleton instance
 _loader_instance: PipelineLoader | None = None
@@ -173,4 +241,11 @@ def get_pipeline_loader() -> PipelineLoader:
     return _loader_instance
 
 
-__all__ = ["PipelineLoader", "get_pipeline_loader"]
+__all__ = [
+    "PipelineLoader",
+    "get_pipeline_loader",
+    "extras_available",
+    "missing_extras",
+    "install_hint",
+    "migration_note",
+]
diff --git a/src/videoannotator/registry/pipeline_registry.py b/src/videoannotator/registry/pipeline_registry.py
index 8eaafb6..ba016aa 100644
--- a/src/videoannotator/registry/pipeline_registry.py
+++ b/src/videoannotator/registry/pipeline_registry.py
@@ -75,6 +75,13 @@ class PipelineMetadata:
     backends: list[str] = field(default_factory=list)
     stability: str | None = None
     examples: list[dict[str, Any]] = field(default_factory=list)
+    # pip extras-group name(s) needed for this pipeline to import successfully;
+    # [] is valid (e.g. a future non-ML/HTTP-only pipeline). See
+    # specs/004-extras-based-install/contracts/pipeline-metadata-schema.md
+    requires_extras: list[str] = field(default_factory=list)
+    # "module.path:ClassName" — required; a file missing it is skipped with a
+    # warning at load time rather than falling back to a hardcoded table.
+    module_path: str | None = None
 
 
 class PipelineRegistry:
@@ -164,6 +171,14 @@ def _parse_metadata(
             LOGGER.warning("Metadata %s examples not a list", source.name)
             examples = []
 
+        module_path = raw.get("module_path")
+        if not module_path or not isinstance(module_path, str):
+            LOGGER.warning(
+                "Metadata %s missing required field 'module_path'; skipping",
+                source.name,
+            )
+            return None
+
         # Optional extended fields (ignored if wrong types)
         def _list_field(key: str) -> list[str]:
             val = raw.get(key)
@@ -188,6 +203,8 @@ def _list_field(key: str) -> list[str]:
             backends=_list_field("backends"),
             stability=str(raw.get("stability")) if raw.get("stability") else None,
             examples=examples,
+            requires_extras=_list_field("requires_extras"),
+            module_path=module_path,
         )
 
     def list(self) -> builtins.list[PipelineMetadata]:
diff --git a/src/videoannotator/utils/audio.py b/src/videoannotator/utils/audio.py
index e4aec23..2597f6b 100644
--- a/src/videoannotator/utils/audio.py
+++ b/src/videoannotator/utils/audio.py
@@ -1,7 +1,5 @@
 """Audio utility helpers for extracting basic signal features."""
 
-import librosa
-
 
 def find_f0(audio_file):
     """Extract the fundamental frequency (F0) from an audio file.
@@ -11,6 +9,11 @@ def find_f0(audio_file):
     Returns:
         np.array: The fundamental frequency values.
     """
+    # librosa is an `audio`/`audio-laion` extra, not a core dependency — import
+    # lazily so `videoannotator.utils` (imported by the core CLI/API) doesn't
+    # require it just to load this module. See 004-extras-based-install.
+    import librosa
+
     # Load the audio file
     y, _sr = librosa.load(audio_file)
     # Extract the fundamental frequency
diff --git a/src/videoannotator/version.py b/src/videoannotator/version.py
index 1acd805..ac33166 100644
--- a/src/videoannotator/version.py
+++ b/src/videoannotator/version.py
@@ -10,10 +10,10 @@
 from videoannotator.utils.logging_config import get_logger
 
 logger = get_logger("videoannotator.version")
-__version__ = "1.4.4"
-__version_info__ = (1, 4, 4, "final")
-# Release version for v1.4.4
-__release_date__ = "2026-07-08"
+__version__ = "1.5.0"
+__version_info__ = (1, 5, 0, "final")
+# Release version for v1.5.0
+__release_date__ = "2026-07-19"
 __author__ = "VideoAnnotator Team"
 __license__ = "MIT"
 
diff --git a/tests/contract/test_migration_message_contract.py b/tests/contract/test_migration_message_contract.py
new file mode 100644
index 0000000..6cf9e5a
--- /dev/null
+++ b/tests/contract/test_migration_message_contract.py
@@ -0,0 +1,82 @@
+"""Contract test: the migration-message variant for pipelines demoted out of
+the v1.4.4 default install (LAION face/voice, OpenFace3).
+
+Contract: specs/004-extras-based-install/contracts/unavailable-pipeline-error.md
+  "Migration case (pipeline demoted from v1.4.4 default install)"
+Data:     specs/004-extras-based-install/data-model.md
+  "Migration message record"
+"""
+
+import pytest
+
+from videoannotator.registry.pipeline_loader import install_hint, migration_note
+
+
+class TestMigrationMessageContract:
+    @pytest.mark.parametrize(
+        "pipeline_name,expected_extra",
+        [
+            ("face_laion_clip", "face-laion"),
+            ("laion_voice", "audio-laion"),
+            ("face_openface3_embedding", "face-openface3"),
+        ],
+    )
+    def test_demoted_pipelines_get_a_migration_note(
+        self, pipeline_name, expected_extra
+    ):
+        note = migration_note(pipeline_name)
+
+        assert note is not None
+        assert "no longer installed by default" in note
+        assert expected_extra in note
+        assert "v1.5.0" in note
+
+    @pytest.mark.parametrize(
+        "pipeline_name",
+        [
+            "face_analysis",
+            "scene_detection",
+            "person_tracking",
+            "audio_processing",
+            "speech_recognition",
+            "speaker_diarization",
+            "never_existed_pipeline",
+        ],
+    )
+    def test_non_demoted_pipelines_get_no_migration_note(self, pipeline_name):
+        assert migration_note(pipeline_name) is None
+
+    def test_migration_note_is_distinguishable_from_generic_message(self):
+        """A demoted pipeline's note must not read like the plain
+        'not a recognized pipeline' case — it must explain the pipeline
+        *used to* work and name the extras group to restore it."""
+        note = migration_note("face_laion_clip")
+        generic_unavailable_message = (
+            "Pipeline 'some_pipeline' is not available in this install."
+        )
+
+        assert note != generic_unavailable_message
+        assert "face-laion" in note
+        assert install_hint(["face-laion"]) == "pip install videoannotator[face-laion]"
+
+    def test_full_message_shape_matches_contract_example(self):
+        """Assemble the same message shape the API/CLI error path builds
+        (exceptions.PipelineUnavailableException) and check it matches the
+        three required parts from the contract: naming the pipeline, the
+        'no longer default' explanation, and the exact install command."""
+        pipeline_name = "face_laion_clip"
+        requires_extras = ["face-laion"]
+
+        note = migration_note(pipeline_name)
+        message = f"Pipeline '{pipeline_name}' is not available in this install."
+        if note:
+            message = f"{message} {note}"
+        hint = install_hint(requires_extras)
+
+        assert message.startswith(
+            "Pipeline 'face_laion_clip' is not available in this install."
+        )
+        assert "no longer installed by default" in message
+        assert "v1.5.0" in message
+        assert "face-laion" in message
+        assert hint == "pip install videoannotator[face-laion]"
diff --git a/tests/contract/test_pipeline_availability_contract.py b/tests/contract/test_pipeline_availability_contract.py
new file mode 100644
index 0000000..1fe3290
--- /dev/null
+++ b/tests/contract/test_pipeline_availability_contract.py
@@ -0,0 +1,91 @@
+"""Contract test: unavailable pipelines are omitted from GET /api/v1/pipelines
+by default (FR-005), and included with `available: false` + `install_hint`
+when `?include_unavailable=true` is passed.
+
+Contract: specs/004-extras-based-install/contracts/unavailable-pipeline-error.md
+"""
+
+import tempfile
+from pathlib import Path
+
+import pytest
+from fastapi.testclient import TestClient
+
+import videoannotator.api.v1.pipelines as pipelines_module
+from videoannotator.api.database import reset_storage_backend, set_database_path
+from videoannotator.api.main import create_app
+
+
+@pytest.fixture
+def client():
+    with tempfile.NamedTemporaryFile(delete=False, suffix=".db") as f:
+        db_path = Path(f.name)
+    set_database_path(db_path)
+    reset_storage_backend()
+
+    app = create_app()
+    yield TestClient(app)
+
+    reset_storage_backend()
+    if db_path.exists():
+        db_path.unlink()
+
+
+def _make_unavailable(monkeypatch, unavailable_extras: set[str]):
+    """Force any pipeline requiring one of `unavailable_extras` to appear
+    unavailable, regardless of what's actually installed in this test
+    environment."""
+
+    def fake_extras_available(requires_extras):
+        return not any(extra in unavailable_extras for extra in requires_extras)
+
+    monkeypatch.setattr(pipelines_module, "extras_available", fake_extras_available)
+
+
+class TestPipelineAvailabilityContract:
+    def test_default_listing_omits_unavailable_pipelines(self, client, monkeypatch):
+        _make_unavailable(monkeypatch, {"face-laion"})
+
+        response = client.get("/api/v1/pipelines/")
+
+        assert response.status_code == 200
+        names = {p["name"] for p in response.json()["pipelines"]}
+        assert "face_laion_clip" not in names
+
+    def test_default_listing_keeps_available_pipelines(self, client, monkeypatch):
+        _make_unavailable(monkeypatch, {"face-laion"})
+
+        response = client.get("/api/v1/pipelines/")
+
+        names = {p["name"] for p in response.json()["pipelines"]}
+        # Pipelines that don't need the unavailable extra are unaffected.
+        assert "scene_detection" in names
+
+    def test_include_unavailable_shows_availability_and_install_hint(
+        self, client, monkeypatch
+    ):
+        _make_unavailable(monkeypatch, {"face-laion"})
+
+        response = client.get(
+            "/api/v1/pipelines/", params={"include_unavailable": "true"}
+        )
+
+        assert response.status_code == 200
+        pipelines_by_name = {p["name"]: p for p in response.json()["pipelines"]}
+        assert "face_laion_clip" in pipelines_by_name
+
+        entry = pipelines_by_name["face_laion_clip"]
+        assert entry["available"] is False
+        assert entry["install_hint"] == "pip install videoannotator[face-laion]"
+
+    def test_available_pipelines_report_available_true(self, client, monkeypatch):
+        _make_unavailable(monkeypatch, {"face-laion"})
+
+        response = client.get(
+            "/api/v1/pipelines/", params={"include_unavailable": "true"}
+        )
+
+        pipelines_by_name = {p["name"]: p for p in response.json()["pipelines"]}
+        entry = pipelines_by_name["scene_detection"]
+        assert entry["available"] is True
+        assert entry["install_hint"] is None
diff --git a/tests/contract/test_unavailable_pipeline_error.py b/tests/contract/test_unavailable_pipeline_error.py
new file mode 100644
index 0000000..d8cc384
--- /dev/null
+++ b/tests/contract/test_unavailable_pipeline_error.py
@@ -0,0 +1,113 @@
+"""Contract test: unavailable-pipeline error shape on every user-facing
+surface that can name a pipeline.
+
+Contract: specs/004-extras-based-install/contracts/unavailable-pipeline-error.md
+- API: 422 (not 500), JSON body with `detail`, `install_hint`, `pipeline`.
+- CLI: non-zero exit, stderr message, no Python traceback.
+"""
+
+import io
+import tempfile
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+from fastapi.testclient import TestClient
+from typer.testing import CliRunner
+
+from videoannotator.api.database import reset_storage_backend, set_database_path
+from videoannotator.api.main import create_app
+from videoannotator.cli import app as cli_app
+
+
+@pytest.fixture
+def client():
+    with tempfile.NamedTemporaryFile(delete=False, suffix=".db") as f:
+        db_path = Path(f.name)
+    set_database_path(db_path)
+    reset_storage_backend()
+
+    app = create_app()
+    yield TestClient(app)
+
+    reset_storage_backend()
+    if db_path.exists():
+        db_path.unlink()
+
+
+@pytest.fixture
+def sample_video_file():
+    from tests.fixtures.synthetic_video import synthetic_video_bytes_avi
+
+    return io.BytesIO(synthetic_video_bytes_avi())
+
+
+class TestAPIUnavailablePipelineErrorShape:
+    def test_submit_job_with_unavailable_pipeline_returns_422(
+        self, client, sample_video_file, monkeypatch
+    ):
+        import videoannotator.api.v1.jobs as jobs_module
+
+        monkeypatch.setattr(jobs_module, "extras_available", lambda extras: False)
+
+        files = {"video": ("test.avi", sample_video_file, "video/avi")}
+        data = {"selected_pipelines": "face_analysis"}
+
+        response = client.post("/api/v1/jobs/", files=files, data=data)
+
+        assert response.status_code == 422
+        body = response.json()
+        assert "face_analysis" in body["detail"]
+        assert body["pipeline"] == "face_analysis"
+        assert body["install_hint"] == "pip install videoannotator[face]"
+
+    def test_submit_job_with_demoted_laion_pipeline_gets_migration_message(
+        self, client, sample_video_file, monkeypatch
+    ):
+        import videoannotator.api.v1.jobs as jobs_module
+
+        monkeypatch.setattr(jobs_module, "extras_available", lambda extras: False)
+
+        files = {"video": ("test.avi", sample_video_file, "video/avi")}
+        data = {"selected_pipelines": "face_laion_clip"}
+
+        response = client.post("/api/v1/jobs/", files=files, data=data)
+
+        assert response.status_code == 422
+        body = response.json()
+        assert "no longer installed by default" in body["detail"]
+        assert body["install_hint"] == "pip install videoannotator[face-laion]"
+
+
+class TestCLIUnavailablePipelineErrorShape:
+    def test_job_submit_unavailable_pipeline_exits_nonzero_no_traceback(self, tmp_path):
+        video_path = tmp_path / "sample.mp4"
+        video_path.write_bytes(b"not a real video, just needs to exist")
+
+        fake_response = MagicMock()
+        fake_response.status_code = 422
+        fake_response.json.return_value = {
+            "detail": "Pipeline 'face_laion_clip' is not available in this install. "
+            "As of v1.5.0, pipelines requiring the 'face-laion' extras group "
+            "are no longer installed by default.",
+            "install_hint": "pip install videoannotator[face-laion]",
+            "pipeline": "face_laion_clip",
+        }
+
+        runner = CliRunner()
+        with patch("requests.post", return_value=fake_response):
+            result = runner.invoke(
+                cli_app,
+                [
+                    "job",
+                    "submit",
+                    str(video_path),
+                    "--pipelines",
+                    "face_laion_clip",
+                ],
+            )
+
+        assert result.exit_code != 0
+        assert "Traceback" not in result.output
+        assert "Error:" in result.output
+        assert "pip install videoannotator[face-laion]" in result.output
diff --git a/tests/fixtures/stub_pipeline.yaml b/tests/fixtures/stub_pipeline.yaml
new file mode 100644
index 0000000..510daa6
--- /dev/null
+++ b/tests/fixtures/stub_pipeline.yaml
@@ -0,0 +1,23 @@
+name: stub_pipeline
+display_name: Stub Forward-Compatibility Pipeline
+description: >-
+  Throwaway pipeline metadata proving PipelineMetadata/the registry loader
+  need no schema changes for a future non-local pipeline (spec 004 User
+  Story 3, SC-007) — e.g. v1.6.0's Ollama-backed `llm` group or v1.7.0+'s
+  HTTP/Slurm-dispatched pipelines.
+pipeline_family: stub
+variant: forward-compat-stub
+module_path: tests.fixtures.stub_pipeline_module:StubPipeline
+requires_extras: []
+backends:
+  - http
+outputs:
+  - format: JSON
+    types: [stub]
+config_schema:
+  enabled:
+    type: boolean
+    default: true
+    description: Stub config field, unused.
+version: 1
+stability: experimental
diff --git a/tests/fixtures/stub_pipeline_module.py b/tests/fixtures/stub_pipeline_module.py
new file mode 100644
index 0000000..1b2f08a
--- /dev/null
+++ b/tests/fixtures/stub_pipeline_module.py
@@ -0,0 +1,36 @@
+"""Throwaway stub pipeline for the forward-compatibility test
+(specs/004-extras-based-install User Story 3 / SC-007).
+
+Not a real pipeline — it exists only to prove that a future non-local
+pipeline (e.g. v1.6.0's Ollama-backed `llm` group, or v1.7.0+'s
+HTTP/Slurm-dispatched pipelines) can declare `requires_extras: []` plus a
+non-ML `backends` value and load through the registry with zero changes to
+PipelineMetadata or the loader.
+"""
+
+from typing import Any
+
+from videoannotator.pipelines.base_pipeline import BasePipeline
+
+
+class StubPipeline(BasePipeline):
+    """Stub pipeline — every method raises NotImplementedError."""
+
+    def initialize(self) -> None:
+        raise NotImplementedError("stub_pipeline is a forward-compatibility fixture")
+
+    def process(
+        self,
+        video_path: str,
+        start_time: float = 0.0,
+        end_time: float | None = None,
+        pps: float = 0.0,
+        output_dir: str | None = None,
+    ) -> list[dict[str, Any]]:
+        raise NotImplementedError("stub_pipeline is a forward-compatibility fixture")
+
+    def cleanup(self) -> None:
+        raise NotImplementedError("stub_pipeline is a forward-compatibility fixture")
+
+    def get_schema(self) -> dict[str, Any]:
+        raise NotImplementedError("stub_pipeline is a forward-compatibility fixture")
diff --git a/tests/integration/test_extras_isolation.py b/tests/integration/test_extras_isolation.py
new file mode 100644
index 0000000..438bb6e
--- /dev/null
+++ b/tests/integration/test_extras_isolation.py
@@ -0,0 +1,118 @@
+"""Integration test: extras groups actually isolate their dependencies.
+
+Installs `videoannotator[scene]` into a throwaway virtual environment and
+confirms torch/open-clip-torch are importable there while pyannote.audio/
+ultralytics/deepface are not (quickstart.md §1, User Story 1).
+
+This is a real network+build operation (pip/uv resolving and downloading
+torch et al.), so it's opt-in like the rest of this repo's "_real" /
+network-bound suites: set VIDEOANNOTATOR_RUN_EXTRAS_ISOLATION=1 to run it.
+It's meant for a dedicated CI job (plan.md), not routine local `pytest tests/`.
+"""
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+pytestmark = pytest.mark.slow
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+
+RUN_FLAG = "VIDEOANNOTATOR_RUN_EXTRAS_ISOLATION"
+
+
+def _skip_unless_enabled():
+    if os.environ.get(RUN_FLAG) != "1":
+        pytest.skip(
+            f"Set {RUN_FLAG}=1 to run the (network+build heavy) extras "
+            "isolation test — see tests/integration/test_extras_isolation.py"
+        )
+    if shutil.which("uv") is None:
+        pytest.skip("uv is not on PATH; required to install into a clean venv")
+
+
+def _venv_python(venv_dir: Path) -> Path:
+    if sys.platform == "win32":
+        return venv_dir / "Scripts" / "python.exe"
+    return venv_dir / "bin" / "python"
+
+
+def _is_importable(python: Path, module: str) -> bool:
+    result = subprocess.run(
+        [str(python), "-c", f"import {module}"],
+        capture_output=True,
+        text=True,
+    )
+    return result.returncode == 0
+
+
+class TestExtrasIsolation:
+    def test_scene_extra_pulls_only_its_own_deps(self, tmp_path):
+        """`pip install videoannotator[scene]` gets torch/open-clip-torch,
+        not pyannote/ultralytics/deepface (research.md §1)."""
+        _skip_unless_enabled()
+
+        venv_dir = tmp_path / "va-scene"
+        subprocess.run([sys.executable, "-m", "venv", str(venv_dir)], check=True)
+        python = _venv_python(venv_dir)
+
+        subprocess.run(
+            [
+                str(python),
+                "-m",
+                "pip",
+                "install",
+                "--quiet",
+                f"{REPO_ROOT}[scene]",
+            ],
+            check=True,
+        )
+
+        assert _is_importable(python, "torch")
+        assert _is_importable(python, "open_clip")
+        assert _is_importable(python, "scenedetect")
+
+        assert not _is_importable(python, "pyannote.audio")
+        assert not _is_importable(python, "ultralytics")
+        assert not _is_importable(python, "deepface")
+
+    def test_scene_pipeline_available_face_pipeline_is_not(self, tmp_path):
+        """The registry reflects the same isolation: `scene_detection`
+        loads, `face_analysis` doesn't, with an actionable reason
+        (quickstart.md §1)."""
+        _skip_unless_enabled()
+
+        venv_dir = tmp_path / "va-scene-registry"
+        subprocess.run([sys.executable, "-m", "venv", str(venv_dir)], check=True)
+        python = _venv_python(venv_dir)
+
+        subprocess.run(
+            [
+                str(python),
+                "-m",
+                "pip",
+                "install",
+                "--quiet",
+                f"{REPO_ROOT}[scene]",
+            ],
+            check=True,
+        )
+
+        check_script = (
+            "from videoannotator.registry.pipeline_loader import get_pipeline_loader\n"
+            "classes = get_pipeline_loader().load_all_pipelines()\n"
+            "assert 'scene_detection' in classes, classes.keys()\n"
+            "assert 'face_analysis' not in classes, classes.keys()\n"
+            "print('OK')\n"
+        )
+        result = subprocess.run(
+            [str(python), "-c", check_script],
+            capture_output=True,
+            text=True,
+        )
+        assert result.returncode == 0, result.stdout + result.stderr
+        assert "OK" in result.stdout
diff --git a/tests/integration/test_model_cache_reuse.py b/tests/integration/test_model_cache_reuse.py
new file mode 100644
index 0000000..96ef723
--- /dev/null
+++ b/tests/integration/test_model_cache_reuse.py
@@ -0,0 +1,52 @@
+"""Integration test: the extras-aware registry/loader never touches the
+user's model cache (HF_HOME / TORCH_HOME) — a pre-existing cache directory
+is left exactly as-is, not cleared or re-populated, when pipelines are
+loaded (User Story 2 / FR-015-equivalent guarantee, plan.md's Storage note).
+
+This doesn't need real models: it plants a marker file standing in for a
+cached model, points HF_HOME/TORCH_HOME at that directory, runs the full
+registry+loader load path, and asserts the marker file (and its mtime) is
+untouched.
+"""
+
+import os
+
+from videoannotator.registry.pipeline_loader import get_pipeline_loader
+from videoannotator.registry.pipeline_registry import get_registry
+
+
+class TestModelCacheReuse:
+    def test_registry_load_does_not_touch_hf_cache(self, tmp_path, monkeypatch):
+        hf_home = tmp_path / "hf_cache"
+        hf_home.mkdir()
+        cached_model = hf_home / "models--fake--cached-model" / "snapshot.bin"
+        cached_model.parent.mkdir(parents=True)
+        cached_model.write_bytes(b"pretend this is a downloaded model weight")
+        mtime_before = cached_model.stat().st_mtime
+
+        monkeypatch.setenv("HF_HOME", str(hf_home))
+
+        registry = get_registry()
+        registry.load(force=True)
+
+        assert cached_model.exists()
+        assert cached_model.stat().st_mtime == mtime_before
+        assert cached_model.read_bytes() == b"pretend this is a downloaded model weight"
+        assert os.environ["HF_HOME"] == str(hf_home)
+
+    def test_pipeline_loader_does_not_touch_torch_cache(self, tmp_path, monkeypatch):
+        torch_home = tmp_path / "torch_cache"
+        torch_home.mkdir()
+        cached_weight = torch_home / "hub" / "checkpoints" / "yolo11n.pt"
+        cached_weight.parent.mkdir(parents=True)
+        cached_weight.write_bytes(b"pretend this is a cached torch checkpoint")
+        mtime_before = cached_weight.stat().st_mtime
+
+        monkeypatch.setenv("TORCH_HOME", str(torch_home))
+
+        loader = get_pipeline_loader()
+        loader.load_all_pipelines()
+
+        assert cached_weight.exists()
+        assert cached_weight.stat().st_mtime == mtime_before
+        assert os.environ["TORCH_HOME"] == str(torch_home)
diff --git a/tests/integration/test_v144_parity.py b/tests/integration/test_v144_parity.py
new file mode 100644
index 0000000..88a93f0
--- /dev/null
+++ b/tests/integration/test_v144_parity.py
@@ -0,0 +1,151 @@
+"""Integration test: v1.4.4 -> v1.5.0 output parity under an `[all]` install
+(User Story 2, FR-009, quickstart.md §3).
+
+Deterministic pipelines (e.g. scene_detection's shot-boundary detection,
+person_tracking's detection/tracking given a fixed seed) must produce
+byte-identical output to the v1.4.4 baseline; non-deterministic ones
+(anything involving sampling or backend-dependent floating point, e.g.
+Whisper decoding or pyannote clustering) get a documented relative
+tolerance instead of exact equality.
+
+Golden fixtures would live in tests/fixtures/v144_golden/<pipeline>.json,
+captured once from the `v1.4.4` git tag in a fully-provisioned `[all]`
+environment (real model downloads + inference — not something to do as
+part of routine `pytest tests/`):
+
+    git worktree add /tmp/va-v144 v1.4.4
+    cd /tmp/va-v144 && uv sync --all-extras
+    # run each pipeline against a fixed sample video/config, serialize its
+    # output to tests/fixtures/v144_golden/<pipeline>.json
+
+No such fixtures exist yet in this repo, and no runner that produces
+comparable current-codebase output exists yet either — both are follow-up
+work. The comparison tests below are structurally complete (they'll run
+for real the moment fixtures + a runner are added) and skip themselves
+with a specific reason until then, rather than asserting something
+nothing was actually verified against. The tolerance-comparison helper
+itself is exercised directly by a real, always-on unit test.
+"""
+
+import json
+from pathlib import Path
+
+import pytest
+
+GOLDEN_DIR = Path(__file__).resolve().parents[1] / "fixtures" / "v144_golden"
+
+# FR-009: pipelines whose output is deterministic given the same input/config
+# get byte-identical comparison; everything else gets a documented tolerance.
+DETERMINISTIC_PIPELINES = {"scene_detection", "person_tracking"}
+NON_DETERMINISTIC_TOLERANCE = {
+    # pipeline_name: (relative float tolerance, rationale)
+    "audio_processing": (1e-3, "Whisper decoding can vary slightly by backend/BLAS"),
+    "speech_recognition": (1e-3, "same as audio_processing"),
+    "speaker_diarization": (1e-2, "pyannote clustering has run-to-run jitter"),
+}
+
+
+def _run_pipeline_for_parity(pipeline_name: str):
+    """Run `pipeline_name` against the shared parity sample video/config and
+    return its JSON-serializable output, for comparison against a v1.4.4
+    golden fixture.
+
+    Not implemented: no golden fixtures exist yet to compare against (see
+    module docstring), so this is never called in practice today. Building
+    it is a prerequisite for adding real fixtures, not optional scaffolding.
+    """
+    raise NotImplementedError(
+        "No golden-fixture capture/comparison tooling exists yet. To add "
+        "real v1.4.4 parity coverage: check out the `v1.4.4` git tag into a "
+        "fully-provisioned `[all]` environment, run "
+        f"'{pipeline_name}' against a fixed sample video, serialize its "
+        f"output to tests/fixtures/v144_golden/{pipeline_name}.json, and "
+        "implement this function to produce the same shape from the "
+        "current codebase."
+    )
+
+
+def _assert_within_tolerance(current, golden, tolerance: float):
+    """Recursively compare `current` vs `golden`: `tolerance` relative
+    error on float leaves, exact equality everywhere else."""
+    if isinstance(golden, dict):
+        assert isinstance(current, dict) and current.keys() == golden.keys()
+        for key in golden:
+            _assert_within_tolerance(current[key], golden[key], tolerance)
+    elif isinstance(golden, list):
+        assert isinstance(current, list) and len(current) == len(golden)
+        for c, g in zip(current, golden, strict=True):
+            _assert_within_tolerance(c, g, tolerance)
+    elif isinstance(golden, float):
+        assert current == pytest.approx(golden, rel=tolerance)
+    else:
+        assert current == golden
+
+
+class TestToleranceComparisonHelper:
+    """Real, always-on coverage of the comparison logic itself, independent
+    of whether golden fixtures exist yet."""
+
+    def test_identical_structures_pass(self):
+        data = {"a": 1, "b": [1.0, 2.0], "c": "text"}
+        _assert_within_tolerance(data, data, tolerance=1e-6)
+
+    def test_float_within_tolerance_passes(self):
+        golden = {"score": 0.700000}
+        current = {"score": 0.700049}  # ~0.007% relative difference
+        _assert_within_tolerance(current, golden, tolerance=1e-3)
+
+    def test_float_outside_tolerance_fails(self):
+        golden = {"score": 0.7}
+        current = {"score": 0.9}
+        with pytest.raises(AssertionError):
+            _assert_within_tolerance(current, golden, tolerance=1e-3)
+
+    def test_non_float_mismatch_fails_exactly(self):
+        golden = {"label": "cat"}
+        current = {"label": "dog"}
+        with pytest.raises(AssertionError):
+            _assert_within_tolerance(current, golden, tolerance=1e-3)
+
+
+class TestV144Parity:
+    def test_golden_fixtures_documented_but_not_yet_captured(self):
+        fixtures = sorted(GOLDEN_DIR.glob("*.json")) if GOLDEN_DIR.exists() else []
+        if not fixtures:
+            pytest.skip(
+                f"No v1.4.4 golden fixtures in {GOLDEN_DIR} yet — see this "
+                "file's module docstring for how to capture them from the "
+                "v1.4.4 git tag. Nothing to compare against until then."
+            )
+
+    @pytest.mark.parametrize("pipeline_name", sorted(DETERMINISTIC_PIPELINES))
+    def test_deterministic_pipeline_matches_v144_byte_identical(self, pipeline_name):
+        fixture_path = GOLDEN_DIR / f"{pipeline_name}.json"
+        if not fixture_path.exists():
+            pytest.skip(
+                f"No golden fixture for '{pipeline_name}' at {fixture_path} yet"
+            )
+
+        golden = json.loads(fixture_path.read_text())
+        current = _run_pipeline_for_parity(pipeline_name)
+
+        assert current == golden, (
+            f"'{pipeline_name}' is a deterministic pipeline (FR-009) — its "
+            "v1.5.0 output must be byte-identical to the v1.4.4 golden fixture."
+        )
+
+    @pytest.mark.parametrize("pipeline_name", sorted(NON_DETERMINISTIC_TOLERANCE))
+    def test_non_deterministic_pipeline_matches_v144_within_tolerance(
+        self, pipeline_name
+    ):
+        fixture_path = GOLDEN_DIR / f"{pipeline_name}.json"
+        if not fixture_path.exists():
+            pytest.skip(
+                f"No golden fixture for '{pipeline_name}' at {fixture_path} yet"
+            )
+
+        tolerance, _rationale = NON_DETERMINISTIC_TOLERANCE[pipeline_name]
+        golden = json.loads(fixture_path.read_text())
+        current = _run_pipeline_for_parity(pipeline_name)
+
+        _assert_within_tolerance(current, golden, tolerance)
diff --git a/tests/unit/registry/test_forward_compat_stub.py b/tests/unit/registry/test_forward_compat_stub.py
new file mode 100644
index 0000000..f5d09eb
--- /dev/null
+++ b/tests/unit/registry/test_forward_compat_stub.py
@@ -0,0 +1,54 @@
+"""Forward-compatibility gate: a stub pipeline with `requires_extras: []`
+plus a non-ML `backends` value loads through the registry and the loader
+with zero code changes (spec 004 User Story 3 / SC-007, quickstart.md §6).
+
+This is the concrete proof that v1.6.0's Ollama `llm` extras group and
+v1.7.0+'s HTTP/Slurm-dispatched pipelines can be added as pure data
+(YAML + a `[project.optional-dependencies]` entry) without touching
+PipelineMetadata or pipeline_loader.py again.
+"""
+
+from pathlib import Path
+
+from videoannotator.registry.pipeline_loader import PipelineLoader
+from videoannotator.registry.pipeline_registry import PipelineRegistry
+
+FIXTURES_DIR = Path(__file__).resolve().parents[2] / "fixtures"
+
+
+class TestForwardCompatStub:
+    def test_stub_pipeline_loads_via_registry(self):
+        registry = PipelineRegistry(metadata_dir=FIXTURES_DIR)
+        registry.load(force=True)
+
+        meta = registry.get("stub_pipeline")
+
+        assert meta is not None
+        assert meta.requires_extras == []
+        assert meta.backends == ["http"]
+        assert meta.module_path == "tests.fixtures.stub_pipeline_module:StubPipeline"
+
+    def test_stub_pipeline_class_loads_via_loader_with_zero_loader_changes(self):
+        """requires_extras: [] must be vacuously "available" (research.md
+        §2), so the loader resolves and imports the stub class exactly like
+        any other pipeline — no special-casing for an empty extras list."""
+        registry = PipelineRegistry(metadata_dir=FIXTURES_DIR)
+        registry.load(force=True)
+
+        loader = PipelineLoader()
+        loader._registry = registry  # point the loader at our stub-only registry
+
+        classes = loader.load_all_pipelines()
+
+        assert "stub_pipeline" in classes
+        stub_class = classes["stub_pipeline"]
+        assert stub_class.__name__ == "StubPipeline"
+
+        # It's a real (if unimplemented) pipeline: instantiating and calling
+        # it raises NotImplementedError, not an import/loading error.
+        instance = stub_class()
+        try:
+            instance.initialize()
+            raise AssertionError("expected NotImplementedError")
+        except NotImplementedError:
+            pass
diff --git a/tests/unit/registry/test_pipeline_registry.py b/tests/unit/registry/test_pipeline_registry.py
new file mode 100644
index 0000000..3b2ded6
--- /dev/null
+++ b/tests/unit/registry/test_pipeline_registry.py
@@ -0,0 +1,143 @@
+"""Unit tests for extras-based metadata parsing and availability checking.
+
+Covers: `requires_extras` parsing (data-model.md), `module_path`-required
+validation (contracts/pipeline-metadata-schema.md), and the
+extras-availability helper in `pipeline_loader.py` (research.md §3).
+"""
+
+import logging
+
+from videoannotator.registry import pipeline_loader
+from videoannotator.registry.pipeline_registry import PipelineRegistry
+
+VALID_YAML = """\
+name: {name}
+display_name: Test Pipeline
+description: A test pipeline.
+{module_path_line}
+{requires_extras_line}
+outputs:
+  - format: JSON
+    types: [test]
+config_schema:
+  foo:
+    type: string
+    default: bar
+version: 1
+"""
+
+
+def _write_metadata(
+    tmp_path,
+    filename,
+    name="test_pipeline",
+    module_path="videoannotator.pipelines.scene_detection:SceneDetectionPipeline",
+    requires_extras=None,
+):
+    module_path_line = f"module_path: {module_path}" if module_path else ""
+    requires_extras_line = (
+        f"requires_extras: [{', '.join(requires_extras)}]"
+        if requires_extras is not None
+        else ""
+    )
+    content = VALID_YAML.format(
+        name=name,
+        module_path_line=module_path_line,
+        requires_extras_line=requires_extras_line,
+    )
+    (tmp_path / filename).write_text(content)
+
+
+class TestRequiresExtrasParsing:
+    def test_parses_requires_extras_list(self, tmp_path):
+        _write_metadata(tmp_path, "test.yaml", requires_extras=["scene", "extra2"])
+        reg = PipelineRegistry(metadata_dir=tmp_path)
+        reg.load(force=True)
+        meta = reg.get("test_pipeline")
+
+        assert meta is not None
+        assert meta.requires_extras == ["scene", "extra2"]
+        assert meta.module_path == (
+            "videoannotator.pipelines.scene_detection:SceneDetectionPipeline"
+        )
+
+    def test_requires_extras_absent_defaults_to_empty_list(self, tmp_path):
+        _write_metadata(tmp_path, "test.yaml", requires_extras=None)
+        reg = PipelineRegistry(metadata_dir=tmp_path)
+        reg.load(force=True)
+        meta = reg.get("test_pipeline")
+
+        assert meta is not None
+        assert meta.requires_extras == []
+
+    def test_requires_extras_empty_list_is_valid(self, tmp_path):
+        _write_metadata(tmp_path, "test.yaml", requires_extras=[])
+        reg = PipelineRegistry(metadata_dir=tmp_path)
+        reg.load(force=True)
+        meta = reg.get("test_pipeline")
+
+        assert meta is not None
+        assert meta.requires_extras == []
+
+
+class TestModulePathRequired:
+    def test_missing_module_path_is_skipped_with_warning(self, tmp_path, caplog):
+        _write_metadata(tmp_path, "bad.yaml", module_path=None)
+        reg = PipelineRegistry(metadata_dir=tmp_path)
+
+        with caplog.at_level(logging.WARNING):
+            reg.load(force=True)
+
+        assert reg.get("test_pipeline") is None
+        assert any("module_path" in record.message for record in caplog.records)
+
+    def test_present_module_path_loads_successfully(self, tmp_path):
+        _write_metadata(tmp_path, "good.yaml")
+        reg = PipelineRegistry(metadata_dir=tmp_path)
+        reg.load(force=True)
+
+        assert reg.get("test_pipeline") is not None
+
+
+class TestExtrasAvailabilityHelper:
+    def test_empty_requires_extras_is_vacuously_available(self):
+        assert pipeline_loader.extras_available([]) is True
+
+    def test_extras_available_false_when_a_package_missing(self, monkeypatch):
+        monkeypatch.setattr(
+            pipeline_loader,
+            "_packages_for_extra",
+            lambda extra: ("totally_fake_pkg_xyz",) if extra == "needs_pkg" else (),
+        )
+        monkeypatch.setattr(
+            pipeline_loader,
+            "_is_distribution_installed",
+            lambda name: name != "totally_fake_pkg_xyz",
+        )
+
+        assert pipeline_loader.extras_available(["needs_pkg"]) is False
+        assert pipeline_loader.extras_available(["other_group"]) is True
+
+    def test_missing_extras_returns_only_unavailable_groups(self, monkeypatch):
+        monkeypatch.setattr(
+            pipeline_loader,
+            "_packages_for_extra",
+            lambda extra: ("missing_pkg",) if extra == "grp" else ("present_pkg",),
+        )
+        monkeypatch.setattr(
+            pipeline_loader,
+            "_is_distribution_installed",
+            lambda name: name != "missing_pkg",
+        )
+
+        assert pipeline_loader.missing_extras(["grp", "other"]) == ["grp"]
+
+    def test_install_hint_names_exact_pip_command(self):
+        assert (
+            pipeline_loader.install_hint(["face-laion"])
+            == "pip install videoannotator[face-laion]"
+        )
+        assert (
+            pipeline_loader.install_hint(["face-laion", "audio"])
+            == "pip install videoannotator[face-laion,audio]"
+        )
diff --git a/uv.lock b/uv.lock
index ced7871..cf58e4b 100644
--- a/uv.lock
+++ b/uv.lock
@@ -9,6 +9,15 @@ resolution-markers = [
     "sys_platform != 'darwin' and sys_platform != 'linux' and sys_platform != 'win32'",
 ]
 
+[[package]]
+name = "absl-py"
+version = "2.5.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d0/4f/d79676ab82f2e42fc3611618139f13a9c4c31d0cff4b486982047679a802/absl_py-2.5.0.tar.gz", hash = "sha256:0c996f25c0490700fadabe6351630f6111534fa0ae252cc6d2014ea3b141135f", size = 118119, upload-time = "2026-07-03T10:57:48.157Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/58/0a/a10b45aab35b175aded078a462dc8d0c698f5b13946e7cb0869097b78bb6/absl_py-2.5.0-py3-none-any.whl", hash = "sha256:0f17b89f2a4eaaedc4f28c622998aa690564b3012a396a4ffad0821007fe03ba", size = 137410, upload-time = "2026-07-03T10:57:46.735Z" },
+]
+
 [[package]]
 name = "accelerate"
 version = "1.10.0"
@@ -206,6 +215,19 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/25/8a/c46dcc25341b5bce5472c718902eb3d38600a903b14fa6aeecef3f21a46f/asttokens-3.0.0-py3-none-any.whl", hash = "sha256:e3078351a059199dd5138cb1c706e6430c05eff2ff136af5eb4790f9d28932e2", size = 26918, upload-time = "2024-11-30T04:30:10.946Z" },
 ]
 
+[[package]]
+name = "astunparse"
+version = "1.6.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "six" },
+    { name = "wheel" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f3/af/4182184d3c338792894f34a62672919db7ca008c89abee9b564dd34d8029/astunparse-1.6.3.tar.gz", hash = "sha256:5ad93a8456f0d084c3456d059fd9a92cce667963232cbf763eac3bc5b7940872", size = 18290, upload-time = "2019-12-22T18:12:13.129Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2b/03/13dde6512ad7b4557eb792fbcf0c653af6076b81e5941d36ec61f7ce6028/astunparse-1.6.3-py2.py3-none-any.whl", hash = "sha256:c2652417f2c8b5bb325c885ae329bdf3f86424075c4fd1a128674bc6fba4b8e8", size = 12732, upload-time = "2019-12-22T18:12:11.297Z" },
+]
+
 [[package]]
 name = "async-lru"
 version = "2.0.5"
@@ -289,6 +311,15 @@ css = [
     { name = "tinycss2" },
 ]
 
+[[package]]
+name = "blinker"
+version = "1.9.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/21/28/9b3f50ce0e048515135495f198351908d99540d69bfdc8c1d15b73dc55ce/blinker-1.9.0.tar.gz", hash = "sha256:b4ce2265a7abece45e7cc896e98dbebe6cead56bcf805a3d23136d145f5445bf", size = 22460, upload-time = "2024-11-08T17:25:47.436Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/10/cb/f2ad4230dc2eb1a74edf38f1a38b9b52277f75bef262d8908e60d957e13c/blinker-1.9.0-py3-none-any.whl", hash = "sha256:ba0efaa9080b619ff2f3459d1d500c57bddea4a6b424b60a91141db6fd2f08bc", size = 8458, upload-time = "2024-11-08T17:25:46.184Z" },
+]
+
 [[package]]
 name = "certifi"
 version = "2025.8.3"
@@ -523,6 +554,35 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/4e/8c/f3147f5c4b73e7550fe5f9352eaa956ae838d5c51eb58e7a25b9f3e2643b/decorator-5.2.1-py3-none-any.whl", hash = "sha256:d316bb415a2d9e2d2b3abcc4084c6502fc09240e292cd76a76afc106a1c8e04a", size = 9190, upload-time = "2025-02-24T04:41:32.565Z" },
 ]
 
+[[package]]
+name = "deepface"
+version = "0.0.100"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "fire" },
+    { name = "flask" },
+    { name = "flask-cors" },
+    { name = "gdown" },
+    { name = "gunicorn" },
+    { name = "keras" },
+    { name = "lightdsa" },
+    { name = "lightphe" },
+    { name = "mtcnn" },
+    { name = "numpy" },
+    { name = "opencv-python" },
+    { name = "pandas" },
+    { name = "pillow" },
+    { name = "python-dotenv" },
+    { name = "requests" },
+    { name = "retina-face" },
+    { name = "tensorflow" },
+    { name = "tqdm" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5c/95/c895451f8a3cfa6b212a9cb9d1b2728cf38ef199a1422f82f931fb89d16e/deepface-0.0.100.tar.gz", hash = "sha256:6aac0b3a5d7b3d8edf59a344ee115f69635b09be4d997410dcdcc1e4736547c0", size = 137539, upload-time = "2026-05-09T18:28:31.927Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/40/62/75631dde60348081938cbb8e1576912a2a31242a77256d784a89146cffc5/deepface-0.0.100-py3-none-any.whl", hash = "sha256:b748c940280bc8f2609741bc4641c1a79af4dd53275611ad8697feeb1ae6fa00", size = 170678, upload-time = "2026-05-09T18:28:29.936Z" },
+]
+
 [[package]]
 name = "defusedxml"
 version = "0.7.1"
@@ -637,6 +697,56 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/42/14/42b2651a2f46b022ccd948bca9f2d5af0fd8929c4eec235b8d6d844fbe67/filelock-3.19.1-py3-none-any.whl", hash = "sha256:d38e30481def20772f5baf097c122c3babc4fcdb7e14e57049eb9d88c6dc017d", size = 15988, upload-time = "2025-08-14T16:56:01.633Z" },
 ]
 
+[[package]]
+name = "fire"
+version = "0.7.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "termcolor" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c0/00/f8d10588d2019d6d6452653def1ee807353b21983db48550318424b5ff18/fire-0.7.1.tar.gz", hash = "sha256:3b208f05c736de98fb343310d090dcc4d8c78b2a89ea4f32b837c586270a9cbf", size = 88720, upload-time = "2025-08-16T20:20:24.175Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e5/4c/93d0f85318da65923e4b91c1c2ff03d8a458cbefebe3bc612a6693c7906d/fire-0.7.1-py3-none-any.whl", hash = "sha256:e43fd8a5033a9001e7e2973bab96070694b9f12f2e0ecf96d4683971b5ab1882", size = 115945, upload-time = "2025-08-16T20:20:22.87Z" },
+]
+
+[[package]]
+name = "flask"
+version = "3.1.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "blinker" },
+    { name = "click" },
+    { name = "itsdangerous" },
+    { name = "jinja2" },
+    { name = "markupsafe" },
+    { name = "werkzeug" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/26/00/35d85dcce6c57fdc871f3867d465d780f302a175ea360f62533f12b27e2b/flask-3.1.3.tar.gz", hash = "sha256:0ef0e52b8a9cd932855379197dd8f94047b359ca0a78695144304cb45f87c9eb", size = 759004, upload-time = "2026-02-19T05:00:57.678Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7f/9c/34f6962f9b9e9c71f6e5ed806e0d0ff03c9d1b0b2340088a0cf4bce09b18/flask-3.1.3-py3-none-any.whl", hash = "sha256:f4bcbefc124291925f1a26446da31a5178f9483862233b23c0c96a20701f670c", size = 103424, upload-time = "2026-02-19T05:00:56.027Z" },
+]
+
+[[package]]
+name = "flask-cors"
+version = "6.0.5"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "flask" },
+    { name = "werkzeug" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/47/03/4e464a50860f9adf08b5c1d3479cb8ea1f12af2aa69535c7042c6e628135/flask_cors-6.0.5.tar.gz", hash = "sha256:30c5031552cd59f620ac0c8211dac45b345d3b2df310e7721879e4f46ef9c601", size = 101386, upload-time = "2026-06-08T20:20:17.765Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/49/55/5bb1a2d918e9f02f131e47a59032bae70e48050e986e941511fd737a935c/flask_cors-6.0.5-py3-none-any.whl", hash = "sha256:68fcf75693e961f3af26683b23c4b9a8fb6b64de17d20d0c37b95e8de7ab2ed8", size = 16692, upload-time = "2026-06-08T20:20:16.247Z" },
+]
+
+[[package]]
+name = "flatbuffers"
+version = "25.12.19"
+source = { registry = "https://pypi.org/simple" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e8/2d/d2a548598be01649e2d46231d151a6c56d10b964d94043a335ae56ea2d92/flatbuffers-25.12.19-py2.py3-none-any.whl", hash = "sha256:7634f50c427838bb021c2d66a3d1168e9d199b0607e6329399f04846d42e20b4", size = 26661, upload-time = "2025-12-19T23:16:13.622Z" },
+]
+
 [[package]]
 name = "fonttools"
 version = "4.59.1"
@@ -715,6 +825,42 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/ab/6e/81d47999aebc1b155f81eca4477a616a70f238a2549848c38983f3c22a82/ftfy-6.3.1-py3-none-any.whl", hash = "sha256:7c70eb532015cd2f9adb53f101fb6c7945988d023a085d127d1573dc49dd0083", size = 44821, upload-time = "2024-10-26T00:50:33.425Z" },
 ]
 
+[[package]]
+name = "gast"
+version = "0.7.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/91/f6/e73969782a2ecec280f8a176f2476149dd9dba69d5f8779ec6108a7721e6/gast-0.7.0.tar.gz", hash = "sha256:0bb14cd1b806722e91ddbab6fb86bba148c22b40e7ff11e248974e04c8adfdae", size = 33630, upload-time = "2025-11-29T15:30:05.266Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1d/33/f1c6a276de27b7d7339a34749cc33fa87f077f921969c47185d34a887ae2/gast-0.7.0-py3-none-any.whl", hash = "sha256:99cbf1365633a74099f69c59bd650476b96baa5ef196fec88032b00b31ba36f7", size = 22966, upload-time = "2025-11-29T15:30:03.983Z" },
+]
+
+[[package]]
+name = "gdown"
+version = "6.1.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "beautifulsoup4" },
+    { name = "filelock" },
+    { name = "requests", extra = ["socks"] },
+    { name = "tqdm" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/6a/b5/a45f62f20664031bf74a6aeb6f8d8cd5910e411bf90d756bd6b09bdc6c35/gdown-6.1.0.tar.gz", hash = "sha256:361c6e04c6ca335df50b9d71f40bcfe9ab70fb26a1b0e890a427267781389553", size = 269670, upload-time = "2026-05-30T11:56:21.322Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7d/56/a99f0f159cce5b26d267317d436afee184f45fc7911938757d7cbbd2d10c/gdown-6.1.0-py3-none-any.whl", hash = "sha256:38a36a94275b8272f684db469bbd73b4d1f64cbbc1751bcb993a1b2be8f013c8", size = 19216, upload-time = "2026-05-30T11:56:20.016Z" },
+]
+
+[[package]]
+name = "google-pasta"
+version = "0.2.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "six" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/35/4a/0bd53b36ff0323d10d5f24ebd67af2de10a1117f5cf4d7add90df92756f1/google-pasta-0.2.0.tar.gz", hash = "sha256:c9f2c8dfc8f96d0d5808299920721be30c9eec37f2389f28904f454565c8a16e", size = 40430, upload-time = "2020-03-13T18:57:50.34Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a3/de/c648ef6835192e6e2cc03f40b19eeda4382c49b5bafb43d88b931c4c74ac/google_pasta-0.2.0-py3-none-any.whl", hash = "sha256:b32482794a366b5366a32c92a9a9201b107821889935a02b3e51f6b432ea84ed", size = 57471, upload-time = "2020-03-13T18:57:48.872Z" },
+]
+
 [[package]]
 name = "greenlet"
 version = "3.2.4"
@@ -733,6 +879,39 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/e9/08/b0814846b79399e585f974bbeebf5580fbe59e258ea7be64d9dfb253c84f/greenlet-3.2.4-cp312-cp312-win_amd64.whl", hash = "sha256:a7d4e128405eea3814a12cc2605e0e6aedb4035bf32697f72deca74de4105e02", size = 299899, upload-time = "2025-08-07T13:38:53.448Z" },
 ]
 
+[[package]]
+name = "grpcio"
+version = "1.82.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/90/bc/656b89387d6f4ed7e0686c7b64c2ae7e554a759aa58122c8e5fb99392c32/grpcio-1.82.1.tar.gz", hash = "sha256:707b24abd90fcb1e45bcc080577da1dbf9971d107490589b9539af8e1e77b4b5", size = 13187300, upload-time = "2026-07-08T12:36:16.588Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/dc/88/d1350bf3343a2ed87d801584e40609f6c6bd3087926eeca03de50348cf4a/grpcio-1.82.1-cp312-cp312-linux_armv7l.whl", hash = "sha256:c09bd5fa0d5b1fbd773ec349fe61441c3e4ebf168c229aa7538a820bdfad6a58", size = 6144689, upload-time = "2026-07-08T12:34:55.567Z" },
+    { url = "https://files.pythonhosted.org/packages/e6/33/71875cdecd27c24ac1385d4783a09853f01b84a825a36aec2a2bc7d0d080/grpcio-1.82.1-cp312-cp312-macosx_11_0_universal2.whl", hash = "sha256:1eae24810720734598e3e6a1a528d5de0f265fe3fc86575e9ecce424b9ec7379", size = 11952034, upload-time = "2026-07-08T12:34:58.128Z" },
+    { url = "https://files.pythonhosted.org/packages/82/b2/d9125df3d8a140dec12cc82c05b7deafedeababcff6496f28b2fd5634d10/grpcio-1.82.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:a6bd5daf5bde7b24d7ad2cbaf8bf9eac620d96222016bb5e7ddde930dec0673f", size = 6710772, upload-time = "2026-07-08T12:35:01.33Z" },
+    { url = "https://files.pythonhosted.org/packages/88/9b/69e2d1627398b964f34437dc476a5aff5a2cc8e7f247d26272b5674b5faf/grpcio-1.82.1-cp312-cp312-manylinux2014_i686.manylinux_2_17_i686.whl", hash = "sha256:1ecfde669cb687ac020d31ff76debe5dc7a62213335f02262eb6625628da1c03", size = 7450677, upload-time = "2026-07-08T12:35:03.926Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/e7/8f855ca29c294956122a2a73023655b9b02602d5111dad2b9b00e7631c68/grpcio-1.82.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:011c8badee95734dee8bf05ce3464756a0ac3ebb8d443afd20c0e2b5e4640ad9", size = 6886855, upload-time = "2026-07-08T12:35:06.174Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/f0/fa87e85f49925f44c479d07e58b051e69bcfef6b6d5fbc6749d140f6730a/grpcio-1.82.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:b85f4564926fb23114d239392bdcae200db1e6179629edd7d7ab0ab89c96a197", size = 7501323, upload-time = "2026-07-08T12:35:08.49Z" },
+    { url = "https://files.pythonhosted.org/packages/67/55/2e0b10ae1d3ef9dcc480b91dc2158f4931fc4675d3af0a2836e39b2a744f/grpcio-1.82.1-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:2c0c8270833395644c3fe6b6a806397955a2bc0538000a19a78b90c05a6c16e0", size = 8536899, upload-time = "2026-07-08T12:35:10.975Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/95/a3d8b0431fa221efc51ee39d73595ede74ba82a43b7c4313192e580face2/grpcio-1.82.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:2ba199205ff46c7778290fe1673c91ac8e7e45678dd5c86e9e56fa33ec8788f6", size = 7913892, upload-time = "2026-07-08T12:35:13.944Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/92/f2651ec704d9852a56faef394775038afba435b50ce82ab2404d119c3355/grpcio-1.82.1-cp312-cp312-win32.whl", hash = "sha256:06127691866e295c14e84a1fb86356dd962254f6abd0da4ca4b001eea9e89438", size = 4240985, upload-time = "2026-07-08T12:35:16.048Z" },
+    { url = "https://files.pythonhosted.org/packages/96/4f/a5fe8bf0d0a1b24855f370293075c931f27de4eb55f0f158786095bf3c11/grpcio-1.82.1-cp312-cp312-win_amd64.whl", hash = "sha256:1fa3223a3a2e1db74f4c2b255189eb7ea875dfba56e221d252ee3fc7b204778e", size = 5001580, upload-time = "2026-07-08T12:35:18.689Z" },
+]
+
+[[package]]
+name = "gunicorn"
+version = "26.0.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "packaging" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/6d/b7/a4a3f632f823e432ce6bc65f62961b7980c898c77f075a2f7118cb3846fe/gunicorn-26.0.0.tar.gz", hash = "sha256:ca9346f85e3a4aeeb64d491045c16b9a35647abd37ea15efe53080eb8b090baf", size = 727286, upload-time = "2026-05-05T06:38:25.529Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e6/40/9c2384fc2be4ad25dd4a49decd5ad9ea5a3639814c11bd40ab77cb9f0a14/gunicorn-26.0.0-py3-none-any.whl", hash = "sha256:40233d26a5f0d1872916188c276e21641155111c2853f0c2cd55260aec0d24fc", size = 212009, upload-time = "2026-05-05T06:38:23.007Z" },
+]
+
 [[package]]
 name = "h11"
 version = "0.16.0"
@@ -742,6 +921,22 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/04/4b/29cac41a4d98d144bf5f6d33995617b185d14b22401f75ca86f384e87ff1/h11-0.16.0-py3-none-any.whl", hash = "sha256:63cf8bbe7522de3bf65932fda1d9c2772064ffb3dae62d55932da54b31cb6c86", size = 37515, upload-time = "2025-04-24T03:35:24.344Z" },
 ]
 
+[[package]]
+name = "h5py"
+version = "3.14.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "numpy" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5d/57/dfb3c5c3f1bf5f5ef2e59a22dec4ff1f3d7408b55bfcefcfb0ea69ef21c6/h5py-3.14.0.tar.gz", hash = "sha256:2372116b2e0d5d3e5e705b7f663f7c8d96fa79a4052d250484ef91d24d6a08f4", size = 424323, upload-time = "2025-06-06T14:06:15.01Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/3e/77/8f651053c1843391e38a189ccf50df7e261ef8cd8bfd8baba0cbe694f7c3/h5py-3.14.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:e0045115d83272090b0717c555a31398c2c089b87d212ceba800d3dc5d952e23", size = 3312740, upload-time = "2025-06-06T14:05:01.193Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/10/20436a6cf419b31124e59fefc78d74cb061ccb22213226a583928a65d715/h5py-3.14.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:6da62509b7e1d71a7d110478aa25d245dd32c8d9a1daee9d2a42dba8717b047a", size = 2829207, upload-time = "2025-06-06T14:05:05.061Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/19/c8bfe8543bfdd7ccfafd46d8cfd96fce53d6c33e9c7921f375530ee1d39a/h5py-3.14.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:554ef0ced3571366d4d383427c00c966c360e178b5fb5ee5bb31a435c424db0c", size = 4708455, upload-time = "2025-06-06T14:05:11.528Z" },
+    { url = "https://files.pythonhosted.org/packages/86/f9/f00de11c82c88bfc1ef22633557bfba9e271e0cb3189ad704183fc4a2644/h5py-3.14.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0cbd41f4e3761f150aa5b662df991868ca533872c95467216f2bec5fcad84882", size = 4929422, upload-time = "2025-06-06T14:05:18.399Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/6d/6426d5d456f593c94b96fa942a9b3988ce4d65ebaf57d7273e452a7222e8/h5py-3.14.0-cp312-cp312-win_amd64.whl", hash = "sha256:bf4897d67e613ecf5bdfbdab39a1158a64df105827da70ea1d90243d796d367f", size = 2862845, upload-time = "2025-06-06T14:05:23.699Z" },
+]
+
 [[package]]
 name = "hf-xet"
 version = "1.1.8"
@@ -977,6 +1172,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/7b/55/e5326141505c5d5e34c5e0935d2908a74e4561eca44108fbfb9c13d2911a/isoduration-20.11.0-py3-none-any.whl", hash = "sha256:b2904c2a4228c3d44f409c8ae8e2370eb21a26f7ac2ec5446df141dde3452042", size = 11321, upload-time = "2020-11-01T10:59:58.02Z" },
 ]
 
+[[package]]
+name = "itsdangerous"
+version = "2.2.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/9c/cb/8ac0172223afbccb63986cc25049b154ecfb5e85932587206f42317be31d/itsdangerous-2.2.0.tar.gz", hash = "sha256:e0050c0b7da1eea53ffaf149c0cfbb5c6e2e2b69c4bef22c81fa6eb73e5f6173", size = 54410, upload-time = "2024-04-16T21:28:15.614Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/04/96/92447566d16df59b2a776c0fb82dbc4d9e07cd95062562af01e408583fc4/itsdangerous-2.2.0-py3-none-any.whl", hash = "sha256:c6242fc49e35958c8b15141343aa660db5fc54d4f13a1db01a3f5891b98700ef", size = 16234, upload-time = "2024-04-16T21:28:14.499Z" },
+]
+
 [[package]]
 name = "jedi"
 version = "0.19.2"
@@ -1297,6 +1501,25 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/43/6a/ca128561b22b60bd5a0c4ea26649e68c8556b82bc70a0c396eebc977fe86/jupyterlab_widgets-3.0.15-py3-none-any.whl", hash = "sha256:d59023d7d7ef71400d51e6fee9a88867f6e65e10a4201605d2d7f3e8f012a31c", size = 216571, upload-time = "2025-05-05T12:32:29.534Z" },
 ]
 
+[[package]]
+name = "keras"
+version = "3.15.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "absl-py" },
+    { name = "h5py" },
+    { name = "ml-dtypes" },
+    { name = "namex" },
+    { name = "numpy" },
+    { name = "optree" },
+    { name = "packaging" },
+    { name = "rich" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/02/0a/c2524cda024e5b24038726de899c4b0ae2603dd0324a30cbc129d6b6314e/keras-3.15.0.tar.gz", hash = "sha256:0123749ac2a704d63f691994b18e432e006cb8ae910cc0ea7035d777aed9c00d", size = 1326815, upload-time = "2026-06-24T23:17:12.332Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d4/16/d506c09bbff25927a65d13c542cb4eedc2d573e304f38b6ac3f49ed6be9b/keras-3.15.0-py3-none-any.whl", hash = "sha256:9bbd7df12b7b53500d00dc24d97b7e066c771260482cb7118de0b7687a7a2781", size = 1696954, upload-time = "2026-06-24T23:17:10.808Z" },
+]
+
 [[package]]
 name = "kiwisolver"
 version = "1.4.9"
@@ -1339,6 +1562,23 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/83/60/d497a310bde3f01cb805196ac61b7ad6dc5dcf8dce66634dc34364b20b4f/lazy_loader-0.4-py3-none-any.whl", hash = "sha256:342aa8e14d543a154047afb4ba8ef17f5563baad3fc610d7b15b213b0f119efc", size = 12097, upload-time = "2024-04-05T13:03:10.514Z" },
 ]
 
+[[package]]
+name = "libclang"
+version = "18.1.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/6e/5c/ca35e19a4f142adffa27e3d652196b7362fa612243e2b916845d801454fc/libclang-18.1.1.tar.gz", hash = "sha256:a1214966d08d73d971287fc3ead8dfaf82eb07fb197680d8b3859dbbbbf78250", size = 39612, upload-time = "2024-03-17T16:04:37.434Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/4b/49/f5e3e7e1419872b69f6f5e82ba56e33955a74bd537d8a1f5f1eff2f3668a/libclang-18.1.1-1-py2.py3-none-macosx_11_0_arm64.whl", hash = "sha256:0b2e143f0fac830156feb56f9231ff8338c20aecfe72b4ffe96f19e5a1dbb69a", size = 25836045, upload-time = "2024-06-30T17:40:31.646Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/e5/fc61bbded91a8830ccce94c5294ecd6e88e496cc85f6704bf350c0634b70/libclang-18.1.1-py2.py3-none-macosx_10_9_x86_64.whl", hash = "sha256:6f14c3f194704e5d09769108f03185fce7acaf1d1ae4bbb2f30a72c2400cb7c5", size = 26502641, upload-time = "2024-03-18T15:52:26.722Z" },
+    { url = "https://files.pythonhosted.org/packages/db/ed/1df62b44db2583375f6a8a5e2ca5432bbdc3edb477942b9b7c848c720055/libclang-18.1.1-py2.py3-none-macosx_11_0_arm64.whl", hash = "sha256:83ce5045d101b669ac38e6da8e58765f12da2d3aafb3b9b98d88b286a60964d8", size = 26420207, upload-time = "2024-03-17T15:00:26.63Z" },
+    { url = "https://files.pythonhosted.org/packages/1d/fc/716c1e62e512ef1c160e7984a73a5fc7df45166f2ff3f254e71c58076f7c/libclang-18.1.1-py2.py3-none-manylinux2010_x86_64.whl", hash = "sha256:c533091d8a3bbf7460a00cb6c1a71da93bffe148f172c7d03b1c31fbf8aa2a0b", size = 24515943, upload-time = "2024-03-17T16:03:45.942Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/3d/f0ac1150280d8d20d059608cf2d5ff61b7c3b7f7bcf9c0f425ab92df769a/libclang-18.1.1-py2.py3-none-manylinux2014_aarch64.whl", hash = "sha256:54dda940a4a0491a9d1532bf071ea3ef26e6dbaf03b5000ed94dd7174e8f9592", size = 23784972, upload-time = "2024-03-17T16:12:47.677Z" },
+    { url = "https://files.pythonhosted.org/packages/fe/2f/d920822c2b1ce9326a4c78c0c2b4aa3fde610c7ee9f631b600acb5376c26/libclang-18.1.1-py2.py3-none-manylinux2014_armv7l.whl", hash = "sha256:cf4a99b05376513717ab5d82a0db832c56ccea4fd61a69dbb7bccf2dfb207dbe", size = 20259606, upload-time = "2024-03-17T16:17:42.437Z" },
+    { url = "https://files.pythonhosted.org/packages/2d/c2/de1db8c6d413597076a4259cea409b83459b2db997c003578affdd32bf66/libclang-18.1.1-py2.py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:69f8eb8f65c279e765ffd28aaa7e9e364c776c17618af8bff22a8df58677ff4f", size = 24921494, upload-time = "2024-03-17T16:14:20.132Z" },
+    { url = "https://files.pythonhosted.org/packages/0b/2d/3f480b1e1d31eb3d6de5e3ef641954e5c67430d5ac93b7fa7e07589576c7/libclang-18.1.1-py2.py3-none-win_amd64.whl", hash = "sha256:4dd2d3b82fab35e2bf9ca717d7b63ac990a3519c7e312f19fa8e86dcc712f7fb", size = 26415083, upload-time = "2024-03-17T16:42:21.703Z" },
+    { url = "https://files.pythonhosted.org/packages/71/cf/e01dc4cc79779cd82d77888a88ae2fa424d93b445ad4f6c02bfc18335b70/libclang-18.1.1-py2.py3-none-win_arm64.whl", hash = "sha256:3f0e1f49f04d3cd198985fea0511576b0aee16f9ff0e0f0cad7f9c57ec3c20e8", size = 22361112, upload-time = "2024-03-17T16:42:59.565Z" },
+]
+
 [[package]]
 name = "libcst"
 version = "1.8.5"
@@ -1382,6 +1622,32 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/b5/ba/c63c5786dfee4c3417094c4b00966e61e4a63efecee22cb7b4c0387dda83/librosa-0.11.0-py3-none-any.whl", hash = "sha256:0b6415c4fd68bff4c29288abe67c6d80b587e0e1e2cfb0aad23e4559504a7fa1", size = 260749, upload-time = "2025-03-11T15:09:52.982Z" },
 ]
 
+[[package]]
+name = "lightdsa"
+version = "0.0.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "lightecc" },
+    { name = "sympy" },
+    { name = "tqdm" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/31/e9/d54a2102150cb217bcd4d22b8961a807c988e16309212ffd856b9ec70dba/lightdsa-0.0.3.tar.gz", hash = "sha256:d4544278fba1e220ad250dbe06c6cb0b4f2bf4430127ccc3080b4ebf353e2b6e", size = 12906, upload-time = "2025-04-01T18:56:34.53Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/0a/49/ac1f258d4868bb8c8c4fbec7f9a69ffc755a525d25c4b0cf879717184cb2/lightdsa-0.0.3-py3-none-any.whl", hash = "sha256:ea9e91586d8002ab205a2638983de72304370856332e986347492a7bf579a38b", size = 17390, upload-time = "2025-04-01T18:56:33.16Z" },
+]
+
+[[package]]
+name = "lightecc"
+version = "0.0.7"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "tqdm" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/4c/6d/a04df6f657d1feeadf9ce3daaa05a00897b5b96b06ff5b071c167becce39/lightecc-0.0.7.tar.gz", hash = "sha256:31c10d460ed0b105878318b886306d89925567a80a3b051faa3bfd2fae71ea58", size = 46809, upload-time = "2026-06-09T08:03:33.854Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d0/4f/8beb6647342b578e0875788b7a52ba7c04f6fbb0ba95bb33cd2bbbfbe194/lightecc-0.0.7-py3-none-any.whl", hash = "sha256:4c0c23be95bcc058f4fab0d4181f83984e9a118d8bf98350b4e57f994219f6d6", size = 51308, upload-time = "2026-06-09T08:03:32.509Z" },
+]
+
 [[package]]
 name = "lightning"
 version = "2.5.3"
@@ -1417,6 +1683,20 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/de/73/3d757cb3fc16f0f9794dd289bcd0c4a031d9cf54d8137d6b984b2d02edf3/lightning_utilities-0.15.2-py3-none-any.whl", hash = "sha256:ad3ab1703775044bbf880dbf7ddaaac899396c96315f3aa1779cec9d618a9841", size = 29431, upload-time = "2025-08-06T13:57:38.046Z" },
 ]
 
+[[package]]
+name = "lightphe"
+version = "0.0.25"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "lightecc" },
+    { name = "sympy" },
+    { name = "tqdm" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/59/fb/73dab4b73dd02381c1806ee097c09b73163f021920f3327a5cef277b186d/lightphe-0.0.25.tar.gz", hash = "sha256:f1354a1b65bfda65ab6d83873d45ea197a7950020838cafbf14019c421c6d1f9", size = 47051, upload-time = "2026-05-12T13:11:45.129Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/6f/82/bff46a0e9a7457458a5a1401d24cfd9f9a005832702a6ddc75870ae771b0/lightphe-0.0.25-py3-none-any.whl", hash = "sha256:d9a3b2a61aca3eca9371279fa61d8a931007552db9395558fb43c442576c0b73", size = 70417, upload-time = "2026-05-12T13:11:43.697Z" },
+]
+
 [[package]]
 name = "llvmlite"
 version = "0.44.0"
@@ -1430,6 +1710,22 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/e2/3b/a9a17366af80127bd09decbe2a54d8974b6d8b274b39bf47fbaedeec6307/llvmlite-0.44.0-cp312-cp312-win_amd64.whl", hash = "sha256:eae7e2d4ca8f88f89d315b48c6b741dcb925d6a1042da694aa16ab3dd4cbd3a1", size = 30332380, upload-time = "2025-01-20T11:14:02.442Z" },
 ]
 
+[[package]]
+name = "lz4"
+version = "4.4.5"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/57/51/f1b86d93029f418033dddf9b9f79c8d2641e7454080478ee2aab5123173e/lz4-4.4.5.tar.gz", hash = "sha256:5f0b9e53c1e82e88c10d7c180069363980136b9d7a8306c4dca4f760d60c39f0", size = 172886, upload-time = "2025-11-03T13:02:36.061Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1b/ac/016e4f6de37d806f7cc8f13add0a46c9a7cfc41a5ddc2bc831d7954cf1ce/lz4-4.4.5-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:df5aa4cead2044bab83e0ebae56e0944cc7fcc1505c7787e9e1057d6d549897e", size = 207163, upload-time = "2025-11-03T13:01:45.895Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/df/0fadac6e5bd31b6f34a1a8dbd4db6a7606e70715387c27368586455b7fc9/lz4-4.4.5-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:6d0bf51e7745484d2092b3a51ae6eb58c3bd3ce0300cf2b2c14f76c536d5697a", size = 207150, upload-time = "2025-11-03T13:01:47.205Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/17/34e36cc49bb16ca73fb57fbd4c5eaa61760c6b64bce91fcb4e0f4a97f852/lz4-4.4.5-cp312-cp312-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:7b62f94b523c251cf32aa4ab555f14d39bd1a9df385b72443fd76d7c7fb051f5", size = 1292045, upload-time = "2025-11-03T13:01:48.667Z" },
+    { url = "https://files.pythonhosted.org/packages/90/1c/b1d8e3741e9fc89ed3b5f7ef5f22586c07ed6bb04e8343c2e98f0fa7ff04/lz4-4.4.5-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:2c3ea562c3af274264444819ae9b14dbbf1ab070aff214a05e97db6896c7597e", size = 1279546, upload-time = "2025-11-03T13:01:50.159Z" },
+    { url = "https://files.pythonhosted.org/packages/55/d9/e3867222474f6c1b76e89f3bd914595af69f55bf2c1866e984c548afdc15/lz4-4.4.5-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:24092635f47538b392c4eaeff14c7270d2c8e806bf4be2a6446a378591c5e69e", size = 1368249, upload-time = "2025-11-03T13:01:51.273Z" },
+    { url = "https://files.pythonhosted.org/packages/b2/e7/d667d337367686311c38b580d1ca3d5a23a6617e129f26becd4f5dc458df/lz4-4.4.5-cp312-cp312-win32.whl", hash = "sha256:214e37cfe270948ea7eb777229e211c601a3e0875541c1035ab408fbceaddf50", size = 88189, upload-time = "2025-11-03T13:01:52.605Z" },
+    { url = "https://files.pythonhosted.org/packages/a5/0b/a54cd7406995ab097fceb907c7eb13a6ddd49e0b231e448f1a81a50af65c/lz4-4.4.5-cp312-cp312-win_amd64.whl", hash = "sha256:713a777de88a73425cf08eb11f742cd2c98628e79a8673d6a52e3c5f0c116f33", size = 99497, upload-time = "2025-11-03T13:01:53.477Z" },
+    { url = "https://files.pythonhosted.org/packages/6a/7e/dc28a952e4bfa32ca16fa2eb026e7a6ce5d1411fcd5986cd08c74ec187b9/lz4-4.4.5-cp312-cp312-win_arm64.whl", hash = "sha256:a88cbb729cc333334ccfb52f070463c21560fca63afcf636a9f160a55fac3301", size = 91279, upload-time = "2025-11-03T13:01:54.419Z" },
+]
+
 [[package]]
 name = "mako"
 version = "1.3.10"
@@ -1528,6 +1824,22 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/01/4d/23c4e4f09da849e127e9f123241946c23c1e30f45a88366879e064211815/mistune-3.1.3-py3-none-any.whl", hash = "sha256:1a32314113cff28aa6432e99e522677c8587fd83e3d51c29b82a52409c842bd9", size = 53410, upload-time = "2025-03-19T14:27:23.451Z" },
 ]
 
+[[package]]
+name = "ml-dtypes"
+version = "0.5.4"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "numpy" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/0e/4a/c27b42ed9b1c7d13d9ba8b6905dece787d6259152f2309338aed29b2447b/ml_dtypes-0.5.4.tar.gz", hash = "sha256:8ab06a50fb9bf9666dd0fe5dfb4676fa2b0ac0f31ecff72a6c3af8e22c063453", size = 692314, upload-time = "2025-11-17T22:32:31.031Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a8/b8/3c70881695e056f8a32f8b941126cf78775d9a4d7feba8abcb52cb7b04f2/ml_dtypes-0.5.4-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:a174837a64f5b16cab6f368171a1a03a27936b31699d167684073ff1c4237dac", size = 676927, upload-time = "2025-11-17T22:31:48.182Z" },
+    { url = "https://files.pythonhosted.org/packages/54/0f/428ef6881782e5ebb7eca459689448c0394fa0a80bea3aa9262cba5445ea/ml_dtypes-0.5.4-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a7f7c643e8b1320fd958bf098aa7ecf70623a42ec5154e3be3be673f4c34d900", size = 5028464, upload-time = "2025-11-17T22:31:50.135Z" },
+    { url = "https://files.pythonhosted.org/packages/3a/cb/28ce52eb94390dda42599c98ea0204d74799e4d8047a0eb559b6fd648056/ml_dtypes-0.5.4-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9ad459e99793fa6e13bd5b7e6792c8f9190b4e5a1b45c63aba14a4d0a7f1d5ff", size = 5009002, upload-time = "2025-11-17T22:31:52.001Z" },
+    { url = "https://files.pythonhosted.org/packages/f5/f0/0cfadd537c5470378b1b32bd859cf2824972174b51b873c9d95cfd7475a5/ml_dtypes-0.5.4-cp312-cp312-win_amd64.whl", hash = "sha256:c1a953995cccb9e25a4ae19e34316671e4e2edaebe4cf538229b1fc7109087b7", size = 212222, upload-time = "2025-11-17T22:31:53.742Z" },
+    { url = "https://files.pythonhosted.org/packages/16/2e/9acc86985bfad8f2c2d30291b27cd2bb4c74cea08695bd540906ed744249/ml_dtypes-0.5.4-cp312-cp312-win_arm64.whl", hash = "sha256:9bad06436568442575beb2d03389aa7456c690a5b05892c471215bfd8cf39460", size = 160793, upload-time = "2025-11-17T22:31:55.358Z" },
+]
+
 [[package]]
 name = "more-itertools"
 version = "10.7.0"
@@ -1582,6 +1894,19 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/c0/23/0abb886e80eab08f5e8c485d6f13924028602829f63b8f5fa25a06636628/msgpack-1.1.1-cp312-cp312-win_amd64.whl", hash = "sha256:5692095123007180dca3e788bb4c399cc26626da51629a31d40207cb262e67f4", size = 72558, upload-time = "2025-06-13T06:52:15.252Z" },
 ]
 
+[[package]]
+name = "mtcnn"
+version = "1.0.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "joblib" },
+    { name = "lz4" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/67/37/b0f60411b6a37dcd5122bbe05c9aa45f271bcc8129caa45ee1012251905d/mtcnn-1.0.0.tar.gz", hash = "sha256:08428bf8e1ae9827d43a40bb0246b57f2239e3572d3742f472ae9924896c6419", size = 1885746, upload-time = "2024-10-08T01:42:22.685Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/dc/7e/0b2b688a9e2d353a661b617b12d00d9af29f877b57c8e4a3cbe447483b46/mtcnn-1.0.0-py3-none-any.whl", hash = "sha256:0a96b4868e56db9ae984449519642be6dba03240e608a67e928ebb47833e9144", size = 1898606, upload-time = "2024-10-08T01:42:18.271Z" },
+]
+
 [[package]]
 name = "multidict"
 version = "6.6.4"
@@ -1654,6 +1979,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/79/7b/2c79738432f5c924bef5071f933bcc9efd0473bac3b4aa584a6f7c1c8df8/mypy_extensions-1.1.0-py3-none-any.whl", hash = "sha256:1be4cccdb0f2482337c4743e60421de3a356cd97508abadd57d47403e94f5505", size = 4963, upload-time = "2025-04-22T14:54:22.983Z" },
 ]
 
+[[package]]
+name = "namex"
+version = "0.1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/0c/c0/ee95b28f029c73f8d49d8f52edaed02a1d4a9acb8b69355737fdb1faa191/namex-0.1.0.tar.gz", hash = "sha256:117f03ccd302cc48e3f5c58a296838f6b89c83455ab8683a1e85f2a430aa4306", size = 6649, upload-time = "2025-05-26T23:17:38.918Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b2/bc/465daf1de06409cdd4532082806770ee0d8d7df434da79c76564d0f69741/namex-0.1.0-py3-none-any.whl", hash = "sha256:e2012a474502f1e2251267062aae3114611f07df4224b6e06334c57b0f2ce87c", size = 5905, upload-time = "2025-05-26T23:17:37.695Z" },
+]
+
 [[package]]
 name = "narwhals"
 version = "2.1.2"
@@ -1792,18 +2126,20 @@ wheels = [
 
 [[package]]
 name = "numpy"
-version = "1.26.4"
+version = "2.2.6"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/65/6e/09db70a523a96d25e115e71cc56a6f9031e7b8cd166c1ac8438307c14058/numpy-1.26.4.tar.gz", hash = "sha256:2a02aba9ed12e4ac4eb3ea9421c420301a0c6460d9830d74a9df87efa4912010", size = 15786129, upload-time = "2024-02-06T00:26:44.495Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/76/21/7d2a95e4bba9dc13d043ee156a356c0a8f0c6309dff6b21b4d71a073b8a8/numpy-2.2.6.tar.gz", hash = "sha256:e29554e2bef54a90aa5cc07da6ce955accb83f21ab5de01a62c8478897b264fd", size = 20276440, upload-time = "2025-05-17T22:38:04.611Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/95/12/8f2020a8e8b8383ac0177dc9570aad031a3beb12e38847f7129bacd96228/numpy-1.26.4-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:b3ce300f3644fb06443ee2222c2201dd3a89ea6040541412b8fa189341847218", size = 20335901, upload-time = "2024-02-05T23:55:32.801Z" },
-    { url = "https://files.pythonhosted.org/packages/75/5b/ca6c8bd14007e5ca171c7c03102d17b4f4e0ceb53957e8c44343a9546dcc/numpy-1.26.4-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:03a8c78d01d9781b28a6989f6fa1bb2c4f2d51201cf99d3dd875df6fbd96b23b", size = 13685868, upload-time = "2024-02-05T23:55:56.28Z" },
-    { url = "https://files.pythonhosted.org/packages/79/f8/97f10e6755e2a7d027ca783f63044d5b1bc1ae7acb12afe6a9b4286eac17/numpy-1.26.4-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:9fad7dcb1aac3c7f0584a5a8133e3a43eeb2fe127f47e3632d43d677c66c102b", size = 13925109, upload-time = "2024-02-05T23:56:20.368Z" },
-    { url = "https://files.pythonhosted.org/packages/0f/50/de23fde84e45f5c4fda2488c759b69990fd4512387a8632860f3ac9cd225/numpy-1.26.4-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:675d61ffbfa78604709862923189bad94014bef562cc35cf61d3a07bba02a7ed", size = 17950613, upload-time = "2024-02-05T23:56:56.054Z" },
-    { url = "https://files.pythonhosted.org/packages/4c/0c/9c603826b6465e82591e05ca230dfc13376da512b25ccd0894709b054ed0/numpy-1.26.4-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:ab47dbe5cc8210f55aa58e4805fe224dac469cde56b9f731a4c098b91917159a", size = 13572172, upload-time = "2024-02-05T23:57:21.56Z" },
-    { url = "https://files.pythonhosted.org/packages/76/8c/2ba3902e1a0fc1c74962ea9bb33a534bb05984ad7ff9515bf8d07527cadd/numpy-1.26.4-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:1dda2e7b4ec9dd512f84935c5f126c8bd8b9f2fc001e9f54af255e8c5f16b0e0", size = 17786643, upload-time = "2024-02-05T23:57:56.585Z" },
-    { url = "https://files.pythonhosted.org/packages/28/4a/46d9e65106879492374999e76eb85f87b15328e06bd1550668f79f7b18c6/numpy-1.26.4-cp312-cp312-win32.whl", hash = "sha256:50193e430acfc1346175fcbdaa28ffec49947a06918b7b92130744e81e640110", size = 5677803, upload-time = "2024-02-05T23:58:08.963Z" },
-    { url = "https://files.pythonhosted.org/packages/16/2e/86f24451c2d530c88daf997cb8d6ac622c1d40d19f5a031ed68a4b73a374/numpy-1.26.4-cp312-cp312-win_amd64.whl", hash = "sha256:08beddf13648eb95f8d867350f6a018a4be2e5ad54c8d8caed89ebca558b2818", size = 15517754, upload-time = "2024-02-05T23:58:36.364Z" },
+    { url = "https://files.pythonhosted.org/packages/82/5d/c00588b6cf18e1da539b45d3598d3557084990dcc4331960c15ee776ee41/numpy-2.2.6-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:41c5a21f4a04fa86436124d388f6ed60a9343a6f767fced1a8a71c3fbca038ff", size = 20875348, upload-time = "2025-05-17T21:34:39.648Z" },
+    { url = "https://files.pythonhosted.org/packages/66/ee/560deadcdde6c2f90200450d5938f63a34b37e27ebff162810f716f6a230/numpy-2.2.6-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:de749064336d37e340f640b05f24e9e3dd678c57318c7289d222a8a2f543e90c", size = 14119362, upload-time = "2025-05-17T21:35:01.241Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/65/4baa99f1c53b30adf0acd9a5519078871ddde8d2339dc5a7fde80d9d87da/numpy-2.2.6-cp312-cp312-macosx_14_0_arm64.whl", hash = "sha256:894b3a42502226a1cac872f840030665f33326fc3dac8e57c607905773cdcde3", size = 5084103, upload-time = "2025-05-17T21:35:10.622Z" },
+    { url = "https://files.pythonhosted.org/packages/cc/89/e5a34c071a0570cc40c9a54eb472d113eea6d002e9ae12bb3a8407fb912e/numpy-2.2.6-cp312-cp312-macosx_14_0_x86_64.whl", hash = "sha256:71594f7c51a18e728451bb50cc60a3ce4e6538822731b2933209a1f3614e9282", size = 6625382, upload-time = "2025-05-17T21:35:21.414Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/35/8c80729f1ff76b3921d5c9487c7ac3de9b2a103b1cd05e905b3090513510/numpy-2.2.6-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:f2618db89be1b4e05f7a1a847a9c1c0abd63e63a1607d892dd54668dd92faf87", size = 14018462, upload-time = "2025-05-17T21:35:42.174Z" },
+    { url = "https://files.pythonhosted.org/packages/8c/3d/1e1db36cfd41f895d266b103df00ca5b3cbe965184df824dec5c08c6b803/numpy-2.2.6-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:fd83c01228a688733f1ded5201c678f0c53ecc1006ffbc404db9f7a899ac6249", size = 16527618, upload-time = "2025-05-17T21:36:06.711Z" },
+    { url = "https://files.pythonhosted.org/packages/61/c6/03ed30992602c85aa3cd95b9070a514f8b3c33e31124694438d88809ae36/numpy-2.2.6-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:37c0ca431f82cd5fa716eca9506aefcabc247fb27ba69c5062a6d3ade8cf8f49", size = 15505511, upload-time = "2025-05-17T21:36:29.965Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/25/5761d832a81df431e260719ec45de696414266613c9ee268394dd5ad8236/numpy-2.2.6-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:fe27749d33bb772c80dcd84ae7e8df2adc920ae8297400dabec45f0dedb3f6de", size = 18313783, upload-time = "2025-05-17T21:36:56.883Z" },
+    { url = "https://files.pythonhosted.org/packages/57/0a/72d5a3527c5ebffcd47bde9162c39fae1f90138c961e5296491ce778e682/numpy-2.2.6-cp312-cp312-win32.whl", hash = "sha256:4eeaae00d789f66c7a25ac5f34b71a7035bb474e679f410e5e1a94deb24cf2d4", size = 6246506, upload-time = "2025-05-17T21:37:07.368Z" },
+    { url = "https://files.pythonhosted.org/packages/36/fa/8c9210162ca1b88529ab76b41ba02d433fd54fecaf6feb70ef9f124683f1/numpy-2.2.6-cp312-cp312-win_amd64.whl", hash = "sha256:c1f9540be57940698ed329904db803cf7a402f3fc200bfe599334c9bd84a40b2", size = 12614190, upload-time = "2025-05-17T21:37:26.213Z" },
 ]
 
 [[package]]
@@ -1843,7 +2179,7 @@ name = "nvidia-cudnn-cu12"
 version = "9.1.0.70"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "nvidia-cublas-cu12", marker = "platform_machine != 'aarch64' and sys_platform == 'linux'" },
+    { name = "nvidia-cublas-cu12" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/9f/fd/713452cd72343f682b1c7b9321e23829f00b842ceaedcda96e742ea0b0b3/nvidia_cudnn_cu12-9.1.0.70-py3-none-manylinux2014_x86_64.whl", hash = "sha256:165764f44ef8c61fcdfdfdbe769d687e06374059fbb388b6c89ecb0e28793a6f", size = 664752741, upload-time = "2024-04-22T15:24:15.253Z" },
@@ -1854,7 +2190,7 @@ name = "nvidia-cufft-cu12"
 version = "11.2.1.3"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "nvidia-nvjitlink-cu12", marker = "platform_machine != 'aarch64' and sys_platform == 'linux'" },
+    { name = "nvidia-nvjitlink-cu12" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/27/94/3266821f65b92b3138631e9c8e7fe1fb513804ac934485a8d05776e1dd43/nvidia_cufft_cu12-11.2.1.3-py3-none-manylinux2014_x86_64.whl", hash = "sha256:f083fc24912aa410be21fa16d157fed2055dab1cc4b6934a0e03cba69eb242b9", size = 211459117, upload-time = "2024-04-03T20:57:40.402Z" },
@@ -1873,9 +2209,9 @@ name = "nvidia-cusolver-cu12"
 version = "11.6.1.9"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "nvidia-cublas-cu12", marker = "platform_machine != 'aarch64' and sys_platform == 'linux'" },
-    { name = "nvidia-cusparse-cu12", marker = "platform_machine != 'aarch64' and sys_platform == 'linux'" },
-    { name = "nvidia-nvjitlink-cu12", marker = "platform_machine != 'aarch64' and sys_platform == 'linux'" },
+    { name = "nvidia-cublas-cu12" },
+    { name = "nvidia-cusparse-cu12" },
+    { name = "nvidia-nvjitlink-cu12" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/3a/e1/5b9089a4b2a4790dfdea8b3a006052cfecff58139d5a4e34cb1a51df8d6f/nvidia_cusolver_cu12-11.6.1.9-py3-none-manylinux2014_x86_64.whl", hash = "sha256:19e33fa442bcfd085b3086c4ebf7e8debc07cfe01e11513cc6d332fd918ac260", size = 127936057, upload-time = "2024-04-03T20:58:28.735Z" },
@@ -1886,7 +2222,7 @@ name = "nvidia-cusparse-cu12"
 version = "12.3.1.170"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "nvidia-nvjitlink-cu12", marker = "platform_machine != 'aarch64' and sys_platform == 'linux'" },
+    { name = "nvidia-nvjitlink-cu12" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/db/f7/97a9ea26ed4bbbfc2d470994b8b4f338ef663be97b8f677519ac195e113d/nvidia_cusparse_cu12-12.3.1.170-py3-none-manylinux2014_x86_64.whl", hash = "sha256:ea4f11a2904e2a8dc4b1833cc1b5181cde564edd0d5cd33e3c168eff2d1863f1", size = 207454763, upload-time = "2024-04-03T20:58:59.995Z" },
@@ -2010,23 +2346,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/a4/7d/f1c30a92854540bf789e9cd5dde7ef49bbe63f855b85a2e6b3db8135c591/opencv_python-4.11.0.86-cp37-abi3-win_amd64.whl", hash = "sha256:085ad9b77c18853ea66283e98affefe2de8cc4c1f43eda4c100cf9b2721142ec", size = 39488044, upload-time = "2025-01-16T13:52:21.928Z" },
 ]
 
-[[package]]
-name = "opencv-python-headless"
-version = "4.11.0.86"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "numpy" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/36/2f/5b2b3ba52c864848885ba988f24b7f105052f68da9ab0e693cc7c25b0b30/opencv-python-headless-4.11.0.86.tar.gz", hash = "sha256:996eb282ca4b43ec6a3972414de0e2331f5d9cda2b41091a49739c19fb843798", size = 95177929, upload-time = "2025-01-16T13:53:40.22Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/dc/53/2c50afa0b1e05ecdb4603818e85f7d174e683d874ef63a6abe3ac92220c8/opencv_python_headless-4.11.0.86-cp37-abi3-macosx_13_0_arm64.whl", hash = "sha256:48128188ade4a7e517237c8e1e11a9cdf5c282761473383e77beb875bb1e61ca", size = 37326460, upload-time = "2025-01-16T13:52:57.015Z" },
-    { url = "https://files.pythonhosted.org/packages/3b/43/68555327df94bb9b59a1fd645f63fafb0762515344d2046698762fc19d58/opencv_python_headless-4.11.0.86-cp37-abi3-macosx_13_0_x86_64.whl", hash = "sha256:a66c1b286a9de872c343ee7c3553b084244299714ebb50fbdcd76f07ebbe6c81", size = 56723330, upload-time = "2025-01-16T13:55:45.731Z" },
-    { url = "https://files.pythonhosted.org/packages/45/be/1438ce43ebe65317344a87e4b150865c5585f4c0db880a34cdae5ac46881/opencv_python_headless-4.11.0.86-cp37-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:6efabcaa9df731f29e5ea9051776715b1bdd1845d7c9530065c7951d2a2899eb", size = 29487060, upload-time = "2025-01-16T13:51:59.625Z" },
-    { url = "https://files.pythonhosted.org/packages/dd/5c/c139a7876099916879609372bfa513b7f1257f7f1a908b0bdc1c2328241b/opencv_python_headless-4.11.0.86-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0e0a27c19dd1f40ddff94976cfe43066fbbe9dfbb2ec1907d66c19caef42a57b", size = 49969856, upload-time = "2025-01-16T13:53:29.654Z" },
-    { url = "https://files.pythonhosted.org/packages/95/dd/ed1191c9dc91abcc9f752b499b7928aacabf10567bb2c2535944d848af18/opencv_python_headless-4.11.0.86-cp37-abi3-win32.whl", hash = "sha256:f447d8acbb0b6f2808da71fddd29c1cdd448d2bc98f72d9bb78a7a898fc9621b", size = 29324425, upload-time = "2025-01-16T13:52:49.048Z" },
-    { url = "https://files.pythonhosted.org/packages/86/8a/69176a64335aed183529207ba8bc3d329c2999d852b4f3818027203f50e6/opencv_python_headless-4.11.0.86-cp37-abi3-win_amd64.whl", hash = "sha256:6c304df9caa7a6a5710b91709dd4786bf20a74d57672b3c31f7033cc638174ca", size = 39402386, upload-time = "2025-01-16T13:52:56.418Z" },
-]
-
 [[package]]
 name = "openface-test"
 version = "0.1.13"
@@ -2048,6 +2367,37 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/c0/da/977ded879c29cbd04de313843e76868e6e13408a94ed6b987245dc7c8506/openpyxl-3.1.5-py2.py3-none-any.whl", hash = "sha256:5282c12b107bffeef825f4617dc029afaf41d0ea60823bbb665ef3079dc79de2", size = 250910, upload-time = "2024-06-28T14:03:41.161Z" },
 ]
 
+[[package]]
+name = "opt-einsum"
+version = "3.4.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/8c/b9/2ac072041e899a52f20cf9510850ff58295003aa75525e58343591b0cbfb/opt_einsum-3.4.0.tar.gz", hash = "sha256:96ca72f1b886d148241348783498194c577fa30a8faac108586b14f1ba4473ac", size = 63004, upload-time = "2024-09-26T14:33:24.483Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/23/cd/066e86230ae37ed0be70aae89aabf03ca8d9f39c8aea0dec8029455b5540/opt_einsum-3.4.0-py3-none-any.whl", hash = "sha256:69bb92469f86a1565195ece4ac0323943e83477171b91d24c35afe028a90d7cd", size = 71932, upload-time = "2024-09-26T14:33:23.039Z" },
+]
+
+[[package]]
+name = "optree"
+version = "0.19.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/44/63/92328a17ab7836562fe0129e605f685a88db35ce98427c34ff48ee4ec157/optree-0.19.1.tar.gz", hash = "sha256:4497d1c9197b8c6842e511368163d318ce536521ebdcff8bebb7551dcdfac532", size = 177531, upload-time = "2026-05-06T02:32:39.704Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ba/a7/cb5567029a608a296b0ca224025d03bba0365b41df19085b9b580191f6f2/optree-0.19.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:96e5c7c3b9144f08ae40c3d9848cfbcfa36b6bead0f8215ad071d5922ee6c4a5", size = 424023, upload-time = "2026-05-06T02:30:57.732Z" },
+    { url = "https://files.pythonhosted.org/packages/b9/a1/3651fb32fa8617108204aa4056d283af742020e0987d106f41402005d800/optree-0.19.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:5d9d198343e1e6ced18bef0cbff84091c1877964fc4a121df33f18840e073a01", size = 394782, upload-time = "2026-05-06T02:30:59.239Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/1e/676470909aa64d7aba7c5edf83b171dc83b7af901d9ebb8e6d7512fe913a/optree-0.19.1-cp312-cp312-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7a1202371d9fe3aa75f3e886b1f871aac4991a655aadb65e54f58a3ae9388ab2", size = 413157, upload-time = "2026-05-06T02:31:00.339Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/41/1a4c58f2af5742b9d9e21ea9e45c6c3c49463b5e2a0537e84ead1e9597ca/optree-0.19.1-cp312-cp312-manylinux_2_26_i686.manylinux_2_28_i686.whl", hash = "sha256:d41ccc4c20bfeae01d1d221c057a6d026e84e32229664952eddcdbe4b9b71417", size = 476923, upload-time = "2026-05-06T02:31:01.492Z" },
+    { url = "https://files.pythonhosted.org/packages/10/c1/f62167bd9d6f6c948b191a0943923404678d47100f777f4a8fb37816e6f8/optree-0.19.1-cp312-cp312-manylinux_2_26_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:7d934f240b109c6891dd06b2e30400b123b8a4b6ed31dcd0db2ae2378d30a6e8", size = 475385, upload-time = "2026-05-06T02:31:02.836Z" },
+    { url = "https://files.pythonhosted.org/packages/30/5e/5323c5fa3024fdd900bdd8f14621139ed844c2247bf1a26e7cf5c1116188/optree-0.19.1-cp312-cp312-manylinux_2_26_s390x.manylinux_2_28_s390x.whl", hash = "sha256:ddeefb7ca799c09647e332ebc1a5f6c09888a5a0e51f2dff4ca55e65b42a8c14", size = 474406, upload-time = "2026-05-06T02:31:04.023Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/6a/54e4c47e61a51504a5224c933722e0c8a69925aacec4c08175e9675aeb81/optree-0.19.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:f0ce49f64f804f7f35f2f9c2a21e3ba94c090199fccdcfd40e3ded4426c5c175", size = 457596, upload-time = "2026-05-06T02:31:05.695Z" },
+    { url = "https://files.pythonhosted.org/packages/a7/12/bba07c0b769586c6bd54e81f1f734cad103dbe30abbadee940fe7d3e330e/optree-0.19.1-cp312-cp312-manylinux_2_39_riscv64.whl", hash = "sha256:e0f02600832ab8d0f6c934dcb5c339e17a36938d477641a45798e02625ebe107", size = 417900, upload-time = "2026-05-06T02:31:07.251Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/8f/6ae994bb47f9394b33912a14593f9247737dd6c3303811550e5a3e918107/optree-0.19.1-cp312-cp312-win32.whl", hash = "sha256:f10d58c1a17e1b32f9d9b5e1b9d1ad964d99c1113d9df0b9f62f2fe7dde19909", size = 317302, upload-time = "2026-05-06T02:31:08.627Z" },
+    { url = "https://files.pythonhosted.org/packages/31/97/d7e3ec79dcdde81f785a0446acf75fea77723f5ca4b98556350d7877986f/optree-0.19.1-cp312-cp312-win_amd64.whl", hash = "sha256:06f5c8a4cf356a1a276ce5cec1be44719ed260690f79c036d04b4d427e801258", size = 341362, upload-time = "2026-05-06T02:31:09.689Z" },
+    { url = "https://files.pythonhosted.org/packages/33/97/813afb84a81fd8ae65444730907c05f0775fd6c79d3359c9e84bd3370445/optree-0.19.1-cp312-cp312-win_arm64.whl", hash = "sha256:a33bd23fc5c67ecb9ff491b75fde10cd9b53f47f8a876de842090e8c7a2437e1", size = 351838, upload-time = "2026-05-06T02:31:11.086Z" },
+]
+
 [[package]]
 name = "optuna"
 version = "4.5.0"
@@ -2128,7 +2478,7 @@ name = "pexpect"
 version = "4.9.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "ptyprocess", marker = "sys_platform != 'win32'" },
+    { name = "ptyprocess" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/42/92/cc564bf6381ff43ce1f4d06852fc19a2f11d180f23dc32d9588bee2f149d/pexpect-4.9.0.tar.gz", hash = "sha256:ee7d41123f3c9911050ea2c2dac107568dc43b2d3b0c7557a33212c398ead30f", size = 166450, upload-time = "2023-11-25T09:07:26.339Z" }
 wheels = [
@@ -2574,6 +2924,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/05/e7/df2285f3d08fee213f2d041540fa4fc9ca6c2d44cf36d3a035bf2a8d2bcc/pyparsing-3.2.3-py3-none-any.whl", hash = "sha256:a749938e02d6fd0b59b356ca504a24982314bb090c383e3cf201c95ef7e2bfcf", size = 111120, upload-time = "2025-03-25T05:01:24.908Z" },
 ]
 
+[[package]]
+name = "pysocks"
+version = "1.7.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/bd/11/293dd436aea955d45fc4e8a35b6ae7270f5b8e00b53cf6c024c83b657a11/PySocks-1.7.1.tar.gz", hash = "sha256:3f8804571ebe159c380ac6de37643bb4685970655d3bba243530d6558b799aa0", size = 284429, upload-time = "2019-09-20T02:07:35.714Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/8d/59/b4572118e098ac8e46e399a1dd0f2d85403ce8bbaad9ec79373ed6badaf9/PySocks-1.7.1-py3-none-any.whl", hash = "sha256:2725bd0a9925919b9b51739eea5f9e2bae91e83288108a9ad338b2e3a4435ee5", size = 16725, upload-time = "2019-09-20T02:06:22.938Z" },
+]
+
 [[package]]
 name = "pytest"
 version = "8.4.1"
@@ -2808,6 +3167,27 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/1e/db/4254e3eabe8020b458f1a747140d32277ec7a271daf1d235b70dc0b4e6e3/requests-2.32.5-py3-none-any.whl", hash = "sha256:2462f94637a34fd532264295e186976db0f5d453d1cdd31473c85a6a161affb6", size = 64738, upload-time = "2025-08-18T20:46:00.542Z" },
 ]
 
+[package.optional-dependencies]
+socks = [
+    { name = "pysocks" },
+]
+
+[[package]]
+name = "retina-face"
+version = "0.0.18"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "gdown" },
+    { name = "numpy" },
+    { name = "opencv-python" },
+    { name = "pillow" },
+    { name = "tensorflow" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/33/9c/a4c9df93bdfafbfcb2ea153a84902f81662e659c4c280193691c8b9b2925/retina_face-0.0.18.tar.gz", hash = "sha256:c93204fbee031dc5b0b19a5c9c1f9807497eb55c4d4b0adf8c704a02c1568dd1", size = 19054, upload-time = "2026-06-01T13:55:05.425Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/05/83/8d9d50d381afa7f4212c55cb7a37db5e1f7e406b8d3d32a5a0a2b33022f9/retina_face-0.0.18-py3-none-any.whl", hash = "sha256:737ec7d30610e1ee24d3f7910281a896de1ac5d84e870b28bd17aa6a2f48a107", size = 24997, upload-time = "2026-06-01T13:45:25.491Z" },
+]
+
 [[package]]
 name = "rfc3339-validator"
 version = "0.1.4"
@@ -2969,11 +3349,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/b1/5b/c090fe55521265eb1816c303267e985125000a4e32237e95562ed462608f/scenedetect-0.6.6-py3-none-any.whl", hash = "sha256:cbd47e4aff1d3ba6f4ee00e54ff9af26378aa2b48f501003dddf5f96e37d3eb0", size = 131581, upload-time = "2025-03-10T01:40:56.136Z" },
 ]
 
-[package.optional-dependencies]
-opencv = [
-    { name = "opencv-python" },
-]
-
 [[package]]
 name = "scikit-image"
 version = "0.25.2"
@@ -3068,26 +3443,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/40/b0/4562db6223154aa4e22f939003cb92514c79f3d4dccca3444253fd17f902/Send2Trash-1.8.3-py3-none-any.whl", hash = "sha256:0c31227e0bd08961c7665474a3d1ef7193929fedda4233843689baa056be46c9", size = 18072, upload-time = "2024-04-07T00:01:07.438Z" },
 ]
 
-[[package]]
-name = "sentence-transformers"
-version = "5.1.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "huggingface-hub" },
-    { name = "pillow" },
-    { name = "scikit-learn" },
-    { name = "scipy" },
-    { name = "torch", version = "2.6.0", source = { registry = "https://pypi.org/simple" }, marker = "sys_platform != 'linux'" },
-    { name = "torch", version = "2.6.0+cu124", source = { registry = "https://download.pytorch.org/whl/cu124" }, marker = "sys_platform == 'linux'" },
-    { name = "tqdm" },
-    { name = "transformers" },
-    { name = "typing-extensions" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/46/b8/1b99379b730bc403d8e9ddc2db56f8ac9ce743734b44a1dbeebb900490d4/sentence_transformers-5.1.0.tar.gz", hash = "sha256:70c7630697cc1c64ffca328d6e8688430ebd134b3c2df03dc07cb3a016b04739", size = 370745, upload-time = "2025-08-06T13:48:55.226Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/6d/70/2b5b76e98191ec3b8b0d1dde52d00ddcc3806799149a9ce987b0d2d31015/sentence_transformers-5.1.0-py3-none-any.whl", hash = "sha256:fc803929f6a3ce82e2b2c06e0efed7a36de535c633d5ce55efac0b710ea5643e", size = 483377, upload-time = "2025-08-06T13:48:53.627Z" },
-]
-
 [[package]]
 name = "sentencepiece"
 version = "0.2.1"
@@ -3328,6 +3683,48 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/e0/1d/b5d63f1a6b824282b57f7b581810d20b7a28ca951f2d5b59f1eb0782c12b/tensorboardx-2.6.4-py3-none-any.whl", hash = "sha256:5970cf3a1f0a6a6e8b180ccf46f3fe832b8a25a70b86e5a237048a7c0beb18e2", size = 87201, upload-time = "2025-06-10T22:37:05.44Z" },
 ]
 
+[[package]]
+name = "tensorflow"
+version = "2.21.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "absl-py" },
+    { name = "astunparse" },
+    { name = "flatbuffers" },
+    { name = "gast" },
+    { name = "google-pasta" },
+    { name = "grpcio" },
+    { name = "h5py" },
+    { name = "keras" },
+    { name = "libclang" },
+    { name = "ml-dtypes" },
+    { name = "numpy" },
+    { name = "opt-einsum" },
+    { name = "packaging" },
+    { name = "protobuf" },
+    { name = "requests" },
+    { name = "setuptools" },
+    { name = "six" },
+    { name = "termcolor" },
+    { name = "typing-extensions" },
+    { name = "wrapt" },
+]
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/39/59/27adba20bbd1088b00fc0e9232aa21493b4800af2299eb6005017a6053f4/tensorflow-2.21.0-cp312-cp312-macosx_12_0_arm64.whl", hash = "sha256:56ecd7d47429acbe1df2694d50b75bf9fc3995ac92cb367cd9af6c4780ead712", size = 223488205, upload-time = "2026-03-06T17:24:03.48Z" },
+    { url = "https://files.pythonhosted.org/packages/20/a5/f139fbbd4e81a2e556170718698acf518a71a84927fa1dc1f5935b6ab3d2/tensorflow-2.21.0-cp312-cp312-manylinux_2_27_aarch64.whl", hash = "sha256:b07d15737406533898e36c7ef7944b1be18e9028dc521b9229952c537bbc5552", size = 281946471, upload-time = "2026-03-06T17:24:11.896Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/d7/6e71b4ded8ce99cd21add95611ca14af6e9ad4f2baeabdeb79a4a6b3cb1f/tensorflow-2.21.0-cp312-cp312-manylinux_2_27_x86_64.whl", hash = "sha256:b3b95643c4e70eb925839938fb35cbe142f317ec84af6844ee61513713bb13c0", size = 572611111, upload-time = "2026-03-06T17:24:26.209Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/0d/4ee4bc074597b41c9c00dc97b4418ef1eb8736fe9186ffdb3961efdfb730/tensorflow-2.21.0-cp312-cp312-win_amd64.whl", hash = "sha256:27ba0682572b1e50a0db1ee74cfb787eafcfdb1b751bbbf401fed62fe32a92e0", size = 350945509, upload-time = "2026-03-06T17:24:41.65Z" },
+]
+
+[[package]]
+name = "termcolor"
+version = "3.3.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/46/79/cf31d7a93a8fdc6aa0fbb665be84426a8c5a557d9240b6239e9e11e35fc5/termcolor-3.3.0.tar.gz", hash = "sha256:348871ca648ec6a9a983a13ab626c0acce02f515b9e1983332b17af7979521c5", size = 14434, upload-time = "2025-12-29T12:55:21.882Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/33/d1/8bb87d21e9aeb323cc03034f5eaf2c8f69841e40e4853c2627edf8111ed3/termcolor-3.3.0-py3-none-any.whl", hash = "sha256:cf642efadaf0a8ebbbf4bc7a31cec2f9b5f21a9f726f4ccbb08192c9c26f43a5", size = 7734, upload-time = "2025-12-29T12:55:20.718Z" },
+]
+
 [[package]]
 name = "terminado"
 version = "0.18.1"
@@ -3342,6 +3739,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/6a/9e/2064975477fdc887e47ad42157e214526dcad8f317a948dee17e1659a62f/terminado-0.18.1-py3-none-any.whl", hash = "sha256:a4468e1b37bb318f8a86514f65814e1afc977cf29b3992a4500d9dd305dcceb0", size = 14154, upload-time = "2024-03-12T14:34:36.569Z" },
 ]
 
+[[package]]
+name = "tf-keras"
+version = "2.21.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "tensorflow" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/76/80/b005b59f9ccdbabc1b6cd07ca1126cbd4d902288438f0c00072f91a43c6f/tf_keras-2.21.0.tar.gz", hash = "sha256:f9af0f2546cd5532de0fae7a481f34a1ca2253737d4cd1000f6b713dc733f770", size = 1255377, upload-time = "2026-03-18T22:12:02.103Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c5/d2/5220e3b93444f1c57c092ab5eb2c30cdc762a6e412234750f2d6a85b3769/tf_keras-2.21.0-py3-none-any.whl", hash = "sha256:f858bf3d97f892304e7fbcf5eb0942ed91674e27204f940a85de8c93cf07fe62", size = 1694939, upload-time = "2026-03-18T22:12:00.662Z" },
+]
+
 [[package]]
 name = "threadpoolctl"
 version = "3.6.0"
@@ -3446,13 +3855,13 @@ resolution-markers = [
     "sys_platform != 'darwin' and sys_platform != 'linux' and sys_platform != 'win32'",
 ]
 dependencies = [
-    { name = "filelock", marker = "sys_platform != 'linux'" },
-    { name = "fsspec", marker = "sys_platform != 'linux'" },
-    { name = "jinja2", marker = "sys_platform != 'linux'" },
-    { name = "networkx", marker = "sys_platform != 'linux'" },
-    { name = "setuptools", marker = "sys_platform != 'linux'" },
-    { name = "sympy", marker = "sys_platform != 'linux'" },
-    { name = "typing-extensions", marker = "sys_platform != 'linux'" },
+    { name = "filelock" },
+    { name = "fsspec" },
+    { name = "jinja2" },
+    { name = "networkx" },
+    { name = "setuptools" },
+    { name = "sympy" },
+    { name = "typing-extensions" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/18/cf/ae99bd066571656185be0d88ee70abc58467b76f2f7c8bfeb48735a71fe6/torch-2.6.0-cp312-cp312-win_amd64.whl", hash = "sha256:7e1448426d0ba3620408218b50aa6ada88aeae34f7a239ba5431f6c8774b1239", size = 204120469, upload-time = "2025-01-29T16:24:01.821Z" },
@@ -3468,27 +3877,27 @@ resolution-markers = [
     "platform_machine != 'aarch64' and sys_platform == 'linux'",
 ]
 dependencies = [
-    { name = "filelock", marker = "sys_platform == 'linux'" },
-    { name = "fsspec", marker = "sys_platform == 'linux'" },
-    { name = "jinja2", marker = "sys_platform == 'linux'" },
-    { name = "networkx", marker = "sys_platform == 'linux'" },
-    { name = "nvidia-cublas-cu12", marker = "platform_machine == 'x86_64' and sys_platform == 'linux'" },
-    { name = "nvidia-cuda-cupti-cu12", marker = "platform_machine == 'x86_64' and sys_platform == 'linux'" },
-    { name = "nvidia-cuda-nvrtc-cu12", marker = "platform_machine == 'x86_64' and sys_platform == 'linux'" },
-    { name = "nvidia-cuda-runtime-cu12", marker = "platform_machine == 'x86_64' and sys_platform == 'linux'" },
-    { name = "nvidia-cudnn-cu12", marker = "platform_machine == 'x86_64' and sys_platform == 'linux'" },
-    { name = "nvidia-cufft-cu12", marker = "platform_machine == 'x86_64' and sys_platform == 'linux'" },
-    { name = "nvidia-curand-cu12", marker = "platform_machine == 'x86_64' and sys_platform == 'linux'" },
-    { name = "nvidia-cusolver-cu12", marker = "platform_machine == 'x86_64' and sys_platform == 'linux'" },
-    { name = "nvidia-cusparse-cu12", marker = "platform_machine == 'x86_64' and sys_platform == 'linux'" },
-    { name = "nvidia-cusparselt-cu12", marker = "platform_machine == 'x86_64' and sys_platform == 'linux'" },
-    { name = "nvidia-nccl-cu12", marker = "platform_machine == 'x86_64' and sys_platform == 'linux'" },
-    { name = "nvidia-nvjitlink-cu12", marker = "platform_machine == 'x86_64' and sys_platform == 'linux'" },
-    { name = "nvidia-nvtx-cu12", marker = "platform_machine == 'x86_64' and sys_platform == 'linux'" },
-    { name = "setuptools", marker = "sys_platform == 'linux'" },
-    { name = "sympy", marker = "sys_platform == 'linux'" },
-    { name = "triton", marker = "platform_machine == 'x86_64' and sys_platform == 'linux'" },
-    { name = "typing-extensions", marker = "sys_platform == 'linux'" },
+    { name = "filelock" },
+    { name = "fsspec" },
+    { name = "jinja2" },
+    { name = "networkx" },
+    { name = "nvidia-cublas-cu12", marker = "platform_machine == 'x86_64'" },
+    { name = "nvidia-cuda-cupti-cu12", marker = "platform_machine == 'x86_64'" },
+    { name = "nvidia-cuda-nvrtc-cu12", marker = "platform_machine == 'x86_64'" },
+    { name = "nvidia-cuda-runtime-cu12", marker = "platform_machine == 'x86_64'" },
+    { name = "nvidia-cudnn-cu12", marker = "platform_machine == 'x86_64'" },
+    { name = "nvidia-cufft-cu12", marker = "platform_machine == 'x86_64'" },
+    { name = "nvidia-curand-cu12", marker = "platform_machine == 'x86_64'" },
+    { name = "nvidia-cusolver-cu12", marker = "platform_machine == 'x86_64'" },
+    { name = "nvidia-cusparse-cu12", marker = "platform_machine == 'x86_64'" },
+    { name = "nvidia-cusparselt-cu12", marker = "platform_machine == 'x86_64'" },
+    { name = "nvidia-nccl-cu12", marker = "platform_machine == 'x86_64'" },
+    { name = "nvidia-nvjitlink-cu12", marker = "platform_machine == 'x86_64'" },
+    { name = "nvidia-nvtx-cu12", marker = "platform_machine == 'x86_64'" },
+    { name = "setuptools" },
+    { name = "sympy" },
+    { name = "triton", marker = "platform_machine == 'x86_64'" },
+    { name = "typing-extensions" },
 ]
 wheels = [
     { url = "https://download-r2.pytorch.org/whl/cu124/torch-2.6.0%2Bcu124-cp312-cp312-linux_x86_64.whl", hash = "sha256:a393b506844035c0dac2f30ea8478c343b8e95a429f06f3b3cadfc7f53adb597", upload-time = "2025-01-30T00:57:08Z" },
@@ -3538,7 +3947,7 @@ resolution-markers = [
     "sys_platform != 'darwin' and sys_platform != 'linux' and sys_platform != 'win32'",
 ]
 dependencies = [
-    { name = "torch", version = "2.6.0", source = { registry = "https://pypi.org/simple" }, marker = "sys_platform != 'linux'" },
+    { name = "torch", version = "2.6.0", source = { registry = "https://pypi.org/simple" } },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/ac/4a/d71b932bda4171970bdf4997541b5c778daa0e2967ed5009d207fca86ded/torchaudio-2.6.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:7d0e4b08c42325bf4b887de9a25c44ed882997001740e1bd7d901f65581cf1ab", size = 1812899, upload-time = "2025-01-29T16:29:41.021Z" },
@@ -3554,7 +3963,7 @@ resolution-markers = [
     "platform_machine != 'aarch64' and sys_platform == 'linux'",
 ]
 dependencies = [
-    { name = "torch", version = "2.6.0+cu124", source = { registry = "https://download.pytorch.org/whl/cu124" }, marker = "sys_platform == 'linux'" },
+    { name = "torch", version = "2.6.0+cu124", source = { registry = "https://download.pytorch.org/whl/cu124" } },
 ]
 wheels = [
     { url = "https://download-r2.pytorch.org/whl/cu124/torchaudio-2.6.0%2Bcu124-cp312-cp312-linux_x86_64.whl", hash = "sha256:3e5ffa69606171c74f3e2b969785ead50b782ca657e746aaee1ee7cc88dcfc08", upload-time = "2025-01-30T01:04:24Z" },
@@ -3586,9 +3995,9 @@ resolution-markers = [
     "sys_platform != 'darwin' and sys_platform != 'linux' and sys_platform != 'win32'",
 ]
 dependencies = [
-    { name = "numpy", marker = "sys_platform != 'linux'" },
-    { name = "pillow", marker = "sys_platform != 'linux'" },
-    { name = "torch", version = "2.6.0", source = { registry = "https://pypi.org/simple" }, marker = "sys_platform != 'linux'" },
+    { name = "numpy" },
+    { name = "pillow" },
+    { name = "torch", version = "2.6.0", source = { registry = "https://pypi.org/simple" } },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/6e/1b/28f527b22d5e8800184d0bc847f801ae92c7573a8c15979d92b7091c0751/torchvision-0.21.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:97a5814a93c793aaf0179cfc7f916024f4b63218929aee977b645633d074a49f", size = 1784140, upload-time = "2025-01-29T16:28:44.694Z" },
@@ -3604,9 +4013,9 @@ resolution-markers = [
     "platform_machine != 'aarch64' and sys_platform == 'linux'",
 ]
 dependencies = [
-    { name = "numpy", marker = "sys_platform == 'linux'" },
-    { name = "pillow", marker = "sys_platform == 'linux'" },
-    { name = "torch", version = "2.6.0+cu124", source = { registry = "https://download.pytorch.org/whl/cu124" }, marker = "sys_platform == 'linux'" },
+    { name = "numpy" },
+    { name = "pillow" },
+    { name = "torch", version = "2.6.0+cu124", source = { registry = "https://download.pytorch.org/whl/cu124" } },
 ]
 wheels = [
     { url = "https://download-r2.pytorch.org/whl/cu124/torchvision-0.21.0%2Bcu124-cp312-cp312-linux_x86_64.whl", hash = "sha256:efb53ea0af7bf09b7b53e2a18b9be6d245f7d46a90b51d5cf97f37e9b929a991", upload-time = "2025-01-30T01:04:29Z" },
@@ -3861,7 +4270,7 @@ wheels = [
 
 [[package]]
 name = "videoannotator"
-version = "1.4.3"
+version = "1.5.0"
 source = { editable = "." }
 dependencies = [
     { name = "accelerate" },
@@ -3871,22 +4280,15 @@ dependencies = [
     { name = "cryptography" },
     { name = "datasets" },
     { name = "fastapi" },
-    { name = "huggingface-hub" },
     { name = "imageio" },
     { name = "imageio-ffmpeg" },
-    { name = "imutils" },
     { name = "ipython" },
-    { name = "librosa" },
     { name = "matplotlib" },
     { name = "moviepy" },
     { name = "networkx" },
     { name = "numba" },
     { name = "numpy" },
-    { name = "open-clip-torch" },
     { name = "openai" },
-    { name = "openai-whisper" },
-    { name = "opencv-python-headless" },
-    { name = "openface-test" },
     { name = "openpyxl" },
     { name = "packaging" },
     { name = "pandas" },
@@ -3894,11 +4296,6 @@ dependencies = [
     { name = "plotly" },
     { name = "praatio" },
     { name = "psutil" },
-    { name = "pyannote-audio" },
-    { name = "pyannote-core" },
-    { name = "pyannote-database" },
-    { name = "pyannote-metrics" },
-    { name = "pyannote-pipeline" },
     { name = "pycocotools" },
     { name = "pydantic" },
     { name = "pyjwt" },
@@ -3908,37 +4305,69 @@ dependencies = [
     { name = "requests" },
     { name = "rich" },
     { name = "ruff" },
-    { name = "scenedetect", extra = ["opencv"] },
     { name = "scikit-image" },
     { name = "scikit-learn" },
-    { name = "scipy" },
     { name = "seaborn" },
-    { name = "sentence-transformers" },
     { name = "sqlalchemy" },
-    { name = "supervision" },
-    { name = "timm" },
-    { name = "torch", version = "2.6.0", source = { registry = "https://pypi.org/simple" }, marker = "sys_platform != 'linux'" },
-    { name = "torch", version = "2.6.0+cu124", source = { registry = "https://download.pytorch.org/whl/cu124" }, marker = "sys_platform == 'linux'" },
-    { name = "torchaudio", version = "2.6.0", source = { registry = "https://pypi.org/simple" }, marker = "sys_platform != 'linux'" },
-    { name = "torchaudio", version = "2.6.0+cu124", source = { registry = "https://download.pytorch.org/whl/cu124" }, marker = "sys_platform == 'linux'" },
-    { name = "torchvision", version = "0.21.0", source = { registry = "https://pypi.org/simple" }, marker = "sys_platform != 'linux'" },
-    { name = "torchvision", version = "0.21.0+cu124", source = { registry = "https://download.pytorch.org/whl/cu124" }, marker = "sys_platform == 'linux'" },
     { name = "tqdm" },
-    { name = "transformers" },
     { name = "typer" },
-    { name = "ultralytics" },
     { name = "uvicorn", extra = ["standard"] },
     { name = "webvtt-py" },
 ]
 
 [package.optional-dependencies]
 all = [
+    { name = "deepface" },
+    { name = "huggingface-hub" },
+    { name = "imutils" },
     { name = "jupyter" },
     { name = "jupyterlab" },
+    { name = "librosa" },
     { name = "mypy" },
+    { name = "open-clip-torch" },
+    { name = "openai-whisper" },
+    { name = "opencv-python" },
+    { name = "openface-test" },
     { name = "pre-commit" },
+    { name = "pyannote-audio" },
+    { name = "pyannote-core" },
+    { name = "pyannote-database" },
+    { name = "pyannote-metrics" },
+    { name = "pyannote-pipeline" },
     { name = "pytest-cov" },
     { name = "ruff" },
+    { name = "scenedetect" },
+    { name = "scipy" },
+    { name = "supervision" },
+    { name = "tf-keras" },
+    { name = "torch", version = "2.6.0", source = { registry = "https://pypi.org/simple" }, marker = "sys_platform != 'linux'" },
+    { name = "torch", version = "2.6.0+cu124", source = { registry = "https://download.pytorch.org/whl/cu124" }, marker = "sys_platform == 'linux'" },
+    { name = "torchaudio", version = "2.6.0", source = { registry = "https://pypi.org/simple" }, marker = "sys_platform != 'linux'" },
+    { name = "torchaudio", version = "2.6.0+cu124", source = { registry = "https://download.pytorch.org/whl/cu124" }, marker = "sys_platform == 'linux'" },
+    { name = "torchvision", version = "0.21.0", source = { registry = "https://pypi.org/simple" }, marker = "sys_platform != 'linux'" },
+    { name = "torchvision", version = "0.21.0+cu124", source = { registry = "https://download.pytorch.org/whl/cu124" }, marker = "sys_platform == 'linux'" },
+    { name = "transformers" },
+    { name = "ultralytics" },
+]
+audio = [
+    { name = "librosa" },
+    { name = "openai-whisper" },
+    { name = "pyannote-audio" },
+    { name = "pyannote-core" },
+    { name = "pyannote-database" },
+    { name = "pyannote-metrics" },
+    { name = "pyannote-pipeline" },
+    { name = "torch", version = "2.6.0", source = { registry = "https://pypi.org/simple" }, marker = "sys_platform != 'linux'" },
+    { name = "torch", version = "2.6.0+cu124", source = { registry = "https://download.pytorch.org/whl/cu124" }, marker = "sys_platform == 'linux'" },
+    { name = "torchaudio", version = "2.6.0", source = { registry = "https://pypi.org/simple" }, marker = "sys_platform != 'linux'" },
+    { name = "torchaudio", version = "2.6.0+cu124", source = { registry = "https://download.pytorch.org/whl/cu124" }, marker = "sys_platform == 'linux'" },
+]
+audio-laion = [
+    { name = "huggingface-hub" },
+    { name = "librosa" },
+    { name = "torch", version = "2.6.0", source = { registry = "https://pypi.org/simple" }, marker = "sys_platform != 'linux'" },
+    { name = "torch", version = "2.6.0+cu124", source = { registry = "https://download.pytorch.org/whl/cu124" }, marker = "sys_platform == 'linux'" },
+    { name = "transformers" },
 ]
 dev = [
     { name = "jupyter" },
@@ -3948,6 +4377,45 @@ dev = [
     { name = "pytest-cov" },
     { name = "ruff" },
 ]
+face = [
+    { name = "deepface" },
+    { name = "imutils" },
+    { name = "opencv-python" },
+    { name = "tf-keras" },
+]
+face-laion = [
+    { name = "deepface" },
+    { name = "huggingface-hub" },
+    { name = "imutils" },
+    { name = "opencv-python" },
+    { name = "tf-keras" },
+    { name = "torch", version = "2.6.0", source = { registry = "https://pypi.org/simple" }, marker = "sys_platform != 'linux'" },
+    { name = "torch", version = "2.6.0+cu124", source = { registry = "https://download.pytorch.org/whl/cu124" }, marker = "sys_platform == 'linux'" },
+    { name = "torchvision", version = "0.21.0", source = { registry = "https://pypi.org/simple" }, marker = "sys_platform != 'linux'" },
+    { name = "torchvision", version = "0.21.0+cu124", source = { registry = "https://download.pytorch.org/whl/cu124" }, marker = "sys_platform == 'linux'" },
+    { name = "transformers" },
+]
+face-openface3 = [
+    { name = "opencv-python" },
+    { name = "openface-test" },
+    { name = "scipy" },
+]
+person = [
+    { name = "opencv-python" },
+    { name = "supervision" },
+    { name = "torch", version = "2.6.0", source = { registry = "https://pypi.org/simple" }, marker = "sys_platform != 'linux'" },
+    { name = "torch", version = "2.6.0+cu124", source = { registry = "https://download.pytorch.org/whl/cu124" }, marker = "sys_platform == 'linux'" },
+    { name = "torchvision", version = "0.21.0", source = { registry = "https://pypi.org/simple" }, marker = "sys_platform != 'linux'" },
+    { name = "torchvision", version = "0.21.0+cu124", source = { registry = "https://download.pytorch.org/whl/cu124" }, marker = "sys_platform == 'linux'" },
+    { name = "ultralytics" },
+]
+scene = [
+    { name = "open-clip-torch" },
+    { name = "opencv-python" },
+    { name = "scenedetect" },
+    { name = "torch", version = "2.6.0", source = { registry = "https://pypi.org/simple" }, marker = "sys_platform != 'linux'" },
+    { name = "torch", version = "2.6.0+cu124", source = { registry = "https://download.pytorch.org/whl/cu124" }, marker = "sys_platform == 'linux'" },
+]
 
 [package.dev-dependencies]
 dev = [
@@ -3973,26 +4441,32 @@ requires-dist = [
     { name = "click", specifier = ">=8.0.0" },
     { name = "cryptography", specifier = ">=45.0.6" },
     { name = "datasets", specifier = ">=2.16.0" },
+    { name = "deepface", marker = "extra == 'face'", specifier = ">=0.0.91" },
     { name = "fastapi", specifier = ">=0.115.0" },
-    { name = "huggingface-hub", specifier = ">=0.20.0" },
+    { name = "huggingface-hub", marker = "extra == 'audio-laion'", specifier = ">=0.20.0" },
+    { name = "huggingface-hub", marker = "extra == 'face-laion'", specifier = ">=0.20.0" },
     { name = "imageio", specifier = ">=2.31.0" },
     { name = "imageio-ffmpeg", specifier = ">=0.4.8" },
-    { name = "imutils", specifier = ">=0.5.4" },
+    { name = "imutils", marker = "extra == 'face'", specifier = ">=0.5.4" },
     { name = "ipython", specifier = ">=8.12.3" },
     { name = "jupyter", marker = "extra == 'dev'", specifier = ">=1.0.0" },
     { name = "jupyterlab", marker = "extra == 'dev'", specifier = ">=4.0.0" },
-    { name = "librosa", specifier = ">=0.10.0" },
+    { name = "librosa", marker = "extra == 'audio'", specifier = ">=0.10.0" },
+    { name = "librosa", marker = "extra == 'audio-laion'", specifier = ">=0.10.0" },
     { name = "matplotlib", specifier = ">=3.9.2" },
     { name = "moviepy", specifier = ">=1.0.3" },
     { name = "mypy", marker = "extra == 'dev'", specifier = ">=1.5.0" },
     { name = "networkx", specifier = ">=3.1" },
     { name = "numba", specifier = ">=0.60.0" },
-    { name = "numpy", specifier = ">=1.24.0,<2.0" },
-    { name = "open-clip-torch", specifier = ">=2.24.0" },
+    { name = "numpy", specifier = ">=1.24.0" },
+    { name = "open-clip-torch", marker = "extra == 'scene'", specifier = ">=2.24.0" },
     { name = "openai", specifier = ">=1.0.0" },
-    { name = "openai-whisper", specifier = ">=20250625" },
-    { name = "opencv-python-headless", specifier = ">=4.11.0.86" },
-    { name = "openface-test", specifier = ">=0.1.13" },
+    { name = "openai-whisper", marker = "extra == 'audio'", specifier = ">=20250625" },
+    { name = "opencv-python", marker = "extra == 'face'", specifier = ">=4.11.0.86,<5.0" },
+    { name = "opencv-python", marker = "extra == 'face-openface3'", specifier = ">=4.11.0.86,<5.0" },
+    { name = "opencv-python", marker = "extra == 'person'", specifier = ">=4.11.0.86,<5.0" },
+    { name = "opencv-python", marker = "extra == 'scene'", specifier = ">=4.11.0.86,<5.0" },
+    { name = "openface-test", marker = "extra == 'face-openface3'", specifier = ">=0.1.13" },
     { name = "openpyxl" },
     { name = "packaging", specifier = ">=21.0" },
     { name = "pandas", specifier = ">=2.2.2" },
@@ -4001,11 +4475,11 @@ requires-dist = [
     { name = "praatio", specifier = ">=6.2.0" },
     { name = "pre-commit", marker = "extra == 'dev'", specifier = ">=3.0.0" },
     { name = "psutil", specifier = ">=5.9.0" },
-    { name = "pyannote-audio", specifier = ">=3.3.2" },
-    { name = "pyannote-core", specifier = ">=5.0.0" },
-    { name = "pyannote-database", specifier = ">=5.1.0" },
-    { name = "pyannote-metrics", specifier = ">=3.2.1" },
-    { name = "pyannote-pipeline", specifier = ">=3.0.1" },
+    { name = "pyannote-audio", marker = "extra == 'audio'", specifier = ">=3.3.2" },
+    { name = "pyannote-core", marker = "extra == 'audio'", specifier = ">=5.0.0" },
+    { name = "pyannote-database", marker = "extra == 'audio'", specifier = ">=5.1.0" },
+    { name = "pyannote-metrics", marker = "extra == 'audio'", specifier = ">=3.2.1" },
+    { name = "pyannote-pipeline", marker = "extra == 'audio'", specifier = ">=3.0.1" },
     { name = "pycocotools", specifier = ">=2.0.10" },
     { name = "pydantic", specifier = ">=2.0.0" },
     { name = "pyjwt", specifier = ">=2.10.1" },
@@ -4017,30 +4491,41 @@ requires-dist = [
     { name = "rich", specifier = ">=13.0.0" },
     { name = "ruff", specifier = "==0.14.0" },
     { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.8.0" },
-    { name = "scenedetect", extras = ["opencv"], specifier = ">=0.6.3" },
+    { name = "scenedetect", marker = "extra == 'scene'", specifier = ">=0.6.3" },
     { name = "scikit-image", specifier = ">=0.25.2" },
     { name = "scikit-learn", specifier = ">=1.3.0" },
-    { name = "scipy", specifier = ">=1.11.0" },
+    { name = "scipy", marker = "extra == 'face-openface3'", specifier = ">=1.11.0" },
     { name = "seaborn", specifier = ">=0.12.0" },
-    { name = "sentence-transformers", specifier = ">=2.2.0" },
     { name = "sqlalchemy", specifier = ">=2.0.0" },
-    { name = "supervision", specifier = ">=0.16.0" },
-    { name = "timm", specifier = ">=0.9.0" },
-    { name = "torch", marker = "sys_platform != 'linux'", specifier = "==2.6.0" },
-    { name = "torch", marker = "sys_platform == 'linux'", specifier = "==2.6.0", index = "https://download.pytorch.org/whl/cu124" },
-    { name = "torchaudio", marker = "sys_platform != 'linux'", specifier = "==2.6.0" },
-    { name = "torchaudio", marker = "sys_platform == 'linux'", specifier = "==2.6.0", index = "https://download.pytorch.org/whl/cu124" },
-    { name = "torchvision", marker = "sys_platform != 'linux'", specifier = "==0.21.0" },
-    { name = "torchvision", marker = "sys_platform == 'linux'", specifier = "==0.21.0", index = "https://download.pytorch.org/whl/cu124" },
+    { name = "supervision", marker = "extra == 'person'", specifier = ">=0.16.0" },
+    { name = "tf-keras", marker = "extra == 'face'", specifier = ">=2.15.0" },
+    { name = "torch", marker = "sys_platform == 'linux' and extra == 'audio'", specifier = "==2.6.0", index = "https://download.pytorch.org/whl/cu124" },
+    { name = "torch", marker = "sys_platform == 'linux' and extra == 'audio-laion'", specifier = "==2.6.0", index = "https://download.pytorch.org/whl/cu124" },
+    { name = "torch", marker = "sys_platform == 'linux' and extra == 'face-laion'", specifier = "==2.6.0", index = "https://download.pytorch.org/whl/cu124" },
+    { name = "torch", marker = "sys_platform == 'linux' and extra == 'person'", specifier = "==2.6.0", index = "https://download.pytorch.org/whl/cu124" },
+    { name = "torch", marker = "sys_platform == 'linux' and extra == 'scene'", specifier = "==2.6.0", index = "https://download.pytorch.org/whl/cu124" },
+    { name = "torch", marker = "sys_platform != 'linux' and extra == 'audio'", specifier = "==2.6.0" },
+    { name = "torch", marker = "sys_platform != 'linux' and extra == 'audio-laion'", specifier = "==2.6.0" },
+    { name = "torch", marker = "sys_platform != 'linux' and extra == 'face-laion'", specifier = "==2.6.0" },
+    { name = "torch", marker = "sys_platform != 'linux' and extra == 'person'", specifier = "==2.6.0" },
+    { name = "torch", marker = "sys_platform != 'linux' and extra == 'scene'", specifier = "==2.6.0" },
+    { name = "torchaudio", marker = "sys_platform == 'linux' and extra == 'audio'", specifier = "==2.6.0", index = "https://download.pytorch.org/whl/cu124" },
+    { name = "torchaudio", marker = "sys_platform != 'linux' and extra == 'audio'", specifier = "==2.6.0" },
+    { name = "torchvision", marker = "sys_platform == 'linux' and extra == 'face-laion'", specifier = "==0.21.0", index = "https://download.pytorch.org/whl/cu124" },
+    { name = "torchvision", marker = "sys_platform == 'linux' and extra == 'person'", specifier = "==0.21.0", index = "https://download.pytorch.org/whl/cu124" },
+    { name = "torchvision", marker = "sys_platform != 'linux' and extra == 'face-laion'", specifier = "==0.21.0" },
+    { name = "torchvision", marker = "sys_platform != 'linux' and extra == 'person'", specifier = "==0.21.0" },
     { name = "tqdm", specifier = ">=4.65.0" },
-    { name = "transformers", specifier = ">=4.40.0" },
+    { name = "transformers", marker = "extra == 'audio-laion'", specifier = ">=4.40.0" },
+    { name = "transformers", marker = "extra == 'face-laion'", specifier = ">=4.40.0" },
     { name = "typer", specifier = ">=0.9.0" },
-    { name = "ultralytics", specifier = ">=8.3.0" },
+    { name = "ultralytics", marker = "extra == 'person'", specifier = ">=8.3.0" },
     { name = "uvicorn", extras = ["standard"], specifier = ">=0.30.0" },
-    { name = "videoannotator", extras = ["dev", "annotation"], marker = "extra == 'all'" },
+    { name = "videoannotator", extras = ["face"], marker = "extra == 'face-laion'" },
+    { name = "videoannotator", extras = ["face", "face-laion", "face-openface3", "audio", "audio-laion", "scene", "person", "dev", "annotation"], marker = "extra == 'all'" },
     { name = "webvtt-py", specifier = ">=0.5.1" },
 ]
-provides-extras = ["dev", "annotation", "all"]
+provides-extras = ["face", "face-laion", "face-openface3", "audio", "audio-laion", "scene", "person", "dev", "annotation", "all"]
 
 [package.metadata.requires-dev]
 dev = [
@@ -4161,6 +4646,30 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/f3/ed/aad7e0f5a462d679f7b4d2e0d8502c3096740c883b5bbed5103146480937/webvtt_py-0.5.1-py3-none-any.whl", hash = "sha256:9d517d286cfe7fc7825e9d4e2079647ce32f5678eb58e39ef544ffbb932610b7", size = 19802, upload-time = "2024-05-30T13:40:14.661Z" },
 ]
 
+[[package]]
+name = "werkzeug"
+version = "3.1.8"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "markupsafe" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/dd/b2/381be8cfdee792dd117872481b6e378f85c957dd7c5bca38897b08f765fd/werkzeug-3.1.8.tar.gz", hash = "sha256:9bad61a4268dac112f1c5cd4630a56ede601b6ed420300677a869083d70a4c44", size = 875852, upload-time = "2026-04-02T18:49:14.268Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/93/8c/2e650f2afeb7ee576912636c23ddb621c91ac6a98e66dc8d29c3c69446e1/werkzeug-3.1.8-py3-none-any.whl", hash = "sha256:63a77fb8892bf28ebc3178683445222aa500e48ebad5ec77b0ad80f8726b1f50", size = 226459, upload-time = "2026-04-02T18:49:12.72Z" },
+]
+
+[[package]]
+name = "wheel"
+version = "0.47.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "packaging" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/39/62/75f18a0f03b4219c456652c7780e4d749b929eb605c098ce3a5b6b6bc081/wheel-0.47.0.tar.gz", hash = "sha256:cc72bd1009ba0cf63922e28f94d9d83b920aa2bb28f798a31d0691b02fa3c9b3", size = 63854, upload-time = "2026-04-22T15:51:27.727Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/87/1b/9e33c09813d65e248f7f773119148a612516a4bea93e9c6f545f78455b7c/wheel-0.47.0-py3-none-any.whl", hash = "sha256:212281cab4dff978f6cedd499cd893e1f620791ca6ff7107cf270781e587eced", size = 32218, upload-time = "2026-04-22T15:51:26.296Z" },
+]
+
 [[package]]
 name = "widgetsnbextension"
 version = "4.0.14"
@@ -4170,6 +4679,26 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/ca/51/5447876806d1088a0f8f71e16542bf350918128d0a69437df26047c8e46f/widgetsnbextension-4.0.14-py3-none-any.whl", hash = "sha256:4875a9eaf72fbf5079dc372a51a9f268fc38d46f767cbf85c43a36da5cb9b575", size = 2196503, upload-time = "2025-04-10T13:01:23.086Z" },
 ]
 
+[[package]]
+name = "wrapt"
+version = "2.2.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/fe/a4/282c8e64300a59fc834518a54bf0afabb4ff9218b5fa76958b450459a844/wrapt-2.2.2.tar.gz", hash = "sha256:0788e321027c999bf221b667bd4a54aaefd1a36283749a860ac3eb77daed0302", size = 129068, upload-time = "2026-06-20T23:49:44.49Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2a/85/180b40628b23772692a0c76e8030114e1c0ae068470ed531919f0a5f2a4a/wrapt-2.2.2-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:8417fd3c674d3c8023d080292d29301531a12daf8bd938dd419710dd2f464f2b", size = 81484, upload-time = "2026-06-20T23:47:59.924Z" },
+    { url = "https://files.pythonhosted.org/packages/94/f2/21c90f2a16689702e2aaff45795b11018dff2c9b1242bac10d225483f676/wrapt-2.2.2-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:0e7070c7472582e31af3dfc2622b2381a0df7435110a9388ed8db5ffbce67efb", size = 82151, upload-time = "2026-06-20T23:48:01.303Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/b3/7e6e9fcf4fe7e1b69a49fe6cc5a44e8224bab6283c5233c97e132f14908e/wrapt-2.2.2-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:2e096c9d39a59b35b63c9aacfbbbec2088ff51ff1fc31051acc60a07f42f273a", size = 169828, upload-time = "2026-06-20T23:48:02.719Z" },
+    { url = "https://files.pythonhosted.org/packages/0b/43/894f132d857ed5a9904d937baf368badcbe5ea9e436e2f1930fe21c9f1f0/wrapt-2.2.2-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6d1a6050405bf334be33bf66296f113563622972a34900ae6fa60fd283a1a900", size = 171544, upload-time = "2026-06-20T23:48:04.266Z" },
+    { url = "https://files.pythonhosted.org/packages/29/de/3c833e03725b477e9ea34028224dd21a48781830101e4e036f77e8b6b102/wrapt-2.2.2-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:10adb01371408c6de504a6658b9886480f1a4919a83752748a387a504a21df79", size = 160663, upload-time = "2026-06-20T23:48:05.708Z" },
+    { url = "https://files.pythonhosted.org/packages/33/be/27edce350b24e3054d9d047f65f16d4c4d4c1f3f31c4278a1f8a95c723c8/wrapt-2.2.2-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:3442eee2a5798f9b451f1b2cd7518ce8b7e28a2a364696c414460a0e295c012a", size = 169387, upload-time = "2026-06-20T23:48:07.243Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/c4/9fd9679af8bf38e146652c7f47b6b352c3e5795b4ad1c0b7f94e15ac2aa7/wrapt-2.2.2-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:6c99012a22f735a85eed7c4b86a3e99c30fdd57d9e115b2b45f796264b58d0bf", size = 158849, upload-time = "2026-06-20T23:48:08.91Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/c2/aa6c0c2206803068c6859dabe01f8c84c43744da93d4c67b8946d21655ee/wrapt-2.2.2-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:3b686cfc008776a3952d6213cb296ed7f45d782a8453936406faa89eac0835ab", size = 168147, upload-time = "2026-06-20T23:48:10.374Z" },
+    { url = "https://files.pythonhosted.org/packages/42/63/3eb25da41049d20ae18fcab2dd8b056e02387c4bfa626cbdfb7c3b872e4f/wrapt-2.2.2-cp312-cp312-win32.whl", hash = "sha256:ef2cce266b5b0b07e19fa82e59673b81142b7a3607c8ed1254113d048ed668da", size = 77734, upload-time = "2026-06-20T23:48:11.769Z" },
+    { url = "https://files.pythonhosted.org/packages/da/09/0390e008a305360948fa9ce69507d041ac12cb2ee5d28e34467e2ee79391/wrapt-2.2.2-cp312-cp312-win_amd64.whl", hash = "sha256:abf8c20a2d72ee69e16328b3c91342c446e723bfe48bfcc4dded3b9722ac027f", size = 80585, upload-time = "2026-06-20T23:48:13.117Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/b3/84c445c66969f2d3457276b183a48c91097d59bbef9af6c075366b0f8c36/wrapt-2.2.2-cp312-cp312-win_arm64.whl", hash = "sha256:c6c64c5d02578bc4c4bca4f0aef1504de933c1d5b4ac2710b9131111459506c8", size = 79553, upload-time = "2026-06-20T23:48:14.5Z" },
+    { url = "https://files.pythonhosted.org/packages/6e/d2/6317eb6d4554855bbf12d61857774af34747bf88a42c19bf306de67e2fa3/wrapt-2.2.2-py3-none-any.whl", hash = "sha256:5bad217350f19ce99ca5b5e71d406765ea86fe541628426772b657375ee1c048", size = 61460, upload-time = "2026-06-20T23:49:42.966Z" },
+]
+
 [[package]]
 name = "xxhash"
 version = "3.5.0"

From bcc64ea42a1de28bc747283a86eb3926b6cade83 Mon Sep 17 00:00:00 2001
From: Caspar Addyman <infantologist@gmail.com>
Date: Sun, 19 Jul 2026 15:30:04 +0000
Subject: [PATCH 05/10] docs(roadmap): update v1.5.0 success criteria with
 verified status

Checks off criteria confirmed this session (no-extras install has no
heavy deps, actionable install-hint errors, Linux NumPy 2.x suite) and
marks two as partially verified (install-to-viewer flow modulo an
actual browser check; the viewer contract test's Python-side, which
already runs in CI, vs. its still-deferred TypeScript-side).

Leaves three genuinely open with explicit reasons rather than silently
unchecked: Docker image size (no docker binary in this sandbox),
macOS/Windows suite runs (Linux-only sandbox, needs real CI), and true
byte-identical v1.4.3 parity (needs golden fixtures captured from the
v1.4.4 tag, not done in this pass).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/development/roadmap_v1.5.0.md | 40 ++++++++++++++++++++++++------
 1 file changed, 32 insertions(+), 8 deletions(-)

diff --git a/docs/development/roadmap_v1.5.0.md b/docs/development/roadmap_v1.5.0.md
index 043dbf8..c98612b 100644
--- a/docs/development/roadmap_v1.5.0.md
+++ b/docs/development/roadmap_v1.5.0.md
@@ -135,15 +135,39 @@ before resubmission.
 
 ## ✅ Success Criteria
 
-- [ ] `pip install videoannotator` (no extras) installs without torch/transformers/pyannote/ultralytics/whisper.
+- [x] `pip install videoannotator` (no extras) installs without torch/transformers/pyannote/ultralytics/whisper.
+      Verified: `[project.dependencies]` contains none of them; confirmed via real `pip install
+      videoannotator[scene]`/`[face]` runs during 004's manual quickstart pass (§1/§2) that only the
+      requested family's deps land, nothing else.
 - [ ] `pip install videoannotator[all]` reproduces v1.4.3 behaviour exactly; no config/CLI changes needed.
-- [ ] Default Docker image size reduced by ≥ 80% vs. the v1.4.3 baseline.
-- [ ] A user with no extras installed gets an actionable install command, not a traceback, when
-      requesting an unavailable pipeline.
-- [ ] `pip install videoannotator[all]` + `videoannotator serve` gets a user from install to a
-      reviewable annotated video in one command, without cloning a second repository.
-- [ ] Full test suite passes on NumPy 2.x, Linux/macOS/Windows.
-- [ ] Cross-repo contract test between VideoAnnotator and Video Annotation Viewer is running in CI.
+      Mechanism exists (`tests/integration/test_v144_parity.py`, run and passing — 4 passed, 6
+      skipped) but the skips are real: no v1.4.4 golden fixtures have been captured yet (needs
+      checking out the v1.4.4 tag and running real model inference to generate them — substantial,
+      not done in this pass). See the test file's own module docstring for the capture procedure.
+- [ ] Default Docker image size reduced by ≥ 80% vs. the v1.4.3 baseline. Not measurable in this
+      sandbox (no `docker` binary available) — needs an environment with Docker to build
+      `Dockerfile.cpu`/`Dockerfile.gpu` both slim and `--build-arg EXTRAS=all`, and compare.
+- [x] A user with no extras installed gets an actionable install command, not a traceback, when
+      requesting an unavailable pipeline. Verified: `tests/contract/test_unavailable_pipeline_error.py`
+      + `test_pipeline_availability_contract.py` pass (7 tests), and confirmed live via a real running
+      server returning `422` + `install_hint` for an unavailable pipeline (004's manual quickstart §1).
+- [~] `pip install videoannotator[all]` + `videoannotator server --dev` gets a user from install to a
+      reviewable annotated video, without cloning a second repository. (Roadmap text said `serve`;
+      the actual command is `server`.) Substantially verified: a real install + running server +
+      `job submit` produced valid COCO output for `scene_detection` and `face_analysis`, and the
+      viewer mounts at `/viewer` same-origin. Not yet confirmed: actually opening `/viewer` in a
+      browser and seeing that output rendered — no browser available in this sandbox to check that
+      last step.
+- [x] Full test suite passes on NumPy 2.x — **on Linux**. Verified repeatedly this session (most
+      recently 1066 passed, 32 skipped, 0 failed under numpy 2.2.6 with `[all]` extras). **Not**
+      verified on macOS/Windows — this sandbox is Linux-only; needs the real CI matrix
+      (`.github/workflows/ci-cd.yml`'s `test` job already covers all three OSes, just needs a run
+      against the numpy-unpinned state to confirm).
+- [~] Cross-repo contract test between VideoAnnotator and Video Annotation Viewer is running in CI.
+      Python-side half: yes — `tests/contract/test_viewer_contract.py` passes (4 tests) and runs
+      automatically in the existing CI `test` job, no workflow changes needed. TypeScript-side half
+      (VAV's own parsers against these fixtures): still deferred, needs Node/bun tooling not
+      available in this sandbox — see Phase 2's own checklist above.
 
 ---
 

From 63c8dc2f43d675350a99569ce7d093356afa9ba0 Mon Sep 17 00:00:00 2001
From: Caspar Addyman <infantologist@gmail.com>
Date: Sun, 19 Jul 2026 15:50:19 +0000
Subject: [PATCH 06/10] ci: work around macOS ARM64 OpenMP double-init crash
 under numpy 2.x

test (macos-latest) started hard-crashing (Fatal Python error: Aborted,
exit 134) during test collection after dropping the numpy<2.0 pin --
numpy 2.x + pyarrow (via datasets/pandas) each bundle their own OpenMP
runtime, which can double-initialize alongside TensorFlow's and abort
the process on import rather than any actual test failure. Confirmed
via CI: master's last green run (numpy 1.26.4) passed macOS cleanly;
this branch's only dependency diff is numpy 1.26.4 -> 2.2.6, and
pyarrow/pandas versions are otherwise identical.

Sets KMP_DUPLICATE_LIB_OK=TRUE for the pytest step, the standard
mitigation for this class of crash and the same one already documented
for audio pipelines in docs/installation/INSTALLATION.md's macOS
libomp note. No-op on Linux/Windows.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .github/workflows/ci-cd.yml | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/.github/workflows/ci-cd.yml b/.github/workflows/ci-cd.yml
index 1c7dff3..c977193 100644
--- a/.github/workflows/ci-cd.yml
+++ b/.github/workflows/ci-cd.yml
@@ -69,6 +69,14 @@ jobs:
           uv run mypy src/videoannotator
 
       - name: Test with pytest
+        env:
+          # macOS ARM64: numpy 2.x + pyarrow (via datasets/pandas) each bundle their
+          # own OpenMP runtime, which can double-initialize alongside TensorFlow's
+          # and abort the process (Fatal Python error: Aborted) on import, not on
+          # any actual test failure. Same class of issue already documented for
+          # audio pipelines in docs/installation/INSTALLATION.md's macOS libomp
+          # note. No-op on Linux/Windows.
+          KMP_DUPLICATE_LIB_OK: "TRUE"
         run: |
           uv run pytest -q --cov=src/videoannotator --cov-report=xml --cov-report=term-missing --cov-fail-under=45
 

From a29829aa069db922bd058a5faf7d0bfc9925c095 Mon Sep 17 00:00:00 2001
From: Caspar Addyman <infantologist@gmail.com>
Date: Sun, 19 Jul 2026 16:10:47 +0000
Subject: [PATCH 07/10] fix(deps): bump pyarrow 21.0.0 -> 25.0.0 (macOS ARM64
 crash)

KMP_DUPLICATE_LIB_OK=TRUE (previous commit) did not fix the macOS
ARM64 test job's Fatal Python error: Aborted crash -- confirmed via
CI, identical crash at pyarrow/__init__.py:61 with the env var set,
ruling out an OpenMP double-init conflict. This looks like an ABI
issue in pyarrow 21.0.0's compiled extension against numpy 2.2.6 on
that specific platform (datasets>=2.16.0 and pandas both leave
pyarrow's upper bound unconstrained, so 21.0.0 was just whatever
uv's numpy-only upgrade left in place, not a deliberate pin).

Forced a fresh resolve of pyarrow specifically (`uv lock
--upgrade-package pyarrow`); verified locally on Linux (pyarrow
imports cleanly, tests/unit: 646 passed, 0 failed) before pushing to
let CI confirm on the actual affected platform.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 uv.lock | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/uv.lock b/uv.lock
index cf58e4b..1bb8d5e 100644
--- a/uv.lock
+++ b/uv.lock
@@ -2805,17 +2805,17 @@ wheels = [
 
 [[package]]
 name = "pyarrow"
-version = "21.0.0"
+version = "25.0.0"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/ef/c2/ea068b8f00905c06329a3dfcd40d0fcc2b7d0f2e355bdb25b65e0a0e4cd4/pyarrow-21.0.0.tar.gz", hash = "sha256:5051f2dccf0e283ff56335760cbc8622cf52264d67e359d5569541ac11b6d5bc", size = 1133487, upload-time = "2025-07-18T00:57:31.761Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/27/f3/95428098d1fa7d04432fb750eed06b41304c2f6a5d3319985e64db2d9d41/pyarrow-25.0.0.tar.gz", hash = "sha256:d2d697008b5ec06d75952ef260c2e9a8a0f6ccfce24266c04c9c8ade927cb3b4", size = 1199181, upload-time = "2026-07-10T08:29:50.116Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/ca/d4/d4f817b21aacc30195cf6a46ba041dd1be827efa4a623cc8bf39a1c2a0c0/pyarrow-21.0.0-cp312-cp312-macosx_12_0_arm64.whl", hash = "sha256:3a302f0e0963db37e0a24a70c56cf91a4faa0bca51c23812279ca2e23481fccd", size = 31160305, upload-time = "2025-07-18T00:55:35.373Z" },
-    { url = "https://files.pythonhosted.org/packages/a2/9c/dcd38ce6e4b4d9a19e1d36914cb8e2b1da4e6003dd075474c4cfcdfe0601/pyarrow-21.0.0-cp312-cp312-macosx_12_0_x86_64.whl", hash = "sha256:b6b27cf01e243871390474a211a7922bfbe3bda21e39bc9160daf0da3fe48876", size = 32684264, upload-time = "2025-07-18T00:55:39.303Z" },
-    { url = "https://files.pythonhosted.org/packages/4f/74/2a2d9f8d7a59b639523454bec12dba35ae3d0a07d8ab529dc0809f74b23c/pyarrow-21.0.0-cp312-cp312-manylinux_2_28_aarch64.whl", hash = "sha256:e72a8ec6b868e258a2cd2672d91f2860ad532d590ce94cdf7d5e7ec674ccf03d", size = 41108099, upload-time = "2025-07-18T00:55:42.889Z" },
-    { url = "https://files.pythonhosted.org/packages/ad/90/2660332eeb31303c13b653ea566a9918484b6e4d6b9d2d46879a33ab0622/pyarrow-21.0.0-cp312-cp312-manylinux_2_28_x86_64.whl", hash = "sha256:b7ae0bbdc8c6674259b25bef5d2a1d6af5d39d7200c819cf99e07f7dfef1c51e", size = 42829529, upload-time = "2025-07-18T00:55:47.069Z" },
-    { url = "https://files.pythonhosted.org/packages/33/27/1a93a25c92717f6aa0fca06eb4700860577d016cd3ae51aad0e0488ac899/pyarrow-21.0.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:58c30a1729f82d201627c173d91bd431db88ea74dcaa3885855bc6203e433b82", size = 43367883, upload-time = "2025-07-18T00:55:53.069Z" },
-    { url = "https://files.pythonhosted.org/packages/05/d9/4d09d919f35d599bc05c6950095e358c3e15148ead26292dfca1fb659b0c/pyarrow-21.0.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:072116f65604b822a7f22945a7a6e581cfa28e3454fdcc6939d4ff6090126623", size = 45133802, upload-time = "2025-07-18T00:55:57.714Z" },
-    { url = "https://files.pythonhosted.org/packages/71/30/f3795b6e192c3ab881325ffe172e526499eb3780e306a15103a2764916a2/pyarrow-21.0.0-cp312-cp312-win_amd64.whl", hash = "sha256:cf56ec8b0a5c8c9d7021d6fd754e688104f9ebebf1bf4449613c9531f5346a18", size = 26203175, upload-time = "2025-07-18T00:56:01.364Z" },
+    { url = "https://files.pythonhosted.org/packages/73/44/fdd3a4377807b7dcabe2d4b5aa99dbbc98e2e5df3f1ca4e7f0aec492d987/pyarrow-25.0.0-cp312-cp312-macosx_12_0_arm64.whl", hash = "sha256:149730a3d1f0fb59d663a0b8aa210adfd9c17c27cd94a0d143e60daea8320d4e", size = 35850884, upload-time = "2026-07-10T08:26:47.357Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/71/9f053177a7709b8c90abb00a2375b916286f9f0d6cfb21a5cadd4ef811e8/pyarrow-25.0.0-cp312-cp312-macosx_12_0_x86_64.whl", hash = "sha256:0721332c30fdd453fdd1fc203b2ac1f4c9db5aea28fa38d41f2574c4b068b9ec", size = 37616197, upload-time = "2026-07-10T08:26:53.564Z" },
+    { url = "https://files.pythonhosted.org/packages/95/1a/22bfb6597dcdc861fa83c39c06e1457cb56f698940eff42fbb25de30e8e5/pyarrow-25.0.0-cp312-cp312-manylinux_2_28_aarch64.whl", hash = "sha256:fa1482b3da10cac2d4db6e26b81da543e237616af2ef6d466018b31ca586496f", size = 46841966, upload-time = "2026-07-10T08:27:07.685Z" },
+    { url = "https://files.pythonhosted.org/packages/55/0e/cd705c042bc4fe7022478db577fcab4abdcfabb9bc37ab7a75556b3fcb2b/pyarrow-25.0.0-cp312-cp312-manylinux_2_28_x86_64.whl", hash = "sha256:5d1dbf24e151042f2fa3c129563f65d66674128868496fb008c4272b16bdf778", size = 50088993, upload-time = "2026-07-10T08:27:14.268Z" },
+    { url = "https://files.pythonhosted.org/packages/98/ee/d822e1ee31fe31ec5d057210e0605c950b975dcd8d9a332976cc859a9df8/pyarrow-25.0.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:20887a762dd61dcc530f93a140840ab1f6aa7836b33270e42d627ab3cf11e537", size = 49941005, upload-time = "2026-07-10T08:27:21.274Z" },
+    { url = "https://files.pythonhosted.org/packages/33/1b/207a90cc64619a095eb75a263ae069735f2810056d43c667befd573ec083/pyarrow-25.0.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:58d1ab556b0cea1c93fdb799b24ad58adb2f2a2788dbce782a94f64ae1a5cc9b", size = 53112355, upload-time = "2026-07-10T08:27:27.911Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/fe/81d1e5f8beed15c01e98649d5c6e2167b67fd395884a2488f18bf1cf0dba/pyarrow-25.0.0-cp312-cp312-win_amd64.whl", hash = "sha256:3f356afe61186395c861d5cd63dc21ff7d5fa335012a4668d979257df7fea0f5", size = 27945954, upload-time = "2026-07-10T08:27:32.903Z" },
 ]
 
 [[package]]

From e2b8cf70e5468fd8b27009fa422b751d5a4459cf Mon Sep 17 00:00:00 2001
From: Caspar Addyman <infantologist@gmail.com>
Date: Sun, 19 Jul 2026 17:34:00 +0100
Subject: [PATCH 08/10] Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 .../contracts/unavailable-pipeline-error.md                     | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/specs/004-extras-based-install/contracts/unavailable-pipeline-error.md b/specs/004-extras-based-install/contracts/unavailable-pipeline-error.md
index 3c17f1c..fc1b2f0 100644
--- a/specs/004-extras-based-install/contracts/unavailable-pipeline-error.md
+++ b/specs/004-extras-based-install/contracts/unavailable-pipeline-error.md
@@ -3,7 +3,7 @@
 Applies to every user-facing surface that can name a pipeline: CLI (`videoannotator job submit
 ... --pipelines <name>`), REST API (`POST /api/v1/jobs`, `GET /api/v1/pipelines`).
 
-## Registry listing (`GET /api/v1/pipelines`, `videoannotator pipelines list`)
+## Registry listing (`GET /api/v1/pipelines`, `videoannotator pipelines`)
 
 Unavailable pipelines (extras not installed) are **omitted** from the default listing — not shown
 with an error, not shown at all — per FR-005. A `--all` / `?include_unavailable=true` variant MAY

From 9e783a515fb2a7b1bce6aaf972c797a980427137 Mon Sep 17 00:00:00 2001
From: Caspar Addyman <infantologist@gmail.com>
Date: Sun, 19 Jul 2026 17:34:28 +0100
Subject: [PATCH 09/10] Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 tests/contract/test_unavailable_pipeline_error.py | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/tests/contract/test_unavailable_pipeline_error.py b/tests/contract/test_unavailable_pipeline_error.py
index d8cc384..28106ad 100644
--- a/tests/contract/test_unavailable_pipeline_error.py
+++ b/tests/contract/test_unavailable_pipeline_error.py
@@ -107,7 +107,7 @@ def test_job_submit_unavailable_pipeline_exits_nonzero_no_traceback(self, tmp_pa
                 ],
             )
 
-        assert result.exit_code != 0
-        assert "Traceback" not in result.output
-        assert "Error:" in result.output
-        assert "pip install videoannotator[face-laion]" in result.output
+        combined = result.stdout + (getattr(result, "stderr", "") or "")
+        assert "Traceback" not in combined
+        assert "Error:" in combined
+        assert "pip install videoannotator[face-laion]" in combined

From b61334c5145fc18b88192d943cc7d2015ba38ffc Mon Sep 17 00:00:00 2001
From: Caspar Addyman <infantologist@gmail.com>
Date: Sun, 19 Jul 2026 17:34:38 +0100
Subject: [PATCH 10/10] Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 src/videoannotator/pipelines/face_analysis/face_pipeline.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/videoannotator/pipelines/face_analysis/face_pipeline.py b/src/videoannotator/pipelines/face_analysis/face_pipeline.py
index 8a2bb92..ec6c0be 100644
--- a/src/videoannotator/pipelines/face_analysis/face_pipeline.py
+++ b/src/videoannotator/pipelines/face_analysis/face_pipeline.py
@@ -45,7 +45,8 @@ def _disable_tensorflow_gpu() -> None:
     try:
         import tensorflow as tf
 
-        tf.config.set_visible_devices([], "GPU")
+        if tf.config.list_physical_devices("GPU"):
+            tf.config.set_visible_devices([], "GPU")
     except ImportError:
         pass
     except Exception as e: