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

# Getting Started

## Requirements

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

## Install

```bash theme={null}
pip install actguard
```

## Configure the runtime client

`Client.from_env()` reads `ACTGUARD_CONFIG` when present.

```python theme={null}
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:

```json theme={null}
{
  "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.

```python theme={null}
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.

```python theme={null}
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(...)`.

```python theme={null}
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(...)`