feat: add event system (ConstructableEvent + TRIGGER_EVENT), RET_FAR instruction, TryNode escape sentinel, WorkflowInterpreter middleware, inline workflow pattern, runtime API updates (jump_offset_far, call_offset_far), 15 demos, Chinese doc fixes, sidebar reorganization, and Mermaid diagrams for manual stack management.

Author: JohnRichard4096

README.md

@@ -21,9 +21,7 @@
     </a>
   </p>
 
-> ### _"Any is thing all you need."_
->
-> ### _"Let developers return with Python again."_
+> ### _"Sense is all you need."_
 
 </center>
 

demos/01_minimal.py

@@ -0,0 +1,27 @@
+"""01_minimal.py — Minimal example: single node + NOP + interpreter run
+
+Usage:
+    python demos/01_minimal.py
+"""
+
+import asyncio
+
+from amrita_sense import NOP, Node, WorkflowInterpreter
+
+
+@Node()
+async def hello() -> None:
+    print("Hello, AmritaSense!")
+
+
+async def main() -> None:
+    # Compose: hello followed by NOP sentinel node
+    composition = hello >> NOP
+    rendered = composition.render()
+
+    interpreter = WorkflowInterpreter(rendered)
+    await interpreter.run()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

demos/02_composition.py

@@ -0,0 +1,36 @@
+"""02_composition.py — Multi-node chain + DI return-value passing
+
+Usage:
+    python demos/02_composition.py
+"""
+
+import asyncio
+
+from amrita_sense import NOP, Node, WorkflowInterpreter
+
+
+@Node()
+async def double() -> int:
+    return 42
+
+
+@Node()
+async def add_one(value: int) -> int:
+    # DI injects the return value (42) from double into `value`
+    return value + 1
+
+
+@Node()
+async def print_result(value: int) -> None:
+    print(f"Final result: {value}")
+
+
+async def main() -> None:
+    composition = double >> add_one >> print_result >> NOP
+    rendered = composition.render()
+    interpreter = WorkflowInterpreter(rendered)
+    await interpreter.run()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

demos/03_dependency_injection.py

@@ -0,0 +1,36 @@
+"""03_dependency_injection.py — extra_args / extra_kwargs explicit injection
+
+Usage:
+    python demos/03_dependency_injection.py
+"""
+
+import asyncio
+
+from amrita_sense import NOP, Node, WorkflowInterpreter
+
+
+@Node()
+async def greet(greeting: str, name: str) -> str:
+    # greeting → injected by name via extra_kwargs
+    # name → injected by type (str) via extra_args
+    return f"{greeting}, {name}!"
+
+
+@Node()
+async def display(message: str) -> None:
+    print(message)
+
+
+async def main() -> None:
+    composition = greet >> display >> NOP
+    rendered = composition.render()
+    interpreter = WorkflowInterpreter(
+        rendered,
+        extra_args=("World",),  # str type → injected into `name`
+        extra_kwargs={"greeting": "Hello"},  # name match → injected into `greeting`
+    )
+    await interpreter.run()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

demos/04_if_branch.py

@@ -0,0 +1,59 @@
+"""04_if_branch.py — IF / ELIF / ELSE conditional branching
+
+Usage:
+    python demos/04_if_branch.py
+"""
+
+import asyncio
+
+from amrita_sense import IF, NOP, Node, 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")
+    return "A"
+
+
+@Node()
+async def grade_b(score: int) -> str:
+    print(f"Score {score}: Good")
+    return "B"
+
+
+@Node()
+async def grade_c(score: int) -> str:
+    print(f"Score {score}: Pass")
+    return "C"
+
+
+@Node()
+async def finished(grade: str) -> None:
+    print(f"Final grade: {grade}")
+
+
+async def main() -> 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]
+        .ELSE(grade_c)
+        >> check_score
+        >> finished
+        >> NOP
+    )
+    rendered = comp.render()
+    interpreter = WorkflowInterpreter(rendered)
+    await interpreter.run()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

demos/05_while_loop.py

