Metadata-Version: 2.4
Name: openai-agents-tonic-textual
Version: 0.1.0
Summary: Tonic Textual PII redaction tools and guardrails for the OpenAI Agents SDK
Project-URL: Homepage, https://www.tonic.ai/textual
Project-URL: Repository, https://github.com/TonicAI/textual-ai-integrations
Author-email: Tonic AI <support@tonic.ai>
License-Expression: MIT
Keywords: agents,guardrails,openai,pii,privacy,redaction,textual,tonic
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security
Requires-Python: <4.0,>=3.10
Requires-Dist: openai-agents>=0.6.0
Requires-Dist: tonic-textual>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff<0.14.0,>=0.13.1; extra == 'dev'
Description-Content-Type: text/markdown

# OpenAI Agents SDK: Tonic Textual

PII detection and redaction tools and guardrails for the [OpenAI Agents SDK](https://github.com/openai/openai-agents-python), powered by [Tonic Textual](https://www.tonic.ai/textual).

Tonic Textual is a transformer-based PII engine supporting 46+ entity types across 50+ languages. This package provides:

- **Function tools** that let agents actively redact PII from text, JSON, HTML, and binary files
- **An input guardrail** that blocks user messages containing PII before they reach the LLM
- **An output guardrail** that catches PII in agent responses before they reach the user

## Installation

```bash
pip install openai-agents-tonic-textual
```

## Authentication

All functions read from the `TONIC_TEXTUAL_API_KEY` environment variable by default:

```bash
export TONIC_TEXTUAL_API_KEY="your-textual-api-key"
```

You can also pass `api_key=` explicitly to any function if you prefer.

## Quick Start

### Tools (agent actively calls redaction)

```python
from agents import Agent, Runner
from openai_agents_tonic_textual import textual_tools

agent = Agent(
    name="PII Redactor",
    instructions="Use the available tools to redact PII from any input.",
    tools=textual_tools(),
)

result = Runner.run_sync(agent, "Redact: John Smith lives at 123 Main St")
print(result.final_output)
```

### Input Guardrail (block PII before it reaches the LLM)

```python
from agents import Agent, Runner, InputGuardrailTripwireTriggered
from openai_agents_tonic_textual import textual_input_guardrail

agent = Agent(
    name="Safe Assistant",
    instructions="You are a helpful assistant.",
    input_guardrails=[textual_input_guardrail()],
)

try:
    result = Runner.run_sync(agent, "My SSN is 123-45-6789")
except InputGuardrailTripwireTriggered as e:
    info = e.guardrail_result.output.output_info
    print(f"PII detected! Redacted: {info['redacted_text']}")
```

### Output Guardrail (catch PII in agent responses)

```python
from agents import Agent, Runner, OutputGuardrailTripwireTriggered
from openai_agents_tonic_textual import textual_output_guardrail

agent = Agent(
    name="Safe Assistant",
    instructions="You are a helpful assistant.",
    output_guardrails=[textual_output_guardrail()],
)

try:
    result = Runner.run_sync(agent, "Tell me about John Smith")
except OutputGuardrailTripwireTriggered as e:
    info = e.guardrail_result.output.output_info
    print(f"PII in output! Redacted: {info['redacted_text']}")
```

### Both Guardrails

```python
from openai_agents_tonic_textual import textual_input_guardrail, textual_output_guardrail

agent = Agent(
    name="Fully guarded assistant",
    instructions="You are a helpful assistant.",
    input_guardrails=[textual_input_guardrail()],
    output_guardrails=[textual_output_guardrail()],
)
```

## Available Tools

| Tool | Description |
|------|-------------|
| `redact_text` | Redact PII from plain text |
| `redact_json` | Redact PII from JSON strings, preserving structure |
| `redact_html` | Redact PII from HTML content, preserving markup |
| `redact_file` | Redact PII from binary files (PDF, JPG, PNG, CSV, TSV) |
| `extract_entities` | Extract PII entities as a JSON array (detection only, no modification) |
| `list_pii_types` | List all 46+ PII entity types Tonic Textual can detect |

## Configuration

### PII Handling Modes

```python
tools = textual_tools(
    generator_default="Synthesis",  # "Off", "Redaction", or "Synthesis"
    generator_config={
        "NAME_GIVEN": "Synthesis",
        "EMAIL_ADDRESS": "Redaction",
        "PHONE_NUMBER": "Off",
    },
)
```

| Mode | Behavior |
|------|----------|
| `Off` | PII is detected but left unchanged |
| `Redaction` | PII is replaced with entity type labels (e.g., `[NAME_GIVEN]`) |
| `Synthesis` | PII is replaced with realistic synthetic values |

### Self-Hosted Deployments

```python
tools = textual_tools(base_url="https://textual.your-company.com")
```

### Guardrail Entity Filtering

Only trigger guardrails for specific PII types:

```python
# Works the same for both input and output guardrails
input_guard = textual_input_guardrail(
    entities=["US_SSN", "CREDIT_CARD"],  # Only block SSNs and credit cards
)

output_guard = textual_output_guardrail(
    entities=["US_SSN", "CREDIT_CARD"],
)
```

## Self-Correcting Error Messages

The tools include built-in format detection. If an agent sends JSON to `redact_text`, the tool returns an error message naming the correct tool (`redact_json`). This enables agents to self-correct without human intervention.
