click-agentcli 0.1.0__py3-none-any.whl

agentcli/__init__.py

@@ -0,0 +1,43 @@
+"""Shared conventions for agent-facing CLI tools."""
+
+from agentcli.candidates import (
+    KINDS,
+    MACRO_KEYS,
+    candidate,
+    macro_options,
+    matches,
+    rank,
+    unverifiable,
+)
+from agentcli.exits import (
+    AssertionFailure,
+    RemoteError,
+    StrictFailure,
+    UsageError,
+)
+from agentcli.group import JsonAwareGroup
+from agentcli.guide import guide_command
+from agentcli.output import dumps, emit, emit_error, json_option, limit_option
+from agentcli.skill import skill_group
+
+__all__ = [
+    "KINDS",
+    "MACRO_KEYS",
+    "AssertionFailure",
+    "JsonAwareGroup",
+    "RemoteError",
+    "StrictFailure",
+    "UsageError",
+    "candidate",
+    "dumps",
+    "emit",
+    "emit_error",
+    "guide_command",
+    "json_option",
+    "limit_option",
+    "macro_options",
+    "matches",
+    "rank",
+    "skill_group",
+    "unverifiable",
+]

agentcli/candidates.py

@@ -0,0 +1,141 @@
+"""A thing you could eat, and the macros you would decide on.
+
+Two questions have the same shape — "what can I cook under 400 kcal a serving
+with 30 g of protein" and "where can I eat out under 800 kcal with 35 g" — so
+the tools that answer them emit the same record. A recipe and a restaurant dish
+differ in how they came to exist and in what detail they can show, not in what
+a decision needs from them.
+
+That shared part lives here so an orchestrator merges two JSON streams and
+ranks, instead of special-casing each tool. Everything kind-specific goes under
+`detail`, which nothing shared ever reads.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import click
+
+MACRO_KEYS = ("kcal", "protein", "fat", "carbs")
+
+KINDS = ("recipe", "meal")
+
+
+def candidate(
+    *,
+    kind: str,
+    identifier: str,
+    name: str,
+    per_serving: dict[str, float | None],
+    detail: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """One comparable option, per serving.
+
+    `per_serving` carries every macro the source published and omits the rest.
+    A macro is never defaulted to zero to fill the shape: a dish whose fat was
+    never measured is not a fat-free dish, and `complete` is what tells them
+    apart.
+    """
+    if kind not in KINDS:
+        raise ValueError(f"unknown candidate kind: {kind}")
+
+    macros = {
+        key: per_serving[key]
+        for key in MACRO_KEYS
+        if per_serving.get(key) is not None
+    }
+    return {
+        "kind": kind,
+        "id": identifier,
+        "name": name,
+        "per_serving": macros,
+        "complete": len(macros) == len(MACRO_KEYS),
+        "detail": detail or {},
+    }
+
+
+def macro_options(f: Callable[..., Any]) -> Callable[..., Any]:
+    """The two filters every candidate source accepts, spelled identically."""
+    f = click.option(
+        "--min-protein",
+        type=click.FloatRange(min=0),
+        help="Least protein, in grams per serving.",
+    )(f)
+    return click.option(
+        "--max-kcal",
+        type=click.FloatRange(min=0),
+        help="Most energy, in kcal per serving.",
+    )(f)
+
+
+def matches(
+    record: dict[str, Any],
+    *,
+    max_kcal: float | None = None,
+    min_protein: float | None = None,
+) -> bool:
+    """Whether a candidate provably satisfies the constraints.
+
+    A candidate missing the macro a filter asks about is excluded, because it
+    cannot be shown to pass. Callers report those separately rather than
+    dropping them silently — "no results" and "three results I could not check"
+    are different answers.
+    """
+    macros = record["per_serving"]
+    kcal, protein = macros.get("kcal"), macros.get("protein")
+
+    # A missing macro fails the filter that asks about it rather than being
+    # treated as zero, which would pass every ceiling and fail every floor.
+    over = max_kcal is not None and (kcal is None or kcal > max_kcal)
+    under = min_protein is not None and (
+        protein is None or protein < min_protein
+    )
+
+    return not (over or under)
+
+
+def unverifiable(
+    record: dict[str, Any],
+    *,
+    max_kcal: float | None = None,
+    min_protein: float | None = None,
+) -> bool:
+    """Whether a filter was asked about a macro this candidate lacks."""
+    macros = record["per_serving"]
+    return (max_kcal is not None and macros.get("kcal") is None) or (
+        min_protein is not None and macros.get("protein") is None
+    )
+
+
+def rank(records: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Protein per 100 kcal, descending. Ties break by name, not file order.
+
+    One ranking for both kinds, so a merged list is ordered the same way
+    whoever produced it. Deterministic on every machine: no locale collation.
+    """
+
+    def key(record: dict[str, Any]) -> tuple[float, float, str]:
+        macros = record["per_serving"]
+
+        # `or 0.0` would be wrong here, and wrong in the one file that defines
+        # the missing-value contract: a published 0 kcal is a fact about black
+        # coffee, not an absent measurement. They coincide in the arithmetic
+        # below but must not coincide in the idiom.
+        kcal = macros.get("kcal")
+        protein = macros.get("protein")
+
+        density = (
+            protein / kcal * 100
+            if kcal is not None and protein is not None and kcal > 0
+            else 0.0
+        )
+
+        return (
+            -density,
+            -(protein if protein is not None else 0.0),
+            record["name"],
+        )
+
+    return sorted(records, key=key)

