helm-sdk 0.1.0__tar.gz

helm_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: helm-sdk
+Version: 0.1.0
+Summary: Python SDK for HELM — fail-closed tool calling for AI agents
+Author-email: Mindburn Labs <oss@mindburn.org>
+License: BSL-1.1
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.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 HELM kernel API. One dependency: `httpx`.
+
+## Install
+
+```bash
+pip install helm-sdk
+```
+
+## Quick Example
+
+```python
+from helm_sdk import HelmClient, HelmApiError, ChatCompletionRequest, ChatMessage
+
+helm = HelmClient(base_url="http://localhost:8080")
+
+# OpenAI-compatible chat (tool calls governed by HELM)
+try:
+    res = helm.chat_completions(ChatCompletionRequest(
+        model="gpt-4",
+        messages=[ChatMessage(role="user", content="List files in /tmp")],
+    ))
+    print(res.choices[0].message.content)
+except HelmApiError as e:
+    print(f"Denied: {e.reason_code}")  # e.g. DENY_TOOL_NOT_FOUND
+
+# Export + verify evidence pack
+pack = helm.export_evidence()
+result = helm.verify_evidence(pack)
+print(result.verdict)  # PASS
+
+# Conformance
+from helm_sdk import ConformanceRequest
+conf = helm.conformance_run(ConformanceRequest(level="L2"))
+print(conf.verdict, conf.gates, "gates")
+```
+
+## API
+
+| Method | Endpoint |
+|--------|----------|
+| `chat_completions(req)` | `POST /v1/chat/completions` |
+| `approve_intent(req)` | `POST /api/v1/kernel/approve` |
+| `list_sessions()` | `GET /api/v1/proofgraph/sessions` |
+| `get_receipts(session_id)` | `GET /api/v1/proofgraph/sessions/{id}/receipts` |
+| `export_evidence(session_id?)` | `POST /api/v1/evidence/export` |
+| `verify_evidence(bundle)` | `POST /api/v1/evidence/verify` |
+| `replay_verify(bundle)` | `POST /api/v1/replay/verify` |
+| `conformance_run(req)` | `POST /api/v1/conformance/run` |
+| `health()` | `GET /healthz` |
+| `version()` | `GET /version` |
+
+## Error Handling
+
+All errors raise `HelmApiError` with a typed `reason_code`:
+```python
+try: helm.chat_completions(req)
+except HelmApiError as e: print(e.reason_code)
+```

helm_sdk-0.1.0/README.md

@@ -0,0 +1,60 @@
+# HELM SDK — Python
+
+Typed Python client for the HELM kernel API. One dependency: `httpx`.
+
+## Install
+
+```bash
+pip install helm-sdk
+```
+
+## Quick Example
+
+```python
+from helm_sdk import HelmClient, HelmApiError, ChatCompletionRequest, ChatMessage
+
+helm = HelmClient(base_url="http://localhost:8080")
+
+# OpenAI-compatible chat (tool calls governed by HELM)
+try:
+    res = helm.chat_completions(ChatCompletionRequest(
+        model="gpt-4",
+        messages=[ChatMessage(role="user", content="List files in /tmp")],
+    ))
+    print(res.choices[0].message.content)
+except HelmApiError as e:
+    print(f"Denied: {e.reason_code}")  # e.g. DENY_TOOL_NOT_FOUND
+
+# Export + verify evidence pack
+pack = helm.export_evidence()
+result = helm.verify_evidence(pack)
+print(result.verdict)  # PASS
+
+# Conformance
+from helm_sdk import ConformanceRequest
+conf = helm.conformance_run(ConformanceRequest(level="L2"))
+print(conf.verdict, conf.gates, "gates")
+```
+
+## API
+
+| Method | Endpoint |
+|--------|----------|
+| `chat_completions(req)` | `POST /v1/chat/completions` |
+| `approve_intent(req)` | `POST /api/v1/kernel/approve` |
+| `list_sessions()` | `GET /api/v1/proofgraph/sessions` |
+| `get_receipts(session_id)` | `GET /api/v1/proofgraph/sessions/{id}/receipts` |
+| `export_evidence(session_id?)` | `POST /api/v1/evidence/export` |
+| `verify_evidence(bundle)` | `POST /api/v1/evidence/verify` |
+| `replay_verify(bundle)` | `POST /api/v1/replay/verify` |
+| `conformance_run(req)` | `POST /api/v1/conformance/run` |
+| `health()` | `GET /healthz` |
+| `version()` | `GET /version` |
+
+## Error Handling
+
+All errors raise `HelmApiError` with a typed `reason_code`:
+```python
+try: helm.chat_completions(req)
+except HelmApiError as e: print(e.reason_code)
+```

