google-adk 0.0.1__py3-none-any.whl → 0.0.3__py3-none-any.whl

google/adk/events/event.py

@@ -0,0 +1,130 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+from datetime import datetime
+import random
+import string
+from typing import Optional
+
+from google.genai import types
+from pydantic import ConfigDict
+from pydantic import Field
+
+from ..models.llm_response import LlmResponse
+from .event_actions import EventActions
+
+
+class Event(LlmResponse):
+  """Represents an event in a conversation between agents and users.
+
+  It is used to store the content of the conversation, as well as the actions
+  taken by the agents like function calls, etc.
+
+  Attributes:
+    invocation_id: The invocation ID of the event.
+    author: "user" or the name of the agent, indicating who appended the event
+      to the session.
+    actions: The actions taken by the agent.
+    long_running_tool_ids: The ids of the long running function calls.
+    branch: The branch of the event.
+    id: The unique identifier of the event.
+    timestamp: The timestamp of the event.
+    is_final_response: Whether the event is the final response of the agent.
+    get_function_calls: Returns the function calls in the event.
+  """
+
+  model_config = ConfigDict(
+      extra='forbid', ser_json_bytes='base64', val_json_bytes='base64'
+  )
+
+  # TODO: revert to be required after spark migration
+  invocation_id: str = ''
+  """The invocation ID of the event."""
+  author: str
+  """'user' or the name of the agent, indicating who appended the event to the
+  session."""
+  actions: EventActions = Field(default_factory=EventActions)
+  """The actions taken by the agent."""
+
+  long_running_tool_ids: Optional[set[str]] = None
+  """Set of ids of the long running function calls.
+  Agent client will know from this field about which function call is long running.
+  only valid for function call event
+  """
+  branch: Optional[str] = None
+  """The branch of the event.
+
+  The format is like agent_1.agent_2.agent_3, where agent_1 is the parent of
+  agent_2, and agent_2 is the parent of agent_3.
+
+  Branch is used when multiple sub-agent shouldn't see their peer agents'
+  conversaction history.
+  """
+
+  # The following are computed fields.
+  # Do not assign the ID. It will be assigned by the session.
+  id: str = ''
+  """The unique identifier of the event."""
+  timestamp: float = Field(default_factory=lambda: datetime.now().timestamp())
+  """The timestamp of the event."""
+
+  def model_post_init(self, __context):
+    """Post initialization logic for the event."""
+    # Generates a random ID for the event.
+    if not self.id:
+      self.id = Event.new_id()
+
+  def is_final_response(self) -> bool:
+    """Returns whether the event is the final response of the agent."""
+    if self.actions.skip_summarization or self.long_running_tool_ids:
+      return True
+    return (
+        not self.get_function_calls()
+        and not self.get_function_responses()
+        and not self.partial
+        and not self.has_trailing_code_exeuction_result()
+    )
+
+  def get_function_calls(self) -> list[types.FunctionCall]:
+    """Returns the function calls in the event."""
+    func_calls = []
+    if self.content and self.content.parts:
+      for part in self.content.parts:
+        if part.function_call:
+          func_calls.append(part.function_call)
+    return func_calls
+
+  def get_function_responses(self) -> list[types.FunctionResponse]:
+    """Returns the function responses in the event."""
+    func_response = []
+    if self.content and self.content.parts:
+      for part in self.content.parts:
+        if part.function_response:
+          func_response.append(part.function_response)
+    return func_response
+
+  def has_trailing_code_exeuction_result(
+      self,
+  ) -> bool:
+    """Returns whether the event has a trailing code execution result."""
+    if self.content:
+      if self.content.parts:
+        return self.content.parts[-1].code_execution_result is not None
+    return False
+
+  @staticmethod
+  def new_id():
+    characters = string.ascii_letters + string.digits
+    return ''.join(random.choice(characters) for _ in range(8))

google/adk/events/event_actions.py

@@ -0,0 +1,55 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+
+from ..auth.auth_tool import AuthConfig
+
+
+class EventActions(BaseModel):
+  """Represents the actions attached to an event."""
+
+  model_config = ConfigDict(extra='forbid')
+
+  skip_summarization: Optional[bool] = None
+  """If true, it won't call model to summarize function response.
+
+  Only used for function_response event.
+  """
+
+  state_delta: dict[str, object] = Field(default_factory=dict)
+  """Indicates that the event is updating the state with the given delta."""
+
+  artifact_delta: dict[str, int] = Field(default_factory=dict)
+  """Indicates that the event is updating an artifact. key is the filename,
+  value is the version."""
+
+  transfer_to_agent: Optional[str] = None
+  """If set, the event transfers to the specified agent."""
+
+  escalate: Optional[bool] = None
+  """The agent is escalating to a higher level agent."""
+
+  requested_auth_configs: dict[str, AuthConfig] = Field(default_factory=dict)
+  """Will only be set by a tool response indicating tool request euc.
+  dict key is the function call id since one function call response (from model)
+  could correspond to multiple function calls.
+  dict value is the required auth config.
+  """

