hflow 0.2.2__tar.gz → 0.2.4__tar.gz

{hflow-0.2.2 → hflow-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hflow
-Version: 0.2.2
+Version: 0.2.4
 Summary: Open source SDK for building Physical AI data pipelines
 Keywords: airflow,data-pipeline,data-quality,dataset-curation,mcap,physical-ai,robotics
 Author: Hebbian Robotics, Kingston Kuan, Brandon Ong
@@ -14,10 +14,10 @@ Requires-Dist: mcap-ros2-support>=0.5.7
 Requires-Dist: numpy>=2.4.6
 Requires-Dist: zstandard>=0.25.0
 Requires-Dist: pyarrow>=25.0.1 ; extra == 'arrow'
-Requires-Dist: obstore>=0.10.0 ; extra == 'bucket'
-Requires-Dist: mediapipe>=1.0.0 ; extra == 'mediapipe'
-Requires-Dist: opencv-python-headless>=4.10 ; extra == 'motion'
-Requires-Dist: openai>=3.0.0 ; extra == 'openai'
+Requires-Dist: obstore>=0.11.1 ; extra == 'bucket'
+Requires-Dist: mediapipe>=1.0.1 ; extra == 'mediapipe'
+Requires-Dist: opencv-python-headless>=5.0.0.93 ; extra == 'motion'
+Requires-Dist: openai>=3.3.1 ; extra == 'openai'
 Requires-Python: >=3.11
 Project-URL: Repository, https://github.com/Hebbian-Robotics/hflow
 Project-URL: Documentation, https://github.com/Hebbian-Robotics/hflow/tree/main/docs
@@ -87,7 +87,7 @@ episode.
 
 | | HFlow's boundary |
 | --- | --- |
-| **Input** | One multimodal episode per standard MCAP file (`hflow doctor` says whether yours qualifies) |
+| **Input** | Supported standard MCAP episodes directly; LeRobot Dataset v3 repositories through `hflow import lerobot` |
 | **Processing** | Your Python transforms, checks, labels, and enrichments |
 | **Execution** | In-process for development; generated Airflow 3 DAGs for scheduled runs |
 | **Durable output** | Canonical MCAP episodes, provenance, artifacts, and a Parquet catalog |
@@ -115,6 +115,13 @@ collection --> ingestion ---------------> curation ------> delivery
 - **Quality checks produce reusable evidence.** Accessors extract the inputs existing processing code expects (numpy arrays, MP4 paths, JPEG frames), and results land as queryable measurements rather than hardcoded verdicts. Different datasets can apply different thresholds without processing the media again.
 - **Query the corpus without loading the recordings.** Metadata, quality measurements, tags, version stamps, and artifact locations live in the Parquet catalog. [DuckDB](https://duckdb.org/) can answer corpus-wide questions and build manifests without opening the underlying MCAP files.
 
+Open DuckDB's browser over the catalog at any time, including before the first
+run starts:
+
+```bash
+hflow catalog ui
+```
+
 ## Hosting and scale
 
 The open-source deployment is built to be easy to own: run one single-tenant
@@ -135,10 +142,9 @@ the trust model, and the current limits.
 
 ## Community and hosted interest
 
-<!-- Add the Google Form link to the entry below once it is live. -->
-
-- **Hosted version interest:** Google Form coming soon.
+- **Hosted platform waitlist:** [tell us about your workflow](https://forms.gle/EZpQpGGF3eJomx498).
 - **Community Discord:** [join us](https://discord.gg/vacepQvjmg) for questions, feedback, and contribution discussion.
+- **Code of conduct:** review our [community standards](./CODE_OF_CONDUCT.md) and report concerns privately.
 
 For reproducible bugs and scoped feature requests, use
 [GitHub issues](https://github.com/Hebbian-Robotics/hflow/issues).
@@ -179,6 +185,19 @@ and contributors should start with [CONTRIBUTING.md](https://github.com/Hebbian-
 the [examples catalog](https://github.com/Hebbian-Robotics/hflow/blob/main/examples/README.md) for the egocentric-corpus and
 OpenAI vision paths.
 
+To import a LeRobot Dataset v3 episode into the same canonical MCAP boundary:
+
+```bash
+uv run hflow import lerobot \
+  --repo lerobot/pusht --revision main \
+  --camera observation.image --episode-index 0 \
+  --output-dir ./data/lerobot_pusht
+```
+
+The importer resolves `main` to an immutable source commit and records it as
+episode provenance. See the [LeRobot import guide](./docs/how-to/import-lerobot-v3.md)
+for the supported feature subset and a multi-camera example.
+
 ## What it looks like
 
 Get started in six lines of code. This fuller example uses a robot
@@ -233,19 +252,13 @@ WHERE task = 'fold_napkin'
   AND pipeline_version = 'a41c9f27b3d8'    -- pin one reprocessing generation
 ```
 
-## Design tenets
+## Design principles
 
 1. **Democratize the architecture, defer the optimizations.** Preserve the useful workflow and standard interfaces at small scale, and label each production-scale mechanism honestly as implemented, simplified, deferred, or out of scope.
 2. **Evidence, not verdicts.** Checks record measurements with coverage; pass/fail policy belongs to the consumer, at curation time. Quality tags route episodes; they never delete data.
 3. **Standard formats at every boundary.** MCAP episodes, Parquet catalogs, Airflow DAGs. Our code exists only where the format forces bridging or a pitfall is genuinely non-obvious.
 4. **Your code stays your code.** Existing transforms, checks, and enrichments plug in through small adapters instead of being rewritten.
 
-## Non-goals
-
-- **Training.** The pipeline ends at curated, quality-tagged, version-stamped episodes and a manifest. Many users filter data to deliver or sell it, not to train on it. (Converters to training formats such as [LeRobot](https://github.com/huggingface/lerobot) are planned as a separate, standalone package.)
-- **Maximum flexibility.** Robotics/physical-AI data is the narrative and the constraint budget: one canonical episode format, coarse-grained steps, and opinionated defaults are features.
-- **Million-hour throughput.** The [benchmark report](https://github.com/Hebbian-Robotics/hflow/blob/main/docs/BENCHMARKS.md) documents honestly what the simple version achieves and where it falls over.
-
 ## Requirements
 
 - Python ≥ 3.11
@@ -278,6 +291,14 @@ WHERE task = 'fold_napkin'
 - [FFmpeg](https://ffmpeg.org/)
 - [Pareto](https://github.com/Hebbian-Robotics/pareto), Hebbian Robotics' robotics data curation platform.
 
+## Contributing
+
+Thank you to all our contributors for making HFlow awesome! See [CONTRIBUTING.md](https://github.com/Hebbian-Robotics/hflow/blob/main/CONTRIBUTING.md) to join our community.
+
+<a href="https://github.com/Hebbian-Robotics/hflow/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=Hebbian-Robotics/hflow&max=48&columns=12" alt="HFlow contributors" />
+</a>
+
 ## License
 
 [Apache-2.0](https://github.com/Hebbian-Robotics/hflow/blob/main/LICENSE).

{hflow-0.2.2 → hflow-0.2.4}/README.md

@@ -56,7 +56,7 @@ episode.
 
 | | HFlow's boundary |
 | --- | --- |
-| **Input** | One multimodal episode per standard MCAP file (`hflow doctor` says whether yours qualifies) |
+| **Input** | Supported standard MCAP episodes directly; LeRobot Dataset v3 repositories through `hflow import lerobot` |
 | **Processing** | Your Python transforms, checks, labels, and enrichments |
 | **Execution** | In-process for development; generated Airflow 3 DAGs for scheduled runs |
 | **Durable output** | Canonical MCAP episodes, provenance, artifacts, and a Parquet catalog |
@@ -84,6 +84,13 @@ collection --> ingestion ---------------> curation ------> delivery
 - **Quality checks produce reusable evidence.** Accessors extract the inputs existing processing code expects (numpy arrays, MP4 paths, JPEG frames), and results land as queryable measurements rather than hardcoded verdicts. Different datasets can apply different thresholds without processing the media again.
 - **Query the corpus without loading the recordings.** Metadata, quality measurements, tags, version stamps, and artifact locations live in the Parquet catalog. [DuckDB](https://duckdb.org/) can answer corpus-wide questions and build manifests without opening the underlying MCAP files.
 
+Open DuckDB's browser over the catalog at any time, including before the first
+run starts:
+
+```bash
+hflow catalog ui
+```
+
 ## Hosting and scale
 
 The open-source deployment is built to be easy to own: run one single-tenant
@@ -104,10 +111,9 @@ the trust model, and the current limits.
 
 ## Community and hosted interest
 
-<!-- Add the Google Form link to the entry below once it is live. -->
-
-- **Hosted version interest:** Google Form coming soon.
+- **Hosted platform waitlist:** [tell us about your workflow](https://forms.gle/EZpQpGGF3eJomx498).
 - **Community Discord:** [join us](https://discord.gg/vacepQvjmg) for questions, feedback, and contribution discussion.
+- **Code of conduct:** review our [community standards](./CODE_OF_CONDUCT.md) and report concerns privately.
 
 For reproducible bugs and scoped feature requests, use
 [GitHub issues](https://github.com/Hebbian-Robotics/hflow/issues).
@@ -148,6 +154,19 @@ and contributors should start with [CONTRIBUTING.md](https://github.com/Hebbian-
 the [examples catalog](https://github.com/Hebbian-Robotics/hflow/blob/main/examples/README.md) for the egocentric-corpus and
 OpenAI vision paths.
 
+To import a LeRobot Dataset v3 episode into the same canonical MCAP boundary:
+
+```bash
+uv run hflow import lerobot \
+  --repo lerobot/pusht --revision main \
+  --camera observation.image --episode-index 0 \
+  --output-dir ./data/lerobot_pusht
+```
+
+The importer resolves `main` to an immutable source commit and records it as
+episode provenance. See the [LeRobot import guide](./docs/how-to/import-lerobot-v3.md)
+for the supported feature subset and a multi-camera example.
+
 ## What it looks like
 
 Get started in six lines of code. This fuller example uses a robot
@@ -202,19 +221,13 @@ WHERE task = 'fold_napkin'
   AND pipeline_version = 'a41c9f27b3d8'    -- pin one reprocessing generation
 ```
 
-## Design tenets
+## Design principles
 
 1. **Democratize the architecture, defer the optimizations.** Preserve the useful workflow and standard interfaces at small scale, and label each production-scale mechanism honestly as implemented, simplified, deferred, or out of scope.
 2. **Evidence, not verdicts.** Checks record measurements with coverage; pass/fail policy belongs to the consumer, at curation time. Quality tags route episodes; they never delete data.
 3. **Standard formats at every boundary.** MCAP episodes, Parquet catalogs, Airflow DAGs. Our code exists only where the format forces bridging or a pitfall is genuinely non-obvious.
 4. **Your code stays your code.** Existing transforms, checks, and enrichments plug in through small adapters instead of being rewritten.
 
-## Non-goals
-
-- **Training.** The pipeline ends at curated, quality-tagged, version-stamped episodes and a manifest. Many users filter data to deliver or sell it, not to train on it. (Converters to training formats such as [LeRobot](https://github.com/huggingface/lerobot) are planned as a separate, standalone package.)
-- **Maximum flexibility.** Robotics/physical-AI data is the narrative and the constraint budget: one canonical episode format, coarse-grained steps, and opinionated defaults are features.
-- **Million-hour throughput.** The [benchmark report](https://github.com/Hebbian-Robotics/hflow/blob/main/docs/BENCHMARKS.md) documents honestly what the simple version achieves and where it falls over.
-
 ## Requirements
 
 - Python ≥ 3.11
@@ -247,6 +260,14 @@ WHERE task = 'fold_napkin'
 - [FFmpeg](https://ffmpeg.org/)
 - [Pareto](https://github.com/Hebbian-Robotics/pareto), Hebbian Robotics' robotics data curation platform.
 
+## Contributing
+
+Thank you to all our contributors for making HFlow awesome! See [CONTRIBUTING.md](https://github.com/Hebbian-Robotics/hflow/blob/main/CONTRIBUTING.md) to join our community.
+
+<a href="https://github.com/Hebbian-Robotics/hflow/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=Hebbian-Robotics/hflow&max=48&columns=12" alt="HFlow contributors" />
+</a>
+
 ## License
 
 [Apache-2.0](https://github.com/Hebbian-Robotics/hflow/blob/main/LICENSE).

{hflow-0.2.2 → hflow-0.2.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hflow"
-version = "0.2.2"
+version = "0.2.4"
 description = "Open source SDK for building Physical AI data pipelines"
 readme = "README.md"
 license = "Apache-2.0"
@@ -36,10 +36,10 @@ name = "Brandon Ong"
 
 [project.optional-dependencies]
 arrow = ["pyarrow>=25.0.1"]
-bucket = ["obstore>=0.10.0"]
-mediapipe = ["mediapipe>=1.0.0"]
-motion = ["opencv-python-headless>=4.10"]
-openai = ["openai>=3.0.0"]
+bucket = ["obstore>=0.11.1"]
+mediapipe = ["mediapipe>=1.0.1"]
+motion = ["opencv-python-headless>=5.0.0.93"]
+openai = ["openai>=3.3.1"]
 
 [project.urls]
 Repository = "https://github.com/Hebbian-Robotics/hflow"
@@ -52,25 +52,29 @@ hflow = "hflow.cli:main"
 [dependency-groups]
 dev = [
     "hflow-server",
-    "httpx2>=2.10",
-    "obstore>=0.10.0",
-    "opencv-python-headless>=4.10",
+    "httpx2>=2.12.0",
+    "obstore>=0.11.1",
+    "opencv-python-headless>=5.0.0.93",
     "pyarrow>=25.0.1",
     "pytest>=9.1.1",
     "pyyaml>=6.0.3",
-    "ruff>=0.16.2",
-    "ty>=0.0.71",
+    "ruff>=0.16.4",
+    "ty>=0.0.74",
 ]
 
 [build-system]
-requires = ["uv_build>=0.11.33,<0.12"]
+requires = ["uv_build>=0.12.5,<0.13"]
 build-backend = "uv_build"
 
 [tool.uv]
 exclude-newer = "5 days"
 
 [tool.uv.workspace]
-members = ["packages/*"]
+members = [
+    "packages/*",
+    "examples/build_ai_evaluation",
+    "examples/egosuite_evaluation",
+]
 
 [tool.uv.sources.hflow-server]
 workspace = true
@@ -120,4 +124,8 @@ unused-ignore-comment = "error"
 possibly-unresolved-reference = "error"
 
 [tool.ty.src]
-exclude = ["examples/openai_vision/"]
+exclude = [
+    "examples/build_ai_evaluation/",
+    "examples/egosuite_evaluation/",
+    "examples/openai_vision/",
+]

{hflow-0.2.2 → hflow-0.2.4}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "hflow"
-version = "0.2.2"
+version = "0.2.4"
 description = "Open source SDK for building Physical AI data pipelines"
 readme = "README.md"
 license = "Apache-2.0"
@@ -35,21 +35,21 @@ arrow = ["pyarrow>=25.0.1"]
 # Native object-store data roots (gs://, s3://, az://): obstore is the Rust
 # object_store crate as a single dependency-free wheel; local-path roots
 # never import it.
-bucket = ["obstore>=0.10.0"]
+bucket = ["obstore>=0.11.1"]
 # Hand detection with MediaPipe's Hand Landmarker (hflow.mediapipe_hands).
 # A MODEL, not a signal statistic, so it is opt-in twice over: outside the core
 # install, and outside the dev group as well (unlike motion and bucket, which
 # are mirrored into dev so the suite exercises them). It adds ~430 MB and its
 # own OpenCV; a dev environment opts in with `--extra mediapipe`, exactly as
 # the openai example does.
-mediapipe = ["mediapipe>=1.0.0"]
+mediapipe = ["mediapipe>=1.0.1"]
 # Camera-shake measurement: pyramidal Lucas-Kanade optical flow and a RANSAC
 # similarity fit. No numpy-only equivalent preserves the instrument, and
 # reimplementing them would make it a different, unvalidated one -- so the
 # dependency is real, and confined to the one check that needs it. Headless
 # because a data pipeline runs where there is no display.
-motion = ["opencv-python-headless>=4.10"]
-openai = ["openai>=3.0.0"]
+motion = ["opencv-python-headless>=5.0.0.93"]
+openai = ["openai>=3.3.1"]
 
 [project.urls]
 Repository = "https://github.com/Hebbian-Robotics/hflow"
@@ -64,20 +64,20 @@ dev = [
     "hflow-server", # the workspace API package, present in dev so the suite tests it
     # Starlette's TestClient transport for the hflow-server suite. httpx2, not
     # httpx: starlette 1.6 deprecates the httpx transport in its favour.
-    "httpx2>=2.10",
-    "obstore>=0.10.0", # the bucket extra, present in dev so the suite tests it
+    "httpx2>=2.12.0",
+    "obstore>=0.11.1", # the bucket extra, present in dev so the suite tests it
     # the motion extra, present in dev so the suite tests it rather than
     # skipping the one check that cannot be verified any other way
-    "opencv-python-headless>=4.10",
+    "opencv-python-headless>=5.0.0.93",
     "pyarrow>=25.0.1", # the arrow extra, present in dev so the suite tests it
     "pytest>=9.1.1",
     "pyyaml>=6.0.3",
-    "ruff>=0.16.2",
-    "ty>=0.0.71",
+    "ruff>=0.16.4",
+    "ty>=0.0.74",
 ]
 
 [build-system]
-requires = ["uv_build>=0.11.33,<0.12"]
+requires = ["uv_build>=0.12.5,<0.13"]
 build-backend = "uv_build"
 
 [tool.uv]
@@ -87,7 +87,11 @@ build-backend = "uv_build"
 exclude-newer = "5 days"
 
 [tool.uv.workspace]
-members = ["packages/*"]
+members = [
+    "packages/*",
+    "examples/build_ai_evaluation",
+    "examples/egosuite_evaluation",
+]
 
 [tool.uv.sources]
 hflow-server = { workspace = true }
@@ -128,7 +132,11 @@ unused-ignore-comment = "error"
 possibly-unresolved-reference = "error"
 
 [tool.ty.src]
-# examples/openai_vision imports the user's own `openai` client: bundling a
-# VLM client is a non-goal (examples ARE the docs), so the package is
-# deliberately not a dependency and the example is excluded from typechecking.
-exclude = ["examples/openai_vision/"]
+# Workspace examples typecheck themselves with their own dependencies.
+# openai_vision imports the user's optional client, so the root project does
+# not typecheck it either.
+exclude = [
+    "examples/build_ai_evaluation/",
+    "examples/egosuite_evaluation/",
+    "examples/openai_vision/",
+]

{hflow-0.2.2 → hflow-0.2.4}/src/hflow/__init__.py

@@ -20,6 +20,12 @@ from hflow.app import (
 )
 from hflow.batching import PlannedBatch, plan_batches, plan_batches_from_files
 from hflow.catalog import AppendResult, Catalog, CheckRunRow
+from hflow.catalog_ui import (
+    DEFAULT_CATALOG_UI_PORT,
+    CatalogUiSettings,
+    CatalogUiStartupError,
+    serve_catalog_ui,
+)
 from hflow.curation import (
     CheckCoverage,
     CurationReport,
@@ -29,8 +35,9 @@ from hflow.curation import (
     stale_episodes,
 )
 from hflow.doctor import DiagnosticLevel, DoctorReport, Finding, diagnose
-from hflow.episode import ChannelData, Episode, ExtractedFrame
+from hflow.episode import ChannelData, DecodedMessageBatch, Episode, ExtractedFrame
 from hflow.format import GopPreset
+from hflow.importers import import_lerobot_dataset
 from hflow.manifest import (
     DerivedChannelManifest,
     PipelineManifest,
@@ -66,6 +73,7 @@ from hflow.steps import (
     IngestMode,
     Interval,
     MeasurementValue,
+    Observation,
     RegisteredCheck,
     RegisteredEnrichment,
     Stage,
@@ -92,12 +100,15 @@ except PackageNotFoundError:  # running from a source tree without an install
 __all__ = [
     "DATASET_SNAPSHOT_FORMAT_NAME",
     "DATASET_SNAPSHOT_FORMAT_VERSION",
+    "DEFAULT_CATALOG_UI_PORT",
     "RUN_PROFILES",
     "Aggregation",
     "App",
     "AppendResult",
     "BucketStorageRoot",
     "Catalog",
+    "CatalogUiSettings",
+    "CatalogUiStartupError",
     "ChannelData",
     "CheckCoverage",
     "CheckResult",
@@ -107,6 +118,7 @@ __all__ = [
     "Comparison",
     "CurationReport",
     "DatasetSnapshotReport",
+    "DecodedMessageBatch",
     "DerivedChannel",
     "DerivedChannelManifest",
     "DerivedSeries",
@@ -128,6 +140,7 @@ __all__ = [
     "LocalStorageRoot",
     "MeasurementValue",
     "MessageBatch",
+    "Observation",
     "PipelineManifest",
     "PlannedBatch",
     "PythonMcapEpisodeReader",
@@ -158,6 +171,7 @@ __all__ = [
     "export_dataset_snapshot",
     "fetch_uri",
     "ffmpeg",
+    "import_lerobot_dataset",
     "import_pipeline_application",
     "is_bucket_url",
     "open_catalog_connection",
@@ -166,6 +180,7 @@ __all__ = [
     "plan_batches",
     "plan_batches_from_files",
     "providers",
+    "serve_catalog_ui",
     "stages_for_profile",
     "stale_episodes",
     "testing",

hflow-0.2.4/src/hflow/__main__.py

@@ -0,0 +1,3 @@
+from hflow.cli import main
+
+raise SystemExit(main())

{hflow-0.2.2 → hflow-0.2.4}/src/hflow/_grouped_mcap_writer/_writer.py

@@ -236,6 +236,7 @@ class GroupedMcapWriter:
         self._flush()
 
     def register_schema(self, name: str, encoding: str, data: bytes) -> SchemaId:
+        """Register a schema and return its id for :meth:`register_channel`."""
         self._raise_if_not_active("register a schema")
         schema_id = SchemaId(len(self._schemas_by_id) + 1)
         schema = Schema(id=schema_id, data=data, encoding=encoding, name=name)
@@ -255,6 +256,11 @@ class GroupedMcapWriter:
         group: str,
         metadata: dict[str, str] | None = None,
     ) -> ChannelId:
+        """Register a topic on a named group and return its id for :meth:`write_message`.
+
+        ``schema_id`` must be a prior :meth:`register_schema` return value, or
+        ``NO_SCHEMA_ID`` for schemaless channels.
+        """
         self._raise_if_not_active("register a channel")
         # schema_id 0 is the MCAP spec's "no schema" sentinel.
         if schema_id != NO_SCHEMA_ID and schema_id not in self._schemas_by_id:
@@ -288,6 +294,11 @@ class GroupedMcapWriter:
         publish_time: int | None = None,
         sequence: int = 0,
     ) -> None:
+        """Write one message on a registered channel.
+
+        ``log_time`` and ``publish_time`` are nanoseconds since epoch; when
+        ``publish_time`` is omitted it defaults to ``log_time``.
+        """
         self._raise_if_not_active("write a message")
         group_name = self._group_name_by_channel_id.get(channel_id)
         if group_name is None:
@@ -318,6 +329,7 @@ class GroupedMcapWriter:
             self._finalize_group_chunk(group_name)
 
     def add_metadata(self, name: str, data: dict[str, str]) -> None:
+        """Append an MCAP Metadata record (e.g. episode or provenance stamps)."""
         self._raise_if_not_active("add metadata")
         self._flush()
         offset = self._stream.tell()
@@ -337,6 +349,7 @@ class GroupedMcapWriter:
         log_time: int = 0,
         create_time: int = 0,
     ) -> None:
+        """Append an MCAP Attachment record; times are nanoseconds since epoch."""
         self._raise_if_not_active("add an attachment")
         self._flush()
         offset = self._stream.tell()
@@ -363,6 +376,9 @@ class GroupedMcapWriter:
         self._flush()
 
     def finish(self) -> None:
+        """Finalize the MCAP file. Must be the last mutating call; safe to call
+        again (idempotent). Further writes raise :class:`RuntimeError`.
+        """
         if self._state is _WriterState.FINISHED:
             return
         self._raise_if_not_active("finish")

{hflow-0.2.2 → hflow-0.2.4}/src/hflow/_video_measurements/_camera_motion.py

@@ -7,6 +7,7 @@ from types import ModuleType
 
 import numpy as np
 
+from ._field_guards import require_float
 from ._raw_frames import LUMA_FRAME_FILTER_GRAPH, luma_frames
 from ._toolchain import VideoMeasurementToolchain
 
@@ -51,6 +52,8 @@ class CameraMotionSettings:
     horizontal_field_of_view_degrees: float = DEFAULT_HORIZONTAL_FIELD_OF_VIEW_DEGREES
 
     def __post_init__(self) -> None:
+        require_float(self.frames_per_second, "frames_per_second")
+        require_float(self.horizontal_field_of_view_degrees, "horizontal_field_of_view_degrees")
         if not math.isfinite(self.frames_per_second) or self.frames_per_second <= 0:
             raise ValueError(
                 f"frames_per_second must be finite and positive, got {self.frames_per_second}"

hflow-0.2.4/src/hflow/_video_measurements/_field_guards.py

@@ -0,0 +1,30 @@
+"""Shared numeric-field validation for the video-measurement settings dataclasses.
+
+Range checks alone (``0 <= x <= 100``) do not reject the wrong *type*: ``bool``
+subclasses ``int``, so ``True``/``False`` satisfy every numeric comparison and
+range test the settings below already run, and a ``str``/``None`` would raise
+a bare ``TypeError`` from the comparison itself instead of a clear message
+naming the field. This closes that hole the same way ``catalog.py`` already
+does for interval bounds and measurement values.
+
+These settings are caller-constructed configuration, not measurement-pipeline
+output, so unlike ``catalog.py``'s NumPy-scalar coercion, no NumPy handling is
+added here: a caller building a ``np.float64`` threshold can call ``.item()``
+itself, the same way any other non-native-Python value would need to.
+"""
+
+
+def require_int(value: object, name: str) -> None:
+    """Refuse anything but a plain ``int``, ``bool`` included."""
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ValueError(f"{name} must be an int, got {type(value).__name__}")
+
+
+def require_float(value: object, name: str) -> None:
+    """Refuse anything but a plain ``int`` or ``float``, ``bool`` included.
+
+    An ``int`` is accepted for a float-declared field: it is a perfectly good
+    float value (``0`` is a real, falsy value that must still pass).
+    """
+    if isinstance(value, bool) or not isinstance(value, int | float):
+        raise ValueError(f"{name} must be an int or float, got {type(value).__name__}")

{hflow-0.2.2 → hflow-0.2.4}/src/hflow/_video_measurements/_frame_statistics.py

@@ -14,6 +14,7 @@ from io import StringIO
 from pathlib import Path
 from typing import Protocol
 
+from ._field_guards import require_float, require_int
 from ._toolchain import VideoMeasurementToolchain
 
 FRAME_STATISTICS_DEFINITION_VERSION = "video-frame-statistics/v1"
@@ -54,6 +55,8 @@ class VideoTimeInterval:
     end_seconds: float
 
     def __post_init__(self) -> None:
+        require_float(self.start_seconds, "start_seconds")
+        require_float(self.end_seconds, "end_seconds")
         if not math.isfinite(self.start_seconds) or self.start_seconds < 0:
             raise ValueError(f"start_seconds must be finite and nonnegative: {self.start_seconds}")
         if not math.isfinite(self.end_seconds) or self.end_seconds < self.start_seconds:
@@ -74,6 +77,14 @@ class FrameStatisticsSettings:
     overexposed_average_luma_threshold: float = 235.0
 
     def __post_init__(self) -> None:
+        require_int(
+            self.black_frame_minimum_pixel_share_percent,
+            "black_frame_minimum_pixel_share_percent",
+        )
+        require_int(self.black_pixel_luma_threshold, "black_pixel_luma_threshold")
+        require_float(self.freeze_noise_tolerance_decibels, "freeze_noise_tolerance_decibels")
+        require_float(self.freeze_minimum_duration_seconds, "freeze_minimum_duration_seconds")
+        require_float(self.overexposed_average_luma_threshold, "overexposed_average_luma_threshold")
         if not 0 <= self.black_frame_minimum_pixel_share_percent <= 100:
             raise ValueError("black_frame_minimum_pixel_share_percent must be between 0 and 100")
         if not 0 <= self.black_pixel_luma_threshold <= 255:
@@ -371,7 +382,11 @@ class _FrameStatisticsAccumulator:
             overexposed_frame_percent=100.0 * self.overexposed_frame_count / frame_count,
             freeze_intervals=tuple(self.freeze_intervals),
             freeze_total_seconds=sum(
-                interval.end_seconds - interval.start_seconds for interval in self.freeze_intervals
+                (
+                    interval.end_seconds - interval.start_seconds
+                    for interval in self.freeze_intervals
+                ),
+                0.0,
             ),
             average_luma_mean=self.average_luma.mean(),
             average_luma_minimum=self.average_luma.minimum(),