athena-ptc-emitter

Stdlib-only PTC event emitter shared by Athena's sandboxed authoring SDKs (athena-python-pptx, athena-python-docx, athena-openpyxl).

Each of those SDKs runs inside a Daytona sandbox spawned by Agora's run_python_code tool, and emits begin/end events to the agora-side PTC runtime so every SDK method call surfaces as a nested sub-tool-card under the parent run_python_code tool in Olympus.

Previously each SDK shipped its own byte-identical _ptc.py. This package consolidates them so a bugfix can land in one place, in one release, instead of being cp-ed across three packages with three release pipelines and three Daytona snapshot rebuilds.

Usage

from athena_ptc_emitter import emit_begin, emit_end

call_id = emit_begin(
    tool_name="CreateParagraph",
    args={"text": "hello"},
    asset_id="asset_abc123",  # optional
)
# … do the actual operation …
emit_end(
    call_id=call_id,
    tool_name="CreateParagraph",
    result={"ok": True},
    is_error=False,
)

Behavior

• No-op when ATHENA_PTC_URL is unset — running locally or in tests is silent. emit_begin still returns a valid call-id so call sites don't have to branch on whether PTC is active.
• Synchronous, best-effort. Each emit blocks for the duration of one HTTP POST (sub-ms loopback, ~10ms over the network); transport errors are swallowed. Synchronous-ness matters for the teardown invariant — see the docstring of _emitter._send and docs/plans/2026-05-14-ptc-flush-race.md.
• Per-call URL snapshot. The URL is read at emit_begin and stashed per call_id so a late emit_end always targets the begin-time URL, even if a new sandbox run replaced ATHENA_PTC_URL.
• 64 KB body cap with {"__truncated__": true} substitution.
• 2-second HTTP timeout with no retries.

Wire protocol

See docs/PROGRAMMATIC_TOOL_CALLING_GUIDE.md at the monorepo root for the full begin/end JSON shape, the HMAC token the URL carries, and the receiver side.

Source of truth

This package is published from python-sdk/athena-ptc-emitter/. The three SDK consumers are:

• pptx-studio/python-sdk/ (pptx → published as athena-python-pptx)
• docx-studio/python-sdk/ (docx → published as athena-python-docx)
• xlsx-studio/python-sdk/ (openpyxl → published as athena-openpyxl)

Migration tracking — each SDK is cutover in a separate PR through that SDK's bump skill so each Daytona snapshot rebuild happens in isolation.