Metadata-Version: 2.4
Name: openaiguardrails-sdk
Version: 0.2.0
Summary: Official Python client for Open AI Guardrails policy distribution, audit evidence, and OPA control-plane APIs.
Author: Noir Stack LLC
License-Expression: MIT
Project-URL: Homepage, https://openaiguardrails.org/
Project-URL: Documentation, https://openaiguardrails.org/docs/
Project-URL: Runtime Reference, https://openaiguardrails.org/api/reference/
Project-URL: Repository, https://github.com/no1rstack/openaiguardrails
Project-URL: Issues, https://github.com/no1rstack/openaiguardrails/issues
Keywords: ai-safety,guardrails,opa,pdp,bifrost,governance,openai-guardrails
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
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 :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# openaiguardrails-sdk

Official Python client for the [Open AI Guardrails](https://openaiguardrails.org/) runtime API.

The PyPI distribution is published as **`openaiguardrails-sdk`** while PyPI reviews the canonical `openaiguardrails` project name. Import from `openaiguardrails`:

```python
from openaiguardrails import OpenAIGuardrailsClient
```

## Install

```sh
pip install openaiguardrails-sdk
```

## Quick start

```python
from openaiguardrails import OpenAIGuardrailsClient

client = OpenAIGuardrailsClient(
    base_url="https://openaiguardrails.org",
    token="YOUR_OPENAIGUARDRAILS_API_TOKEN",
)

policy = client.get_policy("prod-safety-alpha")
skills = client.list_skills()
```

Pass a bearer token for protected routes (policy manager, blog review, admin publish). Public catalog and health endpoints work without a token on the hosted API.

`NoirGuardrailsClient` and `NoirGuardrailsError` remain available as aliases.

## API surface

### Core

| Method | HTTP | Auth |
|--------|------|------|
| `health()` | `GET /health` | — |
| `get_openapi()` | `GET /openapi.json` | — |
| `list_entries()` | `GET /api/entries` | — |
| `list_discussions()` | `GET /api/discussions` | — |

### Policy manager & OPA

| Method | HTTP | Auth |
|--------|------|------|
| `list_policies()` | `GET /api/policies` | optional* |
| `get_policy(policy_id)` | `GET /v1/policy/:id` | — |
| `toggle_policy_control(policy_id, key, value)` | `POST /api/policies/:id/toggles` | policy manager |
| `run_policy_action(policy_id, action, **payload)` | `POST /api/policies/:id/actions` | policy manager |
| `export_audit(policy_id)` | `GET /api/policies/:id/audit-export` | policy manager |
| `list_opa_imports()` | `GET /api/opa/imports` | policy manager |
| `import_opa_policy(payload)` | `POST /api/opa/imports` | policy manager |
| `simulate_opa_import(import_id, input)` | `POST /api/opa/imports/:id/simulate` | policy manager |
| `export_opa_import(import_id, target)` | `GET .../export/:target` | policy manager |
| `publish_opa_import(import_id, payload)` | `POST .../publish` | policy manager |

\*Hosted production may require Auth0 when `POLICY_MANAGER_REQUIRE_AUTH=true`.

### Agent Skills platform

| Method | HTTP |
|--------|------|
| `list_skills()` | `GET /api/skills` |
| `get_skill(skill_id)` | `GET /api/skills/:id` |
| `list_professions()` | `GET /api/professions` |
| `get_profession(profession_id)` | `GET /api/professions/:id` |
| `get_mcp_registry()` | `GET /api/mcp/registry` |
| `get_mcp_tool(skill_id)` | `GET /api/mcp/tools/:skillId` |

### Blog workflow

| Method | HTTP | Auth |
|--------|------|------|
| `list_blog_pending_posts()` | `GET /api/blog/pending-posts` | `read:blog_submissions` or admin |
| `submit_blog_post(payload)` | `POST /api/blog/pending-posts` | `submit:blog` or user/admin |
| `get_blog_review(review_id)` | `GET /api/blog/reviews/:id` | `read:blog_submissions` or admin |
| `approve_blog_review(review_id, payload)` | `POST .../approve` | `manage:blog` or admin |
| `reject_blog_review(review_id, payload)` | `POST .../reject` | `manage:blog` or admin |
| `publish_blog_review(review_id, payload)` | `POST .../publish` | `manage:blog` or admin |
| `publish_blog_post(payload)` | `POST /api/blog/publish` | `manage:blog` or admin |

### Operations

| Method | HTTP | Auth |
|--------|------|------|
| `get_smtp_status()` | `GET /api/ops/smtp-status` | `manage:system` or admin |

Use `request(path, method=..., body=...)` for forward-compatible access to new OpenAPI routes.

## Errors

Failed responses raise `OpenAIGuardrailsError` with `status` and parsed `body`.

## Requirements

- Python 3.9+
- Standard library only (no third-party dependencies)

## Links

- [Documentation](https://openaiguardrails.org/docs/)
- [API reference](https://openaiguardrails.org/api/reference/)
- [Packages](https://openaiguardrails.org/projects/pypi-packages)

## Changelog

See [CHANGELOG.md](./CHANGELOG.md).