helm_sdk-0.1.0/helm_sdk/__init__.py

@@ -0,0 +1,28 @@
+"""HELM SDK for Python."""
+
+from .client import HelmClient, HelmApiError
+from .types_gen import (
+    ApprovalRequest,
+    ChatCompletionRequest,
+    ChatCompletionResponse,
+    ConformanceRequest,
+    ConformanceResult,
+    Receipt,
+    Session,
+    VerificationResult,
+    VersionInfo,
+)
+
+__all__ = [
+    "HelmClient",
+    "HelmApiError",
+    "ApprovalRequest",
+    "ChatCompletionRequest",
+    "ChatCompletionResponse",
+    "ConformanceRequest",
+    "ConformanceResult",
+    "Receipt",
+    "Session",
+    "VerificationResult",
+    "VersionInfo",
+]

helm_sdk-0.1.0/helm_sdk/client.py

@@ -0,0 +1,156 @@
+"""HELM SDK — Python Client
+
+Typed client for HELM kernel API. Minimal deps (httpx).
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import Any, Optional
+
+import httpx
+
+from .types_gen import (
+    ApprovalRequest,
+    ChatCompletionRequest,
+    ChatCompletionResponse,
+    ConformanceRequest,
+    ConformanceResult,
+    Receipt,
+    Session,
+    VerificationResult,
+    VersionInfo,
+)
+
+
+class HelmApiError(Exception):
+    """Raised when the HELM API returns a non-2xx response."""
+
+    def __init__(self, status: int, message: str, reason_code: str, details: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.reason_code = reason_code
+        self.details = details
+
+
+class HelmClient:
+    """Typed client for HELM kernel API."""
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:8080",
+        api_key: Optional[str] = None,
+        timeout: float = 30.0,
+    ):
+        self.base_url = base_url.rstrip("/")
+        headers: dict[str, str] = {"Content-Type": "application/json"}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers=headers,
+            timeout=timeout,
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "HelmClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def _check(self, resp: httpx.Response) -> None:
+        if resp.status_code >= 400:
+            try:
+                body = resp.json()
+                err = body.get("error", {})
+                raise HelmApiError(
+                    status=resp.status_code,
+                    message=err.get("message", resp.text),
+                    reason_code=err.get("reason_code", "ERROR_INTERNAL"),
+                    details=err.get("details"),
+                )
+            except (ValueError, KeyError):
+                raise HelmApiError(
+                    status=resp.status_code,
+                    message=resp.text,
+                    reason_code="ERROR_INTERNAL",
+                )
+
+    # ── OpenAI Proxy ────────────────────────────────
+    def chat_completions(self, req: ChatCompletionRequest) -> ChatCompletionResponse:
+        resp = self._client.post("/v1/chat/completions", json=asdict(req))
+        self._check(resp)
+        data = resp.json()
+        return ChatCompletionResponse(**{k: data.get(k) for k in ChatCompletionResponse.__dataclass_fields__})
+
+    # ── Approval Ceremony ───────────────────────────
+    def approve_intent(self, req: ApprovalRequest) -> Receipt:
+        resp = self._client.post("/api/v1/kernel/approve", json=asdict(req))
+        self._check(resp)
+        return Receipt(**resp.json())
+
+    # ── ProofGraph ──────────────────────────────────
+    def list_sessions(self, limit: int = 50, offset: int = 0) -> list[Session]:
+        resp = self._client.get(f"/api/v1/proofgraph/sessions?limit={limit}&offset={offset}")
+        self._check(resp)
+        return [Session(**s) for s in resp.json()]
+
+    def get_receipts(self, session_id: str) -> list[Receipt]:
+        resp = self._client.get(f"/api/v1/proofgraph/sessions/{session_id}/receipts")
+        self._check(resp)
+        return [Receipt(**r) for r in resp.json()]
+
+    def get_receipt(self, receipt_hash: str) -> Receipt:
+        resp = self._client.get(f"/api/v1/proofgraph/receipts/{receipt_hash}")
+        self._check(resp)
+        return Receipt(**resp.json())
+
+    # ── Evidence ────────────────────────────────────
+    def export_evidence(self, session_id: Optional[str] = None) -> bytes:
+        resp = self._client.post(
+            "/api/v1/evidence/export",
+            json={"session_id": session_id, "format": "tar.gz"},
+        )
+        self._check(resp)
+        return resp.content
+
+    def verify_evidence(self, bundle: bytes) -> VerificationResult:
+        resp = self._client.post(
+            "/api/v1/evidence/verify",
+            files={"bundle": ("pack.tar.gz", bundle, "application/octet-stream")},
+        )
+        self._check(resp)
+        return VerificationResult(**resp.json())
+
+    def replay_verify(self, bundle: bytes) -> VerificationResult:
+        resp = self._client.post(
+            "/api/v1/replay/verify",
+            files={"bundle": ("pack.tar.gz", bundle, "application/octet-stream")},
+        )
+        self._check(resp)
+        return VerificationResult(**resp.json())
+
+    # ── Conformance ─────────────────────────────────
+    def conformance_run(self, req: ConformanceRequest) -> ConformanceResult:
+        resp = self._client.post("/api/v1/conformance/run", json=asdict(req))
+        self._check(resp)
+        return ConformanceResult(**resp.json())
+
+    def get_conformance_report(self, report_id: str) -> ConformanceResult:
+        resp = self._client.get(f"/api/v1/conformance/reports/{report_id}")
+        self._check(resp)
+        return ConformanceResult(**resp.json())
+
+    # ── System ──────────────────────────────────────
+    def health(self) -> dict[str, str]:
+        resp = self._client.get("/healthz")
+        self._check(resp)
+        return resp.json()
+
+    def version(self) -> VersionInfo:
+        resp = self._client.get("/version")
+        self._check(resp)
+        return VersionInfo(**resp.json())

helm_sdk-0.1.0/helm_sdk/types_gen.py

@@ -0,0 +1,173 @@
+# AUTO-GENERATED from api/openapi/helm.openapi.yaml — DO NOT EDIT
+# Regenerate: bash scripts/sdk/gen.sh
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+# ── Reason Codes ──────────────────────────────────────
+REASON_CODES = [
+    "ALLOW",
+    "DENY_TOOL_NOT_FOUND",
+    "DENY_SCHEMA_MISMATCH",
+    "DENY_OUTPUT_DRIFT",
+    "DENY_BUDGET_EXCEEDED",
+    "DENY_APPROVAL_REQUIRED",
+    "DENY_APPROVAL_TIMEOUT",
+    "DENY_SANDBOX_TRAP",
+    "DENY_GAS_EXHAUSTION",
+    "DENY_TIME_LIMIT",
+    "DENY_MEMORY_LIMIT",
+    "DENY_POLICY_VIOLATION",
+    "DENY_TRUST_KEY_REVOKED",
+    "DENY_IDEMPOTENCY_DUPLICATE",
+    "ERROR_INTERNAL",
+]
+
+
+@dataclass
+class HelmErrorDetail:
+    message: str = ""
+    type: str = ""
+    code: str = ""
+    reason_code: str = ""
+    details: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class ChatMessage:
+    role: str = ""
+    content: str = ""
+    tool_call_id: Optional[str] = None
+
+
+@dataclass
+class ToolFunction:
+    name: str = ""
+    description: str = ""
+    parameters: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class Tool:
+    type: str = "function"
+    function: Optional[ToolFunction] = None
+
+
+@dataclass
+class ChatCompletionRequest:
+    model: str = ""
+    messages: List[ChatMessage] = field(default_factory=list)
+    tools: Optional[List[Tool]] = None
+    temperature: Optional[float] = None
+    max_tokens: Optional[int] = None
+    stream: bool = False
+
+
+@dataclass
+class ToolCall:
+    id: str = ""
+    type: str = ""
+    function: Optional[Dict[str, str]] = None
+
+
+@dataclass
+class ChoiceMessage:
+    role: str = ""
+    content: Optional[str] = None
+    tool_calls: Optional[List[ToolCall]] = None
+
+
+@dataclass
+class Choice:
+    index: int = 0
+    message: Optional[ChoiceMessage] = None
+    finish_reason: str = ""
+
+
+@dataclass
+class Usage:
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+
+
+@dataclass
+class ChatCompletionResponse:
+    id: str = ""
+    object: str = "chat.completion"
+    created: int = 0
+    model: str = ""
+    choices: List[Choice] = field(default_factory=list)
+    usage: Optional[Usage] = None
+
+
+@dataclass
+class ApprovalRequest:
+    intent_hash: str = ""
+    signature_b64: str = ""
+    public_key_b64: str = ""
+    challenge_response: Optional[str] = None
+
+
+@dataclass
+class Receipt:
+    receipt_id: str = ""
+    decision_id: str = ""
+    effect_id: str = ""
+    status: str = ""
+    reason_code: str = ""
+    output_hash: str = ""
+    blob_hash: str = ""
+    prev_hash: str = ""
+    lamport_clock: int = 0
+    signature: str = ""
+    timestamp: str = ""
+    principal: str = ""
+
+
+@dataclass
+class Session:
+    session_id: str = ""
+    created_at: str = ""
+    receipt_count: int = 0
+    last_lamport_clock: int = 0
+
+
+@dataclass
+class ExportRequest:
+    session_id: Optional[str] = None
+    format: str = "tar.gz"
+
+
+@dataclass
+class VerificationResult:
+    verdict: str = ""
+    checks: Optional[Dict[str, str]] = None
+    errors: List[str] = field(default_factory=list)
+
+
+@dataclass
+class ConformanceRequest:
+    level: str = "L1"
+    profile: str = "full"
+
+
+@dataclass
+class ConformanceResult:
+    report_id: str = ""
+    level: str = ""
+    verdict: str = ""
+    gates: int = 0
+    failed: int = 0
+    details: Optional[Dict[str, str]] = None
+
+
+@dataclass
+class VersionInfo:
+    version: str = ""
+    commit: str = ""
+    build_time: str = ""
+    go_version: str = ""

helm_sdk-0.1.0/helm_sdk.egg-info/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: helm-sdk
+Version: 0.1.0
+Summary: Python SDK for HELM — fail-closed tool calling for AI agents
+Author-email: Mindburn Labs <oss@mindburn.org>
+License: BSL-1.1
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.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 HELM kernel API. One dependency: `httpx`.
+
+## Install
+
+```bash
+pip install helm-sdk
+```
+
+## Quick Example
+
+```python
+from helm_sdk import HelmClient, HelmApiError, ChatCompletionRequest, ChatMessage
+
+helm = HelmClient(base_url="http://localhost:8080")
+
+# OpenAI-compatible chat (tool calls governed by HELM)
+try:
+    res = helm.chat_completions(ChatCompletionRequest(
+        model="gpt-4",
+        messages=[ChatMessage(role="user", content="List files in /tmp")],
+    ))
+    print(res.choices[0].message.content)
+except HelmApiError as e:
+    print(f"Denied: {e.reason_code}")  # e.g. DENY_TOOL_NOT_FOUND
+
+# Export + verify evidence pack
+pack = helm.export_evidence()
+result = helm.verify_evidence(pack)
+print(result.verdict)  # PASS
+
+# Conformance
+from helm_sdk import ConformanceRequest
+conf = helm.conformance_run(ConformanceRequest(level="L2"))
+print(conf.verdict, conf.gates, "gates")
+```
+
+## API
+
+| Method | Endpoint |
+|--------|----------|
+| `chat_completions(req)` | `POST /v1/chat/completions` |
+| `approve_intent(req)` | `POST /api/v1/kernel/approve` |
+| `list_sessions()` | `GET /api/v1/proofgraph/sessions` |
+| `get_receipts(session_id)` | `GET /api/v1/proofgraph/sessions/{id}/receipts` |
+| `export_evidence(session_id?)` | `POST /api/v1/evidence/export` |
+| `verify_evidence(bundle)` | `POST /api/v1/evidence/verify` |
+| `replay_verify(bundle)` | `POST /api/v1/replay/verify` |
+| `conformance_run(req)` | `POST /api/v1/conformance/run` |
+| `health()` | `GET /healthz` |
+| `version()` | `GET /version` |
+
+## Error Handling
+
+All errors raise `HelmApiError` with a typed `reason_code`:
+```python
+try: helm.chat_completions(req)
+except HelmApiError as e: print(e.reason_code)
+```

helm_sdk-0.1.0/helm_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+helm_sdk/__init__.py
+helm_sdk/client.py
+helm_sdk/types_gen.py
+helm_sdk.egg-info/PKG-INFO
+helm_sdk.egg-info/SOURCES.txt
+helm_sdk.egg-info/dependency_links.txt
+helm_sdk.egg-info/requires.txt
+helm_sdk.egg-info/top_level.txt
+tests/test_client.py

helm_sdk-0.1.0/helm_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

helm_sdk-0.1.0/helm_sdk.egg-info/requires.txt

@@ -0,0 +1,7 @@
+httpx>=0.25.0
+
+[dev]
+pytest>=7.0
+ruff>=0.1.0
+mypy>=1.0
+types-requests

helm_sdk-0.1.0/helm_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+helm_sdk

helm_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "helm-sdk"
+version = "0.1.0"
+description = "Python SDK for HELM — fail-closed tool calling for AI agents"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "BSL-1.1" }
+authors = [{ name = "Mindburn Labs", email = "oss@mindburn.org" }]
+dependencies = ["httpx>=0.25.0"]
+
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["helm_sdk*"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "ruff>=0.1.0", "mypy>=1.0", "types-requests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py39"
+
+[tool.mypy]
+python_version = "3.9"
+strict = true

helm_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

helm_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,261 @@
+"""HELM Python SDK — Unit Tests
+
+Tests for HelmClient, HelmApiError, and generated types.
+Uses unittest.mock to mock httpx.Client.
+"""
+
+from __future__ import annotations
+
+import json
+from unittest.mock import MagicMock, patch
+from dataclasses import asdict
+
+import pytest
+
+from helm_sdk.client import HelmClient, HelmApiError
+from helm_sdk.types_gen import (
+    ApprovalRequest,
+    ChatCompletionRequest,
+    ChatMessage,
+    ConformanceRequest,
+    ConformanceResult,
+    Receipt,
+    Session,
+    VerificationResult,
+    VersionInfo,
+    REASON_CODES,
+)
+
+
+# ── Helpers ──────────────────────────────────────────────
+
+def mock_response(status_code: int = 200, json_data: object = None, content: bytes = b"") -> MagicMock:
+    """Create a mock httpx.Response."""
+    resp = MagicMock()
+    resp.status_code = status_code
+    resp.json.return_value = json_data if json_data is not None else {}
+    resp.text = json.dumps(json_data) if json_data else ""
+    resp.content = content
+    return resp
+
+
+RECEIPT_DATA = {
+    "receipt_id": "r1",
+    "decision_id": "d1",
+    "effect_id": "e1",
+    "status": "APPROVED",
+    "reason_code": "ALLOW",
+    "output_hash": "h",
+    "blob_hash": "b",
+    "prev_hash": "p",
+    "lamport_clock": 1,
+    "signature": "s",
+    "timestamp": "2026-01-01T00:00:00Z",
+    "principal": "pr",
+}
+
+
+# ── HelmApiError ─────────────────────────────────────────
+
+class TestHelmApiError:
+    def test_stores_status_and_reason(self) -> None:
+        err = HelmApiError(403, "denied", "DENY_POLICY_VIOLATION", {"policy": "no-writes"})
+        assert err.status == 403
+        assert err.reason_code == "DENY_POLICY_VIOLATION"
+        assert err.details == {"policy": "no-writes"}
+        assert str(err) == "denied"
+
+    def test_str_representation(self) -> None:
+        err = HelmApiError(500, "internal error", "ERROR_INTERNAL")
+        assert "internal error" in str(err)
+
+
+# ── HelmClient Constructor ───────────────────────────────
+
+class TestHelmClientConstructor:
+    def test_strips_trailing_slash(self) -> None:
+        client = HelmClient(base_url="http://localhost:8080/")
+        assert client.base_url == "http://localhost:8080"
+
+    def test_default_base_url(self) -> None:
+        client = HelmClient()
+        assert client.base_url == "http://localhost:8080"
+
+    def test_context_manager(self) -> None:
+        with HelmClient() as client:
+            assert client is not None
+
+
+# ── Chat Completions ─────────────────────────────────────
+
+class TestChatCompletions:
+    @patch("helm_sdk.client.httpx.Client")
+    def test_posts_to_correct_endpoint(self, mock_client_cls: MagicMock) -> None:
+        mock_client = mock_client_cls.return_value
+        mock_client.post.return_value = mock_response(200, {
+            "id": "chatcmpl-1",
+            "object": "chat.completion",
+            "created": 1,
+            "model": "gpt-4",
+            "choices": [],
+        })
+
+        client = HelmClient(base_url="http://h")
+        req = ChatCompletionRequest(model="gpt-4", messages=[ChatMessage(role="user", content="hi")])
+        result = client.chat_completions(req)
+
+        mock_client.post.assert_called_once()
+        call_args = mock_client.post.call_args
+        assert call_args[0][0] == "/v1/chat/completions"
+        assert result.id == "chatcmpl-1"
+
+
+# ── Approve Intent ───────────────────────────────────────
+
+class TestApproveIntent:
+    @patch("helm_sdk.client.httpx.Client")
+    def test_posts_approval_request(self, mock_client_cls: MagicMock) -> None:
+        mock_client = mock_client_cls.return_value
+        mock_client.post.return_value = mock_response(200, RECEIPT_DATA)
+
+        client = HelmClient(base_url="http://h")
+        req = ApprovalRequest(intent_hash="abc", signature_b64="s", public_key_b64="pk")
+        result = client.approve_intent(req)
+
+        mock_client.post.assert_called_once()
+        assert result.receipt_id == "r1"
+        assert result.status == "APPROVED"
+
+
+# ── ProofGraph ───────────────────────────────────────────
+
+class TestProofGraph:
+    @patch("helm_sdk.client.httpx.Client")
+    def test_list_sessions(self, mock_client_cls: MagicMock) -> None:
+        mock_client = mock_client_cls.return_value
+        mock_client.get.return_value = mock_response(200, [
+            {"session_id": "s1", "created_at": "t", "receipt_count": 1, "last_lamport_clock": 1},
+        ])
+
+        client = HelmClient(base_url="http://h")
+        result = client.list_sessions(10, 5)
+
+        mock_client.get.assert_called_once()
+        assert len(result) == 1
+        assert result[0].session_id == "s1"
+
+    @patch("helm_sdk.client.httpx.Client")
+    def test_get_receipts(self, mock_client_cls: MagicMock) -> None:
+        mock_client = mock_client_cls.return_value
+        mock_client.get.return_value = mock_response(200, [RECEIPT_DATA])
+
+        client = HelmClient(base_url="http://h")
+        result = client.get_receipts("sess-1")
+
+        assert len(result) == 1
+        assert result[0].receipt_id == "r1"
+
+    @patch("helm_sdk.client.httpx.Client")
+    def test_get_receipt(self, mock_client_cls: MagicMock) -> None:
+        mock_client = mock_client_cls.return_value
+        mock_client.get.return_value = mock_response(200, RECEIPT_DATA)
+
+        client = HelmClient(base_url="http://h")
+        result = client.get_receipt("hash-abc")
+        assert result.receipt_id == "r1"
+
+
+# ── Error Handling ───────────────────────────────────────
+
+class TestErrorHandling:
+    @patch("helm_sdk.client.httpx.Client")
+    def test_raises_helm_api_error_on_4xx(self, mock_client_cls: MagicMock) -> None:
+        mock_client = mock_client_cls.return_value
+        mock_client.get.return_value = mock_response(422, {
+            "error": {
+                "message": "bad schema",
+                "type": "invalid_request",
+                "code": "ERR",
+                "reason_code": "DENY_SCHEMA_MISMATCH",
+            }
+        })
+
+        client = HelmClient(base_url="http://h")
+        with pytest.raises(HelmApiError) as exc_info:
+            client.health()
+
+        assert exc_info.value.status == 422
+        assert exc_info.value.reason_code == "DENY_SCHEMA_MISMATCH"
+
+    @patch("helm_sdk.client.httpx.Client")
+    def test_raises_on_malformed_error_body(self, mock_client_cls: MagicMock) -> None:
+        mock_client = mock_client_cls.return_value
+        resp = MagicMock()
+        resp.status_code = 500
+        resp.json.side_effect = ValueError("no JSON")
+        resp.text = "Internal Server Error"
+        mock_client.get.return_value = resp
+
+        client = HelmClient(base_url="http://h")
+        with pytest.raises(HelmApiError) as exc_info:
+            client.health()
+
+        assert exc_info.value.status == 500
+        assert exc_info.value.reason_code == "ERROR_INTERNAL"
+
+
+# ── System Endpoints ─────────────────────────────────────
+
+class TestSystemEndpoints:
+    @patch("helm_sdk.client.httpx.Client")
+    def test_health(self, mock_client_cls: MagicMock) -> None:
+        mock_client = mock_client_cls.return_value
+        mock_client.get.return_value = mock_response(200, {"status": "ok", "version": "0.1.0"})
+
+        client = HelmClient(base_url="http://h")
+        result = client.health()
+        assert result["status"] == "ok"
+
+    @patch("helm_sdk.client.httpx.Client")
+    def test_version(self, mock_client_cls: MagicMock) -> None:
+        mock_client = mock_client_cls.return_value
+        mock_client.get.return_value = mock_response(200, {
+            "version": "0.1.0",
+            "commit": "abc123",
+            "build_time": "2026-01-01T00:00:00Z",
+            "go_version": "1.24",
+        })
+
+        client = HelmClient(base_url="http://h")
+        result = client.version()
+        assert result.version == "0.1.0"
+        assert result.commit == "abc123"
+
+
+# ── Generated Types ──────────────────────────────────────
+
+class TestGeneratedTypes:
+    def test_reason_codes_cover_all_variants(self) -> None:
+        assert "ALLOW" in REASON_CODES
+        assert "ERROR_INTERNAL" in REASON_CODES
+        assert len(REASON_CODES) == 15
+
+    def test_receipt_dataclass(self) -> None:
+        r = Receipt(**RECEIPT_DATA)
+        assert r.receipt_id == "r1"
+        d = asdict(r)
+        assert d["status"] == "APPROVED"
+
+    def test_conformance_request_defaults(self) -> None:
+        req = ConformanceRequest()
+        assert req.level == "L1"
+        assert req.profile == "full"
+
+    def test_verification_result(self) -> None:
+        vr = VerificationResult(
+            verdict="PASS",
+            checks={"signatures": "PASS", "causal_chain": "PASS"},
+            errors=[],
+        )
+        assert vr.verdict == "PASS"
+        assert len(vr.errors) == 0