commandlayer 1.1.0__py3-none-any.whl

commandlayer/__init__.py

@@ -0,0 +1,43 @@
+"""CommandLayer Python SDK."""
+
+from .client import CommandLayerClient, create_client, normalize_command_response
+from .errors import CommandLayerError
+from .types import (
+    CanonicalReceipt,
+    CommandResponse,
+    EnsVerifyOptions,
+    RuntimeMetadata,
+    SignerKeyResolution,
+    VerifyOptions,
+    VerifyResult,
+)
+from .verify import (
+    canonicalize_stable_json_v1,
+    parse_ed25519_pubkey,
+    recompute_receipt_hash_sha256,
+    resolve_signer_key,
+    sha256_hex_utf8,
+    verify_receipt,
+)
+
+__all__ = [
+    "CanonicalReceipt",
+    "CommandLayerClient",
+    "CommandLayerError",
+    "CommandResponse",
+    "EnsVerifyOptions",
+    "RuntimeMetadata",
+    "VerifyOptions",
+    "SignerKeyResolution",
+    "VerifyResult",
+    "canonicalize_stable_json_v1",
+    "create_client",
+    "normalize_command_response",
+    "sha256_hex_utf8",
+    "parse_ed25519_pubkey",
+    "recompute_receipt_hash_sha256",
+    "resolve_signer_key",
+    "verify_receipt",
+]
+
+__version__ = "1.1.0"

commandlayer/client.py

