netra-sdk 0.1.25__py3-none-any.whl → 0.1.28__py3-none-any.whl

netra/__init__.py

@@ -12,7 +12,10 @@ from .session_manager import SessionManager
 from .span_wrapper import ActionModel, SpanWrapper, UsageModel
 from .tracer import Tracer
 
+# Package-level logger. Attach NullHandler by default so library does not emit logs
+# unless explicitly enabled by the user via debug_mode.
 logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
 
 
 class Netra:
@@ -42,6 +45,7 @@ class Netra:
         headers: Optional[str] = None,
         disable_batch: Optional[bool] = None,
         trace_content: Optional[bool] = None,
+        debug_mode: Optional[bool] = None,
         resource_attributes: Optional[Dict[str, Any]] = None,
         environment: Optional[str] = None,
         instruments: Optional[Set[NetraInstruments]] = None,
@@ -61,10 +65,31 @@ class Netra:
                 headers=headers,
                 disable_batch=disable_batch,
                 trace_content=trace_content,
+                debug_mode=debug_mode,
                 resource_attributes=resource_attributes,
                 environment=environment,
             )
 
+            # Configure package logging based on debug mode
+            pkg_logger = logging.getLogger("netra")
+            # Prevent propagating to root to avoid duplicate logs
+            pkg_logger.propagate = False
+            # Clear existing handlers to avoid duplicates across repeated init attempts
+            pkg_logger.handlers.clear()
+            if cfg.debug_mode:
+                pkg_logger.setLevel(logging.DEBUG)
+                handler = logging.StreamHandler()
+                formatter = logging.Formatter(
+                    fmt="%(asctime)s | %(levelname)s | %(name)s | %(message)s",
+                    datefmt="%Y-%m-%d %H:%M:%S",
+                )
+                handler.setFormatter(formatter)
+                pkg_logger.addHandler(handler)
+            else:
+                # Silence SDK logs entirely unless debug is enabled
+                pkg_logger.setLevel(logging.CRITICAL)
+                pkg_logger.addHandler(logging.NullHandler())
+
             # Initialize tracer (OTLP exporter, span processor, resource)
             Tracer(cfg)
 
@@ -89,6 +114,8 @@ class Netra:
         Args:
             session_id: Session identifier
         """
+        if not isinstance(session_id, str):
+            raise TypeError(f"session_id must be a string, got {type(session_id)}")
         if session_id:
             SessionManager.set_session_context("session_id", session_id)
         else:
@@ -102,6 +129,8 @@ class Netra:
         Args:
             user_id: User identifier
         """
+        if not isinstance(user_id, str):
+            raise TypeError(f"user_id must be a string, got {type(user_id)}")
         if user_id:
             SessionManager.set_session_context("user_id", user_id)
         else:
@@ -115,6 +144,8 @@ class Netra:
         Args:
             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)}")
         if tenant_id:
             SessionManager.set_session_context("tenant_id", tenant_id)
         else:

netra/config.py

@@ -16,6 +16,7 @@ class Config:
       - headers:                 Additional headers (W3C Correlation-Context format)
       - disable_batch:           Whether to disable batch span processor (bool)
       - trace_content:           Whether to capture prompt/completion content (bool)
+      - debug_mode:              Whether to enable SDK logging; default False (bool)
       - resource_attributes:     Custom resource attributes dict (e.g., {'env': 'prod', 'version': '1.0.0'})
     """
 
@@ -30,6 +31,7 @@ class Config:
         headers: Optional[str] = None,
         disable_batch: Optional[bool] = None,
         trace_content: Optional[bool] = None,
+        debug_mode: Optional[bool] = None,
         resource_attributes: Optional[Dict[str, Any]] = None,
         environment: Optional[str] = None,
     ):
@@ -91,6 +93,13 @@ class Config:
         else:
             os.environ["TRACELOOP_TRACE_CONTENT"] = "true"
 
+        # Debug mode: enable SDK logging only when True. Default False.
+        if debug_mode is not None:
+            self.debug_mode = debug_mode
+        else:
+            env_dbg = os.getenv("NETRA_DEBUG")
+            self.debug_mode = True if (env_dbg is not None and env_dbg.lower() in ("1", "true")) else False
+
         # 7. Environment: param override, else env
         if environment is not None:
             self.environment = environment

netra/decorators.py

@@ -176,3 +176,18 @@ def task(
     if target is not None:
         return decorator(target)
     return decorator
+
+
+def span(
+    target: Union[Callable[P, R], C, None] = None, *, name: Optional[str] = None
+) -> 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)
+        else:
+            # When obj is a function, it should be type Callable[P, R]
+            return _create_function_wrapper(cast(Callable[P, R], obj), "span", name)
+
+    if target is not None:
+        return decorator(target)
+    return decorator

netra/session_manager.py

@@ -26,6 +26,7 @@ class SessionManager:
     _workflow_stack: List[str] = []
     _task_stack: List[str] = []
     _agent_stack: List[str] = []
+    _span_stack: List[str] = []
 
     @classmethod
     def set_current_span(cls, span: Optional[trace.Span]) -> None:
@@ -53,7 +54,7 @@ class SessionManager:
         Push an entity onto the appropriate entity stack.
 
         Args:
-            entity_type: Type of entity (workflow, task, agent)
+            entity_type: Type of entity (workflow, task, agent, span)
             entity_name: Name of the entity
         """
         if entity_type == "workflow":