google/adk/examples/__init__.py

@@ -0,0 +1,28 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .base_example_provider import BaseExampleProvider
+from .example import Example
+
+__all__ = [
+    'BaseExampleProvider',
+    'Example',
+]
+
+try:
+  from .vertex_ai_example_store import VertexAiExampleStore
+
+  __all__.append('VertexAiExampleStore')
+except ImportError:
+  pass

google/adk/examples/base_example_provider.py

@@ -0,0 +1,35 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import abc
+from .example import Example
+
+
+# A class that provides examples for a given query.
+class BaseExampleProvider(abc.ABC):
+  """Base class for example providers.
+
+  This class defines the interface for providing examples for a given query.
+  """
+
+  @abc.abstractmethod
+  def get_examples(self, query: str) -> list[Example]:
+    """Returns a list of examples for a given query.
+
+    Args:
+        query: The query to get examples for.
+
+    Returns:
+        A list of Example objects.
+    """

google/adk/examples/example.py

@@ -0,0 +1,27 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from google.genai import types
+from pydantic import BaseModel
+
+
+class Example(BaseModel):
+  """A few-shot example.
+
+  Attributes:
+    input: The input content for the example.
+    output: The expected output content for the example.
+  """
+  input: types.Content
+  output: list[types.Content]

google/adk/examples/example_util.py

