arcade-google-slides 0.1.0__py3-none-any.whl

arcade_google_slides/__init__.py

@@ -0,0 +1,17 @@
+from arcade_google_slides.tools import (
+    comment_on_presentation,
+    create_presentation,
+    create_slide,
+    get_presentation_as_markdown,
+    list_presentation_comments,
+    search_presentations,
+)
+
+__all__ = [
+    "create_presentation",
+    "create_slide",
+    "get_presentation_as_markdown",
+    "search_presentations",
+    "comment_on_presentation",
+    "list_presentation_comments",
+]

arcade_google_slides/converters.py

@@ -0,0 +1,329 @@
+"""
+Modular converter class for converting Google Slides presentations to Markdown.
+This converter strictly follows the TypedDict structure definitions.
+"""
+
+import logging
+
+from arcade_google_slides.types import (
+    Bullet,
+    Page,
+    PageElement,
+    ParagraphMarker,
+    Presentation,
+    Shape,
+    TextContent,
+    TextElement,
+    TextRun,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class BulletConverter:
+    """Converts bullet elements to markdown."""
+
+    def convert(self, bullet: Bullet) -> str:
+        """
+        Convert a bullet to markdown representation.
+
+        Args:
+            bullet: Bullet TypedDict with glyph and nestingLevel
+
+        Returns:
+            Markdown string with appropriate indentation and markdown bullet syntax
+        """
+        nesting_level = bullet.get("nestingLevel", 0)
+        indent = "  " * nesting_level
+        return f"{indent}* "
+
+
+class ParagraphMarkerConverter:
+    """Converts paragraph markers to markdown."""
+
+    def __init__(self) -> None:
+        self.bullet_converter = BulletConverter()
+
+    def convert(self, paragraph_marker: ParagraphMarker) -> str:
+        """
+        Convert a paragraph marker to markdown.
+
+        Args:
+            paragraph_marker: ParagraphMarker TypedDict
+
+        Returns:
+            Markdown string representation
+        """
+        if "bullet" in paragraph_marker:
+            return self.bullet_converter.convert(paragraph_marker["bullet"])
+        return ""
+
+
+class TextRunConverter:
+    """Converts text runs to markdown with styling support."""
+
+    def convert(self, text_run: TextRun) -> str:
+        """
+        Convert a text run to markdown with styling.
+
+        Args:
+            text_run: TextRun TypedDict with content and optional style
+
+        Returns:
+            The text content with markdown formatting applied
+        """
+        content = text_run.get("content", "")
+
+        style = text_run.get("style")
+        if not style:
+            return content
+
+        # Extract leading and trailing spaces to apply formatting correctly
+        # Markdown formatting must be adjacent to text, not spaces
+        leading_spaces = len(content) - len(content.lstrip())
+        trailing_spaces = len(content) - len(content.rstrip())
+
+        # Get the spaces
+        prefix = content[:leading_spaces] if leading_spaces > 0 else ""
+        suffix = content[-trailing_spaces:] if trailing_spaces > 0 else ""
+
+        trimmed_content = content.strip()
+
+        if not trimmed_content:
+            return content
+
+        # Apply text formatting to the trimmed content
+        # Note: Order matters for proper markdown rendering
+
+        if style.get("strikethrough", False):
+            trimmed_content = f"~~{trimmed_content}~~"
+
+        is_bold = style.get("bold", False)
+        is_italic = style.get("italic", False)
+
+        if is_bold and is_italic:
+            # Both bold and italic: ***text***
+            trimmed_content = f"***{trimmed_content}***"
+        elif is_bold:
+            # Bold only: **text**
+            trimmed_content = f"**{trimmed_content}**"
+        elif is_italic:
+            # Italic only: *text*
+            trimmed_content = f"*{trimmed_content}*"
+
+        # Note: This may not render in all markdown viewers
+        if style.get("underline", False):
+            trimmed_content = f"<u>{trimmed_content}</u>"
+
+        link = style.get("link")
+        if link:
+            url = link.get("url", "")
+            if url:
+                trimmed_content = f"[{trimmed_content}]({url})"
+
+        return prefix + trimmed_content + suffix
+
+
+class TextElementConverter:
+    """Converts text elements to markdown."""
+
+    def __init__(self) -> None:
+        self.paragraph_marker_converter = ParagraphMarkerConverter()
+        self.text_run_converter = TextRunConverter()
+
+    def convert(self, text_element: TextElement) -> str:
+        """
+        Convert a text element to markdown.
+
+        Args:
+            text_element: Either TextElementWithParagraphMarker or TextElementWithTextRun
+
+        Returns:
+            Markdown string representation
+        """
+        if "paragraphMarker" in text_element:
+            return self.paragraph_marker_converter.convert(text_element["paragraphMarker"])  # type: ignore[typeddict-item]
+
+        elif "textRun" in text_element:
+            return self.text_run_converter.convert(text_element["textRun"])
+
+        return ""
+
+
+class TextContentConverter:
+    """Converts text content to markdown."""
+
+    def __init__(self) -> None:
+        self.text_element_converter = TextElementConverter()
+
+    def convert(self, text_content: TextContent) -> str:
+        """
+        Convert text content to markdown.
+
+        Args:
+            text_content: TextContent TypedDict with textElements list
+
+        Returns:
+            Markdown string representation
+        """
+        markdown_parts = []
+
+        text_elements = text_content.get("textElements", [])
+
+        current_line = ""
+        for element in text_elements:
+            converted = self.text_element_converter.convert(element)
+
+            # If it's a bullet marker, start a new line if needed
+            if "paragraphMarker" in element and "bullet" in element["paragraphMarker"]:  # type: ignore[typeddict-item]
+                if current_line:
+                    markdown_parts.append(current_line)
+                current_line = converted
+            else:
+                current_line += converted
+
+                # Check if the text run ends with a newline
+                if "textRun" in element:
+                    content = element["textRun"].get("content", "")  # type: ignore[typeddict-item]
+                    if content.endswith("\n"):
+                        markdown_parts.append(current_line.rstrip("\n"))
+                        current_line = ""
+
+        # Add any remaining text
+        if current_line:
+            markdown_parts.append(current_line)
+
+        return "\n".join(markdown_parts)
+
+
+class ShapeConverter:
+    """Converts shapes to markdown."""
+
+    def __init__(self) -> None:
+        self.text_content_converter = TextContentConverter()
+
+    def convert(self, shape: Shape) -> str:
+        """
+        Convert a shape to markdown.
+
+        Args:
+            shape: Shape TypedDict with shapeType and text
+
+        Returns:
+            Markdown string representation
+        """
+        markdown = ""
+
+        if "text" in shape:
+            text_markdown = self.text_content_converter.convert(shape["text"])
+            if text_markdown:
+                markdown += text_markdown
+                if not text_markdown.endswith("\n"):
+                    markdown += "\n"
+
+        return markdown
+
+
+class PageElementConverter:
+    """Converts page elements to markdown."""
+
+    def __init__(self) -> None:
+        self.shape_converter = ShapeConverter()
+
+    def convert(self, page_element: PageElement) -> str:
+        """
+        Convert a page element to markdown.
+
+        Args:
+            page_element: PageElement TypedDict with objectId and shape
+
+        Returns:
+            Markdown string representation
+        """
+        if "shape" in page_element:
+            return self.shape_converter.convert(page_element["shape"])
+        return ""
+
+
+class PageConverter:
+    """Converts pages (slides) to markdown."""
+
+    def __init__(self) -> None:
+        self.page_element_converter = PageElementConverter()
+
+    def convert(self, page: Page, page_number: int) -> str:
+        """
+        Convert a page (slide) to markdown.
+
+        Args:
+            page: Page TypedDict with objectId and pageElements
+            page_number: The page/slide number (1-indexed)
+
+        Returns:
+            Markdown string representation
+        """
+        is_hidden = page.get("slideProperties", {}).get("isSkipped", False)
+        is_hidden_str = " (hidden)" if is_hidden else ""
+        markdown = f"## Slide {page_number}{is_hidden_str}\n\n"
+
+        slide_id = page.get("objectId", "")
+        if slide_id:
+            markdown += f"**Slide ID:** {slide_id}\n\n"
+
+        # Process all page elements
+        page_elements = page.get("pageElements", [])
+        for element in page_elements:
+            element_markdown = self.page_element_converter.convert(element)
+            if element_markdown:
+                markdown += element_markdown
+                if not element_markdown.endswith("\n\n"):
+                    markdown += "\n"
+
+        return markdown
+
+
+class PresentationMarkdownConverter:
+    """
+    Main converter class for converting Google Slides presentations to markdown.
+    This converter strictly follows the TypedDict structure definitions.
+    """
+
+    def __init__(self) -> None:
+        self.page_converter = PageConverter()
+
+    def convert(self, presentation: Presentation) -> str:
+        """
+        Convert a Google Slides presentation to markdown format.
+
+        Args:
+            presentation: Presentation TypedDict with presentationId, title, and slides
+
+        Returns:
+            A markdown string representation of the presentation
+        """
+        if not presentation:
+            return ""
+
+        # Extract metadata
+        title = presentation.get("title", "Untitled Presentation")
+        presentation_id = presentation.get("presentationId", "")
+        slides = presentation.get("slides", [])
+
+        # Build markdown
+        markdown = f"# {title}\n\n"
+
+        if presentation_id:
+            markdown += f"**Presentation ID:** {presentation_id}\n\n"
+
+        if slides:
+            markdown += "---\n\n"
+
+            for i, slide in enumerate(slides, 1):
+                slide_markdown = self.page_converter.convert(slide, i)
+                markdown += slide_markdown
+
+                # Adds separator between slides
+                if i < len(slides):
+                    markdown += "\n---\n\n"
+
+        return markdown.strip()

arcade_google_slides/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_slides.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_slides/enum.py

@@ -0,0 +1,165 @@
+from enum import Enum
+
+
+class PredefinedLayout(str, Enum):
+    """Partial implementation of the REST Resource PredefinedLayout.
+
+    Reference: https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations/request#PredefinedLayout
+    """
+
+    BLANK = "BLANK"  # Blank layout, with no placeholders.
+    CAPTION_ONLY = "CAPTION_ONLY"  # Layout with a caption at the bottom.
+    TITLE = "TITLE"  # Layout with a title and a subtitle.
+    TITLE_AND_BODY = "TITLE_AND_BODY"  # Layout with a title and body.
+    TITLE_AND_TWO_COLUMNS = "TITLE_AND_TWO_COLUMNS"  # Layout with a title and two columns.
+    TITLE_ONLY = "TITLE_ONLY"  # Layout with only a title.
+    SECTION_HEADER = "SECTION_HEADER"  # Layout with a section title.
+    SECTION_TITLE_AND_DESCRIPTION = "SECTION_TITLE_AND_DESCRIPTION"  # Layout with a title and subtitle on one side and description on the other.  # noqa: E501
+    ONE_COLUMN_TEXT = (
+        "ONE_COLUMN_TEXT"  # Layout with one title and one body, arranged in a single column.
+    )
+    MAIN_POINT = "MAIN_POINT"  # Layout with a main point.
+    BIG_NUMBER = "BIG_NUMBER"  # Layout with a big number heading.
+
+
+class ShapeType(Enum):
+    """
+    The type of shape. For now, only TEXT_BOX is supported.
+
+    Reference: https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations.pages/shapes#type
+    """
+
+    TEXT_BOX = "TEXT_BOX"
+    # TODO: Support rectangle or table cell?
+
+
+class PlaceholderType(str, Enum):
+    """Partial implementation of the REST Resource 'Type'.
+
+    The type of placeholder shape.
+
+    Reference: https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations.pages/other#Page.Type_3
+    """
+
+    TITLE = "TITLE"
+    BODY = "BODY"
+
+
+# --------------------------------------------------------- #
+# Drive API Enums
+# --------------------------------------------------------- #
+
+
+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_slides/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_slides/templates.py

@@ -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_slides/tools/__init__.py

@@ -0,0 +1,18 @@
+from arcade_google_slides.tools.comment import (
+    comment_on_presentation,
+    list_presentation_comments,
+)
+from arcade_google_slides.tools.create import create_presentation, create_slide
+from arcade_google_slides.tools.get import get_presentation_as_markdown
+from arcade_google_slides.tools.search import (
+    search_presentations,
+)
+
+__all__ = [
+    "create_presentation",
+    "create_slide",
+    "get_presentation_as_markdown",
+    "search_presentations",
+    "comment_on_presentation",
+    "list_presentation_comments",
+]