Merge pull request #46 from aurelio-labs/james/starlette-compat

feat: add direct starlette support for GraphEvent

Author: jamescalam

docs/user-guide/faqs.md

@@ -0,0 +1,33 @@
+
+## TypeError: object dict can't be used in 'await' expression
+
+This is a common mistake when defining the graph. The internals of `graphai` expect _all_ nodes to be defined with `async def`. When defining a node with `def` we will see this error:
+
+```
+Traceback (most recent call last):
+  File "/app/.venv/lib/python3.13/site-packages/graphai/graph.py", line 351, in execute
+    output = await current_node.invoke(input=state, state=self.state)
+             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/app/.venv/lib/python3.13/site-packages/graphai/nodes/base.py", line 152, in invoke
+    out = await instance.execute(**input)
+          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "/app/.venv/lib/python3.13/site-packages/graphai/nodes/base.py", line 74, in execute
+    return await func(**params_dict)  # Pass only the necessary arguments
+           ^^^^^^^^^^^^^^^^^^^^^^^^^
+TypeError: object dict can't be used in 'await' expression
+```
+
+The solution is to always define nodes using `async def`. For example:
+
+```python
+
+# WRONG:
+@node
+def my_node(input: dict) -> dict:
+    return {"output": "Hello, world!"}
+
+# DO THIS INSTEAD:
+@node
+async def my_node(input: dict) -> dict:
+    return {"output": "Hello, world!"}
+```

graphai/callback.py

@@ -1,6 +1,7 @@
 import asyncio
 from dataclasses import dataclass
 from enum import Enum
+import json
 from pydantic import Field
 from typing import Any
 from collections.abc import AsyncIterator
@@ -43,6 +44,22 @@ class GraphEvent:
     token: str | None = None
     params: dict[str, Any] | None = None
 
+    def encode(self, charset: str = "utf-8") -> bytes:
+        """Encodes the event as a JSON string, important for compatability with FastAPI
+        and starlette.
+
+        :param charset: The character set to use for encoding the event.
+        :type charset: str
+        """
+        event_dict = {
+            "type": self.type.value if hasattr(self.type, "value") else str(self.type),
+            "identifier": self.identifier,
+            "token": self.token,
+            "params": self.params,
+        }
+        data = f"data: {json.dumps(event_dict, ensure_ascii=False, separators=(',', ':'))}\n\n"
+        return data.encode(charset)
+
 
 class Callback:
     """The original callback handler class. Outputs a stream of structured text

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "graphai-lib"
-version = "0.0.9"
+version = "0.0.10rc1"
 description = "Not an AI framework"
 readme = "README.md"
 requires-python = ">=3.10,<3.14"