reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/workbench/cli/_records_view.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+from rich import box
+from rich.panel import Panel
+
+from reader_workbench.errors import ReaderError
+from reader_workbench.workbench.commands import reader_command
+
+from . import shared
+from ._lazy import load as _load
+from .helpers import load_job_models
+from .shared import emit_json, normalize_output_format, table
+
+
+def render_records(
+    *,
+    job_path,
+    all_revisions: bool,
+    format: str,
+    limit: int | None = None,
+    continuation: str | None = None,
+) -> None:
+    _, decl = load_job_models(job_path)
+    outputs_dir = decl.experiment_semantics.layout.outputs_dir
+    runtime = _load("reader_workbench.runtime").builtin_runtime()
+    store = runtime.record_store(
+        outputs_dir,
+        plots_subdir=decl.experiment_semantics.layout.plots_subdir,
+        exports_subdir=decl.experiment_semantics.layout.exports_subdir,
+        create=False,
+    )
+    if not store.catalog_exists():
+        raise ReaderError(
+            f"No outputs/manifests/records.json found. Run '{reader_command('run', job_path)}' first to produce records."
+        )
+    current_record_ids = frozenset()
+    if not all_revisions:
+        workbench = _load("reader_workbench.workbench.graph").resolve_workbench(decl)
+        current_record_ids = _load("reader_workbench.workbench.inspection.runtime").workbench_record_ids(
+            workbench, runtime=runtime
+        )
+
+    fmt = normalize_output_format(format)
+    limit, continuation = shared.normalize_paging_options(limit, continuation)
+    shared.require_json_paging(format=fmt, limit=limit, continuation=continuation)
+    if fmt == "json":
+        payload = _load("reader_workbench.workbench.inspection.results").record_catalog_payload(
+            experiment=_load("reader_workbench.workbench.inspection.experiments").experiment_identity_payload(
+                job_path=job_path, decl=decl
+            ),
+            store=store,
+            outputs_dir=outputs_dir,
+            runtime=runtime,
+            include_history=all_revisions,
+            current_config_digest=decl.config_digest,
+            declared_record_ids=current_record_ids,
+        )
+        page_selection = {
+            "config": str(job_path),
+            "config_digest": decl.config_digest,
+            "include_history": all_revisions,
+            "provenance_epoch_id": payload["catalog"]["provenance_epoch_id"],
+            "record_revisions": [
+                {
+                    "record_id": item["record_id"],
+                    "revision_digest": item["revision_digest"],
+                    "revision_count": item.get("revision_count"),
+                }
+                for item in payload["records"]
+            ],
+        }
+        page = shared.page_json_collection(
+            payload["records"],
+            key=lambda item: str(item["record_id"]),
+            surface="records",
+            selection=page_selection,
+            limit=limit,
+            continuation=continuation,
+        )
+        payload["records"] = list(page.items)
+        emit_json(payload, truncated=page.truncated, continuation=page.continuation)
+        return
+
+    snapshot = store.catalog_snapshot(
+        current_config_digest=decl.config_digest if not all_revisions else None,
+        current_record_ids=(current_record_ids or None) if not all_revisions else None,
+    )
+    latest_records = snapshot.latest_records
+    if all_revisions:
+        if not latest_records:
+            shared.console.print(
+                Panel.fit(
+                    (
+                        "No record history listed in outputs/manifests/records.json. "
+                        f"Run '{reader_command('run', job_path)}' first."
+                    ),
+                    border_style="warn",
+                    box=box.ROUNDED,
+                )
+            )
+            return
+        revision_counts = snapshot.revision_counts
+        listing = table("Records • history")
+        listing.add_column("Record")
+        listing.add_column("Kind", style="accent")
+        listing.add_column("Producer")
+        listing.add_column("Description")
+        listing.add_column("Revisions", justify="right")
+        for record in latest_records:
+            listing.add_row(
+                record.record_id,
+                record.kind,
+                f"{record.producer.kind}:{record.producer.id}",
+                _load("reader_workbench.workbench.inspection.results").record_description(record, runtime=runtime),
+                str(revision_counts[record.record_id]),
+            )
+        shared.console.print(Panel(listing, border_style="accent", box=box.ROUNDED))
+        return
+
+    if not latest_records:
+        shared.console.print(
+            Panel.fit(
+                (
+                    "No records listed in outputs/manifests/records.json. "
+                    f"Run '{reader_command('run', job_path)}' first."
+                ),
+                border_style="warn",
+                box=box.ROUNDED,
+            )
+        )
+        return
+    listing = table("Records • latest")
+    listing.add_column("Record")
+    listing.add_column("Kind", style="accent")
+    listing.add_column("Producer")
+    listing.add_column("Description")
+    listing.add_column("Details", style="path")
+    for record in latest_records:
+        detail = _load("reader_workbench.workbench.inspection.results").record_detail_text(
+            record,
+            base=decl.experiment.root,
+        )
+        listing.add_row(
+            record.record_id,
+            record.kind,
+            f"{record.producer.kind}:{record.producer.id}",
+            _load("reader_workbench.workbench.inspection.results").record_description(record, runtime=runtime),
+            detail,
+        )
+    shared.console.print(Panel(listing, border_style="accent", box=box.ROUNDED))

