reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/api/models.py

@@ -0,0 +1,285 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from copy import deepcopy
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+import pandas as pd
+
+from reader_workbench.runtime import ReaderRuntime
+from reader_workbench.workbench.config import ReaderSpec
+from reader_workbench.workbench.decl import WorkbenchDecl
+
+
+def _json_ready(value: Any) -> Any:
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, tuple):
+        return [_json_ready(item) for item in value]
+    if isinstance(value, list):
+        return [_json_ready(item) for item in value]
+    if isinstance(value, dict):
+        return {str(key): _json_ready(item) for key, item in value.items()}
+    return deepcopy(value)
+
+
+class ApiResult:
+    """Base for typed public results with a JSON-ready projection."""
+
+    def to_dict(self) -> dict[str, object]:
+        return _json_ready(asdict(self))
+
+
+@dataclass(frozen=True)
+class ExperimentEvidence(ApiResult):
+    data_class: str
+    data_class_reason: str
+    replicate_kind: str
+    replicate_identity_field: str | None = None
+
+
+@dataclass(frozen=True)
+class ExperimentIdentity(ApiResult):
+    id: str
+    title: str
+    lifecycle: str
+    protocol: str
+    config: str
+    root: str
+    evidence: ExperimentEvidence | None = None
+
+
+@dataclass(frozen=True)
+class Experiment:
+    """A loaded, protocol-bound experiment handle for public API operations."""
+
+    config_path: Path
+    _spec: ReaderSpec = field(repr=False)
+    _declaration: WorkbenchDecl = field(repr=False)
+    _runtime: ReaderRuntime = field(repr=False)
+
+    @property
+    def identity(self) -> ExperimentIdentity:
+        decl = self._declaration
+        semantic_evidence = decl.experiment_semantics.evidence
+        return ExperimentIdentity(
+            id=decl.experiment.id,
+            title=decl.experiment.title,
+            lifecycle=decl.experiment.lifecycle,
+            protocol=decl.experiment_semantics.protocol.id,
+            config=str(self.config_path),
+            root=str(decl.experiment.root),
+            evidence=(
+                ExperimentEvidence(
+                    data_class=semantic_evidence.data_class,
+                    data_class_reason=semantic_evidence.data_class_reason,
+                    replicate_kind=semantic_evidence.replicate_kind,
+                    replicate_identity_field=semantic_evidence.replicate_identity_field,
+                )
+                if semantic_evidence is not None
+                else None
+            ),
+        )
+
+
+@dataclass(frozen=True)
+class InspectionResult(ApiResult):
+    experiment: ExperimentIdentity
+    authoring: Mapping[str, object]
+    semantics: Mapping[str, object]
+    implementation: Mapping[str, object]
+
+
+@dataclass(frozen=True)
+class ValidationResult(ApiResult):
+    experiment: ExperimentIdentity
+    check_files: bool
+    status: str
+    summary: Mapping[str, object]
+    validation: Mapping[str, object]
+
+
+@dataclass(frozen=True)
+class PlanResult(ApiResult):
+    experiment: ExperimentIdentity
+    plan: Mapping[str, object]
+    compiled: Mapping[str, object]
+    semantics: Mapping[str, object]
+
+
+@dataclass(frozen=True)
+class NotebookResult(ApiResult):
+    experiment: ExperimentIdentity
+    path: str
+    template: str
+    created: bool
+
+
+@dataclass(frozen=True)
+class SurfaceCatalogResult(ApiResult):
+    experiment: ExperimentIdentity
+    kind: str
+    protocol: str
+    selection: Mapping[str, object]
+    summary: Mapping[str, object]
+    entries: tuple[Mapping[str, object], ...]
+
+
+@dataclass(frozen=True)
+class RecordCatalogResult(ApiResult):
+    experiment: ExperimentIdentity
+    catalog_exists: bool
+    catalog: Mapping[str, object]
+    include_history: bool
+    summary: Mapping[str, object]
+    entries: tuple[Mapping[str, object], ...]
+
+
+@dataclass(frozen=True)
+class VerificationResult(ApiResult):
+    experiment: ExperimentIdentity
+    status: str
+    summary: Mapping[str, object]
+    issues: tuple[Mapping[str, object], ...]
+    records: tuple[Mapping[str, object], ...]
+
+
+@dataclass(frozen=True)
+class SelectedSteps(ApiResult):
+    pipeline: tuple[str, ...]
+    plots: tuple[str, ...]
+    exports: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class RecordRevision(ApiResult):
+    record_id: str
+    revision: int
+    revision_digest: str
+
+
+@dataclass(frozen=True)
+class DataFrameRecordResult(ApiResult):
+    """One content-digest-verified, contract-validated dataframe record."""
+
+    experiment: ExperimentIdentity
+    record: RecordRevision
+    contract_id: str
+    content_digest: str
+    dataframe: pd.DataFrame = field(repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "dataframe", self.dataframe.copy(deep=True))
+
+    def to_dict(self) -> dict[str, object]:
+        """Project JSON-ready metadata without serializing dataframe values."""
+
+        return {
+            "experiment": self.experiment.to_dict(),
+            "record": self.record.to_dict(),
+            "contract_id": self.contract_id,
+            "content_digest": self.content_digest,
+            "dataframe": {
+                "rows": int(self.dataframe.shape[0]),
+                "columns": [str(column) for column in self.dataframe.columns],
+            },
+        }
+
+
+@dataclass(frozen=True)
+class ArtifactFileResult(ApiResult):
+    """One digest-verified file from an exact file-bundle record revision."""
+
+    experiment: ExperimentIdentity
+    record: RecordRevision
+    relative_path: str
+    media_type: str
+    content_digest: str
+    size_bytes: int
+    content: bytes = field(repr=False, compare=False)
+
+    def to_dict(self) -> dict[str, object]:
+        """Project JSON-ready evidence without serializing artifact bytes."""
+
+        return {
+            "experiment": self.experiment.to_dict(),
+            "record": self.record.to_dict(),
+            "relative_path": self.relative_path,
+            "media_type": self.media_type,
+            "content_digest": self.content_digest,
+            "size_bytes": self.size_bytes,
+        }
+
+
+@dataclass(frozen=True)
+class RunResult(ApiResult):
+    experiment: ExperimentIdentity
+    invocation_id: str | None
+    provenance_epoch_id: str | None
+    operation: Literal["run", "plot", "export", "mixed"]
+    status: Literal["planned", "succeeded"]
+    dry_run: bool
+    selected_steps: SelectedSteps
+    produced_record_revisions: tuple[RecordRevision, ...]
+    ledger_path: str | None
+
+
+@dataclass(frozen=True)
+class PluginSummary(ApiResult):
+    plugin: str
+    key: str
+    category: str
+    domain: str
+    family: str
+    summary: str
+    implementation: str
+
+
+@dataclass(frozen=True)
+class PluginCatalogResult(ApiResult):
+    selection: Mapping[str, object]
+    summary: Mapping[str, object]
+    plugins: tuple[PluginSummary, ...]
+
+
+@dataclass(frozen=True)
+class PluginPort(ApiResult):
+    name: str
+    kind: str
+    optional: bool
+    contract: str | None
+    contract_surface: Mapping[str, object] | None = None
+
+
+@dataclass(frozen=True)
+class PluginDescriptorResult(ApiResult):
+    plugin: PluginSummary
+    config_schema: Mapping[str, object]
+    input_ports: tuple[PluginPort, ...]
+    output_ports: tuple[PluginPort, ...]
+
+
+__all__ = [
+    "ApiResult",
+    "ArtifactFileResult",
+    "DataFrameRecordResult",
+    "Experiment",
+    "ExperimentEvidence",
+    "ExperimentIdentity",
+    "InspectionResult",
+    "NotebookResult",
+    "PlanResult",
+    "PluginCatalogResult",
+    "PluginDescriptorResult",
+    "PluginPort",
+    "PluginSummary",
+    "RecordCatalogResult",
+    "RecordRevision",
+    "RunResult",
+    "SelectedSteps",
+    "SurfaceCatalogResult",
+    "ValidationResult",
+    "VerificationResult",
+]

