smartpipe-cli 1.3.0__py3-none-any.whl

smartpipe/cli/screens.py

@@ -0,0 +1,231 @@
+"""Multi-line UX screens, verbatim from plan/ux.md (golden-pinned in tests).
+
+Style contract (plan/ux.md): every screen contains its own fix — no error may
+require opening a browser or reading docs to resolve.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "BINARY_STDIN_UNPARSEABLE",
+    "CHATGPT_LOGIN_EXPIRED",
+    "EMBEDDINGS_NEED_KEY",
+    "FIELD_REF_ON_PLAIN_INPUT",
+    "NO_MODEL",
+    "WELCOME",
+    "cloud_model_missing",
+    "missing_anthropic_extra",
+    "missing_api_key",
+    "ollama_model_missing",
+    "ollama_unreachable",
+    "openai_needs_key_or_login",
+    "schema_rejected",
+    "stdin_document_failed",
+]
+
+CHATGPT_LOGIN_EXPIRED = """\
+error: the ChatGPT login has expired and couldn't be refreshed
+  Fix: smartpipe auth login"""
+
+EMBEDDINGS_NEED_KEY = """\
+error: embeddings aren't available through ChatGPT login
+  The ChatGPT plan wire serves chat models only.
+  Fix: export OPENAI_API_KEY=sk-...
+   or use a local model: smartpipe config embed-model nomic-embed-text"""
+
+
+def openai_needs_key_or_login(model: str) -> str:
+    return (
+        f"error: model '{model}' needs an OpenAI API key or a ChatGPT login\n"
+        "  smartpipe found no OPENAI_API_KEY and no ChatGPT login. Keys are never\n"
+        "  stored in config.\n"
+        "  Fix: export OPENAI_API_KEY=sk-...        (platform billing)\n"
+        "   or: smartpipe auth login                  (use your ChatGPT Plus/Pro plan)"
+    )
+
+
+BINARY_STDIN_UNPARSEABLE = """\
+error: stdin looks like binary data smartpipe can't parse
+  Recognized on stdin: text lines, or a single PDF/DOCX/PPTX/XLSX/audio/image document.
+  For files on disk use --in: smartpipe map "Summarize" --in 'report.pdf'"""
+
+
+def stdin_document_failed(reason: str) -> str:
+    return (
+        f"error: stdin looks like a document, but it couldn't be read ({reason})\n"
+        "  smartpipe reads ONE binary document per run from stdin.\n"
+        "  Alternative: smartpipe map \"…\" --in 'report.pdf'"
+    )
+
+
+FIELD_REF_ON_PLAIN_INPUT = """\
+error: the prompt references a {field}, but the first input line isn't JSON
+  {field} substitution needs JSON Lines input (one object per line).
+  Either drop the braces, or feed JSONL — e.g.: cat tickets.jsonl | smartpipe filter ..."""
+
+
+def tint(text: str, code: str) -> str:
+    """Style stdout REPORT text (headers, marks): TTY-only, NO_COLOR wins.
+    click.echo also strips ANSI when piped, so goldens stay plain (D42)."""
+    import os
+    import sys
+
+    if not sys.stdout.isatty() or os.environ.get("NO_COLOR"):
+        return text
+    return f"\x1b[{code}m{text}\x1b[0m"
+
+
+def heading(text: str) -> str:
+    return tint(text, "1;36")  # bold cyan — every section/column title, one voice
+
+
+def good(text: str) -> str:
+    return tint(text, "32")
+
+
+def bad(text: str) -> str:
+    return tint(text, "31")
+
+
+def _c(text: str, code: str) -> str:
+    """Bake ANSI into the welcome — click.echo strips it when piped, and the
+    NO_COLOR gate lives at the echo site (D42)."""
+    return f"\x1b[{code}m{text}\x1b[0m"
+
+
+_WORDMARK = r"""
+                       _         _
+ ___ _ __   __ _  _ _ | |_  _ __ (_) _ __  ___
+(_-<| '  \ / _` || '_||  _|| '_ \| || '_ \/ -_)
+/__/|_|_|_|\__,_||_|   \__|| .__/|_|| .__/\___|
+                           |_|      |_|"""
+
+_VERBS: tuple[tuple[str, str], ...] = (
+    ("map", "Transform each item with a prompt"),
+    ("extend", "Add extracted fields to each record"),
+    ("filter", "Keep items matching a semantic condition"),
+    ("embed", "Convert items to vector embeddings"),
+    ("top_k", "Rank items by similarity to a query"),
+    ("reduce", "Synthesize many items into one"),
+    ("join", "Match stdin against a second input, semantically"),
+    ("cluster", "Group items by meaning; label each group"),
+    ("diff", "What distinguishes two sets of items"),
+    ("distinct", "Fold near-duplicate items (embeddings only)"),
+    ("outliers", "Rank the items least like the rest (embeddings only)"),
+)
+
+_UTILITIES: tuple[tuple[str, str], ...] = (
+    ("where", "Keep rows matching a deterministic predicate"),
+    ("summarize", "Aggregate records: count/avg/percentiles by field"),
+    ("sample", "Keep N random rows (seeded, reproducible)"),
+    ("getschema", "Report the stream's fields, types, coverage"),
+    ("sort", "Order records by a field (numbers, then strings)"),
+    ("split", "Break oversized items into chunks"),
+    ("chart", "Draw a bar chart of results (--save writes SVG)"),
+    ("config", "Configure models and settings"),
+)
+
+_NAME_WIDTH = max(len(name) for name, _ in (*_VERBS, *_UTILITIES)) + 2
+
+
+def _rows(entries: tuple[tuple[str, str], ...]) -> str:
+    return "\n".join(f"  {_c(name.ljust(_NAME_WIDTH), '32')}{text}" for name, text in entries)
+
+
+_GET_STARTED = (
+    f"  smartpipe config{' ' * 37}{_c('# one-minute interactive setup', '2')}\n"
+    f'  echo "hello" | smartpipe map "translate to Spanish"'
+)
+
+WELCOME = f"""\
+{_c(_WORDMARK.lstrip(chr(10)), "36")}
+{_c("smartpipe", "1")} — semantic pipes for your terminal
+{_c("PDFs, images, audio, video, and text — verbs that understand their input.", "2")}
+
+{_c("Verbs (call a model):", "1;36")}
+{_rows(_VERBS)}
+
+{_c("Utilities (free — no model calls):", "1;36")}
+{_rows(_UTILITIES)}
+
+{_c("Get started:", "1;36")}
+{_GET_STARTED}
+
+'smartpipe <command> --help' shows examples for each command.
+"""
+
+NO_MODEL = """\
+error: no model configured, and no local Ollama found
+
+  Local (free, private):
+    1. Install Ollama              https://ollama.com
+    2. ollama pull qwen3:8b
+    3. smartpipe config model ollama/qwen3:8b
+
+  Cloud (paid):
+    smartpipe config model claude-opus-4-8    then: export ANTHROPIC_API_KEY=sk-ant-...
+    smartpipe config model gpt-5.4-mini        then: export OPENAI_API_KEY=sk-...
+
+  Then rerun your command. 'smartpipe config' walks you through this interactively."""
+
+
+def ollama_unreachable(host: str, model: str, reason: str) -> str:
+    return (
+        f"error: can't reach ollama at {host} ({reason})\n"
+        f"  The model '{model}' is configured, but nothing is listening there.\n"
+        "  Start it with: ollama serve    (or check OLLAMA_HOST if it runs elsewhere)"
+    )
+
+
+def ollama_model_missing(name: str, host: str, detail: str) -> str:
+    return (
+        f"error: ollama doesn't have the model '{name}'\n"
+        f"  ({host} answered: {detail})\n"
+        f"  Fix: ollama pull {name}        (or check the name with: ollama list)"
+    )
+
+
+def missing_api_key(
+    model: str,
+    provider: str,
+    env_var: str,
+    key_shape: str,
+    note: str = "add it to your shell profile to persist",
+) -> str:
+    return (
+        f"error: model '{model}' needs {_an(provider)} {provider} API key\n"
+        f"  smartpipe found no {env_var} in the environment. Keys are never stored in config.\n"
+        f"  Fix: export {env_var}={key_shape}        ({note})"
+    )
+
+
+def cloud_model_missing(model: str, host: str) -> str:
+    """D18: a 404 for the model dooms every item identically — stop at the first."""
+    return (
+        f"error: the endpoint doesn't know the model '{model}'\n"
+        f"  {host} answered 404 — every item would fail identically, "
+        "so smartpipe stopped at the first.\n"
+        "  Fix: check the name, or set one that exists: smartpipe config model gpt-5.4-mini"
+    )
+
+
+def schema_rejected(host: str, detail: str) -> str:
+    """D18: a schema the endpoint rejects dooms every item identically."""
+    return (
+        "error: the endpoint rejected the --schema\n"
+        f"  {host} answered 400 (response_format): {detail}\n"
+        "  Fix: simplify the schema — or drop --schema and validate downstream."
+    )
+
+
+def missing_anthropic_extra(model: str) -> str:
+    return (
+        f"error: the SDK for '{model}' is unavailable\n"
+        "  Claude models talk through the official anthropic SDK, which ships\n"
+        "  with smartpipe — a broken environment is the only way here.\n"
+        "  Fix: reinstall smartpipe"
+    )
+
+
+def _an(word: str) -> str:
+    return "an" if word[:1].lower() in "aeiou" else "a"

smartpipe/cli/sem_file.py

@@ -0,0 +1,453 @@
+"""Translate a ``.sem`` stage file into the verb argv it stands for (D17).
+
+A ``.sem`` file is TOML pinning exactly one verb invocation; the shebang line
+``#!/usr/bin/env -S smartpipe run`` is legal because ``#`` opens a TOML comment.
+The format is a public contract from day one, so validation is exhaustive and
+loud: unknown keys are *errors* (scripts run unattended — the opposite trade
+from config.toml's forward-compat ignore), types are checked with the offending
+line echoed back, and ``run``/``config`` can never be scripted.
+
+Pure translation — no click, no I/O beyond reading the file.
+"""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from dataclasses import dataclass
+from itertools import chain
+from typing import TYPE_CHECKING
+
+from smartpipe.core.errors import UsageFault
+from smartpipe.core.jsontools import as_items
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+    from pathlib import Path
+
+__all__ = ["Stage", "parse_pipeline", "parse_sem"]
+
+_VERB_NAMES = (
+    "map, extend, filter, where, embed, top_k, reduce, join, split, "
+    "distinct, outliers, cluster, diff, summarize, sample, getschema, sort, chart"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class _KeySpec:
+    expected: str  # names the type in the wrong-type screen
+    accepts: Callable[[object], bool]
+    render: Callable[[object, Path], tuple[str, ...]]
+
+
+# --- type checks (TOML value space) -------------------------------------------------
+
+
+def _is_str(value: object) -> bool:
+    return isinstance(value, str)
+
+
+def _is_int(value: object) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def _is_number(value: object) -> bool:  # `threshold = 1` is fine; demanding 1.0 is pedantry
+    return isinstance(value, int | float) and not isinstance(value, bool)
+
+
+def _is_bool(value: object) -> bool:
+    return isinstance(value, bool)
+
+
+def _is_str_list(value: object) -> bool:
+    entries = as_items(value)
+    return entries is not None and all(isinstance(entry, str) for entry in entries)
+
+
+def _str_entries(value: object) -> tuple[str, ...]:
+    entries = as_items(value)
+    assert entries is not None  # accepts() proved it before render runs
+    return tuple(entry for entry in entries if isinstance(entry, str))
+
+
+# --- renderers: TOML value → argv chunk ----------------------------------------------
+
+
+def _positional(value: object, _sem_dir: Path) -> tuple[str, ...]:
+    return (str(value),)
+
+
+def _flag(name: str) -> Callable[[object, Path], tuple[str, ...]]:
+    def render(value: object, _sem_dir: Path) -> tuple[str, ...]:
+        return (name, str(value))
+
+    return render
+
+
+def _switch(name: str) -> Callable[[object, Path], tuple[str, ...]]:
+    def render(value: object, _sem_dir: Path) -> tuple[str, ...]:
+        return (name,) if value else ()
+
+    return render
+
+
+def _fields_arg(value: object, _sem_dir: Path) -> tuple[str, ...]:
+    return ("--fields", ",".join(_str_entries(value)))
+
+
+def _globs(value: object, _sem_dir: Path) -> tuple[str, ...]:
+    # globs resolve against the CWD, exactly like typing --in at the shell
+    return tuple(chain.from_iterable(("--in", pattern) for pattern in _str_entries(value)))
+
+
+def _schema(value: object, sem_dir: Path) -> tuple[str, ...]:
+    assert isinstance(value, str)  # a script and its schema travel together
+    return ("--schema", str((sem_dir / value).resolve()))
+
+
+def _prompt_file(value: object, sem_dir: Path) -> tuple[str, ...]:
+    assert isinstance(value, str)  # a script and its prompt travel together (D23)
+    return ("--prompt-file", str((sem_dir / value).resolve()))
+
+
+def _right(value: object, sem_dir: Path) -> tuple[str, ...]:
+    assert isinstance(value, str)  # a script and its right side travel together (D21)
+    return ("--right", str((sem_dir / value).resolve()))
+
+
+def _str_key(render: Callable[[object, Path], tuple[str, ...]]) -> _KeySpec:
+    return _KeySpec("a string", _is_str, render)
+
+
+def _int_key(render: Callable[[object, Path], tuple[str, ...]]) -> _KeySpec:
+    return _KeySpec("a whole number", _is_int, render)
+
+
+def _num_key(render: Callable[[object, Path], tuple[str, ...]]) -> _KeySpec:
+    return _KeySpec("a number", _is_number, render)
+
+
+def _bool_key(render: Callable[[object, Path], tuple[str, ...]]) -> _KeySpec:
+    return _KeySpec("true or false", _is_bool, render)
+
+
+def _list_key(render: Callable[[object, Path], tuple[str, ...]]) -> _KeySpec:
+    return _KeySpec("an array of strings", _is_str_list, render)
+
+
+# --- the per-verb key tables (emit order is the tuple order; a public contract) -------
+
+_COMMON_TAIL: tuple[tuple[str, _KeySpec], ...] = (
+    ("concurrency", _int_key(_flag("--concurrency"))),
+    ("max-calls", _int_key(_flag("--max-calls"))),
+    ("in", _list_key(_globs)),
+    ("from-files", _bool_key(_switch("--from-files"))),
+)
+
+_VERB_KEYS: Mapping[str, tuple[tuple[str, _KeySpec], ...]] = {
+    "map": (
+        ("prompt", _str_key(_positional)),
+        ("prompt-file", _str_key(_prompt_file)),
+        ("model", _str_key(_flag("--model"))),
+        ("output", _str_key(_flag("--output"))),
+        ("fields", _list_key(_fields_arg)),
+        ("schema-file", _str_key(_schema)),
+        ("schema-from", _str_key(_flag("--schema-from"))),
+        *_COMMON_TAIL,
+    ),
+    "filter": (
+        ("prompt", _str_key(_positional)),
+        ("allow-captions", _bool_key(_switch("--allow-captions"))),
+        ("prompt-file", _str_key(_prompt_file)),
+        ("model", _str_key(_flag("--model"))),
+        ("not", _bool_key(_switch("--not"))),
+        *_COMMON_TAIL,
+    ),
+    "embed": (
+        ("allow-captions", _bool_key(_switch("--allow-captions"))),
+        ("embed-model", _str_key(_flag("--embed-model"))),
+        ("fields", _list_key(_fields_arg)),
+        *_COMMON_TAIL,
+    ),
+    "top_k": (
+        ("k", _int_key(_positional)),
+        ("allow-captions", _bool_key(_switch("--allow-captions"))),
+        ("near", _str_key(_flag("--near"))),
+        ("threshold", _num_key(_flag("--threshold"))),
+        ("embed-model", _str_key(_flag("--embed-model"))),
+        ("fields", _list_key(_fields_arg)),
+        ("stream", _bool_key(_switch("--stream"))),
+        *_COMMON_TAIL,
+    ),
+    "split": (  # no model and no concurrency — split never calls one
+        ("by", _str_key(_flag("--by"))),
+        ("media", _bool_key(_switch("--media"))),
+        ("max-tokens", _int_key(_flag("--max-tokens"))),
+        ("in", _list_key(_globs)),
+        ("from-files", _bool_key(_switch("--from-files"))),
+    ),
+    "join": (
+        ("prompt", _str_key(_positional)),
+        ("allow-captions", _bool_key(_switch("--allow-captions"))),
+        ("prompt-file", _str_key(_prompt_file)),
+        ("right", _str_key(_right)),
+        ("k", _int_key(_flag("--k"))),
+        ("threshold", _num_key(_flag("--threshold"))),
+        ("model", _str_key(_flag("--model"))),
+        ("embed-model", _str_key(_flag("--embed-model"))),
+        ("output", _str_key(_flag("--output"))),
+        ("fields", _list_key(_fields_arg)),
+        *_COMMON_TAIL,
+    ),
+    "reduce": (
+        ("prompt", _str_key(_positional)),
+        ("allow-captions", _bool_key(_switch("--allow-captions"))),
+        ("prompt-file", _str_key(_prompt_file)),
+        ("model", _str_key(_flag("--model"))),
+        ("group-by", _str_key(_flag("--group-by"))),
+        ("window", _int_key(_flag("--window"))),
+        ("every", _int_key(_flag("--every"))),
+        ("verbose", _bool_key(_switch("--verbose"))),
+        ("schema-file", _str_key(_schema)),
+        ("schema-from", _str_key(_flag("--schema-from"))),
+        ("tally", _str_key(_flag("--tally"))),
+        ("explode", _str_key(_flag("--explode"))),
+        ("fields", _list_key(_fields_arg)),
+        *_COMMON_TAIL,
+    ),
+    "where": (("predicate", _str_key(_positional)),),
+    "extend": (
+        ("prompt", _str_key(_positional)),
+        ("prompt-file", _str_key(_prompt_file)),
+        ("model", _str_key(_flag("--model"))),
+        ("output", _str_key(_flag("--output"))),
+        ("fields", _list_key(_fields_arg)),
+        ("schema-file", _str_key(_schema)),
+        ("schema-from", _str_key(_flag("--schema-from"))),
+        ("tally", _str_key(_flag("--tally"))),
+        ("explode", _str_key(_flag("--explode"))),
+        *_COMMON_TAIL,
+    ),
+    "distinct": (
+        ("show-groups", _bool_key(_switch("--show-groups"))),
+        ("threshold", _num_key(_flag("--threshold"))),
+        ("allow-captions", _bool_key(_switch("--allow-captions"))),
+        ("embed-model", _str_key(_flag("--embed-model"))),
+        *_COMMON_TAIL,
+    ),
+    "outliers": (
+        ("count", _int_key(_positional)),
+        ("allow-captions", _bool_key(_switch("--allow-captions"))),
+        ("embed-model", _str_key(_flag("--embed-model"))),
+        *_COMMON_TAIL,
+    ),
+    "cluster": (
+        ("k", _int_key(_flag("--k"))),
+        ("top", _int_key(_flag("--top"))),
+        ("explode", _str_key(_flag("--explode"))),
+        ("model", _str_key(_flag("--model"))),
+        ("embed-model", _str_key(_flag("--embed-model"))),
+        ("allow-captions", _bool_key(_switch("--allow-captions"))),
+        *_COMMON_TAIL,
+    ),
+    "diff": (
+        ("right", _str_key(_right)),
+        ("top", _int_key(_flag("--top"))),
+        ("all", _bool_key(_switch("--all"))),
+        ("model", _str_key(_flag("--model"))),
+        ("embed-model", _str_key(_flag("--embed-model"))),
+        ("allow-captions", _bool_key(_switch("--allow-captions"))),
+        ("concurrency", _int_key(_flag("--concurrency"))),
+        ("max-calls", _int_key(_flag("--max-calls"))),
+    ),
+    "summarize": (("expression", _str_key(_positional)),),
+    "sample": (
+        ("count", _int_key(_positional)),
+        ("seed", _int_key(_flag("--seed"))),
+    ),
+    "getschema": (("all", _bool_key(_switch("--all"))),),
+    "sort": (
+        ("by", _str_key(_flag("--by"))),
+        ("desc", _bool_key(_switch("--desc"))),
+    ),
+    "chart": (
+        ("field", _str_key(_positional)),
+        ("facet", _str_key(_flag("--facet"))),
+        ("by-time", _str_key(_flag("--by-time"))),
+        ("top", _int_key(_flag("--top"))),
+        ("save", _str_key(_flag("--save"))),
+        ("title", _str_key(_flag("--title"))),
+    ),
+}
+
+_REQUIRES_PROMPT = ("map", "extend", "filter", "reduce", "join")
+_REQUIRED_KEY: Mapping[str, str] = {
+    "where": "predicate",
+    "summarize": "expression",
+    "sample": "count",
+    "sort": "by",
+    "diff": "right",
+}
+
+
+def parse_sem(path: Path) -> list[str]:
+    """The argv the ``.sem`` file stands for — or a ``UsageFault`` naming what's wrong."""
+    try:
+        document = tomllib.loads(path.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as exc:
+        raise UsageFault(_syntax_screen(path, exc)) from exc
+    verb = _checked_verb(path, document)
+    table = _VERB_KEYS[verb]
+    valid = tuple(key for key, _spec in table)
+    unknown = next((key for key in document if key != "verb" and key not in valid), None)
+    if unknown is not None:
+        raise UsageFault(
+            f"{path}: unknown key {unknown!r} — valid keys for {verb}: {', '.join(sorted(valid))}\n"
+            "  A .sem script runs unattended — a typo silently ignored would be a disaster.\n"
+            f"  Fix the key, then: smartpipe run {path}"
+        )
+    if verb in _REQUIRES_PROMPT and "prompt" not in document and "prompt-file" not in document:
+        raise UsageFault(f'{path}: {verb} needs a prompt\n  Add one: prompt = "..."')
+    needed = _REQUIRED_KEY.get(verb)
+    if needed is not None and needed not in document:
+        raise UsageFault(f'{path}: {verb} needs {needed!r}\n  Add one: {needed} = "..."')
+    argv = [verb]
+    for key, spec in table:
+        if key not in document:
+            continue
+        value = document[key]
+        if not spec.accepts(value):
+            raise UsageFault(_wrong_type_screen(path, key, spec.expected, value))
+        argv.extend(spec.render(value, path.parent))
+    return argv
+
+
+def _checked_verb(path: Path, document: Mapping[str, object]) -> str:
+    verb = document.get("verb")
+    if verb is None:
+        raise UsageFault(
+            f"{path}: 'verb' is required ({_VERB_NAMES})\n"
+            "  A .sem file is one saved pipe stage: a verb plus its keys.\n"
+            '  Start it with: verb = "map"'
+        )
+    if not isinstance(verb, str):
+        raise UsageFault(_wrong_type_screen(path, "verb", "a string", verb))
+    if verb in ("run", "config"):
+        spelled_out = _VERB_NAMES.replace(", reduce", ", or reduce")
+        raise UsageFault(
+            f"{path}: verb {verb!r} can't run from a script — use {spelled_out}\n"
+            "  Scripts hold pipe stages; composition and setup stay at the shell."
+        )
+    if verb not in _VERB_KEYS:
+        raise UsageFault(
+            f"{path}: verb {verb!r} isn't one of {_VERB_NAMES}\n"
+            "  A .sem file is one saved pipe stage: a verb plus its keys."
+        )
+    return verb
+
+
+def _wrong_type_screen(path: Path, key: str, expected: str, value: object) -> str:
+    return (
+        f"{path}: key {key!r} should be {expected}\n"
+        f"  got: {key} = {value!r}\n"
+        f"  Fix the line, then: smartpipe run {path}"
+    )
+
+
+def _syntax_screen(path: Path, exc: tomllib.TOMLDecodeError) -> str:
+    detail = str(exc)
+    located = re.search(r"at line (\d+)", detail)
+    location = f", line {located.group(1)}" if located else ""
+    detail = re.sub(r"\s*\(at line [^)]*\)$", "", detail)
+    return (
+        f"{path} has a syntax error\n"
+        f"  {path}{location}: {detail}\n"
+        f"  Fix the line, then: smartpipe run {path}"
+    )
+
+
+# --- multi-stage pipelines (D38/14) ---------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class Stage:
+    name: str
+    argv: tuple[str, ...]
+    input_name: str | None  # None: the previous stage (or real stdin for the first)
+
+
+def parse_pipeline(path: Path) -> tuple[Stage, ...] | None:
+    """The stages a multi-stage ``.sem`` stands for; None for single-stage
+    files (the original format is the degenerate case and stays untouched)."""
+    try:
+        document = tomllib.loads(path.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as exc:
+        raise UsageFault(_syntax_screen(path, exc)) from exc
+    from smartpipe.core.jsontools import as_record
+
+    raw_stages = document.get("stage")
+    if raw_stages is None:
+        return None
+    stages_table = as_record(raw_stages)
+    if stages_table is None:
+        raise UsageFault(f"{path}: [stage.NAME] tables expected under 'stage'")
+    others = [key for key in document if key != "stage"]
+    if others:
+        raise UsageFault(
+            f"{path}: a pipeline file holds only [stage.NAME] tables — "
+            f"found top-level {others[0]!r}\n"
+            "  Single-stage files use top-level keys; pick one shape."
+        )
+    stages: list[Stage] = []
+    seen: list[str] = []
+    for name, raw_body in stages_table.items():
+        body = as_record(raw_body)
+        if body is None:
+            raise UsageFault(f"{path}: [stage.{name}] must be a table of keys")
+        upstream_value = body.get("input")
+        upstream: str | None = None
+        if upstream_value is not None:
+            if not isinstance(upstream_value, str):
+                raise UsageFault(
+                    _wrong_type_screen(path, f"stage.{name}.input", "a string", upstream_value)
+                )
+            upstream = upstream_value
+            if upstream not in seen:
+                raise UsageFault(
+                    f"{path}: stage {name!r} reads input = {upstream!r}, "
+                    "which isn't an EARLIER stage\n"
+                    "  Stages run in file order; input names one above."
+                )
+        stage_doc = {key: value for key, value in body.items() if key != "input"}
+        argv = _stage_argv(path, name, stage_doc)
+        stages.append(Stage(name=name, argv=tuple(argv), input_name=upstream))
+        seen.append(name)
+    if not stages:
+        raise UsageFault(f"{path}: a pipeline needs at least one [stage.NAME]")
+    return tuple(stages)
+
+
+def _stage_argv(path: Path, name: str, document: dict[str, object]) -> list[str]:
+    verb = _checked_verb(path, document)
+    table = _VERB_KEYS[verb]
+    valid = tuple(key for key, _spec in table)
+    unknown = next((key for key in document if key != "verb" and key not in valid), None)
+    if unknown is not None:
+        raise UsageFault(
+            f"{path}: [stage.{name}] unknown key {unknown!r} — "
+            f"valid keys for {verb}: {', '.join(sorted(valid))}"
+        )
+    if verb in _REQUIRES_PROMPT and "prompt" not in document and "prompt-file" not in document:
+        raise UsageFault(f"{path}: [stage.{name}] {verb} needs a prompt")
+    needed = _REQUIRED_KEY.get(verb)
+    if needed is not None and needed not in document:
+        raise UsageFault(f"{path}: [stage.{name}] {verb} needs {needed!r}")
+    argv = [verb]
+    for key, spec in table:
+        if key not in document:
+            continue
+        value = document[key]
+        if not spec.accepts(value):
+            raise UsageFault(_wrong_type_screen(path, f"stage.{name}.{key}", spec.expected, value))
+        argv.extend(spec.render(value, path.parent))
+    return argv