xences-ai 0.1.0__tar.gz

xences_ai-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: xences-ai
+Version: 0.1.0
+Summary: Python SDK for the Xences AI execution runtime
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=42.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# xences-ai
+
+Python SDK for the Xences AI execution runtime.
+
+```bash
+pip install xences-ai
+```
+
+The client signs authentication requests with your application's RSA private key. Keep the private key in a server-side secret store — never expose it to clients or ship it in a browser or mobile application.
+
+## Connect and send a goal
+
+```python
+import os
+from xences_ai import Xences, Principal
+
+xences = Xences(
+    app_id=os.environ["XENCES_APP_ID"],
+    private_key=os.environ["XENCES_PRIVATE_KEY"],
+    base_url="https://xences.app",
+)
+
+result = xences.goals.create(
+    request="Reschedule my appointment to Friday",
+    principal=Principal(external_id=user.id),  # "human" is the default type
+)
+```
+
+For async applications use `await xences.goals.acreate(...)`.
+
+## Register operations
+
+Expose handlers for operations the platform can invoke on your application, then register them once at startup:
+
+```python
+xences.expose(
+    "orders.refund",
+    method="POST",
+    path="/orders/:id/refund",
+    input_schema={
+        "type": "object",
+        "required": ["orderId"],
+        "properties": {"orderId": {"type": "string"}},
+    },
+)(lambda input, context: orders.refund(input["orderId"]))
+
+xences.register()
+```
+
+The decorator form is also supported:
+
+```python
+@xences.expose("orders.refund", method="POST", path="/orders/:id/refund")
+def refund_order(input, context):
+    return orders.refund(input["orderId"])
+
+xences.register()
+```
+
+## Handle inbound invocations
+
+After registering operations, mount a route so the platform can call back into your app. Pass `xences_public_key` to enable signature verification on inbound requests:
+
+```python
+xences = Xences(
+    app_id=os.environ["XENCES_APP_ID"],
+    private_key=os.environ["XENCES_PRIVATE_KEY"],
+    xences_public_key=os.environ["XENCES_PUBLIC_KEY"],  # verifies inbound calls
+    base_url="https://xences.app",
+)
+```
+
+The default invoke path (`/.well-known/xences/invoke`) is sent to the platform when you call `register()`. Mount it in your web framework:
+
+### Flask
+
+```python
+from flask import Flask, request
+from xences_ai import XencesError
+
+app = Flask(__name__)
+
+@app.post("/.well-known/xences/invoke")
+def invoke():
+    try:
+        return xences.handle_request(
+            body=request.get_json(),
+            headers=dict(request.headers),
+        )
+    except XencesError as e:
+        return {"success": False, "error": str(e)}, e.status or 500
+```
+
+### FastAPI
+
+```python
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from xences_ai import XencesError
+
+app = FastAPI()
+
+@app.post("/.well-known/xences/invoke")
+async def invoke(request: Request):
+    try:
+        return await xences.ahandle_request(
+            body=await request.json(),
+            headers=dict(request.headers),
+        )
+    except XencesError as e:
+        return JSONResponse(
+            {"success": False, "error": str(e)},
+            status_code=e.status or 500,
+        )
+```
+
+`handle_request` and `ahandle_request` verify the platform's app identity, timestamp freshness, replay protection, and RSA signature before dispatching. They raise `XencesError` with a `status` code on any failure.
+
+## Key rotation
+
+Rotation is opt-in. Set `allow_key_rotation=True` and call `rotate_key()` only after registering the new public key with the platform operator:
+
+```python
+xences = Xences(
+    ...,
+    allow_key_rotation=True,
+)
+
+xences.rotate_key(new_public_key_pem)
+```

xences_ai-0.1.0/README.md

