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

google/genai/types.py

@@ -22,9 +22,10 @@ import json
 import logging
 import sys
 import typing
-from typing import Any, Callable, GenericAlias, Literal, Optional, Type, TypedDict, Union
+from typing import Any, Callable, GenericAlias, Literal, Optional, Union
 import pydantic
 from pydantic import Field
+from typing_extensions import TypedDict
 from . import _common
 
 if sys.version_info >= (3, 10):
@@ -43,7 +44,7 @@ if typing.TYPE_CHECKING:
   PIL_Image = PIL.Image.Image
   _is_pillow_image_imported = True
 else:
-  PIL_Image: Type = Any
+  PIL_Image: typing.Type = Any
   try:
     import PIL.Image
 
@@ -52,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."""
@@ -690,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."""
 
@@ -1592,7 +1654,7 @@ class File(_common.BaseModel):
   )
   expiration_time: Optional[datetime.datetime] = Field(
       default=None,
-      description="""Optional. The human-readable display name for the `File`. The display name must be no more than 512 characters in length, including spaces. Example: 'Welcome Image'""",
+      description="""Output only. The timestamp of when the `File` will be deleted. Only set if the `File` is scheduled to expire.""",
   )
   update_time: Optional[datetime.datetime] = Field(
       default=None,
@@ -1643,7 +1705,7 @@ class FileDict(TypedDict, total=False):
   """Output only. The timestamp of when the `File` was created."""
 
   expiration_time: Optional[datetime.datetime]
-  """Optional. The human-readable display name for the `File`. The display name must be no more than 512 characters in length, including spaces. Example: 'Welcome Image'"""
+  """Output only. The timestamp of when the `File` will be deleted. Only set if the `File` is scheduled to expire."""
 
   update_time: Optional[datetime.datetime]
   """Output only. The timestamp of when the `File` was last updated."""
@@ -2849,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.'
@@ -2863,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:
@@ -2883,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.'
       )
@@ -2895,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]
@@ -4834,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.1.0' # x-release-please-version
+__version__ = '1.3.0' # x-release-please-version