mantisdk 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

mantisdk/tracing/attributes.py

@@ -0,0 +1,191 @@
+# Copyright (c) Metis. All rights reserved.
+
+"""Semantic attributes for MantisDK tracing.
+
+These attributes follow the Mantis Insight OTEL conventions, ensuring
+spans are properly processed and displayed in the Insight dashboard.
+
+The attributes are organized by namespace:
+- insight.*: Primary namespace for Insight-specific attributes
+- gen_ai.*: OpenTelemetry GenAI semantic conventions
+- langfuse.*: Compatibility namespace for Langfuse SDK spans
+"""
+
+# =============================================================================
+# Insight Trace Attributes (Primary Namespace)
+# =============================================================================
+INSIGHT_TRACE_NAME = "insight.trace.name"
+INSIGHT_TRACE_USER_ID = "insight.user.id"
+INSIGHT_TRACE_SESSION_ID = "insight.session.id"
+INSIGHT_TRACE_TAGS = "insight.trace.tags"
+INSIGHT_TRACE_PUBLIC = "insight.trace.public"
+INSIGHT_TRACE_METADATA = "insight.trace.metadata"
+INSIGHT_TRACE_INPUT = "insight.trace.input"
+INSIGHT_TRACE_OUTPUT = "insight.trace.output"
+
+# =============================================================================
+# Insight Observation Attributes (Primary Namespace)
+# =============================================================================
+INSIGHT_OBSERVATION_TYPE = "insight.observation.type"
+INSIGHT_OBSERVATION_METADATA = "insight.observation.metadata"
+INSIGHT_OBSERVATION_LEVEL = "insight.observation.level"
+INSIGHT_OBSERVATION_STATUS_MESSAGE = "insight.observation.status_message"
+INSIGHT_OBSERVATION_INPUT = "insight.observation.input"
+INSIGHT_OBSERVATION_OUTPUT = "insight.observation.output"
+INSIGHT_OBSERVATION_MODEL = "insight.observation.model.name"
+INSIGHT_OBSERVATION_MODEL_PARAMETERS = "insight.observation.model.parameters"
+
+# =============================================================================
+# Insight General Attributes (Primary Namespace)
+# =============================================================================
+INSIGHT_ENVIRONMENT = "insight.environment"
+INSIGHT_RELEASE = "insight.release"
+INSIGHT_VERSION = "insight.version"
+
+# =============================================================================
+# Langfuse Trace Attributes (Compatibility)
+# =============================================================================
+LANGFUSE_TRACE_NAME = "langfuse.trace.name"
+LANGFUSE_TRACE_USER_ID = "user.id"
+LANGFUSE_TRACE_SESSION_ID = "session.id"
+LANGFUSE_TRACE_TAGS = "langfuse.trace.tags"
+LANGFUSE_TRACE_PUBLIC = "langfuse.trace.public"
+LANGFUSE_TRACE_METADATA = "langfuse.trace.metadata"
+LANGFUSE_TRACE_INPUT = "langfuse.trace.input"
+LANGFUSE_TRACE_OUTPUT = "langfuse.trace.output"
+
+# =============================================================================
+# Langfuse Observation Attributes (Compatibility)
+# =============================================================================
+LANGFUSE_OBSERVATION_TYPE = "langfuse.observation.type"
+LANGFUSE_OBSERVATION_METADATA = "langfuse.observation.metadata"
+LANGFUSE_OBSERVATION_LEVEL = "langfuse.observation.level"
+LANGFUSE_OBSERVATION_STATUS_MESSAGE = "langfuse.observation.status_message"
+LANGFUSE_OBSERVATION_INPUT = "langfuse.observation.input"
+LANGFUSE_OBSERVATION_OUTPUT = "langfuse.observation.output"
+
+# =============================================================================
+# Langfuse Generation Attributes (Compatibility)
+# =============================================================================
+LANGFUSE_OBSERVATION_COMPLETION_START_TIME = "langfuse.observation.completion_start_time"
+LANGFUSE_OBSERVATION_MODEL = "langfuse.observation.model.name"
+LANGFUSE_OBSERVATION_MODEL_PARAMETERS = "langfuse.observation.model.parameters"
+LANGFUSE_OBSERVATION_USAGE_DETAILS = "langfuse.observation.usage_details"
+LANGFUSE_OBSERVATION_COST_DETAILS = "langfuse.observation.cost_details"
+LANGFUSE_OBSERVATION_PROMPT_NAME = "langfuse.observation.prompt.name"
+LANGFUSE_OBSERVATION_PROMPT_VERSION = "langfuse.observation.prompt.version"
+
+# =============================================================================
+# Langfuse General Attributes (Compatibility)
+# =============================================================================
+LANGFUSE_ENVIRONMENT = "langfuse.environment"
+LANGFUSE_RELEASE = "langfuse.release"
+LANGFUSE_VERSION = "langfuse.version"
+
+# =============================================================================
+# OpenTelemetry GenAI Semantic Conventions
+# https://opentelemetry.io/docs/specs/semconv/gen-ai/
+# =============================================================================
+GEN_AI_OPERATION_NAME = "gen_ai.operation.name"
+GEN_AI_SYSTEM = "gen_ai.system"
+GEN_AI_REQUEST_MODEL = "gen_ai.request.model"
+GEN_AI_RESPONSE_MODEL = "gen_ai.response.model"
+GEN_AI_REQUEST_TEMPERATURE = "gen_ai.request.temperature"
+GEN_AI_REQUEST_MAX_TOKENS = "gen_ai.request.max_tokens"
+GEN_AI_RESPONSE_FINISH_REASONS = "gen_ai.response.finish_reasons"
+GEN_AI_CONVERSATION_ID = "gen_ai.conversation.id"
+
+# GenAI Input/Output
+GEN_AI_INPUT_MESSAGES = "gen_ai.input.messages"
+GEN_AI_OUTPUT_MESSAGES = "gen_ai.output.messages"
+
+# GenAI Usage
+GEN_AI_USAGE_INPUT_TOKENS = "gen_ai.usage.input_tokens"
+GEN_AI_USAGE_OUTPUT_TOKENS = "gen_ai.usage.output_tokens"
+GEN_AI_USAGE_COST = "gen_ai.usage.cost"
+
+# GenAI Tool Attributes
+GEN_AI_TOOL_NAME = "gen_ai.tool.name"
+GEN_AI_TOOL_CALL_ARGUMENTS = "gen_ai.tool.call.arguments"
+GEN_AI_TOOL_CALL_RESULT = "gen_ai.tool.call.result"
+
+# =============================================================================
+# OpenInference Semantic Conventions
+# https://github.com/Arize-ai/openinference
+# =============================================================================
+OPENINFERENCE_SPAN_KIND = "openinference.span.kind"
+
+# LLM Attributes
+LLM_MODEL_NAME = "llm.model_name"
+LLM_INVOCATION_PARAMETERS = "llm.invocation_parameters"
+LLM_INPUT_MESSAGES = "llm.input_messages"
+LLM_OUTPUT_MESSAGES = "llm.output_messages"
+LLM_TOKEN_COUNT_PROMPT = "llm.token_count.prompt"
+LLM_TOKEN_COUNT_COMPLETION = "llm.token_count.completion"
+LLM_TOKEN_COUNT_TOTAL = "llm.token_count.total"
+
+# Input/Output (general)
+INPUT_VALUE = "input.value"
+OUTPUT_VALUE = "output.value"
+
+# Tool Attributes
+TOOL_NAME = "tool.name"
+TOOL_DESCRIPTION = "tool.description"
+TOOL_PARAMETERS = "tool.parameters"
+
+# =============================================================================
+# OpenInference Span Kind Values
+# =============================================================================
+SPAN_KIND_LLM = "LLM"
+SPAN_KIND_TOOL = "TOOL"
+SPAN_KIND_AGENT = "AGENT"
+SPAN_KIND_CHAIN = "CHAIN"
+SPAN_KIND_EMBEDDING = "EMBEDDING"
+SPAN_KIND_RETRIEVER = "RETRIEVER"
+SPAN_KIND_RERANKER = "RERANKER"
+SPAN_KIND_GUARDRAIL = "GUARDRAIL"
+SPAN_KIND_EVALUATOR = "EVALUATOR"
+
+# =============================================================================
+# OpenInference MIME Types
+# =============================================================================
+MIME_TYPE_TEXT = "text/plain"
+MIME_TYPE_JSON = "application/json"
+
+# =============================================================================
+# OpenInference Extended Attributes
+# =============================================================================
+INPUT_MIME_TYPE = "input.mime_type"
+OUTPUT_MIME_TYPE = "output.mime_type"
+LLM_SYSTEM = "llm.system"
+LLM_PROVIDER = "llm.provider"
+
+# Session/User attributes (OpenInference convention)
+SESSION_ID = "session.id"
+USER_ID = "user.id"
+
+# Langfuse trace-level session (alias for compatibility)
+LANGFUSE_TRACE_SESSION_ID = "session.id"
+
+# =============================================================================
+# MantisDK Custom Attributes
+# These are additional attributes specific to MantisDK instrumentation
+# =============================================================================
+MANTIS_LLM_THINKING = "mantis.llm.thinking"
+MANTIS_LLM_COST_USD = "mantis.llm.cost_usd"
+MANTIS_DURATION_MS = "mantis.duration_ms"
+MANTIS_DURATION_API_MS = "mantis.duration_api_ms"
+MANTIS_NUM_TURNS = "mantis.num_turns"
+MANTIS_TOOL_IS_ERROR = "mantis.tool.is_error"
+
+# =============================================================================
+# Claude-Specific Attributes
+# These capture Claude Agent SDK-specific data not covered by standard conventions
+# =============================================================================
+CLAUDE_API_ERROR = "claude.api_error"
+CLAUDE_PARENT_TOOL_USE_ID = "claude.parent_tool_use_id"
+CLAUDE_STRUCTURED_OUTPUT = "claude.structured_output"
+CLAUDE_THINKING_SIGNATURE = "claude.thinking.signature"
+CLAUDE_MESSAGE_UUID = "claude.message.uuid"
+CLAUDE_SYSTEM_SUBTYPE = "claude.system.subtype"
+CLAUDE_SYSTEM_DATA = "claude.system.data"

