arcade-google-sheets 2.0.0rc1__py3-none-any.whl

arcade_google_sheets/__init__.py

@@ -0,0 +1,7 @@
+from arcade_google_sheets.tools import (
+    create_spreadsheet,
+    get_spreadsheet,
+    write_to_cell,
+)
+
+__all__ = ["create_spreadsheet", "get_spreadsheet", "write_to_cell"]

arcade_google_sheets/constants.py

@@ -0,0 +1,2 @@
+DEFAULT_SHEET_ROW_COUNT = 1000
+DEFAULT_SHEET_COLUMN_COUNT = 26

arcade_google_sheets/decorators.py

@@ -0,0 +1,24 @@
+import functools
+from collections.abc import Callable
+from typing import Any
+
+from arcade_tdk import ToolContext
+from googleapiclient.errors import HttpError
+
+from arcade_google_sheets.file_picker import generate_google_file_picker_url
+
+
+def with_filepicker_fallback(func: Callable[..., Any]) -> Callable[..., Any]:
+    """ """
+
+    @functools.wraps(func)
+    async def async_wrapper(context: ToolContext, *args: Any, **kwargs: Any) -> Any:
+        try:
+            return await func(context, *args, **kwargs)
+        except HttpError as e:
+            if e.status_code in [403, 404]:
+                file_picker_response = generate_google_file_picker_url(context)
+                return file_picker_response
+            raise
+
+    return async_wrapper

arcade_google_sheets/enums.py

@@ -0,0 +1,25 @@
+from enum import Enum
+
+
+class CellErrorType(str, Enum):
+    """The type of error in a cell
+
+    Implementation of https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/other#ErrorType
+    """
+
+    ERROR_TYPE_UNSPECIFIED = "ERROR_TYPE_UNSPECIFIED"  # The default error type, do not use this.
+    ERROR = "ERROR"  # Corresponds to the #ERROR! error.
+    NULL_VALUE = "NULL_VALUE"  # Corresponds to the #NULL! error.
+    DIVIDE_BY_ZERO = "DIVIDE_BY_ZERO"  # Corresponds to the #DIV/0 error.
+    VALUE = "VALUE"  # Corresponds to the #VALUE! error.
+    REF = "REF"  # Corresponds to the #REF! error.
+    NAME = "NAME"  # Corresponds to the #NAME? error.
+    NUM = "NUM"  # Corresponds to the #NUM! error.
+    N_A = "N_A"  # Corresponds to the #N/A error.
+    LOADING = "LOADING"  # Corresponds to the Loading... state.
+
+
+class NumberFormatType(str, Enum):
+    NUMBER = "NUMBER"
+    PERCENT = "PERCENT"
+    CURRENCY = "CURRENCY"

arcade_google_sheets/file_picker.py

@@ -0,0 +1,49 @@
+import base64
+import json
+
+from arcade_tdk import ToolContext, ToolMetadataKey
+from arcade_tdk.errors import ToolExecutionError
+
+
+def generate_google_file_picker_url(context: ToolContext) -> dict:
+    """Generate a Google File Picker URL for user-driven file selection and authorization.
+
+    Generates a URL that directs the end-user to a Google File Picker interface where
+    where they can select or upload Google Drive files. Users can grant permission to access their
+    Drive files, providing a secure and authorized way to interact with their files.
+
+    This is particularly useful when prior tools (e.g., those accessing or modifying
+    Google Docs, Google Sheets, etc.) encountered failures due to file non-existence
+    (Requested entity was not found) or permission errors. Once the user completes the file
+    picker flow, the prior tool can be retried.
+
+    Returns:
+        A dictionary containing the URL and instructions for the llm to instruct the user.
+    """
+    client_id = context.get_metadata(ToolMetadataKey.CLIENT_ID)
+    client_id_parts = client_id.split("-")
+    if not client_id_parts:
+        raise ToolExecutionError(
+            message="Invalid Google Client ID",
+            developer_message=f"Google Client ID '{client_id}' is not valid",
+        )
+    app_id = client_id_parts[0]
+    cloud_coordinator_url = context.get_metadata(ToolMetadataKey.COORDINATOR_URL).strip("/")
+
+    config = {
+        "auth": {
+            "client_id": client_id,
+            "app_id": app_id,
+        },
+    }
+    config_json = json.dumps(config)
+    config_base64 = base64.urlsafe_b64encode(config_json.encode("utf-8")).decode("utf-8")
+    url = f"{cloud_coordinator_url}/google/drive_picker?config={config_base64}"
+
+    return {
+        "url": url,
+        "llm_instructions": (
+            "Instruct the user to click the following link to open the Google Drive File Picker. "
+            f"This will allow them to select files and grant access permissions: {url}"
+        ),
+    }

arcade_google_sheets/models.py