@@ -0,0 +1,130 @@
+# xences-ai
+
+Python SDK for the Xences AI execution runtime.
+
+```bash
+pip install xences-ai
+```
+
+The client signs authentication requests with your application's RSA private key. Keep the private key in a server-side secret store — never expose it to clients or ship it in a browser or mobile application.
+
+## Connect and send a goal
+
+```python
+import os
+from xences_ai import Xences, Principal
+
+xences = Xences(
+    app_id=os.environ["XENCES_APP_ID"],
+    private_key=os.environ["XENCES_PRIVATE_KEY"],
+    base_url="https://xences.app",
+)
+
+result = xences.goals.create(
+    request="Reschedule my appointment to Friday",
+    principal=Principal(external_id=user.id),  # "human" is the default type
+)
+```
+
+For async applications use `await xences.goals.acreate(...)`.
+
+## Register operations
+
+Expose handlers for operations the platform can invoke on your application, then register them once at startup:
+
+```python
+xences.expose(
+    "orders.refund",
+    method="POST",
+    path="/orders/:id/refund",
+    input_schema={
+        "type": "object",
+        "required": ["orderId"],
+        "properties": {"orderId": {"type": "string"}},
+    },
+)(lambda input, context: orders.refund(input["orderId"]))
+
+xences.register()
+```
+
+The decorator form is also supported:
+
+```python
+@xences.expose("orders.refund", method="POST", path="/orders/:id/refund")
+def refund_order(input, context):
+    return orders.refund(input["orderId"])
+
+xences.register()
+```
+
+## Handle inbound invocations
+
+After registering operations, mount a route so the platform can call back into your app. Pass `xences_public_key` to enable signature verification on inbound requests:
+
+```python
+xences = Xences(
+    app_id=os.environ["XENCES_APP_ID"],
+    private_key=os.environ["XENCES_PRIVATE_KEY"],
+    xences_public_key=os.environ["XENCES_PUBLIC_KEY"],  # verifies inbound calls
+    base_url="https://xences.app",
+)
+```
+
+The default invoke path (`/.well-known/xences/invoke`) is sent to the platform when you call `register()`. Mount it in your web framework:
+
+### Flask
+
+```python
+from flask import Flask, request
+from xences_ai import XencesError
+
+app = Flask(__name__)
+
+@app.post("/.well-known/xences/invoke")
+def invoke():
+    try:
+        return xences.handle_request(
+            body=request.get_json(),
+            headers=dict(request.headers),
+        )
+    except XencesError as e:
+        return {"success": False, "error": str(e)}, e.status or 500
+```
+
+### FastAPI
+
+```python
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from xences_ai import XencesError
+
+app = FastAPI()
+
+@app.post("/.well-known/xences/invoke")
+async def invoke(request: Request):
+    try:
+        return await xences.ahandle_request(
+            body=await request.json(),
+            headers=dict(request.headers),
+        )
+    except XencesError as e:
+        return JSONResponse(
+            {"success": False, "error": str(e)},
+            status_code=e.status or 500,
+        )
+```
+
+`handle_request` and `ahandle_request` verify the platform's app identity, timestamp freshness, replay protection, and RSA signature before dispatching. They raise `XencesError` with a `status` code on any failure.
+
+## Key rotation
+
+Rotation is opt-in. Set `allow_key_rotation=True` and call `rotate_key()` only after registering the new public key with the platform operator:
+
+```python
+xences = Xences(
+    ...,
+    allow_key_rotation=True,
+)
+
+xences.rotate_key(new_public_key_pem)
+```

