netra-sdk 0.1.39__tar.gz → 0.1.40__tar.gz

{netra_sdk-0.1.39 → netra_sdk-0.1.40}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: netra-sdk
-Version: 0.1.39
+Version: 0.1.40
 Summary: A Python SDK for AI application observability that provides OpenTelemetry-based monitoring, tracing, and PII protection for LLM and vector database applications. Enables easy instrumentation, session tracking, and privacy-focused data collection for AI systems in production environments.
 License: Apache-2.0
 Keywords: netra,tracing,observability,sdk,ai,llm,vector,database

{netra_sdk-0.1.39 → netra_sdk-0.1.40}/netra/__init__.py

@@ -9,11 +9,11 @@ from opentelemetry.trace import SpanKind
 
 from netra.instrumentation.instruments import InstrumentSet, NetraInstruments
 
-from .config import Config
+from .config import Config, ConversationType
 
 # Instrumentor functions
 from .instrumentation import init_instrumentations
-from .session_manager import SessionManager
+from .session_manager import ConversationType, SessionManager
 from .span_wrapper import ActionModel, SpanWrapper, UsageModel
 from .tracer import Tracer
 
@@ -248,6 +248,15 @@ class Netra:
         else:
             logger.warning("Both event_name and attributes must be provided for custom events.")
 