mantisdk/tracing/exporters/__init__.py

@@ -0,0 +1,10 @@
+# Copyright (c) Metis. All rights reserved.
+
+"""Exporters for MantisDK tracing."""
+
+from .insight import insight, InsightOTLPExporter
+
+__all__ = [
+    "insight",
+    "InsightOTLPExporter",
+]

mantisdk/tracing/exporters/insight.py

@@ -0,0 +1,202 @@
+# Copyright (c) Metis. All rights reserved.
+
+"""Insight OTLP exporter for MantisDK tracing.
+
+This module provides an OTLP/HTTP exporter configured for Mantis Insight,
+with support for environment variable auto-detection and Basic Auth headers.
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+import os
+from typing import Optional
+
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+
+logger = logging.getLogger(__name__)
+
+# Environment variable names (INSIGHT_* prefix)
+ENV_INSIGHT_HOST = "INSIGHT_HOST"
+ENV_INSIGHT_PUBLIC_KEY = "INSIGHT_PUBLIC_KEY"
+ENV_INSIGHT_SECRET_KEY = "INSIGHT_SECRET_KEY"
+ENV_INSIGHT_OTLP_ENDPOINT = "INSIGHT_OTLP_ENDPOINT"
+
+# Default OTLP endpoint path
+DEFAULT_OTLP_PATH = "/api/public/otel/v1/traces"
+
+
+class InsightOTLPExporter(OTLPSpanExporter):
+    """OTLP exporter configured for Mantis Insight.
+
+    This exporter automatically handles Basic Auth header construction
+    from public/secret key pairs.
+
+    Example::
+
+        from mantisdk.tracing_claude.exporters import InsightOTLPExporter
+
+        exporter = InsightOTLPExporter(
+            host="https://insight.withmetis.ai",
+            public_key="pk-lf-...",
+            secret_key="sk-lf-...",
+        )
+    """
+
+    def __init__(
+        self,
+        host: str,
+        public_key: str,
+        secret_key: str,
+        *,
+        endpoint: Optional[str] = None,
+        **kwargs,
+    ):
+        """Initialize the Insight OTLP exporter.
+
+        Args:
+            host: The Insight server URL (e.g., "https://insight.withmetis.ai").
+            public_key: The public key for authentication (pk-lf-...).
+            secret_key: The secret key for authentication (sk-lf-...).
+            endpoint: Optional full OTLP endpoint URL. If not provided,
+                derived from host + DEFAULT_OTLP_PATH.
+            **kwargs: Additional arguments passed to OTLPSpanExporter.
+        """
+        # Derive endpoint from host if not explicitly provided
+        if endpoint is None:
+            # Remove trailing slash if present
+            host = host.rstrip("/")
+            endpoint = f"{host}{DEFAULT_OTLP_PATH}"
+
+        # Construct Basic Auth header
+        credentials = f"{public_key}:{secret_key}"
+        encoded = base64.b64encode(credentials.encode("utf-8")).decode("utf-8")
+        auth_header = f"Basic {encoded}"
+
+        # Merge auth header with any user-provided headers
+        headers = kwargs.pop("headers", {}) or {}
+        headers["Authorization"] = auth_header
+
+        super().__init__(endpoint=endpoint, headers=headers, **kwargs)
+
+        self._insight_host = host
+        self._insight_public_key = public_key
+        # Don't store secret key in instance for security
+
+        logger.debug(
+            "InsightOTLPExporter initialized: endpoint=%s, public_key=%s",
+            endpoint,
+            public_key[:20] + "..." if len(public_key) > 20 else public_key,
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"InsightOTLPExporter("
+            f"host={self._insight_host!r}, "
+            f"public_key={self._insight_public_key[:10]}...)"
+        )
+
+
+def insight(
+    *,
+    host: Optional[str] = None,
+    public_key: Optional[str] = None,
+    secret_key: Optional[str] = None,
+    endpoint: Optional[str] = None,
+    **kwargs,
+) -> InsightOTLPExporter:
+    """Factory function to create an Insight OTLP exporter.
+
+    This function supports both explicit configuration and environment variable
+    auto-detection. If any required parameter is not provided, it will be read
+    from the corresponding environment variable.
+
+    Environment variables:
+        - INSIGHT_HOST: The Insight server URL
+        - INSIGHT_PUBLIC_KEY: The public key for authentication
+        - INSIGHT_SECRET_KEY: The secret key for authentication
+        - INSIGHT_OTLP_ENDPOINT: Optional override for the OTLP endpoint
+
+    Args:
+        host: The Insight server URL. Falls back to INSIGHT_HOST env var.
+        public_key: The public key. Falls back to INSIGHT_PUBLIC_KEY env var.
+        secret_key: The secret key. Falls back to INSIGHT_SECRET_KEY env var.
+        endpoint: Optional full OTLP endpoint URL. Falls back to INSIGHT_OTLP_ENDPOINT.
+        **kwargs: Additional arguments passed to InsightOTLPExporter.
+
+    Returns:
+        Configured InsightOTLPExporter instance.
+
+    Raises:
+        ValueError: If required credentials are not provided and not found in env vars.
+
+    Example::
+
+        import mantisdk.tracing_claude as tracing
+
+        # Using environment variables
+        tracing.init(exporters=[tracing.insight_exporter()])
+
+        # Explicit configuration
+        tracing.init(exporters=[
+            tracing.insight_exporter(
+                host="https://insight.withmetis.ai",
+                public_key="pk-lf-...",
+                secret_key="sk-lf-...",
+            )
+        ])
+    """
+    # Read from env vars if not provided
+    host = host or os.environ.get(ENV_INSIGHT_HOST)
+    public_key = public_key or os.environ.get(ENV_INSIGHT_PUBLIC_KEY)
+    secret_key = secret_key or os.environ.get(ENV_INSIGHT_SECRET_KEY)
+    endpoint = endpoint or os.environ.get(ENV_INSIGHT_OTLP_ENDPOINT)
+
+    # Validate required parameters
+    missing = []
+    if not host:
+        missing.append(f"{ENV_INSIGHT_HOST} (or host parameter)")
+    if not public_key:
+        missing.append(f"{ENV_INSIGHT_PUBLIC_KEY} (or public_key parameter)")
+    if not secret_key:
+        missing.append(f"{ENV_INSIGHT_SECRET_KEY} (or secret_key parameter)")
+
+    if missing:
+        raise ValueError(
+            f"Missing required Insight configuration: {', '.join(missing)}. "
+            "Provide these values via function arguments or environment variables."
+        )
+
+    return InsightOTLPExporter(
+        host=host,
+        public_key=public_key,
+        secret_key=secret_key,
+        endpoint=endpoint,
+        **kwargs,
+    )
+
+
+def detect_insight_config() -> tuple[Optional[str], Optional[str], Optional[str], Optional[str]]:
+    """Detect Insight configuration from environment variables.
+
+    Returns:
+        Tuple of (host, public_key, secret_key, endpoint) where any value may be None
+        if the corresponding environment variable is not set.
+    """
+    return (
+        os.environ.get(ENV_INSIGHT_HOST),
+        os.environ.get(ENV_INSIGHT_PUBLIC_KEY),
+        os.environ.get(ENV_INSIGHT_SECRET_KEY),
+        os.environ.get(ENV_INSIGHT_OTLP_ENDPOINT),
+    )
+
+
+def is_insight_configured() -> bool:
+    """Check if Insight is configured via environment variables.
+
+    Returns:
+        True if all required environment variables are set.
+    """
+    host, public_key, secret_key, _ = detect_insight_config()
+    return all([host, public_key, secret_key])