smartpipe-cli 1.3.0__py3-none-any.whl

smartpipe/engine/runner.py

@@ -0,0 +1,175 @@
+"""Ordered, bounded-concurrency execution — the one primitive every per-item
+verb runs on (plan/architecture.md "Execution engine").
+
+Guarantees (all property-tested):
+1. Order — outcomes yield in input order, always. Grep-shaped tools that reorder
+   lines break every downstream diff/paste/log habit.
+2. Boundedness — at most ``concurrency`` workers in flight; memory O(concurrency)
+   regardless of input size, so it streams unbounded input the same as a batch.
+3. Isolation — a worker raising ``ItemError`` yields ``Skipped`` and the run
+   continues; any other exception propagates (it's a bug, crash loudly).
+4. Accounting — once enough items finish, a majority-failure run halts with
+   ``TooManyFailures`` rather than burning the whole input on a broken config.
+
+The worker is injected (a first-class async function), so this module does no
+I/O of its own and orders purely by arrival.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Generic, TypeVar
+
+from smartpipe.core.errors import ItemError, TooManyFailures
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Awaitable, Callable
+
+    from smartpipe.io.items import Item, ItemSource
+
+__all__ = [
+    "Done",
+    "FailurePolicy",
+    "ItemOutcome",
+    "Skipped",
+    "run_ordered",
+    "should_halt",
+    "should_halt_consecutive",
+]
+
+R = TypeVar("R")
+
+
+@dataclass(frozen=True, slots=True)
+class Done(Generic[R]):
+    index: int
+    value: R
+
+
+@dataclass(frozen=True, slots=True)
+class Skipped:
+    index: int
+    reason: str
+    source: ItemSource
+
+
+ItemOutcome = Done[R] | Skipped
+
+
+@dataclass(frozen=True, slots=True)
+class FailurePolicy:
+    halt_ratio: float = 0.5
+    min_sample: int = 20
+    consecutive_limit: int = 5  # D18: a doomed run must not wait for the ratio
+
+
+def should_halt(policy: FailurePolicy, *, total: int, skipped: int) -> bool:
+    """True once enough items have finished and a majority of them failed.
+    ``min_sample`` prevents a 3-item pipe halting on 2 flukes."""
+    return total >= policy.min_sample and skipped > total * policy.halt_ratio
+
+
+def should_halt_consecutive(policy: FailurePolicy, *, succeeded: bool, consecutive: int) -> bool:
+    """D18's cost guardrail: N consecutive failures with zero successes *ever* means
+    the run was doomed from item 1 — stop paying. Any success disarms this rule
+    permanently (a working run with a bad patch of input must not die early)."""
+    return not succeeded and consecutive >= policy.consecutive_limit
+
+
+async def run_ordered(
+    items: AsyncIterator[Item],
+    worker: Callable[[Item], Awaitable[R]],
+    *,
+    concurrency: int,
+    failure_policy: FailurePolicy,
+    stop: asyncio.Event | None = None,
+) -> AsyncIterator[ItemOutcome[R]]:
+    """``stop`` (set by the interrupt shell) halts *intake*: no new workers spawn,
+    but everything already in flight completes and is emitted in order — the drain
+    contract of ux.md §12.
+
+    Intake runs as its OWN task so that waiting for the next input item never
+    blocks the emission of already-completed outcomes — the streaming property
+    (a live stream can pause mid-flow; results must still come out).
+    """
+    item_iter = aiter(items)
+    pending: dict[int, asyncio.Task[ItemOutcome[R]]] = {}
+    slots = asyncio.Semaphore(concurrency)
+    progressed = asyncio.Event()  # set whenever intake adds a task or finishes
+    intake_done = False
+    next_to_emit = 0
+    total = 0
+    skipped = 0
+    consecutive = 0
+    succeeded = False
+
+    def stopping() -> bool:
+        return stop is not None and stop.is_set()
+
+    async def intake() -> None:
+        nonlocal intake_done
+        index = 0
+        try:
+            while not stopping():
+                await slots.acquire()
+                if stopping():  # woke up into a drain — don't start new work
+                    slots.release()
+                    break
+                try:
+                    item = await anext(item_iter)
+                except StopAsyncIteration:
+                    slots.release()
+                    break
+                pending[index] = asyncio.create_task(_run_one(worker, item))
+                index += 1
+                progressed.set()
+        finally:
+            intake_done = True
+            progressed.set()
+
+    intake_task = asyncio.create_task(intake())
+    try:
+        while True:
+            task = pending.get(next_to_emit)
+            if task is None:
+                if intake_done and not pending:
+                    return
+                progressed.clear()
+                # re-check before sleeping: intake may have progressed between the
+                # get() above and the clear() — a real race, so the branch can't be
+                # hit deterministically in a test; excluded rather than pretended at.
+                if next_to_emit in pending or (intake_done and not pending):  # pragma: no cover
+                    continue  # pragma: no cover
+                await progressed.wait()
+                continue
+            outcome = await task
+            del pending[next_to_emit]
+            slots.release()
+            next_to_emit += 1
+            yield outcome
+            total += 1
+            if isinstance(outcome, Skipped):
+                skipped += 1
+                consecutive += 1
+                if should_halt(failure_policy, total=total, skipped=skipped):
+                    raise TooManyFailures(skipped, total, outcome.reason)
+                if should_halt_consecutive(
+                    failure_policy, succeeded=succeeded, consecutive=consecutive
+                ):
+                    raise TooManyFailures(skipped, total, outcome.reason)
+            else:
+                consecutive = 0
+                succeeded = True
+    finally:
+        intake_task.cancel()
+        for task in pending.values():
+            task.cancel()
+        await asyncio.gather(intake_task, *pending.values(), return_exceptions=True)
+
+
+async def _run_one(worker: Callable[[Item], Awaitable[R]], item: Item) -> ItemOutcome[R]:
+    try:
+        return Done(item.source.index, await worker(item))
+    except ItemError as exc:
+        return Skipped(item.source.index, str(exc), item.source)

smartpipe/engine/schema.py

@@ -0,0 +1,208 @@
+"""Structured-output schemas (plan/decisions.md D07): shorthand synthesis,
+JSON-Schema loading, and validate-with-light-coercion of a model reply.
+
+``validate_and_coerce`` raises ``ItemError`` on any failure, with a message that
+names the problem — the ``map`` verb feeds that message back to the model as the
+single repair retry, so the message is repair context, not just a log line.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import TYPE_CHECKING
+
+from smartpipe.core.errors import ItemError, SetupFault
+from smartpipe.core.jsontools import as_items, as_record, as_str
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+    from pathlib import Path
+
+__all__ = [
+    "is_strict_compatible",
+    "load_schema",
+    "parse_schema_draft",
+    "shorthand_to_schema",
+    "validate_and_coerce",
+]
+
+_FENCE = re.compile(r"^```[A-Za-z0-9]*\n?|\n?```$")
+
+
+def shorthand_to_schema(
+    fields: Sequence[str],
+    *,
+    descriptions: Mapping[str, str] | None = None,
+    types: Mapping[str, Mapping[str, object]] | None = None,
+) -> dict[str, object]:
+    """Turn ``{vendor, total}`` fields into a strict JSON Schema. Inline types
+    (D37) and rung-2 descriptions (D22) ride each property; a fully-typed group
+    regains strict mode (every property carries a type)."""
+    notes = descriptions or {}
+    typed = types or {}
+
+    def _property(field: str) -> dict[str, object]:
+        prop: dict[str, object] = dict(typed.get(field, {}))
+        if field in notes:
+            prop["description"] = notes[field]
+        return prop
+
+    properties: dict[str, object] = {field: _property(field) for field in fields}
+    return {
+        "type": "object",
+        "properties": properties,
+        "required": list(fields),
+        "additionalProperties": False,
+    }
+
+
+def is_strict_compatible(schema: Mapping[str, object]) -> bool:
+    """Would OpenAI/Mistral ``strict: true`` json_schema mode accept this schema?
+
+    Strict mode demands, at every object layer: every property listed in
+    ``required`` and ``additionalProperties: false``. Brace-shorthand schemas
+    qualify by construction; a user ``--schema`` with optional fields does not —
+    claiming strict for it draws a 400 and skips items for the wrong reason.
+    """
+    if _looks_like_object(schema):
+        if schema.get("additionalProperties") is not False:
+            return False
+        properties = as_record(schema.get("properties")) or {}
+        required = as_items(schema.get("required")) or ()
+        required_names = {name for name in required if isinstance(name, str)}
+        if not set(properties) <= required_names:
+            return False
+        for value in properties.values():
+            child = as_record(value)
+            # live-caught (2026-07-05): strict mode also demands a 'type' per
+            # property — an untyped {} (the brace shorthand) draws the same 400
+            if child is None or ("type" not in child and "enum" not in child):
+                return False
+            if not is_strict_compatible(child):
+                return False
+    items = as_record(schema.get("items"))
+    return items is None or is_strict_compatible(items)
+
+
+def _looks_like_object(schema: Mapping[str, object]) -> bool:
+    return schema.get("type") == "object" or as_record(schema.get("properties")) is not None
+
+
+def load_schema(path: Path) -> dict[str, object]:
+    if not path.exists():
+        raise SetupFault(
+            f"error: no schema file at {path}\n  Check the --schema path and try again."
+        )
+    try:
+        loaded = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise SetupFault(
+            f"error: {path} isn't valid JSON\n  {exc}\n  A --schema file must be a JSON Schema."
+        ) from exc
+    record = as_record(loaded)
+    if record is None:
+        raise SetupFault(
+            f"error: {path} isn't a JSON Schema\n  The top level must be a JSON object."
+        )
+    return dict(record)
+
+
+def parse_schema_draft(reply: str) -> dict[str, object]:
+    """Rung 4 (D22): a model-drafted schema, validated against the JSON-Schema
+    meta-schema AND our loader rules — ``ItemError`` names what's wrong (repair
+    context). An invalid draft must never reach stdout."""
+    import jsonschema
+
+    record = as_record(_extract_json(reply))  # ItemError when there's no JSON at all
+    if record is None:
+        raise ItemError("the draft isn't a JSON object")
+    candidate = dict(record)
+    try:
+        jsonschema.Draft202012Validator.check_schema(candidate)
+    except jsonschema.SchemaError as exc:
+        raise ItemError(f"not a valid JSON Schema: {exc.message}") from exc
+    return candidate
+
+
+def validate_and_coerce(reply: str, schema: Mapping[str, object]) -> dict[str, object]:
+    import jsonschema  # function-local: --help must not pay for the validator stack
+
+    record = as_record(_extract_json(reply))
+    if record is None:
+        raise ItemError("model returned JSON but not an object")
+    coerced = _coerce(record, schema)
+    trimmed = _drop_extra(coerced, schema)
+    try:
+        jsonschema.validate(trimmed, dict(schema))
+    except jsonschema.ValidationError as exc:
+        raise ItemError(f"output does not match the schema: {exc.message}") from exc
+    return trimmed
+
+
+def _extract_json(reply: str) -> object:
+    text = reply.strip()
+    if text.startswith("```"):
+        text = _FENCE.sub("", text).strip()
+    for candidate in _json_candidates(text):
+        try:
+            return json.loads(candidate)
+        except json.JSONDecodeError:
+            continue
+    raise ItemError("model did not return valid JSON")
+
+
+def _json_candidates(text: str) -> tuple[str, ...]:
+    start = text.find("{")
+    end = text.rfind("}")
+    if start != -1 and end > start:
+        return (text, text[start : end + 1])
+    return (text,)
+
+
+def _coerce(record: Mapping[str, object], schema: Mapping[str, object]) -> dict[str, object]:
+    properties = as_record(schema.get("properties")) or {}
+    return {
+        key: _coerce_scalar(value, as_record(properties.get(key))) for key, value in record.items()
+    }
+
+
+def _coerce_scalar(value: object, prop_schema: Mapping[str, object] | None) -> object:
+    if prop_schema is None or not isinstance(value, str):
+        return value
+    text = value.strip()
+    match as_str(prop_schema.get("type")):
+        case "integer":
+            return int(text) if _is_int(text) else value
+        case "number":
+            return float(text) if _is_float(text) else value
+        case "boolean":
+            return _as_bool(text, fallback=value)
+        case "null":
+            return None if text == "null" else value
+        case _:
+            return value
+
+
+def _drop_extra(record: dict[str, object], schema: Mapping[str, object]) -> dict[str, object]:
+    if schema.get("additionalProperties") is not False:
+        return record
+    allowed = as_record(schema.get("properties")) or {}
+    return {key: value for key, value in record.items() if key in allowed}
+
+
+def _is_int(text: str) -> bool:
+    return bool(re.fullmatch(r"[+-]?\d+", text))
+
+
+def _is_float(text: str) -> bool:
+    return bool(re.fullmatch(r"[+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?", text))
+
+
+def _as_bool(text: str, *, fallback: object) -> object:
+    lowered = text.lower()
+    if lowered == "true":
+        return True
+    if lowered == "false":
+        return False
+    return fallback

