athena-python-docx 0.5.2__tar.gz → 0.5.3__tar.gz

{athena_python_docx-0.5.2 → athena_python_docx-0.5.3}/CLAUDE.md

@@ -145,6 +145,13 @@ This is a **thin HTTP client** that mimics the sync python-docx API.
   resolve to `CommandBuffer.call(CreateParagraph(**p))`. Rewriting call
   sites to construct `Command` dataclasses directly is a possible
   follow-up — the wire format is typed end-to-end either way.
+- **Programmatic Tool Calling (PTC):** every `CommandBuffer.call` and
+  `flush` emits begin/end events to agora via `docx/_ptc.py` when run
+  inside a Daytona sandbox with `ATHENA_PTC_URL` set. Each method call
+  surfaces as a nested sub-tool-card under the parent
+  `run_python_code` tool. See
+  [`docs/PROGRAMMATIC_TOOL_CALLING_GUIDE.md`](../../docs/PROGRAMMATIC_TOOL_CALLING_GUIDE.md)
+  at the monorepo root.
 
 ## Development
 

{athena_python_docx-0.5.2 → athena_python_docx-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.5.2
+Version: 0.5.3
 Summary: Drop-in replacement for python-docx that connects to Athena's Superdoc/Keryx collaborative document stack
 Project-URL: Homepage, https://athenaintelligence.ai
 Author-email: Athena Intelligence <engineering@athenaintelligence.ai>

{athena_python_docx-0.5.2 → athena_python_docx-0.5.3}/docx/__init__.py

@@ -6,7 +6,7 @@ See CLAUDE.md for the API parity contract.
 
 from __future__ import annotations
 
-__version__ = "0.5.2"
+__version__ = "0.5.3"
 
 from docx.api import Document
 from docx._buffer import flush_all

{athena_python_docx-0.5.2 → athena_python_docx-0.5.3}/docx/_buffer.py

@@ -26,12 +26,36 @@ import weakref
 from contextlib import contextmanager
 from typing import TYPE_CHECKING, Any, Generator
 
+from docx import _ptc
 from docx.commands import Command, must_flush_immediately
 
 if TYPE_CHECKING:
     from docx._http_doc import HttpClient
 
 
+def _ptc_emit_end_batch(cmds: list[Command], *, is_error: bool) -> None:
+    """Emit a PTC ``end`` event for every cmd that received a ``begin``.
+
+    Tolerant: missing call_ids (cmd was added before PTC env was set) and
+    PTC client exceptions both silently no-op.
+    """
+    for c in cmds:
+        call_id = getattr(c, "_ptc_call_id", None)
+        if not call_id:
+            continue
+        try:
+            _ptc.emit_end(
+                call_id=call_id,
+                tool_name=type(c).__name__,
+                result={"ok": not is_error}
+                if not is_error
+                else {"ok": False, "error": "command batch failed"},
+                is_error=is_error,
+            )
+        except Exception:  # noqa: BLE001
+            pass
+
+
 # ---------------------------------------------------------------------------
 # Process-wide registry for flush_all()
 # ---------------------------------------------------------------------------
@@ -130,8 +154,45 @@ class CommandBuffer:
         # original semantics.
         self._change_mode: str | None = None
         self._user: dict[str, str] | None = None
+        # Batch mode flag — when True, Create* commands buffer instead
+        # of flushing immediately, and proxies bind to a client-side
+        # UUID instead of waiting for the server response. See
+        # :meth:`Document.batch` and ``PERFORMANCE_BATCHING_ANALYSIS.md``.
+        self._batch_depth: int = 0
+        # client_node_id → list of (proxy, attr) pairs to update with the
+        # real nodeId after flush. Populated by ``add_paragraph`` /
+        # ``add_heading`` / etc. when they queue a Create with a
+        # client-assigned id. Drained on every flush.
+        self._proxy_id_refs: dict[
+            str, list[tuple[object, str]]
+        ] = {}
         _register(self)
 
+    @property
+    def is_batching(self) -> bool:
+        """``True`` if a ``with doc.batch():`` block is currently open.
+
+        SDK call sites read this to decide whether to defer Create*
+        commands or eager-flush them. Reentrant — nested ``batch()``
+        blocks increment the counter and decrement on exit; the outer
+        block is what actually flushes.
+        """
+        return self._batch_depth > 0
+
+    def register_proxy_id_ref(
+        self, client_id: str, proxy: object, attr: str = "_node_id"
+    ) -> None:
+        """Register that ``proxy.<attr>`` should be rewritten from
+        ``client_id`` to the real node id once the current batch flushes.
+
+        Called by ``Document.add_paragraph`` (and equivalents) when they
+        queue a Create with a ``client_node_id``. The flush loop walks
+        the per-cmd result for ``real_node_id`` / ``real_entity_id``
+        echoes and applies setattr to every registered ref.
+        """
+        with self._lock:
+            self._proxy_id_refs.setdefault(client_id, []).append((proxy, attr))
+
     @property
     def asset_id(self) -> str:
         return self._asset_id
@@ -193,19 +254,35 @@ class CommandBuffer:
     def call(self, cmd: Command) -> Any:
         """Execute or buffer ``cmd``.
 
-        For eager commands (queries, creates), drains the pending queue and
-        runs ``cmd`` in the same batch; returns the per-cmd result dict.
+        For eager commands (queries, response-bearing creates), drains
+        the pending queue and runs ``cmd`` in the same batch; returns
+        the per-cmd result dict.
 
         For pure mutations, appends to the queue, resets the idle timer,
-        and returns ``None``. The caller MUST NOT rely on the return value
-        of a buffered mutation — it's not available until flush.
+        and returns ``None``. The caller MUST NOT rely on the return
+        value of a buffered mutation — it's not available until flush.
+
+        **Batch mode:** when ``self.is_batching`` is True AND the command
+        carries a non-None ``client_node_id`` / ``client_entity_id``
+        (Create*, CommentsCreate), the command is buffered rather than
+        eager-flushed. The caller is expected to have pre-stamped a
+        proxy with the client-side id; after the batch flushes, the
+        applier's ``real_node_id`` / ``real_entity_id`` echo lets the
+        SDK rewrite the proxy in-place.
         """
         if self._closed:
             raise RuntimeError(
                 f"CommandBuffer for {self._asset_id} is closed",
             )
 
-        if must_flush_immediately(cmd):
+        # PTC begin: one event per user-facing method call, before any
+        # batching. Failures here can't crash the user's code path.
+        try:
+            cmd._ptc_call_id = _ptc.emit_begin(type(cmd).__name__, cmd.to_dict())  # type: ignore[attr-defined]
+        except Exception:  # noqa: BLE001
+            pass
+
+        if must_flush_immediately(cmd) and not self._is_batched_create(cmd):
             return self._eager_flush_with(cmd)
 
         with self._lock:
@@ -213,11 +290,36 @@ class CommandBuffer:
             self._reset_timer_locked()
         return None
 
+    def _is_batched_create(self, cmd: Command) -> bool:
+        """Return True iff this command can be safely deferred because
+        the caller pre-assigned a client-side id and the buffer is in
+        batch mode.
+
+        We only defer Create-shape commands (those with
+        ``client_node_id`` / ``client_entity_id`` set). Pure queries
+        like ``BlocksList`` must still eager-flush — the caller is
+        awaiting their data. Read-bearing creates without a client id
+        (legacy callers / non-batch path) also stay eager so we don't
+        change their semantics.
+        """
+        if not self.is_batching:
+            return False
+        cli_node = getattr(cmd, "client_node_id", None)
+        cli_ent = getattr(cmd, "client_entity_id", None)
+        return cli_node is not None or cli_ent is not None
+
     def flush(self) -> list[Any]:
         """Flush pending commands as one HTTP batch.
 
         Returns the list of per-command result dicts. Empty list if nothing
         was pending. Cancels any active idle timer.
+
+        After the batch returns, walks per-cmd results for
+        ``real_node_id`` / ``real_entity_id`` echoes and updates any
+        proxies registered via :meth:`register_proxy_id_ref` with the
+        resolved server ids. This is what completes the round-trip for
+        ``with doc.batch():`` — the SDK's caller-facing proxies pick up
+        real ids transparently after the block exits.
         """
         with self._lock:
             self._cancel_timer_locked()
@@ -225,37 +327,86 @@ class CommandBuffer:
             self._pending = []
             change_mode = self._change_mode
             user = None if self._user is None else dict(self._user)
+            proxy_id_refs = self._proxy_id_refs
+            self._proxy_id_refs = {}
         if not pending:
             return []
-        return self._client.execute_batch(
-            self._asset_id,
-            pending,
-            change_mode=change_mode,
-            user=user,
-        )
+        try:
+            results = self._client.execute_batch(
+                self._asset_id,
+                pending,
+                change_mode=change_mode,
+                user=user,
+            )
+        except Exception:
+            _ptc_emit_end_batch(pending, is_error=True)
+            raise
+        _ptc_emit_end_batch(pending, is_error=False)
+        # Rewrite registered proxies from client-side UUIDs to the real
+        # SuperDoc ids the applier echoed back. Defensive: tolerate
+        # missing fields (legacy or transitional applier without the
+        # client-id support).
+        if proxy_id_refs:
+            for result in results:
+                if not isinstance(result, dict):
+                    continue
+                for cli_key, real_key in (
+                    ("client_node_id", "real_node_id"),
+                    ("client_entity_id", "real_entity_id"),
+                ):
+                    cli = result.get(cli_key)
+                    real = result.get(real_key)
+                    if not (isinstance(cli, str) and isinstance(real, str)):
+                        continue
+                    refs = proxy_id_refs.pop(cli, [])
+                    for proxy, attr in refs:
+                        try:
+                            setattr(proxy, attr, real)
+                        except Exception:  # noqa: BLE001
+                            # A proxy that rejected setattr (slots without
+                            # the attr, frozen dataclass, etc.) silently
+                            # keeps its client_id — the rewriter in the
+                            # applier will still resolve it correctly
+                            # for the next batch.
+                            pass
+        return results
 
     @contextmanager
     def batch(self) -> Generator[None, None, None]:
         """Group calls into one HTTP batch.
 
-        Inside the ``with`` block, eager commands still flush immediately
-        (we can't buffer reads — the caller is awaiting their result), but
-        pure mutations accumulate without their idle timer firing.
-        On exit, drains anything left.
+        Inside the ``with`` block:
+
+        - Queries (``BlocksList``, ``Find``, ``GetNodeById``, …) still
+          eager-flush — the caller is awaiting their result, so we have
+          no choice.
+        - Pure mutations (formatters, setters) accumulate without their
+          idle timer firing.
+        - Create*-shape commands that carry a ``client_node_id`` /
+          ``client_entity_id`` (set by ``Document.add_paragraph`` and
+          friends when they detect batch mode) also accumulate — the
+          server resolves the client UUIDs to real SuperDoc ids in a
+          single batch via the per-request ``clientIdMap``.
+
+        On exit, drains anything left. Reentrant: nested ``batch()``
+        blocks share the same accumulating queue; only the outermost
+        block flushes.
         """
-        # Cancel the idle timer for the duration of the block; we'll flush
-        # explicitly on exit. New adds inside the block go straight onto
-        # _pending without rescheduling the timer.
         with self._lock:
             self._cancel_timer_locked()
             old_window = self._auto_flush_seconds
-            self._auto_flush_seconds = 0.0  # disable scheduling
+            self._auto_flush_seconds = 0.0  # disable timer-scheduled flush
+            self._batch_depth += 1
         try:
             yield
         finally:
             with self._lock:
-                self._auto_flush_seconds = old_window
-            self.flush()
+                self._batch_depth -= 1
+                outermost = self._batch_depth == 0
+                if outermost:
+                    self._auto_flush_seconds = old_window
+            if outermost:
+                self.flush()
 
     def close(self) -> None:
         """Flush and disable. Idempotent."""
@@ -270,20 +421,54 @@ class CommandBuffer:
     # ----- internals -----
 
     def _eager_flush_with(self, cmd: Command) -> Any:
-        """Drain pending + run ``cmd`` in one batch; return cmd's result."""
+        """Drain pending + run ``cmd`` in one batch; return cmd's result.
+
+        When pending commands include batched Creates with registered
+        proxy refs (e.g. a query mid-batch triggers an eager flush
+        before the ``with doc.batch():`` block ends), the proxies still
+        get their real ids written back via the same flush-time rewrite
+        that :meth:`flush` does.
+        """
         with self._lock:
             self._cancel_timer_locked()
             pending = self._pending
             self._pending = []
             change_mode = self._change_mode
             user = None if self._user is None else dict(self._user)
+            proxy_id_refs = self._proxy_id_refs
+            self._proxy_id_refs = {}
         all_cmds: list[Command] = [*pending, cmd]
-        results: list[Any] = self._client.execute_batch(
-            self._asset_id,
-            all_cmds,
-            change_mode=change_mode,
-            user=user,
-        )
+        try:
+            results: list[Any] = self._client.execute_batch(
+                self._asset_id,
+                all_cmds,
+                change_mode=change_mode,
+                user=user,
+            )
+        except Exception:
+            _ptc_emit_end_batch(all_cmds, is_error=True)
+            raise
+        _ptc_emit_end_batch(all_cmds, is_error=False)
+        # Apply the same proxy-rewrite pass as ``flush()`` — see comment
+        # there for the contract.
+        if proxy_id_refs:
+            for result in results:
+                if not isinstance(result, dict):
+                    continue
+                for cli_key, real_key in (
+                    ("client_node_id", "real_node_id"),
+                    ("client_entity_id", "real_entity_id"),
+                ):
+                    cli = result.get(cli_key)
+                    real = result.get(real_key)
+                    if not (isinstance(cli, str) and isinstance(real, str)):
+                        continue
+                    refs = proxy_id_refs.pop(cli, [])
+                    for proxy, attr in refs:
+                        try:
+                            setattr(proxy, attr, real)
+                        except Exception:  # noqa: BLE001
+                            pass
         if not results:
             return {}
         return results[-1]

{athena_python_docx-0.5.2 → athena_python_docx-0.5.3}/docx/_http_doc.py

@@ -110,10 +110,87 @@ from docx.commands import (
 from docx.errors import (
     AuthenticationError,
     DocxError,
+    NotFoundError,
     SessionError,
 )
 
 
+_NOT_FOUND_ERROR_NAMES: frozenset[str] = frozenset(
+    {
+        "notfound",
+        "notfounderror",
+        "entitynotfound",
+        "entitynotfounderror",
+        "commentnotfound",
+        "commentnotfounderror",
+        "nodenotfound",
+        "nodenotfounderror",
+        "missingnode",
+        "missingnodeerror",
+    }
+)
+
+
+def _looks_like_not_found(parsed: dict) -> bool:
+    """Inspect a docx-studio partial-failure dict and decide whether it
+    describes a "no such entity" miss (vs. a real transport / validation
+    failure).
+
+    Prefers a structured signal (the server-side error class name, or a
+    typed ``code`` field) and falls back to a broadened set of message
+    substrings so phrasing changes upstream don't silently re-route a
+    miss into a transport error.
+    """
+    if not isinstance(parsed, dict):
+        return False
+    err_obj = parsed.get("error")
+    code = parsed.get("code")
+    name_candidates: list[str] = []
+    if isinstance(err_obj, str):
+        name_candidates.append(err_obj)
+    elif isinstance(err_obj, dict):
+        for key in ("name", "code", "type", "kind"):
+            v = err_obj.get(key)
+            if isinstance(v, str):
+                name_candidates.append(v)
+    if isinstance(code, str):
+        name_candidates.append(code)
+    for name in name_candidates:
+        if name.replace("_", "").replace("-", "").lower() in _NOT_FOUND_ERROR_NAMES:
+            return True
+    if parsed.get("status") == 404 or parsed.get("statusCode") == 404:
+        return True
+    # Broad substring fallback (case-insensitive) — covers phrasing
+    # variants the server (or SuperDoc) may use before a typed error
+    # code lands. Includes the original 3 patterns plus additional
+    # common phrasings.
+    msg_parts: list[str] = []
+    for key in ("message", "detail", "error"):
+        v = parsed.get(key)
+        if isinstance(v, str):
+            msg_parts.append(v)
+        elif isinstance(v, dict):
+            inner = v.get("message")
+            if isinstance(inner, str):
+                msg_parts.append(inner)
+    haystack = " ".join(msg_parts).lower()
+    if not haystack:
+        return False
+    return any(
+        needle in haystack
+        for needle in (
+            "not found",
+            "no such",
+            "does not exist",
+            "doesn't exist",
+            "doesnt exist",
+            "404",
+            "unknown id",
+            "missing entity",
+        )
+    )
+
+
 def _user_agent() -> str:
     # Lazy import — docx/__init__.py imports api.py at package load, but
     # _http_doc is only imported lazily from client.py at session-open
@@ -200,6 +277,16 @@ def _http_post_json(
             parsed = json.loads(body) if body else {}
         except json.JSONDecodeError:
             parsed = {"raw": body}
+        # If the failing command's error looks like "no such entity",
+        # raise a typed :class:`NotFoundError` so speculative-read call
+        # sites (``Comments.get``) can coerce it to ``None`` without
+        # swallowing real transport / validation failures.
+        err_obj = parsed.get("error") if isinstance(parsed, dict) else None
+        if isinstance(err_obj, dict) and _looks_like_not_found(err_obj):
+            raise NotFoundError(
+                f"docx-studio batch reported a partial failure: {parsed!r}",
+                payload=err_obj,
+            )
         raise DocxError(
             f"docx-studio batch reported a partial failure: {parsed!r}",
         )
@@ -217,6 +304,11 @@ def _http_post_json(
         raise AuthenticationError(
             f"docx-studio rejected the request (HTTP {resp.status_code}): {err_body}",
         )
+    if resp.status_code == 404:
+        raise NotFoundError(
+            f"docx-studio returned HTTP 404: {err_body}",
+            payload={"status": 404, "body": err_body},
+        )
     raise DocxError(
         f"docx-studio returned HTTP {resp.status_code}: {err_body}",
     )

athena_python_docx-0.5.3/docx/_ptc.py

@@ -0,0 +1,173 @@
+"""Programmatic Tool Calling (PTC) — client side, docx SDK.
+
+Activated only when ``ATHENA_PTC_URL`` is set. The URL is a presigned
+endpoint URL with an HMAC-signed token embedded as ``?t=…``; the token
+carries the (thread, parent_tool_call_id, run) triple and an expiry.
+The SDK doesn't need to know that triple — it just POSTs to the URL
+verbatim, and the server derives identity from the token.
+
+Without ``ATHENA_PTC_URL`` set, every call here is a no-op.
+
+Emits are fire-and-forget on a background daemon thread:
+
+- Never raise into user code.
+- Never block the calling thread.
+- Re-read ``ATHENA_PTC_URL`` on every emit so updates between sandbox
+  executions take effect immediately (the SDK module itself is cached
+  across runs).
+- Snapshot the URL at ``emit_begin`` time and carry it to ``emit_end``
+  so late end events can't be misattributed if a new sandbox run
+  swapped in a different URL between begin and end.
+
+This module is *intentionally* duplicated into the pptx and xlsx SDKs
+— the three SDKs have no shared base. Keeping it byte-identical
+(modulo ``_LIB_NAME``) makes diffs trivial.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import queue
+import threading
+import time
+import urllib.error
+import urllib.request
+import uuid
+from typing import Any
+
+_LIB_NAME = "docx"
+
+_MAX_QUEUE = 4096
+_MAX_BODY = 64 * 1024
+_HTTP_TIMEOUT = 2.0
+
+_PTC_URL_ENV = "ATHENA_PTC_URL"
+
+
+def _read_url() -> str | None:
+    url = os.environ.get(_PTC_URL_ENV)
+    return url if url else None
+
+
+def _utcnow_iso() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%S.000Z", time.gmtime())
+
+
+class _PTCClient:
+    def __init__(self) -> None:
+        # Lazy: don't snapshot URL at import time; runs change between
+        # sandbox executions and the module is cached in sys.modules.
+        self._q: queue.Queue[tuple[str, dict[str, Any]] | None] = queue.Queue(
+            maxsize=_MAX_QUEUE,
+        )
+        self._started = False
+        self._lock = threading.Lock()
+        # call_id -> URL snapshot at begin time. Lets emit_end target
+        # the original run's endpoint even if env changed since.
+        self._call_url: dict[str, str] = {}
+
+    def _ensure_started(self) -> None:
+        if self._started:
+            return
+        with self._lock:
+            if self._started:
+                return
+            t = threading.Thread(
+                target=self._drain,
+                name=f"athena-{_LIB_NAME}-ptc",
+                daemon=True,
+            )
+            t.start()
+            self._started = True
+
+    def emit_begin(self, tool_name: str, args: dict[str, Any]) -> str:
+        call_id = uuid.uuid4().hex
+        url = _read_url()
+        if url is None:
+            return call_id
+        self._call_url[call_id] = url
+        self._ensure_started()
+        body = {
+            "callId": call_id,
+            "toolName": f"{_LIB_NAME}.{tool_name}",
+            "phase": "begin",
+            "args": args,
+            "ts": _utcnow_iso(),
+        }
+        self._enqueue(url, body)
+        return call_id
+
+    def emit_end(
+        self,
+        *,
+        call_id: str,
+        tool_name: str,
+        result: dict[str, Any] | None,
+        is_error: bool,
+    ) -> None:
+        url = self._call_url.pop(call_id, None)
+        if url is None:
+            return  # PTC was disabled at begin, or begin wasn't emitted
+        body = {
+            "callId": call_id,
+            "toolName": f"{_LIB_NAME}.{tool_name}",
+            "phase": "end",
+            "result": result,
+            "isError": is_error,
+            "ts": _utcnow_iso(),
+        }
+        self._enqueue(url, body)
+
+    def _enqueue(self, url: str, body: dict[str, Any]) -> None:
+        try:
+            self._q.put_nowait((url, body))
+        except queue.Full:
+            pass  # drop on backpressure; never block user code
+
+    def _drain(self) -> None:
+        while True:
+            item = self._q.get()
+            if item is None:
+                return
+            url, body = item
+            try:
+                raw = json.dumps(body).encode("utf-8")
+                if len(raw) > _MAX_BODY:
+                    truncated_key = "args" if body.get("phase") == "begin" else "result"
+                    body[truncated_key] = {"__truncated__": True}
+                    raw = json.dumps(body).encode("utf-8")
+                req = urllib.request.Request(
+                    url,
+                    data=raw,
+                    method="POST",
+                    headers={"Content-Type": "application/json"},
+                )
+                urllib.request.urlopen(req, timeout=_HTTP_TIMEOUT).close()
+            except (urllib.error.URLError, OSError, ValueError):
+                pass  # never propagate
+
+
+_CLIENT = _PTCClient()
+
+
+def emit_begin(tool_name: str, args: dict[str, Any]) -> str:
+    return _CLIENT.emit_begin(tool_name, args)
+
+
+def emit_end(
+    *,
+    call_id: str,
+    tool_name: str,
+    result: dict[str, Any] | None,
+    is_error: bool,
+) -> None:
+    _CLIENT.emit_end(
+        call_id=call_id,
+        tool_name=tool_name,
+        result=result,
+        is_error=is_error,
+    )
+
+
+__all__ = ["emit_begin", "emit_end"]