# agentid-sdk (Python)

[![PyPI version](https://img.shields.io/pypi/v/agentid-sdk.svg)](https://pypi.org/project/agentid-sdk/)
[![Python](https://img.shields.io/pypi/pyversions/agentid-sdk.svg)](https://pypi.org/project/agentid-sdk/)
[![Python >=3.9](https://img.shields.io/badge/python-%3E%3D3.9-3776AB.svg)](https://pypi.org/project/agentid-sdk/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

## 1. Introduction

`agentid-sdk` is the official Python SDK for AgentID, an AI security and compliance System of Record. It lets you enforce guardrails before model execution, capture immutable telemetry for auditability, and integrate security checks into OpenAI and LangChain workflows with minimal code.

### The Mental Model

AgentID sits between your application and the LLM runtime:

```text
User Input -> guard() -> [AgentID Policy] -> verdict
                              | allowed
                              v
                         LLM Provider
                              v
                           log() -> [Immutable Ledger]
```

- `guard()`: evaluates prompt and context before model execution.
- Model call: executes only if guard verdict is allowed.
- `log()`: persists immutable telemetry (prompt, output, latency) for audit and compliance.

## 2. Installation

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

Optional extras:

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

## 3. Prerequisites

1. Create an AgentID account at `https://app.getagentid.com`.
2. Create an AI system and copy:
   - `AGENTID_API_KEY` (for example `sk_live_...`)
   - `AGENTID_SYSTEM_ID` (UUID)
3. If using OpenAI/LangChain, set:
   - `OPENAI_API_KEY`

```bash
export AGENTID_API_KEY="sk_live_..."
export AGENTID_SYSTEM_ID="00000000-0000-0000-0000-000000000000"
export OPENAI_API_KEY="sk-proj-..."
```

### Compatibility

- **Node.js:** v18+ / **Python:** 3.9+ (cross-SDK matrix)
- **Thread Safety:** AgentID clients are thread-safe and intended to be instantiated once and reused across concurrent requests.
- **Latency:** async `log()` is non-blocking for model execution paths; sync `guard()` typically adds network latency (commonly ~50-100ms, environment-dependent).

## 4. Quickstart

```python
import os
from agentid import AgentID

agent = AgentID()  # auto-loads AGENTID_API_KEY
system_id = os.environ["AGENTID_SYSTEM_ID"]

verdict = agent.guard(
    input="Summarize this support ticket.",
    system_id=system_id,
    model="gpt-4o-mini",
    user_id="quickstart-user",
)
if not verdict.get("allowed", False):
    raise RuntimeError(f"Blocked: {verdict.get('reason')}")

agent.log(
    system_id=system_id,
    input="Summarize this support ticket.",
    output="Summary generated.",
    model="gpt-4o-mini",
    event_id=verdict.get("client_event_id"),
    metadata={"agent_role": "support-assistant"},
)
print("Guard allowed + telemetry logged")
```

## 5. Core Integrations

### OpenAI Wrapper

```python
import os
from openai import OpenAI
from agentid import AgentID, SecurityBlockError

agent = AgentID(pii_masking=True)
openai = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
secured = agent.wrap_openai(
    openai,
    system_id=os.environ["AGENTID_SYSTEM_ID"],
    user_id="customer-123",
)

try:
    response = secured.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "What is the capital of the Czech Republic?"}],
    )
    print(response.choices[0].message.content)
except SecurityBlockError as exc:
    print("Blocked by AgentID:", exc.reason)
```

### LangChain Integration

```bash
pip install agentid-sdk openai langchain langchain-openai
```

```python
import os
from langchain_core.prompts import PromptTemplate
from langchain_core.output_parsers import StrOutputParser
from langchain_openai import ChatOpenAI
from agentid import AgentID, AgentIDCallbackHandler

agent = AgentID()
handler = AgentIDCallbackHandler(agent, system_id=os.environ["AGENTID_SYSTEM_ID"])

prompt = PromptTemplate.from_template("Answer in one sentence: {question}")
model = ChatOpenAI(model="gpt-4o-mini", api_key=os.environ["OPENAI_API_KEY"])
chain = prompt | model | StrOutputParser()

result = chain.invoke(
    {"question": "What is the capital of the Czech Republic?"},
    config={"callbacks": [handler]},
)
print(result)
```

### Raw Ingest API (Telemetry Only)

```python
import os
from agentid import AgentID

agent = AgentID()
agent.log(
    system_id=os.environ["AGENTID_SYSTEM_ID"],
    event_type="complete",
    severity="info",
    model="gpt-4o-mini",
    input="Raw telemetry prompt",
    output='{"ok": true}',
    metadata={"agent_role": "batch-worker", "channel": "manual_ingest"},
)
```

## 6. Advanced Configuration

### Custom identity / role metadata

Use `user_id` for actor identity and `metadata` for additional context (for example `agent_role`, environment, trace IDs).

```python
verdict = agent.guard(
    input="Process user request",
    system_id=system_id,
    user_id="service:billing-agent",
)
agent.log(
    system_id=system_id,
    input="Process user request",
    output="Done",
    model="gpt-4o-mini",
    metadata={"agent_role": "billing-agent", "environment": "prod"},
)
```

### Timeouts

```python
agent = AgentID(
    guard_timeout_s=10.0,
    ingest_timeout_s=10.0,
    strict_mode=True,  # fail-closed on connectivity/timeouts
)
```

### Error Handling & Strict Mode

By default, AgentID is designed to keep your application running if the AgentID API has a timeout or is temporarily unreachable.

| Mode | Connectivity Failure | LLM Execution | Best For |
| :--- | :--- | :--- | :--- |
| **Default** (Strict Off) | API Timeout / Unreachable | **Fail-Open** (continues) | Standard SaaS, chatbots |
| **Strict Mode** (`strict_mode=True`) | API Timeout / Unreachable | **Fail-Closed** (blocks) | Healthcare, FinTech, high-risk |

- `guard()` returns a verdict (`allowed`, `reason`); handle deny paths explicitly.
- Wrapped OpenAI/LangChain flows raise `SecurityBlockError` when a prompt is blocked.
- If `strict_mode` is not explicitly set in SDK code, runtime behavior follows the system configuration from AgentID (`strict_security_mode` / `failure_mode`).
- Ingest retries transient failures (5xx/429) and logs warnings if persistence fails.

## 7. Security & Compliance

- Optional local-first reversible PII masking via `PIIManager` and `pii_masking=True`.
- Prompt-injection scanning and policy enforcement run before model dispatch.
- Telemetry logging is async/fire-and-forget to minimize app latency.
- Designed for server, serverless, and background-worker runtimes.
- Supports compliance workflows requiring complete prompt/output traceability.

## 8. Support

- Dashboard: `https://app.getagentid.com`
- Repository: `https://github.com/ondrejsukac-rgb/agentid/tree/main/python-sdk`
- Issues: `https://github.com/ondrejsukac-rgb/agentid/issues`

## 9. Publishing Notes (PyPI)

PyPI renders this `README.md` as package long description.

### `setup.py` projects

```python
from setuptools import setup

with open("README.md", "r", encoding="utf-8") as fh:
    long_description = fh.read()

setup(
    name="agentid-sdk",
    long_description=long_description,
    long_description_content_type="text/markdown",
)
```

### `pyproject.toml` projects

```toml
readme = { file = "README.md", content-type = "text/markdown" }
```
