Metadata-Version: 2.4
Name: phionyx-openai-agents
Version: 0.1.0a1
Summary: OpenAI Agents SDK tracing bridge for Phionyx runtime evidence — every Trace and Span emitted by the SDK becomes a signed, hash-chained envelope entry.
Author-email: Ali Toygar Abak <founder@phionyx.ai>
License: AGPL-3.0-or-later
Project-URL: Homepage, https://phionyx.ai/runtime-evidence
Project-URL: Repository, https://github.com/halvrenofviryel/phionyx_openai_agents
Project-URL: Documentation, https://phionyx.ai/start
Keywords: openai-agents,agents-sdk,ai-governance,runtime-evidence,audit-chain,agent-observability,phionyx
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: phionyx-core>=0.4.0
Requires-Dist: pydantic>=2.0
Requires-Dist: cryptography>=42.0
Provides-Extra: sdk
Requires-Dist: openai-agents>=0.0.1; extra == "sdk"
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.23; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Dynamic: license-file

# phionyx-openai-agents

> **Status:** alpha (v0.1.0a1) — TracingProcessor adapter live; 37 tests pass; PyPI publish pending founder authorisation.

OpenAI Agents SDK tracing bridge for [Phionyx](https://phionyx.ai/runtime-evidence) runtime evidence.

Every `Trace` and `Span` emitted by the [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/) is recorded as a signed, hash-chained envelope entry. Phionyx provides the trust-object substrate above the SDK's own tracing — observability records *what happened*, Phionyx makes it *verifiable*.

## Why

The OpenAI Agents SDK ships its own tracing (`add_trace_processor`, `BatchTraceProcessor`, `BackendSpanExporter`) optimised for *debugging* and *internal observability*. It is not optimised for *third-party verification*: the trace stream is mutable, unsigned, and exported to the operator's choice of backend. Phionyx envelopes are immutable, hash-chained, and signed under the operator's Ed25519 key — they survive review even when the agent and the trace store are not trusted.

## Install

```bash
pip install phionyx-openai-agents          # core
pip install "phionyx-openai-agents[sdk]"   # + openai-agents SDK
```

Until v0.1.0a1 ships to PyPI, install from source:

```bash
pip install -e tools/phionyx_openai_agents
```

## 60-second usage

```python
from agents import add_trace_processor
from phionyx_openai_agents import PhionyxTracingProcessor

processor = PhionyxTracingProcessor()    # default HmacSigner + filesystem store
add_trace_processor(processor)

# ... run any Agents SDK workflow ...

print(f"{len(processor.envelopes)} signed envelopes")
print(f"Chain verifies: {processor.verify_chain()['ok']}")
processor.export_envelopes("evidence/run.jsonl")
```

A complete runnable example (works with or without the SDK installed)
is in [`examples/quickstart.py`](examples/quickstart.py):

```bash
pip install -e tools/phionyx_openai_agents
python tools/phionyx_openai_agents/examples/quickstart.py
```

Expected output (mocked-SDK mode):

    Mode        : mocked Trace/Span
    Envelopes   : 8 ({'trace_start': 1, 'span_start': 2, 'span_end': 2, 'processor_flush': 1, 'trace_end': 1, 'processor_shutdown': 1})
    Verify chain: OK (8 envelopes; 0 errors)
    Exported    : 8 envelopes → /tmp/phionyx-oai-demo-XXXXXXXX/quickstart-evidence.jsonl

## Span trees

The processor preserves `parent_id` linkage in every envelope payload, so verifiers can reconstruct the full span tree:

```python
# A typical workflow: supervisor → worker → tool
on_trace_start(trace)
on_span_start(root)                              # parent_id = None
on_span_start(child, parent_id=root.span_id)     # parent_id = "sp-root"
on_span_start(grand, parent_id=child.span_id)    # parent_id = "sp-child"
on_span_end(grand)
on_span_end(child)
on_span_end(root)
on_trace_end(trace)
```

Each `span_start` envelope's payload exposes `parent_id` and `span_id`; together with `trace_id` you can reconstruct any tree shape offline without reading the SDK's own trace stream.

## Status — what's live in v0.1.0a1

- ✅ **PhionyxTracingProcessor** — all 6 SDK `TracingProcessor` methods
  (`on_trace_start/end`, `on_span_start/end`, `shutdown`, `force_flush`)
  emit signed envelopes.
- ✅ **AgentMessageEnvelope** as the inner record (from
  `phionyx_core.contracts.envelopes`).
- ✅ **HmacSigner** demo + **Signer** protocol for Ed25519 swap.
- ✅ **FilesystemEnvelopeStore** with `PHIONYX_OPENAI_AGENTS_AUDIT_ROOT`
  env-var override.
- ✅ **`verify_chain`** — detects payload tamper + broken links.
- ✅ **`export_envelopes`** — JSONL round-trip preserves chain
  byte-exact and re-verifies under module-level helper.
- ✅ **Cross-thread emission lock** — 5-thread × 20-callback test
  yields a dense `[0..99]` turn-index sequence; no race conditions.
- ✅ **Defensive serialization** — minimally-attributed Trace/Span
  objects degrade to `unknown` / `None`, never crash.
- ✅ **`register()` defers SDK import** — package loads cleanly
  without `openai-agents` installed.
- ✅ **37 tests** — smoke, envelope chain, extended scenarios
  (multi-span tree, parent_id chains, error spans, 100-event chain,
  concurrent callbacks, lifecycle edges, JSONL round-trip).

Roadmap beyond v0.1.0a1: PyPI publish (gated on founder authorisation),
v0.1.0 stable schema lock alongside `phionyx-core` v0.5.0, audit_chain
promotion into `phionyx_core` for shared use across all companion packages.

## audit_chain vendoring

This package vendors a copy of `audit_chain.py` from `phionyx-langchain-langgraph`. The two copies differ only in namespace constants (schema id, runtime tag, default audit root, env var, HMAC secret prefix); the canonical-JSON discipline and hash format are identical, so verifiers written once apply to both companion packages. For v0.5.0 stable, `audit_chain` will be promoted into `phionyx_core` and the companion packages will share one canonical implementation.

## License

AGPL-3.0-or-later. Commercial dual-license available — contact founder@phionyx.ai.

## See also

- [phionyx.ai/runtime-evidence](https://phionyx.ai/runtime-evidence) — long-form thesis
- `phionyx-core` (PyPI) — core envelope schema + Ed25519 signing
- `phionyx-langchain-langgraph` (PyPI) — LangChain + LangGraph bridge companion
- `phionyx-mcp-server` (PyPI) — MCP trust boundary companion
- `phionyx-pipeline-mcp` (PyPI) — agent self-claim gate companion
- `phionyx-eval-inspect` (PyPI) — UK AISI Inspect bridge companion
