PyPI - arcade-google-docs - Versions diffs - 2.0.0__py3-none-any.whl - Mend

arcade-google-docs 2.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

arcade_google_docs/__init__.py +17 -0
arcade_google_docs/decorators.py +24 -0
arcade_google_docs/doc_to_html.py +99 -0
arcade_google_docs/doc_to_markdown.py +64 -0
arcade_google_docs/enum.py +116 -0
arcade_google_docs/file_picker.py +49 -0
arcade_google_docs/templates.py +5 -0
arcade_google_docs/tools/__init__.py +19 -0
arcade_google_docs/tools/create.py +82 -0
arcade_google_docs/tools/get.py +35 -0
arcade_google_docs/tools/search.py +219 -0
arcade_google_docs/tools/update.py +60 -0
arcade_google_docs/utils.py +119 -0
arcade_google_docs-2.0.0.dist-info/METADATA +23 -0
arcade_google_docs-2.0.0.dist-info/RECORD +16 -0
arcade_google_docs-2.0.0.dist-info/WHEEL +4 -0

arcade_google_docs/__init__.py ADDED Viewed

@@ -0,0 +1,17 @@
+from arcade_google_docs.tools import (
+    create_blank_document,
+    create_document_from_text,
+    get_document_by_id,
+    insert_text_at_end_of_document,
+    search_and_retrieve_documents,
+    search_documents,
+)
+__all__ = [
+    "create_blank_document",
+    "create_document_from_text",
+    "get_document_by_id",
+    "insert_text_at_end_of_document",
+    "search_and_retrieve_documents",
+    "search_documents",
+]

arcade_google_docs/decorators.py ADDED Viewed

@@ -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_docs.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_docs/doc_to_html.py ADDED Viewed

@@ -0,0 +1,99 @@
+def convert_document_to_html(document: dict) -> str:
+    html = (
+        "<html><head>"
+        f"<title>{document['title']}</title>"
+        f'<meta name="documentId" content="{document["documentId"]}">'
+        "</head><body>"
+    )
+    for element in document["body"]["content"]:
+        html += convert_structural_element(element)
+    html += "</body></html>"
+    return html
+def convert_structural_element(element: dict, wrap_paragraphs: bool = True) -> str:
+    if "sectionBreak" in element or "tableOfContents" in element:
+        return ""
+    elif "paragraph" in element:
+        paragraph_content = ""
+        prepend, append = get_paragraph_style_tags(
+            style=element["paragraph"]["paragraphStyle"],
+            wrap_paragraphs=wrap_paragraphs,
+        )
+        for item in element["paragraph"]["elements"]:
+            if "textRun" not in item:
+                continue
+            paragraph_content += extract_paragraph_content(item["textRun"])
+        if not paragraph_content:
+            return ""
+        return f"{prepend}{paragraph_content.strip()}{append}"
+    elif "table" in element:
+        table = [
+            [
+                "".join([
+                    convert_structural_element(element=cell_element, wrap_paragraphs=False)
+                    for cell_element in cell["content"]
+                ])
+                for cell in row["tableCells"]
+            ]
+            for row in element["table"]["tableRows"]
+        ]
+        return table_list_to_html(table)
+    else:
+        raise ValueError(f"Unknown document body element type: {element}")
+def extract_paragraph_content(text_run: dict) -> str:
+    content = text_run["content"]
+    style = text_run["textStyle"]
+    return apply_text_style(content, style)
+def apply_text_style(content: str, style: dict) -> str:
+    content = content.rstrip("\n")
+    content = content.replace("\n", "<br>")
+    italic = style.get("italic", False)
+    bold = style.get("bold", False)
+    if italic:
+        content = f"<i>{content}</i>"
+    if bold:
+        content = f"<b>{content}</b>"
+    return content
+def get_paragraph_style_tags(style: dict, wrap_paragraphs: bool = True) -> tuple[str, str]:
+    named_style = style["namedStyleType"]
+    if named_style == "NORMAL_TEXT":
+        return ("<p>", "</p>") if wrap_paragraphs else ("", "")
+    elif named_style == "TITLE":
+        return "<h1>", "</h1>"
+    elif named_style == "SUBTITLE":
+        return "<h2>", "</h2>"
+    elif named_style.startswith("HEADING_"):
+        try:
+            heading_level = int(named_style.split("_")[1])
+        except ValueError:
+            return ("<p>", "</p>") if wrap_paragraphs else ("", "")
+        else:
+            return f"<h{heading_level}>", f"</h{heading_level}>"
+    return ("<p>", "</p>") if wrap_paragraphs else ("", "")
+def table_list_to_html(table: list[list[str]]) -> str:
+    html = "<table>"
+    for row in table:
+        html += "<tr>"
+        for cell in row:
+            if cell.endswith("<br>"):
+                cell = cell[:-4]
+            html += f"<td>{cell}</td>"
+        html += "</tr>"
+    html += "</table>"
+    return html

