Metadata-Version: 2.4
Name: helm-sdk
Version: 0.8.3
Summary: Python SDK for HELM — fail-closed tool calling for AI agents
Author-email: Mindburn Labs <oss@mindburn.org>
License: Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic<3,>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: types-requests; extra == "dev"

# HELM SDK - Python

Typed Python client for the retained HELM kernel API.

## Local Install

```bash
cd sdk/python
python -m pip install .
```

Package metadata identifies source target `0.8.3`; this README does not claim
that a registry package has been published.

## Local Development

```bash
pip install '.[dev]'
pytest -v --tb=short
```

## Generated Sources

`helm_sdk/types_gen.py` is generated from `api/openapi/helm.openapi.yaml`.
Generated protobuf modules live under `helm_sdk/generated/` when codegen has
been run.

## Usage

```python
from helm_sdk import EvaluateRequest, HelmClient

client = HelmClient(base_url="http://127.0.0.1:7714")
decision = client.evaluate_decision_v5(EvaluateRequest(
    tool="read-ticket",
    effect_level="ticket:123",
    session_id="example-session",
))
print(decision.verdict)  # ALLOW or DENY
```

Run the first-class local example with `make sdk-examples-smoke` or directly
from `examples/python_sdk/`.

## Execution Boundary Methods

The client includes helpers for the May 2026 execution-boundary surfaces:
evidence envelope manifests, boundary records and checkpoints, conformance
vectors, MCP quarantine and authorization profiles, sandbox profiles and
grants, authz snapshots, approvals, budgets, telemetry export, and coexistence
capabilities.

External evidence envelopes remain compatibility wrappers; HELM-native
EvidencePack roots stay authoritative.

## Source target

The SDK requires canonical typed evaluation and returns receipt-bearing V5
responses. Verify registry evidence before using a pinned package coordinate.
