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

google/adk/cli/utils/__init__.py

@@ -0,0 +1,49 @@
+# 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 re
+from typing import Any
+from typing import Optional
+
+from ...agents.base_agent import BaseAgent
+from ...agents.llm_agent import LlmAgent
+
+__all__ = [
+    'create_empty_state',
+]
+
+
+def _create_empty_state(agent: BaseAgent, all_state: dict[str, Any]):
+  for sub_agent in agent.sub_agents:
+    _create_empty_state(sub_agent, all_state)
+
+  if (
+      isinstance(agent, LlmAgent)
+      and agent.instruction
+      and isinstance(agent.instruction, str)
+  ):
+    for key in re.findall(r'{([\w]+)}', agent.instruction):
+      all_state[key] = ''
+
+
+def create_empty_state(
+    agent: BaseAgent, initialized_states: Optional[dict[str, Any]] = None
+) -> dict[str, Any]:
+  """Creates empty str for non-initialized states."""
+  non_initialized_states = {}
+  _create_empty_state(agent, non_initialized_states)
+  for key in initialized_states or {}:
+    if key in non_initialized_states:
+      del non_initialized_states[key]
+  return non_initialized_states

google/adk/cli/utils/envs.py

@@ -0,0 +1,57 @@
+# 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 logging
+import os
+
+from dotenv import load_dotenv
+
+logger = logging.getLogger(__file__)
+
+
+def _walk_to_root_until_found(folder, filename) -> str:
+  checkpath = os.path.join(folder, filename)
+  if os.path.exists(checkpath) and os.path.isfile(checkpath):
+    return checkpath
+
+  parent_folder = os.path.dirname(folder)
+  if parent_folder == folder:  # reached the root
+    return ''
+
+  return _walk_to_root_until_found(parent_folder, filename)
+
+
+def load_dotenv_for_agent(
+    agent_name: str, agent_parent_folder: str, filename: str = '.env'
+):
+  """Lods the .env file for the agent module."""
+
+  # Gets the folder of agent_module as starting_folder
+  starting_folder = os.path.abspath(
+      os.path.join(agent_parent_folder, agent_name)
+  )
+  dotenv_file_path = _walk_to_root_until_found(starting_folder, filename)
+  if dotenv_file_path:
+    load_dotenv(dotenv_file_path, override=True, verbose=True)
+    logger.info(
+        'Loaded %s file for %s at %s',
+        filename,
+        agent_name,
+        dotenv_file_path,
+    )
+    logger.info(
+        'Reloaded %s file for %s at %s', filename, agent_name, dotenv_file_path
+    )
+  else:
+    logger.info('No %s file found for %s', filename, agent_name)

google/adk/cli/utils/evals.py

@@ -0,0 +1,93 @@
+# 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 typing import Any
+
+from ...sessions.session import Session
+
+
+def convert_session_to_eval_format(session: Session) -> list[dict[str, Any]]:
+  """Converts a session data into eval format.
+
+  Args:
+      session: The session that should be converted.
+
+  Returns:
+      list: A single evaluation dataset in the required format.
+  """
+  eval_case = []
+  events = session.events if session and session.events else []
+
+  for event in events:
+    if event.author == 'user':
+      if not event.content or not event.content.parts:
+        continue
+
+      # Extract user query
+      content = event.content
+      parts = content.parts
+
+      query = parts[0].text or ''
+
+      # Find the corresponding tool usage or response for the query
+      expected_tool_use = []
+      intermediate_agent_responses = []
+
+      # Check subsequent events to extract tool uses or responses for this turn.
+      for subsequent_event in events[events.index(event) + 1 :]:
+        event_author = subsequent_event.author or 'agent'
+        if event_author == 'user':
+          # We found an event where the author was the user. This means that a
+          # new turn has started. So close this turn here.
+          break
+
+        if not subsequent_event.content or not subsequent_event.content.parts:
+          continue
+
+        for subsequent_part in subsequent_event.content.parts:
+          # Some events have both function call and reference
+
+          if subsequent_part.function_call:
+            tool_name = subsequent_part.function_call.name or ''
+            tool_input = subsequent_part.function_call.args or {}
+            expected_tool_use.append({
+                'tool_name': tool_name,
+                'tool_input': tool_input,
+            })
+          elif subsequent_part.text:
+            # Also keep track of all the natural langauge responses that
+            # agent (or sub agents) generated.
+            intermediate_agent_responses.append(
+                {'author': event_author, 'text': subsequent_part.text}
+            )
+
+      # If we are here then either we are done reading all the events or we
+      # encountered an event that had content authored by the end-user.
+      # This, basically means an end of turn.
+      # We assume that the last natural langauge intermediate response is the
+      # final response from the agent/model. We treat that as a reference.
+      eval_case.append({
+          'query': query,
+          'expected_tool_use': expected_tool_use,
+          'expected_intermediate_agent_responses': intermediate_agent_responses[
+              :-1
+          ],
+          'reference': (
+              intermediate_agent_responses[-1]['text']
+              if intermediate_agent_responses
+              else ''
+          ),
+      })
+
+  return eval_case

