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

# API Reference

> Complete reference for the quint-agent Python SDK.

## `quint_agent.init()`

Initialize the global Quint client. Must be called before any `@guard()` calls. Idempotent — calling twice returns the same client.

```python theme={null}
def init(
    *,
    api_key: str | None = None,        # or QUINT_API_KEY env var
    endpoint: str | None = None,        # default: https://api.quintai.dev/v1/sdk/events
    policy: Policy | dict | str | None = None,  # YAML file path, dict, or Policy object
) -> Client
```

| Parameter  | Default                                 | Description                                  |
| ---------- | --------------------------------------- | -------------------------------------------- |
| `api_key`  | `$QUINT_API_KEY`                        | SDK API key (starts with `qak_`)             |
| `endpoint` | `https://api.quintai.dev/v1/sdk/events` | Cloud ingest endpoint                        |
| `policy`   | Built-in default                        | Security policy (YAML path, dict, or Policy) |

**Raises:** `QuintConfigError` if `api_key` is missing.

## `@quint_agent.guard()`

Decorator that wraps a tool function with capture and policy enforcement.

```python theme={null}
def guard(*, name: str | None = None) -> Callable
```

| Parameter | Default       | Description                         |
| --------- | ------------- | ----------------------------------- |
| `name`    | Function name | Override the tool name in telemetry |

Works with both sync and async functions:

```python theme={null}
@quint_agent.guard()
def sync_tool(path: str) -> str: ...

@quint_agent.guard(name="custom_name")
async def async_tool(url: str) -> dict: ...
```

**Raises:** `ToolBlockedError` if the call violates policy.

## `Client`

The underlying client object. Usually you don't interact with it directly — `init()` creates a global singleton.

```python theme={null}
class Client:
    api_key: str
    endpoint: str
    policy: Policy
    policy_engine: PolicyEngine
    transport: Transport
    sdk_version: str
```

## `Policy`

A collection of rules evaluated against each tool call.

```python theme={null}
class Policy:
    rules: list[Rule]
```

## `Rule`

A single policy rule.

```python theme={null}
class Rule:
    name: str
    action: Action          # Action.BLOCK or Action.ESCALATE
    reason: str
    conditions: list[Matcher]
```

## `Decision`

The result of evaluating a tool call against the policy.

```python theme={null}
class Decision:
    action: Action          # ALLOW, BLOCK, or ESCALATE
    matched_rule: Rule | None
    reason: str | None
```

## Exceptions

```python theme={null}
class QuintError(Exception):
    """Base class for all quint-agent exceptions."""

class QuintConfigError(QuintError):
    """Raised when init() is called with invalid configuration."""

class ToolBlockedError(QuintError):
    """Raised when @guard() blocks a tool call due to policy."""
    tool_name: str
    rule_name: str
    reason: str
```

## Environment variables

| Variable         | Description                                                |
| ---------------- | ---------------------------------------------------------- |
| `QUINT_API_KEY`  | SDK API key (alternative to passing `api_key` to `init()`) |
| `QUINT_ENDPOINT` | Override the cloud endpoint URL                            |
| `QUINT_POLICY`   | Path to a YAML policy file                                 |

## Transport

Events are batched in-memory and flushed asynchronously every 500ms (or when the buffer reaches 100 events). The transport is non-blocking — `@guard()` never waits for the HTTP POST to complete.

```
@guard() call → emit() → in-memory queue → background flush → POST /v1/sdk/events
                                                                    ↓
                                                             Quint cloud
```

Failed flushes retry with exponential backoff (1s, 2s, 4s, max 30s). After 5 consecutive failures, events are dropped with a stderr warning.