commandlayer 1.1.0__tar.gz

commandlayer-1.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,63 @@
+# 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/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-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-1.1.0/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-1.1.0/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