@@ -62,6 +63,8 @@ class SessionManager:
             cls._task_stack.append(entity_name)
         elif entity_type == "agent":
             cls._agent_stack.append(entity_name)
+        elif entity_type == "span":
+            cls._span_stack.append(entity_name)
 
     @classmethod
     def pop_entity(cls, entity_type: str) -> Optional[str]:
@@ -69,7 +72,7 @@ class SessionManager:
         Pop the most recent entity from the specified entity stack.
 
         Args:
-            entity_type: Type of entity (workflow, task, agent)
+            entity_type: Type of entity (workflow, task, agent, span)
 
         Returns:
             Entity name or None if stack is empty
@@ -80,6 +83,8 @@ class SessionManager:
             return cls._task_stack.pop()
         elif entity_type == "agent" and cls._agent_stack:
             return cls._agent_stack.pop()
+        elif entity_type == "span" and cls._span_stack:
+            return cls._span_stack.pop()
         return None
 
     @classmethod
@@ -104,6 +109,10 @@ class SessionManager:
         if cls._agent_stack:
             attributes[f"{Config.LIBRARY_NAME}.agent.name"] = cls._agent_stack[-1]
 
+        # Add current span if exists
+        if cls._span_stack:
+            attributes[f"{Config.LIBRARY_NAME}.span.name"] = cls._span_stack[-1]
+
         return attributes
 
     @classmethod
@@ -112,6 +121,7 @@ class SessionManager:
         cls._workflow_stack.clear()
         cls._task_stack.clear()
         cls._agent_stack.clear()
+        cls._span_stack.clear()
 
     @classmethod
     def get_stack_info(cls) -> Dict[str, List[str]]:
@@ -125,6 +135,7 @@ class SessionManager:
             "workflows": cls._workflow_stack.copy(),
             "tasks": cls._task_stack.copy(),
             "agents": cls._agent_stack.copy(),
+            "spans": cls._span_stack.copy(),
         }
 
     @staticmethod

netra/version.py

@@ -1 +1 @@
-__version__ = "0.1.25"
+__version__ = "0.1.28"