arcade_google_docs/doc_to_markdown.py ADDED Viewed

@@ -0,0 +1,64 @@
+import arcade_google_docs.doc_to_html as doc_to_html
+def convert_document_to_markdown(document: dict) -> str:
+    md = f"---\ntitle: {document['title']}\ndocumentId: {document['documentId']}\n---\n"
+    for element in document["body"]["content"]:
+        md += convert_structural_element(element)
+    return md
+def convert_structural_element(element: dict) -> str:
+    if "sectionBreak" in element or "tableOfContents" in element:
+        return ""
+    elif "paragraph" in element:
+        md = ""
+        prepend = get_paragraph_style_prepend_str(element["paragraph"]["paragraphStyle"])
+        for item in element["paragraph"]["elements"]:
+            if "textRun" not in item:
+                continue
+            content = extract_paragraph_content(item["textRun"])
+            md += f"{prepend}{content}"
+        return md
+    elif "table" in element:
+        return doc_to_html.convert_structural_element(element)
+    else:
+        raise ValueError(f"Unknown document body element type: {element}")
+def extract_paragraph_content(text_run: dict) -> str:
+    content = text_run["content"]
+    style = text_run["textStyle"]
+    return apply_text_style(content, style)
+def apply_text_style(content: str, style: dict) -> str:
+    append = "\n" if content.endswith("\n") else ""
+    content = content.rstrip("\n")
+    italic = style.get("italic", False)
+    bold = style.get("bold", False)
+    if italic:
+        content = f"_{content}_"
+    if bold:
+        content = f"**{content}**"
+    return f"{content}{append}"
+def get_paragraph_style_prepend_str(style: dict) -> str:
+    named_style = style["namedStyleType"]
+    if named_style == "NORMAL_TEXT":
+        return ""
+    elif named_style == "TITLE":
+        return "# "
+    elif named_style == "SUBTITLE":
+        return "## "
+    elif named_style.startswith("HEADING_"):
+        try:
+            heading_level = int(named_style.split("_")[1])
+            return f"{'#' * heading_level} "
+        except ValueError:
+            return ""
+    return ""

arcade_google_docs/enum.py ADDED Viewed

