reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/workbench/inspection/runtime.py

@@ -0,0 +1,287 @@
+from __future__ import annotations
+
+from copy import deepcopy
+
+from reader_workbench.runtime import ReaderRuntime
+from reader_workbench.workbench.config import ReaderSpec
+from reader_workbench.workbench.decl import RecordCollectionInputDecl, WorkbenchDecl
+from reader_workbench.workbench.graph import OutputRef, input_ref_display, output_ref_to_dict, resolve_workbench
+from reader_workbench.workbench.records import RecordVerificationScope
+
+
+def plot_output_summaries(bound_protocol) -> dict[str, str]:
+    return {item.id: item.summary for item in bound_protocol.descriptor.figures}
+
+
+def export_output_summaries(bound_protocol) -> dict[str, str]:
+    return {item.id: item.summary for item in bound_protocol.descriptor.artifacts}
+
+
+def selected_plan_payload(*, spec: ReaderSpec, decl: WorkbenchDecl, runtime: ReaderRuntime) -> dict[str, object]:
+    bound_protocol = runtime.bind_protocol(decl.experiment_semantics.protocol)
+    workbench = resolve_workbench(decl)
+    plot_ids = [spec_decl.id for spec_decl in workbench.plots]
+    export_ids = [spec_decl.id for spec_decl in workbench.exports]
+    pipeline_ids = [step.id for step in workbench.pipeline]
+    return {
+        "plot_profile": spec.protocol.outputs.plots.profile or bound_protocol.default_plot_profile or "—",
+        "pipeline": {"count": len(pipeline_ids), "ids": pipeline_ids},
+        "plots": {"count": len(plot_ids), "ids": plot_ids},
+        "exports": {"count": len(export_ids), "ids": export_ids},
+    }
+
+
+def selected_plan_summary(selected: dict[str, object] | None) -> str:
+    if not selected:
+        return "—"
+    pipeline = dict(selected["pipeline"])
+    plots = dict(selected["plots"])
+    exports = dict(selected["exports"])
+    profile = str(selected.get("plot_profile") or "—")
+    return f"{profile} • {pipeline['count']} st • {plots['count']} pl • {exports['count']} ex"
+
+
+def generated_summary(generated: dict[str, int]) -> str:
+    return (
+        f"{generated['records']} rec • "
+        f"{generated['plots']} pl • "
+        f"{generated['exports']} ex • "
+        f"{generated['notebooks']} nb"
+    )
+
+
+def implementation_plan_payload(
+    *,
+    bound_protocol,
+    decl: WorkbenchDecl,
+    pipeline_steps,
+    plot_steps,
+    export_steps,
+) -> dict[str, object]:
+    return {
+        "protocol": bound_protocol.id,
+        "input_sections": sorted(bound_protocol.inputs),
+        "analysis_knobs": sorted(bound_protocol.analysis),
+        "resources": sorted(decl.experiment_semantics.resources.by_id.keys()),
+        "pipeline_flow": [step.id for step in pipeline_steps],
+        "plots": [step.id for step in plot_steps],
+        "exports": [step.id for step in export_steps],
+    }
+
+
+def compiled_workbench_payload(
+    *,
+    bound_protocol,
+    pipeline_steps,
+    plot_steps,
+    export_steps,
+    runtime: ReaderRuntime,
+    record_producers,
+) -> dict[str, object]:
+    plot_summaries = plot_output_summaries(bound_protocol)
+    export_summaries = export_output_summaries(bound_protocol)
+    return {
+        "pipeline": [
+            pipeline_step_payload(step, runtime=runtime, record_producers=record_producers) for step in pipeline_steps
+        ],
+        "plots": [
+            spec_step_payload(
+                step,
+                summary=plot_summaries.get(step.id, "—"),
+                runtime=runtime,
+                record_producers=record_producers,
+            )
+            for step in plot_steps
+        ],
+        "exports": [
+            spec_step_payload(
+                step,
+                summary=export_summaries.get(step.id, "—"),
+                runtime=runtime,
+                record_producers=record_producers,
+            )
+            for step in export_steps
+        ],
+    }
+
+
+def record_producer_map(steps, *, runtime: ReaderRuntime) -> dict[str, dict[str, object]]:
+    producers: dict[str, dict[str, object]] = {}
+    for step in steps:
+        plugin_cls = runtime.plugins.resolve_descriptor(step.plugin).cls
+        for output_name, port in plugin_cls.output_ports().items():
+            if port.kind != "dataframe":
+                continue
+            record_ref = (step.writes or {}).get(output_name, OutputRef(record_id=f"{step.id}/{output_name}"))
+            producers[record_ref.record_id] = {
+                "producer": {"id": step.id, "plugin": step.plugin, "stage": step.plugin.split("/", 1)[0]},
+                "output": output_name,
+                "contract": port.contract,
+                "surface": _output_surface_payload(port),
+            }
+    return producers
+
+
+def workbench_record_verification_scope(workbench, *, runtime: ReaderRuntime) -> RecordVerificationScope:
+    return RecordVerificationScope(record_ids=workbench_record_ids(workbench, runtime=runtime))
+
+
+def workbench_record_ids(workbench, *, runtime: ReaderRuntime) -> frozenset[str]:
+    """Return record identities owned by the current compiled workbench."""
+
+    record_ids = set(record_producer_map(workbench.plugin_steps(), runtime=runtime))
+    record_ids.update(f"plot:{step.id}" for step in workbench.plots)
+    record_ids.update(f"export:{step.id}" for step in workbench.exports)
+    return frozenset(record_ids)
+
+
+def pipeline_step_payload(step, *, runtime: ReaderRuntime, record_producers=None) -> dict[str, object]:
+    plugin_cls = runtime.plugins.resolve_descriptor(step.plugin).cls
+    return {
+        "stage": step.plugin.split("/", 1)[0],
+        "id": step.id,
+        "plugin": step.plugin,
+        "semantics": plugin_semantics_payload(step.plugin, runtime=runtime),
+        "reads": serialize_reads(
+            step.reads, declared_ports=plugin_cls.input_ports(), record_producers=record_producers
+        ),
+        "writes": pipeline_writes_payload(step, runtime=runtime),
+    }
+
+
+def spec_step_payload(step, *, summary: str, runtime: ReaderRuntime, record_producers=None) -> dict[str, object]:
+    plugin_cls = runtime.plugins.resolve_descriptor(step.plugin).cls
+    return {
+        "id": step.id,
+        "plugin": step.plugin,
+        "summary": summary,
+        "semantics": plugin_semantics_payload(step.plugin, runtime=runtime),
+        "reads": serialize_reads(
+            step.reads, declared_ports=plugin_cls.input_ports(), record_producers=record_producers
+        ),
+    }
+
+
+def render_read_binding(item: dict[str, object]) -> str:
+    rendered = f"{item['label']} <- {item['display']}"
+    source = item.get("source")
+    if not isinstance(source, dict):
+        return rendered
+    surface = source.get("surface")
+    if not isinstance(surface, dict):
+        return rendered
+    producer = source.get("producer")
+    producer_id = producer.get("id") if isinstance(producer, dict) else None
+    if not isinstance(producer_id, str) or not producer_id:
+        return rendered
+    mode = surface.get("runtime_mode")
+    promoted = [str(value) for value in (surface.get("promoted") or []) if str(value).strip()]
+    contract = item.get("contract")
+    if mode == "promoted" and promoted:
+        return f"{rendered} (via {producer_id}; may promote to {', '.join(promoted)})"
+    if mode == "passthrough" and isinstance(contract, str) and contract in promoted:
+        return f"{rendered} (via {producer_id}; preserves {contract})"
+    return rendered
+
+
+def plugin_semantics_payload(plugin: str, *, runtime: ReaderRuntime) -> dict[str, object]:
+    descriptor = runtime.plugins.resolve_descriptor(plugin)
+    return {
+        "category": descriptor.category,
+        "domain": descriptor.domain,
+        "family": descriptor.family,
+        "summary": descriptor.summary,
+    }
+
+
+def serialize_reads(reads, *, declared_ports=None, record_producers=None) -> list[dict[str, object]]:
+    payload: list[dict[str, object]] = []
+    for label, ref in (reads or {}).items():
+        item: dict[str, object] = {"label": label, "display": _binding_display(ref)}
+        record_id = getattr(ref, "record_id", None)
+        resource_id = getattr(ref, "resource_id", None)
+        path = getattr(ref, "path", None)
+        if isinstance(record_id, str) and record_id:
+            item["ref"] = {"record": record_id}
+            if record_producers and record_id in record_producers:
+                item["source"] = deepcopy(record_producers[record_id])
+        elif isinstance(resource_id, str) and resource_id:
+            item["ref"] = {"resource": resource_id}
+        elif isinstance(ref, RecordCollectionInputDecl):
+            item["ref"] = {"record_resources": list(ref.resource_ids)}
+        elif path is not None:
+            item["ref"] = {"file": str(path)}
+        else:
+            item["ref"] = {"display": _binding_display(ref)}
+        declared_port = (declared_ports or {}).get(label)
+        if declared_port is not None:
+            item["kind"] = declared_port.kind
+            item["declared"] = declared_port.render()
+            if declared_port.contract is not None:
+                item["contract"] = declared_port.contract
+            if declared_port.optional:
+                item["optional"] = True
+        payload.append(item)
+    return payload
+
+
+def pipeline_writes_payload(step, *, runtime: ReaderRuntime) -> list[dict[str, object]]:
+    plugin_cls = runtime.plugins.resolve_descriptor(step.plugin).cls
+    outputs: list[dict[str, object]] = []
+    for output_name, port in plugin_cls.output_ports().items():
+        if port.kind == "dataframe":
+            record_ref = (step.writes or {}).get(output_name, OutputRef(record_id=f"{step.id}/{output_name}"))
+            output: dict[str, object] = {
+                "label": output_name,
+                "kind": port.kind,
+                "declared": port.render(),
+                "display": record_ref.record_id,
+                "contract": port.contract,
+                "ref": output_ref_to_dict(record_ref),
+            }
+            surface = _output_surface_payload(port)
+            if surface is not None:
+                output["surface"] = surface
+            outputs.append(output)
+            continue
+        outputs.append(
+            {
+                "label": output_name,
+                "kind": port.kind,
+                "declared": port.render(),
+                "display": output_name,
+            }
+        )
+    return outputs
+
+
+def binding_display(ref) -> str:
+    return _binding_display(ref)
+
+
+def _binding_display(ref) -> str:
+    if isinstance(ref, RecordCollectionInputDecl):
+        return "record_resources(" + ", ".join(ref.resource_ids) + ")"
+    record_id = getattr(ref, "record_id", None)
+    if isinstance(record_id, str) and record_id:
+        return record_id
+    resource_id = getattr(ref, "resource_id", None)
+    if isinstance(resource_id, str) and resource_id:
+        return f"resource({resource_id})"
+    path = getattr(ref, "path", None)
+    if path is not None:
+        return str(path)
+    return input_ref_display(ref)
+
+
+def _output_surface_payload(port) -> dict[str, object] | None:
+    surface = getattr(port, "contract_surface", None)
+    if surface is None:
+        return None
+    return {
+        "minimum": surface.minimum,
+        "runtime_mode": surface.runtime_mode,
+        "promoted": list(surface.promoted),
+        "note": surface.note,
+        "rendered": surface.render(),
+    }

