google-cloud-agentplatform 1.165.1.dev0__py3-none-any.whl

agentplatform/_genai/_bigquery_utils.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 google.cloud import bigquery
+from google.genai._api_client import BaseApiClient
+import pandas as pd
+
+
+logger = logging.getLogger(__name__)
+
+
+class BigQueryUtils:
+    """Handles BigQuery operations."""
+
+    def __init__(self, api_client: BaseApiClient):
+        self.api_client = api_client
+        self.bigquery_client = bigquery.Client(
+            project=self.api_client.project,
+            credentials=self.api_client._credentials,
+        )
+
+    def load_bigquery_to_dataframe(self, table_uri: str) -> "pd.DataFrame":
+        """Loads data from a BigQuery table into a DataFrame."""
+        table = self.bigquery_client.get_table(table_uri)
+        return self.bigquery_client.list_rows(table).to_dataframe()
+
+    def upload_dataframe_to_bigquery(
+        self, df: "pd.DataFrame", bq_table_uri: str
+    ) -> None:
+        """Uploads a Pandas DataFrame to a BigQuery table."""
+        job = self.bigquery_client.load_table_from_dataframe(df, bq_table_uri)
+        job.result()
+        logger.info(
+            f"DataFrame successfully uploaded to BigQuery table: {bq_table_uri}"
+        )

agentplatform/_genai/_datasets_utils.py

