# Cyphrex (Python)

Official SDK for [Cyphrex](https://cyphrex.io) — call `check()` before every agent action.

## Installation

```bash
pip install cyphrex
```

Or from source:

```bash
cd packages/sdk-python
pip install -e .
```

## Quick start

```python
import os
from cyphrex import Cyphrex

client = Cyphrex(
    api_key=os.environ["CYPHREX_API_KEY"],
    agent_id="your-agent-uuid",
    # api_url optional; defaults to production API
)

result = client.check(
    action_type="http_call",
    url="https://api.example.com/data",
)

if not result["allowed"]:
    print(result.get("reason"), result.get("violations"))
else:
    # proceed with the action
    pass
```

## Constructor

| Argument | Required | Description |
|----------|----------|-------------|
| `api_key` | Yes | Account API key from Dashboard → API Keys |
| `agent_id` | Yes | UUID of the agent |
| `api_url` | No | API base URL (default: `https://cyphrexapi-production.up.railway.app`) |
| `timeout` | No | Seconds (default `10`) |
| `fail_open` | No | If `True`, allow actions when Cyphrex is unreachable |

Environment variable `CYPHREX_API_URL` overrides the default base URL when `api_url` is omitted.

## `check(action_type, url=None, payload=None, metadata=None)`

Returns a dict:

- `allowed` (bool)
- `reason` (str, optional)
- `violations` (list, optional) — e.g. severity codes when blocked
- `severity` (str, optional) — `P1` / `P2` / `P3`
- `spend` (dict, optional) — reserved for future use

For **data access**, include `dataScope` in `metadata` or use `check_data_access(scope)`.

For **LLM cost limits**, pass `estimatedCost` in `metadata` or use `check_llm_input(..., estimated_cost=...)`.

## HTTP

`POST {api_url}/v1/check` with:

- `Authorization: Bearer <api_key>`
- JSON body: `{"agentId": "...", "action": {"type": "...", ...}}`

## License

MIT
