improved local debugging system, fleshed our docs a bit more

Author: zeryx

README.md

@@ -1,7 +1,8 @@
 # Algorithm Development Kit (ADK), Python edition
 
 ```python
-import from adk import ADK
+import Algorithmia
+from adk import ADK
 
 
 # API calls will begin at the apply() method, with the request body passed as 'input'
@@ -12,7 +13,7 @@ def apply(input):
 
 
 algo = ADK(apply)
-algo.serve()
+algo.serve("Algorithmia")
 ```
 
 This document will describe the following:
@@ -38,16 +39,17 @@ Algorithm development does change with this introduction:
 - Primary development file has been renamed to `src/Algorithm.py` to aide in understanding around what this file actually does / why it's important
 - An additional import (`from adk import ADK`)
 - An optional `load()` function that can be implemented
-    - this enables a dedicated function for preparing your algorithm for runtime operations, such as model loading, configuration, etc
+    - This enables a dedicated function for preparing your algorithm for runtime operations, such as model loading, configuration, etc
 - A call to the handler function with your `apply` and optional` load` functions as inputs
     - ```python
       algo = ADK(apply)
-      algo.serve()
+      algo.serve("Algorithmia")
       ```
-    - converts the project into an executable, rather than a library
-      - which will interact with the `langserver` service on Algorithmia
-      - but is debuggable via stdin/stdout when executed locally / outside of an Algorithm container
-      - this includes being able to step through your algorithm code in your IDE of choice! Just execute your `src/Algorithm.py` script
+    - Converts the project into an executable, rather than a library
+      - Which will interact with the `langserver` service on Algorithmia
+      - But is debuggable via stdin/stdout when executed locally / outside of an Algorithm container
+        - When a payload is provided to `serve()`, that payload will be directly provided to your algorithm when executed locally, bypassing stdin parsing and simplifying debugging!
+      - This includes being able to step through your algorithm code in your IDE of choice! Just execute your `src/Algorithm.py` script and try stepping through your code with your favorite IDE
 
 ## Example workflows
 Check out these examples to help you get started:

adk/ADK.py

@@ -109,16 +109,8 @@ def create_exception(self, exception):
         }
         return response
 
-    def serve(self):
-        try:
-            if self.load_func:
-                self.load()
-        except Exception as e:
-            load_error = self.create_exception(e)
-            self.write_to_pipe(load_error)
+    def process_loop(self):
         response_obj = ""
-        if self.is_local:
-            print("waiting for input...")
         for line in sys.stdin:
             try:
                 request = json.loads(line)
@@ -132,3 +124,20 @@ def serve(self):
                 response_obj = self.create_exception(e)
             finally:
                 self.write_to_pipe(response_obj)
+
+    def serve(self, local_payload=None):
+        try:
+            if self.load_func:
+                self.load()
+        except Exception as e:
+            load_error = self.create_exception(e)
+            self.write_to_pipe(load_error)
+        if self.is_local and local_payload:
+            if self.load_result:
+                apply_result = self.apply_func(local_payload, self.load_result)
+            else:
+                apply_result = self.apply_func(local_payload)
+            print(self.format_response(apply_result))
+
+        else:
+            self.process_loop()

examples/hello_world/src/Algorithm.py

@@ -1,9 +1,18 @@
 from adk import ADK
 
 
+# API calls will begin at the apply() method, with the request body passed as 'input'
+# For more details, see algorithmia.com/developers/algorithm-development/languages
+
 def apply(input):
+    # If your apply function uses state that's loaded into memory via load, you can pass that loaded state to your apply
+    # function by defining an additional "state" parameter in your apply function; but it's optional!
     return "hello {}".format(str(input))
 
 
-algorithm = ADK(apply)
-algorithm.serve()
+# This turns your library code into an algorithm that can run on the platform.
+# If you intend to use loading operations, remember to pass a `load` function as a second variable.
+algo = ADK(apply)
+# The 'serve()' function actually starts the algorithm, you can follow along in the source code
+# to see how everything works.
+algo.serve("Algorithmia")

examples/loaded_state_hello_world/src/Algorithm.py

@@ -25,4 +25,4 @@ def load():
 algo = ADK(apply, load)
 # The 'serve()' function actually starts the algorithm, you can follow along in the source code
 # to see how everything works.
-algo.serve()
+algo.serve("Algorithmia")

examples/pytorch_image_classification/src/Algorithm.py

@@ -90,5 +90,5 @@ def apply(input, state):
         raise Exception('input must be a json object')
 
 
-adk = ADK(apply_func=apply, load_func=load)
-adk.serve()
+algo = ADK(apply_func=apply, load_func=load)
+algo.serve({"data": "https://i.imgur.com/bXdORXl.jpeg"})