@@ -0,0 +1,344 @@
+# 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 multimodal dataset."""
+
+import asyncio
+import datetime
+from typing import Any, Type, TypeVar
+import uuid
+
+import google.auth.credentials
+from agentplatform._genai.types import common
+from google.genai import _common
+
+
+METADATA_SCHEMA_URI = (
+    "gs://google-cloud-aiplatform/schema/dataset/metadata/multimodal_1.0.0.yaml"
+)
+_BQ_MULTIREGIONS = {"us", "eu"}
+_DEFAULT_BQ_DATASET_PREFIX = "vertex_datasets"
+_DEFAULT_BQ_TABLE_PREFIX = "multimodal_dataset"
+
+T = TypeVar("T", bound=_common.BaseModel)
+
+
+def create_from_response(
+    model_type: Type[T],
+    response: dict[str, Any],
+    config: Any | None = None,
+) -> T:
+    """Creates a model from a response."""
+    kwargs = (
+        {
+            "config": {
+                "response_schema": getattr(config, "response_schema", None),
+                "response_json_schema": getattr(config, "response_json_schema", None),
+                "include_all_fields": getattr(config, "include_all_fields", None),
+            }
+        }
+        if config
+        else {}
+    )
+    return model_type._from_response(response=response, kwargs=kwargs)
+
+
+def validate_multimodal_dataset_bigquery_uri(
+    multimodal_dataset: common.MultimodalDataset,
+) -> None:
+    """Validates that a multimodal dataset has a bigquery uri or raises ValueError."""
+    if (
+        not hasattr(multimodal_dataset, "metadata")
+        or multimodal_dataset.metadata is None
+    ):
+        raise ValueError("Multimodal dataset metadata is required.")
+    if (
+        not hasattr(multimodal_dataset.metadata, "input_config")
+        or multimodal_dataset.metadata.input_config is None
+    ):
+        raise ValueError("Multimodal dataset input config is required.")
+    if (
+        not hasattr(multimodal_dataset.metadata.input_config, "bigquery_source")
+        or multimodal_dataset.metadata.input_config.bigquery_source is None
+    ):
+        raise ValueError("Multimodal dataset input config bigquery source is required.")
+    if (
+        not hasattr(multimodal_dataset.metadata.input_config.bigquery_source, "uri")
+        or multimodal_dataset.metadata.input_config.bigquery_source.uri is None
+    ):
+        raise ValueError(
+            "Multimodal dataset input config bigquery source uri is required."
+        )
+    if not str(multimodal_dataset.metadata.input_config.bigquery_source.uri).startswith(
+        "bq://"
+    ):
+        raise ValueError(
+            "Multimodal dataset bigquery source uri must start with 'bq://'."
+        )
+
+
+def _try_import_bigframes() -> Any:
+    """Tries to import `bigframes`."""
+    try:
+        import bigframes
+        import bigframes.pandas
+        import bigframes.bigquery
+
+        return bigframes
+    except ImportError as exc:
+        raise ImportError(
+            "`bigframes` is not installed. Please call 'pip install bigframes'."
+        ) from exc
+
+
+def _try_import_bigquery() -> Any:
+    """Tries to import `bigquery`."""
+    try:
+        from google.cloud import bigquery
+
+        return bigquery
+    except ImportError as exc:
+        raise ImportError(
+            "`bigquery` is not installed. Please call 'pip install"
+            " google-cloud-bigquery'."
+        ) from exc
+
+
+def _bq_dataset_location_allowed(
+    vertex_location: str, bq_dataset_location: str
+) -> bool:
+    if bq_dataset_location == vertex_location:
+        return True
+    if bq_dataset_location in _BQ_MULTIREGIONS:
+        return vertex_location.startswith(bq_dataset_location)
+    return False
+
+
+def _normalize_and_validate_table_id(
+    *,
+    table_id: str,
+    project: str,
+    location: str,
+    credentials: google.auth.credentials.Credentials,
+) -> str:
+    bigquery = _try_import_bigquery()
+
+    table_ref = bigquery.TableReference.from_string(table_id, default_project=project)
+    if table_ref.project != project:
+        raise ValueError(
+            "The BigQuery table "
+            f"`{table_ref.project}.{table_ref.dataset_id}.{table_ref.table_id}`"
+            " must be in the same project as the multimodal dataset."
+            f" The multimodal dataset is in `{project}`, but the BigQuery table"
+            f" is in `{table_ref.project}`."
+        )
+
+    dataset_ref = bigquery.DatasetReference(
+        project=table_ref.project, dataset_id=table_ref.dataset_id
+    )
+    client = bigquery.Client(project=project, credentials=credentials)
+    bq_dataset = client.get_dataset(dataset_ref=dataset_ref)
+    if not _bq_dataset_location_allowed(location, bq_dataset.location):
+        raise ValueError(
+            "The BigQuery dataset"
+            f" `{dataset_ref.project}.{dataset_ref.dataset_id}` must be in the"
+            " same location as the multimodal dataset. The multimodal dataset"
+            f" is in `{location}`, but the BigQuery dataset is in"
+            f" `{bq_dataset.location}`."
+        )
+    return f"{table_ref.project}.{table_ref.dataset_id}.{table_ref.table_id}"
+
+
+async def _normalize_and_validate_table_id_async(
+    *,
+    table_id: str,
+    project: str,
+    location: str,
+    credentials: google.auth.credentials.Credentials,
+) -> str:
+    bigquery = _try_import_bigquery()
+
+    table_ref = bigquery.TableReference.from_string(table_id, default_project=project)
+    if table_ref.project != project:
+        raise ValueError(
+            "The BigQuery table "
+            f"`{table_ref.project}.{table_ref.dataset_id}.{table_ref.table_id}`"
+            " must be in the same project as the multimodal dataset."
+            f" The multimodal dataset is in `{project}`, but the BigQuery table"
+            f" is in `{table_ref.project}`."
+        )
+
+    dataset_ref = bigquery.DatasetReference(
+        project=table_ref.project, dataset_id=table_ref.dataset_id
+    )
+    client = bigquery.Client(project=project, credentials=credentials)
+    bq_dataset = await asyncio.to_thread(client.get_dataset, dataset_ref=dataset_ref)
+    if not _bq_dataset_location_allowed(location, bq_dataset.location):
+        raise ValueError(
+            "The BigQuery dataset"
+            f" `{dataset_ref.project}.{dataset_ref.dataset_id}` must be in the"
+            " same location as the multimodal dataset. The multimodal dataset"
+            f" is in `{location}`, but the BigQuery dataset is in"
+            f" `{bq_dataset.location}`."
+        )
+    return f"{table_ref.project}.{table_ref.dataset_id}.{table_ref.table_id}"
+
+
+def _create_default_bigquery_dataset_if_not_exists(
+    *,
+    project: str,
+    location: str,
+    credentials: google.auth.credentials.Credentials,
+) -> str:
+    bigquery = _try_import_bigquery()
+
+    bigquery_client = bigquery.Client(project=project, credentials=credentials)
+    location_str = location.lower().replace("-", "_")
+    dataset_id = bigquery.DatasetReference(
+        project, f"{_DEFAULT_BQ_DATASET_PREFIX}_{location_str}"
+    )
+    dataset = bigquery.Dataset(dataset_ref=dataset_id)
+    dataset.location = location
+    bigquery_client.create_dataset(dataset, exists_ok=True)
+    return f"{dataset_id.project}.{dataset_id.dataset_id}"
+
+
+async def _create_default_bigquery_dataset_if_not_exists_async(
+    *,
+    project: str,
+    location: str,
+    credentials: google.auth.credentials.Credentials,
+) -> str:
+    bigquery = _try_import_bigquery()
+
+    bigquery_client = bigquery.Client(project=project, credentials=credentials)
+    location_str = location.lower().replace("-", "_")
+    dataset_id = bigquery.DatasetReference(
+        project, f"{_DEFAULT_BQ_DATASET_PREFIX}_{location_str}"
+    )
+    dataset = bigquery.Dataset(dataset_ref=dataset_id)
+    dataset.location = location
+    await asyncio.to_thread(bigquery_client.create_dataset, dataset, exists_ok=True)
+    return f"{dataset_id.project}.{dataset_id.dataset_id}"
+
+
+def _generate_target_table_id(dataset_id: str) -> str:
+    return f"{dataset_id}.{_DEFAULT_BQ_TABLE_PREFIX}_{str(uuid.uuid4())}"
+
+
+def generate_multimodal_dataset_display_name() -> str:
+    """Generates a display name with a timestamp."""
+    return f"MultimodalDataset {datetime.datetime.now().isoformat(sep=' ')}"
+
+
+def get_batch_job_unique_name() -> str:
+    """Generates a unique name suffix for a batch job destination."""
+    timestamp = datetime.datetime.now().strftime("%Y%m%d%H%M%S")
+    unique_id = uuid.uuid4().hex[0:5]
+    return f"{timestamp}_{unique_id}"
+
+
+def save_dataframe_to_bigquery(
+    dataframe: "bigframes.pandas.DataFrame",  # type: ignore # noqa: F821
+    target_table_id: str,
+    bq_client: "bigquery.Client",  # type: ignore # noqa: F821
+) -> None:
+    # `to_gbq` does not support cross-region use cases. We use `copy_table` as a workaround.
+    temp_table_id = dataframe.to_gbq()
+    copy_job = bq_client.copy_table(
+        sources=temp_table_id,
+        destination=target_table_id,
+    )
+    copy_job.result()
+    bq_client.delete_table(temp_table_id)
+
+
+async def save_dataframe_to_bigquery_async(
+    dataframe: "bigframes.pandas.DataFrame",  # type: ignore # noqa: F821
+    target_table_id: str,
+    bq_client: "bigquery.Client",  # type: ignore # noqa: F821
+) -> None:
+    # `to_gbq` does not support cross-region use cases. We use `copy_table` as a workaround.
+    temp_table_id = await asyncio.to_thread(dataframe.to_gbq)
+    copy_job = await asyncio.to_thread(
+        bq_client.copy_table,
+        sources=temp_table_id,
+        destination=target_table_id,
+    )
+    await asyncio.to_thread(copy_job.result)
+    await asyncio.to_thread(bq_client.delete_table, temp_table_id)
+
+
+def load_dataframe_from_bigquery(
+    *,
+    bigquery_uri: str,
+    project: str,
+    location: str,
+    credentials: google.auth.credentials.Credentials,
+) -> "bigframes.pandas.DataFrame":  # type: ignore # noqa: F821
+    """Loads a BigQuery table into a BigFrames DataFrame.
+
+    Args:
+      bigquery_uri: The URI of the BigQuery table, with or without the `bq://`
+        prefix.
+      project: The project to use for the BigFrames session.
+      location: The location to use for the BigFrames session.
+      credentials: The credentials to use for the BigFrames session.
+
+    Returns:
+      A BigFrames DataFrame backed by the BigQuery table.
+    """
+    bigframes = _try_import_bigframes()
+    session_options = bigframes.BigQueryOptions(
+        credentials=credentials,
+        project=project,
+        location=location,
+    )
+    with bigframes.connect(session_options) as session:
+        return session.read_gbq(bigquery_uri.removeprefix("bq://"))
+
+
+async def load_dataframe_from_bigquery_async(
+    *,
+    bigquery_uri: str,
+    project: str,
+    location: str,
+    credentials: google.auth.credentials.Credentials,
+) -> "bigframes.pandas.DataFrame":  # type: ignore # noqa: F821
+    """Loads a BigQuery table into a BigFrames DataFrame.
+
+    Args:
+      bigquery_uri: The URI of the BigQuery table, with or without the `bq://`
+        prefix.
+      project: The project to use for the BigFrames session.
+      location: The location to use for the BigFrames session.
+      credentials: The credentials to use for the BigFrames session.
+
+    Returns:
+      A BigFrames DataFrame backed by the BigQuery table.
+    """
+    return await asyncio.to_thread(
+        load_dataframe_from_bigquery,
+        bigquery_uri=bigquery_uri,
+        project=project,
+        location=location,
+        credentials=credentials,
+    )
+
+
+def resolve_dataset_name(resource_name_or_id: str, project: str, location: str) -> str:
+    """Resolves a dataset name or ID to a full resource name."""
+    if "/" not in resource_name_or_id:
+        return f"projects/{project}/locations/{location}/datasets/{resource_name_or_id}"
+    return resource_name_or_id