@@ -0,0 +1,116 @@
+from enum import Enum
+class Corpora(str, Enum):
+    """
+    Bodies of items (files/documents) to which the query applies.
+    Prefer 'user' or 'drive' to 'allDrives' for efficiency.
+    By default, corpora is set to 'user'.
+    """
+    USER = "user"
+    DOMAIN = "domain"
+    DRIVE = "drive"
+    ALL_DRIVES = "allDrives"
+class DocumentFormat(str, Enum):
+    MARKDOWN = "markdown"
+    HTML = "html"
+    GOOGLE_API_JSON = "google_api_json"
+class OrderBy(str, Enum):
+    """
+    Sort keys for ordering files in Google Drive.
+    Each key has both ascending and descending options.
+    """
+    CREATED_TIME = (
+        # When the file was created (ascending)
+        "createdTime"
+    )
+    CREATED_TIME_DESC = (
+        # When the file was created (descending)
+        "createdTime desc"
+    )
+    FOLDER = (
+        # The folder ID, sorted using alphabetical ordering (ascending)
+        "folder"
+    )
+    FOLDER_DESC = (
+        # The folder ID, sorted using alphabetical ordering (descending)
+        "folder desc"
+    )
+    MODIFIED_BY_ME_TIME = (
+        # The last time the file was modified by the user (ascending)
+        "modifiedByMeTime"
+    )
+    MODIFIED_BY_ME_TIME_DESC = (
+        # The last time the file was modified by the user (descending)
+        "modifiedByMeTime desc"
+    )
+    MODIFIED_TIME = (
+        # The last time the file was modified by anyone (ascending)
+        "modifiedTime"
+    )
+    MODIFIED_TIME_DESC = (
+        # The last time the file was modified by anyone (descending)
+        "modifiedTime desc"
+    )
+    NAME = (
+        # The name of the file, sorted using alphabetical ordering (e.g., 1, 12, 2, 22) (ascending)
+        "name"
+    )
+    NAME_DESC = (
+        # The name of the file, sorted using alphabetical ordering (e.g., 1, 12, 2, 22) (descending)
+        "name desc"
+    )
+    NAME_NATURAL = (
+        # The name of the file, sorted using natural sort ordering (e.g., 1, 2, 12, 22) (ascending)
+        "name_natural"
+    )
+    NAME_NATURAL_DESC = (
+        # The name of the file, sorted using natural sort ordering (e.g., 1, 2, 12, 22) (descending)
+        "name_natural desc"
+    )
+    QUOTA_BYTES_USED = (
+        # The number of storage quota bytes used by the file (ascending)
+        "quotaBytesUsed"
+    )
+    QUOTA_BYTES_USED_DESC = (
+        # The number of storage quota bytes used by the file (descending)
+        "quotaBytesUsed desc"
+    )
+    RECENCY = (
+        # The most recent timestamp from the file's date-time fields (ascending)
+        "recency"
+    )
+    RECENCY_DESC = (
+        # The most recent timestamp from the file's date-time fields (descending)
+        "recency desc"
+    )
+    SHARED_WITH_ME_TIME = (
+        # When the file was shared with the user, if applicable (ascending)
+        "sharedWithMeTime"
+    )
+    SHARED_WITH_ME_TIME_DESC = (
+        # When the file was shared with the user, if applicable (descending)
+        "sharedWithMeTime desc"
+    )
+    STARRED = (
+        # Whether the user has starred the file (ascending)
+        "starred"
+    )
+    STARRED_DESC = (
+        # Whether the user has starred the file (descending)
+        "starred desc"
+    )
+    VIEWED_BY_ME_TIME = (
+        # The last time the file was viewed by the user (ascending)
+        "viewedByMeTime"
+    )
+    VIEWED_BY_ME_TIME_DESC = (
+        # The last time the file was viewed by the user (descending)
+        "viewedByMeTime desc"
+    )

arcade_google_docs/file_picker.py ADDED Viewed

@@ -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_docs/templates.py ADDED Viewed

@@ -0,0 +1,5 @@
+optional_file_picker_instructions_template = (
+    "Ensure the user knows that they have the option to select and grant access permissions to "
+    "additional documents via the Google Drive File Picker. "
+    "The user can pick additional documents via the following link: {url}"
+)

arcade_google_docs/tools/__init__.py ADDED Viewed

@@ -0,0 +1,19 @@
+from arcade_google_docs.tools.create import (
+    create_blank_document,
+    create_document_from_text,
+)
+from arcade_google_docs.tools.get import get_document_by_id
+from arcade_google_docs.tools.search import (
+    search_and_retrieve_documents,
+    search_documents,
+)
+from arcade_google_docs.tools.update import insert_text_at_end_of_document
+__all__ = [
+    "create_blank_document",
+    "create_document_from_text",
+    "get_document_by_id",
+    "insert_text_at_end_of_document",
+    "search_and_retrieve_documents",
+    "search_documents",
+]

arcade_google_docs/tools/create.py ADDED Viewed

