Metadata-Version: 2.4
Name: ppx-google-adk
Version: 0.1.0a2
Summary: Google ADK (Agent Development Kit) integration for the Preference Profile Exchange (PPX).
Project-URL: Homepage, https://ppx.dev/
Author: Blazing Customs
License: Apache-2.0
License-File: LICENSE
Keywords: adk,agents,google-adk,ppx,preferences
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: ppx-client>=0.1.0a2
Provides-Extra: adk
Requires-Dist: google-adk>=0.1.0; extra == 'adk'
Description-Content-Type: text/markdown

# ppx-google-adk

> [Google Agent Development Kit (ADK)](https://google.github.io/adk-docs/)
> integration for the [Preference Profile Exchange (PPX)](https://blazing-customs.github.io/ppx-spec/).

## Install

```bash
pip install ppx-google-adk
```

Requires Python 3.11+. Published version: **0.1.0a1** ([PyPI](https://pypi.org/project/ppx-google-adk/)).

> Alpha, tracking a **draft** specification. Expect breaking changes.
> The version is `0.1.0a1` on PyPI and `0.1.0-alpha.1` on npm — the
> same release in each ecosystem's required format.

## Use PPX from an ADK agent

Two complementary patterns.

### Pattern 1 — Inject preferences as context at session start

```python
from ppx_client import PpxClient
from ppx_google_adk import fetch_preference_context
from google.adk.agents import LlmAgent

client = PpxClient("https://api.provider.app")
preferences = fetch_preference_context(
    client,
    grant_token=my_grant_token,
    context={"climate": "hot_humid"},
    requested_namespaces=["core", "fragrance"],
)

agent = LlmAgent(
    name="scent_advisor",
    model="gemini-2.0-flash",
    instruction=(
        "You recommend fragrances. Use the user's preferences below when suggesting.\n\n"
        + preferences
    ),
)
```

The agent sees a deterministic, grant-scoped block of claims — no tool
call needed — and the model can cite specific preferences in its output.

### Pattern 2 — Let the agent call PPX on demand

```python
from google.adk.agents import LlmAgent
from google.adk.tools import FunctionTool
from ppx_google_adk import build_preference_tool

lookup = build_preference_tool(client, grant_token=my_grant_token)

agent = LlmAgent(
    name="scent_advisor",
    model="gemini-2.0-flash",
    instruction="When relevant, call lookup_user_preference to check the user's preferences.",
    tools=[FunctionTool(lookup)],
)
```

Every tool invocation is grant-scoped. The agent can never see claims the
user hasn't authorized; out-of-scope keys are silently redacted by the
provider.

## Combining both patterns

For long-running agents, inject a small baseline preference context
(pattern 1) and register the tool (pattern 2) so the agent can refine
its understanding with targeted queries without re-reading the full
profile on every turn.

## License

Apache-2.0.
