google-genai 1.2.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

google/genai/types.py

@@ -53,6 +53,8 @@ else:
   except ImportError:
     PIL_Image = None
 
+logger = logging.getLogger('google_genai.types')
+
 
 class Outcome(_common.CaseInSensitiveEnum):
   """Required. Outcome of the code execution."""
@@ -691,6 +693,65 @@ class Content(_common.BaseModel):
   )
 
 
+class UserContent(Content):
+  """UserContent facilitates the creation of a Content object with a user role.
+
+  Example usages:
+
+
+  - Create a user Content object with a string:
+    user_content = UserContent("Why is the sky blue?")
+  - Create a user Content object with a file data Part object:
+    user_content = UserContent(Part.from_uri(file_uril="gs://bucket/file.txt",
+    mime_type="text/plain"))
+  - Create a user Content object with byte data Part object:
+    user_content = UserContent(Part.from_bytes(data=b"Hello, World!",
+    mime_type="text/plain"))
+
+    You can create a user Content object using other classmethods in the Part
+    class as well.
+    You can also create a user Content using a list of Part objects or strings.
+  """
+
+  role: Literal['user'] = Field(default='user', init=False, frozen=True)
+  parts: list[Part] = Field(init=False)
+
+  @pydantic.field_validator('parts', mode='before')
+  def validate_parts(cls, value):
+    from . import _transformers as t
+
+    return t.t_parts(None, parts=value)
+
+
+class ModelContent(Content):
+  """ModelContent facilitates the creation of a Content object with a model role.
+
+  Example usages:
+
+  - Create a model Content object with a string:
+    model_content = ModelContent("Why is the sky blue?")
+  - Create a model Content object with a file data Part object:
+    model_content = ModelContent(Part.from_uri(file_uril="gs://bucket/file.txt",
+    mime_type="text/plain"))
+  - Create a model Content object with byte data Part object:
+    model_content = ModelContent(Part.from_bytes(data=b"Hello, World!",
+    mime_type="text/plain"))
+
+    You can create a model Content object using other classmethods in the Part
+    class as well.
+    You can also create a model Content using a list of Part objects or strings.
+  """
+
+  role: Literal['model'] = Field(default='model', init=False, frozen=True)
+  parts: list[Part] = Field(init=False)
+
+  @pydantic.field_validator('parts', mode='before')
+  def validate_parts(cls, value):
+    from . import _transformers as t
+
+    return t.t_parts(None, parts=value)
+
+
 class ContentDict(TypedDict, total=False):
   """Contains the multi-part content of a message."""
 
@@ -2850,7 +2911,7 @@ class GenerateContentResponse(_common.BaseModel):
     ):
       return None
     if len(self.candidates) > 1:
