sync: update from blackroad-operator 2026-03-14

Synced from BlackRoad-OS-Inc/blackroad-operator/orgs/personal/lucidia
BlackRoad OS — Pave Tomorrow.

RoadChain-SHA2048: fe729062952871e7
RoadChain-Identity: alexa@sovereign
RoadChain-Full: fe729062952871e77147cf6d938b799096e87d9024d7005a14c9e209e12e8ad0c825b624c7bc649fc7eeb4c284fdcab8231af77980065cc04d9f36fca479ffc2346ed3c1b73de6f240d8f9485f47c995ad5b81142f7179b84932c67914dff1c08db039349ba28fca36cb57688093bf0199268dd1c2f3448c9383000bc77cc9663066ff57b834370afc8838b18466ea9029908018b961555cccaabf2ce21649cf3cabc7f64bdcc4abdf2da259b210c342835a2cecf92bdd3b4e109b4d6e622f6934e13b2b123607bd61ce3d0f20454c9ab594f9284cffe18716619c52db57ce5f4ee2856cb96e1fa3748fe1fe65435bec297c5ab3ab58d570ec1064aea29931dd

human_machine/collaboration_protocols.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Callable, Any
+
+
+@dataclass
+class ProtocolStep:
+    """Represents a single step in a collaboration protocol.
+
+    Attributes
+    ----------
+    order : int
+        The execution order of the step (lower numbers run first).
+    description : str
+        A short description of the step's purpose.
+    action : Callable[[], Any]
+        A callable to execute for this step.
+    """
+    order: int
+    description: str
+    action: Callable[[], Any] = lambda: None
+
+
+class CollaborationProtocol:
+    """
+    Defines an ordered set of steps for human-machine collaboration.
+
+    Steps can be added with arbitrary order values and will be
+    executed in ascending order of `order`.
+    """
+
+    def __init__(self) -> None:
+        self.steps: List[ProtocolStep] = []
+
+    def add_step(self, step: ProtocolStep) -> None:
+        """Add a protocol step and maintain proper ordering."""
+        self.steps.append(step)
+        self.steps.sort(key=lambda s: s.order)
+
+    def execute(self) -> List[Any]:
+        """
+        Execute each protocol step's action in order.
+
+        Returns
+        -------
+        List[Any]
+            A list of return values from each step's action.
+        """
+        results: List[Any] = []
+        for step in self.steps:
+            results.append(step.action())
+        return results
+
+
+if __name__ == "__main__":
+    # Demonstration of a simple collaboration protocol
+    proto = CollaborationProtocol()
+    # Add steps out of order; sorting ensures correct execution order
+    proto.add_step(ProtocolStep(2, "Process input", action=lambda: "Processing done"))
+    proto.add_step(ProtocolStep(1, "Greet user", action=lambda: "Hello!"))
+    proto.add_step(ProtocolStep(3, "Say goodbye", action=lambda: "Goodbye!"))
+
+    outputs = proto.execute()
+    print(outputs)