refactor(examples): clean up composition and branching demos, enhance RET_FAR documentation

Author: JohnRichard4096

demos/02_composition.py

@@ -1,4 +1,4 @@
-"""02_composition.py — Multi-node chain + DI return-value passing
+"""02_composition.py — Multi-node chain
 
 Usage:
     python demos/02_composition.py
@@ -10,19 +10,18 @@
 
 
 @Node()
-async def double() -> int:
-    return 42
+async def double() -> None:
+    pass  # placeholder: real logic goes here
 
 
 @Node()
-async def add_one(value: int) -> int:
-    # DI injects the return value (42) from double into `value`
-    return value + 1
+async def add_one() -> None:
+    pass  # placeholder: real logic goes here
 
 
 @Node()
-async def print_result(value: int) -> None:
-    print(f"Final result: {value}")
+async def print_result() -> None:
+    print("Composition complete")
 
 
 async def main() -> None:

demos/04_if_branch.py

@@ -6,48 +6,36 @@
 
 import asyncio
 
-from amrita_sense import IF, NOP, Node, WorkflowInterpreter
+from amrita_sense import IF, NOP, Node, NodeType, WorkflowInterpreter
 
 
 @Node()
-async def check_score() -> int:
-    """Simulate returning a score"""
-    return 85
-
-
-@Node()
-async def grade_a(score: int) -> str:
-    print(f"Score {score}: Excellent")
+async def grade_a() -> str:
+    print("Excellent")
     return "A"
 
 
 @Node()
-async def grade_b(score: int) -> str:
-    print(f"Score {score}: Good")
+async def grade_b() -> str:
+    print("Good")
     return "B"
 
 
 @Node()
-async def grade_c(score: int) -> str:
-    print(f"Score {score}: Pass")
+async def grade_c() -> str:
+    print("Pass")
     return "C"
 
 
-@Node()
-async def finished(grade: str) -> None:
-    print(f"Final grade: {grade}")
-
-
 async def main() -> None:
+    # Inline condition nodes via NodeType
+    cond_a = NodeType(lambda: False, wrap_to_async=False, address_able=False, tag=None)
+    cond_b = NodeType(lambda: True, wrap_to_async=False, address_able=False, tag=None)
+
     comp = (
-        IF(
-            Node(lambda score: score >= 90, wrap_to_async=False),  # type: ignore[arg-type]
-            grade_a,
-        )
-        .ELIF(Node(lambda score: score >= 75, wrap_to_async=False), grade_b)  # type: ignore[arg-type]
+        IF(cond_a, grade_a)  # type: ignore[arg-type]
+        .ELIF(cond_b, grade_b)  # type: ignore[arg-type]
         .ELSE(grade_c)
-        >> check_score
-        >> finished
         >> NOP
     )
     rendered = comp.render()

demos/05_while_loop.py

@@ -9,49 +9,48 @@
 from amrita_sense import DO, NOP, WHILE, Node, WorkflowInterpreter
 from amrita_sense.exceptions import BreakLoop
 
+_counter = 0
+
+
+@Node()
+def bump() -> None:
+    global _counter
+    _counter += 1
+
 
 @Node()
-def counter() -> int:
-    """Increment and return the counter on each call"""
-    if not hasattr(counter, "n"):
-        counter.n = 1  # type: ignore[attr-defined]
-    else:
-        counter.n += 1  # type: ignore[attr-defined]
-    return counter.n  # type: ignore[attr-defined]
+def under_three() -> bool:
+    return _counter < 3
 
 
 @Node()
-async def under_three(n: int) -> bool:
-    """WHILE loop condition"""
-    return n < 3
+def body() -> None:
+    print(f"  WHILE iteration {_counter}")
 
 
 @Node()
-def body(n: int) -> None:
-    """Loop body"""
-    print(f"  WHILE iteration {n}")
+def cond_dowhile() -> bool:
+    return _counter < 5
 
 
 @Node()
