google-genai 1.55.0__py3-none-any.whl → 1.57.0__py3-none-any.whl

google/genai/version.py

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

{google_genai-1.55.0.dist-info → google_genai-1.57.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-genai
-Version: 1.55.0
+Version: 1.57.0
 Summary: GenAI Python SDK
 Author-email: Google LLC <googleapis-packages@google.com>
 License-Expression: Apache-2.0
@@ -20,7 +20,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: anyio<5.0.0,>=4.8.0
-Requires-Dist: google-auth[requests]<3.0.0,>=2.14.1
+Requires-Dist: google-auth[requests]<3.0.0,>=2.46.0
 Requires-Dist: httpx<1.0.0,>=0.28.1
 Requires-Dist: pydantic<3.0.0,>=2.9.0
 Requires-Dist: requests<3.0.0,>=2.28.1
@@ -57,11 +57,7 @@ APIs.
 
 Generative models are often unaware of recent API and SDK updates and may suggest outdated or legacy code.
 
-We recommend using our Code Generation instructions [codegen_instructions.md](https://raw.githubusercontent.com/googleapis/python-genai/refs/heads/main/codegen_instructions.md) when generating Google Gen AI SDK code to guide your model towards using the more recent SDK features.
-
-Copy and paste the instructions from [this file](https://raw.githubusercontent.com/googleapis/python-genai/refs/heads/main/codegen_instructions.md)
-into your development environment to provide the model with the necessary
-context
+We recommend using our Code Generation instructions [`codegen_instructions.md`](https://raw.githubusercontent.com/googleapis/python-genai/refs/heads/main/codegen_instructions.md) when generating Google Gen AI SDK code to guide your model towards using the more recent SDK features. Copy and paste the instructions into your development environment to provide the model with the necessary context.
 
 ## Installation
 
@@ -174,7 +170,7 @@ client = genai.Client()
 ## Close a client
 
 Explicitly close the sync client to ensure that resources, such as the
- underlying HTTP connections, are properly cleaned up and closed.
+underlying HTTP connections, are properly cleaned up and closed.
 
 ```python
 from google.genai import Client
@@ -215,7 +211,7 @@ await aclient.aclose()
 ## Client context managers
 
 By using the sync client context manager, it will close the underlying
- sync client when exiting the with block and avoid httpx "client has been closed" error like [issues#1763](https://github.com/googleapis/python-genai/issues/1763).
+sync client when exiting the with block and avoid httpx "client has been closed" error like [issues#1763](https://github.com/googleapis/python-genai/issues/1763).
 
 ```python
 from google.genai import Client
@@ -286,7 +282,7 @@ client = genai.Client(
 By default we use httpx for both sync and async client implementations. In order
 to have faster performance, you may install `google-genai[aiohttp]`. In Gen AI
 SDK we configure `trust_env=True` to match with the default behavior of httpx.
-Additional args of `aiohttp.ClientSession.request()` ([see _RequestOptions args](https://github.com/aio-libs/aiohttp/blob/v3.12.13/aiohttp/client.py#L170)) can be passed
+Additional args of `aiohttp.ClientSession.request()` ([see `_RequestOptions` args](https://github.com/aio-libs/aiohttp/blob/v3.12.13/aiohttp/client.py#L170)) can be passed
 through the following way:
 
 ```python
@@ -301,7 +297,7 @@ client=Client(..., http_options=http_options)
 
 Both httpx and aiohttp libraries use `urllib.request.getproxies` from
 environment variables. Before client initialization, you may set proxy (and
-optional SSL_CERT_FILE) by setting the environment variables:
+optional `SSL_CERT_FILE`) by setting the environment variables:
 
 ```bash
 export HTTPS_PROXY='http://username:password@proxy_uri:port'
@@ -324,7 +320,7 @@ client=Client(..., http_options=http_options)
 ### Custom base url
 
 In some cases you might need a custom base url (for example, API gateway proxy
- server) and bypass some authentication checks for project, location, or API key.
+server) and bypass some authentication checks for project, location, or API key.
 You may pass the custom base url like this:
 
 ```python
@@ -383,7 +379,8 @@ for part in response.parts:
 ```
 
 #### with uploaded file (Gemini Developer API only)
-download the file in console.
+
+Download the file in console.
 
 ```sh
 !wget -q https://storage.googleapis.com/generativeai-downloads/data/a11.txt
@@ -401,11 +398,13 @@ print(response.text)
 ```
 
 #### 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
@@ -451,7 +450,7 @@ The SDK will assume this is a text part, and it converts this into the following
 Where a `types.UserContent` is a subclass of `types.Content`, it sets the
 `role` field to be `user`.
 
-##### Provide a list of string
+##### Provide a list of strings
 
 ```python
 contents=['Why is the sky blue?', 'Why is the cloud white?']
@@ -520,7 +519,7 @@ contents = [
 ]
 ```
 
-The SDK converts a list of function call parts to the a content with a `model` role:
+The SDK converts a list of function call parts to a content with a `model` role:
 
 ```python
 [
@@ -712,7 +711,9 @@ 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:
@@ -944,7 +945,9 @@ including by giving examples of expected JSON output. If you do, the generated
 output might be lower in quality.
 
 #### JSON Schema support
+
 Schemas can be provided as standard JSON schema.
+
 ```python
 user_profile = {
     'properties': {
@@ -1071,7 +1074,7 @@ print(response.text)
 
 #### JSON Response
 
-You can also set response_mime_type to 'application/json', the response will be
+You can also set `response_mime_type` to `'application/json'`, the response will be
 identical but in quotes.
 
 ```python
@@ -1561,6 +1564,205 @@ response = client.models.generate_content(
 print(response.text)
 ```
 
+## Interactions (Preview)
+
+> **Warning:** The Interactions API is in **Beta**. This is a preview of an experimental feature. Features and schemas are subject to **breaking changes**.
+
+The Interactions API is a unified interface for interacting with Gemini models and agents. It simplifies state management, tool orchestration, and long-running tasks.
+
+See the [documentation site](https://ai.google.dev/gemini-api/docs/interactions) for more details.
+
+### Basic Interaction
+
+```python
+interaction = client.interactions.create(
+    model='gemini-2.5-flash',
+    input='Tell me a short joke about programming.'
+)
+print(interaction.outputs[-1].text)
+
+```
+
+### Stateful Conversation
+
+The Interactions API supports server-side state management. You can continue a conversation by referencing the `previous_interaction_id`.
+
+```python
+# 1. First turn
+interaction1 = client.interactions.create(
+    model='gemini-2.5-flash',
+    input='Hi, my name is Amir.'
+)
+print(f"Model: {interaction1.outputs[-1].text}")
+
+# 2. Second turn (passing previous_interaction_id)
+interaction2 = client.interactions.create(
+    model='gemini-2.5-flash',
+    input='What is my name?',
+    previous_interaction_id=interaction1.id
+)
+print(f"Model: {interaction2.outputs[-1].text}")
+
+```
+
+### Agents (Deep Research)
+
+You can use specialized agents like `deep-research-pro-preview-12-2025` for complex tasks.
+
+```python
+import time
+
+# 1. Start the Deep Research Agent
+initial_interaction = client.interactions.create(
+    input='Research the history of the Google TPUs with a focus on 2025 and 2026.',
+    agent='deep-research-pro-preview-12-2025',
+    background=True
+)
+print(f"Research started. Interaction ID: {initial_interaction.id}")
+
+# 2. Poll for results
+while True:
+    interaction = client.interactions.get(id=initial_interaction.id)
+    print(f"Status: {interaction.status}")
+
+    if interaction.status == "completed":
+        print("\nFinal Report:\n", interaction.outputs[-1].text)
+        break
+    elif interaction.status in ["failed", "cancelled"]:
+        print(f"Failed with status: {interaction.status}")
+        break
+
+    time.sleep(10)
+
+```
+
+### Multimodal Input
+
+You can provide multimodal data (text, images, audio, etc.) in the input list.
+
+```python
+import base64
+
+# Assuming you have an image loaded as bytes
+# base64_image = ...
+
+interaction = client.interactions.create(
+    model='gemini-2.5-flash',
+    input=[
+        {'type': 'text', 'text': 'Describe the image.'},
+        {'type': 'image', 'data': base64_image, 'mime_type': 'image/png'}
+    ]
+)
+print(interaction.outputs[-1].text)
+
+```
+
+### Function Calling
+
+You can define custom functions for the model to use. The Interactions API handles the tool selection, and you provide the execution result back to the model.
+
+```python
+# 1. Define the tool
+def get_weather(location: str):
+    """Gets the weather for a given location."""
+    return f"The weather in {location} is sunny."
+
+weather_tool = {
+    'type': 'function',
+    'name': 'get_weather',
+    'description': 'Gets the weather for a given location.',
+    'parameters': {
+        'type': 'object',
+        'properties': {
+            'location': {'type': 'string', 'description': 'The city and state, e.g. San Francisco, CA'}
+        },
+        'required': ['location']
+    }
+}
+
+# 2. Send the request with tools
+interaction = client.interactions.create(
+    model='gemini-2.5-flash',
+    input='What is the weather in Mountain View, CA?',
+    tools=[weather_tool]
+)
+
+# 3. Handle the tool call
+for output in interaction.outputs:
+    if output.type == 'function_call':
+        print(f"Tool Call: {output.name}({output.arguments})")
+
+        # Execute your actual function here
+        result = get_weather(**output.arguments)
+
+        # Send result back to the model
+        interaction = client.interactions.create(
+            model='gemini-2.5-flash',
+            previous_interaction_id=interaction.id,
+            input=[{
+                'type': 'function_result',
+                'name': output.name,
+                'call_id': output.id,
+                'result': result
+            }]
+        )
+        print(f"Response: {interaction.outputs[-1].text}")
+
+```
+
+### Built-in Tools
+You can also use Google's built-in tools, such as **Google Search** or **Code Execution**.
+
+#### Grounding with Google Search
+
+```python
+interaction = client.interactions.create(
+    model='gemini-2.5-flash',
+    input='Who won the last Super Bowl?',
+    tools=[{'type': 'google_search'}]
+)
+
+# Find the text output (not the GoogleSearchResultContent)
+text_output = next((o for o in interaction.outputs if o.type == 'text'), None)
+if text_output:
+    print(text_output.text)
+
+```
+
+#### Code Execution
+
+```python
+interaction = client.interactions.create(
+    model='gemini-2.5-flash',
+    input='Calculate the 50th Fibonacci number.',
+    tools=[{'type': 'code_execution'}]
+)
+print(interaction.outputs[-1].text)
+
+```
+
+### Multimodal Output
+
+The Interactions API can generate multimodal outputs, such as images. You must specify the `response_modalities`.
+
+```python
+import base64
+
+interaction = client.interactions.create(
+    model='gemini-3-pro-image-preview',
+    input='Generate an image of a futuristic city.',
+    response_modalities=['IMAGE']
+)
+
+for output in interaction.outputs:
+    if output.type == 'image':
+        print(f"Generated image with mime_type: {output.mime_type}")
+        # Save the image
+        with open("generated_city.png", "wb") as f:
+            f.write(base64.b64decode(output.data))
+
+```
+
 ## Tunings
 
 `client.tunings` contains tuning job APIs and supports supervised fine
@@ -1756,13 +1958,14 @@ job
 ```
 
 In order to create a batch job with file name. Need to upload a json file.
-For example myrequests.json:
+For example `myrequests.json`:
 
-```
+```json
 {"key":"request_1", "request": {"contents": [{"parts": [{"text":
  "Explain how AI works in a few words"}]}], "generation_config": {"response_modalities": ["TEXT"]}}}
 {"key":"request_2", "request": {"contents": [{"parts": [{"text": "Explain how Crypto works in a few words"}]}]}}
 ```
+
 Then upload the file.
 
 ```python
@@ -1779,7 +1982,6 @@ batch_job = client.batches.create(
 )
 ```
 
-
 ```python
 # Get a job by name
 job = client.batches.get(name=job.name)
@@ -1850,7 +2052,7 @@ 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.
+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
@@ -1872,8 +2074,8 @@ properties to include in the request body. This can be used to access new or
 experimental backend features that are not yet formally supported in the SDK.
 The structure of the dictionary must match the backend API's request structure.
 
-- VertexAI backend API docs: https://cloud.google.com/vertex-ai/docs/reference/rest
-- GeminiAPI backend API docs: https://ai.google.dev/api/rest
+- Vertex AI backend API docs: https://cloud.google.com/vertex-ai/docs/reference/rest
+- Gemini API backend API docs: https://ai.google.dev/api/rest
 
 ```python
 response = client.models.generate_content(