Metadata-Version: 2.4
Name: athena-ptc-middleware
Version: 0.1.0
Summary: LangGraph agent middleware that surfaces Athena Programmatic Tool Calling (PTC) sub-events as nested tool cards
License: Proprietary
Requires-Python: >=3.11
Requires-Dist: langchain-core>=1.0
Requires-Dist: langchain>=1.0
Requires-Dist: langgraph>=1.0
Description-Content-Type: text/markdown

# athena-ptc-middleware

LangGraph agent middleware that surfaces **Programmatic Tool Calling (PTC)**
sub-events from Athena's sandboxed SDKs (`athena-python-pptx`,
`athena-python-docx`, `athena-openpyxl`, …) as nested sub-tool-cards on the
parent agent tool call.

The middleware:

1. Runs a small in-process HTTP listener on `127.0.0.1:3101/ptc-events`.
2. Publishes `ATHENA_PTC_URL` in `os.environ` at import time so any bash
   subprocess spawned by the parent agent inherits it.
3. For each tool call, claims a per-call buffer, drains buffered events to the
   LangGraph stream writer as custom events (`ptc_subcall_event`), and attaches
   the final event log to the `ToolMessage.artifact.subgraph_state.messages`
   shape consumed by Olympus.

## Usage

```python
from athena_ptc_middleware import PTCEventsMiddleware
from deepagents import create_deep_agent

graph = create_deep_agent(
    model=...,
    system_prompt=...,
    backend=...,
    tools=...,
    middleware=[PTCEventsMiddleware()],
)
```

Sandboxed SDKs that emit PTC events read `ATHENA_PTC_URL` from their
environment and `POST` JSON events to it. As long as the env var is inherited
by the subprocess where the SDK runs (e.g. `bash` spawned by the agent), the
middleware will surface them.

## Source of truth

This package is published from `python-sdk/athena-ptc-middleware/` in the
`Athena-Intel/demo-app-monorepo` repo. The Athena developer agent
(`sandbox/developer_agent/`) consumes it from PyPI; do not re-vendor the
source into other locations.