google/adk/cli/utils/logs.py

@@ -0,0 +1,72 @@
+# 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 logging
+import os
+import tempfile
+import time
+
+LOGGING_FORMAT = (
+    '%(asctime)s - %(levelname)s - %(filename)s:%(lineno)d - %(message)s'
+)
+
+
+def log_to_stderr(level=logging.INFO):
+  logging.basicConfig(
+      level=level,
+      format=LOGGING_FORMAT,
+  )
+
+
+def log_to_tmp_folder(
+    level=logging.INFO,
+    *,
+    sub_folder: str = 'agents_log',
+    log_file_prefix: str = 'agent',
+    log_file_timestamp: str = time.strftime('%Y%m%d_%H%M%S'),
+):
+  """Logs to system temp folder, instead of logging to stderr.
+
+  Args
+    sub_folder: str = 'agents_log',
+    log_file_prefix: str = 'agent',
+    log_file_timestamp: str = time.strftime('%Y%m%d_%H%M%S'),
+
+  Returns
+    the log file path.
+  """
+  log_dir = os.path.join(tempfile.gettempdir(), sub_folder)
+  log_filename = f'{log_file_prefix}.{log_file_timestamp}.log'
+  log_filepath = os.path.join(log_dir, log_filename)
+
+  os.makedirs(log_dir, exist_ok=True)
+
+  file_handler = logging.FileHandler(log_filepath, mode='w')
+  file_handler.setLevel(level)
+  file_handler.setFormatter(logging.Formatter(LOGGING_FORMAT))
+
+  root_logger = logging.getLogger()
+  root_logger.setLevel(level)
+  root_logger.handlers = []  # Clear handles to disable logging to stderr
+  root_logger.addHandler(file_handler)
+
+  print(f'Log setup complete: {log_filepath}')
+
+  latest_log_link = os.path.join(log_dir, f'{log_file_prefix}.latest.log')
+  if os.path.islink(latest_log_link):
+    os.unlink(latest_log_link)
+  os.symlink(log_filepath, latest_log_link)
+
+  print(f'To access latest log: tail -F {latest_log_link}')
+  return log_filepath

google/adk/code_executors/__init__.py

@@ -0,0 +1,49 @@
+# 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 logging
+
+from .base_code_executor import BaseCodeExecutor
+from .code_executor_context import CodeExecutorContext
+from .unsafe_local_code_executor import UnsafeLocalCodeExecutor
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    'BaseCodeExecutor',
+    'CodeExecutorContext',
+    'UnsafeLocalCodeExecutor',
+]
+
+try:
+  from .vertex_ai_code_executor import VertexAiCodeExecutor
+
+  __all__.append('VertexAiCodeExecutor')
+except ImportError:
+  logger.debug(
+      'The Vertex sdk is not installed. If you want to use the Vertex Code'
+      ' Interpreter with agents, please install it. If not, you can ignore this'
+      ' warning.'
+  )
+
+try:
+  from .container_code_executor import ContainerCodeExecutor
+
+  __all__.append('ContainerCodeExecutor')
+except ImportError:
+  logger.debug(
+      'The docker sdk is not installed. If you want to use the Container Code'
+      ' Executor with agents, please install it. If not, you can ignore this'
+      ' warning.'
+  )

google/adk/code_executors/base_code_executor.py

