> ## 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.

# Tool Guards

## Overview

ActGuard exports these decorators and rule helpers:

* `@actguard.rate_limit`
* `@actguard.circuit_breaker`
* `@actguard.max_attempts`
* `@actguard.timeout`
* `@actguard.idempotent`
* `@actguard.prove`
* `@actguard.enforce`
* `@actguard.tool(...)`
* `actguard.RequireFact`, `actguard.Threshold`, `actguard.BlockRegex`

## Runtime requirements

* `max_attempts` and `idempotent` require `client.run(...)`
* `prove` and `enforce` require `actguard.session(...)`

## `@rate_limit`

```python theme={null}
actguard.rate_limit(
    *,
    max_calls: int = 10,
    period: float = 60.0,
    scope: str | None = None,
)
```

Sliding-window rate limiting for sync and async tools.

## `@circuit_breaker`

```python theme={null}
actguard.circuit_breaker(
    *,
    name: str,
    max_fails: int = 3,
    reset_timeout: float = 60.0,
    fail_on=actguard.FAIL_ON_DEFAULT,
    ignore_on=actguard.IGNORE_ON_DEFAULT,
)
```

`FailureKind` values:

* `TRANSPORT`, `TIMEOUT`, `OVERLOADED`, `THROTTLED`
* `AUTH`, `INVALID`, `NOT_FOUND`, `CONFLICT`, `UNKNOWN`

Preset constants:

* `FAIL_ON_DEFAULT`
* `IGNORE_ON_DEFAULT`
* `FAIL_ON_STRICT`
* `FAIL_ON_INFRA_ONLY`

## `@max_attempts`

```python theme={null}
actguard.max_attempts(*, calls: int)
```

Caps per-tool attempts in the active run.

## `@timeout`

```python theme={null}
actguard.timeout(seconds: float, executor: Executor | None = None)
```

Bounds tool runtime. On timeout, raises `ToolTimeoutError`.

```python theme={null}
actguard.shutdown(wait: bool = True)
```

Shuts down the shared timeout executor.

## `@idempotent`

```python theme={null}
actguard.idempotent(
    *,
    ttl_s: float = 3600,
    on_duplicate: Literal["return", "raise"] = "return",
    safe_exceptions: tuple = (),
)
```

Requires an `idempotency_key` function argument and an active run context.

## Chain-of-custody APIs

### `actguard.session(...)`

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

Context manager for proof/enforcement state.

### `@prove`

```python theme={null}
actguard.prove(
    kind: str,
    extract: str | Callable,
    ttl: float = 300,
    max_items: int = 200,
    on_too_many: str = "block",
)
```

Mints verified facts from read-tool results.

### `@enforce`

```python theme={null}
actguard.enforce(rules: list[Rule])
```

Evaluates rules before write-tool execution.

### Rules

```python theme={null}
actguard.RequireFact(arg: str, kind: str, hint: str = "")
actguard.Threshold(arg: str, max: float)
actguard.BlockRegex(arg: str, pattern: str)
```

## Unified decorator

```python theme={null}
actguard.tool(
    *,
    rate_limit: dict | None = None,
    circuit_breaker: dict | None = None,
    max_attempts: dict | None = None,
    timeout: float | None = None,
    timeout_executor: Executor | None = None,
    idempotent: dict | None = None,
    policy=None,
)
```

Execution order:

`idempotent -> max_attempts -> circuit_breaker -> rate_limit -> timeout -> fn`