@@ -0,0 +1,349 @@
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import Mapping
+from typing import Any, cast
+
+import httpx
+
+from .errors import CommandLayerError
+from .types import CommandResponse, RuntimeMetadata, VerifyOptions
+from .verify import verify_receipt
+
+COMMONS_VERSION = "1.1.0"
+PACKAGE_VERSION = "1.1.0"
+DEFAULT_RUNTIME = "https://runtime.commandlayer.org"
+VERBS = {
+    "summarize",
+    "analyze",
+    "classify",
+    "clean",
+    "convert",
+    "describe",
+    "explain",
+    "format",
+    "parse",
+    "fetch",
+}
+
+
+def _normalize_base(url: str) -> str:
+    return str(url or "").rstrip("/")
+
+
+def normalize_command_response(payload: Any) -> CommandResponse:
+    if not isinstance(payload, dict):
+        raise CommandLayerError("Runtime response must be a JSON object", 502, payload)
+
+    if isinstance(payload.get("receipt"), dict):
+        response: CommandResponse = {"receipt": payload["receipt"]}
+        if isinstance(payload.get("runtime_metadata"), dict):
+            response["runtime_metadata"] = cast(RuntimeMetadata, dict(payload["runtime_metadata"]))
+        return response
+
+    receipt = dict(payload)
+    runtime_metadata = receipt.pop("trace", None)
+    response = {"receipt": receipt}
+    if isinstance(runtime_metadata, dict):
+        response["runtime_metadata"] = cast(RuntimeMetadata, runtime_metadata)
+    return response
+
+
+class CommandLayerClient:
+    """Synchronous CommandLayer client for Protocol-Commons v1.1.0 verbs."""
+
+    def __init__(
+        self,
+        runtime: str = DEFAULT_RUNTIME,
+        actor: str = "sdk-user",
+        timeout_ms: int = 30_000,
+        headers: Mapping[str, str] | None = None,
+        retries: int = 0,
+        verify_receipts: bool = False,
+        verify: VerifyOptions | None = None,
+        http_client: httpx.Client | None = None,
+    ):
+        self.runtime = _normalize_base(runtime)
+        self.actor = actor
+        self.timeout_ms = timeout_ms
+        self.retries = max(0, retries)
+        self.verify_receipts = verify_receipts is True
+        self.verify_defaults: VerifyOptions = verify or {}
+        self.default_headers = {
+            "Content-Type": "application/json",
+            "User-Agent": f"commandlayer-py/{PACKAGE_VERSION}",
+        }
+        if headers:
+            self.default_headers.update(dict(headers))
+        self._http = http_client or httpx.Client(timeout=self.timeout_ms / 1000)
+
+    def _ensure_verify_config_if_enabled(self) -> None:
+        if not self.verify_receipts:
+            return
+        explicit_public_key = self.verify_defaults.get("public_key") or self.verify_defaults.get(
+            "publicKey"
+        )
+        has_explicit = bool(str(explicit_public_key or "").strip())
+        ens = self.verify_defaults.get("ens") or {}
+        has_ens = bool(ens.get("name") and (ens.get("rpcUrl") or ens.get("rpc_url")))
+        if not has_explicit and not has_ens:
+            raise CommandLayerError(
+                "verify_receipts is enabled but no verification key config provided. "
+                "Set verify.public_key (or verify.publicKey) or verify.ens {name, rpcUrl}.",
+                400,
+            )
+
+    def summarize(
+        self,
+        *,
+        content: str,
+        style: str | None = None,
+        format: str | None = None,
+        max_tokens: int = 1000,
+    ) -> CommandResponse:
+        return self.call(
+            "summarize",
+            {
+                "input": {
+                    "content": content,
+                    "summary_style": style,
+                    "format_hint": format,
+                },
+                "limits": {"max_output_tokens": max_tokens},
+            },
+        )
+
+    def analyze(
+        self,
+        *,
+        content: str,
+        goal: str | None = None,
+        hints: list[str] | None = None,
+        max_tokens: int = 1000,
+    ) -> CommandResponse:
+        payload: dict[str, Any] = {
+            "input": content,
+            "limits": {"max_output_tokens": max_tokens},
+        }
+        if goal:
+            payload["goal"] = goal
+        if hints:
+            payload["hints"] = hints
+        return self.call("analyze", payload)
+
+    def classify(
+        self, *, content: str, max_labels: int = 5, max_tokens: int = 1000
+    ) -> CommandResponse:
+        return self.call(
+            "classify",
+            {
+                "actor": self.actor,
+                "input": {"content": content},
+                "limits": {"max_labels": max_labels, "max_output_tokens": max_tokens},
+            },
+        )
+
+    def clean(
+        self,
+        *,
+        content: str,
+        operations: list[str] | None = None,
+        max_tokens: int = 1000,
+    ) -> CommandResponse:
+        return self.call(
+            "clean",
+            {
+                "input": {
+                    "content": content,
+                    "operations": operations
+                    or ["normalize_newlines", "collapse_whitespace", "trim"],
+                },
+                "limits": {"max_output_tokens": max_tokens},
+            },
+        )
+
+    def convert(
+        self,
+        *,
+        content: str,
+        from_format: str,
+        to_format: str,
+        max_tokens: int = 1000,
+    ) -> CommandResponse:
+        return self.call(
+            "convert",
+            {
+                "input": {
+                    "content": content,
+                    "source_format": from_format,
+                    "target_format": to_format,
+                },
+                "limits": {"max_output_tokens": max_tokens},
+            },
+        )
+
+    def describe(
+        self,
+        *,
+        subject: str,
+        audience: str = "general",
+        detail: str = "medium",
+        max_tokens: int = 1000,
+    ) -> CommandResponse:
+        return self.call(
+            "describe",
+            {
+                "input": {
+                    "subject": (subject or "")[:140],
+                    "audience": audience,
+                    "detail_level": detail,
+                },
+                "limits": {"max_output_tokens": max_tokens},
+            },
+        )
+
+    def explain(
+        self,
+        *,
+        subject: str,
+        audience: str = "general",
+        style: str = "step-by-step",
+        detail: str = "medium",
+        max_tokens: int = 1000,
+    ) -> CommandResponse:
+        return self.call(
+            "explain",
+            {
+                "input": {
+                    "subject": (subject or "")[:140],
+                    "audience": audience,
+                    "style": style,
+                    "detail_level": detail,
+                },
+                "limits": {"max_output_tokens": max_tokens},
+            },
+        )
+
+    def format(self, *, content: str, to: str, max_tokens: int = 1000) -> CommandResponse:
+        return self.call(
+            "format",
+            {
+                "input": {"content": content, "target_style": to},
+                "limits": {"max_output_tokens": max_tokens},
+            },
+        )
+
+    def parse(
+        self,
+        *,
+        content: str,
+        content_type: str = "text",
+        mode: str = "best_effort",
+        target_schema: str | None = None,
+        max_tokens: int = 1000,
+    ) -> CommandResponse:
+        payload: dict[str, Any] = {
+            "input": {
+                "content": content,
+                "content_type": content_type,
+                "mode": mode,
+            },
+            "limits": {"max_output_tokens": max_tokens},
+        }
+        if target_schema:
+            payload["input"]["target_schema"] = target_schema
+        return self.call("parse", payload)
+
+    def fetch(
+        self,
+        *,
+        source: str,
+        query: str | None = None,
+        include_metadata: bool | None = None,
+        max_tokens: int = 1000,
+    ) -> CommandResponse:
+        input_obj: dict[str, Any] = {"source": source}
+        if query is not None:
+            input_obj["query"] = query
+        if include_metadata is not None:
+            input_obj["include_metadata"] = include_metadata
+        return self.call(
+            "fetch",
+            {"input": input_obj, "limits": {"max_output_tokens": max_tokens}},
+        )
+
+    def _build_payload(self, verb: str, body: dict[str, Any]) -> dict[str, Any]:
+        return {
+            "x402": {
+                "verb": verb,
+                "version": COMMONS_VERSION,
+                "entry": f"x402://{verb}agent.eth/{verb}/v{COMMONS_VERSION}",
+            },
+            "actor": body.get("actor", self.actor),
+            **body,
+        }
+
+    def _request(self, verb: str, payload: dict[str, Any]) -> httpx.Response:
+        url = f"{self.runtime}/{verb}/v{COMMONS_VERSION}"
+        attempt = 0
+        while True:
+            try:
+                return self._http.post(url, headers=self.default_headers, json=payload)
+            except httpx.TimeoutException as err:
+                if attempt >= self.retries:
+                    raise CommandLayerError("Request timed out", 408) from err
+            except httpx.HTTPError as err:
+                if attempt >= self.retries:
+                    raise CommandLayerError(f"HTTP transport error: {err}") from err
+            attempt += 1
+            time.sleep(min(0.2 * attempt, 1.0))
+
+    def call(self, verb: str, body: dict[str, Any]) -> CommandResponse:
+        if verb not in VERBS:
+            raise CommandLayerError(f"Unsupported verb: {verb}", 400)
+        self._ensure_verify_config_if_enabled()
+        payload = self._build_payload(verb, body)
+        response = self._request(verb, payload)
+
+        try:
+            data: Any = response.json()
+        except json.JSONDecodeError:
+            data = {}
+
+        if not response.is_success:
+            message = (
+                (data.get("message") if isinstance(data, dict) else None)
+                or (
+                    (data.get("error") or {}).get("message")
+                    if isinstance(data, dict) and isinstance(data.get("error"), dict)
+                    else None
+                )
+                or f"HTTP {response.status_code}"
+            )
+            raise CommandLayerError(str(message), response.status_code, data)
+
+        normalized = normalize_command_response(data)
+        if self.verify_receipts:
+            verify_result = verify_receipt(
+                normalized["receipt"],
+                public_key=self.verify_defaults.get("public_key")
+                or self.verify_defaults.get("publicKey"),
+                ens=self.verify_defaults.get("ens"),
+            )
+            if not verify_result["ok"]:
+                raise CommandLayerError("Receipt verification failed", 422, verify_result)
+        return normalized
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> CommandLayerClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+def create_client(**kwargs: Any) -> CommandLayerClient:
+    return CommandLayerClient(**kwargs)