@@ -0,0 +1,97 @@
+# 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 typing import List
+
+from pydantic import BaseModel
+
+from ..agents.invocation_context import InvocationContext
+from .code_execution_utils import CodeExecutionInput
+from .code_execution_utils import CodeExecutionResult
+
+
+class BaseCodeExecutor(BaseModel):
+  """Abstract base class for all code executors.
+
+  The code executor allows the agent to execute code blocks from model responses
+  and incorporate the execution results into the final response.
+
+  Attributes:
+    optimize_data_file: If true, extract and process data files from the model
+      request and attach them to the code executor. Supported data file
+      MimeTypes are [text/csv]. Default to False.
+    stateful: Whether the code executor is stateful. Default to False.
+    error_retry_attempts: The number of attempts to retry on consecutive code
+      execution errors. Default to 2.
+    code_block_delimiters: The list of the enclosing delimiters to identify the
+      code blocks.
+    execution_result_delimiters: The delimiters to format the code execution
+      result.
+  """
+
+  optimize_data_file: bool = False
+  """
+  If true, extract and process data files from the model request
+  and attach them to the code executor.
+  Supported data file MimeTypes are [text/csv].
+
+  Default to False.
+  """
+
+  stateful: bool = False
+  """
+  Whether the code executor is stateful. Default to False.
+  """
+
+  error_retry_attempts: int = 2
+  """
+  The number of attempts to retry on consecutive code execution errors. Default to 2.
+  """
+
+  code_block_delimiters: List[tuple[str, str]] = [
+      ('```tool_code\n', '\n```'),
+      ('```python\n', '\n```'),
+  ]
+  """
+  The list of the enclosing delimiters to identify the code blocks.
+  For example, the delimiter ('```python\n', '\n```') can be
+  used to identify code blocks with the following format:
+
+  ```python
+  print("hello")
+  ```
+  """
+
+  execution_result_delimiters: tuple[str, str] = ('```tool_output\n', '\n```')
+  """
+  The delimiters to format the code execution result.
+  """
+
+  @abc.abstractmethod
+  def execute_code(
+      self,
+      invocation_context: InvocationContext,
+      code_execution_input: CodeExecutionInput,
+  ) -> CodeExecutionResult:
+    """Executes code and return the code execution result.
+
+    Args:
+      invocation_context: The invocation context of the code execution.
+      code_execution_input: The code execution input.
+
+    Returns:
+      The code execution result.
+    """
+    pass

google/adk/code_executors/code_execution_utils.py

