Skip to main content

​
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

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

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

actguard.max_attempts(*, calls: int)
Caps per-tool attempts in the active run.

​
@timeout

actguard.timeout(seconds: float, executor: Executor | None = None)
Bounds tool runtime. On timeout, raises ToolTimeoutError. 
actguard.shutdown(wait: bool = True)
Shuts down the shared timeout executor.

​
@idempotent

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(...)

actguard.session(id: str, scope: dict[str, str] | None = None)
Context manager for proof/enforcement state.

​
@prove

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

actguard.enforce(rules: list[Rule])
Evaluates rules before write-tool execution.

​
Rules

actguard.RequireFact(arg: str, kind: str, hint: str = "")
actguard.Threshold(arg: str, max: float)
actguard.BlockRegex(arg: str, pattern: str)

​
Unified decorator

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