Python SDK - FrostWolf

pip install frostwolf

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

Client

import os
from frostwolf import FrostWolfClient

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

Options

str

required

Authenticates detection, telemetry, and capture. Raises FrostWolfError when missing or blank.

str

default:"https://api.frostwolf.app"

Base URL of the FrostWolf API.

bool

default:"True"

Ship scan metrics to the console. Detection is unaffected either way.

int

default:"5000"

How often the telemetry queue is flushed.

int

default:"50"

Flush as soon as this many events are queued.

int

default:"1000"

Drop the oldest events past this depth.

int

default:"5000"

Abort a request after this long.

bool

default:"False"

Return matched substrings and include them in telemetry.

"block" | "allow"

default:"block"

What to do when the detection call fails. block fails closed.

bool | CaptureOptions

default:"False"

Capture request and response bodies for decorated calls.

Transport

Override the HTTP transport. Defaults to urllib.

Callable[[Exception], None]

Called when a detection call or background flush fails. Never raises.

GuardOptions

Defaults applied to every guard call.

`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

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.

​Client

​Options

​GuardOptions

​CloakConfig

​Client methods

​fw.guard

​fw.guard.cloak

​Example

​Errors