Metadata-Version: 2.4
Name: airg-client
Version: 0.3.2
Summary: Python client for the AI Runtime Governor – runtime AI-agent governance service
Project-URL: Homepage, https://github.com/othnielObasi/ai-runtime-governor-core
Project-URL: Repository, https://github.com/othnielObasi/ai-runtime-governor-core
Project-URL: Documentation, https://github.com/othnielObasi/ai-runtime-governor-core#readme
Project-URL: Issues, https://github.com/othnielObasi/ai-runtime-governor-core/issues
Author: Sovereign AI Lab
License-Expression: MIT
License-File: LICENSE
Keywords: agent-governance,ai-runtime-governor,ai-safety,airg,runtime-policy
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24.0
Description-Content-Type: text/markdown

# airg-client

Python client for the **AI Runtime Governor** – a runtime governance layer for AI agents.

The Governor evaluates every tool invocation against configurable policies and
returns an **allow / block / review** decision before the tool executes.

## Installation

```bash
pip install airg-client
```

## Quick start

```python
from airg import AIRG

client = AIRG()

decision = client.evaluate(
    tool="shell_exec",
    args={"command": "ls -la /tmp"},
    context={"session_id": "abc-123"},
)
print(decision["decision"])      # "allow" | "review"
print(decision["risk_score"])    # 0.0 – 1.0
print(decision["explanation"])
```

## Configuration

| Environment variable | Description |
|---|---|
| `GOVERNOR_URL` | Base URL of the Governor service |
| `GOVERNOR_API_KEY` | API key (`airg_…`) |

Or pass them explicitly:

```python
client = AIRG(api_key="airg_...", base_url="https://...")
```

## API

### `AIRG(*, api_key=None, base_url=None, timeout=10.0)`

Create a client. Reads `GOVERNOR_API_KEY` and `GOVERNOR_URL` from
environment variables when not provided.

### `client.evaluate(tool, args, context=None) → dict`

Evaluate a tool call. Returns the decision dict:

```python
{
    "decision": "allow",        # "allow" | "block" | "review"
    "risk_score": 0.15,
    "explanation": "Low-risk read operation",
    "policy_ids": ["shell-guard"],
    "modified_args": None,
}
```

Raises `BlockedError` if the decision is `"block"`.

### `client.scan(text, agent_id=None, session_id=None, context=None) → dict`

Scan agent output for threats before sending to users.

### `client.verify(action_id, tool, result, context=None) → dict`

Post-execution verification. Raises `VerificationError` on violations.

### `client.ingest_spans(spans) → dict`

Batch-ingest agent trace spans.

### `client.list_traces(**filters) → list`

List traces with optional filters (`agent_id`, `session_id`, `has_blocks`, `limit`, `offset`).

### `client.get_trace(trace_id) → dict`

Fetch full trace detail.

### `client.delete_trace(trace_id) → dict`

Delete all spans for a trace.

## Exceptions

| Exception | Description |
|---|---|
| `AIRGError` | Base exception |
| `BlockedError` | Governor blocked the action |
| `ReviewRejectedError` | Human reviewer rejected |
| `ReviewExpiredError` | Review timed out |
| `VerificationError` | Post-execution violation |

## Requirements

- Python ≥ 3.9
- [httpx](https://www.python-httpx.org/) ≥ 0.24.0

## License

MIT — see [LICENSE](LICENSE).
