arcade-google-docs 4.0.0__py3-none-any.whl → 4.2.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/tools/get.py

@@ -3,6 +3,8 @@ from typing import Annotated
 from arcade_tdk import ToolContext, tool
 from arcade_tdk.auth import Google
 
+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
 
 
@@ -21,6 +23,7 @@ async def get_document_by_id(
     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())
@@ -30,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

@@ -5,7 +5,9 @@ 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.models.document import Document
 from arcade_google_docs.tools import get_document_by_id
 from arcade_google_docs.utils import (
     build_drive_service,
@@ -189,7 +191,9 @@ 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)

arcade_google_docs/tools/system_context.py

@@ -0,0 +1,36 @@
+from typing import Annotated, Any
+
+from arcade_tdk import ToolContext, tool
+from arcade_tdk.auth import Google
+
+from arcade_google_docs.utils import build_docs_service
+from arcade_google_docs.who_am_i_util import build_who_am_i_response
+
+
+@tool(
+    requires_auth=Google(
+        scopes=[
+            "https://www.googleapis.com/auth/drive.file",
+            "https://www.googleapis.com/auth/userinfo.profile",
+            "https://www.googleapis.com/auth/userinfo.email",
+        ]
+    )
+)
+async def who_am_i(
+    context: ToolContext,
+) -> Annotated[
+    dict[str, Any],
+    "Get comprehensive user profile and Google Docs environment information.",
+]:
+    """
+    Get comprehensive user profile and Google Docs environment information.
+
+    This tool provides detailed information about the authenticated user including
+    their name, email, profile picture, Google Docs access permissions, and other
+    important profile details from Google services.
+    """
+
+    docs_service = build_docs_service(context.get_auth_token_or_empty())
+    user_info = build_who_am_i_response(context, docs_service)
+
+    return dict(user_info)

arcade_google_docs/who_am_i_util.py

@@ -0,0 +1,86 @@
+from typing import Any, TypedDict, cast
+
+from google.oauth2.credentials import Credentials
+from googleapiclient.discovery import build
+
+
+class WhoAmIResponse(TypedDict, total=False):
+    my_email_address: str
+    display_name: str
+    given_name: str
+    family_name: str
+    formatted_name: str
+    profile_picture_url: str
+    google_docs_access: bool
+
+
+def build_who_am_i_response(context: Any, docs_service: Any) -> WhoAmIResponse:
+    """Build complete who_am_i response from Google Docs and People APIs."""
+    credentials = Credentials(
+        context.authorization.token if context.authorization and context.authorization.token else ""
+    )
+    people_service = _build_people_service(credentials)
+    person = _get_people_api_data(people_service)
+
+    user_info = _extract_profile_data(person)
+    user_info.update(_extract_google_docs_info(docs_service))
+
+    return cast(WhoAmIResponse, user_info)
+
+
+def _extract_profile_data(person: dict[str, Any]) -> dict[str, Any]:
+    """Extract user profile data from People API response."""
+    profile_data = {}
+
+    names = person.get("names", [])
+    if names:
+        primary_name = names[0]
+        profile_data.update({
+            "display_name": primary_name.get("displayName"),
+            "given_name": primary_name.get("givenName"),
+            "family_name": primary_name.get("familyName"),
+            "formatted_name": primary_name.get("displayNameLastFirst"),
+        })
+
+    photos = person.get("photos", [])
+    if photos:
+        profile_data["profile_picture_url"] = photos[0].get("url")
+
+    email_addresses = person.get("emailAddresses", [])
+    if email_addresses:
+        primary_emails = [
+            email for email in email_addresses if email.get("metadata", {}).get("primary")
+        ]
+        if primary_emails:
+            profile_data["my_email_address"] = primary_emails[0].get("value")
+
+    return profile_data
+
+
+def _extract_google_docs_info(docs_service: Any) -> dict[str, Any]:
+    """Extract Google Docs specific information."""
+    docs_info = {}
+
+    try:
+        # Test Google Docs access by checking if we can access the service
+        # Since there's no direct way to test docs access, we'll assume it's available
+        # if we have the service (the scope validation happens at auth time)
+        docs_info["google_docs_access"] = True
+    except Exception:
+        docs_info["google_docs_access"] = False
+
+    return docs_info
+
+
+def _build_people_service(credentials: Credentials) -> Any:
+    """Build and return the People API service client."""
+    return build("people", "v1", credentials=credentials)
+
+
+def _get_people_api_data(people_service: Any) -> dict[str, Any]:
+    """Get user profile information from People API."""
+    person_fields = "names,emailAddresses,photos"
+    return cast(
+        dict[str, Any],
+        people_service.people().get(resourceName="people/me", personFields=person_fields).execute(),
+    )

{arcade_google_docs-4.0.0.dist-info → arcade_google_docs-4.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arcade_google_docs
-Version: 4.0.0
+Version: 4.2.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.2.0.dist-info/RECORD

@@ -0,0 +1,30 @@
+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/who_am_i_util.py,sha256=NGQpQ0CuE2N86mGpkIdujXBRjcPBJ5SJ9BYzlb3mGFI,2925
+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=kQChYFQ6y1LJg7q6fngzCOPtaDH1-CeWUOzqxfR_oGY,904
+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/system_context.py,sha256=19HPSpNkLsb-MDWc-9CFgK_ha-rRzwaJr7hV6Us_1LI,1130
+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.2.0.dist-info/METADATA,sha256=nLo_FmuOXT86wVAbVVFk-fnxFqI04jI_pJI0B2spx3g,1127
+arcade_google_docs-4.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+arcade_google_docs-4.2.0.dist-info/RECORD,,

arcade_google_docs-4.0.0.dist-info/RECORD

@@ -1,16 +0,0 @@
-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/enum.py,sha256=vFJWPe1JPG6I9xqdVVvuaEeen4LvvtJxax1sDYeh4UU,3421
-arcade_google_docs/templates.py,sha256=pxbdMj57eV3-ImW3CixDWscpVKS94Z8nTNyTxDhUfGY,283
-arcade_google_docs/utils.py,sha256=XMgKcWPWKy8SbH3y2eCil01hssHhUgYxVrwXyvHEU4A,3748
-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=tCByk1-C97Mdo9P3oDdr--6bXD1dIQ3FxsDxptCJaA8,1145
-arcade_google_docs/tools/search.py,sha256=JpaOvcn3a6MjJEAqtne4vfiq4SvlINCw6lKv6nWt3zc,8035
-arcade_google_docs/tools/update.py,sha256=_dReYit0s7ykn2bYQEUwohl3D_63U5leF87egO4eEiQ,1836
-arcade_google_docs-4.0.0.dist-info/METADATA,sha256=lQakZrQRnTWx8Qa_vGbSwGxFOiVAMebNYVaSghfAGsw,1097
-arcade_google_docs-4.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-arcade_google_docs-4.0.0.dist-info/RECORD,,