hflow 0.2.0__tar.gz → 0.2.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hflow
-Version: 0.2.0
+Version: 0.2.2
 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
@@ -15,6 +15,8 @@ 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-Python: >=3.11
 Project-URL: Repository, https://github.com/Hebbian-Robotics/hflow
@@ -22,6 +24,8 @@ Project-URL: Documentation, https://github.com/Hebbian-Robotics/hflow/tree/main/
 Project-URL: Issues, https://github.com/Hebbian-Robotics/hflow/issues
 Provides-Extra: arrow
 Provides-Extra: bucket
+Provides-Extra: mediapipe
+Provides-Extra: motion
 Provides-Extra: openai
 Description-Content-Type: text/markdown
 
@@ -35,7 +39,7 @@ Description-Content-Type: text/markdown
 
 <h1 align="center">HFlow</h1>
 
-<p align="center"><strong>Open source SDK for building Physical AI data pipelines</strong></p>
+<p align="center"><strong>Open source SDK for scalable multimodal data pipelines in robotics and physical AI</strong></p>
 
 <p align="center">
   <a href="https://www.ycombinator.com/companies/hebbian-robotics">
@@ -49,25 +53,27 @@ Description-Content-Type: text/markdown
   </a>
 </p>
 
-HFlow provides reusable infrastructure for physical AI data pipelines. Add your
-existing Python transformations, quality checks, labels, and enrichments; HFlow
-handles the orchestration, storage, versioning, and curation around them.
+Hebbian Robotics (YC S26) is building HFlow, an open source SDK for scalable
+multimodal data pipelines in robotics and physical AI. It makes data tooling and
+practices typically developed inside large robotics teams accessible to teams of
+any size.
+
+We believe processing data is a major bottleneck in robotics. A corpus can combine
+video, state, actions, timestamps, and metadata from many recording systems. Teams
+often feel the problem first in quality control: determining whether cameras froze,
+streams drifted out of sync, required topics disappeared, or duplicate recordings
+entered the corpus. As the corpus grows, fragmented scripts make it difficult to
+know what ran, audit the results, or reproduce a dataset.
+
+Teams can start with HFlow's built-in checks, write new transformations, checks,
+labels, and enrichments, or connect processing code they already use. HFlow handles
+the orchestration, storage, versioning, and curation around those steps.
 
 HFlow stamps each processed episode with its provenance, renders the pipeline
 as a graph, and records metadata and quality evidence in a queryable catalog.
 You can trace how outputs were produced, monitor every stage, and
 investigate a corpus without loading the underlying recordings.
 
