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

graph_agents_cli/scaffold/agents/langgraph/app/policies/__init__.py

@@ -0,0 +1,55 @@
+# 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.
+
+"""AuthPolicy registry: `AUTH_POLICY` value -> policy factory.
+
+Agent code, never touched by `graph-agents-cli scaffold upgrade`. Add a policy
+by registering its factory here.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from {{cookiecutter.agent_directory}}.app_utils.auth import (
+    CUSTOM,
+    JWT,
+    SHARED_BEARER,
+    AuthPolicy,
+    JwtPolicy,
+    SharedBearerPolicy,
+)
+
+
+def _custom() -> AuthPolicy:
+    from {{cookiecutter.agent_directory}}.policies.custom import CustomPolicy
+
+    return CustomPolicy()
+
+
+REGISTRY: dict[str, Callable[[], AuthPolicy]] = {
+    SHARED_BEARER: SharedBearerPolicy,
+    JWT: JwtPolicy,
+    CUSTOM: _custom,
+}
+
+
+def build_policy(name: str) -> AuthPolicy:
+    try:
+        factory = REGISTRY[name]
+    except KeyError:
+        raise RuntimeError(
+            f"Unknown AUTH_POLICY {name!r}; expected one of {sorted(REGISTRY)}."
+        ) from None
+    return factory()

graph_agents_cli/scaffold/agents/langgraph/app/policies/custom.py

@@ -0,0 +1,97 @@
+# 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.
+
+"""`custom` policy: the interface the project implements, shipped as a fail-closed stub.
+
+Use it when callers authenticate with something the built-in policies do not
+cover, for example the session cookie of an existing application (for OIDC
+bearer tokens use the built-in `jwt` policy instead). The same policy object
+guards every surface: the chat and thread routes, the A2A card and JSON-RPC
+endpoint, and, under `langgraph-server`, the server's native API.
+
+Implement `CustomPolicy` so that, on every request:
+
+* `authenticate(request)` validates the caller's credential (a cookie, a
+  header, a token) against the system that issued it and returns a
+  `Principal`:
+  - `id`: stable and unique per caller. It owns threads and A2A tasks (two
+    callers with the same id see each other's conversations), and is hashed
+    into traces and run records.
+  - `roles`: matched against `AUTH_READ_ACROSS_ROLES` (may read other
+    principals' threads) and `AUTH_ADMIN_ROLES` (may manage assistants, crons
+    and the store under langgraph-server). Role names must not contain commas.
+  - `permissions`: usually `set(ACTIONS)`; `authorize` decides per action.
+  - `attributes`: optional, for example `tenant`. Secrets go only under
+    `attributes["credentials"][<api name>]` (see below). Keys starting with
+    `@` belong to the framework.
+  - `actor`: None when the caller is the user. When the credential shows that
+    another agent presents it for the user, `Actor(id=<that agent>)` (with
+    `chain`, the agents before it). A policy through which other agents
+    forward users' credentials must set it, or this agent treats the calling
+    agent as the person. `app_utils.auth.actor_from_claims` reads an RFC 8693
+    `act` claim as the `jwt` policy does.
+  Ids (`id`, the actor's) are 1-256 characters without control characters;
+  anything else fails the request with 500 (a bug in the policy).
+  `finalize_principal` then applies `AUTH_ALLOWED_ACTORS`,
+  `AUTH_DELEGATED_ROLES` and `AUTH_MAX_DELEGATION_DEPTH` to every policy.
+  A missing or invalid credential raises `HTTPException(401)` with a
+  `WWW-Authenticate` header; a server-side problem (the issuer cannot be
+  reached) raises `HTTPException(503)`. Never put the credential itself in an
+  error detail or a log line.
+* `authorize(principal, action, resource)` allows or refuses `action` (see
+  `app_utils.auth.ACTIONS`) on `resource` (a thread id or None) with
+  `HTTPException(403)`. Thread ownership is enforced separately, by
+  `app_utils.threads` (fastapi) and the owner filters in `app_utils.auth`
+  (langgraph-server).
+* Optionally `startup_problems() -> list[str]`: configuration problems found
+  when the app starts. Any problem stops the process outside `APP_ENV=dev`
+  (see `app_utils.auth.check_startup`).
+
+Both methods are awaited on the request path: do blocking I/O through an
+async client, and cache what you can (sessions, keys) with a short TTL.
+
+To let tools call an `auth: forward` API of `api-policy.yaml` with the caller's
+own credential, put it in `attributes["credentials"][<api name>]`; that is the
+only attribute that may hold a secret (`Principal.public_attributes()` is what
+gets persisted, logged or traced).
+
+Until it is implemented every request fails with 503, and
+`graph-agents-cli deploy --env staging|prod` refuses while the manifest says
+`auth_policy_implemented: false`. Flip that flag after replacing this stub,
+and add tests beside `tests/unit/test_policy.py` (a valid credential, a
+missing one, an invalid one, and two principals that must not see each
+other's threads).
+"""
+
+from __future__ import annotations
+
+from fastapi import HTTPException, Request
+
+from {{cookiecutter.agent_directory}}.app_utils.auth import Principal
+
+NOT_IMPLEMENTED = (
+    "AUTH_POLICY=custom is scaffolded as a fail-closed stub. Implement CustomPolicy in "
+    "{{cookiecutter.agent_directory}}/policies/custom.py (authenticate the caller, load roles "
+    "and permissions) and set auth_policy_implemented: true in graph-agents-cli-manifest.yaml."
+)
+
+
+class CustomPolicy:
+    """The project's own authentication and authorization. Stub: fails closed."""
+
+    async def authenticate(self, request: Request) -> Principal:
+        raise HTTPException(status_code=503, detail=NOT_IMPLEMENTED)
+
+    async def authorize(self, principal: Principal, action: str, resource: str | None) -> None:
+        raise HTTPException(status_code=503, detail=NOT_IMPLEMENTED)

graph_agents_cli/scaffold/agents/langgraph/app/tools/__init__.py

@@ -0,0 +1,46 @@
+# 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.
+
+"""Tool registry.
+
+Convention: every module in this package declares ``API_CALLS``, a
+module-level list of ``{"api", "method", "operation_id", "path"}`` dicts naming
+every external API call it makes (``[]`` when it makes none), and ``TOOLS``,
+the list of tool objects it contributes. External calls go through
+``app_utils.api_client.get_client`` only, which enforces `api-policy.yaml` at
+runtime; `graph-agents-cli lint` checks the declarations against the same file.
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+import pkgutil
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def get_tools() -> list[Any]:
+    """Every tool contributed by the modules of this package, in module-name order."""
+    tools: list[Any] = []
+    for info in sorted(pkgutil.iter_modules(__path__), key=lambda i: i.name):
+        module = importlib.import_module(f"{__name__}.{info.name}")
+        if not hasattr(module, "API_CALLS"):
+            logger.warning(
+                "%s declares no API_CALLS (use [] when it calls no external API).",
+                module.__name__,
+            )
+        tools.extend(getattr(module, "TOOLS", []))
+    return tools

graph_agents_cli/scaffold/agents/langgraph/app/tools/example_api.py

@@ -0,0 +1,92 @@
+{% if cookiecutter.example_api -%}
+# 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.
+
+"""Example API tool: one explicit call through the policy-enforcing client.
+
+Generated from `api-policy.yaml`: the call is the first operation its first API
+allows, whatever its method (an `allowed_operations` entry, else an operation
+of its OpenAPI spec), so it passes `graph-agents-cli lint` and the policy test
+as generated. It is one concrete, declared call rather than a generic
+"any method, any path" tool, because lint can only check calls a tool declares.
+It shows the pattern every tool that calls an external API follows: declare
+each call in `API_CALLS` (checked by `graph-agents-cli lint`), send it through
+`app_utils.api_client.get_client` (which refuses anything outside
+`api-policy.yaml` before sending), and pass the run context so an
+`auth: forward` API receives the caller's own credential. Replace the call with
+the one your agent needs, or delete this module.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from langchain.tools import ToolRuntime
+from langchain_core.tools import tool
+
+from {{cookiecutter.agent_directory}}.app_utils.api_client import get_client
+
+API_CALLS: list[dict[str, str]] = [
+    {
+        "api": "{{ cookiecutter.example_api.api }}",
+        "method": "{{ cookiecutter.example_api.method }}",
+{%- if cookiecutter.example_api.operation_id %}
+        "operation_id": "{{ cookiecutter.example_api.operation_id }}",
+{%- endif %}
+        "path": "{{ cookiecutter.example_api.path }}",
+    },
+]
+
+
+@tool
+async def call_{{ cookiecutter.example_api.api }}_api(
+{%- for name in cookiecutter.example_api.params %}
+    {{ name }}: str,
+{%- endfor %}
+{%- if cookiecutter.example_api.has_body %}
+    body: dict[str, Any],
+{%- endif %}
+    runtime: ToolRuntime[Any],
+) -> str:
+    """{{ cookiecutter.example_api.method }} {{ cookiecutter.example_api.path }} on the {{ cookiecutter.example_api.api }} API{% if cookiecutter.example_api.has_body %} with `body` as the JSON request body{% endif %}; return the response as JSON."""
+    context: Any = getattr(runtime, "context", None)
+    client = get_client("{{ cookiecutter.example_api.api }}", context=context)
+    # The path stays the declared template; the client encodes each path
+    # parameter as one segment and refuses `.`/`..`, so model input cannot reach
+    # another endpoint. A refusal (ApiPolicyError, also when the API's limits are
+    # reached) or a failed call (ApiCallError) propagates: agent.py turns it
+    # into a tool error the model can read.
+    data = await client.request(
+        "{{ cookiecutter.example_api.method }}",
+        "{{ cookiecutter.example_api.path }}",
+{%- if cookiecutter.example_api.operation_id %}
+        operation_id="{{ cookiecutter.example_api.operation_id }}",
+{%- endif %}
+{%- if cookiecutter.example_api.params %}
+        path_params={
+{%- for name in cookiecutter.example_api.params %}
+            "{{ name }}": {{ name }},
+{%- endfor %}
+        },
+{%- endif %}
+{%- if cookiecutter.example_api.has_body %}
+        json_body=body,
+{%- endif %}
+    )
+    return data if isinstance(data, str) else json.dumps(data)
+
+
+TOOLS = [call_{{ cookiecutter.example_api.api }}_api]
+{% endif -%}

graph_agents_cli/scaffold/agents/langgraph/app/tools/weather.py

@@ -0,0 +1,33 @@
+# 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.
+
+"""Example tool: a simulated weather lookup. Calls no external API."""
+
+from __future__ import annotations
+
+from langchain_core.tools import tool
+
+API_CALLS: list[dict[str, str]] = []
+
+
+@tool
+def get_weather(query: str) -> str:
+    """Get the current weather for a place. Use it whenever the user asks about the weather."""
+    if "sf" in query.lower() or "san francisco" in query.lower():
+        return "It's 60 degrees and foggy."
+    return "It's 90 degrees and sunny."
+
+
+TOOLS = [get_weather]

graph_agents_cli/scaffold/agents/langgraph/langgraph.json

@@ -0,0 +1,14 @@
+{
+  "dependencies": ["."],
+  "graphs": {
+    "agent": "./{{cookiecutter.agent_directory}}/agent.py:graph"
+  },
+  "env": ".env",
+  "http": {
+    "app": "./{{cookiecutter.agent_directory}}/fast_api_app.py:app"
+  },
+  "auth": {
+    "path": "./{{cookiecutter.agent_directory}}/app_utils/auth.py:auth"
+  },
+  "python_version": "3.12"
+}

graph_agents_cli/scaffold/agents/langgraph/pyproject.toml

@@ -0,0 +1,78 @@
+[project]
+name = "{{cookiecutter.project_name}}"
+version = "0.1.0"
+description = "LangGraph agent scaffolded by graph-agents-cli"
+requires-python = ">=3.12,<3.14"
+dependencies = [
+    # Agent framework
+    "langchain>=1.0,<2",
+    "langgraph>=1.0,<2",
+    "langchain-core>=1.0,<2",
+    # Model providers. All four are installed so MODEL_PROVIDER is a runtime
+    # setting (openai-compatible endpoints use langchain-openai).
+    "langchain-openai>=1.0,<2",
+    "langchain-anthropic>=1.0,<2",
+    "langchain-google-genai>=3.0,<5",
+    # Server
+    "fastapi>=0.115,<1",
+    "uvicorn>=0.30,<1",
+    "httpx>=0.27,<1",
+    "python-dotenv>=1.0,<2",
+    "pydantic>=2.7,<3",
+    "pyyaml>=6.0,<7",
+    # Auth (AUTH_POLICY=jwt verifies OIDC tokens) and Prometheus metrics
+    "pyjwt[crypto]>=2.8,<3",
+    "prometheus-client>=0.20,<1",
+    # Persistence (fastapi runtime binds the checkpointer itself)
+    "langgraph-checkpoint-postgres>=2.0,<4",
+    "psycopg[binary]>=3.1,<4",
+    "psycopg-pool>=3.2,<4",
+    # A2A protocol
+    "a2a-sdk[http-server]>=1.0,<2",
+    # Observability (opt-in at runtime, see .env.example)
+    "opentelemetry-sdk>=1.25,<2",
+    "opentelemetry-exporter-otlp-proto-http>=1.25,<2",
+    "openinference-instrumentation-langchain>=0.1.40,<1",
+    "langsmith>=0.3,<1",
+{% if cookiecutter.runtime == 'langgraph-server' %}
+    # LangGraph Server runtime: the server package, its SDK (loopback client
+    # used by /chat) and the local dev server used by `run` and `playground`.
+    "langgraph-api>=0.2,<1",
+    "langgraph-sdk>=0.1,<1",
+    "langgraph-cli[inmem]>=0.2,<1",
+{% endif %}
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3,<10",
+    "pytest-asyncio>=0.24,<2",
+    "httpx>=0.27,<1",
+    "ruff>=0.6,<1",
+    "langgraph-cli[inmem]>=0.2,<1",
+]
+
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["{{cookiecutter.agent_directory}}"]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+filterwarnings = ["ignore::DeprecationWarning"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+extend-exclude = [".venv", "tests/load_test/.results"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "RUF"]
+ignore = ["E501", "B008"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["{{cookiecutter.agent_directory}}"]