xences_ai-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xences-ai"
+version = "0.1.0"
+description = "Python SDK for the Xences AI execution runtime"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = ["cryptography>=42.0"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

xences_ai-0.1.0/setup.cfg

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

xences_ai-0.1.0/src/xences_ai/__init__.py

@@ -0,0 +1,5 @@
+"""Xences AI Python SDK."""
+
+from .client import Xences, XencesError, Principal
+
+__all__ = ["Xences", "XencesError", "Principal"]

xences_ai-0.1.0/src/xences_ai/client.py

@@ -0,0 +1,483 @@
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import time
+import uuid
+from typing import Any, Callable, Dict, Optional
+from urllib.error import HTTPError
+from urllib.request import Request, urlopen
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import padding
+from cryptography.hazmat.primitives.asymmetric.rsa import RSAPrivateKey
+
+
+class XencesError(RuntimeError):
+    """Raised when the Xences platform returns an error or an invocation fails validation."""
+
+    def __init__(self, message: str, status: int = 0, body: Any = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+class Principal:
+    """Identifies the actor submitting a goal."""
+
+    def __init__(self, external_id: str, type: str = "human") -> None:
+        self.external_id = external_id
+        self.type = type
+
+
+class _GoalsNamespace:
+    """Namespace for goal operations — ``xences.goals.create(...)``."""
+
+    __slots__ = ("_sdk",)
+
+    def __init__(self, sdk: "Xences") -> None:
+        self._sdk = sdk
+
+    def create(
+        self,
+        *,
+        request: Optional[str] = None,
+        effect: Optional[str] = None,
+        input: Optional[Dict[str, Any]] = None,
+        principal: Optional[Principal] = None,
+    ) -> Any:
+        """Submit a goal to the Xences orchestrator."""
+        message = request or effect or ""
+        metadata: Dict[str, Any] = dict(input or {})
+        if effect:
+            metadata["effect"] = effect
+        p = principal or Principal(external_id="sdk-app")
+        return self._sdk._request(
+            "/api/ai/orchestrator/surfaces/sdk/respond",
+            {"message": message, "channel": "api", "metadata": metadata},
+            p,
+        )
+
+    async def acreate(
+        self,
+        *,
+        request: Optional[str] = None,
+        effect: Optional[str] = None,
+        input: Optional[Dict[str, Any]] = None,
+        principal: Optional[Principal] = None,
+    ) -> Any:
+        """Async version of ``create()``."""
+        return await asyncio.to_thread(
+            self.create, request=request, effect=effect, input=input, principal=principal
+        )
+
+
+class Xences:
+    """Server-side Xences SDK client.
+
+    Args:
+        app_id: Application ID issued by the platform operator.
+        private_key: PEM-encoded RSA private key used to sign SDK auth requests.
+            Keep this in a server-side secret store — never expose it to clients.
+        base_url: Base URL of the Xences platform (e.g. ``"https://xences.app"``).
+        xences_public_key: PEM-encoded RSA public key for verifying inbound platform
+            invocations.  Required when using ``handle_request`` / ``ahandle_request``.
+        allow_key_rotation: Set ``True`` to enable ``rotate_key()``.
+
+    Example::
+
+        xences = Xences(
+            app_id=os.environ["XENCES_APP_ID"],
+            private_key=os.environ["XENCES_PRIVATE_KEY"],
+            base_url="https://xences.app",
+        )
+    """
+
+    def __init__(
+        self,
+        app_id: str,
+        private_key: str,
+        base_url: str,
+        xences_public_key: Optional[str] = None,
+        allow_key_rotation: bool = False,
+    ) -> None:
+        if not app_id or not private_key or not base_url:
+            raise ValueError("Xences requires app_id, private_key, and base_url.")
+
+        try:
+            key = serialization.load_pem_private_key(private_key.encode(), password=None)
+        except Exception as exc:
+            raise ValueError("Xences private_key must be a valid PEM private key.") from exc
+        if not isinstance(key, RSAPrivateKey):
+            raise ValueError("Xences private_key must be an RSA private key.")
+
+        self.app_id = app_id
+        self._private_key_pem = private_key
+        self.base_url = base_url.rstrip("/")
+        self._xences_public_key = xences_public_key
+        self._allow_key_rotation = allow_key_rotation
+
+        # Token cache
+        self._token: Optional[str] = None
+        self._token_expires_at: float = 0.0
+
+        # Operation registry
+        self._operations: Dict[str, Callable[..., Any]] = {}
+        self._manifests: Dict[str, Dict[str, Any]] = {}
+        self._invocation_nonces: Dict[str, float] = {}
+
+        self.goals = _GoalsNamespace(self)
+
+    # ------------------------------------------------------------------
+    # Authentication
+    # ------------------------------------------------------------------
+
+    def _authenticate(self) -> str:
+        now = int(time.time())
+        nonce = str(uuid.uuid4())
+        message = f"{self.app_id}.{now}.{nonce}".encode()
+        key = serialization.load_pem_private_key(self._private_key_pem.encode(), password=None)
+        sig = key.sign(message, padding.PKCS1v15(), hashes.SHA256())
+        req = Request(
+            f"{self.base_url}/api/auth/sdk/token",
+            data=json.dumps(
+                {
+                    "appId": self.app_id,
+                    "timestamp": now,
+                    "nonce": nonce,
+                    "signature": base64.b64encode(sig).decode(),
+                }
+            ).encode(),
+            headers={"Accept": "application/json", "Content-Type": "application/json"},
+            method="POST",
+        )
+        try:
+            with urlopen(req, timeout=15) as resp:
+                body: Dict[str, Any] = json.loads(resp.read().decode())
+        except HTTPError as exc:
+            raw = exc.read() if exc.fp else b"{}"
+            body = json.loads(raw.decode())
+            raise XencesError(
+                body.get("error", {}).get("message", "SDK authentication failed"),
+                status=exc.code,
+                body=body,
+            ) from exc
+        token = body.get("token")
+        if not token:
+            raise XencesError(
+                body.get("error", {}).get("message", "SDK authentication failed"),
+                status=200,
+                body=body,
+            )
+        expires_in = max(60, int(body.get("expiresIn", 300)) - 30)
+        self._token = str(token)
+        self._token_expires_at = time.time() + expires_in
+        return self._token
+
+    def _access_token(self) -> str:
+        if self._token and time.time() < self._token_expires_at:
+            return self._token
+        return self._authenticate()
+
+    # ------------------------------------------------------------------
+    # HTTP transport
+    # ------------------------------------------------------------------
+
+    def _request(
+        self,
+        path: str,
+        payload: Dict[str, Any],
+        principal: Optional[Principal] = None,
+    ) -> Any:
+        token = self._access_token()
+        headers: Dict[str, str] = {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {token}",
+        }
+        if principal:
+            headers["x-xences-principal-id"] = principal.external_id
+            headers["x-xences-principal-type"] = principal.type
+        req = Request(
+            f"{self.base_url}{path}",
+            data=json.dumps(payload).encode(),
+            headers=headers,
+            method="POST",
+        )
+        try:
+            with urlopen(req, timeout=15) as resp:
+                return json.loads(resp.read().decode())
+        except HTTPError as exc:
+            raw = exc.read() if exc.fp else b"{}"
+            body = json.loads(raw.decode())
+            raise XencesError(
+                body.get("error", {}).get("message", body.get("message", "Xences request failed")),
+                status=exc.code,
+                body=body,
+            ) from exc
+
+    # ------------------------------------------------------------------
+    # Goals (legacy convenience methods — prefer xences.goals.create())
+    # ------------------------------------------------------------------
+
+    def create_goal(
+        self,
+        request: str,
+        principal: Optional[Principal] = None,
+        **input_data: Any,
+    ) -> Any:
+        """Submit a goal. Prefer ``xences.goals.create()`` for new code."""
+        return self.goals.create(request=request, input=input_data or None, principal=principal)
+
+    async def acreate_goal(
+        self,
+        request: str,
+        principal: Optional[Principal] = None,
+        **input_data: Any,
+    ) -> Any:
+        """Async version of ``create_goal()``."""
+        return await asyncio.to_thread(self.create_goal, request, principal, **input_data)
+
+    # ------------------------------------------------------------------
+    # Operations — expose / register
+    # ------------------------------------------------------------------
+
+    def expose(
+        self,
+        operation_id: str,
+        *,
+        method: str = "POST",
+        path: Optional[str] = None,
+        description: str = "",
+        input_schema: Optional[Dict[str, Any]] = None,
+        output_schema: Optional[Dict[str, Any]] = None,
+        endpoint: str = "/.well-known/xences/invoke",
+    ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        """Register an operation handler. Returns a decorator.
+
+        Functional usage::
+
+            xences.expose("orders.refund", method="POST", path="/orders/:id/refund")(
+                lambda input, ctx: orders.refund(input["orderId"])
+            )
+
+        Decorator usage::
+
+            @xences.expose("orders.refund", method="POST", path="/orders/:id/refund")
+            def refund_order(input, context):
+                return orders.refund(input["orderId"])
+        """
+        manifest: Dict[str, Any] = {
+            "operationId": operation_id,
+            "method": method,
+            "path": path or f"/{operation_id}",
+            "endpoint": endpoint,
+        }
+        if description:
+            manifest["description"] = description
+        if input_schema is not None:
+            manifest["inputSchema"] = input_schema
+        if output_schema is not None:
+            manifest["outputSchema"] = output_schema
+        self._manifests[operation_id] = manifest
+
+        def decorator(handler: Callable[..., Any]) -> Callable[..., Any]:
+            self._operations[operation_id] = handler
+            return handler
+
+        return decorator
+
+    def register(self) -> Any:
+        """Register all exposed operations with the platform.
+
+        Call once at application startup after all ``expose()`` calls.
+        """
+        operations = list(self._manifests.values())
+        if not operations:
+            return {"success": True, "data": []}
+        return self._request("/api/auth/sdk/operations", {"operations": operations})
+
+    async def aregister(self) -> Any:
+        """Async version of ``register()``."""
+        return await asyncio.to_thread(self.register)
+
+    def register_operations(self, operations: list[Dict[str, Any]]) -> Any:
+        """Register a custom list of operations directly.
+
+        Prefer ``expose()`` + ``register()`` for new code.
+        """
+        return self._request("/api/auth/sdk/operations", {"operations": operations})
+
+    async def aregister_operations(self, operations: list[Dict[str, Any]]) -> Any:
+        """Async version of ``register_operations()``."""
+        return await asyncio.to_thread(self.register_operations, operations)
+
+    # ------------------------------------------------------------------
+    # Inbound invocation handler
+    # ------------------------------------------------------------------
+
+    def _verify_invocation(
+        self,
+        *,
+        operation_id: str,
+        input_data: Dict[str, Any],
+        headers: Dict[str, str],
+    ) -> Callable[..., Any]:
+        """Verify identity, timestamp freshness, replay, and signature.
+
+        Returns the registered operation handler, or raises ``XencesError``.
+        """
+        h = {k.lower(): v for k, v in headers.items()}
+        app_id = h.get("x-xences-app-id", "").strip()
+        timestamp_str = h.get("x-xences-timestamp", "").strip()
+        nonce = h.get("x-xences-nonce", "").strip()
+        signature = h.get("x-xences-signature", "").strip()
+
+        if not app_id or app_id != self.app_id:
+            raise XencesError("Unexpected Xences app identity.", status=401)
+
+        try:
+            ts = int(timestamp_str)
+        except (ValueError, TypeError) as exc:
+            raise XencesError("Invalid or missing timestamp.", status=401) from exc
+
+        now = int(time.time())
+        if abs(now - ts) > 60:
+            raise XencesError("Expired Xences invocation.", status=401)
+        if nonce in self._invocation_nonces:
+            raise XencesError("Replayed Xences invocation.", status=401)
+
+        if self._xences_public_key and signature:
+            # Canonical form matches Node.js JSON.stringify(input)
+            canonical = json.dumps(input_data, separators=(",", ":"))
+            message = f"{operation_id}.{timestamp_str}.{nonce}.{canonical}".encode()
+            pub_key = serialization.load_pem_public_key(self._xences_public_key.encode())
+            try:
+                pub_key.verify(
+                    base64.b64decode(signature),
+                    message,
+                    padding.PKCS1v15(),
+                    hashes.SHA256(),
+                )
+            except InvalidSignature as exc:
+                raise XencesError("Invalid Xences invocation signature.", status=401) from exc
+
+        # Record nonce; purge expired entries
+        self._invocation_nonces[nonce] = float(now + 60)
+        self._invocation_nonces = {k: v for k, v in self._invocation_nonces.items() if v > now}
+
+        handler = self._operations.get(operation_id)
+        if not handler:
+            raise XencesError(f"Operation not registered: {operation_id}", status=404)
+        return handler
+
+    def handle_request(
+        self,
+        *,
+        body: Dict[str, Any],
+        headers: Dict[str, str],
+    ) -> Dict[str, Any]:
+        """Verify and dispatch an inbound platform invocation (sync).
+
+        Raises ``XencesError`` on authentication or validation failure.
+
+        Flask example::
+
+            @app.post("/.well-known/xences/invoke")
+            def invoke():
+                try:
+                    return xences.handle_request(
+                        body=request.get_json(),
+                        headers=dict(request.headers),
+                    )
+                except XencesError as e:
+                    return {"success": False, "error": str(e)}, e.status or 500
+        """
+        operation_id = str(body.get("operationId", "")).strip()
+        input_data: Dict[str, Any] = body.get("input") or {}
+        context: Dict[str, Any] = {
+            "goalId": str(body.get("goalId") or ""),
+            "actionId": str(body.get("actionId") or ""),
+            "principal": body.get("principal"),
+            "traceId": str(body.get("traceId") or ""),
+        }
+        handler = self._verify_invocation(
+            operation_id=operation_id, input_data=input_data, headers=headers
+        )
+        result = handler(input_data, context)
+        return {"success": True, "operationId": operation_id, "result": result}
+
+    async def ahandle_request(
+        self,
+        *,
+        body: Dict[str, Any],
+        headers: Dict[str, str],
+    ) -> Dict[str, Any]:
+        """Verify and dispatch an inbound platform invocation (async).
+
+        Awaits the handler result if it is a coroutine.
+
+        FastAPI example::
+
+            @app.post("/.well-known/xences/invoke")
+            async def invoke(request: Request):
+                try:
+                    return await xences.ahandle_request(
+                        body=await request.json(),
+                        headers=dict(request.headers),
+                    )
+                except XencesError as e:
+                    return JSONResponse(
+                        {"success": False, "error": str(e)},
+                        status_code=e.status or 500,
+                    )
+        """
+        operation_id = str(body.get("operationId", "")).strip()
+        input_data: Dict[str, Any] = body.get("input") or {}
+        context: Dict[str, Any] = {
+            "goalId": str(body.get("goalId") or ""),
+            "actionId": str(body.get("actionId") or ""),
+            "principal": body.get("principal"),
+            "traceId": str(body.get("traceId") or ""),
+        }
+        handler = self._verify_invocation(
+            operation_id=operation_id, input_data=input_data, headers=headers
+        )
+        result = handler(input_data, context)
+        if asyncio.iscoroutine(result):
+            result = await result
+        return {"success": True, "operationId": operation_id, "result": result}
+
+    def handle_invocation(
+        self,
+        operation_id: str,
+        input_data: Dict[str, Any],
+        context: Dict[str, Any],
+    ) -> Any:
+        """Dispatch to a registered operation directly, without HTTP validation.
+
+        .. deprecated::
+            Prefer ``handle_request()`` which includes full signature verification.
+        """
+        handler = self._operations.get(operation_id)
+        if not handler:
+            raise XencesError(f"Operation not registered: {operation_id}", status=404)
+        return handler(input_data, context)
+
+    # ------------------------------------------------------------------
+    # Key rotation
+    # ------------------------------------------------------------------
+
+    def rotate_key(self, public_key: str) -> Any:
+        """Rotate the application public key registered with the platform.
+
+        Call this *after* registering the new public key with the platform operator.
+        Only available when ``allow_key_rotation=True`` was passed to the constructor.
+        """
+        if not self._allow_key_rotation:
+            raise RuntimeError(
+                "Client key rotation is disabled. Set allow_key_rotation=True to opt in."
+            )
+        return self._request("/api/auth/sdk/rotate-key", {"publicKey": public_key})

xences_ai-0.1.0/src/xences_ai.egg-info/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: xences-ai
+Version: 0.1.0
+Summary: Python SDK for the Xences AI execution runtime
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=42.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# xences-ai
+
+Python SDK for the Xences AI execution runtime.
+
+```bash
+pip install xences-ai
+```
+
+The client signs authentication requests with your application's RSA private key. Keep the private key in a server-side secret store — never expose it to clients or ship it in a browser or mobile application.
+
+## Connect and send a goal
+
+```python
+import os
+from xences_ai import Xences, Principal
+
+xences = Xences(
+    app_id=os.environ["XENCES_APP_ID"],
+    private_key=os.environ["XENCES_PRIVATE_KEY"],
+    base_url="https://xences.app",
+)
+
+result = xences.goals.create(
+    request="Reschedule my appointment to Friday",
+    principal=Principal(external_id=user.id),  # "human" is the default type
+)
+```
+
+For async applications use `await xences.goals.acreate(...)`.
+
+## Register operations
+
+Expose handlers for operations the platform can invoke on your application, then register them once at startup:
+
+```python
+xences.expose(
+    "orders.refund",
+    method="POST",
+    path="/orders/:id/refund",
+    input_schema={
+        "type": "object",
+        "required": ["orderId"],
+        "properties": {"orderId": {"type": "string"}},
+    },
+)(lambda input, context: orders.refund(input["orderId"]))
+
+xences.register()
+```
+
+The decorator form is also supported:
+
+```python
+@xences.expose("orders.refund", method="POST", path="/orders/:id/refund")
+def refund_order(input, context):
+    return orders.refund(input["orderId"])
+
+xences.register()
+```
+
+## Handle inbound invocations
+
+After registering operations, mount a route so the platform can call back into your app. Pass `xences_public_key` to enable signature verification on inbound requests:
+
+```python
+xences = Xences(
+    app_id=os.environ["XENCES_APP_ID"],
+    private_key=os.environ["XENCES_PRIVATE_KEY"],
+    xences_public_key=os.environ["XENCES_PUBLIC_KEY"],  # verifies inbound calls
+    base_url="https://xences.app",
+)
+```
+
+The default invoke path (`/.well-known/xences/invoke`) is sent to the platform when you call `register()`. Mount it in your web framework:
+
+### Flask
+
+```python
+from flask import Flask, request
+from xences_ai import XencesError
+
+app = Flask(__name__)
+
+@app.post("/.well-known/xences/invoke")
+def invoke():
+    try:
+        return xences.handle_request(
+            body=request.get_json(),
+            headers=dict(request.headers),
+        )
+    except XencesError as e:
+        return {"success": False, "error": str(e)}, e.status or 500
+```
+
+### FastAPI
+
+```python
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from xences_ai import XencesError
+
+app = FastAPI()
+
+@app.post("/.well-known/xences/invoke")
+async def invoke(request: Request):
+    try:
+        return await xences.ahandle_request(
+            body=await request.json(),
+            headers=dict(request.headers),
+        )
+    except XencesError as e:
+        return JSONResponse(
+            {"success": False, "error": str(e)},
+            status_code=e.status or 500,
+        )
+```
+
+`handle_request` and `ahandle_request` verify the platform's app identity, timestamp freshness, replay protection, and RSA signature before dispatching. They raise `XencesError` with a `status` code on any failure.
+
+## Key rotation
+
+Rotation is opt-in. Set `allow_key_rotation=True` and call `rotate_key()` only after registering the new public key with the platform operator:
+
+```python
+xences = Xences(
+    ...,
+    allow_key_rotation=True,
+)
+
+xences.rotate_key(new_public_key_pem)
+```

xences_ai-0.1.0/src/xences_ai.egg-info/SOURCES.txt

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

xences_ai-0.1.0/src/xences_ai.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

xences_ai-0.1.0/src/xences_ai.egg-info/requires.txt

@@ -0,0 +1,4 @@
+cryptography>=42.0
+
+[dev]
+pytest>=8.0

xences_ai-0.1.0/src/xences_ai.egg-info/top_level.txt

@@ -0,0 +1 @@
+xences_ai

xences_ai-0.1.0/tests/test_client.py

@@ -0,0 +1,374 @@
+"""Tests for xences_sdk.client — mirrors the Node.js SDK test coverage."""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import time
+import unittest
+import uuid
+from unittest.mock import MagicMock, patch
+
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import padding, rsa
+
+from xences_ai import Principal, Xences, XencesError
+
+
+# ---------------------------------------------------------------------------
+# Shared key material — generated once for the whole module
+# ---------------------------------------------------------------------------
+
+def _generate_rsa_pair():
+    private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+    private_pem = private_key.private_bytes(
+        serialization.Encoding.PEM,
+        serialization.PrivateFormat.PKCS8,
+        serialization.NoEncryption(),
+    ).decode()
+    public_pem = private_key.public_key().public_bytes(
+        serialization.Encoding.PEM,
+        serialization.PublicFormat.SubjectPublicKeyInfo,
+    ).decode()
+    return private_pem, public_pem, private_key
+
+
+PRIVATE_PEM, PUBLIC_PEM, _PRIVATE_KEY_OBJ = _generate_rsa_pair()
+
+
+def _make_invocation_headers(
+    operation_id: str,
+    input_data: dict,
+    *,
+    app_id: str = "app_test",
+    private_key=None,
+) -> dict:
+    """Build the signed headers the platform would send for a callback invocation."""
+    private_key = private_key or _PRIVATE_KEY_OBJ
+    ts = str(int(time.time()))
+    nonce = str(uuid.uuid4())
+    canonical = json.dumps(input_data, separators=(",", ":"))
+    message = f"{operation_id}.{ts}.{nonce}.{canonical}".encode()
+    sig = private_key.sign(message, padding.PKCS1v15(), hashes.SHA256())
+    return {
+        "x-xences-app-id": app_id,
+        "x-xences-timestamp": ts,
+        "x-xences-nonce": nonce,
+        "x-xences-signature": base64.b64encode(sig).decode(),
+    }
+
+
+def _make_sdk(**kwargs) -> Xences:
+    defaults = dict(app_id="app_test", private_key=PRIVATE_PEM, base_url="https://xences.test")
+    defaults.update(kwargs)
+    return Xences(**defaults)
+
+
+# ---------------------------------------------------------------------------
+# Constructor validation
+# ---------------------------------------------------------------------------
+
+class TestConstructor(unittest.TestCase):
+    def test_rejects_non_pem_private_key(self):
+        with self.assertRaises(ValueError):
+            _make_sdk(private_key="not-a-key")
+
+    def test_rejects_public_key_as_private(self):
+        # A public key is valid PEM but not an RSA private key
+        with self.assertRaises(ValueError):
+            _make_sdk(private_key=PUBLIC_PEM)
+
+    def test_rejects_empty_app_id(self):
+        with self.assertRaises(ValueError):
+            _make_sdk(app_id="")
+
+    def test_accepts_valid_rsa_private_key(self):
+        sdk = _make_sdk()
+        self.assertEqual(sdk.app_id, "app_test")
+
+
+# ---------------------------------------------------------------------------
+# Token caching
+# ---------------------------------------------------------------------------
+
+class TestTokenCaching(unittest.TestCase):
+    def test_valid_cached_token_is_reused(self):
+        sdk = _make_sdk()
+        sdk._token = "cached_token"
+        sdk._token_expires_at = time.time() + 300
+
+        with patch.object(sdk, "_authenticate") as mock_auth:
+            token1 = sdk._access_token()
+            token2 = sdk._access_token()
+
+        mock_auth.assert_not_called()
+        self.assertEqual(token1, "cached_token")
+        self.assertEqual(token2, "cached_token")
+
+    def test_expired_token_triggers_reauthentication(self):
+        sdk = _make_sdk()
+        sdk._token = "old_token"
+        sdk._token_expires_at = time.time() - 1  # already expired
+
+        with patch.object(sdk, "_authenticate", return_value="new_token") as mock_auth:
+            token = sdk._access_token()
+
+        mock_auth.assert_called_once()
+        self.assertEqual(token, "new_token")
+
+    def test_multiple_access_token_calls_use_single_authenticate(self):
+        """Successive _access_token() calls should only trigger _authenticate() once."""
+        sdk = _make_sdk()
+        auth_calls = 0
+
+        def fake_authenticate():
+            nonlocal auth_calls
+            auth_calls += 1
+            sdk._token = "tok"
+            sdk._token_expires_at = time.time() + 300
+            return "tok"
+
+        with patch.object(sdk, "_authenticate", side_effect=fake_authenticate):
+            sdk._access_token()  # triggers auth, caches token
+            sdk._access_token()  # reuses cached token
+            sdk._access_token()  # reuses cached token
+
+        self.assertEqual(auth_calls, 1)
+
+
+# ---------------------------------------------------------------------------
+# Goals namespace
+# ---------------------------------------------------------------------------
+
+class TestGoalsNamespace(unittest.TestCase):
+    def test_goals_create_defaults_to_human_principal_type(self):
+        sdk = _make_sdk()
+        captured = {}
+
+        def fake_request(path, payload, principal=None):
+            captured["principal"] = principal
+            return {"success": True}
+
+        with patch.object(sdk, "_request", side_effect=fake_request):
+            sdk.goals.create(request="Do something", principal=Principal(external_id="u1"))
+
+        self.assertEqual(captured["principal"].type, "human")
+
+    def test_goals_create_sends_effect_in_metadata(self):
+        sdk = _make_sdk()
+        captured = {}
+
+        def fake_request(path, payload, principal=None):
+            captured["payload"] = payload
+            return {"success": True}
+
+        with patch.object(sdk, "_request", side_effect=fake_request):
+            sdk.goals.create(effect="send.email")
+
+        self.assertIn("effect", captured["payload"]["metadata"])
+        self.assertEqual(captured["payload"]["metadata"]["effect"], "send.email")
+
+    def test_goals_create_falls_back_to_sdk_app_principal(self):
+        sdk = _make_sdk()
+        captured = {}
+
+        def fake_request(path, payload, principal=None):
+            captured["principal"] = principal
+            return {}
+
+        with patch.object(sdk, "_request", side_effect=fake_request):
+            sdk.goals.create(request="Do something")
+
+        self.assertEqual(captured["principal"].external_id, "sdk-app")
+
+
+# ---------------------------------------------------------------------------
+# expose() and register()
+# ---------------------------------------------------------------------------
+
+class TestExposeAndRegister(unittest.TestCase):
+    def test_decorator_form_registers_handler(self):
+        sdk = _make_sdk()
+
+        @sdk.expose("ping", method="POST", path="/ping")
+        def ping(input, context):
+            return "pong"
+
+        self.assertIn("ping", sdk._operations)
+        self.assertEqual(sdk._operations["ping"]({}, {}), "pong")
+
+    def test_functional_form_registers_handler(self):
+        sdk = _make_sdk()
+        sdk.expose("ping", method="POST", path="/ping")(lambda i, c: "pong")
+        self.assertIn("ping", sdk._operations)
+        self.assertEqual(sdk._operations["ping"]({}, {}), "pong")
+
+    def test_expose_stores_manifest(self):
+        sdk = _make_sdk()
+        sdk.expose("orders.refund", method="POST", path="/orders/:id/refund")( lambda i, c: None)
+        manifest = sdk._manifests["orders.refund"]
+        self.assertEqual(manifest["operationId"], "orders.refund")
+        self.assertEqual(manifest["method"], "POST")
+        self.assertEqual(manifest["path"], "/orders/:id/refund")
+
+    def test_register_returns_empty_success_when_no_operations(self):
+        sdk = _make_sdk()
+        result = sdk.register()
+        self.assertTrue(result["success"])
+        self.assertEqual(result.get("data", []), [])
+
+    def test_register_calls_platform_with_manifests(self):
+        sdk = _make_sdk()
+        sdk.expose("ping", method="POST", path="/ping")(lambda i, c: None)
+        captured = {}
+
+        def fake_request(path, payload, principal=None):
+            captured["path"] = path
+            captured["payload"] = payload
+            return {"success": True}
+
+        with patch.object(sdk, "_request", side_effect=fake_request):
+            sdk.register()
+
+        self.assertEqual(captured["path"], "/api/auth/sdk/operations")
+        ops = captured["payload"]["operations"]
+        self.assertEqual(len(ops), 1)
+        self.assertEqual(ops[0]["operationId"], "ping")
+
+
+# ---------------------------------------------------------------------------
+# handle_request — sync inbound invocation handler
+# ---------------------------------------------------------------------------
+
+class TestHandleRequest(unittest.TestCase):
+    def _make_verified_sdk(self) -> Xences:
+        return _make_sdk(xences_public_key=PUBLIC_PEM)
+
+    def test_dispatches_registered_operation(self):
+        sdk = self._make_verified_sdk()
+        sdk.expose("health.check", method="POST", path="/health")(lambda i, c: {"ok": True})
+        headers = _make_invocation_headers("health.check", {})
+        result = sdk.handle_request(body={"operationId": "health.check", "input": {}}, headers=headers)
+        self.assertTrue(result["success"])
+        self.assertEqual(result["result"], {"ok": True})
+        self.assertEqual(result["operationId"], "health.check")
+
+    def test_rejects_wrong_app_id(self):
+        sdk = self._make_verified_sdk()
+        sdk.expose("orders.refund", method="POST", path="/orders/:id/refund")(lambda i, c: None)
+        headers = _make_invocation_headers("orders.refund", {"orderId": "42"}, app_id="app_other")
+        with self.assertRaises(XencesError) as ctx:
+            sdk.handle_request(
+                body={"operationId": "orders.refund", "input": {"orderId": "42"}},
+                headers=headers,
+            )
+        self.assertEqual(ctx.exception.status, 401)
+
+    def test_rejects_replayed_nonce(self):
+        sdk = self._make_verified_sdk()
+        sdk.expose("health.check", method="POST", path="/health")(lambda i, c: {"ok": True})
+        headers = _make_invocation_headers("health.check", {})
+        body = {"operationId": "health.check", "input": {}}
+        sdk.handle_request(body=body, headers=headers)  # first call — OK
+        with self.assertRaises(XencesError) as ctx:
+            sdk.handle_request(body=body, headers=headers)  # replay — must fail
+        self.assertEqual(ctx.exception.status, 401)
+
+    def test_rejects_unregistered_operation(self):
+        sdk = self._make_verified_sdk()
+        headers = _make_invocation_headers("unknown.op", {})
+        with self.assertRaises(XencesError) as ctx:
+            sdk.handle_request(body={"operationId": "unknown.op", "input": {}}, headers=headers)
+        self.assertEqual(ctx.exception.status, 404)
+
+    def test_headers_are_case_insensitive(self):
+        sdk = self._make_verified_sdk()
+        sdk.expose("ping", method="POST", path="/ping")(lambda i, c: "pong")
+        h = _make_invocation_headers("ping", {})
+        # Upper-case all header names
+        upper_h = {k.upper(): v for k, v in h.items()}
+        result = sdk.handle_request(body={"operationId": "ping", "input": {}}, headers=upper_h)
+        self.assertTrue(result["success"])
+
+    def test_passes_context_to_handler(self):
+        sdk = self._make_verified_sdk()
+        received_context: dict = {}
+
+        def handler(inp, ctx):
+            received_context.update(ctx)
+            return None
+
+        sdk.expose("ctx.check", method="POST", path="/ctx")(handler)
+        headers = _make_invocation_headers("ctx.check", {})
+        sdk.handle_request(
+            body={
+                "operationId": "ctx.check",
+                "input": {},
+                "goalId": "goal-1",
+                "traceId": "trace-99",
+            },
+            headers=headers,
+        )
+        self.assertEqual(received_context["goalId"], "goal-1")
+        self.assertEqual(received_context["traceId"], "trace-99")
+
+
+# ---------------------------------------------------------------------------
+# ahandle_request — async inbound invocation handler
+# ---------------------------------------------------------------------------
+
+class TestAsyncHandleRequest(unittest.IsolatedAsyncioTestCase):
+    async def test_ahandle_request_dispatches_sync_handler(self):
+        sdk = _make_sdk(xences_public_key=PUBLIC_PEM)
+        sdk.expose("ping", method="POST", path="/ping")(lambda i, c: "pong")
+        headers = _make_invocation_headers("ping", {})
+        result = await sdk.ahandle_request(body={"operationId": "ping", "input": {}}, headers=headers)
+        self.assertTrue(result["success"])
+        self.assertEqual(result["result"], "pong")
+
+    async def test_ahandle_request_awaits_async_handler(self):
+        sdk = _make_sdk(xences_public_key=PUBLIC_PEM)
+
+        @sdk.expose("async.op", method="POST", path="/async")
+        async def async_handler(inp, ctx):
+            await asyncio.sleep(0)
+            return {"async": True}
+
+        headers = _make_invocation_headers("async.op", {})
+        result = await sdk.ahandle_request(
+            body={"operationId": "async.op", "input": {}}, headers=headers
+        )
+        self.assertTrue(result["success"])
+        self.assertEqual(result["result"], {"async": True})
+
+    async def test_ahandle_request_rejects_wrong_app_id(self):
+        sdk = _make_sdk(xences_public_key=PUBLIC_PEM)
+        sdk.expose("ping", method="POST", path="/ping")(lambda i, c: "pong")
+        headers = _make_invocation_headers("ping", {}, app_id="wrong_app")
+        with self.assertRaises(XencesError) as ctx:
+            await sdk.ahandle_request(body={"operationId": "ping", "input": {}}, headers=headers)
+        self.assertEqual(ctx.exception.status, 401)
+
+
+# ---------------------------------------------------------------------------
+# Key rotation
+# ---------------------------------------------------------------------------
+
+class TestKeyRotation(unittest.TestCase):
+    def test_rotate_key_raises_when_not_enabled(self):
+        sdk = _make_sdk()  # allow_key_rotation defaults to False
+        with self.assertRaises(RuntimeError):
+            sdk.rotate_key("new-public-key-pem")
+
+    def test_rotate_key_calls_platform_when_enabled(self):
+        sdk = _make_sdk(allow_key_rotation=True)
+        with patch.object(sdk, "_request", return_value={"success": True}) as mock_req:
+            sdk.rotate_key("new-public-key-pem")
+        mock_req.assert_called_once_with(
+            "/api/auth/sdk/rotate-key", {"publicKey": "new-public-key-pem"}
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()