google-adk 1.0.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

google/adk/code_executors/vertex_ai_code_executor.py

@@ -15,7 +15,8 @@
 import datetime
 import mimetypes
 import os
-from typing import Any, Optional
+from typing import Any
+from typing import Optional
 
 from typing_extensions import override
 from vertexai.preview.extensions import Extension
@@ -147,18 +148,15 @@ class VertexAiCodeExecutor(BaseCodeExecutor):
     )
 
     # Save output file as artifacts.
-    current_timestamp = datetime.datetime.now().strftime('%Y%m%d_%H%M%S')
-    file_name_prefix = '%s_' % str(current_timestamp)
     saved_files = []
     file_count = 0
     for output_file in code_execution_result['output_files']:
       file_type = output_file['name'].split('.')[-1]
-      file_name = file_name_prefix + '%d.%s' % (file_count, file_type)
       if file_type in _SUPPORTED_IMAGE_TYPES:
         file_count += 1
         saved_files.append(
             File(
-                name='plot_' + file_name,
+                name=output_file['name'],
                 content=output_file['contents'],
                 mime_type=f'image/{file_type}',
             )
@@ -167,16 +165,16 @@ class VertexAiCodeExecutor(BaseCodeExecutor):
         file_count += 1
         saved_files.append(
             File(
-                name='data_' + file_name,
+                name=output_file['name'],
                 content=output_file['contents'],
                 mime_type=f'text/{file_type}',
             )
         )
       else:
-        mime_type, _ = mimetypes.guess_type(file_name)
+        mime_type, _ = mimetypes.guess_type(output_file['name'])
         saved_files.append(
             File(
-                name=file_name,
+                name=output_file['name'],
                 content=output_file['contents'],
                 mime_type=mime_type,
             )

google/adk/evaluation/eval_case.py

@@ -13,7 +13,9 @@
 # limitations under the License.
 
 
-from typing import Any, Optional, Tuple
+from typing import Any
+from typing import Optional
+from typing import Tuple
 
 from google.genai import types as genai_types
 from pydantic import alias_generators

google/adk/evaluation/eval_metrics.py

@@ -0,0 +1,74 @@
+# 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 alias_generators
+from pydantic import BaseModel
+from pydantic import ConfigDict
+
+from .eval_case import Invocation
+from .evaluator import EvalStatus
+
+
+class EvalMetric(BaseModel):
+  """A metric used to evaluate a particular aspect of an eval case."""
+
+  model_config = ConfigDict(
+      alias_generator=alias_generators.to_camel,
+      populate_by_name=True,
+  )
+
+  model_config = ConfigDict(
+      alias_generator=alias_generators.to_camel,
+      populate_by_name=True,
+  )
+
+  metric_name: str
+  """The name of the metric."""
+
+  threshold: float
+  """A threshold value. Each metric decides how to interpret this threshold."""
+
+
+class EvalMetricResult(EvalMetric):
+  """The actual computed score/value of a particular EvalMetric."""
+
+  model_config = ConfigDict(
+      alias_generator=alias_generators.to_camel,
+      populate_by_name=True,
+  )
+
+  score: Optional[float] = None
+  eval_status: EvalStatus
+
+
+class EvalMetricResultPerInvocation(BaseModel):
+  """Eval metric results per invocation."""
+
+  model_config = ConfigDict(
+      alias_generator=alias_generators.to_camel,
+      populate_by_name=True,
+  )
+
+  actual_invocation: Invocation
+  """The actual invocation, usually obtained by inferencing the agent."""
+
+  expected_invocation: Invocation
+  """The expected invocation, usually the reference or golden invocation."""
+
+  eval_metric_results: list[EvalMetricResult] = []
+  """Eval resutls for each applicable metric."""

google/adk/evaluation/eval_result.py

@@ -0,0 +1,86 @@
+# 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 alias_generators
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+
+from ..sessions.session import Session
+from .eval_metrics import EvalMetric
+from .eval_metrics import EvalMetricResult
+from .eval_metrics import EvalMetricResultPerInvocation
+from .evaluator import EvalStatus
+
+
+class EvalCaseResult(BaseModel):
+  """Case level evaluation results."""
+
+  model_config = ConfigDict(
+      alias_generator=alias_generators.to_camel,
+      populate_by_name=True,
+  )
+
+  eval_set_file: str = Field(
+      deprecated=True,
+      description="This field is deprecated, use eval_set_id instead.",
+  )
+  eval_set_id: str = ""
+  """The eval set id."""
+
+  eval_id: str = ""
+  """The eval case id."""
+
+  final_eval_status: EvalStatus
+  """Final eval status for this eval case."""
+
+  eval_metric_results: list[tuple[EvalMetric, EvalMetricResult]] = Field(
+      deprecated=True,
+      description=(
+          "This field is deprecated, use overall_eval_metric_results instead."
+      ),
+  )
+
+  overall_eval_metric_results: list[EvalMetricResult]
+  """Overall result for each metric for the entire eval case."""
+
+  eval_metric_result_per_invocation: list[EvalMetricResultPerInvocation]
+  """Result for each metric on a per invocation basis."""
+
+  session_id: str
+  """Session id of the session generated as result of inferencing/scraping stage of the eval."""
+
+  session_details: Optional[Session] = None
+  """Session generated as result of inferencing/scraping stage of the eval."""
+
+  user_id: Optional[str] = None
+  """User id used during inferencing/scraping stage of the eval."""
+
+
+class EvalSetResult(BaseModel):
+  """Eval set level evaluation results."""
+
+  model_config = ConfigDict(
+      alias_generator=alias_generators.to_camel,
+      populate_by_name=True,
+  )
+  eval_set_result_id: str
+  eval_set_result_name: str
+  eval_set_id: str
+  eval_case_results: list[EvalCaseResult] = Field(default_factory=list)
+  creation_timestamp: float = 0.0

google/adk/evaluation/eval_set.py

@@ -13,7 +13,9 @@
 # limitations under the License.
 
 from typing import Optional
+
 from pydantic import BaseModel
+
 from .eval_case import EvalCase
 
 

google/adk/evaluation/eval_set_results_manager.py

@@ -0,0 +1,47 @@
+# 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 abc import ABC
+from abc import abstractmethod
+
+from .eval_result import EvalCaseResult
+from .eval_result import EvalSetResult
+
+
+class EvalSetResultsManager(ABC):
+  """An interface to manage Eval Set Results."""
+
+  @abstractmethod
+  def save_eval_set_result(
+      self,
+      app_name: str,
+      eval_set_id: str,
+      eval_case_results: list[EvalCaseResult],
+  ) -> None:
+    """Creates and saves a new EvalSetResult given eval_case_results."""
+    raise NotImplementedError()
+
+  @abstractmethod
+  def get_eval_set_result(
+      self, app_name: str, eval_set_result_id: str
+  ) -> EvalSetResult:
+    """Returns an EvalSetResult identified by app_name and eval_set_result_id."""
+    raise NotImplementedError()
+
+  @abstractmethod
+  def list_eval_set_results(self, app_name: str) -> list[str]:
+    """Returns the eval result ids that belong to the given app_name."""
+    raise NotImplementedError()

google/adk/evaluation/eval_sets_manager.py

@@ -12,7 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from abc import ABC, abstractmethod
+from abc import ABC
+from abc import abstractmethod
 
 from .eval_case import EvalCase
 from .eval_set import EvalSet

google/adk/evaluation/evaluator.py

@@ -15,7 +15,9 @@
 from abc import ABC
 from enum import Enum
 from typing import Optional
+
 from pydantic import BaseModel
+
 from .eval_case import Invocation
 
 

google/adk/evaluation/local_eval_set_results_manager.py

@@ -0,0 +1,113 @@
+# 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
+
+import json
+import logging
+import os
+import time
+
+from typing_extensions import override
+
+from .eval_result import EvalCaseResult
+from .eval_result import EvalSetResult
+from .eval_set_results_manager import EvalSetResultsManager
+
+logger = logging.getLogger("google_adk." + __name__)
+
+_ADK_EVAL_HISTORY_DIR = ".adk/eval_history"
+_EVAL_SET_RESULT_FILE_EXTENSION = ".evalset_result.json"
+
+
+def _sanitize_eval_set_result_name(eval_set_result_name: str) -> str:
+  return eval_set_result_name.replace("/", "_")
+
+
+class LocalEvalSetResultsManager(EvalSetResultsManager):
+  """An EvalSetResult manager that stores eval set results locally on disk."""
+
+  def __init__(self, agents_dir: str):
+    self._agents_dir = agents_dir
+
+  @override
+  def save_eval_set_result(
+      self,
+      app_name: str,
+      eval_set_id: str,
+      eval_case_results: list[EvalCaseResult],
+  ) -> None:
+    """Creates and saves a new EvalSetResult given eval_case_results."""
+    timestamp = time.time()
+    eval_set_result_id = app_name + "_" + eval_set_id + "_" + str(timestamp)
+    eval_set_result_name = _sanitize_eval_set_result_name(eval_set_result_id)
+    eval_set_result = EvalSetResult(
+        eval_set_result_id=eval_set_result_id,
+        eval_set_result_name=eval_set_result_name,
+        eval_set_id=eval_set_id,
+        eval_case_results=eval_case_results,
+        creation_timestamp=timestamp,
+    )
+    # Write eval result file, with eval_set_result_name.
+    app_eval_history_dir = self._get_eval_history_dir(app_name)
+    if not os.path.exists(app_eval_history_dir):
+      os.makedirs(app_eval_history_dir)
+    # Convert to json and write to file.
+    eval_set_result_json = eval_set_result.model_dump_json()
+    eval_set_result_file_path = os.path.join(
+        app_eval_history_dir,
+        eval_set_result_name + _EVAL_SET_RESULT_FILE_EXTENSION,
+    )
+    logger.info("Writing eval result to file: %s", eval_set_result_file_path)
+    with open(eval_set_result_file_path, "w") as f:
+      f.write(json.dumps(eval_set_result_json, indent=2))
+
+  @override
+  def get_eval_set_result(
+      self, app_name: str, eval_set_result_id: str
+  ) -> EvalSetResult:
+    """Returns an EvalSetResult identified by app_name and eval_set_result_id."""
+    # Load the eval set result file data.
+    maybe_eval_result_file_path = (
+        os.path.join(
+            self._get_eval_history_dir(app_name),
+            eval_set_result_id,
+        )
+        + _EVAL_SET_RESULT_FILE_EXTENSION
+    )
+    if not os.path.exists(maybe_eval_result_file_path):
+      raise ValueError(
+          f"Eval set result `{eval_set_result_id}` does not exist."
+      )
+    with open(maybe_eval_result_file_path, "r") as file:
+      eval_result_data = json.load(file)
+    return EvalSetResult.model_validate_json(eval_result_data)
+
+  @override
+  def list_eval_set_results(self, app_name: str) -> list[str]:
+    """Returns the eval result ids that belong to the given app_name."""
+    app_eval_history_directory = self._get_eval_history_dir(app_name)
+
+    if not os.path.exists(app_eval_history_directory):
+      return []
+
+    eval_result_files = [
+        file.removesuffix(_EVAL_SET_RESULT_FILE_EXTENSION)
+        for file in os.listdir(app_eval_history_directory)
+        if file.endswith(_EVAL_SET_RESULT_FILE_EXTENSION)
+    ]
+    return eval_result_files
+
+  def _get_eval_history_dir(self, app_name: str) -> str:
+    return os.path.join(self._agents_dir, app_name, _ADK_EVAL_HISTORY_DIR)

google/adk/evaluation/local_eval_sets_manager.py

@@ -182,8 +182,8 @@ def load_eval_set_from_file(
 class LocalEvalSetsManager(EvalSetsManager):
   """An EvalSets manager that stores eval sets locally on disk."""
 
-  def __init__(self, agent_dir: str):
-    self._agent_dir = agent_dir
+  def __init__(self, agents_dir: str):
+    self._agents_dir = agents_dir
 
   @override
   def get_eval_set(self, app_name: str, eval_set_id: str) -> EvalSet:
@@ -216,7 +216,7 @@ class LocalEvalSetsManager(EvalSetsManager):
   @override
   def list_eval_sets(self, app_name: str) -> list[str]:
     """Returns a list of EvalSets that belong to the given app_name."""
-    eval_set_file_path = os.path.join(self._agent_dir, app_name)
+    eval_set_file_path = os.path.join(self._agents_dir, app_name)
     eval_sets = []
     for file in os.listdir(eval_set_file_path):
       if file.endswith(_EVAL_SET_FILE_EXTENSION):
@@ -247,7 +247,7 @@ class LocalEvalSetsManager(EvalSetsManager):
 
   def _get_eval_set_file_path(self, app_name: str, eval_set_id: str) -> str:
     return os.path.join(
-        self._agent_dir,
+        self._agents_dir,
         app_name,
         eval_set_id + _EVAL_SET_FILE_EXTENSION,
     )

google/adk/evaluation/response_evaluator.py

@@ -12,7 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from typing import Any, Optional
+from typing import Any
+from typing import Optional
 
 from deprecated import deprecated
 from google.genai import types as genai_types

google/adk/evaluation/trajectory_evaluator.py

@@ -12,7 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from typing import Any, cast
+from typing import Any
+from typing import cast
 
 from deprecated import deprecated
 from google.genai import types as genai_types
@@ -115,7 +116,7 @@ class TrajectoryEvaluator(Evaluator):
     tool use trajectories. An exact match scores a 1, 0 otherwise. The final
     number is an average of these individual scores.
 
-    Value range: [0, 1], where 0 is means none of the too use entries aligned,
+    Value range: [0, 1], where 0 means none of the tool use entries aligned,
     and 1 would mean all of them aligned. Higher value is good.
 
     Args:

google/adk/examples/base_example_provider.py

@@ -13,6 +13,7 @@
 # limitations under the License.
 
 import abc
+
 from .example import Example
 
 

google/adk/flows/llm_flows/base_llm_flow.py

@@ -25,6 +25,7 @@ from typing import TYPE_CHECKING
 
 from websockets.exceptions import ConnectionClosedOK
 
+from . import functions
 from ...agents.base_agent import BaseAgent
 from ...agents.callback_context import CallbackContext
 from ...agents.invocation_context import InvocationContext
@@ -40,7 +41,6 @@ from ...telemetry import trace_call_llm
 from ...telemetry import trace_send_data
 from ...telemetry import tracer
 from ...tools.tool_context import ToolContext
-from . import functions
 
 if TYPE_CHECKING:
   from ...agents.llm_agent import LlmAgent
@@ -472,14 +472,12 @@ class BaseLlmFlow(ABC):
           yield event
 
   def _get_agent_to_run(
-      self, invocation_context: InvocationContext, transfer_to_agent
+      self, invocation_context: InvocationContext, agent_name: str
   ) -> BaseAgent:
     root_agent = invocation_context.agent.root_agent
-    agent_to_run = root_agent.find_agent(transfer_to_agent)
+    agent_to_run = root_agent.find_agent(agent_name)
     if not agent_to_run:
-      raise ValueError(
-          f'Agent {transfer_to_agent} not found in the agent tree.'
-      )
+      raise ValueError(f'Agent {agent_name} not found in the agent tree.')
     return agent_to_run
 
   async def _call_llm_async(

google/adk/flows/llm_flows/contents.py

@@ -15,7 +15,9 @@
 from __future__ import annotations
 
 import copy
-from typing import AsyncGenerator, Generator, Optional
+from typing import AsyncGenerator
+from typing import Generator
+from typing import Optional
 
 from google.genai import types
 from typing_extensions import override

google/adk/flows/llm_flows/instructions.py

@@ -26,6 +26,7 @@ from typing_extensions import override
 from ...agents.readonly_context import ReadonlyContext
 from ...events.event import Event
 from ...sessions.state import State
+from ...utils import instructions_utils
 from ._base_llm_processor import BaseLlmRequestProcessor
 
 if TYPE_CHECKING:
@@ -60,7 +61,9 @@ class _InstructionsLlmRequestProcessor(BaseLlmRequestProcessor):
       )
       si = raw_si
       if not bypass_state_injection:
-        si = await _populate_values(raw_si, invocation_context)
+        si = await instructions_utils.inject_session_state(
+            raw_si, ReadonlyContext(invocation_context)
+        )
       llm_request.append_instructions([si])
 
     # Appends agent instructions if set.
@@ -70,7 +73,9 @@ class _InstructionsLlmRequestProcessor(BaseLlmRequestProcessor):
       )
       si = raw_si
       if not bypass_state_injection:
-        si = await _populate_values(raw_si, invocation_context)
+        si = await instructions_utils.inject_session_state(
+            raw_si, ReadonlyContext(invocation_context)
+        )
       llm_request.append_instructions([si])
 
     # Maintain async generator behavior
@@ -79,78 +84,3 @@ class _InstructionsLlmRequestProcessor(BaseLlmRequestProcessor):
 
 
 request_processor = _InstructionsLlmRequestProcessor()
-
-
-async def _populate_values(
-    instruction_template: str,
-    context: InvocationContext,
-) -> str:
-  """Populates values in the instruction template, e.g. state, artifact, etc."""
-
-  async def _async_sub(pattern, repl_async_fn, string) -> str:
-    result = []
-    last_end = 0
-    for match in re.finditer(pattern, string):
-      result.append(string[last_end : match.start()])
-      replacement = await repl_async_fn(match)
-      result.append(replacement)
-      last_end = match.end()
-    result.append(string[last_end:])
-    return ''.join(result)
-
-  async def _replace_match(match) -> str:
-    var_name = match.group().lstrip('{').rstrip('}').strip()
-    optional = False
-    if var_name.endswith('?'):
-      optional = True
-      var_name = var_name.removesuffix('?')
-    if var_name.startswith('artifact.'):
-      var_name = var_name.removeprefix('artifact.')
-      if context.artifact_service is None:
-        raise ValueError('Artifact service is not initialized.')
-      artifact = await context.artifact_service.load_artifact(
-          app_name=context.session.app_name,
-          user_id=context.session.user_id,
-          session_id=context.session.id,
-          filename=var_name,
-      )
-      if not var_name:
-        raise KeyError(f'Artifact {var_name} not found.')
-      return str(artifact)
-    else:
-      if not _is_valid_state_name(var_name):
-        return match.group()
-      if var_name in context.session.state:
-        return str(context.session.state[var_name])
-      else:
-        if optional:
-          return ''
-        else:
-          raise KeyError(f'Context variable not found: `{var_name}`.')
-
-  return await _async_sub(r'{+[^{}]*}+', _replace_match, instruction_template)
-
-
-def _is_valid_state_name(var_name):
-  """Checks if the variable name is a valid state name.
-
-  Valid state is either:
-    - Valid identifier
-    - <Valid prefix>:<Valid identifier>
-  All the others will just return as it is.
-
-  Args:
-    var_name: The variable name to check.
-
-  Returns:
-    True if the variable name is a valid state name, False otherwise.
-  """
-  parts = var_name.split(':')
-  if len(parts) == 1:
-    return var_name.isidentifier()
-
-  if len(parts) == 2:
-    prefixes = [State.APP_PREFIX, State.USER_PREFIX, State.TEMP_PREFIX]
-    if (parts[0] + ':') in prefixes:
-      return parts[1].isidentifier()
-  return False

google/adk/flows/llm_flows/single_flow.py

@@ -16,13 +16,13 @@
 
 import logging
 
-from ...auth import auth_preprocessor
 from . import _code_execution
 from . import _nl_planning
 from . import basic
 from . import contents
 from . import identity
 from . import instructions
+from ...auth import auth_preprocessor
 from .base_llm_flow import BaseLlmFlow
 
 logger = logging.getLogger('google_adk.' + __name__)

google/adk/models/base_llm.py

@@ -14,7 +14,8 @@
 from __future__ import annotations
 
 from abc import abstractmethod
-from typing import AsyncGenerator, TYPE_CHECKING
+from typing import AsyncGenerator
+from typing import TYPE_CHECKING
 
 from google.genai import types
 from pydantic import BaseModel

google/adk/models/base_llm_connection.py

@@ -14,7 +14,9 @@
 
 from abc import abstractmethod
 from typing import AsyncGenerator
+
 from google.genai import types
+
 from .llm_response import LlmResponse