@@ -0,0 +1,241 @@
+import json
+from typing import Optional
+
+from pydantic import BaseModel, field_validator, model_validator
+
+from arcade_google_sheets.enums import CellErrorType, NumberFormatType
+from arcade_google_sheets.types import CellValue
+
+
+class CellErrorValue(BaseModel):
+    """An error in a cell
+
+    Implementation of https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/other#ErrorValue
+    """
+
+    type: CellErrorType
+    message: str
+
+
+class CellExtendedValue(BaseModel):
+    """The kinds of value that a cell in a spreadsheet can have
+
+    Implementation of https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/other#ExtendedValue
+    """
+
+    numberValue: float | None = None
+    stringValue: str | None = None
+    boolValue: bool | None = None
+    formulaValue: str | None = None
+    errorValue: Optional["CellErrorValue"] = None
+
+    @model_validator(mode="after")
+    def check_exactly_one_value(cls, instance):  # type: ignore[no-untyped-def]
+        provided = [v for v in instance.__dict__.values() if v is not None]
+        if len(provided) != 1:
+            raise ValueError(
+                "Exactly one of numberValue, stringValue, boolValue, "
+                "formulaValue, or errorValue must be set."
+            )
+        return instance
+
+
+class NumberFormat(BaseModel):
+    """The format of a number
+
+    Implementation of https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/cells#NumberFormat
+    """
+
+    pattern: str
+    type: NumberFormatType
+
+
+class CellFormat(BaseModel):
+    """The format of a cell
+
+    Partial implementation of https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/cells#CellFormat
+    """
+
+    numberFormat: NumberFormat
+
+
+class CellData(BaseModel):
+    """Data about a specific cell
+
+    A partial implementation of https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/cells#CellData
+    """
+
+    userEnteredValue: CellExtendedValue
+    userEnteredFormat: CellFormat | None = None
+
+
+class RowData(BaseModel):
+    """Data about each cellin a row
+
+    A partial implementation of https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/sheets#RowData
+    """
+
+    values: list[CellData]
+
+
+class GridData(BaseModel):
+    """Data in the grid
+
+    A partial implementation of https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/sheets#GridData
+    """
+
+    startRow: int
+    startColumn: int
+    rowData: list[RowData]
+
+
+class GridProperties(BaseModel):
+    """Properties of a grid
+
+    A partial implementation of https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/sheets#GridProperties
+    """
+
+    rowCount: int
+    columnCount: int
+
+
+class SheetProperties(BaseModel):
+    """Properties of a Sheet
+
+    A partial implementation of https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/sheets#SheetProperties
+    """
+
+    sheetId: int
+    title: str
+    gridProperties: GridProperties | None = None
+
+
+class Sheet(BaseModel):
+    """A Sheet in a spreadsheet
+
+    A partial implementation of https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/sheets#Sheet
+    """
+
+    properties: SheetProperties
+    data: list[GridData] | None = None
+
+
+class SpreadsheetProperties(BaseModel):
+    """Properties of a spreadsheet
+
+    A partial implementation of https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets#SpreadsheetProperties
+    """
+
+    title: str
+
+
+class Spreadsheet(BaseModel):
+    """A spreadsheet
+
+    A partial implementation of https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets
+    """
+
+    properties: SpreadsheetProperties
+    sheets: list[Sheet]
+
+
+class SheetDataInput(BaseModel):
+    """
+    SheetDataInput models the cell data of a spreadsheet in a custom format.
+
+    It is a dictionary mapping row numbers (as ints) to dictionaries that map
+    column letters (as uppercase strings) to cell values (int, float, str, or bool).
+
+    This model enforces that:
+      - The outer keys are convertible to int.
+      - The inner keys are alphabetic strings (normalized to uppercase).
+      - All cell values are only of type int, float, str, or bool.
+
+    The model automatically serializes (via `json_data()`)
+    and validates the inner types.
+    """
+
+    data: dict[int, dict[str, CellValue]]
+
+    @classmethod
+    def _parse_json_if_string(cls, value):  # type: ignore[no-untyped-def]
+        """Parses the value if it is a JSON string, otherwise returns it.
+
+        Helper method for when validating the `data` field.
+        """
+        if isinstance(value, str):
+            try:
+                return json.loads(value)
+            except json.JSONDecodeError as e:
+                raise TypeError(f"Invalid JSON: {e}")
+        return value
+
+    @classmethod
+    def _validate_row_key(cls, row_key) -> int:  # type: ignore[no-untyped-def]
+        """Converts the row key to an integer, raising an error if conversion fails.
+
+        Helper method for when validating the `data` field.
+        """
+        try:
+            return int(row_key)
+        except (ValueError, TypeError):
+            raise TypeError(f"Row key '{row_key}' is not convertible to int.")
+
+    @classmethod
+    def _validate_inner_cells(cls, cells, row_int: int) -> dict:  # type: ignore[no-untyped-def]
+        """Validates that 'cells' is a dict mapping column letters to valid cell values
+        and normalizes the keys.
+
+        Helper method for when validating the `data` field.
+        """
+        if not isinstance(cells, dict):
+            raise TypeError(
+                f"Value for row '{row_int}' must be a dict mapping column letters to cell values."
+            )
+        new_inner = {}
+        for col_key, cell_value in cells.items():
+            if not isinstance(col_key, str):
+                raise TypeError(f"Column key '{col_key}' must be a string.")
+            col_string = col_key.upper()
+            if not col_string.isalpha():
+                raise TypeError(f"Column key '{col_key}' is invalid. Must be alphabetic.")
+            if not isinstance(cell_value, int | float | str | bool):
+                raise TypeError(
+                    f"Cell value for {col_string}{row_int} must be an int, float, str, or bool."
+                )
+            new_inner[col_string] = cell_value
+        return new_inner
+
+    @field_validator("data", mode="before")
+    @classmethod
+    def validate_and_convert_keys(cls, value):  # type: ignore[no-untyped-def]
+        """
+        Validates data when SheetDataInput is instantiated and converts it to the correct format.
+        Uses private helper methods to parse JSON, validate row keys, and validate inner cell data.
+        """
+        if value is None:
+            return {}
+
+        value = cls._parse_json_if_string(value)
+        if isinstance(value, dict):
+            new_value = {}
+            for row_key, cells in value.items():
+                row_int = cls._validate_row_key(row_key)
+                inner_cells = cls._validate_inner_cells(cells, row_int)
+                new_value[row_int] = inner_cells
+            return new_value
+
+        raise TypeError("data must be a dict or a valid JSON string representing a dict")
+
+    def json_data(self) -> str:
+        """
+        Serialize the sheet data to a JSON string.
+        """
+        return json.dumps(self.data)
+
+    @classmethod
+    def from_json(cls, json_str: str) -> "SheetDataInput":
+        """
+        Create a SheetData instance from a JSON string.
+        """
+        return cls.model_validate_json(json_str)

