flo-python 0.1.0.dev2__tar.gz → 0.1.0.dev3__tar.gz

{flo_python-0.1.0.dev2 → flo_python-0.1.0.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flo-python
-Version: 0.1.0.dev2
+Version: 0.1.0.dev3
 Summary: Python SDK for the Flo distributed systems platform
 Project-URL: Homepage, https://github.com/floruntime/flo-python
 Project-URL: Documentation, https://github.com/floruntime/flo-python#readme
@@ -321,7 +321,7 @@ for record in result.records:
     try:
         process(record.payload)
         # Acknowledge successful processing
-        await client.stream.group_ack("events", "processors", [record.offset])
+        await client.stream.group_ack("events", "processors", [record.id])
     except Exception:
         # Record will be redelivered to another consumer
         pass
@@ -457,8 +457,8 @@ from flo import FloClient
 
 async def run_worker():
     async with FloClient("localhost:9000", namespace="myapp") as client:
-        # Create a worker from the client
-        worker = client.new_worker(concurrency=5)
+        # Create an action worker from the client
+        worker = client.new_action_worker(concurrency=5)
 
         @worker.action("process-image")
         async def process_image(ctx):
@@ -471,6 +471,31 @@ async def run_worker():
 asyncio.run(run_worker())
 ```
 
+### StreamWorker Example
+
+```python
+import asyncio
+from flo import FloClient, StreamContext
+
+async def process_event(ctx: StreamContext) -> None:
+    event = ctx.json()
+    print(f"Got event: {event}")
+    # Return normally → auto-ack
+    # Raise an exception → auto-nack (redelivery)
+
+async def run_stream_worker():
+    async with FloClient("localhost:9000", namespace="myapp") as client:
+        worker = client.new_stream_worker(
+            stream="events",
+            group="processors",
+            handler=process_event,
+            concurrency=5,
+        )
+        await worker.start()
+
+asyncio.run(run_stream_worker())
+```
+
 ## Configuration
 
 ### Client Options

{flo_python-0.1.0.dev2 → flo_python-0.1.0.dev3}/README.md

@@ -291,7 +291,7 @@ for record in result.records:
     try:
         process(record.payload)
         # Acknowledge successful processing
-        await client.stream.group_ack("events", "processors", [record.offset])
+        await client.stream.group_ack("events", "processors", [record.id])
     except Exception:
         # Record will be redelivered to another consumer
         pass
@@ -427,8 +427,8 @@ from flo import FloClient
 
 async def run_worker():
     async with FloClient("localhost:9000", namespace="myapp") as client:
-        # Create a worker from the client
-        worker = client.new_worker(concurrency=5)
+        # Create an action worker from the client
+        worker = client.new_action_worker(concurrency=5)
 
         @worker.action("process-image")
         async def process_image(ctx):
@@ -441,6 +441,31 @@ async def run_worker():
 asyncio.run(run_worker())
 ```
 
+### StreamWorker Example
+
+```python
+import asyncio
+from flo import FloClient, StreamContext
+
+async def process_event(ctx: StreamContext) -> None:
+    event = ctx.json()
+    print(f"Got event: {event}")
+    # Return normally → auto-ack
+    # Raise an exception → auto-nack (redelivery)
+
+async def run_stream_worker():
+    async with FloClient("localhost:9000", namespace="myapp") as client:
+        worker = client.new_stream_worker(
+            stream="events",
+            group="processors",
+            handler=process_event,
+            concurrency=5,
+        )
+        await worker.start()
+
+asyncio.run(run_stream_worker())
+```
+
 ## Configuration
 
 ### Client Options

flo_python-0.1.0.dev3/examples/stream_worker.py

@@ -0,0 +1,76 @@
+"""Example: StreamWorker usage with the Flo Python SDK
+
+Demonstrates how to use StreamWorker to process stream records
+via consumer groups with automatic ack/nack handling.
+"""
+
+import asyncio
+import logging
+import os
+import signal
+
+from flo import FloClient, StreamContext
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+
+async def process_event(ctx: StreamContext) -> None:
+    """Process a stream record.
+
+    Return normally to auto-ack. Raise an exception to auto-nack
+    (the record will be redelivered).
+    """
+    event = ctx.json()
+    logger.info(
+        f"Processing event (stream={ctx.stream}, id={ctx.stream_id}): {event}"
+    )
+
+    # Simulate work
+    await asyncio.sleep(0.1)
+
+    # If processing fails, just raise — the worker will nack for you:
+    # raise RuntimeError("transient failure")
+
+
+async def main():
+    client = FloClient(
+        os.getenv("FLO_ENDPOINT", "localhost:3000"),
+        namespace=os.getenv("FLO_NAMESPACE", "myapp"),
+        debug=os.getenv("FLO_DEBUG", "").lower() in ("1", "true"),
+    )
+    await client.connect()
+
+    worker = client.new_stream_worker(
+        stream="events",
+        group="processors",
+        handler=process_event,
+        concurrency=5,
+        batch_size=10,
+    )
+
+    # Handle shutdown signals
+    def signal_handler():
+        logger.info("Received shutdown signal")
+        worker.stop()
+
+    loop = asyncio.get_running_loop()
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        loop.add_signal_handler(sig, signal_handler)
+
+    logger.info("Starting stream worker...")
+    try:
+        await worker.start()
+    except KeyboardInterrupt:
+        logger.info("Interrupted")
+    finally:
+        await worker.close()
+        await client.close()
+        logger.info("Stream worker shutdown complete")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

flo_python-0.1.0.dev3/examples/test_decorator.py

@@ -0,0 +1,44 @@
+"""Minimal test: register an action using only the @worker.action decorator."""
+import asyncio
+import logging
+import signal
+from flo import FloClient, ActionContext
+
+logging.basicConfig(level=logging.DEBUG, format="%(asctime)s %(levelname)s %(name)s: %(message)s")
+
+
+async def main():
+    client = FloClient("localhost:9000", namespace="default", debug=True)
+    await client.connect()
+    print(f"Connected: {client.is_connected}")
+
+    worker = client.new_action_worker(concurrency=1)
+
+    @worker.action("health-check")
+    async def health_check(ctx: ActionContext) -> bytes:
+        return ctx.to_bytes({"status": "healthy"})
+
+    stop = asyncio.Event()
+
+    def on_signal():
+        print("Shutting down...")
+        worker.stop()
+        stop.set()
+
+    loop = asyncio.get_running_loop()
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        loop.add_signal_handler(sig, on_signal)
+
+    print("Starting worker with @worker.action('health-check')...")
+    try:
+        await worker.start()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        await worker.close()
+        await client.close()
+        print("Done.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{flo_python-0.1.0.dev2 → flo_python-0.1.0.dev3}/examples/worker.py

@@ -167,7 +167,7 @@ async def main():
     await client.connect()
 
     # Create a worker from the client
-    worker = client.new_worker(
+    worker = client.new_action_worker(
         concurrency=5,
         action_timeout=300,  # 5 minutes
     )

{flo_python-0.1.0.dev2 → flo_python-0.1.0.dev3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "flo-python"
-version = "0.1.0.dev2"
+version = "0.1.0.dev3"
 description = "Python SDK for the Flo distributed systems platform"
 readme = "README.md"
 license = "MIT"
@@ -45,6 +45,8 @@ packages = ["src/flo"]
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "session"
+asyncio_default_test_loop_scope = "session"
 testpaths = ["tests"]
 
 [tool.mypy]

{flo_python-0.1.0.dev2 → flo_python-0.1.0.dev3}/src/flo/__init__.py

@@ -24,7 +24,7 @@ Example:
             await client.action.invoke("process", b'{}')
 
             # Worker (created from client)
-            worker = client.new_worker(concurrency=5)
+            worker = client.new_action_worker(concurrency=5)
             worker.register_action("my-action", handler)
             await worker.start()
 
@@ -45,6 +45,7 @@ from .exceptions import (
     InvalidMagicError,
     KeyTooLargeError,
     NamespaceTooLargeError,
+    NonRetryableError,
     NotConnectedError,
     NotFoundError,
     OverloadedError,
@@ -57,11 +58,11 @@ from .exceptions import (
     UnsupportedVersionError,
     ValidationError,
     ValueTooLargeError,
+    is_connection_error,
 )
+from .processing import ProcessingOperations
 from .types import (
-    # KV types
     AckOptions,
-    # Action types
     ActionDeleteOptions,
     ActionInfo,
     ActionInvokeOptions,
@@ -86,11 +87,22 @@ from .types import (
     OpCode,
     OptionTag,
     PeekOptions,
+    ProcessingCancelOptions,
+    ProcessingListEntry,
+    ProcessingListOptions,
+    ProcessingRescaleOptions,
+    ProcessingRestoreOptions,
+    ProcessingSavepointOptions,
+    ProcessingStatusOptions,
+    ProcessingStatusResult,
+    ProcessingStopOptions,
+    ProcessingSubmitOptions,
+    ProcessingSyncOptions,
+    ProcessingSyncResult,
     PutOptions,
     ScanOptions,
     ScanResult,
     StatusCode,
-    # Stream types
     StorageTier,
     StreamAppendOptions,
     StreamAppendResult,
@@ -105,7 +117,6 @@ from .types import (
     StreamReadResult,
     StreamRecord,
     StreamTrimOptions,
-    # Worker types
     TaskAssignment,
     TouchOptions,
     VersionEntry,
@@ -119,8 +130,31 @@ from .types import (
     WorkerRegisterOptions,
     WorkerTask,
     WorkerTouchOptions,
+    WorkflowCancelOptions,
+    WorkflowCreateOptions,
+    WorkflowDisableOptions,
+    WorkflowEnableOptions,
+    WorkflowGetDefinitionOptions,
+    WorkflowHistoryOptions,
+    WorkflowListDefinitionsOptions,
+    WorkflowListRunsOptions,
+    WorkflowSignalOptions,
+    WorkflowStartOptions,
+    WorkflowStatusOptions,
+    WorkflowSyncOptions,
+    WorkflowSyncResult,
+)
+from .worker import (
+    ActionContext,
+    ActionResult,
+    ActionWorker,
+    ActionWorkerOptions,
+    StreamContext,
+    StreamRecordHandler,
+    StreamWorker,
+    StreamWorkerOptions,
 )
-from .worker import ActionContext, Worker, WorkerOptions
+from .workflows import WorkflowOperations
 
 __version__ = "0.1.0"
 
@@ -128,11 +162,19 @@ __all__ = [
     # Client
     "FloClient",
     # High-level Worker API
-    "Worker",
-    "WorkerOptions",
+    "ActionWorker",
+    "ActionWorkerOptions",
     "ActionContext",
+    "ActionResult",
+    "StreamWorker",
+    "StreamWorkerOptions",
+    "StreamContext",
+    "StreamRecordHandler",
+    "WorkflowOperations",
+    "ProcessingOperations",
     # Exceptions
     "FloError",
+    "NonRetryableError",
     "NotConnectedError",
     "ConnectionFailedError",
     "InvalidEndpointError",
@@ -156,6 +198,7 @@ __all__ = [
     "RateLimitedError",
     "InternalServerError",
     "GenericServerError",
+    "is_connection_error",
     # Types
     "OpCode",
     "StatusCode",
@@ -221,4 +264,33 @@ __all__ = [
     "WorkerCompleteOptions",
     "WorkerFailOptions",
     "WorkerListOptions",
+    # Workflow types
+    "WorkflowOperations",
+    "WorkflowCreateOptions",
+    "WorkflowGetDefinitionOptions",
+    "WorkflowStartOptions",
+    "WorkflowStatusOptions",
+    "WorkflowSignalOptions",
+    "WorkflowCancelOptions",
+    "WorkflowHistoryOptions",
+    "WorkflowListRunsOptions",
+    "WorkflowListDefinitionsOptions",
+    "WorkflowDisableOptions",
+    "WorkflowEnableOptions",
+    "WorkflowSyncOptions",
+    "WorkflowSyncResult",
+    # Processing types
+    "ProcessingOperations",
+    "ProcessingSubmitOptions",
+    "ProcessingStatusOptions",
+    "ProcessingListOptions",
+    "ProcessingStopOptions",
+    "ProcessingCancelOptions",
+    "ProcessingSavepointOptions",
+    "ProcessingRestoreOptions",
+    "ProcessingRescaleOptions",
+    "ProcessingSyncOptions",
+    "ProcessingStatusResult",
+    "ProcessingListEntry",
+    "ProcessingSyncResult",
 ]

{flo_python-0.1.0.dev2 → flo_python-0.1.0.dev3}/src/flo/actions.py

@@ -68,7 +68,7 @@ class ActionOperations:
 
         Args:
             name: Action name.
-            action_type: Type of action (USER or WASM).
+            action_type: Type of action (USER only).
             options: Optional registration options.
         """
         opts = options or ActionRegisterOptions()
@@ -231,7 +231,12 @@ class WorkerOperations:
         opts = options or WorkerRegisterOptions()
         namespace = self._client.get_namespace(opts.namespace)
 
-        value = serialize_worker_register_value(task_types)
+        value = serialize_worker_register_value(
+            task_types,
+            max_concurrency=opts.concurrency,
+            metadata=opts.metadata,
+            machine_id=opts.machine_id,
+        )
 
         await self._client._send_and_check(
             OpCode.WORKER_REGISTER,
@@ -240,6 +245,30 @@ class WorkerOperations:
             value,
         )
 
+    async def heartbeat(
+        self,
+        worker_id: str,
+        current_load: int = 0,
+        namespace: str | None = None,
+    ) -> None:
+        """Send a worker heartbeat to keep the registration alive.
+
+        Args:
+            worker_id: Worker identifier.
+            current_load: Current number of active tasks.
+            namespace: Optional namespace override.
+        """
+        import struct
+
+        ns = self._client.get_namespace(namespace)
+        value = struct.pack("<I", current_load)
+        await self._client._send_and_check(
+            OpCode.WORKER_HEARTBEAT,
+            ns,
+            worker_id.encode("utf-8"),
+            value,
+        )
+
     async def await_task(
         self,
         worker_id: str,
@@ -269,7 +298,7 @@ class WorkerOperations:
             options_builder.add_u32(OptionTag.TIMEOUT_MS, opts.timeout_ms)
 
         response = await self._client._send_and_check(
-            OpCode.WORKER_AWAIT,
+            OpCode.ACTION_AWAIT,
             namespace,
             worker_id.encode("utf-8"),
             value,
@@ -287,6 +316,7 @@ class WorkerOperations:
     async def touch(
         self,
         worker_id: str,
+        action_name: str,
         task_id: str,
         options: WorkerTouchOptions | None = None,
     ) -> None:
@@ -294,16 +324,17 @@ class WorkerOperations:
 
         Args:
             worker_id: Worker identifier.
+            action_name: Action name for routing.
             task_id: Task identifier to extend.
             options: Optional touch options (extend_ms).
         """
         opts = options or WorkerTouchOptions()
         namespace = self._client.get_namespace(opts.namespace)
 
-        value = serialize_worker_touch_value(task_id, opts.extend_ms)
+        value = serialize_worker_touch_value(action_name, task_id, opts.extend_ms)
 
         await self._client._send_and_check(
-            OpCode.WORKER_TOUCH,
+            OpCode.ACTION_TOUCH,
             namespace,
             worker_id.encode("utf-8"),
             value,
@@ -312,6 +343,7 @@ class WorkerOperations:
     async def complete(
         self,
         worker_id: str,
+        action_name: str,
         task_id: str,
         result: bytes,
         options: WorkerCompleteOptions | None = None,
@@ -320,6 +352,7 @@ class WorkerOperations:
 
         Args:
             worker_id: Worker identifier.
+            action_name: Action name for routing.
             task_id: Task identifier to complete.
             result: Result data from the task.
             options: Optional complete options.
@@ -327,10 +360,10 @@ class WorkerOperations:
         opts = options or WorkerCompleteOptions()
         namespace = self._client.get_namespace(opts.namespace)
 
-        value = serialize_worker_complete_value(task_id, result)
+        value = serialize_worker_complete_value(action_name, task_id, result, opts.outcome)
 
         await self._client._send_and_check(
-            OpCode.WORKER_COMPLETE,
+            OpCode.ACTION_COMPLETE,
             namespace,
             worker_id.encode("utf-8"),
             value,
@@ -339,6 +372,7 @@ class WorkerOperations:
     async def fail(
         self,
         worker_id: str,
+        action_name: str,
         task_id: str,
         error_message: str,
         options: WorkerFailOptions | None = None,
@@ -347,6 +381,7 @@ class WorkerOperations:
 
         Args:
             worker_id: Worker identifier.
+            action_name: Action name for routing.
             task_id: Task identifier that failed.
             error_message: Error message describing the failure.
             options: Optional fail options (retry flag).
@@ -354,19 +389,13 @@ class WorkerOperations:
         opts = options or WorkerFailOptions()
         namespace = self._client.get_namespace(opts.namespace)
 
-        value = serialize_worker_fail_value(task_id, error_message)
-
-        # Retry flag goes in TLV options (matches Go SDK)
-        options_builder = OptionsBuilder()
-        if opts.retry:
-            options_builder.add_flag(OptionTag.RETRY)
+        value = serialize_worker_fail_value(action_name, task_id, error_message, opts.retry)
 
         await self._client._send_and_check(
-            OpCode.WORKER_FAIL,
+            OpCode.ACTION_FAIL,
             namespace,
             worker_id.encode("utf-8"),
             value,
-            options_builder.build(),
         )
 
     async def list(