reader_workbench/workbench/cli/_surface_execution.py

@@ -0,0 +1,443 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+
+import typer
+from rich import box
+from rich.panel import Panel
+
+from reader_workbench.workbench.commands import reader_command
+
+from . import shared
+from ._lazy import load as _load
+from .helpers import bind_decl_protocol, format_job_arg, load_job_models
+from .shared import emit_json, normalize_output_format, table
+
+
+def spec_overrides():
+    return _load("reader_workbench.workbench.spec_overrides")
+
+
+def validate_list_mode_flags(
+    *,
+    list_only: bool,
+    dry_run: bool,
+    inputs: list[str] | None,
+    sets: list[str] | None,
+) -> None:
+    if not list_only:
+        return
+    if dry_run:
+        raise typer.BadParameter("--dry-run cannot be combined with --list")
+    if inputs:
+        raise typer.BadParameter("--input cannot be combined with --list")
+    if sets:
+        raise typer.BadParameter("--set cannot be combined with --list")
+
+
+def apply_surface_overrides(
+    selected,
+    *,
+    inputs: list[str] | None,
+    sets: list[str] | None,
+    experiment_root: Path,
+    resources,
+):
+    overrides = spec_overrides()
+    input_overrides = overrides.parse_input_overrides(inputs or [], root=experiment_root, resources=resources)
+    set_overrides = overrides.parse_set_overrides(sets or [])
+    selected = overrides.apply_step_overrides(
+        selected,
+        input_overrides=input_overrides,
+        set_overrides=set_overrides,
+        root=experiment_root,
+        resources=resources,
+    )
+    return overrides, selected
+
+
+def _raise_dependency_preflight_errors(*, selected, runtime, bound_protocol, exp_root: Path, label: str) -> None:
+    errors: list[str] = []
+    for step in selected:
+        plugin_cls = runtime.plugins.resolve(step.plugin)
+        cfg = plugin_cls.ConfigModel.model_validate(
+            bound_protocol.effective_plugin_config(plugin_id=step.plugin, step_with=(step.with_ or {}))
+        )
+        for issue in plugin_cls.preflight_readiness(exp_dir=exp_root, cfg=cfg, reads=(step.reads or {})):
+            if issue.kind == "dependency":
+                errors.append(f"{label}:{step.id} • {issue.message}")
+    if errors:
+        raise typer.BadParameter("\n".join(errors))
+
+
+def _validate_dry_run_selection(*, decl, selected, runtime, label: str) -> None:
+    validation = _load("reader_workbench.workbench.engine.validation")
+    validation.validation_summary(
+        decl,
+        check_files=False,
+        exp_root=decl.experiment.root,
+        runtime=runtime,
+        plot_specs_override=(selected if label == "plot" else []),
+        export_specs_override=(selected if label == "export" else []),
+    )
+
+
+def validate_plot_job_for_execution(
+    job_path: Path,
+    *,
+    only: list[str] | None,
+    exclude: list[str] | None,
+    dry_run: bool,
+    inputs: list[str] | None,
+    sets: list[str] | None,
+    ensure_active_lifecycle_fn: Callable,
+    require_dataframe_records_fn: Callable,
+) -> None:
+    runtime = _load("reader_workbench.runtime").builtin_runtime()
+    _, decl = load_job_models(job_path, runtime=runtime)
+    if not dry_run:
+        ensure_active_lifecycle_fn(decl, job_path, command_name="plot")
+    workbench = _load("reader_workbench.workbench.graph").resolve_workbench(decl)
+    plot_specs = list(workbench.plots)
+    if not plot_specs:
+        raise typer.BadParameter("No plots configured in this experiment. Add plots to the config.")
+    selected = spec_overrides().select_surface_specs(
+        plot_specs, only=only or [], exclude=exclude or [], kind="plot spec"
+    )
+    if not selected:
+        raise typer.BadParameter("No plots selected. Adjust --only/--exclude or use --list to inspect valid ids.")
+    _, selected = apply_surface_overrides(
+        selected,
+        inputs=inputs,
+        sets=sets,
+        experiment_root=decl.experiment.root,
+        resources=decl.experiment_semantics.resources,
+    )
+    if dry_run:
+        _validate_dry_run_selection(decl=decl, selected=selected, runtime=runtime, label="plot")
+        _raise_dependency_preflight_errors(
+            selected=selected,
+            runtime=runtime,
+            bound_protocol=bind_decl_protocol(decl=decl, runtime=runtime),
+            exp_root=decl.experiment.root,
+            label="plot",
+        )
+    if not dry_run:
+        require_dataframe_records_fn(decl, job_path, runtime=runtime)
+
+
+def render_surface_specs_table(
+    *,
+    title_text: str,
+    selected,
+    runtime,
+    record_producers,
+    summaries: dict[str, str],
+) -> None:
+    inspection_runtime = _load("reader_workbench.workbench.inspection.runtime")
+    listing = table(title_text)
+    listing.add_column("#", justify="right", style="muted")
+    listing.add_column("id", style="accent", overflow="fold")
+    listing.add_column("summary", overflow="fold")
+    listing.add_column("from", overflow="fold")
+    listing.add_column("plugin", overflow="fold")
+    for index, spec in enumerate(selected, 1):
+        spec_payload = inspection_runtime.spec_step_payload(
+            spec, summary=summaries.get(spec.id, "—"), runtime=runtime, record_producers=record_producers
+        )
+        from_refs = ", ".join(inspection_runtime.render_read_binding(item) for item in spec_payload["reads"]) or "—"
+        listing.add_row(str(index), spec.id, summaries.get(spec.id, "—"), from_refs, spec.plugin)
+    shared.console.print(
+        Panel(listing, border_style="accent", box=box.ROUNDED, subtitle=f"[muted]{len(selected)} total[/muted]")
+    )
+
+
+def surface_next_steps(
+    *,
+    job_hint: str | None,
+    output_dir: Path,
+    include_plot: bool,
+    include_export: bool,
+) -> None:
+    def _cmd(base: str, tail: str = "") -> str:
+        return reader_command(base, job_hint, tail)
+
+    lines = [f"Files saved in [path]{output_dir}[/path]", "", "Next steps:"]
+    if include_plot:
+        lines.append(f"  {_cmd('plot')}")
+    if include_export:
+        lines.append(f"  {_cmd('export')}")
+    lines.append(f"  {_cmd('notebook')}")
+    shared.console.print(Panel.fit("\n".join(lines), border_style="green", box=box.ROUNDED))
+
+
+def run_plot_job(
+    job_path: Path,
+    *,
+    job_hint: str | None,
+    only: list[str] | None,
+    exclude: list[str] | None,
+    list_only: bool,
+    format: str,
+    dry_run: bool,
+    log_level: str,
+    inputs: list[str] | None,
+    sets: list[str] | None,
+    ensure_active_lifecycle_fn: Callable,
+    require_dataframe_records_fn: Callable,
+) -> None:
+    _, decl = load_job_models(job_path)
+    if not list_only and not dry_run:
+        ensure_active_lifecycle_fn(decl, job_path, command_name="plot")
+    runtime = _load("reader_workbench.runtime").builtin_runtime()
+    workbench = _load("reader_workbench.workbench.graph").resolve_workbench(decl)
+    bound_protocol = bind_decl_protocol(decl=decl, runtime=runtime)
+    inspection_catalogs = _load("reader_workbench.workbench.inspection.catalogs")
+    inspection_runtime = _load("reader_workbench.workbench.inspection.runtime")
+    fmt = normalize_output_format(format)
+    if not list_only:
+        if fmt == "json" and not dry_run:
+            raise typer.BadParameter("--format json is only supported with --list or --dry-run")
+        if not dry_run:
+            require_dataframe_records_fn(decl, job_path, runtime=runtime)
+    plot_specs = list(workbench.plots)
+    record_producers = inspection_runtime.record_producer_map(workbench.plugin_steps(), runtime=runtime)
+    if not plot_specs:
+        if list_only:
+            if fmt == "json":
+                emit_json(
+                    inspection_catalogs.workbench_surface_specs_payload(
+                        job_path=job_path,
+                        decl=decl,
+                        runtime=runtime,
+                        bound_protocol=bound_protocol,
+                        selected=[],
+                        kind="plot",
+                        only=only or [],
+                        exclude=exclude or [],
+                    )
+                )
+                return
+            shared.console.print(
+                Panel.fit("No plots configured in this experiment.", border_style="warn", box=box.ROUNDED)
+            )
+            return
+        raise typer.BadParameter("No plots configured in this experiment. Add plots to the config.")
+    selected = spec_overrides().select_surface_specs(
+        plot_specs, only=only or [], exclude=exclude or [], kind="plot spec"
+    )
+    if list_only:
+        if fmt == "json":
+            emit_json(
+                inspection_catalogs.workbench_surface_specs_payload(
+                    job_path=job_path,
+                    decl=decl,
+                    runtime=runtime,
+                    bound_protocol=bound_protocol,
+                    selected=selected,
+                    kind="plot",
+                    only=only or [],
+                    exclude=exclude or [],
+                )
+            )
+            return
+        render_surface_specs_table(
+            title_text="Plots",
+            selected=selected,
+            runtime=runtime,
+            record_producers=record_producers,
+            summaries=inspection_runtime.plot_output_summaries(bound_protocol),
+        )
+        return
+    if not selected:
+        raise typer.BadParameter("No plots selected. Adjust --only/--exclude or use --list to inspect valid ids.")
+    experiment_root = decl.experiment.root
+    resources = decl.experiment_semantics.resources
+    _, selected = apply_surface_overrides(
+        selected,
+        inputs=inputs,
+        sets=sets,
+        experiment_root=experiment_root,
+        resources=resources,
+    )
+    if dry_run:
+        _load("reader_workbench.workbench.engine").normalize_log_level(log_level)
+        _validate_dry_run_selection(decl=decl, selected=selected, runtime=runtime, label="plot")
+        _raise_dependency_preflight_errors(
+            selected=selected,
+            runtime=runtime,
+            bound_protocol=bound_protocol,
+            exp_root=experiment_root,
+            label="plot",
+        )
+        if fmt == "json":
+            payload = inspection_catalogs.workbench_surface_specs_payload(
+                job_path=job_path,
+                decl=decl,
+                runtime=runtime,
+                bound_protocol=bound_protocol,
+                selected=selected,
+                kind="plot",
+                only=only or [],
+                exclude=exclude or [],
+            )
+            payload["dry_run"] = True
+            emit_json(payload)
+            return
+    _load("reader_workbench.workbench.engine").run_spec(
+        decl,
+        dry_run=dry_run,
+        log_level=log_level,
+        console=shared.console,
+        include_pipeline=False,
+        include_plots=True,
+        include_exports=False,
+        plot_specs=selected,
+        runtime=runtime,
+    )
+    if not dry_run:
+        outputs_dir = decl.experiment_semantics.layout.outputs_dir
+        plots_cfg = decl.experiment_semantics.layout.plots_subdir
+        plots_dir = outputs_dir if plots_cfg in ("", ".", "./") else outputs_dir / str(plots_cfg)
+        surface_next_steps(
+            job_hint=format_job_arg(job_hint),
+            output_dir=plots_dir,
+            include_plot=False,
+            include_export=bool(workbench.exports),
+        )
+
+
+def run_export_job(
+    job_path: Path,
+    *,
+    job_hint: str | None,
+    only: list[str] | None,
+    exclude: list[str] | None,
+    list_only: bool,
+    format: str,
+    dry_run: bool,
+    log_level: str,
+    inputs: list[str] | None,
+    sets: list[str] | None,
+    ensure_active_lifecycle_fn: Callable,
+    require_dataframe_records_fn: Callable,
+) -> None:
+    _, decl = load_job_models(job_path)
+    if not list_only and not dry_run:
+        ensure_active_lifecycle_fn(decl, job_path, command_name="export")
+    fmt = normalize_output_format(format)
+    workbench = _load("reader_workbench.workbench.graph").resolve_workbench(decl)
+    runtime = _load("reader_workbench.runtime").builtin_runtime()
+    inspection_catalogs = _load("reader_workbench.workbench.inspection.catalogs")
+    inspection_runtime = _load("reader_workbench.workbench.inspection.runtime")
+    record_producers = inspection_runtime.record_producer_map(workbench.plugin_steps(), runtime=runtime)
+    bound_protocol = bind_decl_protocol(decl=decl, runtime=runtime)
+    export_specs = list(workbench.exports)
+    if not export_specs:
+        if list_only:
+            if fmt == "json":
+                emit_json(
+                    inspection_catalogs.workbench_surface_specs_payload(
+                        job_path=job_path,
+                        decl=decl,
+                        runtime=runtime,
+                        bound_protocol=bound_protocol,
+                        selected=[],
+                        kind="export",
+                        only=only or [],
+                        exclude=exclude or [],
+                    )
+                )
+                return
+            shared.console.print(
+                Panel.fit("No exports configured in this experiment.", border_style="warn", box=box.ROUNDED)
+            )
+            return
+        raise typer.BadParameter("No exports configured in this experiment. Add exports to the config.")
+    selected = spec_overrides().select_surface_specs(
+        export_specs, only=only or [], exclude=exclude or [], kind="export spec"
+    )
+    if list_only:
+        if fmt == "json":
+            emit_json(
+                inspection_catalogs.workbench_surface_specs_payload(
+                    job_path=job_path,
+                    decl=decl,
+                    runtime=runtime,
+                    bound_protocol=bound_protocol,
+                    selected=selected,
+                    kind="export",
+                    only=only or [],
+                    exclude=exclude or [],
+                )
+            )
+            return
+        render_surface_specs_table(
+            title_text="Exports",
+            selected=selected,
+            runtime=runtime,
+            record_producers=record_producers,
+            summaries=inspection_runtime.export_output_summaries(bound_protocol),
+        )
+        return
+    if not selected:
+        raise typer.BadParameter("No exports selected. Adjust --only/--exclude or use --list to inspect valid ids.")
+    if fmt == "json" and not dry_run:
+        raise typer.BadParameter("--format json is only supported with --list or --dry-run")
+    if not dry_run:
+        require_dataframe_records_fn(decl, job_path, runtime=runtime)
+    experiment_root = decl.experiment.root
+    resources = decl.experiment_semantics.resources
+    _, selected = apply_surface_overrides(
+        selected,
+        inputs=inputs,
+        sets=sets,
+        experiment_root=experiment_root,
+        resources=resources,
+    )
+    if dry_run:
+        _load("reader_workbench.workbench.engine").normalize_log_level(log_level)
+        _validate_dry_run_selection(decl=decl, selected=selected, runtime=runtime, label="export")
+        _raise_dependency_preflight_errors(
+            selected=selected,
+            runtime=runtime,
+            bound_protocol=bound_protocol,
+            exp_root=experiment_root,
+            label="export",
+        )
+        if fmt == "json":
+            payload = inspection_catalogs.workbench_surface_specs_payload(
+                job_path=job_path,
+                decl=decl,
+                runtime=runtime,
+                bound_protocol=bound_protocol,
+                selected=selected,
+                kind="export",
+                only=only or [],
+                exclude=exclude or [],
+            )
+            payload["dry_run"] = True
+            emit_json(payload)
+            return
+    _load("reader_workbench.workbench.engine").run_spec(
+        decl,
+        dry_run=dry_run,
+        log_level=log_level,
+        console=shared.console,
+        include_pipeline=False,
+        include_plots=False,
+        include_exports=True,
+        export_specs=selected,
+        runtime=runtime,
+    )
+    if not dry_run:
+        outputs_dir = decl.experiment_semantics.layout.outputs_dir
+        exports_cfg = decl.experiment_semantics.layout.exports_subdir
+        exports_dir = outputs_dir if exports_cfg in ("", ".", "./") else outputs_dir / str(exports_cfg)
+        surface_next_steps(
+            job_hint=format_job_arg(job_hint),
+            output_dir=exports_dir,
+            include_plot=bool(workbench.plots),
+            include_export=False,
+        )