smartpipe/engine/schema_dsl.py

@@ -0,0 +1,144 @@
+"""Rung 3 of the schema ladder (D22): a deterministic mini-DSL → JSON Schema.
+
+``vendor string; total number >= 0; status enum(paid, unpaid)`` — parsed with
+zero model calls and zero I/O, so a typo fails at argv time, before anything
+could cost money (D18 applied to schemas). Everything richer than this grammar
+belongs in a ``--schema`` file; the error screens say so.
+
+Grammar (pinned in ux.md):
+    fields      ::= field (";" field)*
+    field       ::= name type constraint*
+    type        ::= string | number | integer | boolean | enum(a, b, …)
+                  | string[] | number[]
+    constraint  ::= ">=" N | "<=" N | minLength=N | maxLength=N | optional
+"""
+
+from __future__ import annotations
+
+import re
+
+from smartpipe.core.errors import UsageFault
+
+__all__ = ["TYPE_MENU", "dsl_to_schema", "type_token"]
+
+_NAME = re.compile(r"[A-Za-z_][A-Za-z0-9_]*\Z")
+_HELP = (
+    "\n  Types: string · number · integer · boolean · enum(a, b, …) · string[] · number[]"
+    "\n  Constraints: >= N · <= N · minLength=N · maxLength=N · optional"
+)
+
+_SIMPLE_TYPES: dict[str, dict[str, object]] = {
+    "string": {"type": "string"},
+    "number": {"type": "number"},
+    "integer": {"type": "integer"},
+    "boolean": {"type": "boolean"},
+    "string[]": {"type": "array", "items": {"type": "string"}},
+    "number[]": {"type": "array", "items": {"type": "number"}},
+}
+
+_BOUND = re.compile(r"(>=|<=)\s*(-?\d+(?:\.\d+)?)")
+_LENGTH = re.compile(r"(minLength|maxLength)=(\d+)")
+
+
+TYPE_MENU = "string · number · integer · boolean · enum(a, b, …) · string[] · number[]"
+
+
+def type_token(token: str) -> dict[str, object] | None:
+    """One type token → a property dict, or None when it isn't a type.
+
+    Shared vocabulary with the braces (D37): one grammar, two homes."""
+    simple = _SIMPLE_TYPES.get(token)
+    if simple is not None:
+        return dict(simple)
+    if token.startswith("enum(") and token.endswith(")"):
+        values = [value.strip() for value in token[5:-1].split(",") if value.strip()]
+        return {"enum": values} if values else None
+    return None
+
+
+def dsl_to_schema(text: str) -> dict[str, object]:
+    """Parse the ``--schema-from`` DSL; every problem is a loud, free UsageFault."""
+    properties: dict[str, object] = {}
+    required: list[str] = []
+    fields = [field.strip() for field in text.split(";") if field.strip()]
+    if not fields:
+        raise UsageFault(f"--schema-from describes no fields{_HELP}")
+    for field in fields:
+        name, prop, is_required = _parse_field(field)
+        if name in properties:
+            raise UsageFault(f"--schema-from names {name!r} more than once{_HELP}")
+        properties[name] = prop
+        if is_required:
+            required.append(name)
+    return {
+        "type": "object",
+        "properties": properties,
+        "required": required,
+        "additionalProperties": False,
+    }
+
+
+def _parse_field(field: str) -> tuple[str, dict[str, object], bool]:
+    name, _space, rest = field.partition(" ")
+    if not _NAME.match(name):
+        raise UsageFault(f"--schema-from: field names must be identifiers, got {name!r}{_HELP}")
+    rest = rest.strip()
+    prop, remainder = _parse_type(name, rest)
+    prop, remainder, is_required = _parse_constraints(name, prop, remainder)
+    if remainder:
+        raise UsageFault(f"--schema-from: unexpected {remainder!r} for field {name!r}{_HELP}")
+    return name, prop, is_required
+
+
+def _parse_type(name: str, rest: str) -> tuple[dict[str, object], str]:
+    if rest.startswith("enum("):
+        close = rest.find(")")
+        if close == -1:
+            raise UsageFault(f"--schema-from: unclosed enum( for field {name!r}{_HELP}")
+        values = [value.strip() for value in rest[len("enum(") : close].split(",")]
+        values = [value for value in values if value]
+        if not values:
+            raise UsageFault(f"--schema-from: enum needs at least one value for {name!r}{_HELP}")
+        return {"enum": values}, rest[close + 1 :].strip()
+    head, _space, tail = rest.partition(" ")
+    simple = _SIMPLE_TYPES.get(head)
+    if simple is None:
+        offending = head if head else "(nothing)"
+        raise UsageFault(f"--schema-from: unexpected {offending!r} for field {name!r}{_HELP}")
+    return dict(simple), tail.strip()
+
+
+def _parse_constraints(
+    name: str, prop: dict[str, object], remainder: str
+) -> tuple[dict[str, object], str, bool]:
+    is_required = True
+    kind = prop.get("type")
+    while remainder:
+        if remainder.startswith("optional"):
+            is_required = False
+            remainder = remainder[len("optional") :].strip()
+            continue
+        bound = _BOUND.match(remainder)
+        if bound is not None:
+            if kind not in ("number", "integer"):
+                raise UsageFault(
+                    f"--schema-from: {bound.group(1)} only applies to number/integer "
+                    f"(field {name!r} is {kind or 'enum'}){_HELP}"
+                )
+            key = "minimum" if bound.group(1) == ">=" else "maximum"
+            value = bound.group(2)
+            prop[key] = int(value) if "." not in value else float(value)
+            remainder = remainder[bound.end() :].strip()
+            continue
+        length = _LENGTH.match(remainder)
+        if length is not None:
+            if kind != "string":
+                raise UsageFault(
+                    f"--schema-from: {length.group(1)} only applies to string "
+                    f"(field {name!r} is {kind or 'enum'}){_HELP}"
+                )
+            prop[length.group(1)] = int(length.group(2))
+            remainder = remainder[length.end() :].strip()
+            continue
+        break  # unconsumed — the caller names it
+    return prop, remainder, is_required

