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

# API Reference

## Client

```python theme={null}
class actguard.Client(
    *,
    api_key: str | None = None,
    gateway_url: str | None = None,
    event_mode: str = "verbose",
    flush_interval_ms: int = 1000,
    max_batch_events: int = 100,
    max_batch_bytes: int = 256_000,
    max_queue_events: int = 10_000,
    timeout_s: float | None = None,
    max_retries: int | None = None,
    budget_timeout_s: float | None = None,
    budget_max_retries: int | None = None,
    event_timeout_s: float | None = None,
    event_max_retries: int | None = None,
    backoff_base_ms: int = 200,
    backoff_max_ms: int = 10_000,
)
```

### Constructors

```python theme={null}
actguard.Client.from_env() -> Client
actguard.Client.from_file(path: str | os.PathLike[str]) -> Client
```

### Runtime methods

```python theme={null}
client.run(user_id: str | None = None, run_id: str | None = None)
client.budget_guard(
    *,
    user_id: str | None = None,
    name: str | None = None,
    usd_limit: float | None = None,
    run_id: str | None = None,
    plan_key: str | None = None,
)
client.close() -> None
```

### Budget transport helpers

```python theme={null}
client.reserve_budget(
    *,
    run_id: str,
    usd_limit_micros: int | None,
    plan_key: str | None = None,
    user_id: str | None = None,
) -> str
client.settle_budget(
    *,
    reserve_id: str,
    provider: str,
    provider_model_id: str,
    input_tokens: int,
    cached_input_tokens: int,
    output_tokens: int,
) -> None
```

## BudgetGuard

`client.budget_guard(...)` returns `actguard.BudgetGuard`.

Readable properties include:

* `run_id`
* `tokens_used`
* `usd_used`
* `local_tokens_used`
* `local_usd_used`
* `root_tokens_used`
* `root_usd_used`

Supports `with` and `async with`.

## Event reporting APIs

```python theme={null}
actguard.emit_event(category: str, name: str, payload: dict, **fields) -> None
actguard.emit_violation(error: Exception, **context_overrides) -> None
```

`emit_event` is a no-op without an active `client.run(...)` context.

## Tool guard decorators

```python theme={null}
actguard.rate_limit(...)
actguard.circuit_breaker(...)
actguard.max_attempts(...)
actguard.timeout(...)
actguard.idempotent(...)
actguard.prove(...)
actguard.enforce(...)
actguard.tool(...)
actguard.shutdown(wait: bool = True)
```

See [Tool guards](/python-sdk/tool-guards) for parameter-level behavior.

## Session API

```python theme={null}
actguard.session(id: str, scope: dict[str, str] | None = None)
```

Creates a `GuardSession` context manager used by `prove` and `enforce`.

## Exceptions

### Core

* `ActGuardError`
* `ActGuardToolError`
* `ActGuardPaymentRequired`
* `MonitoringDegradedError`
* `ActGuardViolation`

### Runtime and budget

* `MissingRuntimeContextError`
* `NestedRuntimeContextError` (alias: `NestedRunContextError`)
* `NestedBudgetGuardError` (legacy export; current budget scopes support nesting)
* `BudgetExceededError`
* `BudgetTransportError`
* `BudgetConfigurationError`
* `BudgetClientMismatchError`

### Tool guard failures

* `RateLimitExceeded`
* `CircuitOpenError`
* `MaxAttemptsExceeded`
* `ToolTimeoutError`
* `MissingIdempotencyKeyError`
* `IdempotencyInProgress`
* `DuplicateIdempotencyKey`
* `IdempotencyOutcomeUnknown`
* `InvalidIdempotentToolError`
* `GuardError`
* `ToolGuardError`
* `ToolExecutionError`