dataeval-flow 0.2.0__tar.gz → 0.2.2__tar.gz

dataeval_flow-0.2.0/README.md → dataeval_flow-0.2.2/PKG-INFO

@@ -1,3 +1,61 @@
+Metadata-Version: 2.5
+Name: dataeval-flow
+Version: 0.2.2
+Summary: DataEval Workflows container for data evaluation
+Project-URL: Homepage, https://github.com/aria-ml/dataeval-flow
+Project-URL: Documentation, https://dataeval-flow.readthedocs.io/
+Project-URL: Repository, https://github.com/aria-ml/dataeval-flow
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: dataeval>=1.1.0
+Requires-Dist: datamaite[ic,od]==0.4.1
+Requires-Dist: numpy>=1.24.2
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: app
+Requires-Dist: textual>=3.0; extra == 'app'
+Provides-Extra: cpu
+Requires-Dist: torch>=2.2.0; extra == 'cpu'
+Requires-Dist: torchvision>=0.17.0; extra == 'cpu'
+Provides-Extra: cu126
+Requires-Dist: torch>=2.2.0; extra == 'cu126'
+Requires-Dist: torchvision>=0.17.0; extra == 'cu126'
+Provides-Extra: cu130
+Requires-Dist: torch>=2.2.0; extra == 'cu130'
+Requires-Dist: torchvision>=0.17.0; extra == 'cu130'
+Provides-Extra: onnx
+Requires-Dist: onnx>=1.15; extra == 'onnx'
+Requires-Dist: onnxruntime<1.24,>=1.20; (python_version == '3.10') and extra == 'onnx'
+Requires-Dist: onnxruntime>=1.20; (python_version >= '3.11') and extra == 'onnx'
+Provides-Extra: onnx-cu126
+Requires-Dist: onnx>=1.15; extra == 'onnx-cu126'
+Requires-Dist: onnxruntime-gpu<1.24,>=1.20; (python_version == '3.10' and extra != 'onnx-cu130') and extra == 'onnx-cu126'
+Requires-Dist: onnxruntime-gpu<1.27,>=1.20; (python_version >= '3.11' and extra != 'onnx-cu130') and extra == 'onnx-cu126'
+Requires-Dist: onnxruntime-gpu<1.27,>=1.24; (python_version >= '3.14' and extra != 'onnx-cu130') and extra == 'onnx-cu126'
+Provides-Extra: onnx-cu130
+Requires-Dist: onnx>=1.15; extra == 'onnx-cu130'
+Requires-Dist: onnxruntime-gpu>=1.27; (python_version >= '3.11' and extra != 'onnx-cu126') and extra == 'onnx-cu130'
+Requires-Dist: onnxruntime>=1.20; (python_version == '3.10' and extra != 'onnx-cu126') and extra == 'onnx-cu130'
+Provides-Extra: ontology
+Requires-Dist: dataeval[ontology]==1.1.0; extra == 'ontology'
+Provides-Extra: opencv
+Requires-Dist: opencv-python-headless>=4.8.0; extra == 'opencv'
+Provides-Extra: opencv-fips
+Requires-Dist: opencv-python-headless<4.13.0,>=4.8.0; extra == 'opencv-fips'
+Description-Content-Type: text/markdown
+
 <!-- markdownlint-disable MD041 -->
 ![DataEval Flow](docs/source/_static/images/DataEvalFlow_Logo.png)
 
@@ -66,8 +124,8 @@ The guidance below applies to both the container and the Python-library forms.
 
 DataEval Flow is developed and tested on Linux (Ubuntu 22.04 and 24.04, including
 WSL2). The Python package supports **Python 3.10–3.14**; the CI test matrix runs
-all five. The container images are built on Ubuntu 22.04 (cu118) and
-Ubuntu 24.04 (cpu, cu128). macOS and Windows are supported only through Docker or
+all five. The container images are all built on Ubuntu 24.04 (cpu, cu126, cu130).
+macOS and Windows are supported only through Docker or
 WSL2 and are not part of the CI test matrix — if you hit an issue on those hosts,
 the OS/hardware may be the root cause.
 
@@ -106,17 +164,17 @@ at least the minimum CPU/memory above; size memory to your largest dataset.
 ## Quick Start
 
 ```bash
-# 1. Build CUDA 11.8 container
-docker build -f docker/Dockerfile.cu118 -t dataeval:cu118 .
+# 1. Build CUDA 12.6 container
+docker build -f docker/Dockerfile.cu126 -t dataeval:cu126 .
 
 # 2. Show help
-docker run dataeval:cu118
+docker run dataeval:cu126
 
 # 3. Run with data and output
 docker run --gpus all \
   --mount type=bind,source=/path/to/data,target=/dataeval,readonly \
   --mount type=bind,source=/path/to/output,target=/output \
-  dataeval:cu118
+  dataeval:cu126
 ```
 
 ## Pulling pre-built images