@@ -0,0 +1,82 @@
+from typing import Annotated
+from arcade_tdk import ToolContext, tool
+from arcade_tdk.auth import Google
+from arcade_google_docs.utils import build_docs_service
+# Uses https://developers.google.com/docs/api/reference/rest/v1/documents/create
+# Example `arcade chat` query: `create blank document with title "My New Document"`
+@tool(
+    requires_auth=Google(
+        scopes=[
+            "https://www.googleapis.com/auth/drive.file",
+        ],
+    )
+)
+async def create_blank_document(
+    context: ToolContext, title: Annotated[str, "The title of the blank document to create"]
+) -> Annotated[dict, "The created document's title, documentId, and documentUrl in a dictionary"]:
+    """
+    Create a blank Google Docs document with the specified title.
+    """
+    service = build_docs_service(context.get_auth_token_or_empty())
+    body = {"title": title}
+    # Execute the documents().create() method. Returns a Document object https://developers.google.com/docs/api/reference/rest/v1/documents#Document
+    request = service.documents().create(body=body)
+    response = request.execute()
+    return {
+        "title": response["title"],
+        "documentId": response["documentId"],
+        "documentUrl": f"https://docs.google.com/document/d/{response['documentId']}/edit",
+    }
+# Uses https://developers.google.com/docs/api/reference/rest/v1/documents/batchUpdate
+# Example `arcade chat` query:
+#   `create document with title "My New Document" and text content "Hello, World!"`
+@tool(
+    requires_auth=Google(
+        scopes=[
+            "https://www.googleapis.com/auth/drive.file",
+        ],
+    )
+)
+async def create_document_from_text(
+    context: ToolContext,
+    title: Annotated[str, "The title of the document to create"],
+    text_content: Annotated[str, "The text content to insert into the document"],
+) -> Annotated[dict, "The created document's title, documentId, and documentUrl in a dictionary"]:
+    """
+    Create a Google Docs document with the specified title and text content.
+    """
+    # First, create a blank document
+    document = await create_blank_document(context, title)
+    service = build_docs_service(context.get_auth_token_or_empty())
+    requests = [
+        {
+            "insertText": {
+                "location": {
+                    "index": 1,
+                },
+                "text": text_content,
+            }
+        }
+    ]
+    # Execute the batchUpdate method to insert text
+    service.documents().batchUpdate(
+        documentId=document["documentId"], body={"requests": requests}
+    ).execute()
+    return {
+        "title": document["title"],
+        "documentId": document["documentId"],
+        "documentUrl": f"https://docs.google.com/document/d/{document['documentId']}/edit",
+    }

arcade_google_docs/tools/get.py ADDED Viewed

@@ -0,0 +1,35 @@
+from typing import Annotated
+from arcade_tdk import ToolContext, ToolMetadataKey, tool
+from arcade_tdk.auth import Google
+from arcade_google_docs.decorators import with_filepicker_fallback
+from arcade_google_docs.utils import build_docs_service
+# Uses https://developers.google.com/docs/api/reference/rest/v1/documents/get
+# Example `arcade chat` query: `get document with ID 1234567890`
+# Note: Document IDs are returned in the response of the Google Drive's `list_documents` tool
+@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_document_by_id(
+    context: ToolContext,
+    document_id: Annotated[str, "The ID of the document to retrieve."],
+) -> Annotated[dict, "The document contents as a dictionary"]:
+    """
+    Get the latest version of the specified Google Docs document.
+    """
+    service = build_docs_service(context.get_auth_token_or_empty())
+    # Execute the documents().get() method. Returns a Document object
+    # https://developers.google.com/docs/api/reference/rest/v1/documents#Document
+    request = service.documents().get(documentId=document_id)
+    response = request.execute()
+    return dict(response)

arcade_google_docs/tools/search.py ADDED Viewed