smartpipe/engine/tally.py

@@ -0,0 +1,53 @@
+"""``--tally FIELD``: count a field's values across structured results (pure)."""
+
+from __future__ import annotations
+
+from collections import Counter
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+__all__ = ["Tally", "explode_record", "render_tally"]
+
+_MISSING = "(missing)"
+_TOP_LIVE = 3  # the status line shows the leaders; the final line shows everything
+
+
+class Tally:
+    """Counts one field's values as structured results land."""
+
+    def __init__(self, field: str) -> None:
+        self.field = field
+        self.counts: Counter[str] = Counter()
+
+    def add(self, record: Mapping[str, object]) -> None:
+        value = record.get(self.field, None)
+        self.counts[_MISSING if value is None else str(value)] += 1
+
+    def live_segment(self) -> str:
+        return render_tally(self.counts, limit=_TOP_LIVE)
+
+    def final_line(self) -> str:
+        return f"tally: {render_tally(self.counts, limit=None)}"
+
+
+def render_tally(counts: Counter[str], *, limit: int | None) -> str:
+    ranked = counts.most_common(limit)
+    rendered = " · ".join(f"{value} {count}" for value, count in ranked)
+    if limit is not None and len(counts) > limit:
+        rendered += " · …"
+    return rendered
+
+
+def explode_record(record: Mapping[str, object], field: str) -> list[dict[str, object]]:
+    """``--explode``: one row per element of a list-valued field, sibling fields
+    copied. Non-lists (including a missing field) pass through as one row."""
+    from smartpipe.core.jsontools import as_items
+
+    value = as_items(record.get(field))
+    if value is None:
+        return [dict(record)]
+    if not value:
+        return []  # an empty list is zero rows — nothing to say, honestly
+    return [{**record, field: element} for element in value]