@@ -0,0 +1,59 @@
+"""05_while_loop.py — WHILE + DO-WHILE loops
+
+Usage:
+    python demos/05_while_loop.py
+"""
+
+import asyncio
+
+from amrita_sense import DO, NOP, WHILE, Node, WorkflowInterpreter
+from amrita_sense.exceptions import BreakLoop
+
+
+@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]
+
+
+@Node()
+async def under_three(n: int) -> bool:
+    """WHILE loop condition"""
+    return n < 3
+
+
+@Node()
+def body(n: int) -> None:
+    """Loop body"""
+    print(f"  WHILE iteration {n}")
+
+
+@Node()
+def early_break(n: int) -> None:
+    """DO loop body: break out on iteration 3"""
+    print(f"  DO-WHILE iteration {n}")
+    if n >= 3:
+        raise BreakLoop
+
+
+async def main() -> None:
+    print("=== WHILE example ===")
+    wf = (counter >> 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()
+    await WorkflowInterpreter(wf2).run()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

demos/06_try_catch.py

@@ -0,0 +1,64 @@
+"""06_try_catch.py — TRY / CATCH / FINALLY / THEN exception handling
+
+Usage:
+    python demos/06_try_catch.py
+"""
+
+import asyncio
+
+from amrita_sense import NOP, Node, NodeType, Try, WorkflowInterpreter
+
+
+@Node()
+async def may_fail() -> str:
+    """Always raises ValueError"""
+    raise ValueError("something went wrong")
+
+
+@Node()
+async def handle_error(exc_val: ValueError):
+    """Catch ValueError and return fallback"""
+    print(f"Caught: {exc_val}")
+
+
+@Node()
+async def on_success() -> None:
+    """Executes when TRY succeeds (THEN)"""
+    print("Success: all good")
+
+
+@Node()
+async def cleanup() -> None:
+    """Always runs — success or failure (FINALLY)"""
+    print("Cleanup complete")
+
+
+async def example_1() -> None:
+    """Exception caught by CATCH"""
+    print("=== Example 1: ValueError → caught by CATCH ===")
+    comp = Try(may_fail).CATCH(ValueError, handle_error) >> NOP
+    rendered = comp.render()
+    await WorkflowInterpreter(rendered).run()
+
+
+async def example_2() -> None:
+    """Normal execution + THEN + FINALLY"""
+    print("\n=== Example 2: normal execution + THEN + FINALLY ===")
+    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)
+        >> NOP
+    )
+    rendered = comp.render()
+    await WorkflowInterpreter(rendered).run()
+
+
+async def main() -> None:
+    await example_1()
+    await example_2()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

demos/07_goto_call.py

@@ -0,0 +1,55 @@
+"""07_goto_call.py — GOTO + CALL + ALIAS + ARCHIVED_NODES
+
+Usage:
+    python demos/07_goto_call.py
+"""
+
+import asyncio
+
+from amrita_sense import ALIAS, ARCHIVED_NODES, CALL, NOP, Node, WorkflowInterpreter
+from amrita_sense.instructions import GOTO
+
+
+@Node()
+async def start() -> None:
+    print("Start")
+
+
+@Node()
+async def skip_me() -> None:
+    print("This line should never appear")
+
+
+@Node()
+async def after_jump() -> None:
+    print("Arrived after GOTO jump")
+
+
+@Node()
+async def reusable_greet(name: str = "World") -> str:
+    print(f"  Hello, {name}!")
+    return name
+
+
+@Node()
+async def done(result: str) -> None:
+    print(f"CALL returned: {result}")
+
+
+async def main() -> None:
+    print("=== GOTO example ===")
+
+    # GOTO("target") skips skip_me, goes directly to after_jump
+    comp = start >> GOTO("target") >> skip_me >> ALIAS(after_jump, "target") >> NOP
+    await WorkflowInterpreter(comp.render()).run()
+
+    print("\n=== CALL example ===")
+
+    # CALL("greeter") invokes the subroutine, then returns to continue
+    sub = ARCHIVED_NODES(ALIAS(reusable_greet, "greeter"))
+    comp2 = start >> CALL("greeter") >> done >> NOP >> sub
+    await WorkflowInterpreter(comp2.render()).run()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

demos/08_interrupt_suspend.py

@@ -0,0 +1,40 @@
+"""08_interrupt_suspend.py — run_step_by() step-by-step debugging
+
+Usage:
+    python demos/08_interrupt_suspend.py
+"""
+
+import asyncio
+
+from amrita_sense import NOP, Node, WorkflowInterpreter
+
+
+@Node()
+async def step_one() -> int:
+    print("[1] First step")
+    return 1
+
+
+@Node()
+async def step_two(prev: int) -> int:
+    print(f"[2] Received previous result: {prev}")
+    return prev + 1
+
+
+@Node()
+async def step_three(prev: int) -> None:
+    print(f"[3] Final result: {prev}")
+
+
+async def main() -> None:
+    print("=== Using run_step_by() to inspect between steps ===")
+    comp = (step_one >> step_two >> step_three >> NOP).render()
+    interpreter = WorkflowInterpreter(comp)
+
+    async for result in interpreter.run_step_by():
+        print(f"  → Node output: {result}")
+        # You can pause, inspect the pointer, or decide whether to continue here
+
+
+if __name__ == "__main__":
+    asyncio.run(main())