cleanup: add better documentation and comments

Author: grutt

fast-api-react/README.md

@@ -28,27 +28,48 @@ OPENAI_API_KEY="<openai-key>"
    poetry install
    ```
 
-## Running the API
+### Running the API
 
 To start the FastAPI server, run the following command in the terminal:
 
 ```shell
 poetry run api
 ```
 
-## Running the Hatchet Worker
+### Running the Hatchet Worker
 
 In a separate terminal, start the the Hatchet worker by running the following command:
 
 ```shell
 poetry run hatchet
 ```
 
-## (Optional) Running the Example Frontend Application
+### (Optional) Running the Example Frontend Application
 
 We've included a basic chat engine frontend to play with the example workflow. To run this script:
 
-1. Open a new terminal window and cd into the `fast-api-react/frontend` directory.
+1. Open a new terminal window and cd into the [`./frontend`](./frontend/) directory.
 2. run `npm install`
 3. run `npm start`
 4. By default you can access the application in your browser at `http://localhost:3000` or by following the instructions in the terminal window.
+
+## Project Overview
+
+### Example Workflows
+
+The project contains two example workflows in the [`./backend/src/workflows`](./backend/src/workflows/) directory. These workflows are registered with hatchet in [`./backend/src/workflows/main.py`](./backend/src/workflows/main.py) which is started when running `poetry run hatchet`.
+
+1. [Simple Response Generation](./backend/src/workflows/simple.py): a single step workflow making a request to OpenAI
+2. [Basic Retrieval Augmented Generation](./backend/src/workflows/basicrag.py): a multi-step workflow to load the contents of a website with Beautiful soup, reason about the information, and generate a response with OpenAI.
+
+### Exposing the workflows via a RestAPI
+
+A common design pattern is to start a Hatchet workflow run from a rest api endpoint. In this way, you can handle authentication and authorization as you normally do and let Hatchet handle execution. The simple FastAPI example can be found at [./backend/src/api/main.py](./backend/src/api/main.py)
+
+### Starting a Run
+
+The `POST /message` endpoint initiates a Hatchet workflow run, utilizing the message body as input. Given Hatchet operates asynchronously, this endpoint immediately returns a run ID. This ID acts as a reference for clients to track the status and outcomes of the initiated run.
+
+### Streaming Responses
+
+After initiating a workflow run and receiving a run ID, clients can subscribe to updates through a `GET /message/{id}` request. This request allows clients to receive real-time notifications and results from the asynchronous Hatchet worker, associated with their specific run ID.

fast-api-react/backend/README.md

@@ -3,7 +3,7 @@ name = "src"
 version = "0.0.0"
 description = "Easily run background tasks in FastAPI with Hatchet"
 authors = []
-readme = "README.md"
+readme = "../README.md"
 
 [tool.poetry.scripts]
 api = "src.api.main:start"
@@ -18,7 +18,7 @@ openai = "^1.11.0"
 beautifulsoup4 = "^4.12.3"
 requests = "^2.31.0"
 urllib3 = "1.26.15"
-hatchet-sdk = "0.10.3"
+hatchet-sdk = "^0.10.4"
 
 [build-system]
 requires = ["poetry-core"]

fast-api-react/backend/poetry.lock

@@ -33,31 +33,39 @@
 
 @app.post("/message")
 def message(data: MessageRequest):