agentcli/candidates_test.py

@@ -0,0 +1,195 @@
+"""The contract two independent tools have to agree on without talking."""
+
+from __future__ import annotations
+
+import itertools
+
+import click
+import pytest
+from click.testing import CliRunner
+
+from agentcli.candidates import (
+    candidate,
+    macro_options,
+    matches,
+    rank,
+    unverifiable,
+)
+
+FULL = {"kcal": 384.2, "protein": 31.5, "fat": 12.1, "carbs": 38.4}
+PARTIAL = {"kcal": 540.0, "protein": 45.8, "fat": None, "carbs": None}
+
+
+def make(kind: str = "recipe", name: str = "Thing", **macros: object) -> dict:
+    return candidate(
+        kind=kind,
+        identifier=name.lower(),
+        name=name,
+        per_serving=macros or FULL,
+    )
+
+
+def test_an_unpublished_macro_is_omitted_rather_than_zeroed() -> None:
+    """A dish whose fat was never measured is not a fat-free dish."""
+    partial = candidate(
+        kind="meal", identifier="x", name="Bowl", per_serving=PARTIAL
+    )
+
+    assert partial["per_serving"] == {"kcal": 540.0, "protein": 45.8}
+    assert "fat" not in partial["per_serving"]
+    assert partial["complete"] is False
+
+
+def test_complete_means_all_four_macros_present() -> None:
+    assert make()["complete"] is True
+    assert make(kcal=1.0, protein=1.0, fat=1.0)["complete"] is False
+
+
+def test_detail_is_where_the_kinds_differ() -> None:
+    """Nothing shared reads `detail`, so the kinds cannot collide in it."""
+    meal = candidate(
+        kind="meal",
+        identifier="crust-margherita",
+        name="Margherita",
+        per_serving=FULL,
+        detail={"restaurant": "Crust Pizza", "distance_km": 1.5},
+    )
+
+    assert meal["detail"]["restaurant"] == "Crust Pizza"
+    assert set(meal) == {
+        "kind",
+        "id",
+        "name",
+        "per_serving",
+        "complete",
+        "detail",
+    }
+
+
+def test_an_unknown_kind_is_refused() -> None:
+    """A third kind is a decision, not something a caller slips in."""
+    with pytest.raises(ValueError, match="unknown candidate kind"):
+        candidate(kind="snack", identifier="x", name="X", per_serving=FULL)
+
+
+@pytest.mark.parametrize(
+    ("max_kcal", "expected"), [(384.2, True), (384.1, False), (500.0, True)]
+)
+def test_the_calorie_ceiling_is_inclusive(
+    max_kcal: float, expected: bool
+) -> None:
+    assert matches(make(), max_kcal=max_kcal) is expected
+
+
+@pytest.mark.parametrize(
+    ("min_protein", "expected"), [(31.5, True), (31.6, False), (10.0, True)]
+)
+def test_the_protein_floor_is_inclusive(
+    min_protein: float, expected: bool
+) -> None:
+    assert matches(make(), min_protein=min_protein) is expected
+
+
+def test_a_missing_macro_fails_the_filter_that_asks_about_it() -> None:
+    """Treating it as zero would pass every ceiling and fail every floor."""
+    no_kcal = make(protein=40.0, fat=1.0, carbs=1.0)
+
+    assert matches(no_kcal, max_kcal=800) is False
+    # And it is not silently a miss: the caller can say why it could not check.
+    assert unverifiable(no_kcal, max_kcal=800) is True
+    # A filter about a macro it does have is answerable as normal.
+    assert matches(no_kcal, min_protein=30) is True
+    assert unverifiable(no_kcal, min_protein=30) is False
+
+
+def test_no_filters_matches_everything_including_incomplete() -> None:
+    partial = candidate(
+        kind="meal", identifier="x", name="Bowl", per_serving=PARTIAL
+    )
+
+    assert matches(partial) is True
+    assert unverifiable(partial) is False
+
+
+def test_ranking_is_protein_density_then_name() -> None:
+    dense = make(name="Dense", kcal=200.0, protein=30.0, fat=1.0, carbs=1.0)
+    lean = make(name="Lean", kcal=600.0, protein=30.0, fat=1.0, carbs=1.0)
+
+    assert [c["name"] for c in rank([lean, dense])] == ["Dense", "Lean"]
+
+
+def test_ranking_does_not_depend_on_input_order() -> None:
+    """A merged list must be ordered the same whoever produced it."""
+    tied = [
+        make(name=name, kcal=400.0, protein=20.0, fat=1.0, carbs=1.0)
+        for name in ("Beta", "Alpha", "Gamma")
+    ]
+
+    orders = {
+        tuple(c["name"] for c in rank(list(p)))
+        for p in itertools.permutations(tied)
+    }
+
+    assert orders == {("Alpha", "Beta", "Gamma")}
+
+
+def test_a_zero_calorie_candidate_does_not_divide_by_zero() -> None:
+    """Water and black coffee are real entries, not arithmetic hazards."""
+    zero = make(name="Water", kcal=0.0, protein=0.0, fat=0.0, carbs=0.0)
+
+    assert [c["name"] for c in rank([zero, make(name="Food")])] == [
+        "Food",
+        "Water",
+    ]
+
+
+def test_both_tools_spell_the_filters_identically() -> None:
+    """The flags are shared code precisely so they cannot drift apart."""
+
+    @click.command()
+    @macro_options
+    def cli(max_kcal: float | None, min_protein: float | None) -> None:
+        click.echo(f"{max_kcal} {min_protein}")
+
+    runner = CliRunner()
+    assert runner.invoke(cli, []).output.strip() == "None None"
+    ok = runner.invoke(cli, ["--max-kcal", "400", "--min-protein", "30"])
+    assert ok.output.strip() == "400.0 30.0"
+
+    # A negative ceiling is a mistake, not something to clamp silently.
+    assert runner.invoke(cli, ["--max-kcal", "-1"]).exit_code == 1
+
+
+def test_a_published_zero_is_not_a_missing_measurement() -> None:
+    """The distinction this whole project turns on, in the file that defines it.
+
+    Black coffee at 0 kcal is a measured fact; a dish whose energy was never
+    recorded is not. They happen to rank the same, so only the idiom keeps them
+    apart -- which is exactly why it is asserted here rather than assumed.
+    """
+    measured = candidate(
+        kind="meal",
+        identifier="coffee",
+        name="Black Coffee",
+        per_serving={"kcal": 0.0, "protein": 0.0, "fat": 0.0, "carbs": 0.0},
+    )
+    unmeasured = candidate(
+        kind="meal",
+        identifier="mystery",
+        name="Mystery",
+        per_serving={"protein": 0.0, "fat": 0.0, "carbs": 0.0},
+    )
+
+    assert measured["per_serving"]["kcal"] == 0.0
+    assert measured["complete"] is True
+
+    assert "kcal" not in unmeasured["per_serving"]
+    assert unmeasured["complete"] is False
+
+    # A calorie ceiling is answerable for one and not the other.
+    assert matches(measured, max_kcal=100) is True
+    assert matches(unmeasured, max_kcal=100) is False
+    assert unverifiable(unmeasured, max_kcal=100) is True
+
+    # And neither divides by zero on the way through the shared ranking.
+    assert len(rank([measured, unmeasured])) == 2

