# Superagent Guard Python SDK
Python client for sending commands to the Superagent Guard endpoint.
## Installation
```bash
pip install superagent-ai
```
## Local development with uv
From the repository root, install the package (including test extras) and create a managed virtual environment:
```bash
cd guard/python
uv sync --extra tests
```
This will provision `.venv`, install the SDK in editable mode, and pull in the testing dependencies. Once synced, run the test suite with:
```bash
uv run pytest tests
```
## Quick start
```python
import asyncio
from superagent_ai import create_guard
async def main() -> None:
guard = create_guard(
api_base_url="https://example.com/api/guard",
api_key="sk-...",
)
result = await guard(
"Generate a friendly greeting",
on_block=lambda reason: print("Guard blocked:", reason),
on_pass=lambda: print("Guard passed"),
)
if result.rejected:
print("Rejected with:", result.reasoning)
else:
print("Approved", result.decision)
await guard.aclose()
asyncio.run(main())
```
### Options
- `api_base_url` – fully qualified URL for your Guard endpoint.
- `api_key` – API key provisioned in Superagent.
- `timeout` – optional request timeout (defaults to 10 seconds).
- `client` – optionally provide your own configured `httpx.AsyncClient`.
- `mode` – operation mode: `"analyze"` (default), `"redact"`, or `"full"`.
The returned `GuardResult` includes both the raw analysis payload from the Guard endpoint and the parsed decision for straightforward policy enforcement.
## Operation Modes
### Analyze Mode (Default)
Performs guard security analysis via API without redaction:
```python
import asyncio
from superagent_ai import create_guard
async def main() -> None:
guard = create_guard(
api_base_url="https://example.com/api/guard",
api_key="sk-...",
mode="analyze", # Default mode
)
result = await guard("Write a hello world script")
# Returns: GuardResult(rejected=False, decision={...}, usage={...})
await guard.aclose()
asyncio.run(main())
```
### Redact Mode
Redacts sensitive PII/PHI data only, without making an API call:
```python
import asyncio
from superagent_ai import create_guard
async def main() -> None:
guard = create_guard(
api_base_url="https://example.com/api/guard",
api_key="sk-...",
mode="redact", # No API call, redaction only
)
result = await guard("My email is john@example.com and SSN is 123-45-6789")
print(result.redacted)
# Output: "My email is <REDACTED_EMAIL> and SSN is <REDACTED_SSN>"
await guard.aclose()
asyncio.run(main())
```
### Full Mode
Performs guard analysis AND includes redacted text in the result:
```python
import asyncio
from superagent_ai import create_guard
async def main() -> None:
guard = create_guard(
api_base_url="https://example.com/api/guard",
api_key="sk-...",
mode="full", # Both analysis and redaction
)
result = await guard("My email is john@example.com")
# Returns: GuardResult with both decision and redacted fields
await guard.aclose()
asyncio.run(main())
```
### Detected PII/PHI Types
The redaction feature detects and replaces:
- **Email addresses** → `<REDACTED_EMAIL>`
- **Social Security Numbers** → `<REDACTED_SSN>`
- **Credit cards** (Visa, Mastercard, Amex) → `<REDACTED_CC>`
- **Phone numbers** (US format) → `<REDACTED_PHONE>`
- **IP addresses** (IPv4/IPv6) → `<REDACTED_IP>`
- **API keys & tokens** → `<REDACTED_API_KEY>`
- **AWS access keys** → `<REDACTED_AWS_KEY>`
- **Bearer tokens** → `Bearer <REDACTED_TOKEN>`
- **MAC addresses** → `<REDACTED_MAC>`
- **Medical record numbers** → `<REDACTED_MRN>`
- **Passport numbers** → `<REDACTED_PASSPORT>`
- **IBAN** → `<REDACTED_IBAN>`
- **ZIP codes** → `<REDACTED_ZIP>`
### GuardResult Fields
```python
@dataclass
class GuardResult:
rejected: bool # True if guard blocked the command
reasoning: str # Explanation from the guard
raw: AnalysisResponse # Full API response
decision: Optional[GuardDecision] # Parsed decision details
usage: Optional[GuardUsage] # Token usage stats
redacted: Optional[str] # Redacted command (if redacted=True)
```
Raw data
{
"_id": null,
"home_page": null,
"name": "superagent-ai",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "superagent, guard, sdk, safety",
"author": "Superagent",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/8b/01/855cb10d754a7f2859477576033a908fc6be620521b25bd4f0160e0c9402/superagent_ai-0.0.9.tar.gz",
"platform": null,
"description": "# Superagent Guard Python SDK\n\nPython client for sending commands to the Superagent Guard endpoint.\n\n## Installation\n\n```bash\npip install superagent-ai\n```\n\n## Local development with uv\n\nFrom the repository root, install the package (including test extras) and create a managed virtual environment:\n\n```bash\ncd guard/python\nuv sync --extra tests\n```\n\nThis will provision `.venv`, install the SDK in editable mode, and pull in the testing dependencies. Once synced, run the test suite with:\n\n```bash\nuv run pytest tests\n```\n\n## Quick start\n\n```python\nimport asyncio\nfrom superagent_ai import create_guard\n\nasync def main() -> None:\n guard = create_guard(\n api_base_url=\"https://example.com/api/guard\",\n api_key=\"sk-...\",\n )\n\n result = await guard(\n \"Generate a friendly greeting\",\n on_block=lambda reason: print(\"Guard blocked:\", reason),\n on_pass=lambda: print(\"Guard passed\"),\n )\n\n if result.rejected:\n print(\"Rejected with:\", result.reasoning)\n else:\n print(\"Approved\", result.decision)\n\n await guard.aclose()\n\nasyncio.run(main())\n```\n\n### Options\n\n- `api_base_url` \u2013 fully qualified URL for your Guard endpoint.\n- `api_key` \u2013 API key provisioned in Superagent.\n- `timeout` \u2013 optional request timeout (defaults to 10 seconds).\n- `client` \u2013 optionally provide your own configured `httpx.AsyncClient`.\n- `mode` \u2013 operation mode: `\"analyze\"` (default), `\"redact\"`, or `\"full\"`.\n\nThe returned `GuardResult` includes both the raw analysis payload from the Guard endpoint and the parsed decision for straightforward policy enforcement.\n\n## Operation Modes\n\n### Analyze Mode (Default)\n\nPerforms guard security analysis via API without redaction:\n\n```python\nimport asyncio\nfrom superagent_ai import create_guard\n\nasync def main() -> None:\n guard = create_guard(\n api_base_url=\"https://example.com/api/guard\",\n api_key=\"sk-...\",\n mode=\"analyze\", # Default mode\n )\n\n result = await guard(\"Write a hello world script\")\n # Returns: GuardResult(rejected=False, decision={...}, usage={...})\n\n await guard.aclose()\n\nasyncio.run(main())\n```\n\n### Redact Mode\n\nRedacts sensitive PII/PHI data only, without making an API call:\n\n```python\nimport asyncio\nfrom superagent_ai import create_guard\n\nasync def main() -> None:\n guard = create_guard(\n api_base_url=\"https://example.com/api/guard\",\n api_key=\"sk-...\",\n mode=\"redact\", # No API call, redaction only\n )\n\n result = await guard(\"My email is john@example.com and SSN is 123-45-6789\")\n\n print(result.redacted)\n # Output: \"My email is <REDACTED_EMAIL> and SSN is <REDACTED_SSN>\"\n\n await guard.aclose()\n\nasyncio.run(main())\n```\n\n### Full Mode\n\nPerforms guard analysis AND includes redacted text in the result:\n\n```python\nimport asyncio\nfrom superagent_ai import create_guard\n\nasync def main() -> None:\n guard = create_guard(\n api_base_url=\"https://example.com/api/guard\",\n api_key=\"sk-...\",\n mode=\"full\", # Both analysis and redaction\n )\n\n result = await guard(\"My email is john@example.com\")\n # Returns: GuardResult with both decision and redacted fields\n\n await guard.aclose()\n\nasyncio.run(main())\n```\n\n### Detected PII/PHI Types\n\nThe redaction feature detects and replaces:\n\n- **Email addresses** \u2192 `<REDACTED_EMAIL>`\n- **Social Security Numbers** \u2192 `<REDACTED_SSN>`\n- **Credit cards** (Visa, Mastercard, Amex) \u2192 `<REDACTED_CC>`\n- **Phone numbers** (US format) \u2192 `<REDACTED_PHONE>`\n- **IP addresses** (IPv4/IPv6) \u2192 `<REDACTED_IP>`\n- **API keys & tokens** \u2192 `<REDACTED_API_KEY>`\n- **AWS access keys** \u2192 `<REDACTED_AWS_KEY>`\n- **Bearer tokens** \u2192 `Bearer <REDACTED_TOKEN>`\n- **MAC addresses** \u2192 `<REDACTED_MAC>`\n- **Medical record numbers** \u2192 `<REDACTED_MRN>`\n- **Passport numbers** \u2192 `<REDACTED_PASSPORT>`\n- **IBAN** \u2192 `<REDACTED_IBAN>`\n- **ZIP codes** \u2192 `<REDACTED_ZIP>`\n\n### GuardResult Fields\n\n```python\n@dataclass\nclass GuardResult:\n rejected: bool # True if guard blocked the command\n reasoning: str # Explanation from the guard\n raw: AnalysisResponse # Full API response\n decision: Optional[GuardDecision] # Parsed decision details\n usage: Optional[GuardUsage] # Token usage stats\n redacted: Optional[str] # Redacted command (if redacted=True)\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python SDK for Superagent.",
"version": "0.0.9",
"project_urls": null,
"split_keywords": [
"superagent",
" guard",
" sdk",
" safety"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "eddf333cc1aa3ff63ed15b84af4e8e357ccfe4c54c3107e93f437058519f5b77",
"md5": "1cce60b135233a2892766b83f03fb818",
"sha256": "887ba504927c4ae36809e50530fb46e8642f1733b42a9d369d031f8d3ab1ff07"
},
"downloads": -1,
"filename": "superagent_ai-0.0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1cce60b135233a2892766b83f03fb818",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 7544,
"upload_time": "2025-10-06T06:32:16",
"upload_time_iso_8601": "2025-10-06T06:32:16.146314Z",
"url": "https://files.pythonhosted.org/packages/ed/df/333cc1aa3ff63ed15b84af4e8e357ccfe4c54c3107e93f437058519f5b77/superagent_ai-0.0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8b01855cb10d754a7f2859477576033a908fc6be620521b25bd4f0160e0c9402",
"md5": "5833e11c668d770c71ae3fd8d469ae08",
"sha256": "d22bdfd2e98d25f2b062bba348ffcb7151a7c879616006c7367b0d9497f7a65c"
},
"downloads": -1,
"filename": "superagent_ai-0.0.9.tar.gz",
"has_sig": false,
"md5_digest": "5833e11c668d770c71ae3fd8d469ae08",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 10555,
"upload_time": "2025-10-06T06:32:16",
"upload_time_iso_8601": "2025-10-06T06:32:16.957882Z",
"url": "https://files.pythonhosted.org/packages/8b/01/855cb10d754a7f2859477576033a908fc6be620521b25bd4f0160e0c9402/superagent_ai-0.0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-06 06:32:16",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "superagent-ai"
}
JSON