QuantaWatch Python SDK

Python SDK for QuantaWatch — the post-quantum security layer for AI agents.

Route your AI SDK traffic through the QuantaWatch gateway for threat detection, policy enforcement, and tamper-evident audit logging — all signed with post-quantum cryptography (ML-DSA-65).

Installation

Not yet published to PyPI. Install from source until the first release.

git clone https://github.com/dyber-pqc/QuantaWatch.git
pip install -e QuantaWatch/sdk/python

Requirements: Python 3.10+

Quick Start

Option 1: Protect an existing AI client (recommended)

The protect() wrapper transparently routes your existing SDK's HTTP traffic through the gateway. No code changes needed beyond the wrap call.

from anthropic import Anthropic
from quantawatch import protect

# One line — all API calls now flow through QuantaWatch
client = protect(Anthropic(), gateway_url="http://localhost:9090")

# Use the client exactly as before
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)

Works with any httpx-based SDK, including OpenAI:

from openai import OpenAI
from quantawatch import protect

client = protect(OpenAI(), gateway_url="http://localhost:9090")
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)

Option 2: Use the gateway client directly

The QuantaWatchClient gives you direct access to the gateway proxy and admin API.

import asyncio
from quantawatch import QuantaWatchClient

async def main():
    async with QuantaWatchClient() as qw:
        # Proxy a raw request through the gateway
        response = await qw.proxy_request(
            "POST",
            "/v1/messages",
            headers={
                "x-api-key": "sk-ant-...",
                "anthropic-version": "2023-06-01",
                "Content-Type": "application/json",
            },
            body=b'{"model":"claude-sonnet-4-20250514","max_tokens":1024,"messages":[{"role":"user","content":"Hello!"}]}',
        )
        print(response.status_code, response.text)

        # Query the admin API
        sessions = await qw.get_sessions()
        stats = await qw.get_stats()
        audit = await qw.get_audit_entries(limit=10)

        # Verify audit chain integrity
        result = await qw.verify_audit_chain()
        print("Audit chain valid:", result.get("valid"))

asyncio.run(main())

API Reference

protect(client, *, gateway_url="http://localhost:9090")

Wraps an AI SDK client so its HTTP traffic flows through the QuantaWatch gateway.

Returns a proxy object that behaves identically to the original client.

QuantaWatchClient

Async client for the QuantaWatch gateway and admin APIs.

QuantaWatchClient(
    gateway_url="http://localhost:9090",
    admin_url="http://localhost:9091",
    timeout=30.0,
)

Types

All response types are Pydantic models:

• SessionInfo — Gateway session with agent name, token count, PQC key fingerprint
• AuditEntry — Signed audit log entry with sequence number and hash chain
• GatewayStats — Aggregate stats (sessions, requests, threats, audit entries)
• ThreatAssessment — Threat analysis result with severity and blocked status
• DetectedThreat — Individual threat with category, severity, confidence, and pattern name

Prerequisites

The SDK requires a running QuantaWatch gateway. Start one with Docker:

git clone https://github.com/dyber-pqc/QuantaWatch.git
cd QuantaWatch
cp quantawatch.yaml.example quantawatch.yaml
export ANTHROPIC_API_KEY=sk-ant-...
docker compose up -d

Or build from source:

cargo run -p qw-gateway -- quantawatch.yaml

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Type checking (if mypy installed)
mypy quantawatch/

License

Apache License 2.0

Links

• QuantaWatch repository
• OpenAPI spec
• Examples