Skip to main content

​
Requirements

  • Python 3.9+
  • At least one supported provider SDK (OpenAI, Anthropic, or Google GenAI)

​
Install

pip install actguard

​
Configure the runtime client

Client.from_env() reads ACTGUARD_CONFIG when present. 
import actguard

client = actguard.Client.from_env()
ACTGUARD_CONFIG accepts either:
  • Base64 JSON payload
  • Path to a JSON file
The JSON shape maps directly to Client(...) constructor fields, commonly: 
{
  "gateway_url": "http://localhost:8085",
  "api_key": "ag_live_...",
  "event_mode": "verbose"
}

​
Run + budget scope

Use client.run(...) as the runtime root, then client.budget_guard(...) for budget enforcement. 
import actguard

client = actguard.Client.from_env()

with client.run(user_id="alice", run_id="req-123"):
    with client.budget_guard(usd_limit=0.05) as guard:
        # call your LLM SDKs/tools here
        ...

print(f"tokens={guard.tokens_used} usd={guard.usd_used:.6f}")
client.budget_guard(...) works locally, but reserve/settle-backed enforcement requires gateway_url + api_key on the client. Start here first, then layer tool decorators.

​
budget_guard vs decorators

  • budget_guard checks and enforces budget constraints before and during model execution.
  • Tool decorators (rate_limit, circuit_breaker, max_attempts, timeout, idempotent, prove, enforce, tool) guard tool invocation behavior and emit runtime events.

​
Runtime-scoped decorators

max_attempts and idempotent require an active client.run(...) context. 
from actguard import max_attempts

@max_attempts(calls=2)
def lookup_customer(customer_id: str) -> dict:
    ...

with client.run(run_id="req-123"):
    lookup_customer("cus_1")

​
Chain-of-custody decorators

prove and enforce require actguard.session(...). 
import actguard

with client.run(run_id="req-123"):
    with actguard.session("req-123", {"user_id": "alice"}):
        ...

​
Examples from the repository

Reference implementations:
  • actguard/examples/10_langchain
  • actguard/examples/20_langgraph
  • actguard/examples/30_google_adk
  • actguard/examples/40_prove_enforce
All four use:
  • client = actguard.Client.from_env()
  • with client.run(...)
  • optional with client.budget_guard(...)