merge

Change-Id: I361c62ffbe3b7b7471f54382cb2b02cd6e5e5e05

Author: MarkDaoust

README.md

@@ -9,7 +9,7 @@ The Google AI Python SDK is the easiest way for Python developers to build with
 ## Get started with the Gemini API
 1. Go to [Google AI Studio](https://aistudio.google.com/).
 2. Login with your Google account.
-3. [Create](https://aistudio.google.com/app/apikey) an API key. Note that in Europe the free tier is not available.
+3. [Create](https://aistudio.google.com/app/apikey) an API key.
 4. Try a Python SDK [quickstart](https://github.com/google-gemini/gemini-api-cookbook/blob/main/quickstarts/Prompting.ipynb) in the [Gemini API Cookbook](https://github.com/google-gemini/gemini-api-cookbook/).
 5. For detailed instructions, try the 
 [Python SDK tutorial](https://ai.google.dev/tutorials/python_quickstart) on [ai.google.dev](https://ai.google.dev).

google/generativeai/client.py

@@ -2,9 +2,9 @@
 
 import os
 import contextlib
+import inspect
 import dataclasses
 import pathlib
-import types
 from typing import Any, cast
 from collections.abc import Sequence
 import httplib2
@@ -30,6 +30,21 @@
     __version__ = "0.0.0"
 
 USER_AGENT = "genai-py"
+
+#### Caution! ####
+#  - It would make sense for the discovery URL to respect the client_options.endpoint setting.
+#    - That would make testing Files on the staging server possible.
+#  - We tried fixing this once, but broke colab in the process because their endpoint didn't forward the discovery
+#    requests. https://github.com/google-gemini/generative-ai-python/pull/333
+#  - Kaggle would have a similar problem  (b/362278209).
+#    - I think their proxy would forward the discovery traffic.
+#    - But they don't need to intercept the files-service at all, and uploads of large files could overload them.
+#      - Do the scotty uploads go to the same domain?
+#    - If you do route the discovery call to kaggle, be sure to attach the default_metadata (they need it).
+#  - One solution to all this would be if configure could take overrides per service.
+#    - set client_options.endpoint, but use a different endpoint for file service? It's not clear how best to do that
+#      through the file service.
+##################
 GENAI_API_DISCOVERY_URL = "https://generativelanguage.googleapis.com/$discovery/rest"
 
 
@@ -50,7 +65,7 @@ def __init__(self, *args, **kwargs):
         self._discovery_api = None
         super().__init__(*args, **kwargs)
 
-    def _setup_discovery_api(self):
+    def _setup_discovery_api(self, metadata: dict | Sequence[tuple[str, str]] = ()):
         api_key = self._client_options.api_key
         if api_key is None:
             raise ValueError(
@@ -61,6 +76,7 @@ def _setup_discovery_api(self):
             http=httplib2.Http(),
             postproc=lambda resp, content: (resp, content),
             uri=f"{GENAI_API_DISCOVERY_URL}?version=v1beta&key={api_key}",
+            headers=dict(metadata),
         )
         response, content = request.execute()
         request.http.close()
@@ -78,9 +94,10 @@ def create_file(
         name: str | None = None,
         display_name: str | None = None,
         resumable: bool = True,
+        metadata: Sequence[tuple[str, str]] = (),
     ) -> protos.File:
         if self._discovery_api is None:
-            self._setup_discovery_api()
+            self._setup_discovery_api(metadata)
 
         file = {}
         if name is not None:
@@ -92,6 +109,8 @@ def create_file(
             filename=path, mimetype=mime_type, resumable=resumable
         )
         request = self._discovery_api.media().upload(body={"file": file}, media_body=media)
+        for key, value in metadata:
+            request.headers[key] = value
         result = request.execute()
 
         return self.get_file({"name": result["file"]["name"]})
@@ -226,16 +245,14 @@ def make_client(self, name):
         def keep(name, f):
             if name.startswith("_"):
                 return False
-            elif name == "create_file":
-                return False
-            elif not isinstance(f, types.FunctionType):
-                return False
-            elif isinstance(f, classmethod):
+
+            if not callable(f):
                 return False
-            elif isinstance(f, staticmethod):
+
+            if "metadata" not in inspect.signature(f).parameters.keys():
                 return False
-            else:
-                return True
+
+            return True
 
         def add_default_metadata_wrapper(f):
             def call(*args, metadata=(), **kwargs):
@@ -244,7 +261,7 @@ def call(*args, metadata=(), **kwargs):
 
             return call
 
-        for name, value in cls.__dict__.items():
+        for name, value in inspect.getmembers(cls):
             if not keep(name, value):
                 continue
             f = getattr(client, name)

google/generativeai/types/generation_types.py

@@ -144,17 +144,27 @@ class GenerationConfig:
             Note: The default value varies by model, see the
             `Model.top_k` attribute of the `Model` returned the
             `genai.get_model` function.
-
+        seed:
+            Optional.  Seed used in decoding. If not set, the request uses a randomly generated seed.
         response_mime_type:
             Optional. Output response mimetype of the generated candidate text.
 
             Supported mimetype:
                 `text/plain`: (default) Text output.
+                `text/x-enum`: for use with a string-enum in `response_schema`
                 `application/json`: JSON response in the candidates.
 
         response_schema:
             Optional. Specifies the format of the JSON requested if response_mime_type is
             `application/json`.
+        presence_penalty:
+            Optional.
+        frequency_penalty:
+            Optional.
+        response_logprobs:
+            Optional. If true, export the `logprobs` results in response.
+        logprobs:
+            Optional. Number of candidates of log probabilities to return at each step of decoding.
     """
 
     candidate_count: int | None = None
@@ -163,8 +173,13 @@ class GenerationConfig:
     temperature: float | None = None
     top_p: float | None = None
     top_k: int | None = None
+    seed: int | None = None
     response_mime_type: str | None = None
     response_schema: protos.Schema | Mapping[str, Any] | type | None = None
+    presence_penalty: float | None = None
+    frequency_penalty: float | None = None
+    response_logprobs: bool | None = None
+    logprobs: int | None = None
 
 
 GenerationConfigType = Union[protos.GenerationConfig, GenerationConfigDict, GenerationConfig]
@@ -306,6 +321,7 @@ def _join_code_execution_result(result_1, result_2):
 
 
 def _join_candidates(candidates: Iterable[protos.Candidate]):
+    """Joins stream chunks of a single candidate."""
     candidates = tuple(candidates)
 
     index = candidates[0].index  # These should all be the same.
@@ -321,6 +337,7 @@ def _join_candidates(candidates: Iterable[protos.Candidate]):
 
 
 def _join_candidate_lists(candidate_lists: Iterable[list[protos.Candidate]]):
+    """Joins stream chunks where each chunk is a list of candidate chunks."""
     # Assuming that is a candidate ends, it is no longer returned in the list of
     # candidates and that's why candidates have an index
     candidates = collections.defaultdict(list)
@@ -344,10 +361,15 @@ def _join_prompt_feedbacks(
 
 def _join_chunks(chunks: Iterable[protos.GenerateContentResponse]):
     chunks = tuple(chunks)
+    if "usage_metadata" in chunks[-1]:
+        usage_metadata = chunks[-1].usage_metadata
+    else:
+        usage_metadata = None
+
     return protos.GenerateContentResponse(
         candidates=_join_candidate_lists(c.candidates for c in chunks),
         prompt_feedback=_join_prompt_feedbacks(c.prompt_feedback for c in chunks),
-        usage_metadata=chunks[-1].usage_metadata,
+        usage_metadata=usage_metadata,
     )
 
 
@@ -412,14 +434,22 @@ def parts(self):
         """
         candidates = self.candidates
         if not candidates:
-            raise ValueError(
+            msg = (
                 "Invalid operation: The `response.parts` quick accessor requires a single candidate, "
-                "but none were returned. Please check the `response.prompt_feedback` to determine if the prompt was blocked."
+                "but but `response.candidates` is empty."
             )
+            if self.prompt_feedback:
+                raise ValueError(
+                    msg + "\nThis appears to be caused by a blocked prompt, "
+                    f"see `response.prompt_feedback`: {self.prompt_feedback}"
+                )
+            else:
+                raise ValueError(msg)
+
         if len(candidates) > 1:
             raise ValueError(
-                "Invalid operation: The `response.parts` quick accessor requires a single candidate. "
-                "For multiple candidates, please use `result.candidates[index].text`."
+                "Invalid operation: The `response.parts` quick accessor retrieves the parts for a single candidate. "
+                "This response contains multiple candidates, please use `result.candidates[index].text`."
             )
         parts = candidates[0].content.parts
         return parts
@@ -433,10 +463,53 @@ def text(self):
         """
         parts = self.parts
         if not parts:
-            raise ValueError(
-                "Invalid operation: The `response.text` quick accessor requires the response to contain a valid `Part`, "
-                "but none were returned. Please check the `candidate.safety_ratings` to determine if the response was blocked."
+            candidate = self.candidates[0]
+
+            fr = candidate.finish_reason
+            FinishReason = protos.Candidate.FinishReason
+
+            msg = (
+                "Invalid operation: The `response.text` quick accessor requires the response to contain a valid "
+                "`Part`, but none were returned. The candidate's "
+                f"[finish_reason](https://ai.google.dev/api/generate-content#finishreason) is {fr}."
             )
+            if candidate.finish_message:
+                msg += 'The `finish_message` is "{candidate.finish_message}".'
+
+            if fr is FinishReason.FINISH_REASON_UNSPECIFIED:
+                raise ValueError(msg)
+            elif fr is FinishReason.STOP:
+                raise ValueError(msg)
+            elif fr is FinishReason.MAX_TOKENS:
+                raise ValueError(msg)
+            elif fr is FinishReason.SAFETY:
+                raise ValueError(
+                    msg + f" The candidate's safety_ratings are: {candidate.safety_ratings}.",
+                    candidate.safety_ratings,
+                )
+            elif fr is FinishReason.RECITATION:
+                raise ValueError(
+                    msg + " Meaning that the model was reciting from copyrighted material."
+                )
+            elif fr is FinishReason.LANGUAGE:
+                raise ValueError(msg + " Meaning the response was using an unsupported language.")
+            elif fr is FinishReason.OTHER:
+                raise ValueError(msg)
+            elif fr is FinishReason.BLOCKLIST:
+                raise ValueError(msg)
+            elif fr is FinishReason.PROHIBITED_CONTENT:
+                raise ValueError(msg)
+            elif fr is FinishReason.SPII:
+                raise ValueError(msg + " SPII - Sensitive Personally Identifiable Information.")
+            elif fr is FinishReason.MALFORMED_FUNCTION_CALL:
+                raise ValueError(
+                    msg + " Meaning that model generated a `FunctionCall` that was invalid. "
+                    "Setting the "
+                    "[Function calling mode](https://ai.google.dev/gemini-api/docs/function-calling#function_calling_mode) "
+                    "to `ANY` can fix this because it enables constrained decoding."
+                )
+            else:
+                raise ValueError(msg)
 
         texts = []
         for part in parts:
@@ -490,7 +563,8 @@ def __str__(self) -> str:
         _result = _result.replace("\n", "\n                    ")
 
         if self._error:
-            _error = f",\nerror=<{self._error.__class__.__name__}> {self._error}"
+
+            _error = f",\nerror={repr(self._error)}"
         else:
             _error = ""
 

google/generativeai/types/model_types.py

@@ -143,7 +143,9 @@ def idecode_time(parent: dict["str", Any], name: str):
 
 def decode_tuned_model(tuned_model: protos.TunedModel | dict["str", Any]) -> TunedModel:
     if isinstance(tuned_model, protos.TunedModel):
-        tuned_model = type(tuned_model).to_dict(tuned_model)  # pytype: disable=attribute-error
+        tuned_model = type(tuned_model).to_dict(
+            tuned_model, including_default_value_fields=False
+        )  # pytype: disable=attribute-error
     tuned_model["state"] = to_tuned_model_state(tuned_model.pop("state", None))
 
     base_model = tuned_model.pop("base_model", None)
@@ -195,6 +197,7 @@ class TunedModel:
     create_time: datetime.datetime | None = None
     update_time: datetime.datetime | None = None
     tuning_task: TuningTask | None = None
+    reader_project_numbers: list[int] | None = None
 
     @property
     def permissions(self) -> permission_types.Permissions:

google/generativeai/version.py

@@ -14,4 +14,4 @@
 # limitations under the License.
 from __future__ import annotations
 
-__version__ = "0.7.2"
+__version__ = "0.8.2"

samples/controlled_generation.py

@@ -139,7 +139,7 @@ class Choice(enum.Enum):
                 response_mime_type="text/x.enum", response_schema=Choice
             ),
         )
-        print(result)  # "Keyboard"
+        print(result)  # Keyboard
         # [END x_enum]
 
     def test_x_enum_raw(self):
@@ -157,7 +157,7 @@ def test_x_enum_raw(self):
                 },
             ),
         )
-        print(result)  # "Keyboard"
+        print(result)  # Keyboard
         # [END x_enum_raw]
 
 

setup.py

@@ -42,7 +42,7 @@ def get_version():
     release_status = "Development Status :: 5 - Production/Stable"
 
 dependencies = [
-    "google-ai-generativelanguage==0.6.6",
+    "google-ai-generativelanguage==0.6.10",
     "google-api-core",
     "google-api-python-client",
     "google-auth>=2.15.0",  # 2.15 adds API key auth support

tests/test_files.py

@@ -12,13 +12,14 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+from __future__ import annotations
 
 from google.generativeai.types import file_types
 
 import collections
 import datetime
 import os
-from typing import Iterable, Union
+from typing import Iterable, Sequence
 import pathlib
 
 import google
@@ -37,12 +38,13 @@ def __init__(self, test):
 
     def create_file(
         self,
-        path: Union[str, pathlib.Path, os.PathLike],
+        path: str | pathlib.Path | os.PathLike,
         *,
-        mime_type: Union[str, None] = None,
-        name: Union[str, None] = None,
-        display_name: Union[str, None] = None,
+        mime_type: str | None = None,
+        name: str | None = None,
+        display_name: str | None = None,
         resumable: bool = True,
+        metadata: Sequence[tuple[str, str]] = (),
     ) -> protos.File:
         self.observed_requests.append(
             dict(