reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/workbench/cli/pagination.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from bisect import bisect_right
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+
+DEFAULT_PAGE_LIMIT = 25
+MAX_PAGE_LIMIT = 100
+_TOKEN_SCHEMA = "reader.page/v1"
+_MAX_TOKEN_LENGTH = 4096
+
+
+class PageRequestError(ValueError):
+    def __init__(self, field: str, reason: str) -> None:
+        super().__init__(reason)
+        self.field = field
+
+
+@dataclass(frozen=True)
+class Page[T]:
+    items: tuple[T, ...]
+    limit: int
+    truncated: bool
+    continuation: str | None
+
+
+def _selection_digest(selection: Mapping[str, object]) -> str:
+    encoded = json.dumps(selection, sort_keys=True, separators=(",", ":"), ensure_ascii=True).encode("utf-8")
+    return "sha256:" + hashlib.sha256(encoded).hexdigest()
+
+
+def _encode_token(*, surface: str, selection_digest: str, after: str) -> str:
+    payload = {
+        "after": after,
+        "schema": _TOKEN_SCHEMA,
+        "selection": selection_digest,
+        "surface": surface,
+    }
+    encoded = json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=True).encode("utf-8")
+    return base64.urlsafe_b64encode(encoded).decode("ascii").rstrip("=")
+
+
+def _decode_token(token: str) -> dict[str, str]:
+    if not token or len(token) > _MAX_TOKEN_LENGTH:
+        raise PageRequestError("continuation", "continuation must be a nonempty Reader page token")
+    try:
+        padding = "=" * (-len(token) % 4)
+        raw = base64.b64decode(token + padding, altchars=b"-_", validate=True)
+        payload = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, ValueError, json.JSONDecodeError) as exc:
+        raise PageRequestError("continuation", "continuation is not a valid Reader page token") from exc
+    expected_keys = {"after", "schema", "selection", "surface"}
+    if not isinstance(payload, dict) or set(payload) != expected_keys:
+        raise PageRequestError("continuation", "continuation is not a valid Reader page token")
+    if any(not isinstance(payload[key], str) or not payload[key] for key in expected_keys):
+        raise PageRequestError("continuation", "continuation is not a valid Reader page token")
+    if payload["schema"] != _TOKEN_SCHEMA:
+        raise PageRequestError("continuation", "continuation uses an unsupported Reader page-token schema")
+    return payload
+
+
+def _normalize_limit(limit: int | None) -> int:
+    if limit is None:
+        return DEFAULT_PAGE_LIMIT
+    if isinstance(limit, bool) or not isinstance(limit, int) or not 1 <= limit <= MAX_PAGE_LIMIT:
+        raise PageRequestError("limit", f"limit must be between 1 and {MAX_PAGE_LIMIT}")
+    return limit
+
+
+def page_collection[T](
+    items: Sequence[T],
+    *,
+    key: Callable[[T], str],
+    surface: str,
+    selection: Mapping[str, object],
+    limit: int | None,
+    continuation: str | None,
+) -> Page[T]:
+    """Return one deterministic keyset page bound to a semantic selection."""
+
+    effective_limit = _normalize_limit(limit)
+    keyed = sorted(((key(item), item) for item in items), key=lambda pair: pair[0])
+    keys = [item_key for item_key, _ in keyed]
+    if any(not item_key for item_key in keys):
+        raise ValueError(f"{surface} collection contains an empty pagination key")
+    if len(keys) != len(set(keys)):
+        raise ValueError(f"{surface} collection contains duplicate pagination keys")
+
+    fingerprint = _selection_digest(selection)
+    start = 0
+    if continuation is not None:
+        token = _decode_token(continuation)
+        if token["surface"] != surface or token["selection"] != fingerprint:
+            raise PageRequestError(
+                "continuation",
+                "continuation does not match this collection and filter selection",
+            )
+        start = bisect_right(keys, token["after"])
+
+    selected = keyed[start : start + effective_limit]
+    truncated = start + effective_limit < len(keyed)
+    next_token = None
+    if truncated and selected:
+        next_token = _encode_token(
+            surface=surface,
+            selection_digest=fingerprint,
+            after=selected[-1][0],
+        )
+    return Page(
+        items=tuple(item for _, item in selected),
+        limit=effective_limit,
+        truncated=truncated,
+        continuation=next_token,
+    )

