Skip to content

Commit ea7a16a

Browse files
committed
docs(bqaa): drop GitHub-issue references from docstrings/comments
Following review feedback that docstrings shouldn't reference GitHub issue numbers or PR review-thread revisions. The technical substance (contract names like 'A1/A2 envelope', 'C7 pair-key emit', 'flat-with- prefix', 'HITL non-routing') stays where it aids navigation; only the '#NNN' and 'v5' annotations come out. 20 sites swept across the plugin module and test file. Behavior and test names unchanged; suite still 252/252. The existing 'google#4645' reference in workflow plumbing is left alone -- it was not introduced by this change.
1 parent fa20827 commit ea7a16a

2 files changed

Lines changed: 27 additions & 27 deletions

File tree

‎src/google/adk/plugins/bigquery_agent_analytics_plugin.py‎

Lines changed: 24 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -97,9 +97,9 @@
9797
"adk_request_input": "HITL_INPUT_REQUEST",
9898
})
9999

100-
# Reverse of _HITL_EVENT_MAP for the C7 pause_kind discriminator. The
101-
# id→name lookup in #199/#293 v5 routes ``adk_request_credential`` →
102-
# ``hitl_credential`` etc.; everything else is ``tool``.
100+
# Reverse of _HITL_EVENT_MAP for the long-running-tool pause_kind
101+
# discriminator. The id→name lookup routes ``adk_request_credential``
102+
# → ``hitl_credential`` etc.; everything else is ``tool``.
103103
_HITL_PAUSE_KIND_MAP = MappingProxyType({
104104
"adk_request_credential": "hitl_credential",
105105
"adk_request_confirmation": "hitl_confirmation",
@@ -110,7 +110,7 @@
110110
def _derive_scope(
111111
isolation_scope: Optional[str],
112112
) -> Optional[dict[str, str]]:
113-
"""Derives ``attributes.adk.scope`` per the #198 / #293 v5 rule.
113+
"""Derives ``attributes.adk.scope`` from an Event's isolation_scope.
114114
115115
Order is fixed: (1) None → null; (2) node-shape (``name@run_id`` or
116116
``parent/name@run_id``) → ``node_run``; (3) any other non-empty
@@ -2018,7 +2018,7 @@ class EventData:
20182018
# so ``_log_event`` can stamp ``attributes.adk.{source_event_id, node,
20192019
# branch, scope, ...}``. Leave None for rows that don't originate from
20202020
# an Event — the envelope helper omits those keys rather than
2021-
# synthesizing fake identity (per #293 v5 A3 contract). Because the
2021+
# synthesizing fake identity. Because the
20222022
# surrounding column is BigQuery JSON, an omitted key resolves to SQL
20232023
# NULL via ``JSON_VALUE(attributes, '$.adk.<field>')``, so consumer
20242024
# gating with ``... IS NOT NULL`` works without explicit JSON nulls.
@@ -2027,7 +2027,7 @@ class EventData:
20272027
# at the top level of ``attributes``). C7's pair keys
20282028
# (``pause_kind`` / ``function_call_id``) ride here so consumer SQL
20292029
# like ``JSON_VALUE(attributes, '$.adk.function_call_id')`` lands at
2030-
# the right JSON path per #293 v5.
2030+
# the right JSON path.
20312031
adk_extras: dict[str, Any] = field(default_factory=dict)
20322032

20332033

@@ -2820,7 +2820,7 @@ def _build_adk_envelope(
28202820
callback_context: CallbackContext,
28212821
source_event: Optional["Event"],
28222822
) -> dict[str, Any]:
2823-
"""Builds the ``attributes.adk`` envelope per #293 v5.
2823+
"""Builds the ``attributes.adk`` envelope.
28242824
28252825
A1 / A2 (``schema_version``, ``app_name``) stamp on every ADK-enriched
28262826
row regardless of origin. A3 / C1 / C2 / C3 (``source_event_id``,
@@ -2883,7 +2883,7 @@ def _build_adk_envelope(
28832883
except Exception:
28842884
pass
28852885

2886-
# C3: scope shape derivation (per #190 v5 / #198). Order matters:
2886+
# Scope shape derivation. Order matters:
28872887
# node-shape patterns must be checked before falling through to
28882888
# function_call so bare ``name@run_id`` doesn't misclassify.
28892889
try:
@@ -2892,7 +2892,7 @@ def _build_adk_envelope(
28922892
except Exception:
28932893
pass
28942894

2895-
# C8: raw EventActions mirror (flat under attributes.adk per #203).
2895+
# Raw EventActions mirror (flat under attributes.adk).
28962896
# Stamp only when actually set so JSON doesn't bloat with nulls.
28972897
try:
28982898
actions = getattr(source_event, "actions", None)
@@ -2931,7 +2931,7 @@ def _enrich_attributes(
29312931
29322932
Reads ``model``, ``model_version``, and ``usage_metadata`` from
29332933
*event_data*, copies ``extra_attributes``, then adds session metadata
2934-
and custom tags. Also stamps the ``adk`` envelope (#293 v5).
2934+
and custom tags. Also stamps the ``adk`` envelope.
29352935
29362936
Returns:
29372937
A new dict ready for JSON serialization into the attributes column.
@@ -2940,7 +2940,7 @@ def _enrich_attributes(
29402940
adk_envelope = self._build_adk_envelope(
29412941
callback_context, event_data.source_event
29422942
)
2943-
# Merge producer-supplied adk_extras (#293 v5 C7 pair keys etc.)
2943+
# Merge producer-supplied adk_extras (long-running pair keys etc.)
29442944
# INTO the adk envelope so consumer SQL on
29452945
# ``$.adk.pause_kind`` / ``$.adk.function_call_id`` resolves.
29462946
# adk_envelope wins on key conflict — producer-derived envelope
@@ -3107,7 +3107,7 @@ async def on_user_message_callback(
31073107
are the long-running tool completions for tools that paused via
31083108
``TOOL_PAUSED``. Emitted as ``TOOL_COMPLETED`` with
31093109
``pause_kind = 'tool'`` and ``function_call_id`` so the customer
3110-
can join the pair from BigQuery (#293 v5 C7 pair-key subset).
3110+
can join the pair from BigQuery.
31113111
31123112
Args:
31133113
invocation_context: The context of the current invocation.
@@ -3137,7 +3137,7 @@ async def on_user_message_callback(
31373137
}
31383138
if hitl_event:
31393139
# HITL completions stay on the HITL_*_COMPLETED stream — they
3140-
# MUST NOT also emit TOOL_COMPLETED (per #293 v5 C7).
3140+
# MUST NOT also emit TOOL_COMPLETED.
31413141
await self._log_event(
31423142
hitl_event + "_COMPLETED",
31433143
callback_ctx,
@@ -3150,8 +3150,8 @@ async def on_user_message_callback(
31503150
# tool calls complete inside the agent run via
31513151
# after_tool_callback, so a function_response inside a user
31523152
# message is the resume side of a previously-paused tool.
3153-
# Stamp the pair keys; pause_orphan / registry semantics are
3154-
# deferred to #206.
3153+
# Stamp the pair keys; pause_orphan / registry semantics
3154+
# are intentionally deferred.
31553155
await self._log_event(
31563156
"TOOL_COMPLETED",
31573157
callback_ctx,
@@ -3211,10 +3211,10 @@ async def on_event_callback(
32113211
),
32123212
)
32133213

3214-
# --- AGENT_TRANSFER (C4 / #200) ---
3214+
# --- AGENT_TRANSFER ---
32153215
# actions.transfer_to_agent stores the *target* agent only
32163216
# (events/event_actions.py:75); from_agent is pinned to event.author
3217-
# per #293 v5 C4. Never fabricate authors on non-Event paths.
3217+
# by contract. Never fabricate authors on non-Event paths.
32183218
if event.actions.transfer_to_agent:
32193219
await self._log_event(
32203220
"AGENT_TRANSFER",
@@ -3226,7 +3226,7 @@ async def on_event_callback(
32263226
event_data=EventData(source_event=event),
32273227
)
32283228

3229-
# --- EVENT_COMPACTION (C5 / #201) ---
3229+
# --- EVENT_COMPACTION ---
32303230
# EventCompaction.start_timestamp / end_timestamp are float epoch
32313231
# seconds. Preserve fractional precision here; consumer view
32323232
# conversion is deferred.
@@ -3247,7 +3247,7 @@ async def on_event_callback(
32473247
event_data=EventData(source_event=event),
32483248
)
32493249

3250-
# --- AGENT_STATE_CHECKPOINT (C6 / #202) ---
3250+
# --- AGENT_STATE_CHECKPOINT ---
32513251
# Fires when *either* agent_state is set or end_of_agent is True;
32523252
# supports {agent_state: None, end_of_agent: True} payloads.
32533253
# Inline payload only — oversized-state GCS offload deferred.
@@ -3274,7 +3274,7 @@ async def on_event_callback(
32743274
event_data=EventData(source_event=event),
32753275
)
32763276

3277-
# --- HITL + TOOL_PAUSED (C7 / #199 — pair-key subset) + per-part
3277+
# --- HITL + TOOL_PAUSED (pair-key emit) + per-part
32783278
# iteration over event.content.parts ---
32793279
# TOOL_PAUSED fires per long_running_tool_id; pause_kind is derived
32803280
# via the id→name lookup against _HITL_PAUSE_KIND_MAP, so a HITL
@@ -3305,9 +3305,9 @@ async def on_event_callback(
33053305
is_truncated=is_truncated,
33063306
event_data=EventData(source_event=event),
33073307
)
3308-
# C7: per-id TOOL_PAUSED emit. pause_kind derives from the
3309-
# function_call NAME (#199 / #293 v5) — looking it up against
3310-
# the id value would misclassify every HITL pause as 'tool'.
3308+
# Per-id TOOL_PAUSED emit. pause_kind derives from the
3309+
# function_call NAME — looking it up against the id value
3310+
# would misclassify every HITL pause as 'tool'.
33113311
if part.function_call.id in long_running_ids:
33123312
pause_kind = _HITL_PAUSE_KIND_MAP.get(
33133313
part.function_call.name, "tool"
@@ -3334,7 +3334,7 @@ async def on_event_callback(
33343334
)
33353335
# Detect HITL function responses (completion events). HITL
33363336
# function responses route ONLY here, never to TOOL_COMPLETED
3337-
# (per #293 v5 C7 / verified at this file's HITL test suite).
3337+
# (verified by this file's HITL test suite).
33383338
if part.function_response:
33393339
hitl_event = _HITL_EVENT_MAP.get(part.function_response.name)
33403340
if hitl_event:

‎tests/unittests/plugins/test_bigquery_agent_analytics_plugin.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8008,7 +8008,7 @@ async def test_skips_executable_code_only_events(
80088008

80098009

80108010
# -----------------------------------------------------------------------------
8011-
# ADK 2.0 minimum producer cut (#293 v5)
8011+
# ADK 2.0 minimum producer cut
80128012
#
80138013
# Coverage matrix:
80148014
# A1 / A2 attributes.adk.{schema_version, app_name} on every row
@@ -8451,7 +8451,7 @@ async def test_route_and_rewind_flat_under_attributes_adk(
84518451
invocation_context,
84528452
dummy_arrow_schema,
84538453
):
8454-
"""C8 (#203): route / rewind_before_invocation_id mirror under
8454+
"""C8: route / rewind_before_invocation_id mirror under
84558455
attributes.adk.* (flat-with-prefix, NOT nested under .actions.)."""
84568456
event = event_lib.Event(
84578457
author="agent",
@@ -8470,7 +8470,7 @@ async def test_route_and_rewind_flat_under_attributes_adk(
84708470
mock_write_client, dummy_arrow_schema
84718471
)
84728472
adk = json.loads(log_entry["attributes"])["adk"]
8473-
# Flat-with-prefix per #203 / #293 v5.
8473+
# Flat-with-prefix mirror under attributes.adk.*.
84748474
assert adk["route"] == "branch_b"
84758475
assert adk["rewind_before_invocation_id"] == "inv-earlier"
84768476
# Not nested under .actions.

0 commit comments

Comments
 (0)