reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/workbench/inspection/protocols.py

@@ -0,0 +1,368 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+import yaml
+from rich import box
+from rich.table import Table
+
+from reader_workbench.errors import ConfigError
+from reader_workbench.protocols import ProtocolBinding
+from reader_workbench.protocols.model import ProtocolAnalysisChoiceRef, ProtocolBindingValueRef
+
+from .runtime import compiled_workbench_payload, record_producer_map
+from .semantics import semantic_program_payload
+
+PROTOCOL_DESCRIPTOR_SECTIONS = ("identity", "authoring", "semantics", "defaults", "compiled")
+_PROTOCOL_IDENTITY_FIELDS = ("protocol", "domain", "family", "summary", "tags")
+
+
+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 protocol_surface_rows(fields) -> list[tuple[str, str, str, str, str]]:
+    rows: list[tuple[str, str, str, str, str]] = []
+    for field in fields:
+        rows.extend(field.iter_rows())
+    return rows
+
+
+def _protocol_field_payload(field, *, prefix: str = "") -> dict[str, object]:
+    path = f"{prefix}{field.key}"
+    payload: dict[str, object] = {
+        "key": field.key,
+        "path": path,
+        "kind": field.kind,
+        "summary": field.summary,
+        "required": field.required,
+        "allow_none": field.allow_none,
+        "allow_unknown": field.allow_unknown,
+    }
+    if field.has_default:
+        payload["default"] = deepcopy(field.default)
+    if field.has_example:
+        payload["example"] = deepcopy(field.example)
+    if field.choices:
+        payload["choices"] = list(field.choices)
+    if field.children:
+        payload["children"] = [_protocol_field_payload(child, prefix=f"{path}.") for child in field.children]
+    return payload
+
+
+def protocol_surface_payload(fields) -> list[dict[str, object]]:
+    return [_protocol_field_payload(field) for field in fields]
+
+
+def protocol_surface_table(title: str, rows: list[tuple[str, str, str, str, str]]) -> Table:
+    table = _table(title)
+    table.add_column("Path", style="accent")
+    table.add_column("Type")
+    table.add_column("Required", justify="center")
+    table.add_column("Default")
+    table.add_column("Summary")
+    for path, kind, required, default, summary in rows:
+        table.add_row(path, kind, required, default, summary)
+    return table
+
+
+def protocol_plot_profiles_table(descriptor) -> Table:
+    table = _table("Plot Profiles")
+    table.add_column("id", style="accent")
+    table.add_column("figures")
+    table.add_column("summary")
+    for item in descriptor.plot_profiles:
+        table.add_row(item.id, ", ".join(item.figures), item.summary)
+    return table
+
+
+def protocol_plot_outputs_table(descriptor) -> Table:
+    table = _table("Plot Outputs")
+    table.add_column("id", style="accent")
+    table.add_column("kind")
+    table.add_column("primary", justify="center")
+    table.add_column("summary")
+    for item in descriptor.figures:
+        table.add_row(item.id, item.kind, "yes" if item.primary else "no", item.summary)
+    return table
+
+
+def protocol_artifacts_table(descriptor) -> Table:
+    table = _table("Export Artifacts")
+    table.add_column("id", style="accent")
+    table.add_column("summary")
+    for item in descriptor.artifacts:
+        table.add_row(item.id, item.summary)
+    return table
+
+
+def protocol_pipeline_table(steps) -> Table:
+    table = _table("Default Pipeline")
+    table.add_column("#", justify="right", style="muted")
+    table.add_column("stage", style="accent")
+    table.add_column("id", overflow="fold")
+    table.add_column("plugin", overflow="fold")
+    for idx, step in enumerate(steps, 1):
+        stage = step.plugin.split("/", 1)[0]
+        table.add_row(str(idx), stage, step.id, step.plugin)
+    return table
+
+
+def protocol_surface_impl_table(title: str, steps, summaries: dict[str, str], *, binding_display) -> Table:
+    table = _table(title)
+    table.add_column("id", style="accent", overflow="fold")
+    table.add_column("plugin", overflow="fold")
+    table.add_column("from", overflow="fold")
+    table.add_column("summary", overflow="fold")
+    for step in steps:
+        from_refs = ", ".join(f"{label} <- {binding_display(ref)}" for label, ref in (step.reads or {}).items()) or "—"
+        table.add_row(step.id, step.plugin, from_refs, summaries.get(step.id, "—"))
+    return table
+
+
+_EXAMPLE_OMIT = object()
+
+
+def _protocol_field_example_value(field) -> object:
+    if field.has_example:
+        return deepcopy(field.example)
+    if field.kind == "mapping":
+        example: dict[str, object] = {}
+        for child in field.children:
+            child_value = _protocol_field_example_value(child)
+            if child_value is _EXAMPLE_OMIT:
+                continue
+            example[child.key] = child_value
+        if example:
+            return example
+        if field.has_default:
+            return deepcopy(field.default)
+        if field.required:
+            return {}
+        return _EXAMPLE_OMIT
+    if field.has_default:
+        return deepcopy(field.default)
+    if field.required:
+        return "<required>"
+    return _EXAMPLE_OMIT
+
+
+def _protocol_surface_example(fields) -> dict[str, object]:
+    example: dict[str, object] = {}
+    for field in fields:
+        value = _protocol_field_example_value(field)
+        if value is _EXAMPLE_OMIT:
+            continue
+        example[field.key] = value
+    return example
+
+
+def protocol_authoring_output_payload(descriptor) -> dict[str, object]:
+    return {
+        "default_plot_profile": descriptor.default_plot_profile,
+        "plot_profiles": [
+            {
+                "id": item.id,
+                "figures": list(item.figures),
+                "summary": item.summary,
+            }
+            for item in descriptor.plot_profiles
+        ],
+        "figures": [
+            {
+                "id": item.id,
+                "kind": item.kind,
+                "primary": item.primary,
+                "summary": item.summary,
+            }
+            for item in descriptor.figures
+        ],
+        "artifacts": [
+            {
+                "id": item.id,
+                "summary": item.summary,
+                "default": item.default,
+            }
+            for item in descriptor.artifacts
+        ],
+    }
+
+
+def protocol_example_document(descriptor) -> dict[str, object]:
+    protocol_block: dict[str, object] = {"id": descriptor.protocol}
+    inputs = _protocol_surface_example(descriptor.input_fields)
+    if inputs:
+        protocol_block["inputs"] = inputs
+    analysis = _protocol_surface_example(descriptor.analysis_fields)
+    if analysis:
+        protocol_block["analysis"] = analysis
+
+    outputs: dict[str, object] = {}
+    if descriptor.plot_profiles or descriptor.figures:
+        plots: dict[str, object] = {}
+        if descriptor.default_plot_profile is not None:
+            plots["profile"] = descriptor.default_plot_profile
+        elif descriptor.figures:
+            plots["include"] = [item.id for item in descriptor.figures if item.primary]
+        if plots:
+            outputs["plots"] = plots
+    default_artifacts = [item.id for item in descriptor.artifacts if item.default]
+    if default_artifacts:
+        outputs["exports"] = {"include": default_artifacts}
+    protocol_block["outputs"] = outputs
+
+    return {
+        "schema": "reader/v8",
+        "experiment": {"id": "example_experiment"},
+        "protocol": protocol_block,
+        "resources": {item.id: {"kind": item.kind, "path": item.path} for item in descriptor.resources},
+        "annotations": deepcopy(descriptor.example_annotations),
+    }
+
+
+def protocol_example_config(descriptor) -> str:
+    return yaml.safe_dump(protocol_example_document(descriptor), sort_keys=False)
+
+
+def _runtime_default_value_payload(value: Any) -> Any:
+    if isinstance(value, ProtocolBindingValueRef):
+        payload: dict[str, object] = {
+            "source": f"protocol.inputs.{value.key}",
+        }
+        if value.has_default:
+            payload["default"] = _runtime_default_value_payload(value.default)
+        else:
+            payload["required"] = True
+        return payload
+    if isinstance(value, ProtocolAnalysisChoiceRef):
+        payload: dict[str, object] = {
+            "source": f"protocol.analysis.{value.key}",
+            "cases": {key: _runtime_default_value_payload(item) for key, item in value.cases.items()},
+        }
+        if value.has_default:
+            payload["default"] = _runtime_default_value_payload(value.default)
+        else:
+            payload["required"] = True
+        return payload
+    if isinstance(value, dict):
+        return {key: _runtime_default_value_payload(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_runtime_default_value_payload(item) for item in value]
+    if isinstance(value, tuple):
+        return [_runtime_default_value_payload(item) for item in value]
+    return deepcopy(value)
+
+
+def protocol_runtime_defaults_payload(plugin_defaults) -> list[dict[str, object]]:
+    return [
+        {
+            "plugin": item.plugin,
+            "summary": item.summary,
+            "parameters": _runtime_default_value_payload(item.with_),
+        }
+        for item in plugin_defaults
+    ]
+
+
+def protocol_descriptor_payload(descriptor, *, runtime) -> dict[str, object]:
+    try:
+        bound_protocol = runtime.bind_protocol(ProtocolBinding(id=descriptor.protocol))
+    except ConfigError as exc:
+        semantic_program = descriptor.semantic_program()
+        compiled_payload = {
+            "status": "requires_authoring",
+            "reason": str(exc),
+            "pipeline": [],
+            "plots": [],
+            "exports": [],
+            "semantic_program": semantic_program_payload(semantic_program),
+        }
+    else:
+        compiled_plan = bound_protocol.compile()
+        semantic_program = compiled_plan.semantic_program
+        record_producers = record_producer_map(compiled_plan.pipeline, runtime=runtime)
+        compiled_payload = compiled_workbench_payload(
+            bound_protocol=bound_protocol,
+            pipeline_steps=compiled_plan.pipeline,
+            plot_steps=compiled_plan.plots,
+            export_steps=compiled_plan.exports,
+            runtime=runtime,
+            record_producers=record_producers,
+        )
+        compiled_payload["semantic_program"] = semantic_program_payload(semantic_program)
+    return {
+        "protocol": descriptor.protocol,
+        "domain": descriptor.domain,
+        "family": descriptor.family,
+        "summary": descriptor.summary,
+        "tags": list(descriptor.tags),
+        "authoring": {
+            "inputs": protocol_surface_payload(descriptor.input_fields),
+            "analysis": protocol_surface_payload(descriptor.analysis_fields),
+            "resources": [
+                {
+                    "id": item.id,
+                    "kind": item.kind,
+                    "path": item.path,
+                    "summary": item.summary,
+                }
+                for item in descriptor.resources
+            ],
+            "outputs": protocol_authoring_output_payload(descriptor),
+            "starter_config": protocol_example_document(descriptor),
+        },
+        "semantics": {
+            "factors": [
+                {
+                    "name": item.name,
+                    "role": item.role,
+                    "summary": item.summary,
+                    "required": item.required,
+                    "repeatable": item.repeatable,
+                }
+                for item in descriptor.factors
+            ],
+            "effect_signs": [
+                {
+                    "target": item.target,
+                    "expected_sign": item.expected_sign,
+                    "summary": item.summary,
+                }
+                for item in descriptor.effect_signs
+            ],
+            "program": semantic_program_payload(semantic_program, include_execution=False),
+        },
+        "implementation": {
+            "defaults": protocol_runtime_defaults_payload(descriptor.execution.plugin_defaults),
+            "compiled": compiled_payload,
+        },
+    }
+
+
+def protocol_descriptor_section_payload(
+    payload: dict[str, object],
+    *,
+    section: str,
+) -> dict[str, object]:
+    """Project a protocol descriptor through a stable semantic section name."""
+
+    if section not in PROTOCOL_DESCRIPTOR_SECTIONS:
+        raise ValueError(f"Unknown protocol descriptor section {section!r}")
+    projected = {field: deepcopy(payload[field]) for field in _PROTOCOL_IDENTITY_FIELDS}
+    if section in {"authoring", "semantics"}:
+        projected[section] = deepcopy(payload[section])
+    elif section != "identity":
+        implementation = payload["implementation"]
+        if not isinstance(implementation, dict):
+            raise ValueError("Protocol descriptor payload does not contain implementation details")
+        projected[section] = deepcopy(implementation[section])
+    return projected

reader_workbench/workbench/inspection/readiness.py

@@ -0,0 +1,333 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from pathlib import Path
+
+from reader_workbench.errors import RecordError
+from reader_workbench.runtime import ReaderRuntime
+from reader_workbench.workbench.commands import reader_command
+from reader_workbench.workbench.decl import WorkbenchDecl
+from reader_workbench.workbench.engine.planning import build_next_steps
+from reader_workbench.workbench.engine.validation import validation_summary
+from reader_workbench.workbench.graph import RecordRef, resolve_workbench
+from reader_workbench.workbench.records import verify_record_store
+
+from .common import summarize_outputs_dir
+from .runtime import workbench_record_verification_scope
+
+READINESS_STATES = frozenset(
+    {
+        "config_error",
+        "draft",
+        "template",
+        "dependency_blocked",
+        "blocked",
+        "runnable",
+        "uncataloged_outputs_present",
+        "catalog_ready",
+        "records_ready",
+    }
+)
+READINESS_CAPABILITY_KEYS = frozenset(
+    {
+        "run",
+        "records",
+        "verify",
+        "plot",
+        "export",
+        "notebook_scaffold",
+        "notebook_read_records",
+    }
+)
+
+
+def config_error_readiness_payload(error: str) -> dict[str, object]:
+    return {
+        "state": "config_error",
+        "summary": "config error",
+        "preflight": {
+            "status": "error",
+            "issues": 1,
+            "files": "not checked",
+            "dependencies": "not checked",
+        },
+        "records": {
+            "catalog": False,
+            "available": False,
+            "verification": None,
+            "uncataloged_outputs_present": False,
+        },
+        "capabilities": {
+            "run": False,
+            "records": False,
+            "verify": False,
+            "plot": False,
+            "export": False,
+            "notebook_scaffold": False,
+            "notebook_read_records": False,
+        },
+        "errors": [error],
+        "next_steps": [],
+    }
+
+
+def _non_active_lifecycle_payload(*, lifecycle: str, job_path: Path) -> dict[str, object]:
+    next_step = {
+        "command": reader_command("validate", job_path, "--no-files", "--format", "json"),
+        "description": "Check the config shape without treating this non-active experiment as ready to run.",
+    }
+    summary_by_lifecycle = {
+        "draft": "draft experiment; add inputs and switch lifecycle to active when ready",
+        "template": "template scaffold; copy/customize before treating it as a runnable experiment",
+    }
+    return {
+        "state": lifecycle,
+        "summary": summary_by_lifecycle.get(lifecycle, lifecycle),
+        "preflight": {
+            "status": "skipped",
+            "issues": 0,
+            "files": "not evaluated for non-active lifecycle",
+            "dependencies": "not evaluated for non-active lifecycle",
+        },
+        "records": {
+            "catalog": False,
+            "available": False,
+            "verification": None,
+            "uncataloged_outputs_present": False,
+        },
+        "capabilities": {
+            "run": False,
+            "records": False,
+            "verify": False,
+            "plot": False,
+            "export": False,
+            "notebook_scaffold": True,
+            "notebook_read_records": False,
+        },
+        "errors": [],
+        "next_steps": [next_step],
+    }
+
+
+def readiness_summary_text(payload: dict[str, object] | None) -> str:
+    if not isinstance(payload, dict):
+        return "—"
+    summary = str(payload.get("summary") or "").strip()
+    return summary or str(payload.get("state") or "—")
+
+
+def readiness_primary_command(payload: dict[str, object] | None) -> str:
+    if not isinstance(payload, dict):
+        return "—"
+    next_steps = payload.get("next_steps") or []
+    if not isinstance(next_steps, list) or not next_steps:
+        return "—"
+    first = next_steps[0]
+    if not isinstance(first, dict):
+        return "—"
+    command = str(first.get("command") or "").strip()
+    return command or "—"
+
+
+def _surface_record_dependencies_verified(steps, verification_report: dict[str, object] | None) -> bool:
+    required_record_ids = {
+        ref.record_id for step in steps for ref in (step.reads or {}).values() if isinstance(ref, RecordRef)
+    }
+    if not verification_report or verification_report.get("status") != "ok":
+        return False
+    if not required_record_ids:
+        return True
+    record_statuses = {
+        str(record.get("record_id")): record.get("status")
+        for record in verification_report.get("records", [])
+        if isinstance(record, dict)
+    }
+    return all(record_statuses.get(record_id) == "ok" for record_id in required_record_ids)
+
+
+def experiment_readiness_payload(
+    *,
+    job_path: Path,
+    decl: WorkbenchDecl,
+    runtime: ReaderRuntime,
+    check_files: bool = True,
+) -> dict[str, object]:
+    if decl.experiment.lifecycle != "active":
+        return _non_active_lifecycle_payload(lifecycle=decl.experiment.lifecycle, job_path=job_path)
+
+    summary = validation_summary(
+        decl,
+        check_files=check_files,
+        exp_root=decl.experiment.root,
+        runtime=runtime,
+    )
+    layout = decl.experiment_semantics.layout
+    workbench = resolve_workbench(decl)
+    outputs_dir = layout.outputs_dir
+    store = runtime.record_store(
+        outputs_dir,
+        plots_subdir=layout.plots_subdir,
+        exports_subdir=layout.exports_subdir,
+        experiment_root=decl.experiment.root,
+        create=False,
+    )
+    records_catalog = store.catalog_exists()
+    records_available = False
+    record_catalog_error: str | None = None
+    verification_report: dict[str, object] | None = None
+    verification_scope = workbench_record_verification_scope(workbench, runtime=runtime)
+    if records_catalog:
+        try:
+            current_records = tuple(
+                record for record in store.iter_latest_records() if verification_scope.includes(record)
+            )
+            records_available = bool(current_records)
+            if records_available:
+                verification_report = verify_record_store(
+                    store,
+                    experiment_root=decl.experiment.root,
+                    expected_config_digest=decl.config_digest,
+                    scope=verification_scope,
+                )
+        except RecordError as exc:
+            record_catalog_error = str(exc)
+    generated = summarize_outputs_dir(
+        outputs_dir,
+        plots_subdir=layout.plots_subdir,
+        exports_subdir=layout.exports_subdir,
+        notebooks_subdir=layout.notebooks_subdir,
+    )
+    uncataloged_outputs_present = (
+        any(generated[key] for key in ("records", "plots", "exports")) and not records_available
+    )
+    verified_records = bool(verification_report and verification_report["status"] == "ok")
+    plot_ready = verified_records and _surface_record_dependencies_verified(workbench.plots, verification_report)
+    export_ready = verified_records and _surface_record_dependencies_verified(workbench.exports, verification_report)
+    surfaces_waiting = (bool(workbench.plots) and not plot_ready) or (bool(workbench.exports) and not export_ready)
+    can_run = summary["status"] == "ok"
+    file_issues = int(summary["files"].get("issues") or 0)
+    dependency_issues = int(summary["dependencies"].get("issues") or 0)
+    if not can_run and dependency_issues and not file_issues:
+        state = "dependency_blocked"
+        summary_text = f"dependency blocked ({dependency_issues} issue(s))"
+        next_steps = [
+            {
+                "command": reader_command("validate", job_path, "--format", "json"),
+                "description": "Check missing runtime dependencies before running this assay.",
+            }
+        ]
+    elif not can_run:
+        state = "blocked"
+        summary_text = f"blocked ({len(summary['errors'])} issue(s))"
+        next_steps = [
+            {
+                "command": reader_command("validate", job_path, "--format", "json"),
+                "description": "Check blocking file or dependency issues.",
+            }
+        ]
+    elif record_catalog_error is not None:
+        state = "blocked"
+        summary_text = "blocked (invalid records catalog)"
+        next_steps = [
+            {
+                "command": reader_command("run", job_path, "--reset-records"),
+                "description": "Replace the invalid catalog and perform one complete pipeline rerun.",
+            }
+        ]
+    elif records_available and verification_report and verification_report["status"] == "failed":
+        state = "blocked"
+        summary_text = "blocked (record verification failed)"
+        next_steps = [
+            {
+                "command": reader_command("verify", job_path, "--format", "json"),
+                "description": "Inspect source, dependency, config, or artifact drift before using persisted outputs.",
+            }
+        ]
+    elif records_available and verification_report and verification_report["status"] == "unverifiable":
+        state = "catalog_ready"
+        summary_text = "catalog ready; provenance is not fully verifiable"
+        next_steps = [
+            {
+                "command": reader_command("verify", job_path, "--format", "json"),
+                "description": "Inspect missing or stale evidence, then rerun affected surfaces to emit schema-v6 records.",
+            }
+        ]
+    elif records_available:
+        state = "records_ready"
+        summary_text = (
+            "current records verified; configured surfaces await record dependencies"
+            if surfaces_waiting
+            else "records ready and verified"
+        )
+        next_steps = [
+            {"command": command, "description": description}
+            for command, description in build_next_steps(
+                decl,
+                job_label=str(job_path),
+                runtime=runtime,
+                include_plot=plot_ready,
+                include_export=export_ready,
+            )
+        ]
+        if surfaces_waiting:
+            next_steps.insert(
+                0,
+                {
+                    "command": reader_command("run", job_path),
+                    "description": "Produce the missing record dependencies before using configured plot or export surfaces.",
+                },
+            )
+    elif uncataloged_outputs_present:
+        state = "uncataloged_outputs_present"
+        summary_text = "generated outputs present without usable current records"
+        next_steps = [
+            {
+                "command": reader_command("run", job_path),
+                "description": "Rerun from source inputs to rebuild records and selected outputs.",
+            }
+        ]
+    else:
+        state = "runnable"
+        summary_text = "ready to run"
+        next_steps = [
+            {
+                "command": reader_command("run", job_path),
+                "description": "Generate dataframe records and selected outputs.",
+            }
+        ]
+    errors = deepcopy(summary["errors"])
+    if record_catalog_error is not None:
+        errors.append(f"records catalog: {record_catalog_error}")
+    if verification_report is not None and verification_report["status"] == "failed":
+        for issue in verification_report.get("issues", []):
+            errors.append(f"record verification: {issue['reason']}")
+        for record in verification_report.get("records", []):
+            for issue in record.get("issues", []):
+                errors.append(f"record verification ({record['record_id']}): {issue['reason']}")
+    return {
+        "state": state,
+        "summary": summary_text,
+        "preflight": {
+            "status": summary["status"],
+            "issues": len(errors),
+            "files": summary["files"]["summary"],
+            "dependencies": summary["dependencies"]["summary"],
+        },
+        "records": {
+            "catalog": records_catalog,
+            "available": records_available,
+            "verification": verification_report["status"] if verification_report else None,
+            "uncataloged_outputs_present": uncataloged_outputs_present,
+        },
+        "capabilities": {
+            "run": can_run,
+            "records": records_available,
+            "verify": records_catalog,
+            "plot": plot_ready and bool(workbench.plots),
+            "export": export_ready and bool(workbench.exports),
+            "notebook_scaffold": True,
+            "notebook_read_records": verified_records,
+        },
+        "errors": errors,
+        "next_steps": next_steps,
+    }