google / google/adk-python-community

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

Aperta
#183 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
Lingua principale
Python
Stelle
182
Fork
75
Metriche di merge delle PR
Nessuna PR unita negli ultimi 30g

Descrizione

## 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.

Guida per i contributori

Apri la guida per i contributori

Direzione di ricerca

Start with the proposed src/google/adk_community/plugins/seenrelay_ambient_plugin.py path, the google.adk_community.plugins export, and ADK's before_tool_callback, after_tool_callback, and on_tool_error_callback hooks. Review the focused plugin tests and compatibility evidence, then confirm the placement and API direction with maintainers. Done means an optional, local shadow-only integration with bounded non-raw state that preserves normal tool behavior.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
python
Ambito
tooling
Tipo di issue
Funzionalità
Difficoltà
5/5
Tempo stimato
Più di una settimana
Stato di attività
Attiva
Chiarezza
Abbastanza chiara
Idoneità per principianti
45/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.