raindrop-ai 0.0.32__py3-none-any.whl → 0.0.34__py3-none-any.whl

raindrop/analytics.py

@@ -63,6 +63,8 @@ __all__ = [
     "tool",
     "task_span",
     "tool_span",
+    "start_span",
+    "ManualSpan",
     "set_span_properties",
     "flush",
     "shutdown",
@@ -492,7 +494,7 @@ def begin(
             {k: v for k, v in span_attributes.items() if v is not None}
         )
 
-    interaction = Interaction(eid)
+    interaction = Interaction(eid, user_id=user_id, event=event, convo_id=convo_id)
     INTERACTION_EVENT_ID_REGISTRY[eid] = interaction
     if current_trace_id is not None and current_trace_id != 0:
         INTERACTION_TRACE_ID_REGISTRY[current_trace_id] = interaction
@@ -635,6 +637,63 @@ class TraceEntitySpan:
             Traceloop.set_association_properties(props)
 
 
+class ManualSpan:
+    """
+    A manually-controlled span for async/distributed operations.
+    Unlike context-managed spans, this requires explicit .end() calls.
+    """
+
+    def __init__(self, span, kind: str, name: str, event_id: str | None = None):
+        self._span = span
+        self._kind = kind
+        self._name = name
+        self._event_id = event_id
+        self._ended = False
+
+    @property
+    def event_id(self) -> str | None:
+        return self._event_id
+
+    def record_input(self, data: Any) -> None:
+        if self._span and _should_send_prompts():
+            try:
+                json_input = json.dumps({"args": [data]}, cls=JSONEncoder)
+                truncated = _truncate_json_if_needed(json_input)
+                self._span.set_attribute(
+                    SpanAttributes.TRACELOOP_ENTITY_INPUT, truncated
+                )
+            except TypeError as e:
+                logger.debug(f"[raindrop] Could not serialize input for span: {e}")
+
+    def record_output(self, data: Any) -> None:
+        if self._span and _should_send_prompts():
+            try:
+                json_output = json.dumps(data, cls=JSONEncoder)
+                truncated = _truncate_json_if_needed(json_output)
+                self._span.set_attribute(
+                    SpanAttributes.TRACELOOP_ENTITY_OUTPUT, truncated
+                )
+            except TypeError as e:
+                logger.debug(f"[raindrop] Could not serialize output for span: {e}")
+
+    def set_properties(self, props: Dict[str, Any]) -> None:
+        if self._span and props:
+            for key, value in props.items():
+                if value is not None:
+                    self._span.set_attribute(
+                        f"traceloop.association.properties.{key}", value
+                    )
+
+    def end(self, error: Exception | None = None) -> None:
+        if self._ended or not self._span:
+            return
+        self._ended = True
+        if error is not None:
+            self._span.set_status(Status(StatusCode.ERROR, str(error)))
+            self._span.record_exception(error)
+        self._span.end()
+
+
 class _EntitySpanContext:
     def __init__(self, kind: Literal["task", "tool"], name: str, version: int | None):
         self._kind = kind
@@ -708,6 +767,63 @@ def tool_span(name: str, version: int | None = None) -> _EntitySpanContext:
     return _EntitySpanContext("tool", name, version)
 
 
+def start_span(
+    kind: Literal["task", "tool"],
+    name: str,
+    version: int | None = None,
+    event_id: str | None = None,
+    user_id: str | None = None,
+    event: str | None = None,
+    convo_id: str | None = None,
+) -> ManualSpan:
+    """
+    Create a manual span that must be explicitly ended with .end().
+
+    Use this for async/distributed operations where the span lifecycle
+    extends beyond a single context manager scope.
+
+    Args:
+        kind: Type of span - "task" or "tool"
+        name: Name of the span
+        version: Optional version number
+        event_id: Optional event_id for tracing association
+        user_id: Optional user_id for tracing association
+        event: Optional event name for tracing association
+        convo_id: Optional conversation ID for tracing association
+
+    Returns:
+        ManualSpan instance (safe to use even if tracing is disabled)
+    """
+    if not _tracing_enabled or not TracerWrapper.verify_initialized():
+        return ManualSpan(None, kind, name, event_id)
+
+    tlp_kind = (
+        TraceloopSpanKindValues.TASK if kind == "task" else TraceloopSpanKindValues.TOOL
+    )
+    span_name = f"{name}.{tlp_kind.value}"
+
+    with get_tracer() as tracer:
+        span = tracer.start_span(span_name)
+
+    span.set_attribute(SpanAttributes.TRACELOOP_SPAN_KIND, tlp_kind.value)
+    span.set_attribute(SpanAttributes.TRACELOOP_ENTITY_NAME, name)
+    if version is not None:
+        span.set_attribute(SpanAttributes.TRACELOOP_ENTITY_VERSION, version)
+
+    # Set association properties directly on the span (not on current context)
+    association_props = {
+        "event_id": event_id,
+        "user_id": user_id,
+        "event": event,
+        "convo_id": convo_id,
+    }
+    for key, value in association_props.items():
+        if value is not None:
+            span.set_attribute(f"traceloop.association.properties.{key}", value)
+
+    return ManualSpan(span, kind, name, event_id)
+
+
 def resume_interaction(event_id: str | None = None) -> Interaction:
     """Return an Interaction associated with the current trace or given event_id."""
 

raindrop/interaction.py

@@ -3,7 +3,9 @@ from typing import (
     Any,
     Dict,
     List,
+    Literal,
     Optional,
+    TYPE_CHECKING,
     Union,
     Iterator,
 )
@@ -14,6 +16,9 @@ from .models import Attachment, PartialTrackAIEvent
 from . import analytics as _core
 from opentelemetry import context as context_api
 
+if TYPE_CHECKING:
+    from .analytics import ManualSpan
+
 
 class Interaction:
     """
@@ -23,6 +28,9 @@ class Interaction:
 
     __slots__ = (
         "_event_id",
+        "_user_id",
+        "_event",
+        "_convo_id",
         "_analytics",
         "__weakref__",
     )
@@ -30,8 +38,14 @@ class Interaction:
     def __init__(
         self,
         event_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+        event: Optional[str] = None,
+        convo_id: Optional[str] = None,
     ):
         self._event_id = event_id or str(uuid4())
+        self._user_id = user_id
+        self._event = event
+        self._convo_id = convo_id
         self._analytics = _core
 
     # -- mutators ----------------------------------------------------------- #
@@ -63,6 +77,36 @@ class Interaction:
         )
         self._analytics._track_ai_partial(payload)
 
+    def start_span(
+        self,
+        kind: Literal["task", "tool"],
+        name: str,
+        version: int | None = None,
+    ) -> "ManualSpan":
+        """
+        Create a manual span tied to this interaction.
+
+        The span automatically inherits association properties from this interaction
+        (event_id, user_id, event, convo_id) for proper tracing.
+
+        Args:
+            kind: Type of span - "task" or "tool"
+            name: Name of the span
+            version: Optional version number
+
+        Returns:
+            ManualSpan instance that must be explicitly ended with .end()
+        """
+        return self._analytics.start_span(
+            kind,
+            name,
+            version,
+            event_id=self._event_id,
+            user_id=self._user_id,
+            event=self._event,
+            convo_id=self._convo_id,
+        )
+
     # convenience
     @property
     def id(self) -> str:

raindrop/version.py

@@ -1 +1 @@
-VERSION = "0.0.32"
+VERSION = "0.0.34"

{raindrop_ai-0.0.32.dist-info → raindrop_ai-0.0.34.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: raindrop-ai
-Version: 0.0.32
+Version: 0.0.34
 Summary: Raindrop AI (Python SDK)
 License: MIT
 Author: Raindrop AI
@@ -13,7 +13,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Dist: pydantic (>=2.09,<3)
 Requires-Dist: requests (>=2.32.3,<3.0.0)
-Requires-Dist: traceloop-sdk (==0.45.6)
+Requires-Dist: traceloop-sdk (>=0.46.0)
 Description-Content-Type: text/markdown
 
 # Raindrop Python SDK

raindrop_ai-0.0.34.dist-info/RECORD

@@ -0,0 +1,10 @@
+raindrop/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+raindrop/analytics.py,sha256=uS4D8_r9VEzIVJgPDBpT7Nkr2i1PS9Yj_QCWgqGEBNM,28507
+raindrop/interaction.py,sha256=Kw8HNaDSHVIi1p-2HK5SsYGI4Xg1zQFml4dX2EhIT7w,3123
+raindrop/models.py,sha256=9lOOUQ2FF11RPkntuLZwN3e54pa9HtR8lGvCbzlWOPM,5198
+raindrop/redact.py,sha256=rMNUoI90KxOY3d_zcHAr0TFD2yQ_CDgpDz-1XJLVmHs,7658
+raindrop/version.py,sha256=46z7DjpRJ03wdmbNWoSr-zmeqNLwMTq3Ue5OAhyiKPU,19
+raindrop/well-known-names.json,sha256=9giJF6u6W1R0APW-Pf1dvNUU32OXQEoQ9CBQXSnA3ks,144403
+raindrop_ai-0.0.34.dist-info/METADATA,sha256=24MFAmx6jhHt8W2MybBsEfbWa-wcTrFaU0ATAK6F3Xs,1269
+raindrop_ai-0.0.34.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+raindrop_ai-0.0.34.dist-info/RECORD,,

raindrop_ai-0.0.32.dist-info/RECORD

@@ -1,10 +0,0 @@
-raindrop/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-raindrop/analytics.py,sha256=XHCXHM-S92ZAgsigPrDovUDTSlHiLLfuIHHEq9wnpTY,24354
-raindrop/interaction.py,sha256=1gYFj2-oEobLtG56RZw5de3RjYr0pCXg_NqYDGx32Uc,1896
-raindrop/models.py,sha256=9lOOUQ2FF11RPkntuLZwN3e54pa9HtR8lGvCbzlWOPM,5198
-raindrop/redact.py,sha256=rMNUoI90KxOY3d_zcHAr0TFD2yQ_CDgpDz-1XJLVmHs,7658
-raindrop/version.py,sha256=cNdQQHZ8mflTb7N2BvtJg9nS-15yTl7r-Bo6P1TZQ4s,19
-raindrop/well-known-names.json,sha256=9giJF6u6W1R0APW-Pf1dvNUU32OXQEoQ9CBQXSnA3ks,144403
-raindrop_ai-0.0.32.dist-info/METADATA,sha256=2s5D6vchrSiUXk1VTFLz5ngqvdgE8pj_8YLigrpTeg0,1269
-raindrop_ai-0.0.32.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-raindrop_ai-0.0.32.dist-info/RECORD,,