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

graph_agents_cli/system/_deploy.py

@@ -0,0 +1,215 @@
+# 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.
+
+"""``system deploy``: ``graph-agents-cli deploy --env ENV`` in every project, callees first.
+
+The projects deploy in waves: a wave holds the agents whose callees are all
+deployed, so a caller's first card check finds its peers up (a cycle is broken
+at its first agent in file order, with a warning). At most ``--parallel``
+deploys run at once (default ``deploy.parallel`` of the file, else 3): round 1
+of the experiments deployed seven agents at once and the hub took 158 s where
+27-38 s was usual. A failed wave stops the run unless ``--keep-going``. Each
+deploy is a child process in its project's directory with no terminal input,
+its output kept in a log file; the per-agent build, image load and rollout
+times are read from the commands it prints.
+
+Outside ``dev`` every project must record its kube context
+(``environments.<env>.context``): a deploy would otherwise ask to confirm the
+kubeconfig's current context, and ``system deploy`` never answers that for it.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+from collections.abc import Callable
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from graph_agents_cli.system._system import Node, System
+
+BUILD = "build"
+LOAD = "load"
+ROLL = "roll"
+# The commands `deploy` echoes (`▸ cmd` or `[dry-run] cmd`) that start each phase.
+PHASE_MARKERS: tuple[tuple[str, tuple[str, ...]], ...] = (
+    (BUILD, ("docker build",)),
+    (
+        LOAD,
+        ("kind load", "k3d image import", "minikube image load", "k3s ctr", "docker push"),
+    ),
+    (ROLL, ("helm upgrade", "helm template")),
+)
+TAIL_LINES = 15
+
+
+@dataclass
+class Outcome:
+    """One project's deploy."""
+
+    agent: str
+    exit_code: int
+    seconds: float
+    phases: dict[str, float] = field(default_factory=dict)
+    log: Path | None = None
+    tail: list[str] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return self.exit_code == 0
+
+    def describe(self) -> str:
+        phases = ", ".join(f"{name} {secs:.1f} s" for name, secs in self.phases.items())
+        timing = f"{self.seconds:.1f} s" + (f" ({phases})" if phases else "")
+        if self.ok:
+            return f"{self.agent}: deployed in {timing}"
+        return f"{self.agent}: FAILED (exit {self.exit_code}) after {timing}"
+
+
+# (node, argv after `graph-agents-cli`, log path) -> (exit code, [(seconds since start, line)])
+Runner = Callable[[Node, list[str], Path], tuple[int, list[tuple[float, str]]]]
+
+
+def run_cli(node: Node, args: list[str], log: Path) -> tuple[int, list[tuple[float, str]]]:
+    """Run ``graph-agents-cli <args>`` in ``node``'s project; every line timed and logged."""
+    command = [sys.executable, "-m", "graph_agents_cli.main", *args]
+    env = {**os.environ, "PYTHONUNBUFFERED": "1"}
+    start = time.monotonic()
+    lines: list[tuple[float, str]] = []
+    with log.open("w", encoding="utf-8") as sink:
+        process = subprocess.Popen(
+            command,
+            cwd=node.root,
+            env=env,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+        assert process.stdout is not None
+        for line in process.stdout:
+            lines.append((time.monotonic() - start, line.rstrip("\n")))
+            sink.write(line)
+            sink.flush()
+        code = process.wait()
+    return code, lines
+
+
+def phases(lines: list[tuple[float, str]], total: float) -> dict[str, float]:
+    """How long each phase took, from the first line that starts it to the next phase."""
+    starts: dict[str, float] = {}
+    for seconds, line in lines:
+        for phase, markers in PHASE_MARKERS:
+            if phase not in starts and any(marker in line for marker in markers):
+                starts[phase] = seconds
+    ordered = sorted(starts.items(), key=lambda item: item[1])
+    result = {}
+    for index, (phase, begin) in enumerate(ordered):
+        end = ordered[index + 1][1] if index + 1 < len(ordered) else total
+        result[phase] = max(0.0, end - begin)
+    return {phase: result[phase] for phase, _ in PHASE_MARKERS if phase in result}
+
+
+def waves(system: System, names: list[str]) -> tuple[list[list[str]], list[str]]:
+    """The deploy waves of ``names`` (file order within a wave), and the cycle warnings."""
+    selected = [n for n in system.nodes if n in names]
+    callees = {
+        n: {lk.callee.name for lk in system.calls(system.nodes[n])} & set(selected)
+        for n in selected
+    }
+    done: set[str] = set()
+    remaining = list(selected)
+    result: list[list[str]] = []
+    warnings: list[str] = []
+    while remaining:
+        wave = [n for n in remaining if callees[n] <= done]
+        if not wave:
+            first = remaining[0]
+            waiting = sorted(callees[first] - done)
+            warnings.append(
+                f"a cycle: {first} is deployed before {', '.join(waiting)}, which it calls "
+                "(its first card checks may fail until they are up)"
+            )
+            wave = [first]
+        result.append(wave)
+        done.update(wave)
+        remaining = [n for n in remaining if n not in done]
+    return result, warnings
+
+
+def deploy(
+    system: System,
+    env: str,
+    names: list[str],
+    *,
+    parallel: int,
+    keep_going: bool,
+    extra: list[str],
+    runner: Runner | None = None,
+    report: Callable[[str], None] = print,
+    log_dir: Path | None = None,
+) -> list[Outcome]:
+    """Deploy ``names`` wave by wave; the outcome of each deploy that ran (``runner``: how a
+    deploy runs, ``run_cli`` by default)."""
+    run = runner or run_cli
+    plan, warnings = waves(system, names)
+    for warning in warnings:
+        report(f"Warning: {warning}")
+    logs = log_dir or Path(tempfile.mkdtemp(prefix=f"gac-system-deploy-{env}-"))
+    report(f"Logs: {logs}")
+    outcomes: list[Outcome] = []
+    lock = threading.Lock()
+
+    def one(name: str) -> Outcome:
+        node = system.nodes[name]
+        log = logs / f"{name}.log"
+        start = time.monotonic()
+        try:
+            code, lines = run(node, ["deploy", "--env", env, *extra], log)
+        except OSError as exc:
+            code, lines = 2, [(0.0, f"could not run graph-agents-cli deploy: {exc}")]
+        total = time.monotonic() - start
+        outcome = Outcome(
+            agent=name,
+            exit_code=code,
+            seconds=total,
+            phases=phases(lines, total),
+            log=log,
+            tail=[line for _, line in lines[-TAIL_LINES:]],
+        )
+        with lock:
+            report(outcome.describe())
+            if not outcome.ok:
+                for line in outcome.tail:
+                    report(f"    {line}")
+                report(f"    log: {log}")
+        return outcome
+
+    for number, wave in enumerate(plan, start=1):
+        report(f"Wave {number}/{len(plan)}: {', '.join(wave)}")
+        with ThreadPoolExecutor(max_workers=max(1, parallel)) as pool:
+            results = list(pool.map(one, wave))
+        outcomes.extend(results)
+        if any(not r.ok for r in results) and not keep_going and number < len(plan):
+            skipped = [n for later in plan[number:] for n in later]
+            report(f"Stopped after wave {number}; not deployed: {', '.join(skipped)}")
+            break
+    return outcomes

graph_agents_cli/system/_model.py

@@ -0,0 +1,363 @@
+# 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-system.yaml``: the agents of a system, their projects and who calls whom.
+
+The file is optional: every project stays self-contained (``peer add`` alone is
+complete). It names each agent's project directory (relative to the file), the
+client id other agents see it as (its actor id), and the agents it calls; the
+environments the agents run in; the issuer that exchanges users' tokens; a
+shared database's connection budget; and how many projects ``system deploy``
+deploys at once. The models below are the schema: ``load`` validates a file with
+them, and ``uv run python -m graph_agents_cli.system._model`` rewrites the
+published JSON Schema (``schemas/graph-agents-system.schema.json``, which a test
+keeps equal to the models).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated, Any, Literal
+
+import click
+import yaml
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    StringConstraints,
+    ValidationError,
+    model_validator,
+)
+
+SYSTEM_FILENAME = "graph-agents-system.yaml"
+EXIT_INVALID = 3
+
+# An agent's name is the peer name its callers give it (`peer add NAME`), so it follows
+# that rule: the model picks peers by it, and the API is `<name>_agent`.
+AGENT_NAME_PATTERN = r"^[a-z][a-z0-9_]{0,25}$"
+# A client id at the issuer: the actor id callees list in AUTH_ALLOWED_ACTORS (a comma
+# list), so no comma, whitespace or control character.
+CLIENT_ID_PATTERN = r"^[^\s,\x00-\x1f\x7f]{1,256}$"
+# RFC 6749 scope tokens separated by single spaces.
+SCOPE_PATTERN = r"^[\x21\x23-\x5b\x5d-\x7e]+(?: [\x21\x23-\x5b\x5d-\x7e]+)*$"
+ENV_NAME_PATTERN = r"^[a-z][a-z0-9-]{0,30}$"
+# The placeholders an environment's url template may use.
+URL_PLACEHOLDERS = ("{agent}", "{project}", "{env}")
+
+AgentName = Annotated[str, StringConstraints(pattern=AGENT_NAME_PATTERN)]
+EnvName = Annotated[str, StringConstraints(pattern=ENV_NAME_PATTERN)]
+
+CALL_KINDS = ("ask", "status", "cancel")
+RELAY = "relay"
+DENY = "deny"
+DEFAULT_PARALLEL = 3
+MAX_PARALLEL = 16
+
+
+class _Strict(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class Edge(_Strict):
+    """One agent this agent calls, with what `peer add` would be told about it."""
+
+    agent: AgentName = Field(description="The agent called (a key of `agents`).")
+    approvals: Literal["relay", "deny"] = Field(
+        default=RELAY,
+        description=(
+            "relay: the person's decisions on the called agent's pending approvals go through "
+            "a gate here (requester); deny: this agent never sends them."
+        ),
+    )
+    auth: Literal["exchange", "forward", "bearer"] | None = Field(
+        default=None,
+        description=(
+            "How the caller authenticates; default by its auth policy (jwt: exchange, custom: "
+            "forward, shared-bearer: bearer)."
+        ),
+    )
+    scope: Annotated[str, StringConstraints(pattern=SCOPE_PATTERN)] | None = Field(
+        default=None, description="exchange: the scopes asked for (least privilege)."
+    )
+    allow_actorless: bool = Field(
+        default=False,
+        description=(
+            "exchange: accept exchanged tokens that name no actor (the called agent then lists "
+            "client:<client_id> in AUTH_ALLOWED_ACTORS)."
+        ),
+    )
+    calls: list[Literal["ask", "status", "cancel"]] | None = Field(
+        default=None,
+        description="What the caller may send: ask (SendMessage), status (GetTask), cancel.",
+    )
+    description: Annotated[str, StringConstraints(max_length=300)] | None = Field(
+        default=None,
+        description=(
+            "What the called agent does, for the caller's model (default: the called agent's "
+            "A2A_DESCRIPTION)."
+        ),
+    )
+
+    @model_validator(mode="after")
+    def _consistent(self) -> Edge:
+        if self.calls is not None and "ask" not in self.calls:
+            raise ValueError("calls must include ask")
+        if self.auth not in (None, "exchange") and (self.scope or self.allow_actorless):
+            raise ValueError("scope and allow_actorless go with auth: exchange")
+        return self
+
+
+class Agent(_Strict):
+    """One agent of the system: a graph-agents-cli project."""
+
+    project: Annotated[str, StringConstraints(min_length=1)] = Field(
+        description="The project directory, relative to this file."
+    )
+    client_id: Annotated[str, StringConstraints(pattern=CLIENT_ID_PATTERN)] | None = Field(
+        default=None,
+        description=(
+            "The client id this agent exchanges tokens with at the issuer "
+            "(TOKEN_EXCHANGE_CLIENT_ID; default: the agent's name)."
+        ),
+    )
+    actor_id: Annotated[str, StringConstraints(pattern=CLIENT_ID_PATTERN)] | None = Field(
+        default=None,
+        description=(
+            "The actor id the agents it calls see: the act.sub the issuer puts in this "
+            "agent's exchanged tokens, which their AUTH_ALLOWED_ACTORS and --relayers name "
+            "(default: client_id). Set it when the issuer names the client differently there."
+        ),
+    )
+    calls: list[AgentName | Edge] = Field(
+        default_factory=list, description="The agents this agent calls (names, or edges)."
+    )
+
+
+class Identity(_Strict):
+    """The issuer that exchanges users' tokens (RFC 8693) for the `auth: exchange` edges."""
+
+    issuer: Annotated[str, StringConstraints(min_length=1)] = Field(
+        description="Compared with each called agent's AUTH_JWT_ISSUER."
+    )
+    token_url: str | dict[EnvName, str] | None = Field(
+        default=None,
+        description=(
+            "The issuer's token endpoint (TOKEN_EXCHANGE_URL), one for every environment or one "
+            "per environment."
+        ),
+    )
+
+
+class Environment(_Strict):
+    """Where the agents run, and so the URL each is called at."""
+
+    port_base: Annotated[int, Field(ge=1024, le=65000)] | None = Field(
+        default=None,
+        description=(
+            "Local processes: the agent at position i of `agents` listens on "
+            "http://127.0.0.1:<port_base + i>."
+        ),
+    )
+    url: Annotated[str, StringConstraints(min_length=1)] | None = Field(
+        default=None,
+        description=(
+            "Each agent's URL, from a template with {agent} (and optionally {project}, {env}), "
+            "e.g. https://{agent}.agents.example.com. Without url or port_base, the in-cluster "
+            "URL of each project's chart and manifest namespace."
+        ),
+    )
+
+    @model_validator(mode="after")
+    def _one_kind(self) -> Environment:
+        if self.port_base is not None and self.url is not None:
+            raise ValueError("give port_base (local processes) or url, not both")
+        if self.url is not None and "{agent}" not in self.url and "{project}" not in self.url:
+            raise ValueError("url must hold {agent} or {project}: every agent needs its own URL")
+        return self
+
+
+class Database(_Strict):
+    """A database server the agents share (enables check SC10)."""
+
+    max_connections: dict[EnvName, Annotated[int, Field(ge=1)]] = Field(
+        default_factory=dict,
+        description="The server's max_connections, per environment.",
+    )
+
+
+class Deploy(_Strict):
+    """How `system deploy` runs."""
+
+    parallel: Annotated[int, Field(ge=1, le=MAX_PARALLEL)] = Field(
+        default=DEFAULT_PARALLEL,
+        description="How many projects deploy at once (default 3).",
+    )
+
+
+class SystemFile(_Strict):
+    """A graph-agents-cli system: agent projects that call each other."""
+
+    version: Literal[1] = Field(description="The format version: 1.")
+    name: Annotated[str, StringConstraints(pattern=r"^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$")] = Field(
+        description="The system's name."
+    )
+    agents: dict[AgentName, Agent] = Field(
+        min_length=1, description="The agents, by name (the name their callers give them)."
+    )
+    identity: Identity | None = Field(
+        default=None, description="Required when an edge uses auth: exchange."
+    )
+    environments: dict[EnvName, Environment | None] = Field(
+        default_factory=dict, description="The environments the agents run in."
+    )
+    database: Database | None = None
+    deploy: Deploy = Field(default_factory=Deploy)
+
+    def edges(self, name: str) -> list[Edge]:
+        """The edges of agent ``name``, a bare name read as an edge with the defaults."""
+        return [
+            call if isinstance(call, Edge) else Edge(agent=call) for call in self.agents[name].calls
+        ]
+
+    def environment(self, name: str) -> Environment:
+        return self.environments.get(name) or Environment()
+
+
+class SystemFileError(click.ClickException):
+    """The system file is unreadable or invalid, or names an unknown project (exit 3)."""
+
+    exit_code = EXIT_INVALID
+
+
+def find(start: Path | None = None) -> Path | None:
+    """``graph-agents-system.yaml`` in ``start`` (the working directory) or a parent."""
+    here = (start or Path.cwd()).resolve()
+    for directory in [here, *here.parents]:
+        candidate = directory / SYSTEM_FILENAME
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _where(loc: tuple[Any, ...]) -> str:
+    parts: list[str] = []
+    for part in loc:
+        if isinstance(part, int):
+            parts.append(f"[{part}]")
+        elif part == "[key]":
+            parts.append(" (the name)")
+        elif part in ("str", "Edge", "dict[str,str]") or str(part).startswith(
+            ("function-", "constrained-str", "literal[")
+        ):
+            continue  # a union branch, not a place in the file
+        else:
+            parts.append(("." if parts else "") + str(part))
+    return "".join(parts) or "(the file)"
+
+
+# A value that may be a name or an edge (a mapping) fails both branches of the union; only
+# the branch of the value's own kind says anything useful.
+_OTHER_BRANCH = {
+    dict: ("Input should be a valid string",),
+    str: ("Input should be a valid dictionary",),
+}
+
+
+def validation_errors(data: Any) -> list[str]:
+    """The schema errors of a parsed file (empty when valid)."""
+    try:
+        SystemFile.model_validate(data)
+    except ValidationError as exc:
+        seen: list[str] = []
+        for error in exc.errors():
+            noise = _OTHER_BRANCH.get(type(error.get("input")), ())
+            if any(str(error["msg"]).startswith(prefix) for prefix in noise):
+                continue
+            message = str(error["msg"]).removeprefix("Value error, ")
+            line = f"{_where(tuple(error['loc']))}: {message}"
+            if line not in seen:
+                seen.append(line)
+        return seen
+    return []
+
+
+def load(path: Path) -> SystemFile:
+    """Read and validate a system file; ``SystemFileError`` (exit 3) when it cannot be used."""
+    from graph_agents_cli._api_policy import PolicyLoader
+
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        raise SystemFileError(f"cannot read {path}: {exc}") from None
+    try:
+        data = yaml.load(text, Loader=PolicyLoader)  # refuses a repeated key
+    except yaml.YAMLError as exc:
+        raise SystemFileError(f"{path} is not valid YAML: {exc}") from None
+    errors = validation_errors(data)
+    if errors:
+        lines = "\n".join(f"  - {error}" for error in errors)
+        raise SystemFileError(f"{path} is invalid:\n{lines}")
+    return SystemFile.model_validate(data)
+
+
+# ---------------------------------------------------------------------------
+# The published JSON Schema
+# ---------------------------------------------------------------------------
+
+SCHEMA_FILE = "graph-agents-system.schema.json"
+# Repo-only, like the extension schema: for editors and the published contract.
+# <repo>/src/graph_agents_cli/system/_model.py -> <repo>/schemas/<file>
+SCHEMA_PATH = Path(__file__).resolve().parents[3] / "schemas" / SCHEMA_FILE
+SCHEMA_ID = f"https://raw.githubusercontent.com/ss7172/graph-agents-cli/main/schemas/{SCHEMA_FILE}"
+
+
+def _closed(node: Any) -> None:
+    """Mappings keyed by a pattern (agent and environment names) take no other key, as the
+    models refuse one (pydantic writes only ``patternProperties``)."""
+    if isinstance(node, dict):
+        if "patternProperties" in node and "additionalProperties" not in node:
+            node["additionalProperties"] = False
+        for value in node.values():
+            _closed(value)
+    elif isinstance(node, list):
+        for value in node:
+            _closed(value)
+
+
+def build_json_schema() -> dict[str, Any]:
+    """The file's schema as a JSON Schema 2020-12 document."""
+    schema = SystemFile.model_json_schema(by_alias=True)
+    _closed(schema)
+    return {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "$id": SCHEMA_ID,
+        **schema,
+        "title": "graph-agents-cli system (graph-agents-system.yaml, version 1)",
+        "description": (
+            "Agent projects that call each other over A2A, for `graph-agents-cli system`. "
+            "Generated from the CLI's own models: edit those, not this file."
+        ),
+    }
+
+
+def render() -> str:
+    """The schema as it is written to disk (trailing newline included)."""
+    return json.dumps(build_json_schema(), indent=2, sort_keys=False) + "\n"
+
+
+if __name__ == "__main__":
+    SCHEMA_PATH.write_text(render(), encoding="utf-8")
+    print(f"wrote {SCHEMA_PATH}")