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

google/adk/models/llm_request.py

@@ -0,0 +1,98 @@
+# 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 google.genai import types
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+
+from ..tools.base_tool import BaseTool
+
+
+class LlmRequest(BaseModel):
+  """LLM request class that allows passing in tools, output schema and system
+
+  instructions to the model.
+
+  Attributes:
+    model: The model name.
+    contents: The contents to send to the model.
+    config: Additional config for the generate content request.
+    tools_dict: The tools dictionary.
+  """
+
+  model_config = ConfigDict(arbitrary_types_allowed=True)
+  """The model config."""
+
+  model: Optional[str] = None
+  """The model name."""
+
+  contents: list[types.Content] = Field(default_factory=list)
+  """The contents to send to the model."""
+
+  config: Optional[types.GenerateContentConfig] = None
+  live_connect_config: types.LiveConnectConfig = types.LiveConnectConfig()
+  """Additional config for the generate content request.
+
+  tools in generate_content_config should not be set.
+  """
+  tools_dict: dict[str, BaseTool] = Field(default_factory=dict, exclude=True)
+  """The tools dictionary."""
+
+  def append_instructions(self, instructions: list[str]) -> None:
+    """Appends instructions to the system instruction.
+
+    Args:
+      instructions: The instructions to append.
+    """
+
+    if self.config.system_instruction:
+      self.config.system_instruction += '\n\n' + '\n\n'.join(instructions)
+    else:
+      self.config.system_instruction = '\n\n'.join(instructions)
+
+  def append_tools(self, tools: list[BaseTool]) -> None:
+    """Appends tools to the request.
+
+    Args:
+      tools: The tools to append.
+    """
+
+    if not tools:
+      return
+    declarations = []
+    for tool in tools:
+      if isinstance(tool, BaseTool):
+        declaration = tool._get_declaration()
+      else:
+        declaration = tool.get_declaration()
+      if declaration:
+        declarations.append(declaration)
+        self.tools_dict[tool.name] = tool
+    if declarations:
+      self.config.tools.append(types.Tool(function_declarations=declarations))
+
+  def set_output_schema(self, base_model: type[BaseModel]) -> None:
+    """Sets the output schema for the request.
+
+    Args:
+      base_model: The pydantic base model to set the output schema to.
+    """
+
+    self.config.response_schema = base_model
+    self.config.response_mime_type = 'application/json'

google/adk/models/llm_response.py

@@ -0,0 +1,111 @@
+# 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 google.genai import types
+from pydantic import BaseModel
+from pydantic import ConfigDict
+
+
+class LlmResponse(BaseModel):
+  """LLM response class that provides the first candidate response from the
+
+  model if available. Otherwise, returns error code and message.
+
+  Attributes:
+    content: The content of the response.
+    grounding_metadata: The grounding metadata of the response.
+    partial: Indicates whether the text content is part of a unfinished text
+      stream. Only used for streaming mode and when the content is plain text.
+    turn_complete: Indicates whether the response from the model is complete.
+      Only used for streaming mode.
+    error_code: Error code if the response is an error. Code varies by model.
+    error_message: Error message if the response is an error.
+    interrupted: Flag indicating that LLM was interrupted when generating the
+      content. Usually it's due to user interruption during a bidi streaming.
+  """
+
+  model_config = ConfigDict(extra='forbid')
+  """The model config."""
+
+  content: Optional[types.Content] = None
+  """The content of the response."""
+
+  grounding_metadata: Optional[types.GroundingMetadata] = None
+  """The grounding metadata of the response."""
+
+  partial: Optional[bool] = None
+  """Indicates whether the text content is part of a unfinished text stream.
+
+  Only used for streaming mode and when the content is plain text.
+  """
+
+  turn_complete: Optional[bool] = None
+  """Indicates whether the response from the model is complete.
+
+  Only used for streaming mode.
+  """
+
+  error_code: Optional[str] = None
+  """Error code if the response is an error. Code varies by model."""
+
+  error_message: Optional[str] = None
+  """Error message if the response is an error."""
+
+  interrupted: Optional[bool] = None
+  """Flag indicating that LLM was interrupted when generating the content.
+  Usually it's due to user interruption during a bidi streaming.
+  """
+
+  @staticmethod
+  def create(
+      generate_content_response: types.GenerateContentResponse,
+  ) -> 'LlmResponse':
+    """Creates an LlmResponse from a GenerateContentResponse.
+
+    Args:
+      generate_content_response: The GenerateContentResponse to create the
+        LlmResponse from.
+
+    Returns:
+      The LlmResponse.
+    """
+
+    if generate_content_response.candidates:
+      candidate = generate_content_response.candidates[0]
+      if candidate.content and candidate.content.parts:
+        return LlmResponse(
+            content=candidate.content,
+            grounding_metadata=candidate.grounding_metadata,
+        )
+      else:
+        return LlmResponse(
+            error_code=candidate.finish_reason,
+            error_message=candidate.finish_message,
+        )
+    else:
+      if generate_content_response.prompt_feedback:
+        prompt_feedback = generate_content_response.prompt_feedback
+        return LlmResponse(
+            error_code=prompt_feedback.block_reason,
+            error_message=prompt_feedback.block_reason_message,
+        )
+      else:
+        return LlmResponse(
+            error_code='UNKNOWN_ERROR',
+            error_message='Unknown error.',
+        )

