Metadata-Version: 2.4
Name: cordum-guard
Version: 2.5.2
Summary: Cordum Safety Guard — @guard decorator for LangChain, LlamaIndex, and plain Python functions
Author-email: Cordum <eng@cordum.io>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/cordum-io/cap
Project-URL: Documentation, https://docs.cordum.io/sdk/python-guard
Project-URL: Repository, https://github.com/cordum-io/cap
Project-URL: Issues, https://github.com/cordum-io/cap/issues
Keywords: cordum,guard,safety,ai,langchain,llamaindex
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
Provides-Extra: llamaindex
Requires-Dist: llama-index-core>=0.10.0; extra == "llamaindex"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"

# cordum-guard

Safety governance for Python AI agents. Add Cordum safety checks to **existing** Python code with a single decorator — no rewrite required.

## Install

```bash
pip install cordum-guard
```

With LangChain or LlamaIndex support:

```bash
pip install cordum-guard[langchain]
pip install cordum-guard[llamaindex]
```

## Quick Start

```python
from cordum_guard import CordumClient, guard

client = CordumClient("http://localhost:8081", api_key="your-api-key")

@guard(client, policy="financial_ops", risk_tags=["write", "financial"])
def execute_transfer(amount: float, to_account: str):
    bank_api.transfer(amount, to_account)
```

The `@guard` decorator intercepts every call to `execute_transfer`:

1. Evaluates the safety policy via the Cordum Safety Kernel
2. **allow** — function runs normally
3. **deny** — raises `CordumBlockedError`
4. **require_approval** — waits for human approval in the dashboard
5. **throttle** — delays execution per policy

## LangChain Integration

```python
from cordum_guard import CordumClient
from cordum_guard.langchain import CordumToolGuard

client = CordumClient("http://localhost:8081", api_key="your-api-key")
guarded_tools = CordumToolGuard(client, policy="agent_ops").wrap(tools)
agent = initialize_agent(guarded_tools, llm)
```

## LlamaIndex Integration

```python
from cordum_guard import CordumClient
from cordum_guard.llamaindex import CordumToolGuard

client = CordumClient("http://localhost:8081", api_key="your-api-key")
guarded_tools = CordumToolGuard(client, policy="agent_ops").wrap(tools)
```

## Async Support

The `@guard` decorator works with both sync and async functions:

```python
@guard(client, policy="ops")
async def async_operation():
    return await some_api_call()
```

## Configuration

### CordumClient

| Parameter     | Default       | Description                          |
|---------------|---------------|--------------------------------------|
| `gateway_url` | —             | Cordum gateway URL                   |
| `api_key`     | —             | API key for authentication           |
| `tenant_id`   | `"default"`   | Tenant identifier                    |
| `timeout`     | `30.0`        | HTTP request timeout (seconds)       |

### @guard decorator

| Parameter    | Default        | Description                              |
|--------------|----------------|------------------------------------------|
| `client`     | —              | CordumClient instance                    |
| `policy`     | `""`           | Policy name (label for traceability)     |
| `risk_tags`  | `[]`           | Risk tags sent to the Safety Kernel      |
| `capability` | function name  | Override the capability identifier       |
| `topic`      | `"job.guard"`  | NATS topic for policy evaluation         |
| `timeout`    | `300.0`        | Max wait for approval decisions (seconds)|

### CordumToolGuard (LangChain / LlamaIndex)

| Parameter    | Default        | Description                          |
|--------------|----------------|--------------------------------------|
| `client`     | —              | CordumClient instance                |
| `policy`     | `""`           | Policy name                          |
| `risk_tags`  | `[]`           | Risk tags for all wrapped tools      |
| `topic`      | `"job.guard"`  | NATS topic for evaluation            |

## License

Apache-2.0
