gemini-webapi 1.12.3__py3-none-any.whl → 1.14.1__py3-none-any.whl

gemini_webapi/__init__.py

@@ -1,4 +1,6 @@
-from .client import GeminiClient, ChatSession  # noqa: F401
-from .exceptions import *  # noqa: F401, F403
-from .types import *  # noqa: F401, F403
-from .utils import set_log_level  # noqa: F401
+# flake8: noqa
+
+from .client import GeminiClient, ChatSession
+from .exceptions import *
+from .types import *
+from .utils import set_log_level, logger

gemini_webapi/client.py

@@ -1,11 +1,12 @@
 import asyncio
 import functools
-import json
+import itertools
 import re
 from asyncio import Task
 from pathlib import Path
 from typing import Any, Optional
 
+import orjson as json
 from httpx import AsyncClient, ReadTimeout
 
 from .constants import Endpoint, ErrorCode, Headers, Model
@@ -19,7 +20,7 @@ from .exceptions import (
     ModelInvalid,
     TemporarilyBlocked,
 )
-from .types import WebImage, GeneratedImage, Candidate, ModelOutput
+from .types import WebImage, GeneratedImage, Candidate, ModelOutput, Gem, GemJar
 from .utils import (
     upload_file,
     parse_file_name,
@@ -116,6 +117,7 @@ class GeminiClient:
         "close_task",
         "auto_refresh",
         "refresh_interval",
+        "_gems",
         "kwargs",
     ]
 
@@ -131,12 +133,13 @@ class GeminiClient:
         self.running: bool = False
         self.client: AsyncClient | None = None
         self.access_token: str | None = None
-        self.timeout: float = 30
+        self.timeout: float = 300
         self.auto_close: bool = False
         self.close_delay: float = 300
         self.close_task: Task | None = None
         self.auto_refresh: bool = True
         self.refresh_interval: float = 540
+        self._gems: GemJar | None = None
         self.kwargs = kwargs
 
         # Validate cookies
@@ -274,12 +277,131 @@ class GeminiClient:
                 self.cookies["__Secure-1PSIDTS"] = new_1psidts
             await asyncio.sleep(self.refresh_interval)
 
+    @property
+    def gems(self) -> GemJar:
+        """
+        Returns a `GemJar` object containing cached gems.
+        Only available after calling `GeminiClient.fetch_gems()`.
+
+        Returns
+        -------
+        :class:`GemJar`
+            Refer to `gemini_webapi.types.GemJar`.
+
+        Raises
+        ------
+        `RuntimeError`
+            If `GeminiClient.fetch_gems()` has not been called before accessing this property.
+        """
+
+        if self._gems is None:
+            raise RuntimeError(
+                "Gems not fetched yet. Call `GeminiClient.fetch_gems()` method to fetch gems from gemini.google.com."
+            )
+
+        return self._gems
+
+    @running(retry=2)
+    async def fetch_gems(self, **kwargs) -> GemJar:
+        """
+        Get a list of available gems from gemini, including system predefined gems and user-created custom gems.
+
+        Note that network request will be sent every time this method is called.
+        Once the gems are fetched, they will be cached and accessible via `GeminiClient.gems` property.
+
+        Returns
+        -------
+        :class:`GemJar`
+            Refer to `gemini_webapi.types.GemJar`.
+        """
+
+        try:
+            response = await self.client.post(
+                Endpoint.BATCH_EXEC,
+                data={
+                    "at": self.access_token,
+                    "f.req": json.dumps(
+                        [
+                            [
+                                ["CNgdBe", '[2,["en"],0]', None, "custom"],
+                                ["CNgdBe", '[3,["en"],0]', None, "system"],
+                            ]
+                        ]
+                    ).decode(),
+                },
+                **kwargs,
+            )
+        except ReadTimeout:
+            raise TimeoutError(
+                "Fetch gems request timed out, please try again. If the problem persists, "
+                "consider setting a higher `timeout` value when initializing GeminiClient."
+            )
+
+        if response.status_code != 200:
+            raise APIError(
+                f"Failed to fetch gems. Request failed with status code {response.status_code}"
+            )
+        else:
+            try:
+                response_json = json.loads(response.text.split("\n")[2])
+
+                predefined_gems, custom_gems = [], []
+
+                for part in response_json:
+                    if part[-1] == "system":
+                        predefined_gems = json.loads(part[2])[2]
+                    elif part[-1] == "custom":
+                        if custom_gems_container := json.loads(part[2]):
+                            custom_gems = custom_gems_container[2]
+
+                if not predefined_gems and not custom_gems:
+                    raise Exception
+            except Exception:
+                logger.debug(f"Invalid response: {response.text}")
+                raise APIError(
+                    "Failed to fetch gems. Invalid response data received. Client will try to re-initialize on next request."
+                )
+
+        self._gems = GemJar(
+            itertools.chain(
+                (
+                    (
+                        gem[0],
+                        Gem(
+                            id=gem[0],
+                            name=gem[1][0],
+                            description=gem[1][1],
+                            prompt=gem[2] and gem[2][0] or None,
+                            predefined=True,
+                        ),
+                    )
+                    for gem in predefined_gems
+                ),
+                (
+                    (
+                        gem[0],
+                        Gem(
+                            id=gem[0],
+                            name=gem[1][0],
+                            description=gem[1][1],
+                            prompt=gem[2] and gem[2][0] or None,
+                            predefined=False,
+                        ),
+                    )
+                    for gem in custom_gems
+                ),
+            )
+        )
+
+        return self._gems
+
     @running(retry=2)
     async def generate_content(
         self,
         prompt: str,
         files: list[str | Path] | None = None,
         model: Model | str = Model.UNSPECIFIED,
+        gem: Gem | str | None = None,
         chat: Optional["ChatSession"] = None,
         **kwargs,
     ) -> ModelOutput:
@@ -295,6 +417,9 @@ class GeminiClient:
         model: `Model` | `str`, optional
             Specify the model to use for generation.
             Pass either a `gemini_webapi.constants.Model` enum or a model name string.
+        gem: `Gem | str`, optional
+            Specify a gem to use as system prompt for the chat session.
+            Pass either a `gemini_webapi.types.Gem` object or a gem id string.
         chat: `ChatSession`, optional
             Chat data to retrieve conversation history. If None, will automatically generate a new chat id when sending post request.
         kwargs: `dict`, optional
@@ -325,6 +450,9 @@ class GeminiClient:
         if not isinstance(model, Model):
             model = Model.from_name(model)
 
+        if isinstance(gem, Gem):
+            gem = gem.id
+
         if self.auto_close:
             await self.reset_close_task()
 
@@ -356,15 +484,17 @@ class GeminiClient:
                                     None,
                                     chat and chat.metadata,
                                 ]
-                            ),
+                                + (gem and [None] * 16 + [gem] or [])
+                            ).decode(),
                         ]
-                    ),
+                    ).decode(),
                 },
                 **kwargs,
             )
         except ReadTimeout:
             raise TimeoutError(
-                "Request timed out, please try again. If the problem persists, consider setting a higher `timeout` value when initializing GeminiClient."
+                "Generate content request timed out, please try again. If the problem persists, "
+                "consider setting a higher `timeout` value when initializing GeminiClient."
             )
 
         if response.status_code != 200:
@@ -422,7 +552,7 @@ class GeminiClient:
                 for candidate_index, candidate in enumerate(body[4]):
                     text = candidate[1][0]
                     if re.match(
-                        r"^http://googleusercontent\.com/card_content/\d+$", text
+                        r"^http://googleusercontent\.com/card_content/\d+", text
                     ):
                         text = candidate[22] and candidate[22][0] or text
 
@@ -470,7 +600,7 @@ class GeminiClient:
                         img_candidate = img_body[4][candidate_index]
 
                         text = re.sub(
-                            r"http://googleusercontent\.com/image_generation_content/\d+$",
+                            r"http://googleusercontent\.com/image_generation_content/\d+",
                             "",
                             img_candidate[1][0],
                         ).rstrip()
@@ -554,6 +684,9 @@ class ChatSession:
     model: `Model` | `str`, optional
         Specify the model to use for generation.
         Pass either a `gemini_webapi.constants.Model` enum or a model name string.
+    gem: `Gem | str`, optional
+        Specify a gem to use as system prompt for the chat session.
+        Pass either a `gemini_webapi.types.Gem` object or a gem id string.
     """
 
     __slots__ = [
@@ -561,6 +694,7 @@ class ChatSession:
         "geminiclient",
         "last_output",
         "model",
+        "gem",
     ]
 
     def __init__(
@@ -571,11 +705,13 @@ class ChatSession:
         rid: str | None = None,  # reply id
         rcid: str | None = None,  # reply candidate id
         model: Model | str = Model.UNSPECIFIED,
+        gem: Gem | str | None = None,
     ):
         self.__metadata: list[str | None] = [None, None, None]
         self.geminiclient: GeminiClient = geminiclient
         self.last_output: ModelOutput | None = None
-        self.model = model
+        self.model: Model | str = model
+        self.gem: Gem | str | None = gem
 
         if metadata:
             self.metadata = metadata
@@ -638,7 +774,12 @@ class ChatSession:
         """
 
         return await self.geminiclient.generate_content(
-            prompt=prompt, files=files, model=self.model, chat=self, **kwargs
+            prompt=prompt,
+            files=files,
+            model=self.model,
+            gem=self.gem,
+            chat=self,
+            **kwargs,
         )
 
     def choose_candidate(self, index: int) -> ModelOutput:

gemini_webapi/constants.py

@@ -1,11 +1,13 @@
-from enum import Enum
+from enum import Enum, IntEnum, StrEnum
 
 
-class Endpoint(Enum):
+class Endpoint(StrEnum):
+    GOOGLE = "https://www.google.com"
     INIT = "https://gemini.google.com/app"
     GENERATE = "https://gemini.google.com/_/BardChatUi/data/assistant.lamda.BardFrontendService/StreamGenerate"
     ROTATE_COOKIES = "https://accounts.google.com/RotateCookies"
     UPLOAD = "https://content-push.googleapis.com/upload"
