cascades-sdk 0.2.0__tar.gz

cascades_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: cascades-sdk
+Version: 0.2.0
+Summary: Python SDK for Cascades workflow orchestration
+Author: Noir Stack LLC
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/no1rstack/cascades
+Project-URL: Documentation, https://github.com/no1rstack/cascades/tree/main/sdk/python
+Project-URL: Repository, https://github.com/no1rstack/cascades
+Project-URL: Issues, https://github.com/no1rstack/cascades/issues
+Keywords: cascades,workflow,orchestration,dag,task,flow
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: mypy>=1.8.0; extra == "dev"
+Requires-Dist: black>=24.0.0; extra == "dev"
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+
+# Cascades SDK (Python)
+
+PyPI package for the Cascades workflow orchestration control plane.
+
+## Install
+
+```bash
+pip install cascades-sdk
+```
+
+## Quick start
+
+```python
+from cascades_sdk import task, flow, CascadesClient, wait_for_completion
+from cascades_sdk.compiler import build_dag_from_flow
+
+@task
+def add(a: int, b: int) -> int:
+    return a + b
+
+@flow
+def math_flow(a: int, b: int):
+    return add(a, b)
+
+dag = build_dag_from_flow(math_flow, {"a": 1, "b": 2})
+
+client = CascadesClient(base_url="http://localhost:3000", api_key="your_api_key")
+flow_id = client.register_flow("math_flow", dag)
+run_id = client.trigger_flow(flow_id, {"a": 1, "b": 2})
+result = wait_for_completion(client, run_id)
+print(result.get("result"))
+```
+
+## What this SDK provides
+
+- `@task` and `@flow` decorators
+- Deterministic DAG capture/compilation
+- Thin HTTP API client for flow registration and runs
+- Polling helpers (sync + async)
+
+## Publish to PyPI
+
+```bash
+python -m build
+python -m twine check dist/*
+python -m twine upload dist/*
+```

cascades_sdk-0.2.0/README.md

@@ -0,0 +1,47 @@
+# Cascades SDK (Python)
+
+PyPI package for the Cascades workflow orchestration control plane.
+
+## Install
+
+```bash
+pip install cascades-sdk
+```
+
+## Quick start
+
+```python
+from cascades_sdk import task, flow, CascadesClient, wait_for_completion
+from cascades_sdk.compiler import build_dag_from_flow
+
+@task
+def add(a: int, b: int) -> int:
+    return a + b
+
+@flow
+def math_flow(a: int, b: int):
+    return add(a, b)
+
+dag = build_dag_from_flow(math_flow, {"a": 1, "b": 2})
+
+client = CascadesClient(base_url="http://localhost:3000", api_key="your_api_key")
+flow_id = client.register_flow("math_flow", dag)
+run_id = client.trigger_flow(flow_id, {"a": 1, "b": 2})
+result = wait_for_completion(client, run_id)
+print(result.get("result"))
+```
+
+## What this SDK provides
+
+- `@task` and `@flow` decorators
+- Deterministic DAG capture/compilation
+- Thin HTTP API client for flow registration and runs
+- Polling helpers (sync + async)
+
+## Publish to PyPI
+
+```bash
+python -m build
+python -m twine check dist/*
+python -m twine upload dist/*
+```