arcade_google_sheets/tools/__init__.py

@@ -0,0 +1,4 @@
+from arcade_google_sheets.tools.read import get_spreadsheet
+from arcade_google_sheets.tools.write import create_spreadsheet, write_to_cell
+
+__all__ = ["create_spreadsheet", "get_spreadsheet", "write_to_cell"]

arcade_google_sheets/tools/read.py

@@ -0,0 +1,42 @@
+from typing import Annotated
+
+from arcade_tdk import ToolContext, ToolMetadataKey, tool
+from arcade_tdk.auth import Google
+
+from arcade_google_sheets.decorators import with_filepicker_fallback
+from arcade_google_sheets.utils import (
+    build_sheets_service,
+    parse_get_spreadsheet_response,
+)
+
+
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/drive.file"],
+    ),
+    requires_metadata=[ToolMetadataKey.CLIENT_ID, ToolMetadataKey.COORDINATOR_URL],
+)
+@with_filepicker_fallback
+async def get_spreadsheet(
+    context: ToolContext,
+    spreadsheet_id: Annotated[str, "The id of the spreadsheet to get"],
+) -> Annotated[
+    dict,
+    "The spreadsheet properties and data for all sheets in the spreadsheet",
+]:
+    """
+    Get the user entered values and formatted values for all cells in all sheets in the spreadsheet
+    along with the spreadsheet's properties
+    """
+    service = build_sheets_service(context.get_auth_token_or_empty())
+
+    response = (
+        service.spreadsheets()
+        .get(
+            spreadsheetId=spreadsheet_id,
+            includeGridData=True,
+            fields="spreadsheetId,spreadsheetUrl,properties/title,sheets/properties,sheets/data/rowData/values/userEnteredValue,sheets/data/rowData/values/formattedValue,sheets/data/rowData/values/effectiveValue",
+        )
+        .execute()
+    )
+    return parse_get_spreadsheet_response(response)

arcade_google_sheets/tools/write.py