@@ -0,0 +1,219 @@
+from typing import Annotated, Any
+from arcade_tdk import ToolContext, ToolMetadataKey, tool
+from arcade_tdk.auth import Google
+from arcade_google_docs.doc_to_html import convert_document_to_html
+from arcade_google_docs.doc_to_markdown import convert_document_to_markdown
+from arcade_google_docs.enum import DocumentFormat, OrderBy
+from arcade_google_docs.file_picker import generate_google_file_picker_url
+from arcade_google_docs.templates import optional_file_picker_instructions_template
+from arcade_google_docs.tools import get_document_by_id
+from arcade_google_docs.utils import (
+    build_drive_service,
+    build_files_list_params,
+)
+# Implements: https://googleapis.github.io/google-api-python-client/docs/dyn/drive_v3.files.html#list
+# Example `arcade chat` query: `list my 5 most recently modified documents`
+# TODO: Support query with natural language. Currently, the tool expects a fully formed query
+#       string as input with the syntax defined here: https://developers.google.com/drive/api/guides/search-files
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/drive.file"],
+    ),
+    requires_metadata=[ToolMetadataKey.CLIENT_ID, ToolMetadataKey.COORDINATOR_URL],
+)
+async def search_documents(
+    context: ToolContext,
+    document_contains: Annotated[
+        list[str] | None,
+        "Keywords or phrases that must be in the document title or body. Provide a list of "
+        "keywords or phrases if needed.",
+    ] = None,
+    document_not_contains: Annotated[
+        list[str] | None,
+        "Keywords or phrases that must NOT be in the document title or body. Provide a list of "
+        "keywords or phrases if needed.",
+    ] = None,
+    search_only_in_shared_drive_id: Annotated[
+        str | None,
+        "The ID of the shared drive to restrict the search to. If provided, the search will only "
+        "return documents from this drive. Defaults to None, which searches across all drives.",
+    ] = None,
+    include_shared_drives: Annotated[
+        bool,
+        "Whether to include documents from shared drives. Defaults to False (searches only in "
+        "the user's 'My Drive').",
+    ] = False,
+    include_organization_domain_documents: Annotated[
+        bool,
+        "Whether to include documents from the organization's domain. This is applicable to admin "
+        "users who have permissions to view organization-wide documents in a Google Workspace "
+        "account. Defaults to False.",
+    ] = False,
+    order_by: Annotated[
+        list[OrderBy] | None,
+        "Sort order. Defaults to listing the most recently modified documents first",
+    ] = None,
+    limit: Annotated[int, "The number of documents to list"] = 50,
+    pagination_token: Annotated[
+        str | None, "The pagination token to continue a previous request"
+    ] = None,
+) -> Annotated[
+    dict,
+    "A dictionary containing 'documents_count' (number of documents returned) and 'documents' "
+    "(a list of document details including 'kind', 'mimeType', 'id', and 'name' for each document)",
+]:
+    """
+    Searches for documents in the user's Google Drive. Excludes documents that are in the trash.
+    """
+    if order_by is None:
+        order_by = [OrderBy.MODIFIED_TIME_DESC]
+    elif isinstance(order_by, OrderBy):
+        order_by = [order_by]
+    page_size = min(10, limit)
+    files: list[dict[str, Any]] = []
+    service = build_drive_service(context.get_auth_token_or_empty())
+    params = build_files_list_params(
+        mime_type="application/vnd.google-apps.document",
+        document_contains=document_contains,
+        document_not_contains=document_not_contains,
+        page_size=page_size,
+        order_by=order_by,
+        pagination_token=pagination_token,
+        include_shared_drives=include_shared_drives,
+        search_only_in_shared_drive_id=search_only_in_shared_drive_id,
+        include_organization_domain_documents=include_organization_domain_documents,
+    )
+    while len(files) < limit:
+        if pagination_token:
+            params["pageToken"] = pagination_token
+        else:
+            params.pop("pageToken", None)
+        results = service.files().list(**params).execute()
+        batch = results.get("files", [])
+        files.extend(batch[: limit - len(files)])
+        pagination_token = results.get("nextPageToken")
+        if not pagination_token or len(batch) < page_size:
+            break
+    file_picker_response = generate_google_file_picker_url(
+        context,
+    )
+    return {
+        "documents_count": len(files),
+        "documents": files,
+        "file_picker": {
+            "url": file_picker_response["url"],
+            "llm_instructions": optional_file_picker_instructions_template.format(
+                url=file_picker_response["url"]
+            ),
+        },
+    }
+@tool(
+    requires_auth=Google(
+        scopes=["https://www.googleapis.com/auth/drive.file"],
+    ),
+    requires_metadata=[ToolMetadataKey.CLIENT_ID, ToolMetadataKey.COORDINATOR_URL],
+)
+async def search_and_retrieve_documents(
+    context: ToolContext,
+    return_format: Annotated[
+        DocumentFormat,
+        "The format of the document to return. Defaults to Markdown.",
+    ] = DocumentFormat.MARKDOWN,
+    document_contains: Annotated[
+        list[str] | None,
+        "Keywords or phrases that must be in the document title or body. Provide a list of "
+        "keywords or phrases if needed.",
+    ] = None,
+    document_not_contains: Annotated[
+        list[str] | None,
+        "Keywords or phrases that must NOT be in the document title or body. Provide a list of "
+        "keywords or phrases if needed.",
+    ] = None,
+    search_only_in_shared_drive_id: Annotated[
+        str | None,
+        "The ID of the shared drive to restrict the search to. If provided, the search will only "
+        "return documents from this drive. Defaults to None, which searches across all drives.",
+    ] = None,
+    include_shared_drives: Annotated[
+        bool,
+        "Whether to include documents from shared drives. Defaults to False (searches only in "
+        "the user's 'My Drive').",
+    ] = False,
+    include_organization_domain_documents: Annotated[
+        bool,
+        "Whether to include documents from the organization's domain. This is applicable to admin "
+        "users who have permissions to view organization-wide documents in a Google Workspace "
+        "account. Defaults to False.",
+    ] = False,
+    order_by: Annotated[
+        list[OrderBy] | None,
+        "Sort order. Defaults to listing the most recently modified documents first",
+    ] = None,
+    limit: Annotated[int, "The number of documents to list"] = 50,
+    pagination_token: Annotated[
+        str | None, "The pagination token to continue a previous request"
+    ] = None,
+) -> Annotated[
+    dict,
+    "A dictionary containing 'documents_count' (number of documents returned) and 'documents' "
+    "(a list of documents with their content).",
+]:
+    """
+    Searches for documents in the user's Google Drive and returns a list of documents (with text
+    content) matching the search criteria. Excludes documents that are in the trash.
+    Note: use this tool only when the user prompt requires the documents' content. If the user only
+    needs a list of documents, use the `search_documents` tool instead.
+    """
+    response = await search_documents(
+        context=context,
+        document_contains=document_contains,
+        document_not_contains=document_not_contains,
+        search_only_in_shared_drive_id=search_only_in_shared_drive_id,
+        include_shared_drives=include_shared_drives,
+        include_organization_domain_documents=include_organization_domain_documents,
+        order_by=order_by,
+        limit=limit,
+        pagination_token=pagination_token,
+    )
+    documents = []
+    for item in response["documents"]:
+        document = await get_document_by_id(context, document_id=item["id"])
+        if return_format == DocumentFormat.MARKDOWN:
+            document = convert_document_to_markdown(document)
+        elif return_format == DocumentFormat.HTML:
+            document = convert_document_to_html(document)
+        documents.append(document)
+    file_picker_response = generate_google_file_picker_url(
+        context,
+    )
+    return {
+        "documents_count": len(documents),
+        "documents": documents,
+        "file_picker": {
+            "url": file_picker_response["url"],
+            "llm_instructions": optional_file_picker_instructions_template.format(
+                url=file_picker_response["url"]
+            ),
+        },
+    }

