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

graph_agents_cli/_defaults.py

@@ -0,0 +1,139 @@
+# 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.
+
+"""Shared defaults: model providers, runtimes, targets, CD modes.
+
+Model names are placeholders; verify
+them at release time. Nothing here imports a model SDK.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Sequence
+
+MODEL_PROVIDERS: tuple[str, ...] = ("openai", "anthropic", "gemini", "openai-compatible")
+
+# Test-only provider (LangChain GenericFakeChatModel); never offered by `create`.
+FAKE_PROVIDER = "fake"
+
+DEFAULT_MODEL_PROVIDER = "openai"
+
+DEFAULT_MODELS: dict[str, str] = {
+    "openai": "gpt-5-mini",
+    "anthropic": "claude-sonnet-5",
+    "gemini": "gemini-3.8-flash",
+    "openai-compatible": "qwen2.5:14b",
+}
+
+PROVIDER_KEY_VARS: dict[str, str] = {
+    "openai": "OPENAI_API_KEY",
+    "anthropic": "ANTHROPIC_API_KEY",
+    "gemini": "GOOGLE_API_KEY",
+    "openai-compatible": "MODEL_API_KEY",
+}
+
+RUNTIMES: tuple[str, ...] = ("fastapi", "langgraph-server")
+DEFAULT_RUNTIME = "fastapi"
+
+CHECKPOINTERS: tuple[str, ...] = ("memory", "postgres")
+
+DEPLOYMENT_TARGETS: tuple[str, ...] = ("kubernetes", "none")
+DEFAULT_DEPLOYMENT_TARGET = "kubernetes"
+
+CD_MODES: tuple[str, ...] = ("argocd", "helm-push", "skip")
+DEFAULT_CD = "skip"
+
+AUTH_POLICIES: tuple[str, ...] = ("shared-bearer", "jwt", "custom")
+DEFAULT_AUTH_POLICY = "shared-bearer"
+# Policies scaffolded as a stub the project implements: the manifest records
+# auth_policy_implemented: false for them, and deploy to staging/prod refuses
+# until the developer flips it.
+STUB_AUTH_POLICIES: frozenset[str] = frozenset({"custom"})
+# Retired policy names still accepted from an existing manifest or AUTH_POLICY.
+LEGACY_AUTH_POLICY_ALIASES: dict[str, str] = {"product-session": "custom"}
+
+_warned_aliases: set[str] = set()
+
+
+def normalize_auth_policy(value: str | None, *, warn: bool = True) -> str:
+    """The current name of an auth policy read from a manifest or the environment.
+
+    ``product-session`` is the retired name of ``custom``: it maps to ``custom``
+    with a one-line deprecation warning (once per process). ``None`` or an
+    empty value is the default policy.
+    """
+    name = (value or DEFAULT_AUTH_POLICY).strip().lower()
+    alias = LEGACY_AUTH_POLICY_ALIASES.get(name)
+    if alias is None:
+        return name
+    if warn and name not in _warned_aliases:
+        _warned_aliases.add(name)
+        print(
+            f"Warning: auth_policy '{name}' is deprecated and read as '{alias}'; "
+            f"record auth_policy: {alias} in graph-agents-cli-manifest.yaml.",
+            file=sys.stderr,
+        )
+    return alias
+
+
+def auth_policy_implemented_default(auth_policy: str) -> bool:
+    """False for a policy scaffolded as a stub (``custom``), True otherwise."""
+    return normalize_auth_policy(auth_policy, warn=False) not in STUB_AUTH_POLICIES
+
+
+ENVIRONMENTS: tuple[str, ...] = ("dev", "staging", "prod")
+
+DEFAULT_REGISTRY_HOST = "ghcr.io"
+DEFAULT_REGISTRY_PLACEHOLDER = "ghcr.io/CHANGE-ME"
+# The one command that replaces the placeholder everywhere `create` wrote it:
+# `build` and `deploy` read the manifest, Argo CD and the chart read the values,
+# and the CI workflows read .github/agent.env.
+REGISTRY_FIX_COMMAND = "graph-agents-cli scaffold enhance --registry <host>/<org>"
+REGISTRY_FIX_EFFECT = (
+    "it sets create_params.registry in graph-agents-cli-manifest.yaml, image.repository "
+    "in the chart's values.yaml and IMAGE_REPOSITORY in .github/agent.env"
+)
+
+DEFAULT_AGENT_GUIDANCE_FILENAME = "AGENTS.md"
+
+
+def default_secret_keys(
+    model_provider: str,
+    runtime: str,
+    api_token_envs: Sequence[str] = (),
+    *,
+    auth_policy: str = "shared-bearer",
+) -> list[str]:
+    """Allow-listed Secret keys for a new project.
+
+    The list follows the model provider (its key variable), the runtime (the
+    connection strings it reads) and the auth policy (``API_KEY`` only under
+    ``shared-bearer``, the one policy that reads it). ``api_token_envs`` are
+    the ``token_env`` variables of the ``auth: bearer`` APIs in
+    ``api-policy.yaml``; they are appended so each token reaches the
+    environment's Secret.
+    """
+    keys = [PROVIDER_KEY_VARS.get(model_provider, "MODEL_API_KEY"), "JUDGE_API_KEY"]
+    if runtime == "langgraph-server":
+        keys += ["DATABASE_URI", "REDIS_URI"]
+    else:
+        keys.append("POSTGRES_DSN")
+    if normalize_auth_policy(auth_policy, warn=False) == "shared-bearer":
+        keys.append("API_KEY")
+    keys.append("LANGSMITH_API_KEY")
+    for token_env in api_token_envs:
+        if token_env and token_env not in keys:
+            keys.append(token_env)
+    return keys

graph_agents_cli/_experiments.py

@@ -0,0 +1,64 @@
+# Copyright 2026 Google LLC
+# Modifications 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
+#
+#     http://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.
+
+"""Experiment flags.
+
+The registry is intentionally empty (no feature is experimental today): the
+mechanism is kept so a future flag can be gated behind
+``GRAPH_AGENTS_CLI_EXPERIMENTS='{"label": value}'`` without re-inventing it.
+The former ``build_command`` gate is gone; ``build`` is always available.
+"""
+
+import json
+import logging
+import os
+from typing import Any, NamedTuple
+
+EXPERIMENTS_ENV = "GRAPH_AGENTS_CLI_EXPERIMENTS"
+
+
+class Experiment(NamedTuple):
+    label: str
+    value_type: type
+    default_value: Any
+
+
+# Central registry of experiments: new experiment flags get added here.
+_REGISTRY: dict[str, Experiment] = {}
+
+
+def resolve_experiment(label: str) -> Any:
+    """Returns the value for the given experiment label."""
+    if label not in _REGISTRY:
+        raise ValueError(f"Unknown experiment: {label}")
+
+    exp = _REGISTRY[label]
+
+    # Check for environment variable override
+    env_val = os.environ.get(EXPERIMENTS_ENV)
+    if env_val:
+        try:
+            overrides = json.loads(env_val)
+            if label in overrides:
+                val = overrides[label]
+                # Cast to correct type if necessary
+                return exp.value_type(val)
+        except Exception as e:
+            logging.warning(
+                f"Failed to apply {EXPERIMENTS_ENV} override for '{label}', "
+                f"using default ({exp.default_value}). Error: {e}"
+            )
+
+    return exp.default_value

graph_agents_cli/_http.py

@@ -0,0 +1,192 @@
+# 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.
+
+"""HTTP clients for the CLI's own requests, and how they treat proxies.
+
+httpx takes ``HTTP_PROXY``, ``HTTPS_PROXY``, ``ALL_PROXY`` and ``NO_PROXY`` from
+the environment (and, on macOS, the system proxy settings), and it builds a
+transport for every proxy it finds when a client is created, whatever host the
+request is for. So a proxy it cannot use (an unknown scheme, or a SOCKS proxy
+without the ``socksio`` package) breaks every request, and ``NO_PROXY`` does
+not help. Coding-agent sandboxes set exactly such variables (Codex's network
+proxy: an HTTP proxy in ``HTTP(S)_PROXY`` and a ``socks5h://`` one in
+``ALL_PROXY``).
+
+The rules here:
+
+* A request to this machine (``localhost``, ``*.localhost``, a loopback or
+  unspecified address) never goes through a proxy: its client ignores the
+  environment (``trust_env=False``). That is the local server of ``run``,
+  ``eval`` and ``approvals``, and the playground.
+* Any other request honours the environment's proxies, SOCKS included
+  (graph-agents-cli depends on ``httpx[socks]``). A proxy setting httpx cannot
+  use is a :class:`ProxyConfigError`: one line that names the variable, exit 3.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import ipaddress
+import os
+import urllib.request
+from typing import Any
+from urllib.parse import urlsplit, urlunsplit
+
+import click
+import httpx
+
+EXIT_CONFIG_ERROR = 3
+# The proxy schemes httpx can use; socks5 and socks5h need the socksio package.
+SUPPORTED_PROXY_SCHEMES = ("http", "https", "socks5", "socks5h")
+SOCKS_SCHEMES = ("socks5", "socks5h")
+
+
+class ProxyConfigError(click.ClickException):
+    """A proxy setting in the environment that the CLI's HTTP client cannot use (exit 3)."""
+
+    exit_code = EXIT_CONFIG_ERROR
+
+
+def is_local(url: str | httpx.URL) -> bool:
+    """Whether ``url`` names this machine: localhost, a loopback or an unspecified address."""
+    try:
+        host = httpx.URL(url).host
+    except (httpx.InvalidURL, TypeError, ValueError):
+        return False
+    host = host.rstrip(".").lower()
+    if host == "localhost" or host.endswith(".localhost"):
+        return True
+    try:
+        address = ipaddress.ip_address(host)
+    except ValueError:
+        return False
+    return address.is_loopback or address.is_unspecified
+
+
+def _redacted(value: str) -> str:
+    """``value`` without the ``user:password@`` of a proxy URL."""
+    try:
+        parts = urlsplit(value)
+    except ValueError:
+        return "<unparseable>"
+    if "@" not in parts.netloc:
+        return value
+    return urlunsplit(parts._replace(netloc="***@" + parts.netloc.rsplit("@", 1)[1]))
+
+
+def _variable(kind: str) -> str:
+    """The environment variable httpx read the ``kind`` (http, https, all) proxy from."""
+    for name in (f"{kind}_proxy", f"{kind.upper()}_PROXY"):
+        if os.environ.get(name):
+            return name
+    return f"the system {kind.upper()} proxy setting"
+
+
+def env_proxy_problem() -> str | None:
+    """Why the environment's proxy settings would break an httpx client, or None when usable.
+
+    It checks what httpx itself reads (``urllib.request.getproxies``): every proxy
+    it would build a transport for, not only the one a request would use.
+    """
+    try:
+        proxies = urllib.request.getproxies()
+    except Exception:  # an unreadable system setting: httpx fails on it too, but say nothing
+        return None
+    for kind in ("all", "http", "https"):
+        value = (proxies.get(kind) or "").strip()
+        if not value:
+            continue
+        where = f"{_variable(kind)}={_redacted(value)}"
+        scheme = value.split("://", 1)[0].lower() if "://" in value else "http"
+        if scheme not in SUPPORTED_PROXY_SCHEMES:
+            return (
+                f"the proxy in {where} cannot be used: its scheme {scheme!r} is not one of "
+                f"{', '.join(SUPPORTED_PROXY_SCHEMES)}. Fix or unset {_variable(kind)} "
+                "(requests to this machine never use a proxy)."
+            )
+        if scheme in SOCKS_SCHEMES and importlib.util.find_spec("socksio") is None:
+            return (
+                f"the SOCKS proxy in {where} needs the socksio package, which this "
+                "installation lacks: reinstall graph-agents-cli (it depends on httpx[socks]) "
+                f"or unset {_variable(kind)} (requests to this machine never use a proxy)."
+            )
+    return None
+
+
+def check_env_proxies(url: str | httpx.URL) -> None:
+    """Raise :class:`ProxyConfigError` when a request to ``url`` would fail on a proxy setting.
+
+    Nothing to check for a local ``url``: its requests ignore the environment.
+    """
+    if is_local(url):
+        return
+    problem = env_proxy_problem()
+    if problem:
+        raise ProxyConfigError(f"Cannot send requests to {_origin(url)}: {problem}")
+
+
+def _origin(url: str | httpx.URL) -> str:
+    try:
+        parsed = httpx.URL(url)
+    except (httpx.InvalidURL, TypeError, ValueError):
+        return "the agent"
+    port = f":{parsed.port}" if parsed.port else ""
+    return f"{parsed.scheme}://{parsed.host}{port}"
+
+
+def _options(url: str | httpx.URL, kwargs: dict[str, Any]) -> dict[str, Any]:
+    if is_local(url):
+        return {**kwargs, "trust_env": False}
+    check_env_proxies(url)
+    return kwargs
+
+
+def _built(factory: Any, url: str | httpx.URL, kwargs: dict[str, Any]) -> Any:
+    options = _options(url, kwargs)
+    try:
+        return factory(**options)
+    except ImportError as exc:  # a proxy transport whose package is missing
+        raise ProxyConfigError(f"Cannot send requests to {_origin(url)}: {exc}") from exc
+
+
+def client(url: str | httpx.URL, **kwargs: Any) -> httpx.Client:
+    """An ``httpx.Client`` for requests to ``url``'s origin (see the module's proxy rules)."""
+    return _built(httpx.Client, url, kwargs)
+
+
+def async_client(url: str | httpx.URL, **kwargs: Any) -> httpx.AsyncClient:
+    """An ``httpx.AsyncClient`` for requests to ``url``'s origin (see the module's proxy rules)."""
+    return _built(httpx.AsyncClient, url, kwargs)
+
+
+def request(
+    method: str,
+    url: str | httpx.URL,
+    *,
+    timeout: float | httpx.Timeout | None = 5.0,
+    **kwargs: Any,
+) -> httpx.Response:
+    """One request, like ``httpx.request``, with the module's proxy rules."""
+    with client(url, timeout=timeout) as http:
+        return http.request(method, url, **kwargs)
+
+
+def get(url: str | httpx.URL, **kwargs: Any) -> httpx.Response:
+    """``GET url``, like ``httpx.get``, with the module's proxy rules."""
+    return request("GET", url, **kwargs)
+
+
+def delete(url: str | httpx.URL, **kwargs: Any) -> httpx.Response:
+    """``DELETE url``, like ``httpx.delete``, with the module's proxy rules."""
+    return request("DELETE", url, **kwargs)

