netra-sdk 0.1.45__tar.gz → 0.1.47__tar.gz

{netra_sdk-0.1.45 → netra_sdk-0.1.47}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: netra-sdk
-Version: 0.1.45
+Version: 0.1.47
 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-Expression: Apache-2.0
 License-File: LICENCE

{netra_sdk-0.1.45 → netra_sdk-0.1.47}/netra/__init__.py

@@ -1,7 +1,7 @@
 import atexit
 import logging
 import threading
-from typing import Any, Dict, List, Optional, Set
+from typing import Any, Dict, List, Literal, Optional, Set
 
 from opentelemetry import context as context_api
 from opentelemetry import trace
@@ -14,7 +14,7 @@ from .config import Config
 # Instrumentor functions
 from .instrumentation import init_instrumentations
 from .session_manager import ConversationType, SessionManager
-from .span_wrapper import ActionModel, SpanWrapper, UsageModel
+from .span_wrapper import ActionModel, SpanType, SpanWrapper, UsageModel
 from .tracer import Tracer
 
 # Package-level logger. Attach NullHandler by default so library does not emit logs
@@ -183,11 +183,12 @@ class Netra:
             session_id: Session identifier
         """
         if not isinstance(session_id, str):
-            raise TypeError(f"session_id must be a string, got {type(session_id)}")
+            logger.error(f"set_session_id: session_id must be a string, got {type(session_id)}")
+            return
         if session_id:
             SessionManager.set_session_context("session_id", session_id)
         else:
-            logger.warning("Session ID must be provided for setting session_id.")
+            logger.warning("set_session_id: Session ID must be provided for setting session_id.")
 
     @classmethod
     def set_user_id(cls, user_id: str) -> None:
@@ -198,11 +199,12 @@ class Netra:
             user_id: User identifier
         """
         if not isinstance(user_id, str):
-            raise TypeError(f"user_id must be a string, got {type(user_id)}")
+            logger.error(f"set_user_id: user_id must be a string, got {type(user_id)}")
+            return
         if user_id:
             SessionManager.set_session_context("user_id", user_id)
         else:
-            logger.warning("User ID must be provided for setting user_id.")
+            logger.warning("set_user_id: User ID must be provided for setting user_id.")
 
     @classmethod
     def set_tenant_id(cls, tenant_id: str) -> None:
@@ -213,11 +215,12 @@ class Netra:
             user_account_id: User account identifier
         """
         if not isinstance(tenant_id, str):
-            raise TypeError(f"tenant_id must be a string, got {type(tenant_id)}")
+            logger.error(f"set_tenant_id: tenant_id must be a string, got {type(tenant_id)}")
+            return
         if tenant_id:
             SessionManager.set_session_context("tenant_id", tenant_id)
         else:
-            logger.warning("Tenant ID must be provided for setting tenant_id.")
+            logger.warning("set_tenant_id: Tenant ID must be provided for setting tenant_id.")
 
     @classmethod
     def set_custom_attributes(cls, key: str, value: Any) -> None:
@@ -263,11 +266,12 @@ class Netra:
         name: str,
         attributes: Optional[Dict[str, str]] = None,
         module_name: str = "combat_sdk",
+        as_type: Optional[SpanType] = SpanType.SPAN,
     ) -> SpanWrapper:
         """
         Start a new session.
         """
-        return SpanWrapper(name, attributes, module_name)
+        return SpanWrapper(name, attributes, module_name, as_type=as_type)
 
 
-__all__ = ["Netra", "UsageModel", "ActionModel"]
+__all__ = ["Netra", "UsageModel", "ActionModel", "SpanType"]

{netra_sdk-0.1.45 → netra_sdk-0.1.47}/netra/config.py

@@ -30,7 +30,7 @@ class Config:
     # Maximum length for any attribute value (strings and bytes). Processors should honor this.
     ATTRIBUTE_MAX_LEN = 2000
     # Maximum length specifically for conversation entry content (strings or JSON when serialized)
-    CONVERSATION_CONTENT_MAX_LEN = 1000
+    CONVERSATION_CONTENT_MAX_LEN = 2000
 
     def __init__(
         self,

{netra_sdk-0.1.45 → netra_sdk-0.1.47}/netra/decorators.py

@@ -33,6 +33,7 @@ from opentelemetry import trace
 
 from .config import Config
 from .session_manager import SessionManager
+from .span_wrapper import SpanType
 
 logger = logging.getLogger(__name__)
 
@@ -262,7 +263,12 @@ def _wrap_streaming_response_with_span(
     return resp
 
 
-def _create_function_wrapper(func: Callable[P, R], entity_type: str, name: Optional[str] = None) -> Callable[P, R]:
+def _create_function_wrapper(
+    func: Callable[P, R],
+    entity_type: str,
+    name: Optional[str] = None,
+    as_type: Optional[SpanType] = SpanType.SPAN,
+) -> Callable[P, R]:
     module_name = func.__name__
     is_async = inspect.iscoroutinefunction(func)
     span_name = name if name is not None else func.__name__
@@ -276,6 +282,15 @@ def _create_function_wrapper(func: Callable[P, R], entity_type: str, name: Optio
 
             tracer = trace.get_tracer(module_name)
             span = tracer.start_span(span_name)
+            # Set span type if provided
+
+            if not isinstance(as_type, SpanType):
+                logger.error("Invalid span type: %s", as_type)
+                return
+            try:
+                span.set_attribute("netra.span.type", as_type.value)
+            except Exception:
+                pass
             # Register and activate span
             try:
                 SessionManager.register_span(span_name, span)
@@ -327,6 +342,15 @@ def _create_function_wrapper(func: Callable[P, R], entity_type: str, name: Optio
 
             tracer = trace.get_tracer(module_name)
             span = tracer.start_span(span_name)
+            # Set span type if provided
+            if as_type is not None:
+                if not isinstance(as_type, SpanType):
+                    logger.error("Invalid span type: %s", as_type)
+                    return
+                try:
+                    span.set_attribute("netra.span.type", as_type.value)
+                except Exception:
+                    pass
             # Register and activate span
             try:
                 SessionManager.register_span(span_name, span)
@@ -370,7 +394,12 @@ def _create_function_wrapper(func: Callable[P, R], entity_type: str, name: Optio
         return cast(Callable[P, R], sync_wrapper)
 
 
-def _wrap_class_methods(cls: C, entity_type: str, name: Optional[str] = None) -> C:
+def _wrap_class_methods(
+    cls: C,
+    entity_type: str,
+    name: Optional[str] = None,
+    as_type: Optional[SpanType] = SpanType.SPAN,
+) -> C:
     class_name = name if name is not None else cls.__name__
     for attr_name in cls.__dict__:
         attr = getattr(cls, attr_name)
@@ -378,7 +407,7 @@ def _wrap_class_methods(cls: C, entity_type: str, name: Optional[str] = None) ->
             continue
         if callable(attr) and inspect.isfunction(attr):
             method_span_name = f"{class_name}.{attr_name}"
-            wrapped_method = _create_function_wrapper(attr, entity_type, method_span_name)
+            wrapped_method = _create_function_wrapper(attr, entity_type, method_span_name, as_type=as_type)
             setattr(cls, attr_name, wrapped_method)
     return cls
 
@@ -416,10 +445,10 @@ def task(
 ) -> Union[Callable[P, R], C, Callable[[Callable[P, R]], Callable[P, R]]]:
     def decorator(obj: Union[Callable[P, R], C]) -> Union[Callable[P, R], C]:
         if inspect.isclass(obj):
-            return _wrap_class_methods(cast(C, obj), "task", name)
+            return _wrap_class_methods(cast(C, obj), "task", name, as_type=SpanType.TOOL)
         else:
             # When obj is a function, it should be type Callable[P, R]
-            return _create_function_wrapper(cast(Callable[P, R], obj), "task", name)
+            return _create_function_wrapper(cast(Callable[P, R], obj), "task", name, as_type=SpanType.TOOL)
 
     if target is not None:
         return decorator(target)
@@ -427,14 +456,17 @@ def task(
 
 
 def span(
-    target: Union[Callable[P, R], C, None] = None, *, name: Optional[str] = None
+    target: Union[Callable[P, R], C, None] = None,
+    *,
+    name: Optional[str] = None,
+    as_type: Optional[SpanType] = SpanType.SPAN,
 ) -> Union[Callable[P, R], C, Callable[[Callable[P, R]], Callable[P, R]]]:
     def decorator(obj: Union[Callable[P, R], C]) -> Union[Callable[P, R], C]:
         if inspect.isclass(obj):
-            return _wrap_class_methods(cast(C, obj), "span", name)
+            return _wrap_class_methods(cast(C, obj), "span", name, as_type=as_type)
         else:
             # When obj is a function, it should be type Callable[P, R]
-            return _create_function_wrapper(cast(Callable[P, R], obj), "span", name)
+            return _create_function_wrapper(cast(Callable[P, R], obj), "span", name, as_type=as_type)
 
     if target is not None:
         return decorator(target)

{netra_sdk-0.1.45 → netra_sdk-0.1.47}/netra/processors/instrumentation_span_processor.py

@@ -74,9 +74,6 @@ class InstrumentationSpanProcessor(SpanProcessor):  # type: ignore[misc]
                     truncated = self._truncate_value(value)
                     # Forward to original
                     original_set_attribute(key, truncated)
-                    # Special rule: if model key set, mark span as llm
-                    if key == "gen_ai.request.model":
-                        original_set_attribute(f"{Config.LIBRARY_NAME}.span.type", "llm")
                 except Exception:
                     # Best-effort; never break span
                     try:

{netra_sdk-0.1.45 → netra_sdk-0.1.47}/netra/session_manager.py

@@ -275,20 +275,27 @@ class SessionManager:
 
         # Hard runtime validation of input types and values
         if not isinstance(conversation_type, ConversationType):
-            raise TypeError("conversation_type must be a ConversationType enum value (input, output, system)")
+            logger.error(
+                "add_conversation: conversation_type must be a ConversationType enum value (input, output, system)"
+            )
+            return
         normalized_type = conversation_type.value
 
         if not isinstance(role, str):
-            raise TypeError(f"role must be a string, got {type(role)}")
+            logger.error("add_conversation: role must be a string")
+            return
 
         if not isinstance(content, (str, dict)):
-            raise TypeError(f"content must be a string or dict, got {type(content)}")
+            logger.error("add_conversation: content must be a string or dict")
+            return
 
         if not role:
-            raise ValueError("role must be a non-empty string")
+            logger.error("add_conversation: role must be a non-empty string")
+            return
 
         if not content:
-            raise ValueError("content must not be empty")
+            logger.error("add_conversation: content must not be empty")
+            return
 
         try:
 

{netra_sdk-0.1.45 → netra_sdk-0.1.47}/netra/span_wrapper.py

@@ -2,6 +2,7 @@ import json
 import logging
 import time
 from datetime import datetime
+from enum import Enum
 from typing import Any, Dict, List, Literal, Optional
 
 from opentelemetry import baggage
@@ -49,6 +50,13 @@ class ATTRIBUTE:
     ACTION = "action"
 
 
+class SpanType(str, Enum):
+    SPAN = "SPAN"
+    GENERATION = "GENERATION"
+    TOOL = "TOOL"
+    EMBEDDING = "EMBEDDING"
+
+
 class SpanWrapper:
     """
     Context manager for tracking observability data for external API calls.