reader_workbench/workbench/inspection/semantics.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+from rich import box
+from rich.table import Table
+
+
+def _table(title: str) -> Table:
+    return Table(
+        title=f"[title]{title}[/title]",
+        title_justify="left",
+        header_style="bold",
+        box=box.ROUNDED,
+        expand=True,
+        show_lines=False,
+        show_edge=True,
+    )
+
+
+def semantic_node_payload(node, *, include_execution: bool = True) -> dict[str, object]:
+    payload = {
+        "id": node.id,
+        "kind": node.kind,
+        "summary": node.summary,
+        "profiles": list(node.profiles),
+    }
+    if include_execution:
+        payload["execution"] = {
+            "status": node.execution.status,
+            "step_ids": list(node.execution.step_ids),
+            "plugin_ids": list(node.execution.plugin_ids),
+            "record_ids": list(node.execution.record_ids),
+            "config_paths": list(node.execution.config_paths),
+            "note": node.execution.note,
+        }
+    if node.kind == "control_rule":
+        payload["match_on"] = list(node.match_on)
+        payload["control_selector"] = node.control_selector
+    if node.kind == "window":
+        payload["anchor"] = node.anchor
+        payload["selector"] = node.selector
+        payload["params"] = dict(node.params)
+    if node.kind == "metric":
+        payload["stage"] = node.stage
+        payload["formula"] = node.formula
+        payload["depends_on"] = list(node.depends_on)
+        payload["value_space"] = node.value_space
+        payload["unit"] = node.unit
+        payload["comparable_group"] = node.comparable_group
+    if node.kind == "ranking":
+        payload["primary_metric"] = node.primary_metric
+        payload["direction"] = node.direction
+        payload["penalties"] = list(node.penalties)
+        payload["supporting_metrics"] = list(node.supporting_metrics)
+    return payload
+
+
+def semantic_program_structure_summary(program) -> dict[str, object]:
+    summary = {
+        "total": 0,
+        "by_kind": {
+            "control_rule": 0,
+            "window": 0,
+            "metric": 0,
+            "ranking": 0,
+        },
+    }
+
+    def _record(node) -> None:
+        summary["total"] += 1
+        summary["by_kind"][str(node.kind)] += 1
+
+    for node in program.controls:
+        _record(node)
+    for node in program.windows:
+        _record(node)
+    for node in program.metrics:
+        _record(node)
+    if program.ranking is not None:
+        _record(program.ranking)
+    return summary
+
+
+def semantic_program_execution_summary(program) -> dict[str, object]:
+    summary = {
+        "total": 0,
+        "compiled": 0,
+        "descriptive_only": 0,
+        "by_kind": {
+            "control_rule": {"total": 0, "compiled": 0, "descriptive_only": 0},
+            "window": {"total": 0, "compiled": 0, "descriptive_only": 0},
+            "metric": {"total": 0, "compiled": 0, "descriptive_only": 0},
+            "ranking": {"total": 0, "compiled": 0, "descriptive_only": 0},
+        },
+    }
+
+    def _record(node) -> None:
+        status = str(node.execution.status)
+        kind = str(node.kind)
+        summary["total"] += 1
+        summary[status] += 1
+        kind_counts = dict(summary["by_kind"][kind])
+        kind_counts["total"] += 1
+        kind_counts[status] += 1
+        summary["by_kind"][kind] = kind_counts
+
+    for node in program.controls:
+        _record(node)
+    for node in program.windows:
+        _record(node)
+    for node in program.metrics:
+        _record(node)
+    if program.ranking is not None:
+        _record(program.ranking)
+    return summary
+
+
+def semantic_program_payload(program, *, include_execution: bool = True) -> dict[str, object]:
+    return {
+        "protocol": program.protocol,
+        "profiles": [
+            {
+                "id": profile.id,
+                "family": profile.family,
+                "summary": profile.summary,
+                "primary_metric": profile.primary_metric,
+                "primary_readout": profile.primary_readout,
+                "tags": list(profile.tags),
+            }
+            for profile in program.profiles
+        ],
+        "active_profile": program.active_profile,
+        "summary": (
+            semantic_program_execution_summary(program)
+            if include_execution
+            else semantic_program_structure_summary(program)
+        ),
+        "controls": [semantic_node_payload(node, include_execution=include_execution) for node in program.controls],
+        "windows": [semantic_node_payload(node, include_execution=include_execution) for node in program.windows],
+        "metrics": [semantic_node_payload(node, include_execution=include_execution) for node in program.metrics],
+        "ranking": (
+            semantic_node_payload(program.ranking, include_execution=include_execution)
+            if program.ranking is not None
+            else None
+        ),
+    }
+
+
+def semantic_program_table(
+    program,
+    *,
+    title: str = "Semantic Program",
+    include_execution: bool = True,
+) -> Table:
+    profile_text = f" • profile: {program.active_profile}" if program.active_profile else ""
+    if include_execution:
+        coverage = semantic_program_execution_summary(program)
+        table = _table(
+            f"{title}{profile_text} • {coverage['compiled']}/{coverage['total']} compiled"
+            f" • {coverage['descriptive_only']} descriptive"
+        )
+        table.add_column("kind", style="accent", width=13)
+        table.add_column("id", style="accent", overflow="fold")
+        table.add_column("status", width=18)
+        table.add_column("compiled via", overflow="fold")
+        table.add_column("summary", overflow="fold")
+
+        def _add_node(kind: str, node) -> None:
+            compiled_via = ", ".join(node.execution.step_ids) or "—"
+            note = node.execution.note
+            summary = node.summary if not note else f"{node.summary} ({note})"
+            table.add_row(kind, node.id, node.execution.status, compiled_via, summary)
+    else:
+        coverage = semantic_program_structure_summary(program)
+        table = _table(f"{title}{profile_text} • {coverage['total']} node(s)")
+        table.add_column("kind", style="accent", width=13)
+        table.add_column("id", style="accent", overflow="fold")
+        table.add_column("profiles", overflow="fold")
+        table.add_column("summary", overflow="fold")
+
+        def _add_node(kind: str, node) -> None:
+            profiles = ", ".join(node.profiles) or "all"
+            table.add_row(kind, node.id, profiles, node.summary)
+
+    for node in program.controls:
+        _add_node("control_rule", node)
+    for node in program.windows:
+        _add_node("window", node)
+    for node in program.metrics:
+        _add_node("metric", node)
+    if program.ranking is not None:
+        _add_node("ranking", program.ranking)
+    return table