@@ -0,0 +1,114 @@
+from typing import Annotated
+
+from arcade_tdk import ToolContext, tool
+from arcade_tdk.auth import Google
+from arcade_tdk.errors import RetryableToolError
+
+from arcade_google_sheets.models import (
+    SheetDataInput,
+    Spreadsheet,
+    SpreadsheetProperties,
+)
+from arcade_google_sheets.utils import (
+    build_sheets_service,
+    create_sheet,
+    parse_write_to_cell_response,
+    validate_write_to_cell_params,
+)
+
+
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/drive.file"],
+    )
+)
+def create_spreadsheet(
+    context: ToolContext,
+    title: Annotated[str, "The title of the new spreadsheet"] = "Untitled spreadsheet",
+    data: Annotated[
+        str | None,
+        "The data to write to the spreadsheet. A JSON string "
+        "(property names enclosed in double quotes) representing a dictionary that "
+        "maps row numbers to dictionaries that map column letters to cell values. "
+        "For example, data[23]['C'] would be the value of the cell in row 23, column C. "
+        "Type hint: dict[int, dict[str, Union[int, float, str, bool]]]",
+    ] = None,
+) -> Annotated[dict, "The created spreadsheet's id and title"]:
+    """Create a new spreadsheet with the provided title and data in its first sheet
+
+    Returns the newly created spreadsheet's id and title
+    """
+    service = build_sheets_service(context.get_auth_token_or_empty())
+
+    try:
+        sheet_data = SheetDataInput(data=data)  # type: ignore[arg-type]
+    except Exception as e:
+        msg = "Invalid JSON or unexpected data format for parameter `data`"
+        raise RetryableToolError(
+            message=msg,
+            additional_prompt_content=f"{msg}: {e}",
+            retry_after_ms=100,
+        )
+
+    spreadsheet = Spreadsheet(
+        properties=SpreadsheetProperties(title=title),
+        sheets=[create_sheet(sheet_data)],
+    )
+
+    body = spreadsheet.model_dump()
+
+    response = (
+        service.spreadsheets()
+        .create(body=body, fields="spreadsheetId,spreadsheetUrl,properties/title")
+        .execute()
+    )
+
+    return {
+        "title": response["properties"]["title"],
+        "spreadsheetId": response["spreadsheetId"],
+        "spreadsheetUrl": response["spreadsheetUrl"],
+    }
+
+
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/drive.file"],
+    )
+)
+def write_to_cell(
+    context: ToolContext,
+    spreadsheet_id: Annotated[str, "The id of the spreadsheet to write to"],
+    column: Annotated[str, "The column string to write to. For example, 'A', 'F', or 'AZ'"],
+    row: Annotated[int, "The row number to write to"],
+    value: Annotated[str, "The value to write to the cell"],
+    sheet_name: Annotated[
+        str, "The name of the sheet to write to. Defaults to 'Sheet1'"
+    ] = "Sheet1",
+) -> Annotated[dict, "The status of the operation"]:
+    """
+    Write a value to a single cell in a spreadsheet.
+    """
+    service = build_sheets_service(context.get_auth_token_or_empty())
+    validate_write_to_cell_params(service, spreadsheet_id, sheet_name, column, row)
+
+    range_ = f"'{sheet_name}'!{column.upper()}{row}"
+    body = {
+        "range": range_,
+        "majorDimension": "ROWS",
+        "values": [[value]],
+    }
+
+    sheet_properties = (
+        service.spreadsheets()
+        .values()
+        .update(
+            spreadsheetId=spreadsheet_id,
+            range=range_,
+            valueInputOption="USER_ENTERED",
+            includeValuesInResponse=True,
+            body=body,
+        )
+        .execute()
+    )
+
+    return parse_write_to_cell_response(sheet_properties)

arcade_google_sheets/types.py

@@ -0,0 +1 @@
+CellValue = int | float | str | bool

arcade_google_sheets/utils.py

