Re-added files not mentioned in .fernignore

Author: Andrei Bratu

.fernignore

@@ -8,7 +8,7 @@ README.md
 
 # Directories used by SDK decorators
 
-src/humanloop/decorators
+src/humanloop/utilities
 src/humanloop/otel
 
 # Tests

src/humanloop/otel/processor.py

@@ -109,6 +109,8 @@ def _wait_for_children(self, span: ReadableSpan):
         """Wait for all children spans to complete before processing the Humanloop span."""
         span_id = span.context.span_id
         while not all(child["complete"] for child in self._children[span_id]):
+            # TODO: This assumes that the children spans will complete
+            # The LLM provider might fail; address in future
             logger.debug(
                 "[HumanloopSpanProcessor] Span %s %s waiting for children to complete: %s",
                 span_id,

src/humanloop/utilities/__init__.py

@@ -0,0 +1,89 @@
+import logging
+from functools import wraps
+from typing import Any, Callable, Mapping, Optional, Sequence
+
+from opentelemetry.sdk.trace import Span
+from opentelemetry.trace import Tracer
+from typing_extensions import Unpack
+
+from humanloop.utilities.helpers import args_to_inputs
+from humanloop.eval_utils.types import File
+from humanloop.otel.constants import (
+    HUMANLOOP_FILE_KEY,
+    HUMANLOOP_FILE_TYPE_KEY,
+    HUMANLOOP_LOG_KEY,
+    HUMANLOOP_PATH_KEY,
+)
+from humanloop.otel.helpers import jsonify_if_not_string, write_to_opentelemetry_span
+from humanloop.requests import FlowKernelRequestParams as FlowDict
+from humanloop.requests.flow_kernel_request import FlowKernelRequestParams
+
+logger = logging.getLogger("humanloop.sdk")
+
+
+def flow(
+    opentelemetry_tracer: Tracer,
+    path: Optional[str] = None,
+    **flow_kernel: Unpack[FlowKernelRequestParams],  # type: ignore
+):
+    flow_kernel["attributes"] = {k: v for k, v in flow_kernel.get("attributes", {}).items() if v is not None}
+
+    def decorator(func: Callable):
+        @wraps(func)
+        def wrapper(*args: Sequence[Any], **kwargs: Mapping[str, Any]) -> Any:
+            span: Span
+            with opentelemetry_tracer.start_as_current_span("humanloop.flow") as span:  # type: ignore
+                span.set_attribute(HUMANLOOP_PATH_KEY, path if path else func.__name__)
+                span.set_attribute(HUMANLOOP_FILE_TYPE_KEY, "flow")
+
+                if flow_kernel:
+                    write_to_opentelemetry_span(
+                        span=span,
+                        key=f"{HUMANLOOP_FILE_KEY}.flow",
+                        value=flow_kernel,  # type: ignore
+                    )
+
+                # Call the decorated function
+                try:
+                    output = func(*args, **kwargs)
+                    output_stringified = jsonify_if_not_string(
+                        func=func,
+                        output=output,
+                    )
+                    error = None
+                except Exception as e:
+                    logger.error(f"Error calling {func.__name__}: {e}")
+                    output = None
+                    output_stringified = jsonify_if_not_string(
+                        func=func,
+                        output=None,
+                    )
+                    error = str(e)
+
+                flow_log = {
+                    "inputs": args_to_inputs(func, args, kwargs),
+                    "output": output_stringified,
+                    "error": error,
+                }
+
+                # Write the Flow Log to the Span on HL_LOG_OT_KEY
+                if flow_log:
+                    write_to_opentelemetry_span(
+                        span=span,
+                        key=HUMANLOOP_LOG_KEY,
+                        value=flow_log,  # type: ignore
+                    )
+
+            # Return the output of the decorated function
+            return output
+
+        wrapper.file = File(  # type: ignore
+            path=path if path else func.__name__,
+            type="flow",
+            version=FlowDict(**flow_kernel),  # type: ignore
+            callable=wrapper,
+        )
+
+        return wrapper
+
+    return decorator

src/humanloop/utilities/flow.py

@@ -0,0 +1,21 @@
+import inspect
+from typing import Any, Callable
+
+
+def args_to_inputs(func: Callable, args: tuple, kwargs: dict) -> dict[str, Any]:
+    """Maps arguments to their corresponding parameter names in the function signature.
+
+    For example:
+    ```python
+    def foo(a, b=2, c=3):
+        pass
+
+    assert args_to_inputs(foo, (1, 2), {}) == {'a': 1, 'b': 2, 'c': 3}
+    assert args_to_inputs(foo, (1,), {'b': 8}) == {'a': 1, 'b': 8, 'c': 3}
+    assert args_to_inputs(foo, (1,), {}) == {'a': 1, 'b': 2, 'c': 3}
+    ```
+    """
+    signature = inspect.signature(func)
+    bound_args = signature.bind(*args, **kwargs)
+    bound_args.apply_defaults()
+    return dict(bound_args.arguments)

src/humanloop/utilities/helpers.py

@@ -0,0 +1,88 @@
+import logging
+from functools import wraps
+from typing import Any, Callable, Mapping, Optional, Sequence
+
+from opentelemetry.sdk.trace import Span
+from opentelemetry.trace import Tracer
+from typing_extensions import Unpack
+
+from humanloop.utilities.helpers import args_to_inputs
+from humanloop.utilities.types import DecoratorPromptKernelRequestParams
+from humanloop.eval_utils import File
+from humanloop.otel.constants import (
+    HUMANLOOP_FILE_KEY,
+    HUMANLOOP_FILE_TYPE_KEY,
+    HUMANLOOP_LOG_KEY,
+    HUMANLOOP_PATH_KEY,
+)
+from humanloop.otel.helpers import jsonify_if_not_string, write_to_opentelemetry_span
+
+logger = logging.getLogger("humanloop.sdk")
+
+
+def prompt(
+    opentelemetry_tracer: Tracer,
+    path: Optional[str] = None,
+    # TODO: Template can be a list of objects?
+    **prompt_kernel: Unpack[DecoratorPromptKernelRequestParams],  # type: ignore
+):
+    def decorator(func: Callable):
+        @wraps(func)
+        def wrapper(*args: Sequence[Any], **kwargs: Mapping[str, Any]) -> Any:
+            span: Span
+            with opentelemetry_tracer.start_as_current_span("humanloop.prompt") as span:  # type: ignore
+                span.set_attribute(HUMANLOOP_PATH_KEY, path if path else func.__name__)
+                span.set_attribute(HUMANLOOP_FILE_TYPE_KEY, "prompt")
+
+                if prompt_kernel:
+                    write_to_opentelemetry_span(
+                        span=span,
+                        key=f"{HUMANLOOP_FILE_KEY}.prompt",
+                        value={
+                            **prompt_kernel,  # type: ignore
+                            "attributes": prompt_kernel.get("attributes") or None,  # type: ignore
+                        },  # type: ignore
+                    )
+
+                # Call the decorated function
+                try:
+                    output = func(*args, **kwargs)
+                    output_stringified = jsonify_if_not_string(
+                        func=func,
+                        output=output,
+                    )
+                    error = None
+                except Exception as e:
+                    logger.error(f"Error calling {func.__name__}: {e}")
+                    output = None
+                    output_stringified = jsonify_if_not_string(
+                        func=func,
+                        output=output,
+                    )
+                    error = str(e)
+
+                prompt_log = {
+                    "inputs": args_to_inputs(func, args, kwargs),
+                    "output": output_stringified,
+                    "error": error,
+                }
+
+                write_to_opentelemetry_span(
+                    span=span,
+                    key=HUMANLOOP_LOG_KEY,
+                    value=prompt_log,  # type: ignore
+                )
+
+            # Return the output of the decorated function
+            return output
+
+        wrapper.file = File(  # type: ignore
+            path=path if path else func.__name__,
+            type="prompt",
+            version={**prompt_kernel},  # type: ignore
+            callable=wrapper,
+        )
+
+        return wrapper
+
+    return decorator