@@ -0,0 +1,256 @@
+# 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 code execution."""
+
+import base64
+import binascii
+import copy
+import dataclasses
+import re
+from typing import List, Optional
+
+from google.genai import types
+
+
+@dataclasses.dataclass(frozen=True)
+class File:
+  """A structure that contains a file name and its content."""
+
+  name: str
+  """
+  The name of the file with file extension (e.g., "file.csv").
+  """
+
+  content: str
+  """
+  The base64-encoded bytes of the file content.
+  """
+
+  mime_type: str = 'text/plain'
+  """
+  The mime type of the file (e.g., "image/png").
+  """
+
+
+@dataclasses.dataclass
+class CodeExecutionInput:
+  """A structure that contains the input of code execution."""
+
+  code: str
+  """
+  The code to execute.
+  """
+
+  input_files: list[File] = dataclasses.field(default_factory=list)
+  """
+  The input files available to the code.
+  """
+
+  execution_id: Optional[str] = None
+  """
+  The execution ID for the stateful code execution.
+  """
+
+
+@dataclasses.dataclass
+class CodeExecutionResult:
+  """A structure that contains the result of code execution."""
+
+  stdout: str = ''
+  """
+  The standard output of the code execution.
+  """
+
+  stderr: str = ''
+  """
+  The standard error of the code execution.
+  """
+
+  output_files: list[File] = dataclasses.field(default_factory=list)
+  """
+  The output files from the code execution.
+  """
+
+
+class CodeExecutionUtils:
+  """Utility functions for code execution."""
+
+  @staticmethod
+  def get_encoded_file_content(data: bytes) -> bytes:
+    """Gets the file content as a base64-encoded bytes.
+
+    Args:
+      data: The file content bytes.
+
+    Returns:
+      The file content as a base64-encoded bytes.
+    """
+
+    def _is_base64_encoded(data: bytes) -> bool:
+      try:
+        return base64.b64encode(base64.b64decode(data)) == data
+      except binascii.Error:
+        return False
+
+    return data if _is_base64_encoded(data) else base64.b64encode(data)
+
+  @staticmethod
+  def extract_code_and_truncate_content(
+      content: types.Content,
+      code_block_delimiters: List[tuple[str, str]],
+  ) -> Optional[str]:
+    """Extracts the first code block from the content and truncate everything after it.
+
+    Args:
+      content: The mutable content to extract the code from.
+      code_block_delimiters: The list of the enclosing delimiters to identify
+        the code blocks.
+
+    Returns:
+      The first code block if found, otherwise None.
+    """
+    if not content or not content.parts:
+      return
+
+    # Extract the code from the executable code parts if there're no associated
+    # code execution result parts.
+    for idx, part in enumerate(content.parts):
+      if part.executable_code and (
+          idx == len(content.parts) - 1
+          or not content.parts[idx + 1].code_execution_result
+      ):
+        content.parts = content.parts[: idx + 1]
+        return part.executable_code.code
+
+    # Extract the code from the text parts.
+    text_parts = [p for p in content.parts if p.text]
+    if not text_parts:
+      return
+
+    first_text_part = copy.deepcopy(text_parts[0])
+    response_text = '\n'.join([p.text for p in text_parts])
+
+    # Find the first code block.
+    leading_delimiter_pattern = '|'.join(d[0] for d in code_block_delimiters)
+    trailing_delimiter_pattern = '|'.join(d[1] for d in code_block_delimiters)
+    pattern = re.compile(
+        (
+            rf'(?P<prefix>.*?)({leading_delimiter_pattern})(?P<code>.*?)({trailing_delimiter_pattern})(?P<suffix>.*?)$'
+        ).encode(),
+        re.DOTALL,
+    )
+    pattern_match = pattern.search(response_text.encode())
+    if pattern_match is None:
+      return
+
+    code_str = pattern_match.group('code').decode()
+    if not code_str:
+      return
+
+    content.parts = []
+    if pattern_match.group('prefix'):
+      first_text_part.text = pattern_match.group('prefix').decode()
+      content.parts.append(first_text_part)
+    content.parts.append(
+        CodeExecutionUtils.build_executable_code_part(code_str)
+    )
+    return pattern_match.group('code').decode()
+
+  @staticmethod
+  def build_executable_code_part(code: str) -> types.Part:
+    """Builds an executable code part with code string.
+
+    Args:
+      code: The code string.
+
+    Returns:
+      The constructed executable code part.
+    """
+    return types.Part.from_executable_code(
+        code=code,
+        language='PYTHON',
+    )
+
+  @staticmethod
+  def build_code_execution_result_part(
+      code_execution_result: CodeExecutionResult,
+  ) -> types.Part:
+    """Builds the code execution result part from the code execution result.
+
+    Args:
+      code_execution_result: The code execution result.
+
+    Returns:
+      The constructed code execution result part.
+    """
+    if code_execution_result.stderr:
+      return types.Part.from_code_execution_result(
+          outcome='OUTCOME_FAILED',
+          output=code_execution_result.stderr,
+      )
+    final_result = []
+    if code_execution_result.stdout or not code_execution_result.output_files:
+      final_result.append(
+          'Code execution result:\n' + '%s\n' % code_execution_result.stdout
+      )
+    if code_execution_result.output_files:
+      final_result.append(
+          'Saved artifacts:\n'
+          + ','.join(
+              ['`%s`' % f.name for f in code_execution_result.output_files]
+          )
+      )
+    return types.Part.from_code_execution_result(
+        outcome='OUTCOME_OK',
+        output='\n\n'.join(final_result),
+    )
+
+  @staticmethod
+  def convert_code_execution_parts(
+      content: types.Content,
+      code_block_delimiter: tuple[str, str],
+      execution_result_delimiters: tuple[str, str],
+  ):
+    """Converts the code execution parts to text parts in a Content.
+
+    Args:
+      content: The mutable content to convert the code execution parts to text
+        parts.
+      code_block_delimiter: The delimiter to format the code block.
+      execution_result_delimiters: The delimiter to format the code execution
+        result.
+    """
+    if not content.parts:
+      return
+
+    # Handle the conversion of trailing executable code parts.
+    if content.parts[-1].executable_code:
+      content.parts[-1] = types.Part(
+          text=(
+              code_block_delimiter[0]
+              + content.parts[-1].executable_code.code
+              + code_block_delimiter[1]
+          )
+      )
+    # Handle the conversion of trailing code execution result parts.
+    # Skip if the Content has multiple parts, which means the Content is
+    # likely generated by the model.
+    elif len(content.parts) == 1 and content.parts[-1].code_execution_result:
+      content.parts[-1] = types.Part(
+          text=execution_result_delimiters[0]
+          + content.parts[-1].code_execution_result.output
+          + execution_result_delimiters[1]
+      )
+      content.role = 'user'