graph_agents_cli/_output.py

@@ -0,0 +1,83 @@
+# Copyright 2026 Google LLC
+# Modifications 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.
+
+"""Output helpers for agents CLI."""
+
+import json
+import os
+import sys
+from enum import IntEnum
+from typing import Any
+
+from rich.console import Console as _RichConsole
+
+
+class ExitCode(IntEnum):
+    OK = 0
+    ERROR = 1
+
+
+# The widest a table grows off a terminal (CI logs, a pipe, a file) when COLUMNS is
+# unset: Rich would use 80 columns there and cut long cells with "…".
+NON_TERMINAL_TABLE_WIDTH = 250
+
+
+class Console(_RichConsole):
+    """Rich Console configured with project-wide defaults (soft_wrap=True)."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        kwargs.setdefault("soft_wrap", True)
+        super().__init__(*args, **kwargs)
+        self.explicit_width = kwargs.get("width") is not None
+
+
+def print_table(console: _RichConsole, table: Any) -> None:
+    """Print ``table`` whole: off a terminal it may grow past 80 columns to fit its cells.
+
+    Only when the width was not chosen (no ``width``, no ``COLUMNS``); up to
+    :data:`NON_TERMINAL_TABLE_WIDTH`, beyond which cells fold onto more lines.
+    Rules and panels printed by the same console keep the normal width.
+    """
+    chosen = (
+        getattr(console, "explicit_width", False) or (os.environ.get("COLUMNS") or "").isdigit()
+    )
+    if console.is_terminal or chosen:
+        console.print(table)
+        return
+    from rich.measure import Measurement
+
+    # Measured against the cap: the console's own options would clamp it to 80.
+    options = console.options.update_width(NON_TERMINAL_TABLE_WIDTH)
+    needed = Measurement.get(console, options, table).maximum
+    if needed <= console.width:
+        console.print(table)
+        return
+    original = console.width
+    console.width = min(needed, NON_TERMINAL_TABLE_WIDTH)
+    try:
+        console.print(table)
+    finally:
+        console.width = original
+
+
+def emit(data: dict) -> None:
+    """Write structured data to stdout."""
+    print(json.dumps(data), file=sys.stdout)
+
+
+def emit_error(msg: str, code: int = ExitCode.ERROR) -> None:
+    """Write error message to stderr and exit."""
+    print(json.dumps({"error": msg}), file=sys.stderr)
+    raise SystemExit(code)