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

arcade_google_slides/tools/comment.py

@@ -0,0 +1,99 @@
+from typing import Annotated
+
+from arcade_tdk import ToolContext, tool
+from arcade_tdk.auth import Google
+
+from arcade_google_slides.utils import build_drive_service
+
+
+@tool(
+    requires_auth=Google(
+        scopes=[
+            "https://www.googleapis.com/auth/drive.file",
+        ],
+    )
+)
+async def comment_on_presentation(
+    context: ToolContext,
+    presentation_id: Annotated[str, "The ID of the presentation to comment on"],
+    comment_text: Annotated[str, "The comment to add to the slide"],
+) -> Annotated[dict, "The comment's ID, presentationId, and slideNumber in a dictionary"]:
+    """
+    Comment on a specific slide by its index in a Google Slides presentation.
+    """
+    drive_service = build_drive_service(context.get_auth_token_or_empty())
+
+    # Get the presentation
+    response = (
+        drive_service.comments()
+        .create(
+            fileId=presentation_id,
+            body={
+                "content": comment_text,
+            },
+            fields="id",
+        )
+        .execute()
+    )
+
+    return {
+        "comment_id": response["id"],
+        "presentation_url": f"https://docs.google.com/presentation/d/{presentation_id}",
+    }
+
+
+@tool(
+    requires_auth=Google(
+        scopes=[
+            "https://www.googleapis.com/auth/drive.file",
+        ],
+    )
+)
+async def list_presentation_comments(
+    context: ToolContext,
+    presentation_id: Annotated[str, "The ID of the presentation to list comments for"],
+    include_deleted: Annotated[
+        bool,
+        "Whether to include deleted comments in the results. Defaults to False.",
+    ] = False,
+) -> Annotated[
+    dict,
+    "A dictionary containing the comments",
+]:
+    """
+    List all comments on the specified Google Slides presentation.
+    """
+    drive_service = build_drive_service(context.get_auth_token_or_empty())
+
+    comments: list[dict] = []
+    params: dict = {
+        "fileId": presentation_id,
+        "pageSize": 100,
+        "fields": (
+            "nextPageToken,comments(id,content,createdTime,modifiedTime,deleted,"
+            "author(displayName,emailAddress),replies(id,content,createdTime,modifiedTime,deleted,author(displayName,emailAddress)))"
+        ),
+    }
+    if include_deleted:
+        params["includeDeleted"] = True
+
+    while True:
+        results = drive_service.comments().list(**params).execute()
+        batch = results.get("comments", [])
+        comments.extend(batch)
+        next_page_token = results.get("nextPageToken")
+        if not next_page_token:
+            break
+        params["pageToken"] = next_page_token
+
+    reply_count = 0
+    for comment in comments:
+        reply_count += len(comment.get("replies", []))
+
+    return {
+        "comments_count": len(comments),
+        "replies_count": reply_count,
+        "total_discussion_count": len(comments) + reply_count,
+        "comments": comments,
+        "presentation_url": f"https://docs.google.com/presentation/d/{presentation_id}",
+    }

arcade_google_slides/tools/create.py

