athena-python-docx 0.42.0__tar.gz → 0.42.1__tar.gz

{athena_python_docx-0.42.0 → athena_python_docx-0.42.1}/PKG-INFO

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

{athena_python_docx-0.42.0 → athena_python_docx-0.42.1}/docx/__init__.py

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

{athena_python_docx-0.42.0 → athena_python_docx-0.42.1}/docx/_buffer.py

@@ -29,6 +29,7 @@ alive.
 from __future__ import annotations
 
 import copy
+import dataclasses
 import json
 import sys
 import threading
@@ -58,6 +59,7 @@ from docx.errors import DocxError, DocxUnsupportedCommandError, FlushAllError
 def _apply_proxy_id_rewrites(
     results: list[Any],
     proxy_id_refs: "dict[str, list[tuple[object, str]]]",
+    resolved: "dict[str, str] | None" = None,
 ) -> None:
     """Walk ``results`` and rewrite registered proxy ids from client UUIDs
     to the real DOCX Studio ids the applier echoed back.
@@ -79,7 +81,7 @@ def _apply_proxy_id_rewrites(
     ``clientIdMap`` rewrite still resolves them server-side on the
     *next* call.
     """
-    if not proxy_id_refs:
+    if not proxy_id_refs and resolved is None:
         return
     for result in results:
         if not isinstance(result, dict):
