google-genai 0.3.0__tar.gz → 0.5.0__tar.gz

{google_genai-0.3.0/google_genai.egg-info → google_genai-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: google-genai
-Version: 0.3.0
+Version: 0.5.0
 Summary: GenAI Python SDK
 Author-email: Google LLC <googleapis-packages@google.com>
 License: Apache-2.0
@@ -436,10 +436,10 @@ response1 = client.models.generate_image(
     model='imagen-3.0-generate-001',
     prompt='An umbrella in the foreground, and a rainy night sky in the background',
     config=types.GenerateImageConfig(
-        negative_prompt= "human",
+        negative_prompt= 'human',
         number_of_images= 1,
         include_rai_reason= True,
-        output_mime_type= "image/jpeg"
+        output_mime_type= 'image/jpeg'
     )
 )
 response1.generated_images[0].image.show()
@@ -454,7 +454,11 @@ Upscale image is not supported in Google AI.
 response2 = client.models.upscale_image(
     model='imagen-3.0-generate-001',
     image=response1.generated_images[0].image,
-    config=types.UpscaleImageConfig(upscale_factor="x2")
+    upscale_factor='x2',
+    config=types.UpscaleImageConfig(
+        include_rai_reason= True,
+        output_mime_type= 'image/jpeg',
+    ),
 )
 response2.generated_images[0].image.show()
 ```
@@ -497,6 +501,42 @@ response3 = client.models.edit_image(
 response3.generated_images[0].image.show()
 ```
 
+## Chats
+
+Create a chat session to start a multi-turn conversations with the model.
+
+### Send Message
+
+```python
+chat = client.chats.create(model='gemini-2.0-flash-exp')
+response = chat.send_message('tell me a story')
+print(response.text)
+```
+
+### Streaming
+
+```python
+chat = client.chats.create(model='gemini-2.0-flash-exp')
+for chunk in chat.send_message_stream('tell me a story'):
+  print(chunk.text)
+```
+
+### Async
+
+```python
+chat = client.aio.chats.create(model='gemini-2.0-flash-exp')
+response = await chat.send_message('tell me a story')
+print(response.text)
+```
+
+### Async Streaming
+
+```python
+chat = client.aio.chats.create(model='gemini-2.0-flash-exp')
+async for chunk in chat.send_message_stream('tell me a story'):
+  print(chunk.text)
+```
+
 ## Files (Only Google AI)
 
 ``` python
@@ -539,19 +579,19 @@ else:
 
 cached_content = client.caches.create(
       model='gemini-1.5-pro-002',
-      contents=[
-          types.Content(
-              role='user',
-              parts=[
-                types.Part.from_uri(
-                    file_uri=file_uris[0],
-                    mime_type='application/pdf'),
-                types.Part.from_uri(
-                    file_uri=file_uris[1],
-                    mime_type='application/pdf',)])
-      ],
-      system_instruction='What is the sum of the two pdfs?',
       config=types.CreateCachedContentConfig(
+          contents=[
+              types.Content(
+                  role='user',
+                  parts=[
+                    types.Part.from_uri(
+                        file_uri=file_uris[0],
+                        mime_type='application/pdf'),
+                    types.Part.from_uri(
+                        file_uri=file_uris[1],
+                        mime_type='application/pdf',)])
+          ],
+          system_instruction='What is the sum of the two pdfs?',
           display_name='test cache',
           ttl='3600s',
       ),

{google_genai-0.3.0 → google_genai-0.5.0}/README.md

@@ -408,10 +408,10 @@ response1 = client.models.generate_image(
     model='imagen-3.0-generate-001',
     prompt='An umbrella in the foreground, and a rainy night sky in the background',
     config=types.GenerateImageConfig(
-        negative_prompt= "human",
+        negative_prompt= 'human',
         number_of_images= 1,
         include_rai_reason= True,
-        output_mime_type= "image/jpeg"
+        output_mime_type= 'image/jpeg'
     )
 )
 response1.generated_images[0].image.show()
@@ -426,7 +426,11 @@ Upscale image is not supported in Google AI.
 response2 = client.models.upscale_image(
     model='imagen-3.0-generate-001',
     image=response1.generated_images[0].image,
-    config=types.UpscaleImageConfig(upscale_factor="x2")
+    upscale_factor='x2',
+    config=types.UpscaleImageConfig(
+        include_rai_reason= True,
+        output_mime_type= 'image/jpeg',
+    ),
 )
 response2.generated_images[0].image.show()
 ```
@@ -469,6 +473,42 @@ response3 = client.models.edit_image(
 response3.generated_images[0].image.show()
 ```
 
+## Chats
+
+Create a chat session to start a multi-turn conversations with the model.
+
+### Send Message
+
+```python
+chat = client.chats.create(model='gemini-2.0-flash-exp')
+response = chat.send_message('tell me a story')
+print(response.text)
+```
+
+### Streaming
+
+```python
+chat = client.chats.create(model='gemini-2.0-flash-exp')
+for chunk in chat.send_message_stream('tell me a story'):
+  print(chunk.text)
+```
+
+### Async
+
+```python
+chat = client.aio.chats.create(model='gemini-2.0-flash-exp')
+response = await chat.send_message('tell me a story')
+print(response.text)
+```
+
+### Async Streaming
+
+```python
+chat = client.aio.chats.create(model='gemini-2.0-flash-exp')
+async for chunk in chat.send_message_stream('tell me a story'):
+  print(chunk.text)
+```
+
 ## Files (Only Google AI)
 
 ``` python
@@ -511,19 +551,19 @@ else:
 
 cached_content = client.caches.create(
       model='gemini-1.5-pro-002',
-      contents=[
-          types.Content(
-              role='user',
-              parts=[
-                types.Part.from_uri(
-                    file_uri=file_uris[0],
-                    mime_type='application/pdf'),
-                types.Part.from_uri(
-                    file_uri=file_uris[1],
-                    mime_type='application/pdf',)])
-      ],
-      system_instruction='What is the sum of the two pdfs?',
       config=types.CreateCachedContentConfig(
+          contents=[
+              types.Content(
+                  role='user',
+                  parts=[
+                    types.Part.from_uri(
+                        file_uri=file_uris[0],
+                        mime_type='application/pdf'),
+                    types.Part.from_uri(
+                        file_uri=file_uris[1],
+                        mime_type='application/pdf',)])
+          ],
+          system_instruction='What is the sum of the two pdfs?',
           display_name='test cache',
           ttl='3600s',
       ),

{google_genai-0.3.0 → google_genai-0.5.0}/google/genai/__init__.py

@@ -16,7 +16,8 @@
 """Google Gen AI SDK"""
 
 from .client import Client
+from . import  version
 
-__version__ = '0.3.0'
+__version__ = version.__version__
 
 __all__ = ['Client']

{google_genai-0.3.0 → google_genai-0.5.0}/google/genai/_api_client.py

@@ -21,37 +21,74 @@ import copy
 from dataclasses import dataclass
 import datetime
 import json
+import logging
 import os
 import sys
-from typing import Any, Optional, TypedDict, Union
+from typing import Any, Optional, Tuple, TypedDict, Union
 from urllib.parse import urlparse, urlunparse
 
 import google.auth
 import google.auth.credentials
 from google.auth.transport.requests import AuthorizedSession
-from pydantic import BaseModel
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
 import requests
 
 from . import errors
+from . import version
 
 
-class HttpOptions(TypedDict):
+class HttpOptions(BaseModel):
+  """HTTP options for the api client."""
+  model_config = ConfigDict(extra='forbid')
+
+  base_url: Optional[str] = Field(
+      default=None,
+      description="""The base URL for the AI platform service endpoint.""",
+  )
+  api_version: Optional[str] = Field(
+      default=None,
+      description="""Specifies the version of the API to use.""",
+  )
+  headers: Optional[dict[str, str]] = Field(
+      default=None,
+      description="""Additional HTTP headers to be sent with the request.""",
+  )
+  response_payload: Optional[dict] = Field(
+      default=None,
+      description="""If set, the response payload will be returned int the supplied dict.""",
+  )
+  timeout: Optional[Union[float, Tuple[float, float]]] = Field(
+      default=None,
+      description="""Timeout for the request in seconds.""",
+  )
+  skip_project_and_location_in_path: bool = Field(
+      default=False,
+      description="""If set to True, the project and location will not be appended to the path.""",
+  )
+
+
+class HttpOptionsDict(TypedDict):
   """HTTP options for the api client."""
 
-  base_url: str = None
+  base_url: Optional[str] = None
   """The base URL for the AI platform service endpoint."""
-  api_version: str = None
+  api_version: Optional[str] = None
   """Specifies the version of the API to use."""
-  headers: dict[str, dict] = None
+  headers: Optional[dict[str, str]] = None
   """Additional HTTP headers to be sent with the request."""
-  response_payload: dict = None
+  response_payload: Optional[dict] = None
   """If set, the response payload will be returned int the supplied dict."""
+  timeout: Optional[Union[float, Tuple[float, float]]] = None
+  """Timeout for the request in seconds."""
+  skip_project_and_location_in_path: bool = False
+  """If set to True, the project and location will not be appended to the path."""
+
+HttpOptionsOrDict = Union[HttpOptions, HttpOptionsDict]
 
 
 def _append_library_version_headers(headers: dict[str, str]) -> None:
   """Appends the telemetry header to the headers dict."""
-  # TODO: Automate revisions to the SDK library version.
-  library_label = f'google-genai-sdk/0.3.0'
+  library_label = f'google-genai-sdk/{version.__version__}'
   language_label = 'gl-python/' + sys.version.split()[0]
   version_header_value = f'{library_label} {language_label}'
   if (
@@ -71,20 +108,24 @@ def _append_library_version_headers(headers: dict[str, str]) -> None:
 
 
 def _patch_http_options(
-    options: HttpOptions, patch_options: HttpOptions
-) -> HttpOptions:
+    options: HttpOptionsDict, patch_options: HttpOptionsDict
+) -> HttpOptionsDict:
   # use shallow copy so we don't override the original objects.
-  copy_option = HttpOptions()
+  copy_option = HttpOptionsDict()
   copy_option.update(options)
-  for k, v in patch_options.items():
+  for patch_key, patch_value in patch_options.items():
     # if both are dicts, update the copy.
     # This is to handle cases like merging headers.
-    if isinstance(v, dict) and isinstance(copy_option.get(k, None), dict):
-      copy_option[k] = {}
-      copy_option[k].update(options[k])  # shallow copy from original options.
-      copy_option[k].update(v)
-    elif v is not None:  # Accept empty values.
-      copy_option[k] = v
+    if isinstance(patch_value, dict) and isinstance(
+        copy_option.get(patch_key, None), dict
+    ):
+      copy_option[patch_key] = {}
+      copy_option[patch_key].update(
+          options[patch_key]
+      )  # shallow copy from original options.
+      copy_option[patch_key].update(patch_value)
+    elif patch_value is not None:  # Accept empty values.
+      copy_option[patch_key] = patch_value
   _append_library_version_headers(copy_option['headers'])
   return copy_option
 
@@ -102,6 +143,7 @@ class HttpRequest:
   url: str
   method: str
   data: Union[dict[str, object], bytes]
+  timeout: Optional[Union[float, Tuple[float, float]]] = None
 
 
 class HttpResponse:
@@ -147,7 +189,7 @@ class ApiClient:
       credentials: google.auth.credentials.Credentials = None,
       project: Union[str, None] = None,
       location: Union[str, None] = None,
-      http_options: HttpOptions = None,
+      http_options: HttpOptionsOrDict = None,
   ):
     self.vertexai = vertexai
     if self.vertexai is None:
@@ -159,30 +201,84 @@ class ApiClient:
 
     # Validate explicitly set intializer values.
     if (project or location) and api_key:
+      # API cannot consume both project/location and api_key.
       raise ValueError(
           'Project/location and API key are mutually exclusive in the client initializer.'
       )
+    elif credentials and api_key:
+      # API cannot consume both credentials and api_key.
+      raise ValueError(
+          'Credentials and API key are mutually exclusive in the client initializer.'
+      )
+
+    # Validate http_options if a dict is provided.
+    if isinstance(http_options, dict):
+      try:
+        HttpOptions.model_validate(http_options)
+      except ValidationError as e:
+        raise ValueError(f'Invalid http_options: {e}')
+    elif(isinstance(http_options, HttpOptions)):
+      http_options = http_options.model_dump()
+
+    # 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 = os.environ.get('GOOGLE_API_KEY', None)
+    self.project = project or env_project
+    self.location = location or env_location
+    self.api_key = api_key or env_api_key
 
-    self.api_key: Optional[str] = None
-    self.project = project or os.environ.get('GOOGLE_CLOUD_PROJECT', None)
-    self.location = location or os.environ.get('GOOGLE_CLOUD_LOCATION', None)
     self._credentials = credentials
-    self._http_options = HttpOptions()
+    self._http_options = HttpOptionsDict()
 
+    # Handle when to use Vertex AI in express mode (api key).
+    # Explicit initializer arguments are already validated above.
     if self.vertexai:
-      if not self.project:
+      if credentials:
+        # Explicit credentials take precedence over implicit api_key.
+        logging.info(
+            'The user provided Google Cloud credentials will take precedence'
+            + ' over the API key from the environment variable.'
+        )
+        self.api_key = None
+      elif (env_location or env_project) and api_key:
+        # Explicit api_key takes precedence over implicit project/location.
+        logging.info(
+            'The user provided Vertex AI API key will take precedence over the'
+            + ' project/location from the environment variables.'
+        )
+        self.project = None
+        self.location = None
+      elif (project or location) and env_api_key:
+        # Explicit project/location takes precedence over implicit api_key.
+        logging.info(
+            'The user provided project/location will take precedence over the'
+            + ' Vertex AI API key from the environment variable.'
+        )
+        self.api_key = None
+      elif (env_location or env_project) and env_api_key:
+        # Implicit project/location takes precedence over implicit api_key.
+        logging.info(
+            'The project/location from the environment variables will take'
+            + ' precedence over the API key from the environment variables.'
+        )
+        self.api_key = None
+      if not self.project and not self.api_key:
         self.project = google.auth.default()[1]
-      # Will change this to support EasyGCP in the future.
-      if not self.project or not self.location:
+      if not (self.project or self.location) and not self.api_key:
         raise ValueError(
-            'Project and location must be set when using the Vertex AI API.'
+            'Project/location or API key must be set when using the Vertex AI API.'
+        )
+      if self.api_key:
+        self._http_options['base_url'] = (
+            f'https://aiplatform.googleapis.com/'
+        )
+      else:
+        self._http_options['base_url'] = (
+            f'https://{self.location}-aiplatform.googleapis.com/'
         )
-      self._http_options['base_url'] = (
-          f'https://{self.location}-aiplatform.googleapis.com/'
-      )
       self._http_options['api_version'] = 'v1beta1'
     else:  # ML Dev API
-      self.api_key = api_key or os.environ.get('GOOGLE_API_KEY', None)
       if not self.api_key:
         raise ValueError('API key must be set when using the Google AI API.')
       self._http_options['base_url'] = (
@@ -191,7 +287,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:
+    if self.api_key and not self.vertexai:
       self._http_options['headers']['x-goog-api-key'] = self.api_key
     # Update the http options with the user provided http options.
     if http_options:
@@ -208,7 +304,7 @@ class ApiClient:
       http_method: str,
       path: str,
       request_dict: dict[str, object],
-      http_options: HttpOptions = None,
+      http_options: HttpOptionsDict = None,
   ) -> HttpRequest:
     # Remove all special dict keys such as _url and _query.
     keys_to_delete = [key for key in request_dict.keys() if key.startswith('_')]
@@ -221,8 +317,18 @@ class ApiClient:
       )
     else:
       patched_http_options = self._http_options
-    if self.vertexai and not path.startswith('projects/'):
+    skip_project_and_location_in_path_val = patched_http_options.get(
+        'skip_project_and_location_in_path', False
+    )
+    if (
+        self.vertexai
+        and not path.startswith('projects/')
+        and not skip_project_and_location_in_path_val
+        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,
@@ -232,6 +338,7 @@ class ApiClient:
         url=url,
         headers=patched_http_options['headers'],
         data=request_dict,
+        timeout=patched_http_options.get('timeout', None),
     )
 
   def _request(
@@ -239,7 +346,7 @@ class ApiClient:
       http_request: HttpRequest,
       stream: bool = False,
   ) -> HttpResponse:
-    if self.vertexai:
+    if self.vertexai and not self.api_key:
       if not self._credentials:
         self._credentials, _ = google.auth.default(
             scopes=["https://www.googleapis.com/auth/cloud-platform"],
@@ -250,10 +357,10 @@ class ApiClient:
           http_request.method.upper(),
           http_request.url,
           headers=http_request.headers,
-          data=json.dumps(http_request.data, cls=RequestJsonEncoder) if http_request.data else None,
-          # TODO: support timeout in RequestOptions so it can be configured
-          # per methods.
-          timeout=None,
+          data=json.dumps(http_request.data, cls=RequestJsonEncoder)
+          if http_request.data
+          else None,
+          timeout=http_request.timeout,
       )
       errors.APIError.raise_for_response(response)
       return HttpResponse(
@@ -275,13 +382,14 @@ class ApiClient:
         data = http_request.data
 
     http_session = requests.Session()
-    request = requests.Request(
+    response = http_session.request(
         method=http_request.method,
         url=http_request.url,
         headers=http_request.headers,
         data=data,
-    ).prepare()
-    response = http_session.send(request, stream=stream)
+        timeout=http_request.timeout,
+        stream=stream,
+    )
     errors.APIError.raise_for_response(response)
     return HttpResponse(
         response.headers, response if stream else [response.text]
@@ -307,8 +415,10 @@ class ApiClient:
           stream=stream,
       )
 
-  def get_read_only_http_options(self) -> HttpOptions:
-    copied = HttpOptions()
+  def get_read_only_http_options(self) -> HttpOptionsDict:
+    copied = HttpOptionsDict()
+    if isinstance(self._http_options, BaseModel):
+      self._http_options = self._http_options.model_dump()
     copied.update(self._http_options)
     return copied
 
@@ -317,7 +427,7 @@ class ApiClient:
       http_method: str,
       path: str,
       request_dict: dict[str, object],
-      http_options: HttpOptions = None,
+      http_options: HttpOptionsDict = None,
   ):
     http_request = self._build_request(
         http_method, path, request_dict, http_options
@@ -332,7 +442,7 @@ class ApiClient:
       http_method: str,
       path: str,
       request_dict: dict[str, object],
-      http_options: HttpOptions = None,
+      http_options: HttpOptionsDict = None,
   ):
     http_request = self._build_request(
         http_method, path, request_dict, http_options
@@ -349,7 +459,7 @@ class ApiClient:
       http_method: str,
       path: str,
       request_dict: dict[str, object],
-      http_options: HttpOptions = None,
+      http_options: HttpOptionsDict = None,
   ) -> dict[str, object]:
     http_request = self._build_request(
         http_method, path, request_dict, http_options
@@ -365,7 +475,7 @@ class ApiClient:
       http_method: str,
       path: str,
       request_dict: dict[str, object],
-      http_options: HttpOptions = None,
+      http_options: HttpOptionsDict = None,
   ):
     http_request = self._build_request(
         http_method, path, request_dict, http_options
@@ -464,13 +574,12 @@ class ApiClient:
     pass
 
 
+# TODO(b/389693448): Cleanup datetime hacks.
 class RequestJsonEncoder(json.JSONEncoder):
   """Encode bytes as strings without modify its content."""
 
   def default(self, o):
-    if isinstance(o, bytes):
-      return o.decode()
-    elif isinstance(o, datetime.datetime):
+    if isinstance(o, datetime.datetime):
       # This Zulu time format is used by the Vertex AI API and the test recorder
       # Using strftime works well, but we want to align with the replay encoder.
       # o.astimezone(datetime.timezone.utc).strftime('%Y-%m-%dT%H:%M:%S.%fZ')