{netra_sdk-0.1.25.dist-info → netra_sdk-0.1.28.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: netra-sdk
-Version: 0.1.25
+Version: 0.1.28
 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
@@ -72,7 +72,6 @@ Requires-Dist: presidio-anonymizer (==2.2.358) ; extra == "presidio"
 Requires-Dist: stanza (>=1.10.1,<2.0.0) ; extra == "presidio"
 Requires-Dist: traceloop-sdk (>=0.40.7,<0.43.0)
 Requires-Dist: transformers (==4.51.3) ; extra == "presidio"
-Requires-Dist: twine (>=6.1.0,<7.0.0)
 Project-URL: Bug Tracker, https://github.com/KeyValueSoftwareSystems/netra-sdk-py/issues
 Project-URL: Documentation, https://github.com/KeyValueSoftwareSystems/netra-sdk-py/blob/main/README.md
 Project-URL: Homepage, https://github.com/KeyValueSoftwareSystems/netra-sdk-py
@@ -174,7 +173,7 @@ Netra.init(
 Use decorators to automatically trace your functions and classes:
 
 ```python
-from netra.decorators import workflow, agent, task
+from netra.decorators import workflow, agent, task, span
 
 @workflow
 def data_processing_workflow(data):
@@ -192,6 +191,11 @@ def data_validation_task(data):
     """Task for validating input data"""
     return validate_schema(data)
 
+@span
+def data_processing_span(data):
+    """Span for processing data"""
+    return process_data(data)
+
 # Works with async functions too
 @workflow(name="Async Data Pipeline")
 async def async_workflow(data):
@@ -206,6 +210,16 @@ class CustomerSupportAgent:
 
     def escalate_issue(self, issue):
         return self.forward_to_human(issue)
+
+@task
+async def async_task(data):
+    """Task for processing data"""
+    return await process_data_async(data)
+
+@span
+async def async_span(data):
+    """Span for processing data"""
+    return await process_data_async(data)
 ```
 
 ## 🔍 Supported Instrumentations

{netra_sdk-0.1.25.dist-info → netra_sdk-0.1.28.dist-info}/RECORD

@@ -1,10 +1,10 @@
-netra/__init__.py,sha256=49R2bZrVu30HhpE3gfpu0b5C5cNovC6WyNyUwHCOfQ8,5392
+netra/__init__.py,sha256=hboj9svp8pHeMk59ifwyNgXNElaHvTEpUKhjD1-1azU,6997
 netra/anonymizer/__init__.py,sha256=KeGPPZqKVZbtkbirEKYTYhj6aZHlakjdQhD7QHqBRio,133
 netra/anonymizer/anonymizer.py,sha256=IcrYkdwWrFauGWUeAW-0RwrSUM8VSZCFNtoywZhvIqU,3778
 netra/anonymizer/base.py,sha256=ytPxHCUD2OXlEY6fNTuMmwImNdIjgj294I41FIgoXpU,5946
 netra/anonymizer/fp_anonymizer.py,sha256=_6svIYmE0eejdIMkhKBUWCNjGtGimtrGtbLvPSOp8W4,6493
-netra/config.py,sha256=S9GsCvwtakrmryAaV-AhyVB_wAQ6tjwPLLZQemLgXko,5006
-netra/decorators.py,sha256=V_WpZ2IgW2Y7B_WnSXmKUGGhkM5Cra2TwONddmJpPaI,6837
+netra/config.py,sha256=MiJXqQ1GntU9U4MyzZnQ38Lma0EE96Tx1l5wH3rTrus,5452
+netra/decorators.py,sha256=TqORBs0Xv_CZHOAwrWkpvscMj4FgOJsgo1CRYoG6C7Y,7435
 netra/exceptions/__init__.py,sha256=uDgcBxmC4WhdS7HRYQk_TtJyxH1s1o6wZmcsnSHLAcM,174
 netra/exceptions/injection.py,sha256=ke4eUXRYUFJkMZgdSyPPkPt5PdxToTI6xLEBI0hTWUQ,1332
 netra/exceptions/pii.py,sha256=MT4p_x-zH3VtYudTSxw1Z9qQZADJDspq64WrYqSWlZc,2438
@@ -40,11 +40,11 @@ netra/pii.py,sha256=Rn4SjgTJW_aw9LcbjLuMqF3fKd9b1ndlYt1CaK51Ge0,33125
 netra/processors/__init__.py,sha256=wfnSskRBtMT90hO7LqFJoEW374LgoH_gnTxhynqtByI,109
 netra/processors/session_span_processor.py,sha256=qcsBl-LnILWefsftI8NQhXDGb94OWPc8LvzhVA0JS_c,2432
 netra/scanner.py,sha256=kyDpeZiscCPb6pjuhS-sfsVj-dviBFRepdUWh0sLoEY,11554
-netra/session_manager.py,sha256=EVcnWcSj4NdkH--HmqHx0mmzivQiM4GCyFLu6lwi33M,6252
+netra/session_manager.py,sha256=Ks8A6B9RYe0tV8PeWYuN0M-UMZqa47uquuw6D7C1vCE,6701
 netra/span_wrapper.py,sha256=ec2WLYTRLZ02WSSCYEsMn1PgUGVji9rFyq_CRCV9rog,7388
 netra/tracer.py,sha256=In5QPVLz_6BxrolWpav9EuR9_hirD2UUIlyY75QUaKk,3450
-netra/version.py,sha256=Ej7LsXg-6CASlaEHsZkUoLDpYEfHeFKdIeXMIM0esgA,23
-netra_sdk-0.1.25.dist-info/LICENCE,sha256=8B_UoZ-BAl0AqiHAHUETCgd3I2B9yYJ1WEQtVb_qFMA,11359
-netra_sdk-0.1.25.dist-info/METADATA,sha256=AnDcjfLzY00vGhSd_3kOjoVPK9W15JqeVPj2LyIYn7A,27855
-netra_sdk-0.1.25.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-netra_sdk-0.1.25.dist-info/RECORD,,
+netra/version.py,sha256=MWZDdAHrdUZS0c3VlLqX4O1eaxPodI7irMtEvknKQ94,23
+netra_sdk-0.1.28.dist-info/LICENCE,sha256=8B_UoZ-BAl0AqiHAHUETCgd3I2B9yYJ1WEQtVb_qFMA,11359
+netra_sdk-0.1.28.dist-info/METADATA,sha256=T63YlGVzQCx6cxKp8fXMK136IYwpcFC5VOUeLTKg_8E,28151
+netra_sdk-0.1.28.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+netra_sdk-0.1.28.dist-info/RECORD,,