Metadata-Version: 2.4
Name: qerexa
Version: 0.1.0
Summary: Qerexa clients for verifiable credentials and fail-closed gate checks (preview).
Project-URL: Homepage, https://qerexa.com
Project-URL: Documentation, https://qerexa.com/docs
Project-URL: Repository, https://github.com/rodriguew/Trust-Rails/tree/main/packages/sdk-python
Project-URL: Issues, https://github.com/rodriguew/Trust-Rails/issues
Author: Qerexa
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,autogen,governance,trust,verifiable-credentials
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: requests<3,>=2.28
Provides-Extra: dev
Requires-Dist: build<2,>=1; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Requires-Dist: twine<7,>=5; extra == 'dev'
Description-Content-Type: text/markdown

# qerexa (Python, preview)

Python clients for Qerexa:

- `QerexaGateMiddleware` — decorator that runs a function only after a
  direct, unexpired Qerexa `allowed` decision. Works for AutoGen functions and
  any plain Python function, including CrewAI or LangChain tool functions.
- `QerexaVCClient` — issue and verify verifiable credentials, federation
  tokens, and trust relationships.

## Install

```bash
pip install qerexa
```

## Gate a function

```python
import os
from qerexa import (
    ExecutionAuthorizationRequiredError,
    GateBlockedError,
    QerexaGateMiddleware,
)

gate = QerexaGateMiddleware(api_key=os.environ["QEREXA_API_KEY"])

@gate.gate_check(action="report.export", reasoning="Monthly compliance export")
def export_report(report_id: str) -> str:
    ...

try:
    export_report("rpt_123")
except ExecutionAuthorizationRequiredError as e:
    # Human review was requested (flow e.flow_id). Approval of that review does
    # not authorize this call; stop here or use an action-bound execution flow.
    ...
except GateBlockedError as e:
    ...
```

The wrapped function runs only for HTTP 200 with `decision: "allowed"`,
`allowed: true`, a `decision_id`, and a future, timezone-aware `expires_at`.
Everything else raises and the function does not run: `blocked`,
`approval_required`, expired or malformed allows, non-JSON responses, and
network errors (`QerexaError`, the base of both errors above).

Function arguments are never sent. Qerexa receives the action, the actor, the
`reasoning` you pass (default: the function name), and `metadata`. Do not put
credentials or customer data in either.

For CrewAI, decorate the function that implements the tool before handing it
to CrewAI; the gate then runs on every call regardless of CrewAI callbacks.

## Verifiable credentials

```python
from qerexa import VCClientConfig, create_vc_client

vc = create_vc_client(VCClientConfig(org_id="org_123", api_key=os.environ["QEREXA_API_KEY"]))
relationships = vc.list_trust_relationships(limit=10)
```

Requests time out after 10 seconds by default (`VCClientConfig(timeout=...)`).

## Preview limits

This package is not a regulated execution adapter. It does not verify
receipts, poll or resume review flows, or bind an approval to a specific
execution. Use the documented API proof flow and an independently reviewed
execution contract for high-impact actions.

## Development

```bash
python -m pip install -e "./packages/sdk-python[dev]"
ruff check packages/sdk-python
pytest packages/sdk-python
```

Releases follow [the SDK release runbook](../../apps/sdk/SDK_RELEASE.md).
