google-genai 1.30.0__py3-none-any.whl → 1.32.0__py3-none-any.whl

google/genai/_api_client.py

@@ -91,7 +91,7 @@ class EphemeralTokenAPIKeyError(ValueError):
 
 # This method checks for the API key in the environment variables. Google API
 # key is precedenced over Gemini API key.
-def _get_env_api_key() -> Optional[str]:
+def get_env_api_key() -> Optional[str]:
   """Gets the API key from environment variables, prioritizing GOOGLE_API_KEY.
 
   Returns:
@@ -108,7 +108,7 @@ def _get_env_api_key() -> Optional[str]:
   return env_google_api_key or env_gemini_api_key or None
 
 
-def _append_library_version_headers(headers: dict[str, str]) -> None:
+def append_library_version_headers(headers: dict[str, str]) -> None:
   """Appends the telemetry header to the headers dict."""
   library_label = f'google-genai-sdk/{version.__version__}'
   language_label = 'gl-python/' + sys.version.split()[0]
@@ -131,7 +131,7 @@ def _append_library_version_headers(headers: dict[str, str]) -> None:
     headers['x-goog-api-client'] = version_header_value
 
 
-def _patch_http_options(
+def patch_http_options(
     options: HttpOptions, patch_options: HttpOptions
 ) -> HttpOptions:
   copy_option = options.model_copy()
@@ -155,11 +155,11 @@ def _patch_http_options(
       setattr(copy_option, key, getattr(options, key))
 
   if copy_option.headers is not None:
-    _append_library_version_headers(copy_option.headers)
+    append_library_version_headers(copy_option.headers)
   return copy_option
 
 
-def _populate_server_timeout_header(
+def populate_server_timeout_header(
     headers: dict[str, str], timeout_in_seconds: Optional[Union[float, int]]
 ) -> None:
   """Populates the server timeout header in the headers dict."""
@@ -167,7 +167,7 @@ def _populate_server_timeout_header(
     headers['X-Server-Timeout'] = str(math.ceil(timeout_in_seconds))
 
 
-def _join_url_path(base_url: str, path: str) -> str:
+def join_url_path(base_url: str, path: str) -> str:
   parsed_base = urlparse(base_url)
   base_path = (
       parsed_base.path[:-1]
@@ -178,7 +178,7 @@ def _join_url_path(base_url: str, path: str) -> str:
   return urlunparse(parsed_base._replace(path=base_path + '/' + path))
 
 
-def _load_auth(*, project: Union[str, None]) -> Tuple[Credentials, str]:
+def load_auth(*, project: Union[str, None]) -> Tuple[Credentials, str]:
   """Loads google auth credentials and project id."""
   credentials, loaded_project_id = google.auth.default(  # type: ignore[no-untyped-call]
       scopes=['https://www.googleapis.com/auth/cloud-platform'],
@@ -195,12 +195,12 @@ def _load_auth(*, project: Union[str, None]) -> Tuple[Credentials, str]:
   return credentials, project
 
 
-def _refresh_auth(credentials: Credentials) -> Credentials:
+def refresh_auth(credentials: Credentials) -> Credentials:
   credentials.refresh(Request())  # type: ignore[no-untyped-call]
   return credentials
 
 
-def _get_timeout_in_seconds(
+def get_timeout_in_seconds(
     timeout: Optional[Union[float, int]],
 ) -> Optional[float]:
   """Converts the timeout to seconds."""
@@ -454,7 +454,7 @@ _RETRY_HTTP_STATUS_CODES = (
 )
 
 
-def _retry_args(options: Optional[HttpRetryOptions]) -> _common.StringDict:
+def retry_args(options: Optional[HttpRetryOptions]) -> _common.StringDict:
   """Returns the retry args for the given http retry options.
 
   Args:
@@ -574,7 +574,7 @@ class BaseApiClient:
     # Retrieve implicitly set values from the environment.
     env_project = os.environ.get('GOOGLE_CLOUD_PROJECT', None)
     env_location = os.environ.get('GOOGLE_CLOUD_LOCATION', None)
-    env_api_key = _get_env_api_key()
+    env_api_key = get_env_api_key()
     self.project = project or env_project
     self.location = location or env_location
     self.api_key = api_key or env_api_key
@@ -631,7 +631,7 @@ class BaseApiClient:
           and not self.api_key
           and not validated_http_options.base_url
       ):