agentcli/exits.py

@@ -0,0 +1,48 @@
+"""Deterministic exit codes, so an agent never has to read prose.
+
+| 0 | success                                                     |
+| 1 | usage error: bad flags, unparseable input, refused input     |
+| 2 | remote error: network, API, or a site refusal (never retried) |
+| 3 | assertion failure: a caller-stated expectation did not hold  |
+| 4 | data-quality warning escalated by `--strict`                 |
+
+`click.ClickException` is the base because click already routes it to stderr
+with a nonzero status; only the code differs per class.
+"""
+
+from __future__ import annotations
+
+import click
+
+# Click exits 2 for its own parse failures, which this table documents as a
+# remote error. Agents are told to branch on these codes, and reading a
+# mistyped flag as a transient outage invites a pointless retry, so click is
+# brought into line rather than the documentation bent around it.
+#
+# Applied on import of `agentcli`, which every tool does, because the same
+# correction living in each tool's cli.py is one a new tool silently forgets.
+click.UsageError.exit_code = 1
+
+
+class UsageError(click.ClickException):
+    """The request could not be understood or was refused as stated."""
+
+    exit_code = 1
+
+
+class RemoteError(click.ClickException):
+    """A remote source refused or could not answer. Never retried."""
+
+    exit_code = 2
+
+
+class AssertionFailure(click.ClickException):
+    """Something the caller asserted turned out not to hold."""
+
+    exit_code = 3
+
+
+class StrictFailure(click.ClickException):
+    """Warnings were raised and `--strict` makes them fatal."""
+
+    exit_code = 4