cascades_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cascades-sdk"
+version = "0.2.0"
+description = "Python SDK for Cascades workflow orchestration"
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+authors = [
+  { name = "Noir Stack LLC" }
+]
+keywords = ["cascades", "workflow", "orchestration", "dag", "task", "flow"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules"
+]
+dependencies = [
+  "requests>=2.25.0"
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0.0",
+  "mypy>=1.8.0",
+  "black>=24.0.0",
+  "build>=1.2.0",
+  "twine>=5.0.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/no1rstack/cascades"
+Documentation = "https://github.com/no1rstack/cascades/tree/main/sdk/python"
+Repository = "https://github.com/no1rstack/cascades"
+Issues = "https://github.com/no1rstack/cascades/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["cascades_sdk*"]
+
+[tool.setuptools.package-data]
+cascades_sdk = ["py.typed"]

cascades_sdk-0.2.0/setup.cfg

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

cascades_sdk-0.2.0/src/cascades_sdk/__init__.py

@@ -0,0 +1,51 @@
+"""Cascades SDK - Python client for Cascades workflow orchestration."""
+
+__version__ = "0.2.0"
+
+from .compiler import (
+    task,
+    flow,
+    build_dag_from_flow,
+    build_dag_from_flow_json,
+    canonical_json,
+    canonicalize_dag,
+)
+
+from .client import (
+    CascadesClient,
+    CascadeClient,
+    CascadesSDKError,
+    CascadeSDKError,
+    AuthenticationError,
+    ValidationError,
+    NotFoundError,
+    RateLimitError,
+    OrchestrationError,
+    NetworkError,
+    TimeoutError,
+    wait_for_completion,
+    wait_for_completion_async,
+)
+
+__all__ = [
+    "__version__",
+    "task",
+    "flow",
+    "build_dag_from_flow",
+    "build_dag_from_flow_json",
+    "canonical_json",
+    "canonicalize_dag",
+    "CascadesClient",
+    "CascadeClient",
+    "wait_for_completion",
+    "wait_for_completion_async",
+    "CascadesSDKError",
+    "CascadeSDKError",
+    "AuthenticationError",
+    "ValidationError",
+    "NotFoundError",
+    "RateLimitError",
+    "OrchestrationError",
+    "NetworkError",
+    "TimeoutError",
+]

cascades_sdk-0.2.0/src/cascades_sdk/client/__init__.py

@@ -0,0 +1,31 @@
+"""Cascades SDK client module."""
+
+from .client import CascadesClient, CascadeClient
+from .errors import (
+    CascadesSDKError,
+    CascadeSDKError,
+    AuthenticationError,
+    ValidationError,
+    NotFoundError,
+    RateLimitError,
+    OrchestrationError,
+    NetworkError,
+    TimeoutError,
+)
+from .polling import wait_for_completion, wait_for_completion_async
+
+__all__ = [
+    "CascadesClient",
+    "CascadeClient",
+    "CascadesSDKError",
+    "CascadeSDKError",
+    "AuthenticationError",
+    "ValidationError",
+    "NotFoundError",
+    "RateLimitError",
+    "OrchestrationError",
+    "NetworkError",
+    "TimeoutError",
+    "wait_for_completion",
+    "wait_for_completion_async",
+]

cascades_sdk-0.2.0/src/cascades_sdk/client/client.py

@@ -0,0 +1,137 @@
+"""HTTP client for Cascades control plane API."""
+
+from typing import Any, Dict, Optional
+
+import requests
+
+from .errors import (
+    CascadesSDKError,
+    AuthenticationError,
+    ValidationError,
+    NotFoundError,
+    RateLimitError,
+    OrchestrationError,
+    NetworkError,
+    TimeoutError as SDKTimeoutError,
+)
+
+
+class CascadesClient:
+    """Thin HTTP client for Cascades flow registration and execution APIs."""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        timeout: int = 30,
+        verify_ssl: bool = True,
+        task_output_path_template: str = "/api/runs/{run_id}/tasks/{task_id}/output",
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self.verify_ssl = verify_ssl
+        self.task_output_path_template = task_output_path_template
+
+        self.session = requests.Session()
+        self.session.headers.update(
+            {
+                "X-API-Key": api_key,
+                "Content-Type": "application/json",
+                "User-Agent": "cascades-sdk-python/0.2.0",
+            }
+        )
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        json: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Any]:
+        url = f"{self.base_url}{path}"
+        try:
+            response = self.session.request(
+                method=method,
+                url=url,
+                json=json,
+                params=params,
+                headers=headers,
+                timeout=self.timeout,
+                verify=self.verify_ssl,
+            )
+        except requests.exceptions.Timeout as exc:
+            raise SDKTimeoutError(f"Request timeout after {self.timeout}s") from exc
+        except requests.exceptions.ConnectionError as exc:
+            raise NetworkError(f"Connection failed: {exc}") from exc
+        except requests.exceptions.RequestException as exc:
+            raise NetworkError(f"Network error: {exc}") from exc
+
+        try:
+            response_body = response.json() if response.content else {}
+        except ValueError:
+            response_body = {"raw": response.text}
+
+        if response.status_code == 401:
+            raise AuthenticationError("Authentication failed - check API key", 401, response_body)
+        if response.status_code == 400:
+            raise ValidationError(response_body.get("title", "Validation failed"), 400, response_body)
+        if response.status_code == 404:
+            raise NotFoundError(response_body.get("title", "Resource not found"), 404, response_body)
+        if response.status_code == 429:
+            raise RateLimitError(response_body.get("title", "Rate limit exceeded"), 429, response_body)
+        if response.status_code >= 500:
+            raise OrchestrationError(response_body.get("title", "Server error"), response.status_code, response_body)
+        if not response.ok:
+            raise CascadesSDKError(f"HTTP {response.status_code}: {response.text}", response.status_code, response_body)
+
+        return response_body
+
+    def register_flow(self, flow_name: str, dag: Dict[str, Any], version: str = "1.0.0") -> str:
+        response = self._request(
+            "POST",
+            "/api/flows/register",
+            json={"name": flow_name, "version": version, "dag": dag},
+        )
+        return response["id"]
+
+    def trigger_flow(self, flow_id: str, inputs: Dict[str, Any]) -> str:
+        response = self._request("POST", "/api/runs", json={"flow_id": flow_id, "input": inputs})
+        return response["run_id"]
+
+    def get_run(self, run_id: str) -> Dict[str, Any]:
+        run = self._request("GET", f"/api/runs/{run_id}")
+        status = run.get("status")
+        if isinstance(status, str):
+            run["status"] = status.lower()
+
+        if "result" not in run and "output" in run:
+            run["result"] = run.get("output")
+
+        return run
+
+    def get_flow_graph(self, flow_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/api/flows/definitions/{flow_id}/graph")
+
+    def get_run_graph(self, run_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/api/flow-runs/{run_id}/graph")
+
+    def submit_task_output(
+        self,
+        run_id: str,
+        task_id: str,
+        output: Any,
+        metadata: Optional[Dict[str, Any]] = None,
+        path_template: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        template = path_template or self.task_output_path_template
+        path = template.format(run_id=run_id, task_id=task_id)
+        payload: Dict[str, Any] = {"output": output}
+        if metadata:
+            payload["metadata"] = metadata
+        return self._request("POST", path, json=payload)
+
+
+# Backward-compatible alias
+CascadeClient = CascadesClient

cascades_sdk-0.2.0/src/cascades_sdk/client/errors.py

@@ -0,0 +1,42 @@
+"""Exception hierarchy for Cascades SDK."""
+
+
+class CascadesSDKError(Exception):
+    """Base exception for Cascades SDK errors."""
+
+    def __init__(self, message: str, status_code: int = None, response_body: dict = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_body = response_body
+
+
+# Backward-compatible alias
+CascadeSDKError = CascadesSDKError
+
+
+class AuthenticationError(CascadesSDKError):
+    """Authentication failed (HTTP 401)."""
+
+
+class ValidationError(CascadesSDKError):
+    """Request validation failed (HTTP 400)."""
+
+
+class NotFoundError(CascadesSDKError):
+    """Resource was not found (HTTP 404)."""
+
+
+class RateLimitError(CascadesSDKError):
+    """Rate limit exceeded (HTTP 429)."""
+
+
+class OrchestrationError(CascadesSDKError):
+    """Control plane orchestration error (HTTP 5xx)."""
+
+
+class NetworkError(CascadesSDKError):
+    """Network communication failed."""
+
+
+class TimeoutError(CascadesSDKError):
+    """Request or polling timeout."""

cascades_sdk-0.2.0/src/cascades_sdk/client/polling.py

@@ -0,0 +1,64 @@
+"""Polling utilities for run completion."""
+
+import asyncio
+import time
+from typing import Any, Callable, Dict, Optional
+
+from .client import CascadesClient
+from .errors import TimeoutError as SDKTimeoutError
+
+
+def wait_for_completion(
+    client: CascadesClient,
+    run_id: str,
+    timeout: int = 300,
+    poll_interval: float = 1.0,
+    on_status_change: Optional[Callable[[str], None]] = None,
+) -> Dict[str, Any]:
+    start_time = time.time()
+    last_status = None
+
+    while True:
+        elapsed = time.time() - start_time
+        if elapsed > timeout:
+            raise SDKTimeoutError(f"Run {run_id} did not complete within {timeout}s")
+
+        run = client.get_run(run_id)
+        status = run.get("status")
+
+        if status != last_status and on_status_change and isinstance(status, str):
+            on_status_change(status)
+            last_status = status
+
+        if status in ("completed", "failed", "canceled", "cancelled", "timedout", "crashed"):
+            return run
+
+        time.sleep(poll_interval)
+
+
+async def wait_for_completion_async(
+    client: CascadesClient,
+    run_id: str,
+    timeout: int = 300,
+    poll_interval: float = 1.0,
+    on_status_change: Optional[Callable[[str], None]] = None,
+) -> Dict[str, Any]:
+    start_time = time.time()
+    last_status = None
+
+    while True:
+        elapsed = time.time() - start_time
+        if elapsed > timeout:
+            raise SDKTimeoutError(f"Run {run_id} did not complete within {timeout}s")
+
+        run = await asyncio.to_thread(client.get_run, run_id)
+        status = run.get("status")
+
+        if status != last_status and on_status_change and isinstance(status, str):
+            on_status_change(status)
+            last_status = status
+
+        if status in ("completed", "failed", "canceled", "cancelled", "timedout", "crashed"):
+            return run
+
+        await asyncio.sleep(poll_interval)

cascades_sdk-0.2.0/src/cascades_sdk/compiler/__init__.py

@@ -0,0 +1,14 @@
+"""Compiler module for deterministic DAG generation from @flow functions."""
+
+from .decorators import task, flow
+from .dag_builder import build_dag_from_flow, build_dag_from_flow_json
+from .canonical import canonical_json, canonicalize_dag
+
+__all__ = [
+    "task",
+    "flow",
+    "build_dag_from_flow",
+    "build_dag_from_flow_json",
+    "canonical_json",
+    "canonicalize_dag",
+]

cascades_sdk-0.2.0/src/cascades_sdk/compiler/canonical.py

@@ -0,0 +1,28 @@
+"""Deterministic JSON serialization for DAG definitions."""
+
+import json
+from typing import Any, Dict
+
+
+def _normalize(obj: Any) -> Any:
+    if isinstance(obj, dict):
+        return {key: _normalize(obj[key]) for key in sorted(obj.keys())}
+    if isinstance(obj, list):
+        return [_normalize(item) for item in obj]
+    if isinstance(obj, (str, int, float, bool, type(None))):
+        return obj
+    return str(obj)
+
+
+def canonical_json(obj: Any) -> str:
+    """Serialize to canonical JSON string with deterministic key ordering."""
+    normalized = _normalize(obj)
+    return json.dumps(normalized, sort_keys=True, separators=(",", ":"))
+
+
+def canonicalize_dag(dag: Dict[str, Any]) -> Dict[str, Any]:
+    """Normalize DAG for deterministic comparisons."""
+    normalized_dag: Dict[str, Any] = {}
+    for key in sorted(dag.keys()):
+        normalized_dag[key] = _normalize(dag[key])
+    return normalized_dag

cascades_sdk-0.2.0/src/cascades_sdk/compiler/context.py

@@ -0,0 +1,57 @@
+"""Flow execution context for DAG capture mode."""
+
+from typing import Any, Dict, List, Optional
+import threading
+
+
+class FlowContext:
+    """Context manager that captures task calls to build a DAG."""
+
+    _thread_local = threading.local()
+
+    def __init__(self) -> None:
+        self.nodes: List[Dict[str, Any]] = []
+        self.edges: List[Dict[str, str]] = []
+        self.return_node_id: Optional[str] = None
+        self.node_counter = 0
+
+    def add_node(self, task_func: Any, args: tuple, kwargs: dict, dependencies: List[str]) -> str:
+        node_id = f"node-{self.node_counter}"
+        self.node_counter += 1
+
+        task_name = getattr(task_func, "_task_name", task_func.__name__)
+        node = {
+            "id": node_id,
+            "task_name": task_name,
+            "dependencies": dependencies,
+        }
+        self.nodes.append(node)
+
+        for dep_id in dependencies:
+            self.add_edge(dep_id, node_id)
+
+        return node_id
+
+    def add_edge(self, from_node: str, to_node: str) -> None:
+        edge = {"from": from_node, "to": to_node}
+        if edge not in self.edges:
+            self.edges.append(edge)
+
+    def set_return_node(self, node_id: str) -> None:
+        self.return_node_id = node_id
+
+    @classmethod
+    def get_current(cls) -> Optional["FlowContext"]:
+        return getattr(cls._thread_local, "context", None)
+
+    @classmethod
+    def set_current(cls, context: Optional["FlowContext"]) -> None:
+        cls._thread_local.context = context
+
+    def __enter__(self) -> "FlowContext":
+        FlowContext.set_current(self)
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> bool:
+        FlowContext.set_current(None)
+        return False

cascades_sdk-0.2.0/src/cascades_sdk/compiler/dag_builder.py

@@ -0,0 +1,61 @@
+"""DAG builder - extract DAG from @flow functions in capture mode."""
+
+import inspect
+from typing import Any, Callable, Dict, Optional
+
+from .context import FlowContext
+from .decorators import _TaskPlaceholder
+from .canonical import canonical_json
+
+
+def _build_args_for_capture(flow_func: Callable, flow_inputs: Optional[Dict[str, Any]]) -> tuple:
+    sig = inspect.signature(flow_func)
+    if not sig.parameters:
+        return tuple()
+
+    if flow_inputs is not None:
+        bound = sig.bind_partial(**flow_inputs)
+        args = []
+        for name, param in sig.parameters.items():
+            if name in bound.arguments:
+                args.append(bound.arguments[name])
+            elif param.default is not inspect._empty:
+                args.append(param.default)
+            else:
+                args.append(None)
+        return tuple(args)
+
+    return tuple(None for _ in sig.parameters)
+
+
+def build_dag_from_flow(flow_func: Callable, flow_inputs: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """Build deterministic DAG structure from a @flow-decorated function."""
+    if not getattr(flow_func, "_is_flow", False):
+        raise ValueError(f"{flow_func.__name__} is not decorated with @flow")
+
+    context = FlowContext()
+    args = _build_args_for_capture(flow_func, flow_inputs)
+
+    with context:
+        result = flow_func(*args)
+        if isinstance(result, _TaskPlaceholder):
+            context.set_return_node(result.node_id)
+
+    dag: Dict[str, Any] = {
+        "nodes": context.nodes,
+        "edges": context.edges,
+    }
+
+    if context.return_node_id:
+        dag["return_node"] = context.return_node_id
+
+    if context.nodes:
+        dag["entrypoints"] = {"default": {"node": context.nodes[0]["id"]}}
+
+    return dag
+
+
+def build_dag_from_flow_json(flow_func: Callable, flow_inputs: Optional[Dict[str, Any]] = None) -> str:
+    """Build DAG and return canonical JSON payload."""
+    dag = build_dag_from_flow(flow_func, flow_inputs=flow_inputs)
+    return canonical_json(dag)

cascades_sdk-0.2.0/src/cascades_sdk/compiler/decorators.py

@@ -0,0 +1,58 @@
+"""Decorators for task and flow definitions."""
+
+import functools
+from typing import Any, Callable, TypeVar
+
+from .context import FlowContext
+
+T = TypeVar("T", bound=Callable[..., Any])
+
+
+class _TaskPlaceholder:
+    """Placeholder returned by task wrappers during capture mode."""
+
+    def __init__(self, node_id: str, task_name: str):
+        self.node_id = node_id
+        self.task_name = task_name
+
+    def __repr__(self) -> str:
+        return f"<TaskPlaceholder {self.task_name} @ {self.node_id}>"
+
+
+def task(func: T) -> T:
+    """Mark a function as a task in a flow DAG."""
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        context = FlowContext.get_current()
+        if context is not None:
+            dependencies = []
+            for arg in args:
+                if isinstance(arg, _TaskPlaceholder):
+                    dependencies.append(arg.node_id)
+            for value in kwargs.values():
+                if isinstance(value, _TaskPlaceholder):
+                    dependencies.append(value.node_id)
+
+            node_id = context.add_node(func, args, kwargs, dependencies)
+            return _TaskPlaceholder(node_id, func.__name__)
+
+        return func(*args, **kwargs)
+
+    wrapper._is_task = True  # type: ignore[attr-defined]
+    wrapper._task_name = func.__name__  # type: ignore[attr-defined]
+    wrapper._original_func = func  # type: ignore[attr-defined]
+    return wrapper  # type: ignore[return-value]
+
+
+def flow(func: T) -> T:
+    """Mark a function as a flow definition."""
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        return func(*args, **kwargs)
+
+    wrapper._is_flow = True  # type: ignore[attr-defined]
+    wrapper._flow_name = func.__name__  # type: ignore[attr-defined]
+    wrapper._original_func = func  # type: ignore[attr-defined]
+    return wrapper  # type: ignore[return-value]

cascades_sdk-0.2.0/src/cascades_sdk/types/__init__.py

@@ -0,0 +1,32 @@
+"""TypedDict contracts for Cascades SDK."""
+
+from typing import Any, List, Optional, TypedDict
+
+
+class Node(TypedDict, total=False):
+    id: str
+    task_name: str
+    dependencies: List[str]
+
+
+class Edge(TypedDict):
+    from_node: str
+    to_node: str
+
+
+class DAGDefinition(TypedDict, total=False):
+    nodes: List[Node]
+    edges: List[dict]
+    return_node: Optional[str]
+    entrypoints: dict
+
+
+class FlowRun(TypedDict, total=False):
+    run_id: str
+    flow_id: str
+    status: str
+    result: Optional[Any]
+    error: Optional[str]
+    created_at: str
+    started_at: Optional[str]
+    completed_at: Optional[str]

cascades_sdk-0.2.0/src/cascades_sdk.egg-info/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: cascades-sdk
+Version: 0.2.0
+Summary: Python SDK for Cascades workflow orchestration
+Author: Noir Stack LLC
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/no1rstack/cascades
+Project-URL: Documentation, https://github.com/no1rstack/cascades/tree/main/sdk/python
+Project-URL: Repository, https://github.com/no1rstack/cascades
+Project-URL: Issues, https://github.com/no1rstack/cascades/issues
+Keywords: cascades,workflow,orchestration,dag,task,flow
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: mypy>=1.8.0; extra == "dev"
+Requires-Dist: black>=24.0.0; extra == "dev"
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+
+# Cascades SDK (Python)
+
+PyPI package for the Cascades workflow orchestration control plane.
+
+## Install
+
+```bash
+pip install cascades-sdk
+```
+
+## Quick start
+
+```python
+from cascades_sdk import task, flow, CascadesClient, wait_for_completion
+from cascades_sdk.compiler import build_dag_from_flow
+
+@task
+def add(a: int, b: int) -> int:
+    return a + b
+
+@flow
+def math_flow(a: int, b: int):
+    return add(a, b)
+
+dag = build_dag_from_flow(math_flow, {"a": 1, "b": 2})
+
+client = CascadesClient(base_url="http://localhost:3000", api_key="your_api_key")
+flow_id = client.register_flow("math_flow", dag)
+run_id = client.trigger_flow(flow_id, {"a": 1, "b": 2})
+result = wait_for_completion(client, run_id)
+print(result.get("result"))
+```
+
+## What this SDK provides
+
+- `@task` and `@flow` decorators
+- Deterministic DAG capture/compilation
+- Thin HTTP API client for flow registration and runs
+- Polling helpers (sync + async)
+
+## Publish to PyPI
+
+```bash
+python -m build
+python -m twine check dist/*
+python -m twine upload dist/*
+```

cascades_sdk-0.2.0/src/cascades_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+README.md
+pyproject.toml
+src/cascades_sdk/__init__.py
+src/cascades_sdk/py.typed
+src/cascades_sdk.egg-info/PKG-INFO
+src/cascades_sdk.egg-info/SOURCES.txt
+src/cascades_sdk.egg-info/dependency_links.txt
+src/cascades_sdk.egg-info/requires.txt
+src/cascades_sdk.egg-info/top_level.txt
+src/cascades_sdk/client/__init__.py
+src/cascades_sdk/client/client.py
+src/cascades_sdk/client/errors.py
+src/cascades_sdk/client/polling.py
+src/cascades_sdk/compiler/__init__.py
+src/cascades_sdk/compiler/canonical.py
+src/cascades_sdk/compiler/context.py
+src/cascades_sdk/compiler/dag_builder.py
+src/cascades_sdk/compiler/decorators.py
+src/cascades_sdk/types/__init__.py
+tests/test_client_aliases.py
+tests/test_compiler.py

cascades_sdk-0.2.0/src/cascades_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cascades_sdk-0.2.0/src/cascades_sdk.egg-info/requires.txt

@@ -0,0 +1,8 @@
+requests>=2.25.0
+
+[dev]
+pytest>=7.0.0
+mypy>=1.8.0
+black>=24.0.0
+build>=1.2.0
+twine>=5.0.0

cascades_sdk-0.2.0/src/cascades_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+cascades_sdk

cascades_sdk-0.2.0/tests/test_client_aliases.py

@@ -0,0 +1,5 @@
+from cascades_sdk import CascadesClient, CascadeClient
+
+
+def test_alias_types_match():
+    assert CascadeClient is CascadesClient

cascades_sdk-0.2.0/tests/test_compiler.py

@@ -0,0 +1,34 @@
+from cascades_sdk import flow, task
+from cascades_sdk.compiler import build_dag_from_flow, canonical_json
+
+
+@task
+def add(a, b):
+    return a + b
+
+
+@task
+def mul(a, b):
+    return a * b
+
+
+@flow
+def math_flow(a, b):
+    x = add(a, b)
+    return mul(x, 2)
+
+
+def test_build_dag_from_flow_contains_nodes_edges_and_return_node():
+    dag = build_dag_from_flow(math_flow, {"a": 1, "b": 2})
+
+    assert "nodes" in dag
+    assert "edges" in dag
+    assert "return_node" in dag
+    assert len(dag["nodes"]) == 2
+    assert len(dag["edges"]) == 1
+
+
+def test_canonical_json_is_deterministic():
+    dag_1 = build_dag_from_flow(math_flow, {"a": 1, "b": 2})
+    dag_2 = build_dag_from_flow(math_flow, {"a": 3, "b": 4})
+    assert canonical_json(dag_1) == canonical_json(dag_2)