axonflow-google-adk-plugin 1.0.0__tar.gz

axonflow_google_adk_plugin-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 getaxonflow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

axonflow_google_adk_plugin-1.0.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: axonflow-google-adk-plugin
+Version: 1.0.0
+Summary: AxonFlow governance plugin for Google Agent Development Kit (ADK)
+Author-email: AxonFlow <hello@getaxonflow.com>
+License: MIT
+Project-URL: Homepage, https://getaxonflow.com
+Project-URL: Documentation, https://docs.getaxonflow.com/docs/integration/google-adk
+Project-URL: Repository, https://github.com/getaxonflow/axonflow-google-adk-plugin
+Project-URL: Changelog, https://github.com/getaxonflow/axonflow-google-adk-plugin/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/getaxonflow/axonflow-google-adk-plugin/issues
+Keywords: axonflow,google-adk,adk,ai-governance,llm,policy,compliance
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: google-adk>=2.0.0
+Requires-Dist: axonflow>=8.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# axonflow-google-adk-plugin
+
+AxonFlow governance plugin for [Google Agent Development Kit (ADK)](https://adk.dev/).
+
+Register `AxonFlowPlugin` once on a `Runner` and **every model call and every
+tool call across every agent on that Runner** is governed by AxonFlow
+policies: pre-check, HITL approval, deny short-circuit, audit trail, PII
+redaction on tool I/O.
+
+## Install
+
+```bash
+pip install axonflow-google-adk-plugin
+```
+
+Requires `google-adk>=2.0` and `axonflow>=8.2.0` (AxonFlow Python SDK).
+
+## Quickstart (5 lines)
+
+```python
+from google.adk.runners import InMemoryRunner
+from google.adk.agents import LlmAgent
+from axonflow_adk import AxonFlowPlugin
+
+agent = LlmAgent(model="gemini-2.0-flash", name="loan_desk", instruction="...")
+runner = InMemoryRunner(
+    agent=agent,
+    app_name="loan_desk",
+    plugins=[AxonFlowPlugin(
+        endpoint="http://localhost:8080",
+        client_id="loan-desk",
+        client_secret="secret-from-axonflow",
+    )],
+)
+```
+
+## Hook → AxonFlow endpoint mapping
+
+| ADK hook                     | AxonFlow call             | Deny shape                                     |
+|------------------------------|---------------------------|------------------------------------------------|
+| `before_model_callback`      | `pre_check`               | `LlmResponse` with policy-denial text          |
+| `after_model_callback`       | `audit_llm_call`          | never blocks (audit only)                      |
+| `before_tool_callback`       | `check_tool_input`        | `{"error": "[AxonFlow] <reason>"}`             |
+| `after_tool_callback`        | `check_tool_output`       | redacted dict OR `{"error": ...}` on hard deny |
+| `on_tool_error_callback`     | `audit_tool_call`         | never blocks (audit only)                      |
+| `on_user_message_callback`   | no-op (v1)                | n/a                                            |
+
+The `on_user_message_callback` hook is intentionally a no-op in v1 — returning
+non-None Content there would silently **replace** the user's message, which is
+the wrong tool for governance.
+
+## HITL approval flow — 4-step
+
+When AxonFlow policy evaluates to `require_approval`, the plugin runs the
+full **4-step HITL flow** by default (`enable_hitl_polling=True`):
+
+```
+before_model_callback / before_tool_callback
+    │
+    ├─ STEP 1 — gate (pre_check / check_tool_input)
+    │           returns blocked, BlockReason == "require_approval"
+    │
+    ├─ STEP 2 — POST /api/v1/hitl/queue
+    │           plugin calls client.create_hitl_request(request=HITLCreateInput(...))
+    │           returns approval_id (uuid)
+    │
+    ├─ STEP 3 — GET /api/v1/hitl/queue/{approval_id}
+    │           polled every approval_poll_interval_seconds (default 2s);
+    │           local consecutive-failure counter (NOT the shared
+    │           breaker) so a polling outage can't disable governance
+    │           for other in-flight calls
+    │
+    └─ STEP 4 — terminal state:
+        ├─ "approved"            → return None (let LLM / tool proceed)
+        ├─ "rejected" | "expired" → return deny short-circuit
+        ├─ N consecutive poll failures → deny
+        └─ time > approval_max_wait_seconds → deny
+```
+
+The plugin's `before_model_callback` and `before_tool_callback` both run
+this flow. Detection is an exact-string match against the platform's
+`require_approval` sentinel. Substring matching previously false-positived
+on any policy whose reason text contained the word "approval".
+
+The 4-step flow is the only **fail-closed** path in the plugin —
+everything else fails open. Approvals are safety-critical; defaulting to
+"allow" on an AxonFlow outage during an approval gate would defeat the
+gate.
+
+### Approving / rejecting out-of-band
+
+When step 2 returns an `approval_id`, the plugin emits a single INFO log:
+
+```
+axonflow hitl AWAITING APPROVAL: request_id=<uuid>; approve via
+POST /api/v1/hitl/queue/<uuid>/{approve|reject}
+```
+
+The reviewer (UI, Slack bot, internal portal) posts the decision via:
+
+```bash
+# Approve
+curl -X POST $AXONFLOW_ENDPOINT/api/v1/hitl/queue/<approval_id>/approve \
+     -H 'Content-Type: application/json' \
+     -d '{"reviewer_id":"compliance","reviewer_email":"compliance@bank.example"}'
+
+# Reject (same shape)
+curl -X POST $AXONFLOW_ENDPOINT/api/v1/hitl/queue/<approval_id>/reject \
+     -H 'Content-Type: application/json' \
+     -d '{"reviewer_id":"compliance","reviewer_email":"compliance@bank.example"}'
+```
+
+### Opting out — deny-fast mode
+
+Set `enable_hitl_polling=False` on the config to short-circuit
+`require_approval` immediately without enqueuing a row. The host app
+then drives its own approval workflow.
+
+## Authenticating in enterprise mode
+
+ADK does not carry a first-class `user_token` concept. To propagate the
+end-user identity AxonFlow's enterprise-mode policy enforcement requires,
+set `state["axonflow_user_token"]` to a valid JWT on the session BEFORE
+calling `runner.run_async(...)`:
+
+```python
+session = runner.session_service.create_session(
+    app_name="loan_desk", user_id="cust-001", session_id="sess-A",
+)
+session.state["axonflow_user_token"] = generate_axonflow_jwt(user_id="cust-001")
+```
+
+For **community mode** (no tenant signing key), leave the state key
+unset; the plugin will use `config.default_user_token` (default
+`"anonymous"`).
+
+## Failure semantics
+
+A buggy or unreachable AxonFlow **must not** break the agent. The plugin
+ships with:
+
+- **Per-hook timeout** (default 5s, configurable via `call_timeout_seconds`)
+- **Half-open circuit breaker** (default open after 5 consecutive failures,
+  recover after 30s). HALF_OPEN admits exactly one probe; concurrent
+  hooks during recovery are skipped without leaking a thundering herd.
+- **Fail-open default** — every hook except `_await_hitl_decision`
+  returns `None` on error/timeout/open-circuit, letting the model or
+  tool call proceed.
+
+## MCP toolset helper
+
+```python
+from google.adk.agents import LlmAgent
+from axonflow_adk import axonflow_mcp_toolset
+
+agent = LlmAgent(
+    model="gemini-2.0-flash",
+    name="postgres_governed",
+    instruction="Answer questions about the production DB.",
+    tools=[axonflow_mcp_toolset(
+        endpoint="http://localhost:8080",
+        client_id="my-app",
+        client_secret="secret",
+    )],
+)
+```
+
+## Run the example
+
+```bash
+pip install axonflow-google-adk-plugin
+export GOOGLE_API_KEY=...
+export AXONFLOW_ENDPOINT=http://localhost:8080
+export AXONFLOW_CLIENT_ID=loan-desk
+export AXONFLOW_CLIENT_SECRET=...
+
+python -m examples.loan_disbursement_agent
+# or: python examples/loan_disbursement_agent.py
+```
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+## Documentation
+
+Full integration guide: [docs.getaxonflow.com/docs/integration/google-adk](https://docs.getaxonflow.com/docs/integration/google-adk/)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

axonflow_google_adk_plugin-1.0.0/README.md

@@ -0,0 +1,194 @@
+# axonflow-google-adk-plugin
+
+AxonFlow governance plugin for [Google Agent Development Kit (ADK)](https://adk.dev/).
+
+Register `AxonFlowPlugin` once on a `Runner` and **every model call and every
+tool call across every agent on that Runner** is governed by AxonFlow
+policies: pre-check, HITL approval, deny short-circuit, audit trail, PII
+redaction on tool I/O.
+
+## Install
+
+```bash
+pip install axonflow-google-adk-plugin
+```
+
+Requires `google-adk>=2.0` and `axonflow>=8.2.0` (AxonFlow Python SDK).
+
+## Quickstart (5 lines)
+
+```python
+from google.adk.runners import InMemoryRunner
+from google.adk.agents import LlmAgent
+from axonflow_adk import AxonFlowPlugin
+
+agent = LlmAgent(model="gemini-2.0-flash", name="loan_desk", instruction="...")
+runner = InMemoryRunner(
+    agent=agent,
+    app_name="loan_desk",
+    plugins=[AxonFlowPlugin(
+        endpoint="http://localhost:8080",
+        client_id="loan-desk",
+        client_secret="secret-from-axonflow",
+    )],
+)
+```
+
+## Hook → AxonFlow endpoint mapping
+
+| ADK hook                     | AxonFlow call             | Deny shape                                     |
+|------------------------------|---------------------------|------------------------------------------------|
+| `before_model_callback`      | `pre_check`               | `LlmResponse` with policy-denial text          |
+| `after_model_callback`       | `audit_llm_call`          | never blocks (audit only)                      |
+| `before_tool_callback`       | `check_tool_input`        | `{"error": "[AxonFlow] <reason>"}`             |
+| `after_tool_callback`        | `check_tool_output`       | redacted dict OR `{"error": ...}` on hard deny |
+| `on_tool_error_callback`     | `audit_tool_call`         | never blocks (audit only)                      |
+| `on_user_message_callback`   | no-op (v1)                | n/a                                            |
+
+The `on_user_message_callback` hook is intentionally a no-op in v1 — returning
+non-None Content there would silently **replace** the user's message, which is
+the wrong tool for governance.
+
+## HITL approval flow — 4-step
+
+When AxonFlow policy evaluates to `require_approval`, the plugin runs the
+full **4-step HITL flow** by default (`enable_hitl_polling=True`):
+
+```
+before_model_callback / before_tool_callback
+    │
+    ├─ STEP 1 — gate (pre_check / check_tool_input)
+    │           returns blocked, BlockReason == "require_approval"
+    │
+    ├─ STEP 2 — POST /api/v1/hitl/queue
+    │           plugin calls client.create_hitl_request(request=HITLCreateInput(...))
+    │           returns approval_id (uuid)
+    │
+    ├─ STEP 3 — GET /api/v1/hitl/queue/{approval_id}
+    │           polled every approval_poll_interval_seconds (default 2s);
+    │           local consecutive-failure counter (NOT the shared
+    │           breaker) so a polling outage can't disable governance
+    │           for other in-flight calls
+    │
+    └─ STEP 4 — terminal state:
+        ├─ "approved"            → return None (let LLM / tool proceed)
+        ├─ "rejected" | "expired" → return deny short-circuit
+        ├─ N consecutive poll failures → deny
+        └─ time > approval_max_wait_seconds → deny
+```
+
+The plugin's `before_model_callback` and `before_tool_callback` both run
+this flow. Detection is an exact-string match against the platform's
+`require_approval` sentinel. Substring matching previously false-positived
+on any policy whose reason text contained the word "approval".
+
+The 4-step flow is the only **fail-closed** path in the plugin —
+everything else fails open. Approvals are safety-critical; defaulting to
+"allow" on an AxonFlow outage during an approval gate would defeat the
+gate.
+
+### Approving / rejecting out-of-band
+
+When step 2 returns an `approval_id`, the plugin emits a single INFO log:
+
+```
+axonflow hitl AWAITING APPROVAL: request_id=<uuid>; approve via
+POST /api/v1/hitl/queue/<uuid>/{approve|reject}
+```
+
+The reviewer (UI, Slack bot, internal portal) posts the decision via:
+
+```bash
+# Approve
+curl -X POST $AXONFLOW_ENDPOINT/api/v1/hitl/queue/<approval_id>/approve \
+     -H 'Content-Type: application/json' \
+     -d '{"reviewer_id":"compliance","reviewer_email":"compliance@bank.example"}'
+
+# Reject (same shape)
+curl -X POST $AXONFLOW_ENDPOINT/api/v1/hitl/queue/<approval_id>/reject \
+     -H 'Content-Type: application/json' \
+     -d '{"reviewer_id":"compliance","reviewer_email":"compliance@bank.example"}'
+```
+
+### Opting out — deny-fast mode
+
+Set `enable_hitl_polling=False` on the config to short-circuit
+`require_approval` immediately without enqueuing a row. The host app
+then drives its own approval workflow.
+
+## Authenticating in enterprise mode
+
+ADK does not carry a first-class `user_token` concept. To propagate the
+end-user identity AxonFlow's enterprise-mode policy enforcement requires,
+set `state["axonflow_user_token"]` to a valid JWT on the session BEFORE
+calling `runner.run_async(...)`:
+
+```python
+session = runner.session_service.create_session(
+    app_name="loan_desk", user_id="cust-001", session_id="sess-A",
+)
+session.state["axonflow_user_token"] = generate_axonflow_jwt(user_id="cust-001")
+```
+
+For **community mode** (no tenant signing key), leave the state key
+unset; the plugin will use `config.default_user_token` (default
+`"anonymous"`).
+
+## Failure semantics
+
+A buggy or unreachable AxonFlow **must not** break the agent. The plugin
+ships with:
+
+- **Per-hook timeout** (default 5s, configurable via `call_timeout_seconds`)
+- **Half-open circuit breaker** (default open after 5 consecutive failures,
+  recover after 30s). HALF_OPEN admits exactly one probe; concurrent
+  hooks during recovery are skipped without leaking a thundering herd.
+- **Fail-open default** — every hook except `_await_hitl_decision`
+  returns `None` on error/timeout/open-circuit, letting the model or
+  tool call proceed.
+
+## MCP toolset helper
+
+```python
+from google.adk.agents import LlmAgent
+from axonflow_adk import axonflow_mcp_toolset
+
+agent = LlmAgent(
+    model="gemini-2.0-flash",
+    name="postgres_governed",
+    instruction="Answer questions about the production DB.",
+    tools=[axonflow_mcp_toolset(
+        endpoint="http://localhost:8080",
+        client_id="my-app",
+        client_secret="secret",
+    )],
+)
+```
+
+## Run the example
+
+```bash
+pip install axonflow-google-adk-plugin
+export GOOGLE_API_KEY=...
+export AXONFLOW_ENDPOINT=http://localhost:8080
+export AXONFLOW_CLIENT_ID=loan-desk
+export AXONFLOW_CLIENT_SECRET=...
+
+python -m examples.loan_disbursement_agent
+# or: python examples/loan_disbursement_agent.py
+```
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+## Documentation
+
+Full integration guide: [docs.getaxonflow.com/docs/integration/google-adk](https://docs.getaxonflow.com/docs/integration/google-adk/)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

axonflow_google_adk_plugin-1.0.0/axonflow_adk/__init__.py

@@ -0,0 +1,34 @@
+# Copyright 2026 AxonFlow
+# SPDX-License-Identifier: MIT
+
+"""AxonFlow governance plugin for Google Agent Development Kit (ADK).
+
+Register `AxonFlowPlugin` on a `Runner` and every model + tool call across
+every agent on that runner is governed by AxonFlow policies, with HITL
+approval, denial short-circuits, and an audit trail.
+
+    from google.adk.runners import InMemoryRunner
+    from axonflow_adk import AxonFlowPlugin
+
+    runner = InMemoryRunner(
+        agent=root_agent,
+        app_name="loan_desk",
+        plugins=[AxonFlowPlugin(
+            endpoint="http://localhost:8080",
+            client_id="loan-desk",
+            client_secret="...",
+        )],
+    )
+"""
+
+from axonflow_adk._version import __version__
+from axonflow_adk.plugin import AxonFlowPlugin, ApprovalTimeout, ApprovalRejected
+from axonflow_adk.mcp_helper import axonflow_mcp_toolset
+
+__all__ = [
+    "__version__",
+    "ApprovalRejected",
+    "ApprovalTimeout",
+    "AxonFlowPlugin",
+    "axonflow_mcp_toolset",
+]

axonflow_google_adk_plugin-1.0.0/axonflow_adk/_version.py

@@ -0,0 +1,4 @@
+# Copyright 2026 AxonFlow
+# SPDX-License-Identifier: MIT
+
+__version__ = "1.0.0"

axonflow_google_adk_plugin-1.0.0/axonflow_adk/mcp_helper.py

@@ -0,0 +1,90 @@
+# Copyright 2026 AxonFlow
+# SPDX-License-Identifier: MIT
+
+"""ADK `MCPToolset` helper for the AxonFlow agent's MCP server.
+
+The AxonFlow agent ships an MCP endpoint at `/mcp/` on the same host as
+its REST API. This module returns an `McpToolset` configured against that
+endpoint over Streamable HTTP, so ADK callers can register AxonFlow's
+governed MCP tools (e.g. PostgreSQL, Snowflake, GCS) with one line:
+
+    from axonflow_adk import axonflow_mcp_toolset
+
+    toolset = axonflow_mcp_toolset(
+        endpoint="http://localhost:8080",
+        client_id="my-app",
+        client_secret="...",
+    )
+
+Reference: https://adk.dev/tools-custom/mcp-tools/
+"""
+
+from __future__ import annotations
+
+import base64
+from typing import Any
+
+
+def axonflow_mcp_toolset(
+    endpoint: str,
+    *,
+    client_id: str | None = None,
+    client_secret: str | None = None,
+    bearer_token: str | None = None,
+    mcp_path: str = "/mcp/",
+    extra_headers: dict[str, str] | None = None,
+) -> Any:
+    """Return an ADK `McpToolset` pointed at AxonFlow's MCP server.
+
+    Authentication shape (R3 HIGH-3 — the platform's MCP server expects
+    one of):
+
+      * `Authorization: Basic <base64(client_id:client_secret)>` when
+        `client_id` AND `client_secret` are provided.
+      * `Authorization: Bearer <token>` when `bearer_token` is provided.
+      * Anonymous (no header) when none are provided — community-mode.
+
+    Custom `X-AxonFlow-*` headers (a prior shape) are NOT recognized by
+    the platform and would result in silently-anonymous calls bypassing
+    per-client / per-tenant policy scoping. Use the canonical
+    Authorization header instead.
+
+    Args:
+        endpoint: AxonFlow agent base URL (e.g. `http://localhost:8080`).
+            Trailing slash is stripped; `mcp_path` is appended.
+        client_id: AxonFlow client identifier (community/enterprise).
+        client_secret: AxonFlow client secret (community/enterprise).
+        bearer_token: Pre-issued bearer token (overrides client_id/secret
+            when set).
+        mcp_path: Path component of the AxonFlow MCP endpoint. Defaults
+            to `/mcp/` which is the agent's canonical path.
+        extra_headers: Optional additional headers (tenant scoping,
+            tracing context) merged into the connection params.
+
+    Returns:
+        `McpToolset` ready to drop into `LlmAgent(tools=[...])`.
+
+    Raises:
+        ImportError: if `google-adk` is not installed.
+    """
+    from google.adk.tools.mcp_tool import McpToolset
+    from google.adk.tools.mcp_tool.mcp_session_manager import (
+        StreamableHTTPConnectionParams,
+    )
+
+    headers: dict[str, str] = {}
+    if bearer_token:
+        headers["Authorization"] = f"Bearer {bearer_token}"
+    elif client_id and client_secret:
+        raw = f"{client_id}:{client_secret}".encode()
+        headers["Authorization"] = "Basic " + base64.b64encode(raw).decode("ascii")
+    if extra_headers:
+        headers.update(extra_headers)
+
+    url = endpoint.rstrip("/") + mcp_path
+    return McpToolset(
+        connection_params=StreamableHTTPConnectionParams(
+            url=url,
+            headers=headers,
+        )
+    )