agentcli/exits_test.py

@@ -0,0 +1,66 @@
+"""Exit codes are the contract an agent reads instead of prose."""
+
+from __future__ import annotations
+
+import click
+import pytest
+from click.testing import CliRunner
+
+from agentcli.exits import (
+    AssertionFailure,
+    RemoteError,
+    StrictFailure,
+    UsageError,
+)
+
+DOCUMENTED = [
+    (UsageError, 1),
+    (RemoteError, 2),
+    (AssertionFailure, 3),
+    (StrictFailure, 4),
+]
+
+
+@pytest.mark.parametrize(("error", "code"), DOCUMENTED)
+def test_class_declares_documented_code(error, code) -> None:
+    assert error.exit_code == code
+
+
+@pytest.mark.parametrize(("error", "code"), DOCUMENTED)
+def test_raising_exits_with_documented_code(error, code) -> None:
+    """The number a caller sees, not just the one the class declares."""
+
+    @click.command()
+    def cmd() -> None:
+        raise error("no")
+
+    result = CliRunner().invoke(cmd, [])
+
+    assert result.exit_code == code
+
+
+def test_success_is_zero() -> None:
+    @click.command()
+    def cmd() -> None:
+        click.echo("ok")
+
+    assert CliRunner().invoke(cmd, []).exit_code == 0
+
+
+def test_click_parse_failures_are_usage_errors_not_remote_ones() -> None:
+    """A mistyped flag must not look like a network outage to an agent.
+
+    Click's own `UsageError` defaults to exit 2, the code this project reserves
+    for a remote failure. Importing agentcli has to correct that, because a
+    tool cannot opt into the convention it forgot to apply.
+    """
+
+    @click.command()
+    @click.option("--limit", type=click.IntRange(min=0), default=10)
+    def cli(limit: int) -> None:
+        click.echo(limit)
+
+    runner = CliRunner()
+    assert runner.invoke(cli, ["--limit", "-1"]).exit_code == 1
+    assert runner.invoke(cli, ["--nonexistent"]).exit_code == 1
+    assert runner.invoke(cli, []).exit_code == 0

agentcli/group.py

@@ -0,0 +1,82 @@
+"""A command group that keeps the `--json` promise even when it fails.
+
+Requesting JSON is a promise that stdout is parseable, and that has to hold for
+failures too. The hard case is a bad flag: click raises before any subcommand
+has parsed `--json`, so at that point nothing in the parsed context knows JSON
+was wanted. The raw argument list is the only place it is known that early.
+
+This lives here rather than in each tool because every tool has the same
+problem, and a tool that solves it locally is a tool the next one forgets to
+copy.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Sequence
+from typing import Any, Literal, NoReturn, overload
+
+import click
+
+from agentcli.output import emit_error
+
+
+class JsonAwareGroup(click.Group):
+    """Routes `click.ClickException` to the JSON error shape when asked."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._json_requested = False
+
+    # The overloads mirror `click.Group.main` exactly, so a caller holding a
+    # `click.Group` can call this the same way, positionals included.
+    @overload
+    def main(
+        self,
+        args: Sequence[str] | None = None,
+        prog_name: str | None = None,
+        complete_var: str | None = None,
+        standalone_mode: Literal[True] = True,
+        **extra: Any,
+    ) -> NoReturn: ...
+
+    @overload
+    def main(
+        self,
+        args: Sequence[str] | None = None,
+        prog_name: str | None = None,
+        complete_var: str | None = None,
+        standalone_mode: bool = ...,
+        **extra: Any,
+    ) -> Any: ...
+
+    def main(
+        self,
+        args: Sequence[str] | None = None,
+        prog_name: str | None = None,
+        complete_var: str | None = None,
+        standalone_mode: bool = True,
+        **extra: Any,
+    ) -> Any:
+        arguments = list(sys.argv[1:] if args is None else args)
+        self._json_requested = "--json" in arguments
+
+        return super().main(
+            arguments,
+            prog_name,
+            complete_var,
+            standalone_mode,
+            **extra,
+        )
+
+    def invoke(self, ctx: click.Context) -> Any:
+        try:
+            return super().invoke(ctx)
+        except click.ClickException as exc:
+            # The human path stays click's own, which prints the usage block
+            # too: worth more to a person than a uniform shape.
+            if not self._json_requested:
+                raise
+
+            emit_error(exc.format_message(), json_output=True)
+            ctx.exit(exc.exit_code)