@@ -0,0 +1,548 @@
+import logging
+from typing import Any
+
+from arcade_tdk.errors import RetryableToolError, ToolExecutionError
+from google.oauth2.credentials import Credentials
+from googleapiclient.discovery import Resource, build
+
+from arcade_google_sheets.constants import (
+    DEFAULT_SHEET_COLUMN_COUNT,
+    DEFAULT_SHEET_ROW_COUNT,
+)
+from arcade_google_sheets.enums import NumberFormatType
+from arcade_google_sheets.models import (
+    CellData,
+    CellExtendedValue,
+    CellFormat,
+    GridData,
+    GridProperties,
+    NumberFormat,
+    RowData,
+    Sheet,
+    SheetDataInput,
+    SheetProperties,
+)
+from arcade_google_sheets.types import CellValue
+
+logging.basicConfig(
+    level=logging.DEBUG,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+
+logger = logging.getLogger(__name__)
+
+
+def build_sheets_service(auth_token: str | None) -> Resource:  # type: ignore[no-any-unimported]
+    """
+    Build a Sheets service object.
+    """
+    auth_token = auth_token or ""
+    return build("sheets", "v4", credentials=Credentials(auth_token))
+
+
+def col_to_index(col: str) -> int:
+    """Convert a sheet's column string to a 0-indexed column index
+
+    Args:
+        col (str): The column string to convert. e.g., "A", "AZ", "QED"
+
+    Returns:
+        int: The 0-indexed column index.
+    """
+    result = 0
+    for char in col.upper():
+        result = result * 26 + (ord(char) - ord("A") + 1)
+    return result - 1
+
+
+def index_to_col(index: int) -> str:
+    """Convert a 0-indexed column index to its corresponding column string
+
+    Args:
+        index (int): The 0-indexed column index to convert.
+
+    Returns:
+        str: The column string. e.g., "A", "AZ", "QED"
+    """
+    result = ""
+    index += 1
+    while index > 0:
+        index, rem = divmod(index - 1, 26)
+        result = chr(rem + ord("A")) + result
+    return result
+
+
+def is_col_greater(col1: str, col2: str) -> bool:
+    """Determine if col1 represents a column that comes after col2 in a sheet
+
+    This comparison is based on:
+      1. The length of the column string (longer means greater).
+      2. Lexicographical comparison if both strings are the same length.
+
+    Args:
+        col1 (str): The first column string to compare.
+        col2 (str): The second column string to compare.
+
+    Returns:
+        bool: True if col1 comes after col2, False otherwise.
+    """
+    if len(col1) != len(col2):
+        return len(col1) > len(col2)
+    return col1.upper() > col2.upper()
+
+
+def compute_sheet_data_dimensions(
+    sheet_data_input: SheetDataInput,
+) -> tuple[tuple[int, int], tuple[int, int]]:
+    """
+    Compute the dimensions of a sheet based on the data provided.
+
+    Args:
+        sheet_data_input (SheetDataInput):
+            The data to compute the dimensions of.
+
+    Returns:
+        tuple[tuple[int, int], tuple[int, int]]: The dimensions of the sheet. The first tuple
+            contains the row range (start, end) and the second tuple contains the column range
+            (start, end).
+    """
+    max_row = 0
+    min_row = 10_000_000  # max number of cells in a sheet
+    max_col_str = None
+    min_col_str = None
+
+    for key, row in sheet_data_input.data.items():
+        try:
+            row_num = int(key)
+        except ValueError:
+            continue
+        if row_num > max_row:
+            max_row = row_num
+        if row_num < min_row:
+            min_row = row_num
+
+        if isinstance(row, dict):
+            for col in row:
+                # Update max column string
+                if max_col_str is None or is_col_greater(col, max_col_str):
+                    max_col_str = col
+                # Update min column string
+                if min_col_str is None or is_col_greater(min_col_str, col):
+                    min_col_str = col
+
+    max_col_index = col_to_index(max_col_str) if max_col_str is not None else -1
+    min_col_index = col_to_index(min_col_str) if min_col_str is not None else 0
+
+    return (min_row, max_row), (min_col_index, max_col_index)
+
+
+def create_sheet(sheet_data_input: SheetDataInput) -> Sheet:
+    """Create a Google Sheet from a dictionary of data.
+
+    Args:
+        sheet_data_input (SheetDataInput): The data to create the sheet from.
+
+    Returns:
+        Sheet: The created sheet.
+    """
+    (_, max_row), (min_col_index, max_col_index) = compute_sheet_data_dimensions(sheet_data_input)
+    sheet_data = create_sheet_data(sheet_data_input, min_col_index, max_col_index)
+    sheet_properties = create_sheet_properties(
+        row_count=max(DEFAULT_SHEET_ROW_COUNT, max_row),
+        column_count=max(DEFAULT_SHEET_COLUMN_COUNT, max_col_index + 1),
+    )
+
+    return Sheet(properties=sheet_properties, data=sheet_data)
+
+
+def create_sheet_properties(
+    sheet_id: int = 1,
+    title: str = "Sheet1",
+    row_count: int = DEFAULT_SHEET_ROW_COUNT,
+    column_count: int = DEFAULT_SHEET_COLUMN_COUNT,
+) -> SheetProperties:
+    """Create a SheetProperties object
+
+    Args:
+        sheet_id (int): The ID of the sheet.
+        title (str): The title of the sheet.
+        row_count (int): The number of rows in the sheet.
+        column_count (int): The number of columns in the sheet.
+
+    Returns:
+        SheetProperties: The created sheet properties object.
+    """
+    return SheetProperties(
+        sheetId=sheet_id,
+        title=title,
+        gridProperties=GridProperties(rowCount=row_count, columnCount=column_count),
+    )
+
+
+def group_contiguous_rows(row_numbers: list[int]) -> list[list[int]]:
+    """Groups a sorted list of row numbers into contiguous groups
+
+    A contiguous group is a list of row numbers that are consecutive integers.
+    For example, [1,2,3,5,6] is converted to [[1,2,3],[5,6]].
+
+    Args:
+        row_numbers (list[int]): The list of row numbers to group.
+
+    Returns:
+        list[list[int]]: The grouped row numbers.
+    """
+    if not row_numbers:
+        return []
+    groups = []
+    current_group = [row_numbers[0]]
+    for r in row_numbers[1:]:
+        if r == current_group[-1] + 1:
+            current_group.append(r)
+        else:
+            groups.append(current_group)
+            current_group = [r]
+    groups.append(current_group)
+    return groups
+
+
+def create_cell_data(cell_value: CellValue) -> CellData:
+    """
+    Create a CellData object based on the type of cell_value.
+    """
+    if isinstance(cell_value, bool):
+        return _create_bool_cell(cell_value)
+    elif isinstance(cell_value, int):
+        return _create_int_cell(cell_value)
+    elif isinstance(cell_value, float):
+        return _create_float_cell(cell_value)
+    elif isinstance(cell_value, str):
+        return _create_string_cell(cell_value)
+
+
+def _create_formula_cell(cell_value: str) -> CellData:
+    cell_val = CellExtendedValue(formulaValue=cell_value)
+    return CellData(userEnteredValue=cell_val)
+
+
+def _create_currency_cell(cell_value: str) -> CellData:
+    value_without_symbol = cell_value[1:]
+    try:
+        num_value = int(value_without_symbol)
+        cell_format = CellFormat(
+            numberFormat=NumberFormat(type=NumberFormatType.CURRENCY, pattern="$#,##0")
+        )
+        cell_val = CellExtendedValue(numberValue=num_value)
+        return CellData(userEnteredValue=cell_val, userEnteredFormat=cell_format)
+    except ValueError:
+        try:
+            num_value = float(value_without_symbol)  # type: ignore[assignment]
+            cell_format = CellFormat(
+                numberFormat=NumberFormat(type=NumberFormatType.CURRENCY, pattern="$#,##0.00")
+            )
+            cell_val = CellExtendedValue(numberValue=num_value)
+            return CellData(userEnteredValue=cell_val, userEnteredFormat=cell_format)
+        except ValueError:
+            return CellData(userEnteredValue=CellExtendedValue(stringValue=cell_value))
+
+
+def _create_percent_cell(cell_value: str) -> CellData:
+    try:
+        num_value = float(cell_value[:-1].strip())
+        cell_format = CellFormat(
+            numberFormat=NumberFormat(type=NumberFormatType.PERCENT, pattern="0.00%")
+        )
+        cell_val = CellExtendedValue(numberValue=num_value)
+        return CellData(userEnteredValue=cell_val, userEnteredFormat=cell_format)
+    except ValueError:
+        return CellData(userEnteredValue=CellExtendedValue(stringValue=cell_value))
+
+
+def _create_bool_cell(cell_value: bool) -> CellData:
+    return CellData(userEnteredValue=CellExtendedValue(boolValue=cell_value))
+
+
+def _create_int_cell(cell_value: int) -> CellData:
+    cell_format = CellFormat(
+        numberFormat=NumberFormat(type=NumberFormatType.NUMBER, pattern="#,##0")
+    )
+    return CellData(
+        userEnteredValue=CellExtendedValue(numberValue=cell_value), userEnteredFormat=cell_format
+    )
+
+
+def _create_float_cell(cell_value: float) -> CellData:
+    cell_format = CellFormat(
+        numberFormat=NumberFormat(type=NumberFormatType.NUMBER, pattern="#,##0.00")
+    )
+    return CellData(
+        userEnteredValue=CellExtendedValue(numberValue=cell_value), userEnteredFormat=cell_format
+    )
+
+
+def _create_string_cell(cell_value: str) -> CellData:
+    if cell_value.startswith("="):
+        return _create_formula_cell(cell_value)
+    elif cell_value.startswith("$") and len(cell_value) > 1:
+        return _create_currency_cell(cell_value)
+    elif cell_value.endswith("%") and len(cell_value) > 1:
+        return _create_percent_cell(cell_value)
+
+    return CellData(userEnteredValue=CellExtendedValue(stringValue=cell_value))
+
+
+def create_row_data(
+    row_data: dict[str, CellValue], min_col_index: int, max_col_index: int
+) -> RowData:
+    """Constructs RowData for a single row using the provided row_data.
+
+    Args:
+        row_data (dict[str, CellValue]): The data to create the row from.
+        min_col_index (int): The minimum column index from the SheetDataInput.
+        max_col_index (int): The maximum column index from the SheetDataInput.
+    """
+    row_cells = []
+    for col_idx in range(min_col_index, max_col_index + 1):
+        col_letter = index_to_col(col_idx)
+        if col_letter in row_data:
+            cell_data = create_cell_data(row_data[col_letter])
+        else:
+            cell_data = CellData(userEnteredValue=CellExtendedValue(stringValue=""))
+        row_cells.append(cell_data)
+    return RowData(values=row_cells)
+
+
+def create_sheet_data(
+    sheet_data_input: SheetDataInput,
+    min_col_index: int,
+    max_col_index: int,
+) -> list[GridData]:
+    """Create grid data from SheetDataInput by grouping contiguous rows and processing cells.
+
+    Args:
+        sheet_data_input (SheetDataInput): The data to create the sheet from.
+        min_col_index (int): The minimum column index from the SheetDataInput.
+        max_col_index (int): The maximum column index from the SheetDataInput.
+
+    Returns:
+        list[GridData]: The created grid data.
+    """
+    row_numbers = list(sheet_data_input.data.keys())
+    if not row_numbers:
+        return []
+
+    sorted_rows = sorted(row_numbers)
+    groups = group_contiguous_rows(sorted_rows)
+
+    sheet_data = []
+    for group in groups:
+        rows_data = []
+        for r in group:
+            current_row_data = sheet_data_input.data.get(r, {})
+            row = create_row_data(current_row_data, min_col_index, max_col_index)
+            rows_data.append(row)
+        grid_data = GridData(
+            startRow=group[0] - 1,  # convert to 0-indexed
+            startColumn=min_col_index,
+            rowData=rows_data,
+        )
+        sheet_data.append(grid_data)
+
+    return sheet_data
+
+
+def parse_get_spreadsheet_response(api_response: dict) -> dict:
+    """
+    Parse the get spreadsheet Google Sheets API response into a structured dictionary.
+    """
+    properties = api_response.get("properties", {})
+    sheets = [parse_sheet(sheet) for sheet in api_response.get("sheets", [])]
+
+    return {
+        "title": properties.get("title", ""),
+        "spreadsheetId": api_response.get("spreadsheetId", ""),
+        "spreadsheetUrl": api_response.get("spreadsheetUrl", ""),
+        "sheets": sheets,
+    }
+
+
+def parse_sheet(api_sheet: dict) -> dict:
+    """
+    Parse an individual sheet's data from the Google Sheets 'get spreadsheet'
+    API response into a structured dictionary.
+    """
+    props = api_sheet.get("properties", {})
+    grid_props = props.get("gridProperties", {})
+    cell_data = convert_api_grid_data_to_dict(api_sheet.get("data", []))
+
+    return {
+        "sheetId": props.get("sheetId"),
+        "title": props.get("title", ""),
+        "rowCount": grid_props.get("rowCount", 0),
+        "columnCount": grid_props.get("columnCount", 0),
+        "data": cell_data,
+    }
+
+
+def extract_user_entered_cell_value(cell: dict) -> Any:
+    """
+    Extract the user entered value from a cell's 'userEnteredValue'.
+
+    Args:
+        cell (dict): A cell dictionary from the grid data.
+
+    Returns:
+        The extracted value if present, otherwise None.
+    """
+    user_val = cell.get("userEnteredValue", {})
+    for key in ["stringValue", "numberValue", "boolValue", "formulaValue"]:
+        if key in user_val:
+            return user_val[key]
+
+    return ""
+
+
+def process_row(row: dict, start_column_index: int) -> dict:
+    """
+    Process a single row from grid data, converting non-empty cells into a dictionary
+    that maps column letters to cell values.
+
+    Args:
+        row (dict): A row from the grid data.
+        start_column_index (int): The starting column index for this row.
+
+    Returns:
+        dict: A mapping of column letters to cell values for non-empty cells.
+    """
+    row_result = {}
+    for j, cell in enumerate(row.get("values", [])):
+        column_index = start_column_index + j
+        column_string = index_to_col(column_index)
+        user_entered_cell_value = extract_user_entered_cell_value(cell)
+        formatted_cell_value = cell.get("formattedValue", "")
+
+        if user_entered_cell_value != "" or formatted_cell_value != "":
+            row_result[column_string] = {
+                "userEnteredValue": user_entered_cell_value,
+                "formattedValue": formatted_cell_value,
+            }
+
+    return row_result
+
+
+def convert_api_grid_data_to_dict(grids: list[dict]) -> dict:
+    """
+    Convert a list of grid data dictionaries from the 'get spreadsheet' API
+    response into a structured cell dictionary.
+
+    The returned dictionary maps row numbers to sub-dictionaries that map column letters
+    (e.g., 'A', 'B', etc.) to their corresponding non-empty cell values.
+
+    Args:
+        grids (list[dict]): The list of grid data dictionaries from the API.
+
+    Returns:
+        dict: A dictionary mapping row numbers to dictionaries of column letter/value pairs.
+            Only includes non-empty rows and non-empty cells.
+    """
+    result = {}
+    for grid in grids:
+        start_row = grid.get("startRow", 0)
+        start_column = grid.get("startColumn", 0)
+
+        for i, row in enumerate(grid.get("rowData", []), start=1):
+            current_row = start_row + i
+            row_data = process_row(row, start_column)
+
+            if row_data:
+                result[current_row] = row_data
+
+    return dict(sorted(result.items()))
+
+
+def validate_write_to_cell_params(  # type: ignore[no-any-unimported]
+    service: Resource,
+    spreadsheet_id: str,
+    sheet_name: str,
+    column: str,
+    row: int,
+) -> None:
+    """Validates the input parameters for the write to cell tool.
+
+    Args:
+        service (Resource): The Google Sheets service.
+        spreadsheet_id (str): The ID of the spreadsheet provided to the tool.
+        sheet_name (str): The name of the sheet provided to the tool.
+        column (str): The column to write to provided to the tool.
+        row (int): The row to write to provided to the tool.
+
+    Raises:
+        RetryableToolError:
+            If the sheet name is not found in the spreadsheet
+        ToolExecutionError:
+            If the column is not alphabetical
+            If the row is not a positive number
+            If the row is out of bounds for the sheet
+            If the column is out of bounds for the sheet
+    """
+    if not column.isalpha():
+        raise ToolExecutionError(
+            message=(
+                f"Invalid column name {column}. "
+                "It must be a non-empty string containing only letters"
+            ),
+        )
+
+    if row < 1:
+        raise ToolExecutionError(
+            message=(f"Invalid row number {row}. It must be a positive integer greater than 0."),
+        )
+
+    sheet_properties = (
+        service.spreadsheets()
+        .get(
+            spreadsheetId=spreadsheet_id,
+            includeGridData=True,
+            fields="sheets/properties/title,sheets/properties/gridProperties/rowCount,sheets/properties/gridProperties/columnCount",
+        )
+        .execute()
+    )
+    sheet_names = [sheet["properties"]["title"] for sheet in sheet_properties["sheets"]]
+    sheet_row_count = sheet_properties["sheets"][0]["properties"]["gridProperties"]["rowCount"]
+    sheet_column_count = sheet_properties["sheets"][0]["properties"]["gridProperties"][
+        "columnCount"
+    ]
+
+    if sheet_name not in sheet_names:
+        raise RetryableToolError(
+            message=f"Sheet name {sheet_name} not found in spreadsheet with id {spreadsheet_id}",
+            additional_prompt_content=f"Sheet names in the spreadsheet: {sheet_names}",
+            retry_after_ms=100,
+        )
+
+    if row > sheet_row_count:
+        raise ToolExecutionError(
+            message=(
+                f"Row {row} is out of bounds for sheet {sheet_name} "
+                f"in spreadsheet with id {spreadsheet_id}. "
+                f"Sheet only has {sheet_row_count} rows which is less than the requested row {row}"
+            )
+        )
+
+    if col_to_index(column) > sheet_column_count:
+        raise ToolExecutionError(
+            message=(
+                f"Column {column} is out of bounds for sheet {sheet_name} "
+                f"in spreadsheet with id {spreadsheet_id}. "
+                f"Sheet only has {sheet_column_count} columns which "
+                f"is less than the requested column {column}"
+            )
+        )
+
+
+def parse_write_to_cell_response(response: dict) -> dict:
+    return {
+        "spreadsheetId": response["spreadsheetId"],
+        "sheetTitle": response["updatedData"]["range"].split("!")[0],
+        "updatedCell": response["updatedData"]["range"].split("!")[1],
+        "value": response["updatedData"]["values"][0][0],
+    }

arcade_google_sheets-2.0.0rc1.dist-info/METADATA

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: arcade_google_sheets
+Version: 2.0.0rc1
+Summary: Arcade.dev LLM tools for Google Sheets
+Author-email: Arcade <dev@arcade.dev>
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: arcade-tdk<3.0.0,>=2.0.0
+Requires-Dist: google-api-core<3.0.0,>=2.19.1
+Requires-Dist: google-api-python-client<3.0.0,>=2.137.0
+Requires-Dist: google-auth-httplib2<1.0.0,>=0.2.0
+Requires-Dist: google-auth<3.0.0,>=2.32.0
+Requires-Dist: googleapis-common-protos<2.0.0,>=1.63.2
+Provides-Extra: dev
+Requires-Dist: arcade-ai[evals]<3.0.0,>=2.0.0rc1; extra == 'dev'
+Requires-Dist: arcade-serve<3.0.0,>=2.0.0; extra == 'dev'
+Requires-Dist: mypy<1.6.0,>=1.5.1; extra == 'dev'
+Requires-Dist: pre-commit<3.5.0,>=3.4.0; extra == 'dev'
+Requires-Dist: pytest-asyncio<0.25.0,>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov<4.1.0,>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-mock<3.12.0,>=3.11.1; extra == 'dev'
+Requires-Dist: pytest<8.4.0,>=8.3.0; extra == 'dev'
+Requires-Dist: ruff<0.8.0,>=0.7.4; extra == 'dev'
+Requires-Dist: tox<4.12.0,>=4.11.1; extra == 'dev'

arcade_google_sheets-2.0.0rc1.dist-info/RECORD

@@ -0,0 +1,15 @@
+arcade_google_sheets/__init__.py,sha256=FB9h_cws_gu3UJp32GWlqvBQyAOb77JfAJNSSBqz-Jk,177
+arcade_google_sheets/constants.py,sha256=4tQOrQ1YagSklJSSw5Eq21XCcFCJdO7lso5SqWIdrPI,63
+arcade_google_sheets/decorators.py,sha256=QMqfvSXaFBoxYJrz69EGeMdAxF0V7JPReVXfp73Nf3Y,753
+arcade_google_sheets/enums.py,sha256=_gZxlgciXK-_Sg-62lTv6JFpmxWV7obH9VWE-s1zjug,942
+arcade_google_sheets/file_picker.py,sha256=kGfUVfH5QVlIW1sL-_gAwPokt7TwVEcPk3Vnk53GKUE,2005
+arcade_google_sheets/models.py,sha256=VQy3L_Acch1MEM2RkTe-Qp_AEU-cb0JciLJ-0Ci87aw,7613
+arcade_google_sheets/types.py,sha256=R-rCRcyFqDZx3jgl_kWeCliqC8fHuZ8ub_LQ2KoU2AE,37
+arcade_google_sheets/utils.py,sha256=CqQJPwXP_QoMJG18LrltG4sblTcFe4Mu5psY4U2nsvc,18412
+arcade_google_sheets/tools/__init__.py,sha256=TPlitJn1VJffCXFkpOtoYXNsaEFkpujQzsYvuikCe4U,209
+arcade_google_sheets/tools/read.py,sha256=Fh9nh8ISHBgf6akixVYQIt3TihrmW7P9WW8yeb-njhI,1416
+arcade_google_sheets/tools/write.py,sha256=gmbErdBbBKUEPxGjCWDpMJ9pMWRAvoEjApIXFQax6Z4,3598
+arcade_google_sheets-2.0.0rc1.dist-info/METADATA,sha256=7i1LqljWn_XKRIbID_4i-cF0qigW2_o0xGQbrs0vOgM,1067
+arcade_google_sheets-2.0.0rc1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+arcade_google_sheets-2.0.0rc1.dist-info/licenses/LICENSE,sha256=XjKuCk1TG4bFrY-8x79oGMmNqrS4TP7c_Zv4-TrMWQY,1063
+arcade_google_sheets-2.0.0rc1.dist-info/RECORD,,

arcade_google_sheets-2.0.0rc1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

arcade_google_sheets-2.0.0rc1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Arcade
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.