Metadata-Version: 2.4
Name: agentads-nat
Version: 0.1.0
Summary: AgentAds monetization plugin for NVIDIA NeMo Agent Toolkit
Project-URL: Homepage, https://tryagentads.com
Project-URL: Documentation, https://github.com/0xShortx/agentads-nat
Project-URL: Repository, https://github.com/0xShortx/agentads-nat
Author-email: Malte Wagenbach <malte@tryagentads.com>
License-Expression: MIT
Keywords: ads,agent-toolkit,agentads,ai-agents,monetization,nemo,nvidia
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.22; extra == 'dev'
Provides-Extra: nat
Requires-Dist: nvidia-nat>=1.0; extra == 'nat'
Description-Content-Type: text/markdown

# agentads-nat

Monetize AI agents built on NVIDIA NeMo Agent Toolkit with contextual ads. One line to integrate. Never blocks your agent (50ms timeout).

## Install

```bash
pip install agentads-nat
```

With NeMo Agent Toolkit support:

```bash
pip install agentads-nat[nat]
```

## Quick Start

### With NeMo Agent Toolkit

Add to your workflow config:

```yaml
functions:
  monetize:
    _type: agentads_monetize
    publisher_api_key: ${AGENTADS_API_KEY}
    format: suffix        # suffix | citation | followup
    timeout_ms: 50        # never blocks your agent

workflow:
  _type: react_agent
  tool_names: [your_tools, monetize]
  llm_name: your_llm
```

Run:

```bash
export AGENTADS_API_KEY=pub_xxx
nat run --config_file config.yaml --input "What CRM should I use?"
```

### Standalone (any Python agent)

```python
from agentads_nat import AgentAdsConfig, monetize_output

config = AgentAdsConfig(publisher_api_key="pub_xxx")

# Your agent produces a response
response = await my_agent(query)

# One line to monetize
result = await monetize_output(config, response, query=query)
```

### Middleware wrapper

```python
from agentads_nat import AgentAdsConfig, AgentAdsMiddleware

config = AgentAdsConfig(publisher_api_key="pub_xxx")
middleware = AgentAdsMiddleware(config)

# Wrap any async function
monetized_agent = middleware.wrap(my_agent)
result = await monetized_agent("What CRM should I use?")
```

## Ad Formats

| Format | Rendering |
|--------|-----------|
| `suffix` (default) | `---` separator + italic ad below response |
| `citation` | Blockquote with **Sponsored** label |
| `followup` | Italic sponsored suggestion |

## OpenShell Policy

If running inside NVIDIA OpenShell, apply the included network policy:

```bash
openshell policy set agentads --policy policies/agentads.yaml --wait
```

This allows only `POST /v1/bid` to `api.tryagentads.com`.

## How It Works

1. Your agent generates a response normally
2. AgentAds fires a parallel bid request (50ms timeout - never delays your agent)
3. If an ad fills, it's appended to the response in your chosen format
4. If no fill or timeout, the response passes through unchanged

No latency impact. No data leaves beyond the query/response excerpt (500/300 chars max).

## Configuration

| Option | Default | Description |
|--------|---------|-------------|
| `publisher_api_key` | required | Your key from [tryagentads.com](https://tryagentads.com) |
| `format` | `suffix` | Ad rendering format |
| `api_url` | `https://api.tryagentads.com` | API endpoint |
| `timeout_ms` | `50` | Bid timeout (ms) |
| `disabled` | `false` | Kill switch for ads |
| `session_id` | `null` | Session ID for frequency capping |

## Get Your API Key

Sign up at [tryagentads.com](https://tryagentads.com) to get a publisher API key.
