feat(python): create require approval decorator (#25)

clients/python/README.md

@@ -15,23 +15,14 @@ adding an approval workflow to your function:
 
 ```py
 from phantasmpy import Phantasm
+phantasm = Phantasm()
 
-# Replace with your own function and parameters.
-parameters = {...}
+# Replace with your own function.
+@phantasm.require_approval()
 def schedule_meeting(...):
     pass
 
-phantasm = Phantasm()
-response = phantasm.get_approval(
-    name="schedule_meeting",
-    parameters=parameters
-)
-
-if response.approved:
-    # Do this only if you trust the approvers.
-    schedule_meeting(**response.parameters)
-else:
-    fallback()
+schedule_meeting(...)
 ```
 
 ## Advanced Usage With LangChain

clients/python/phantasmpy/client.py

@@ -1,6 +1,7 @@
 import grpc
 import json
-from typing import Any, Dict
+from typing import Any, Callable
+from functools import wraps
 from google.protobuf.empty_pb2 import Empty
 from .stubs import receiver_pb2 as protos
 from .stubs.receiver_pb2_grpc import ReceiverStub
@@ -73,23 +74,58 @@ def get_approval(
             parameters=response.parameters or "",
         )
 
+    def require_approval(self, with_parameters: bool = True) -> Callable:
+        """Decorator to request approval before executing a function.
 
-def test_get_approval():
-    params = {
-        "x": 5,
-        "y": 10,
-    }
+        By default, the decorator will use the parameters provided by the
+        approvers to call the function. If you want to use the original
+        parameters, set `with_parameters` to false.
+
+        This decorator raises exceptions if:
+        - The approval request is rejected.
+        - Error when requesting approval from the server.
+
+        Example:
+
+        ```py
+        phantasm = Phantasm()
+        @phantasm.require_approval()
+        def double(x: int) -> int:
+            return x * 2
+
+        double(x=5)
+        ```
+        """
+
+        def decorator(function: Callable) -> Callable:
+            @wraps(function)
+            def wrapper(**kwargs) -> Callable:
+                name = function.__name__
+                docs = function.__doc__ or ""
+                response = self.get_approval(
+                    name=name,
+                    parameters=kwargs,
+                    context=docs,
+                )
+
+                if response.approved:
+                    if with_parameters:
+                        kwargs = response.parameters
+                    return function(**kwargs)
 
+                raise PermissionError("The approval request is not approved.")
+
+            return wrapper
+
+        return decorator
+
+
+def test_get_approval():
     phantasm = Phantasm()
-    response = phantasm.get_approval(
-        name="multiply",
-        parameters=params,
-        context="Multiply two numbers: x and y.",
-    )
-
-    if response.approved:
-        result = response.parameters["x"] * response.parameters["y"]
-        print("Request Approved")
-        print(f"Result: {result}")
-    else:
-        print("Request Rejected")
+
+    @phantasm.require_approval()
+    def multiply(x: int, y: int) -> int:
+        """Multiply two numbers, x and y."""
+        return x * y
+
+    print(multiply(x=5, y=10))