@@ -0,0 +1,122 @@
+import uuid
+from typing import Annotated
+
+from arcade_tdk import ToolContext, tool
+from arcade_tdk.auth import Google
+
+from arcade_google_slides.enum import PlaceholderType
+from arcade_google_slides.types import (
+    Page,
+    PredefinedLayout,
+    Presentation,
+    Request,
+)
+from arcade_google_slides.utils import build_slides_service, create_blank_presentation
+
+
+@tool(
+    requires_auth=Google(
+        scopes=[
+            "https://www.googleapis.com/auth/drive.file",
+        ],
+    )
+)
+async def create_presentation(
+    context: ToolContext,
+    title: Annotated[str, "The title of the presentation to create"],
+    subtitle: Annotated[str | None, "The subtitle of the presentation to create"] = None,
+) -> Annotated[dict, "The created presentation's title, presentationId, and presentationUrl"]:
+    """
+    Create a new Google Slides presentation
+    The first slide will be populated with the specified title and subtitle.
+    """
+    service = build_slides_service(context.get_auth_token_or_empty())
+
+    presentation: Presentation = create_blank_presentation(service, title)
+
+    slide: Page = presentation["slides"][0]
+    title_text_box_id = slide["pageElements"][0]["objectId"]
+    subtitle_text_box_id = slide["pageElements"][1]["objectId"]
+
+    requests: list[Request] = [
+        {
+            "insertText": {
+                "objectId": title_text_box_id,
+                "text": title,
+            }
+        },
+        {
+            "insertText": {
+                "objectId": subtitle_text_box_id,
+                "text": subtitle if subtitle else "",
+            }
+        },
+    ]
+
+    service.presentations().batchUpdate(
+        presentationId=presentation["presentationId"], body={"requests": requests}
+    ).execute()
+
+    return {
+        "presentation_title": presentation["title"],
+        "presentation_id": presentation["presentationId"],
+        "presentation_url": f"https://docs.google.com/presentation/d/{presentation['presentationId']}/edit",
+    }
+
+
+@tool(
+    requires_auth=Google(
+        scopes=[
+            "https://www.googleapis.com/auth/drive.file",
+        ],
+    )
+)
+async def create_slide(
+    context: ToolContext,
+    presentation_id: Annotated[str, "The ID of the presentation to create the slide in"],
+    slide_title: Annotated[str, "The title of the slide to create"],
+    slide_body: Annotated[str, "The body (text) of the slide to create"],
+) -> Annotated[dict, "A URL to the created slide"]:
+    """Create a new slide at the end of the specified presentation"""
+    service = build_slides_service(context.get_auth_token_or_empty())
+
+    title_id = str(uuid.uuid4())[:8]
+    body_id = str(uuid.uuid4())[:8]
+
+    create_slide_request: Request = {
+        "createSlide": {
+            "objectId": "",  # NOTE: We can utilize creating custom IDs for easier lookup/edits
+            "slideLayoutReference": {
+                "predefinedLayout": PredefinedLayout.TITLE_AND_BODY,
+            },
+            "placeholderIdMappings": [
+                {
+                    "layoutPlaceholder": {"type": PlaceholderType.TITLE, "index": 0},
+                    "objectId": title_id,
+                },
+                {
+                    "layoutPlaceholder": {"type": PlaceholderType.BODY, "index": 0},
+                    "objectId": body_id,
+                },
+            ],
+        },
+    }
+
+    insert_text_requests: list[Request] = [
+        {"insertText": {"objectId": title_id, "text": slide_title}},
+        {"insertText": {"objectId": body_id, "text": slide_body}},
+    ]
+
+    response = (
+        service.presentations()
+        .batchUpdate(
+            presentationId=presentation_id,
+            body={"requests": [create_slide_request, *insert_text_requests]},
+        )
+        .execute()
+    )
+
+    slide_id = response["replies"][0]["createSlide"]["objectId"]
+    return {
+        "slide_url": f"https://docs.google.com/presentation/d/{presentation_id}/edit?slide=id.{slide_id}"
+    }

arcade_google_slides/tools/get.py

@@ -0,0 +1,33 @@
+from typing import Annotated, cast
+
+from arcade_tdk import ToolContext, ToolMetadataKey, tool
+from arcade_tdk.auth import Google
+
+from arcade_google_slides.decorators import with_filepicker_fallback
+from arcade_google_slides.types import Presentation
+from arcade_google_slides.utils import build_slides_service, convert_presentation_to_markdown
+
+
+@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_presentation_as_markdown(
+    context: ToolContext,
+    presentation_id: Annotated[str, "The ID of the presentation to retrieve."],
+) -> Annotated[str, "The presentation textual content as markdown"]:
+    """
+    Get the specified Google Slides presentation and convert it to markdown.
+
+    Only retrieves the text content of the presentation and formats it as markdown.
+    """
+    service = build_slides_service(context.get_auth_token_or_empty())
+
+    response = service.presentations().get(presentationId=presentation_id).execute()
+
+    return convert_presentation_to_markdown(cast(Presentation, response))

arcade_google_slides/tools/search.py

