gemini-webapi 1.17.3__py3-none-any.whl → 1.18.0__py3-none-any.whl

gemini_webapi/client.py

@@ -1,19 +1,21 @@
 import asyncio
+import codecs
+import io
+import random
 import re
 from asyncio import Task
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any, AsyncGenerator, Optional
 
 import orjson as json
-from httpx import AsyncClient, ReadTimeout, Response
+from httpx import AsyncClient, Cookies, ReadTimeout, Response
 
 from .components import GemMixin
-from .constants import Endpoint, ErrorCode, Headers, Model
+from .constants import Endpoint, ErrorCode, GRPC, Headers, Model
 from .exceptions import (
     APIError,
     AuthError,
     GeminiError,
-    ImageGenerationError,
     ModelInvalid,
     TemporarilyBlocked,
     TimeoutError,
@@ -28,13 +30,12 @@ from .types import (
     WebImage,
 )
 from .utils import (
-    extract_json_from_response,
     get_access_token,
     get_nested_value,
     logger,
     parse_file_name,
+    parse_stream_frames,
     rotate_1psidts,
-    rotate_tasks,
     running,
     upload_file,
 )
@@ -52,7 +53,7 @@ class GeminiClient(GemMixin):
     secure_1psid: `str`, optional
         __Secure-1PSID cookie value.
     secure_1psidts: `str`, optional
-        __Secure-1PSIDTS cookie value, some google accounts don't require this value, provide only if it's in the cookie list.
+        __Secure-1PSIDTS cookie value, some Google accounts don't require this value, provide only if it's in the cookie list.
     proxy: `str`, optional
         Proxy URL.
     kwargs: `dict`, optional
@@ -71,12 +72,18 @@ class GeminiClient(GemMixin):
         "_running",
         "client",
         "access_token",
+        "build_label",
+        "session_id",
         "timeout",
         "auto_close",
         "close_delay",
         "close_task",
         "auto_refresh",
         "refresh_interval",
+        "refresh_task",
+        "verbose",
+        "_lock",
+        "_reqid",
         "_gems",  # From GemMixin
         "kwargs",
     ]
@@ -89,23 +96,31 @@ class GeminiClient(GemMixin):
         **kwargs,
     ):
         super().__init__()
-        self.cookies = {}
+        self.cookies = Cookies()
         self.proxy = proxy
         self._running: bool = False
         self.client: AsyncClient | None = None
         self.access_token: str | None = None
+        self.build_label: str | None = None
+        self.session_id: str | None = None
         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.refresh_task: Task | None = None
+        self.verbose: bool = True
+        self._lock = asyncio.Lock()
+        self._reqid: int = random.randint(10000, 99999)
         self.kwargs = kwargs
 
         if secure_1psid:
-            self.cookies["__Secure-1PSID"] = secure_1psid
+            self.cookies.set("__Secure-1PSID", secure_1psid, domain=".google.com")
             if secure_1psidts:
-                self.cookies["__Secure-1PSIDTS"] = secure_1psidts
+                self.cookies.set(
+                    "__Secure-1PSIDTS", secure_1psidts, domain=".google.com"
+                )
 
     async def init(
         self,
@@ -129,50 +144,64 @@ class GeminiClient(GemMixin):
         close_delay: `float`, optional
             Time to wait before auto-closing the client in seconds. Effective only if `auto_close` is `True`.
         auto_refresh: `bool`, optional
-            If `True`, will schedule a task to automatically refresh cookies in the background.
+            If `True`, will schedule a task to automatically refresh cookies and access token in the background.
         refresh_interval: `float`, optional
-            Time interval for background cookie refresh in seconds. Effective only if `auto_refresh` is `True`.
+            Time interval for background cookie and access token refresh in seconds. Effective only if `auto_refresh` is `True`.
         verbose: `bool`, optional
             If `True`, will print more infomation in logs.
         """
 
-        try:
-            access_token, valid_cookies = await get_access_token(
-                base_cookies=self.cookies, proxy=self.proxy, verbose=verbose
-            )
+        async with self._lock:
+            if self._running:
+                return
 
-            self.client = AsyncClient(
-                timeout=timeout,
-                proxy=self.proxy,
-                follow_redirects=True,
-                headers=Headers.GEMINI.value,
-                cookies=valid_cookies,
-                **self.kwargs,
-            )
-            self.access_token = access_token
-            self.cookies = valid_cookies
-            self._running = True
-
-            self.timeout = timeout
-            self.auto_close = auto_close
-            self.close_delay = close_delay
-            if self.auto_close:
-                await self.reset_close_task()
-
-            self.auto_refresh = auto_refresh
-            self.refresh_interval = refresh_interval
-            if task := rotate_tasks.get(self.cookies["__Secure-1PSID"]):
-                task.cancel()
-            if self.auto_refresh:
-                rotate_tasks[self.cookies["__Secure-1PSID"]] = asyncio.create_task(
-                    self.start_auto_refresh()
+            try:
+                self.verbose = verbose
+                access_token, build_label, session_id, valid_cookies = (
+                    await get_access_token(
+                        base_cookies=self.cookies,
+                        proxy=self.proxy,
+                        verbose=self.verbose,
+                        verify=self.kwargs.get("verify", True),
+                    )
                 )
 
-            if verbose:
-                logger.success("Gemini client initialized successfully.")
-        except Exception:
-            await self.close()
-            raise
+                self.client = AsyncClient(
+                    http2=True,
+                    timeout=timeout,
+                    proxy=self.proxy,
+                    follow_redirects=True,
+                    headers=Headers.GEMINI.value,
+                    cookies=valid_cookies,
+                    **self.kwargs,
+                )
+                self.access_token = access_token
+                self.cookies = valid_cookies
+                self.build_label = build_label
+                self.session_id = session_id
+                self._running = True
+
+                self.timeout = timeout
+                self.auto_close = auto_close
+                self.close_delay = close_delay
+                if self.auto_close:
+                    await self.reset_close_task()
+
+                self.auto_refresh = auto_refresh
+                self.refresh_interval = refresh_interval
+
+                if self.refresh_task:
+                    self.refresh_task.cancel()
+                    self.refresh_task = None
+
+                if self.auto_refresh:
+                    self.refresh_task = asyncio.create_task(self.start_auto_refresh())
+
+                if self.verbose:
+                    logger.success("Gemini client initialized successfully.")
+            except Exception:
+                await self.close()
+                raise
 
     async def close(self, delay: float = 0) -> None:
         """
@@ -193,6 +222,10 @@ class GeminiClient(GemMixin):
             self.close_task.cancel()
             self.close_task = None
 
+        if self.refresh_task:
+            self.refresh_task.cancel()
+            self.refresh_task = None
+
         if self.client:
             await self.client.aclose()
 
@@ -211,34 +244,49 @@ class GeminiClient(GemMixin):
         """
         Start the background task to automatically refresh cookies.
         """
+        if self.refresh_interval < 60:
+            self.refresh_interval = 60
+
+        while self._running:
+            await asyncio.sleep(self.refresh_interval)
+
+            if not self._running:
+                break
 
-        while True:
-            new_1psidts: str | None = None
             try:
-                new_1psidts = await rotate_1psidts(self.cookies, self.proxy)
+                async with self._lock:
+                    # Refresh all cookies in the background to keep the session alive.
+                    new_1psidts, rotated_cookies = await rotate_1psidts(
+                        self.cookies, self.proxy
+                    )
+                    if rotated_cookies:
+                        self.cookies.update(rotated_cookies)
+                        if self.client:
+                            self.client.cookies.update(rotated_cookies)
+
+                    if new_1psidts:
+                        if rotated_cookies:
+                            logger.debug("Cookies refreshed (network update).")
+                        else:
+                            logger.debug("Cookies are up to date (cached).")
+                    else:
+                        logger.warning(
+                            "Rotation response did not contain a new __Secure-1PSIDTS. "
+                            "Session might expire soon if this persists."
+                        )
+            except asyncio.CancelledError:
+                raise
             except AuthError:
-                if task := rotate_tasks.get(self.cookies.get("__Secure-1PSID", "")):
-                    task.cancel()
                 logger.warning(
-                    "AuthError: Failed to refresh cookies. Auto refresh task canceled."
+                    "AuthError: Failed to refresh cookies. Retrying in next interval."
                 )
-                return
-            except Exception as exc:
-                logger.warning(f"Unexpected error while refreshing cookies: {exc}")
-
-            if new_1psidts:
-                self.cookies["__Secure-1PSIDTS"] = new_1psidts
-                if self._running:
-                    self.client.cookies.set("__Secure-1PSIDTS", new_1psidts)
-                logger.debug("Cookies refreshed. New __Secure-1PSIDTS applied.")
+            except Exception as e:
+                logger.warning(f"Unexpected error while refreshing cookies: {e}")
 
-            await asyncio.sleep(self.refresh_interval)
-
-    @running(retry=2)
     async def generate_content(
         self,
         prompt: str,
-        files: list[str | Path] | None = None,
+        files: list[str | Path | bytes | io.BytesIO] | None = None,
         model: Model | str | dict = Model.UNSPECIFIED,
         gem: Gem | str | None = None,
         chat: Optional["ChatSession"] = None,
@@ -285,6 +333,182 @@ class GeminiClient(GemMixin):
             - If response structure is invalid and failed to parse.
         """
 
+        if self.auto_close:
+            await self.reset_close_task()
+
+        if not (isinstance(chat, ChatSession) and chat.cid):
+            self._reqid = random.randint(10000, 99999)
+
+        file_data = None
+        if files:
+            await self._batch_execute(
+                [
+                    RPCData(
+                        rpcid=GRPC.BARD_ACTIVITY,
+                        payload='[[["bard_activity_enabled"]]]',
+                    )
+                ]
+            )
+
+            uploaded_urls = await asyncio.gather(
+                *(upload_file(file, self.proxy) for file in files)
+            )
+            file_data = [
+                [[url], parse_file_name(file)]
+                for url, file in zip(uploaded_urls, files)
+            ]
+
+        try:
+            await self._batch_execute(
+                [
+                    RPCData(
+                        rpcid=GRPC.BARD_ACTIVITY,
+                        payload='[[["bard_activity_enabled"]]]',
+                    )
+                ]
+            )
+
+            output = None
+            async for output in self._generate(
+                prompt=prompt,
+                req_file_data=file_data,
+                model=model,
+                gem=gem,
+                chat=chat,
+                **kwargs,
+            ):
+                pass
+
+            if output is None:
+                raise GeminiError(
+                    "Failed to generate contents. No output data found in response."
+                )
+
+            if isinstance(chat, ChatSession):
+                chat.last_output = output
+
+            return output
+
+        finally:
+            if files:
+                for file in files:
+                    if isinstance(file, io.BytesIO):
+                        file.close()
+
+    async def generate_content_stream(
+        self,
+        prompt: str,
+        files: list[str | Path | bytes | io.BytesIO] | None = None,
+        model: Model | str | dict = Model.UNSPECIFIED,
+        gem: Gem | str | None = None,
+        chat: Optional["ChatSession"] = None,
+        **kwargs,
+    ) -> AsyncGenerator[ModelOutput, None]:
+        """
+        Generates contents with prompt in streaming mode.
+
+        This method sends a request to Gemini and yields partial responses as they arrive.
+        It automatically calculates the text delta (new characters) to provide a smooth
+        streaming experience. It also continuously updates chat metadata and candidate IDs.
+
+        Parameters
+        ----------
+        prompt: `str`
+            Prompt provided by user.
+        files: `list[str | Path | bytes | io.BytesIO]`, optional
+            List of file paths or byte streams to be attached.
+        model: `Model | str | dict`, optional
+            Specify the model to use for generation.
+        gem: `Gem | str`, optional
+            Specify a gem to use as system prompt for the chat session.
+        chat: `ChatSession`, optional
+            Chat data to retrieve conversation history.
+        kwargs: `dict`, optional
+            Additional arguments passed to `httpx.AsyncClient.stream`.
+
+        Yields
+        ------
+        :class:`ModelOutput`
+            Partial output data. The `text` attribute contains only the NEW characters
+            received since the last yield.
+
+        Raises
+        ------
+        `gemini_webapi.APIError`
+            If the request fails or response structure is invalid.
+        `gemini_webapi.TimeoutError`
+            If the stream request times out.
+        """
+
+        if self.auto_close:
+            await self.reset_close_task()
+
+        if not (isinstance(chat, ChatSession) and chat.cid):
+            self._reqid = random.randint(10000, 99999)
+
+        file_data = None
+        if files:
+            await self._batch_execute(
+                [
+                    RPCData(
+                        rpcid=GRPC.BARD_ACTIVITY,
+                        payload='[[["bard_activity_enabled"]]]',
+                    )
+                ]
+            )
+
+            uploaded_urls = await asyncio.gather(
+                *(upload_file(file, self.proxy) for file in files)
+            )
+            file_data = [
+                [[url], parse_file_name(file)]
+                for url, file in zip(uploaded_urls, files)
+            ]
+
+        try:
+            await self._batch_execute(
+                [
+                    RPCData(
+                        rpcid=GRPC.BARD_ACTIVITY,
+                        payload='[[["bard_activity_enabled"]]]',
+                    )
+                ]
+            )
+
+            output = None
+            async for output in self._generate(
+                prompt=prompt,
+                req_file_data=file_data,
+                model=model,
+                gem=gem,
+                chat=chat,
+                **kwargs,
+            ):
+                yield output
+
+            if output and isinstance(chat, ChatSession):
+                chat.last_output = output
+
+        finally:
+            if files:
+                for file in files:
+                    if isinstance(file, io.BytesIO):
+                        file.close()
+
+    @running(retry=5)
+    async def _generate(
+        self,
+        prompt: str,
+        req_file_data: list[Any] | None = None,
+        model: Model | str | dict = Model.UNSPECIFIED,
+        gem: Gem | str | None = None,
+        chat: Optional["ChatSession"] = None,
+        **kwargs,
+    ) -> AsyncGenerator[ModelOutput, None]:
+        """
+        Internal method which actually sends content generation requests.
+        """
+
         assert prompt, "Prompt cannot be empty."
 
         if isinstance(model, str):
@@ -297,253 +521,298 @@ class GeminiClient(GemMixin):
                 f"string, or dictionary; got `{type(model).__name__}`"
             )
 
-        if isinstance(gem, Gem):
-            gem_id = gem.id
-        else:
-            gem_id = gem
+        _reqid = self._reqid
+        self._reqid += 100000
 
-        if self.auto_close:
-            await self.reset_close_task()
+        gem_id = gem.id if isinstance(gem, Gem) else gem
 
         try:
-            response = await self.client.post(
-                Endpoint.GENERATE.value,
+            message_content = [
+                prompt,
+                0,
+                None,
+                req_file_data,
+                None,
+                None,
+                0,
+            ]
+
+            params: dict[str, Any] = {"_reqid": _reqid, "rt": "c"}
+            if self.build_label:
+                params["bl"] = self.build_label
+            if self.session_id:
+                params["f.sid"] = self.session_id
+
+            inner_req_list: list[Any] = [None] * 69
+            inner_req_list[0] = message_content
+            inner_req_list[2] = (
+                chat.metadata
+                if chat
+                else ["", "", "", None, None, None, None, None, None, ""]
+            )
+            inner_req_list[7] = 1  # Enable Snapshot Streaming
+            if gem_id:
+                inner_req_list[19] = gem_id
+
+            request_data = {
+                "at": self.access_token,
+                "f.req": json.dumps(
+                    [
+                        None,
+                        json.dumps(inner_req_list).decode("utf-8"),
+                    ]
+                ).decode("utf-8"),
+            }
+
+            async with self.client.stream(
+                "POST",
+                Endpoint.GENERATE,
+                params=params,
                 headers=model.model_header,
-                data={
-                    "at": self.access_token,
-                    "f.req": json.dumps(
-                        [
-                            None,
-                            json.dumps(
-                                [
-                                    files
-                                    and [
-                                        prompt,
-                                        0,
-                                        None,
-                                        [
-                                            [
-                                                [await upload_file(file, self.proxy)],
-                                                parse_file_name(file),
-                                            ]
-                                            for file in files
-                                        ],
-                                    ]
-                                    or [prompt],
-                                    None,
-                                    chat and chat.metadata,
-                                ]
-                                + (gem_id and [None] * 16 + [gem_id] or [])
-                            ).decode(),
-                        ]
-                    ).decode(),
-                },
+                data=request_data,
                 **kwargs,
-            )
-        except ReadTimeout:
-            raise TimeoutError(
-                "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:
-            await self.close()
-            raise APIError(
-                f"Failed to generate contents. Request failed with status code {response.status_code}"
-            )
-        else:
-            response_json: list[Any] = []
-            body: list[Any] = []
-            body_index = 0
+            ) as response:
+                if response.status_code != 200:
+                    await self.close()
+                    raise APIError(
+                        f"Failed to generate contents. Status: {response.status_code}"
+                    )
 
-            try:
-                response_json = extract_json_from_response(response.text)
+                if self.client:
+                    self.cookies.update(self.client.cookies)
 
-                for part_index, part in enumerate(response_json):
-                    try:
-                        part_body = get_nested_value(part, [2])
-                        if not part_body:
-                            continue
+                buffer = ""
+                decoder = codecs.getincrementaldecoder("utf-8")(errors="replace")
 
-                        part_json = json.loads(part_body)
-                        if get_nested_value(part_json, [4]):
-                            body_index, body = part_index, part_json
-                            break
-                    except json.JSONDecodeError:
-                        continue
+                # Track last seen content for each candidate by rcid
+                last_texts: dict[str, str] = {}
+                last_thoughts: dict[str, str] = {}
 
-                if not body:
-                    raise Exception
-            except Exception:
-                await self.close()
+                is_busy = False
+                has_candidates = False
 
-                try:
-                    error_code = get_nested_value(response_json, [0, 5, 2, 0, 1, 0], -1)
-                    match error_code:
-                        case ErrorCode.USAGE_LIMIT_EXCEEDED:
-                            raise UsageLimitExceeded(
-                                f"Failed to generate contents. Usage limit of {model.model_name} model has exceeded. Please try switching to another model."
-                            )
-                        case ErrorCode.MODEL_INCONSISTENT:
-                            raise ModelInvalid(
-                                "Failed to generate contents. The specified model is inconsistent with the chat history. Please make sure to pass the same "
-                                "`model` parameter when starting a chat session with previous metadata."
-                            )
-                        case ErrorCode.MODEL_HEADER_INVALID:
-                            raise ModelInvalid(
-                                "Failed to generate contents. The specified model is not available. Please update gemini_webapi to the latest version. "
-                                "If the error persists and is caused by the package, please report it on GitHub."
-                            )
-                        case ErrorCode.IP_TEMPORARILY_BLOCKED:
-                            raise TemporarilyBlocked(
-                                "Failed to generate contents. Your IP address is temporarily blocked by Google. Please try using a proxy or waiting for a while."
-                            )
-                        case _:
-                            raise Exception
-                except GeminiError:
-                    raise
-                except Exception:
-                    logger.debug(f"Invalid response: {response.text}")
-                    raise APIError(
-                        "Failed to generate contents. Invalid response data received. Client will try to re-initialize on next request."
-                    )
-
-            try:
-                candidate_list: list[Any] = get_nested_value(body, [4], [])
-                output_candidates: list[Candidate] = []
-
-                for candidate_index, candidate in enumerate(candidate_list):
-                    rcid = get_nested_value(candidate, [0])
-                    if not rcid:
-                        continue  # Skip candidate if it has no rcid
-
-                    # Text output and thoughts
-                    text = get_nested_value(candidate, [1, 0], "")
-                    if re.match(
-                        r"^http://googleusercontent\.com/card_content/\d+", text
-                    ):
-                        text = get_nested_value(candidate, [22, 0]) or text
-
-                    thoughts = get_nested_value(candidate, [37, 0, 0])
-
-                    # Web images
-                    web_images = []
-                    for web_img_data in get_nested_value(candidate, [12, 1], []):
-                        url = get_nested_value(web_img_data, [0, 0, 0])
-                        if not url:
-                            continue
+                async for chunk in response.aiter_bytes():
+                    buffer += decoder.decode(chunk, final=False)
+                    if buffer.startswith(")]}'"):
+                        buffer = buffer[4:].lstrip()
 
-                        web_images.append(
-                            WebImage(
-                                url=url,
-                                title=get_nested_value(web_img_data, [7, 0], ""),
-                                alt=get_nested_value(web_img_data, [0, 4], ""),
-                                proxy=self.proxy,
-                            )
-                        )
+                    parsed_parts, buffer = parse_stream_frames(buffer)
 
-                    # Generated images
-                    generated_images = []
-                    if get_nested_value(candidate, [12, 7, 0]):
-                        img_body = None
-                        for img_part_index, part in enumerate(response_json):
-                            if img_part_index < body_index:
-                                continue
+                    for part in parsed_parts:
+                        part_json = None
+                        # 0. Update chat metadata first whenever available to support follow-up polls
+                        inner_json_str = get_nested_value(part, [2])
+                        if inner_json_str:
                             try:
-                                img_part_body = get_nested_value(part, [2])
-                                if not img_part_body:
-                                    continue
-
-                                img_part_json = json.loads(img_part_body)
-                                if get_nested_value(
-                                    img_part_json, [4, candidate_index, 12, 7, 0]
+                                part_json = json.loads(inner_json_str)
+                                m_data = get_nested_value(part_json, [1])
+                                if m_data and isinstance(chat, ChatSession):
+                                    chat.metadata = m_data
+
+                                # Update context string from index 25 if available
+                                context_str = get_nested_value(part_json, [25])
+                                if isinstance(context_str, str) and isinstance(
+                                    chat, ChatSession
                                 ):
-                                    img_body = img_part_json
-                                    break
+                                    chat.metadata = [None] * 9 + [context_str]
                             except json.JSONDecodeError:
-                                continue
+                                pass
+
+                        # 1. Check for fatal error codes in any part
+                        error_code = get_nested_value(part, [5, 2, 0, 1, 0])
+                        if error_code:
+                            await self.close()
+                            match error_code:
+                                case ErrorCode.USAGE_LIMIT_EXCEEDED:
+                                    raise UsageLimitExceeded(
+                                        f"Usage limit exceeded for model '{model.model_name}'. Please wait a few minutes, "
+                                        "switch to a different model (e.g., Gemini Flash), or check your account limits on gemini.google.com."
+                                    )
+                                case ErrorCode.MODEL_INCONSISTENT:
+                                    raise ModelInvalid(
+                                        "The specified model is inconsistent with the conversation history. "
+                                        "Please ensure you are using the same 'model' parameter throughout the entire ChatSession."
+                                    )
+                                case ErrorCode.MODEL_HEADER_INVALID:
+                                    raise ModelInvalid(
+                                        f"The model '{model.model_name}' is currently unavailable or the request structure is outdated. "
+                                        "Please update 'gemini_webapi' to the latest version or report this on GitHub if the problem persists."
+                                    )
+                                case ErrorCode.IP_TEMPORARILY_BLOCKED:
+                                    raise TemporarilyBlocked(
+                                        "Your IP address has been temporarily flagged or blocked by Google. "
+                                        "Please try using a proxy, a different network, or wait for a while before retrying."
+                                    )
+                                case _:
+                                    raise APIError(
+                                        f"Failed to generate contents (stream). Unknown API error code: {error_code}. "
+                                        "This might be a temporary Google service issue."
+                                    )
+
+                        # 2. Detect if model is busy analyzing data (Thinking state)
+                        if "data_analysis_tool" in str(part):
+                            is_busy = True
+                            if not has_candidates:
+                                logger.debug("Model is busy (thinking/analyzing)...")
+
+                        # 3. Check for queueing status
+                        status = get_nested_value(part, [5])
+                        if isinstance(status, list) and status:
+                            is_busy = True
+                            if not has_candidates:
+                                logger.debug(
+                                    "Model is in a waiting state (queueing)..."
+                                )
 
-                        if not img_body:
-                            raise ImageGenerationError(
-                                "Failed to parse generated images. Please update gemini_webapi to the latest version. "
-                                "If the error persists and is caused by the package, please report it on GitHub."
-                            )
+                        if not inner_json_str:
+                            continue
 
-                        img_candidate = get_nested_value(
-                            img_body, [4, candidate_index], []
-                        )
+                        try:
+                            if part_json is None:
+                                part_json = json.loads(inner_json_str)
 
-                        if finished_text := get_nested_value(
-                            img_candidate, [1, 0]
-                        ):  # Only overwrite if new text is returned after image generation
-                            text = re.sub(
-                                r"http://googleusercontent\.com/image_generation_content/\d+",
-                                "",
-                                finished_text,
-                            ).rstrip()
-
-                        for img_index, gen_img_data in enumerate(
-                            get_nested_value(img_candidate, [12, 7, 0], [])
-                        ):
-                            url = get_nested_value(gen_img_data, [0, 3, 3])
-                            if not url:
+                            # Extract data from candidates
+                            candidates_list = get_nested_value(part_json, [4], [])
+                            if not candidates_list:
                                 continue
 
-                            img_num = get_nested_value(gen_img_data, [3, 6])
-                            title = (
-                                f"[Generated Image {img_num}]"
-                                if img_num
-                                else "[Generated Image]"
-                            )
-
-                            alt_list = get_nested_value(gen_img_data, [3, 5], [])
-                            alt = (
-                                get_nested_value(alt_list, [img_index])
-                                or get_nested_value(alt_list, [0])
-                                or ""
-                            )
-
-                            generated_images.append(
-                                GeneratedImage(
-                                    url=url,
-                                    title=title,
-                                    alt=alt,
-                                    proxy=self.proxy,
-                                    cookies=self.cookies,
+                            output_candidates = []
+                            any_changed = False
+
+                            for candidate_data in candidates_list:
+                                rcid = get_nested_value(candidate_data, [0])
+                                if not rcid:
+                                    continue
+
+                                if isinstance(chat, ChatSession):
+                                    chat.rcid = rcid
+
+                                # Text output and thoughts
+                                text = get_nested_value(candidate_data, [1, 0], "")
+                                if re.match(
+                                    r"^http://googleusercontent\.com/card_content/\d+",
+                                    text,
+                                ):
+                                    text = (
+                                        get_nested_value(candidate_data, [22, 0])
+                                        or text
+                                    )
+
+                                # Cleanup googleusercontent artifacts
+                                text = re.sub(
+                                    r"http://googleusercontent\.com/\w+/\d+\n*",
+                                    "",
+                                    text,
+                                ).rstrip()
+
+                                thoughts = (
+                                    get_nested_value(candidate_data, [37, 0, 0]) or ""
                                 )
-                            )
-
-                    output_candidates.append(
-                        Candidate(
-                            rcid=rcid,
-                            text=text,
-                            thoughts=thoughts,
-                            web_images=web_images,
-                            generated_images=generated_images,
-                        )
-                    )
 
-                if not output_candidates:
-                    raise GeminiError(
-                        "Failed to generate contents. No output data found in response."
-                    )
+                                # Web images
+                                web_images = []
+                                for web_img_data in get_nested_value(
+                                    candidate_data, [12, 1], []
+                                ):
+                                    url = get_nested_value(web_img_data, [0, 0, 0])
+                                    if url:
+                                        web_images.append(
+                                            WebImage(
+                                                url=url,
+                                                title=get_nested_value(
+                                                    web_img_data, [7, 0], ""
+                                                ),
+                                                alt=get_nested_value(
+                                                    web_img_data, [0, 4], ""
+                                                ),
+                                                proxy=self.proxy,
+                                            )
+                                        )
+
+                                # Generated images
+                                generated_images = []
+                                for gen_img_data in get_nested_value(
+                                    candidate_data, [12, 7, 0], []
+                                ):
+                                    url = get_nested_value(gen_img_data, [0, 3, 3])
+                                    if url:
+                                        img_num = get_nested_value(gen_img_data, [3, 6])
+                                        alt_list = get_nested_value(
+                                            gen_img_data, [3, 5], []
+                                        )
+                                        generated_images.append(
+                                            GeneratedImage(
+                                                url=url,
+                                                title=(
+                                                    f"[Generated Image {img_num}]"
+                                                    if img_num
+                                                    else "[Generated Image]"
+                                                ),
+                                                alt=get_nested_value(alt_list, [0], ""),
+                                                proxy=self.proxy,
+                                                cookies=self.cookies,
+                                            )
+                                        )
+
+                                # Calculate Deltas for this specific candidate
+                                last_text = last_texts.get(rcid, "")
+                                last_thought = last_thoughts.get(rcid, "")
+
+                                text_delta = text
+                                if text.startswith(last_text):
+                                    text_delta = text[len(last_text) :]
+
+                                thoughts_delta = thoughts
+                                if thoughts.startswith(last_thought):
+                                    thoughts_delta = thoughts[len(last_thought) :]
+
+                                if (
+                                    text_delta
+                                    or thoughts_delta
+                                    or web_images
+                                    or generated_images
+                                ):
+                                    any_changed = True
+
+                                last_texts[rcid] = text
+                                last_thoughts[rcid] = thoughts
+
+                                output_candidates.append(
+                                    Candidate(
+                                        rcid=rcid,
+                                        text=text,
+                                        text_delta=text_delta,
+                                        thoughts=thoughts or None,
+                                        thoughts_delta=thoughts_delta,
+                                        web_images=web_images,
+                                        generated_images=generated_images,
+                                    )
+                                )
 
-                output = ModelOutput(
-                    metadata=get_nested_value(body, [1], []),
-                    candidates=output_candidates,
-                )
-            except (TypeError, IndexError) as e:
-                logger.debug(
-                    f"{type(e).__name__}: {e}; Invalid response structure: {response.text}"
-                )
-                raise APIError(
-                    "Failed to parse response body. Data structure is invalid."
-                )
+                            if any_changed:
+                                has_candidates = True
+                                yield ModelOutput(
+                                    metadata=get_nested_value(part_json, [1], []),
+                                    candidates=output_candidates,
+                                )
+                        except json.JSONDecodeError:
+                            continue
 
-            if isinstance(chat, ChatSession):
-                chat.last_output = output
+                if is_busy and not has_candidates:
+                    raise APIError("Model is busy. Polling again...")
 
-            return output
+        except ReadTimeout:
+            raise TimeoutError(
+                "The request timed out while waiting for Gemini to respond. This often happens with very long prompts "
+                "or complex file analysis. Try increasing the 'timeout' value when initializing GeminiClient."
+            )
+        except (GeminiError, APIError):
+            raise
+        except Exception as e:
+            logger.debug(
+                f"{type(e).__name__}: {e}; Unexpected response or parsing error. Response: {locals().get('response', 'N/A')}"
+            )
+            raise APIError(f"Failed to parse response body: {e}")
 
     def start_chat(self, **kwargs) -> "ChatSession":
         """
@@ -563,14 +832,15 @@ class GeminiClient(GemMixin):
 
         return ChatSession(geminiclient=self, **kwargs)
 
+    @running(retry=2)
     async def _batch_execute(self, payloads: list[RPCData], **kwargs) -> Response:
         """
         Execute a batch of requests to Gemini API.
 
         Parameters
         ----------
-        payloads: `list[GRPC]`
-            List of `gemini_webapi.types.GRPC` objects to be executed.
+        payloads: `list[RPCData]`
+            List of `gemini_webapi.types.RPCData` objects to be executed.
         kwargs: `dict`, optional
             Additional arguments which will be passed to the post request.
             Refer to `httpx.AsyncClient.request` for more information.
@@ -581,31 +851,47 @@ class GeminiClient(GemMixin):
             Response object containing the result of the batch execution.
         """
 
+        _reqid = self._reqid
+        self._reqid += 100000
+
         try:
+            params: dict[str, Any] = {
+                "rpcids": ",".join([p.rpcid.value for p in payloads]),
+                "_reqid": _reqid,
+                "rt": "c",
+                "source-path": "/app",
+            }
+            if self.build_label:
+                params["bl"] = self.build_label
+            if self.session_id:
+                params["f.sid"] = self.session_id
+
             response = await self.client.post(
                 Endpoint.BATCH_EXEC,
+                params=params,
                 data={
                     "at": self.access_token,
                     "f.req": json.dumps(
                         [[payload.serialize() for payload in payloads]]
-                    ).decode(),
+                    ).decode("utf-8"),
                 },
                 **kwargs,
             )
         except ReadTimeout:
             raise TimeoutError(
-                "Batch execute request timed out, please try again. If the problem persists, "
-                "consider setting a higher `timeout` value when initializing GeminiClient."
+                "The request timed out while waiting for Gemini to respond. This often happens with very long prompts "
+                "or complex file analysis. Try increasing the 'timeout' value when initializing GeminiClient."
             )
 
-        # ? Seems like batch execution will immediately invalidate the current access token,
-        # ? causing the next request to fail with 401 Unauthorized.
         if response.status_code != 200:
             await self.close()
             raise APIError(
                 f"Batch execution failed with status code {response.status_code}"
             )
 
+        if self.client:
+            self.cookies.update(self.client.cookies)
+
         return response
 
 
@@ -652,7 +938,18 @@ class ChatSession:
         model: Model | str | dict = Model.UNSPECIFIED,
         gem: Gem | str | None = None,
     ):
