langchain-google-genai 2.1.11__py3-none-any.whl → 3.0.0a1__py3-none-any.whl

langchain_google_genai/__init__.py

@@ -1,4 +1,4 @@
-"""**LangChain Google Generative AI Integration**
+"""**LangChain Google Generative AI Integration**.
 
 This module integrates Google's Generative AI models, specifically the Gemini series, with the LangChain framework. It provides classes for interacting with chat models and generating embeddings, leveraging Google's advanced AI capabilities.
 
@@ -76,12 +76,12 @@ __all__ = [
     "AqaOutput",
     "ChatGoogleGenerativeAI",
     "DoesNotExistsException",
+    "DoesNotExistsException",
     "GenAIAqa",
-    "GoogleGenerativeAIEmbeddings",
     "GoogleGenerativeAI",
+    "GoogleGenerativeAIEmbeddings",
     "GoogleVectorStore",
     "HarmBlockThreshold",
     "HarmCategory",
     "Modality",
-    "DoesNotExistsException",
 ]

langchain_google_genai/_common.py

@@ -13,19 +13,17 @@ _TELEMETRY_ENV_VARIABLE_NAME = "GOOGLE_CLOUD_AGENT_ENGINE_ID"
 
 
 class GoogleGenerativeAIError(Exception):
-    """
-    Custom exception class for errors associated with the `Google GenAI` API.
-    """
+    """Custom exception class for errors associated with the `Google GenAI` API."""
 
 
 class _BaseGoogleGenerativeAI(BaseModel):
-    """Base class for Google Generative AI LLMs"""
+    """Base class for Google Generative AI LLMs."""
 
     model: str = Field(
         ...,
         description="""The name of the model to use.
 Examples:
-    - gemini-2.5-pro
+    - gemini-2.5-flash
     - models/text-bison-001""",
     )
     """Model name to use."""
@@ -34,28 +32,38 @@ Examples:
     )
     """Google AI API key.
     If not specified will be read from env var ``GOOGLE_API_KEY``."""
+
     credentials: Any = None
     "The default custom credentials (google.auth.credentials.Credentials) to use "
     "when making API calls. If not provided, credentials will be ascertained from "
     "the GOOGLE_API_KEY envvar"
+
     temperature: float = 0.7
-    """Run inference with this temperature. Must be within ``[0.0, 2.0]``."""
+    """Run inference with this temperature. Must be within ``[0.0, 2.0]``. If unset,
+    will default to ``0.7``."""
+
     top_p: Optional[float] = None
     """Decode using nucleus sampling: consider the smallest set of tokens whose
-       probability sum is at least ``top_p``. Must be within ``[0.0, 1.0]``."""
+    probability sum is at least ``top_p``. Must be within ``[0.0, 1.0]``."""
+
     top_k: Optional[int] = None
     """Decode using top-k sampling: consider the set of ``top_k`` most probable tokens.
-       Must be positive."""
+    Must be positive."""
+
     max_output_tokens: Optional[int] = Field(default=None, alias="max_tokens")
     """Maximum number of tokens to include in a candidate. Must be greater than zero.
-       If unset, will default to ``64``."""
+    If unset, will use the model's default value, which varies by model.
+    See https://ai.google.dev/gemini-api/docs/models for model-specific limits."""
+
     n: int = 1
     """Number of chat completions to generate for each prompt. Note that the API may
-       not return the full ``n`` completions if duplicates are generated."""
-    max_retries: int = 6
-    """The maximum number of retries to make when generating."""
+    not return the full ``n`` completions if duplicates are generated."""
+
+    max_retries: int = Field(default=6, alias="retries")
+    """The maximum number of retries to make when generating. If unset, will default
+    to ``6``."""
 
-    timeout: Optional[float] = None
+    timeout: Optional[float] = Field(default=None, alias="request_timeout")
     """The maximum number of seconds to wait for a response."""
 
     client_options: Optional[Dict] = Field(
@@ -68,6 +76,7 @@ Examples:
     transport: Optional[str] = Field(
         default=None,
         description="A string, one of: [`rest`, `grpc`, `grpc_asyncio`].",
+        alias="api_transport",
     )
     additional_headers: Optional[Dict[str, str]] = Field(
         default=None,
@@ -89,9 +98,9 @@ Examples:
     )
 
     safety_settings: Optional[Dict[HarmCategory, HarmBlockThreshold]] = None
-    """The default safety settings to use for all generations. 
-    
-        For example: 
+    """The default safety settings to use for all generations.
+
+        For example:
 
         .. code-block:: python
             from google.generativeai.types.safety_types import HarmBlockThreshold, HarmCategory
@@ -127,6 +136,7 @@ def get_user_agent(module: Optional[str] = None) -> Tuple[str, str]:
     Args:
         module (Optional[str]):
             Optional. The module for a custom user agent header.
+
     Returns:
         Tuple[str, str]
     """
