Synchronous and asynchronous Python clients for the OGuardAI API with session context managers and typed error handling

The oguardai-sdk package provides synchronous and asynchronous clients for the OGuardAI API.

Install

pip install oguardai-sdk

Sync Usage

Basic Transform and Rehydrate

from guardai_sdk import OGuardAIClient

client = OGuardAIClient(base_url="http://localhost:3000")

# Transform: replace PII with semantic tokens
result = client.transform(
    "Contact Julia Schneider at julia@firma.de",
    policy="default",
)

print(result.safe_text)
# "Contact `{{person:p_001}}` at `{{email:e_001}}`"

# Send safe_text to your LLM
llm_response = call_your_llm(result.safe_text)

# Rehydrate: restore real values
restored = client.rehydrate(
    llm_response,
    session_state=result.session_state,
    output_channel="customer_email",
    restore_mode="formatted",
)

print(restored.restored_text)
# "Dear Frau Julia Schneider, ..."

client.close()

Context Manager

with OGuardAIClient(base_url="http://localhost:3000") as client:
    result = client.transform("Hello, I am John Smith", policy="default")
    # ...

Detect Only

result = client.detect("Email: test@example.com, SSN: 123-45-6789")
for entity in result.entities:
    print(f"{entity.type}: {entity.value} (confidence={entity.confidence})")

Health Check

health = client.health()
print(health.status)  # "healthy"

Async Usage

import asyncio
from guardai_sdk import AsyncOGuardAIClient

async def main():
    async with AsyncOGuardAIClient(base_url="http://localhost:3000") as client:
        result = await client.transform(
            "Contact Julia Schneider at julia@firma.de",
            policy="default",
        )
        print(result.safe_text)

        restored = await client.rehydrate(
            "Dear `{{person:p_001}}`, thank you.",
            session_state=result.session_state,
            output_channel="customer_email",
        )
        print(restored.restored_text)

asyncio.run(main())

Session Context Manager

For multi-turn conversations, SessionContext automatically carries session state between calls:

Sync Sessions

from guardai_sdk import OGuardAIClient, SessionContext

client = OGuardAIClient(base_url="http://localhost:3000")

with SessionContext(client, policy="german-support") as session:
    # Turn 1
    turn1 = session.transform("Ich bin Anna Mueller, Kundennummer 948221")
    print(turn1.safe_text)
    # "Ich bin `{{person:p_001}}`, Kundennummer `{{customer_id:cid_001}}`"

    llm_reply = "Guten Tag `{{person:p_001}}`, wie kann ich helfen?"
    restored = session.rehydrate(llm_reply, channel="customer_email")
    print(restored.restored_text)

    # Turn 2: entities are deduplicated across turns
    turn2 = session.transform("Meine E-Mail ist anna@example.com")
    # Anna Mueller is still p_001

Async Sessions

from guardai_sdk import AsyncOGuardAIClient, AsyncSessionContext

async def chat():
    async with AsyncOGuardAIClient(base_url="http://localhost:3000") as client:
        async with AsyncSessionContext(client, policy="default") as session:
            turn1 = await session.transform("Hello, I'm John Smith")
            # ... call LLM ...
            restored = await session.rehydrate(llm_output, channel="user_output")

Error Handling

from guardai_sdk import (
    OGuardAIClient,
    OGuardAIError,
    ValidationError,
    AuthError,
    SessionExpiredError,
    PolicyDeniedError,
)

client = OGuardAIClient(base_url="http://localhost:3000")

try:
    result = client.transform("some text", policy="nonexistent")
except ValidationError as e:
    # 400/422: malformed request
    print(f"Invalid request: {e}")
except AuthError as e:
    # 401: authentication failed
    print(f"Auth error: {e}")
except SessionExpiredError as e:
    # 410: session TTL elapsed
    print("Session expired, create a new one")
except PolicyDeniedError as e:
    # 403: entity blocked by policy
    print(f"Policy blocked: {e}")
except OGuardAIError as e:
    # Other API error
    print(f"Error [{e.code}]: {e.message}")

Configuration

client = OGuardAIClient(
    base_url="http://localhost:3000",  # Required
    api_key="your-api-key",            # Optional: sent as X-API-Key header
    timeout=30.0,                      # Optional: request timeout in seconds (default: 30)
)

Type Reference

All types are Pydantic models:

from guardai_sdk import (
    TransformRequest,
    TransformResponse,
    RehydrateRequest,
    RehydrateResponse,
    DetectRequest,
    DetectResponse,
    HealthResponse,
    EntityContext,
    EntityType,
    RestoreMode,
    OutputChannel,
)

Python SDK