smartpipe/engine/timebin.py

@@ -0,0 +1,67 @@
+"""Time bucketing for chart/summarize (D38/13, KQL ``bin()``) — pure, fenced.
+
+The fence IS the design: timestamps parse as ISO-8601 or epoch
+seconds/milliseconds, nothing else — timestamp-format hell is the swamp KQL
+never had to cross (its ingest normalizes time), and we refuse to cross it
+one format at a time. Labels are UTC.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from smartpipe.core.errors import UsageFault
+
+__all__ = ["BUCKETS_MENU", "bucket_label", "parse_bucket", "parse_timestamp"]
+
+_BUCKETS: dict[str, int] = {
+    "1m": 60,
+    "5m": 300,
+    "15m": 900,
+    "1h": 3_600,
+    "6h": 21_600,
+    "1d": 86_400,
+}
+
+BUCKETS_MENU = (
+    "error: unknown time bucket\n"
+    "  Buckets: 1m · 5m · 15m · 1h · 6h · 1d\n"
+    "  Example: smartpipe chart --by-time ts:1h"
+)
+
+_EPOCH_MILLIS_FLOOR = 1e11  # numbers past this are milliseconds, not seconds
+
+
+def parse_bucket(text: str) -> int:
+    seconds = _BUCKETS.get(text.strip())
+    if seconds is None:
+        raise UsageFault(BUCKETS_MENU + f"\n  (got: {text!r})")
+    return seconds
+
+
+def parse_timestamp(value: object) -> float | None:
+    """Epoch seconds from ISO-8601 or epoch numbers; None means unparseable
+    (the caller tallies and discloses — silence must never lie)."""
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, (int, float)):
+        number = float(value)
+        return number / 1000.0 if number >= _EPOCH_MILLIS_FLOOR else number
+    if isinstance(value, str):
+        text = value.strip().replace("Z", "+00:00")
+        try:
+            moment = datetime.fromisoformat(text)
+        except ValueError:
+            return None
+        if moment.tzinfo is None:
+            moment = moment.replace(tzinfo=UTC)  # naive reads as UTC, documented
+        return moment.timestamp()
+    return None
+
+
+def bucket_label(epoch: float, bucket_seconds: int) -> str:
+    floored = int(epoch // bucket_seconds) * bucket_seconds
+    moment = datetime.fromtimestamp(floored, tz=UTC)
+    if bucket_seconds >= 86_400:
+        return moment.strftime("%Y-%m-%d")
+    return moment.strftime("%H:%M")

smartpipe/engine/units.py

@@ -0,0 +1,43 @@
+"""``split --by`` grammar (D26/D27): UNIT[:N], parsed deterministically, free."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from smartpipe.core.errors import UsageFault
+
+__all__ = ["SplitBy", "parse_by"]
+
+Unit = Literal["tokens", "pages", "minutes", "seconds"]
+
+_DEFAULTS: dict[Unit, int] = {"tokens": 2_000, "pages": 1, "minutes": 10, "seconds": 600}
+_HELP = "\n  Examples: --by pages · --by pages:5 · --by minutes:10 · --by tokens:2000"
+
+
+@dataclass(frozen=True, slots=True)
+class SplitBy:
+    unit: Unit
+    amount: int
+
+    @property
+    def slice_seconds(self) -> int:
+        """The duration units, normalized to seconds."""
+        assert self.unit in ("minutes", "seconds")
+        return self.amount * 60 if self.unit == "minutes" else self.amount
+
+
+def parse_by(text: str) -> SplitBy:
+    """``"pages"`` / ``"pages:5"`` / ``"minutes:10"`` → a validated SplitBy."""
+    unit_text, colon, amount_text = text.partition(":")
+    unit = unit_text.strip()
+    if unit not in ("tokens", "pages", "minutes", "seconds"):
+        raise UsageFault(
+            f"--by wants UNIT or UNIT:N — units: tokens, pages, minutes, seconds{_HELP}"
+        )
+    if not colon:
+        return SplitBy(unit, _DEFAULTS[unit])
+    stripped = amount_text.strip()
+    if not stripped.isdigit() or int(stripped) < 1:
+        raise UsageFault(f"--by {unit}:N wants a positive whole number, got {stripped!r}{_HELP}")
+    return SplitBy(unit, int(stripped))