+    BATCH_EXEC = "https://gemini.google.com/_/BardChatUi/data/batchexecute"
 
 
 class Headers(Enum):
@@ -45,16 +47,6 @@ class Model(Enum):
         {"x-goog-ext-525001261-jspb": '[null,null,null,null,"7ca48d02d802f20a"]'},
         False,
     )  # Deprecated
-    G_2_0_EXP_ADVANCED = (
-        "gemini-2.0-exp-advanced",
-        {"x-goog-ext-525001261-jspb": '[null,null,null,null,"b1e46a6037e6aa9f"]'},
-        True,
-    )  # Deprecated
-    G_2_5_EXP_ADVANCED = (
-        "gemini-2.5-exp-advanced",
-        {"x-goog-ext-525001261-jspb": '[null,null,null,null,"203e6bb81620bcfe"]'},
-        True,
-    )  # Deprecated
 
     def __init__(self, name, header, advanced_only):
         self.model_name = name
@@ -71,7 +63,7 @@ class Model(Enum):
         )
 
 
-class ErrorCode(Enum):
+class ErrorCode(IntEnum):
     """
     Known error codes returned from server.
     """

gemini_webapi/types/__init__.py

@@ -1,3 +1,6 @@
-from .image import Image, WebImage, GeneratedImage  # noqa: F401
-from .candidate import Candidate  # noqa: F401
-from .modeloutput import ModelOutput  # noqa: F401
+# flake8: noqa
+
+from .candidate import Candidate
+from .gem import Gem, GemJar
+from .image import Image, WebImage, GeneratedImage
+from .modeloutput import ModelOutput

gemini_webapi/types/gem.py

@@ -0,0 +1,132 @@
+from pydantic import BaseModel
+
+
+class Gem(BaseModel):
+    """
+    Reusable Gemini Gem object working as a system prompt, providing additional context to the model.
+    Gemini provides a set of predefined gems, and users can create custom gems as well.
+
+    Parameters
+    ----------
+    id: `str`
+        Unique identifier for the gem.
+    name: `str`
+        User-friendly name of the gem.
+    description: `str`, optional
+        Brief description of the gem's purpose or content.
+    prompt: `str`, optional
+        The system prompt text that the gem provides to the model.
+    predefined: `bool`
+        Indicates whether the gem is predefined by Gemini or created by the user.
+    """
+
+    id: str
+    name: str
+    description: str | None = None
+    prompt: str | None = None
+    predefined: bool
+
+    def __str__(self) -> str:
+        return (
+            f"Gem(id='{self.id}', name='{self.name}', description='{self.description}', "
+            f"prompt='{self.prompt}', predefined={self.predefined})"
+        )
+
+
+class GemJar(dict[str, Gem]):
+    """
+    Helper class for handling a collection of `Gem` objects, stored by their ID.
+    This class extends `dict` to allows retrieving gems with extra filtering options.
+    """
+
+    def __iter__(self):
+        """
+        Iter over the gems in the jar.
+        """
+
+        return self.values().__iter__()
+
+    def get(
+        self, id: str | None = None, name: str | None = None, default: Gem | None = None
+    ) -> Gem | None:
+        """
+        Retrieves a gem by its id and/or name.
+        If both id and name are provided, returns the gem that matches both id and name.
+        If only id is provided, it's a direct lookup.
+        If only name is provided, it searches through the gems.
+
+        Parameters
+        ----------
+        id: `str`, optional
+            The unique identifier of the gem to retrieve.
+        name: `str`, optional
+            The user-friendly name of the gem to retrieve.
+        default: `Gem`, optional
+            The default value to return if no matching gem is found.
+
+        Returns
+        -------
+        `Gem` | None
+            The matching gem if found, otherwise return the default value.
+
+        Raises
+        ------
+        `AssertionError`
+            If neither id nor name is provided.
+        """
+
+        assert not (
+            id is None and name is None
+        ), "At least one of gem id or name must be provided."
+
+        if id is not None:
+            gem_candidate = super().get(id)
+            if gem_candidate:
+                if name is not None:
+                    if gem_candidate.name == name:
+                        return gem_candidate
+                    else:
+                        return default
+                else:
+                    return gem_candidate
+            else:
+                return default
+        elif name is not None:
+            for gem_obj in self.values():
+                if gem_obj.name == name:
+                    return gem_obj
+            return default
+
+        # Should be unreachable due to the assertion.
+        return default
+
+    def filter(
+        self, predefined: bool | None = None, name: str | None = None
+    ) -> "GemJar":
+        """
+        Returns a new `GemJar` containing gems that match the given filters.
+
+        Parameters
+        ----------
+        predefined: `bool`, optional
+            If provided, filters gems by whether they are predefined (True) or user-created (False).
+        name: `str`, optional
+            If provided, filters gems by their name (exact match).
+
+        Returns
+        -------
+        `GemJar`
+            A new `GemJar` containing the filtered gems. Can be empty if no gems match the criteria.
+        """
+
+        filtered_gems = GemJar()
+
+        for gem_id, gem in self.items():
+            if predefined is not None and gem.predefined != predefined:
+                continue
+            if name is not None and gem.name != name:
+                continue
+
+            filtered_gems[gem_id] = gem
+
+        return GemJar(filtered_gems)

