galileo-core 3.82.0__py3-none-any.whl → 3.83.0__py3-none-any.whl

galileo_core/__init__.py

@@ -1 +1 @@
-__version__ = "3.82.0"
+__version__ = "3.83.0"

galileo_core/exceptions/base.py

@@ -6,11 +6,24 @@ from galileo_core.helpers.logger import logger
 
 
 class BaseGalileoException(Exception, ABC):
-    """Base exception for all exceptions in galileo."""
+    """Base exception for all exceptions in galileo.
+
+    Attributes:
+        message: Human-readable error message
+        error_code: Optional EMS catalog lookup key for standardized error handling
+        LOG_LEVEL: Logging level for this exception type
+    """
 
     LOG_LEVEL: int = WARNING
 
-    def __init__(self, message: str, logging_extra: Optional[Dict[str, Any]] = None) -> None:
+    def __init__(
+        self,
+        message: str,
+        logging_extra: Optional[Dict[str, Any]] = None,
+        *,
+        error_code: Optional[int] = None,
+    ) -> None:
         logger.log(self.LOG_LEVEL, message, extra=logging_extra)
         self.message: str = message
+        self.error_code: Optional[int] = error_code
         super().__init__(self.message)

galileo_core/schemas/logging/span.py

@@ -34,6 +34,9 @@ class BaseSpan(BaseStep):
 class StepWithChildSpans(BaseSpan):
     spans: List["Span"] = Field(default_factory=list, description="Child spans.")
     _last_child_created_at: Optional[datetime] = PrivateAttr(default=None)
+    # Runtime back-pointer for cursor navigation in TracesLogger (not serialized).
+    # This enables O(1) navigation up the trace hierarchy without maintaining a stack.
+    _parent: Optional["StepWithChildSpans"] = PrivateAttr(default=None)
 
     def add_child_spans(self, spans: Sequence["Span"]) -> None:
         self.spans.extend(spans)

galileo_core/schemas/shared/traces_logger.py

@@ -1,9 +1,10 @@
 from collections import deque
+from contextvars import ContextVar
 from datetime import datetime
 from json import dumps
-from typing import Deque, Dict, List, Optional
+from typing import Any, Deque, Dict, List, Mapping, Optional
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field, PrivateAttr
 from pydantic.types import UUID4
 
 from galileo_core.schemas.logging.agent import AgentType
@@ -27,11 +28,127 @@ from galileo_core.utils.json import PydanticJsonEncoder
 
 
 class TracesLogger(BaseModel):