@@ -0,0 +1,123 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Utility functions for converting examples to a string that can be used in system instructions in the prompt."""
+
+import logging
+from typing import Optional, Union
+from typing import TYPE_CHECKING
+
+from .base_example_provider import BaseExampleProvider
+from .example import Example
+
+if TYPE_CHECKING:
+  from ..sessions.session import Session
+
+logger = logging.getLogger(__name__)
+
+# Constant parts of the example string
+_EXAMPLES_INTRO = (
+    "<EXAMPLES>\nBegin few-shot\nThe following are examples of user queries and"
+    " model responses using the available tools.\n\n"
+)
+_EXAMPLES_END = "End few-shot\n<EXAMPLES>"
+_EXAMPLE_START = "EXAMPLE {}:\nBegin example\n"
+_EXAMPLE_END = "End example\n\n"
+_USER_PREFIX = "[user]\n"
+_MODEL_PREFIX = "[model]\n"
+_FUNCTION_PREFIX = "```\n"
+_FUNCTION_CALL_PREFIX = "```tool_code\n"
+_FUNCTION_CALL_SUFFIX = "\n```\n"
+_FUNCTION_RESPONSE_PREFIX = "```tool_outputs\n"
+_FUNCTION_RESPONSE_SUFFIX = "\n```\n"
+
+
+# TODO(yaojie): Add unit tests for this function.
+def convert_examples_to_text(
+    examples: list[Example], model: Optional[str]
+) -> str:
+  """Converts a list of examples to a string that can be used in a system instruction."""
+  examples_str = ""
+  for example_num, example in enumerate(examples):
+    output = f"{_EXAMPLE_START.format(example_num + 1)}{_USER_PREFIX}"
+    if example.input and example.input.parts:
+      output += (
+          "\n".join(part.text for part in example.input.parts if part.text)
+          + "\n"
+      )
+
+    gemini2 = model is None or "gemini-2" in model
+    previous_role = None
+    for content in example.output:
+      role = _MODEL_PREFIX if content.role == "model" else _USER_PREFIX
+      if role != previous_role:
+        output += role
+      previous_role = role
+      for part in content.parts:
+        if part.function_call:
+          args = []
+          # Convert function call part to python-like function call
+          for k, v in part.function_call.args.items():
+            if isinstance(v, str):
+              args.append(f"{k}='{v}'")
+            else:
+              args.append(f"{k}={v}")
+          prefix = _FUNCTION_PREFIX if gemini2 else _FUNCTION_CALL_PREFIX
+          output += (
+              f"{prefix}{part.function_call.name}({', '.join(args)}){_FUNCTION_CALL_SUFFIX}"
+          )
+        # Convert function response part to json string
+        elif part.function_response:
+          prefix = _FUNCTION_PREFIX if gemini2 else _FUNCTION_RESPONSE_PREFIX
+          output += f"{prefix}{part.function_response.__dict__}{_FUNCTION_RESPONSE_SUFFIX}"
+        elif part.text:
+          output += f"{part.text}\n"
+
+    output += _EXAMPLE_END
+    examples_str += output
+
+  return f"{_EXAMPLES_INTRO}{examples_str}{_EXAMPLES_END}"
+
+
+def _get_latest_message_from_user(session: "Session") -> str:
+  """Gets the latest message from the user.
+
+  Returns:
+    The latest message from the user. If not found, returns an empty string.
+  """
+  events = session.events
+  if not events:
+    return ""
+
+  event = events[-1]
+  if event.author == "user" and not event.get_function_responses():
+    if event.content.parts and event.content.parts[0].text:
+      return event.content.parts[0].text
+    else:
+      logger.warning("No message from user for fetching example.")
+
+  return ""
+
+
+def build_example_si(
+    examples: Union[list[Example], BaseExampleProvider],
+    query: str,
+    model: Optional[str],
+) -> str:
+  if isinstance(examples, list):
+    return convert_examples_to_text(examples, model)
+  if isinstance(examples, BaseExampleProvider):
+    return convert_examples_to_text(examples.get_examples(query), model)
+
+  raise ValueError("Invalid example configuration")

google/adk/examples/vertex_ai_example_store.py

@@ -0,0 +1,104 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from google.genai import types
+from typing_extensions import override
+from vertexai.preview import example_stores
+
+from .base_example_provider import BaseExampleProvider
+from .example import Example
+
+
+class VertexAiExampleStore(BaseExampleProvider):
+  """Provides examples from Vertex example store."""
+
+  def __init__(self, examples_store_name: str):
+    """Initializes the VertexAiExampleStore.
+
+    Args:
+        examples_store_name: The resource name of the vertex example store, in
+          the format of
+          ``projects/{project}/locations/{location}/exampleStores/{example_store}``.
+    """
+    self.examples_store_name = examples_store_name
+
+  @override
+  def get_examples(self, query: str) -> list[Example]:
+    example_store = example_stores.ExampleStore(self.examples_store_name)
+    # Retrieve relevant examples.
+    request = {
+        "stored_contents_example_parameters": {
+            "content_search_key": {
+                "contents": [{"role": "user", "parts": [{"text": query}]}],
+                "search_key_generation_method": {"last_entry": {}},
+            }
+        },
+        "top_k": 10,
+        "example_store": self.examples_store_name,
+    }
+    response = example_store.api_client.search_examples(request)
+
+    returned_examples = []
+    # Convert results to genai formats
+    for result in response.results:
+      if result.similarity_score < 0.5:
+        continue
+      expected_contents = [
+          content.content
+          for content in result.example.stored_contents_example.contents_example.expected_contents
+      ]
+      expected_output = []
+      for content in expected_contents:
+        expected_parts = []
+        for part in content.parts:
+          if part.text:
+            expected_parts.append(types.Part.from_text(text=part.text))
+          elif part.function_call:
+            expected_parts.append(
+                types.Part.from_function_call(
+                    name=part.function_call.name,
+                    args={
+                        key: value
+                        for key, value in part.function_call.args.items()
+                    },
+                )
+            )
+          elif part.function_response:
+            expected_parts.append(
+                types.Part.from_function_response(
+                    name=part.function_response.name,
+                    response={
+                        key: value
+                        for key, value in part.function_response.response.items()
+                    },
+                )
+            )
+        expected_output.append(
+            types.Content(role=content.role, parts=expected_parts)
+        )
+
+      returned_examples.append(
+          Example(
+              input=types.Content(
+                  role="user",
+                  parts=[
+                      types.Part.from_text(
+                          text=result.example.stored_contents_example.search_key
+                      )
+                  ],
+              ),
+              output=expected_output,
+          )
+      )
+    return returned_examples

google/adk/flows/__init__.py

@@ -0,0 +1,14 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+

google/adk/flows/llm_flows/__init__.py

@@ -0,0 +1,20 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from . import _code_execution
+from . import _nl_planning
+from . import contents
+from . import functions
+from . import identity
+from . import instructions

google/adk/flows/llm_flows/_base_llm_processor.py

@@ -0,0 +1,52 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Defines the processor interface used for BaseLlmFlow."""
+from __future__ import annotations
+
+from abc import ABC
+from abc import abstractmethod
+from typing import AsyncGenerator
+from typing import TYPE_CHECKING
+
+from ...agents.invocation_context import InvocationContext
+from ...events.event import Event
+
+if TYPE_CHECKING:
+  from ...models.llm_request import LlmRequest
+  from ...models.llm_response import LlmResponse
+
+
+class BaseLlmRequestProcessor(ABC):
+  """Base class for LLM request processor."""
+
+  @abstractmethod
+  async def run_async(
+      self, invocation_context: InvocationContext, llm_request: LlmRequest
+  ) -> AsyncGenerator[Event, None]:
+    """Runs the processor."""
+    raise NotImplementedError("Not implemented.")
+    yield  # AsyncGenerator requires a yield in function body.
+
+
+class BaseLlmResponseProcessor(ABC):
+  """Base class for LLM response processor."""
+
+  @abstractmethod
+  async def run_async(
+      self, invocation_context: InvocationContext, llm_response: LlmResponse
+  ) -> AsyncGenerator[Event, None]:
+    """Processes the LLM response."""
+    raise NotImplementedError("Not implemented.")
+    yield  # AsyncGenerator requires a yield in function body.