@@ -148,11 +158,13 @@ def get_client_info(module: Optional[str] = None) -> "ClientInfo":
     Args:
         module (Optional[str]):
             Optional. The module for a custom user agent header.
+
     Returns:
         ``google.api_core.gapic_v1.client_info.ClientInfo``
     """
     client_library_version, user_agent = get_user_agent(module)
-    return ClientInfo(
+    # TODO: remove ignore once google-auth has types.
+    return ClientInfo(  # type: ignore[no-untyped-call]
         client_library_version=client_library_version,
         user_agent=user_agent,
     )

langchain_google_genai/_compat.py

@@ -0,0 +1,248 @@
+"""Go from v1 content blocks to generativelanguage_v1beta format."""
+
+import json
+from typing import Any, Optional
+
+from langchain_core.messages import content as types
+
+
+def translate_citations_to_grounding_metadata(
+    citations: list[types.Citation], web_search_queries: Optional[list[str]] = None
+) -> dict[str, Any]:
+    """Translate LangChain Citations to Google AI grounding metadata format.
+
+    Args:
+        citations: List of Citation content blocks.
+        web_search_queries: Optional list of search queries that generated
+            the grounding data.
+
+    Returns:
+        Google AI grounding metadata dictionary.
+
+    Example:
+        >>> citations = [
+        ...     create_citation(
+        ...         url="https://uefa.com/euro2024",
+        ...         title="UEFA Euro 2024 Results",
+        ...         start_index=0,
+        ...         end_index=47,
+        ...         cited_text="Spain won the UEFA Euro 2024 championship",
+        ...     )
+        ... ]
+        >>> metadata = translate_citations_to_grounding_metadata(citations)
+        >>> len(metadata["groundingChunks"])
+        1
+        >>> metadata["groundingChunks"][0]["web"]["uri"]
+        'https://uefa.com/euro2024'
+    """
+    if not citations:
+        return {}
+
+    # Group citations by text segment (start_index, end_index, cited_text)
+    segment_to_citations: dict[
+        tuple[Optional[int], Optional[int], Optional[str]], list[types.Citation]
+    ] = {}
+
+    for citation in citations:
+        key = (
+            citation.get("start_index"),
+            citation.get("end_index"),
+            citation.get("cited_text"),
+        )
+        if key not in segment_to_citations:
+            segment_to_citations[key] = []
+        segment_to_citations[key].append(citation)
+
+    # Build grounding chunks from unique URLs
+    url_to_chunk_index: dict[str, int] = {}
+    grounding_chunks: list[dict[str, Any]] = []
+
+    for citation in citations:
+        url = citation.get("url")
+        if url and url not in url_to_chunk_index:
+            url_to_chunk_index[url] = len(grounding_chunks)
+            grounding_chunks.append(
+                {"web": {"uri": url, "title": citation.get("title", "")}}
+            )
+
+    # Build grounding supports
+    grounding_supports: list[dict[str, Any]] = []
+
+    for (
+        start_index,
+        end_index,
+        cited_text,
+    ), citations_group in segment_to_citations.items():
+        if start_index is not None and end_index is not None and cited_text:
+            chunk_indices = []
+            confidence_scores = []
+
+            for citation in citations_group:
+                url = citation.get("url")
+                if url and url in url_to_chunk_index:
+                    chunk_indices.append(url_to_chunk_index[url])
+
+                    # Extract confidence scores from extras if available
+                    extras = citation.get("extras", {})
+                    google_metadata = extras.get("google_ai_metadata", {})
+                    scores = google_metadata.get("confidence_scores", [])
+                    confidence_scores.extend(scores)
+
+            support = {
+                "segment": {
+                    "startIndex": start_index,
+                    "endIndex": end_index,
+                    "text": cited_text,
+                },
+                "groundingChunkIndices": chunk_indices,
+            }
+
+            if confidence_scores:
+                support["confidenceScores"] = confidence_scores
+
+            grounding_supports.append(support)
+
+    # Extract search queries from extras if not provided
+    if web_search_queries is None:
+        web_search_queries = []
+        for citation in citations:
+            extras = citation.get("extras", {})
+            google_metadata = extras.get("google_ai_metadata", {})
+            queries = google_metadata.get("web_search_queries", [])
+            web_search_queries.extend(queries)
+        # Remove duplicates while preserving order
+        web_search_queries = list(dict.fromkeys(web_search_queries))
+
+    return {
+        "webSearchQueries": web_search_queries,
+        "groundingChunks": grounding_chunks,
+        "groundingSupports": grounding_supports,
+    }
+
+
+def _convert_from_v1_to_generativelanguage_v1beta(
+    content: list[types.ContentBlock], model_provider: str | None
+) -> list[dict[str, Any]]:
+    """Convert v1 content blocks to `google.ai.generativelanguage_v1beta.types.Content`.
+
+    Args:
+        content: List of v1 `ContentBlock` objects.
+        model_provider: The model provider name that generated the v1 content.
+
+    Returns:
+        List of dictionaries in `google.ai.generativelanguage_v1beta.types.Content`
+        format, ready to be sent to the API.
+    """
+    new_content: list = []
+    for block in content:
+        if not isinstance(block, dict) or "type" not in block:
+            continue
+
+        block_dict = dict(block)  # (For typing)
+
+        # TextContentBlock
+        if block_dict["type"] == "text":
+            new_block = {"text": block_dict.get("text", "")}
+            new_content.append(new_block)
+            # Citations are only handled on output. Can't pass them back :/
+
+        # ReasoningContentBlock -> thinking
+        elif block_dict["type"] == "reasoning" and model_provider == "google_genai":
+            # Google requires passing back the thought_signature when available.
+            # Signatures are only provided when function calling is enabled.
+            # If no signature is available, we skip the reasoning block as it cannot
+            # be properly serialized back to the API.
+            if "extras" in block_dict and isinstance(block_dict["extras"], dict):
+                extras = block_dict["extras"]
+                if "signature" in extras:
+                    new_block = {
+                        "thought": True,
+                        "text": block_dict.get("reasoning", ""),
+                        "thought_signature": extras["signature"],
+                    }
+                    new_content.append(new_block)
+                # else: skip reasoning blocks without signatures
+                # TODO: log a warning?
+            # else: skip reasoning blocks without extras
+            # TODO: log a warning?
+
+        # ImageContentBlock
+        elif block_dict["type"] == "image":
+            if base64 := block_dict.get("base64"):
+                new_block = {
+                    "inline_data": {
+                        "mime_type": block_dict.get("mime_type", "image/jpeg"),
+                        "data": base64.encode("utf-8")
+                        if isinstance(base64, str)
+                        else base64,
+                    }
+                }
+                new_content.append(new_block)
+            elif url := block_dict.get("url") and model_provider == "google_genai":
+                # Google file service
+                new_block = {
+                    "file_data": {
+                        "mime_type": block_dict.get("mime_type", "image/jpeg"),
+                        "file_uri": block_dict[str(url)],
+                    }
+                }
+                new_content.append(new_block)
+
+        # TODO: AudioContentBlock -> audio once models support passing back in
+
+        # FileContentBlock (documents)
+        elif block_dict["type"] == "file":
+            if base64 := block_dict.get("base64"):
+                new_block = {
+                    "inline_data": {
+                        "mime_type": block_dict.get(
+                            "mime_type", "application/octet-stream"
+                        ),
+                        "data": base64.encode("utf-8")
+                        if isinstance(base64, str)
+                        else base64,
+                    }
+                }
+                new_content.append(new_block)
+            elif url := block_dict.get("url") and model_provider == "google_genai":
+                # Google file service
+                new_block = {
+                    "file_data": {
+                        "mime_type": block_dict.get(
+                            "mime_type", "application/octet-stream"
+                        ),
+                        "file_uri": block_dict[str(url)],
+                    }
+                }
+                new_content.append(new_block)
+
+        # ToolCall -> FunctionCall
+        elif block_dict["type"] == "tool_call":
+            function_call = {
+                "function_call": {
+                    "name": block_dict.get("name", ""),
+                    "args": block_dict.get("args", {}),
+                }
+            }
+            new_content.append(function_call)
+
+        # ToolCallChunk -> FunctionCall
+        elif block_dict["type"] == "tool_call_chunk":
+            try:
+                args_str = block_dict.get("args") or "{}"
+                input_ = json.loads(args_str) if isinstance(args_str, str) else args_str
+            except json.JSONDecodeError:
+                input_ = {}
+
+            function_call = {
+                "function_call": {
+                    "name": block_dict.get("name", "no_tool_name_present"),
+                    "args": input_,
+                }
+            }
+            new_content.append(function_call)
+
+        # NonStandardContentBlock
+        # TODO: Handle new server tools
+
+    return new_content