-        credentials, self.project = _load_auth(project=None)
+        credentials, self.project = load_auth(project=None)
         if not self._credentials:
           self._credentials = credentials
 
@@ -670,12 +670,12 @@ class BaseApiClient:
         self._http_options.headers['x-goog-api-key'] = self.api_key
     # Update the http options with the user provided http options.
     if http_options:
-      self._http_options = _patch_http_options(
+      self._http_options = patch_http_options(
           self._http_options, validated_http_options
       )
     else:
       if self._http_options.headers is not None:
-        _append_library_version_headers(self._http_options.headers)
+        append_library_version_headers(self._http_options.headers)
 
     client_args, async_client_args = self._ensure_httpx_ssl_ctx(
         self._http_options
@@ -689,7 +689,7 @@ class BaseApiClient:
       )
     self._websocket_ssl_ctx = self._ensure_websocket_ssl_ctx(self._http_options)
 
-    retry_kwargs = _retry_args(self._http_options.retry_options)
+    retry_kwargs = retry_args(self._http_options.retry_options)
     self._retry = tenacity.Retrying(**retry_kwargs)
     self._async_retry = tenacity.AsyncRetrying(**retry_kwargs)
 
@@ -889,14 +889,14 @@ class BaseApiClient:
     """Retrieves the access token for the credentials."""
     with self._sync_auth_lock:
       if not self._credentials:
-        self._credentials, project = _load_auth(project=self.project)
+        self._credentials, project = load_auth(project=self.project)
         if not self.project:
           self.project = project
 
       if self._credentials:
         if self._credentials.expired or not self._credentials.token:
           # Only refresh when it needs to. Default expiration is 3600 seconds.
-          _refresh_auth(self._credentials)
+          refresh_auth(self._credentials)
         if not self._credentials.token:
           raise RuntimeError('Could not resolve API token from the environment')
         return self._credentials.token  # type: ignore[no-any-return]
@@ -912,7 +912,7 @@ class BaseApiClient:
         if not self._credentials:
           # Double check that the credentials are not set before loading them.
           self._credentials, project = await asyncio.to_thread(
-              _load_auth, project=self.project
+              load_auth, project=self.project
           )
           if not self.project:
             self.project = project
@@ -923,7 +923,7 @@ class BaseApiClient:
         async with self._async_auth_lock:
           if self._credentials.expired or not self._credentials.token:
             # Double check that the credentials expired before refreshing.
-            await asyncio.to_thread(_refresh_auth, self._credentials)
+            await asyncio.to_thread(refresh_auth, self._credentials)
 
       if not self._credentials.token:
         raise RuntimeError('Could not resolve API token from the environment')
@@ -946,12 +946,12 @@ class BaseApiClient:
     # patch the http options with the user provided settings.
     if http_options:
       if isinstance(http_options, HttpOptions):
-        patched_http_options = _patch_http_options(
+        patched_http_options = patch_http_options(
             self._http_options,
             http_options,
         )
       else:
-        patched_http_options = _patch_http_options(
+        patched_http_options = patch_http_options(
             self._http_options, HttpOptions.model_validate(http_options)
         )
     else:
@@ -993,7 +993,7 @@ class BaseApiClient:
           request_dict, patched_http_options.extra_body
       )
 
-    url = _join_url_path(
+    url = join_url_path(
         base_url,
         versioned_path,
     )
@@ -1003,11 +1003,11 @@ class BaseApiClient:
           'Ephemeral tokens can only be used with the live API.'
       )
 
-    timeout_in_seconds = _get_timeout_in_seconds(patched_http_options.timeout)
+    timeout_in_seconds = get_timeout_in_seconds(patched_http_options.timeout)
 
     if patched_http_options.headers is None:
       raise ValueError('Request headers must be set.')
-    _populate_server_timeout_header(
+    populate_server_timeout_header(
         patched_http_options.headers, timeout_in_seconds
     )
     return HttpRequest(
@@ -1079,7 +1079,7 @@ class BaseApiClient:
       )
       # Support per request retry options.
       if parameter_model.retry_options:
-        retry_kwargs = _retry_args(parameter_model.retry_options)
+        retry_kwargs = retry_args(parameter_model.retry_options)
         retry = tenacity.Retrying(**retry_kwargs)
         return retry(self._request_once, http_request, stream)  # type: ignore[no-any-return]
 
@@ -1239,7 +1239,7 @@ class BaseApiClient:
       )
       # Support per request retry options.
       if parameter_model.retry_options:
-        retry_kwargs = _retry_args(parameter_model.retry_options)
+        retry_kwargs = retry_args(parameter_model.retry_options)
         retry = tenacity.AsyncRetrying(**retry_kwargs)
         return await retry(self._async_request_once, http_request, stream)  # type: ignore[no-any-return]
     return await self._async_retry(  # type: ignore[no-any-return]
@@ -1398,13 +1398,13 @@ class BaseApiClient:
             if isinstance(self._http_options, dict)
             else self._http_options.timeout
         )
-      timeout_in_seconds = _get_timeout_in_seconds(timeout)
+      timeout_in_seconds = get_timeout_in_seconds(timeout)
       upload_headers = {
           'X-Goog-Upload-Command': upload_command,
           'X-Goog-Upload-Offset': str(offset),
           'Content-Length': str(chunk_size),
       }
-      _populate_server_timeout_header(upload_headers, timeout_in_seconds)
+      populate_server_timeout_header(upload_headers, timeout_in_seconds)
       retry_count = 0
       while retry_count < MAX_RETRY_COUNT:
         response = self._httpx_client.request(
@@ -1558,13 +1558,13 @@ class BaseApiClient:
                 if isinstance(self._http_options, dict)
                 else self._http_options.timeout
             )
-          timeout_in_seconds = _get_timeout_in_seconds(timeout)
+          timeout_in_seconds = get_timeout_in_seconds(timeout)
           upload_headers = {
               'X-Goog-Upload-Command': upload_command,
               'X-Goog-Upload-Offset': str(offset),
               'Content-Length': str(chunk_size),
           }
-          _populate_server_timeout_header(upload_headers, timeout_in_seconds)
+          populate_server_timeout_header(upload_headers, timeout_in_seconds)
 
           retry_count = 0
           response = None
@@ -1634,13 +1634,13 @@ class BaseApiClient:
               if isinstance(self._http_options, dict)
               else self._http_options.timeout
           )
-        timeout_in_seconds = _get_timeout_in_seconds(timeout)
+        timeout_in_seconds = get_timeout_in_seconds(timeout)
         upload_headers = {
             'X-Goog-Upload-Command': upload_command,
             'X-Goog-Upload-Offset': str(offset),
             'Content-Length': str(chunk_size),
         }
-        _populate_server_timeout_header(upload_headers, timeout_in_seconds)
+        populate_server_timeout_header(upload_headers, timeout_in_seconds)
 
         retry_count = 0
         client_response = None

google/genai/_automatic_function_calling_util.py

@@ -30,6 +30,18 @@ if sys.version_info >= (3, 10):
 else:
   VersionedUnionType = typing._UnionGenericAlias  # type: ignore[attr-defined]
 
+
+__all__ = [
+    '_py_builtin_type_to_schema_type',
+    '_raise_for_unsupported_param',
+    '_handle_params_as_deferred_annotations',
+    '_add_unevaluated_items_to_fixed_len_tuple_schema',
+    '_is_builtin_primitive_or_compound',
+    '_is_default_value_compatible',
+    '_parse_schema_from_parameter',
+    '_get_required_fields',
+]
+
 _py_builtin_type_to_schema_type = {
     str: types.Type.STRING,
     int: types.Type.INTEGER,

google/genai/_base_transformers.py

@@ -0,0 +1,26 @@
+# 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.
+#
+
+"""Base transformers for Google GenAI SDK."""
+import base64
+
+# Some fields don't accept url safe base64 encoding.
+# We shouldn't use this transformer if the backend adhere to Cloud Type
+# format https://cloud.google.com/docs/discovery/type-format.
+# TODO(b/389133914,b/390320301): Remove the hack after backend fix the issue.
+def t_bytes(data: bytes) -> str:
+  if not isinstance(data, bytes):
+    return data
+  return base64.b64encode(data).decode('ascii')

google/genai/_live_converters.py

@@ -16,6 +16,7 @@
 # Code generated by the Google Gen AI SDK generator DO NOT EDIT.
 
 from typing import Any, Optional, Union
+
 from . import _transformers as t
 from ._api_client import BaseApiClient
 from ._common import get_value_by_path as getv

google/genai/_local_tokenizer_loader.py

@@ -0,0 +1,223 @@
+# 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 dataclasses
+import functools
+import hashlib
+import os
+import tempfile
+from typing import Optional, cast
+import uuid
+
+import requests  # type: ignore
+import sentencepiece as spm
+from sentencepiece import sentencepiece_model_pb2
+
+
+# Source of truth: https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models
+_GEMINI_MODELS_TO_TOKENIZER_NAMES = {
+    "gemini-1.0-pro": "gemma2",
+    "gemini-1.5-pro": "gemma2",
+    "gemini-1.5-flash": "gemma2",
+    "gemini-2.5-pro": "gemma3",
+    "gemini-2.5-flash": "gemma3",
+    "gemini-2.5-flash-lite": "gemma3",
+    "gemini-2.0-flash": "gemma3",
+    "gemini-2.0-flash-lite": "gemma3",
+}
+_GEMINI_STABLE_MODELS_TO_TOKENIZER_NAMES = {
+    "gemini-1.0-pro-001": "gemma2",
+    "gemini-1.0-pro-002": "gemma2",
+    "gemini-1.5-pro-001": "gemma2",
+    "gemini-1.5-flash-001": "gemma2",
+    "gemini-1.5-flash-002": "gemma2",
+    "gemini-1.5-pro-002": "gemma2",
+    "gemini-2.5-pro-preview-06-05": "gemma3",
+    "gemini-2.5-pro-preview-05-06": "gemma3",
+    "gemini-2.5-pro-exp-03-25": "gemma3",
+    "gemini-live-2.5-flash": "gemma3",
+    "gemini-2.5-flash-preview-05-20": "gemma3",
+    "gemini-2.5-flash-preview-04-17": "gemma3",
+    "gemini-2.5-flash-lite-preview-06-17": "gemma3",
+    "gemini-2.0-flash-001": "gemma3",
+    "gemini-2.0-flash-lite-001": "gemma3",
+}
+
+
+@dataclasses.dataclass(frozen=True)
+class _TokenizerConfig:
+  model_url: str
+  model_hash: str
+
+
+# TODO: update gemma3 tokenizer
+_TOKENIZERS = {
+    "gemma2": _TokenizerConfig(
+        model_url="https://raw.githubusercontent.com/google/gemma_pytorch/33b652c465537c6158f9a472ea5700e5e770ad3f/tokenizer/tokenizer.model",
+        model_hash=(
+            "61a7b147390c64585d6c3543dd6fc636906c9af3865a5548f27f31aee1d4c8e2"
+        ),
+    ),
+    "gemma3": _TokenizerConfig(
+        model_url="https://raw.githubusercontent.com/google/gemma_pytorch/014acb7ac4563a5f77c76d7ff98f31b568c16508/tokenizer/gemma3_cleaned_262144_v2.spiece.model",
+        model_hash=(
+            "1299c11d7cf632ef3b4e11937501358ada021bbdf7c47638d13c0ee982f2e79c"
+        ),
+    ),
+}
+
+
+def _load_file(file_url_path: str) -> bytes:
+  """Loads file bytes from the given file url path."""
+  resp = requests.get(file_url_path)
+  resp.raise_for_status()
+  return cast(bytes, resp.content)
+
+
+def _is_valid_model(*, model_data: bytes, expected_hash: str) -> bool:
+  """Returns true if the content is valid by checking the hash."""
+  if not expected_hash:
+    raise ValueError("expected_hash is required")
+  return hashlib.sha256(model_data).hexdigest() == expected_hash
+
+
+def _maybe_remove_file(file_path: str) -> None:
+  """Removes the file if exists."""
+  if not os.path.exists(file_path):
+    return
+  try:
+    os.remove(file_path)
+  except OSError:
+    # Don't raise if we cannot remove file.
+    pass
+
+
+def _maybe_load_from_cache(
+    *, file_path: str, expected_hash: str
+) -> Optional[bytes]:
+  """Loads the content from the cache path."""
+  if not os.path.exists(file_path):
+    return None
+  with open(file_path, "rb") as f:
+    content = f.read()
+  if _is_valid_model(model_data=content, expected_hash=expected_hash):
+    return content
+
+  # Cached file corrupted.
+  _maybe_remove_file(file_path)
+  return None
+
+
+def _maybe_save_to_cache(
+    *, cache_dir: str, cache_path: str, content: bytes
+) -> None:
+  """Saves the content to the cache path."""
+  try:
+    os.makedirs(cache_dir, exist_ok=True)
+    tmp_path = cache_dir + "." + str(uuid.uuid4()) + ".tmp"
+    with open(tmp_path, "wb") as f:
+      f.write(content)
+    os.rename(tmp_path, cache_path)
+  except OSError:
+    # Don't raise if we cannot write file.
+    pass
+
+
+def _load_from_url(*, file_url: str, expected_hash: str) -> bytes:
+  """Loads model bytes from the given file url."""
+  content = _load_file(file_url)
+  if not _is_valid_model(model_data=content, expected_hash=expected_hash):
+    actual_hash = hashlib.sha256(content).hexdigest()
+    raise ValueError(
+        "Downloaded model file is corrupted."
+        f" Expected hash {expected_hash}. Got file hash {actual_hash}."
+    )
+  return content
+
+
+def _load(*, file_url: str, expected_hash: str) -> bytes:
+  """Loads model bytes from the given file url.
+
+  1. If the find local cached file for the given url and the cached file hash
+     matches the expected hash, the cached file is returned.
+  2. If local cached file is not found or the hash does not match, the file is
+     downloaded from the given url. And write to local cache and return the
+     file bytes.
+  3. If the file downloaded from the given url does not match the expected
+     hash, raise ValueError.
+
+  Args:
+      file_url: The url of the file to load.
+      expected_hash: The expected hash of the file.
+
+  Returns:
+      The file bytes.
+  """
+  model_dir = os.path.join(tempfile.gettempdir(), "vertexai_tokenizer_model")
+  filename = hashlib.sha1(file_url.encode()).hexdigest()
+  model_path = os.path.join(model_dir, filename)
+
+  model_data = _maybe_load_from_cache(
+      file_path=model_path, expected_hash=expected_hash
+  )
+  if not model_data:
+    model_data = _load_from_url(file_url=file_url, expected_hash=expected_hash)
+
+  _maybe_save_to_cache(
+      cache_dir=model_dir, cache_path=model_path, content=model_data
+  )
+  return model_data
+
+
+def _load_model_proto_bytes(tokenizer_name: str) -> bytes:
+  """Loads model proto bytes from the given tokenizer name."""
+  if tokenizer_name not in _TOKENIZERS:
+    raise ValueError(
+        f"Tokenizer {tokenizer_name} is not supported."
+        f"Supported tokenizers: {list(_TOKENIZERS.keys())}"
+    )
+  return _load(
+      file_url=_TOKENIZERS[tokenizer_name].model_url,
+      expected_hash=_TOKENIZERS[tokenizer_name].model_hash,
+  )
+
+
+@functools.lru_cache()
+def load_model_proto(
+    tokenizer_name: str,
+) -> sentencepiece_model_pb2.ModelProto:
+  """Loads model proto from the given tokenizer name."""
+  model_proto = sentencepiece_model_pb2.ModelProto()
+  model_proto.ParseFromString(_load_model_proto_bytes(tokenizer_name))
+  return model_proto
+
+
+def get_tokenizer_name(model_name: str) -> str:
+  """Gets the tokenizer name for the given model name."""
+  if model_name in _GEMINI_MODELS_TO_TOKENIZER_NAMES.keys():
+    return _GEMINI_MODELS_TO_TOKENIZER_NAMES[model_name]
+  if model_name in _GEMINI_STABLE_MODELS_TO_TOKENIZER_NAMES.keys():
+    return _GEMINI_STABLE_MODELS_TO_TOKENIZER_NAMES[model_name]
+  raise ValueError(
+      f"Model {model_name} is not supported. Supported models: {', '.join(_GEMINI_MODELS_TO_TOKENIZER_NAMES.keys())}, {', '.join(_GEMINI_STABLE_MODELS_TO_TOKENIZER_NAMES.keys())}.\n"  # pylint: disable=line-too-long
+  )
+
+
+@functools.lru_cache()
+def get_sentencepiece(tokenizer_name: str) -> spm.SentencePieceProcessor:
+  """Loads sentencepiece tokenizer from the given tokenizer name."""
+  processor = spm.SentencePieceProcessor()
+  processor.LoadFromSerializedProto(_load_model_proto_bytes(tokenizer_name))
+  return processor