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

# Python SDK

> frostwolf: install, client options, methods, and defaults.

```bash theme={null}
pip install frostwolf
```

Requires Python 3.10 or newer. No runtime dependencies. The API is synchronous, as its transport is.

## Client

```python theme={null}
import os
from frostwolf import FrostWolfClient

fw = FrostWolfClient(api_key=os.environ["FROSTWOLF_API_KEY"])
```

### Options

<ParamField body="api_key" type="str" required>
  Authenticates detection, telemetry, and capture. Raises `FrostWolfError` when missing or blank.
</ParamField>

<ParamField body="endpoint" type="str" default="https://api.frostwolf.app">
  Base URL of the FrostWolf API.
</ParamField>

<ParamField body="telemetry" type="bool" default="True">
  Ship scan metrics to the console. Detection is unaffected either way.
</ParamField>

<ParamField body="flush_interval_ms" type="int" default="5000">
  How often the telemetry queue is flushed.
</ParamField>

<ParamField body="max_batch_size" type="int" default="50">
  Flush as soon as this many events are queued.
</ParamField>

<ParamField body="max_queue_size" type="int" default="1000">
  Drop the oldest events past this depth.
</ParamField>

<ParamField body="timeout_ms" type="int" default="5000">
  Abort a request after this long.
</ParamField>

<ParamField body="include_evidence" type="bool" default="False">
  Return matched substrings and include them in telemetry.
</ParamField>

<ParamField body="on_scan_error" type={'"block" | "allow"'} default="block">
  What to do when the detection call fails. `block` fails closed.
</ParamField>

<ParamField body="capture" type="bool | CaptureOptions" default="False">
  Capture request and response bodies for decorated calls.
</ParamField>

<ParamField body="transport" type="Transport">
  Override the HTTP transport. Defaults to `urllib`.
</ParamField>

<ParamField body="on_error" type="Callable[[Exception], None]">
  Called when a detection call or background flush fails. Never raises.
</ParamField>

<ParamField body="guard" type="GuardOptions">
  Defaults applied to every guard call.
</ParamField>

### `GuardOptions`

| Option | Default | Purpose |
| - | - | - |
| `on_match` | `"block"` | What `wrap` and `decorate` do when a payload trips the policy. |
| `block_severity` | server default `"medium"` | Lowest severity that trips the policy. |
| `max_scan_chars` | server default `100000` | Longer payloads are truncated server-side. |
| `replacement` | `"[REDACTED]"` | Text substituted for each redacted span. |
| `on_decision` | `None` | Called after every inspection. |
| `cloak` | `None` | A `CloakConfig`. |

### `CloakConfig`

| Option | Default | Purpose |
| - | - | - |
| `vault` | in-memory | Where tokenized values are kept. |
| `key` | random per process | Secret that keys tokens and hashes. |
| `semantic_pass` | `None` (enforce) | What the semantic pass may do on calls that use Cloak. |
| `vault_ttl_ms` | `3600000` | How long a value is kept. |
| `max_vault_entries` | `10000` | Cap on the default in-memory store. |

## Client methods

| Method | Returns | Notes |
| - | - | - |
| `init(options=None)` | `InitResult` | Authenticate the key, optionally setting capture. Never raises. |
| `flush()` | `None` | Send everything queued. |
| `close()` | `None` | Flush, and stop the background timers. |

## `fw.guard`

| Method | Returns | Notes |
| - | - | - |
| `scan(input, options=None)` | `ScanResult` | Never raises. |
| `sanitise(input, options=None)` | `SanitiseResult` | Redacts matches, returns both provider shapes. |
| `wrap(input, call, options=None)` | `T \| BlockedResponse` | Applies `on_match`. |
| `decorate(fn, options=None)` | `Callable` | Wraps a completions function. Sync or async. |
| `protect(input, options=None)` | `ProtectResult` | Attacks and personal data in one call. |
| `is_blocked(input)` | `bool` | Fast path. |
| `assert_allowed(input)` | `ScanResult` | Raises `BlockedError` when blocked. |
| `validate_tool_calls(calls, options=None)` | `ToolValidationResult` | Judges calls before execution. |

## `fw.guard.cloak`

| Method | Returns | Notes |
| - | - | - |
| `scan(input, options=None)` | `CloakBlock` | Find entities without changing anything. Never raises. |
| `protect(input, options)` | `ProtectResult` | Cloak without the attack check. |
| `restore(value, RestoreOptions(context=...))` | `RestoreResult` | Restore a string or JSON value. |
| `forget(context)` | `int` | Erase everything held for one identity. |

## Example

```python theme={null}
from frostwolf import (
    CloakContext,
    CloakOptions,
    FrostWolfClient,
    MaskStrategy,
    ProtectOptions,
)

fw = FrostWolfClient(api_key=os.environ["FROSTWOLF_API_KEY"])

result = fw.guard.protect(
    {"messages": [{"role": "user", "content": "Charge card 4242 4242 4242 4242"}]},
    ProtectOptions(
        cloak=CloakOptions(
            context=CloakContext(subject=user.id),
            strategies={"payment_card": MaskStrategy(keep_last=4)},
        )
    ),
)
```

## Errors

| Error | When |
| - | - |
| `FrostWolfError` | Misuse, such as a missing key or an invalid option. Has a `code`. |
| `BlockedError` | Raised by `assert_allowed`. Carries the full result. |
| `RestoreDeniedError` | A response carried another context's token. Has `denied`, a count. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.