# AgentID Python SDK

Lightweight Python client for the AgentID security platform.

- `guard` -> POST `/guard` (blocking / awaitable, **fail-closed** on errors)
- `log` -> POST `/ingest` (fire-and-forget telemetry)
- OpenAI/LangChain wrappers automatically apply `transformed_input` from Guard (if returned).

Default `base_url`: `https://app.getagentid.com/api/v1`

## Install

```bash
pip install agentid-sdk
```

## Optional: Local-First PII Masking (Reversible)

```bash
pip install "agentid-sdk[pii]"
```

## Optional: Enhanced Injection Security Stack

```bash
pip install "agentid-sdk[security]"
```

## Sync Example

```python
import time
from agentid import AgentID
from openai import OpenAI

agent = AgentID(api_key="sk_live_...", pii_masking=True)
openai = agent.wrap_openai(
    OpenAI(api_key="..."),
    system_id="...",
    user_id="system-auto-summary",  # optional service/user identity for audit
)

# Guard + logging happens automatically for chat.completions.create
start = time.perf_counter()
resp = openai.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "You are helpful."},
        {"role": "user", "content": "User prompt"},
    ],
)
latency_ms = int((time.perf_counter() - start) * 1000)

print(resp.choices[0].message.content, latency_ms)
```

## Async Example

```python
import asyncio
from agentid import AsyncAgentID
from openai import AsyncOpenAI

async def main():
    async with AsyncAgentID(api_key="sk_live_...") as agent:
        openai = agent.wrap_openai(
            AsyncOpenAI(api_key="..."),
            system_id="...",
            user_id="system-auto-summary",  # optional service/user identity for audit
        )
        resp = await openai.chat.completions.create(
            model="gpt-4o-mini",
            messages=[{"role": "user", "content": "User prompt"}],
        )
        print(resp.choices[0].message.content)

asyncio.run(main())
```

## Security Notes

- Never print or log your API key.
- AgentID prioritizes security. If the gateway is unreachable, the SDK fails closed to prevent unmonitored PII leaks.

## LangChain (Python) Callback

```python
from agentid import AgentID, AgentIDCallbackHandler

agent = AgentID(api_key="sk_live_...")
handler = AgentIDCallbackHandler(agent, system_id="...")

# Then pass `handler` into LangChain callbacks (exact wiring depends on your chain/LLM):
# callbacks=[handler]
```