-def early_break(n: int) -> None:
-    """DO loop body: break out on iteration 3"""
-    print(f"  DO-WHILE iteration {n}")
-    if n >= 3:
+def do_body() -> None:
+    print(f"  DO-WHILE iteration {_counter}")
+    if _counter >= 3:
         raise BreakLoop
 
 
 async def main() -> None:
+    global _counter
+
     print("=== WHILE example ===")
-    wf = (counter >> WHILE(under_three).ACTION(body) >> NOP).render()
+    _counter = 0
+    wf = (bump >> WHILE(under_three).ACTION(body) >> NOP).render()
     await WorkflowInterpreter(wf).run()
 
-    # Reset counter
-    counter.n = 0  # type: ignore[attr-defined]
-
     print("\n=== DO-WHILE example ===")
-    wf2 = (
-        counter >> DO(early_break).WHILE(Node(lambda n: n < 5, wrap_to_async=False)) >> NOP  # type: ignore[arg-type]
-    ).render()
+    _counter = 0
+    wf2 = (bump >> DO(do_body).WHILE(cond_dowhile) >> NOP).render()
     await WorkflowInterpreter(wf2).run()
 
 

demos/06_try_catch.py

@@ -6,7 +6,7 @@
 
 import asyncio
 
-from amrita_sense import NOP, Node, NodeType, Try, WorkflowInterpreter
+from amrita_sense import NOP, Node, Try, WorkflowInterpreter
 
 
 @Node()
@@ -16,8 +16,8 @@ async def may_fail() -> str:
 
 
 @Node()
-async def handle_error(exc_val: ValueError):
-    """Catch ValueError and return fallback"""
+async def handle_error(exc_val: ValueError) -> None:
+    """Catch ValueError"""
     print(f"Caught: {exc_val}")
 
 
@@ -44,11 +44,13 @@ async def example_1() -> None:
 async def example_2() -> None:
     """Normal execution + THEN + FINALLY"""
     print("\n=== Example 2: normal execution + THEN + FINALLY ===")
+
+    @Node()
+    async def always_ok() -> str:
+        return "all good"
+
     comp = (
-        Try(NodeType(lambda: "all good", wrap_to_async=False, address_able=False, tag=None))  # type: ignore[arg-type]
-        .THEN(on_success)
-        .CATCH(ValueError, handle_error)
-        .FINALLY(cleanup)
+        Try(always_ok).THEN(on_success).CATCH(ValueError, handle_error).FINALLY(cleanup)
         >> NOP
     )
     rendered = comp.render()

demos/08_interrupt_suspend.py

@@ -10,20 +10,18 @@
 
 
 @Node()
-async def step_one() -> int:
+async def step_one() -> None:
     print("[1] First step")
-    return 1
 
 
 @Node()
-async def step_two(prev: int) -> int:
-    print(f"[2] Received previous result: {prev}")
-    return prev + 1
+async def step_two() -> None:
+    print("[2] Second step")
 
 
 @Node()
-async def step_three(prev: int) -> None:
-    print(f"[3] Final result: {prev}")
+async def step_three() -> None:
+    print("[3] Third step")
 
 
 async def main() -> None:

demos/10_event_base.py

@@ -15,6 +15,7 @@
 @dataclass
 class NotifyEvent(BaseEvent[str]):
     """Custom event"""
+
     message: str
 
     @property
@@ -40,7 +41,7 @@ async def produce_event() -> str:
 
 @Node()
 async def finish(result: str) -> None:
-    print(f"工作流完成: {result}")
+    print(f"[Finish] Workflow completed: {result}")
 
 
 async def main() -> None:

demos/11_event_trigger.py

@@ -15,6 +15,7 @@
 @dataclass
 class AuditEvent(ConstructableEvent):
     """Constructable event — triggered by TRIGGER_EVENT in a workflow"""
+
     action: str
 
     @property
@@ -38,7 +39,7 @@ async def audit_handler(event: AuditEvent) -> None:
 
 @Node()
 async def do_work() -> str:
-    print("执行核心逻辑...")
+    print("Executing core logic...")
     return "completed"
 
 

demos/12_inline_workflow.py

