Metadata-Version: 2.4
Name: athena-ptc-emitter
Version: 0.1.0
Summary: Stdlib-only PTC event emitter shared by Athena's sandboxed authoring SDKs (athena-python-pptx, athena-python-docx, athena-openpyxl)
License: Proprietary
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 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](../../docs/PROGRAMMATIC_TOOL_CALLING_GUIDE.md) 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

```python
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`](../../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.