@@ -63,9 +71,16 @@ class SpanWrapper:
             span.set_usage(usage_data)
     """
 
-    def __init__(self, name: str, attributes: Optional[Dict[str, str]] = None, module_name: str = "combat_sdk"):
+    def __init__(
+        self,
+        name: str,
+        attributes: Optional[Dict[str, str]] = None,
+        module_name: str = "combat_sdk",
+        as_type: Optional[SpanType] = SpanType.SPAN,
+    ):
         self.name = name
         self.attributes = attributes or {}
+
         self.start_time: Optional[float] = None
         self.end_time: Optional[float] = None
         self.status = "pending"
@@ -80,6 +95,12 @@ class SpanWrapper:
         # Token for locally attached baggage (if any)
         self._local_block_token: Optional[object] = None
 
+        if isinstance(as_type, SpanType):
+            self.attributes["netra.span.type"] = as_type.value
+        else:
+            logger.error("Invalid span type: %s", as_type)
+            return
+
     def __enter__(self) -> "SpanWrapper":
         """Start the span wrapper, begin time tracking, and create OpenTelemetry span."""
         self.start_time = time.time()

netra_sdk-0.1.47/netra/tracer.py

@@ -0,0 +1,134 @@
+"""Netra OpenTelemetry tracer configuration module.
+
+This module handles the initialization and configuration of OpenTelemetry tracing,
+including exporter setup and span processor configuration.
+"""
+
+import logging
+import threading
+from typing import Any, Dict
+
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk import trace as sdk_trace
+from opentelemetry.sdk.resources import DEPLOYMENT_ENVIRONMENT, SERVICE_NAME, Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import (
+    BatchSpanProcessor,
+    ConsoleSpanExporter,
+    SimpleSpanProcessor,
+)
+
+from netra.config import Config
+from netra.exporters import FilteringSpanExporter
+
+logger = logging.getLogger(__name__)
+
+_provider_install_lock = threading.Lock()
+
+
+class Tracer:
+    """
+    Configures Netra's OpenTelemetry tracer with OTLP exporter (or Console exporter as fallback)
+    and appropriate span processor.
+    """
+
+    def __init__(self, cfg: Config) -> None:
+        """Initialize the Netra tracer with the provided configuration.
+
+        Args:
+            cfg: Configuration object with tracer settings
+        """
+        self.cfg = cfg
+        self._setup_tracer()
+
+    def _setup_tracer(self) -> None:
+        """Set up the OpenTelemetry tracer with appropriate exporters and processors.
+
+        Creates a resource with service name and custom attributes,
+        configures the appropriate exporter (OTLP or Console fallback),
+        and sets up either a batch or simple span processor based on configuration.
+        """
+        # Create Resource with service.name + custom attributes
+        resource_attrs: Dict[str, Any] = {
+            SERVICE_NAME: self.cfg.app_name,
+            DEPLOYMENT_ENVIRONMENT: self.cfg.environment,
+        }
+        if self.cfg.resource_attributes:
+            resource_attrs.update(self.cfg.resource_attributes)
+        resource = Resource(attributes=resource_attrs)
+
+        # Build TracerProvider
+        current_provider = trace.get_tracer_provider()
+        if isinstance(current_provider, sdk_trace.TracerProvider):
+            provider = current_provider
+            logger.info("Reusing existing TracerProvider. Possible loss of Resource attributes")
+        else:
+            provider = TracerProvider(resource=resource)
+            trace.set_tracer_provider(provider)
+            logger.info("Using Netra TracerProvider")
+
+        with _provider_install_lock:
+            if getattr(provider, "_netra_processors_installed", False):
+                logger.info("Netra processors already installed on provider; skipping setup")
+                return
+
+            if not self.cfg.otlp_endpoint:
+                logger.warning("OTLP endpoint not provided, falling back to console exporter")
+                exporter = ConsoleSpanExporter()
+            else:
+                exporter = OTLPSpanExporter(
+                    endpoint=self._format_endpoint(self.cfg.otlp_endpoint),
+                    headers=self.cfg.headers,
+                )
+            original_exporter = exporter
+            try:
+                patterns = getattr(self.cfg, "blocked_spans", None) or []
+                exporter = FilteringSpanExporter(exporter, patterns)
+                if patterns:
+                    logger.info("Enabled FilteringSpanExporter with %d global pattern(s)", len(patterns))
+                else:
+                    logger.info("Enabled FilteringSpanExporter with local-only rules")
+            except (ValueError, TypeError) as e:
+                logger.warning("Failed to enable FilteringSpanExporter: %s; using unwrapped exporter", e)
+                exporter = original_exporter
+
+            from netra.processors import (
+                InstrumentationSpanProcessor,
+                LocalFilteringSpanProcessor,
+                ScrubbingSpanProcessor,
+                SessionSpanProcessor,
+            )
+
+            provider.add_span_processor(LocalFilteringSpanProcessor())
+            provider.add_span_processor(InstrumentationSpanProcessor())
+            provider.add_span_processor(SessionSpanProcessor())
+
+            if self.cfg.enable_scrubbing:
+                provider.add_span_processor(ScrubbingSpanProcessor())  # type: ignore[no-untyped-call]
+
+            if self.cfg.disable_batch:
+                provider.add_span_processor(SimpleSpanProcessor(exporter))
+            else:
+                provider.add_span_processor(BatchSpanProcessor(exporter))
+
+            setattr(provider, "_netra_processors_installed", True)
+
+            logger.info(
+                "Netra initialized: endpoint=%s, disable_batch=%s",
+                self.cfg.otlp_endpoint,
+                self.cfg.disable_batch,
+            )
+
+    def _format_endpoint(self, endpoint: str) -> str:
+        """Format the OTLP endpoint URL to ensure it ends with '/v1/traces'.
+
+        Args:
+            endpoint: Base OTLP endpoint URL
+
+        Returns:
+            Properly formatted endpoint URL
+        """
+        if not endpoint.endswith("/v1/traces"):
+            return endpoint.rstrip("/") + "/v1/traces"
+        return endpoint

netra_sdk-0.1.47/netra/version.py

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

{netra_sdk-0.1.45 → netra_sdk-0.1.47}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "netra-sdk"
-version = "0.1.45"
+version = "0.1.47"
 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.45/netra/tracer.py

@@ -1,121 +0,0 @@
-"""Netra OpenTelemetry tracer configuration module.
-
-This module handles the initialization and configuration of OpenTelemetry tracing,
-including exporter setup and span processor configuration.
-"""
-
-import logging
-from typing import Any, Dict
-
-from opentelemetry import trace
-from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
-from opentelemetry.sdk.resources import DEPLOYMENT_ENVIRONMENT, SERVICE_NAME, Resource
-from opentelemetry.sdk.trace import TracerProvider
-from opentelemetry.sdk.trace.export import (
-    BatchSpanProcessor,
-    ConsoleSpanExporter,
-    SimpleSpanProcessor,
-)
-
-from netra.config import Config
-from netra.exporters import FilteringSpanExporter
-
-logger = logging.getLogger(__name__)
-
-
-class Tracer:
-    """
-    Configures Netra's OpenTelemetry tracer with OTLP exporter (or Console exporter as fallback)
-    and appropriate span processor.
-    """
-
-    def __init__(self, cfg: Config) -> None:
-        """Initialize the Netra tracer with the provided configuration.
-
-        Args:
-            cfg: Configuration object with tracer settings
-        """
-        self.cfg = cfg
-        self._setup_tracer()
-
-    def _setup_tracer(self) -> None:
-        """Set up the OpenTelemetry tracer with appropriate exporters and processors.
-
-        Creates a resource with service name and custom attributes,
-        configures the appropriate exporter (OTLP or Console fallback),
-        and sets up either a batch or simple span processor based on configuration.
-        """
-        # Create Resource with service.name + custom attributes
-        resource_attrs: Dict[str, Any] = {
-            SERVICE_NAME: self.cfg.app_name,
-            DEPLOYMENT_ENVIRONMENT: self.cfg.environment,
-        }
-        if self.cfg.resource_attributes:
-            resource_attrs.update(self.cfg.resource_attributes)
-        resource = Resource(attributes=resource_attrs)
-
-        # Build TracerProvider
-        provider = TracerProvider(resource=resource)
-
-        # Configure exporter based on configuration
-        if not self.cfg.otlp_endpoint:
-            logger.warning("OTLP endpoint not provided, falling back to console exporter")
-            exporter = ConsoleSpanExporter()
-        else:
-            exporter = OTLPSpanExporter(
-                endpoint=self._format_endpoint(self.cfg.otlp_endpoint),
-                headers=self.cfg.headers,
-            )
-        # Wrap exporter with filtering to support both global and local (baggage-based) rules
-        try:
-            patterns = getattr(self.cfg, "blocked_spans", None) or []
-            exporter = FilteringSpanExporter(exporter, patterns)
-            if patterns:
-                logger.info("Enabled FilteringSpanExporter with %d global pattern(s)", len(patterns))
-            else:
-                logger.info("Enabled FilteringSpanExporter with local-only rules")
-        except Exception as e:
-            logger.warning("Failed to enable FilteringSpanExporter: %s", e)
-        # Add span processors: first instrumentation wrapper, then session processor
-        from netra.processors import (
-            InstrumentationSpanProcessor,
-            LocalFilteringSpanProcessor,
-            ScrubbingSpanProcessor,
-            SessionSpanProcessor,
-        )
-
-        # Apply local filtering propagation first so later processors and spans see attributes
-        provider.add_span_processor(LocalFilteringSpanProcessor())
-        provider.add_span_processor(InstrumentationSpanProcessor())
-        provider.add_span_processor(SessionSpanProcessor())
-
-        # Add scrubbing processor if enabled
-        if self.cfg.enable_scrubbing:
-            provider.add_span_processor(ScrubbingSpanProcessor())  # type: ignore[no-untyped-call]
-
-        # Install appropriate span processor
-        if self.cfg.disable_batch:
-            provider.add_span_processor(SimpleSpanProcessor(exporter))
-        else:
-            provider.add_span_processor(BatchSpanProcessor(exporter))
-
-        # Set global tracer provider
-        trace.set_tracer_provider(provider)
-        logger.info(
-            "Netra TracerProvider initialized: endpoint=%s, disable_batch=%s",
-            self.cfg.otlp_endpoint,
-            self.cfg.disable_batch,
-        )
-
-    def _format_endpoint(self, endpoint: str) -> str:
-        """Format the OTLP endpoint URL to ensure it ends with '/v1/traces'.
-
-        Args:
-            endpoint: Base OTLP endpoint URL
-
-        Returns:
-            Properly formatted endpoint URL
-        """
-        if not endpoint.endswith("/v1/traces"):
-            return endpoint.rstrip("/") + "/v1/traces"
-        return endpoint

netra_sdk-0.1.45/netra/version.py

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