google-genai 0.7.0__tar.gz → 1.0.0__tar.gz

{google_genai-0.7.0/google_genai.egg-info → google_genai-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: google-genai
-Version: 0.7.0
+Version: 1.0.0
 Summary: GenAI Python SDK
 Author-email: Google LLC <googleapis-packages@google.com>
 License: Apache-2.0
@@ -34,7 +34,7 @@ Requires-Dist: websockets<15.0dev,>=13.0
 
 -----
 
-Google Gen AI Python SDK provides an interface for developers to integrate Google's generative models into their Python applications. It supports the [Gemini Developer API](https://ai.google.dev/gemini-api/docs) and [Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/overview) APIs. This is an early release. API is subject to change. Please do not use this SDK in production environments at this stage.
+Google Gen AI Python SDK provides an interface for developers to integrate Google's generative models into their Python applications. It supports the [Gemini Developer API](https://ai.google.dev/gemini-api/docs) and [Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/overview) APIs.
 
 ## Installation
 
@@ -66,6 +66,23 @@ client = genai.Client(
 )
 ```
 
+To set the API version use `http_options`. For example, to set the API version
+to `v1` for Vertex AI:
+
+```python
+client = genai.Client(
+    vertexai=True, project='your-project-id', location='us-central1',
+    http_options={'api_version': 'v1'}
+)
+```
+
+To set the API version to `v1alpha` for the Gemini API:
+
+```python
+client = genai.Client(api_key='GEMINI_API_KEY',
+                      http_options={'api_version': 'v1alpha'})
+```
+
 ## Types
 
 Parameter types can be specified as either dictionaries(`TypedDict`) or
@@ -97,9 +114,10 @@ download the file in console.
 python code.
 
 ```python
-file = client.files.upload(path="a11.text")
+file = client.files.upload(path="a11.txt")
 response = client.models.generate_content(
-    model="gemini-2.0-flash-exp", contents=["Summarize this file", file]
+    model="gemini-2.0-flash-exp",
+    contents=["Could you summarize this file?", file]
 )
 print(response.text)
 ```
@@ -143,53 +161,17 @@ response = client.models.generate_content(
 print(response.text)
 ```
 
-### Thinking
-
-The Gemini 2.0 Flash Thinking model is an experimental model that could return
-"thoughts" as part of its response.
-
-#### Gemini Developer API
-
-Thinking config is only available in v1alpha for Gemini AI API.
-
-```python
-response = client.models.generate_content(
-    model='gemini-2.0-flash-thinking-exp',
-    contents='What is the sum of natural numbers from 1 to 100?',
-    config=types.GenerateContentConfig(
-        thinking_config=types.ThinkingConfig(include_thoughts=True),
-        http_options=types.HttpOptions(api_version='v1alpha'),
-    )
-)
-for part in response.candidates[0].content.parts:
-    print(part)
-```
-
-#### Vertex AI API
-
-```python
-response = client.models.generate_content(
-    model='gemini-2.0-flash-thinking-exp-01-21',
-    contents='What is the sum of natural numbers from 1 to 100?',
-    config=types.GenerateContentConfig(
-        thinking_config=types.ThinkingConfig(include_thoughts=True),
-    )
-)
-for part in response.candidates[0].content.parts:
-    print(part)
-```
-
 ### List Base Models
 
 To retrieve tuned models, see [list tuned models](#list-tuned-models).
 
 ```python
-for model in client.models.list(config={'query_base':True}):
+for model in client.models.list():
     print(model)
 ```
 
 ```python
-pager = client.models.list(config={"page_size": 10, 'query_base':True})
+pager = client.models.list(config={"page_size": 10})
 print(pager.page_size)
 print(pager[0])
 pager.next_page()
@@ -199,12 +181,12 @@ print(pager[0])
 #### Async
 
 ```python
-async for job in await client.aio.models.list(config={'query_base':True}):
+async for job in await client.aio.models.list():
     print(job)
 ```
 
 ```python
-async_pager = await client.aio.models.list(config={"page_size": 10, 'query_base':True})
+async_pager = await client.aio.models.list(config={"page_size": 10})
 print(async_pager.page_size)
 print(async_pager[0])
 await async_pager.next_page()
@@ -337,6 +319,66 @@ response = client.models.generate_content(
 print(response.text)
 ```
 
+#### Function calling with `ANY` tools config mode
+
+If you configure function calling mode to be `ANY`, then the model will always
+return function call parts. If you also pass a python function as a tool, by
+default the SDK will perform automatic function calling until the remote calls exceed the
+maximum remote call for automatic function calling (default to 10 times).
+
+If you'd like to disable automatic function calling in `ANY` mode:
+
+```python
+def get_current_weather(location: str) -> str:
+    """Returns the current weather.
+
+    Args:
+      location: The city and state, e.g. San Francisco, CA
+    """
+    return "sunny"
+
+response = client.models.generate_content(
+    model="gemini-2.0-flash-exp",
+    contents="What is the weather like in Boston?",
+    config=types.GenerateContentConfig(
+        tools=[get_current_weather],
+        automatic_function_calling=types.AutomaticFunctionCallingConfig(
+            disable=True
+        ),
+        tool_config=types.ToolConfig(
+            function_calling_config=types.FunctionCallingConfig(mode='ANY')
+        ),
+    ),
+)
+```
+
+If you'd like to set `x` number of automatic function call turns, you can
+configure the maximum remote calls to be `x + 1`.
+Assuming you prefer `1` turn for automatic function calling.
+
+```python
+def get_current_weather(location: str) -> str:
+    """Returns the current weather.
+
+    Args:
+      location: The city and state, e.g. San Francisco, CA
+    """
+    return "sunny"
+
+response = client.models.generate_content(
+    model="gemini-2.0-flash-exp",
+    contents="What is the weather like in Boston?",
+    config=types.GenerateContentConfig(
+        tools=[get_current_weather],
+        automatic_function_calling=types.AutomaticFunctionCallingConfig(
+            maximum_remote_calls=2
+        ),
+        tool_config=types.ToolConfig(
+            function_calling_config=types.FunctionCallingConfig(mode='ANY')
+        ),
+    ),
+)
+```
 ### JSON Response Schema
 
 #### Pydantic Model Schema support
@@ -863,12 +905,12 @@ print(tuned_model)
 To retrieve base models, see [list base models](#list-base-models).
 
 ```python
-for model in client.models.list(config={"page_size": 10}):
+for model in client.models.list(config={"page_size": 10, "query_base": False}):
     print(model)
 ```
 
 ```python
-pager = client.models.list(config={"page_size": 10})
+pager = client.models.list(config={"page_size": 10, "query_base": False})
 print(pager.page_size)
 print(pager[0])
 pager.next_page()
@@ -878,12 +920,12 @@ print(pager[0])
 #### Async
 
 ```python
-async for job in await client.aio.models.list(config={"page_size": 10}):
+async for job in await client.aio.models.list(config={"page_size": 10, "query_base": False}):
     print(job)
 ```
 
 ```python
-async_pager = await client.aio.models.list(config={"page_size": 10})
+async_pager = await client.aio.models.list(config={"page_size": 10, "query_base": False})
 print(async_pager.page_size)
 print(async_pager[0])
 await async_pager.next_page()

{google_genai-0.7.0 → google_genai-1.0.0}/README.md

@@ -7,7 +7,7 @@
 
 -----
 
-Google Gen AI Python SDK provides an interface for developers to integrate Google's generative models into their Python applications. It supports the [Gemini Developer API](https://ai.google.dev/gemini-api/docs) and [Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/overview) APIs. This is an early release. API is subject to change. Please do not use this SDK in production environments at this stage.
+Google Gen AI Python SDK provides an interface for developers to integrate Google's generative models into their Python applications. It supports the [Gemini Developer API](https://ai.google.dev/gemini-api/docs) and [Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/overview) APIs.
 
 ## Installation
 
@@ -39,6 +39,23 @@ client = genai.Client(
 )
 ```
 
+To set the API version use `http_options`. For example, to set the API version
+to `v1` for Vertex AI:
+
+```python
+client = genai.Client(
+    vertexai=True, project='your-project-id', location='us-central1',
+    http_options={'api_version': 'v1'}
+)
+```
+
+To set the API version to `v1alpha` for the Gemini API:
+
+```python
+client = genai.Client(api_key='GEMINI_API_KEY',
+                      http_options={'api_version': 'v1alpha'})
+```
+
 ## Types
 
 Parameter types can be specified as either dictionaries(`TypedDict`) or
@@ -70,9 +87,10 @@ download the file in console.
 python code.
 
 ```python
-file = client.files.upload(path="a11.text")
+file = client.files.upload(path="a11.txt")
 response = client.models.generate_content(
-    model="gemini-2.0-flash-exp", contents=["Summarize this file", file]
+    model="gemini-2.0-flash-exp",
+    contents=["Could you summarize this file?", file]
 )
 print(response.text)
 ```
@@ -116,53 +134,17 @@ response = client.models.generate_content(
 print(response.text)
 ```
 
-### Thinking
-
-The Gemini 2.0 Flash Thinking model is an experimental model that could return
-"thoughts" as part of its response.
-
-#### Gemini Developer API
-
-Thinking config is only available in v1alpha for Gemini AI API.
-
-```python
-response = client.models.generate_content(
-    model='gemini-2.0-flash-thinking-exp',
-    contents='What is the sum of natural numbers from 1 to 100?',
-    config=types.GenerateContentConfig(
-        thinking_config=types.ThinkingConfig(include_thoughts=True),
-        http_options=types.HttpOptions(api_version='v1alpha'),
-    )
-)
-for part in response.candidates[0].content.parts:
-    print(part)
-```
-
-#### Vertex AI API
-
-```python
-response = client.models.generate_content(
-    model='gemini-2.0-flash-thinking-exp-01-21',
-    contents='What is the sum of natural numbers from 1 to 100?',
-    config=types.GenerateContentConfig(
-        thinking_config=types.ThinkingConfig(include_thoughts=True),
-    )
-)
-for part in response.candidates[0].content.parts:
-    print(part)
-```
-
 ### List Base Models
 
 To retrieve tuned models, see [list tuned models](#list-tuned-models).
 
 ```python
-for model in client.models.list(config={'query_base':True}):
+for model in client.models.list():
     print(model)
 ```
 
 ```python
-pager = client.models.list(config={"page_size": 10, 'query_base':True})
+pager = client.models.list(config={"page_size": 10})
 print(pager.page_size)
 print(pager[0])
 pager.next_page()
@@ -172,12 +154,12 @@ print(pager[0])
 #### Async
 
 ```python
-async for job in await client.aio.models.list(config={'query_base':True}):
+async for job in await client.aio.models.list():
     print(job)
 ```
 
 ```python
-async_pager = await client.aio.models.list(config={"page_size": 10, 'query_base':True})
+async_pager = await client.aio.models.list(config={"page_size": 10})
 print(async_pager.page_size)
 print(async_pager[0])
 await async_pager.next_page()
@@ -310,6 +292,66 @@ response = client.models.generate_content(
 print(response.text)
 ```
 
+#### Function calling with `ANY` tools config mode
+
+If you configure function calling mode to be `ANY`, then the model will always
+return function call parts. If you also pass a python function as a tool, by
+default the SDK will perform automatic function calling until the remote calls exceed the
+maximum remote call for automatic function calling (default to 10 times).
+
+If you'd like to disable automatic function calling in `ANY` mode:
+
+```python
+def get_current_weather(location: str) -> str:
+    """Returns the current weather.
+
+    Args:
+      location: The city and state, e.g. San Francisco, CA
+    """
+    return "sunny"
+
+response = client.models.generate_content(
+    model="gemini-2.0-flash-exp",
+    contents="What is the weather like in Boston?",
+    config=types.GenerateContentConfig(
+        tools=[get_current_weather],
+        automatic_function_calling=types.AutomaticFunctionCallingConfig(
+            disable=True
+        ),
+        tool_config=types.ToolConfig(
+            function_calling_config=types.FunctionCallingConfig(mode='ANY')
+        ),
+    ),
+)
+```
+
+If you'd like to set `x` number of automatic function call turns, you can
+configure the maximum remote calls to be `x + 1`.
+Assuming you prefer `1` turn for automatic function calling.
+
+```python
+def get_current_weather(location: str) -> str:
+    """Returns the current weather.
+
+    Args:
+      location: The city and state, e.g. San Francisco, CA
+    """
+    return "sunny"
+
+response = client.models.generate_content(
+    model="gemini-2.0-flash-exp",
+    contents="What is the weather like in Boston?",
+    config=types.GenerateContentConfig(
+        tools=[get_current_weather],
+        automatic_function_calling=types.AutomaticFunctionCallingConfig(
+            maximum_remote_calls=2
+        ),
+        tool_config=types.ToolConfig(
+            function_calling_config=types.FunctionCallingConfig(mode='ANY')
+        ),
+    ),
+)
+```
 ### JSON Response Schema
 
 #### Pydantic Model Schema support
@@ -836,12 +878,12 @@ print(tuned_model)
 To retrieve base models, see [list base models](#list-base-models).
 
 ```python
-for model in client.models.list(config={"page_size": 10}):
+for model in client.models.list(config={"page_size": 10, "query_base": False}):
     print(model)
 ```
 
 ```python
-pager = client.models.list(config={"page_size": 10})
+pager = client.models.list(config={"page_size": 10, "query_base": False})
 print(pager.page_size)
 print(pager[0])
 pager.next_page()
@@ -851,12 +893,12 @@ print(pager[0])
 #### Async
 
 ```python
-async for job in await client.aio.models.list(config={"page_size": 10}):
+async for job in await client.aio.models.list(config={"page_size": 10, "query_base": False}):
     print(job)
 ```
 
 ```python
-async_pager = await client.aio.models.list(config={"page_size": 10})
+async_pager = await client.aio.models.list(config={"page_size": 10, "query_base": False})
 print(async_pager.page_size)
 print(async_pager[0])
 await async_pager.next_page()

{google_genai-0.7.0 → google_genai-1.0.0}/google/genai/_api_client.py

@@ -99,6 +99,19 @@ class HttpRequest:
   timeout: Optional[float] = None
 
 
+# TODO(b/394358912): Update this class to use a SDKResponse class that can be
+# generated and used for all languages.
+@dataclass
+class BaseResponse:
+  http_headers: dict[str, str]
+
+  @property
+  def dict(self) -> dict[str, Any]:
+    if isinstance(self, dict):
+      return self
+    return {'httpHeaders': self.http_headers}
+
+
 class HttpResponse:
 
   def __init__(
@@ -255,7 +268,7 @@ class ApiClient:
             'Project and location or API key must be set when using the Vertex '
             'AI API.'
         )
-      if self.api_key:
+      if self.api_key or self.location == 'global':
         self._http_options['base_url'] = (
             f'https://aiplatform.googleapis.com/'
         )
@@ -273,7 +286,7 @@ class ApiClient:
       self._http_options['api_version'] = 'v1beta'
     # Default options for both clients.
     self._http_options['headers'] = {'Content-Type': 'application/json'}
-    if self.api_key and not self.vertexai:
+    if self.api_key:
       self._http_options['headers']['x-goog-api-key'] = self.api_key
     # Update the http options with the user provided http options.
     if http_options:
@@ -323,8 +336,6 @@ class ApiClient:
         and not self.api_key
     ):
       path = f'projects/{self.project}/locations/{self.location}/' + path
-    elif self.vertexai and self.api_key:
-      path = f'{path}?key={self.api_key}'
     url = _join_url_path(
         patched_http_options['base_url'],
         patched_http_options['api_version'] + '/' + path,
@@ -436,18 +447,12 @@ class ApiClient:
         http_method, path, request_dict, http_options
     )
     response = self._request(http_request, stream=False)
-    if http_options:
-      if (
-          isinstance(http_options, HttpOptions)
-          and http_options.deprecated_response_payload is not None
-      ):
-        response._copy_to_dict(http_options.deprecated_response_payload)
-      elif (
-          isinstance(http_options, dict)
-          and 'deprecated_response_payload' in http_options
-      ):
-        response._copy_to_dict(http_options['deprecated_response_payload'])
-    return response.json
+    json_response = response.json
+    if not json_response:
+      base_response = BaseResponse(response.headers).dict
+      return base_response
+
+    return json_response
 
   def request_streamed(
       self,
@@ -461,10 +466,6 @@ class ApiClient:
     )
 
     session_response = self._request(http_request, stream=True)
-    if http_options and 'deprecated_response_payload' in http_options:
-      session_response._copy_to_dict(
-          http_options['deprecated_response_payload']
-      )
     for chunk in session_response.segments():
       yield chunk
 
@@ -480,9 +481,11 @@ class ApiClient:
     )
 
     result = await self._async_request(http_request=http_request, stream=False)
-    if http_options and 'deprecated_response_payload' in http_options:
-      result._copy_to_dict(http_options['deprecated_response_payload'])
-    return result.json
+    json_response = result.json
+    if not json_response:
+      base_response = BaseResponse(result.headers).dict
+      return base_response
+    return json_response
 
   async def async_request_streamed(
       self,
@@ -497,8 +500,6 @@ class ApiClient:
 
     response = await self._async_request(http_request=http_request, stream=True)
 
-    if http_options and 'deprecated_response_payload' in http_options:
-      response._copy_to_dict(http_options['deprecated_response_payload'])
     async def async_generator():
       async for chunk in response:
         yield chunk

{google_genai-0.7.0 → google_genai-1.0.0}/google/genai/_automatic_function_calling_util.py

@@ -17,14 +17,18 @@ import inspect
 import sys
 import types as builtin_types
 import typing
-from typing import Any, Callable, Literal, Union, _GenericAlias, get_args, get_origin
+from typing import _GenericAlias, Any, Callable, get_args, get_origin, Literal, Union
+
 import pydantic
+
+from . import _extra_utils
 from . import types
 
+
 if sys.version_info >= (3, 10):
-  UnionType = builtin_types.UnionType
+  VersionedUnionType = builtin_types.UnionType
 else:
-  UnionType = typing._UnionGenericAlias
+  VersionedUnionType = typing._UnionGenericAlias
 
 _py_builtin_type_to_schema_type = {
     str: 'STRING',
@@ -45,7 +49,8 @@ def _is_builtin_primitive_or_compound(
 def _raise_for_any_of_if_mldev(schema: types.Schema):
   if schema.any_of:
     raise ValueError(
-        'AnyOf is not supported in function declaration schema for Google AI.'
+        'AnyOf is not supported in function declaration schema for'
+        ' the Gemini API.'
     )
 
 
@@ -53,15 +58,7 @@ def _raise_for_default_if_mldev(schema: types.Schema):
   if schema.default is not None:
     raise ValueError(
         'Default value is not supported in function declaration schema for'
-        ' Google AI.'
-    )
-
-
-def _raise_for_nullable_if_mldev(schema: types.Schema):
-  if schema.nullable:
-    raise ValueError(
-        'Nullable is not supported in function declaration schema for'
-        ' Google AI.'
+        ' the Gemini API.'
     )
 
 
@@ -69,7 +66,6 @@ def _raise_if_schema_unsupported(client, schema: types.Schema):
   if not client.vertexai:
     _raise_for_any_of_if_mldev(schema)
     _raise_for_default_if_mldev(schema)
-    _raise_for_nullable_if_mldev(schema)
 
 
 def _is_default_value_compatible(
@@ -82,10 +78,10 @@ def _is_default_value_compatible(
   if (
       isinstance(annotation, _GenericAlias)
       or isinstance(annotation, builtin_types.GenericAlias)
-      or isinstance(annotation, UnionType)
+      or isinstance(annotation, VersionedUnionType)
   ):
     origin = get_origin(annotation)
-    if origin in (Union, UnionType):
+    if origin in (Union, VersionedUnionType):
       return any(
           _is_default_value_compatible(default_value, arg)
           for arg in get_args(annotation)
@@ -141,7 +137,7 @@ def _parse_schema_from_parameter(
     _raise_if_schema_unsupported(client, schema)
     return schema
   if (
-      isinstance(param.annotation, UnionType)
+      isinstance(param.annotation, VersionedUnionType)
       # only parse simple UnionType, example int | str | float | bool
       # complex UnionType will be invoked in raise branch
       and all(
@@ -229,7 +225,11 @@ def _parse_schema_from_parameter(
       schema.type = 'OBJECT'
       unique_types = set()
       for arg in args:
-        if arg.__name__ == 'NoneType':  # Optional type
+        # The first check is for NoneType in Python 3.9, since the __name__
+        # attribute is not available in Python 3.9
+        if type(arg) is type(None) or (
+            hasattr(arg, '__name__') and arg.__name__ == 'NoneType'
+        ):  # Optional type
           schema.nullable = True
           continue
         schema_in_any_of = _parse_schema_from_parameter(
@@ -272,9 +272,8 @@ def _parse_schema_from_parameter(
       return schema
       # all other generic alias will be invoked in raise branch
   if (
-      inspect.isclass(param.annotation)
       # for user defined class, we only support pydantic model
-      and issubclass(param.annotation, pydantic.BaseModel)
+      _extra_utils.is_annotation_pydantic_model(param.annotation)
   ):
     if (
         param.default is not inspect.Parameter.empty

{google_genai-0.7.0 → google_genai-1.0.0}/google/genai/_common.py

@@ -18,14 +18,17 @@
 import base64
 import datetime
 import enum
+import functools
 import typing
 from typing import Union
 import uuid
+import warnings
 
 import pydantic
 from pydantic import alias_generators
 
 from . import _api_client
+from . import errors
 
 
 def set_value_by_path(data, keys, value):
@@ -213,8 +216,16 @@ class CaseInSensitiveEnum(str, enum.Enum):
     except KeyError:
       try:
         return cls[value.lower()]  # Try to access directly with lowercase
-      except KeyError as e:
-        raise ValueError(f"{value} is not a valid {cls.__name__}") from e
+      except KeyError:
+        warnings.warn(f"{value} is not a valid {cls.__name__}")
+        try:
+          # Creating a enum instance based on the value
+          unknown_enum_val = cls._new_member_(cls)  # pylint: disable=protected-access,attribute-error
+          unknown_enum_val._name_ = str(value)  # pylint: disable=protected-access
+          unknown_enum_val._value_ = value  # pylint: disable=protected-access
+          return unknown_enum_val
+        except:
+          return None
 
 
 def timestamped_unique_name() -> str:
@@ -264,3 +275,23 @@ def encode_unserializable_types(data: dict[str, object]) -> dict[str, object]:
     else:
       processed_data[key] = value
   return processed_data
+
+
+def experimental_warning(message: str):
+  """Experimental warning, only warns once."""
+  def decorator(func):
+    warning_done = False
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+      nonlocal warning_done
+      if not warning_done:
+        warning_done = True
+        warnings.warn(
+            message=message,
+            category=errors.ExperimentalWarning,
+            stacklevel=2,
+        )
+      return func(*args, **kwargs)
+    return wrapper
+  return decorator
+