reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/workbench/notebooks/eda.marimo.py.txt

@@ -0,0 +1,153 @@
+import marimo
+
+__generated_with = "0.23.14"
+app = marimo.App(width="medium")
+
+
+@app.cell(hide_code=True)
+def _():
+    from pathlib import Path
+
+    import marimo as mo
+    from reader_workbench.api import read_artifact, read_dataframe, records, verify
+    from reader_workbench.api.notebooks import (
+        build_notebook_deliverable_selector,
+        build_notebook_overview,
+        collect_notebook_deliverables,
+        load_notebook_context,
+        render_notebook_deliverable_viewport,
+        render_notebook_overview_panel,
+    )
+
+    return (
+        Path,
+        mo,
+        read_artifact,
+        read_dataframe,
+        records,
+        verify,
+        build_notebook_deliverable_selector,
+        build_notebook_overview,
+        collect_notebook_deliverables,
+        load_notebook_context,
+        render_notebook_deliverable_viewport,
+        render_notebook_overview_panel,
+    )
+
+
+@app.cell(hide_code=True)
+def _(Path, build_notebook_overview, load_notebook_context):
+    notebook_context = load_notebook_context(Path(__file__).resolve())
+    experiment = notebook_context.experiment
+    outputs_dir = notebook_context.outputs_dir
+    notebooks_dir = notebook_context.notebooks_dir
+    notebook_overview = build_notebook_overview(
+        experiment_id=experiment.identity.id,
+        experiment_title=experiment.identity.title or "",
+        protocol_id=experiment.identity.protocol,
+        experiment_root=notebook_context.experiment_root,
+        outputs_dir=outputs_dir,
+        notebooks_dir=notebooks_dir,
+        pipeline_step_ids=notebook_context.pipeline_step_ids,
+    )
+    return experiment, notebook_overview, outputs_dir
+
+
+@app.cell(hide_code=True)
+def _(experiment, records, verify):
+    _record_catalog = records(experiment)
+    _verification = verify(experiment)
+    record_entries = _record_catalog.entries
+    verification_issues = _verification.issues
+    verification_records = _verification.records
+    verification_status = _verification.status
+    return record_entries, verification_issues, verification_records, verification_status
+
+
+@app.cell(hide_code=True)
+def _(
+    collect_notebook_deliverables,
+    outputs_dir,
+    record_entries,
+    verification_issues,
+    verification_records,
+    verification_status,
+):
+    deliverables = collect_notebook_deliverables(
+        record_entries,
+        outputs_dir=outputs_dir,
+        verification_status=verification_status,
+        verification_issues=verification_issues,
+        verification_records=verification_records,
+    )
+    return (deliverables,)
+
+
+@app.cell(hide_code=True)
+def _(mo, notebook_overview, render_notebook_overview_panel):
+    eda_overview_panel = render_notebook_overview_panel(mo, notebook_overview)
+    return (eda_overview_panel,)
+
+
+@app.cell(hide_code=True)
+def _(build_notebook_deliverable_selector, deliverables, mo):
+    deliverable_selector = build_notebook_deliverable_selector(mo, deliverables)
+    return (deliverable_selector,)
+
+
+@app.cell(hide_code=True)
+def _(
+    deliverable_selector,
+    deliverables,
+    experiment,
+    mo,
+    read_artifact,
+    read_dataframe,
+    render_notebook_deliverable_viewport,
+):
+    def _load_dataframe(_record_id, _revision, _revision_digest):
+        return read_dataframe(
+            experiment,
+            _record_id,
+            revision=_revision,
+            revision_digest=_revision_digest,
+            row_limit=200,
+        ).dataframe
+
+    def _load_artifact(_record_id, _revision, _revision_digest, _path):
+        return read_artifact(
+            experiment,
+            _record_id,
+            revision=_revision,
+            revision_digest=_revision_digest,
+            path=_path,
+        ).content
+
+    deliverables_panel = render_notebook_deliverable_viewport(
+        mo,
+        deliverables,
+        deliverable_selector,
+        dataframe_loader=_load_dataframe,
+        artifact_loader=_load_artifact,
+    )
+    return (deliverables_panel,)
+
+
+@app.cell(hide_code=True)
+def _(deliverables_panel, eda_overview_panel, mo):
+    notebook_panel = mo.vstack(
+        [
+            eda_overview_panel,
+            deliverables_panel,
+        ]
+    )
+    return (notebook_panel,)
+
+
+@app.cell(hide_code=True)
+def _(notebook_panel):
+    notebook_panel
+
+
+if __name__ == "__main__":
+    app.run()