commandlayer/errors.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class CommandLayerError(Exception):
+    """Top-level SDK error with optional HTTP metadata."""
+
+    def __init__(self, message: str, status_code: int | None = None, details: Any = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.details = details

commandlayer/types.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal, TypedDict
+
+CanonicalReceipt = dict[str, Any]
+
+
+class RuntimeMetadata(TypedDict, total=False):
+    trace_id: str
+    parent_trace_id: str | None
+    started_at: str
+    completed_at: str
+    duration_ms: int
+    provider: str
+    runtime: str
+    request_id: str
+
+
+class CommandResponse(TypedDict, total=False):
+    receipt: CanonicalReceipt
+    runtime_metadata: RuntimeMetadata
+
+
+class EnsVerifyOptions(TypedDict, total=False):
+    name: str
+    rpc_url: str
+    rpcUrl: str
+
+
+class VerifyOptions(TypedDict, total=False):
+    public_key: str
+    publicKey: str
+    ens: EnsVerifyOptions
+
+
+class VerifyChecks(TypedDict):
+    hash_matches: bool
+    signature_valid: bool
+    receipt_id_matches: bool
+    alg_matches: bool
+    canonical_matches: bool
+
+
+class VerifyValues(TypedDict):
+    verb: str | None
+    signer_id: str | None
+    alg: str | None
+    canonical: str | None
+    claimed_hash: str | None
+    recomputed_hash: str | None
+    receipt_id: str | None
+    pubkey_source: Literal["explicit", "ens"] | None
+    ens_txt_key: str | None
+
+
+class VerifyErrors(TypedDict):
+    signature_error: str | None
+    ens_error: str | None
+    verify_error: str | None
+
+
+class VerifyResult(TypedDict):
+    ok: bool
+    checks: VerifyChecks
+    values: VerifyValues
+    errors: VerifyErrors
+
+
+@dataclass(frozen=True)
+class SignerKeyResolution:
+    algorithm: Literal["ed25519"]
+    kid: str
+    raw_public_key_bytes: bytes

commandlayer/verify.py

@@ -0,0 +1,335 @@
+from __future__ import annotations
+
+import base64
+import copy
+import hashlib
+import json
+import re
+from typing import Any, Protocol
+
+from nacl.exceptions import BadSignatureError
+from nacl.signing import VerifyKey
+from web3 import Web3
+
+from .types import (
+    CanonicalReceipt,
+    CommandResponse,
+    EnsVerifyOptions,
+    SignerKeyResolution,
+    VerifyResult,
+)
+
+_ED25519_PREFIX_RE = re.compile(r"^ed25519\s*[:=]\s*(.+)$", re.IGNORECASE)
+_ED25519_HEX_RE = re.compile(r"^(0x)?[0-9a-fA-F]{64}$")
+
+
+class EnsTextResolver(Protocol):
+    def get_text(self, name: str, key: str) -> str | None: ...
+
+
+class Web3EnsTextResolver:
+    def __init__(self, rpc_url: str):
+        self._w3 = Web3(Web3.HTTPProvider(rpc_url))
+
+    def get_text(self, name: str, key: str) -> str | None:
+        if not self._w3.is_connected():
+            raise ValueError(f"Unable to connect to RPC: {self._w3.provider}")
+        ens_module = self._w3.ens  # type: ignore[attr-defined]
+        if ens_module is None:
+            raise ValueError("ENS module is unavailable on this web3 instance")
+        value = ens_module.get_text(name, key)  # type: ignore[union-attr]
+        if value is None:
+            return None
+        text = str(value).strip()
+        return text or None
+
+
+def canonicalize_stable_json_v1(value: Any) -> str:
+    def encode(v: Any) -> str:
+        if v is None:
+            return "null"
+        value_type = type(v)
+        if value_type is str:
+            return json.dumps(v, ensure_ascii=False)
+        if value_type is bool:
+            return "true" if v else "false"
+        if value_type in (int, float):
+            if isinstance(v, float):
+                if v != v or v in (float("inf"), float("-inf")):
+                    raise ValueError("canonicalize: non-finite number not allowed")
+                if v == 0.0 and str(v).startswith("-"):
+                    return "0"
+            return str(v)
+        if value_type in (complex, bytes, bytearray):
+            raise ValueError(f"canonicalize: unsupported type {value_type.__name__}")
+        if isinstance(v, list):
+            return "[" + ",".join(encode(item) for item in v) + "]"
+        if isinstance(v, dict):
+            out: list[str] = []
+            for key in sorted(v.keys()):
+                val = v[key]
+                if val is ...:
+                    raise ValueError(f'canonicalize: unsupported value for key "{key}"')
+                out.append(f"{json.dumps(str(key), ensure_ascii=False)}:{encode(val)}")
+            return "{" + ",".join(out) + "}"
+        raise ValueError(f"canonicalize: unsupported type {value_type.__name__}")
+
+    return encode(value)
+
+
+def sha256_hex_utf8(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def parse_ed25519_pubkey(text: str) -> bytes:
+    candidate = str(text).strip()
+    match = _ED25519_PREFIX_RE.match(candidate)
+    if match:
+        candidate = match.group(1).strip()
+    if _ED25519_HEX_RE.match(candidate):
+        hex_part = candidate[2:] if candidate.startswith("0x") else candidate
+        decoded = bytes.fromhex(hex_part)
+        if len(decoded) != 32:
+            raise ValueError("invalid ed25519 pubkey length")
+        return decoded
+    try:
+        decoded = base64.b64decode(candidate, validate=True)
+    except Exception as err:  # noqa: BLE001
+        raise ValueError("invalid base64 in ed25519 pubkey") from err
+    if len(decoded) != 32:
+        raise ValueError("invalid base64 ed25519 pubkey length (need 32 bytes)")
+    return decoded
+
+
+def verify_ed25519_signature_over_utf8_hash_string(
+    hash_hex: str,
+    signature_b64: str,
+    pubkey32: bytes,
+) -> bool:
+    if len(pubkey32) != 32:
+        raise ValueError("ed25519: pubkey must be 32 bytes")
+    try:
+        signature = base64.b64decode(signature_b64, validate=True)
+    except Exception as err:  # noqa: BLE001
+        raise ValueError("ed25519: signature must be valid base64") from err
+    if len(signature) != 64:
+        raise ValueError("ed25519: signature must be 64 bytes")
+    verify_key = VerifyKey(pubkey32)
+    try:
+        verify_key.verify(hash_hex.encode("utf-8"), signature)
+        return True
+    except BadSignatureError:
+        return False
+
+
+def resolve_signer_key(
+    name: str,
+    rpc_url: str,
+    *,
+    resolver: EnsTextResolver | None = None,
+) -> SignerKeyResolution:
+    if not rpc_url:
+        raise ValueError("rpcUrl is required for ENS verification")
+    txt_resolver = resolver or Web3EnsTextResolver(rpc_url)
+    signer_name = txt_resolver.get_text(name, "cl.receipt.signer")
+    if not signer_name:
+        raise ValueError(f"ENS TXT cl.receipt.signer missing for agent ENS name: {name}")
+    pub_key_text = txt_resolver.get_text(signer_name, "cl.sig.pub")
+    if not pub_key_text:
+        raise ValueError(f"ENS TXT cl.sig.pub missing for signer ENS name: {signer_name}")
+    kid = txt_resolver.get_text(signer_name, "cl.sig.kid")
+    if not kid:
+        raise ValueError(f"ENS TXT cl.sig.kid missing for signer ENS name: {signer_name}")
+    try:
+        raw_public_key_bytes = parse_ed25519_pubkey(pub_key_text)
+    except ValueError as err:
+        raise ValueError(
+            f"ENS TXT cl.sig.pub malformed for signer ENS name: {signer_name}. {err}"
+        ) from err
+    return SignerKeyResolution(
+        algorithm="ed25519",
+        kid=kid,
+        raw_public_key_bytes=raw_public_key_bytes,
+    )
+
+
+def _extract_receipt(receipt: CanonicalReceipt | CommandResponse) -> CanonicalReceipt:
+    if isinstance(receipt, dict) and isinstance(receipt.get("receipt"), dict):
+        return dict(receipt["receipt"])
+    return dict(receipt)
+
+
+def to_unsigned_receipt(receipt: CanonicalReceipt | CommandResponse) -> CanonicalReceipt:
+    target = _extract_receipt(receipt)
+    if not isinstance(target, dict):
+        raise ValueError("receipt must be an object")
+    unsigned = copy.deepcopy(target)
+    metadata = unsigned.get("metadata")
+    if isinstance(metadata, dict):
+        metadata.pop("receipt_id", None)
+        proof = metadata.get("proof")
+        if isinstance(proof, dict):
+            unsigned_proof: dict[str, str] = {}
+            for key in ("alg", "canonical", "signer_id"):
+                value = proof.get(key)
+                if isinstance(value, str):
+                    unsigned_proof[key] = value
+            metadata["proof"] = unsigned_proof
+    unsigned.pop("receipt_id", None)
+    return unsigned
+
+
+def recompute_receipt_hash_sha256(receipt: CanonicalReceipt | CommandResponse) -> dict[str, str]:
+    unsigned = to_unsigned_receipt(receipt)
+    canonical = canonicalize_stable_json_v1(unsigned)
+    return {"canonical": canonical, "hash_sha256": sha256_hex_utf8(canonical)}
+
+
+def _extract_rpc_url(ens: EnsVerifyOptions) -> str:
+    return str(ens.get("rpcUrl") or ens.get("rpc_url") or "")
+
+
+def verify_receipt(
+    receipt: CanonicalReceipt | CommandResponse,
+    public_key: str | None = None,
+    ens: EnsVerifyOptions | None = None,
+) -> VerifyResult:
+    target = _extract_receipt(receipt)
+    try:
+        proof = (
+            ((target.get("metadata") or {}).get("proof") or {}) if isinstance(target, dict) else {}
+        )
+        claimed_hash = (
+            proof.get("hash_sha256") if isinstance(proof.get("hash_sha256"), str) else None
+        )
+        signature_b64 = (
+            proof.get("signature_b64") if isinstance(proof.get("signature_b64"), str) else None
+        )
+        alg = proof.get("alg") if isinstance(proof.get("alg"), str) else None
+        canonical = proof.get("canonical") if isinstance(proof.get("canonical"), str) else None
+        signer_id = proof.get("signer_id") if isinstance(proof.get("signer_id"), str) else None
+        alg_matches = alg == "ed25519-sha256"
+        canonical_matches = canonical == "cl-stable-json-v1"
+        recomputed_hash = recompute_receipt_hash_sha256(target)["hash_sha256"]
+        hash_matches = bool(claimed_hash and claimed_hash == recomputed_hash)
+        metadata = target.get("metadata") if isinstance(target, dict) else None
+        receipt_id_value = metadata.get("receipt_id") if isinstance(metadata, dict) else None
+        receipt_id = receipt_id_value if isinstance(receipt_id_value, str) else None
+        receipt_id_matches = bool(claimed_hash and receipt_id == claimed_hash)
+
+        pubkey: bytes | None = None
+        pubkey_source: str | None = None
+        ens_error: str | None = None
+        ens_txt_key: str | None = None
+
+        if public_key:
+            pubkey = parse_ed25519_pubkey(public_key)
+            pubkey_source = "explicit"
+        elif ens:
+            ens_txt_key = "cl.receipt.signer -> cl.sig.pub, cl.sig.kid"
+            ens_name = ens.get("name")
+            if not ens_name:
+                ens_error = "ens.name is required"
+            else:
+                try:
+                    signer_key = resolve_signer_key(ens_name, _extract_rpc_url(ens))
+                    pubkey = signer_key.raw_public_key_bytes
+                    pubkey_source = "ens"
+                except Exception as err:  # noqa: BLE001
+                    ens_error = str(err)
+
+        signature_valid = False
+        signature_error: str | None = None
+        if not alg_matches:
+            signature_error = f'proof.alg must be "ed25519-sha256" (got {alg})'
+        elif not canonical_matches:
+            signature_error = f'proof.canonical must be "cl-stable-json-v1" (got {canonical})'
+        elif not claimed_hash or not signature_b64:
+            signature_error = "missing proof.hash_sha256 or proof.signature_b64"
+        elif not pubkey:
+            signature_error = (
+                ens_error or "no public key available (provide public_key/publicKey or ens)"
+            )
+        else:
+            try:
+                signature_valid = verify_ed25519_signature_over_utf8_hash_string(
+                    claimed_hash,
+                    signature_b64,
+                    pubkey,
+                )
+            except Exception as err:  # noqa: BLE001
+                signature_error = str(err)
+
+        return {
+            "ok": alg_matches
+            and canonical_matches
+            and hash_matches
+            and receipt_id_matches
+            and signature_valid,
+            "checks": {
+                "hash_matches": hash_matches,
+                "signature_valid": signature_valid,
+                "receipt_id_matches": receipt_id_matches,
+                "alg_matches": alg_matches,
+                "canonical_matches": canonical_matches,
+            },
+            "values": {
+                "verb": ((target.get("x402") or {}).get("verb"))
+                if isinstance(target, dict)
+                else None,
+                "signer_id": signer_id,
+                "alg": alg,
+                "canonical": canonical,
+                "claimed_hash": claimed_hash,
+                "recomputed_hash": recomputed_hash,
+                "receipt_id": receipt_id,
+                "pubkey_source": pubkey_source,  # type: ignore[typeddict-item]
+                "ens_txt_key": ens_txt_key,
+            },
+            "errors": {
+                "signature_error": signature_error,
+                "ens_error": ens_error,
+                "verify_error": None,
+            },
+        }
+    except Exception as err:  # noqa: BLE001
+        proof = (
+            ((target.get("metadata") or {}).get("proof") or {}) if isinstance(target, dict) else {}
+        )
+        metadata = target.get("metadata") if isinstance(target, dict) else None
+        return {
+            "ok": False,
+            "checks": {
+                "hash_matches": False,
+                "signature_valid": False,
+                "receipt_id_matches": False,
+                "alg_matches": False,
+                "canonical_matches": False,
+            },
+            "values": {
+                "verb": ((target.get("x402") or {}).get("verb"))
+                if isinstance(target, dict)
+                else None,
+                "signer_id": proof.get("signer_id")
+                if isinstance(proof.get("signer_id"), str)
+                else None,
+                "alg": proof.get("alg") if isinstance(proof.get("alg"), str) else None,
+                "canonical": proof.get("canonical")
+                if isinstance(proof.get("canonical"), str)
+                else None,
+                "claimed_hash": proof.get("hash_sha256")
+                if isinstance(proof.get("hash_sha256"), str)
+                else None,
+                "recomputed_hash": None,
+                "receipt_id": metadata.get("receipt_id")
+                if isinstance(metadata, dict) and isinstance(metadata.get("receipt_id"), str)
+                else None,
+                "pubkey_source": None,
+                "ens_txt_key": None,
+            },
+            "errors": {
+                "signature_error": None,
+                "ens_error": None,
+                "verify_error": str(err),
+            },
+        }

commandlayer-1.1.0.dist-info/METADATA

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: commandlayer
+Version: 1.1.0
+Summary: CommandLayer Python SDK — semantic verbs, signed receipts, and verification helpers.
+Author-email: CommandLayer <security@commandlayer.org>
+License: MIT
+Project-URL: Homepage, https://github.com/commandlayer/sdk
+Project-URL: Repository, https://github.com/commandlayer/sdk
+Project-URL: Documentation, https://github.com/commandlayer/sdk#readme
+Project-URL: Changelog, https://github.com/commandlayer/sdk/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/commandlayer/sdk/issues
+Keywords: commandlayer,agents,receipts,protocol-commons,ens,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pynacl>=1.5.0
+Requires-Dist: web3>=6.20.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: mypy>=1.10.0; extra == "dev"
+Requires-Dist: build>=1.1.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+
+# CommandLayer Python SDK
+
+Official Python SDK for CommandLayer Commons v1.1.0.
+
+The Python package mirrors the TypeScript SDK's protocol model:
+- client methods return `{ "receipt": ..., "runtime_metadata": ... }`,
+- the signed `receipt` is the canonical verification payload,
+- `runtime_metadata` is optional execution context, and
+- verification can use an explicit Ed25519 key or ENS discovery.
+
+## Install
+
+```bash
+pip install commandlayer
+```
+
+Supported Python versions: 3.10+.
+
+## Quick start
+
+```python
+from commandlayer import create_client, verify_receipt
+
+client = create_client(actor="docs-example")
+response = client.summarize(
+    content="CommandLayer makes agent execution verifiable.",
+    style="bullet_points",
+)
+
+print(response["receipt"]["result"]["summary"])
+print(response["receipt"]["metadata"]["receipt_id"])
+print(response.get("runtime_metadata", {}).get("duration_ms"))
+
+verification = verify_receipt(
+    response["receipt"],
+    public_key="ed25519:BASE64_PUBLIC_KEY",
+)
+print(verification["ok"])
+```
+
+## Verification
+
+```python
+result = verify_receipt(
+    response["receipt"],
+    ens={
+        "name": "summarizeagent.eth",
+        "rpcUrl": "https://mainnet.infura.io/v3/YOUR_KEY",
+    },
+)
+```
+
+## Development
+
+```bash
+cd python-sdk
+python -m venv .venv
+source .venv/bin/activate
+pip install -e '.[dev]'
+ruff check .
+mypy commandlayer
+pytest
+```

commandlayer-1.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+commandlayer/__init__.py,sha256=Sxv6j4VISGe0F9ZC9ajszd4cK4WR9K-RVQZEbTSdyAE,983
+commandlayer/client.py,sha256=27RJAbur969S12oeuJIAPlGfAed4vAcVAgUD3SdTAt4,10987
+commandlayer/errors.py,sha256=v4e6QrsrtVkTkxk77NVQgoSvOVDoJoRihdyzsmgBglQ,352
+commandlayer/types.py,sha256=8TzSj3bPpFNzI3nZ69QH--Xx7ApxJI2AAnRwxVfPeUM,1520
+commandlayer/verify.py,sha256=dM34jtudtv_gzCc4GRH68P6R11BJUqIrL9FYewCW0Es,12921
+commandlayer-1.1.0.dist-info/METADATA,sha256=b7VBudBYOHSjZp3yHHaa4Dw5uPQh01Kx0wDWqAPQwwI,2986
+commandlayer-1.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+commandlayer-1.1.0.dist-info/top_level.txt,sha256=yX7_Pcnri1VbvOWfoUEqwuz3v_tXIn4n0Lj2BI7vEi4,13
+commandlayer-1.1.0.dist-info/RECORD,,

commandlayer-1.1.0.dist-info/WHEEL

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

commandlayer-1.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+commandlayer