google / google/adk-python-community
feat(plugins): optional SeenRelay ambient measurement for repeated read-only tool calls
- 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