Merge remote-tracking branch 'upstream/main' into pr-1210

Author: parkerhancock

libs/community/langchain_google_community/__init__.py

@@ -41,6 +41,13 @@
     GoogleSearchResults,
     GoogleSearchRun,
 )
+from langchain_google_community.sheets import (
+    SheetsBatchReadDataTool,
+    SheetsFilteredReadDataTool,
+    SheetsGetSpreadsheetInfoTool,
+    SheetsReadDataTool,
+    SheetsToolkit,
+)
 from langchain_google_community.texttospeech import TextToSpeechTool
 from langchain_google_community.translate import GoogleTranslateTransformer
 from langchain_google_community.vertex_ai_search import (
@@ -76,6 +83,11 @@
     "GMailLoader",
     "GmailToolkit",
     "GoogleDriveLoader",
+    "SheetsReadDataTool",
+    "SheetsBatchReadDataTool",
+    "SheetsFilteredReadDataTool",
+    "SheetsGetSpreadsheetInfoTool",
+    "SheetsToolkit",
     "GoogleGeocodingAPIWrapper",
     "GoogleGeocodingTool",
     "GooglePlacesAPIWrapper",

libs/community/langchain_google_community/sheets/__init__.py

@@ -0,0 +1,24 @@
+"""Google Sheets tools for LangChain."""
+
+from langchain_google_community.sheets.base import SheetsBaseTool
+from langchain_google_community.sheets.get_spreadsheet_info import (
+    SheetsGetSpreadsheetInfoTool,
+)
+from langchain_google_community.sheets.read_sheet_tools import (
+    SheetsBatchReadDataTool,
+    SheetsFilteredReadDataTool,
+    SheetsReadDataTool,
+)
+from langchain_google_community.sheets.toolkit import SheetsToolkit
+
+__all__ = [
+    # Base classes
+    "SheetsBaseTool",
+    # Individual tools
+    "SheetsReadDataTool",
+    "SheetsBatchReadDataTool",
+    "SheetsFilteredReadDataTool",
+    "SheetsGetSpreadsheetInfoTool",
+    # Toolkit
+    "SheetsToolkit",
+]

libs/community/langchain_google_community/sheets/base.py

@@ -0,0 +1,121 @@
+"""Base class for Google Sheets tools."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional
+
+from langchain_core.tools import BaseTool
+from pydantic import Field
+
+if TYPE_CHECKING:
+    # This is for linting and IDE typehints
+    from googleapiclient.discovery import Resource  # type: ignore[import]
+else:
+    try:
+        # We do this so pydantic can resolve the types when instantiating
+        from googleapiclient.discovery import Resource
+    except ImportError:
+        pass
+
+
+class SheetsBaseTool(BaseTool):  # type: ignore[override]
+    """Base class for Google Sheets tools.
+
+    Authentication:
+    - api_resource: OAuth2 credentials for full access (read/write private sheets)
+    - api_key: API key for read-only access (public sheets only)
+
+    Note: Write operations require OAuth2 credentials.
+    """
+
+    api_resource: Optional[Resource] = Field(
+        default=None,
+        description="Google Sheets API resource, OAuth2 credentials for full access",
+    )
+    api_key: Optional[str] = Field(
+        default=None,
+        description="Google API key for read-only access to public spreadsheets",
+    )
+
+    def _get_service(self) -> Resource:
+        """Get the appropriate Google Sheets service based on available credentials.
+
+        Returns:
+            Resource: Google Sheets API service
+
+        Raises:
+            ValueError: If neither api_resource nor api_key is provided
+        """
+        if self.api_resource:
+            return self.api_resource  # OAuth2 - full access
+        elif self.api_key:
+            from langchain_google_community.sheets.utils import (
+                build_sheets_service_with_api_key,
+            )
+
+            return build_sheets_service_with_api_key(
+                self.api_key
+            )  # API key - read-only
+        else:
+            # Try to create OAuth2 service as fallback
+            from langchain_google_community.sheets.utils import build_sheets_service
+
+            return build_sheets_service()
+
+    def _check_write_permissions(self) -> None:
+        """Check if the current authentication method supports write operations.
+
+        Raises:
+            ValueError: If using API key for write operations
+        """
+        if self.api_key and not self.api_resource:
+            raise ValueError(
+                "Write operations require OAuth2 credentials, not API key. "
+                "Please provide api_resource for write access to private spreadsheets."
+            )
+
+    @classmethod
+    def from_api_resource(cls, api_resource: Resource) -> "SheetsBaseTool":
+        """Create a tool from an API resource.
+
+        Args:
+            api_resource: The API resource to use.
+
+        Returns:
+            A tool with OAuth2 credentials for full access.
+        """
+        return cls(api_resource=api_resource)  # type: ignore[call-arg]
+
+    @classmethod
+    def from_api_key(cls, api_key: str) -> "SheetsBaseTool":
+        """Create a tool from an API key.
+
+        Args:
+            api_key: The API key to use.
+
+        Returns:
+            A tool with API key for read-only access.
+        """
+        return cls(api_key=api_key)  # type: ignore[call-arg]
+
+    def _safe_get_cell_value(self, cell_data: dict) -> str:
+        """Safely extract cell value with proper fallback hierarchy.
+
+        Args:
+            cell_data: Cell data dictionary from Google Sheets API
+
+        Returns:
+            str: The cell value as a string
+        """
+        if cell_data.get("formattedValue"):
+            return cell_data["formattedValue"]
+        elif cell_data.get("effectiveValue", {}).get("stringValue"):
+            return str(cell_data["effectiveValue"]["stringValue"])
+        elif cell_data.get("effectiveValue", {}).get("numberValue") is not None:
+            return str(cell_data["effectiveValue"]["numberValue"])
+        elif cell_data.get("userEnteredValue", {}).get("stringValue"):
+            return str(cell_data["userEnteredValue"]["stringValue"])
+        elif cell_data.get("userEnteredValue", {}).get("numberValue") is not None:
+            return str(cell_data["userEnteredValue"]["numberValue"])
+        else:
+            return ""

libs/community/langchain_google_community/sheets/enums.py

@@ -0,0 +1,167 @@
+"""Google Sheets API enums and constants.
+
+This module contains all the enums and constants used across the Google Sheets
+module for type safety, validation, and better developer experience.
+"""
+
+from enum import Enum
+
+
+class ValueRenderOption(str, Enum):
+    """Google Sheets value render options.
+
+    Determines how values should be rendered in the response.
+    """
+
+    FORMATTED_VALUE = "FORMATTED_VALUE"
+    """Values will be calculated and formatted in the reply according to the 
+    cell's formatting. Formatting is based on the spreadsheet's locale, not 
+    the requesting user's locale."""
+
+    UNFORMATTED_VALUE = "UNFORMATTED_VALUE"
+    """Values will be calculated, but not formatted in the reply. For example, 
+    if A1 is 1.23 and A2 is =A1 and formatted as currency, then A2 would 
+    return the number 1.23, not "$1.23"."""
+
+    FORMULA = "FORMULA"
+    """Values will not be calculated. The reply will include the formulas. 
+    For example, if A1 is 1.23 and A2 is =A1 and formatted as currency, 
+    then A2 would return "=A1"."""
+
+
+class DateTimeRenderOption(str, Enum):
+    """Google Sheets date/time render options.
+
+    Determines how dates, times, and durations should be rendered in the response.
+    """
+
+    SERIAL_NUMBER = "SERIAL_NUMBER"
+    """Instructs date, time, datetime, and duration fields to be output as 
+    doubles in "serial number" format, as popularized by Lotus 1-2-3. The 
+    whole number portion of the value (counting the epoch of 1900-01-01 as 1) 
+    is the number of days since 1900-01-01. The fractional portion of the 
+    value counts the time as a fraction of the day."""
+
+    FORMATTED_STRING = "FORMATTED_STRING"
+    """Instructs date, time, datetime, and duration fields to be output as 
+    strings in their given number format (which depends on the spreadsheet 
+    locale)."""
+
+
+class MajorDimension(str, Enum):
+    """Google Sheets major dimension options.
+
+    Determines how the values should be oriented in the response.
+    """
+
+    ROWS = "ROWS"
+    """The values are returned as a 2D array with rows as the major dimension.
+    Each row contains all the values for that row."""
+
+    COLUMNS = "COLUMNS"
+    """The values are returned as a 2D array with columns as the major dimension.
+    Each column contains all the values for that column."""
+
+
+# Common constants for validation and default values
+DEFAULT_VALUE_RENDER_OPTION = ValueRenderOption.FORMATTED_VALUE
+DEFAULT_DATE_TIME_RENDER_OPTION = DateTimeRenderOption.SERIAL_NUMBER
+DEFAULT_MAJOR_DIMENSION = MajorDimension.ROWS
+
+# Valid options for validation
+VALID_VALUE_RENDER_OPTIONS = [option.value for option in ValueRenderOption]
+VALID_DATE_TIME_RENDER_OPTIONS = [option.value for option in DateTimeRenderOption]
+VALID_MAJOR_DIMENSIONS = [option.value for option in MajorDimension]
+
+
+class FilterConditionType(str, Enum):
+    """Filter condition types for Google Sheets data filters."""
+
+    # Number conditions
+    NUMBER_GREATER = "NUMBER_GREATER"
+    """Number is greater than the specified value."""
+    NUMBER_GREATER_THAN_OR_EQUAL = "NUMBER_GREATER_THAN_OR_EQUAL"
+    """Number is greater than or equal to the specified value."""
+    NUMBER_LESS = "NUMBER_LESS"
+    """Number is less than the specified value."""
+    NUMBER_LESS_THAN_OR_EQUAL = "NUMBER_LESS_THAN_OR_EQUAL"
+    """Number is less than or equal to the specified value."""
+    NUMBER_EQUAL = "NUMBER_EQUAL"
+    """Number is equal to the specified value."""
+    NUMBER_NOT_EQUAL = "NUMBER_NOT_EQUAL"
+    """Number is not equal to the specified value."""
+    NUMBER_BETWEEN = "NUMBER_BETWEEN"
+    """Number is between two specified values."""
+
+    # Text conditions
+    TEXT_CONTAINS = "TEXT_CONTAINS"
+    """Text contains the specified value."""
+    TEXT_DOES_NOT_CONTAIN = "TEXT_DOES_NOT_CONTAIN"
+    """Text does not contain the specified value."""
+    TEXT_STARTS_WITH = "TEXT_STARTS_WITH"
+    """Text starts with the specified value."""
+    TEXT_ENDS_WITH = "TEXT_ENDS_WITH"
+    """Text ends with the specified value."""
+    TEXT_EQUAL = "TEXT_EQUAL"
+    """Text is equal to the specified value."""
+    TEXT_NOT_EQUAL = "TEXT_NOT_EQUAL"
+    """Text is not equal to the specified value."""
+
+    # Date conditions
+    DATE_IS_AFTER = "DATE_IS_AFTER"
+    """Date is after the specified value."""
+    DATE_IS_BEFORE = "DATE_IS_BEFORE"
+    """Date is before the specified value."""
+    DATE_IS_ON_OR_AFTER = "DATE_IS_ON_OR_AFTER"
+    """Date is on or after the specified value."""
+    DATE_IS_ON_OR_BEFORE = "DATE_IS_ON_OR_BEFORE"
+    """Date is on or before the specified value."""
+    DATE_IS_BETWEEN = "DATE_IS_BETWEEN"
+    """Date is between two specified values."""
+    DATE_IS_EQUAL = "DATE_IS_EQUAL"
+    """Date is equal to the specified value."""
+
+    # Boolean conditions
+    BOOLEAN_IS_TRUE = "BOOLEAN_IS_TRUE"
+    """Boolean is true."""
+    BOOLEAN_IS_FALSE = "BOOLEAN_IS_FALSE"
+    """Boolean is false."""
+
+
+# Default values and validation lists for filter conditions
+DEFAULT_FILTER_CONDITION_TYPE = FilterConditionType.TEXT_CONTAINS
+VALID_FILTER_CONDITION_TYPES = [option.value for option in FilterConditionType]
+
+# Grouped filter condition types for easier validation
+NUMBER_CONDITIONS = [
+    FilterConditionType.NUMBER_GREATER.value,
+    FilterConditionType.NUMBER_GREATER_THAN_OR_EQUAL.value,
+    FilterConditionType.NUMBER_LESS.value,
+    FilterConditionType.NUMBER_LESS_THAN_OR_EQUAL.value,
+    FilterConditionType.NUMBER_EQUAL.value,
+    FilterConditionType.NUMBER_NOT_EQUAL.value,
+    FilterConditionType.NUMBER_BETWEEN.value,
+]
+
+TEXT_CONDITIONS = [
+    FilterConditionType.TEXT_CONTAINS.value,
+    FilterConditionType.TEXT_DOES_NOT_CONTAIN.value,
+    FilterConditionType.TEXT_STARTS_WITH.value,
+    FilterConditionType.TEXT_ENDS_WITH.value,
+    FilterConditionType.TEXT_EQUAL.value,
+    FilterConditionType.TEXT_NOT_EQUAL.value,
+]
+
+DATE_CONDITIONS = [
+    FilterConditionType.DATE_IS_AFTER.value,
+    FilterConditionType.DATE_IS_BEFORE.value,
+    FilterConditionType.DATE_IS_ON_OR_AFTER.value,
+    FilterConditionType.DATE_IS_ON_OR_BEFORE.value,
+    FilterConditionType.DATE_IS_BETWEEN.value,
+    FilterConditionType.DATE_IS_EQUAL.value,
+]
+
+BOOLEAN_CONDITIONS = [
+    FilterConditionType.BOOLEAN_IS_TRUE.value,
+    FilterConditionType.BOOLEAN_IS_FALSE.value,
+]