Metadata-Version: 2.4
Name: aiyoplane-google-adk
Version: 1.0.0
Summary: AEAP Composition Boundary Adapter for Google ADK. Thin wrapper that attaches the Runtime Decision Point to agent tool invocations.
Author-email: "Aiyoplane, Inc." <rashon@aiyoplane.com>
License: Apache-2.0
Project-URL: Homepage, https://aiyoplane.com
Project-URL: Documentation, https://github.com/aiyoplane/google-adk
Project-URL: Repository, https://github.com/aiyoplane/google-adk
Project-URL: Issues, https://github.com/aiyoplane/google-adk/issues
Project-URL: Trust Surface, https://aiyoplane.com/trust
Project-URL: AEAP Specification, https://github.com/aiyoplane/aeap
Keywords: aiyo,aiyoplane,aeap,google,google-adk,gemini,gcp,authorization,runtime-decision-point,rdp,execution-receipt,composition-boundary,agent-authorization,code-execution
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: aiyoplane-mcp-authz>=1.0.1
Requires-Dist: google-adk>=0.1.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21; extra == "test"
Dynamic: license-file

# aiyoplane-google-adk

**AEAP Composition Boundary Adapter for Google ADK.**

A thin wrapper that attaches the AEAP Runtime Decision Point (RDP) to Google ADK's tool invocation surface. Consequential tool executions — including code execution and sandboxed environment operations — produce independently verifiable Execution Receipts.

```bash
pip install aiyoplane-google-adk
```

## Why Google ADK + AEAP

Google ADK already reaches into agent runtime code execution and sandboxed environments. Those are prime AEAP territory: code execution, external API calls, cloud resource mutations, and economic actions are all consequential and benefit from the "before this crosses the boundary, authorize it" property AEAP provides. ADK owns the runtime; AEAP owns the authorization semantics at the consequential-execution boundary. Clean architectural separation.

See the [AEAP specification](https://github.com/aiyoplane/aeap) §9.

## Minimal usage — decorator

```python
from google.adk.agents import Agent
from aiyoplane_mcp_authz import create_aiyo_mcp_authz, create_local_rdp
from aiyoplane_google_adk import aiyo_tool, BlockedByPolicy, EscalationRequired

policy = {
    "rules": [
        {"action_type": "code_execution", "language": "python", "effect": "allow"},
        {"action_type": "code_execution", "effect": "escalate"},
    ]
}

authz = create_aiyo_mcp_authz(
    rdp=create_local_rdp(policy=policy),
    tool_config={
        "run_code": {"aiyo_gated": True, "action": {"type": "code_execution"}},
    },
)

@aiyo_tool(
    authz=authz,
    tool_name="run_code",
    intent_builder=lambda kw: {
        "type": "code_execution",
        "language": kw["language"],
        "code_hash": compute_hash(kw["code"]),
    },
)
def run_code(language: str, code: str) -> str:
    """Execute code in a sandbox."""
    return sandbox_exec(language, code)

agent = Agent(
    name="coder",
    model="gemini-1.5-pro",
    tools=[run_code],
    instruction="Help the user execute code safely.",
)
```

## Minimal usage — function form

```python
from aiyoplane_google_adk import wrap_tool_function

def run_code(language: str, code: str) -> str:
    return sandbox_exec(language, code)

guarded = wrap_tool_function(
    run_code,
    authz=authz,
    tool_name="run_code",
    intent_builder=lambda kw: {"type": "code_execution", "language": kw["language"]},
)
```

## Composition Boundary — what the adapter actually does

1. **Intent construction** via `intent_builder(tool_kwargs)`.
2. **RDP evaluation** via `aiyoplane-mcp-authz`.
3. **Verdict composition.** ALLOW → inner function runs; ESCALATE → `EscalationRequired`; BLOCK → `BlockedByPolicy`.
4. **Fail-closed default** on every ambiguous condition.

## Local vs. hosted RDP

```python
from aiyoplane_mcp_authz import create_local_rdp, create_hosted_rdp

# Development:
authz = create_aiyo_mcp_authz(rdp=create_local_rdp(policy=policy), tool_config={...})

# Production:
authz = create_aiyo_mcp_authz(
    rdp=create_hosted_rdp(api_key="aiyo_live_..."),
    tool_config={...},
)
```

## API reference

### `aiyo_tool(*, authz, tool_name, intent_builder, attach_receipt=False)`
Decorator form.

### `wrap_tool_function(fn, *, authz, tool_name, intent_builder, attach_receipt=False)`
Function form.

### Exceptions

- `AiyoGoogleADKError`, `AdapterConfigError`, `BlockedByPolicy`, `EscalationRequired`

## License

Apache License 2.0.

## Links

- **AEAP specification:** https://github.com/aiyoplane/aeap
- **Underlying implementation:** [`aiyoplane-mcp-authz`](https://pypi.org/project/aiyoplane-mcp-authz/)
- **Trust surface:** https://aiyoplane.com/trust
- **Issues:** https://github.com/aiyoplane/google-adk/issues

Google, Google ADK, Gemini, and Google Cloud are trademarks of Google LLC. This package is an independent AEAP Composition Boundary Adapter and is not affiliated with or endorsed by Google LLC.

**Verify First. Execute Second.**