@@ -21,12 +21,12 @@ def __init__(self, value: int) -> None:
         self.interpreter = WorkflowInterpreter(rendered)
 
     @Node()
-    async def double(self) -> int:
-        return self.value * 2
+    async def double(self) -> None:
+        self.value *= 2
 
     @Node()
-    async def format(self, prev: int) -> str:
-        self.result = f"Processed: {prev}"
+    async def format(self) -> str:
+        self.result = f"Processed: {self.value}"
         return self.result
 
     async def run(self) -> str | None:

demos/13_ret_far.py

@@ -1,42 +1,56 @@
-"""13_ret_far.py — CALL + RET_FAR nested return
+"""13_ret_far.py — Manual push + GOTO + RET_FAR pop-and-return
 
 Usage:
     python demos/13_ret_far.py
 """
 
 import asyncio
 
-from amrita_sense import ALIAS, ARCHIVED_NODES, CALL, NOP, Node, WorkflowInterpreter
-from amrita_sense.instructions import RET_FAR
+from amrita_sense import ALIAS, NOP, Node, PointerVector, WorkflowInterpreter
+from amrita_sense.instructions import GOTO, RET_FAR
 
 
 @Node()
-async def deep_work() -> object:
-    """Deep task: simulate an early-exit condition"""
-    print("  Entering deep task...")
-    print("  Early exit condition met — executing RET_FAR")
-    return RET_FAR()  # Pop return address and jump back to the outermost caller
+async def start() -> None:
+    print("Start")
 
 
 @Node()
-async def never_reached() -> None:
-    print("  This line should never print (RET_FAR already jumped out)")
+async def save_ret_addr(pc: WorkflowInterpreter) -> None:
+    """Manually push a return destination onto _ret_addr_stack."""
+    print("  Saving return address...")
+    return_dest = PointerVector(pc.find_addr_alias("after"))
+    pc._ret_addr_stack.push(return_dest)
 
 
 @Node()
-async def back_to_top() -> None:
-    print("Back to top level")
+async def doing_work() -> None:
+    """The section we GOTO into."""
+    print("  Doing work in the jumped-to section")
+
+
+@Node()
+async def after_return() -> None:
+    """RET_FAR pops _ret_addr_stack and jumps here."""
+    print("Back here (popped via RET_FAR)")
 
 
 async def main() -> None:
     print("=== RET_FAR example ===")
-    sub = ARCHIVED_NODES(ALIAS(deep_work, "deep"))
+    # Pattern: manual push → GOTO → RET_FAR pop-and-return
+    #   1) save_ret_addr pushes "after" address onto _ret_addr_stack
+    #   2) GOTO("work") jumps to the work section
+    #   3) RET_FAR() pops the saved address and jumps back
     comp = (
-        Node(lambda: print("Start"))  # type: ignore[arg-type]
-        >> CALL("deep")
-        >> back_to_top
+        start
+        >> save_ret_addr
+        >> GOTO("work")
+        >> ALIAS(after_return, "after")
+        >> GOTO("end")
+        >> ALIAS(doing_work, "work")
+        >> RET_FAR()
+        >> ALIAS(NOP, "end")
         >> NOP
-        >> sub
     )
     await WorkflowInterpreter(comp.render()).run()
 

demos/15_step_by.py

@@ -10,18 +10,18 @@
 
 
 @Node()
-async def a() -> int:
-    return 1
+async def a() -> None:
+    print("Node A")
 
 
 @Node()
-async def b(prev: int) -> int:
-    return prev * 10
+async def b() -> None:
+    print("Node B")
 
 
 @Node()
-async def c(prev: int) -> None:
-    print(f"Final value: {prev}")
+async def c() -> None:
+    print("Node C")
 
 
 async def main() -> None:
@@ -34,9 +34,6 @@ async def main() -> None:
         ptr = interpreter._pointer.base_addr
         print(f"Step {step}: output={result!r}, pointer={ptr}")
 
-        # Inspect state and decide next action here.
-        # e.g.: if step >= 2: break
-
 
 if __name__ == "__main__":
     asyncio.run(main())