reader_workbench/workbench/inspection/validation.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+
+def validation_surface_payload(
+    *,
+    experiment: dict[str, object],
+    check_files: bool,
+    summary: dict[str, Any],
+) -> dict[str, object]:
+    payload = deepcopy(summary)
+    return {
+        "experiment": deepcopy(experiment),
+        "selection": {
+            "check_files": check_files,
+        },
+        "summary": {
+            "status": payload.pop("status"),
+            "checks": payload.pop("checks"),
+            "counts": payload.pop("counts"),
+        },
+        "validation": {
+            "files": payload.pop("files"),
+            "dependencies": payload.pop("dependencies"),
+            "errors": payload.pop("errors"),
+            "tip": payload.pop("tip"),
+        },
+    }

reader_workbench/workbench/notebooks/__init__.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import importlib
+
+_EXPORTS = {
+    "scaffold": {"CANONICAL_NOTEBOOK_ID", "write_experiment_notebook"},
+}
+
+__all__ = tuple(sorted({name for names in _EXPORTS.values() for name in names}))
+
+
+def __getattr__(name: str):
+    for module_name, names in _EXPORTS.items():
+        if name in names:
+            module = importlib.import_module(f"reader_workbench.workbench.notebooks.{module_name}")
+            return getattr(module, name)
+    raise AttributeError(name)

