google-genai 1.14.0__tar.gz → 1.16.0__tar.gz

{google_genai-1.14.0/google_genai.egg-info → google_genai-1.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-genai
-Version: 1.14.0
+Version: 1.16.0
 Summary: GenAI Python SDK
 Author-email: Google LLC <googleapis-packages@google.com>
 License: Apache-2.0
@@ -40,7 +40,11 @@ Dynamic: license-file
 
 -----
 
-Google Gen AI Python SDK provides an interface for developers to integrate Google's generative models into their Python applications. It supports the [Gemini Developer API](https://ai.google.dev/gemini-api/docs) and [Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/overview) APIs.
+Google Gen AI Python SDK provides an interface for developers to integrate
+Google's generative models into their Python applications. It supports the
+[Gemini Developer API](https://ai.google.dev/gemini-api/docs) and
+[Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/overview)
+APIs.
 
 ## Installation
 
@@ -61,11 +65,15 @@ Please run one of the following code blocks to create a client for
 different services ([Gemini Developer API](https://ai.google.dev/gemini-api/docs) or [Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/overview)).
 
 ```python
+from google import genai
+
 # Only run this block for Gemini Developer API
 client = genai.Client(api_key='GEMINI_API_KEY')
 ```
 
 ```python
+from google import genai
+
 # Only run this block for Vertex AI API
 client = genai.Client(
     vertexai=True, project='your-project-id', location='us-central1'
@@ -84,8 +92,8 @@ Developer API or the Gemini API in Vertex AI.
 export GOOGLE_API_KEY='your-api-key'
 ```
 
-**Gemini API on Vertex AI:** Set `GOOGLE_GENAI_USE_VERTEXAI`, `GOOGLE_CLOUD_PROJECT`
-and `GOOGLE_CLOUD_LOCATION`, as shown below:
+**Gemini API on Vertex AI:** Set `GOOGLE_GENAI_USE_VERTEXAI`,
+`GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION`, as shown below:
 
 ```bash
 export GOOGLE_GENAI_USE_VERTEXAI=true
@@ -94,6 +102,8 @@ export GOOGLE_CLOUD_LOCATION='us-central1'
 ```
 
 ```python
+from google import genai
+
 client = genai.Client()
 ```
 
@@ -107,6 +117,9 @@ To set the API version use `http_options`. For example, to set the API version
 to `v1` for Vertex AI:
 
 ```python
+from google import genai
+from google.genai import types
+
 client = genai.Client(
     vertexai=True,
     project='your-project-id',
@@ -118,6 +131,9 @@ client = genai.Client(
 To set the API version to `v1alpha` for the Gemini Developer API:
 
 ```python
+from google import genai
+from google.genai import types
+
 client = genai.Client(
     api_key='GEMINI_API_KEY',
     http_options=types.HttpOptions(api_version='v1alpha')
@@ -133,6 +149,7 @@ Pydantic model types are available in the `types` module.
 ## Models
 
 The `client.models` modules exposes model inferencing and model getters.
+See the 'Create a client' section above to initialize a client.
 
 ### Generate Content
 
@@ -174,6 +191,8 @@ This is the canonical way to provide contents, SDK will not do any conversion.
 ##### Provide a `types.Content` instance
 
 ```python
+from google.genai import types
+
 contents = types.Content(
   role='user',
   parts=[types.Part.from_text(text='Why is the sky blue?')]
@@ -238,6 +257,8 @@ Where a `types.UserContent` is a subclass of `types.Content`, the
 ##### Provide a function call part
 
 ```python
+from google.genai import types
+
 contents = types.Part.from_function_call(
   name='get_weather_by_location',
   args={'location': 'Boston'}
@@ -265,6 +286,8 @@ Where a `types.ModelContent` is a subclass of `types.Content`, the
 ##### Provide a list of function call parts
 
 ```python
+from google.genai import types
+
 contents = [
   types.Part.from_function_call(
     name='get_weather_by_location',
@@ -302,6 +325,8 @@ Where a `types.ModelContent` is a subclass of `types.Content`, the
 ##### Provide a non function call part
 
 ```python
+from google.genai import types
+
 contents = types.Part.from_uri(
   file_uri: 'gs://generativeai-downloads/images/scones.jpg',
   mime_type: 'image/jpeg',
@@ -324,6 +349,8 @@ The SDK converts all non function call parts into a content with a `user` role.
 ##### Provide a list of non function call parts
 
 ```python
+from google.genai import types
+
 contents = [
   types.Part.from_text('What is this image about?'),
   types.Part.from_uri(
@@ -363,11 +390,17 @@ If you put a list within a list, the inner list can only contain
 ### System Instructions and Other Configs
 
 The output of the model can be influenced by several optional settings
-available in generate_content's config parameter. For example, the
-variability and length of the output can be influenced by the temperature
-and max_output_tokens respectively.
+available in generate_content's config parameter. For example, increasing
+`max_output_tokens` is essential for longer model responses. To make a model more
+deterministic, lowering the `temperature` parameter reduces randomness, with
+values near 0 minimizing variability. Capabilities and parameter defaults for
+each model is shown in the
+[Vertex AI docs](https://cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/2-5-flash)
+and [Gemini API docs](https://ai.google.dev/gemini-api/docs/models) respectively.
 
 ```python
+from google.genai import types
+
 response = client.models.generate_content(
     model='gemini-2.0-flash-001',
     contents='high',
@@ -386,6 +419,8 @@ All API methods support Pydantic types for parameters as well as
 dictionaries. You can get the type from `google.genai.types`.
 
 ```python
+from google.genai import types
+
 response = client.models.generate_content(
     model='gemini-2.0-flash-001',
     contents=types.Part.from_text(text='Why is the sky blue?'),
@@ -422,7 +457,7 @@ pager.next_page()
 print(pager[0])
 ```
 
-#### Async
+#### List Base Models (Asynchronous)
 
 ```python
 async for job in await client.aio.models.list():
@@ -440,6 +475,8 @@ print(async_pager[0])
 ### Safety Settings
 
 ```python
+from google.genai import types
+
 response = client.models.generate_content(
     model='gemini-2.0-flash-001',
     contents='Say something bad.',
@@ -463,6 +500,8 @@ You can pass a Python function directly and it will be automatically
 called and responded by default.
 
 ```python
+from google.genai import types
+
 def get_current_weather(location: str) -> str:
     """Returns the current weather.
 
@@ -486,6 +525,8 @@ automatic function calling, you can disable automatic function calling
 as follows:
 
 ```python
+from google.genai import types
+
 response = client.models.generate_content(
   model='gemini-2.0-flash-001',
   contents='What is the weather like in Boston?',
@@ -514,6 +555,8 @@ The following example shows how to declare a function and pass it as a tool.
 Then you will receive a function call part in the response.
 
 ```python
+from google.genai import types
+
 function = types.FunctionDeclaration(
     name='get_current_weather',
     description='Get the current weather in a given location',
@@ -546,6 +589,8 @@ the model.
 The following example shows how to do it for a simple function invocation.
 
 ```python
+from google.genai import types
+
 user_prompt_content = types.Content(
     role='user',
     parts=[types.Part.from_text(text='What is the weather like in Boston?')],
@@ -598,6 +643,8 @@ maximum remote call for automatic function calling (default to 10 times).
 If you'd like to disable automatic function calling in `ANY` mode:
 
 ```python
+from google.genai import types
+
 def get_current_weather(location: str) -> str:
     """Returns the current weather.
 
@@ -626,6 +673,8 @@ configure the maximum remote calls to be `x + 1`.
 Assuming you prefer `1` turn for automatic function calling.
 
 ```python
+from google.genai import types
+
 def get_current_weather(location: str) -> str:
     """Returns the current weather.
 
@@ -660,6 +709,7 @@ Schemas can be provided as Pydantic Models.
 
 ```python
 from pydantic import BaseModel
+from google.genai import types
 
 
 class CountryInfo(BaseModel):
@@ -684,6 +734,8 @@ print(response.text)
 ```
 
 ```python
+from google.genai import types
+
 response = client.models.generate_content(
     model='gemini-2.0-flash-001',
     contents='Give me information for the United States.',
@@ -743,7 +795,8 @@ print(response.text)
 
 #### JSON Response
 
-You can also set response_mime_type to 'application/json', the response will be identical but in quotes.
+You can also set response_mime_type to 'application/json', the response will be
+identical but in quotes.
 
 ```python
 from enum import Enum
@@ -766,7 +819,10 @@ response = client.models.generate_content(
 print(response.text)
 ```
 
-### Streaming
+### Generate Content (Synchronous Streaming)
+
+Generate content in a streaming format so that the model outputs streams back
+to you, rather than being returned as one chunk.
 
 #### Streaming for text content
 
@@ -783,6 +839,8 @@ If your image is stored in [Google Cloud Storage](https://cloud.google.com/stora
 you can use the `from_uri` class method to create a `Part` object.
 
 ```python
+from google.genai import types
+
 for chunk in client.models.generate_content_stream(
     model='gemini-2.0-flash-001',
     contents=[
@@ -800,6 +858,8 @@ If your image is stored in your local file system, you can read it in as bytes
 data and use the `from_bytes` class method to create a `Part` object.
 
 ```python
+from google.genai import types
+
 YOUR_IMAGE_PATH = 'your_image_path'
 YOUR_IMAGE_MIME_TYPE = 'your_image_mime_type'
 with open(YOUR_IMAGE_PATH, 'rb') as f:
@@ -815,10 +875,10 @@ for chunk in client.models.generate_content_stream(
     print(chunk.text, end='')
 ```
 
-### Async
+### Generate Content (Asynchronous Non Streaming)
 
 `client.aio` exposes all the analogous [`async` methods](https://docs.python.org/3/library/asyncio.html)
-that are available on `client`
+that are available on `client`. Note that it applies to all the modules.
 
 For example, `client.aio.models.generate_content` is the `async` version
 of `client.models.generate_content`
@@ -831,7 +891,8 @@ response = await client.aio.models.generate_content(
 print(response.text)
 ```
 
-### Streaming
+### Generate Content (Asynchronous Streaming)
+
 
 ```python
 async for chunk in await client.aio.models.generate_content_stream(
@@ -883,6 +944,8 @@ print(response)
 ```
 
 ```python
+from google.genai import types
+
 # multiple contents with config
 response = client.models.embed_content(
     model='text-embedding-004',
@@ -900,6 +963,8 @@ print(response)
 Support for generate images in Gemini Developer API is behind an allowlist
 
 ```python
+from google.genai import types
+
 # Generate Image
 response1 = client.models.generate_images(
     model='imagen-3.0-generate-002',
@@ -918,6 +983,8 @@ response1.generated_images[0].image.show()
 Upscale image is only supported in Vertex AI.
 
 ```python
+from google.genai import types
+
 # Upscale the generated image from above
 response2 = client.models.upscale_image(
     model='imagen-3.0-generate-001',
@@ -939,6 +1006,7 @@ Edit image is only supported in Vertex AI.
 
 ```python
 # Edit the generated image from above
+from google.genai import types
 from google.genai.types import RawReferenceImage, MaskReferenceImage
 
 raw_ref_image = RawReferenceImage(
@@ -976,6 +1044,8 @@ response3.generated_images[0].image.show()
 Support for generate videos in Vertex and Gemini Developer API is behind an allowlist
 
 ```python
+from google.genai import types
+
 # Create operation
 operation = client.models.generate_videos(
     model='veo-2.0-generate-001',
@@ -999,17 +1069,22 @@ video.show()
 
 ## Chats
 
-Create a chat session to start a multi-turn conversations with the model.
+Create a chat session to start a multi-turn conversations with the model. Then,
+use `chat.send_message` function multiple times within the same chat session so
+that it can reflect on its previous responses (i.e., engage in an ongoing
+ conversation). See the 'Create a client' section above to initialize a client.
 
-### Send Message
+### Send Message (Synchronous Non-Streaming)
 
 ```python
 chat = client.chats.create(model='gemini-2.0-flash-001')
 response = chat.send_message('tell me a story')
 print(response.text)
+response = chat.send_message('summarize the story you told me in 1 sentence')
+print(response.text)
 ```
 
-### Streaming
+### Send Message (Synchronous Streaming)
 
 ```python
 chat = client.chats.create(model='gemini-2.0-flash-001')
@@ -1017,7 +1092,7 @@ for chunk in chat.send_message_stream('tell me a story'):
     print(chunk.text)
 ```
 
-### Async
+### Send Message (Asynchronous Non-Streaming)
 
 ```python
 chat = client.aio.chats.create(model='gemini-2.0-flash-001')
@@ -1025,7 +1100,7 @@ response = await chat.send_message('tell me a story')
 print(response.text)
 ```
 
-### Async Streaming
+### Send Message (Asynchronous Streaming)
 
 ```python
 chat = client.aio.chats.create(model='gemini-2.0-flash-001')
@@ -1035,7 +1110,8 @@ async for chunk in await chat.send_message_stream('tell me a story'):
 
 ## Files
 
-Files are only supported in Gemini Developer API.
+Files are only supported in Gemini Developer API. See the 'Create a client'
+section above to initialize a client.
 
 ```cmd
 !gsutil cp gs://cloud-samples-data/generative-ai/pdf/2312.11805v3.pdf .
@@ -1069,11 +1145,14 @@ client.files.delete(name=file3.name)
 
 ## Caches
 
-`client.caches` contains the control plane APIs for cached content
+`client.caches` contains the control plane APIs for cached content. See the
+'Create a client' section above to initialize a client.
 
 ### Create
 
 ```python
+from google.genai import types
+
 if client.vertexai:
     file_uris = [
         'gs://cloud-samples-data/generative-ai/pdf/2312.11805v3.pdf',
@@ -1115,6 +1194,8 @@ cached_content = client.caches.get(name=cached_content.name)
 ### Generate Content with Caches
 
 ```python
+from google.genai import types
+
 response = client.models.generate_content(
     model='gemini-2.0-flash-001',
     contents='Summarize the pdfs',
@@ -1128,7 +1209,8 @@ print(response.text)
 ## Tunings
 
 `client.tunings` contains tuning job APIs and supports supervised fine
-tuning through `tune`.
+tuning through `tune`. See the 'Create a client' section above to initialize a
+client.
 
 ### Tune
 
@@ -1136,6 +1218,8 @@ tuning through `tune`.
 -   Gemini Developer API supports tuning from inline examples
 
 ```python
+from google.genai import types
+
 if client.vertexai:
     model = 'gemini-2.0-flash-001'
     training_dataset = types.TuningDataset(
@@ -1155,6 +1239,8 @@ else:
 ```
 
 ```python
+from google.genai import types
+
 tuning_job = client.tunings.tune(
     base_model=model,
     training_dataset=training_dataset,
@@ -1241,6 +1327,8 @@ print(async_pager[0])
 ### Update Tuned Model
 
 ```python
+from google.genai import types
+
 model = pager[0]
 
 model = client.models.update(
@@ -1286,7 +1374,8 @@ print(async_pager[0])
 
 ## Batch Prediction
 
-Only supported in Vertex AI.
+Only supported in Vertex AI. See the 'Create a client' section above to
+initialize a client.
 
 ### Create