netra-sdk 0.1.4__tar.gz → 0.1.6__tar.gz

{netra_sdk-0.1.4 → netra_sdk-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: netra-sdk
-Version: 0.1.4
+Version: 0.1.6
 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
@@ -407,28 +407,38 @@ Netra.set_custom_event(event_name="conversion", attributes={
 Use the custom session tracking utility to track external API calls with detailed observability:
 
 ```python
-from netra import Netra
-
-# Initialize SDK
-Netra.init(app_name="My App")
-
-# Use session context manager for tracking API calls
-with Netra.start_session("video_generation_task") as session:
-    # Set attributes before the API call
-    session.set_prompt("A cat playing piano")
-    session.set_image_height("1024")
-    session.set_image_width("1024")
-    session.set_model("stable-diffusion-xl")
-
-    # Make your external API call
-    result = external_api.generate_video(...)
-
-    # Set post-call attributes
-    session.set_tokens("1250")
-    session.set_credits("30")
-    session.set_cost("0.15")
-
-    # Add events during session
+from netra import Netra, Session
+from netra.session import UsageModel
+
+# Start a new session
+with Netra.start_session("image_generation") as session:
+    # Set session attributes
+    session.set_prompt("A beautiful sunset over mountains")
+    session.set_negative_prompt("blurry, low quality")
+    session.set_height("1024")
+    session.set_width("1024")
+    session.set_model("dall-e-3")
+    session.set_llm_system("openai")
+
+    # Set usage data with UsageModel
+    usage_data = [
+        UsageModel(
+            model="dall-e-3",
+            type="image_generation",
+            unit_used=1,
+            cost_in_usd=0.02
+        )
+    ]
+    session.set_usage(usage_data)
+
+    # Your API calls here
+    # ...
+
+    # Set custom attributes
+    session.set_attribute("custom_key", "custom_value")
+
+    # Add events
+    session.add_event("generation_started", {"step": 1, "status": "processing"})
     session.add_event("processing_completed", {"step": "rendering"})
 
 # Session automatically captures duration, status, and any errors
@@ -662,42 +672,7 @@ pre-commit install --hook-type pre-push
 
 ## 🤝 Contributing
 
-We welcome contributions! Please follow these guidelines:
-
-### Commit Message Format
-
-We use [Conventional Commits](https://www.conventionalcommits.org/) for commit messages:
-
-```
-<type>[optional scope]: <description>
-
-[optional body]
-
-[optional footer(s)]
-```
-
-**Types:**
-- **feat**: A new feature
-- **fix**: A bug fix
-- **docs**: Documentation only changes
-- **style**: Changes that do not affect the meaning of the code
-- **refactor**: A code change that neither fixes a bug nor adds a feature
-- **perf**: A code change that improves performance
-- **test**: Adding missing tests or correcting existing tests
-- **chore**: Changes to the build process or auxiliary tools
-
-**Examples:**
-```
-feat: add support for Claude AI instrumentation
-fix(pii): resolve masking issue with nested objects
-docs: update installation instructions
-```
-
-**Scope** can be used to specify the area of change (e.g., `pii`, `instrumentation`, `decorators`).
-
-**Body** should include the motivation for the change and contrast with previous behavior.
-
-**Footer** can be used for "BREAKING CHANGE:" or issue references.
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for detailed information on how to contribute to the project, including development setup, testing, and our commit message format.
 
 ---
 

{netra_sdk-0.1.4 → netra_sdk-0.1.6}/README.md

@@ -331,28 +331,38 @@ Netra.set_custom_event(event_name="conversion", attributes={
 Use the custom session tracking utility to track external API calls with detailed observability:
 
 ```python
-from netra import Netra
-
-# Initialize SDK
-Netra.init(app_name="My App")
-
-# Use session context manager for tracking API calls
-with Netra.start_session("video_generation_task") as session:
-    # Set attributes before the API call
-    session.set_prompt("A cat playing piano")
-    session.set_image_height("1024")
-    session.set_image_width("1024")
-    session.set_model("stable-diffusion-xl")
-
-    # Make your external API call
-    result = external_api.generate_video(...)
-
-    # Set post-call attributes
-    session.set_tokens("1250")
-    session.set_credits("30")
-    session.set_cost("0.15")
-
-    # Add events during session
+from netra import Netra, Session
+from netra.session import UsageModel
+
+# Start a new session
+with Netra.start_session("image_generation") as session:
+    # Set session attributes
+    session.set_prompt("A beautiful sunset over mountains")
+    session.set_negative_prompt("blurry, low quality")
+    session.set_height("1024")
+    session.set_width("1024")
+    session.set_model("dall-e-3")
+    session.set_llm_system("openai")
+
+    # Set usage data with UsageModel
+    usage_data = [
+        UsageModel(
+            model="dall-e-3",
+            type="image_generation",
+            unit_used=1,
+            cost_in_usd=0.02
+        )
+    ]
+    session.set_usage(usage_data)
+
+    # Your API calls here
+    # ...
+
+    # Set custom attributes
+    session.set_attribute("custom_key", "custom_value")
+
+    # Add events
+    session.add_event("generation_started", {"step": 1, "status": "processing"})
     session.add_event("processing_completed", {"step": "rendering"})
 
 # Session automatically captures duration, status, and any errors
@@ -586,41 +596,6 @@ pre-commit install --hook-type pre-push
 
 ## 🤝 Contributing
 
-We welcome contributions! Please follow these guidelines:
-
-### Commit Message Format
-
-We use [Conventional Commits](https://www.conventionalcommits.org/) for commit messages:
-
-```
-<type>[optional scope]: <description>
-
-[optional body]
-
-[optional footer(s)]
-```
-
-**Types:**
-- **feat**: A new feature
-- **fix**: A bug fix
-- **docs**: Documentation only changes
-- **style**: Changes that do not affect the meaning of the code
-- **refactor**: A code change that neither fixes a bug nor adds a feature
-- **perf**: A code change that improves performance
-- **test**: Adding missing tests or correcting existing tests
-- **chore**: Changes to the build process or auxiliary tools
-
-**Examples:**
-```
-feat: add support for Claude AI instrumentation
-fix(pii): resolve masking issue with nested objects
-docs: update installation instructions
-```
-
-**Scope** can be used to specify the area of change (e.g., `pii`, `instrumentation`, `decorators`).
-
-**Body** should include the motivation for the change and contrast with previous behavior.
-
-**Footer** can be used for "BREAKING CHANGE:" or issue references.
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for detailed information on how to contribute to the project, including development setup, testing, and our commit message format.
 
 ---

{netra_sdk-0.1.4 → netra_sdk-0.1.6}/netra/decorators.py

@@ -12,6 +12,7 @@ from typing import Any, Awaitable, Callable, Dict, Optional, ParamSpec, Tuple, T
 from opentelemetry import trace
 
 from .config import Config
+from .session_manager import SessionManager
 
 P = ParamSpec("P")
 R = TypeVar("R")
@@ -78,6 +79,9 @@ def _create_function_wrapper(func: Callable[P, R], entity_type: str, name: Optio
 
         @functools.wraps(func)
         async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+            # Push entity to stack before span starts so SessionSpanProcessor can capture it
+            SessionManager.push_entity(entity_type, span_name)
+
             tracer = trace.get_tracer(module_name)
             with tracer.start_as_current_span(span_name) as span:
                 _add_span_attributes(span, func, args, kwargs, entity_type)
@@ -87,8 +91,10 @@ def _create_function_wrapper(func: Callable[P, R], entity_type: str, name: Optio
                     return result
                 except Exception as e:
                     span.set_attribute(f"{Config.LIBRARY_NAME}.entity.error", str(e))
-                    span.record_exception(e)
                     raise
+                finally:
+                    # Pop entity from stack after function call is done
+                    SessionManager.pop_entity(entity_type)
 
         return cast(Callable[P, R], async_wrapper)
 
@@ -96,6 +102,9 @@ def _create_function_wrapper(func: Callable[P, R], entity_type: str, name: Optio
 
         @functools.wraps(func)
         def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            # Push entity to stack before span starts so SessionSpanProcessor can capture it
+            SessionManager.push_entity(entity_type, span_name)
+
             tracer = trace.get_tracer(module_name)
             with tracer.start_as_current_span(span_name) as span:
                 _add_span_attributes(span, func, args, kwargs, entity_type)
@@ -105,8 +114,10 @@ def _create_function_wrapper(func: Callable[P, R], entity_type: str, name: Optio
                     return result
                 except Exception as e:
                     span.set_attribute(f"{Config.LIBRARY_NAME}.entity.error", str(e))
-                    span.record_exception(e)
                     raise
+                finally:
+                    # Pop entity from stack after function call is done
+                    SessionManager.pop_entity(entity_type)
 
         return cast(Callable[P, R], sync_wrapper)
 

{netra_sdk-0.1.4 → netra_sdk-0.1.6}/netra/processors/error_detection_processor.py

@@ -1,9 +1,9 @@
 import logging
-from typing import Any, Optional
+from typing import Any, Optional, Union
 
 import httpx
 from opentelemetry.sdk.trace import SpanProcessor
-from opentelemetry.trace import Context, Span
+from opentelemetry.trace import Context, Span, Status, StatusCode
 
 from netra import Netra
 
@@ -63,4 +63,22 @@ class ErrorDetectionProcessor(SpanProcessor):  # type: ignore[misc]
 
             return original_set_attribute(key, value)
 
+        # Wrap set_status
+        original_set_status = span.set_status
+
+        def wrapped_set_status(status: Union[Status, StatusCode]) -> Any:
+            # Check if status code is ERROR
+            if isinstance(status, Status):
+                status_code = status.status_code
+            elif isinstance(status, StatusCode):
+                status_code = status
+            if status_code == StatusCode.ERROR:
+                event_attributes = {
+                    "has_error": True,
+                }
+                Netra.set_custom_event(event_name="error_detected", attributes=event_attributes)
+
+            return original_set_status(status)
+
         span.set_attribute = wrapped_set_attribute
+        span.set_status = wrapped_set_status

{netra_sdk-0.1.4 → netra_sdk-0.1.6}/netra/processors/session_span_processor.py

@@ -42,6 +42,12 @@ class SessionSpanProcessor(SpanProcessor):  # type: ignore[misc]
                     value = baggage.get_baggage(f"custom.{key}", ctx)
                     if value:
                         span.set_attribute(f"{Config.LIBRARY_NAME}.custom.{key}", value)
+
+            # Add entity attributes from SessionManager
+            entity_attributes = SessionManager.get_current_entity_attributes()
+            for attr_key, attr_value in entity_attributes.items():
+                span.set_attribute(attr_key, attr_value)
+
         except Exception as e:
             logger.exception(f"Error setting span attributes: {e}")
 

{netra_sdk-0.1.4 → netra_sdk-0.1.6}/netra/session.py

@@ -1,11 +1,13 @@
+import json
 import logging
 import time
-from typing import Any, Dict, Literal, Optional
+from typing import Any, Dict, List, Literal, Optional
 
 from opentelemetry import context as context_api
 from opentelemetry import trace
 from opentelemetry.trace import SpanKind, Status, StatusCode
 from opentelemetry.trace.propagation import set_span_in_context
+from pydantic import BaseModel
 
 from netra.config import Config
 
@@ -14,22 +16,22 @@ logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
 
+class UsageModel(BaseModel):  # type: ignore[misc]
+    model: str
+    type: str
+    unit_used: Optional[int] = None
+    cost_in_usd: Optional[float] = None
+
+
 class ATTRIBUTE:
     LLM_SYSTEM = "llm_system"
     MODEL = "model"
     PROMPT = "prompt"
     NEGATIVE_PROMPT = "negative_prompt"
-    IMAGE_HEIGHT = "image_height"
-    IMAGE_WIDTH = "image_width"
-    CREDITS = "credits"
-    TOTAL_COST = "total_cost"
-    TOTAL_TOKENS = "total_tokens"
-    PROMPT_TOKENS_COST = "prompt_tokens_cost"
-    PROMPT_TOKENS = "prompt_tokens"
-    COMPLETION_TOKENS_COST = "completion_tokens_cost"
-    COMPLETION_TOKENS = "completion_tokens"
-    CACHED_TOKENS_COST = "cached_tokens_cost"
-    CACHED_TOKENS = "cached_tokens"
+    HEIGHT = "height"
+    WIDTH = "width"
+    OUTPUT_TYPE = "output_type"
+    USAGE = "usage"
     STATUS = "status"
     DURATION_MS = "duration_ms"
     ERROR_MESSAGE = "error_message"
@@ -46,7 +48,7 @@ class Session:
             # External API call
             result = external_api.generate_video(...)
 
-            session.set_tokens("20").set_credits("30")
+            session.set_usage(usage_data)
     """
 
     def __init__(self, name: str, attributes: Optional[Dict[str, str]] = None, module_name: str = "combat_sdk"):
@@ -139,49 +141,23 @@ class Session:
         """Set the negative prompt."""
         return self.set_attribute(f"{Config.LIBRARY_NAME}.{ATTRIBUTE.NEGATIVE_PROMPT}", negative_prompt)
 
-    def set_image_height(self, height: str) -> "Session":
-        """Set the image height."""
-        return self.set_attribute(f"{Config.LIBRARY_NAME}.{ATTRIBUTE.IMAGE_HEIGHT}", height)
-
-    def set_image_width(self, width: str) -> "Session":
-        """Set the image width."""
-        return self.set_attribute(f"{Config.LIBRARY_NAME}.{ATTRIBUTE.IMAGE_WIDTH}", width)
-
-    def set_total_tokens(self, tokens: str) -> "Session":
-        """Set the number of tokens used."""
-        return self.set_attribute(f"{Config.LIBRARY_NAME}.{ATTRIBUTE.TOTAL_TOKENS}", tokens)
-
-    def set_prompt_tokens_cost(self, cost: str) -> "Session":
-        """Set the number of tokens used."""
-        return self.set_attribute(f"{Config.LIBRARY_NAME}.{ATTRIBUTE.PROMPT_TOKENS_COST}", cost)
-
-    def set_prompt_tokens(self, tokens: str) -> "Session":
-        """Set the number of tokens used."""
-        return self.set_attribute(f"{Config.LIBRARY_NAME}.{ATTRIBUTE.PROMPT_TOKENS}", tokens)
-
-    def set_completion_tokens_cost(self, cost: str) -> "Session":
-        """Set the number of tokens used."""
-        return self.set_attribute(f"{Config.LIBRARY_NAME}.{ATTRIBUTE.COMPLETION_TOKENS_COST}", cost)
-
-    def set_completion_tokens(self, tokens: str) -> "Session":
-        """Set the number of tokens used."""
-        return self.set_attribute(f"{Config.LIBRARY_NAME}.{ATTRIBUTE.COMPLETION_TOKENS}", tokens)
-
-    def set_cached_tokens_cost(self, cost: str) -> "Session":
-        """Set the number of tokens used."""
-        return self.set_attribute(f"{Config.LIBRARY_NAME}.{ATTRIBUTE.CACHED_TOKENS_COST}", cost)
+    def set_height(self, height: str) -> "Session":
+        """Set the height."""
+        return self.set_attribute(f"{Config.LIBRARY_NAME}.{ATTRIBUTE.HEIGHT}", height)
 
-    def set_cached_tokens(self, tokens: str) -> "Session":
-        """Set the number of tokens used."""
-        return self.set_attribute(f"{Config.LIBRARY_NAME}.{ATTRIBUTE.CACHED_TOKENS}", tokens)
+    def set_width(self, width: str) -> "Session":
+        """Set the width."""
+        return self.set_attribute(f"{Config.LIBRARY_NAME}.{ATTRIBUTE.WIDTH}", width)
 
-    def set_credits(self, credits: str) -> "Session":
-        """Set the number of credits used."""
-        return self.set_attribute(f"{Config.LIBRARY_NAME}.{ATTRIBUTE.CREDITS}", credits)
+    def set_output_type(self, output_type: str) -> "Session":
+        """Set the output type."""
+        return self.set_attribute(f"{Config.LIBRARY_NAME}.{ATTRIBUTE.OUTPUT_TYPE}", output_type)
 
-    def set_total_cost(self, cost: str) -> "Session":
-        """Set the cost of the operation."""
-        return self.set_attribute(f"{Config.LIBRARY_NAME}.{ATTRIBUTE.TOTAL_COST}", cost)
+    def set_usage(self, usage: List[UsageModel]) -> "Session":
+        """Set the usage data as a JSON string."""
+        usage_dict = [u.model_dump() for u in usage]
+        usage_json = json.dumps(usage_dict)
+        return self.set_attribute(f"{Config.LIBRARY_NAME}.{ATTRIBUTE.USAGE}", usage_json)
 
     def set_model(self, model: str) -> "Session":
         """Set the model used."""

{netra_sdk-0.1.4 → netra_sdk-0.1.6}/netra/session_manager.py

@@ -5,7 +5,7 @@ Handles automatic session and user ID management for applications.
 
 import logging
 from datetime import datetime
-from typing import Any, Dict, Optional, Union
+from typing import Any, Dict, List, Optional, Union
 
 from opentelemetry import baggage
 from opentelemetry import context as otel_context
@@ -22,6 +22,11 @@ class SessionManager:
     # Class variable to track the current span
     _current_span: Optional[trace.Span] = None
 
+    # Class variables to track separate entity stacks
+    _workflow_stack: List[str] = []
+    _task_stack: List[str] = []
+    _agent_stack: List[str] = []
+
     @classmethod
     def set_current_span(cls, span: Optional[trace.Span]) -> None:
         """
@@ -42,6 +47,86 @@ class SessionManager:
         """
         return cls._current_span
 
+    @classmethod
+    def push_entity(cls, entity_type: str, entity_name: str) -> None:
+        """
+        Push an entity onto the appropriate entity stack.
+
+        Args:
+            entity_type: Type of entity (workflow, task, agent)
+            entity_name: Name of the entity
+        """
+        if entity_type == "workflow":
+            cls._workflow_stack.append(entity_name)
+        elif entity_type == "task":
+            cls._task_stack.append(entity_name)
+        elif entity_type == "agent":
+            cls._agent_stack.append(entity_name)
+
+    @classmethod
+    def pop_entity(cls, entity_type: str) -> Optional[str]:
+        """
+        Pop the most recent entity from the specified entity stack.
+
+        Args:
+            entity_type: Type of entity (workflow, task, agent)
+
+        Returns:
+            Entity name or None if stack is empty
+        """
+        if entity_type == "workflow" and cls._workflow_stack:
+            return cls._workflow_stack.pop()
+        elif entity_type == "task" and cls._task_stack:
+            return cls._task_stack.pop()
+        elif entity_type == "agent" and cls._agent_stack:
+            return cls._agent_stack.pop()
+        return None
+
+    @classmethod
+    def get_current_entity_attributes(cls) -> Dict[str, str]:
+        """
+        Get current entity attributes for span annotation.
+
+        Returns:
+            Dictionary of entity attributes to add to spans
+        """
+        attributes = {}
+
+        # Add current workflow if exists
+        if cls._workflow_stack:
+            attributes[f"{Config.LIBRARY_NAME}.workflow.name"] = cls._workflow_stack[-1]
+
+        # Add current task if exists
+        if cls._task_stack:
+            attributes[f"{Config.LIBRARY_NAME}.task.name"] = cls._task_stack[-1]
+
+        # Add current agent if exists
+        if cls._agent_stack:
+            attributes[f"{Config.LIBRARY_NAME}.agent.name"] = cls._agent_stack[-1]
+
+        return attributes
+
+    @classmethod
+    def clear_entity_stacks(cls) -> None:
+        """Clear all entity stacks."""
+        cls._workflow_stack.clear()
+        cls._task_stack.clear()
+        cls._agent_stack.clear()
+
+    @classmethod
+    def get_stack_info(cls) -> Dict[str, List[str]]:
+        """
+        Get information about all current stacks.
+
+        Returns:
+            Dictionary containing all stack contents
+        """
+        return {
+            "workflows": cls._workflow_stack.copy(),
+            "tasks": cls._task_stack.copy(),
+            "agents": cls._agent_stack.copy(),
+        }
+
     @staticmethod
     def set_session_context(session_key: str, value: Union[str, Dict[str, str]]) -> None:
         """

netra_sdk-0.1.6/netra/version.py

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

{netra_sdk-0.1.4 → netra_sdk-0.1.6}/pyproject.toml

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

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