add minor improvements

Author: pritamsoni-hsr

overmind_sdk/__init__.py

@@ -11,10 +11,10 @@
 from .tracing import init, get_tracer, set_user, set_tag, capture_exception
 from opentelemetry.overmind.prompt import PromptString
 
-from .tracer import observe, SpanType, function, entry_point, workflow, tool
+from .tracer import observe, SpanType, span, function, entry_point, workflow, tool
 
 
-__version__ = "0.1.32"
+__version__ = "0.1.33"
 __all__ = [
     "OvermindClient",
     "OvermindError",
@@ -27,6 +27,7 @@
     "capture_exception",
     "PromptString",
     "observe",
+    "span",
     "SpanType",
     "function",
     "entry_point",

overmind_sdk/tracer.py

@@ -5,6 +5,7 @@
 capturing inputs and outputs in OpenTelemetry style.
 """
 
+from contextlib import contextmanager
 from enum import Enum
 from functools import wraps
 import inspect
@@ -23,28 +24,40 @@ class SpanType(str, Enum):
     TOOL = "tool"
 
 
-def _prepare_for_otel(value: Any) -> Any:
-    """
-    Prepare a value for inclusion in OpenTelemetry span attributes.
+_SKIP_INPUT_TYPES = (
+    "Console", "Progress", "Live", "Table", "Panel",
+    "TracerProvider", "Tracer", "Span",
+)
 
-    Converts complex types to serializable formats while preserving simple types.
-    """
-    # Simple types can be used directly
+
+def _should_skip_value(value: Any) -> bool:
+    type_name = type(value).__name__
+    return type_name in _SKIP_INPUT_TYPES
+
+
+def _prepare_for_otel(value: Any) -> Any:
     if isinstance(value, (str, int, float, bool, type(None))):
         return value
 
-    # For Pydantic models, convert to dict
+    if _should_skip_value(value):
+        return f"<{type(value).__name__}>"
+
     if hasattr(value, "model_dump"):
         try:
             return value.model_dump()
         except Exception:
             return str(value)
 
-    # For dicts, lists, tuples - return as-is (will be serialized later)
     if isinstance(value, (dict, list, tuple)):
         return value
 
-    # For other types, convert to string
+    if isinstance(value, (set, frozenset)):
+        return list(value)
+
+    from pathlib import PurePath
+    if isinstance(value, PurePath):
+        return str(value)
+
     return str(value)
 
 
@@ -54,36 +67,11 @@ def observe(span_name: Optional[str] = None, type: SpanType = SpanType.FUNCTION)
 
     Captures function inputs and outputs as span attributes in OTEL style.
     Works with both synchronous and asynchronous functions.
-
-    Args:
-        span_name: Optional name for the span. If not provided, uses the function name.
-        type: The type of span, as a SpanType enum value.
-
-    Example:
-        ```python
-        @observe(span_name="process_data", type=SpanType.FUNCTION)
-        def process_data(user_id: int, data: dict):
-            return {"result": "success"}
-
-        @observe()  # Uses function name as span name
-        async def async_operation(param: str):
-            return await some_async_call(param)
-        ```
-
-    The decorator will:
-    - Create a span with the specified name (or function name)
-    - Set the span name and type as attributes
-    - Capture all function arguments as span attributes (skips self/cls for class methods)
-    - Capture the return value as a span attribute
-    - Record exceptions if they occur
-    - Set appropriate span status codes
     """
 
     def decorator(func: Callable) -> Callable:
-        # Determine span name
         name = span_name or func.__name__
 
-        # Check if function is async
         is_async = inspect.iscoroutinefunction(func)
 
         if is_async:
@@ -92,56 +80,42 @@ def decorator(func: Callable) -> Callable:
             async def async_wrapper(*args, **kwargs):
                 tracer = get_tracer()
 
-                # Get function signature for better argument names
                 sig = inspect.signature(func)
-                bound_args = sig.bind(*args, **kwargs)
-                bound_args.apply_defaults()
-
-                # Check if this is a method (has self or cls as first parameter)
                 param_names = list(sig.parameters.keys())
                 is_method = len(param_names) > 0 and param_names[0] in ("self", "cls")
                 start_idx = 1 if is_method else 0
 
-                # Start span
-                with tracer.start_as_current_span(name) as span:
+                with tracer.start_as_current_span(name) as otel_span:
                     try:
-                        span.set_attribute("name", name)
-                        span.set_attribute("type", type.value)
+                        otel_span.set_attribute("name", name)
+                        otel_span.set_attribute("type", type.value)
 
-                        # Capture inputs
                         inputs = {}
-
-                        # Add positional arguments (skip self/cls if it's a method)
                         for i, arg in enumerate(args[start_idx:], start=start_idx):
-                            if i < len(param_names):
-                                param_name = param_names[i]
-                                inputs[param_name] = _prepare_for_otel(arg)
-                            else:
-                                inputs[f"arg_{i}"] = _prepare_for_otel(arg)
+                            if _should_skip_value(arg):
+                                continue
+                            param_name = param_names[i] if i < len(param_names) else f"arg_{i}"
+                            inputs[param_name] = _prepare_for_otel(arg)
 
-                        # Add keyword arguments
                         for key, value in kwargs.items():
+                            if _should_skip_value(value):
+                                continue
                             inputs[key] = _prepare_for_otel(value)
 
-                        # Set input attributes on span (serialize the entire inputs dict)
-                        span.set_attribute("inputs", serialize(inputs))
+                        otel_span.set_attribute("inputs", serialize(inputs))
 
-                        # Execute function
                         result = await func(*args, **kwargs)
 
-                        # Capture output
                         output = _prepare_for_otel(result)
-                        span.set_attribute("outputs", serialize(output))
+                        otel_span.set_attribute("outputs", serialize(output))
 
-                        # Set success status
-                        span.set_status(Status(StatusCode.OK))
+                        otel_span.set_status(Status(StatusCode.OK))
 
                         return result
 
                     except Exception as e:
-                        # Record exception
-                        span.record_exception(e)
-                        span.set_status(Status(StatusCode.ERROR, str(e)))
+                        otel_span.record_exception(e)
+                        otel_span.set_status(Status(StatusCode.ERROR, str(e)))
                         raise
 
             return async_wrapper
@@ -151,63 +125,95 @@ async def async_wrapper(*args, **kwargs):
             def sync_wrapper(*args, **kwargs):
                 tracer = get_tracer()
 
-                # Get function signature for better argument names
                 sig = inspect.signature(func)
-                bound_args = sig.bind(*args, **kwargs)
-                bound_args.apply_defaults()
-
-                # Check if this is a method (has self or cls as first parameter)
                 param_names = list(sig.parameters.keys())
                 is_method = len(param_names) > 0 and param_names[0] in ("self", "cls")
                 start_idx = 1 if is_method else 0
 
-                # Start span
-                with tracer.start_as_current_span(name) as span:
+                with tracer.start_as_current_span(name) as otel_span:
                     try:
-                        span.set_attribute("name", name)
-                        span.set_attribute("type", type.value)
+                        otel_span.set_attribute("name", name)
+                        otel_span.set_attribute("type", type.value)
 
-                        # Capture inputs
                         inputs = {}
-
-                        # Add positional arguments (skip self/cls if it's a method)
                         for i, arg in enumerate(args[start_idx:], start=start_idx):
-                            if i < len(param_names):
-                                param_name = param_names[i]
-                                inputs[param_name] = _prepare_for_otel(arg)
-                            else:
-                                inputs[f"arg_{i}"] = _prepare_for_otel(arg)
+                            if _should_skip_value(arg):
+                                continue
+                            param_name = param_names[i] if i < len(param_names) else f"arg_{i}"
+                            inputs[param_name] = _prepare_for_otel(arg)
 
-                        # Add keyword arguments
                         for key, value in kwargs.items():
+                            if _should_skip_value(value):
+                                continue
                             inputs[key] = _prepare_for_otel(value)
 
-                        # Set input attributes on span (serialize the entire inputs dict)
-                        span.set_attribute("inputs", serialize(inputs))
+                        otel_span.set_attribute("inputs", serialize(inputs))
 
-                        # Execute function
                         result = func(*args, **kwargs)
 
-                        # Capture output
                         output = _prepare_for_otel(result)
-                        span.set_attribute("outputs", serialize(output))
+                        otel_span.set_attribute("outputs", serialize(output))
 
-                        # Set success status
-                        span.set_status(Status(StatusCode.OK))
+                        otel_span.set_status(Status(StatusCode.OK))
 
                         return result
 
                     except Exception as e:
-                        # Record exception
-                        span.record_exception(e)
-                        span.set_status(Status(StatusCode.ERROR, str(e)))
+                        otel_span.record_exception(e)
+                        otel_span.set_status(Status(StatusCode.ERROR, str(e)))
                         raise
 
             return sync_wrapper
 
     return decorator
 
 
+@contextmanager
+def span(name: str, span_type: SpanType = SpanType.FUNCTION, attributes: dict[str, Any] | None = None):
+    """Context manager that creates a child span under the current trace.
+
+    Use this for explicit span creation in loops or conditional blocks
+    where a decorator isn't practical.
+
+    Example::
+
+        for i in range(iterations):
+            with span("iteration", attributes={"iteration": i, "score": score}):
+                # ... iteration work ...
+                set_tag("decision", "keep")
+    """
+    tracer = get_tracer()
+    with tracer.start_as_current_span(name) as otel_span:
+        otel_span.set_attribute("name", name)
+        otel_span.set_attribute("type", span_type.value)
+        if attributes:
+            for key, value in attributes.items():
+                _safe_set_attribute(otel_span, key, value)
+        try:
+            yield otel_span
+        except Exception as e:
+            otel_span.record_exception(e)
+            otel_span.set_status(Status(StatusCode.ERROR, str(e)))
+            raise
+        else:
+            otel_span.set_status(Status(StatusCode.OK))
+
+
+def _safe_set_attribute(otel_span, key: str, value: Any) -> None:
+    """Set a span attribute, coercing the value to an OTel-compatible type."""
+    if isinstance(value, (str, int, float, bool)):
+        otel_span.set_attribute(key, value)
+    elif value is None:
+        otel_span.set_attribute(key, "")
+    elif isinstance(value, (list, tuple)):
+        if all(isinstance(v, str) for v in value):
+            otel_span.set_attribute(key, list(value))
+        else:
+            otel_span.set_attribute(key, serialize(value))
+    else:
+        otel_span.set_attribute(key, str(value))
+
+
 def set_workflow_name(workflow_name: str) -> None:
     attach(set_value("workflow_name", workflow_name))
 
@@ -217,16 +223,11 @@ def set_agent_name(agent_name: str) -> None:
 
 
 def set_conversation_id(conversation_id: str):
-    """
-    Set the conversation ID for the current context.
-    """
     attach(set_value("conversation_id", conversation_id))
 
 
 def conversation(conversation_id: str):
-    """
-    Decorator that automatically traces a conversation with OpenTelemetry.
-    """
+    """Decorator that sets a conversation ID in the current context."""
 
     def decorator(fn: Callable) -> Callable:
         if inspect.iscoroutinefunction(fn):
@@ -250,60 +251,20 @@ def sync_wrapper(*args, **kwargs):
 
 
 def function(name: Optional[str] = None):
-    """
-    Decorator that traces a function span.
-
-    Args:
-        name: Optional span name. Defaults to the decorated function's name.
-
-    Example:
-        @function(name="process_data")
-        def process_data(user_id: int):
-            ...
-    """
+    """Decorator that traces a function span."""
     return observe(span_name=name, type=SpanType.FUNCTION)
 
 
 def entry_point(name: Optional[str] = None):
-    """
-    Decorator that traces an entry point span.
-
-    Args:
-        name: Optional span name. Defaults to the decorated function's name.
-
-    Example:
-        @entry_point(name="api_handler")
-        async def handle_request(request):
-            ...
-    """
+    """Decorator that traces an entry point span."""
     return observe(span_name=name, type=SpanType.ENTRY_POINT)
 
 
 def workflow(name: Optional[str] = None):
-    """
-    Decorator that traces a workflow span.
-
-    Args:
-        name: Optional span name. Defaults to the decorated function's name.
-
-    Example:
-        @workflow(name="onboarding_flow")
-        def run_onboarding(user_id: str):
-            ...
-    """
+    """Decorator that traces a workflow span."""
     return observe(span_name=name, type=SpanType.WORKFLOW)
 
 
 def tool(name: Optional[str] = None):
-    """
-    Decorator that traces a tool span.
-
-    Args:
-        name: Optional span name. Defaults to the decorated function's name.
-
-    Example:
-        @tool(name="web_search")
-        def search(query: str):
-            ...
-    """
+    """Decorator that traces a tool span."""
     return observe(span_name=name, type=SpanType.TOOL)