reader_workbench/workbench/notebooks/launch.py

@@ -0,0 +1,274 @@
+from __future__ import annotations
+
+import os
+import signal
+import socket
+import sys
+import time
+import webbrowser
+from dataclasses import dataclass
+from pathlib import Path
+
+from reader_workbench.errors import ConfigError
+
+from ._launch_registry import (
+    MarimoSessionRecord,
+)
+from ._launch_registry import (
+    load_registry as _load_registry,
+)
+from ._launch_registry import (
+    prune_registry as _prune_registry,
+)
+from ._launch_registry import (
+    session_matches_current_inputs as _session_matches_current_inputs,
+)
+from ._launch_registry import (
+    write_registry as _write_registry,
+)
+from ._launch_runtime import (
+    MarimoRuntimePaths,
+)
+from ._launch_runtime import (
+    build_env as _build_env,
+)
+from ._launch_runtime import (
+    find_experiment_root as _find_experiment_root,
+)
+from ._launch_runtime import (
+    resolve_repo_root as _resolve_repo_root,
+)
+from ._launch_runtime import (
+    runtime_fingerprint as _runtime_fingerprint,
+)
+from ._launch_runtime import (
+    runtime_paths_for_repo_root as _runtime_paths_for_repo_root,
+)
+from ._launch_runtime import (
+    target_signature as _target_signature,
+)
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 2718
+DEFAULT_PORT_SCAN_LIMIT = 32
+
+
+@dataclass(frozen=True)
+class MarimoLaunchPlan:
+    cmd: tuple[str, ...]
+    env: dict[str, str]
+    url: str
+    port: int
+    host: str
+    target: Path
+    repo_root: Path
+    runtime_paths: MarimoRuntimePaths
+    reused_session: MarimoSessionRecord | None = None
+    terminated_sessions: tuple[MarimoSessionRecord, ...] = ()
+
+
+@dataclass(frozen=True)
+class _LaunchContext:
+    resolved_target: Path
+    experiment_root: Path
+    repo_root: Path
+    notebook_mtime_ns: int
+    notebook_size_bytes: int
+    runtime_fingerprint: str
+
+
+def _pid_is_live(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True
+
+
+def _port_is_open(host: str, port: int, *, timeout: float = 0.15) -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.settimeout(timeout)
+        return sock.connect_ex((host, port)) == 0
+
+
+def _terminate_pid(pid: int, *, grace_seconds: float = 1.0) -> bool:
+    try:
+        os.kill(pid, signal.SIGTERM)
+    except ProcessLookupError:
+        return True
+    except PermissionError:
+        return False
+
+    deadline = time.monotonic() + grace_seconds
+    while time.monotonic() < deadline:
+        if not _pid_is_live(pid):
+            return True
+        time.sleep(0.05)
+
+    try:
+        os.kill(pid, signal.SIGKILL)
+    except ProcessLookupError:
+        return True
+    except PermissionError:
+        return False
+    return not _pid_is_live(pid)
+
+
+def _resolve_launch_context(target: Path, *, repo_root: Path | None = None) -> _LaunchContext:
+    resolved_target = target.resolve()
+    experiment_root = _find_experiment_root(resolved_target)
+    resolved_repo_root = _resolve_repo_root(resolved_target, repo_root=repo_root)
+    notebook_mtime_ns, notebook_size_bytes = _target_signature(resolved_target)
+    return _LaunchContext(
+        resolved_target=resolved_target,
+        experiment_root=experiment_root,
+        repo_root=resolved_repo_root,
+        notebook_mtime_ns=notebook_mtime_ns,
+        notebook_size_bytes=notebook_size_bytes,
+        runtime_fingerprint=_runtime_fingerprint(resolved_repo_root),
+    )
+
+
+def _choose_port(
+    *,
+    host: str,
+    preferred_port: int | None,
+    records: list[MarimoSessionRecord],
+    scan_limit: int = DEFAULT_PORT_SCAN_LIMIT,
+) -> int:
+    occupied_ports = {record.port for record in records if _pid_is_live(record.pid)}
+
+    if preferred_port is not None:
+        if preferred_port in occupied_ports or _port_is_open(host, preferred_port):
+            raise ConfigError(f"Port {preferred_port} is already in use on {host}")
+        return preferred_port
+
+    for port in range(DEFAULT_PORT, DEFAULT_PORT + scan_limit):
+        if port in occupied_ports:
+            continue
+        if not _port_is_open(host, port):
+            return port
+    raise ConfigError(
+        f"No free Marimo port found on {host} in range {DEFAULT_PORT}-{DEFAULT_PORT + scan_limit - 1}. "
+        "Close existing sessions or provide --port."
+    )
+
+
+def plan_marimo_launch(
+    *,
+    mode: str,
+    target: Path,
+    headless: bool = False,
+    preferred_port: int | None = None,
+    base_env: dict[str, str] | None = None,
+    repo_root: Path | None = None,
+) -> MarimoLaunchPlan:
+    context = _resolve_launch_context(target, repo_root=repo_root)
+    runtime_paths = _runtime_paths_for_repo_root(context.repo_root)
+    env = _build_env(context.repo_root, runtime_paths=runtime_paths, base_env=base_env)
+    records = _prune_registry(_load_registry(runtime_paths.registry_path), pid_is_live=_pid_is_live)
+
+    for record in records:
+        if _session_matches_current_inputs(
+            record,
+            mode=mode,
+            resolved_target=context.resolved_target,
+            experiment_root=context.experiment_root,
+            runtime_fingerprint=context.runtime_fingerprint,
+            notebook_mtime_ns=context.notebook_mtime_ns,
+            notebook_size_bytes=context.notebook_size_bytes,
+            port_is_open=lambda host, port: _port_is_open(host, port),
+        ):
+            _write_registry(runtime_paths.registry_path, records)
+            return MarimoLaunchPlan(
+                cmd=(),
+                env=env,
+                url=f"http://{record.host}:{record.port}",
+                port=record.port,
+                host=record.host,
+                target=context.resolved_target,
+                repo_root=context.repo_root,
+                runtime_paths=runtime_paths,
+                reused_session=record,
+            )
+
+    terminated_sessions: list[MarimoSessionRecord] = []
+    kept_records: list[MarimoSessionRecord] = []
+    for record in records:
+        if (
+            record.mode == mode
+            and record.experiment_root == str(context.experiment_root)
+            and _terminate_pid(record.pid)
+        ):
+            terminated_sessions.append(record)
+            continue
+        kept_records.append(record)
+
+    port = _choose_port(host=DEFAULT_HOST, preferred_port=preferred_port, records=kept_records)
+
+    cmd = [sys.executable, "-m", "marimo", mode, "--host", DEFAULT_HOST, "--port", str(port)]
+    if mode == "edit":
+        cmd.append("--skip-update-check")
+    if headless:
+        cmd.append("--headless")
+        cmd.append("--no-token")
+    cmd.append(str(context.resolved_target))
+
+    _write_registry(runtime_paths.registry_path, kept_records)
+    return MarimoLaunchPlan(
+        cmd=tuple(cmd),
+        env=env,
+        url=f"http://{DEFAULT_HOST}:{port}",
+        port=port,
+        host=DEFAULT_HOST,
+        target=context.resolved_target,
+        repo_root=context.repo_root,
+        runtime_paths=runtime_paths,
+        terminated_sessions=tuple(terminated_sessions),
+    )
+
+
+def register_managed_session(
+    *,
+    registry_path: Path,
+    pid: int,
+    port: int,
+    host: str,
+    mode: str,
+    target: Path,
+    repo_root: Path,
+) -> None:
+    records = _prune_registry(_load_registry(registry_path), pid_is_live=_pid_is_live)
+    target_mtime_ns, target_size_bytes = _target_signature(target)
+    resolved_repo_root = _resolve_repo_root(target, repo_root=repo_root)
+    runtime_fingerprint = _runtime_fingerprint(resolved_repo_root)
+    record = MarimoSessionRecord(
+        pid=pid,
+        port=port,
+        host=host,
+        mode=mode,
+        notebook=str(target.resolve()),
+        experiment_root=str(_find_experiment_root(target)),
+        repo_root=str(resolved_repo_root),
+        launched_at=time.time(),
+        notebook_mtime_ns=target_mtime_ns,
+        notebook_size_bytes=target_size_bytes,
+        runtime_fingerprint=runtime_fingerprint,
+    )
+    records = [existing for existing in records if existing.pid != pid]
+    records.append(record)
+    _write_registry(registry_path, records)
+
+
+def unregister_managed_session(*, registry_path: Path, pid: int) -> None:
+    records = _prune_registry(_load_registry(registry_path), pid_is_live=_pid_is_live)
+    _write_registry(registry_path, [record for record in records if record.pid != pid])
+
+
+def open_url(url: str) -> None:
+    try:
+        webbrowser.open(url, new=0, autoraise=True)
+    except Exception:
+        return

reader_workbench/workbench/notebooks/presentation.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import re
+from collections import Counter
+from collections.abc import Mapping
+from datetime import datetime
+from pathlib import Path
+
+from reader_workbench.workbench.config import load_reader_config_document
+
+_DATE_PREFIX = re.compile(r"^(?P<date>\d{8})(?:[_-]+(?P<name>.+))?$")
+_WORD_BREAK = re.compile(r"[_-]+")
+_UPPERCASE_TOKENS = frozenset(
+    {
+        "cfp",
+        "dna",
+        "gfp",
+        "iptg",
+        "od600",
+        "rfp",
+        "rna",
+        "yfp",
+    }
+)
+
+
+def experiment_display_title(*, experiment_id: str, authored_title: str | None = None) -> str:
+    """Resolve a human title without changing the stable experiment identity."""
+
+    stable_id = _required_text(experiment_id, field="experiment_id")
+    title = str(authored_title or "").strip()
+    if title and title != stable_id:
+        return title
+
+    match = _DATE_PREFIX.fullmatch(stable_id)
+    if match is None:
+        return _humanize_slug(stable_id)
+
+    date_label = _date_label(match.group("date"))
+    name = str(match.group("name") or "").strip()
+    if not name:
+        return date_label
+    return f"{date_label} · {_humanize_slug(name)}"
+
+
+def experiment_display_title_from_config(
+    config_path: Path,
+    *,
+    expected_experiment_id: str | None = None,
+) -> str:
+    """Resolve the authored or fallback title from a Reader experiment config."""
+
+    payload = load_reader_config_document(Path(config_path))
+    experiment = payload.get("experiment")
+    if not isinstance(experiment, Mapping):
+        raise ValueError("experiment config must define an experiment mapping.")
+    experiment_id = _required_text(experiment.get("id"), field="experiment.id")
+    authored_title = experiment.get("title")
+    if authored_title is not None and not isinstance(authored_title, str):
+        raise ValueError("experiment.title must be a string when provided.")
+    if expected_experiment_id is not None and experiment_id != expected_experiment_id:
+        raise ValueError(
+            "experiment config identity disagrees with the expected experiment ID: "
+            f"{experiment_id!r} != {expected_experiment_id!r}."
+        )
+    return experiment_display_title(
+        experiment_id=experiment_id,
+        authored_title=authored_title,
+    )
+
+
+def experiment_selector_options(experiment_titles: Mapping[str, str]) -> dict[str, str]:
+    """Map readable selector labels to stable experiment IDs."""
+
+    normalized: dict[str, str] = {}
+    for raw_experiment_id, title in experiment_titles.items():
+        experiment_id = _required_text(raw_experiment_id, field="experiment_id")
+        if experiment_id in normalized:
+            raise ValueError(f"duplicate experiment IDs after normalization: {experiment_id!r}.")
+        normalized[experiment_id] = _required_text(title, field="experiment_title")
+    title_counts = Counter(normalized.values())
+    options: dict[str, str] = {}
+    for experiment_id in sorted(normalized):
+        title = normalized[experiment_id]
+        label = title if title_counts[title] == 1 else f"{title} · {_identity_suffix(experiment_id)}"
+        if label in options:
+            label = f"{title} · {experiment_id}"
+        options[label] = experiment_id
+    if len(options) != len(normalized):
+        raise ValueError("experiment selector labels must be unique.")
+    return options
+
+
+def _humanize_slug(value: str) -> str:
+    words = [word for word in _WORD_BREAK.split(value.strip()) if word]
+    if not words:
+        raise ValueError("experiment_id must contain displayable text.")
+    return " ".join(_display_word(word) for word in words)
+
+
+def _display_word(word: str) -> str:
+    lowered = word.casefold()
+    if lowered in _UPPERCASE_TOKENS:
+        return word.upper()
+    if any(character.isupper() for character in word) and any(character.islower() for character in word):
+        return word
+    if any(character.isdigit() for character in word):
+        return word.upper()
+    return word[:1].upper() + word[1:]
+
+
+def _identity_suffix(experiment_id: str) -> str:
+    match = _DATE_PREFIX.fullmatch(experiment_id)
+    return _date_label(match.group("date")) if match is not None else experiment_id
+
+
+def _date_label(value: str) -> str:
+    try:
+        parsed = datetime.strptime(value, "%Y%m%d")
+    except ValueError:
+        return value
+    return parsed.strftime("%Y-%m-%d")
+
+
+def _required_text(value: object, *, field: str) -> str:
+    text = str(value or "").strip()
+    if not text:
+        raise ValueError(f"{field} is required for notebook presentation.")
+    return text
+
+
+__all__ = [
+    "experiment_display_title",
+    "experiment_display_title_from_config",
+    "experiment_selector_options",
+]

reader_workbench/workbench/notebooks/scaffold.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from importlib.resources import files
+from pathlib import Path
+
+from reader_workbench.errors import ConfigError
+from reader_workbench.workbench.paths import resolve_confined_sink_root, resolve_path_within_root
+
+CANONICAL_NOTEBOOK_ID = "notebook/eda"
+_CANONICAL_NOTEBOOK_SOURCE = "eda.marimo.py.txt"
+
+
+def write_experiment_notebook(
+    target: Path,
+    *,
+    experiment_root: Path,
+    notebooks_root: Path,
+    overwrite: bool = False,
+) -> tuple[Path, bool]:
+    target = _confined_notebook_target(
+        target,
+        experiment_root=experiment_root,
+        notebooks_root=notebooks_root,
+    )
+    if target.exists() and not overwrite:
+        return target, False
+    body = _load_canonical_notebook_body()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(body, encoding="utf-8")
+    return target, True
+
+
+def _load_canonical_notebook_body() -> str:
+    try:
+        return files(__package__).joinpath(_CANONICAL_NOTEBOOK_SOURCE).read_text(encoding="utf-8")
+    except (FileNotFoundError, OSError) as exc:
+        raise ConfigError(f"Canonical notebook source {CANONICAL_NOTEBOOK_ID!r} is unavailable.") from exc
+
+
+def _confined_notebook_target(target: Path, *, experiment_root: Path, notebooks_root: Path) -> Path:
+    try:
+        owned_root = resolve_confined_sink_root(
+            notebooks_root,
+            root=experiment_root,
+            label="notebooks",
+        )
+    except ValueError as exc:
+        raise ConfigError(str(exc)) from exc
+
+    candidate = Path(target).expanduser()
+    if not candidate.is_absolute():
+        candidate = owned_root / candidate
+    candidate = candidate.absolute()
+    if candidate.is_symlink():
+        raise ConfigError(f"Notebook target must not be a symlink: {candidate}")
+    try:
+        resolve_confined_sink_root(candidate.parent, root=owned_root, label="notebook target parent")
+        return resolve_path_within_root(candidate, root=owned_root)
+    except ValueError as exc:
+        raise ConfigError(f"Notebook target must stay within the configured notebooks root: {candidate}") from exc

reader_workbench/workbench/ontology.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+PluginCategory = Literal["ingest", "transform", "plot", "export", "validator"]
+PluginDomain = Literal["generic", "plate_reader", "cytometry", "logic"]
+WorkbenchItemKind = Literal["pipeline", "plot", "export"]
+WorkbenchPluginStepKind = Literal["pipeline", "plot", "export"]
+WorkbenchProducerKind = Literal["pipeline", "plot", "export"]
+WorkbenchRecordKind = Literal["dataframe_artifact", "file_bundle"]
+WorkbenchRefKind = Literal["plugin"]
+
+KNOWN_PLUGIN_DOMAINS: tuple[PluginDomain, ...] = ("generic", "plate_reader", "cytometry", "logic")
+
+
+def validate_plugin_domain(domain: str) -> PluginDomain:
+    normalized = str(domain).strip()
+    if normalized in KNOWN_PLUGIN_DOMAINS:
+        return normalized  # type: ignore[return-value]
+    options = ", ".join(KNOWN_PLUGIN_DOMAINS)
+    raise ValueError(f"Unknown plugin domain '{domain}'. Expected one of: {options}")
+
+
+@dataclass(frozen=True)
+class PluginSemantics:
+    domain: PluginDomain
+    family: str
+    summary: str
+    tags: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "domain", validate_plugin_domain(self.domain))
+
+
+@dataclass(frozen=True)
+class WorkbenchSurfaceSemantics:
+    kind: WorkbenchItemKind
+    section: str
+    title: str
+    item_label: str
+    items_label: str
+    ref_kind: WorkbenchRefKind
+    expected_plugin_category: str | None = None
+
+
+_WORKBENCH_SURFACE_SEMANTICS: dict[WorkbenchItemKind, WorkbenchSurfaceSemantics] = {
+    "pipeline": WorkbenchSurfaceSemantics(
+        kind="pipeline",
+        section="pipeline",
+        title="Pipeline",
+        item_label="pipeline step",
+        items_label="pipeline steps",
+        ref_kind="plugin",
+    ),
+    "plot": WorkbenchSurfaceSemantics(
+        kind="plot",
+        section="plots",
+        title="Plots",
+        item_label="plot spec",
+        items_label="plot specs",
+        ref_kind="plugin",
+        expected_plugin_category="plot",
+    ),
+    "export": WorkbenchSurfaceSemantics(
+        kind="export",
+        section="exports",
+        title="Exports",
+        item_label="export spec",
+        items_label="export specs",
+        ref_kind="plugin",
+        expected_plugin_category="export",
+    ),
+}
+
+
+def get_workbench_surface_semantics(kind: WorkbenchItemKind) -> WorkbenchSurfaceSemantics:
+    return _WORKBENCH_SURFACE_SEMANTICS[kind]