fluid-workflow-engine-sdk 0.2.1__tar.gz

fluid_workflow_engine_sdk-0.2.1/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+dist/
+build/

fluid_workflow_engine_sdk-0.2.1/Makefile

@@ -0,0 +1,22 @@
+#MakeFile
+PROTO_SRC  := ../api/workflow/workflow_service.proto
+PROTO_DIR  := ../api/workflow
+STUB_DIR   := workflow_engine_sdk/_proto
+
+gen-stubs:
+	python -m grpc_tools.protoc \
+		--proto_path=$(PROTO_DIR) \
+		--python_out=$(STUB_DIR) \
+		--grpc_python_out=$(STUB_DIR) \
+		workflow_service.proto
+	python -c "\
+	import re, pathlib; \
+	f = pathlib.Path('$(STUB_DIR)/workflow_service_pb2_grpc.py'); \
+	f.write_text(re.sub(r'^import workflow_service_pb2', \
+	  'from workflow_engine_sdk._proto import workflow_service_pb2', \
+	  f.read_text(), flags=re.MULTILINE))"
+
+test:
+	pytest tests/ -v
+
+.PHONY: gen-stubs test

fluid_workflow_engine_sdk-0.2.1/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: fluid-workflow-engine-sdk
+Version: 0.2.1
+Summary: Python SDK for the Coredgeio Fluid workflow engine — worker registration, step execution, and workflow management
+Project-URL: Homepage, https://github.com/coredgeio/fluid-workflow-engine
+Project-URL: Repository, https://github.com/coredgeio/fluid-workflow-engine
+Project-URL: Issues, https://github.com/coredgeio/fluid-workflow-engine/issues
+Author-email: "Coredge.io" <ashok@coredge.io>
+License: Apache-2.0
+Keywords: fastapi,grpc,orchestration,saga,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+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
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: grpcio>=1.60
+Requires-Dist: httpx>=0.27
+Requires-Dist: protobuf>=4.25
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: grpcio-tools>=1.60; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'

