daedalus-flow 0.1.0__py3-none-any.whl

daedalus/__init__.py

@@ -0,0 +1,12 @@
+"""Design, validate and run labs of modules."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+# The distribution name; must match [project].name in pyproject.toml.
+_DIST_NAME = "daedalus-flow"
+
+try:
+    __version__ = version(_DIST_NAME)
+except PackageNotFoundError:
+    # Bare source tree (package not installed); keep imports working.
+    __version__ = "0.0.0.dev0"

daedalus/cli/__init__.py

@@ -0,0 +1,9 @@
+"""daedalus.cli - the command-line interface.
+
+Builds the ``dae`` / ``daedalus`` console scripts (both point at :func:`main`).
+This is not a public Python API; script authors should use :mod:`daedalus.flow`.
+"""
+
+from daedalus.cli.app import app, main
+
+__all__ = ["app", "main"]

daedalus/cli/app.py

@@ -0,0 +1,86 @@
+"""daedalus root command (Typer).
+
+Builds the root Typer app, mounts the four command groups, and emits the
+onboarding text when invoked bare. Both console scripts (``dae`` and
+``daedalus``) point at :func:`main`.
+"""
+
+from typing import Annotated
+
+import typer
+
+from daedalus import __version__
+from daedalus.cli import render, strings
+from daedalus.cli.commands._outcome import is_json, resolve, state
+from daedalus.cli.commands.example import example
+from daedalus.cli.commands.flow import flow
+from daedalus.cli.commands.lab import lab
+from daedalus.cli.commands.module import module
+from daedalus.core.outcomes import Outcome
+
+# --help track panels. The groups bucket by function so `dae --help`
+# reads as a guided surface rather than a flat list.
+_TRACK_AUTHOR = "Author a Lab"
+_TRACK_EXPLORE = "Start from an example"
+_TRACK_INSPECT = "Inspect a run"
+
+app = typer.Typer(
+    help=strings.ROOT_TAGLINE,
+    no_args_is_help=False,
+    add_completion=True,
+    # -h is the conventional help alias; set once on the root, Click's context
+    # tree carries it down to every group and leaf without per-command wiring.
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+def _version_callback(value: bool) -> None:
+    """Print ``dae <version>`` and exit; an eager flag outside the outcome codes."""
+    if value:
+        typer.echo(f"dae {__version__}")
+        raise typer.Exit()
+
+
+app.add_typer(example, name="example", rich_help_panel=_TRACK_EXPLORE)
+app.add_typer(module, name="module", rich_help_panel=_TRACK_AUTHOR)
+app.add_typer(lab, name="lab", rich_help_panel=_TRACK_AUTHOR)
+app.add_typer(flow, name="flow", rich_help_panel=_TRACK_INSPECT)
+
+
+@app.callback(invoke_without_command=True)
+def root(
+    ctx: typer.Context,
+    json_out: Annotated[
+        bool, typer.Option("--json", help=strings.JSON_OPTION_HELP)
+    ] = False,
+    _version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-V",
+            callback=_version_callback,
+            is_eager=True,
+            help=strings.VERSION_OPTION_HELP,
+        ),
+    ] = False,
+) -> None:
+    """Emit the onboarding text when invoked with no subcommand.
+
+    ``--json`` here sets the per-invocation baseline before any subcommand; a
+    leaf's shared ``--json`` can then only raise it, so the flag works in
+    either position.
+    """
+    state["json"] = json_out
+    if ctx.invoked_subcommand is None:
+        # Bare 'dae' (dae.onboarding.ok); the command list comes from the
+        # registered groups.
+        if not is_json():
+            # Every add_typer above passes name=..., so no group name is None;
+            # the filter only narrows the type for mypy.
+            groups = [group.name for group in app.registered_groups if group.name]
+            render.onboarding(groups)
+        resolve(Outcome.DAE_ONBOARDING_OK)
+
+
+def main() -> None:
+    app()

daedalus/cli/chrome.py

@@ -0,0 +1,28 @@
+"""The stderr chrome of dae, its teaching notes and Next hints.
+
+stdout carries the transcript only; stderr carries the teaching chrome and the
+Next hint. Both helpers print through the shared ``err`` console, so the chrome
+picks up the theme. ``next_line`` takes a fixed command string and frames it
+with one ``[muted]`` tag; ``note`` carries dynamic content that may contain
+``[``, so it prints with markup parsing off.
+"""
+
+from .console import err
+
+
+def next_line(text: str) -> None:
+    """Print the stderr Next hint, e.g. ``Next: dae lab visualize``.
+
+    Each command ends with one of these pointing at the next step. ``text`` is
+    a fixed command string, so its one ``[muted]`` markup tag stays parsed.
+    """
+    err.print(f"[muted]Next:[/muted] {text}")
+
+
+def note(text: str) -> None:
+    """Print one line of teaching chrome to stderr.
+
+    One call is one line. Markup parsing is off, so a literal ``[...]`` in the
+    message (a ``[viz]`` hint, a bracket in a path) renders verbatim.
+    """
+    err.print(text, style="muted", markup=False)

daedalus/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""daedalus command groups."""

daedalus/cli/commands/_outcome.py

@@ -0,0 +1,65 @@
+"""Every command names its Outcome through ``resolve``.
+
+``resolve`` owns the exit code (0 for ok and dry_run outcomes, 2 for usage
+errors). Under ``--json`` it prints the ``{code, exit, error, data}`` envelope
+to plain stdout rather than the Rich console, so the machine surface stays free
+of ANSI. The root ``--json`` flag sets ``state["json"]``; command bodies guard
+their human output behind ``if not is_json():``.
+"""
+
+import json
+from typing import Annotated, Any
+
+import typer
+
+from daedalus.cli import strings
+from daedalus.core.outcomes import Outcome
+
+# Process-global flag. The root callback sets the baseline before any command
+# body runs; the per-leaf option below can only raise it to True, so --json
+# works before or after the noun.
+state = {"json": False}
+
+
+def is_json() -> bool:
+    """Whether the current invocation requested machine-readable JSON output."""
+    return state["json"]
+
+
+def _escalate_json(value: bool) -> bool:
+    """Set the json flag when --json is passed; a leaf's False never lowers it."""
+    if value:
+        state["json"] = True
+    return value
+
+
+# One shared --json option reused on every leaf, so the flag is accepted after
+# the noun (`dae lab visualize --json`) as well as before it.
+JsonOption = Annotated[
+    bool,
+    typer.Option("--json", callback=_escalate_json, help=strings.JSON_OPTION_HELP),
+]
+
+
+def resolve(
+    outcome: Outcome,
+    payload: dict[str, Any] | None = None,
+    *,
+    error: dict[str, Any] | None = None,
+) -> None:
+    """Make the outcome explicit; exit non-zero only for error outcomes.
+
+    Under ``--json``, print the ``{code, exit, error, data}`` envelope first,
+    with the dotted code, its registry exit, the failure cause (null on success)
+    and the command payload (null when there is none). The four-key shape is fixed.
+    """
+    if is_json():
+        body = {
+            "code": str(outcome),
+            "exit": outcome.exit_code,
+            "error": error,
+            "data": payload or None,
+        }
+        print(json.dumps(body))
+    if outcome.exit_code != 0:
+        raise typer.Exit(code=outcome.exit_code)

daedalus/cli/commands/example.py

@@ -0,0 +1,97 @@
+"""List the example ladder or scaffold one example (the ``example`` command).
+
+A thin command layer over the pure functions in ``strings``; teaching notes and
+the Next hint go to stderr through ``chrome``. ``example`` takes an optional
+positional name, so it is a one-callback Typer mounted with ``add_typer``, which
+makes both ``dae example`` and ``dae example minimal`` work. The bare ladder is
+example.list.ok, a known example example.scaffold.ok and an unknown one
+example.scaffold.not_found (exit 2).
+"""
+
+from typing import Annotated
+
+import typer
+
+from daedalus.cli import chrome, render, strings
+from daedalus.cli.commands._outcome import JsonOption, is_json, resolve
+from daedalus.cli.console import out
+from daedalus.core import paths
+from daedalus.core.outcomes import Outcome
+
+example = typer.Typer(
+    help="Show the example ladder, or scaffold a single example by name.",
+    invoke_without_command=True,
+    no_args_is_help=False,
+)
+
+# The example names with a bundle directory on disk, from strings so the
+# ladder and the command agree; any other name is refused as unknown.
+_BUNDLED_EXAMPLES = set(strings.AVAILABLE_EXAMPLES)
+
+
+def _scaffold_bundled(name: str) -> None:
+    """Copy the bundled example ``name`` into ``./<name>/``, refusing to clobber."""
+    dest = paths.example_dir(name)
+    if dest.exists():
+        if not is_json():
+            chrome.note(f"'{name}' already exists here; refusing to overwrite it.")
+        return resolve(Outcome.DAE_EXAMPLE_SCAFFOLD_EXISTS)
+    paths.copy_example_bundle(name, dest)
+    if not is_json():
+        # The result path goes to stdout so an agent capturing stdout alone
+        # learns where the example landed; the teaching note + Next hint stay on
+        # stderr. The path is the one machine-relevant fact of a scaffold.
+        out.print(f"scaffolded ./{name}/")
+        chrome.note(f"scaffolded example '{name}' into ./{name}/")
+        # Point at the input/ dir when the scaffolded bundle ships one (detected
+        # on disk).
+        input_dir = dest / "input"
+        if input_dir.is_dir():
+            inputs = sorted(p for p in input_dir.iterdir() if p.is_file())
+            if inputs:
+                rel = f"{name}/input/{inputs[0].name}"
+                chrome.note(strings.INPUT_DIR_HINT.format(input_file=rel))
+        chrome.next_line(strings.NEXT_AFTER_SCAFFOLD[name])
+    return resolve(Outcome.EXAMPLE_SCAFFOLD_OK, payload={"paths": [str(dest)]})
+
+
+def _example_entries() -> list[dict[str, object]]:
+    """The example ladder as ``--json`` entries, simplest first."""
+    return [
+        {
+            "name": name,
+            "available": name in _BUNDLED_EXAMPLES,
+            "description": description,
+        }
+        for name, description in strings.example_rows()
+    ]
+
+
+@example.callback(invoke_without_command=True)
+def example_main(
+    name: Annotated[
+        str | None,
+        typer.Argument(help="Example to scaffold; omit to list the ladder."),
+    ] = None,
+    json_out: JsonOption = False,
+) -> None:
+    """Show the example ladder, or scaffold a single example by name."""
+    if name is None:
+        # Bare 'dae example': list the ladder, point at the simplest example.
+        if not is_json():
+            render.example_ladder()
+            chrome.next_line("dae example minimal")
+        # Under --json, attach the ladder as an array built from the same
+        # strings data as the human render, so the two surfaces agree.
+        return resolve(
+            Outcome.EXAMPLE_LIST_OK, payload={"examples": _example_entries()}
+        )
+
+    if name in _BUNDLED_EXAMPLES:
+        return _scaffold_bundled(name)
+
+    # An unknown example gets a stderr note and the usage exit code.
+    if not is_json():
+        chrome.note(f"unknown example '{name}'.")
+        chrome.note("valid examples: " + ", ".join(strings.KNOWN_EXAMPLES))
+    return resolve(Outcome.EXAMPLE_SCAFFOLD_NOT_FOUND)

daedalus/cli/commands/flow.py

@@ -0,0 +1,126 @@
+"""Inspect the latest flow and resume a failed one (the ``flow`` command group).
+
+``status`` reads the lineage the engine wrote under ``dae-outputs/flows/`` in
+cwd and renders the latest flow; it returns ``dae.flow.status.ok``, or
+``dae.flow.status.nothing`` (exit 0) when there is none. ``resume`` replays the
+recorded plan of the latest failed flow through ``LocalEngine.resume_flow``,
+skipping completed steps; it returns ``dae.flow.resume.ok``, ``.nothing``
+(exit 0) or ``.failed`` (the re-run failed again).
+"""
+
+from pathlib import Path
+
+import typer
+
+from daedalus.cli import chrome, render
+from daedalus.cli.commands._outcome import JsonOption, is_json, resolve
+from daedalus.core import lineage, topology
+from daedalus.core.outcomes import Outcome
+
+flow = typer.Typer(
+    help="Inspect a flow run; resume a failed flow.", no_args_is_help=True
+)
+
+
+def _note(message: str) -> None:
+    """Write a stderr note only on the human (non-json) surface."""
+    if not is_json():
+        chrome.note(message)
+
+
+@flow.command()
+def status(json_out: JsonOption = False) -> None:
+    """Show the latest flow's lineage from dae-outputs/flows/ in cwd.
+
+    No flow here is dae.flow.status.nothing (exit 0), not an error. status is
+    read-only and exits 0 even for a failed flow, which names its cause in the
+    envelope error slot; act on a failure with 'dae flow resume'.
+    """
+    output_root = Path.cwd() / topology.OUTPUT_ROOT
+    flow_ids = lineage.list_flows(output_root)
+    if not flow_ids:
+        _note("no flows here yet (run 'dae lab run' first).")
+        return resolve(Outcome.DAE_FLOW_STATUS_NOTHING)
+
+    latest = flow_ids[-1]
+    # A run stranded as `running`/`submitted` by a crash is flipped to `failed`
+    # on read, so status never reports a dead run as alive.
+    record = lineage.read_flow_record_reconciled(output_root / "flows" / latest)
+    if not is_json():
+        render.flow_status(record)
+        # resume only re-runs failed steps, so the hint appears for a failed flow.
+        if record.status == "failed":
+            chrome.next_line("dae flow resume   (re-run only the steps that need it)")
+    return resolve(
+        Outcome.FLOW_STATUS_OK,
+        payload=render.flow_status_payload(record),
+        error=render.failure_cause(record),
+    )
+
+
+@flow.command()
+def resume(json_out: JsonOption = False) -> None:
+    """Resume the latest failed flow, re-running the failed step and what follows it.
+
+    Completed steps are skipped and their artifacts reused. With no flow, or the
+    latest completed, there is nothing to resume (dae.flow.resume.nothing, exit 0);
+    a re-run that fails again is .failed (exit 1). Edits since are not re-validated.
+    """
+    # Lazy (off the bare `dae --help` path): recipe + engine pull networkx.
+    from daedalus.core import recipe  # noqa: PLC0415
+    from daedalus.core.engine import LabConfig, LocalEngine  # noqa: PLC0415
+
+    cwd = Path.cwd()
+    output_root = cwd / topology.OUTPUT_ROOT
+    flow_ids = lineage.list_flows(output_root)
+    if not flow_ids:
+        _note("no flows here to resume (run 'dae lab run' first).")
+        return resolve(Outcome.DAE_FLOW_RESUME_NOTHING)
+
+    latest = flow_ids[-1]
+    record = lineage.read_flow_record(output_root / "flows" / latest)
+    if record.status != "failed":
+        _note(f"latest flow '{latest}' is {record.status}; nothing to resume.")
+        return resolve(Outcome.DAE_FLOW_RESUME_NOTHING)
+
+    lab_path = recipe.discover_lab(cwd)
+    if lab_path is None:
+        _note("no lab.yaml here to resume against.")
+        return resolve(Outcome.DAE_FLOW_RESUME_NOTHING)
+    lab_dir = lab_path.parent
+    try:
+        spec = recipe.load_recipe(lab_path)
+        plan = recipe.build_plan(spec, lab_dir)
+    except recipe.RecipeParseError:
+        # The lab no longer parses or builds (a structural edit since the run); it
+        # cannot be resumed against, and the note says so.
+        _note("this lab no longer builds a valid plan; cannot resume it.")
+        return resolve(Outcome.DAE_FLOW_RESUME_NOTHING)
+
+    config = LabConfig(
+        lab_name=spec.name or lab_dir.name,
+        lab_dir=lab_dir,
+        seed=0,
+        output_root=output_root,
+        max_workers=spec.max_workers,
+        engine=spec.engine,
+        isolation=spec.isolation,
+    )
+    result = LocalEngine().resume_flow(plan, config, latest)
+
+    record = lineage.read_flow_record(output_root / "flows" / latest)
+    payload = render.flow_status_payload(record)
+    if not is_json():
+        render.flow_status(record)
+    _note(
+        "resume replayed the recorded plan; module / recipe edits since the "
+        "failed run were not re-validated."
+    )
+    if result.error is not None:
+        _note(f"resume still failed at a step: {result.error}")
+        return resolve(
+            Outcome.DAE_FLOW_RESUME_FAILED,
+            payload=payload,
+            error=render.failure_cause(record),
+        )
+    return resolve(Outcome.FLOW_RESUME_OK, payload=payload)