simpleflow-sdk 0.1.0__tar.gz

simpleflow_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: simpleflow-sdk
+Version: 0.1.0
+Summary: SimpleFlow remote runtime SDK for Python
+Requires-Python: >=3.11
+Requires-Dist: httpx<1.0.0,>=0.27.0
+Requires-Dist: PyJWT<3.0.0,>=2.10.0

simpleflow_sdk-0.1.0/README.md

@@ -0,0 +1,66 @@
+# SimpleFlow Python SDK (Remote Runtime)
+
+This SDK helps Python remote runtime backends integrate with the SimpleFlow control plane.
+
+## Features
+
+- API client for auth/session helpers, runtime registration lifecycle orchestration (`list/activate/deactivate/validate/ensure_active`), invoke, runtime events, chat message writes, queue contract publication, and chat history list/create/update.
+- Invoke token verification helper for control-plane issued tokens (HS256 shared key and RS256 public key/JWKS usage).
+- Method-level auth token overrides on control-plane and lifecycle methods.
+- Typed request errors (`SimpleFlowAuthenticationError`, `SimpleFlowAuthorizationError`, `SimpleFlowLifecycleError`).
+- Typed dataclasses for common runtime payloads and telemetry span envelopes.
+- Telemetry bridge with `simpleflow` and `otlp` modes.
+
+## Install
+
+```bash
+pip install -e ./python
+```
+
+## Minimal usage
+
+```python
+from simpleflow_sdk import RuntimeEvent, SimpleFlowClient
+
+client = SimpleFlowClient(base_url="https://api.simpleflow.example", api_token="runtime-token")
+client.write_event(
+    RuntimeEvent(
+        type="runtime.invoke.accepted",
+        agent_id="agent-1",
+        run_id="run_123"
+    )
+)
+
+telemetry = client.with_telemetry(mode="simpleflow", sample_rate=0.2)
+telemetry.emit_span(
+    span={"name": "llm.call", "start_time_ms": 1000, "end_time_ms": 1250},
+    trace_id="trace_123",
+    run_id="run_123",
+    agent_id="agent-1",
+)
+```
+
+## Security note: runtime endpoint allowlist
+
+If your control-plane backend enables `RUNTIME_ENDPOINT_ALLOWLIST`, runtime registration calls from this SDK (`register_runtime` / `ensure_runtime_registration_active`) will fail with `400` unless the registration `endpoint_url` host is included in that allowlist.
+
+## Auth verifier usage
+
+```python
+from simpleflow_sdk import InvokeTokenVerifier
+
+hs_verifier = InvokeTokenVerifier.for_hs256_shared_key(
+    issuer="https://api.simpleflow.example",
+    audience="runtime",
+    shared_key="local-dev-secret",
+)
+
+rs_verifier = InvokeTokenVerifier.for_rs256_public_key(
+    issuer="https://api.simpleflow.example",
+    audience="runtime",
+    public_key=public_key_pem,
+)
+
+# You can also pass a key per call when needed.
+claims = hs_verifier.verify(token)
+```

simpleflow_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "simpleflow-sdk"
+version = "0.1.0"
+description = "SimpleFlow remote runtime SDK for Python"
+requires-python = ">=3.11"
+dependencies = [
+  "httpx>=0.27.0,<1.0.0",
+  "PyJWT>=2.10.0,<3.0.0",
+]
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["simpleflow_sdk*"]

simpleflow_sdk-0.1.0/setup.cfg

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

simpleflow_sdk-0.1.0/simpleflow_sdk/__init__.py

@@ -0,0 +1,37 @@
+from .auth import InvokeTokenVerifier
+from .client import (
+    SimpleFlowAuthenticationError,
+    SimpleFlowAuthorizationError,
+    SimpleFlowClient,
+    SimpleFlowLifecycleError,
+    SimpleFlowRequestError,
+    TelemetryBridge,
+)
+from .contracts import (
+    ChatHistoryMessage,
+    ChatMessageWrite,
+    InvokeTrace,
+    QueueContract,
+    RuntimeEvent,
+    RuntimeRegistration,
+    TelemetrySpan,
+    WorkflowTraceTenant,
+)
+
+__all__ = [
+    "SimpleFlowClient",
+    "TelemetryBridge",
+    "SimpleFlowRequestError",
+    "SimpleFlowAuthenticationError",
+    "SimpleFlowAuthorizationError",
+    "SimpleFlowLifecycleError",
+    "InvokeTokenVerifier",
+    "RuntimeEvent",
+    "InvokeTrace",
+    "ChatHistoryMessage",
+    "ChatMessageWrite",
+    "QueueContract",
+    "RuntimeRegistration",
+    "TelemetrySpan",
+    "WorkflowTraceTenant",
+]

simpleflow_sdk-0.1.0/simpleflow_sdk/auth.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from typing import Any
+
+import jwt
+
+
+class InvokeTokenVerifier:
+    """Verify invoke tokens using HS256 shared keys or RS256 public keys.
+
+    You can pass a verification key per call via ``verify(token, key=...)`` or
+    configure a default key using ``for_hs256_shared_key`` / ``for_rs256_public_key``.
+    """
+
+    def __init__(
+        self,
+        issuer: str,
+        audience: str,
+        algorithms: list[str] | None = None,
+        verification_key: str | bytes | Any | None = None,
+    ) -> None:
+        if issuer.strip() == "":
+            raise ValueError("simpleflow sdk auth config error: issuer is required")
+        if audience.strip() == "":
+            raise ValueError("simpleflow sdk auth config error: audience is required")
+
+        self._issuer = issuer
+        self._audience = audience
+        self._algorithms = algorithms if algorithms is not None else ["HS256", "RS256"]
+        self._verification_key = verification_key
+
+    @classmethod
+    def for_hs256_shared_key(
+        cls,
+        *,
+        issuer: str,
+        audience: str,
+        shared_key: str | bytes,
+    ) -> "InvokeTokenVerifier":
+        return cls(
+            issuer=issuer,
+            audience=audience,
+            algorithms=["HS256"],
+            verification_key=shared_key,
+        )
+
+    @classmethod
+    def for_rs256_public_key(
+        cls,
+        *,
+        issuer: str,
+        audience: str,
+        public_key: str | bytes,
+    ) -> "InvokeTokenVerifier":
+        return cls(
+            issuer=issuer,
+            audience=audience,
+            algorithms=["RS256"],
+            verification_key=public_key,
+        )
+
+    def verify(
+        self, token: str, key: str | bytes | Any | None = None
+    ) -> dict[str, Any]:
+        if token.strip() == "":
+            raise ValueError("simpleflow sdk auth error: token is required")
+        verification_key = key if key is not None else self._verification_key
+        if verification_key is None:
+            raise ValueError("simpleflow sdk auth error: verification key is required")
+
+        claims = jwt.decode(
+            token,
+            key=verification_key,
+            algorithms=self._algorithms,
+            audience=self._audience,
+            issuer=self._issuer,
+            options={"require": ["exp", "iat", "iss", "aud"]},
+        )
+
+        if (
+            str(claims.get("agent_id", "")).strip() == ""
+            or str(claims.get("org_id", "")).strip() == ""
+        ):
+            raise ValueError(
+                "simpleflow sdk auth error: token missing required agent_id or org_id"
+            )
+
+        return claims