Metadata-Version: 2.4
Name: onewolf
Version: 4.1.0
Summary: OneWolf AI Security SDK - Guard, Document Shield, Output Filter, RAG Protection
Author: OneWolf Team
License: MIT
Project-URL: Homepage, https://github.com/onewolf-ai/onewolf-guard
Project-URL: Documentation, https://github.com/onewolf-ai/onewolf-guard/tree/main/sdk/python
Keywords: ai-security,llm-guard,prompt-injection,pii-detection,rag-protection
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: async
Requires-Dist: httpx[http2]>=0.25.0; extra == "async"
Provides-Extra: observers
Requires-Dist: wrapt>=1.16; extra == "observers"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"
Requires-Dist: wrapt>=1.16; extra == "dev"
Provides-Extra: e2e
Requires-Dist: pytest>=8.0; extra == "e2e"
Requires-Dist: pytest-timeout>=2.3; extra == "e2e"

# onewolf

OneWolf AI Security SDK for Python — typed sync/async client for the Guard,
Document Shield, Output Filter, RAG Protection and A2A policy APIs. Mirrors the
[TypeScript SDK](https://github.com/onewolf-ai/onewolf-guard/tree/main/sdk/ts/onewolf):
same endpoints, same request bodies, same validation and error behavior.

## What it does

- **Guard (Cerberus):** `analyze(text)` — 3-layer prompt-injection / threat
  detection before your prompt reaches the LLM.
- **Document Shield (Fenrir):** `analyze_document(file)` — multi-layer document
  analysis (threats + PII) for uploads.
- **Output Filter (Anubis):** `filter_output(text)` — PII/credential filtering
  of AI responses, with optional reversible restore via `session_id`.
- **RAG Protection (Orthrus):** `rag_pre_retrieval`, `rag_post_retrieval`,
  `rag_ingest` — query, retrieval and ingestion protection for RAG pipelines.
- **A2A policy:** `a2a_check(caller_agent, callee_agent)` — enforce the org's
  agent-to-agent hop policy.
- **Observer:** `OneWolfObserver().start()` — optional runtime interceptor that
  patches the official `openai`/`anthropic` clients so every prompt is analyzed
  before it leaves the process (requires the `observers` extra).

## Install

```bash
pip install onewolf
```

Optional extras:

```bash
pip install "onewolf[observers]"   # OneWolfObserver (wrapt)
pip install "onewolf[async]"       # HTTP/2 for the async client
```

Python 3.9+ required.

## Quickstart

```python
from onewolf import OneWolf

# Defaults to the OneWolf cloud backend (https://app.onewolf.ai).
# Pass base_url="http://localhost:8001" to target a local endpoint agent.
client = OneWolf(api_key="ow_...")

result = client.analyze("user prompt here")
if result.blocked:
    print(f"blocked: {result.threat_type} (score {result.threat_score})")
elif result.redacted:
    print(f"redacted: {result.masked_text}")
else:
    print("allowed")
```

Async mirror with the same surface:

```python
from onewolf import AsyncOneWolf

async with AsyncOneWolf(api_key="ow_...") as client:
    result = await client.analyze("user prompt here")
```

HTTP errors map to `AuthenticationError` (401), `RateLimitError` (429, with
`retry_after`), `AgentIdentityError` (A2A 403 with `IDENTITY_UNVERIFIED`) and
`OneWolfError` (any other >= 400). Input validation happens client-side before
any HTTP request: `analyze` raises `ValueError` for a non-string or for text
outside the backend contract limits (1..10000 characters).

## API surface

| Method | Endpoint | Result |
| ------ | -------- | ------ |
| `analyze(text)` | `POST /api/v1/analyze` | `GuardResult` |
| `analyze_document(file, filename="document")` | `POST /api/v1/documents/analyze` | `DocumentResult` |
| `filter_output(text, session_id=None)` | `POST /api/v1/extension/filter-output` | `OutputFilterResult` |
| `rag_pre_retrieval(query)` | `POST /api/v1/rag/pre-retrieval` | `RAGPreRetrievalResult` |
| `rag_post_retrieval(documents, query="")` | `POST /api/v1/rag/post-retrieval` | `RAGPostRetrievalResult` |
| `rag_ingest(file, filename="document")` | `POST /api/v1/rag/ingestion` | `RAGIngestionResult` |
| `a2a_check(caller_agent, callee_agent, context=None)` | `POST /api/v1/a2a/check` | `A2ACheckResult` |
| `health()` | `GET /api/health` | free-form JSON |
| `metrics()` | `GET /api/health/metrics` | Prometheus text |

## Configuration

| Setting | Default | Description |
|---|---|---|
| `api_key` (constructor, required) | — | Your OneWolf API key |
| `base_url` (constructor) | `https://app.onewolf.ai` | Backend base URL (same default as the Observer's `DEFAULT_API_URL`) |
| `timeout` (constructor) | `30.0` | HTTP timeout in seconds |
| `agent_credential` (constructor) | `ONEWOLF_AGENT_CREDENTIAL` env var | A2A agent credential, sent as `X-Agent-Credential` exclusively by `a2a_check` |

## Links

- Repository: <https://github.com/onewolf-ai/onewolf-guard>
- Source and docs: [`sdk/python/onewolf`](https://github.com/onewolf-ai/onewolf-guard/tree/main/sdk/python/onewolf)
- Endpoint migration notes: [`sdk/MIGRATION.md`](https://github.com/onewolf-ai/onewolf-guard/blob/main/sdk/MIGRATION.md)

## License

MIT
