helm-sdk 0.1.0__py3-none-any.whl

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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,7 @@
+helm_sdk/__init__.py,sha256=_0BiJPT28L2kV5iDsBFLqAIktni2lo4jRd_28nt2xmw,551
+helm_sdk/client.py,sha256=Yfwuu5wAq9Nfhh2dnD3qRz0pQvTRM-xjyodQaucZklA,5788
+helm_sdk/types_gen.py,sha256=QKj4KH0L_tqmUFijIg6yxZxW1z9KsspwEJYzTVmI5DE,3528
+helm_sdk-0.1.0.dist-info/METADATA,sha256=7RxPDw97oQtwhsC-vC2m1kVoc9H31ju968EWgvloSHY,2217
+helm_sdk-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+helm_sdk-0.1.0.dist-info/top_level.txt,sha256=5V0cwQFcRzWuO0kC_cKfaUMUP1hhUGHB8H_q1YaQ7TA,9
+helm_sdk-0.1.0.dist-info/RECORD,,

helm_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

helm_sdk-0.1.0.dist-info/top_level.txt

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