> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goantiai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Full documentation for the Anti AI Python SDK.

## Installation

```bash theme={null}
pip install oculus-sdk
```

## Quick reference

```python theme={null}
from oculus_sdk import OculusClient
from oculus_sdk.exceptions import OculusAuthError, OculusAPIError, TokenRevokedException

client = OculusClient(
    client_id="your-client-id",
    client_secret="your-client-secret",
    base_url="https://api.antiailabs.com",
)

token = client.get_token(scope="db:read")
token = await client.aget_token(scope="db:read")
token = client.get_token(scope="db:read stripe:customer:read")
token = client.get_token(scope="db:read", audience="https://myservice.example.com")

client.stop()  # on shutdown
```

## Full example

```python theme={null}
import os
import atexit
import httpx
from oculus_sdk import OculusClient
from oculus_sdk.exceptions import OculusAuthError, OculusAPIError, TokenRevokedException

client = OculusClient(
    client_id=os.environ["AGENT_CLIENT_ID"],
    client_secret=os.environ["AGENT_CLIENT_SECRET"],
    base_url=os.environ.get("ANTI_AI_URL", "https://api.antiailabs.com"),
)
atexit.register(client.stop)

def call_api(endpoint: str, scope: str) -> dict:
    try:
        token = client.get_token(scope=scope)
    except TokenRevokedException:
        raise RuntimeError("Agent access has been revoked. Contact your admin.")
    except OculusAuthError as e:
        raise RuntimeError(f"Authentication failed: {e}")
    except OculusAPIError as e:
        raise RuntimeError(f"Anti AI error: {e}")

    response = httpx.get(endpoint, headers={"Authorization": f"Bearer {token}"})
    response.raise_for_status()
    return response.json()
```

## Token caching

The SDK caches tokens in memory keyed by `(scope, audience)`. Tokens are reused until 10 seconds before expiry. You never manage token lifetimes.

## Exception reference

| Exception               | When raised                                  | What to do                             |
| ----------------------- | -------------------------------------------- | -------------------------------------- |
| `OculusAuthError`       | Invalid credentials, agent suspended/revoked | Check credentials; verify agent status |
| `OculusAPIError`        | Any other API error                          | Check `e.status_code` and `e.details`  |
| `TokenRevokedException` | Cached token revoked                         | Alert your team — this is intentional  |