feat(community): add Google Sheets read-only tools and toolkit (#1208)

# Add Google Sheets read-only tools and toolkit

Add Google Sheets read-only integration to the community package,
providing tools for reading spreadsheet data with dual authentication
support and error handling.

## Type
🆕 New Feature
✅ Test

## Changes
Add Google Sheets read-only tools for LangChain integration

- **SheetsBaseTool** — abstract base with dual auth (API key / OAuth2)
- **SheetsReadDataTool** — read a single range with flexible formatting
- **SheetsBatchReadDataTool** — read multiple ranges in one call
- **SheetsFilteredReadDataTool** — filter data with multiple condition
types
- **SheetsGetSpreadsheetInfoTool** — access spreadsheet
metadata/properties
- **SheetsToolkit** — curated tool bundle

Error handling
- Type hints
- Support for both API key and OAuth2 authentication
- Data formatting options
- Error messages and validation

Add supporting infrastructure
- **enums.py** — constants for Sheets API options
- **utils.py** — service builder and auth helpers
- **urls.py** — endpoint definitions
- **base.py** — authentication and service management

Add integration tests
- Unit tests for all tools
- Integration tests with actual API calls
- Error handling scenarios
- Authentication flow tests

## Testing
✅ All checks passed:



Test scenarios covered:
- Single range data reading
- Batch range operations
- Filtered data queries
- Spreadsheet metadata access
- API key authentication
- OAuth2 authentication
- Error handling with invalid inputs

## Note
Requires GOOGLE_SHEETS_API_KEY environment variable for API key
authentication
All tests pass locally
Follows community package standards
Error handling for API responses
Type hints included
Supports both API key and OAuth2 authentication
Compatible with LangChain agents and toolkits
Read-only scope - write operations will come in a follow-up PR

## Checklist
- [x] PR Title follows convention: "feat(community): add Google Sheets
read-only tools and toolkit"
- [x] Added tests
- [x] All linting and formatting checks pass
- [x] Type checking passes
- [x] Optional dependencies properly handled
- [x] Changes are backwards compatible

Author: von-development

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,
+]