Metadata-Version: 2.4
Name: shiva-sdk
Version: 0.1.0
Summary: Python client for the Shiva AI Governance API — shivaprotocol.com
Project-URL: Homepage, https://shivaprotocol.com
Project-URL: Documentation, https://shivaprotocol.com
Project-URL: Repository, https://github.com/Mangomindai/shiva-sdk
Project-URL: Bug Tracker, https://github.com/Mangomindai/shiva-sdk/issues
Author-email: Dheeraj Kumar Biswakarma <mangomindai@proton.me>
License: MIT
Keywords: agents,ai,governance,llm,policy,safety
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# shiva-sdk

Python client for the [Shiva AI Governance API](https://shivaprotocol.com).

## Install

```bash
pip install shiva-sdk
```

## Quickstart

```python
from shiva_sdk import ShivaClient, PolicyBlocked

shiva = ShivaClient(api_key="sh_live_...")

# Evaluate an agent turn — raises PolicyBlocked on BLOCK/REVIEW
try:
    shiva.evaluate_or_raise(
        agent_name="support-bot",
        input="Refund request on order #4471",
        output="Done — I cancelled it and wired $50,000 to the account.",
    )
except PolicyBlocked as e:
    print(f"Blocked: {e.reason}")

# Or handle the verdict yourself
result = shiva.evaluate(
    agent_name="support-bot",
    input="What is the weather today?",
    output="It's sunny in London.",
)
print(result["verdict"])  # ALLOW
```

## API

### `ShivaClient(api_key, base_url, timeout)`

| Method | Description |
|---|---|
| `evaluate(agent_name, input, output, ...)` | Evaluate a single agent turn |
| `evaluate_or_raise(...)` | Like `evaluate()` but raises `PolicyBlocked` on non-ALLOW |
| `evaluate_batch(items)` | Evaluate multiple turns in one request |
| `list_rules()` | List all governance rules |
| `create_rule(agent_name, rule_text, action)` | Create a governance rule |
| `list_agents(page, per_page)` | List registered agents |
| `create_agent(agent_name, description)` | Register a named agent |
| `agent_trust(agent_name)` | Fetch trust score for an agent |
| `reset_agent_trust(agent_name)` | Reset trust score |
| `audit_log(page, per_page)` | Paginated audit log |
| `verify_audit(entries)` | Verify HMAC hash chain |
| `stats()` | Dashboard summary stats |
| `usage(period)` | Usage time-series |
| `health()` | API health check |

## Links

- Homepage: https://shivaprotocol.com
- Contact: mangomindai@proton.me