reader_workbench/api/notebooks.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from reader_workbench.workbench.graph import resolve_workbench
+from reader_workbench.workbench.notebooks.components import (
+    NotebookDeliverables,
+    NotebookOverview,
+    build_notebook_deliverable_selector,
+    build_notebook_overview,
+    collect_notebook_deliverables,
+    render_notebook_deliverable_viewport,
+    render_notebook_overview_panel,
+)
+
+from .facade import open_experiment
+from .models import Experiment
+
+
+@dataclass(frozen=True)
+class NotebookContext:
+    """Stable experiment context used by Reader-generated notebooks."""
+
+    experiment: Experiment
+    experiment_root: Path
+    outputs_dir: Path
+    notebooks_dir: Path
+    pipeline_step_ids: tuple[str, ...]
+
+
+def load_notebook_context(start: str | Path) -> NotebookContext:
+    """Open the owning experiment for a generated notebook path."""
+
+    experiment = open_experiment(start)
+    decl = experiment._declaration
+    layout = decl.experiment_semantics.layout
+    notebooks_dir = (
+        layout.outputs_dir
+        if layout.notebooks_subdir in {"", ".", "./"}
+        else layout.outputs_dir / layout.notebooks_subdir
+    )
+    workbench = resolve_workbench(decl)
+    return NotebookContext(
+        experiment=experiment,
+        experiment_root=decl.experiment.root,
+        outputs_dir=layout.outputs_dir,
+        notebooks_dir=notebooks_dir,
+        pipeline_step_ids=tuple(step.id for step in workbench.pipeline),
+    )
+
+
+__all__ = [
+    "NotebookContext",
+    "NotebookDeliverables",
+    "NotebookOverview",
+    "build_notebook_deliverable_selector",
+    "build_notebook_overview",
+    "collect_notebook_deliverables",
+    "load_notebook_context",
+    "render_notebook_deliverable_viewport",
+    "render_notebook_overview_panel",
+]

