docs: Fix docstring and update module public name list for generating API references

To fix google/adk-docs#131

PiperOrigin-RevId: 783080206

Author: seanzhougoogle

src/google/adk/agents/__init__.py

@@ -13,6 +13,7 @@
 # limitations under the License.
 
 from .base_agent import BaseAgent
+from .invocation_context import InvocationContext
 from .live_request_queue import LiveRequest
 from .live_request_queue import LiveRequestQueue
 from .llm_agent import Agent
@@ -29,4 +30,8 @@
     'LoopAgent',
     'ParallelAgent',
     'SequentialAgent',
+    'InvocationContext',
+    'LiveRequest',
+    'LiveRequestQueue',
+    'RunConfig',
 ]

src/google/adk/agents/invocation_context.py

@@ -149,7 +149,7 @@ class InvocationContext(BaseModel):
   """The running streaming tools of this invocation."""
 
   transcription_cache: Optional[list[TranscriptionEntry]] = None
-  """Caches necessary, data audio or contents, that are needed by transcription."""
+  """Caches necessary data, audio or contents, that are needed by transcription."""
 
   run_config: Optional[RunConfig] = None
   """Configurations for live agents under this invocation."""

src/google/adk/agents/llm_agent.py

@@ -168,9 +168,9 @@ class LlmAgent(BaseAgent):
   """Controls content inclusion in model requests.
 
   Options:
-      default: Model receives relevant conversation history
-      none: Model receives no prior history, operates solely on current
-            instruction and input
+    default: Model receives relevant conversation history
+    none: Model receives no prior history, operates solely on current
+    instruction and input
   """
 
   # Controlled input/output configurations - Start
@@ -179,8 +179,9 @@ class LlmAgent(BaseAgent):
   output_schema: Optional[type[BaseModel]] = None
   """The output schema when agent replies.
 
-  NOTE: when this is set, agent can ONLY reply and CANNOT use any tools, such as
-  function tools, RAGs, agent transfer, etc.
+  NOTE:
+    When this is set, agent can ONLY reply and CANNOT use any tools, such as
+    function tools, RAGs, agent transfer, etc.
   """
   output_key: Optional[str] = None
   """The key in session state to store the output of the agent.
@@ -195,9 +196,9 @@ class LlmAgent(BaseAgent):
   planner: Optional[BasePlanner] = None
   """Instructs the agent to make a plan and execute it step by step.
 
-  NOTE: to use model's built-in thinking features, set the `thinking_config`
-  field in `google.adk.planners.built_in_planner`.
-
+  NOTE:
+    To use model's built-in thinking features, set the `thinking_config`
+    field in `google.adk.planners.built_in_planner`.
   """
 
   code_executor: Optional[BaseCodeExecutor] = None
@@ -206,7 +207,8 @@ class LlmAgent(BaseAgent):
 
   Check out available code executions in `google.adk.code_executor` package.
 
-  NOTE: to use model's built-in code executor, use the `BuiltInCodeExecutor`.
+  NOTE:
+    To use model's built-in code executor, use the `BuiltInCodeExecutor`.
   """
   # Advance features - End
 

src/google/adk/code_executors/base_code_executor.py

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import abc
 from typing import List
 
@@ -42,42 +44,35 @@ class BaseCodeExecutor(BaseModel):
   """
 
   optimize_data_file: bool = False
-  """
-  If true, extract and process data files from the model request
+  """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].
 
+  Supported data file MimeTypes are [text/csv].
   Default to False.
   """
 
   stateful: bool = False
-  """
-  Whether the code executor is stateful. Default to 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.
-  """
+  """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:
+  """The list of the enclosing delimiters to identify the code blocks.
 
-  ```python
-  print("hello")
-  ```
+  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.
-  """
+  """The delimiters to format the code execution result."""
 
   @abc.abstractmethod
   def execute_code(

src/google/adk/runners.py

@@ -122,8 +122,9 @@ def run(
   ) -> Generator[Event, None, None]:
     """Runs the agent.
 
-    NOTE: This sync interface is only for local testing and convenience purpose.
-    Consider using `run_async` for production usage.
+    NOTE:
+      This sync interface is only for local testing and convenience purpose.
+      Consider using `run_async` for production usage.
 
     Args:
       user_id: The user ID of the session.