-
-    messageId = hatchet.client.admin.run_workflow("GenerateWorkflow", {
+    ''' This endpoint is called by the client to start a message generation workflow. '''
+    messageId = hatchet.client.admin.run_workflow("BasicRagWorkflow", {
         "request": data.model_dump()
     })
 
-    # save step message id -> workflowRunId
+    # normally, we'd save the workflowRunId to a database and return a reference to the client
+    # for this simple example, we just return the workflowRunId
 
-    return {"workflowRunId": messageId}
+    return {"messageId": messageId}
 
 
 def event_stream_generator(workflowRunId):
+    ''' This helper function is a generator that yields events from the Hatchet event stream. '''
     stream = hatchet.client.listener.stream(workflowRunId)
 
     for event in stream:
+        ''' you can filter and transform event data here that will be sent to the client'''
         data = json.dumps({
             "type": event.type,
             "payload": event.payload,
-            "workflowRunId": workflowRunId
+            "messageId": workflowRunId
         })
         yield "data: " + data + "\n\n"
 
 
-@app.get("/stream/{messageId}")
+@app.get("/message/{messageId}")
 async def stream(messageId: str):
-    # message id -> workflowRunId
+    '''
+    in a normal application you might use the message id to look up a workflowRunId
+    for this simple case, we have no persistence and just use the message id as the workflowRunId
+
+    you might also consider looking up the workflowRunId in a database and returning the results if the message has already been processed
+    '''
     workflowRunId = messageId
     return StreamingResponse(event_stream_generator(workflowRunId), media_type='text/event-stream')
 

fast-api-react/backend/pyproject.toml

@@ -3,13 +3,12 @@
 from bs4 import BeautifulSoup
 from openai import OpenAI
 import requests
-import time
 
 openai = OpenAI()
 
 
 @hatchet.workflow(on_events=["question:create"])
-class GenerateWorkflow:
+class BasicRagWorkflow:
 
     @hatchet.step()
     def start(self, context: Context):
@@ -88,27 +87,3 @@ def generate_response(self, ctx: Context):
             "status": "idle",
             "message": completion.choices[0].message.content,
         }
-
-@hatchet.workflow()
-class SimpleWorkflow:
-    @hatchet.step()
-    def start(self, ctx: Context):
-        message = ctx.workflow_input()["messages"][-1]
-
-        prompt = ctx.playground("prompt", "The user is asking the following question: {message}")
-
-        prompt = prompt.format(message=message['content'])
-
-        model = ctx.playground("model", "gpt-3.5-turbo")
-
-        completion = openai.chat.completions.create(
-            model=model,
-            messages=[
-                {"role": "system", "content": prompt},
-                message
-            ]
-        )
-
-        return {
-            "answer": completion.choices[0].message.content,
-        }

fast-api-react/backend/src/api/main.py

@@ -1,6 +1,5 @@
 from hatchet_sdk import Hatchet
 from dotenv import load_dotenv
-
 load_dotenv()
 
 hatchet = Hatchet(debug=True)

…-react/backend/src/workflows/generate.py …-react/backend/src/workflows/basicrag.pyfast-api-react/backend/src/workflows/generate.py renamed to fast-api-react/backend/src/workflows/basicrag.py fast-api-react/backend/src/workflows/generate.py renamed to fast-api-react/backend/src/workflows/basicrag.py

@@ -1,12 +1,12 @@
 from .hatchet import hatchet
-from .generate import GenerateWorkflow, SimpleWorkflow
+from .basicrag import BasicRagWorkflow
+from .simple import SimpleWorkflow
 
 
 def start():
     worker = hatchet.worker('example-worker')
 
-    generate = GenerateWorkflow()
-    worker.register_workflow(generate)
+    worker.register_workflow(BasicRagWorkflow())
     worker.register_workflow(SimpleWorkflow())
 
     worker.start()

fast-api-react/backend/src/workflows/hatchet.py

@@ -0,0 +1,28 @@
+from .hatchet import hatchet
+from hatchet_sdk import Context
+
+
+@hatchet.workflow()
+class SimpleWorkflow:
+    @hatchet.step()
+    def start(self, ctx: Context):
+        message = ctx.workflow_input()["messages"][-1]
+
+        prompt = ctx.playground(
+            "prompt", "The user is asking the following question: {message}")
+
+        prompt = prompt.format(message=message['content'])
+
+        model = ctx.playground("model", "gpt-3.5-turbo")
+
+        completion = openai.chat.completions.create(
+            model=model,
+            messages=[
+                {"role": "system", "content": prompt},
+                message
+            ]
+        )
+
+        return {
+            "answer": completion.choices[0].message.content,
+        }

fast-api-react/backend/src/workflows/main.py

@@ -22,7 +22,7 @@ function App() {
   useEffect(() => {
     if (!openRequest) return;
 
-    const sse = new EventSource(`${API_URL}/stream/${openRequest}`, {
+    const sse = new EventSource(`${API_URL}/message/${openRequest}`, {
       withCredentials: true,
     });
 
@@ -38,7 +38,7 @@ function App() {
           {
             role: "assistant",
             content: data.payload.message,
-            hatchetRunId: data.workflowRunId,
+            messageId: data.messageId,
           },
         ]);
         setOpenRequest(undefined);
@@ -81,7 +81,7 @@ function App() {
 
       if (response.ok) {
         // Handle successful response
-        setOpenRequest((await response.json()).workflowRunId);
+        setOpenRequest((await response.json()).messageId);
       } else {
         // Handle error response
       }