+    """Logger for managing traces and spans with async-safe parent tracking.
+
+    Each TracesLogger instance maintains its own isolated ContextVar for tracking
+    the current parent in the trace hierarchy. This allows:
+    - Multiple TracesLogger instances to operate independently
+    - Async-safe parent tracking within each instance (via ContextVar semantics)
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
     traces: List[Trace] = Field(default_factory=list, description="List of traces.")
-    _parent_stack: Deque[StepWithChildSpans] = deque()
+
+    # Per-instance ContextVar for async-safe parent tracking.
+    # Each instance has its own ContextVar, providing isolation between logger instances.
+    _parent_context_var: ContextVar[Optional[StepWithChildSpans]] = PrivateAttr()
+
+    def _create_context_var(self) -> None:
+        """Create a new ContextVar for this instance.
+
+        Each instance must have its own ContextVar to maintain isolation.
+        """
+        self._parent_context_var = ContextVar(f"_current_parent_{id(self)}", default=None)
+
+    def model_post_init(self, __context: Any) -> None:
+        """Initialize the per-instance ContextVar after model construction."""
+        self._create_context_var()
+
+    def model_copy(self, *, update: Optional[Mapping[str, Any]] = None, deep: bool = False) -> "TracesLogger":
+        """Override model_copy to create a fresh ContextVar on the copy.
+
+        Pydantic's model_copy bypasses model_post_init and would share the
+        same ContextVar reference, so we must create a new one for isolation.
+        """
+        copied = super().model_copy(update=update, deep=deep)
+        copied._create_context_var()
+        return copied
+
+    def __copy__(self) -> "TracesLogger":
+        """Create fresh ContextVar when using copy.copy()."""
+        copied = super().__copy__()
+        copied._create_context_var()
+        return copied
+
+    def __deepcopy__(self, memo: Optional[Dict[int, Any]] = None) -> "TracesLogger":
+        """Create fresh ContextVar when using copy.deepcopy().
+
+        ContextVar objects cannot be pickled, so we must handle deepcopy
+        by creating a new instance with deepcopied data, then creating
+        a fresh ContextVar.
+        """
+        import copy
+
+        if memo is None:
+            memo = {}
+
+        # Deepcopy the traces (the main data)
+        copied_traces = copy.deepcopy(self.traces, memo)
+
+        # Create new instance with copied data
+        copied = TracesLogger(traces=copied_traces)
+        # model_post_init already creates the ContextVar for new instances
+
+        # Register in memo to handle circular references
+        memo[id(self)] = copied
+
+        return copied
+
+    def _set_current_parent(self, parent: Optional[StepWithChildSpans]) -> None:
+        """Set the current parent for the current async context."""
+        self._parent_context_var.set(parent)
 
     def current_parent(self) -> Optional[StepWithChildSpans]:
-        return self._parent_stack[-1] if self._parent_stack else None
+        """Get the current parent span/trace for the current async context."""
+        return self._parent_context_var.get()
+
+    def reset_parent_tracking(self) -> None:
+        """Reset the current parent tracking for this logger instance.
+
+        Call this when reinitializing the logger or switching contexts.
+        """
+        self._parent_context_var.set(None)
+
+    @property
+    def _parent_stack(self) -> Deque[StepWithChildSpans]:
+        """Reconstruct the parent stack by walking up the _parent chain.
+
+        This property provides backward compatibility for code that accesses
+        _parent_stack directly. The returned deque represents the path from
+        root to current position.
+
+        Note: This is a read-only view. Mutations to this deque will not
+        affect the actual parent tracking. Use the span methods instead.
+        """
+        path: List[StepWithChildSpans] = []
+        current = self.current_parent()
+        while current is not None:
+            path.append(current)
+            current = current._parent
+        # Reverse to get root-to-current order (like a stack bottom-to-top)
+        return deque(reversed(path))
+
+    @_parent_stack.setter
+    def _parent_stack(self, value: Deque[StepWithChildSpans]) -> None:
+        """Set the current parent from a deque (for backward compatibility).
+
+        If deque is empty, clears the current parent.
+        Otherwise, sets current parent to the last item and rebuilds _parent chain.
+        """
+        if not value:
+            self._set_current_parent(None)
+            return
+
+        # Build the _parent chain from the deque
+        items = list(value)
+        for i, item in enumerate(items):
+            if i == 0:
+                item._parent = None
+            else:
+                item._parent = items[i - 1]
+
+        # Set current parent to the top of the stack (last item)
+        self._set_current_parent(items[-1])
 
     def add_child_span_to_parent(self, span: Span) -> None:
         current_parent = self.current_parent()
@@ -107,8 +224,9 @@ class TracesLogger(BaseModel):
             external_id=external_id,
             id=id,
         )
+        trace._parent = None  # Trace is root
         self.traces.append(trace)
-        self._parent_stack.append(trace)
+        self._set_current_parent(trace)
         return trace
 
     def add_single_llm_span_trace(
@@ -219,7 +337,7 @@ class TracesLogger(BaseModel):
         )
         self.traces.append(trace)
         # Single span traces are automatically concluded so we reset the current parent.
-        self._parent_stack = deque()
+        self._set_current_parent(None)
         return trace
 
     def add_llm_span(
@@ -443,6 +561,7 @@ class TracesLogger(BaseModel):
         -------
             WorkflowSpan: The created span.
         """
+        parent = self.current_parent()
         span = WorkflowSpan(
             input=input,
             redacted_input=redacted_input,
@@ -456,8 +575,9 @@ class TracesLogger(BaseModel):
             id=id,
             step_number=step_number,
         )
+        span._parent = parent  # Set back-pointer before adding to parent
         self.add_child_span_to_parent(span)