-        self.__metadata: list[str | None] = [None, None, None]
+        self.__metadata: list[str | None] = [
+            "",
+            "",
+            "",
+            None,
+            None,
+            None,
+            None,
+            None,
+            None,
+            "",
+        ]
         self.geminiclient: GeminiClient = geminiclient
         self.last_output: ModelOutput | None = None
         self.model: Model | str | dict = model
@@ -727,6 +1024,43 @@ class ChatSession:
             **kwargs,
         )
 
+    async def send_message_stream(
+        self,
+        prompt: str,
+        files: list[str | Path] | None = None,
+        **kwargs,
+    ) -> AsyncGenerator[ModelOutput, None]:
+        """
+        Generates contents with prompt in streaming mode within this chat session.
+
+        This is a shortcut for `GeminiClient.generate_content_stream(prompt, files, self)`.
+        The session's metadata and conversation history are automatically managed.
+
+        Parameters
+        ----------
+        prompt: `str`
+            Prompt provided by user.
+        files: `list[str | Path]`, optional
+            List of file paths to be attached.
+        kwargs: `dict`, optional
+            Additional arguments passed to the streaming request.
+
+        Yields
+        ------
+        :class:`ModelOutput`
+            Partial output data containing text deltas.
+        """
+
+        async for output in self.geminiclient.generate_content_stream(
+            prompt=prompt,
+            files=files,
+            model=self.model,
+            gem=self.gem,
+            chat=self,
+            **kwargs,
+        ):
+            yield output
+
     def choose_candidate(self, index: int) -> ModelOutput:
         """
         Choose a candidate from the last `ModelOutput` to control the ongoing conversation flow.
@@ -765,9 +1099,13 @@ class ChatSession:
 
     @metadata.setter
     def metadata(self, value: list[str]):
-        if len(value) > 3:
-            raise ValueError("metadata cannot exceed 3 elements")
-        self.__metadata[: len(value)] = value
+        if not isinstance(value, list):
+            return
+
+        # Update only non-None elements to preserve existing CID/RID/RCID/Context
+        for i, val in enumerate(value):
+            if i < 10 and val is not None:
+                self.__metadata[i] = val
 
     @property
     def cid(self):
@@ -777,14 +1115,6 @@ class ChatSession:
     def cid(self, value: str):
         self.__metadata[0] = value
 
-    @property
-    def rid(self):
-        return self.__metadata[1]
-
-    @rid.setter
-    def rid(self, value: str):
-        self.__metadata[1] = value
-
     @property
     def rcid(self):
         return self.__metadata[2]
@@ -792,3 +1122,11 @@ class ChatSession:
     @rcid.setter
     def rcid(self, value: str):
         self.__metadata[2] = value
+
+    @property
+    def rid(self):
+        return self.__metadata[1]
+
+    @rid.setter
+    def rid(self, value: str):
+        self.__metadata[1] = value