shadow-warden-sdk
Python SDK for the Shadow Warden AI security gateway.
Install
pip install shadow-warden-sdk
Quick start
from shadow_warden import WardenClient
with WardenClient(gateway_url="http://localhost:8001", api_key="sk_...") as warden:
result = warden.filter("Summarise the contract for client@example.com")
if result.allowed:
# safe to forward to your AI model
...
else:
print("Blocked:", result.risk_level, result.flag_names)
OpenAI wrapper (drop-in)
import openai
from shadow_warden import WardenClient
warden = WardenClient(api_key="sk_warden_...")
client = warden.wrap_openai(openai.OpenAI(api_key="sk-openai-..."))
# Identical to the standard OpenAI API — Warden intercepts transparently
response = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "..."}],
raise_on_block=True, # raises WardenBlockedError if blocked
)
Async
from shadow_warden import AsyncWardenClient
async with AsyncWardenClient(gateway_url="...", api_key="...") as warden:
result = await warden.filter("user prompt")
Batch filtering
results = warden.filter_batch([
"What is the capital of France?",
{"content": "My SSN is 123-45-6789", "strict": True},
])
Fail-open mode
# If the gateway is unreachable, return a permissive result instead of raising
warden = WardenClient(fail_open=True)
Configuration
| Parameter | Default | Description |
|---|---|---|
gateway_url |
http://localhost:8001 |
Warden gateway base URL |
api_key |
"" |
X-API-Key header value |
tenant_id |
"default" |
Default tenant for all requests |
timeout |
10.0 |
HTTP timeout in seconds |
fail_open |
False |
Return permissive result on network errors |
Error handling
from shadow_warden import WardenBlockedError, WardenGatewayError, WardenTimeoutError
try:
result = warden.filter(content, raise_on_block=True)
except WardenBlockedError as e:
print("Blocked:", e.result.risk_level)
except WardenTimeoutError:
print("Gateway timeout")
except WardenGatewayError as e:
print(f"HTTP {e.status_code}: {e.detail}")
FilterResult fields
| Field | Type | Description |
|---|---|---|
allowed |
bool |
Whether the content passed all filters |
blocked |
bool |
Convenience inverse of allowed |
risk_level |
str |
low / medium / high / block |
filtered_content |
str |
Content after PII redaction |
secrets_found |
list[SecretFinding] |
Detected secrets/PII |
semantic_flags |
list[SemanticFlag] |
Triggered semantic rules |
flag_names |
list[str] |
Shorthand for flag names |
has_secrets |
bool |
True if any secrets were found |
has_pii |
bool |
True if pii_detected flag is present |
processing_ms |
dict[str, float] |
Per-stage timing breakdown |
Agentic commerce
ShadowWardenClient carries the mandate, order, spend and MCP-intent calls, and
SecureAgent is the mixin that gives any agent class mandate-controlled
purchasing:
from shadow_warden import SecureAgent
class ProcurementAgent(SecureAgent):
def run(self, task: str):
if self.filter_prompt(task).get("blocked"):
raise ValueError("task blocked")
self.create_mandate(max_amount=200.0)
return self.purchase({"store_url": "shop.example.com", "items": [...]})
OpenTelemetry
pip install "shadow-warden-sdk[otel]" adds WardenSpanProcessor, which filters
span attributes through the gateway before they are exported.
Metadata
Release files for shadow-warden-sdk 1.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| shadow_warden_sdk-1.1.0.tar.gz | 21.4 kB | Without provenance | Details for shadow_warden_sdk-1.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| shadow_warden_sdk-1.1.0-py3-none-any.whl | Python 3 | none | any | Details for shadow_warden_sdk-1.1.0-py3-none-any.whl |
Total release size: 40.7 kB
Release files / shadow_warden_sdk-1.1.0.tar.gz
| Download URL | shadow_warden_sdk-1.1.0.tar.gz |
|---|---|
| Size | 21.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
46ccc524f85a55c97b3c45d7b6833dada95a8b6f248faddb00f0e64891992f40
|
|
BLAKE2b-256 checksum How to use checksums |
a14613409d08322fac76b11087e2ef786f5e1a3cd076b4c66b58a493c3b46095
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Release files / shadow_warden_sdk-1.1.0-py3-none-any.whl
| Download URL | shadow_warden_sdk-1.1.0-py3-none-any.whl |
|---|---|
| Size | 19.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
838c09d85096a5c8520d6537665b1333a8cae744425841da99a4094494ee38fb
|
|
BLAKE2b-256 checksum How to use checksums |
23df5e5773ab9400e6a7fbf9d7ec3312430eccb871f4ede928507f113f302490
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Security for shadow-warden-sdk 1.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.