-      logging.warning(
+      logger.warning(
           f'there are {len(self.candidates)} candidates, returning text from'
           ' the first candidate.Access response.candidates directly to get'
           ' text from other candidates.'
@@ -2864,7 +2925,7 @@ class GenerateContentResponse(_common.BaseModel):
         if field_value is not None:
           raise ValueError(
               'GenerateContentResponse.text only supports text parts, but got'
-              f' {field_name} part{part}'
+              f' {field_name} part'
           )
       if isinstance(part.text, str):
         if isinstance(part.thought, bool) and part.thought:
@@ -2884,7 +2945,7 @@ class GenerateContentResponse(_common.BaseModel):
     ):
       return None
     if len(self.candidates) > 1:
-      logging.warning(
+      logger.warning(
           'Warning: there are multiple candidates in the response, returning'
           ' function calls from the first one.'
       )
@@ -2896,6 +2957,44 @@ class GenerateContentResponse(_common.BaseModel):
 
     return function_calls if function_calls else None
 
+  @property
+  def executable_code(self) -> Optional[str]:
+    """Returns the executable code in the response."""
+    if (
+        not self.candidates
+        or not self.candidates[0].content
+        or not self.candidates[0].content.parts
+    ):
+      return None
+    if len(self.candidates) > 1:
+      logging.warning(
+          'Warning: there are multiple candidates in the response, returning'
+          ' executable code from the first one.'
+      )
+    for part in self.candidates[0].content.parts:
+      if part.executable_code is not None:
+        return part.executable_code.code
+    return None
+
+  @property
+  def code_execution_result(self) -> Optional[str]:
+    """Returns the code execution result in the response."""
+    if (
+        not self.candidates
+        or not self.candidates[0].content
+        or not self.candidates[0].content.parts
+    ):
+      return None
+    if len(self.candidates) > 1:
+      logging.warning(
+          'Warning: there are multiple candidates in the response, returning'
+          ' code execution result from the first one.'
+      )
+    for part in self.candidates[0].content.parts:
+      if part.code_execution_result is not None:
+        return part.code_execution_result.output
+    return None
+
   @classmethod
   def _from_response(
       cls, *, response: dict[str, object], kwargs: dict[str, object]
@@ -4835,6 +4934,338 @@ ComputeTokensResponseOrDict = Union[
 ]
 
 
+class GenerateVideosConfig(_common.BaseModel):
+  """Configuration for generating videos."""
+
+  http_options: Optional[HttpOptions] = Field(
+      default=None, description="""Used to override HTTP request options."""
+  )
+  number_of_videos: Optional[int] = Field(
+      default=None, description="""Number of output videos."""
+  )
+  output_gcs_uri: Optional[str] = Field(
+      default=None,
+      description="""The gcs bucket where to save the generated videos.""",
+  )
+  fps: Optional[int] = Field(
+      default=None, description="""Frames per second for video generation."""
+  )
+  duration_seconds: Optional[int] = Field(
+      default=None,
+      description="""Duration of the clip for video generation in seconds.""",
+  )
+  seed: Optional[int] = Field(
+      default=None,
+      description="""The RNG seed. If RNG seed is exactly same for each request with unchanged inputs, the prediction results will be consistent. Otherwise, a random RNG seed will be used each time to produce a different result.""",
+  )
+  aspect_ratio: Optional[str] = Field(
+      default=None,
+      description="""The aspect ratio for the generated video. 16:9 (landscape) and 9:16 (portrait) are supported.""",
+  )
+  resolution: Optional[str] = Field(
+      default=None,
+      description="""The resolution for the generated video. 1280x720, 1920x1080 are supported.""",
+  )
+  person_generation: Optional[str] = Field(
+      default=None,
+      description="""Whether allow to generate person videos, and restrict to specific ages. Supported values are: dont_allow, allow_adult.""",
+  )
+  pubsub_topic: Optional[str] = Field(
+      default=None,
+      description="""The pubsub topic where to publish the video generation progress.""",
+  )
+  negative_prompt: Optional[str] = Field(
+      default=None,
+      description="""Optional field in addition to the text content. Negative prompts can be explicitly stated here to help generate the video.""",
+  )
+  enhance_prompt: Optional[bool] = Field(
+      default=None, description="""Whether to use the prompt rewriting logic."""
+  )
+
+
+class GenerateVideosConfigDict(TypedDict, total=False):
+  """Configuration for generating videos."""
+
+  http_options: Optional[HttpOptionsDict]
+  """Used to override HTTP request options."""
+
+  number_of_videos: Optional[int]
+  """Number of output videos."""
+
+  output_gcs_uri: Optional[str]
+  """The gcs bucket where to save the generated videos."""
+
+  fps: Optional[int]
+  """Frames per second for video generation."""
+
+  duration_seconds: Optional[int]
+  """Duration of the clip for video generation in seconds."""
+
+  seed: Optional[int]
+  """The RNG seed. If RNG seed is exactly same for each request with unchanged inputs, the prediction results will be consistent. Otherwise, a random RNG seed will be used each time to produce a different result."""
+
+  aspect_ratio: Optional[str]
+  """The aspect ratio for the generated video. 16:9 (landscape) and 9:16 (portrait) are supported."""
+
+  resolution: Optional[str]
+  """The resolution for the generated video. 1280x720, 1920x1080 are supported."""
+
+  person_generation: Optional[str]
+  """Whether allow to generate person videos, and restrict to specific ages. Supported values are: dont_allow, allow_adult."""
+
+  pubsub_topic: Optional[str]
+  """The pubsub topic where to publish the video generation progress."""
+
+  negative_prompt: Optional[str]
+  """Optional field in addition to the text content. Negative prompts can be explicitly stated here to help generate the video."""
+
+  enhance_prompt: Optional[bool]
+  """Whether to use the prompt rewriting logic."""
+
+
+GenerateVideosConfigOrDict = Union[
+    GenerateVideosConfig, GenerateVideosConfigDict
+]
+
+
+class _GenerateVideosParameters(_common.BaseModel):
+  """Class that represents the parameters for generating an image."""
+
+  model: Optional[str] = Field(
+      default=None,
+      description="""ID of the model to use. For a list of models, see `Google models
+    <https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models>`_.""",
+  )
+  prompt: Optional[str] = Field(
+      default=None,
+      description="""The text prompt for generating the videos. Optional for image to video use cases.""",
+  )
+  config: Optional[GenerateVideosConfig] = Field(
+      default=None, description="""Configuration for generating videos."""
+  )
+
+
+class _GenerateVideosParametersDict(TypedDict, total=False):
+  """Class that represents the parameters for generating an image."""
+
+  model: Optional[str]
+  """ID of the model to use. For a list of models, see `Google models
+    <https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models>`_."""
+
+  prompt: Optional[str]
+  """The text prompt for generating the videos. Optional for image to video use cases."""
+
+  config: Optional[GenerateVideosConfigDict]
+  """Configuration for generating videos."""
+
+
+_GenerateVideosParametersOrDict = Union[
+    _GenerateVideosParameters, _GenerateVideosParametersDict
+]
+
+
+class Video(_common.BaseModel):
+  """A generated video."""
+
+  uri: Optional[str] = Field(
+      default=None, description="""Path to another storage."""
+  )
+  video_bytes: Optional[bytes] = Field(
+      default=None, description="""Video bytes."""
+  )
+  mime_type: Optional[str] = Field(
+      default=None, description="""Video encoding, for example "video/mp4"."""
+  )
+
+  def save(
+      self,
+      path: str,
+      # *,
+      # client: Optional[ApiClient] = None,
+  ) -> None:
+    """Saves the video to a file.
+
+    Args:
+        path: Local path where to save the video.
+    """
+    import pathlib  # pylint: disable=g-import-not-at-top
+
+    if not self.data:
+      raise NotImplementedError('Saving remote videos is not supported.')
+      if not self.uri:
+        raise ValueError('No data or uri provided.')
+      if not client:
+        raise ValueError('Client is required to save remote videos.')
+      self.data = client.files.download(self.uri)
+
+    pathlib.Path(path).write_bytes(self.data)
+
+  def show(self):
+    """Shows the video.
+
+    This method only works in a notebook environment.
+    """
+    if self.uri:
+      return ValueError('Showing remote videos is not supported.')
+    if not self.video_bytes:
+      return ValueError('Video has no bytes.')
+    if not self.mime_type:
+      return ValueError('Mime type must be provided to display video.')
+
+    try:
+      from IPython import display as IPython_display
+    except ImportError:
+      IPython_display = None
+
+    if IPython_display:
+      return IPython_display.Video(
+          data=self.video_bytes, mimetype=self.mime_type, embed=True
+      )
+
+  def __repr__(self):
+    video_bytes = '<video_bytes>' if self.video_bytes else 'None'
+    return (
+        f'Video(uri={self.uri}, video_bytes={video_bytes},'
+        f' mime_type={self.mime_type})'
+    )
+
+
+class VideoDict(TypedDict, total=False):
+  """A generated video."""
+
+  uri: Optional[str]
+  """Path to another storage."""
+
+  video_bytes: Optional[bytes]
+  """Video bytes."""
+
+  mime_type: Optional[str]
+  """Video encoding, for example "video/mp4"."""
+
+
+VideoOrDict = Union[Video, VideoDict]
+
+
+class GeneratedVideo(_common.BaseModel):
+  """A generated video."""
+
+  video: Optional[Video] = Field(
+      default=None, description="""The output video"""
+  )
+
+
+class GeneratedVideoDict(TypedDict, total=False):
+  """A generated video."""
+
+  video: Optional[VideoDict]
+  """The output video"""
+
+
+GeneratedVideoOrDict = Union[GeneratedVideo, GeneratedVideoDict]
+
+
+class GenerateVideosResponse(_common.BaseModel):
+  """Response with generated videos."""
+
+  generated_videos: Optional[list[GeneratedVideo]] = Field(
+      default=None, description="""List of the generated videos"""
+  )
+  rai_media_filtered_count: Optional[int] = Field(
+      default=None,
+      description="""Returns if any videos were filtered due to RAI policies.""",
+  )
+  rai_media_filtered_reasons: Optional[list[str]] = Field(
+      default=None, description="""Returns rai failure reasons if any."""
+  )
+
+
+class GenerateVideosResponseDict(TypedDict, total=False):
+  """Response with generated videos."""
+
+  generated_videos: Optional[list[GeneratedVideoDict]]
+  """List of the generated videos"""
+
+  rai_media_filtered_count: Optional[int]
+  """Returns if any videos were filtered due to RAI policies."""
+
+  rai_media_filtered_reasons: Optional[list[str]]
+  """Returns rai failure reasons if any."""
+
+
+GenerateVideosResponseOrDict = Union[
+    GenerateVideosResponse, GenerateVideosResponseDict
+]
+
+
+class GenerateVideosOperation(_common.BaseModel):
+  """A video generation operation.
+
+  Use the following code to refresh the operation:
+
+  ```
+  operation = client.operations.get(operation)
+  ```
+  """
+
+  name: Optional[str] = Field(
+      default=None,
+      description="""The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the `name` should be a resource name ending with `operations/{unique_id}`.""",
+  )
+  metadata: Optional[dict[str, Any]] = Field(
+      default=None,
+      description="""Service-specific metadata associated with the operation. It typically contains progress information and common metadata such as create time. Some services might not provide such metadata.  Any method that returns a long-running operation should document the metadata type, if any.""",
+  )
+  done: Optional[bool] = Field(
+      default=None,
+      description="""If the value is `false`, it means the operation is still in progress. If `true`, the operation is completed, and either `error` or `response` is available.""",
+  )
+  error: Optional[dict[str, Any]] = Field(
+      default=None,
+      description="""The error result of the operation in case of failure or cancellation.""",
+  )
+  response: Optional[dict[str, Any]] = Field(
+      default=None,
+      description="""The normal response of the operation in case of success.""",
+  )
+  result: Optional[GenerateVideosResponse] = Field(
+      default=None, description="""The generated videos."""
+  )
+
+
+class GenerateVideosOperationDict(TypedDict, total=False):
+  """A video generation operation.
+
+  Use the following code to refresh the operation:
+
+  ```
+  operation = client.operations.get(operation)
+  ```
+  """
+
+  name: Optional[str]
+  """The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the `name` should be a resource name ending with `operations/{unique_id}`."""
+
+  metadata: Optional[dict[str, Any]]
+  """Service-specific metadata associated with the operation. It typically contains progress information and common metadata such as create time. Some services might not provide such metadata.  Any method that returns a long-running operation should document the metadata type, if any."""
+
+  done: Optional[bool]
+  """If the value is `false`, it means the operation is still in progress. If `true`, the operation is completed, and either `error` or `response` is available."""
+
+  error: Optional[dict[str, Any]]
+  """The error result of the operation in case of failure or cancellation."""
+
+  response: Optional[dict[str, Any]]
+  """The normal response of the operation in case of success."""
+
+  result: Optional[GenerateVideosResponseDict]
+  """The generated videos."""
+
+
+GenerateVideosOperationOrDict = Union[
+    GenerateVideosOperation, GenerateVideosOperationDict
+]
+
+
 class GetTuningJobConfig(_common.BaseModel):
   """Optional parameters for tunings.get method."""
 

google/genai/version.py

@@ -13,4 +13,4 @@
 # limitations under the License.
 #
 
-__version__ = '1.2.0' # x-release-please-version
+__version__ = '1.3.0' # x-release-please-version

{google_genai-1.2.0.dist-info → google_genai-1.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: google-genai
-Version: 1.2.0
+Version: 1.3.0
 Summary: GenAI Python SDK
 Author-email: Google LLC <googleapis-packages@google.com>
 License: Apache-2.0
@@ -21,6 +21,7 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: google-auth<3.0.0dev,>=2.14.1
+Requires-Dist: httpx<1.0.0dev,>=0.28.1
 Requires-Dist: pydantic<3.0.0dev,>=2.0.0
 Requires-Dist: requests<3.0.0dev,>=2.28.1
 Requires-Dist: websockets<15.0dev,>=13.0
@@ -83,7 +84,7 @@ export GOOGLE_API_KEY='your-api-key'
 and `GOOGLE_CLOUD_LOCATION`, as shown below:
 
 ```bash
-export GOOGLE_GENAI_USE_VERTEXAI=false
+export GOOGLE_GENAI_USE_VERTEXAI=true
 export GOOGLE_CLOUD_PROJECT='your-project-id'
 export GOOGLE_CLOUD_LOCATION='us-central1'
 ```
@@ -94,21 +95,29 @@ client = genai.Client()
 
 ### API Selection
 
+By default, the SDK uses the beta API endpoints provided by Google to support
+preview features in the APIs. The stable API endpoints can be selected by
+setting the API version to `v1`.
+
 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'}
+    vertexai=True,
+    project='your-project-id',
+    location='us-central1',
+    http_options=types.HttpOptions(api_version='v1')
 )
 ```
 
-To set the API version to `v1alpha` for the Gemini API:
+To set the API version to `v1alpha` for the Gemini Developer API:
 
 ```python
-client = genai.Client(api_key='GEMINI_API_KEY',
-                      http_options={'api_version': 'v1alpha'})
+client = genai.Client(
+    api_key='GEMINI_API_KEY',
+    http_options=types.HttpOptions(api_version='v1alpha')
+)
 ```
 
 ## Types
@@ -127,7 +136,7 @@ The `client.models` modules exposes model inferencing and model getters.
 
 ```python
 response = client.models.generate_content(
-    model='gemini-2.0-flash-001', contents='why is the sky blue?'
+    model='gemini-2.0-flash-001', contents='Why is the sky blue?'
 )
 print(response.text)
 ```
@@ -135,7 +144,7 @@ print(response.text)
 #### with uploaded file (Gemini API only)
 download the file in console.
 
-```cmd
+```sh
 !wget -q https://storage.googleapis.com/generativeai-downloads/data/a11.txt
 ```
 
@@ -275,7 +284,7 @@ print(response.text)
 #### Automatic Python function Support
 
 You can pass a Python function directly and it will be automatically
-called and responded.
+called and responded by default.
 
 ```python
 def get_current_weather(location: str) -> str:
@@ -295,6 +304,30 @@ response = client.models.generate_content(
 
 print(response.text)
 ```
+#### Disabling automatic function calling
+If you pass in a python function as a tool directly, and do not want
+automatic function calling, you can disable automatic function calling
+as follows:
+
+```python
+response = client.models.generate_content(
+  model='gemini-2.0-flash-001',
+  contents='What is the weather like in Boston?',
+  config=types.GenerateContentConfig(
+    tools=[get_current_weather],
+    automatic_function_calling=types.AutomaticFunctionCallingConfig(
+      disable=True
+    ),
+  ),
+)
+```
+
+With automatic function calling disabled, you will get a list of function call
+parts in the response:
+
+```python
+function_calls: Optional[List[types.FunctionCall]] = response.function_calls
+```
 
 #### Manually declare and invoke a function for function calling
 
@@ -692,7 +725,6 @@ response1 = client.models.generate_images(
     model='imagen-3.0-generate-002',
     prompt='An umbrella in the foreground, and a rainy night sky in the background',
     config=types.GenerateImagesConfig(
-        negative_prompt='human',
         number_of_images=1,
         include_rai_reason=True,
         output_mime_type='image/jpeg',
@@ -750,7 +782,6 @@ response3 = client.models.edit_image(
     config=types.EditImageConfig(
         edit_mode='EDIT_MODE_INPAINT_INSERTION',
         number_of_images=1,
-        negative_prompt='human',
         include_rai_reason=True,
         output_mime_type='image/jpeg',
     ),
@@ -758,6 +789,34 @@ response3 = client.models.edit_image(
 response3.generated_images[0].image.show()
 ```
 
+### Veo
+
+#### Generate Videos
+
+Support for generate videos in Vertex and Gemini Developer API is behind an allowlist
+
+```python
+# Create operation
+operation = client.models.generate_videos(
+    model='veo-2.0-generate-001',
+    prompt='A neon hologram of a cat driving at top speed',
+    config=types.GenerateVideosConfig(
+        number_of_videos=1,
+        fps=24,
+        duration_seconds=5,
+        enhance_prompt=True,
+    ),
+)
+
+# Poll operation
+while not operation.done:
+    time.sleep(20)
+    operation = client.operations.get(operation)
+
+video = operation.result.generated_videos[0].video
+video.show()
+```
+
 ## Chats
 
 Create a chat session to start a multi-turn conversations with the model.
@@ -1128,3 +1187,20 @@ delete_job = client.batches.delete(name=job.name)
 
 delete_job
 ```
+
+## Error Handling
+
+To handle errors raised by the model service, the SDK provides this [APIError](https://github.com/googleapis/python-genai/blob/main/google/genai/errors.py) class.
+
+```python
+from google.genai import errors
+
+try:
+  client.models.generate_content(
+      model="invalid-model-name",
+      contents="What is your name?",
+  )
+except errors.APIError as e:
+  print(e.code) # 404
+  print(e.message)
+```