fluid_workflow_engine_sdk-0.2.1/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fluid-workflow-engine-sdk"
+version = "0.2.1"
+description = "Python SDK for the Coredgeio Fluid workflow engine — worker registration, step execution, and workflow management"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [
+    { name = "Coredge.io", email = "ashok@coredge.io" },
+]
+keywords = ["workflow", "orchestration", "grpc", "fastapi", "saga"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "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",
+    "Topic :: System :: Distributed Computing",
+    "Framework :: FastAPI",
+    "Typing :: Typed",
+]
+dependencies = [
+    "grpcio>=1.60",
+    "protobuf>=4.25",
+    "httpx>=0.27",
+    "pyyaml>=6.0",
+    "pydantic>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/coredgeio/fluid-workflow-engine"
+Repository = "https://github.com/coredgeio/fluid-workflow-engine"
+Issues = "https://github.com/coredgeio/fluid-workflow-engine/issues"
+
+[project.optional-dependencies]
+dev = [
+    "grpcio-tools>=1.60",
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "pytest-httpx>=0.30",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["fluid_workflow_engine_sdk"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "workflow_engine_sdk/**",
+    "tests/**",
+    "Makefile",
+]

fluid_workflow_engine_sdk-0.2.1/tests/test_definition.py

@@ -0,0 +1,120 @@
+import pytest
+import yaml
+
+from workflow_engine_sdk import RetryPolicy, Step, WorkflowDefinition
+
+
+def test_minimal_workflow():
+    wf = WorkflowDefinition("hello").step(Step("greet", "sayHello"))
+    d = wf.to_dict()
+    assert d["apiVersion"] == "workflow/v1"
+    assert d["kind"] == "Workflow"
+    assert d["metadata"]["name"] == "hello"
+    assert d["spec"]["steps"][0]["name"] == "greet"
+    assert d["spec"]["steps"][0]["function"] == "sayHello"
+
+
+def test_inputs_and_outputs():
+    wf = (
+        WorkflowDefinition("wf")
+        .input("region", type="string", required=True, description="AWS region")
+        .input("count", type="integer", default="1")
+        .step(Step("s1", "fn").input("r", "{{ inputs.region }}"))
+        .output("id", "{{ steps.s1.outputs.id }}")
+    )
+    d = wf.to_dict()
+    assert d["spec"]["inputs"]["region"]["required"] is True
+    assert d["spec"]["inputs"]["region"]["description"] == "AWS region"
+    assert "required" not in d["spec"]["inputs"]["count"]
+    assert d["spec"]["steps"][0]["inputs"]["r"] == "{{ inputs.region }}"
+    assert d["spec"]["outputs"]["id"] == "{{ steps.s1.outputs.id }}"
+
+
+def test_step_full_options():
+    step = (
+        Step("deploy", "deployApp")
+        .depends_on("build", "test")
+        .dependency_mode("all")
+        .condition("{{ steps.build.outputs.ok }}")
+        .input("image", "{{ steps.build.outputs.image }}")
+        .execution_mode("grpc")
+        .timeout("5m")
+        .retry(RetryPolicy(max_retries=5, initial_backoff="2s"))
+        .compensation("rollbackDeploy", inputs={"image": "{{ inputs.image }}"})
+        .on_error("compensate")
+    )
+    d = step._to_dict()
+    assert d["dependsOn"] == ["build", "test"]
+    assert d["dependencyMode"] == "all"
+    assert d["condition"] == {"expression": "{{ steps.build.outputs.ok }}"}
+    assert d["executionMode"] == "grpc"
+    assert d["timeout"] == "5m"
+    assert d["retryPolicy"]["maxRetries"] == 5
+    assert d["retryPolicy"]["initialBackoff"] == "2s"
+    assert d["compensations"][0]["function"] == "rollbackDeploy"
+    assert d["onError"] == "compensate"
+
+
+def test_duplicate_step_name_raises():
+    wf = WorkflowDefinition("wf").step(Step("s1", "fn"))
+    with pytest.raises(ValueError, match="Duplicate step name"):
+        wf.step(Step("s1", "fn2"))
+
+
+def test_none_values_stripped_from_yaml():
+    wf = WorkflowDefinition("wf").step(Step("s1", "fn"))
+    y = wf.to_yaml()
+    assert "null" not in y
+    assert "None" not in y
+
+
+def test_to_yaml_roundtrip():
+    wf = (
+        WorkflowDefinition("roundtrip")
+        .version("2.0")
+        .description("Test workflow")
+        .input("x", type="string", required=True)
+        .step(
+            Step("step1", "doWork")
+            .input("val", "{{ inputs.x }}")
+            .retry(RetryPolicy(max_retries=3, initial_backoff="500ms"))
+        )
+        .output("result", "{{ steps.step1.outputs.val }}")
+    )
+    parsed = yaml.safe_load(wf.to_yaml())
+    assert parsed["metadata"]["name"] == "roundtrip"
+    assert parsed["metadata"]["version"] == "2.0"
+    assert parsed["spec"]["steps"][0]["retryPolicy"]["maxRetries"] == 3
+
+
+def test_retry_policy_defaults():
+    r = RetryPolicy()
+    d = r._to_dict()
+    assert d["maxRetries"] == 3
+    assert d["initialBackoff"] == "1s"
+    assert d["maxBackoff"] == "30s"
+    assert d["backoffMultiplier"] == 2.0
+
+
+def test_workflow_level_retry_policy():
+    wf = (
+        WorkflowDefinition("wf")
+        .retry_policy(RetryPolicy(max_retries=10))
+        .step(Step("s1", "fn"))
+    )
+    d = wf.to_dict()
+    assert d["spec"]["retryPolicy"]["maxRetries"] == 10
+
+
+def test_output_mapping():
+    step = Step("s", "fn").output_mapping("alias", "{{ outputs.raw }}")
+    d = step._to_dict()
+    assert d["outputs"]["alias"] == "{{ outputs.raw }}"
+
+
+def test_save_writes_file(tmp_path):
+    wf = WorkflowDefinition("saved").step(Step("s", "fn"))
+    out = tmp_path / "wf.yaml"
+    wf.save(str(out))
+    loaded = yaml.safe_load(out.read_text())
+    assert loaded["metadata"]["name"] == "saved"

fluid_workflow_engine_sdk-0.2.1/tests/test_models.py

@@ -0,0 +1,100 @@
+from datetime import datetime, timezone
+
+from workflow_engine_sdk.models import (
+    ExecutionDetail,
+    StartWorkflowResult,
+    StepState,
+    WorkflowListItem,
+    WorkflowSummary,
+)
+
+
+def _now_iso() -> str:
+    return datetime.now(tz=timezone.utc).isoformat()
+
+
+def test_execution_detail_camel_aliases():
+    data = {
+        "id": "abc-123",
+        "workflowName": "my-flow",
+        "state": "completed",
+        "inputs": {"x": 1},
+        "outputs": {"result": "ok"},
+        "steps": {
+            "step1": {
+                "name": "step1",
+                "state": "completed",
+                "outputs": {"val": 42},
+                "retryCount": 2,
+                "startedAt": _now_iso(),
+                "completedAt": _now_iso(),
+            }
+        },
+        "currentStep": "step1",
+        "failedStep": "",
+        "error": "",
+        "createdAt": _now_iso(),
+        "updatedAt": _now_iso(),
+    }
+    detail = ExecutionDetail.model_validate(data)
+    assert detail.id == "abc-123"
+    assert detail.workflow_name == "my-flow"
+    assert detail.state == "completed"
+    assert detail.steps["step1"].retry_count == 2
+    assert detail.steps["step1"].outputs["val"] == 42
+
+
+def test_execution_detail_snake_case_access():
+    detail = ExecutionDetail.model_validate({
+        "id": "x",
+        "workflowName": "wf",
+        "state": "running",
+        "createdAt": _now_iso(),
+        "updatedAt": _now_iso(),
+    })
+    assert detail.workflow_name == "wf"
+    assert detail.current_step == ""
+    assert detail.completed_at is None
+
+
+def test_step_state_defaults():
+    s = StepState(name="s1", state="pending")
+    assert s.outputs == {}
+    assert s.error == ""
+    assert s.retry_count == 0
+    assert s.started_at is None
+
+
+def test_workflow_list_item():
+    item = WorkflowListItem.model_validate({"name": "wf", "version": "1.0"})
+    assert item.name == "wf"
+    assert item.description == ""
+
+
+def test_workflow_summary_with_steps():
+    data = {
+        "name": "test-wf",
+        "steps": [
+            {
+                "name": "s1",
+                "function": "doWork",
+                "executionMode": "grpc",
+                "dependsOn": ["s0"],
+                "hasCompensation": True,
+            }
+        ],
+    }
+    summary = WorkflowSummary.model_validate(data)
+    assert summary.steps[0].execution_mode == "grpc"
+    assert summary.steps[0].depends_on == ["s0"]
+    assert summary.steps[0].has_compensation is True
+
+
+def test_start_workflow_result():
+    r = StartWorkflowResult.model_validate({
+        "success": True,
+        "workflowId": "uuid-123",
+        "message": "started",
+    })
+    assert r.success is True
+    assert r.workflow_id == "uuid-123"

fluid_workflow_engine_sdk-0.2.1/tests/test_worker.py

@@ -0,0 +1,236 @@
+import base64
+import json
+import threading
+
+import pytest
+
+from workflow_engine_sdk import RetryableError, WorkerClient
+from workflow_engine_sdk.worker import _StepWorkerServicer
+from workflow_engine_sdk._proto import workflow_service_pb2 as pb
+
+
+class _FakeContext:
+    """Minimal ServicerContext: carries optional invocation metadata."""
+
+    def __init__(self, metadata=None):
+        self._metadata = metadata or []
+
+    def invocation_metadata(self):
+        return self._metadata
+
+
+def _userinfo_metadata(**fields):
+    """Build a ('userinfo', <b64>) pair like the engine forwards (base64
+    RawURLEncoding JSON, no padding)."""
+    raw = base64.urlsafe_b64encode(json.dumps(fields).encode()).rstrip(b"=").decode()
+    return [("userinfo", raw)]
+
+
+def _make_request(**kwargs) -> pb.ExecuteStepRequest:
+    defaults = {
+        "execution_id": "exec-1",
+        "workflow_id": "wf-1",
+        "workflow_name": "test-wf",
+        "step_name": "step1",
+        "function_name": "myFn",
+        "is_compensation": False,
+        "retry_count": 0,
+    }
+    defaults.update(kwargs)
+    return pb.ExecuteStepRequest(**defaults)
+
+
+def _make_servicer(steps: dict) -> _StepWorkerServicer:
+    return _StepWorkerServicer(steps, set(), threading.Lock())
+
+
+def _drain(stream):
+    """Consume the ExecuteStep server-stream; return (logs, result) where
+    logs is the list of StepLog frames and result is the terminal
+    ExecuteStepResponse."""
+    logs, result = [], None
+    for event in stream:
+        kind = event.WhichOneof("body")
+        if kind == "log":
+            logs.append(event.log)
+        elif kind == "result":
+            result = event.result
+    return logs, result
+
+
+def _result(stream) -> pb.ExecuteStepResponse:
+    return _drain(stream)[1]
+
+
+def test_step_decorator_registers():
+    worker = WorkerClient("svc", "localhost:50052", "localhost")
+
+    @worker.step("myFn")
+    def my_fn(inputs, **_):
+        return {"out": inputs.get("x")}
+
+    assert "myFn" in worker.registered_steps()
+
+
+def test_step_duplicate_raises():
+    worker = WorkerClient("svc", "localhost:50052", "localhost")
+
+    @worker.step("fn")
+    def fn1(inputs, **_):
+        return {}
+
+    with pytest.raises(ValueError, match="already registered"):
+        @worker.step("fn")
+        def fn2(inputs, **_):
+            return {}
+
+
+def test_execute_step_success():
+    def my_fn(inputs, workflow_id, workflow_name, step_name, is_compensation, retry_count):
+        return {"result": inputs.get("val", 0) * 2}
+
+    servicer = _make_servicer({"myFn": my_fn})
+    req = _make_request()
+
+    from google.protobuf import json_format, struct_pb2
+    inputs_struct = struct_pb2.Struct()
+    json_format.ParseDict({"val": 5}, inputs_struct)
+    req = _make_request()
+    req.inputs.CopyFrom(inputs_struct)
+
+    resp = _result(servicer.ExecuteStep(req, _FakeContext()))
+    assert resp.success is True
+    assert resp.retry is False
+    out = json_format.MessageToDict(resp.outputs)
+    assert out["result"] == 10
+
+
+def test_execute_step_unknown_function():
+    servicer = _make_servicer({})
+    req = _make_request(function_name="missing")
+    resp = _result(servicer.ExecuteStep(req, _FakeContext()))
+    assert resp.success is False
+    assert "not found" in resp.error
+    assert resp.retry is False
+
+
+def test_execute_step_retryable_error():
+    def flaky(inputs, **_):
+        raise RetryableError("transient failure")
+
+    servicer = _make_servicer({"myFn": flaky})
+    req = _make_request()
+    resp = _result(servicer.ExecuteStep(req, _FakeContext()))
+    assert resp.success is False
+    assert resp.retry is True
+    assert "transient failure" in resp.error
+
+
+def test_execute_step_unexpected_error():
+    def broken(inputs, **_):
+        raise ValueError("something broke")
+
+    servicer = _make_servicer({"myFn": broken})
+    req = _make_request()
+    resp = _result(servicer.ExecuteStep(req, _FakeContext()))
+    assert resp.success is False
+    assert resp.retry is False
+    assert "something broke" in resp.error
+
+
+def test_execute_step_none_output():
+    def returns_none(inputs, **_):
+        return None
+
+    servicer = _make_servicer({"myFn": returns_none})
+    req = _make_request()
+    resp = _result(servicer.ExecuteStep(req, _FakeContext()))
+    assert resp.success is True
+
+
+def test_execute_step_streams_log_frames():
+    def chatty(inputs, log, **_):
+        log("info", "starting", phase="begin")
+        log("WARN", "halfway")
+        return {"done": True}
+
+    servicer = _make_servicer({"myFn": chatty})
+    logs, result = _drain(servicer.ExecuteStep(_make_request(), _FakeContext()))
+    assert result.success is True
+    assert [lg.message for lg in logs] == ["starting", "halfway"]
+    assert logs[0].level == "INFO" and logs[0].attrs["phase"] == "begin"
+    assert logs[1].level == "WARN"
+
+
+def test_execute_step_surfaces_auth_from_userinfo():
+    received = {}
+
+    def needs_auth(inputs, auth, **_):
+        received["auth"] = auth
+        return {}
+
+    servicer = _make_servicer({"myFn": needs_auth})
+    ctx = _FakeContext(_userinfo_metadata(preferred_username="svc", email="svc@x.com"))
+    _result(servicer.ExecuteStep(_make_request(), ctx))
+    assert received["auth"] == {"preferred_username": "svc", "email": "svc@x.com"}
+
+
+def test_execute_step_auth_none_without_header():
+    received = {}
+
+    def needs_auth(inputs, auth, **_):
+        received["auth"] = auth
+        return {}
+
+    servicer = _make_servicer({"myFn": needs_auth})
+    _result(servicer.ExecuteStep(_make_request(), _FakeContext()))
+    assert received["auth"] is None
+
+
+def test_execute_step_tracks_active_execution():
+    active: set[str] = set()
+    lock = threading.Lock()
+    started = threading.Event()   # step has begun (so it's in `active`)
+    release = threading.Event()   # let the step finish once we've snapshotted
+
+    def slow_fn(inputs, **_):
+        started.set()
+        release.wait()
+        return {}
+
+    servicer = _StepWorkerServicer({"myFn": slow_fn}, active, lock)
+    req = _make_request(execution_id="exec-tracking")
+
+    def run():
+        _result(servicer.ExecuteStep(req, _FakeContext()))
+
+    t = threading.Thread(target=run)
+    t.start()
+    started.wait()
+    with lock:
+        snapshot = set(active)   # captured while the step is mid-flight
+    release.set()
+    t.join()
+
+    assert "exec-tracking" in snapshot
+    with lock:
+        assert "exec-tracking" not in active   # discarded once the stream ends
+
+
+def test_lifespan_returns_callable():
+    worker = WorkerClient("svc", "localhost:50052", "localhost")
+    lifespan = worker.lifespan
+    assert callable(lifespan)
+
+
+def test_is_compensation_passed():
+    received = {}
+
+    def comp_fn(inputs, is_compensation, **_):
+        received["is_compensation"] = is_compensation
+        return {}
+
+    servicer = _make_servicer({"myFn": comp_fn})
+    req = _make_request(is_compensation=True)
+    _result(servicer.ExecuteStep(req, _FakeContext()))
+    assert received["is_compensation"] is True

fluid_workflow_engine_sdk-0.2.1/workflow_engine_sdk/__init__.py

@@ -0,0 +1,26 @@
+from workflow_engine_sdk.client import WorkflowEngineClient
+from workflow_engine_sdk.definition import RetryPolicy, Step, WorkflowDefinition
+from workflow_engine_sdk.exceptions import EngineError, RetryableError
+from workflow_engine_sdk.models import (
+    ExecutionDetail,
+    StartWorkflowResult,
+    StepState,
+    WorkflowListItem,
+    WorkflowSummary,
+)
+from workflow_engine_sdk.worker import WorkerClient
+
+__all__ = [
+    "RetryableError",
+    "EngineError",
+    "WorkerClient",
+    "WorkflowEngineClient",
+    "WorkflowDefinition",
+    "Step",
+    "RetryPolicy",
+    "ExecutionDetail",
+    "StepState",
+    "WorkflowSummary",
+    "WorkflowListItem",
+    "StartWorkflowResult",
+]