arcade_google_docs/tools/update.py ADDED Viewed

@@ -0,0 +1,60 @@
+from typing import Annotated
+from arcade_tdk import ToolContext, ToolMetadataKey, tool
+from arcade_tdk.auth import Google
+from arcade_google_docs.decorators import with_filepicker_fallback
+from arcade_google_docs.tools.get import get_document_by_id
+from arcade_google_docs.utils import build_docs_service
+# Uses https://developers.google.com/docs/api/reference/rest/v1/documents/batchUpdate
+# Example `arcade chat` query: `insert "The END" at the end of document with ID 1234567890`
+@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 insert_text_at_end_of_document(
+    context: ToolContext,
+    document_id: Annotated[str, "The ID of the document to update."],
+    text_content: Annotated[str, "The text content to insert into the document"],
+) -> Annotated[dict, "The response from the batchUpdate API as a dict."]:
+    """
+    Updates an existing Google Docs document using the batchUpdate API endpoint.
+    """
+    document_or_file_picker_response = await get_document_by_id(context, document_id)
+    # If the document was not found, return the file picker response
+    if "body" not in document_or_file_picker_response:
+        return document_or_file_picker_response  # type: ignore[no-any-return]
+    document = document_or_file_picker_response
+    end_index = document["body"]["content"][-1]["endIndex"]
+    service = build_docs_service(context.get_auth_token_or_empty())
+    requests = [
+        {
+            "insertText": {
+                "location": {
+                    "index": int(end_index) - 1,
+                },
+                "text": text_content,
+            }
+        }
+    ]
+    # Execute the documents().batchUpdate() method
+    response = (
+        service.documents()
+        .batchUpdate(documentId=document_id, body={"requests": requests})
+        .execute()
+    )
+    return dict(response)