-The design is an open source implementation of Dyna Robotics'
-["Training Dyna-2 at million-hour scale, repeatably"](https://www.dyna.co/research/dyna-2-infrastructure) article,
-published August 2026. Dyna-2 was trained on more than one million hours of
-egocentric video data, and the post describes the reusable infrastructure that
-made processing and experimenting with that data repeatable. You can think of
-HFlow as an independent, open-source implementation of those public ideas,
-adapted for people who need the same foundation without Dyna's million-hour
-production stack. It is not Dyna's private source code or an undisclosed
-wire-compatible production system.
-
 MCAP is HFlow's v1 input and output boundary because it efficiently stores
 and serves synchronized video, state, action, and other time-series streams.
 That format requirement does not define where the data comes from: human-worn
@@ -75,13 +81,13 @@ cameras, teleoperated robots, autonomous policies, and other collection systems
 can all feed the pipeline once their data is represented as a supported MCAP
 episode.
 
-> **Status: pre-v1, with the core lifecycle working end to end.** HFlow is ready to try locally. See [what is implemented](https://github.com/Hebbian-Robotics/hflow/blob/main/docs/ARCHITECTURE.md#what-is-different-from-dyna) and [open issues](https://github.com/Hebbian-Robotics/hflow/issues) for current details and remaining work.
+> **Status: pre-v1, with the core lifecycle working end to end.** HFlow is ready to try locally. See [what is implemented](https://github.com/Hebbian-Robotics/hflow/blob/main/docs/ARCHITECTURE.md#implementation-status) and [open issues](https://github.com/Hebbian-Robotics/hflow/issues) for current details and remaining work.
 
-**Help advance open robotics and Physical AI.** [Contributors are welcome](https://github.com/Hebbian-Robotics/hflow/blob/main/CONTRIBUTING.md), and no robot hardware is required.
+**Help grow the open robotics community.** [Star the repository](https://github.com/Hebbian-Robotics/hflow), share it with your network, or [contribute](https://github.com/Hebbian-Robotics/hflow/blob/main/CONTRIBUTING.md). Our goal is an open source community where anyone can participate in building the future of robotics. No robot hardware is required to contribute.
 
 | | HFlow's boundary |
 | --- | --- |
-| **Input** | One multimodal episode per standard MCAP file |
+| **Input** | One multimodal episode per standard MCAP file (`hflow doctor` says whether yours qualifies) |
 | **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 |
@@ -89,7 +95,7 @@ episode.
 
 ## What you get
 
-Human and robot data move through the same four-stage lifecycle Dyna describes:
+Human and robot data move through a four-stage lifecycle:
 
 ```
 collection --> ingestion ---------------> curation ------> delivery
@@ -103,7 +109,7 @@ collection --> ingestion ---------------> curation ------> delivery
 </p>
 
 - **Your processing code stays yours.** Transformations, quality checks, labels, and enrichments are plain Python functions in your own environment. Existing code plugs in through small adapters instead of being rewritten for a proprietary framework.
-- **Episodes are MCAP**, the container that ROS 2 records natively and [Foxglove](https://foxglove.dev/)/[Rerun](https://rerun.io/) open directly, written with the two tuning ideas from Dyna's post: in-band H.264 with GOP length matched to how the data is read, and **topic-group chunking** (camera streams and state streams never share a chunk, so a training sample costs one read per group instead of one per topic).
+- **Episodes are MCAP**, the container that ROS 2 records natively and [Foxglove](https://foxglove.dev/)/[Rerun](https://rerun.io/) open directly, written with two tunings described in Dyna's article: in-band H.264 with GOP length matched to how the data is read, and **topic-group chunking** (camera streams and state streams never share a chunk, so a training sample costs one read per group instead of one per topic).
 - **Processed episodes carry their provenance.** The file itself records the schema, pipeline, and tool versions that produced it, plus its source URI when available. Catalog records connect measurements and outcomes to step versions, making it easier to trace a bad result back to its origin.
 - **The pipeline is visible as a graph.** HFlow renders Airflow DAGs so you can see how stages connect and monitor task status, logs, retries, and reruns.
 - **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.
@@ -121,6 +127,11 @@ same engine can be scaled as multiple isolated workspaces (for example, one
 per team or customer) behind an external control plane. That is the intended
 path to a future hosted version, but the hosted control plane is not
 implemented in this repository and is not a pre-v1 release commitment.
+[docs/HOSTING.md](https://github.com/Hebbian-Robotics/hflow/blob/main/docs/HOSTING.md)
+documents the data-plane contract that makes such a control plane an
+addition rather than a rearchitecture: the workspace unit, the seams a
+service drives (manifests, remote runtime addressing, credential injection),
+the trust model, and the current limits.
 
 ## Community and hosted interest
 
@@ -149,7 +160,7 @@ To run the repository's bundled quickstart:
 ```bash
 git clone https://github.com/Hebbian-Robotics/hflow.git
 cd hflow
-uv sync --locked --all-extras
+uv sync --locked
 uv run python examples/quickstart.py
 ```
 
@@ -176,24 +187,28 @@ and other physical-AI recordings.
 
 ```python
 import hflow
+from hflow.checks import camera_frame_stats
 from your_existing_qc import check_joint_smoothness  # use your existing checks
 
-app = hflow.App("kitchen-pipeline", data_root="./data")
+app = hflow.App("kitchen-pipeline")  # data root: $HFLOW_DATA_ROOT, hflow.toml, else ./data
 
 
-@app.check()
+@app.check(version="1")
 def joint_smoothness(ep: hflow.Episode) -> hflow.CheckResult:
     joints = ep.channel("/joint_states").to_numpy()  # our line: extract
     result = check_joint_smoothness(joints, rate_hz=100)  # your line: unchanged
     return hflow.CheckResult(measurements=result)  # our line: record
 
 
-@app.check(critical=True)
+@app.check(version="1", critical=True)
 def camera_blackout(ep: hflow.Episode) -> hflow.CheckResult:
-    stats = hflow.ffmpeg.frame_stats(ep.video("wrist_cam"))  # one decode pass
+    camera_topic = next(topic for topic in ep.cameras if "wrist_cam" in topic)
+    evidence = camera_frame_stats(ep, cameras=[camera_topic])
+    black_frame_percent = evidence.measurements[f"{camera_topic}/black_frame_pct"]
+    assert isinstance(black_frame_percent, float)
     return hflow.CheckResult(
-        measurements={"black_pct": stats.black_frame_pct},
-        verdict=stats.black_frame_pct < 0.5,  # your threshold
+        measurements={"black_pct": black_frame_percent},
+        verdict=black_frame_percent < 50.0,  # percent; your threshold
     )
 
 
@@ -202,6 +217,10 @@ if __name__ == "__main__":
     # Or call app.run() here to start the Compose runtime, then use `hflow ingest`.
 ```
 
+Every check, enrichment, and derived channel declares a version. HFlow stores
+that value exactly as written: keep it for behavior-preserving refactors, and
+bump it when old and new results should no longer be treated as comparable.
+
 Curation comes afterwards, via `hflow.curate(data_root / "catalog", sql, output="manifest.parquet")`
 or `hflow curate "<sql>"` on the command line, either way reporting coverage
 denominators alongside the manifest:
@@ -209,7 +228,7 @@ denominators alongside the manifest:
 ```sql
 SELECT episode_id, uri FROM episodes
 WHERE task = 'fold_napkin'
-  AND status != 'quarantined'
+  AND status = 'ok'
   AND black_pct < 1.0                      -- percent, user-owned threshold
   AND pipeline_version = 'a41c9f27b3d8'    -- pin one reprocessing generation
 ```
@@ -220,7 +239,6 @@ WHERE task = 'fold_napkin'
 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.
-5. **Transparent provenance.** The docs mark every design element as *Dyna says* (from the blog) or *HFlow chooses* (our engineering judgment, with the evidence behind it).
 
 ## Non-goals
 
@@ -243,28 +261,25 @@ WHERE task = 'fold_napkin'
 - [Frequently asked questions](https://github.com/Hebbian-Robotics/hflow/blob/main/docs/FAQ.md): formats, infrastructure, scale, project scope, and current release status
 - [How HFlow fits the robotics data stack](https://github.com/Hebbian-Robotics/hflow/blob/main/docs/INTEGRATIONS.md): MCAP, Airflow, Foxglove, Rerun, DuckDB, object storage, and training formats
 - [Runnable examples](https://github.com/Hebbian-Robotics/hflow/blob/main/examples/README.md): exact commands, prerequisites, expected output, and links to the relevant guides
-- [Architecture and differences from Dyna](https://github.com/Hebbian-Robotics/hflow/blob/main/docs/ARCHITECTURE.md): the implemented, simplified, deferred, and out-of-scope matrix
+- [Architecture and implementation status](https://github.com/Hebbian-Robotics/hflow/blob/main/docs/ARCHITECTURE.md): the implemented, simplified, deferred, and out-of-scope matrix
 - [Call OpenAI vision from a step](https://github.com/Hebbian-Robotics/hflow/blob/main/docs/how-to/call-openai-vision.md): a focused guide linked to a complete executable pipeline
 - [Contributing](https://github.com/Hebbian-Robotics/hflow/blob/main/CONTRIBUTING.md): development setup, validation commands, test gates, and pull-request expectations
 - [Security policy](https://github.com/Hebbian-Robotics/hflow/blob/main/SECURITY.md): supported versions and private vulnerability reporting
 
 ## References
 
-Primary source:
-
-- Dyna Robotics, [Training Dyna-2 at million-hour scale, repeatably](https://www.dyna.co/research/dyna-2-infrastructure) (Aug 2026)
-
-Formats and tooling this project builds on:
 
+- Dyna Robotics, [Training Dyna-2 at million-hour scale, repeatably](https://www.dyna.co/research/dyna-2-infrastructure)
 - [MCAP specification](https://mcap.dev/spec) and [Python libraries](https://mcap.dev/docs/python/) (Foxglove)
 - [foxglove.CompressedVideo schema](https://docs.foxglove.dev/docs/sdk/schemas/compressed-video): in-band H.264/H.265/VP9/AV1 video in MCAP
-- [Apache Airflow 3](https://airflow.apache.org/): ingestion DAG orchestration
-- [DuckDB](https://duckdb.org/): curation queries over the Parquet catalog
-- [Foxglove](https://foxglove.dev/) and [Rerun](https://rerun.io/): episode inspection
-- [FFmpeg](https://ffmpeg.org/): video processing and the deterministic frame instrument
-
-Parts of the durability and measurement design draw on production experience from [Pareto](https://github.com/Hebbian-Robotics/pareto), Hebbian Robotics' robotics data curation platform.
+- [Apache Airflow](https://airflow.apache.org/)
+- [DuckDB](https://duckdb.org/)
+- [Foxglove](https://foxglove.dev/) and [Rerun](https://rerun.io/)
+- [FFmpeg](https://ffmpeg.org/)
+- [Pareto](https://github.com/Hebbian-Robotics/pareto), Hebbian Robotics' robotics data curation platform.
 
 ## License
 
-[Apache-2.0](https://github.com/Hebbian-Robotics/hflow/blob/main/LICENSE)
+[Apache-2.0](https://github.com/Hebbian-Robotics/hflow/blob/main/LICENSE).
+The license covers the code, not the names: see the
+[trademark policy](https://github.com/Hebbian-Robotics/hflow/blob/main/TRADEMARKS.md).

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

@@ -8,7 +8,7 @@
 
 <h1 align="center">HFlow</h1>
 
-<p align="center"><strong>Open source SDK for building Physical AI data pipelines</strong></p>
+<p align="center"><strong>Open source SDK for scalable multimodal data pipelines in robotics and physical AI</strong></p>
 
 <p align="center">
   <a href="https://www.ycombinator.com/companies/hebbian-robotics">
@@ -22,25 +22,27 @@
   </a>
 </p>
 
-HFlow provides reusable infrastructure for physical AI data pipelines. Add your
-existing Python transformations, quality checks, labels, and enrichments; HFlow
-handles the orchestration, storage, versioning, and curation around them.
+Hebbian Robotics (YC S26) is building HFlow, an open source SDK for scalable
+multimodal data pipelines in robotics and physical AI. It makes data tooling and
+practices typically developed inside large robotics teams accessible to teams of
+any size.
+
+We believe processing data is a major bottleneck in robotics. A corpus can combine
+video, state, actions, timestamps, and metadata from many recording systems. Teams
+often feel the problem first in quality control: determining whether cameras froze,
+streams drifted out of sync, required topics disappeared, or duplicate recordings
+entered the corpus. As the corpus grows, fragmented scripts make it difficult to
+know what ran, audit the results, or reproduce a dataset.
+
+Teams can start with HFlow's built-in checks, write new transformations, checks,
+labels, and enrichments, or connect processing code they already use. HFlow handles
+the orchestration, storage, versioning, and curation around those steps.
 
 HFlow stamps each processed episode with its provenance, renders the pipeline
 as a graph, and records metadata and quality evidence in a queryable catalog.
 You can trace how outputs were produced, monitor every stage, and
 investigate a corpus without loading the underlying recordings.
 
-The design is an open source implementation of Dyna Robotics'
-["Training Dyna-2 at million-hour scale, repeatably"](https://www.dyna.co/research/dyna-2-infrastructure) article,
-published August 2026. Dyna-2 was trained on more than one million hours of
-egocentric video data, and the post describes the reusable infrastructure that
-made processing and experimenting with that data repeatable. You can think of
-HFlow as an independent, open-source implementation of those public ideas,
-adapted for people who need the same foundation without Dyna's million-hour
-production stack. It is not Dyna's private source code or an undisclosed
-wire-compatible production system.
-
 MCAP is HFlow's v1 input and output boundary because it efficiently stores
 and serves synchronized video, state, action, and other time-series streams.
 That format requirement does not define where the data comes from: human-worn
@@ -48,13 +50,13 @@ cameras, teleoperated robots, autonomous policies, and other collection systems
 can all feed the pipeline once their data is represented as a supported MCAP
 episode.
 
-> **Status: pre-v1, with the core lifecycle working end to end.** HFlow is ready to try locally. See [what is implemented](https://github.com/Hebbian-Robotics/hflow/blob/main/docs/ARCHITECTURE.md#what-is-different-from-dyna) and [open issues](https://github.com/Hebbian-Robotics/hflow/issues) for current details and remaining work.
+> **Status: pre-v1, with the core lifecycle working end to end.** HFlow is ready to try locally. See [what is implemented](https://github.com/Hebbian-Robotics/hflow/blob/main/docs/ARCHITECTURE.md#implementation-status) and [open issues](https://github.com/Hebbian-Robotics/hflow/issues) for current details and remaining work.
 
-**Help advance open robotics and Physical AI.** [Contributors are welcome](https://github.com/Hebbian-Robotics/hflow/blob/main/CONTRIBUTING.md), and no robot hardware is required.
+**Help grow the open robotics community.** [Star the repository](https://github.com/Hebbian-Robotics/hflow), share it with your network, or [contribute](https://github.com/Hebbian-Robotics/hflow/blob/main/CONTRIBUTING.md). Our goal is an open source community where anyone can participate in building the future of robotics. No robot hardware is required to contribute.
 
 | | HFlow's boundary |
 | --- | --- |
-| **Input** | One multimodal episode per standard MCAP file |
+| **Input** | One multimodal episode per standard MCAP file (`hflow doctor` says whether yours qualifies) |
 | **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 |
@@ -62,7 +64,7 @@ episode.
 
 ## What you get
 
-Human and robot data move through the same four-stage lifecycle Dyna describes:
+Human and robot data move through a four-stage lifecycle:
 
 ```
 collection --> ingestion ---------------> curation ------> delivery
@@ -76,7 +78,7 @@ collection --> ingestion ---------------> curation ------> delivery
 </p>
 
 - **Your processing code stays yours.** Transformations, quality checks, labels, and enrichments are plain Python functions in your own environment. Existing code plugs in through small adapters instead of being rewritten for a proprietary framework.
-- **Episodes are MCAP**, the container that ROS 2 records natively and [Foxglove](https://foxglove.dev/)/[Rerun](https://rerun.io/) open directly, written with the two tuning ideas from Dyna's post: in-band H.264 with GOP length matched to how the data is read, and **topic-group chunking** (camera streams and state streams never share a chunk, so a training sample costs one read per group instead of one per topic).
+- **Episodes are MCAP**, the container that ROS 2 records natively and [Foxglove](https://foxglove.dev/)/[Rerun](https://rerun.io/) open directly, written with two tunings described in Dyna's article: in-band H.264 with GOP length matched to how the data is read, and **topic-group chunking** (camera streams and state streams never share a chunk, so a training sample costs one read per group instead of one per topic).
 - **Processed episodes carry their provenance.** The file itself records the schema, pipeline, and tool versions that produced it, plus its source URI when available. Catalog records connect measurements and outcomes to step versions, making it easier to trace a bad result back to its origin.
 - **The pipeline is visible as a graph.** HFlow renders Airflow DAGs so you can see how stages connect and monitor task status, logs, retries, and reruns.
 - **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.
@@ -94,6 +96,11 @@ same engine can be scaled as multiple isolated workspaces (for example, one
 per team or customer) behind an external control plane. That is the intended
 path to a future hosted version, but the hosted control plane is not
 implemented in this repository and is not a pre-v1 release commitment.
+[docs/HOSTING.md](https://github.com/Hebbian-Robotics/hflow/blob/main/docs/HOSTING.md)
+documents the data-plane contract that makes such a control plane an
+addition rather than a rearchitecture: the workspace unit, the seams a
+service drives (manifests, remote runtime addressing, credential injection),
+the trust model, and the current limits.
 
 ## Community and hosted interest
 
@@ -122,7 +129,7 @@ To run the repository's bundled quickstart:
 ```bash
 git clone https://github.com/Hebbian-Robotics/hflow.git
 cd hflow
-uv sync --locked --all-extras
+uv sync --locked
 uv run python examples/quickstart.py
 ```
 
@@ -149,24 +156,28 @@ and other physical-AI recordings.
 
 ```python
 import hflow
+from hflow.checks import camera_frame_stats
 from your_existing_qc import check_joint_smoothness  # use your existing checks
 
-app = hflow.App("kitchen-pipeline", data_root="./data")
+app = hflow.App("kitchen-pipeline")  # data root: $HFLOW_DATA_ROOT, hflow.toml, else ./data
 
 
-@app.check()
+@app.check(version="1")
 def joint_smoothness(ep: hflow.Episode) -> hflow.CheckResult:
     joints = ep.channel("/joint_states").to_numpy()  # our line: extract
     result = check_joint_smoothness(joints, rate_hz=100)  # your line: unchanged
     return hflow.CheckResult(measurements=result)  # our line: record
 
 
-@app.check(critical=True)
+@app.check(version="1", critical=True)
 def camera_blackout(ep: hflow.Episode) -> hflow.CheckResult:
-    stats = hflow.ffmpeg.frame_stats(ep.video("wrist_cam"))  # one decode pass
+    camera_topic = next(topic for topic in ep.cameras if "wrist_cam" in topic)
+    evidence = camera_frame_stats(ep, cameras=[camera_topic])
+    black_frame_percent = evidence.measurements[f"{camera_topic}/black_frame_pct"]
+    assert isinstance(black_frame_percent, float)
     return hflow.CheckResult(
-        measurements={"black_pct": stats.black_frame_pct},
-        verdict=stats.black_frame_pct < 0.5,  # your threshold
+        measurements={"black_pct": black_frame_percent},
+        verdict=black_frame_percent < 50.0,  # percent; your threshold
     )
 
 
@@ -175,6 +186,10 @@ if __name__ == "__main__":
     # Or call app.run() here to start the Compose runtime, then use `hflow ingest`.
 ```
 
+Every check, enrichment, and derived channel declares a version. HFlow stores
+that value exactly as written: keep it for behavior-preserving refactors, and
+bump it when old and new results should no longer be treated as comparable.
+
 Curation comes afterwards, via `hflow.curate(data_root / "catalog", sql, output="manifest.parquet")`
 or `hflow curate "<sql>"` on the command line, either way reporting coverage
 denominators alongside the manifest:
@@ -182,7 +197,7 @@ denominators alongside the manifest:
 ```sql
 SELECT episode_id, uri FROM episodes
 WHERE task = 'fold_napkin'
-  AND status != 'quarantined'
+  AND status = 'ok'
   AND black_pct < 1.0                      -- percent, user-owned threshold
   AND pipeline_version = 'a41c9f27b3d8'    -- pin one reprocessing generation
 ```
@@ -193,7 +208,6 @@ WHERE task = 'fold_napkin'
 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.
-5. **Transparent provenance.** The docs mark every design element as *Dyna says* (from the blog) or *HFlow chooses* (our engineering judgment, with the evidence behind it).
 
 ## Non-goals
 
@@ -216,28 +230,25 @@ WHERE task = 'fold_napkin'
 - [Frequently asked questions](https://github.com/Hebbian-Robotics/hflow/blob/main/docs/FAQ.md): formats, infrastructure, scale, project scope, and current release status
 - [How HFlow fits the robotics data stack](https://github.com/Hebbian-Robotics/hflow/blob/main/docs/INTEGRATIONS.md): MCAP, Airflow, Foxglove, Rerun, DuckDB, object storage, and training formats
 - [Runnable examples](https://github.com/Hebbian-Robotics/hflow/blob/main/examples/README.md): exact commands, prerequisites, expected output, and links to the relevant guides
-- [Architecture and differences from Dyna](https://github.com/Hebbian-Robotics/hflow/blob/main/docs/ARCHITECTURE.md): the implemented, simplified, deferred, and out-of-scope matrix
+- [Architecture and implementation status](https://github.com/Hebbian-Robotics/hflow/blob/main/docs/ARCHITECTURE.md): the implemented, simplified, deferred, and out-of-scope matrix
 - [Call OpenAI vision from a step](https://github.com/Hebbian-Robotics/hflow/blob/main/docs/how-to/call-openai-vision.md): a focused guide linked to a complete executable pipeline
 - [Contributing](https://github.com/Hebbian-Robotics/hflow/blob/main/CONTRIBUTING.md): development setup, validation commands, test gates, and pull-request expectations
 - [Security policy](https://github.com/Hebbian-Robotics/hflow/blob/main/SECURITY.md): supported versions and private vulnerability reporting
 
 ## References
 
-Primary source:
-
-- Dyna Robotics, [Training Dyna-2 at million-hour scale, repeatably](https://www.dyna.co/research/dyna-2-infrastructure) (Aug 2026)
-
-Formats and tooling this project builds on:
 
+- Dyna Robotics, [Training Dyna-2 at million-hour scale, repeatably](https://www.dyna.co/research/dyna-2-infrastructure)
 - [MCAP specification](https://mcap.dev/spec) and [Python libraries](https://mcap.dev/docs/python/) (Foxglove)
 - [foxglove.CompressedVideo schema](https://docs.foxglove.dev/docs/sdk/schemas/compressed-video): in-band H.264/H.265/VP9/AV1 video in MCAP
-- [Apache Airflow 3](https://airflow.apache.org/): ingestion DAG orchestration
-- [DuckDB](https://duckdb.org/): curation queries over the Parquet catalog
-- [Foxglove](https://foxglove.dev/) and [Rerun](https://rerun.io/): episode inspection
-- [FFmpeg](https://ffmpeg.org/): video processing and the deterministic frame instrument
-
-Parts of the durability and measurement design draw on production experience from [Pareto](https://github.com/Hebbian-Robotics/pareto), Hebbian Robotics' robotics data curation platform.
+- [Apache Airflow](https://airflow.apache.org/)
+- [DuckDB](https://duckdb.org/)
+- [Foxglove](https://foxglove.dev/) and [Rerun](https://rerun.io/)
+- [FFmpeg](https://ffmpeg.org/)
+- [Pareto](https://github.com/Hebbian-Robotics/pareto), Hebbian Robotics' robotics data curation platform.
 
 ## License
 
-[Apache-2.0](https://github.com/Hebbian-Robotics/hflow/blob/main/LICENSE)
+[Apache-2.0](https://github.com/Hebbian-Robotics/hflow/blob/main/LICENSE).
+The license covers the code, not the names: see the
+[trademark policy](https://github.com/Hebbian-Robotics/hflow/blob/main/TRADEMARKS.md).

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

@@ -1,6 +1,6 @@
 [project]
 name = "hflow"
-version = "0.2.0"
+version = "0.2.2"
 description = "Open source SDK for building Physical AI data pipelines"
 readme = "README.md"
 license = "Apache-2.0"
@@ -37,6 +37,8 @@ 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"]
 
 [project.urls]
@@ -49,7 +51,11 @@ hflow = "hflow.cli:main"
 
 [dependency-groups]
 dev = [
+    "hflow-server",
+    "httpx2>=2.10",
     "obstore>=0.10.0",
+    "opencv-python-headless>=4.10",
+    "pyarrow>=25.0.1",
     "pytest>=9.1.1",
     "pyyaml>=6.0.3",
     "ruff>=0.16.2",
@@ -63,8 +69,17 @@ build-backend = "uv_build"
 [tool.uv]
 exclude-newer = "5 days"
 
+[tool.uv.workspace]
+members = ["packages/*"]
+
+[tool.uv.sources.hflow-server]
+workspace = true
+
 [tool.pytest.ini_options]
-testpaths = ["tests"]
+testpaths = [
+    "tests",
+    "packages/hflow-server/tests",
+]
 
 [tool.ruff]
 line-length = 100

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

@@ -1,6 +1,6 @@
 [project]
 name = "hflow"
-version = "0.2.0"
+version = "0.2.2"
 description = "Open source SDK for building Physical AI data pipelines"
 readme = "README.md"
 license = "Apache-2.0"
@@ -36,6 +36,19 @@ arrow = ["pyarrow>=25.0.1"]
 # object_store crate as a single dependency-free wheel; local-path roots
 # never import it.
 bucket = ["obstore>=0.10.0"]
+# 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"]
+# 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"]
 
 [project.urls]
@@ -48,7 +61,15 @@ hflow = "hflow.cli:main"
 
 [dependency-groups]
 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
+    # 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",
+    "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",
@@ -65,8 +86,14 @@ build-backend = "uv_build"
 # trusted first-party packages.
 exclude-newer = "5 days"
 
+[tool.uv.workspace]
+members = ["packages/*"]
+
+[tool.uv.sources]
+hflow-server = { workspace = true }
+
 [tool.pytest.ini_options]
-testpaths = ["tests"]
+testpaths = ["tests", "packages/hflow-server/tests"]
 
 [tool.ruff]
 line-length = 100