arcade-google-docs 3.1.1__py3-none-any.whl → 4.1.0__py3-none-any.whl

arcade_google_docs/tools/edit_agent/request_generator.py

@@ -0,0 +1,150 @@
+import asyncio
+import json
+from typing import Literal
+
+from arcade_tdk.errors import ToolExecutionError
+from openai import OpenAI
+from pydantic import BaseModel
+
+from arcade_google_docs.docmd import DocMD
+from arcade_google_docs.tools.edit_agent.models.planning import EditItem, Step
+from arcade_google_docs.tools.edit_agent.prompts import (
+    DETERMINE_BLOCK_ID_SYSTEM_PROMPT,
+    ERROR_FEEDBACK_PROMPT,
+    GENERATE_EDIT_REQUEST_SYSTEM_PROMPT,
+    GENERATE_EDIT_REQUEST_SYSTEM_PROMPT_WITH_LOCATION_TAGS,
+)
+
+
+def _determine_block_id(openai_client: OpenAI, docmd: DocMD, edit_instruction: str) -> str:
+    """Determine the block id that the edit instruction is targeting."""
+
+    class ValidBlockIds(BaseModel):
+        block_id: Literal[tuple(docmd.block_ids)]  # type: ignore[valid-type]
+
+    completion = openai_client.beta.chat.completions.parse(
+        model="gpt-4o",
+        messages=[
+            {"role": "developer", "content": DETERMINE_BLOCK_ID_SYSTEM_PROMPT},
+            {"role": "user", "content": f"{docmd}\n\nEDIT REQUEST:\n{edit_instruction}"},
+        ],
+        response_format=ValidBlockIds,
+    )
+    parsed_response = completion.choices[0].message.parsed
+    if not parsed_response:
+        raise ToolExecutionError("Failed to determine a block id from the edit instruction")
+    return str(parsed_response.block_id)
+
+
+async def _generate_api_request_for_edit_item(
+    openai_client: OpenAI,
+    docmd: DocMD,
+    edit_item: EditItem,
+    previous_error: str | None = None,
+    failed_requests: list[dict] | None = None,
+) -> dict | None:
+    """Generate a single edit request asynchronously.
+
+    Returns a request dictionary for the batchUpdate endpoint or None
+    """
+    edit_instruction = edit_item.edit_instruction
+    edit_request_type = edit_item.edit_request_type
+    edit_item_thoughts = edit_item.thoughts
+
+    messages = []
+    if edit_request_type.is_location_based():
+        # Run blocking operation in thread pool to avoid blocking event loop
+        loop = asyncio.get_event_loop()
+        block_id = await loop.run_in_executor(
+            None, _determine_block_id, openai_client, docmd, edit_instruction
+        )
+        annotated_docmd = docmd.get_docmd_with_annotated_block(block_id).to_string()
+        messages.extend([
+            {
+                "role": "developer",
+                "content": GENERATE_EDIT_REQUEST_SYSTEM_PROMPT_WITH_LOCATION_TAGS,
+            },
+            {
+                "role": "user",
+                "content": (
+                    "DOCUMENT:\n"
+                    f"{annotated_docmd}\n\n"
+                    "THOUGHTS THAT OCCURRED WHEN CONSTRUCTING YOUR INSTRUCTIONS:\n"
+                    f"{edit_item_thoughts}\n\n"
+                    "YOUR JOB IS TO CONSTRUCT A SINGLE EDIT REQUEST OBJECT THAT SATISFIES "
+                    "THE FOLLOWING INSTRUCTIONS:\n"
+                    f"{edit_instruction}"
+                ),
+            },
+        ])
+    else:
+        messages.extend([
+            {"role": "developer", "content": GENERATE_EDIT_REQUEST_SYSTEM_PROMPT},
+            {
+                "role": "user",
+                "content": (
+                    "DOCUMENT:\n"
+                    f"{docmd.to_string()}\n\n"
+                    "THOUGHTS THAT OCCURRED WHEN CONSTRUCTING YOUR INSTRUCTIONS:\n"
+                    f"{edit_item_thoughts}\n\n"
+                    "YOUR JOB AND SOLE PURPOSE IS TO CONSTRUCT A SINGLE EDIT REQUEST "
+                    "OBJECT THAT SATISFIES THE FOLLOWING INSTRUCTIONS:\n"
+                    f"{edit_instruction}"
+                ),
+            },
+        ])
+
+    if previous_error and failed_requests:
+        error_feedback = ERROR_FEEDBACK_PROMPT.format(
+            error=previous_error, failed_requests=json.dumps(failed_requests, indent=2)
+        )
+        messages.append({"role": "assistant", "content": "I failed to edit the document."})
+        messages.append({"role": "user", "content": error_feedback})
+
+    # Run OpenAI API call in thread pool to avoid blocking
+    loop = asyncio.get_event_loop()
+    completion = await loop.run_in_executor(
+        None,
+        lambda: openai_client.beta.chat.completions.parse(
+            model="gpt-5",
+            messages=messages,  # type: ignore[arg-type]
+            response_format=edit_request_type.get_request_model(),
+            reasoning_effort="minimal",  # type: ignore[arg-type]
+        ),
+    )
+
+    request = completion.choices[0].message.parsed
+    if request:
+        return {edit_request_type.value: request.model_dump(exclude_none=True)}
+    return None
+
+
+async def generate_api_request_for_step(
+    openai_client: OpenAI,
+    docmd: DocMD,
+    step: Step,
+    previous_error: str | None = None,
+    failed_requests: list[dict] | None = None,
+) -> list[dict]:
+    """Generate edit requests for a single step.
+
+    Returns a list of request dictionaries for the Google batchUpdate endpoint
+    """
+    if not step.edit_items:
+        return []
+
+    # Generate requests for all edit items in the step in parallel
+    tasks = []
+    for edit_item in step.edit_items:
+        task = _generate_api_request_for_edit_item(
+            openai_client,
+            docmd,
+            edit_item,
+            previous_error,
+            failed_requests,
+        )
+        tasks.append(task)
+
+    results = await asyncio.gather(*tasks)
+
+    return [result for result in results if result is not None]