@@ -128,13 +186,13 @@ if you don't need to modify the code.
 **Rolling channel** — tracks the latest commit on `main`. The tag is overwritten on every merge.
 
 ```bash
-docker pull harbor.jatic.net/aria/dataeval:cu118   # cpu / cu118 / cu128
+docker pull harbor.jatic.net/aria/dataeval:cu126   # cpu / cu126 / cu130
 ```
 
 **Pinned release channel** — immutable, version-tagged images cut from `v*` git tags. Use these for reproducible workloads.
 
 ```bash
-docker pull harbor.jatic.net/aria/dataeval:0.1.0-cu118
+docker pull harbor.jatic.net/aria/dataeval:0.2.1-cu126
 ```
 
 **Verifying the signature** — every published image is signed with
@@ -142,11 +200,11 @@ docker pull harbor.jatic.net/aria/dataeval:0.1.0-cu118
 [docker/cosign.pub](docker/cosign.pub).
 
 ```bash
-cosign verify --key docker/cosign.pub harbor.jatic.net/aria/dataeval:cu118
+cosign verify --key docker/cosign.pub harbor.jatic.net/aria/dataeval:cu126
 ```
 
-Then drop the `dataeval:cu118` reference in the Quick Start `docker run`
-commands above with the fully-qualified `harbor.jatic.net/aria/dataeval:cu118`
+Then drop the `dataeval:cu126` reference in the Quick Start `docker run`
+commands above with the fully-qualified `harbor.jatic.net/aria/dataeval:cu126`
 (or pinned version) and skip step 1.
 
 > **Note on feature branches.** Containers are only built and published from
@@ -157,17 +215,23 @@ commands above with the fully-qualified `harbor.jatic.net/aria/dataeval:cu118`
 
 ## Requirements
 
-| Requirement   | Version               |
-| ------------- | --------------------- |
-| Docker        | >= 20.10              |
-| NVIDIA GPU    | Any (for GPU mode)    |
-| NVIDIA Driver | >= 520 (for GPU mode) |
-| CUDA          | 11.8.0 (for GPU mode) |
+| Requirement   | Version                                                        |
+| ------------- | -------------------------------------------------------------- |
+| Docker        | >= 20.10                                                       |
+| NVIDIA GPU    | Any (for GPU mode)                                             |
+| NVIDIA Driver | >= 525 for the `cu126` image; >= 580 for `cu130` (GPU mode)    |
+| CUDA          | 12.6 (`cu126`) or 13.0 (`cu130`) — bundled in the image        |
+
+The CUDA runtime libraries ship inside the image via PyTorch and `onnxruntime-gpu`, so
+the host needs only the NVIDIA driver and the NVIDIA Container Toolkit — no host CUDA
+install. The driver floors above are the CUDA major versions' minimums: any driver from
+the 525 series up runs a CUDA 12.x image under minor-version compatibility, and CUDA 13.0
+requires a 580-series or newer driver.
 
 ### Verify GPU Access
 
 ```bash
-docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi
+docker run --rm --gpus all nvidia/cuda:12.6.3-base-ubuntu24.04 nvidia-smi
 ```
 
 ## Volume Mounts
@@ -193,7 +257,7 @@ docker run --gpus all \
   --user "$(id -u):$(id -g)" \
   --mount type=bind,source=/path/to/data,target=/dataeval,readonly \
   --mount type=bind,source=/path/to/output,target=/output \
-  dataeval:cu118
+  dataeval:cu126
 ```
 
 #### Option 2: Open directory permissions
@@ -215,7 +279,7 @@ docker run --gpus all \
   -e DATAEVAL_DATA=/data \
   --mount type=bind,source=/path/to/data,target=/data,readonly \
   --mount type=bind,source=/path/to/output,target=/output \
-  dataeval:cu118
+  dataeval:cu126
 ```
 
 ## Environment Variables
