google-genai 1.5.0__tar.gz → 1.7.0__tar.gz

{google_genai-1.5.0 → google_genai-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: google-genai
-Version: 1.5.0
+Version: 1.7.0
 Summary: GenAI Python SDK
 Author-email: Google LLC <googleapis-packages@google.com>
 License: Apache-2.0
@@ -20,13 +20,13 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: anyio<5.0.0dev,>=4.8.0
-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
-Requires-Dist: typing-extensions<5.0.0dev,>=4.11.0
+Requires-Dist: anyio<5.0.0,>=4.8.0
+Requires-Dist: google-auth<3.0.0,>=2.14.1
+Requires-Dist: httpx<1.0.0,>=0.28.1
+Requires-Dist: pydantic<3.0.0,>=2.0.0
+Requires-Dist: requests<3.0.0,>=2.28.1
+Requires-Dist: websockets<15.1.0,>=13.0.0
+Requires-Dist: typing-extensions<5.0.0,>=4.11.0
 
 # Google Gen AI SDK
 
@@ -41,7 +41,7 @@ Google Gen AI Python SDK provides an interface for developers to integrate Googl
 
 ## Installation
 
-```cmd
+```sh
 pip install google-genai
 ```
 
@@ -72,16 +72,16 @@ client = genai.Client(
 **(Optional) Using environment variables:**
 
 You can create a client by configuring the necessary environment variables.
-Configuration setup instructions depends on whether you're using the Gemini API
-on Vertex AI or the ML Dev Gemini API.
+Configuration setup instructions depends on whether you're using the Gemini
+Developer API or the Gemini API in Vertex AI.
 
-**ML Dev Gemini API:** Set `GOOGLE_API_KEY` as shown below:
+**Gemini Developer API:** Set `GOOGLE_API_KEY` as shown below:
 
 ```bash
 export GOOGLE_API_KEY='your-api-key'
 ```
 
-**Vertex AI API:** Set `GOOGLE_GENAI_USE_VERTEXAI`, `GOOGLE_CLOUD_PROJECT`
+**Gemini API on Vertex AI:** Set `GOOGLE_GENAI_USE_VERTEXAI`, `GOOGLE_CLOUD_PROJECT`
 and `GOOGLE_CLOUD_LOCATION`, as shown below:
 
 ```bash
@@ -142,7 +142,7 @@ response = client.models.generate_content(
 print(response.text)
 ```
 
-#### with uploaded file (Gemini API only)
+#### with uploaded file (Gemini Developer API only)
 download the file in console.
 
 ```sh
@@ -160,37 +160,203 @@ response = client.models.generate_content(
 print(response.text)
 ```
 
-#### How to structure `contents`
-There are several ways to structure the `contents` in your request.
+#### How to structure `contents` argument for `generate_content`
+The SDK always converts the inputs to the `contents` argument into
+`list[types.Content]`.
+The following shows some common ways to provide your inputs.
+
+##### Provide a `list[types.Content]`
+This is the canonical way to provide contents, SDK will not do any conversion.
+
+##### Provide a `types.Content` instance
+
+```python
+contents = types.Content(
+  role='user',
+  parts=[types.Part.from_text(text='Why is the sky blue?')]
+)
+```
+
+SDK converts this to
+
+```python
+[
+  types.Content(
+    role='user',
+    parts=[types.Part.from_text(text='Why is the sky blue?')]
+  )
+]
+```
+
+##### Provide a string
+
+```python
+contents='Why is the sky blue?'
+```
+
+The SDK will assume this is a text part, and it converts this into the following:
 
-Provide a single string as shown in the text example above:
+```python
+[
+  types.UserContent(
+    parts=[
+      types.Part.from_text(text='Why is the sky blue?')
+    ]
+  )
+]
+```
+
+Where a `types.UserContent` is a subclass of `types.Content`, it sets the
+`role` field to be `user`.
+
+##### Provide a list of string
 
 ```python
-contents='Can you recommend some things to do in Boston and New York in the winter?'
+contents=['Why is the sky blue?', 'Why is the cloud white?']
 ```
 
-Provide a single `Content` instance with multiple `Part` instances:
+The SDK assumes these are 2 text parts, it converts this into a single content,
+like the following:
 
 ```python
-contents=types.Content(parts=[
-    types.Part.from_text(text='Can you recommend some things to do in Boston in the winter?'),
-    types.Part.from_text(text='Can you recommend some things to do in New York in the winter?')
-], role='user')
+[
+  types.UserContent(
+    parts=[
+      types.Part.from_text(text='Why is the sky blue?'),
+      types.Part.from_text(text='Why is the cloud white?'),
+    ]
+  )
+]
 ```
 
-When sending more than one input type, provide a list with multiple `Content`
-instances:
+Where a `types.UserContent` is a subclass of `types.Content`, the
+`role` field in `types.UserContent` is fixed to be `user`.
+
+##### Provide a function call part
 
 ```python
-contents=[
-    'What is this a picture of?',
+contents = types.Part.from_function_call(
+  name='get_weather_by_location',
+  args={'location': 'Boston'}
+)
+```
+
+The SDK converts a function call part to a content with a `model` role:
+
+```python
+[
+  types.ModelContent(
+    parts=[
+      types.Part.from_function_call(
+        name='get_weather_by_location',
+        args={'location': 'Boston'}
+      )
+    ]
+  )
+]
+```
+
+Where a `types.ModelContent` is a subclass of `types.Content`, the
+`role` field in `types.ModelContent` is fixed to be `model`.
+
+##### Provide a list of function call parts
+
+```python
+contents = [
+  types.Part.from_function_call(
+    name='get_weather_by_location',
+    args={'location': 'Boston'}
+  ),
+  types.Part.from_function_call(
+    name='get_weather_by_location',
+    args={'location': 'New York'}
+  ),
+]
+```
+
+The SDK converts a list of function call parts to the a content with a `model` role:
+
+```python
+[
+  types.ModelContent(
+    parts=[
+      types.Part.from_function_call(
+        name='get_weather_by_location',
+        args={'location': 'Boston'}
+      ),
+      types.Part.from_function_call(
+        name='get_weather_by_location',
+        args={'location': 'New York'}
+      )
+    ]
+  )
+]
+```
+
+Where a `types.ModelContent` is a subclass of `types.Content`, the
+`role` field in `types.ModelContent` is fixed to be `model`.
+
+##### Provide a non function call part
+
+```python
+contents = types.Part.from_uri(
+  file_uri: 'gs://generativeai-downloads/images/scones.jpg',
+  mime_type: 'image/jpeg',
+)
+```
+
+The SDK converts all non function call parts into a content with a `user` role.
+
+```python
+[
+  types.UserContent(parts=[
     types.Part.from_uri(
-        file_uri='gs://generativeai-downloads/images/scones.jpg',
-        mime_type='image/jpeg',
-    ),
-],
+     file_uri: 'gs://generativeai-downloads/images/scones.jpg',
+      mime_type: 'image/jpeg',
+    )
+  ])
+]
+```
+
+##### Provide a list of non function call parts
+
+```python
+contents = [
+  types.Part.from_text('What is this image about?'),
+  types.Part.from_uri(
+    file_uri: 'gs://generativeai-downloads/images/scones.jpg',
+    mime_type: 'image/jpeg',
+  )
+]
+```
+
+The SDK will convert the list of parts into a content with a `user` role
+
+```python
+[
+  types.UserContent(
+    parts=[
+      types.Part.from_text('What is this image about?'),
+      types.Part.from_uri(
+        file_uri: 'gs://generativeai-downloads/images/scones.jpg',
+        mime_type: 'image/jpeg',
+      )
+    ]
+  )
+]
 ```
 
+##### Mix types in contents
+
+You can also provide a list of `types.ContentUnion`. The SDK leaves items of
+`types.Content` as is, it groups consecutive non function call parts into a
+single `types.UserContent`, and it groups consecutive function call parts into
+a single `types.ModelContent`.
+
+If you put a list within a list, the inner list can only contain
+`types.PartUnion` items. The SDK will convert the inner list into a single
+`types.UserContent`.
+
 ### System Instructions and Other Configs
 
 The output of the model can be influenced by several optional settings
@@ -481,6 +647,10 @@ response = client.models.generate_content(
 ```
 ### JSON Response Schema
 
+However you define your schema, don't duplicate it in your input prompt,
+including by giving examples of expected JSON output. If you do, the generated
+output might be lower in quality.
+
 #### Pydantic Model Schema support
 
 Schemas can be provided as Pydantic Models.

google_genai-1.5.0/google_genai.egg-info/PKG-INFO → google_genai-1.7.0/README.md

@@ -1,33 +1,3 @@
-Metadata-Version: 2.2
-Name: google-genai
-Version: 1.5.0
-Summary: GenAI Python SDK
-Author-email: Google LLC <googleapis-packages@google.com>
-License: Apache-2.0
-Project-URL: Homepage, https://github.com/googleapis/python-genai
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Internet
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: anyio<5.0.0dev,>=4.8.0
-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
-Requires-Dist: typing-extensions<5.0.0dev,>=4.11.0
-
 # Google Gen AI SDK
 
 [![PyPI version](https://img.shields.io/pypi/v/google-genai.svg)](https://pypi.org/project/google-genai/)
@@ -41,7 +11,7 @@ Google Gen AI Python SDK provides an interface for developers to integrate Googl
 
 ## Installation
 
-```cmd
+```sh
 pip install google-genai
 ```
 
@@ -72,16 +42,16 @@ client = genai.Client(
 **(Optional) Using environment variables:**
 
 You can create a client by configuring the necessary environment variables.
-Configuration setup instructions depends on whether you're using the Gemini API
-on Vertex AI or the ML Dev Gemini API.
+Configuration setup instructions depends on whether you're using the Gemini
+Developer API or the Gemini API in Vertex AI.
 
-**ML Dev Gemini API:** Set `GOOGLE_API_KEY` as shown below:
+**Gemini Developer API:** Set `GOOGLE_API_KEY` as shown below:
 
 ```bash
 export GOOGLE_API_KEY='your-api-key'
 ```
 
-**Vertex AI API:** Set `GOOGLE_GENAI_USE_VERTEXAI`, `GOOGLE_CLOUD_PROJECT`
+**Gemini API on Vertex AI:** Set `GOOGLE_GENAI_USE_VERTEXAI`, `GOOGLE_CLOUD_PROJECT`
 and `GOOGLE_CLOUD_LOCATION`, as shown below:
 
 ```bash
@@ -142,7 +112,7 @@ response = client.models.generate_content(
 print(response.text)
 ```
 
-#### with uploaded file (Gemini API only)
+#### with uploaded file (Gemini Developer API only)
 download the file in console.
 
 ```sh
@@ -160,37 +130,203 @@ response = client.models.generate_content(
 print(response.text)
 ```
 
-#### How to structure `contents`
-There are several ways to structure the `contents` in your request.
+#### How to structure `contents` argument for `generate_content`
+The SDK always converts the inputs to the `contents` argument into
+`list[types.Content]`.
+The following shows some common ways to provide your inputs.
+
+##### Provide a `list[types.Content]`
+This is the canonical way to provide contents, SDK will not do any conversion.
+
+##### Provide a `types.Content` instance
+
+```python
+contents = types.Content(
+  role='user',
+  parts=[types.Part.from_text(text='Why is the sky blue?')]
+)
+```
+
+SDK converts this to
+
+```python
+[
+  types.Content(
+    role='user',
+    parts=[types.Part.from_text(text='Why is the sky blue?')]
+  )
+]
+```
+
+##### Provide a string
+
+```python
+contents='Why is the sky blue?'
+```
+
+The SDK will assume this is a text part, and it converts this into the following:
+
+```python
+[
+  types.UserContent(
+    parts=[
+      types.Part.from_text(text='Why is the sky blue?')
+    ]
+  )
+]
+```
+
+Where a `types.UserContent` is a subclass of `types.Content`, it sets the
+`role` field to be `user`.
+
+##### Provide a list of string
+
+```python
+contents=['Why is the sky blue?', 'Why is the cloud white?']
+```
+
+The SDK assumes these are 2 text parts, it converts this into a single content,
+like the following:
+
+```python
+[
+  types.UserContent(
+    parts=[
+      types.Part.from_text(text='Why is the sky blue?'),
+      types.Part.from_text(text='Why is the cloud white?'),
+    ]
+  )
+]
+```
+
+Where a `types.UserContent` is a subclass of `types.Content`, the
+`role` field in `types.UserContent` is fixed to be `user`.
+
+##### Provide a function call part
+
+```python
+contents = types.Part.from_function_call(
+  name='get_weather_by_location',
+  args={'location': 'Boston'}
+)
+```
+
+The SDK converts a function call part to a content with a `model` role:
+
+```python
+[
+  types.ModelContent(
+    parts=[
+      types.Part.from_function_call(
+        name='get_weather_by_location',
+        args={'location': 'Boston'}
+      )
+    ]
+  )
+]
+```
 
-Provide a single string as shown in the text example above:
+Where a `types.ModelContent` is a subclass of `types.Content`, the
+`role` field in `types.ModelContent` is fixed to be `model`.
+
+##### Provide a list of function call parts
 
 ```python
-contents='Can you recommend some things to do in Boston and New York in the winter?'
+contents = [
+  types.Part.from_function_call(
+    name='get_weather_by_location',
+    args={'location': 'Boston'}
+  ),
+  types.Part.from_function_call(
+    name='get_weather_by_location',
+    args={'location': 'New York'}
+  ),
+]
+```
+
+The SDK converts a list of function call parts to the a content with a `model` role:
+
+```python
+[
+  types.ModelContent(
+    parts=[
+      types.Part.from_function_call(
+        name='get_weather_by_location',
+        args={'location': 'Boston'}
+      ),
+      types.Part.from_function_call(
+        name='get_weather_by_location',
+        args={'location': 'New York'}
+      )
+    ]
+  )
+]
 ```
 
-Provide a single `Content` instance with multiple `Part` instances:
+Where a `types.ModelContent` is a subclass of `types.Content`, the
+`role` field in `types.ModelContent` is fixed to be `model`.
+
+##### Provide a non function call part
 
 ```python
-contents=types.Content(parts=[
-    types.Part.from_text(text='Can you recommend some things to do in Boston in the winter?'),
-    types.Part.from_text(text='Can you recommend some things to do in New York in the winter?')
-], role='user')
+contents = types.Part.from_uri(
+  file_uri: 'gs://generativeai-downloads/images/scones.jpg',
+  mime_type: 'image/jpeg',
+)
 ```
 
-When sending more than one input type, provide a list with multiple `Content`
-instances:
+The SDK converts all non function call parts into a content with a `user` role.
 
 ```python
-contents=[
-    'What is this a picture of?',
+[
+  types.UserContent(parts=[
     types.Part.from_uri(
-        file_uri='gs://generativeai-downloads/images/scones.jpg',
-        mime_type='image/jpeg',
-    ),
-],
+     file_uri: 'gs://generativeai-downloads/images/scones.jpg',
+      mime_type: 'image/jpeg',
+    )
+  ])
+]
+```
+
+##### Provide a list of non function call parts
+
+```python
+contents = [
+  types.Part.from_text('What is this image about?'),
+  types.Part.from_uri(
+    file_uri: 'gs://generativeai-downloads/images/scones.jpg',
+    mime_type: 'image/jpeg',
+  )
+]
 ```
 
+The SDK will convert the list of parts into a content with a `user` role
+
+```python
+[
+  types.UserContent(
+    parts=[
+      types.Part.from_text('What is this image about?'),
+      types.Part.from_uri(
+        file_uri: 'gs://generativeai-downloads/images/scones.jpg',
+        mime_type: 'image/jpeg',
+      )
+    ]
+  )
+]
+```
+
+##### Mix types in contents
+
+You can also provide a list of `types.ContentUnion`. The SDK leaves items of
+`types.Content` as is, it groups consecutive non function call parts into a
+single `types.UserContent`, and it groups consecutive function call parts into
+a single `types.ModelContent`.
+
+If you put a list within a list, the inner list can only contain
+`types.PartUnion` items. The SDK will convert the inner list into a single
+`types.UserContent`.
+
 ### System Instructions and Other Configs
 
 The output of the model can be influenced by several optional settings
@@ -481,6 +617,10 @@ response = client.models.generate_content(
 ```
 ### JSON Response Schema
 
+However you define your schema, don't duplicate it in your input prompt,
+including by giving examples of expected JSON output. If you do, the generated
+output might be lower in quality.
+
 #### Pydantic Model Schema support
 
 Schemas can be provided as Pydantic Models.