reader_workbench/workbench/cli/protocols.py

@@ -0,0 +1,336 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich import box
+from rich.panel import Panel
+from rich.table import Table
+
+from reader_workbench.errors import ConfigError
+from reader_workbench.workbench.commands import reader_command
+
+from . import shared
+from ._lazy import load as _load
+from .shared import app, emit_json, normalize_output_format, table
+
+
+@app.command(help="List built-in protocols or describe one.")
+def protocols(
+    name: str | None = typer.Argument(
+        None,
+        metavar="[NAME]",
+        help=(
+            "Optional protocol id to describe "
+            "(e.g., plate_reader/dual_reporter_screen or plate_reader/single_reporter_screen)."
+        ),
+    ),
+    domain: str | None = typer.Option(None, "--domain", metavar="NAME", help="Filter protocols by domain."),
+    family: str | None = typer.Option(None, "--family", metavar="NAME", help="Filter protocols by family."),
+    example_config: bool = typer.Option(
+        False,
+        "--example-config",
+        help="Print a starter YAML outline for the named protocol.",
+    ),
+    format: str = typer.Option(
+        "table",
+        "--format",
+        metavar="FMT",
+        help="Output format: table | json (default: table).",
+    ),
+    section: str | None = typer.Option(
+        None,
+        "--section",
+        metavar="NAME",
+        help="Named-protocol JSON projection: identity | authoring | semantics | defaults | compiled.",
+    ),
+):
+    runtime = _load("reader_workbench.runtime").builtin_runtime()
+    inspection_protocols = _load("reader_workbench.workbench.inspection.protocols")
+    inspection_runtime = _load("reader_workbench.workbench.inspection.runtime")
+    inspection_semantics = _load("reader_workbench.workbench.inspection.semantics")
+    try:
+        fmt = normalize_output_format(format)
+        selected_section = shared.normalize_semantic_section(
+            section,
+            allowed=inspection_protocols.PROTOCOL_DESCRIPTOR_SECTIONS,
+            format=fmt,
+        )
+        if example_config and not name:
+            raise typer.BadParameter("--example-config requires a protocol name.")
+        if selected_section is not None and not name:
+            raise typer.BadParameter("--section requires a protocol name", param_hint="--section")
+        if name:
+            descriptor = runtime.protocols.resolve(name)
+            if fmt == "json":
+                payload = inspection_protocols.protocol_descriptor_payload(descriptor, runtime=runtime)
+                if selected_section is not None:
+                    payload = inspection_protocols.protocol_descriptor_section_payload(
+                        payload,
+                        section=selected_section,
+                    )
+                emit_json(
+                    payload,
+                    projection=f"section:{selected_section}" if selected_section is not None else "full",
+                )
+                return
+            compilation_error = None
+            try:
+                bound_protocol = runtime.bind_protocol(
+                    _load("reader_workbench.protocols").ProtocolBinding(id=descriptor.protocol)
+                )
+            except ConfigError as exc:
+                bound_protocol = None
+                compiled_plan = None
+                semantic_program = descriptor.semantic_program()
+                compilation_error = str(exc)
+            else:
+                compiled_plan = bound_protocol.compile()
+                semantic_program = compiled_plan.semantic_program
+            summary = table(f"Protocol: {descriptor.protocol}")
+            summary.add_column("Section", style="accent")
+            summary.add_column("Details")
+            summary.add_row("Domain", descriptor.domain)
+            summary.add_row("Family", descriptor.family)
+            summary.add_row("Summary", descriptor.summary)
+            if descriptor.tags:
+                summary.add_row("Tags", ", ".join(descriptor.tags))
+            if descriptor.resources:
+                summary.add_row(
+                    "Input resources",
+                    ", ".join(f"{item.id} → {item.path}" for item in descriptor.resources),
+                )
+            if descriptor.semantic_profiles:
+                summary.add_row("Profiles", ", ".join(profile.id for profile in descriptor.semantic_profiles))
+            if descriptor.factors:
+                summary.add_row("Factors", ", ".join(f"{item.name} ({item.role})" for item in descriptor.factors))
+            if descriptor.windows:
+                summary.add_row("Windows", ", ".join(item.id for item in descriptor.windows))
+            if descriptor.metrics:
+                summary.add_row("Metrics", ", ".join(item.id for item in descriptor.metrics))
+            if descriptor.ranking is not None:
+                summary.add_row("Primary ranking", descriptor.ranking.primary_metric)
+            if semantic_program.has_nodes:
+                summary.add_row(
+                    "Semantic nodes",
+                    str(
+                        len(semantic_program.controls)
+                        + len(semantic_program.windows)
+                        + len(semantic_program.metrics)
+                        + (1 if semantic_program.ranking is not None else 0)
+                    ),
+                )
+            if descriptor.default_plot_profile is not None:
+                summary.add_row("Default plot profile", descriptor.default_plot_profile)
+            if compilation_error is not None:
+                summary.add_row("Default compilation", f"Requires authoring: {compilation_error}")
+            shared.console.print(Panel(summary, border_style="accent", box=box.ROUNDED))
+
+            input_rows = inspection_protocols.protocol_surface_rows(descriptor.input_fields)
+            if input_rows:
+                shared.console.print(
+                    Panel(
+                        inspection_protocols.protocol_surface_table("Inputs", input_rows),
+                        border_style="accent",
+                        box=box.ROUNDED,
+                    )
+                )
+            analysis_rows = inspection_protocols.protocol_surface_rows(descriptor.analysis_fields)
+            if analysis_rows:
+                shared.console.print(
+                    Panel(
+                        inspection_protocols.protocol_surface_table("Analysis", analysis_rows),
+                        border_style="accent",
+                        box=box.ROUNDED,
+                    )
+                )
+            if semantic_program.has_nodes:
+                shared.console.print(
+                    Panel(
+                        inspection_semantics.semantic_program_table(semantic_program, include_execution=False),
+                        border_style="accent",
+                        box=box.ROUNDED,
+                    )
+                )
+            if semantic_program.has_nodes:
+                shared.console.print(
+                    Panel(
+                        inspection_semantics.semantic_program_table(
+                            semantic_program,
+                            title="Compiled Semantic Execution",
+                        ),
+                        border_style="accent",
+                        box=box.ROUNDED,
+                    )
+                )
+            if descriptor.plot_profiles:
+                shared.console.print(
+                    Panel(
+                        inspection_protocols.protocol_plot_profiles_table(descriptor),
+                        border_style="accent",
+                        box=box.ROUNDED,
+                    )
+                )
+            if descriptor.figures:
+                shared.console.print(
+                    Panel(
+                        inspection_protocols.protocol_plot_outputs_table(descriptor),
+                        border_style="accent",
+                        box=box.ROUNDED,
+                    )
+                )
+            if descriptor.artifacts:
+                shared.console.print(
+                    Panel(
+                        inspection_protocols.protocol_artifacts_table(descriptor),
+                        border_style="accent",
+                        box=box.ROUNDED,
+                    )
+                )
+            if compiled_plan is not None and compiled_plan.pipeline:
+                shared.console.print(
+                    Panel(
+                        inspection_protocols.protocol_pipeline_table(compiled_plan.pipeline),
+                        border_style="accent",
+                        box=box.ROUNDED,
+                    )
+                )
+            if compiled_plan is not None and bound_protocol is not None and compiled_plan.plots:
+                shared.console.print(
+                    Panel(
+                        inspection_protocols.protocol_surface_impl_table(
+                            "Plot Implementations",
+                            compiled_plan.plots,
+                            inspection_runtime.plot_output_summaries(bound_protocol),
+                            binding_display=inspection_runtime.binding_display,
+                        ),
+                        border_style="accent",
+                        box=box.ROUNDED,
+                    )
+                )
+            if compiled_plan is not None and bound_protocol is not None and compiled_plan.exports:
+                shared.console.print(
+                    Panel(
+                        inspection_protocols.protocol_surface_impl_table(
+                            "Export Implementations",
+                            compiled_plan.exports,
+                            inspection_runtime.export_output_summaries(bound_protocol),
+                            binding_display=inspection_runtime.binding_display,
+                        ),
+                        border_style="accent",
+                        box=box.ROUNDED,
+                    )
+                )
+            if example_config:
+                shared.console.print(
+                    Panel(
+                        inspection_protocols.protocol_example_config(descriptor),
+                        title="Starter YAML",
+                        border_style="accent",
+                        box=box.ROUNDED,
+                    )
+                )
+            return
+
+        if fmt == "json":
+            emit_json(
+                {
+                    "protocols": [
+                        {
+                            "protocol": descriptor.protocol,
+                            "domain": descriptor.domain,
+                            "family": descriptor.family,
+                            "summary": descriptor.summary,
+                            "tags": list(descriptor.tags),
+                        }
+                        for descriptor in runtime.protocols.all()
+                        if (not domain or descriptor.domain == domain) and (not family or descriptor.family == family)
+                    ]
+                }
+            )
+            return
+
+        listing = table("Protocols")
+        listing.add_column("Name", style="accent", min_width=24)
+        listing.add_column("Domain")
+        listing.add_column("Family")
+        listing.add_column("Description")
+        for descriptor in runtime.protocols.all():
+            if domain and descriptor.domain != domain:
+                continue
+            if family and descriptor.family != family:
+                continue
+            listing.add_row(descriptor.protocol, descriptor.domain, descriptor.family, descriptor.summary)
+        shared.console.print(Panel(listing, border_style="accent", box=box.ROUNDED))
+    except ConfigError as err:
+        raise typer.BadParameter(str(err)) from err
+
+
+@app.command(help="Scaffold a new experiment directory from a protocol starter config.")
+def init(
+    target: str = typer.Argument(..., metavar="DIR", help="Experiment directory to create."),
+    protocol: str = typer.Option(
+        ...,
+        "--protocol",
+        "-p",
+        metavar="ID",
+        help=(
+            "Protocol id to bind, for example: plate_reader/dual_reporter_screen "
+            "or plate_reader/single_reporter_screen."
+        ),
+    ),
+    title: str | None = typer.Option(None, "--title", metavar="TEXT", help="Optional human-readable experiment title."),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help="Overwrite config.yaml when the target directory already contains one.",
+    ),
+):
+    runtime = _load("reader_workbench.runtime").builtin_runtime()
+    try:
+        descriptor = runtime.protocols.resolve(protocol)
+    except ConfigError as err:
+        raise typer.BadParameter(str(err)) from err
+    target_dir = Path(target).expanduser()
+    if target_dir.suffix:
+        raise typer.BadParameter("init expects a directory path, not a file path")
+    target_dir = target_dir.resolve()
+    config_path = target_dir / "config.yaml"
+    if config_path.exists() and not force:
+        shared.abort(f"{config_path} already exists. Pass --force to overwrite it.")
+    target_dir.mkdir(parents=True, exist_ok=True)
+    (target_dir / "inputs").mkdir(exist_ok=True)
+    (target_dir / "notebooks").mkdir(exist_ok=True)
+    example_document = _load("reader_workbench.workbench.inspection.protocols").protocol_example_document(descriptor)
+    experiment_block = dict(example_document["experiment"])
+    experiment_block["id"] = target_dir.name
+    if title:
+        experiment_block["title"] = title
+    example_document["experiment"] = experiment_block
+    config_path.write_text(_load("yaml").safe_dump(example_document, sort_keys=False), encoding="utf-8")
+
+    summary = Table(box=box.ROUNDED, expand=True, show_header=False)
+    summary.add_column("Field", style="accent", no_wrap=True)
+    summary.add_column("Value")
+    summary.add_row("Protocol", descriptor.protocol)
+    summary.add_row("Experiment", experiment_block["id"])
+    summary.add_row("Config", str(config_path))
+    summary.add_row("Inputs dir", str(target_dir / "inputs"))
+    summary.add_row("Notebook dir", str(target_dir / "notebooks"))
+    for resource in descriptor.resources:
+        summary.add_row(f"Resource: {resource.id}", str((target_dir / resource.path).resolve()))
+    shared.console.print(Panel(summary, title="Experiment scaffolded", border_style="accent", box=box.ROUNDED))
+    shared.console.print(
+        Panel(
+            "\n".join(
+                [
+                    reader_command("inspect", config_path),
+                    reader_command("validate", config_path, "--no-files"),
+                    reader_command("protocols", descriptor.protocol),
+                ]
+            ),
+            title="Next steps",
+            border_style="accent",
+            box=box.ROUNDED,
+        )
+    )