@@ -0,0 +1,125 @@
+from typing import Annotated, Any
+
+from arcade_tdk import ToolContext, ToolMetadataKey, tool
+from arcade_tdk.auth import Google
+
+from arcade_google_slides.enum import OrderBy
+from arcade_google_slides.file_picker import generate_google_file_picker_url
+from arcade_google_slides.templates import optional_file_picker_instructions_template
+from arcade_google_slides.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 presentations`
+# 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_presentations(
+    context: ToolContext,
+    presentation_contains: Annotated[
+        list[str] | None,
+        "Keywords or phrases that must be in the presentation title or content. Provide a list of "
+        "keywords or phrases if needed.",
+    ] = None,
+    presentation_not_contains: Annotated[
+        list[str] | None,
+        "Keywords or phrases that must NOT be in the presentation title or content. "
+        "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 presentations from this drive. Defaults to None, which searches across all drives.",
+    ] = None,
+    include_shared_drives: Annotated[
+        bool,
+        "Whether to include presentations from shared drives. Defaults to False (searches only in "
+        "the user's 'My Drive').",
+    ] = False,
+    include_organization_domain_presentations: Annotated[
+        bool,
+        "Whether to include presentations from the organization's domain. "
+        "This is applicable to admin users who have permissions to view "
+        "organization-wide presentations in a Google Workspace "
+        "account. Defaults to False.",
+    ] = False,
+    order_by: Annotated[
+        list[OrderBy] | None,
+        "Sort order. Defaults to listing the most recently modified presentations first",
+    ] = None,
+    limit: Annotated[int, "The number of presentations to list"] = 50,
+    pagination_token: Annotated[
+        str | None, "The pagination token to continue a previous request"
+    ] = None,
+) -> Annotated[
+    dict,
+    "A dictionary containing 'presentations_count' (number of presentations returned) "
+    "and 'presentations' (a list of presentation details including 'kind', 'mimeType', "
+    "'id', and 'name' for each presentation)",
+]:
+    """
+    Searches for presentations in the user's Google Drive.
+    Excludes presentations 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.presentation",
+        document_contains=presentation_contains,
+        document_not_contains=presentation_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_presentations,
+    )
+
+    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 {
+        "presentations_count": len(files),
+        "presentations": files,
+        "file_picker": {
+            "url": file_picker_response["url"],
+            "llm_instructions": optional_file_picker_instructions_template.format(
+                url=file_picker_response["url"]
+            ),
+        },
+        "llm_instructions": (
+            "If the results were not satisfactory, then inform the user that "
+            "you can also search across all of their shared drives."
+        ),
+    }

arcade_google_slides/types.py

@@ -0,0 +1,223 @@
+from typing import TypedDict
+
+from arcade_google_slides.enum import PlaceholderType, PredefinedLayout, ShapeType
+
+
+class Bullet(TypedDict):
+    """Partial implementation of the REST Resource Bullet.
+
+    Represents a bullet in a TextElement.
+
+    Reference: https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations.pages/text#Page.Bullet
+    """
+
+    nestingLevel: int  # The nesting level of this paragraph in the list.
+
+
+class ParagraphMarker(TypedDict):
+    """Partial implementation of the REST Resource ParagraphMarker.
+
+    Represents a paragraph marker in a TextElement.
+
+    Reference: https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations.pages/text#Page.ParagraphMarker
+    """
+
+    bullet: Bullet
+
+
+class Link(TypedDict):
+    """Partial implementation of the REST Resource Link.
+
+    Represents a hypertext link.
+
+    Reference: https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations.pages/other#Page.Link
+    """
+
+    url: str
+
+
+class TextStyle(TypedDict):
+    """Partial implementation of the REST Resource TextStyle.
+
+    Represents the styling that can be applied to a TextRun.
+
+    Reference: https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations.pages/text#Page.TextStyle
+    """
+
+    bold: bool
+    italic: bool
+    strikethrough: bool
+    underline: bool
+    link: Link
+
+
+class TextRun(TypedDict):
+    """Partial implementation of the REST Resource TextRun.
+
+    A TextElement kind that represents a run of text that all has the same styling.
+
+    Reference: https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations.pages/text#Page.TextRun
+    """
+
+    content: str  # The text of this run.
+    style: TextStyle
+
+
+class TextElementWithParagraphMarker(TypedDict):
+    """Partial implementation of the REST Resource TextElement.
+
+    TextElement containing a paragraph marker.
+
+    Reference: https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations.pages/text#Page.TextElement
+    """
+
+    paragraphMarker: ParagraphMarker
+
+
+class TextElementWithTextRun(TypedDict):
+    """Partial implementation of the REST Resource TextElement.
+
+    TextElement containing a text run.
+
+    Reference: https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations.pages/text#Page.TextElement
+    """
+
+    textRun: TextRun
+
+
+# https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations.pages/text#Page.TextElement
+TextElement = TextElementWithParagraphMarker | TextElementWithTextRun
+
+
+class TextContent(TypedDict):
+    """Partial implementation of the REST Resource TextContent.
+
+    Reference: https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations.pages/text#Page.TextContent
+    """
+
+    textElements: list[TextElement]
+
+
+class Shape(TypedDict):
+    """Partial implementation of the REST Resource Shape.
+
+
+    Reference: https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations.pages/shapes#Page.Shape
+    """
+
+    shapeType: ShapeType
+    text: TextContent
+
+
+class PageElement(TypedDict):
+    """Partial implementation of the REST Resource PageElement.
+
+    A visual element on a page.
+
+    Reference: https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations.pages#Page.PageElement
+    """
+
+    objectId: str
+    shape: Shape
+
+
+class SlideProperties(TypedDict):
+    """Partial implementation of the REST Resource SlideProperties.
+
+    The properties of Page that are only relevant for pages with pageType SLIDE.
+
+    Reference: https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations.pages#Page.SlideProperties
+    """
+
+    # Whether the slide is skipped (hidden) in the presentation mode. Defaults to false.
+    isSkipped: bool
+
+
+class Page(TypedDict):
+    """Partial implementation of the REST Resource Page.
+
+    A page is a single slide in a presentation.
+
+    Reference: https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations.pages#Page
+    """
+
+    objectId: str
+    pageElements: list[PageElement]
+    slideProperties: SlideProperties
+
+
+class Presentation(TypedDict):
+    """Partial implementation of the REST Resource Presentation.
+
+    Reference: https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations#Presentation
+    """
+
+    presentationId: str | None  # None when creating a new presentation
+    title: str
+    slides: list[Page]
+
+
+class InsertTextRequest(TypedDict):
+    """Partial implementation of the REST Resource InsertTextRequest.
+
+    Reference: https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations/request#InsertTextRequest
+    """
+
+    objectId: str
+    text: str
+
+
+class Placeholder(TypedDict):
+    """Partial implementation of the REST Resource Placeholder.
+
+    Reference: https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations.pages/other#Page.Placeholder
+    """
+
+    type: PlaceholderType
+    index: int
+
+
+class LayoutPlaceholderIdMapping(TypedDict):
+    """Partial implementation of the REST Resource LayoutPlaceholderIdMapping.
+
+    The user-specified ID mapping for a placeholder that will be
+    created on a slide from a specified layout.
+
+    Reference: https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations/request#LayoutPlaceholderIdMapping
+    """
+
+    objectId: str
+    layoutPlaceholder: Placeholder
+
+
+class LayoutReference(TypedDict):
+    """Partial implementation of the REST Resource LayoutReference.
+
+    Reference: https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations/request#LayoutReference
+    """
+
+    predefinedLayout: PredefinedLayout
+
+
+class CreateSlideRequest(TypedDict, total=False):
+    """Partial implementation of the REST Resource CreateSlideRequest.
+
+    insertionIndex is not required
+
+    Reference: https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations/request#CreateSlideRequest
+    """
+
+    objectId: str
+    insertionIndex: int  # The zero-based index where the new slide should be inserted. If not provided, the slide will be added to the end of the presentation.  # noqa: E501
+    slideLayoutReference: LayoutReference
+    placeholderIdMappings: list[LayoutPlaceholderIdMapping]
+
+
+class Request(TypedDict, total=False):
+    """Partial implementation of the REST Resource Request.
+
+    Reference: https://developers.google.com/workspace/slides/api/reference/rest/v1/presentations/request#Request
+    """
+
+    createSlide: CreateSlideRequest
+    insertText: InsertTextRequest