@@ -231,7 +295,10 @@ precedence over them (see [Input Precedence](#input-precedence) below).
 
 No secret mounts or credentials are required — DataEval Flow uses no API keys,
 tokens, or passwords. (`DATAEVAL_FLOW_VERSION` and `DATAEVAL_NOX_UV_EXTRAS_OVERRIDE`
-are build-time only and are not read at run time.)
+are build-time only and are not read at run time. `UV_EXTRAS_OVERRIDE` and
+`CONTAINER_MODE` are baked into the image by the build and read at run time by the
+entrypoint, purely to label the help text and decide whether to run the GPU check —
+neither is meant to be set by the caller.)
 
 ## Input Precedence
 
@@ -253,7 +320,7 @@ options, precedence, and examples — via its help command, which is also the
 default when the container runs with no pipeline arguments:
 
 ```bash
-docker run dataeval:cu118 --help
+docker run dataeval:cu126 --help
 ```
 
 The library form exposes the same options via `python -m dataeval_flow --help`.
@@ -273,25 +340,33 @@ To specify a config path explicitly:
 docker run --gpus all \
   --mount type=bind,source=/path/to/data,target=/dataeval,readonly \
   --mount type=bind,source=/path/to/output,target=/output \
-  dataeval:cu118 --config config/
+  dataeval:cu126 --config config/
 
 # Single config file
 docker run --gpus all \
   --mount type=bind,source=/path/to/data,target=/dataeval,readonly \
   --mount type=bind,source=/path/to/output,target=/output \
-  dataeval:cu118 --config params.yaml
+  dataeval:cu126 --config params.yaml
 ```
 
 Dataset and model paths in config files are resolved relative to the data root (`/dataeval` by default).
 
 ## Dataset Formats
 
-Currently supported dataset structures:
+A `datasets` entry selects its loader with `format`:
 
-| Format          | Structure                                          | Example         |
-| --------------- | -------------------------------------------------- | --------------- |
-| **Dataset**     | Single split, used directly                        | `cifar10_test/` |
-| **DatasetDict** | Multiple splits (dict), configured via config YAML | `cifar10_full/` |
+| `format`       | Structure                                                     | Split selection                    |
+| -------------- | ------------------------------------------------------------- | ---------------------------------- |
+| `huggingface`  | HuggingFace arrow dataset or dataset dict                     | `split:` (omit for a single split) |
+| `image_folder` | Directory of images, optionally one subdirectory per class    | n/a                                |
+| `coco`         | COCO images plus a JSON annotation file                       | `annotations_file:` + `images_dir:` |
+| `yolo`         | Ultralytics root — `data.yaml` plus image/label trees         | `split:` (omit to load every split) |
+
+Both single-split datasets and multi-split dataset dicts are supported. In-memory MAITE
+and TorchVision datasets are also accepted programmatically via `DatasetProtocolConfig`,
+which is not serializable and so cannot be named in a config file. See the
+[Run workflows in containers](https://dataeval-flow.readthedocs.io/en/latest/how_to/containerized_workflows.html)
+guide for the full field list of each format.
 
 ## CPU Fallback
 
@@ -308,13 +383,53 @@ docker run \
 
 ## CLI Modes
 
-DataEval Flow has three modes:
+DataEval Flow has four modes:
+
+| Command                   | Purpose                                                             |
+| ------------------------- | ------------------------------------------------------------------- |
+| `dataeval-flow [opts]`    | Headless execution — for automation and CI/CD pipelines             |
+| `dataeval-flow app`       | Interactive TUI dashboard — configure, execute, and view results    |
+| `dataeval-flow config`    | Simple CLI config builder — create/edit configs without the TUI     |
+| `dataeval-flow encoding`  | Write the metadata encoding descriptor a result was computed under  |
+| `dataeval-flow workflows` | List the available workflow types, or print one's parameter schema  |
+
+`dataeval-flow --version` reports the installed build — useful for pinning down
+which image produced a result.
+
+### Headless execution
+
+```bash
+# Every enabled task in the config
+dataeval-flow --config params.yaml --data . --output ./results
+
+# One task by name, whether or not the config marks it enabled
+dataeval-flow --config params.yaml --task clean_my_data
+
+# Several, in the order given
+dataeval-flow --config params.yaml --task clean_my_data --task analyze_my_data
+
+# Stop the pipeline when a finding breaches its health threshold
+dataeval-flow --config params.yaml --output ./results --fail-on-warning
+```
+
+**Exit codes:** `0` when every task succeeded, `1` when any task failed. Health
+warnings are reported but are not fatal unless you pass `--fail-on-warning`, which
+turns them into an exit code of `1` as well. Every run's `result.json` carries a
+`health` block per task (`status`, `warnings`, `findings`) so a pipeline can gate
+on findings without parsing the text report.
 
-| Command                | Purpose                                                          |
-| ---------------------- | ---------------------------------------------------------------- |
-| `dataeval-flow [opts]` | Headless execution — for automation and CI/CD pipelines          |
-| `dataeval-flow app`    | Interactive TUI dashboard — configure, execute, and view results |
-| `dataeval-flow config` | Simple CLI config builder — create/edit configs without the TUI  |
+### Workflow Discovery (`workflows`)
+
+For images that ship without the TUI extra:
+
+```bash
+# What can this build run?
+dataeval-flow workflows
+dataeval-flow workflows --json
+
+# What does a given workflow type accept?
+dataeval-flow workflows data-cleaning
+```
 
 ### Interactive TUI (`app`)
 
@@ -350,12 +465,35 @@ python -m dataeval_flow config --config /path/to/params.yaml
 
 Configs can be saved as YAML or JSON.
 
+### Encoding Descriptor (`encoding`)
+
+Extract the metadata encoding descriptor from an archived `result.json` and write it
+where it can be reviewed and committed, so a later dataset is cut the same way:
+
+```bash
+python -m dataeval_flow encoding output/results/result.json -o policy/factor_bins.json
+python -m dataeval_flow encoding output/results/result.json --task clean_my_data
+```
+
+Reference the committed descriptor from a metadata policy's `encoding` field. A run with
+`-o` already writes `results/encoding.json` beside its results; this command recovers one
+from a result archived earlier. See
+[Configure metadata binning](https://dataeval-flow.readthedocs.io/en/latest/how_to/configure_metadata_binning.html).
+
 ## Dependencies
 
+Declared runtime dependencies:
+
 - `dataeval` - Core evaluation library
-- `datamaite` - MAITE protocol dataset loaders
-- `maite` - MAITE protocol library
+- `datamaite` - MAITE protocol dataset loaders (which brings in `maite` itself)
 - `pydantic` - Structural typing and schema validation
+- `click` - Interactive prompts for the simple CLI config builder
+- `pyyaml` - YAML config parsing
+- `numpy` - Array handling
+
+PyTorch arrives transitively through `dataeval`. Optional extras (`onnx`, `opencv`,
+`app`, `ontology`, and the CUDA variants) are listed under
+[Running Without Container](#running-without-container).
 
 ## Troubleshooting
 
@@ -392,8 +530,8 @@ DataEval Flow — it accepts the build already present (omit step 1 and you'll g
 CUDA-bundled manylinux build of torch from PyPI, which is much larger):
 
 ```bash
-# 1. Pick your PyTorch build (cpu / cu118 / cu128)
-pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128
+# 1. Pick your PyTorch build (cpu / cu126 / cu130)
+pip install torch torchvision --index-url https://download.pytorch.org/whl/cu130
 
 # 2. Install DataEval Flow
 pip install dataeval-flow
@@ -411,14 +549,14 @@ pip install dataeval-flow
 `torchvision` is not installed by default — it is imported lazily and is only needed
 for preprocessing pipelines, the torchvision dataset adapter, and the TUI's transform
 discovery. Install it together with `torch` in step 1 so both come from the same index.
-Feature extras (`onnx`, `onnx-gpu`, `opencv`, `app`, `ontology`) work normally under
+Feature extras (`onnx`, `onnx-cu126`, `onnx-cu130`, `opencv`, `opencv-fips`, `app`, `ontology`) work normally under
 pip and are independent of the PyTorch variant:
 
 ```bash
 pip install "dataeval-flow[onnx,opencv,app]"
 ```
 
-> **The `cpu` / `cu118` / `cu128` extras do not select a PyTorch variant under pip.**
+> **The `cpu` / `cu126` / `cu130` extras do not select a PyTorch variant under pip.**
 > All three declare the same requirements (`torch`, `torchvision`); what distinguishes
 > them is `[tool.uv.sources]`, which routes those packages to the right wheel index.
 > That is project metadata applied by uv when resolving **from source** — it is not
@@ -429,7 +567,7 @@ pip install "dataeval-flow[onnx,opencv,app]"
 `uv` from PyPI:
 
 ```bash
-uv pip install dataeval-flow --torch-backend cpu     # or cu118 / cu128 / auto
+uv pip install dataeval-flow --torch-backend cpu     # or cu126 / cu130 / auto
 ```
 
 `uv` from source (default toolchain; uses committed `uv.lock`) — extras apply here:
@@ -437,7 +575,7 @@ uv pip install dataeval-flow --torch-backend cpu     # or cu118 / cu128 / auto
 ```bash
 git clone https://github.com/aria-ml/dataeval-flow.git
 cd dataeval-flow
-uv sync --extra cpu      # or cu118 / cu128; add --extra onnx --extra opencv --extra app as needed
+uv sync --extra cpu      # or cu126 / cu130; add --extra onnx --extra opencv --extra app as needed
 ```
 
 `poetry` (source checkout; uses committed `poetry.lock`):
@@ -462,7 +600,7 @@ Notes:
 
 - PyTorch is installed from PyPI/`download.pytorch.org` in every path
   (it is no longer maintained on conda-forge).
-- GPU variants (`cu118`, `cu128`) are only wired through `uv` and
+- GPU variants (`cu126`, `cu130`) are only wired through `uv` and
   `pip` today; the Poetry/conda paths install the CPU build of PyTorch.
 
 **CLI Usage:**