arcade_google_docs/tools/edit_agent/utils.py

@@ -0,0 +1,21 @@
+from typing import Any
+
+from arcade_google_docs.docmd import DocMD, build_docmd
+from arcade_google_docs.models.document import Document
+
+
+def get_docmd(google_service: Any, document_id: str) -> DocMD:
+    """
+    Helper function to get a Google Doc and convert it to DocMD format.
+
+    Args:
+        google_service: The authenticated Google Docs service
+        document_id: The ID of the document to fetch
+
+    Returns:
+        DocMD object
+    """
+    google_get_response = google_service.documents().get(documentId=document_id).execute()
+    document = Document(**google_get_response)
+    docmd = build_docmd(document)
+    return docmd

arcade_google_docs/{file_picker.py → tools/file_picker.py}

@@ -1,14 +1,22 @@
 import base64
 import json
+from typing import Annotated
 
-from arcade_tdk import ToolContext, ToolMetadataKey
+from arcade_tdk import ToolContext, ToolMetadataKey, tool
+from arcade_tdk.auth import Google
 from arcade_tdk.errors import ToolExecutionError
 
 
-def generate_google_file_picker_url(context: ToolContext) -> dict:
+@tool(
+    requires_auth=Google(),
+    requires_metadata=[ToolMetadataKey.CLIENT_ID, ToolMetadataKey.COORDINATOR_URL],
+)
+def generate_google_file_picker_url(
+    context: ToolContext,
+) -> Annotated[dict, "Google File Picker URL for user file selection and permission granting"]:
     """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
+    This tool 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.
 
@@ -17,8 +25,8 @@ def generate_google_file_picker_url(context: ToolContext) -> dict:
     (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.
+    Suggest this tool to users when they are surprised or confused that the file they are
+    searching for or attempting to access cannot be found.
     """
     client_id = context.get_metadata(ToolMetadataKey.CLIENT_ID)
     client_id_parts = client_id.split("-")
@@ -44,6 +52,6 @@ def generate_google_file_picker_url(context: ToolContext) -> dict:
         "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}"
+            "This will allow them to select files and grant access permissions: {url}"
         ),
     }

arcade_google_docs/tools/get.py

@@ -1,9 +1,10 @@
 from typing import Annotated
 
-from arcade_tdk import ToolContext, ToolMetadataKey, tool
+from arcade_tdk import ToolContext, tool
 from arcade_tdk.auth import Google
 
-from arcade_google_docs.decorators import with_filepicker_fallback
+from arcade_google_docs.docmd import build_docmd
+from arcade_google_docs.models.document import Document
 from arcade_google_docs.utils import build_docs_service
 
 