reader_workbench/workbench/notebooks/_launch_registry.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class MarimoSessionRecord:
+    pid: int
+    port: int
+    host: str
+    mode: str
+    notebook: str
+    experiment_root: str
+    repo_root: str
+    launched_at: float
+    notebook_mtime_ns: int | None = None
+    notebook_size_bytes: int | None = None
+    runtime_fingerprint: str | None = None
+
+    @classmethod
+    def from_dict(cls, payload: dict[str, object]) -> MarimoSessionRecord | None:
+        try:
+            return cls(
+                pid=int(payload["pid"]),
+                port=int(payload["port"]),
+                host=str(payload["host"]),
+                mode=str(payload["mode"]),
+                notebook=str(payload["notebook"]),
+                experiment_root=str(payload["experiment_root"]),
+                repo_root=str(payload["repo_root"]),
+                launched_at=float(payload["launched_at"]),
+                notebook_mtime_ns=(
+                    int(payload["notebook_mtime_ns"]) if payload.get("notebook_mtime_ns") is not None else None
+                ),
+                notebook_size_bytes=(
+                    int(payload["notebook_size_bytes"]) if payload.get("notebook_size_bytes") is not None else None
+                ),
+                runtime_fingerprint=(
+                    str(payload["runtime_fingerprint"]) if payload.get("runtime_fingerprint") is not None else None
+                ),
+            )
+        except (KeyError, TypeError, ValueError):
+            return None
+
+
+def load_registry(registry_path: Path) -> list[MarimoSessionRecord]:
+    if not registry_path.exists():
+        return []
+    try:
+        payload = json.loads(registry_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return []
+    if not isinstance(payload, list):
+        return []
+    records: list[MarimoSessionRecord] = []
+    for item in payload:
+        if isinstance(item, dict):
+            record = MarimoSessionRecord.from_dict(item)
+            if record is not None:
+                records.append(record)
+    return records
+
+
+def write_registry(registry_path: Path, records: list[MarimoSessionRecord]) -> None:
+    registry_path.parent.mkdir(parents=True, exist_ok=True)
+    payload = [asdict(record) for record in records]
+    registry_path.write_text(json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8")
+
+
+def prune_registry(
+    records: list[MarimoSessionRecord],
+    *,
+    pid_is_live: Callable[[int], bool],
+) -> list[MarimoSessionRecord]:
+    pruned: list[MarimoSessionRecord] = []
+    for record in records:
+        notebook_path = Path(record.notebook)
+        if not notebook_path.exists():
+            continue
+        if not pid_is_live(record.pid):
+            continue
+        pruned.append(record)
+    return pruned
+
+
+def session_matches_current_inputs(
+    record: MarimoSessionRecord,
+    *,
+    mode: str,
+    resolved_target: Path,
+    experiment_root: Path,
+    runtime_fingerprint: str,
+    notebook_mtime_ns: int,
+    notebook_size_bytes: int,
+    port_is_open: Callable[[str, int], bool],
+) -> bool:
+    if record.mode != mode:
+        return False
+    if record.notebook != str(resolved_target):
+        return False
+    if record.experiment_root != str(experiment_root):
+        return False
+    if record.notebook_mtime_ns != notebook_mtime_ns:
+        return False
+    if record.notebook_size_bytes != notebook_size_bytes:
+        return False
+    if record.runtime_fingerprint != runtime_fingerprint:
+        return False
+    return port_is_open(record.host, record.port)