-        self._parent_stack.append(span)
+        self._set_current_parent(span)
         return span
 
     def add_agent_span(
@@ -492,6 +612,7 @@ class TracesLogger(BaseModel):
         -------
             AgentSpan: The created span.
         """
+        parent = self.current_parent()
         span = AgentSpan(
             input=input,
             redacted_input=redacted_input,
@@ -506,8 +627,9 @@ class TracesLogger(BaseModel):
             id=id,
             step_number=step_number,
         )
+        span._parent = parent  # Set back-pointer before adding to parent
         self.add_child_span_to_parent(span)
-        self._parent_stack.append(span)
+        self._set_current_parent(span)
         return span
 
     def conclude(
@@ -542,7 +664,10 @@ class TracesLogger(BaseModel):
         if duration_ns is not None:
             current_parent.metrics.duration_ns = duration_ns
 
-        finished_step = self._parent_stack.pop()
-        if self.current_parent() is None and not isinstance(finished_step, Trace):
+        # Navigate up to parent via _parent pointer
+        parent = current_parent._parent
+        self._set_current_parent(parent)
+
+        if parent is None and not isinstance(current_parent, Trace):
             raise ValueError("Finished step is not a trace, but has no parent.  Not added to the list of traces.")
         return self.current_parent()

{galileo_core-3.82.0.dist-info → galileo_core-3.83.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: galileo-core
-Version: 3.82.0
+Version: 3.83.0
 Summary: Shared schemas and configuration for Galileo's Python packages.
 License: Apache-2.0
 Keywords: llm,quality,language_models,galileo

{galileo_core-3.82.0.dist-info → galileo_core-3.83.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-galileo_core/__init__.py,sha256=Za0uTMfFaftHcrL2K7d8-r1a_Sek_wUhBGK_J52fbow,23
+galileo_core/__init__.py,sha256=FJQtOiI1SJSt2a463wEccA_T8wmbbGEon12b3WLW6k0,23
 galileo_core/constants/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 galileo_core/constants/config.py,sha256=MYvixj3X3CoiC38QVMdidApURKFOAaPaYoHhFESOJlU,329
 galileo_core/constants/dataset_format.py,sha256=H6ZigDd2QMpRcRhLC38e0hRoMh0kKbvdhbmS5yK1gZU,116
@@ -9,7 +9,7 @@ galileo_core/constants/request_method.py,sha256=szwggZ9BPQwY7qVFdOJRREfFfp-wT_LO
 galileo_core/constants/routes.py,sha256=q0EJ6oidfkUAlRAF7UUXw2_fYO5L5ejGzqbN7Ut0JOI,1577
 galileo_core/constants/scorers.py,sha256=5Mojtg2arv03o7fxuUI64x9L36OGButJvwWVeM8LQrE,1229
 galileo_core/exceptions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-galileo_core/exceptions/base.py,sha256=EHgqf3DAocpWyGZa4HwQYUDMYZQH0MCzDEQBoAtLS2g,502
+galileo_core/exceptions/base.py,sha256=9eZQ0ak_fcvt8ywJWJg9wmkgKVCxcZ2U1BDvclNQGFw,847
 galileo_core/exceptions/execution.py,sha256=oR7h-aw1qgBfxKRiB6re2IrTavkrygC8ybE-AWiRTKM,2754
 galileo_core/exceptions/http.py,sha256=lW3oIcxb3U5l9ZfsiPZmKHxQiqG-ASK3CJtD4WK8n5w,343
 galileo_core/helpers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -73,7 +73,7 @@ galileo_core/schemas/logging/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NM
 galileo_core/schemas/logging/agent.py,sha256=zexqP7o_wjicj4H1ZhrF9wkaYBxcj-skLv_LXj8H7gU,252
 galileo_core/schemas/logging/llm.py,sha256=BN2oya2sqAWdOxthN2bCWCfDXEsjKBTCXjBYWh4Q758,7521
 galileo_core/schemas/logging/session.py,sha256=R7J5B33ffdQrNpzj7HEBLjQ3rKqNRuHOYttO_-PK378,751
-galileo_core/schemas/logging/span.py,sha256=k4UdVNV4fbUaCQ4ZsKir125jbAnN3ZD1vDNFA7fVB1I,12480
+galileo_core/schemas/logging/span.py,sha256=smaGm3kvghRi3seaFdMKcgdvRF0ZLerptBIZAh-I6i4,12722
 galileo_core/schemas/logging/step.py,sha256=rRwRSeFbUFbnWg6mOfclo3s6VTtPayLE2-7qBMwqKFQ,8702
 galileo_core/schemas/logging/trace.py,sha256=irLlf6XyPL0k326A3u_dfN7sb6TzEdfR8veCXWB3c3o,925
 galileo_core/schemas/logging/tree.py,sha256=eC9LR10zARWYl7DFJzGvQrTTaEnaB02Jyxy0NyctZ9c,3188
@@ -109,7 +109,7 @@ galileo_core/schemas/shared/scorers/scorer_configuration.py,sha256=hSJ-rObA_Wqff
 galileo_core/schemas/shared/scorers/scorer_name.py,sha256=9MbDQzObVcmJl53AmmD-xrBM7Qxmm2YhNBr4RNhn2YE,3586
 galileo_core/schemas/shared/scorers/scorer_type.py,sha256=04ZPqHkvRR6b9ARitQJhGfn-9nKP4fNH_n1noeEt08c,1401
 galileo_core/schemas/shared/scorers/scorers.py,sha256=3OA8-QYkCslo7IOHrHQ5kVKRfBbaFvt5gG7WVTzi9pc,4962
-galileo_core/schemas/shared/traces_logger.py,sha256=HXydSyfHmizxcqYFzwAKYdamH1lfgRrxXThh1yirjYU,23498
+galileo_core/schemas/shared/traces_logger.py,sha256=Xulis-c_pYXDm1ejyRxTWkMivFNtl6yYnuVL0xsd26c,28490
 galileo_core/schemas/shared/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 galileo_core/schemas/shared/workflows/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 galileo_core/schemas/shared/workflows/node_type.py,sha256=CKiYkOanhE9vtseAikj0UmWCiOnEjSLLiIISScl6xE8,241
@@ -122,8 +122,8 @@ galileo_core/utils/dataset.py,sha256=wjm3NdNRuxj5mK7GqQUdA-Map_EB0SpFfM1QKapd6-A
 galileo_core/utils/json.py,sha256=ug5P-iozgmqXRhLZS3Dm_JPViTICboKukg1mqqBq2i4,327
 galileo_core/utils/name.py,sha256=kaDeZJ1K3-SSazYrUeSbUsQrnZlnOBYU42t-QvX-coE,204
 galileo_core/utils/scorer_validation.py,sha256=bjNmDZhNsmmb8qHBfndXVAL60W5nCvoDdKrAoAegxJg,11259
-galileo_core-3.82.0.dist-info/LICENSE,sha256=4D_6tarPnIYkAqF-0LzrodE9wFtSulO3V4RZf__MriE,10946
-galileo_core-3.82.0.dist-info/METADATA,sha256=wBo3uAicViV37ZZy7RtvYX4rpgie7DQJVlevlvsKICY,2731
-galileo_core-3.82.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-galileo_core-3.82.0.dist-info/entry_points.txt,sha256=epOvdlN6_7ua8stNHURhJhXDIIrheccwYv0Z-QFmHJU,61
-galileo_core-3.82.0.dist-info/RECORD,,
+galileo_core-3.83.0.dist-info/LICENSE,sha256=4D_6tarPnIYkAqF-0LzrodE9wFtSulO3V4RZf__MriE,10946
+galileo_core-3.83.0.dist-info/METADATA,sha256=6mkFU2IxzmZsCxyLavQbEqoaFHshCZq-uurvR8o29EQ,2731
+galileo_core-3.83.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+galileo_core-3.83.0.dist-info/entry_points.txt,sha256=epOvdlN6_7ua8stNHURhJhXDIIrheccwYv0Z-QFmHJU,61
+galileo_core-3.83.0.dist-info/RECORD,,