agentcli/group_test.py

@@ -0,0 +1,89 @@
+"""A bad flag must still honour `--json`, before click has parsed it."""
+
+from __future__ import annotations
+
+import json
+
+import click
+import pytest
+from click.testing import CliRunner
+
+from agentcli import JsonAwareGroup, UsageError, emit
+
+
+@click.group(cls=JsonAwareGroup)
+def cli() -> None:
+    """Fixture tool."""
+
+
+@click.command("go")
+@click.option("--limit", type=click.IntRange(min=0), default=10)
+@click.option("--json", "json_output", is_flag=True)
+@click.option("--boom", is_flag=True)
+def go(limit: int, json_output: bool, boom: bool) -> None:
+    if boom:
+        raise UsageError("refused on purpose")
+    emit({"limit": limit}, json_output=json_output, human=lambda d: ["ok"])
+
+
+cli.add_command(go)
+
+
+def _run(*args: str):
+    return CliRunner().invoke(cli, list(args))
+
+
+def test_success_is_enveloped() -> None:
+    result = _run("go", "--json")
+
+    assert result.exit_code == 0
+    assert json.loads(result.output) == {"ok": True, "data": {"limit": 10}}
+
+
+def test_raised_failure_is_enveloped() -> None:
+    result = _run("go", "--json", "--boom")
+
+    assert result.exit_code == 1
+    assert json.loads(result.output) == {
+        "ok": False,
+        "error": {"message": "refused on purpose"},
+    }
+
+
+def test_parse_failure_is_enveloped_though_json_never_parsed() -> None:
+    """The hard case: click refuses before the subcommand sees --json."""
+    result = _run("go", "--json", "--limit", "-1")
+
+    assert result.exit_code == 1
+    payload = json.loads(result.output)
+    assert payload["ok"] is False
+    assert "-1" in payload["error"]["message"]
+
+
+def test_unknown_option_is_enveloped() -> None:
+    result = _run("go", "--json", "--nonexistent")
+
+    assert result.exit_code == 1
+    assert json.loads(result.output)["ok"] is False
+
+
+def test_human_path_keeps_clicks_own_usage_block() -> None:
+    """Without --json a person gets click's output, not a uniform shape."""
+    result = _run("go", "--limit", "-1")
+
+    assert result.exit_code == 1
+    assert "Usage:" in result.output
+
+
+def test_main_accepts_clicks_own_positional_arguments(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """A caller holding a `click.Group` may pass click's own positionals."""
+    group: click.Group = cli
+
+    group.main(["go", "--json"], "tool", None, False)
+
+    assert json.loads(capsys.readouterr().out) == {
+        "ok": True,
+        "data": {"limit": 10},
+    }

agentcli/guide.py

@@ -0,0 +1,21 @@
+"""`<tool> guide` — the manual, shipped inside the binary.
+
+The skill file stays a thin router precisely because the detail lives here: a
+skill installed once goes stale, while the guide is upgraded with the package
+that implements it.
+"""
+
+from __future__ import annotations
+
+import click
+
+
+def guide_command(text: str) -> click.Command:
+    """Build the `guide` subcommand for a tool's own manual text."""
+
+    @click.command("guide")
+    def guide() -> None:
+        """Print the full agent-facing manual for this tool."""
+        click.echo(text.strip())
+
+    return guide