lumera 0.8.0__tar.gz → 0.8.2__tar.gz

{lumera-0.8.0 → lumera-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lumera
-Version: 0.8.0
+Version: 0.8.2
 Summary: SDK for building on Lumera platform
 Requires-Python: >=3.11
 Requires-Dist: requests

{lumera-0.8.0 → lumera-0.8.2}/lumera/__init__.py

@@ -1,14 +1,14 @@
 """
 Lumera Agent SDK
 
-This SDK provides helpers for agents running within the Lumera Notebook environment
+This SDK provides helpers for automations running within the Lumera environment
 to interact with the Lumera API and define dynamic user interfaces.
 """
 
 __version__ = "0.8.0"
 
 # Import new modules (as modules, not individual functions)
-from . import automations, exceptions, llm, locks, pb, storage, webhooks
+from . import automations, exceptions, integrations, llm, locks, pb, storage, webhooks
 from ._utils import (
     LumeraAPIError,
     RecordNotUniqueError,
@@ -98,4 +98,5 @@ __all__ = [
     "locks",
     "exceptions",
     "webhooks",
+    "integrations",
 ]

{lumera-0.8.0 → lumera-0.8.2}/lumera/_utils.py

@@ -13,6 +13,7 @@ from functools import wraps as _wraps
 from typing import IO, Any, Callable, Iterable, Mapping, MutableMapping, Sequence, TypeVar
 
 import requests
+import requests.adapters
 from dotenv import load_dotenv
 
 TOKEN_ENV = "LUMERA_TOKEN"
@@ -35,6 +36,25 @@ MOUNT_ROOT = _mount_env
 
 _token_cache: dict[str, tuple[str, float]] = {}
 
+# Connection pooling for better performance
+_http_session: requests.Session | None = None
+
+
+def _get_session() -> requests.Session:
+    """Get or create a shared requests Session with connection pooling."""
+    global _http_session
+    if _http_session is None:
+        _http_session = requests.Session()
+        # Configure connection pooling
+        adapter = requests.adapters.HTTPAdapter(
+            pool_connections=10,
+            pool_maxsize=20,
+            max_retries=0,  # Don't retry automatically, let caller handle
+        )
+        _http_session.mount("https://", adapter)
+        _http_session.mount("http://", adapter)
+    return _http_session
+
 
 def get_lumera_token() -> str:
     token = os.getenv(TOKEN_ENV)
@@ -251,7 +271,8 @@ def _api_request(
         "Accept": "application/json",
     }
 
-    resp = requests.request(
+    session = _get_session()
+    resp = session.request(
         method,
         url,
         params=params,

{lumera-0.8.0 → lumera-0.8.2}/lumera/automations.py

@@ -25,7 +25,7 @@ Example:
     >>> from lumera import automations
     >>>
     >>> # Run an automation
-    >>> run = automations.run("agent_id", inputs={"limit": 100})
+    >>> run = automations.run("automation_id", inputs={"limit": 100})
     >>> print(run.id, run.status)
     >>>
     >>> # Wait for completion
@@ -78,7 +78,7 @@ class Run:
 
     Attributes:
         id: The run ID.
-        automation_id: The automation/agent ID.
+        automation_id: The automation ID.
         status: Current status (queued, running, succeeded, failed, cancelled, timeout).
         inputs: The inputs passed to the run.
         result: The result returned by the automation (when succeeded).
@@ -329,7 +329,7 @@ def run(
     """Run an automation by ID.
 
     Args:
-        automation_id: The automation/agent ID to run.
+        automation_id: The automation ID to run.
         inputs: Input parameters (dict). Types are coerced based on input_schema.
         files: File inputs to upload (mapping of input key to file path(s)).
         external_id: Optional correlation ID for idempotency. Repeated calls
@@ -430,7 +430,7 @@ def list_runs(
         List of Run objects.
 
     Example:
-        >>> runs = automations.list_runs("agent_id", status="succeeded", limit=10)
+        >>> runs = automations.list_runs("automation_id", status="succeeded", limit=10)
         >>> for r in runs:
         ...     print(r.id, r.created, r.status)
     """
@@ -509,8 +509,8 @@ def get(automation_id: str) -> Automation:
         An Automation object.
 
     Example:
-        >>> agent = automations.get("abc123")
-        >>> print(agent.name, agent.input_schema)
+        >>> automation = automations.get("abc123")
+        >>> print(automation.name, automation.input_schema)
     """
     automation_id = automation_id.strip()
     if not automation_id:
@@ -535,8 +535,8 @@ def get_by_external_id(external_id: str) -> Automation:
         LumeraAPIError: If no automation with that external_id exists.
 
     Example:
-        >>> agent = automations.get_by_external_id("deposit_matching:step1")
-        >>> print(agent.id, agent.name)
+        >>> automation = automations.get_by_external_id("deposit_matching:step1")
+        >>> print(automation.id, automation.name)
     """
     external_id = external_id.strip()
     if not external_id:
@@ -582,7 +582,7 @@ def create(
         The created Automation object.
 
     Example:
-        >>> agent = automations.create(
+        >>> automation = automations.create(
         ...     name="My Automation",
         ...     code="def main(x): return {'result': x * 2}",
         ...     input_schema={

lumera-0.8.2/lumera/google.py

@@ -0,0 +1,47 @@
+"""
+Backward compatibility shim for lumera.google.
+
+This module has moved to lumera.integrations.google.
+All imports are re-exported here for backward compatibility.
+
+New code should use:
+    from lumera.integrations import google
+    # or
+    from lumera.integrations.google import get_sheets_service, get_drive_service
+"""
+
+# Re-export everything from the new location
+from lumera.integrations.google import (
+    MIME_EXCEL,
+    MIME_GOOGLE_SHEET,
+    delete_rows_api_call,
+    download_file_direct,
+    get_credentials,
+    get_drive_service,
+    get_google_credentials,
+    get_sheets_service,
+    get_spreadsheet_and_sheet_id,
+    read_cell,
+    sheet_name_from_gid,
+    upload_excel_as_google_sheet,
+)
+
+__all__ = [
+    # Authentication
+    "get_credentials",
+    "get_google_credentials",
+    # Services
+    "get_sheets_service",
+    "get_drive_service",
+    # Sheets helpers
+    "get_spreadsheet_and_sheet_id",
+    "sheet_name_from_gid",
+    "read_cell",
+    "delete_rows_api_call",
+    # Drive helpers
+    "download_file_direct",
+    "upload_excel_as_google_sheet",
+    # Constants
+    "MIME_GOOGLE_SHEET",
+    "MIME_EXCEL",
+]

{lumera-0.8.0 → lumera-0.8.2}/lumera/sdk.py

@@ -399,10 +399,10 @@ def run_automation(
     external_id: str | None = None,
     metadata: Mapping[str, Any] | None = None,
 ) -> dict[str, Any]:
-    """Create an agent run and optionally upload files for file inputs.
+    """Create an automation run and optionally upload files for file inputs.
 
     Args:
-        automation_id: The automation/agent to run. Required.
+        automation_id: The automation to run. Required.
         inputs: Inputs payload (dict or JSON string). File refs are resolved automatically.
         files: Mapping of input key -> path(s) to upload before run creation.
         status: Optional initial status (defaults to ``queued``).
@@ -463,12 +463,13 @@ def get_automation_run(
     run_id: str | None = None,
     external_id: str | None = None,
 ) -> dict[str, Any]:
-    """Fetch an agent run by id or by automation_id + external_id idempotency key.
+    """Fetch an automation run by id or by automation_id + external_id idempotency key.
 
     Args:
-        automation_id: Agent id for external_id lookup. Required when ``run_id`` is not provided.
-        run_id: Optional run id. When provided, this takes precedence over external_id lookup.
-        external_id: Optional idempotency key to look up the latest run for the agent.
+        automation_id: Automation id for external_id lookup.
+            Required when ``run_id`` is not provided.
+        run_id: Optional run id. When provided, takes precedence over external_id.
+        external_id: Optional idempotency key to look up the latest run for the automation.
 
     Raises:
         ValueError: If required identifiers are missing.
@@ -510,7 +511,7 @@ def update_automation_run(
     error: str | None = None,
     metadata: Mapping[str, Any] | None = None,
 ) -> dict[str, Any]:
-    """Update an agent run with result, status, or other fields.
+    """Update an automation run with result, status, or other fields.
 
     Args:
         run_id: The run id to update. Required.
@@ -520,7 +521,7 @@ def update_automation_run(
         metadata: Optional metadata update.
 
     Returns:
-        The updated agent run record.
+        The updated automation run record.
     """
     run_id = run_id.strip() if isinstance(run_id, str) else ""
     if not run_id:

{lumera-0.8.0 → lumera-0.8.2}/lumera/webhooks.py

@@ -25,7 +25,7 @@ Example:
     >>> # Get the public URL to configure in Stripe
     >>> webhook_url = webhooks.url("stripe-events")
     >>> print(webhook_url)
-    https://app.lumerahq.com/webhooks/acme/stripe-events
+    https://app.lumerahq.com/webhooks/rec_abc123/stripe-events
     >>>
     >>> # List all endpoints
     >>> for ep in webhooks.list():
@@ -171,11 +171,18 @@ def get(external_id: str) -> dict[str, Any]:
     result = _api_request("GET", f"collections/{_COLLECTION}/records", params=params)
 
     if not isinstance(result, dict):
-        raise LumeraAPIError(404, "endpoint not found", url=f"collections/{_COLLECTION}/records", payload=None)
+        raise LumeraAPIError(
+            404, "endpoint not found", url=f"collections/{_COLLECTION}/records", payload=None
+        )
 
     items = result.get("items", [])
     if not items:
-        raise LumeraAPIError(404, f"webhook endpoint '{external_id}' not found", url=f"collections/{_COLLECTION}/records", payload=None)
+        raise LumeraAPIError(
+            404,
+            f"webhook endpoint '{external_id}' not found",
+            url=f"collections/{_COLLECTION}/records",
+            payload=None,
+        )
 
     return items[0]
 
@@ -223,7 +230,9 @@ def update(
     if not payload:
         raise ValueError("at least one field (name or description) must be provided")
 
-    result = _api_request("PATCH", f"collections/{_COLLECTION}/records/{record_id}", json_body=payload)
+    result = _api_request(
+        "PATCH", f"collections/{_COLLECTION}/records/{record_id}", json_body=payload
+    )
     if not isinstance(result, dict):
         raise RuntimeError("unexpected response payload")
     return result
@@ -257,7 +266,7 @@ def url(external_id: str) -> str:
     """Get the public webhook URL for an endpoint.
 
     This returns the full URL that external services should send webhooks to.
-    The URL format is: https://{base}/webhooks/{company_api}/{external_id}
+    The URL format is: https://{base}/webhooks/{company_id}/{external_id}
 
     Args:
         external_id: The external_id of the endpoint
@@ -267,12 +276,12 @@ def url(external_id: str) -> str:
 
     Raises:
         ValueError: If external_id is empty
-        RuntimeError: If COMPANY_API_NAME environment variable is not set
+        RuntimeError: If COMPANY_ID environment variable is not set
 
     Example:
         >>> url = webhooks.url("stripe-events")
         >>> print(url)
-        https://app.lumerahq.com/webhooks/acme/stripe-events
+        https://app.lumerahq.com/webhooks/rec_abc123/stripe-events
 
         # Use this URL when configuring webhooks in Stripe, GitHub, etc.
     """
@@ -280,10 +289,10 @@ def url(external_id: str) -> str:
     if not external_id:
         raise ValueError("external_id is required")
 
-    company_api = os.getenv("COMPANY_API_NAME", "").strip()
-    if not company_api:
+    company_id = os.getenv("COMPANY_ID", "").strip()
+    if not company_id:
         raise RuntimeError(
-            "COMPANY_API_NAME environment variable not set. "
+            "COMPANY_ID environment variable not set. "
             "This is required to construct the webhook URL."
         )
 
@@ -292,4 +301,4 @@ def url(external_id: str) -> str:
     if base_url.endswith("/api"):
         base_url = base_url[:-4]
 
-    return f"{base_url}/webhooks/{company_api}/{external_id}"
+    return f"{base_url}/webhooks/{company_id}/{external_id}"

{lumera-0.8.0 → lumera-0.8.2}/lumera.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lumera
-Version: 0.8.0
+Version: 0.8.2
 Summary: SDK for building on Lumera platform
 Requires-Python: >=3.11
 Requires-Dist: requests

{lumera-0.8.0 → lumera-0.8.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lumera"
-version = "0.8.0"
+version = "0.8.2"
 description = "SDK for building on Lumera platform"
 requires-python = ">=3.11"
 dependencies = [

{lumera-0.8.0 → lumera-0.8.2}/tests/test_sdk.py

@@ -5,6 +5,7 @@ from typing import IO, Any, Mapping
 import pytest
 import requests
 
+import lumera._utils as _utils
 import lumera.sdk as sdk
 from lumera.sdk import (
     FileRef,
@@ -31,6 +32,14 @@ ROOT = sdk.MOUNT_ROOT.rstrip("/")
 LEGACY_ROOT = "/lumera-files"
 
 
+@pytest.fixture(autouse=True)
+def reset_http_session() -> None:
+    """Reset the cached HTTP session before each test to allow proper mocking."""
+    _utils._http_session = None
+    yield
+    _utils._http_session = None
+
+
 class DummyResponse:
     def __init__(
         self,
@@ -127,7 +136,14 @@ def test_list_collections_uses_token_and_returns_payload(monkeypatch: pytest.Mon
         recorded["headers"] = kwargs.get("headers")
         return DummyResponse(json_data={"items": [{"id": "col"}]})
 
-    monkeypatch.setattr(sdk.requests, "request", fake_request)
+    class MockSession:
+        def request(self, method: str, url: str, **kwargs: object) -> DummyResponse:
+            return fake_request(method, url, **kwargs)
+
+        def mount(self, prefix: str, adapter: object) -> None:
+            pass
+
+    monkeypatch.setattr(_utils, "_get_session", lambda: MockSession())
 
     resp = list_collections()
     assert resp["items"][0]["id"] == "col"
@@ -147,7 +163,14 @@ def test_create_collection_posts_payload(monkeypatch: pytest.MonkeyPatch) -> Non
         captured["json"] = kwargs.get("json")
         return DummyResponse(status_code=201, json_data={"id": "new"})
 
-    monkeypatch.setattr(sdk.requests, "request", fake_request)
+    class MockSession:
+        def request(self, method: str, url: str, **kwargs: object) -> DummyResponse:
+            return fake_request(method, url, **kwargs)
+
+        def mount(self, prefix: str, adapter: object) -> None:
+            pass
+
+    monkeypatch.setattr(_utils, "_get_session", lambda: MockSession())
 
     resp = create_collection(
         "example", schema=[{"name": "field", "type": "text"}], indexes=["CREATE INDEX"]
@@ -170,7 +193,14 @@ def test_create_record_sends_json_payload(monkeypatch: pytest.MonkeyPatch) -> No
         captured["json"] = kwargs.get("json")
         return DummyResponse(status_code=201, json_data={"id": "rec"})
 
-    monkeypatch.setattr(sdk.requests, "request", fake_request)
+    class MockSession:
+        def request(self, method: str, url: str, **kwargs: object) -> DummyResponse:
+            return fake_request(method, url, **kwargs)
+
+        def mount(self, prefix: str, adapter: object) -> None:
+            pass
+
+    monkeypatch.setattr(_utils, "_get_session", lambda: MockSession())
 
     resp = create_record("example", {"name": "value"})
     assert resp["id"] == "rec"
@@ -332,7 +362,14 @@ def test_replay_hook_posts_payload(monkeypatch: pytest.MonkeyPatch) -> None:
             url=url,
         )
 
-    monkeypatch.setattr(sdk.requests, "request", fake_request)
+    class MockSession:
+        def request(self, method: str, url: str, **kwargs: object) -> DummyResponse:
+            return fake_request(method, url, **kwargs)
+
+        def mount(self, prefix: str, adapter: object) -> None:
+            pass
+
+    monkeypatch.setattr(_utils, "_get_session", lambda: MockSession())
 
     results: list[HookReplayResult] = replay_hook(
         " lm_event_log ",
@@ -371,7 +408,14 @@ def test_get_collection_error_raises(monkeypatch: pytest.MonkeyPatch) -> None:
     def fake_request(_method: str, _url: str, **_kwargs: object) -> DummyResponse:
         return DummyResponse(status_code=404, json_data={"error": "not found"}, url=_url)
 
-    monkeypatch.setattr(sdk.requests, "request", fake_request)
+    class MockSession:
+        def request(self, method: str, url: str, **kwargs: object) -> DummyResponse:
+            return fake_request(method, url, **kwargs)
+
+        def mount(self, prefix: str, adapter: object) -> None:
+            pass
+
+    monkeypatch.setattr(_utils, "_get_session", lambda: MockSession())
 
     with pytest.raises(LumeraAPIError) as exc:
         get_collection("missing")
@@ -390,7 +434,14 @@ def test_create_record_unique_error(monkeypatch: pytest.MonkeyPatch) -> None:
             url="https://app.lumerahq.com/api/pb/collections/example/records",
         )
 
-    monkeypatch.setattr(sdk.requests, "request", fake_request)
+    class MockSession:
+        def request(self, method: str, url: str, **kwargs: object) -> DummyResponse:
+            return fake_request(method, url, **kwargs)
+
+        def mount(self, prefix: str, adapter: object) -> None:
+            pass
+
+    monkeypatch.setattr(_utils, "_get_session", lambda: MockSession())
 
     with pytest.raises(RecordNotUniqueError):
         create_record("example", {"external_id": "dup"})
@@ -407,7 +458,14 @@ def test_get_record_by_external_id(monkeypatch: pytest.MonkeyPatch) -> None:
         captured["params"] = kwargs.get("params")
         return DummyResponse(json_data={"items": [{"id": "rec"}]})
 
-    monkeypatch.setattr(sdk.requests, "request", fake_request)
+    class MockSession:
+        def request(self, method: str, url: str, **kwargs: object) -> DummyResponse:
+            return fake_request(method, url, **kwargs)
+
+        def mount(self, prefix: str, adapter: object) -> None:
+            pass
+
+    monkeypatch.setattr(_utils, "_get_session", lambda: MockSession())
 
     record = get_record_by_external_id("example", "ext value")
     assert record["id"] == "rec"
@@ -424,7 +482,14 @@ def test_get_record_by_external_id_not_found(monkeypatch: pytest.MonkeyPatch) ->
     def fake_request(_method: str, _url: str, **_kwargs: object) -> DummyResponse:
         return DummyResponse(json_data={"items": []})
 
-    monkeypatch.setattr(sdk.requests, "request", fake_request)
+    class MockSession:
+        def request(self, method: str, url: str, **kwargs: object) -> DummyResponse:
+            return fake_request(method, url, **kwargs)
+
+        def mount(self, prefix: str, adapter: object) -> None:
+            pass
+
+    monkeypatch.setattr(_utils, "_get_session", lambda: MockSession())
 
     with pytest.raises(LumeraAPIError) as exc:
         get_record_by_external_id("example", "missing")
@@ -703,7 +768,7 @@ def test_get_automation_run_by_external_id(monkeypatch: pytest.MonkeyPatch) -> N
 
 def test_claim_locks_default_provenance_uses_env(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setenv(sdk.TOKEN_ENV, "tok")
-    monkeypatch.setenv("LUMERA_AGENT_ID", "agent-env")
+    monkeypatch.setenv("LUMERA_AUTOMATION_ID", "agent-env")
     monkeypatch.setenv("LUMERA_RUN_ID", "run-env")
 
     captured: dict[str, object] = {}

lumera-0.8.0/lumera/google.py

@@ -1,270 +0,0 @@
-import io
-import logging
-import os
-import re
-from typing import TYPE_CHECKING, Optional, Tuple
-
-# When type checking we want access to the concrete ``Resource`` class that
-# ``googleapiclient.discovery.build`` returns. Importing it unconditionally
-# would require ``googleapiclient`` to be available in every execution
-# environment – something we cannot guarantee.  By guarding the import with
-# ``TYPE_CHECKING`` we give static analysers (ruff, mypy, etc.) the
-# information they need without introducing a hard runtime dependency.
-# During static analysis we want to import ``Resource`` so that it is a known
-# name for type checkers, but we don't require this import at runtime. Guard
-# it with ``TYPE_CHECKING`` to avoid hard dependencies.
-if TYPE_CHECKING:  # pragma: no cover
-    from googleapiclient.discovery import Resource  # noqa: F401
-
-# Always ensure that the symbol ``Resource`` exists at runtime to placate static
-# analysers like ruff (F821) that inspect the AST without executing the code.
-try:  # pragma: no cover – optional runtime import
-    from googleapiclient.discovery import Resource  # type: ignore
-except ModuleNotFoundError:  # pragma: no cover – provide a stub fallback
-
-    class Resource:  # noqa: D401
-        """Stub replacement for ``googleapiclient.discovery.Resource``."""
-
-        pass
-
-
-from google.oauth2.credentials import Credentials
-from googleapiclient.discovery import build
-from googleapiclient.http import MediaFileUpload, MediaIoBaseDownload
-
-from lumera import get_access_token
-
-# Module logger
-logger = logging.getLogger(__name__)
-
-# =====================================================================================
-# Configuration
-# =====================================================================================
-
-MIME_GOOGLE_SHEET = "application/vnd.google-apps.spreadsheet"
-MIME_EXCEL = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
-
-# =====================================================================================
-# Authentication & Service Initialization
-# =====================================================================================
-
-
-def get_google_credentials() -> Credentials:
-    """
-    Retrieves a Google OAuth token from Lumera and
-    converts it into a Credentials object usable by googleapiclient.
-    """
-    logger.debug("Fetching Google access token from Lumera…")
-    access_token = get_access_token("google")
-    logger.debug("Access token received.")
-    creds = Credentials(token=access_token)
-    logger.debug("Credentials object created.")
-    return creds
-
-
-def get_sheets_service(credentials: Optional[Credentials] = None) -> 'Resource':
-    """
-    Initializes and returns the Google Sheets API service.
-
-    If no credentials are provided, this function will automatically fetch a
-    Google access token from Lumera and construct the appropriate
-    ``google.oauth2.credentials.Credentials`` instance.
-    """
-    if credentials is None:
-        logger.info("No credentials provided; fetching Google token…")
-        credentials = get_google_credentials()
-    logger.info("Google Sheets API service being initialized…")
-    return build('sheets', 'v4', credentials=credentials)
-
-
-def get_drive_service(credentials: Optional[Credentials] = None) -> 'Resource':
-    """
-    Initializes and returns the Google Drive API service.
-
-    If no credentials are provided, this function will automatically fetch a
-    Google access token from Lumera and construct the appropriate
-    ``google.oauth2.credentials.Credentials`` instance.
-    """
-    if credentials is None:
-        logger.info("No credentials provided; fetching Google token…")
-        credentials = get_google_credentials()
-    logger.info("Google Drive API service being initialized…")
-    return build('drive', 'v3', credentials=credentials)
-
-
-# =====================================================================================
-# Google Sheets & Drive Utility Functions
-# =====================================================================================
-
-
-def get_spreadsheet_and_sheet_id(
-    service: 'Resource', spreadsheet_url: str, tab_name: str
-) -> Tuple[Optional[str], Optional[int]]:
-    """
-    Given a Google Sheets URL and a tab (sheet) name, returns a tuple:
-    (spreadsheet_id, sheet_id)
-    """
-    spreadsheet_id = _extract_spreadsheet_id(spreadsheet_url)
-    if not spreadsheet_id:
-        return None, None
-
-    sheet_id = _get_sheet_id_from_name(service, spreadsheet_id, tab_name)
-    return spreadsheet_id, sheet_id
-
-
-def _extract_spreadsheet_id(spreadsheet_url: str) -> Optional[str]:
-    """Extracts the spreadsheet ID from a Google Sheets URL."""
-    logger.debug(f"Extracting spreadsheet ID from URL: {spreadsheet_url}")
-    pattern = r"/d/([a-zA-Z0-9-_]+)"
-    match = re.search(pattern, spreadsheet_url)
-    if match:
-        spreadsheet_id = match.group(1)
-        logger.debug(f"Spreadsheet ID extracted: {spreadsheet_id}")
-        return spreadsheet_id
-    logger.warning("Could not extract Spreadsheet ID.")
-    return None
-
-
-def _get_sheet_id_from_name(
-    service: 'Resource', spreadsheet_id: str, tab_name: str
-) -> Optional[int]:
-    """Uses the Google Sheets API to fetch the sheet ID corresponding to 'tab_name'."""
-    logger.debug(f"Requesting sheet metadata for spreadsheet ID: {spreadsheet_id}")
-    response = (
-        service.spreadsheets()
-        .get(spreadsheetId=spreadsheet_id, fields="sheets.properties")
-        .execute()
-    )
-    logger.debug("Metadata received. Searching for tab…")
-
-    for sheet in response.get("sheets", []):
-        properties = sheet.get("properties", {})
-        if properties.get("title") == tab_name:
-            sheet_id = properties.get("sheetId")
-            logger.debug(f"Match found for tab '{tab_name}'. Sheet ID is {sheet_id}")
-            return sheet_id
-    logger.warning(f"No sheet found with tab name '{tab_name}'.")
-    return None
-
-
-def sheet_name_from_gid(service: 'Resource', spreadsheet_id: str, gid: int) -> Optional[str]:
-    """Resolve a sheet's human-readable name (title) from its gid."""
-    logger.debug(f"Resolving sheet name from gid={gid} …")
-    meta = (
-        service.spreadsheets()
-        .get(
-            spreadsheetId=spreadsheet_id,
-            includeGridData=False,
-            fields="sheets(properties(sheetId,title))",
-        )
-        .execute()
-    )
-
-    for sheet in meta.get("sheets", []):
-        props = sheet.get("properties", {})
-        if props.get("sheetId") == gid:
-            title = props["title"]
-            logger.debug(f"Sheet gid={gid} corresponds to sheet name='{title}'.")
-            return title
-    logger.warning(f"No sheet found with gid={gid}")
-    return None
-
-
-def read_cell(service: 'Resource', spreadsheet_id: str, range_a1: str) -> Optional[str]:
-    """Fetch a single cell value (as string); returns None if empty."""
-    logger.debug(f"Reading cell '{range_a1}' …")
-    resp = (
-        service.spreadsheets()
-        .values()
-        .get(spreadsheetId=spreadsheet_id, range=range_a1, majorDimension="ROWS")
-        .execute()
-    )
-
-    values = resp.get("values", [])
-    return values[0][0] if values and values[0] else None
-
-
-# NOTE: The function performs I/O side-effects and does not return a value.
-def download_file_direct(drive_service: 'Resource', file_id: str, dest_path: str) -> None:
-    """
-    Downloads a file directly from Google Drive using files().get_media
-    without any format conversion.
-    """
-    logger.info(f"Initiating direct download for file ID: {file_id}")
-
-    request = drive_service.files().get_media(fileId=file_id)
-    fh = io.BytesIO()
-    downloader = MediaIoBaseDownload(fh, request)
-
-    done = False
-    while not done:
-        status, done = downloader.next_chunk()
-        if status:
-            logger.debug(f"Download progress: {int(status.progress() * 100)}%")
-
-    with open(dest_path, "wb") as f:
-        f.write(fh.getvalue())
-    logger.info(f"File saved to: {dest_path}")
-
-
-def upload_excel_as_google_sheet(
-    drive_service: 'Resource', local_path: str, desired_name: str
-) -> Tuple[Optional[str], Optional[str]]:
-    """
-    Uploads a local XLSX file to Google Drive, converting it to Google Sheets format.
-    Returns the file ID and web link.
-    """
-    logger.info(f"Preparing to upload '{local_path}' as Google Sheet named '{desired_name}'")
-
-    if not os.path.isfile(local_path):
-        logger.error(f"Local file not found at '{local_path}'. Aborting.")
-        return None, None
-
-    media = MediaFileUpload(local_path, mimetype=MIME_EXCEL, resumable=True)
-    file_metadata = {"name": desired_name, "mimeType": MIME_GOOGLE_SHEET}
-
-    logger.info("Initiating Google Drive upload & conversion…")
-    request = drive_service.files().create(
-        body=file_metadata, media_body=media, fields="id, webViewLink"
-    )
-
-    response = None
-    while response is None:
-        status, response = request.next_chunk()
-        if status:
-            logger.debug(f"Upload progress: {int(status.progress() * 100)}%")
-
-    file_id = response.get("id")
-    web_view_link = response.get("webViewLink")
-    logger.info(f"Upload completed. File ID: {file_id}")
-    return file_id, web_view_link
-
-
-# Remove rows from a sheet.  All parameters are 1-based (both *start_row* and
-# *end_row* are inclusive) mirroring the UI behaviour in Google Sheets.
-def delete_rows_api_call(
-    service: 'Resource',
-    spreadsheet_id: str,
-    sheet_gid: int,
-    start_row: int,
-    end_row: int,
-) -> None:
-    """Executes the API call to delete rows."""
-    logger.info(f"Deleting rows {start_row}-{end_row} (1-based inclusive)…")
-
-    body = {
-        "requests": [
-            {
-                "deleteDimension": {
-                    "range": {
-                        "sheetId": sheet_gid,
-                        "dimension": "ROWS",
-                        "startIndex": start_row - 1,  # 0-based
-                        "endIndex": end_row,  # end-exclusive
-                    }
-                }
-            }
-        ]
-    }
-    service.spreadsheets().batchUpdate(spreadsheetId=spreadsheet_id, body=body).execute()
-    logger.info("Rows deleted.")