@@ -92,6 +94,8 @@ def _apply_proxy_id_rewrites(
             real = result.get(real_key)
             if not (isinstance(cli, str) and isinstance(real, str)):
                 continue
+            if resolved is not None:
+                resolved[cli] = real
             refs = proxy_id_refs.pop(cli, [])
             for proxy, attr in refs:
                 try:
@@ -104,6 +108,44 @@ def _apply_proxy_id_rewrites(
                     pass
 
 
+_MINTED_ID_FIELDS: frozenset[str] = frozenset({"client_node_id", "client_entity_id"})
+
+
+def _with_resolved_ids(value: Any, resolved: "dict[str, str]") -> Any:
+    """``value`` with every string that is a client id in ``resolved`` swapped
+    for its real id; the same object when nothing changed."""
+    if isinstance(value, str):
+        return resolved.get(value, value)
+    if isinstance(value, dict):
+        out = {k: _with_resolved_ids(v, resolved) for k, v in value.items()}
+        return value if all(out[k] is value[k] for k in value) else out
+    if isinstance(value, list):
+        items = [_with_resolved_ids(v, resolved) for v in value]
+        return value if all(a is b for a, b in zip(items, value)) else items
+    return value
+
+
+def _resolve_client_ids(cmd: Command, resolved: "dict[str, str]") -> None:
+    """Point ``cmd`` at the real ids of the creates an earlier batch landed.
+
+    A proxy's own id is rewritten when its create's batch returns, but a copy
+    of the client id taken before then (a ``Run``'s paragraph id, the id
+    ``add_paragraph`` promotes to a list item) still names the client id. Only
+    the docx-studio pod that applied the create can resolve that id when the
+    replicas share no client-id map, so a later batch that reaches another pod
+    fails with ``block "p_…" not found``.
+    """
+    if not resolved or not dataclasses.is_dataclass(cmd):
+        return
+    for f in dataclasses.fields(cmd):
+        if f.name in _MINTED_ID_FIELDS:
+            continue
+        value = getattr(cmd, f.name)
+        new = _with_resolved_ids(value, resolved)
+        if new is not value:
+            setattr(cmd, f.name, new)
+
+
 _WRITES_UNAPPLIED = "_docx_writes_unapplied"
 
 
@@ -551,6 +593,10 @@ class CommandBuffer:
         # ``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]]] = {}
+        # client id → real id of every create a batch landed, so a command
+        # that still names a client id is sent with the real one
+        # (:func:`_resolve_client_ids`).
+        self._resolved_client_ids: dict[str, str] = {}
         # The last command's ``GetNodeById`` key, result and time, while
         # nothing has been sent or buffered after it (see :meth:`call`), for a
         # docx-studio that gives no version.
@@ -866,6 +912,7 @@ class CommandBuffer:
                 user = None if self._user is None else dict(self._user)
             version = self._version_request()
             sent_at = _now()
+            self._resolve_drained(cmds)
             try:
                 outcome = self._client.execute_batch(
                     self._asset_id,
@@ -944,6 +991,7 @@ class CommandBuffer:
         proxy's ``_node_id`` in-place.
         """
         self.ensure_usable()
+        _resolve_client_ids(cmd, self._resolved_client_ids)
         # A write whose text holds a character XML does not allow raises
         # python-docx's ValueError here, before anything is sent: every command
         # comes through, a path-proxy op's and a direct ``send_command``'s.
@@ -1073,6 +1121,7 @@ class CommandBuffer:
             self._proxy_id_refs = {}
         if not pending:
             return []
+        self._resolve_drained(pending)
         try:
             results, _skipped_by_index = self._client.execute_batch(
                 self._asset_id,
@@ -1088,7 +1137,9 @@ class CommandBuffer:
             # batch ships REAL ids for the survivors (vs. dead client
             # UUIDs that would cascade into another "Block not found").
             # See ``_apply_proxy_id_rewrites`` for the full rationale.
-            _apply_proxy_id_rewrites(_extract_partial_results(exc), proxy_id_refs)
+            _apply_proxy_id_rewrites(
+                _extract_partial_results(exc), proxy_id_refs, self._resolved_client_ids
+            )
             _ptc_emit_end_batch(pending, is_error=True)
             _unapplied_writes(exc)
             raise
@@ -1099,7 +1150,7 @@ class CommandBuffer:
         finally:
             _forget_reads_of_others(self)
         _ptc_emit_end_batch(pending, is_error=False)
-        _apply_proxy_id_rewrites(results, proxy_id_refs)
+        _apply_proxy_id_rewrites(results, proxy_id_refs, self._resolved_client_ids)
         return results
 
     def close(self) -> None:
@@ -1126,6 +1177,14 @@ class CommandBuffer:
 
     # ----- internals -----
 
+    def _resolve_drained(self, cmds: "list[Command]") -> None:
+        """Point ``cmds``, about to be sent under ``_post_lock``, at the real
+        ids every earlier batch returned: one queued while the idle timer's
+        batch with its create was still in flight missed that id in
+        :meth:`call`."""
+        for queued in cmds:
+            _resolve_client_ids(queued, self._resolved_client_ids)
+
     def _eager_flush_with(self, cmd: Command) -> Any:
         """Drain pending + run ``cmd`` in one batch; return cmd's result.
 
@@ -1151,6 +1210,7 @@ class CommandBuffer:
             self._proxy_id_refs = {}
             writes = self._writes
         all_cmds: list[Command] = [*pending, cmd]
+        self._resolve_drained(all_cmds)
         trailing_index = len(all_cmds) - 1
         # A batch that answers a read asks for the document's version (a
         # docx-studio that predates it ignores the question).
@@ -1175,7 +1235,9 @@ class CommandBuffer:
             # ``table.cell(0, 0)`` → ``tables.get``), so a failure on
             # the trailing ``cmd`` would otherwise abandon every
             # buffered Create's rewrite at once.
-            _apply_proxy_id_rewrites(_extract_partial_results(exc), proxy_id_refs)
+            _apply_proxy_id_rewrites(
+                _extract_partial_results(exc), proxy_id_refs, self._resolved_client_ids
+            )
             _ptc_emit_end_batch([cmd], is_error=True)
             if pending:
                 self._settle_writes_of_failed_read(
@@ -1198,7 +1260,7 @@ class CommandBuffer:
         # Proxy-id rewrites still run for the buffered prefix that DID apply —
         # the trailing skip (if any) doesn't strand the supported Creates that
         # flushed alongside it.
-        _apply_proxy_id_rewrites(results, proxy_id_refs)
+        _apply_proxy_id_rewrites(results, proxy_id_refs, self._resolved_client_ids)
         # This is the AWAITED-result path: the caller is about to read the
         # trailing command's result. If the server skipped that command
         # (capability gap), there is no result to return — returning some
@@ -1260,11 +1322,13 @@ class CommandBuffer:
             # ``MAX_BATCH_COMMANDS``: those a failed request's earlier ones
             # applied keep their ids, as a flush's do, and only the rest are
             # the failure's unapplied writes.
-            _apply_proxy_id_rewrites(_extract_partial_results(again), proxy_id_refs)
+            _apply_proxy_id_rewrites(
+                _extract_partial_results(again), proxy_id_refs, self._resolved_client_ids
+            )
             _ptc_emit_end_batch(pending, is_error=True)
             raise _unapplied_writes(again) from exc
         _ptc_emit_end_batch(pending, is_error=False)
-        _apply_proxy_id_rewrites(results, proxy_id_refs)
+        _apply_proxy_id_rewrites(results, proxy_id_refs, self._resolved_client_ids)
         _as_the_read_s_own_failure(exc, failed)
 
     def _reset_timer_locked(self) -> None:

{athena_python_docx-0.42.0 → athena_python_docx-0.42.1}/docx/_http.py

@@ -141,7 +141,10 @@ def create_empty_document(
         )
 
     url: str = resolved_base.rstrip("/") + "/docs/empty"
-    body: dict[str, str] = {}
+    # The document is born as its creator's: its first write is signed as the
+    # caller, with the agent run's attributions when the script runs in one
+    # (``X-Custom-Attributions``), so the run's turn replay starts with it.
+    body: dict[str, str] = {"seedAuthor": "requester"}
     if name is not None:
         body["name"] = name
     if parent_folder_id is not None:
@@ -152,6 +155,7 @@ def create_empty_document(
     # Lazy import — _http is loaded lazily by Document.create(), so the
     # package is fully initialized by the time we reach this code.
     from docx import __version__
+    from docx._http_doc import _delegation_headers
 
     payload: bytes = json.dumps(body).encode("utf-8")
     req = urllib.request.Request(  # noqa: S310
@@ -163,6 +167,7 @@ def create_empty_document(
             "Authorization": f"Bearer {resolved_key}",
             "Accept": "application/json",
             "User-Agent": f"athena-python-docx/{__version__}",
+            **_delegation_headers(),
         },
     )
 
@@ -308,7 +313,16 @@ def upload_document(
     with open(docx_path, "rb") as f:
         file_bytes: bytes = f.read()
 
-    create_body: dict[str, str] = {"name": title}
+    # The document is born holding the uploaded file: the create seeds no
+    # template (``seed_template``), and the import below is its first write,
+    # signed as the caller with the agent run's attributions when the script
+    # runs in one (``seed_author``, ``X-Custom-Attributions``). An agora that
+    # predates both seeds the template, which the overwrite import replaces.
+    create_body: dict[str, str | bool] = {
+        "name": title,
+        "seed_author": "requester",
+        "seed_template": False,
+    }
     if parent_folder_id is not None:
         create_body["parent_folder_id"] = parent_folder_id
     if workspace_id is not None:
@@ -317,6 +331,7 @@ def upload_document(
     create_url: str = resolved_agora_base.rstrip("/") + "/api/docx-studio/assets"
 
     from docx import __version__
+    from docx._http_doc import _delegation_headers
 
     req = urllib.request.Request(  # noqa: S310
         create_url,
@@ -327,6 +342,7 @@ def upload_document(
             "Authorization": f"Bearer {resolved_key}",
             "Accept": "application/json",
             "User-Agent": f"athena-python-docx/{__version__}",
+            **_delegation_headers(),
         },
     )
 
@@ -374,6 +390,7 @@ def upload_document(
     import_body = {
         "docx_base64": base64.b64encode(file_bytes).decode("ascii"),
         "overwrite": True,
+        "seed_author": "requester",
     }
     import_req = urllib.request.Request(  # noqa: S310
         import_url,
@@ -384,6 +401,7 @@ def upload_document(
             "Authorization": f"Bearer {resolved_key}",
             "Accept": "application/json",
             "User-Agent": f"athena-python-docx/{__version__}",
+            **_delegation_headers(),
         },
     )
 

{athena_python_docx-0.42.0 → athena_python_docx-0.42.1}/docx/_http_doc.py

@@ -33,6 +33,7 @@ from __future__ import annotations
 import dataclasses
 import json
 import os
+import re
 import urllib.parse
 import warnings
 from typing import Any, TypedDict
@@ -477,6 +478,9 @@ _PARAGRAPH_TARGETING_COMMANDS: frozenset[str] = frozenset(
 )
 
 
+# The id ``Document._mint_client_node_id`` gives a node it creates.
+_SDK_MINTED_ID = re.compile(r"[a-z]+_[0-9a-f]{12}")
+
 _CELL_PARAGRAPH_HINT: str = (
     "\n\nHint: DOCX Studio 1.8.1 cannot format paragraphs nested inside "
     "table cells via SetParagraphAlignment / SetParagraphStyle / "
@@ -534,6 +538,15 @@ _TABLE_QUERY_COMMANDS: frozenset[str] = frozenset(
 )
 
 
+_SDK_CLIENT_ID_HINT: str = (
+    "\n\nHint: this id is one the SDK minted for a block it created "
+    "(``p_xxxxxxxxxxxx``), not one docx-studio assigned. The create that "
+    "minted it failed or was discarded in an earlier batch, or it belongs "
+    "to a previous execution. This is not a table-cell problem: re-read "
+    "the block (``doc.paragraphs`` / ``doc.tables``) and use the proxy it "
+    "returns, or create the block again."
+)
+
 _TABLE_CLIENT_ID_HINT: str = (
     "\n\nHint: this looks like a stale client-side table UUID "
     "(``t_xxxxxxxxxxxx``). Either an earlier batch in this execution "
@@ -882,8 +895,12 @@ def _http_post_json(
                     isinstance(cmd_type, str) and cmd_type in _PARAGRAPH_TARGETING_COMMANDS
                 )
                 table_query = isinstance(cmd_type, str) and cmd_type in _TABLE_QUERY_COMMANDS
-                if _missing_block_id(err_obj.get("message")) in header_footer_block_ids:
+                missing = _missing_block_id(err_obj.get("message"))
+                if missing in header_footer_block_ids:
                     hint = _HEADER_FOOTER_PARAGRAPH_HINT
+                elif missing is not None and _SDK_MINTED_ID.fullmatch(missing):
+                    # A block this SDK created, not a cell's own paragraph.
+                    hint = _SDK_CLIENT_ID_HINT
                 elif paragraph_targeting:
                     hint = _CELL_PARAGRAPH_HINT
                 elif table_query:

{athena_python_docx-0.42.0 → athena_python_docx-0.42.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-docx"
-version = "0.42.0"
+version = "0.42.1"
 description = "Drop-in replacement for python-docx that connects to Athena's DOCX Studio collaborative document stack"
 readme = "README.md"
 license = "MIT"

{athena_python_docx-0.42.0 → athena_python_docx-0.42.1}/tests/live/fixture_scripts.py

@@ -752,6 +752,44 @@ FIXTURE_SCRIPTS: list[FixtureScript] = [
             'row.cells[0].text = "Delta"\n'
         ),
     ),
+    FixtureScript(
+        # Writes to a table merged the legacy way (w:hMerge), which python-docx
+        # reads as written, each w:tc its own cell: text added after the
+        # nested table of a merge's first cell, a merge's first cell and a
+        # cell that continues it rewritten, bold on a row's runs, and a row
+        # added. The export writes each cell's w:hMerge back, as python-docx
+        # keeps it.
+        name="fixture-tables-horizontal-merges-writes",
+        fixture="tables-horizontal-merges",
+        script=(
+            "table = doc.tables[0]\n"
+            'table.cell(0, 0).paragraphs[-1].add_run("Issued")\n'
+            'table.cell(2, 0).text = "Merged text rewritten"\n'
+            'table.cell(2, 1).text = "Continued"\n'
+            "for run in table.cell(1, 3).paragraphs[0].runs:\n"
+            "    run.bold = True\n"
+            "row = table.add_row()\n"
+            'row.cells[0].text = "Beta"\n'
+        ),
+    ),
+    FixtureScript(
+        # Writes to tables whose rows of one cell set no span in a grid of two
+        # columns: python-docx reads such a row's one cell as written, and
+        # writes it so; a row added after one, and a column added, as
+        # python-docx adds them (a w:tc in every row).
+        name="fixture-tables-implied-span-writes",
+        fixture="tables-implied-span",
+        script=(
+            "form = doc.tables[0]\n"
+            'form.rows[2].cells[0].text = "Reviewed"\n'
+            'form.rows[4].cells[0].paragraphs[0].add_run(" (internal)")\n'
+            'form.rows[5].cells[1].text = "Closed"\n'
+            "closing = doc.tables[1]\n"
+            "row = closing.add_row()\n"
+            'row.cells[0].text = "Total"\n'
+            "closing.add_column(Pt(72))\n"
+        ),
+    ),
     FixtureScript(
         # Writes to a footer part written with a header's root element and to
         # a header part written with a footer's: python-docx edits the part's

{athena_python_docx-0.42.0 → athena_python_docx-0.42.1}/tests/test_block_not_found_error.py

@@ -123,6 +123,30 @@ def test_insert_block_not_found_carries_cell_hint() -> None:
     )
 
 
+def test_sdk_minted_id_block_not_found_names_the_stale_client_id() -> None:
+    """A miss on an id the SDK minted (``p_<12 hex>``) is a create that never
+    landed, not a cell paragraph: the hint says so instead of the cell one."""
+
+    def _capture(url: str, **kwargs: Any) -> _FakeResponse:  # noqa: ARG001
+        return _FakeResponse(
+            status_code=207,
+            body=_partial_failure_body(
+                cmd_type="Insert",
+                message='Block "p_7b3a2a6afbf3" not found.',
+            ),
+        )
+
+    client = HttpClient(base_url="https://example.com", api_key="bg_key")
+
+    with patch.object(client._session, "post", side_effect=_capture):
+        with pytest.raises(BlockNotFoundError) as exc_info:
+            _execute_setalignment(client)
+
+    msg = str(exc_info.value)
+    assert "the SDK minted" in msg
+    assert "cell.add_paragraph" not in msg
+
+
 def test_non_paragraph_command_block_not_found_skips_hint() -> None:
     """A ``Block ... not found`` miss on a non-paragraph-targeting
     command (a stale image id from ``SetImageSize``, a deleted list

{athena_python_docx-0.42.0 → athena_python_docx-0.42.1}/tests/test_buffer.py

@@ -670,3 +670,89 @@ def test_discard_all_skips_stale_buffers() -> None:
             buf.close()
         finally:
             begin_execution(None)
+
+
+class _EchoingClient(_FakeClient):
+    """Answers each create with its real id, as docx-studio echoes it."""
+
+    def execute_batch(
+        self, asset_id: str, commands: list[Command], **kw: Any
+    ) -> tuple[list[Any], dict[int, dict[str, Any]]]:
+        super().execute_batch(asset_id, commands, **kw)
+        results: list[Any] = []
+        for cmd in commands:
+            cli = getattr(cmd, "client_node_id", None)
+            results.append({"client_node_id": cli, "real_node_id": f"REAL-{cli}"} if cli else {})
+        return results, {}
+
+
+def test_a_client_id_copied_before_its_create_landed_is_sent_as_the_real_id() -> None:
+    """``add_paragraph(style="List Bullet")`` and ``p.add_run().add_break()``
+    keep the paragraph's client id; when a read flushed the create first, the
+    next batch may reach a docx-studio pod that never minted it."""
+    fake = _EchoingClient()
+    buf = CommandBuffer(fake, "asset_1", auto_flush_seconds=0.0)
+    buf.call(CreateParagraph(text="one", at={"kind": "documentEnd"}, client_node_id="p_abc"))
+    buf.flush()
+    buf.call(
+        Replace(
+            target={
+                "kind": "selection",
+                "start": {"kind": "text", "blockId": "p_abc", "offset": 0},
+            },
+            text="y",
+        )
+    )
+    buf.call(
+        CreateParagraph(
+            text="two", at={"kind": "after", "target": {"nodeId": "p_abc"}}, client_node_id="p_def"
+        )
+    )
+    buf.flush()
+    replace, create = fake.batches[1]
+    assert replace.target == {
+        "kind": "selection",
+        "start": {"kind": "text", "blockId": "REAL-p_abc", "offset": 0},
+    }
+    assert create.at == {"kind": "after", "target": {"nodeId": "REAL-p_abc"}}
+    assert create.client_node_id == "p_def"
+    buf.close()
+
+
+class _HeldEchoingClient(_EchoingClient):
+    """An echoing client whose first batch waits for ``release``."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.sent = threading.Event()
+        self.release = threading.Event()
+
+    def execute_batch(
+        self, asset_id: str, commands: list[Command], **kw: Any
+    ) -> tuple[list[Any], dict[int, dict[str, Any]]]:
+        if not self.batches:
+            self.sent.set()
+            assert self.release.wait(5)
+        return super().execute_batch(asset_id, commands, **kw)
+
+
+def test_a_command_queued_while_its_create_is_in_flight_is_sent_as_the_real_id() -> None:
+    """The idle timer's batch carries the create; an edit queued before that
+    batch answers still goes out naming the paragraph by its real id."""
+    fake = _HeldEchoingClient()
+    buf = CommandBuffer(fake, "asset_1", auto_flush_seconds=0.0)
+    buf.call(CreateParagraph(text="one", at={"kind": "documentEnd"}, client_node_id="p_abc"))
+    in_flight = threading.Thread(target=buf.flush)
+    in_flight.start()
+    assert fake.sent.wait(5)
+    buf.call(
+        CreateParagraph(
+            text="two", at={"kind": "after", "target": {"nodeId": "p_abc"}}, client_node_id="p_def"
+        )
+    )
+    fake.release.set()
+    in_flight.join(5)
+    buf.flush()
+    (create,) = fake.batches[1]
+    assert create.at == {"kind": "after", "target": {"nodeId": "REAL-p_abc"}}
+    buf.close()

{athena_python_docx-0.42.0 → athena_python_docx-0.42.1}/tests/test_document_create.py

@@ -153,12 +153,54 @@ def test_create_request_body_includes_optional_fields() -> None:
     assert captured["url"] == "https://example.com/docs/empty"
     assert captured["headers"]["Authorization"] == "Bearer bg_test_key"
     assert captured["body"] == {
+        "seedAuthor": "requester",
         "name": "explicit",
         "parentFolderId": "folder_abc",
         "workspaceId": "ws_explicit",
     }
 
 
+def test_create_asks_for_a_document_born_as_its_agent_run(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """In an agent run the create carries the run's attributions, so the
+    document's first write is the run's and its turn replay starts there."""
+    monkeypatch.setenv(
+        "ATHENA_DOCX_CUSTOM_ATTRIBUTIONS",
+        "agent_id:athena_assist_agent,session_id:thread_1,tool_call_id:call_1",
+    )
+    captured: dict[str, Any] = {}
+
+    def _capture(req: Any, **_kwargs: Any) -> _FakeResponse:
+        captured["headers"] = {k.lower(): v for k, v in req.header_items()}
+        captured["body"] = json.loads(req.data.decode("utf-8"))
+        return _FakeResponse(json.dumps(_FAKE_RESPONSE).encode("utf-8"))
+
+    with patch("docx._http.urllib.request.urlopen", side_effect=_capture):
+        Document.create(name="Report", base_url="https://example.com", api_key="k")
+
+    assert captured["body"]["seedAuthor"] == "requester"
+    assert captured["headers"]["x-custom-attributions"] == (
+        "agent_id:athena_assist_agent,session_id:thread_1,tool_call_id:call_1"
+    )
+
+
+def test_create_outside_a_run_sends_no_attributions(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("ATHENA_DOCX_CUSTOM_ATTRIBUTIONS", raising=False)
+    captured: dict[str, Any] = {}
+
+    def _capture(req: Any, **_kwargs: Any) -> _FakeResponse:
+        captured["headers"] = {k.lower(): v for k, v in req.header_items()}
+        return _FakeResponse(json.dumps(_FAKE_RESPONSE).encode("utf-8"))
+
+    with patch("docx._http.urllib.request.urlopen", side_effect=_capture):
+        Document.create(name="Report", base_url="https://example.com", api_key="k")
+
+    assert "x-custom-attributions" not in captured["headers"]
+
+
 def test_create_prefers_user_key_over_studio_key(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:

{athena_python_docx-0.42.0 → athena_python_docx-0.42.1}/tests/test_document_create_from_template.py

@@ -89,6 +89,7 @@ def test_upload_document_creates_asset_then_imports_docx(
     """upload_document() should create the asset, then import the .docx bytes."""
     monkeypatch.setenv("ATHENA_DOCX_API_KEY", "bg_test_key")
     monkeypatch.setenv("ATHENA_DOCX_BASE_URL", "https://docx-studio.stg.athenaintel.com")
+    monkeypatch.setenv("ATHENA_DOCX_CUSTOM_ATTRIBUTIONS", "session_id:thread_1")
 
     captured: list[dict[str, Any]] = []
 
@@ -99,6 +100,7 @@ def test_upload_document_creates_asset_then_imports_docx(
                 "method": req.get_method(),
                 "content_type": req.get_header("Content-type"),
                 "auth": req.get_header("Authorization"),
+                "attributions": req.get_header("X-custom-attributions"),
                 "body": json.loads(bytes(req.data).decode("utf-8")),
             },
         )
@@ -125,10 +127,15 @@ def test_upload_document_creates_asset_then_imports_docx(
     assert create_req["method"] == "POST"
     assert create_req["content_type"] == "application/json"
     assert create_req["auth"] == "Bearer bg_test_key"
+    # The document is born holding the file: no template seed, and the import
+    # is its first write, the run's.
     assert create_req["body"] == {
         "name": "My Template Seeded Doc",
+        "seed_author": "requester",
+        "seed_template": False,
         "workspace_id": "ws_explicit",
     }
+    assert create_req["attributions"] == "session_id:thread_1"
     assert (
         import_req["url"] == "https://agora.stg.athenaintel.com/api/docx-studio/assets/"
         "asset_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/import"
@@ -137,6 +144,8 @@ def test_upload_document_creates_asset_then_imports_docx(
     assert import_req["content_type"] == "application/json"
     assert import_req["auth"] == "Bearer bg_test_key"
     assert import_req["body"]["overwrite"] is True
+    assert import_req["body"]["seed_author"] == "requester"
+    assert import_req["attributions"] == "session_id:thread_1"
     assert base64.b64decode(import_req["body"]["docx_base64"]) == b"PK\x03\x04fake-docx-bytes"
 
 

{athena_python_docx-0.42.0 → athena_python_docx-0.42.1}/uv.lock

@@ -8,7 +8,7 @@ resolution-markers = [
 
 [[package]]
 name = "athena-python-docx"
-version = "0.42.0"
+version = "0.42.1"
 source = { editable = "." }
 dependencies = [
     { name = "athena-references" },