+    @classmethod
+    def add_conversation(cls, type: ConversationType, field_name: str, value: Any) -> None:
+        """
+        Append a conversation entry and set span attribute 'conversation' as an array.
+        If a conversation array already exists for the current active span, this appends
+        to it; otherwise, it initializes a new array.
+        """
+        SessionManager.add_conversation(type=type, field_name=field_name, value=value)
+
     @classmethod
     def start_span(
         cls,
@@ -260,43 +269,5 @@ class Netra:
         """
         return SpanWrapper(name, attributes, module_name)
 
-    @classmethod
-    def set_input(cls, value: Any, span_name: Optional[str] = None) -> None:
-        """
-        Set custom attribute `netra.span.input` on a target span.
-
-        Args:
-            value: Input payload to record (string or JSON-serializable object)
-            span_name: Optional. When provided, sets the attribute on the span registered
-                       with this name. Otherwise sets on the active span.
-        """
-        SessionManager.set_attribute_on_target_span(f"{Config.LIBRARY_NAME}.span.input", value, span_name)
-
-    @classmethod
-    def set_output(cls, value: Any, span_name: Optional[str] = None) -> None:
-        """
-        Set custom attribute `netra.span.output` on a target span.
-
-        Args:
-            value: Output payload to record (string or JSON-serializable object)
-            span_name: Optional. When provided, sets the attribute on the span registered
-                       with this name. Otherwise sets on the active span.
-        """
-        if value:
-            SessionManager.set_attribute_on_target_span(f"{Config.LIBRARY_NAME}.span.output", value, span_name)
-
-    @classmethod
-    def set_prompt(cls, value: Any, span_name: Optional[str] = None) -> None:
-        """
-        Set custom attribute `netra.span.prompt` on a target span.
-
-        Args:
-            value: Prompt payload to record (string or JSON-serializable object)
-            span_name: Optional. When provided, sets the attribute on the span registered
-                       with this name. Otherwise sets on the active span.
-        """
-        if value:
-            SessionManager.set_attribute_on_target_span(f"{Config.LIBRARY_NAME}.span.prompt", value, span_name)
-
 
 __all__ = ["Netra", "UsageModel", "ActionModel"]

{netra_sdk-0.1.39 → netra_sdk-0.1.40}/netra/config.py

@@ -1,5 +1,6 @@
 import json
 import os
+from enum import Enum
 from typing import Any, Dict, List, Optional
 
 from opentelemetry.util.re import parse_env_headers
@@ -7,6 +8,12 @@ from opentelemetry.util.re import parse_env_headers
 from netra.version import __version__
 
 
+class ConversationType(str, Enum):
+    INPUT = "input"
+    OUTPUT = "output"
+    SYSTEM = "system"
+
+
 class Config:
     """
     Holds configuration options for the tracer:

{netra_sdk-0.1.39 → netra_sdk-0.1.40}/netra/session_manager.py

@@ -5,17 +5,24 @@ Handles automatic session and user ID management for applications.
 
 import logging
 from datetime import datetime
+from enum import Enum
 from typing import Any, Dict, List, Optional, Union
 
 from opentelemetry import baggage
 from opentelemetry import context as otel_context
 from opentelemetry import trace
 
-from .config import Config
+from netra.config import Config
 
 logger = logging.getLogger(__name__)
 
 
+class ConversationType(str, Enum):
+    INPUT = "input"
+    OUTPUT = "output"
+    SYSTEM = "system"
+
+
 class SessionManager:
     """Manages session and user context for applications."""
 
@@ -254,79 +261,64 @@ class SessionManager:
         except Exception as e:
             logger.exception(f"Failed to add custom event: {name} - {e}")
 
-    @classmethod
-    def set_attribute_on_target_span(cls, attr_key: str, attr_value: Any, span_name: Optional[str] = None) -> None:
+    @staticmethod
+    def add_conversation(type: ConversationType, field_name: str, value: Any) -> None:
         """
-        Best-effort setter to annotate a target span with the provided attribute.
+        Append a conversation entry and set span attribute 'conversation' as an array.
 
-        Behavior:
-        - If span_name is provided, set the attribute on the span registered with that name.
-        - If no span_name is provided, attempt to set the attribute on the SDK root span
-          (created when Netra.init(enable_root_span=True)). If the root span is unavailable,
-          fall back to the currently active span (OTel current span or SDK-managed current span).
+        Stored attribute format:
+        conversation: [
+          { "type": "input/output/system", "field_name": "sample_name", "value": "sample_value" },
+          ...
+        ]
         """
-        try:
-            # Convert attribute value to a JSON-safe string representation
-            try:
-                if isinstance(attr_value, str):
-                    attr_str = attr_value
-                else:
-                    import json
 
-                    attr_str = json.dumps(attr_value)
-            except Exception:
-                attr_str = str(attr_value)
-
-            # If a target span name is provided, use the registry for explicit lookup
-            if span_name is not None:
-                target = cls.get_span_by_name(span_name)
-                if target is None:
-                    logger.debug("No span found with name '%s' to set attribute %s", span_name, attr_key)
-                    return
-                target.set_attribute(attr_key, attr_str)
+        # Hard runtime validation of input types and values
+        if not isinstance(type, ConversationType):
+            raise TypeError("type must be a ConversationType enum value (input, output, system)")
+        normalized_type = type.value
+
+        if not isinstance(field_name, str):
+            raise TypeError(f"field_name must be a string, got {type(field_name)}")
+        if not field_name:
+            raise ValueError("field_name must be a non-empty string")
+
+        if value is None:
+            raise ValueError("value must not be None")
+
+        try:
+            span = trace.get_current_span()
+            if not (span and getattr(span, "is_recording", lambda: False)()):
+                logger.warning("No active span to add conversation attribute.")
                 return
 
-            # Otherwise, attempt to set on the root-most span in the current trace
-            candidate = None
+            existing: List[Dict[str, Any]] = []
+            raw_data = None
 
-            # Determine current trace_id from the active/current span
-            current_span = trace.get_current_span()
-            has_valid_current = getattr(current_span, "is_recording", None) is not None and current_span.is_recording()
-            base_span = current_span if has_valid_current else cls.get_current_span()
-            trace_id: Optional[int] = None
             try:
-                if base_span is not None and hasattr(base_span, "get_span_context"):
-                    sc = base_span.get_span_context()
-                    trace_id = getattr(sc, "trace_id", None)
+                attrs = getattr(span, "_attributes", None)
+                if attrs is not None and hasattr(attrs, "get"):
+                    raw_data = attrs.get("conversation")
             except Exception:
-                trace_id = None
-
-            # Find the earliest active span in this process that belongs to the same trace
-            if trace_id is not None:
+                logger.exception("Failed to retrieve conversation attribute")
+            if raw_data:
                 try:
-                    for s in cls._active_spans:
-                        if s is None:
-                            continue
-                        if not getattr(s, "is_recording", lambda: False)():
-                            continue
-                        sc = getattr(s, "get_span_context", lambda: None)()
-                        if sc is None:
-                            continue
-                        if getattr(sc, "trace_id", None) == trace_id:
-                            candidate = s
-                            break
+                    import json
+
+                    if isinstance(raw_data, str):
+                        parsed = json.loads(raw_data)
+                    if isinstance(parsed, list):
+                        existing = parsed
                 except Exception:
-                    candidate = None
+                    existing = []
 
-            # Fallback to the current active span if no root-most could be found
-            if candidate is None:
-                candidate = base_span
-            if candidate is None:
-                logger.debug("No active span found to set attribute %s", attr_key)
-                return
-            candidate.set_attribute(attr_key, attr_str)
+            # Append new entry
+            entry: Dict[str, Any] = {"type": normalized_type, "field_name": field_name, "value": value}
+            existing.append(entry)
+
+            SessionManager.set_attribute_on_active_span("conversation", existing)
         except Exception as e:
-            logger.exception("Failed setting attribute %s: %s", attr_key, e)
+            logger.exception("Failed to add conversation attribute: %s", e)
 
     @staticmethod
     def set_attribute_on_active_span(attr_key: str, attr_value: Any) -> None:

netra_sdk-0.1.40/netra/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.40"

{netra_sdk-0.1.39 → netra_sdk-0.1.40}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "netra-sdk"
-version = "0.1.39"
+version = "0.1.40"
 description = "A Python SDK for AI application observability that provides OpenTelemetry-based monitoring, tracing, and PII protection for LLM and vector database applications. Enables easy instrumentation, session tracking, and privacy-focused data collection for AI systems in production environments."
 authors = [
     {name = "Sooraj Thomas",email = "sooraj@keyvalue.systems"}

netra_sdk-0.1.39/netra/version.py

@@ -1 +0,0 @@
-__version__ = "0.1.39"