Metadata-Version: 2.4
Name: hb-eval-sdk
Version: 2.0.0
Summary: HB-Eval SDK for reliable agent evaluation, semantic memory, and LangChain/LangGraph integration
Author-email: Abuelgasim Mohamed Ibrahim Adam <abuelgasim.hbeval@outlook.com>
License: MIT
Project-URL: Homepage, https://github.com/hb-evalSystem/HB-System
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: cryptography>=41.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: langchain-core>=0.1.0
Requires-Dist: langgraph>=0.0.10
Dynamic: license-file

# HB-Eval SDK

Secure Python SDK for **HB-Eval Reliability OS** — the first cognitive runtime for evaluating and ensuring AI agent reliability.

## Features

- AES-256-GCM encrypted payloads for all API communication
- HMAC-SHA256 request signing with replay-attack protection
- Safe Halt protocol — automatic failure handling on connection loss
- Semantic memory retrieval for agent context
- Native LangChain / LangGraph callback integration

## Installation

```bash
pip install hb-eval-sdk
```

## Quick Start

```python
from hb_eval_sdk import HBEvalClient

client = HBEvalClient(
    api_key="your_api_key",
    aes_key="your_base64_encoded_32byte_aes_key",
)

result = client.evaluate({
    "trajectory": [{"step": 1, "action": "query_memory", "input": "..."}],
    "sub_tasks": 1,
    "constraint_violations": 0,
    "recovery_attempts": 1,
    "context": "my agent task",
    "agent_id": "my-agent",
})

print(result.verdict)      # Verdict.SAFE or Verdict.UNSAFE
print(result.metrics.pei)  # float
print(result.metrics.irs)  # float
```

## Memory Retrieval

```python
matches = client.retrieve_memory(context="my task context")
for match in matches:
    print(match.trajectory_summary, match.similarity)
```

## LangChain Integration

```python
from hb_eval_sdk import HBEvalCallback

callback = HBEvalCallback(
    api_key="your_api_key",
    aes_key="your_base64_encoded_32byte_aes_key",
)

# Pass the callback to your LangChain agent
agent.invoke({"input": "..."}, config={"callbacks": [callback]})
```

## Exception Handling

```python
from hb_eval_sdk import (
    HBEvalError,
    AuthenticationError,
    EncryptionError,
    SafeHaltError,
    ConnectionError,
)

try:
    result = client.evaluate({...})
except SafeHaltError as e:
    print(f"Safe halt triggered: {e.reason}")
except AuthenticationError as e:
    print(f"Auth failed: {e}")
except ConnectionError as e:
    print(f"Connection error: {e}")
```

## Requirements

- Python >= 3.8
- requests >= 2.28.0
- cryptography >= 41.0.0
- pydantic >= 2.0.0
- langchain-core >= 0.1.0
- langgraph >= 0.0.10

## Documentation

Full documentation: https://hb-eval.readthedocs.io

## License

MIT License — Copyright (c) 2026 Abuelgasim Mohamed Ibrahim Adam
