jsonify output of decorators if necessary

Author: Andrei Bratu

src/humanloop/client.py

@@ -236,6 +236,12 @@ def call_llm(messages):
         }
         ```
 
+        The decorated function should return a string or the output should be JSON serializable. If
+        the output cannot be serialized, TypeError will be raised.
+
+        If the function raises an exception, the log created by the function will have the output
+        field set to None and the error field set to the string representation of the exception.
+
         :param path: The path where the Prompt is created. If not
             provided, the function name is used as the path and the File
             is created in the root of your Humanloop organization workspace.
@@ -308,6 +314,13 @@ def calculator(a: int, b: Optional[int]) -> int:
             },
             "output": 3
         }
+        ```
+
+        The decorated function should return a string or the output should be JSON serializable. If
+        the output cannot be serialized, TypeError will be raised.
+
+        If the function raises an exception, the log created by the function will have the output
+        field set to None and the error field set to the string representation of the exception.
 
         :param path: The path to the Tool. If not provided, the function name
             will be used as the path and the File will be created in the root
@@ -365,6 +378,12 @@ def entrypoint():
         will be nested, allowing you to track the whole conversation session
         between the user and the assistant.
 
+        The decorated function should return a string or the output should be JSON serializable. If
+        the output cannot be serialized, TypeError will be raised.
+
+        If the function raises an exception, the log created by the function will have the output
+        field set to None and the error field set to the string representation of the exception.
+
         :param path: The path to the Flow. If not provided, the function name
             will be used as the path and the File will be created in the root
             of your organization workspace.

src/humanloop/decorators/flow.py

@@ -1,3 +1,4 @@
+import json
 import logging
 from functools import wraps
 from typing import Any, Callable, Mapping, Optional, Sequence
@@ -10,7 +11,7 @@
 from humanloop.eval_utils.types import File
 from humanloop.otel import TRACE_FLOW_CONTEXT, FlowContext
 from humanloop.otel.constants import HUMANLOOP_FILE_KEY, HUMANLOOP_FILE_TYPE_KEY, HUMANLOOP_LOG_KEY, HUMANLOOP_PATH_KEY
-from humanloop.otel.helpers import generate_span_id, write_to_opentelemetry_span
+from humanloop.otel.helpers import generate_span_id, jsonify_if_not_string, write_to_opentelemetry_span
 from humanloop.requests import FlowKernelRequestParams as FlowDict
 from humanloop.requests.flow_kernel_request import FlowKernelRequestParams
 
@@ -63,6 +64,10 @@ def wrapper(*args: Sequence[Any], **kwargs: Mapping[str, Any]) -> Any:
                 # Call the decorated function
                 try:
                     output = func(*args, **kwargs)
+                    output = jsonify_if_not_string(
+                        func=func,
+                        output=output,
+                    )
                     error = None
                 except Exception as e:
                     logger.error(f"Error calling {func.__name__}: {e}")

src/humanloop/decorators/prompt.py

@@ -11,7 +11,7 @@
 from humanloop.eval_utils import File
 from humanloop.otel import TRACE_FLOW_CONTEXT, FlowContext
 from humanloop.otel.constants import HUMANLOOP_FILE_KEY, HUMANLOOP_FILE_TYPE_KEY, HUMANLOOP_LOG_KEY, HUMANLOOP_PATH_KEY
-from humanloop.otel.helpers import generate_span_id, write_to_opentelemetry_span
+from humanloop.otel.helpers import generate_span_id, jsonify_if_not_string, write_to_opentelemetry_span
 
 logger = logging.getLogger("humanloop.sdk")
 
@@ -54,6 +54,10 @@ def wrapper(*args: Sequence[Any], **kwargs: Mapping[str, Any]) -> Any:
                 # Call the decorated function
                 try:
                     output = func(*args, **kwargs)
+                    output = jsonify_if_not_string(
+                        func=func,
+                        output=output,
+                    )
                     error = None
                 except Exception as e:
                     logger.error(f"Error calling {func.__name__}: {e}")

src/humanloop/decorators/tool.py

@@ -20,7 +20,7 @@
     HUMANLOOP_LOG_KEY,
     HUMANLOOP_PATH_KEY,
 )
-from humanloop.otel.helpers import generate_span_id, write_to_opentelemetry_span
+from humanloop.otel.helpers import generate_span_id, jsonify_if_not_string, write_to_opentelemetry_span
 from humanloop.requests.tool_function import ToolFunctionParams
 from humanloop.requests.tool_kernel_request import ToolKernelRequestParams
 
@@ -72,6 +72,10 @@ def wrapper(*args, **kwargs):
                 # Call the decorated function
                 try:
                     output = func(*args, **kwargs)
+                    output = jsonify_if_not_string(
+                        func=func,
+                        output=output,
+                    )
                     error = None
                 except Exception as e:
                     logger.error(f"Error calling {func.__name__}: {e}")
@@ -178,7 +182,7 @@ def _build_function_parameters_property(func) -> _JSONSchemaFunctionParameters:
         try:
             parameter_signature = _parse_annotation(parameter.annotation)
         except ValueError as e:
-            raise ValueError(f"{func.__name__}: {e.args[0]}") from e
+            raise ValueError(f"Error parsing signature of @tool annotated function {func.__name__}: {e}") from e
         param_json_schema = _annotation_parse_to_json_schema(parameter_signature)
         properties[parameter.name] = param_json_schema
         if not _parameter_is_optional(parameter):

src/humanloop/otel/helpers.py

@@ -1,5 +1,6 @@
+import json
 import uuid
-from typing import Union
+from typing import Any, Callable, Union
 
 from opentelemetry.sdk.trace import ReadableSpan
 from opentelemetry.trace import SpanKind
@@ -289,3 +290,12 @@ def module_is_installed(module_name: str) -> bool:
 
 def generate_span_id() -> str:
     return str(uuid.uuid4())
+
+
+def jsonify_if_not_string(func: Callable, output: Any) -> str:
+    if not isinstance(output, str):
+        try:
+            output = json.dumps(output)
+        except TypeError as e:
+            raise TypeError(f"Output of {func.__name__} must be a string or JSON serializable") from e
+    return output