Metadata-Version: 2.4
Name: zeqcy_agent
Version: 0.1.2
Summary: Developer SDK for ZEQCY AI Agent Firewall
Author-email: ZEQCY Firewall Team <dev@zeqcy.local>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown

# ZEQCY AI Agent Firewall SDK

The ZEQCY AI Agent Firewall SDK allows your autonomous AI agent to securely route its intent through the ZEQCY Gateway for risk evaluation before execution.

## 1. Installation & Import

Simply include `zeqcy_agent.py` in your project and import the connector:

```python
from zeqcy_agent import ZEQCYFirewall
```

## 2. Agent Registration

Before connecting, you must register your agent identity with the ZEQCY Firewall Gateway to receive a secure connection credential. You can do this via the Dashboard UI (Connect Agent tab) or via a POST request to `/api/security/agents/register`.

**Keep your credential secure. It will only be shown once.**

## 3. Initialization & Connection

Initialize the SDK using your generated `agent_id`, `session_id`, and `auth_token` (credential).

```python
firewall = ZEQCYFirewall(
    agent_id="your-agent-id",
    session_id="session-100",
    auth_token="zeqcy_local_xxxxxxxxxxxxxxxxxxxxxxxx"
)

if not firewall.connect():
    print("Failed to establish secure connection.")
```

## 4. Sending a Request

Before executing any external tool or API, route the intent through the firewall:

```python
result = firewall.send_request(
    tool="WEB_SEARCH",
    action="search",
    target="latest tech news",
    parameters={"query": "AI Agents"} # optional
)
```

## 5. Reading the Firewall Decision

The firewall analyzes the request and returns a `ZEQCYFirewallResult` object. The `decision` property contains the authoritative security decision:

```python
if result.decision == "ALLOWED":
    print("Request is safe to execute.")
    # Safe to proceed
elif result.decision == "REVIEW_REQUIRED":
    print("Request requires human approval.")
    # Pause execution
elif result.decision == "BLOCKED":
    print("Request blocked by security policy.")
    # Halt
else:
    print(f"Error evaluating request: {result.result}")
```

## 6. Disconnecting

When your session is complete, safely disconnect the SDK to clear the connection state:

```python
firewall.disconnect()
```

## Error Handling

If authentication fails (e.g., revoked credential or forged identity), `send_request` safely catches the `401 UNAUTHORIZED` rejection from the gateway and returns an `ERROR` decision safely without crashing your application. Always verify `result.decision == "ALLOWED"` before proceeding with any action.