reader_workbench/contracts/__init__.py

@@ -0,0 +1,18 @@
+"""Explicit dataframe-contract kernel and built-in contract catalog."""
+
+from .builtins import BUILTIN_CONTRACTS, builtin_contract_catalog
+from .catalog import ContractCatalog, OutputContractSurface
+from .model import ColumnRule, ContractId, ContractToken, DataFrameContract, DType, validate_df
+
+__all__ = [
+    "BUILTIN_CONTRACTS",
+    "ColumnRule",
+    "ContractCatalog",
+    "ContractId",
+    "ContractToken",
+    "DType",
+    "DataFrameContract",
+    "OutputContractSurface",
+    "builtin_contract_catalog",
+    "validate_df",
+]

reader_workbench/contracts/builtins/__init__.py

@@ -0,0 +1,36 @@
+"""Explicit built-in dataframe contract catalog."""
+
+from __future__ import annotations
+
+from functools import cache
+
+from ..catalog import ContractCatalog
+from .cytometry import CONTRACTS as CYTOMETRY_CONTRACTS
+from .four_state_event_window import CONTRACTS as FOUR_STATE_EVENT_WINDOW_CONTRACTS
+from .generic import CONTRACTS as GENERIC_CONTRACTS
+from .logic import CONTRACTS as LOGIC_CONTRACTS
+from .plate_reader import CONTRACTS as PLATE_READER_CONTRACTS
+
+BUILTIN_CONTRACTS = (
+    *GENERIC_CONTRACTS,
+    *PLATE_READER_CONTRACTS,
+    *FOUR_STATE_EVENT_WINDOW_CONTRACTS,
+    *LOGIC_CONTRACTS,
+    *CYTOMETRY_CONTRACTS,
+)
+
+
+@cache
+def builtin_contract_catalog() -> ContractCatalog:
+    return ContractCatalog.from_contracts(BUILTIN_CONTRACTS)
+
+
+__all__ = [
+    "BUILTIN_CONTRACTS",
+    "CYTOMETRY_CONTRACTS",
+    "GENERIC_CONTRACTS",
+    "LOGIC_CONTRACTS",
+    "PLATE_READER_CONTRACTS",
+    "FOUR_STATE_EVENT_WINDOW_CONTRACTS",
+    "builtin_contract_catalog",
+]

