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

graph_agents_cli/scaffold/agents/langgraph/app/app_utils/limits.py

@@ -0,0 +1,203 @@
+# 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.
+
+"""Run guardrails and request limits, read from the environment.
+
+Every limit has a default in code, so an unset variable never means
+"unlimited". A value that does not parse (or is out of range) stops the app
+at startup (`check_settings()`, called by the lifespan) instead of silently
+falling back, so a typo cannot quietly change a limit. The getters read the
+environment on every call, which keeps them easy to override in tests.
+
+| Variable                   | Default | Meaning                                              |
+|----------------------------|---------|------------------------------------------------------|
+| `RUN_TIMEOUT_S`            | 300     | wall-clock limit of one run; the run is cancelled    |
+| `RECURSION_LIMIT`          | 50      | LangGraph super-steps per run (model + tool steps)   |
+| `MAX_REQUEST_BYTES`        | 1048576 | request body cap (413 above it)                      |
+| `MAX_METADATA_KEYS`        | 16      | keys in a `/chat` `metadata` object (422 above it)   |
+| `MAX_METADATA_VALUE_CHARS` | 256     | characters per metadata key and string value (422)   |
+| `SSE_HEARTBEAT_S`          | 15      | idle seconds before a `: keep-alive` SSE comment     |
+| `RETENTION_DAYS`           | 0       | purge threads idle longer than this (0 = keep all)   |
+
+A run of the template's agent needs two steps to answer at all and two more
+for each tool call made after the previous one returned (the model step that
+asks for it, then the tool step), so `RECURSION_LIMIT` = 50 leaves room for 24
+sequential tool calls in one run (`sequential_tool_calls`). A run that
+reaches it ends with a final message saying so (`message.end` status
+`step_limit`) and keeps everything it did in the thread, so "continue" picks
+up where it stopped; `chat.py` warns at startup when an API's
+`limits.max_calls_per_run` cannot be reached within the limit.
+
+Thread ids are 1-128 letters, digits or `_ . : -` (`THREAD_ID_PATTERN`).
+"""
+
+from __future__ import annotations
+
+import math
+import os
+import re
+from collections.abc import Callable, Mapping
+from typing import Any
+
+RUN_TIMEOUT_S = ("RUN_TIMEOUT_S", 300.0)
+RECURSION_LIMIT = ("RECURSION_LIMIT", 50)
+MAX_REQUEST_BYTES = ("MAX_REQUEST_BYTES", 1_048_576)
+MAX_METADATA_KEYS = ("MAX_METADATA_KEYS", 16)
+MAX_METADATA_VALUE_CHARS = ("MAX_METADATA_VALUE_CHARS", 256)
+SSE_HEARTBEAT_S = ("SSE_HEARTBEAT_S", 15.0)
+RETENTION_DAYS = ("RETENTION_DAYS", 0)
+
+MAX_THREAD_ID_CHARS = 128
+# Letters, digits and `_ . : -`: safe in URLs, logs and SQL parameters alike.
+THREAD_ID_PATTERN = "^[A-Za-z0-9_.:-]{1," + str(MAX_THREAD_ID_CHARS) + "}$"
+_THREAD_ID = re.compile(THREAD_ID_PATTERN)
+
+
+class SettingsError(ValueError):
+    """A limit variable is set to something that is not a valid value."""
+
+
+def _raw(name: str) -> str | None:
+    value = os.environ.get(name)
+    if value is None or not value.strip():
+        return None
+    return value.strip()
+
+
+def _int(spec: tuple[str, int], *, minimum: int) -> int:
+    name, default = spec
+    raw = _raw(name)
+    if raw is None:
+        return default
+    try:
+        value = int(raw)
+    except ValueError:
+        raise SettingsError(f"{name}={raw!r} is not an integer.") from None
+    if value < minimum:
+        raise SettingsError(f"{name}={value} must be >= {minimum}.")
+    return value
+
+
+def _float(spec: tuple[str, float], *, minimum: float, exclusive: bool = True) -> float:
+    name, default = spec
+    raw = _raw(name)
+    if raw is None:
+        return default
+    try:
+        value = float(raw)
+    except ValueError:
+        raise SettingsError(f"{name}={raw!r} is not a number.") from None
+    if not math.isfinite(value) or value < minimum or (exclusive and value == minimum):
+        bound = ">" if exclusive else ">="
+        raise SettingsError(f"{name}={raw} must be a finite number {bound} {minimum}.")
+    return value
+
+
+def run_timeout_s() -> float:
+    """Seconds one run may take before it is cancelled and recorded as `timeout`."""
+    return _float(RUN_TIMEOUT_S, minimum=0)
+
+
+def recursion_limit() -> int:
+    """LangGraph's per-run step limit (`GraphRecursionError` beyond it)."""
+    return _int(RECURSION_LIMIT, minimum=1)
+
+
+def sequential_tool_calls(steps: int) -> int:
+    """How many tool calls, one after another, fit in `steps` graph steps with a final answer."""
+    return max(0, (steps - 2) // 2)
+
+
+def steps_for_tool_calls(calls: int) -> int:
+    """The `RECURSION_LIMIT` that fits `calls` sequential tool calls and a final answer."""
+    return 2 * calls + 2
+
+
+def max_request_bytes() -> int:
+    return _int(MAX_REQUEST_BYTES, minimum=1)
+
+
+def max_metadata_keys() -> int:
+    return _int(MAX_METADATA_KEYS, minimum=0)
+
+
+def max_metadata_value_chars() -> int:
+    return _int(MAX_METADATA_VALUE_CHARS, minimum=1)
+
+
+def sse_heartbeat_s() -> float:
+    return _float(SSE_HEARTBEAT_S, minimum=0)
+
+
+def retention_days() -> int:
+    """Days of inactivity after which a thread is purged; 0 keeps everything."""
+    return _int(RETENTION_DAYS, minimum=0)
+
+
+GETTERS: tuple[Callable[[], Any], ...] = (
+    run_timeout_s,
+    recursion_limit,
+    max_request_bytes,
+    max_metadata_keys,
+    max_metadata_value_chars,
+    sse_heartbeat_s,
+    retention_days,
+)
+
+
+def check_settings(extra: tuple[Callable[[], Any], ...] = ()) -> None:
+    """Parse every limit once; raise one `SettingsError` naming every bad variable."""
+    problems: list[str] = []
+    for getter in (*GETTERS, *extra):
+        try:
+            getter()
+        except SettingsError as exc:
+            problems.append(str(exc))
+    if problems:
+        raise SettingsError("Invalid settings: " + " ".join(problems))
+
+
+def valid_thread_id(thread_id: str) -> bool:
+    return isinstance(thread_id, str) and bool(_THREAD_ID.fullmatch(thread_id))
+
+
+def check_metadata(metadata: Mapping[str, Any]) -> dict[str, Any]:
+    """Validate `/chat` client metadata against the caps; return it as a plain dict.
+
+    Metadata is a flat object of scalars (string, number, boolean or null),
+    at most `MAX_METADATA_KEYS` keys, keys and string values at most
+    `MAX_METADATA_VALUE_CHARS` characters. Anything else raises `ValueError`
+    (a 422 for the caller) instead of being dropped silently.
+    """
+    max_keys = max_metadata_keys()
+    max_chars = max_metadata_value_chars()
+    if len(metadata) > max_keys:
+        raise ValueError(f"metadata has {len(metadata)} keys; at most {max_keys} are allowed.")
+    out: dict[str, Any] = {}
+    for key, value in metadata.items():
+        if not isinstance(key, str) or not key:
+            raise ValueError("metadata keys must be non-empty strings.")
+        if len(key) > max_chars:
+            raise ValueError(f"metadata key is longer than {max_chars} characters.")
+        if value is not None and not isinstance(value, str | int | float | bool):
+            raise ValueError(
+                f"metadata[{key[:40]!r}] must be a string, number, boolean or null "
+                "(nested objects and lists are not accepted)."
+            )
+        if isinstance(value, float) and not math.isfinite(value):
+            raise ValueError(f"metadata[{key[:40]!r}] must be a finite number.")
+        if isinstance(value, str) and len(value) > max_chars:
+            raise ValueError(f"metadata[{key[:40]!r}] is longer than {max_chars} characters.")
+        out[key] = value
+    return out

graph_agents_cli/scaffold/agents/langgraph/app/app_utils/metrics.py

@@ -0,0 +1,231 @@
+# 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.
+
+"""Prometheus metrics served at `GET /metrics` (`METRICS_ENABLED`, default true).
+
+`METRICS_TOKEN` (optional, a secret): when set, `/metrics` answers only
+requests carrying `Authorization: Bearer <METRICS_TOKEN>` (401 otherwise), as
+defence in depth behind keeping the endpoint off the public ingress. `/health`
+and `/ready` stay open for the probes. Under langgraph-server this is the
+`/metrics` of the server image, which turns the server's own meta routes off
+(`disable_meta`); `langgraph dev` keeps the server's `/metrics` in front of it.
+
+Per process (scrape every replica):
+
+* `http_requests_total{method, route, status}` and
+  `http_request_duration_seconds{method, route}`: every HTTP request, labelled
+  by the route template (`/threads/{thread_id}/messages`), never the raw path;
+  a streamed `/chat` counts until its last event.
+* `agent_runs_total{status}`: finished runs by status (`ok`, `step_limit`,
+  `error`, `timeout`, `cancelled`, `interrupted`). `interrupted` counts the
+  runs this replica stopped because it lost its lease on the thread, plus the
+  runs of dead processes it found and closed (each counted once across the
+  replicas, see `RunStore.reconcile`); `agent_active_runs`: runs in progress;
+  `agent_run_duration_seconds`; `agent_tokens_total{kind}` (input/output).
+* `agent_database_up`: 1 while the database answered at last contact, 0 while
+  it is known to be unreachable (always 1 without a database).
+* `agent_approvals_total{event}`: human approvals of gated API calls:
+  `requested` (a run paused for one), `approved`, `rejected`, `expired` (a
+  pending approval that reached its `timeout_s`, or was superseded). A run
+  that pauses ends with status `awaiting_approval` in `agent_runs_total`.
+* `agent_token_exchanges_total{api, outcome}`: tokens asked for `auth: exchange`
+  APIs (`token_exchange.py`) by outcome: `issued` (the issuer minted one),
+  `cached` (a kept one, or one another call was exchanging), `refused` (the
+  issuer refused, or refused within `TOKEN_EXCHANGE_FAILURE_TTL_S`),
+  `no_actor` (the issued token names no actor and the API does not set
+  `exchange.allow_actorless`: this agent refused it, and remembers that for
+  `TOKEN_EXCHANGE_FAILURE_TTL_S`), `unavailable` (a timeout, connection
+  error, 5xx or unusable answer) and
+  `circuit_open` (failed at once while the issuer's breaker is open);
+  `agent_token_exchange_duration_seconds{api}`: the exchanges sent. `api` is
+  the API's name in api-policy.yaml.
+
+Metrics live in a registry of their own, so nothing else in the process
+(libraries, a reloaded module) can add or duplicate series. Labels never carry
+ids, principals or client input.
+"""
+
+from __future__ import annotations
+
+import hmac
+import os
+from typing import Any
+
+from prometheus_client import (
+    CONTENT_TYPE_LATEST,
+    CollectorRegistry,
+    Counter,
+    Gauge,
+    Histogram,
+    generate_latest,
+)
+
+from {{cookiecutter.agent_directory}}.app_utils.limits import SettingsError
+
+REGISTRY = CollectorRegistry(auto_describe=True)
+
+HTTP_REQUESTS = Counter(
+    "http_requests_total",
+    "HTTP requests by method, route template and status code.",
+    ["method", "route", "status"],
+    registry=REGISTRY,
+)
+HTTP_LATENCY = Histogram(
+    "http_request_duration_seconds",
+    "HTTP request duration (a streamed response counts until its last byte).",
+    ["method", "route"],
+    registry=REGISTRY,
+)
+RUNS = Counter(
+    "agent_runs_total",
+    "Finished agent runs by status (ok, awaiting_approval, step_limit, error, timeout, "
+    "cancelled, interrupted).",
+    ["status"],
+    registry=REGISTRY,
+)
+APPROVAL_EVENTS = ("requested", "approved", "rejected", "expired")
+APPROVALS = Counter(
+    "agent_approvals_total",
+    "Human approvals of gated API calls by event (requested, approved, rejected, expired).",
+    ["event"],
+    registry=REGISTRY,
+)
+for _event in APPROVAL_EVENTS:
+    APPROVALS.labels(_event)  # every series exists from the start, at 0
+TOKEN_EXCHANGE_OUTCOMES = (
+    "issued",
+    "cached",
+    "refused",
+    "no_actor",
+    "unavailable",
+    "circuit_open",
+)
+TOKEN_EXCHANGES = Counter(
+    "agent_token_exchanges_total",
+    "Tokens asked for auth: exchange APIs by API and outcome (issued, cached, refused, "
+    "no_actor, unavailable, circuit_open).",
+    ["api", "outcome"],
+    registry=REGISTRY,
+)
+TOKEN_EXCHANGE_LATENCY = Histogram(
+    "agent_token_exchange_duration_seconds",
+    "Token exchanges sent to the issuer, by API.",
+    ["api"],
+    buckets=(0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2, 5),
+    registry=REGISTRY,
+)
+ACTIVE_RUNS = Gauge("agent_active_runs", "Agent runs in progress.", registry=REGISTRY)
+DATABASE_UP = Gauge(
+    "agent_database_up",
+    "1 while the database answered at last contact, 0 while it is known to be unreachable.",
+    registry=REGISTRY,
+)
+DATABASE_UP.set(1)
+RUN_LATENCY = Histogram(
+    "agent_run_duration_seconds",
+    "Agent run duration.",
+    buckets=(0.25, 0.5, 1, 2, 5, 10, 20, 30, 60, 120, 300, 600),
+    registry=REGISTRY,
+)
+TOKENS = Counter(
+    "agent_tokens_total",
+    "Model tokens used by agent runs.",
+    ["kind"],
+    registry=REGISTRY,
+)
+
+_TRUE = ("1", "true", "yes", "on")
+_FALSE = ("0", "false", "no", "off")
+_METHODS = frozenset({"GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"})
+
+
+def metrics_enabled() -> bool:
+    raw = (os.environ.get("METRICS_ENABLED") or "true").strip().lower()
+    if raw in _TRUE:
+        return True
+    if raw in _FALSE:
+        return False
+    raise SettingsError(f"METRICS_ENABLED={raw!r} must be true or false.")
+
+
+def metrics_token() -> str | None:
+    """`METRICS_TOKEN`, or None when unset or blank (then `/metrics` needs no token)."""
+    token = (os.environ.get("METRICS_TOKEN") or "").strip()
+    return token or None
+
+
+def metrics_authorized(authorization: str | None) -> bool:
+    """True when no token is configured or `authorization` is `Bearer <METRICS_TOKEN>`."""
+    token = metrics_token()
+    if token is None:
+        return True
+    scheme, _, presented = (authorization or "").partition(" ")
+    presented = presented.strip()
+    return (
+        scheme.lower() == "bearer"
+        and bool(presented)
+        and hmac.compare_digest(presented.encode("utf-8"), token.encode("utf-8"))
+    )
+
+
+def render() -> tuple[bytes, str]:
+    """The exposition text and its content type."""
+    return generate_latest(REGISTRY), CONTENT_TYPE_LATEST
+
+
+def route_label(scope: dict[str, Any]) -> str:
+    """The matched route's template, or `unmatched` (a 404 must not mint a series per path)."""
+    route = scope.get("route")
+    path = getattr(route, "path_format", None) or getattr(route, "path", None)
+    return str(path) if path else "unmatched"
+
+
+def observe_request(method: str, route: str, status: int, seconds: float) -> None:
+    method = method if method in _METHODS else "OTHER"
+    HTTP_REQUESTS.labels(method, route, str(status)).inc()
+    HTTP_LATENCY.labels(method, route).observe(seconds)
+
+
+def observe_run(status: str, seconds: float, input_tokens: int, output_tokens: int) -> None:
+    RUNS.labels(status).inc()
+    RUN_LATENCY.observe(seconds)
+    if input_tokens:
+        TOKENS.labels("input").inc(input_tokens)
+    if output_tokens:
+        TOKENS.labels("output").inc(output_tokens)
+
+
+def observe_interrupted_runs(count: int) -> None:
+    """Runs of a dead process, found `running` and closed as `interrupted`."""
+    if count:
+        RUNS.labels("interrupted").inc(count)
+
+
+def observe_database(up: bool) -> None:
+    DATABASE_UP.set(1 if up else 0)
+
+
+def observe_approvals(event: str, count: int = 1) -> None:
+    """`count` approvals `requested`, `approved`, `rejected` or `expired`."""
+    if count and event in APPROVAL_EVENTS:
+        APPROVALS.labels(event).inc(count)
+
+
+def observe_token_exchange(api: str, outcome: str, seconds: float | None = None) -> None:
+    """A token asked for the `auth: exchange` API `api`; `seconds` when one was sent."""
+    if outcome not in TOKEN_EXCHANGE_OUTCOMES:
+        return
+    TOKEN_EXCHANGES.labels(api, outcome).inc()
+    if seconds is not None:
+        TOKEN_EXCHANGE_LATENCY.labels(api).observe(seconds)