@@ -350,7 +351,7 @@ async def run_live(
         This feature is **experimental** and its API or behavior may change
         in future releases.
 
-    .. note::
+    .. NOTE::
         Either `session` or both `user_id` and `session_id` must be provided.
     """
     if session is None and (user_id is None or session_id is None):
@@ -433,9 +434,10 @@ def _find_agent_to_run(
     """Finds the agent to run to continue the session.
 
     A qualified agent must be either of:
+
     - The agent that returned a function call and the last user message is a
       function response to this function call.
-    - The root agent;
+    - The root agent.
     - An LlmAgent who replied last and is capable to transfer to any other agent
       in the agent hierarchy.
 

src/google/adk/tools/apihub_tool/apihub_toolset.py

@@ -35,27 +35,25 @@
 class APIHubToolset(BaseToolset):
   """APIHubTool generates tools from a given API Hub resource.
 
-  Examples:
+  Examples::
 
-  ```
-  apihub_toolset = APIHubToolset(
-      apihub_resource_name="projects/test-project/locations/us-central1/apis/test-api",
-      service_account_json="...",
-      tool_filter=lambda tool, ctx=None: tool.name in ('my_tool',
-      'my_other_tool')
-  )
-
-  # Get all available tools
-  agent = LlmAgent(tools=apihub_toolset)
+    apihub_toolset = APIHubToolset(
+        apihub_resource_name="projects/test-project/locations/us-central1/apis/test-api",
+        service_account_json="...",
+        tool_filter=lambda tool, ctx=None: tool.name in ('my_tool',
+        'my_other_tool')
+    )
 
-  ```
+    # Get all available tools
+    agent = LlmAgent(tools=apihub_toolset)
 
   **apihub_resource_name** is the resource name from API Hub. It must include
-    API name, and can optionally include API version and spec name.
-    - If apihub_resource_name includes a spec resource name, the content of that
-      spec will be used for generating the tools.
-    - If apihub_resource_name includes only an api or a version name, the
-      first spec of the first version of that API will be used.
+  API name, and can optionally include API version and spec name.
+
+  - If apihub_resource_name includes a spec resource name, the content of that
+    spec will be used for generating the tools.
+  - If apihub_resource_name includes only an api or a version name, the
+    first spec of the first version of that API will be used.
   """
 
   def __init__(
@@ -78,44 +76,45 @@ def __init__(
   ):
     """Initializes the APIHubTool with the given parameters.
 
-    Examples:
-    ```
-    apihub_toolset = APIHubToolset(
-        apihub_resource_name="projects/test-project/locations/us-central1/apis/test-api",
-        service_account_json="...",
-    )
+    Examples::
 
-    # Get all available tools
-    agent = LlmAgent(tools=[apihub_toolset])
+      apihub_toolset = APIHubToolset(
+          apihub_resource_name="projects/test-project/locations/us-central1/apis/test-api",
+          service_account_json="...",
+      )
 
-    apihub_toolset = APIHubToolset(
-        apihub_resource_name="projects/test-project/locations/us-central1/apis/test-api",
-        service_account_json="...",
-        tool_filter = ['my_tool']
-    )
-    # Get a specific tool
-    agent = LlmAgent(tools=[
-        ...,
-        apihub_toolset,
-    ])
-    ```
+      # Get all available tools
+      agent = LlmAgent(tools=[apihub_toolset])
+
+      apihub_toolset = APIHubToolset(
+          apihub_resource_name="projects/test-project/locations/us-central1/apis/test-api",
+          service_account_json="...",
+          tool_filter = ['my_tool']
+      )
+      # Get a specific tool
+      agent = LlmAgent(tools=[
+          ...,
+          apihub_toolset,
+      ])
 
     **apihub_resource_name** is the resource name from API Hub. It must include
     API name, and can optionally include API version and spec name.
+
     - If apihub_resource_name includes a spec resource name, the content of that
       spec will be used for generating the tools.
     - If apihub_resource_name includes only an api or a version name, the
       first spec of the first version of that API will be used.
 
     Example:
+
     * projects/xxx/locations/us-central1/apis/apiname/...
     * https://console.cloud.google.com/apigee/api-hub/apis/apiname?project=xxx
 
     Args:
         apihub_resource_name: The resource name of the API in API Hub.
-          Example: `projects/test-project/locations/us-central1/apis/test-api`.
-        access_token: Google Access token. Generate with gcloud cli `gcloud auth
-          auth print-access-token`. Used for fetching API Specs from API Hub.
+          Example: ``projects/test-project/locations/us-central1/apis/test-api``.
+        access_token: Google Access token. Generate with gcloud cli
+          ``gcloud auth auth print-access-token``. Used for fetching API Specs from API Hub.
         service_account_json: The service account config as a json string.
           Required if not using default service credential. It is used for
           creating the API Hub client and fetching the API Specs from API Hub.

src/google/adk/tools/application_integration_tool/application_integration_toolset.py

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import logging
 from typing import List
 from typing import Optional
@@ -42,43 +44,39 @@
 # TODO(cheliu): Apply a common toolset interface
 class ApplicationIntegrationToolset(BaseToolset):
   """ApplicationIntegrationToolset generates tools from a given Application
-
   Integration or Integration Connector resource.
-  Example Usage:
-  ```
-  # Get all available tools for an integration with api trigger
-  application_integration_toolset = ApplicationIntegrationToolset(
 
-      project="test-project",
-      location="us-central1"
-      integration="test-integration",
-      triggers=["api_trigger/test_trigger"],
-      service_account_credentials={...},
-  )
+  Example Usage::
 
-  # Get all available tools for a connection using entity operations and
-  # actions
-  # Note: Find the list of supported entity operations and actions for a
-  connection
-  # using integration connector apis:
-  #
-  https://cloud.google.com/integration-connectors/docs/reference/rest/v1/projects.locations.connections.connectionSchemaMetadata
-  application_integration_toolset = ApplicationIntegrationToolset(
-      project="test-project",
-      location="us-central1"
-      connection="test-connection",
-      entity_operations=["EntityId1": ["LIST","CREATE"], "EntityId2": []],
-      #empty list for actions means all operations on the entity are supported
-      actions=["action1"],
-      service_account_credentials={...},
-  )
+    # Get all available tools for an integration with api trigger
+    application_integration_toolset = ApplicationIntegrationToolset(
+        project="test-project",
+        location="us-central1"
+        integration="test-integration",
+        triggers=["api_trigger/test_trigger"],
+        service_account_credentials={...},
+    )
+
+    # Get all available tools for a connection using entity operations and
+    # actions
+    # Note: Find the list of supported entity operations and actions for a
+    # connection using integration connector apis:
+    # https://cloud.google.com/integration-connectors/docs/reference/rest/v1/projects.locations.connections.connectionSchemaMetadata
+    application_integration_toolset = ApplicationIntegrationToolset(
+        project="test-project",
+        location="us-central1"
+        connection="test-connection",
+        entity_operations=["EntityId1": ["LIST","CREATE"], "EntityId2": []],
+        #empty list for actions means all operations on the entity are supported
+        actions=["action1"],
+        service_account_credentials={...},
+    )
 
-  # Feed the toolset to agent
-  agent = LlmAgent(tools=[
-      ...,
-      application_integration_toolset,
-  ])
-  ```
+    # Feed the toolset to agent
+    agent = LlmAgent(tools=[
+        ...,
+        application_integration_toolset,
+    ])
   """
 
   def __init__(
@@ -122,11 +120,11 @@ def __init__(
 
     Raises:
         ValueError: If none of the following conditions are met:
-            - `integration` is provided.
-            - `connection` is provided and at least one of `entity_operations`
-              or `actions` is provided.
+          - ``integration`` is provided.
+          - ``connection`` is provided and at least one of ``entity_operations``
+            or ``actions`` is provided.
         Exception: If there is an error during the initialization of the
-            integration or connection client.
+          integration or connection client.
     """
     super().__init__(tool_filter=tool_filter)
     self.project = project

src/google/adk/tools/application_integration_tool/integration_connector_tool.py

@@ -45,13 +45,12 @@ class IntegrationConnectorTool(BaseTool):
   * Generates request params and body
   * Attaches auth credentials to API call.
 
-  Example:
-  ```
+  Example::
+
     # Each API operation in the spec will be turned into its own tool
     # Name of the tool is the operationId of that operation, in snake case
     operations = OperationGenerator().parse(openapi_spec_dict)
     tool = [RestApiTool.from_parsed_operation(o) for o in operations]
-  ```
   """
 
   EXCLUDE_FIELDS = [