google / google/adk-python-community

feat(plugins): optional SeenRelay ambient measurement for repeated read-only tool calls

Ouverte
#183 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub
Langage dominant
Python
Étoiles
182
Forks
75
Métriques de merge des PR
Aucune PR mergée en 30 j

Description

## Problem

ADK applications can execute the same deterministic, read-only tool validation more than once. Whether that repetition is actually worth optimizing is workload-specific, and short-circuiting tool execution before measuring equivalence would be unsafe.

## Proposal

Would an optional `SeenRelayAmbientPlugin` fit `google.adk_community.plugins` as a third-party integration for measuring exact repeated read-only tool validations before any reuse policy is considered?

The proposed initial integration is deliberately local and shadow-only:

- the application supplies an explicit allowlist of tool names it has classified as read-only validation operations;
- the plugin uses ADK `before_tool_callback`, `after_tool_callback`, and `on_tool_error_callback` lifecycle hooks;
- an exact local coordinate is derived from tool name plus JSON-serializable arguments;
- returned JSON is fingerprinted and compared only with prior local fingerprints;
- only bounded fingerprints and aggregate counters are retained in memory;
- raw tool arguments and raw results are not retained in the report/state;
- unsupported/non-JSON values fail open and preserve normal ADK behavior;
- the plugin always returns `None`, so it never replaces a tool result, short-circuits execution, mutates arguments, or handles failures;
- it performs no hosted SeenRelay `CHECK` or `OBSERVE` operation and authorizes no automatic reuse.

The optional Python dependency would be `seenrelay>=0.2.13,<1`; the default client package has no required dependencies and is MIT-licensed.

## Proposed scope

- `src/google/adk_community/plugins/seenrelay_ambient_plugin.py`
- export from `google.adk_community.plugins`
- `seenrelay` optional dependency extra
- focused plugin tests

No active validation suppression, network reuse policy, tool mutation, or result caching is proposed.

## Compatibility evidence

A compatibility candidate was exercised against Google ADK 2.8.0 at exact source commit `6de43b05a07f8ca89909664b3a21049646d7336c` using the real ADK `PluginManager`. The compatibility suite passed cases covering authoritative execution on exact repeats, changed-result handling, distinct arguments, fail-open unsupported input, bounded state, raw-data non-retention, and tool-error behavior.

If this shape fits the community repository, I have a focused implementation and tests ready in my fork and can open the PR after maintainers confirm the placement/API direction.

Guide de contribution

Ouvrir le guide de contribution

Piste de recherche

Commencez par le chemin proposé src/google/adk_community/plugins/seenrelay_ambient_plugin.py, l’export de google.adk_community.plugins et les hooks before_tool_callback, after_tool_callback et on_tool_error_callback d’ADK. Examinez les tests ciblés du plugin et les éléments attestant la compatibilité, puis confirmez le placement et l’orientation de l’API avec les mainteneurs. Le travail est considéré comme terminé lorsqu’il existe une intégration optionnelle, locale et shadow-only, avec un état non-raw borné, qui préserve le comportement normal de l’outil.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
python
Domaine
tooling
Type d'issue
Fonctionnalité
Difficulté
5/5
Temps estimé
Plus d'une semaine
Activité
Active
Clarté
Plutôt claire
Accessibilité débutants
45/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.