agentplatform/_genai/_evals_builtin_tools.py

@@ -0,0 +1,209 @@
+# Copyright 2026 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.
+#
+"""Built-in tool catalog for Gemini Agent evaluation display.
+
+The Gemini Agents API (``GET agents/{id}``) returns each tool as a bare type
+discriminator (e.g. ``{"type": "code_execution"}``) with no parameter schema
+or description.  The authoritative, full-fidelity expansion lives server-side
+in ``cloud/ai/platform/evaluation/utils/interaction_converter.py``.
+
+This module is a **display-only duplicate** of that server catalog, kept here
+so ``show()`` can render tools with full names and descriptions without a
+server round-trip.  Parameter schemas are intentionally omitted to avoid
+publishing internal tool contract details.
+
+**If the server catalog changes, this SDK-side copy must be updated to match.**
+
+Sandbox orchestration tools (``provision_sandbox``, ``load_sandbox``) are
+intentionally excluded from the tool catalog.  They are infrastructure
+initialization, not user-facing agent capabilities.
+"""
+
+from typing import Any, Optional
+
+from google.genai import types as genai_types
+
+
+# Maps a built-in Gemini Agent tool type to the concrete FunctionDeclarations
+# the agent actually exposes for that type.
+#
+# Source of truth: interaction_converter.py, _BUILTIN_TOOL_FUNCTION_DECLARATIONS
+BUILTIN_TOOL_DECLARATIONS: dict[str, list[genai_types.FunctionDeclaration]] = {
+    "code_execution": [
+        genai_types.FunctionDeclaration(
+            name="run_command",
+            description="Runs a shell command on the sandbox VM.",
+        ),
+    ],
+    "filesystem": [
+        genai_types.FunctionDeclaration(
+            name="view_file",
+            description="Reads the content of a workspace file.",
+        ),
+        genai_types.FunctionDeclaration(
+            name="create_file",
+            description="Writes content to a new or existing file.",
+        ),
+        genai_types.FunctionDeclaration(
+            name="edit_file",
+            description="Replaces a specific block of text in a file.",
+        ),
+        genai_types.FunctionDeclaration(
+            name="list_dir",
+            description="Lists the files in a directory.",
+        ),
+        genai_types.FunctionDeclaration(
+            name="delete_file",
+            description="Removes a file from the workspace.",
+        ),
+        genai_types.FunctionDeclaration(
+            name="move_file",
+            description="Renames or moves a file.",
+        ),
+    ],
+}
+
+
+# Sandbox-environment orchestration tools.
+# Source of truth: interaction_converter.py, _SANDBOX_TOOL_NAMES
+SANDBOX_TOOL_NAMES: frozenset[str] = frozenset(
+    {
+        "provision_sandbox",
+        "load_sandbox",
+    }
+)
+
+
+def is_sandbox_only_turn(
+    events: list[Any],
+) -> bool:
+    """Returns True if a turn contains only sandbox initialization events.
+
+    Sandbox provisioning events (``provision_sandbox``, ``load_sandbox``)
+    are infrastructure setup steps that happen before the user's first
+    real prompt.
+
+    A turn is sandbox-only when every event is either a
+    ``function_call`` or ``function_response`` referencing a sandbox
+    tool name.  Events with plain text content (model output, user
+    input) disqualify the turn.
+
+    Args:
+        events: The list of AgentEvents in the turn.
+
+    Returns:
+        True if the turn is sandbox-only and should be merged into the
+        next real turn for display.
+    """
+    if not events:
+        return True
+
+    for event in events:
+        content = getattr(event, "content", None)
+        if not content:
+            continue
+        parts = getattr(content, "parts", None)
+        if not parts:
+            continue
+        for part in parts:
+            if getattr(part, "function_call", None):
+                if part.function_call.name not in SANDBOX_TOOL_NAMES:
+                    return False
+            elif getattr(part, "function_response", None):
+                if part.function_response.name not in SANDBOX_TOOL_NAMES:
+                    return False
+            else:
+                # Any other part type (text, inline_data, executable_code,
+                # code_execution_result, etc.) means this is a real
+                # conversational event, not sandbox infrastructure.
+                return False
+    return True
+
+
+def agent_tools_to_config_tools(
+    agent_tools: Optional[list[Any]],
+) -> Optional[list[genai_types.Tool]]:
+    """Maps Gemini Agents API tools to ``genai_types.Tool`` for display.
+
+    Expands built-in agent tool types into their concrete function declarations
+    using ``BUILTIN_TOOL_DECLARATIONS`` (a display-only duplicate of the
+    server-side catalog in ``interaction_converter.py``).
+
+    Mapping rules:
+      * ``code_execution`` is expanded to ``run_command``.
+      * ``filesystem`` is expanded to ``view_file``, ``create_file``,
+        ``edit_file``, ``list_dir``, ``delete_file``, ``move_file``.
+      * ``google_search`` and ``url_context`` are mapped to their typed
+        ``genai_types.Tool`` variant.
+      * ``mcp_server`` is represented as a named declaration with a
+        human-readable label.
+      * Tools carrying explicit ``function_declarations`` are passed through.
+
+    Sandbox orchestration tools (``provision_sandbox``, ``load_sandbox``)
+    are intentionally excluded.  They are infrastructure initialization,
+    not user-facing capabilities.
+
+    Args:
+        agent_tools: The ``tools`` list from a fetched Gemini agent dict.
+
+    Returns:
+        A list of ``genai_types.Tool``, or ``None`` if there are no mappable
+        tools.
+    """
+    if not agent_tools:
+        return None
+    tools: list[genai_types.Tool] = []
+    for tool in agent_tools or []:
+        if not isinstance(tool, dict):
+            continue
+        tool_type = tool.get("type")
+        remainder = {k: v for k, v in tool.items() if k != "type"}
+
+        # Check the built-in catalog first (code_execution, filesystem).
+        catalog_decls = BUILTIN_TOOL_DECLARATIONS.get(tool_type or "")
+        if catalog_decls:
+            tools.append(genai_types.Tool(function_declarations=list(catalog_decls)))
+        elif tool_type == "google_search":
+            tools.append(genai_types.Tool(google_search=genai_types.GoogleSearch()))
+        elif tool_type == "url_context":
+            tools.append(genai_types.Tool(url_context=genai_types.UrlContext()))
+        elif "function_declarations" in remainder:
+            # Real function tool with explicit declarations.
+            tools.append(genai_types.Tool.model_validate(remainder))
+        elif tool_type == "mcp_server":
+            label = remainder.get("name") or remainder.get("url")
+            description = f"MCP server: {label}" if label else "MCP server."
+            tools.append(
+                genai_types.Tool(
+                    function_declarations=[
+                        genai_types.FunctionDeclaration(
+                            name="mcp_server", description=description
+                        )
+                    ]
+                )
+            )
+        elif tool_type:
+            # Unknown built-in: show by name so it isn't silently dropped.
+            tools.append(
+                genai_types.Tool(
+                    function_declarations=[
+                        genai_types.FunctionDeclaration(name=tool_type)
+                    ]
+                )
+            )
+        elif remainder:
+            tools.append(genai_types.Tool.model_validate(remainder))
+
+    return tools or None