Metadata-Version: 2.4
Name: novyx-openai-agents
Version: 0.1.0
Summary: Governance, audit, and rollback for OpenAI Agents SDK — powered by Novyx Core
Author-email: Novyx Labs <blake@novyxlabs.com>
Maintainer-email: Novyx Labs <blake@novyxlabs.com>
License: MIT
Project-URL: Homepage, https://novyxlabs.com
Project-URL: Documentation, https://docs.novyxlabs.com
Project-URL: Repository, https://github.com/novyxlabs/novyx-core
Keywords: openai,openai-agents,agents-sdk,agent,ai,memory,audit,rollback,governance,compliance,novyx
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: novyx>=3.4.0
Requires-Dist: openai-agents<0.15,>=0.14.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"

# novyx-openai-agents

**Governance, audit, and rollback for the OpenAI Agents SDK.** Drop-in `RunHooks` that wire every agent run into Novyx Core's tamper-evident audit chain, create rollback-capable checkpoints at safe boundaries, and sync memory into Novyx's cross-session semantic store.

```python
from agents import Agent, Runner
from novyx_openai_agents import NovyxRunHooks

agent = Agent(name="my-agent", instructions="...", tools=[...])
hooks = NovyxRunHooks(api_key="...", agent_id="my-agent")

result = await Runner.run(agent, "user input", hooks=hooks)

# Every tool call + model turn is now in Novyx's SHA-256 audit chain.
# If the run went sideways, roll back to the latest checkpoint:
await hooks.rollback_to_latest()
```

## Why

OpenAI's Agents SDK v0.14.0 (2026-04-15) added a powerful execution layer: `SandboxAgent`, workspace memory, snapshots + resume, hosted sandbox providers. What it did **not** add:

- **Tamper-evident audit chains** — you can trace a run, but you can't prove after the fact that nothing was edited
- **Policy-gated action approvals** — no pre-tool policy evaluation, no approval flow
- **Transactional rollback** — snapshots resume interrupted work; they don't rewind a mission's governed state
- **Cross-session semantic memory** — sandbox memory is workspace-scoped, great for resuming a task, less useful for "what did this agent learn six months ago across five different workspaces"

This package fills those gaps without replacing any of OpenAI's primitives. You keep using `Agent`, `Runner`, `SandboxAgent`, whatever — `NovyxRunHooks` is additive.

## Status: alpha (v0.1.0)

Phase 0 scaffold shipped 2026-04-15, the same day as OpenAI's v0.14.0 release. What's wired up and what isn't:

| Surface | Status |
|---|---|
| Trace open / step / close on lifecycle events | ✅ |
| Memory write at agent end | ✅ |
| Checkpoint create at handoffs and agent end | ✅ |
| Rollback to latest checkpoint | ✅ |
| Pre-tool policy gate via `check_policy` (block / pause for approval) | 🔲 Phase 1 |
| Sandbox memory ↔ Novyx memory sync (seed agent context from prior Novyx memories) | 🔲 Phase 1 |
| Policy-block returns a refusal to the agent instead of raising | 🔲 Phase 1 |
| Runtime v2 mission surfacing in Novyx Console (`/ui/missions/{id}`) | 🔲 Phase 1 (depends on console-rewrite PR #8 + event-emission work) |
| Streaming audit events via SSE for live console updates | 🔲 Phase 2 |

## Install

```bash
pip install novyx-openai-agents
# or directly from source during development:
pip install -e packages/novyx-openai-agents
```

Requires `openai-agents>=0.14.0` and `novyx>=3.4.0`.

## Relationship to OpenAI v0.14.0 features

This package **complements** OpenAI's new primitives; it doesn't duplicate them.

| OpenAI v0.14.0 | Novyx | Use both because |
|---|---|---|
| Sandbox (Cloudflare/Vercel/Modal/E2B/…) | — | Novyx doesn't sandbox; it trusts whatever runtime you pick |
| Workspace memory (extracted lessons, workspace-scoped) | Cross-session semantic memory (vectorized, tagged, tenant-scoped) | Workspace memory for local task continuity; Novyx memory for "what does this agent know across every run it's ever done" |
| Snapshot + resume (workspace filesystem state) | Transactional checkpoint + rollback (mission state, memory pointers, capability bindings) | Snapshots for resuming interrupted work; checkpoints for rewinding governed state after a bad decision |
| Unified sandbox tracing | SHA-256 tamper-evident audit chain with `audit_verify` | Traces for debugging; audit chain for compliance and forensics |
| — | Policy engine + approval workflow (novyx-control) | OpenAI has no governance layer; Novyx wraps the run in one |

## How it works

`NovyxRunHooks` implements OpenAI's `agents.lifecycle.RunHooks` interface. On each event (`on_agent_start`, `on_tool_start`, `on_tool_end`, `on_handoff`, `on_llm_start`, `on_llm_end`, `on_agent_end`), it forwards to three focused bridges:

- **`NovyxAuditBridge`** — opens a Novyx trace on agent start, appends typed steps per event, closes the trace on end. Every step enters the SHA-256 hash chain.
- **`NovyxMemoryBridge`** — writes the agent's final output (plus any notable tool results in Phase 1) as Novyx memory entries tagged with `agent:{id}` and `session:{id}`.
- **`NovyxCheckpointBridge`** — creates Novyx Runtime v2 checkpoints at safe boundaries (handoffs, agent end). Exposes `rollback_latest(mission_id=…)`.

All three bridges are best-effort: if Novyx is unreachable, lifecycle events log a warning and the agent run continues. Auditing should never be a reason for an agent to fail in production.

## Example

See `examples/basic.py` for a minimal working demo.

## License

MIT. See `LICENSE` (copied from the monorepo root).

## Links

- [Novyx Core](https://novyxlabs.com)
- [OpenAI Agents SDK](https://github.com/openai/openai-agents-python)
- Issues and PRs: [novyxlabs/novyx-core](https://github.com/novyxlabs/novyx-core)
