Metadata-Version: 2.1
Name: epistemic-handshake
Version: 0.2.0
Summary: Governance middleware for AI agents. One line before every action.
Home-page: https://github.com/theeohhjay/epistemic-handshake-python
Author: Juwon Ayanniran
Author-email: ayanniranoluwajuwon@gmail.com
Keywords: ai governance agents safety nli verification middleware
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Security
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Provides-Extra: full
Requires-Dist: httpx >=0.24.0 ; extra == 'full'

# Epistemic Handshake - Python SDK

Governance middleware for AI agents. One line before every action.

## Install

```bash
pip install epistemic-handshake
```

## Quick Start

```python
from epistemic_handshake import EH

eh = EH(api_key="eh_xxx", policy_id="your-policy-id")

# One-line check
if eh.allow("Send refund of 350 pounds to customer"):
    send_refund()
else:
    print("Action blocked by policy")
```

## Full Verification

```python
result = eh.verify("Apply 25% discount to order #4521")

print(result.verdict)      # APPROVE, DENY, or ESCALATE
print(result.confidence)   # 0.0 - 1.0
print(result.reasoning)    # Why this verdict
print(result.approved)     # True/False
print(result.blocked)      # True if DENY or ESCALATE
```

## Decorator

```python
@eh.guard("Send email to {recipient}")
def send_email(recipient, body):
    # Only executes if EH approves
    smtp.send(recipient, body)

@eh.guard()  # Auto-generates intent from function name + args
def delete_user(user_id):
    db.delete(user_id)
```

## Observe Mode

Start without blocking anything. See what EH would catch.

```python
eh = EH(api_key="eh_xxx", policy_id="xxx", mode="observe")

# Everything passes, but violations are logged
result = eh.verify("Apply 50% discount")
# result.approved == True (observe mode)
# But logs: "[OBSERVE] Would have blocked: Apply 50% discount"
```

## Environment Variables

```bash
export EH_API_KEY=eh_xxx
export EH_POLICY_ID=your-policy-id
# Optional:
export EH_API_URL=https://your-custom-deployment.com
```

```python
# No args needed if env vars are set
from epistemic_handshake import EH
eh = EH()
```

## Error Handling

```python
eh = EH(
    api_key="eh_xxx",
    policy_id="xxx",
    on_error="escalate",  # If API is down: "escalate", "approve", or "deny"
)
```

## With LangChain

```python
from epistemic_handshake import EH
from langchain.tools import tool

eh = EH(api_key="eh_xxx", policy_id="xxx")

@tool
def send_refund(amount: float, customer_id: str) -> str:
    """Send a refund to a customer."""
    result = eh.verify(f"Send refund of {amount} pounds to customer {customer_id}")
    if result.blocked:
        return f"Action blocked: {result.reasoning}"
    # proceed with refund
    return f"Refund of {amount} sent to {customer_id}"
```

## Free During Early Access

Sign up at [epistemic-handshake-production.up.railway.app](https://epistemic-handshake-production.up.railway.app)