reader_workbench/contracts/builtins/cytometry.py

@@ -0,0 +1,140 @@
+"""Cytometry-domain dataframe contracts."""
+
+from __future__ import annotations
+
+from ..model import ColumnRule, DataFrameContract
+
+CONTRACTS: tuple[DataFrameContract, ...] = (
+    DataFrameContract(
+        id="cytometer.channels.v1",
+        description="Per-sample cytometer channel metadata from FCS headers.",
+        columns=[
+            ColumnRule("sample_id", "string"),
+            ColumnRule("channel_index", "int"),
+            ColumnRule("channel_name", "string"),
+            ColumnRule("pns", "string", required=False, allow_nan=True),
+            ColumnRule("pnn", "string", required=False, allow_nan=True),
+            ColumnRule("pnt", "string", required=False, allow_nan=True),
+            ColumnRule("pnf", "string", required=False, allow_nan=True),
+            ColumnRule("pnl", "string", required=False, allow_nan=True),
+            ColumnRule("pnr", "float", required=False, allow_nan=True),
+            ColumnRule("pnb", "float", required=False, allow_nan=True),
+            ColumnRule("png", "float", required=False, allow_nan=True),
+            ColumnRule("pne_decades", "float", required=False, allow_nan=True),
+            ColumnRule("pne_zero", "float", required=False, allow_nan=True),
+        ],
+        unique_keys=[],
+        domain="cytometry",
+        kind="channel-metadata",
+    ),
+    DataFrameContract(
+        id="cytometry.gate_definition.v1",
+        description="One resolved cytometry gate, threshold, grouping, and QC definition.",
+        columns=[
+            ColumnRule("definition_id", "string"),
+            ColumnRule("cells_enabled", "bool"),
+            ColumnRule("cells_x_channel", "string"),
+            ColumnRule("cells_x_min", "float"),
+            ColumnRule("cells_x_max", "float"),
+            ColumnRule("cells_y_channel", "string"),
+            ColumnRule("cells_y_min", "float"),
+            ColumnRule("cells_y_max", "float"),
+            ColumnRule("singlets_enabled", "bool"),
+            ColumnRule("singlet_x_channel", "string"),
+            ColumnRule("singlet_y_channel", "string"),
+            ColumnRule("singlet_ratio_min", "float"),
+            ColumnRule("singlet_ratio_max", "float"),
+            ColumnRule("fluorescence_channel", "string"),
+            ColumnRule("threshold_mode", "string", allowed_values=("manual", "from_control_quantile")),
+            ColumnRule("threshold_value", "float"),
+            ColumnRule("threshold_group_column", "string", allow_nan=True),
+            ColumnRule("threshold_control_value", "string", allow_nan=True),
+            ColumnRule("threshold_quantile", "float", allow_nan=True),
+            ColumnRule("group_column", "string", allow_nan=True),
+            ColumnRule("minimum_final_events", "int", nonnegative=True),
+            ColumnRule("minimum_final_percent", "float", nonnegative=True),
+            ColumnRule("maximum_nonpositive_percent", "float", nonnegative=True),
+            ColumnRule("nonpositive_scope", "string", allowed_values=("all_events", "gated_events")),
+        ],
+        unique_keys=[["definition_id"]],
+        domain="cytometry",
+        kind="gate-definition",
+    ),
+    DataFrameContract(
+        id="cytometry.gated_events.v1",
+        description="Event-wide cytometry rows that passed the resolved sequential gates.",
+        columns=[
+            ColumnRule("sample_id", "string"),
+            ColumnRule("event_index", "int", nonnegative=True),
+        ],
+        unique_keys=[["sample_id", "event_index"]],
+        domain="cytometry",
+        kind="gated-events",
+    ),
+    DataFrameContract(
+        id="cytometry.sample_stats.v1",
+        description="Per-sample cytometry gate counts and fluorescence summaries.",
+        columns=[
+            ColumnRule("sample_id", "string"),
+            ColumnRule("group_column", "string", allow_nan=True),
+            ColumnRule("group_value", "string", allow_nan=True),
+            ColumnRule("n_total_events", "int", nonnegative=True),
+            ColumnRule("n_cells_gate", "int", nonnegative=True),
+            ColumnRule("n_singlets", "int", nonnegative=True),
+            ColumnRule("pct_cells", "float", nonnegative=True),
+            ColumnRule("pct_singlets_of_cells", "float", nonnegative=True),
+            ColumnRule("pct_final", "float", nonnegative=True),
+            ColumnRule("fluor_median", "float", allow_nan=True),
+            ColumnRule("fluor_mean", "float", allow_nan=True),
+            ColumnRule("fluor_geomean", "float", allow_nan=True),
+            ColumnRule("fluor_p90", "float", allow_nan=True),
+            ColumnRule("fluor_p99", "float", allow_nan=True),
+            ColumnRule("pct_positive", "float", nonnegative=True, allow_nan=True),
+            ColumnRule("fluorescence_channel", "string"),
+            ColumnRule("threshold_value", "float"),
+        ],
+        unique_keys=[["sample_id"]],
+        domain="cytometry",
+        kind="sample-statistics",
+    ),
+    DataFrameContract(
+        id="cytometry.group_stats.v1",
+        description="Explicitly grouped cytometry sample summaries; empty when grouping is disabled.",
+        columns=[
+            ColumnRule("group_column", "string"),
+            ColumnRule("group_value", "string"),
+            ColumnRule("n_samples", "int", nonnegative=True),
+            ColumnRule("fluor_median_mean", "float", allow_nan=True),
+            ColumnRule("fluor_median_std", "float", allow_nan=True),
+            ColumnRule("fluor_geomean_mean", "float", allow_nan=True),
+            ColumnRule("pct_positive_mean", "float", nonnegative=True, allow_nan=True),
+        ],
+        unique_keys=[["group_column", "group_value"]],
+        domain="cytometry",
+        kind="group-statistics",
+    ),
+    DataFrameContract(
+        id="cytometry.qc.v1",
+        description="Per-sample cytometry QC evaluated against explicit retention and signal policies.",
+        columns=[
+            ColumnRule("sample_id", "string"),
+            ColumnRule("n_total_events", "int", nonnegative=True),
+            ColumnRule("n_cells_gate", "int", nonnegative=True),
+            ColumnRule("n_singlets", "int", nonnegative=True),
+            ColumnRule("pct_final", "float", nonnegative=True),
+            ColumnRule("pct_nonpositive", "float", nonnegative=True),
+            ColumnRule("minimum_final_events", "int", nonnegative=True),
+            ColumnRule("minimum_final_percent", "float", nonnegative=True),
+            ColumnRule("maximum_nonpositive_percent", "float", nonnegative=True),
+            ColumnRule("nonpositive_scope", "string", allowed_values=("all_events", "gated_events")),
+            ColumnRule("passes_final_events", "bool"),
+            ColumnRule("passes_final_percent", "bool"),
+            ColumnRule("passes_nonpositive", "bool"),
+            ColumnRule("qc_pass", "bool"),
+            ColumnRule("qc_status", "string", allowed_values=("pass", "fail")),
+        ],
+        unique_keys=[["sample_id"]],
+        domain="cytometry",
+        kind="quality-control",
+    ),
+)