gemini_webapi/types/image.py

@@ -33,7 +33,7 @@ class Image(BaseModel):
         return f"{self.title}({self.url}) - {self.alt}"
 
     def __repr__(self):
-        return f"""Image(title='{self.title}', url='{len(self.url) <= 20 and self.url or self.url[:8] + '...' + self.url[-12:]}', alt='{self.alt}')"""
+        return f"Image(title='{self.title}', url='{len(self.url) <= 20 and self.url or self.url[:8] + '...' + self.url[-12:]}', alt='{self.alt}')"
 
     async def save(
         self,

gemini_webapi/utils/__init__.py

@@ -1,10 +1,12 @@
+# flake8: noqa
+
 from asyncio import Task
 
-from .upload_file import upload_file, parse_file_name  # noqa: F401
-from .rotate_1psidts import rotate_1psidts  # noqa: F401
-from .get_access_token import get_access_token  # noqa: F401
-from .load_browser_cookies import load_browser_cookies  # noqa: F401
-from .logger import logger, set_log_level  # noqa: F401
+from .upload_file import upload_file, parse_file_name
+from .rotate_1psidts import rotate_1psidts
+from .get_access_token import get_access_token
+from .load_browser_cookies import load_browser_cookies
+from .logger import logger, set_log_level
 
 
 rotate_tasks: dict[str, Task] = {}

gemini_webapi/utils/get_access_token.py

@@ -11,6 +11,26 @@ from .load_browser_cookies import load_browser_cookies
 from .logger import logger
 
 
+async def send_request(
+    cookies: dict, proxy: str | None = None
+) -> tuple[Response | None, dict]:
+    """
+    Send http request with provided cookies.
+    """
+
+    async with AsyncClient(
+        http2=True,
+        proxy=proxy,
+        headers=Headers.GEMINI.value,
+        cookies=cookies,
+        follow_redirects=True,
+        verify=False,
+    ) as client:
+        response = await client.get(Endpoint.INIT.value)
+        response.raise_for_status()
+        return response, cookies
+
+
 async def get_access_token(
     base_cookies: dict, proxy: str | None = None, verbose: bool = False
 ) -> tuple[str, dict]:
@@ -45,23 +65,23 @@ async def get_access_token(
         If all requests failed.
     """
 
-    async def send_request(cookies: dict) -> tuple[Response | None, dict]:
-        async with AsyncClient(
-            http2=True,
-            proxy=proxy,
-            headers=Headers.GEMINI.value,
-            cookies=cookies,
-            follow_redirects=True,
-        ) as client:
-            response = await client.get(Endpoint.INIT.value)
-            response.raise_for_status()
-            return response, cookies
+    async with AsyncClient(
+        http2=True,
+        proxy=proxy,
+        follow_redirects=True,
+        verify=False,
+    ) as client:
+        response = await client.get(Endpoint.GOOGLE.value)
+
+    extra_cookies = {}
+    if response.status_code == 200:
+        extra_cookies = response.cookies
 
     tasks = []
 
     # Base cookies passed directly on initializing client
     if "__Secure-1PSID" in base_cookies and "__Secure-1PSIDTS" in base_cookies:
-        tasks.append(Task(send_request(base_cookies)))
+        tasks.append(Task(send_request({**extra_cookies, **base_cookies}, proxy=proxy)))
     elif verbose:
         logger.debug(
             "Skipping loading base cookies. Either __Secure-1PSID or __Secure-1PSIDTS is not provided."
@@ -75,8 +95,12 @@ async def get_access_token(
         if cache_file.is_file():
             cached_1psidts = cache_file.read_text()
             if cached_1psidts:
-                cached_cookies = {**base_cookies, "__Secure-1PSIDTS": cached_1psidts}
-                tasks.append(Task(send_request(cached_cookies)))
+                cached_cookies = {
+                    **extra_cookies,
+                    **base_cookies,
+                    "__Secure-1PSIDTS": cached_1psidts,
+                }
+                tasks.append(Task(send_request(cached_cookies, proxy=proxy)))
             elif verbose:
                 logger.debug("Skipping loading cached cookies. Cache file is empty.")
         elif verbose:
@@ -88,10 +112,11 @@ async def get_access_token(
             cached_1psidts = cache_file.read_text()
             if cached_1psidts:
                 cached_cookies = {
+                    **extra_cookies,
                     "__Secure-1PSID": cache_file.stem[16:],
                     "__Secure-1PSIDTS": cached_1psidts,
                 }
-                tasks.append(Task(send_request(cached_cookies)))
+                tasks.append(Task(send_request(cached_cookies, proxy=proxy)))
                 valid_caches += 1
 
         if valid_caches == 0 and verbose:
@@ -108,7 +133,9 @@ async def get_access_token(
             local_cookies = {"__Secure-1PSID": secure_1psid}
             if secure_1psidts := browser_cookies.get("__Secure-1PSIDTS"):
                 local_cookies["__Secure-1PSIDTS"] = secure_1psidts
-            tasks.append(Task(send_request(local_cookies)))
+            if nid := browser_cookies.get("NID"):
+                local_cookies["NID"] = nid
+            tasks.append(Task(send_request(local_cookies, proxy=proxy)))
         elif verbose:
             logger.debug(
                 "Skipping loading local browser cookies. Login to gemini.google.com in your browser first."

gemini_webapi/utils/logger.py

@@ -1,39 +1,37 @@
-import atexit
-from sys import stderr
+import sys
+from loguru import logger as _logger
 
-from loguru._logger import Core as _Core
-from loguru._logger import Logger as _Logger
+_handler_id = None
 
-logger = _Logger(
-    core=_Core(),
-    exception=None,
-    depth=0,
-    record=False,
-    lazy=False,
-    colors=False,
-    raw=False,
-    capture=True,
-    patchers=[],
-    extra={},
-)
 
-if stderr:
-    logger.add(stderr, level="INFO")
-
-atexit.register(logger.remove)
-
-
-def set_log_level(level: str):
+def set_log_level(level: str | int) -> None:
     """
-    Set the log level for the whole module. Default is "INFO". Set to "DEBUG" to see more detailed logs.
+    Set the log level for gemini_webapi. The default log level is "INFO".
+
+    Note: calling this function for the first time will globally remove all existing loguru
+    handlers. To avoid this, you may want to set logging behaviors directly with loguru.
 
     Parameters
     ----------
-    level : str
-        The log level to set. Must be one of "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL".
+    level : `str | int`
+        Log level: "TRACE", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"
+
+    Examples
+    --------
+    >>> from gemini_webapi import set_log_level
+    >>> set_log_level("DEBUG")  # Show debug messages
+    >>> set_log_level("ERROR")  # Only show errors
     """
 
-    assert level in ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+    global _handler_id
+
+    _logger.remove(_handler_id)
+
+    _handler_id = _logger.add(
+        sys.stderr,
+        level=level,
+        filter=lambda record: record["extra"].get("name") == "gemini_webapi",
+    )
+
 
-    logger.remove()
-    logger.add(stderr, level=level)
+logger = _logger.bind(name="gemini_webapi")

{gemini_webapi-1.12.3.dist-info → gemini_webapi-1.14.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gemini-webapi
-Version: 1.12.3
+Version: 1.14.1
 Summary: ✨ An elegant async Python wrapper for Google Gemini web app
 Author: UZQueen
 License:                     GNU AFFERO GENERAL PUBLIC LICENSE
@@ -678,7 +678,8 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: httpx[http2]~=0.28.1
 Requires-Dist: loguru~=0.7.3
-Requires-Dist: pydantic~=2.11.3
+Requires-Dist: orjson~=3.10.18
+Requires-Dist: pydantic~=2.11.5
 Dynamic: license-file
 
 <p align="center">
@@ -713,8 +714,9 @@ A reverse-engineered asynchronous python wrapper for [Google Gemini](https://gem
 
 - **Persistent Cookies** - Automatically refreshes cookies in background. Optimized for always-on services.
 - **Image Generation** - Natively supports generating and modifying images with natural language.
+- **System Prompt** - Supports customizing model's system prompt with [Gemini Gems](https://gemini.google.com/gems/view).
 - **Extension Support** - Supports generating contents with [Gemini extensions](https://gemini.google.com/extensions) on, like YouTube and Gmail.
-- **Classified Outputs** - Automatically categorizes texts, web images and AI generated images in the response.
+- **Classified Outputs** - Categorizes texts, thoughts, web images and AI generated images in the response.
 - **Official Flavor** - Provides a simple and elegant interface inspired by [Google Generative AI](https://ai.google.dev/tutorials/python_quickstart)'s official API.
 - **Asynchronous** - Utilizes `asyncio` to run generating tasks and return outputs efficiently.
 
@@ -726,17 +728,18 @@ A reverse-engineered asynchronous python wrapper for [Google Gemini](https://gem
 - [Authentication](#authentication)
 - [Usage](#usage)
   - [Initialization](#initialization)
-  - [Select language model](#select-language-model)
-  - [Generate contents from text](#generate-contents-from-text)
+  - [Generate contents](#generate-contents)
   - [Generate contents with files](#generate-contents-with-files)
   - [Conversations across multiple turns](#conversations-across-multiple-turns)
   - [Continue previous conversations](#continue-previous-conversations)
+  - [Select language model](#select-language-model)
+  - [Apply system prompt with Gemini Gems](#apply-system-prompt-with-gemini-gems)
   - [Retrieve model's thought process](#retrieve-models-thought-process)
   - [Retrieve images in response](#retrieve-images-in-response)
-  - [Generate images with Imagen3](#generate-images-with-imagen3)
+  - [Generate images with Imagen4](#generate-images-with-imagen4)
   - [Generate contents with Gemini extensions](#generate-contents-with-gemini-extensions)
   - [Check and switch to other reply candidates](#check-and-switch-to-other-reply-candidates)
-  - [Control log level](#control-log-level)
+  - [Logging Configuration](#logging-configuration)
 - [References](#references)
 - [Stargazers](#stargazers)
 
@@ -748,13 +751,13 @@ A reverse-engineered asynchronous python wrapper for [Google Gemini](https://gem
 
 Install/update the package with pip.
 
-```bash
+```sh
 pip install -U gemini_webapi
 ```
 
 Optionally, package offers a way to automatically import cookies from your local browser. To enable this feature, install `browser-cookie3` as well. Supported platforms and browsers can be found [here](https://github.com/borisbabic/browser_cookie3?tab=readme-ov-file#contribute).
 
-```bash
+```sh
 pip install -U browser-cookie3
 ```
 
@@ -816,43 +819,9 @@ asyncio.run(main())
 >
 > `auto_close` and `close_delay` are optional arguments for automatically closing the client after a certain period of inactivity. This feature is disabled by default. In an always-on service like chatbot, it's recommended to set `auto_close` to `True` combined with reasonable seconds of `close_delay` for better resource management.
 
-### Select language model
-
-You can specify which language model to use by passing `model` argument to `GeminiClient.generate_content` or `GeminiClient.start_chat`. The default value is `unspecified`.
-
-Currently available models (as of Feb 5, 2025):
-
-- `unspecified` - Default model
-- `gemini-2.0-flash` - Gemini 2.0 Flash
-- `gemini-2.0-flash-thinking` - Gemini 2.0 Flash Thinking Experimental
-- `gemini-2.5-flash` - Gemini 2.5 Flash
-- `gemini-2.5-pro` - Gemini 2.5 Pro (daily usage limit imposed)
-
-Models pending update (may not work as expected):
-
-- `gemini-2.5-exp-advanced` - Gemini 2.5 Experimental Advanced **(requires Gemini Advanced account)**
-- `gemini-2.0-exp-advanced` - Gemini 2.0 Experimental Advanced **(requires Gemini Advanced account)**
-
-```python
-from gemini_webapi.constants import Model
-
-async def main():
-    response1 = await client.generate_content(
-        "What's you language model version? Reply version number only.",
-        model=Model.G_2_0_FLASH,
-    )
-    print(f"Model version ({Model.G_2_0_FLASH.model_name}): {response1.text}")
-
-    chat = client.start_chat(model="gemini-2.0-flash-thinking")
-    response2 = await chat.send_message("What's you language model version? Reply version number only.")
-    print(f"Model version (gemini-2.0-flash-thinking): {response2.text}")
-
-asyncio.run(main())
-```
+### Generate contents
 
-### Generate contents from text
-
-Ask a one-turn quick question by calling `GeminiClient.generate_content`.
+Ask a single-turn question by calling `GeminiClient.generate_content`, which returns a `gemini_webapi.ModelOutput` object containing the generated text, images, thoughts, and conversation metadata.
 
 ```python
 async def main():
@@ -883,7 +852,7 @@ asyncio.run(main())
 
 ### Conversations across multiple turns
 
-If you want to keep conversation continuous, please use `GeminiClient.start_chat` to create a `ChatSession` object and send messages through it. The conversation history will be automatically handled and get updated after each turn.
+If you want to keep conversation continuous, please use `GeminiClient.start_chat` to create a `gemini_webapi.ChatSession` object and send messages through it. The conversation history will be automatically handled and get updated after each turn.
 
 ```python
 async def main():
@@ -926,6 +895,70 @@ async def main():
 asyncio.run(main())
 ```
 
+### Select language model
+
+You can specify which language model to use by passing `model` argument to `GeminiClient.generate_content` or `GeminiClient.start_chat`. The default value is `unspecified`.
+
+Currently available models (as of June 12, 2025):
+
+- `unspecified` - Default model
+- `gemini-2.5-flash` - Gemini 2.5 Flash
+- `gemini-2.5-pro` - Gemini 2.5 Pro (daily usage limit imposed)
+
+Deprecated models (yet still working):
+
+- `gemini-2.0-flash` - Gemini 2.0 Flash
+- `gemini-2.0-flash-thinking` - Gemini 2.0 Flash Thinking
+
+```python
+from gemini_webapi.constants import Model
+
+async def main():
+    response1 = await client.generate_content(
+        "What's you language model version? Reply version number only.",
+        model=Model.G_2_5_FLASH,
+    )
+    print(f"Model version ({Model.G_2_5_FLASH.model_name}): {response1.text}")
+
+    chat = client.start_chat(model="gemini-2.5-pro")
+    response2 = await chat.send_message("What's you language model version? Reply version number only.")
+    print(f"Model version (gemini-2.5-pro): {response2.text}")
+
+asyncio.run(main())
+```
+
+### Apply system prompt with Gemini Gems
+
+System prompt can be applied to conversations via [Gemini Gems](https://gemini.google.com/gems/view). To use a gem, you can pass `gem` argument to `GeminiClient.generate_content` or `GeminiClient.start_chat`. `gem` can be either a string of gem id or a `gemini_webapi.Gem` object. Only one gem can be applied to a single conversation.
+
+```python
+async def main():
+    # Fetch all gems for the current account, including both predefined and user-created ones
+    await client.fetch_gems()
+
+    # Once fetched, gems will be cached in `GeminiClient.gems`
+    gems = client.gems
+
+    # Get the gem you want to use
+    system_gems = gems.filter(predefined=True)
+    coding_partner = system_gems.get(id="coding-partner")
+
+    response1 = await client.generate_content(
+        "what's your system prompt?",
+        model=Model.G_2_5_FLASH,
+        gem=coding_partner,
+    )
+    print(response1.text)
+
+    # Another example with a user-created custom gem
+    # Gem ids are consistent strings. Store them somewhere to avoid fetching gems every time
+    your_gem = gems.get(name="Your Gem Name")
+    your_gem_id = your_gem.id
+    chat = client.start_chat(gem=your_gem_id)
+    response2 = await chat.send_message("what's your system prompt?")
+    print(response2)
+```
+
 ### Retrieve model's thought process
 
 When using models with thinking capabilities, the model's thought process will be populated in `ModelOutput.thoughts`.
@@ -933,7 +966,7 @@ When using models with thinking capabilities, the model's thought process will b
 ```python
 async def main():
     response = await client.generate_content(
-            "What's 1+1?", model="gemini-2.0-flash-thinking"
+            "What's 1+1?", model="gemini-2.5-pro"
         )
     print(response.thoughts)
     print(response.text)
@@ -943,7 +976,7 @@ asyncio.run(main())
 
 ### Retrieve images in response
 
-Images in the API's output are stored as a list of `Image` objects. You can access the image title, URL, and description by calling `image.title`, `image.url` and `image.alt` respectively.
+Images in the API's output are stored as a list of `gemini_webapi.Image` objects. You can access the image title, URL, and description by calling `Image.title`, `Image.url` and `Image.alt` respectively.
 
 ```python
 async def main():
@@ -954,9 +987,9 @@ async def main():
 asyncio.run(main())
 ```
 
-### Generate images with Imagen3
+### Generate images with Imagen4
 
-You can ask Gemini to generate and modify images with Imagen3, Google's latest AI image generator, simply by natural language.
+You can ask Gemini to generate and modify images with Imagen4, Google's latest AI image generator, simply by natural language.
 
 > [!IMPORTANT]
 >
@@ -1015,7 +1048,7 @@ asyncio.run(main())
 
 ### Check and switch to other reply candidates
 
-A response from Gemini usually contains multiple reply candidates with different generated contents. You can check all candidates and choose one to continue the conversation. By default, the first candidate will be chosen automatically.
+A response from Gemini sometimes contains multiple reply candidates with different generated contents. You can check all candidates and choose one to continue the conversation. By default, the first candidate will be chosen.
 
 ```python
 async def main():
@@ -1036,9 +1069,9 @@ async def main():
 asyncio.run(main())
 ```
 
-### Control log level
+### Logging Configuration
 
-You can set the log level of the package to one of the following values: `DEBUG`, `INFO`, `WARNING`, `ERROR` and `CRITICAL`. The default value is `INFO`.
+This package uses [loguru](https://loguru.readthedocs.io/en/stable/) for logging, and exposes a function `set_log_level` to control log level. You can set log level to one of the following values: `DEBUG`, `INFO`, `WARNING`, `ERROR` and `CRITICAL`. The default value is `INFO`.
 
 ```python
 from gemini_webapi import set_log_level
@@ -1046,6 +1079,10 @@ from gemini_webapi import set_log_level
 set_log_level("DEBUG")
 ```
 
+> [!NOTE]
+>
+> Calling `set_log_level` for the first time will **globally** remove all existing loguru handlers. You may want to configure logging directly with loguru to avoid this issue and have more advanced control over logging behaviors.
+
 ## References
 
 [Google AI Studio](https://ai.google.dev/tutorials/ai-studio_quickstart)

gemini_webapi-1.14.1.dist-info/RECORD

@@ -0,0 +1,20 @@
+gemini_webapi/__init__.py,sha256=7ELCiUoI10ea3daeJxnv0UwqLVKpM7rxsgOZsPMstO8,150
+gemini_webapi/client.py,sha256=9t_ytH4ClkjJWUwvLJ6KyArSRbNeGxd2MJVyPUmBIUA,30333
+gemini_webapi/constants.py,sha256=rkugkck9qXW_f-9dc0XXEjVIzJ9Ja4gHBVYDP71BESg,2352
+gemini_webapi/exceptions.py,sha256=qkXrIpr0L7LtGbq3VcTO8D1xZ50pJtt0dDRp5I3uDSg,1038
+gemini_webapi/types/__init__.py,sha256=Xap_FGOKOOC9mU3bmp_VT_1pQgFMuqbys_fOcyvTnuE,166
+gemini_webapi/types/candidate.py,sha256=67BhY75toE5mVuB21cmHcTFtw332V_KmCjr3-9VTbJo,1477
+gemini_webapi/types/gem.py,sha256=3Ppjq9V22Zp4Lb9a9ZnDviDKQpfSQf8UZxqOEjeEWd4,4070
+gemini_webapi/types/image.py,sha256=MflOex2tAxBF5zQkYTGTR78CuiqH3Wa6KxMKKXr5Yvo,5233
+gemini_webapi/types/modeloutput.py,sha256=h07kQOkL5r-oPLvZ59uVtO1eP4FGy5ZpzuYQzAeQdr8,1196
+gemini_webapi/utils/__init__.py,sha256=cJ9HQYxr8l0CsY61TFlho-5DdPxCaEOpRfjxPX-eils,320
+gemini_webapi/utils/get_access_token.py,sha256=eNn1omFO41wWXco1eM-KXR2CEi0Tb-chlph7H-PCNjg,6137
+gemini_webapi/utils/load_browser_cookies.py,sha256=A5n_VsB7Rm8ck5lpy856UNJEhv30l3dvQ3j0g3ln1fE,1535
+gemini_webapi/utils/logger.py,sha256=0VcxhVLhHBRDQutNCpapP1y_MhPoQ2ud1uIFLqxC3Z8,958
+gemini_webapi/utils/rotate_1psidts.py,sha256=NyQ9OYPLBOcvpc8bodvEYDIVFrsYN0kdfc831lPEctM,1680
+gemini_webapi/utils/upload_file.py,sha256=SJOMr6kryK_ClrKmqI96fqZBNFOMPsyAvFINAGAU3rk,1468
+gemini_webapi-1.14.1.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
+gemini_webapi-1.14.1.dist-info/METADATA,sha256=Qlym2uwFz03bgKIed0UtBmLMGXfpJwJ8j-2qMraLgJw,58925
+gemini_webapi-1.14.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+gemini_webapi-1.14.1.dist-info/top_level.txt,sha256=dtWtug_ZrmnUqCYuu8NmGzTgWglHeNzhHU_hXmqZGWE,14
+gemini_webapi-1.14.1.dist-info/RECORD,,

{gemini_webapi-1.12.3.dist-info → gemini_webapi-1.14.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.8.0)
+Generator: setuptools (80.9.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

gemini_webapi-1.12.3.dist-info/RECORD

@@ -1,19 +0,0 @@
-gemini_webapi/__init__.py,sha256=28uNIywK4vCXxENaSagNWUzhqr1RyNtLzDF6WRRM4KQ,194
-gemini_webapi/client.py,sha256=W4t4z9Q8tBiS7URdVKFytyELzQylV-K_82NsSqkvrgU,25398
-gemini_webapi/constants.py,sha256=2KKPqz0r3DKYuxQhwCQpTBQmp9sqFMrH88n3wG41V7g,2572
-gemini_webapi/exceptions.py,sha256=qkXrIpr0L7LtGbq3VcTO8D1xZ50pJtt0dDRp5I3uDSg,1038
-gemini_webapi/types/__init__.py,sha256=d2kvXnE004s2E2KDmPPLi5N-BQ59FgDSlrGrO3Wphww,163
-gemini_webapi/types/candidate.py,sha256=67BhY75toE5mVuB21cmHcTFtw332V_KmCjr3-9VTbJo,1477
-gemini_webapi/types/image.py,sha256=4BC8hxAWJrYFwzA60CivF1di4RZkzPKjcaSPPFKmRdY,5237
-gemini_webapi/types/modeloutput.py,sha256=h07kQOkL5r-oPLvZ59uVtO1eP4FGy5ZpzuYQzAeQdr8,1196
-gemini_webapi/utils/__init__.py,sha256=tO6Sx-3fcPeyITZcvUmcFKBFlR5XW87xUFbNrIh3_mE,374
-gemini_webapi/utils/get_access_token.py,sha256=uyb6tuzPr3mHttCjiM86M29ykrnHqsUClYdf5sVkyEQ,5465
-gemini_webapi/utils/load_browser_cookies.py,sha256=A5n_VsB7Rm8ck5lpy856UNJEhv30l3dvQ3j0g3ln1fE,1535
-gemini_webapi/utils/logger.py,sha256=PF4ROQq7scRRrWzeYdeYiYs2S2Jqr0bgjyrPbXVOCqE,816
-gemini_webapi/utils/rotate_1psidts.py,sha256=NyQ9OYPLBOcvpc8bodvEYDIVFrsYN0kdfc831lPEctM,1680
-gemini_webapi/utils/upload_file.py,sha256=SJOMr6kryK_ClrKmqI96fqZBNFOMPsyAvFINAGAU3rk,1468
-gemini_webapi-1.12.3.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
-gemini_webapi-1.12.3.dist-info/METADATA,sha256=A-7kQZNvMeii9afd8XtpLo8pX2oQ8ivqpoj3WOljoJI,57167
-gemini_webapi-1.12.3.dist-info/WHEEL,sha256=zaaOINJESkSfm_4HQVc5ssNzHCPXhJm0kEUakpsEHaU,91
-gemini_webapi-1.12.3.dist-info/top_level.txt,sha256=dtWtug_ZrmnUqCYuu8NmGzTgWglHeNzhHU_hXmqZGWE,14
-gemini_webapi-1.12.3.dist-info/RECORD,,