google/adk/models/registry.py

@@ -0,0 +1,102 @@
+# 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.
+
+"""The registry class for model."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+import logging
+import re
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+  from .base_llm import BaseLlm
+
+logger = logging.getLogger(__name__)
+
+
+_llm_registry_dict: dict[str, type[BaseLlm]] = {}
+"""Registry for LLMs.
+
+Key is the regex that matches the model name.
+Value is the class that implements the model.
+"""
+
+
+class LLMRegistry:
+  """Registry for LLMs."""
+
+  @staticmethod
+  def new_llm(model: str) -> BaseLlm:
+    """Creates a new LLM instance.
+
+    Args:
+        model: The model name.
+
+    Returns:
+        The LLM instance.
+    """
+
+    return LLMRegistry.resolve(model)(model=model)
+
+  @staticmethod
+  def _register(model_name_regex: str, llm_cls: type[BaseLlm]):
+    """Registers a new LLM class.
+
+    Args:
+        model_name_regex: The regex that matches the model name.
+        llm_cls: The class that implements the model.
+    """
+
+    if model_name_regex in _llm_registry_dict:
+      logger.info(
+          'Updating LLM class for %s from %s to %s',
+          model_name_regex,
+          _llm_registry_dict[model_name_regex],
+          llm_cls,
+      )
+
+    _llm_registry_dict[model_name_regex] = llm_cls
+
+  @staticmethod
+  def register(llm_cls: type[BaseLlm]):
+    """Registers a new LLM class.
+
+    Args:
+        llm_cls: The class that implements the model.
+    """
+
+    for regex in llm_cls.supported_models():
+      LLMRegistry._register(regex, llm_cls)
+
+  @staticmethod
+  @lru_cache(maxsize=32)
+  def resolve(model: str) -> type[BaseLlm]:
+    """Resolves the model to a BaseLlm subclass.
+
+    Args:
+        model: The model name.
+
+    Returns:
+        The BaseLlm subclass.
+    Raises:
+        ValueError: If the model is not found.
+    """
+
+    for regex, llm_class in _llm_registry_dict.items():
+      if re.compile(regex).fullmatch(model):
+        return llm_class
+
+    raise ValueError(f'Model {model} not found.')

google/adk/planners/__init__.py

@@ -0,0 +1,23 @@
+# 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_planner import BasePlanner
+from .built_in_planner import BuiltInPlanner
+from .plan_re_act_planner import PlanReActPlanner
+
+__all__ = [
+    'BasePlanner',
+    'BuiltInPlanner',
+    'PlanReActPlanner',
+]

google/adk/planners/base_planner.py

@@ -0,0 +1,66 @@
+# 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 abc import ABC
+from typing import List
+from typing import Optional
+
+from google.genai import types
+
+from ..agents.callback_context import CallbackContext
+from ..agents.readonly_context import ReadonlyContext
+from ..models.llm_request import LlmRequest
+
+
+class BasePlanner(ABC):
+  """Abstract base class for all planners.
+
+  The planner allows the agent to generate plans for the queries to guide its
+  action.
+  """
+
+  @abc.abstractmethod
+  def build_planning_instruction(
+      self,
+      readonly_context: ReadonlyContext,
+      llm_request: LlmRequest,
+  ) -> Optional[str]:
+    """Builds the system instruction to be appended to the LLM request for planning.
+
+    Args:
+        readonly_context: The readonly context of the invocation.
+        llm_request: The LLM request. Readonly.
+
+    Returns:
+        The planning system instruction, or None if no instruction is needed.
+    """
+    pass
+
+  @abc.abstractmethod
+  def process_planning_response(
+      self,
+      callback_context: CallbackContext,
+      response_parts: List[types.Part],
+  ) -> Optional[List[types.Part]]:
+    """Processes the LLM response for planning.
+
+    Args:
+        callback_context: The callback context of the invocation.
+        response_parts: The LLM response parts. Readonly.
+
+    Returns:
+        The processed response parts, or None if no processing is needed.
+    """
+    pass

google/adk/planners/built_in_planner.py

@@ -0,0 +1,75 @@
+# 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 List
+from typing import Optional
+
+from google.genai import types
+from typing_extensions import override
+
+from ..agents.callback_context import CallbackContext
+from ..agents.readonly_context import ReadonlyContext
+from ..models.llm_request import LlmRequest
+from .base_planner import BasePlanner
+
+
+class BuiltInPlanner(BasePlanner):
+  """The built-in planner that uses model's built-in thinking features.
+
+  Attributes:
+      thinking_config: Config for model built-in thinking features. An error
+        will be returned if this field is set for models that don't support
+        thinking.
+  """
+
+  thinking_config: types.ThinkingConfig
+  """
+  Config for model built-in thinking features. An error will be returned if this
+  field is set for models that don't support thinking.
+  """
+
+  def __init__(self, *, thinking_config: types.ThinkingConfig):
+    """Initializes the built-in planner.
+
+    Args:
+      thinking_config: Config for model built-in thinking features. An error
+        will be returned if this field is set for models that don't support
+        thinking.
+    """
+    self.thinking_config = thinking_config
+
+  def apply_thinking_config(self, llm_request: LlmRequest) -> None:
+    """Applies the thinking config to the LLM request.
+
+    Args:
+      llm_request: The LLM request to apply the thinking config to.
+    """
+    if self.thinking_config:
+      llm_request.config.thinking_config = self.thinking_config
+
+  @override
+  def build_planning_instruction(
+      self,
+      readonly_context: ReadonlyContext,
+      llm_request: LlmRequest,
+  ) -> Optional[str]:
+    return
+
+  @override
+  def process_planning_response(
+      self,
+      callback_context: CallbackContext,
+      response_parts: List[types.Part],
+  ) -> Optional[List[types.Part]]:
+    return

google/adk/planners/plan_re_act_planner.py

@@ -0,0 +1,208 @@
+# 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 List
+from typing import Optional
+
+from google.genai import types
+from typing_extensions import override
+
+from ..agents.callback_context import CallbackContext
+from ..agents.readonly_context import ReadonlyContext
+from ..models.llm_request import LlmRequest
+from .base_planner import BasePlanner
+
+PLANNING_TAG = '/*PLANNING*/'
+REPLANNING_TAG = '/*REPLANNING*/'
+REASONING_TAG = '/*REASONING*/'
+ACTION_TAG = '/*ACTION*/'
+FINAL_ANSWER_TAG = '/*FINAL_ANSWER*/'
+
+
+class PlanReActPlanner(BasePlanner):
+  """Plan-Re-Act planner that constraints the LLM response to generate a plan before any action/observation.
+
+  Note: this planner does not require the model to support buil-in thinking
+  features or setting the thinking config.
+  """
+
+  @override
+  def build_planning_instruction(
+      self,
+      readonly_context: ReadonlyContext,
+      llm_request: LlmRequest,
+  ) -> str:
+    return self._build_nl_planner_instruction()
+
+  @override
+  def process_planning_response(
+      self,
+      callback_context: CallbackContext,
+      response_parts: List[types.Part],
+  ) -> Optional[List[types.Part]]:
+    if not response_parts:
+      return None
+
+    preserved_parts = []
+    first_fc_part_index = -1
+    for i in range(len(response_parts)):
+      # Stop at the first (group of) function calls.
+      if response_parts[i].function_call:
+        # Ignore and filter out function calls with empty names.
+        if not response_parts[i].function_call.name:
+          continue
+        preserved_parts.append(response_parts[i])
+        first_fc_part_index = i
+        break
+
+      # Split the response into reasoning and final answer parts.
+      self._handle_non_function_call_parts(response_parts[i], preserved_parts)
+
+    if first_fc_part_index > 0:
+      j = first_fc_part_index + 1
+      while j < len(response_parts):
+        if response_parts[j].function_call:
+          preserved_parts.append(response_parts[j])
+          j += 1
+        else:
+          break
+
+    return preserved_parts
+
+  def _split_by_last_pattern(self, text, separator):
+    """Splits the text by the last occurrence of the separator.
+
+    Args:
+      text: The text to split.
+      separator: The separator to split on.
+
+    Returns:
+      A tuple containing the text before the last separator and the text after
+      the last separator.
+    """
+    index = text.rfind(separator)
+    if index == -1:
+      return text, ''
+    return text[: index + len(separator)], text[index + len(separator) :]
+
+  def _handle_non_function_call_parts(
+      self, response_part: types.Part, preserved_parts: list[types.Part]
+  ):
+    """Handles non-function-call parts of the response.
+
+    Args:
+      response_part: The response part to handle.
+      preserved_parts: The mutable list of parts to store the processed parts
+        in.
+    """
+    if response_part.text and FINAL_ANSWER_TAG in response_part.text:
+      reasoning_text, final_answer_text = self._split_by_last_pattern(
+          response_part.text, FINAL_ANSWER_TAG
+      )
+      if reasoning_text:
+        reasoning_part = types.Part(text=reasoning_text)
+        self._mark_as_thought(reasoning_part)
+        preserved_parts.append(reasoning_part)
+      if final_answer_text:
+        preserved_parts.append(
+            types.Part(
+                text=final_answer_text,
+            )
+        )
+    else:
+      response_text = response_part.text or ''
+      # If the part is a text part with a planning/reasoning/action tag,
+      # label it as reasoning.
+      if response_text and (
+          any(
+              response_text.startswith(tag)
+              for tag in [
+                  PLANNING_TAG,
+                  REASONING_TAG,
+                  ACTION_TAG,
+                  REPLANNING_TAG,
+              ]
+          )
+      ):
+        self._mark_as_thought(response_part)
+      preserved_parts.append(response_part)
+
+  def _mark_as_thought(self, response_part: types.Part):
+    """Marks the response part as thought.
+
+    Args:
+      response_part: The mutable response part to mark as thought.
+    """
+    if response_part.text:
+      response_part.thought = True
+    return
+
+  def _build_nl_planner_instruction(self) -> str:
+    """Builds the NL planner instruction for the Plan-Re-Act planner.
+
+    Returns:
+      NL planner system instruction.
+    """
+
+    high_level_preamble = f"""
+When answering the question, try to leverage the available tools to gather the information instead of your memorized knowledge.
+
+Follow this process when answering the question: (1) first come up with a plan in natural language text format; (2) Then use tools to execute the plan and provide reasoning between tool code snippets to make a summary of current state and next step. Tool code snippets and reasoning should be interleaved with each other. (3) In the end, return one final answer.
+
+Follow this format when answering the question: (1) The planning part should be under {PLANNING_TAG}. (2) The tool code snippets should be under {ACTION_TAG}, and the reasoning parts should be under {REASONING_TAG}. (3) The final answer part should be under {FINAL_ANSWER_TAG}.
+"""
+
+    planning_preamble = f"""
+Below are the requirements for the planning:
+The plan is made to answer the user query if following the plan. The plan is coherent and covers all aspects of information from user query, and only involves the tools that are accessible by the agent. The plan contains the decomposed steps as a numbered list where each step should use one or multiple available tools. By reading the plan, you can intuitively know which tools to trigger or what actions to take.
+If the initial plan cannot be successfully executed, you should learn from previous execution results and revise your plan. The revised plan should be be under {REPLANNING_TAG}. Then use tools to follow the new plan.
+"""
+
+    reasoning_preamble = """
+Below are the requirements for the reasoning:
+The reasoning makes a summary of the current trajectory based on the user query and tool outputs. Based on the tool outputs and plan, the reasoning also comes up with instructions to the next steps, making the trajectory closer to the final answer.
+"""
+
+    final_answer_preamble = """
+Below are the requirements for the final answer:
+The final answer should be precise and follow query formatting requirements. Some queries may not be answerable with the available tools and information. In those cases, inform the user why you cannot process their query and ask for more information.
+"""
+
+    # Only contains the requirements for custom tool/libraries.
+    tool_code_without_python_libraries_preamble = """
+Below are the requirements for the tool code:
+
+**Custom Tools:** The available tools are described in the context and can be directly used.
+- Code must be valid self-contained Python snippets with no imports and no references to tools or Python libraries that are not in the context.
+- You cannot use any parameters or fields that are not explicitly defined in the APIs in the context.
+- The code snippets should be readable, efficient, and directly relevant to the user query and reasoning steps.
+- When using the tools, you should use the library name together with the function name, e.g., vertex_search.search().
+- If Python libraries are not provided in the context, NEVER write your own code other than the function calls using the provided tools.
+"""
+
+    user_input_preamble = """
+VERY IMPORTANT instruction that you MUST follow in addition to the above instructions:
+
+You should ask for clarification if you need more information to answer the question.
+You should prefer using the information available in the context instead of repeated tool use.
+"""
+
+    return '\n\n'.join([
+        high_level_preamble,
+        planning_preamble,
+        reasoning_preamble,
+        final_answer_preamble,
+        tool_code_without_python_libraries_preamble,
+        user_input_preamble,
+    ])