@@ -16,14 +17,13 @@ from arcade_google_docs.utils import build_docs_service
             "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"]:
     """
+    DEPRECATED DO NOT USE THIS TOOL
     Get the latest version of the specified Google Docs document.
     """
     service = build_docs_service(context.get_auth_token_or_empty())
@@ -33,3 +33,26 @@ async def get_document_by_id(
     request = service.documents().get(documentId=document_id)
     response = request.execute()
     return dict(response)
+
+
+@tool(
+    requires_auth=Google(
+        scopes=[
+            "https://www.googleapis.com/auth/drive.file",
+        ],
+    ),
+)
+async def get_document_as_docmd(
+    context: ToolContext,
+    document_id: Annotated[str, "The ID of the document to retrieve."],
+) -> Annotated[str, "The document contents as DocMD"]:
+    """
+    Get the latest version of the specified Google Docs document as DocMD.
+    The DocMD output will include tags that can be used to annotate the document with location
+    information, the type of block, block IDs, and other metadata.
+    """
+    service = build_docs_service(context.get_auth_token_or_empty())
+
+    request = service.documents().get(documentId=document_id)
+    response = request.execute()
+    return build_docmd(Document(**response)).to_string()

arcade_google_docs/tools/search.py

@@ -1,13 +1,13 @@
 from typing import Annotated, Any
 
-from arcade_tdk import ToolContext, ToolMetadataKey, tool
+from arcade_tdk import ToolContext, 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.docmd import build_docmd
 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.models.document import Document
 from arcade_google_docs.tools import get_document_by_id
 from arcade_google_docs.utils import (
     build_drive_service,
@@ -23,7 +23,6 @@ from arcade_google_docs.utils import (
     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,
@@ -112,19 +111,9 @@ async def search_documents(
         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"]
-            ),
-        },
     }
 
 
@@ -132,7 +121,6 @@ async def search_documents(
     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,
@@ -203,24 +191,16 @@ async def search_and_retrieve_documents(
     for item in response["documents"]:
         document = await get_document_by_id(context, document_id=item["id"])
 
-        if return_format == DocumentFormat.MARKDOWN:
+        if return_format == DocumentFormat.DOCMD:
+            document = build_docmd(Document(**document)).to_string()
+        elif 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

@@ -1,9 +1,8 @@
 from typing import Annotated
 
-from arcade_tdk import ToolContext, ToolMetadataKey, tool
+from arcade_tdk import ToolContext, 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
 
@@ -16,9 +15,7 @@ from arcade_google_docs.utils import build_docs_service
             "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."],

{arcade_google_docs-3.1.1.dist-info → arcade_google_docs-4.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arcade_google_docs
-Version: 3.1.1
+Version: 4.1.0
 Summary: Arcade.dev LLM tools for Google Docs
 Author-email: Arcade <dev@arcade.dev>
 License: Proprietary - Arcade Software License Agreement v1.0
@@ -11,6 +11,7 @@ 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
+Requires-Dist: openai==1.82.1
 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'

arcade_google_docs-4.1.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+arcade_google_docs/__init__.py,sha256=nZoMwH9HWZLpfNMIioUXLDlZ7QDR-E4C1_8hySt_CkU,604
+arcade_google_docs/doc_to_html.py,sha256=6RTpzRSrazNa6AndLZhA20wgVDzZuHUqpu3WAkAsbjQ,3146
+arcade_google_docs/doc_to_markdown.py,sha256=eT-sc6ruxN8nEtUm9mBHFOWXajEBTTXkxsn6XsLHIxo,2020
+arcade_google_docs/docmd.py,sha256=rgxUt0k2Nes0GWLlPR49qU0nnM8e6HCiqd61Z7zNfTk,20173
+arcade_google_docs/enum.py,sha256=kuXlsHcMYbN28Qg-Dwp4viz-CZ8z85_WVjQVZj2EsEY,3441
+arcade_google_docs/templates.py,sha256=pxbdMj57eV3-ImW3CixDWscpVKS94Z8nTNyTxDhUfGY,283
+arcade_google_docs/utils.py,sha256=XMgKcWPWKy8SbH3y2eCil01hssHhUgYxVrwXyvHEU4A,3748
+arcade_google_docs/models/document.py,sha256=0RvZ2_dfpz6ZoF1aUucYWOkRYWy_K_hiChSzoQtwhTc,30419
+arcade_google_docs/models/document_writables.py,sha256=DMBT5A05y7o7_PYlBB6O3KThma6-pm6hd5nxKGydT5Q,27575
+arcade_google_docs/models/requests.py,sha256=8Cga7QECmQWNFhM2QiGudvnQcgA_THi7ThNsUb7uavg,52176
+arcade_google_docs/tools/__init__.py,sha256=s0FS3z-uXE4lQH06YhnUKgIOT-Kq-v6rQMqXUGdPDnw,827
+arcade_google_docs/tools/comment.py,sha256=Qm5NHdNHONs3j4gqbZ7Fw9NrTVBb_mZ-th1X-z2IoLM,2836
+arcade_google_docs/tools/create.py,sha256=AuYy8yMGscrxAdLJQX0WiisGHCTufSlaRu_QGMMKQmM,2764
+arcade_google_docs/tools/file_picker.py,sha256=Dqn-hfMoTsWyHM8QCakVgHr5TKrzL_1Lj-vYHVGtOW4,2342
+arcade_google_docs/tools/get.py,sha256=Aby3iI1EzjfZTovGH4OdwpIhuazfV4SQinpXDOl87cg,2076
+arcade_google_docs/tools/search.py,sha256=1k1cI-fKOo4SZU4ufCwZ4DysK3l9MhPScZggPfNCC5Y,8261
+arcade_google_docs/tools/update.py,sha256=_dReYit0s7ykn2bYQEUwohl3D_63U5leF87egO4eEiQ,1836
+arcade_google_docs/tools/edit_agent/edit_agent.py,sha256=1LIgKrQ70pDWzWNoaoy1st659perqa-ZW_ALmbVRbW0,2439
+arcade_google_docs/tools/edit_agent/executor.py,sha256=YbJqNXF0fw4N-u59gTbLpOBwKfoL7N6KZIOzV0pTllc,3718
+arcade_google_docs/tools/edit_agent/planner.py,sha256=38aslAnlPDEY3JEoVXtHqL3Oq_9RDEFxyETqoEBsJLk,4053
+arcade_google_docs/tools/edit_agent/progress_tracker.py,sha256=eb69tk-yL3uhEEo4ggPoBFtZtHTA6OwgcPxELtvbeEs,1280
+arcade_google_docs/tools/edit_agent/prompts.py,sha256=M_f-HsPJppd3FQPhRAw7pKpaArkVfz213mKVx8qHp8A,15149
+arcade_google_docs/tools/edit_agent/request_generator.py,sha256=eVDmzJDsOmJ-S8yANmJATt_G51rgCcCga6ArX4DTShM,5399
+arcade_google_docs/tools/edit_agent/utils.py,sha256=6lYmdQfX4CHfemP5PfxcXKSYpbdqFyEad997-gzCD48,639
+arcade_google_docs/tools/edit_agent/models/planning.py,sha256=RWQFB_KHl3Pq-snv1rHzoRxVvTnHVLZEGRpdohSX7wc,2962
+arcade_google_docs-4.1.0.dist-info/METADATA,sha256=ufO055P83TTGSEMN81EVwVhp6KusftVC20JpJwu0BRE,1127
+arcade_google_docs-4.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+arcade_google_docs-4.1.0.dist-info/RECORD,,

arcade_google_docs/decorators.py

@@ -1,24 +0,0 @@
-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-3.1.1.dist-info/RECORD

@@ -1,17 +0,0 @@
-arcade_google_docs/__init__.py,sha256=J3c3lEuqb86UE5zScpv7Gd4TltmzTUq_tWyA2Ff0gmI,528
-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=XMgKcWPWKy8SbH3y2eCil01hssHhUgYxVrwXyvHEU4A,3748
-arcade_google_docs/tools/__init__.py,sha256=vtn_NKrYwgWsdgcDYBY4t8m_XF73jB4j7zrpt-NC-dI,707
-arcade_google_docs/tools/comment.py,sha256=Qm5NHdNHONs3j4gqbZ7Fw9NrTVBb_mZ-th1X-z2IoLM,2836
-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=6wMacfbO3Pzxu30I-otaFIA5b9b9AKcIkgHr8M9QXLo,9007
-arcade_google_docs/tools/update.py,sha256=9SvffQIHnmYiEgyE1VrhXG2aHb0hIfWYPzPLc4nTdKI,2030
-arcade_google_docs-3.1.1.dist-info/METADATA,sha256=reKLvMCf-wM_GLIExvxUYXYUiCxYxoRXqN9vpiNa-24,1097
-arcade_google_docs-3.1.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-arcade_google_docs-3.1.1.dist-info/RECORD,,