arcade_google_docs/utils.py ADDED Viewed

@@ -0,0 +1,119 @@
+import logging
+from typing import Any
+from google.oauth2.credentials import Credentials
+from googleapiclient.discovery import Resource, build
+from arcade_google_docs.enum import Corpora, OrderBy
+## Set up basic configuration for logging to the console with DEBUG level and a specific format.
+logging.basicConfig(
+    level=logging.DEBUG,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger(__name__)
+def build_docs_service(auth_token: str | None) -> Resource:  # type: ignore[no-any-unimported]
+    """
+    Build a Drive service object.
+    """
+    auth_token = auth_token or ""
+    return build("docs", "v1", credentials=Credentials(auth_token))
+def build_drive_service(auth_token: str | None) -> Resource:  # type: ignore[no-any-unimported]
+    """
+    Build a Drive service object.
+    """
+    auth_token = auth_token or ""
+    return build("drive", "v3", credentials=Credentials(auth_token))
+def build_files_list_params(
+    mime_type: str,
+    page_size: int,
+    order_by: list[OrderBy],
+    pagination_token: str | None,
+    include_shared_drives: bool,
+    search_only_in_shared_drive_id: str | None,
+    include_organization_domain_documents: bool,
+    document_contains: list[str] | None = None,
+    document_not_contains: list[str] | None = None,
+) -> dict[str, Any]:
+    query = build_files_list_query(
+        mime_type=mime_type,
+        document_contains=document_contains,
+        document_not_contains=document_not_contains,
+    )
+    params = {
+        "q": query,
+        "pageSize": page_size,
+        "orderBy": ",".join([item.value for item in order_by]),
+        "pageToken": pagination_token,
+    }
+    if (
+        include_shared_drives
+        or search_only_in_shared_drive_id
+        or include_organization_domain_documents
+    ):
+        params["includeItemsFromAllDrives"] = "true"
+        params["supportsAllDrives"] = "true"
+    if search_only_in_shared_drive_id:
+        params["driveId"] = search_only_in_shared_drive_id
+        params["corpora"] = Corpora.DRIVE.value
+    if include_organization_domain_documents:
+        params["corpora"] = Corpora.DOMAIN.value
+    params = remove_none_values(params)
+    return params
+def build_files_list_query(
+    mime_type: str,
+    document_contains: list[str] | None = None,
+    document_not_contains: list[str] | None = None,
+) -> str:
+    query = [f"(mimeType = '{mime_type}' and trashed = false)"]
+    if isinstance(document_contains, str):
+        document_contains = [document_contains]
+    if isinstance(document_not_contains, str):
+        document_not_contains = [document_not_contains]
+    if document_contains:
+        for keyword in document_contains:
+            name_contains = keyword.replace("'", "\\'")
+            full_text_contains = keyword.replace("'", "\\'")
+            keyword_query = (
+                f"(name contains '{name_contains}' or fullText contains '{full_text_contains}')"
+            )
+            query.append(keyword_query)
+    if document_not_contains:
+        for keyword in document_not_contains:
+            name_not_contains = keyword.replace("'", "\\'")
+            full_text_not_contains = keyword.replace("'", "\\'")
+            keyword_query = (
+                f"(name not contains '{name_not_contains}' and "
+                f"fullText not contains '{full_text_not_contains}')"
+            )
+            query.append(keyword_query)
+    return " and ".join(query)
+def remove_none_values(params: dict) -> dict:
+    """
+    Remove None values from a dictionary.
+    :param params: The dictionary to clean
+    :return: A new dictionary with None values removed
+    """
+    return {k: v for k, v in params.items() if v is not None}

arcade_google_docs-2.0.0.dist-info/METADATA ADDED Viewed

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: arcade_google_docs
+Version: 2.0.0
+Summary: Arcade.dev LLM tools for Google Docs
+Author-email: Arcade <dev@arcade.dev>
+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.4; 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_docs-2.0.0.dist-info/RECORD ADDED Viewed

@@ -0,0 +1,16 @@
+arcade_google_docs/__init__.py,sha256=WxIJBwkBmVeHfvgQ9E8eZy28SVqSkBlbZPhgFWhVd7o,418
+arcade_google_docs/decorators.py,sha256=5ONZ3vS2lZBmog5c1TcuWjyPDeftBPAJ7vXyLjSPFRk,751
+arcade_google_docs/doc_to_html.py,sha256=6RTpzRSrazNa6AndLZhA20wgVDzZuHUqpu3WAkAsbjQ,3146
+arcade_google_docs/doc_to_markdown.py,sha256=eT-sc6ruxN8nEtUm9mBHFOWXajEBTTXkxsn6XsLHIxo,2020
+arcade_google_docs/enum.py,sha256=vFJWPe1JPG6I9xqdVVvuaEeen4LvvtJxax1sDYeh4UU,3421
+arcade_google_docs/file_picker.py,sha256=kGfUVfH5QVlIW1sL-_gAwPokt7TwVEcPk3Vnk53GKUE,2005
+arcade_google_docs/templates.py,sha256=pxbdMj57eV3-ImW3CixDWscpVKS94Z8nTNyTxDhUfGY,283
+arcade_google_docs/utils.py,sha256=Eku4b1olLcXfQ20liE9m3iPWvy60VA62tQ8TFwRKn94,3722
+arcade_google_docs/tools/__init__.py,sha256=f0d7ZRXCqgODDBkKtNhvHzsqs_GuZ97fe0dpjBcXKq8,548
+arcade_google_docs/tools/create.py,sha256=AuYy8yMGscrxAdLJQX0WiisGHCTufSlaRu_QGMMKQmM,2764
+arcade_google_docs/tools/get.py,sha256=2wi9ZF9s_57mMbIGgsqr53Fr0AJyrYVOQ11x7nAyk8Y,1339
+arcade_google_docs/tools/search.py,sha256=_CaEs1A_qGToNPeuGQ2yN3phGtPD7fFQbW3UqZr_qpg,8617
+arcade_google_docs/tools/update.py,sha256=9SvffQIHnmYiEgyE1VrhXG2aHb0hIfWYPzPLc4nTdKI,2030
+arcade_google_docs-2.0.0.dist-info/METADATA,sha256=9UwyGTqc8_dVJiMRHNCk_n-mNn_PM99WnlpaO2LZSYM,1035
+arcade_google_docs-2.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+arcade_google_docs-2.0.0.dist-info/RECORD,,

arcade_google_docs-2.0.0.dist-info/WHEEL ADDED Viewed

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