reader_workbench/workbench/cli/audit.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from . import shared
+from ._lazy import load as _load
+from .shared import app, emit_json, emit_json_error, normalize_output_format
+
+audit_app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help="Pressure-test experiment workbenches without mutating their outputs.",
+)
+EXPERIMENTS_ROOT_OPTION = typer.Option(Path("experiments"), "--root", metavar="DIR", help="Experiments root.")
+EXPERIMENT_YEARS_OPTION = typer.Option(
+    None,
+    "--years",
+    metavar="YYYY",
+    help="Year directory to include (repeatable; defaults to every numeric year).",
+)
+AUDIT_REPORT_PATH_OPTION = typer.Option(
+    None,
+    "--report-path",
+    metavar="FILE",
+    help="Optional path for the raw JSON audit report.",
+)
+
+
+@audit_app.command(
+    "experiments", help="Run active experiments from isolated temporary copies and verify their outputs."
+)
+def experiments(
+    root: Path = EXPERIMENTS_ROOT_OPTION,
+    years: list[str] | None = EXPERIMENT_YEARS_OPTION,
+    include_non_active: bool = typer.Option(
+        False,
+        "--include-non-active",
+        help="Run draft and other non-active experiments instead of reporting them as skipped.",
+    ),
+    fail_fast: bool = typer.Option(False, "--fail-fast", help="Stop after the first failed experiment."),
+    report_path: Path | None = AUDIT_REPORT_PATH_OPTION,
+    format: str = typer.Option(
+        "table",
+        "--format",
+        metavar="FMT",
+        help="Output format: table | json (default: table).",
+    ),
+) -> None:
+    fmt = normalize_output_format(format)
+    audit_module = _load("reader_workbench.workbench.audit.experiments")
+    try:
+        payload = audit_module.audit_experiments(
+            root,
+            years=None if years is None else tuple(years),
+            include_non_active=include_non_active,
+            fail_fast=fail_fast,
+        )
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc), param_hint="--root/--years") from exc
+
+    if report_path is not None:
+        report_path.parent.mkdir(parents=True, exist_ok=True)
+        report_path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+
+    failed = int(payload["summary"]["failed"])
+    if fmt == "json" and failed:
+        first_failed = next(item for item in payload["results"] if item["status"] == "failed")
+        detail = str(first_failed["detail"] or "no failure detail")
+        bounded_detail = detail if len(detail) <= 400 else f"{detail[:399]}…"
+        emit_json_error(
+            code="experiment_audit_failed",
+            field="experiments",
+            reason=(
+                f"{failed} experiment audit(s) failed. First: {first_failed['name']} "
+                f"during {first_failed['phase']}: {bounded_detail}"
+            ),
+            remediation=(
+                "Inspect the named experiment, correct its configuration, validation, execution, or verification failure, "
+                "then rerun the audit. Use --report-path when the complete machine report is required."
+            ),
+        )
+    elif fmt == "json":
+        emit_json(payload)
+    else:
+        results = [audit_module.AuditResult(**item) for item in payload["results"]]
+        shared.console.print(audit_module.render_text(results))
+
+    if failed:
+        raise typer.Exit(code=1)
+
+
+app.add_typer(audit_app, name="audit")