reader-workbench 1.0.0__tar.gz

reader_workbench-1.0.0/CITATION.cff

@@ -0,0 +1,10 @@
+cff-version: 1.2.0
+message: "Cite Reader and record the exact version, source revision and artifact checksum used."
+type: software
+title: "Reader: validated, traceable analysis of experimental instrument data"
+authors:
+  - family-names: South
+    given-names: Eric J.
+repository-code: "https://github.com/e-south/reader"
+license: MIT
+# pyproject.toml owns the version; the release workflow adds it to the bundle citation.

reader_workbench-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Eric South
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

reader_workbench-1.0.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include CITATION.cff
+include assets/reader-banner.png

reader_workbench-1.0.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: reader-workbench
+Version: 1.0.0
+Summary: Validated, traceable analysis workflows for experimental instrument data
+Author: Eric J. South
+License-Expression: MIT
+Project-URL: Documentation, https://github.com/e-south/reader/tree/main/docs
+Project-URL: Issues, https://github.com/e-south/reader/issues
+Project-URL: Repository, https://github.com/e-south/reader
+Keywords: data-analysis,data-pipelines,scientific-computing,workbench
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: <3.13,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: pandas>=2.1
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: typer>=0.16.0
+Requires-Dist: click>=8.3.3
+Requires-Dist: rich>=13.7
+Requires-Dist: pyarrow>=23.0.1
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: seaborn>=0.13
+Requires-Dist: pillow>=12.3.0
+Requires-Dist: polars>=1.36.1
+Requires-Dist: flowio>=1.4.0
+Requires-Dist: filelock<4,>=3.20.3
+Dynamic: license-file
+
+# ![Reader data workbench](https://raw.githubusercontent.com/e-south/reader/v1.0.0/assets/reader-banner.png)
+
+[![Checks](https://github.com/e-south/reader/actions/workflows/checks.yaml/badge.svg?branch=main)](https://github.com/e-south/reader/actions/workflows/checks.yaml)
+[![Python 3.12](https://img.shields.io/badge/python-3.12-3776AB.svg)](https://www.python.org/downloads/release/python-3120/)
+[![MIT license](https://img.shields.io/badge/license-MIT-3D8068.svg)](https://github.com/e-south/reader/blob/main/LICENSE)
+
+Reader ingests instrument files and experiment metadata, applies declared
+transformations, and writes validated records, plots, exports, and notebooks.
+Every unit of work—including a cross-experiment aggregate—has an owned directory
+beneath `experiments/`, with source material in `inputs/`, a `reader/v8`
+contract in `config.yaml`, and generated artifacts in `outputs/`.
+The distribution and import package are named `reader-workbench` and
+`reader_workbench`; the installed command remains `reader`.
+
+## Install
+
+Install Reader as a command-line tool:
+
+```bash
+uv tool install reader-workbench
+```
+
+For development, install from a checkout:
+
+```bash
+git clone https://github.com/e-south/reader.git
+cd reader
+uv sync --locked --group dev
+uv run reader demo
+```
+
+The installed command is `reader`:
+
+```bash
+reader demo
+reader protocols
+reader init ./experiments/my_experiment --protocol plate_reader/single_reporter_screen
+```
+
+The demo prints a guided command tour. It does not execute a pipeline or write
+files. Every generated starter can be inspected and validated before data is
+added.
+
+## Learn more
+
+- [Getting started](https://github.com/e-south/reader/blob/main/docs/guides/getting_started.md) — install Reader, run the
+  demo, and scaffold a first experiment.
+- [Common tasks](https://github.com/e-south/reader/blob/main/docs/guides/common_routes.md) — shortest commands for
+  discovery, validation, execution, and automation.
+- [Python API](https://github.com/e-south/reader/blob/main/docs/core/python_api.md) — typed, task-oriented experiment and
+  plugin interfaces for integrations.
+- [Documentation index](https://github.com/e-south/reader/blob/main/docs/README.md) — complete user, reference, and
+  maintainer documentation.
+
+Reader is available under the [MIT license](https://github.com/e-south/reader/blob/main/LICENSE).

reader_workbench-1.0.0/README.md

@@ -0,0 +1,55 @@
+# ![Reader data workbench](https://raw.githubusercontent.com/e-south/reader/v1.0.0/assets/reader-banner.png)
+
+[![Checks](https://github.com/e-south/reader/actions/workflows/checks.yaml/badge.svg?branch=main)](https://github.com/e-south/reader/actions/workflows/checks.yaml)
+[![Python 3.12](https://img.shields.io/badge/python-3.12-3776AB.svg)](https://www.python.org/downloads/release/python-3120/)
+[![MIT license](https://img.shields.io/badge/license-MIT-3D8068.svg)](https://github.com/e-south/reader/blob/main/LICENSE)
+
+Reader ingests instrument files and experiment metadata, applies declared
+transformations, and writes validated records, plots, exports, and notebooks.
+Every unit of work—including a cross-experiment aggregate—has an owned directory
+beneath `experiments/`, with source material in `inputs/`, a `reader/v8`
+contract in `config.yaml`, and generated artifacts in `outputs/`.
+The distribution and import package are named `reader-workbench` and
+`reader_workbench`; the installed command remains `reader`.
+
+## Install
+
+Install Reader as a command-line tool:
+
+```bash
+uv tool install reader-workbench
+```
+
+For development, install from a checkout:
+
+```bash
+git clone https://github.com/e-south/reader.git
+cd reader
+uv sync --locked --group dev
+uv run reader demo
+```
+
+The installed command is `reader`:
+
+```bash
+reader demo
+reader protocols
+reader init ./experiments/my_experiment --protocol plate_reader/single_reporter_screen
+```
+
+The demo prints a guided command tour. It does not execute a pipeline or write
+files. Every generated starter can be inspected and validated before data is
+added.
+
+## Learn more
+
+- [Getting started](https://github.com/e-south/reader/blob/main/docs/guides/getting_started.md) — install Reader, run the
+  demo, and scaffold a first experiment.
+- [Common tasks](https://github.com/e-south/reader/blob/main/docs/guides/common_routes.md) — shortest commands for
+  discovery, validation, execution, and automation.
+- [Python API](https://github.com/e-south/reader/blob/main/docs/core/python_api.md) — typed, task-oriented experiment and
+  plugin interfaces for integrations.
+- [Documentation index](https://github.com/e-south/reader/blob/main/docs/README.md) — complete user, reference, and
+  maintainer documentation.
+
+Reader is available under the [MIT license](https://github.com/e-south/reader/blob/main/LICENSE).

reader_workbench-1.0.0/pyproject.toml

@@ -0,0 +1,128 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "reader-workbench"
+version = "1.0.0"
+description = "Validated, traceable analysis workflows for experimental instrument data"
+readme = "README.md"
+requires-python = ">=3.12,<3.13"
+authors = [{ name = "Eric J. South" }]
+keywords = ["data-analysis", "data-pipelines", "scientific-computing", "workbench"]
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering",
+]
+
+
+dependencies = [
+  "numpy>=1.26",
+  "matplotlib>=3.8",
+  "pandas>=2.1",
+  "pydantic>=2.6",
+  "pyyaml>=6.0.2",
+  "typer>=0.16.0",
+  "click>=8.3.3",
+  "rich>=13.7",
+  "pyarrow>=23.0.1",
+  "openpyxl>=3.1",
+  "seaborn>=0.13",
+  "pillow>=12.3.0",
+  "polars>=1.36.1",
+  "flowio>=1.4.0",
+  "filelock>=3.20.3,<4",
+]
+
+[project.scripts]
+reader = "reader_workbench.workbench.cli:main"
+
+[project.urls]
+Documentation = "https://github.com/e-south/reader/tree/main/docs"
+Issues = "https://github.com/e-south/reader/issues"
+Repository = "https://github.com/e-south/reader"
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["reader_workbench*"]
+exclude = ["reader_workbench.tests", "reader_workbench.tests.*"]
+namespaces = false
+
+[tool.setuptools.package-data]
+"reader_workbench.workbench.notebooks" = ["*.marimo.py.txt"]
+
+[dependency-groups]
+dev = [
+  "pytest>=8.2",
+  "pytest-cov>=7.0",
+  "pip-audit>=2.10.1,<3",
+  "twine>=7,<8",
+  "ruff>=0.4",
+  "pre-commit>=3.7",
+]
+
+[tool.uv]
+required-version = ">=0.12.3,<0.13"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+src = ["src"]
+extend-exclude = [".venv", "build", "dist", ".eggs", "*.egg-info"]
+
+[tool.ruff.lint]
+select = ["E","F","W","I","UP","B","SIM","C4","PLC","PLE"]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101","PLR2004","B011"]
+"**/*.ipynb" = ["E402"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "auto"
+skip-magic-trailing-comma = false
+docstring-code-format = true
+
+[tool.pytest.ini_options]
+testpaths = [
+  "src/reader_workbench/tests",
+  "tests"
+]
+
+python_files = ["test_*.py", "*_test.py"]
+python_classes = ["Test*", "*Tests"]
+python_functions = ["test_*"]
+
+addopts = [
+  "--strict-config",
+  "--strict-markers",
+  "-ra",
+]
+
+markers = [
+  "integration: cross-surface integration coverage",
+]
+
+norecursedirs = [
+  ".venv", "build", "dist", ".eggs", "*.egg-info",
+  "outputs", "raw_data", "_scratch", ".tmp"
+]
+
+[tool.coverage.run]
+branch = true
+source = ["reader_workbench"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true

reader_workbench-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

reader_workbench-1.0.0/src/reader_workbench/__init__.py

@@ -0,0 +1,22 @@
+"""Reader's narrow, task-oriented public entrypoint."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from reader_workbench.api import Experiment, open_experiment
+
+__all__ = ["Experiment", "__version__", "open_experiment"]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "__version__":
+        from reader_workbench._version import package_version  # noqa: PLC0415
+
+        return package_version()
+    if name not in __all__:
+        raise AttributeError(f"module 'reader_workbench' has no attribute {name!r}")
+    api = import_module("reader_workbench.api")
+    return getattr(api, name)

reader_workbench-1.0.0/src/reader_workbench/__main__.py

@@ -0,0 +1,4 @@
+from reader_workbench.workbench.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

reader_workbench-1.0.0/src/reader_workbench/_version.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+_DISTRIBUTION_NAME = "reader-workbench"
+
+
+def package_version() -> str:
+    """Return the installed Reader distribution version."""
+
+    try:
+        return version(_DISTRIBUTION_NAME)
+    except PackageNotFoundError:
+        return "0+uninstalled"
+
+
+__all__ = ["package_version"]

reader_workbench-1.0.0/src/reader_workbench/api/__init__.py

@@ -0,0 +1,74 @@
+"""Stable, task-oriented interfaces for Reader experiments and plugins."""
+
+from .artifacts import ArtifactFileResult, read_artifact
+from .facade import (
+    describe_plugin,
+    inspect,
+    notebook,
+    open_experiment,
+    plan,
+    plots,
+    plugins,
+    read_dataframe,
+    records,
+    run,
+    validate,
+    verify,
+)
+from .models import (
+    ApiResult,
+    DataFrameRecordResult,
+    Experiment,
+    ExperimentEvidence,
+    ExperimentIdentity,
+    InspectionResult,
+    NotebookResult,
+    PlanResult,
+    PluginCatalogResult,
+    PluginDescriptorResult,
+    PluginPort,
+    PluginSummary,
+    RecordCatalogResult,
+    RecordRevision,
+    RunResult,
+    SelectedSteps,
+    SurfaceCatalogResult,
+    ValidationResult,
+    VerificationResult,
+)
+
+__all__ = [
+    "ApiResult",
+    "ArtifactFileResult",
+    "DataFrameRecordResult",
+    "Experiment",
+    "ExperimentEvidence",
+    "ExperimentIdentity",
+    "InspectionResult",
+    "NotebookResult",
+    "PlanResult",
+    "PluginCatalogResult",
+    "PluginDescriptorResult",
+    "PluginPort",
+    "PluginSummary",
+    "RecordCatalogResult",
+    "RecordRevision",
+    "RunResult",
+    "SelectedSteps",
+    "SurfaceCatalogResult",
+    "ValidationResult",
+    "VerificationResult",
+    "describe_plugin",
+    "inspect",
+    "notebook",
+    "open_experiment",
+    "plan",
+    "plots",
+    "plugins",
+    "read_artifact",
+    "read_dataframe",
+    "records",
+    "run",
+    "validate",
+    "verify",
+]

reader_workbench-1.0.0/src/reader_workbench/api/_record_reads.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from reader_workbench.errors import RecordError
+from reader_workbench.workbench.records import (
+    DataFrameArtifactRecord,
+    FileBundleRecord,
+    RecordStore,
+    record_revision_digest,
+)
+from reader_workbench.workbench.records.identity import is_sha256_digest
+
+from .models import Experiment, RecordRevision
+
+
+def resolve_record_revision(
+    experiment: Experiment,
+    record_id: str,
+    *,
+    revision: int | None,
+    revision_digest: str | None,
+    missing_label: str = "Record",
+) -> tuple[RecordStore, DataFrameArtifactRecord | FileBundleRecord, RecordRevision]:
+    """Resolve one catalog revision and prove its caller-supplied identity."""
+
+    if not isinstance(record_id, str) or not record_id.strip():
+        raise RecordError("record_id must be a non-empty string")
+    if record_id != record_id.strip():
+        raise RecordError("record_id must not contain leading or trailing whitespace")
+    if (revision is None) != (revision_digest is None):
+        raise RecordError("revision and revision_digest must be provided together")
+    if revision is not None and (isinstance(revision, bool) or not isinstance(revision, int) or revision < 1):
+        raise RecordError("revision must be a positive integer")
+    if revision_digest is not None and not is_sha256_digest(revision_digest):
+        raise RecordError("revision_digest must be a sha256 digest")
+
+    declaration = experiment._declaration
+    layout = declaration.experiment_semantics.layout
+    store = experiment._runtime.record_store(
+        layout.outputs_dir,
+        plots_subdir=layout.plots_subdir,
+        exports_subdir=layout.exports_subdir,
+        experiment_root=declaration.experiment.root,
+        create=False,
+    )
+    if not store.catalog_exists():
+        raise RecordError(
+            f"Record catalog is missing for experiment {declaration.experiment.id!r}: {store.records_path}"
+        )
+
+    history = store.record_history(record_id)
+    if not history:
+        raise RecordError(f"{missing_label} {record_id!r} is missing; produce it in an earlier step.")
+    resolved_revision = len(history) if revision is None else revision
+    if resolved_revision > len(history):
+        raise RecordError(
+            f"Record {record_id!r} revision {resolved_revision} is unavailable; refresh the record catalog."
+        )
+    record = history[resolved_revision - 1]
+    actual_revision_digest = record_revision_digest(record, outputs_dir=store.root)
+    if revision_digest is not None and actual_revision_digest != revision_digest:
+        raise RecordError(
+            f"Record {record_id!r} revision digest mismatch; refresh the record catalog before reading it."
+        )
+    return (
+        store,
+        record,
+        RecordRevision(
+            record_id=record.record_id,
+            revision=resolved_revision,
+            revision_digest=actual_revision_digest,
+        ),
+    )
+
+
+__all__ = ["resolve_record_revision"]

reader_workbench-1.0.0/src/reader_workbench/api/artifacts.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import hashlib
+from mimetypes import guess_type
+from pathlib import Path
+
+from reader_workbench.errors import RecordError
+from reader_workbench.workbench.records import (
+    FileBundleRecord,
+    record_to_dict,
+    verify_record_artifact_integrity,
+)
+
+from ._record_reads import resolve_record_revision
+from .models import ArtifactFileResult, Experiment
+
+
+def read_artifact(
+    experiment: Experiment,
+    record_id: str,
+    *,
+    revision: int,
+    revision_digest: str,
+    path: str,
+) -> ArtifactFileResult:
+    """Read verified bytes for one file in an exact file-bundle record revision."""
+
+    if revision is None or revision_digest is None:
+        raise RecordError("read_artifact requires both revision and revision_digest")
+    if not isinstance(path, str) or not path.strip() or path != path.strip():
+        raise RecordError("path must be one non-empty outputs-relative artifact path")
+    requested_path = Path(path)
+    if requested_path.is_absolute() or ".." in requested_path.parts or requested_path == Path("."):
+        raise RecordError("path must be one confined outputs-relative artifact path")
+    normalized_path = requested_path.as_posix()
+    if normalized_path != path:
+        raise RecordError("path must use the canonical outputs-relative artifact path from records()")
+
+    store, record, bound_revision = resolve_record_revision(
+        experiment,
+        record_id,
+        revision=revision,
+        revision_digest=revision_digest,
+        missing_label="File-bundle record",
+    )
+    if not isinstance(record, FileBundleRecord):
+        raise RecordError(f"Record {record_id!r} exists but is not a file bundle")
+    payload = record_to_dict(record, outputs_dir=store.root)
+    raw_files = payload.get("files")
+    encoded_files = raw_files if isinstance(raw_files, list) else []
+    try:
+        file_index = encoded_files.index(normalized_path)
+    except ValueError as exc:
+        raise RecordError(
+            f"Artifact {normalized_path!r} is not part of record {record_id!r} revision {revision}."
+        ) from exc
+
+    verify_record_artifact_integrity(record, outputs_dir=store.root)
+    evidence_by_path = {item.relative_path.as_posix(): item for item in record.file_evidence}
+    evidence = evidence_by_path[normalized_path]
+    try:
+        content = record.files[file_index].read_bytes()
+    except OSError as exc:
+        raise RecordError(f"Artifact {normalized_path!r} could not be read after verification.") from exc
+    actual_digest = "sha256:" + hashlib.sha256(content).hexdigest()
+    if len(content) != evidence.size_bytes or actual_digest != evidence.content_digest:
+        raise RecordError(f"Artifact {normalized_path!r} changed while it was being read; refresh and retry.")
+    return ArtifactFileResult(
+        experiment=experiment.identity,
+        record=bound_revision,
+        relative_path=normalized_path,
+        media_type=guess_type(normalized_path)[0] or "application/octet-stream",
+        content_digest=evidence.content_digest,
+        size_bytes=evidence.size_bytes,
+        content=content,
+    )
+
+
+__all__ = ["ArtifactFileResult", "read_artifact"]