update type hints and examples (#15)

* update Meteorite class typing

* add __pycache__ to gitignore

* clean up json_requests and plain_text_request examples

* rename json_requests to json_request

* add webhook example

* run code formatting with black

.gitignore

@@ -2,4 +2,5 @@
 
 /target
 
-.venv/
+.venv/
+__pycache__/

examples/json_request/README.md

@@ -0,0 +1,12 @@
+# Send a JSON request
+
+This example shows how to send a JSON request to the prediction endpoint.
+The prediction function will syncronously sleep for 10 seconds, and
+then print the request JSON body to the console
+before returning the same body.
+
+Send a POST request using `curl`:
+
+```
+curl -X POST http://localhost:4000/predict -H 'Content-Type: application/json' -d '{"key":"value"}'
+```

examples/json_requests/main.py → examples/json_request/main.py

@@ -1,16 +1,18 @@
 import json
 import time
+import os
 from meteorite import Meteorite
 
 app = Meteorite()
-app.set_webhook_url("https://envzvlfwlg78.x.pipedream.net")
+
 
 @app.predict
 def main(data):
     data = json.loads(data)
+    print("Sleeping for 10 seconds")
     time.sleep(10)
-    print(data["key"])
+    print(data)
     return data
 
 
-app.start(port=5001)
+app.start()

examples/plaintext_request/README.md

@@ -1,6 +1,10 @@
-# Send a plain text request to your model
+# Send a plain text request
 
-### Sending the POST request via CURL
+This example shows how to send a plain text request to the prediction endpoint.
+The prediction function will decode the request body as a string with `utf-8`
+before returning the same body.
+
+Sending a POST request via `curl`:
 
 ```
 curl -X POST http://localhost:4000/predict -H 'Content-Type: text/plain' -d 'hello'

examples/plaintext_request/main.py

@@ -6,6 +6,7 @@
 @app.predict
 def hello(data):
     body = data.decode("utf-8")
+    print(body)
     return body
 
 

examples/webhook/README.md

@@ -0,0 +1,31 @@
+# Setup a webhook
+
+This example shows how to setup a webhook to receive the result of a prediction request.
+When the meteorite inference server receives a request,
+the request is queued and the server immediately returns a 200 response.
+The request is then processed by the inference function that returns an output.
+This output is sent to the webhook server as a POST request.
+
+Install dependencies.
+
+```shell
+pip install meteorite fastapi uvicorn
+```
+
+Run the meteorite inference server that listens to port 4000.
+
+```shell
+python inference.py
+```
+
+In another terminal, run the webhook server that listens to port 8000.
+
+```shell
+uvicorn webhook:app --reload
+```
+
+In another terminal, send a POST request to the inference server.
+
+```shell
+curl -X POST http://localhost:4000/predict -H 'Content-Type: application/json' -d '{"key": "value"}'
+```

examples/webhook/inference.py

@@ -0,0 +1,16 @@
+import os
+from meteorite import Meteorite
+
+app = Meteorite()
+
+webhook_url = "http://localhost:4400"
+app.set_webhook_url(webhook_url)
+
+
+@app.predict
+def main(data):
+    print(data)
+    return "my prediction is 1"
+
+
+app.start()

examples/webhook/webhook.py

@@ -0,0 +1,15 @@
+from typing import Union
+
+from fastapi import FastAPI
+from starlette.requests import Request
+from starlette.responses import Response
+
+
+app = FastAPI()
+
+
+@app.post("/", response_class=Response)
+async def handle(request: Request):
+    body = await request.body()
+    print(body.decode("utf-8"))
+    return "OK"

meteorite.pyi

@@ -1,6 +1,5 @@
 import typing
 
-
 class Meteorite:
     """
     A fast and simple server app for machine learning models.
@@ -10,8 +9,9 @@ class Meteorite:
         """
         Initializes the Meteorite server app
         """
-
-    def predict(self, wraps: typing.Callable[[bytes], typing.Union[str, dict[str, any]]]) -> None:
+    def predict(
+        self, wraps: typing.Callable[[bytes], typing.Union[str, dict[str, typing.Any]]]
+    ) -> None:
         """
         Decorator to wrap a model inference function.
         The inference function should take in a bytes object and return a string or a dictionary.
@@ -24,7 +24,16 @@ class Meteorite:
         >>> def infer(data: bytes) -> str:
         >>>     return "Hello World"
         """
+    def set_webhook_url(self, webhook_url: str) -> None:
+        """
+        Sets the webhook url for the `predict` inference endpoint.
+        After the model inference function finishes processing one inference request,
+        the object returned by the function will be sent to the webhook url as a POST request.
 
+        :param webhook_url: webhook url
+
+        >>> app.set_webhook_url("https://example.com")
+        """
     def start(self, port: int = 4000) -> None:
         """
         Starts the server app