neutralai-sdk 0.1.0

Official NeutralAI Python SDK for masking sensitive prompt data before it reaches AI applications.

NeutralAI Python SDK

Package Status

Final public package name: neutralai-sdk.

Public PyPI publication is in progress. Do not show python -m pip install neutralai-sdk on public website pages until the release workflow has published the package and the registry verification step passes.

Install (local workspace)

pip install -e .

For async web services and batch workers, install the async extra:

pip install -e ".[async]"

After public PyPI publication is complete:

python -m pip install "neutralai-sdk[async]"

Usage (sync)

from neutralai_sdk import NeutralAIClient

client = NeutralAIClient(base_url="http://localhost:8001", api_key="test-key")
res = client.mask("My email is [e-mail]", reversible=False)
print(res.masked_text)

Usage (async)

import asyncio
from neutralai_sdk import AsyncNeutralAIClient

async def main():
    async with AsyncNeutralAIClient(base_url="http://localhost:8001", api_key="test-key") as client:
        res = await client.mask("Call me at [phone]")
        print(res.masked_text)

asyncio.run(main())

The async client keeps one httpx.AsyncClient open for connection pooling and retries transient 408, 429, and 5xx responses by default.

Usage (async streaming)

import asyncio
from neutralai_sdk import AsyncNeutralAIClient

async def main():
    async with AsyncNeutralAIClient(
        base_url="http://localhost:8001",
        service_token="signed-service-token",
    ) as client:
        async for event in client.chat_stream(
            session_id="session-123",
            prompt="Summarize this text",
            provider="openai",
            model="gpt-4-turbo",
        ):
            if event.type == "token":
                print(event.token, end="")

asyncio.run(main())

Integration registry

The SDK includes a small dependency-free adapter registry for framework wrappers. The default registry exposes langchain, and teams can register their own adapters without adding optional framework dependencies to the core package.

from neutralai_sdk import NeutralAIClient, create_integration

client = NeutralAIClient(base_url="http://localhost:8001", agent_token="agent-token")
guard = create_integration("langchain", client, target_agent_id="agent-target")
safe_input = guard.sanitize_input({"input": "Email [e-mail]"})

Supported Endpoints

• POST /v1/shield/mask
• POST /v1/shield/unmask
• POST /v1/agents/mask
• POST /v1/chat/stream

POST /v1/shield/unmask requires tenant-scoped authentication via API key or service token and only restores reversible vault tokens that still match the stored scope and TTL.

Async Throughput

Use asyncio.gather with one shared AsyncNeutralAIClient to run many requests concurrently while reusing pooled connections:

async with AsyncNeutralAIClient(base_url="https://api.neutralai.co.uk", api_key="...") as client:
    results = await asyncio.gather(*(client.mask(prompt) for prompt in prompts))

In internal local benchmarks with mocked 100 ms network latency, 50 concurrent async requests complete about 10x faster than the same requests issued sequentially through the sync client because the async version overlaps network wait time.

To reproduce the local latency benchmark shape:

python sdk/python/examples/async_benchmark.py

Observability Hooks

You can pass observability_hook to capture SDK request lifecycle events:

• request_start
• request_success
• request_error

Diagnostics are redacted by default:

• API keys/tokens are reported as <REDACTED>
• prompt/tokenized values are summarized as <REDACTED len=N>

License

MIT — see LICENSE. This SDK is a thin, dependency-light HTTP client for the NeutralAI Gateway API; all PII detection and masking happens server-side.