graph-agents-cli 0.3.1__py3-none-any.whl

graph_agents_cli/peer/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2026 graph-agents-cli contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""``graph-agents-cli peer``: the other agents a project asks, over A2A (its peers)."""

graph_agents_cli/peer/_generate.py

@@ -0,0 +1,254 @@
+# Copyright 2026 graph-agents-cli contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""``<agent_dir>/tools/a2a_peers.py``, generated from ``api-policy.yaml`` alone.
+
+Every ``protocol: a2a`` API that lets the agent send it a message is a peer.
+Its name, the one the model picks it by, is the one the module already gives
+that API (``PEERS``, read with ``ast``: ``peer add NAME --api-name ...`` records
+it there), else the API's name without an ``_agent`` suffix (``orders_agent``
+is ``orders``), else the API's name (a name another peer already took keeps
+its API's name). Whether the agent
+relays the person's approvals to it (``approvals: relay``) or never decides
+them (``deny``) is read from the policy, as is its description. ``API_CALLS``
+declares exactly the calls the client makes that the policy allows (the card,
+``SendMessage``, a message that approves when relaying, one that rejects,
+``GetTask``, ``CancelTask``, the approvals ledger), so the module always passes
+``lint``. The module is data only: ``peer_tools`` builds the tools.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from graph_agents_cli._api_policy import (
+    A2A_APPROVE,
+    A2A_KEY,
+    A2A_OPERATION_KEY,
+    A2A_REJECT,
+    DESCRIPTION_KEY,
+    PROTOCOL_A2A,
+    RPC_METHOD_KEY,
+    api_protocol,
+)
+
+MODULE_NAME = "a2a_peers.py"
+MARKER = "# graph-agents-cli: generated peers v1"
+HEADER = (
+    "# Generated by `graph-agents-cli peer` from api-policy.yaml (the protocol: a2a APIs). "
+    "Do not edit:\n"
+    "# `peer add|remove|sync` rewrite this file. Put custom peer behaviour in another tool "
+    "module\n"
+    "# that uses app_utils.a2a_client.\n"
+    f"{MARKER}\n"
+)
+AGENT_SUFFIX = "_agent"
+CARD_SUFFIX = "/.well-known/agent-card.json"
+CARD_OPERATION = "getAgentCard"
+LEDGER_OPERATION = "listContextApprovals"
+LEDGER_PATH = "/threads/{context_id}/approvals"
+RELAY = "relay"
+DENY = "deny"
+PEER_NAME_RE = re.compile(r"^[a-z][a-z0-9_]{0,25}$")
+
+
+@dataclass
+class Peer:
+    """One peer as the generated module declares it."""
+
+    name: str
+    api: str
+    approvals: str
+    description: str
+    path: str
+    calls: list[dict[str, str]] = field(default_factory=list)
+
+
+def module_path(root: Path, agent_directory: str) -> Path:
+    return root / agent_directory / "tools" / MODULE_NAME
+
+
+def is_generated(text: str | None) -> bool:
+    """Whether a module's text is the generated one (it carries the marker line)."""
+    return text is not None and MARKER in text.splitlines()
+
+
+def peer_name_of(api: str, taken: set[str]) -> str:
+    """The name a peer's API gives it: without ``_agent``, unless that name is taken."""
+    if api.endswith(AGENT_SUFFIX) and len(api) > len(AGENT_SUFFIX):
+        short = api[: -len(AGENT_SUFFIX)]
+        if short not in taken:
+            return short
+    return api
+
+
+def names_in(text: str | None) -> dict[str, str]:
+    """The peer name the generated module gives each API (``PEERS``): API -> name."""
+    if not is_generated(text):
+        return {}
+    try:
+        tree = ast.parse(text or "")
+    except SyntaxError:
+        return {}
+    for node in tree.body:
+        if isinstance(node, ast.Assign) and any(
+            isinstance(t, ast.Name) and t.id == "PEERS" for t in node.targets
+        ):
+            try:
+                peers = ast.literal_eval(node.value)
+            except ValueError:
+                return {}
+            if not isinstance(peers, dict):
+                return {}
+            return {
+                str(entry["api"]): str(name)
+                for name, entry in peers.items()
+                if isinstance(entry, dict)
+                and isinstance(entry.get("api"), str)
+                and PEER_NAME_RE.fullmatch(str(name))
+            }
+    return {}
+
+
+def _candidates(api: str, path: str) -> list[tuple[str, dict[str, str]]]:
+    """Every call the A2A client may make to one peer, by what it is for."""
+    post = {"api": api, "method": "POST"}
+    return [
+        (
+            "card",
+            {
+                "api": api,
+                "method": "GET",
+                "operation_id": CARD_OPERATION,
+                "path": f"{path}{CARD_SUFFIX}",
+            },
+        ),
+        ("ask", {**post, RPC_METHOD_KEY: "SendMessage", "path": path}),
+        (
+            "approve",
+            {**post, RPC_METHOD_KEY: "SendMessage", A2A_OPERATION_KEY: A2A_APPROVE, "path": path},
+        ),
+        (
+            "reject",
+            {**post, RPC_METHOD_KEY: "SendMessage", A2A_OPERATION_KEY: A2A_REJECT, "path": path},
+        ),
+        ("status", {**post, RPC_METHOD_KEY: "GetTask", "path": path}),
+        ("cancel", {**post, RPC_METHOD_KEY: "CancelTask", "path": path}),
+        (
+            "ledger",
+            {"api": api, "method": "GET", "operation_id": LEDGER_OPERATION, "path": LEDGER_PATH},
+        ),
+    ]
+
+
+def peers_of(
+    document: Mapping[str, Any] | None, names: Mapping[str, str] | None = None
+) -> list[Peer]:
+    """The peers of a (valid) policy document, in the file's order.
+
+    ``names``: the name to keep for an API (API -> name; `names_in` the module).
+    """
+    from graph_agents_cli.dev.policy_check import STATUS_ALLOWED, DeclaredCall, check_call
+
+    apis = (document or {}).get("apis") or {}
+    peers: list[Peer] = []
+    kept = {api: name for api, name in (names or {}).items() if api in apis}
+    taken: set[str] = set()
+    for api in [str(n) for n, a in apis.items() if api_protocol(a) == PROTOCOL_A2A]:
+        settings = apis[api]
+        path = str((settings.get(A2A_KEY) or {}).get("path") or "")
+        allowed: dict[str, dict[str, str]] = {}
+        gated: set[str] = set()
+        for purpose, call in _candidates(api, path):
+            result = check_call(
+                DeclaredCall(
+                    tool=MODULE_NAME,
+                    api=api,
+                    method=call["method"],
+                    operation_id=call.get("operation_id"),
+                    path=call["path"],
+                    rpc_method=call.get(RPC_METHOD_KEY),
+                    a2a_operation=call.get(A2A_OPERATION_KEY),
+                ),
+                document,
+            )
+            if result.status == STATUS_ALLOWED:
+                allowed[purpose] = call
+                if result.gate is not None:
+                    gated.add(purpose)
+        if "ask" not in allowed:
+            continue  # an API the agent cannot send a message to is not a peer
+        wanted = kept.get(api)
+        others = {n for a, n in kept.items() if a != api} | taken
+        name = wanted if wanted and wanted not in taken else peer_name_of(api, others)
+        taken.add(name)
+        peers.append(
+            Peer(
+                name=name,
+                api=api,
+                approvals=RELAY if "approve" in allowed and "approve" in gated else DENY,
+                description=str(settings.get(DESCRIPTION_KEY) or ""),
+                path=path,
+                calls=list(allowed.values()),
+            )
+        )
+    return peers
+
+
+def _py_str(value: str) -> str:
+    """A Python string literal as ``ruff format`` writes it: double quotes, unless the text
+    holds more double quotes than single ones (fewer escapes). Policy text holds no control
+    characters (the schema refuses them), so only backslashes and the quote are escaped."""
+    quote = "'" if value.count('"') > value.count("'") else '"'
+    return quote + value.replace("\\", "\\\\").replace(quote, "\\" + quote) + quote
+
+
+def _dict_lines(entry: Mapping[str, str], indent: str) -> list[str]:
+    lines = [f"{indent}{{"]
+    lines.extend(f"{indent}    {_py_str(k)}: {_py_str(str(v))}," for k, v in entry.items())
+    lines.append(f"{indent}}},")
+    return lines
+
+
+def module_text(peers: list[Peer], agent_directory: str) -> str | None:
+    """The generated module for these peers (None: no peer, no module)."""
+    if not peers:
+        return None
+    lines = [
+        HEADER.rstrip("\n"),
+        "from __future__ import annotations",
+        "",
+        f"from {agent_directory}.app_utils.a2a_client import peer_tools",
+        "",
+        "PEERS = {",
+    ]
+    for peer in peers:
+        lines.append(f"    {_py_str(peer.name)}: {{")
+        lines.append(f'        "api": {_py_str(peer.api)},')
+        lines.append(f'        "approvals": {_py_str(peer.approvals)},')
+        lines.append(f'        "description": {_py_str(peer.description)},')
+        lines.append("    },")
+    lines.append("}")
+    lines.append("API_CALLS = [")
+    for peer in peers:
+        for call in peer.calls:
+            lines.extend(_dict_lines(call, "    "))
+    lines.append("]")
+    lines.append("TOOLS = peer_tools(PEERS)")
+    return "\n".join(lines) + "\n"