magic-lab-observer 0.1.1__py3-none-any.whl

llm_observatory/__init__.py

@@ -0,0 +1,32 @@
+"""LLM Observatory Python SDK - Open-source LLM observability."""
+
+from llm_observatory.exporters.otlp import OTLPExporter
+from llm_observatory.instrumentors import instrument, uninstrument
+from llm_observatory.pricing import MODEL_PRICING, calculate_cost, get_model_pricing
+from llm_observatory.tracer import (
+    Span,
+    SpanStatus,
+    TokenUsage,
+    Tracer,
+    get_tracer,
+    set_tracer,
+    trace,
+)
+
+__version__ = "0.1.1"
+
+__all__ = [
+    "Tracer",
+    "Span",
+    "SpanStatus",
+    "TokenUsage",
+    "trace",
+    "get_tracer",
+    "set_tracer",
+    "instrument",
+    "uninstrument",
+    "calculate_cost",
+    "get_model_pricing",
+    "MODEL_PRICING",
+    "OTLPExporter",
+]

llm_observatory/exporters/__init__.py

@@ -0,0 +1,23 @@
+"""Exporters for sending traces to backends."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class BaseExporter(ABC):
+    """Base class for trace exporters."""
+
+    @abstractmethod
+    def export(self, spans: list[dict[str, Any]]) -> None:
+        """Export spans to the backend.
+
+        Args:
+            spans: List of span dictionaries to export.
+        """
+        ...
+
+    def flush(self) -> None:
+        """Flush any buffered spans."""
+        pass

llm_observatory/exporters/otlp.py

@@ -0,0 +1,90 @@
+"""OTLP HTTP exporter for sending traces to observatory backend."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import httpx
+
+from llm_observatory.exporters import BaseExporter
+
+logger = logging.getLogger(__name__)
+
+
+class OTLPExporter(BaseExporter):
+    """Exports traces to an OTLP-compatible backend via HTTP."""
+
+    def __init__(
+        self,
+        endpoint: str = "http://localhost:8000",
+        api_key: str | None = None,
+        timeout: float = 10.0,
+        max_retries: int = 3,
+    ) -> None:
+        """Initialize the exporter.
+
+        Args:
+            endpoint: Backend endpoint URL.
+            api_key: Optional API key for authentication.
+            timeout: Request timeout in seconds.
+            max_retries: Maximum number of retries on failure.
+        """
+        self.endpoint = endpoint.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._client = httpx.Client(timeout=timeout)
+
+    def export(self, spans: list[dict[str, Any]]) -> None:
+        """Export spans to the backend.
+
+        Args:
+            spans: List of span dictionaries to export.
+        """
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+
+        for attempt in range(self.max_retries):
+            try:
+                response = self._client.post(
+                    f"{self.endpoint}/v1/traces/batch",
+                    json={"spans": spans},
+                    headers=headers,
+                )
+                response.raise_for_status()
+                logger.debug(f"Exported {len(spans)} spans successfully")
+                return
+            except httpx.HTTPStatusError as e:
+                logger.warning(
+                    f"Export failed (attempt {attempt + 1}/{self.max_retries}): "
+                    f"HTTP {e.response.status_code} - {e.response.text}"
+                )
+                if attempt == self.max_retries - 1:
+                    msg = (
+                        f"Export failed after {self.max_retries} attempts, "
+                        f"dropping {len(spans)} spans"
+                    )
+                    logger.error(msg)
+            except httpx.HTTPError as e:
+                logger.warning(
+                    f"Export failed (attempt {attempt + 1}/{self.max_retries}): {e}"
+                )
+                if attempt == self.max_retries - 1:
+                    msg = (
+                        f"Export failed after {self.max_retries} attempts, "
+                        f"dropping {len(spans)} spans"
+                    )
+                    logger.error(msg)
+
+    def flush(self) -> None:
+        """Flush any buffered spans."""
+        self._client.close()
+
+    def __del__(self) -> None:
+        """Clean up the client."""
+        try:
+            self._client.close()
+        except Exception:
+            pass

llm_observatory/instrumentors/__init__.py

@@ -0,0 +1,57 @@
+"""Auto-instrumentation for LLM libraries."""
+
+from __future__ import annotations
+
+from typing import Any
+
+# Store instrumentor instances for uninstrument()
+_active_instrumentors: list[Any] = []
+
+
+def instrument(
+    openai: bool = False,
+    anthropic: bool = False,
+    langchain: bool = False,
+    **kwargs: Any,
+) -> None:
+    """Auto-instrument LLM libraries.
+
+    Args:
+        openai: Enable OpenAI instrumentation.
+        anthropic: Enable Anthropic instrumentation.
+        langchain: Enable LangChain instrumentation.
+        **kwargs: Additional configuration options.
+    """
+    if openai:
+        from llm_observatory.instrumentors.openai import OpenAIInstrumentor
+
+        inst = OpenAIInstrumentor()
+        inst.instrument()
+        _active_instrumentors.append(inst)
+
+    if anthropic:
+        from llm_observatory.instrumentors.anthropic import AnthropicInstrumentor
+
+        inst = AnthropicInstrumentor()
+        inst.instrument()
+        _active_instrumentors.append(inst)
+
+    if langchain:
+        try:
+            from llm_observatory.instrumentors.langchain import LangChainInstrumentor
+
+            inst = LangChainInstrumentor()
+            inst.instrument()
+            _active_instrumentors.append(inst)
+        except ImportError:
+            pass
+
+
+def uninstrument() -> None:
+    """Uninstrument all active instrumentors."""
+    for inst in _active_instrumentors:
+        try:
+            inst.uninstrument()
+        except Exception:
+            pass
+    _active_instrumentors.clear()

llm_observatory/instrumentors/anthropic.py

@@ -0,0 +1,135 @@
+"""Anthropic auto-instrumentation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from llm_observatory.pricing import calculate_cost
+from llm_observatory.tracer import Span, SpanStatus, get_tracer
+
+
+class AnthropicInstrumentor:
+    """Instruments Anthropic API calls to capture traces."""
+
+    def __init__(self) -> None:
+        self._original_sync_create: Any | None = None
+        self._original_async_create: Any | None = None
+
+    def instrument(self) -> None:
+        """Patch Anthropic to capture traces."""
+        try:
+            import anthropic
+
+            # Patch sync messages
+            self._original_sync_create = anthropic.resources.messages.Messages.create
+            anthropic.resources.messages.Messages.create = self._patched_sync_create
+
+            # Patch async messages
+            self._original_async_create = (
+                anthropic.resources.messages.AsyncMessages.create
+            )
+            anthropic.resources.messages.AsyncMessages.create = (
+                self._patched_async_create
+            )
+        except ImportError:
+            pass
+
+    def _build_span(
+        self, model: str, messages: list[dict[str, Any]]
+    ) -> tuple[Span, Any]:
+        """Build a span for an Anthropic call."""
+        tracer = get_tracer()
+        span = tracer.start_span(
+            name="anthropic.messages.create",
+            span_type="llm",
+        )
+        span.set_input({"model": model, "messages": messages})
+        span.set_attribute("gen_ai.system", "anthropic")
+        span.set_attribute("gen_ai.request.model", model)
+        return span, tracer
+
+    def _finish_span(self, span: Span, result: Any, model: str) -> None:
+        """Extract data from result and finish span."""
+        try:
+            # Extract token usage
+            if hasattr(result, "usage"):
+                input_tokens = getattr(result.usage, "input_tokens", 0) or 0
+                output_tokens = getattr(result.usage, "output_tokens", 0) or 0
+                span.set_token_usage(input_tokens, output_tokens)
+
+                # Calculate cost
+                cost = calculate_cost(model, input_tokens, output_tokens)
+                if cost is not None:
+                    span.set_cost(cost)
+
+            # Extract output
+            if hasattr(result, "content") and result.content:
+                content_blocks = []
+                for block in result.content:
+                    block_data = {}
+                    if hasattr(block, "type"):
+                        block_data["type"] = block.type
+                    if hasattr(block, "text"):
+                        block_data["text"] = block.text
+                    content_blocks.append(block_data)
+                span.set_output({"content": content_blocks})
+
+            span.set_attribute("response_id", getattr(result, "id", None))
+            span.set_status(SpanStatus.OK)
+
+        except Exception as e:
+            span.set_status(SpanStatus.ERROR)
+            span.set_attribute("error.message", str(e))
+
+        finally:
+            span.end()
+
+    def _patched_sync_create(self, *args: Any, **kwargs: Any) -> Any:
+        """Patched sync create method."""
+        model = kwargs.get("model", "unknown")
+        messages = kwargs.get("messages", [])
+
+        span, _ = self._build_span(model, messages)
+
+        try:
+            result = self._original_sync_create(*args, **kwargs)
+            self._finish_span(span, result, model)
+            return result
+        except Exception as e:
+            span.set_status(SpanStatus.ERROR)
+            span.set_attribute("error.message", str(e))
+            span.end()
+            raise
+
+    async def _patched_async_create(self, *args: Any, **kwargs: Any) -> Any:
+        """Patched async create method."""
+        model = kwargs.get("model", "unknown")
+        messages = kwargs.get("messages", [])
+
+        span, _ = self._build_span(model, messages)
+
+        try:
+            result = await self._original_async_create(*args, **kwargs)
+            self._finish_span(span, result, model)
+            return result
+        except Exception as e:
+            span.set_status(SpanStatus.ERROR)
+            span.set_attribute("error.message", str(e))
+            span.end()
+            raise
+
+    def uninstrument(self) -> None:
+        """Remove instrumentation."""
+        try:
+            import anthropic
+
+            if self._original_sync_create is not None:
+                anthropic.resources.messages.Messages.create = (
+                    self._original_sync_create
+                )
+            if self._original_async_create is not None:
+                anthropic.resources.messages.AsyncMessages.create = (
+                    self._original_async_create
+                )
+        except ImportError:
+            pass

llm_observatory/instrumentors/langchain.py

@@ -0,0 +1,156 @@
+"""LangChain auto-instrumentation for LLM Observatory."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from llm_observatory.pricing import calculate_cost
+from llm_observatory.tracer import SpanStatus, _current_span, _get_global_tracer
+
+
+class LangChainInstrumentor:
+    """Instruments LangChain callbacks to capture traces."""
+
+    def __init__(self) -> None:
+        self._patched = False
+        self._original_on_llm_start: Any = None
+        self._original_on_llm_end: Any = None
+        self._original_on_llm_error: Any = None
+
+    def instrument(self) -> None:
+        """Enable LangChain instrumentation."""
+        if self._patched:
+            return
+
+        try:
+            from langchain_core.callbacks import BaseCallbackHandler
+
+            # Monkey-patch BaseCallbackHandler
+            original_on_llm_start = BaseCallbackHandler.on_llm_start
+            original_on_llm_end = BaseCallbackHandler.on_llm_end
+            original_on_llm_error = BaseCallbackHandler.on_llm_error
+
+            # Store original methods
+            self._patched = True
+            self._original_on_llm_start = original_on_llm_start
+            self._original_on_llm_end = original_on_llm_end
+            self._original_on_llm_error = original_on_llm_error
+
+            def patched_on_llm_start(
+                self_handler: Any,
+                serialized: dict[str, Any],
+                prompts: list[str],
+                *,
+                run_id: uuid.UUID | None = None,
+                **kwargs: Any,
+            ) -> Any:
+                """Patched on_llm_start that creates a span."""
+                tracer = _get_global_tracer()
+                model_id = serialized.get("id", ["unknown"])
+                model = (
+                    serialized.get("name", model_id[-1])
+                    if isinstance(model_id, list)
+                    else "unknown"
+                )
+
+                span = tracer.start_span(
+                    f"langchain.{model}",
+                    span_type="llm",
+                    model=model,
+                    provider="langchain",
+                )
+                span.set_input({"prompts": prompts, "serialized": serialized})
+                return original_on_llm_start(
+                    self_handler, serialized, prompts,
+                    run_id=run_id, **kwargs,
+                )
+
+            def patched_on_llm_end(
+                self_handler: Any,
+                response: Any,
+                *,
+                run_id: uuid.UUID | None = None,
+                **kwargs: Any,
+            ) -> Any:
+                """Patched on_llm_end that ends the span."""
+                current = _current_span.get()
+                if current:
+                    # Extract token usage from LLMResult
+                    if hasattr(response, "llm_output") and response.llm_output:
+                        token_usage = response.llm_output.get("token_usage", {})
+                        if token_usage:
+                            input_tokens = token_usage.get(
+                                "prompt_tokens",
+                                token_usage.get("input_tokens", 0),
+                            )
+                            output_tokens = token_usage.get(
+                                "completion_tokens",
+                                token_usage.get("output_tokens", 0),
+                            )
+                            current.set_token_usage(input_tokens, output_tokens)
+
+                            # Calculate cost
+                            model = current.attributes.get("model", "unknown")
+                            cost = calculate_cost(model, input_tokens, output_tokens)
+                            if cost is not None:
+                                current.set_cost(cost)
+
+                    # Capture output
+                    if hasattr(response, "generations") and response.generations:
+                        generations = []
+                        for gen_list in response.generations:
+                            for gen in gen_list:
+                                generations.append(gen.text if hasattr(gen, "text") else str(gen))
+                        current.set_output({"generations": generations})
+
+                    current.set_status(SpanStatus.OK)
+                    current.end()
+
+                return original_on_llm_end(self_handler, response, run_id=run_id, **kwargs)
+
+            def patched_on_llm_error(
+                self_handler: Any,
+                error: BaseException,
+                *,
+                run_id: uuid.UUID | None = None,
+                **kwargs: Any,
+            ) -> Any:
+                """Patched on_llm_error that records error."""
+                current = _current_span.get()
+                if current:
+                    current.set_status(SpanStatus.ERROR)
+                    current.set_attribute("error.message", str(error))
+                    current.end()
+
+                return original_on_llm_error(self_handler, error, run_id=run_id, **kwargs)
+
+            BaseCallbackHandler.on_llm_start = patched_on_llm_start
+            BaseCallbackHandler.on_llm_end = patched_on_llm_end
+            BaseCallbackHandler.on_llm_error = patched_on_llm_error
+
+        except ImportError:
+            # LangChain not available
+            pass
+
+    def uninstrument(self) -> None:
+        """Disable LangChain instrumentation."""
+        if not self._patched:
+            return
+
+        try:
+            from langchain_core.callbacks import BaseCallbackHandler
+
+            if self._original_on_llm_start is not None:
+                BaseCallbackHandler.on_llm_start = self._original_on_llm_start
+            if self._original_on_llm_end is not None:
+                BaseCallbackHandler.on_llm_end = self._original_on_llm_end
+            if self._original_on_llm_error is not None:
+                BaseCallbackHandler.on_llm_error = self._original_on_llm_error
+
+            self._patched = False
+            self._original_on_llm_start = None
+            self._original_on_llm_end = None
+            self._original_on_llm_error = None
+        except ImportError:
+            pass

llm_observatory/instrumentors/openai.py

@@ -0,0 +1,137 @@
+"""OpenAI auto-instrumentation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from llm_observatory.pricing import calculate_cost
+from llm_observatory.tracer import Span, SpanStatus, get_tracer
+
+
+class OpenAIInstrumentor:
+    """Instruments OpenAI API calls to capture traces."""
+
+    def __init__(self) -> None:
+        self._original_sync_create: Any | None = None
+        self._original_async_create: Any | None = None
+
+    def instrument(self) -> None:
+        """Patch OpenAI to capture traces."""
+        try:
+            import openai
+
+            # Patch sync completions
+            self._original_sync_create = (
+                openai.resources.chat.completions.Completions.create
+            )
+            openai.resources.chat.completions.Completions.create = self._patched_sync_create
+
+            # Patch async completions
+            self._original_async_create = (
+                openai.resources.chat.completions.AsyncCompletions.create
+            )
+            openai.resources.chat.completions.AsyncCompletions.create = (
+                self._patched_async_create
+            )
+        except ImportError:
+            pass
+
+    def _build_span(
+        self, model: str, messages: list[dict[str, Any]]
+    ) -> tuple[Span, Any]:
+        """Build a span for an OpenAI call."""
+        tracer = get_tracer()
+        span = tracer.start_span(
+            name="openai.chat.completions.create",
+            span_type="llm",
+        )
+        span.set_input({"model": model, "messages": messages})
+        span.set_attribute("gen_ai.system", "openai")
+        span.set_attribute("gen_ai.request.model", model)
+        return span, tracer
+
+    def _finish_span(self, span: Span, result: Any, model: str) -> None:
+        """Extract data from result and finish span."""
+        try:
+            # Extract token usage
+            if hasattr(result, "usage") and result.usage:
+                input_tokens = getattr(result.usage, "prompt_tokens", 0) or 0
+                output_tokens = getattr(result.usage, "completion_tokens", 0) or 0
+                span.set_token_usage(input_tokens, output_tokens)
+
+                # Calculate cost
+                cost = calculate_cost(model, input_tokens, output_tokens)
+                if cost is not None:
+                    span.set_cost(cost)
+
+            # Extract output
+            if hasattr(result, "choices") and result.choices:
+                choice = result.choices[0]
+                if hasattr(choice, "message"):
+                    message = choice.message
+                    output = {}
+                    if hasattr(message, "content"):
+                        output["content"] = message.content
+                    if hasattr(message, "role"):
+                        output["role"] = message.role
+                    span.set_output(output)
+
+            span.set_attribute("response_id", getattr(result, "id", None))
+            span.set_status(SpanStatus.OK)
+
+        except Exception as e:
+            span.set_status(SpanStatus.ERROR)
+            span.set_attribute("error.message", str(e))
+
+        finally:
+            span.end()
+
+    def _patched_sync_create(self, *args: Any, **kwargs: Any) -> Any:
+        """Patched sync create method."""
+        model = kwargs.get("model", "unknown")
+        messages = kwargs.get("messages", [])
+
+        span, _ = self._build_span(model, messages)
+
+        try:
+            result = self._original_sync_create(*args, **kwargs)
+            self._finish_span(span, result, model)
+            return result
+        except Exception as e:
+            span.set_status(SpanStatus.ERROR)
+            span.set_attribute("error.message", str(e))
+            span.end()
+            raise
+
+    async def _patched_async_create(self, *args: Any, **kwargs: Any) -> Any:
+        """Patched async create method."""
+        model = kwargs.get("model", "unknown")
+        messages = kwargs.get("messages", [])
+
+        span, _ = self._build_span(model, messages)
+
+        try:
+            result = await self._original_async_create(*args, **kwargs)
+            self._finish_span(span, result, model)
+            return result
+        except Exception as e:
+            span.set_status(SpanStatus.ERROR)
+            span.set_attribute("error.message", str(e))
+            span.end()
+            raise
+
+    def uninstrument(self) -> None:
+        """Remove instrumentation."""
+        try:
+            import openai
+
+            if self._original_sync_create is not None:
+                openai.resources.chat.completions.Completions.create = (
+                    self._original_sync_create
+                )
+            if self._original_async_create is not None:
+                openai.resources.chat.completions.AsyncCompletions.create = (
+                    self._original_async_create
+                )
+        except ImportError:
+            pass

llm_observatory/pricing.py

@@ -0,0 +1,78 @@
+"""Model pricing table for cost calculation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class ModelPricing:
+    """Pricing for a model (per 1M tokens)."""
+
+    input_per_1m: float
+    output_per_1m: float
+    currency: str = "USD"
+
+
+# Pricing as of July 2026 (approximate)
+MODEL_PRICING: dict[str, ModelPricing] = {
+    # OpenAI models
+    "gpt-4o": ModelPricing(input_per_1m=2.50, output_per_1m=10.00),
+    "gpt-4o-mini": ModelPricing(input_per_1m=0.15, output_per_1m=0.60),
+    "gpt-4-turbo": ModelPricing(input_per_1m=10.00, output_per_1m=30.00),
+    "gpt-4": ModelPricing(input_per_1m=30.00, output_per_1m=60.00),
+    "gpt-3.5-turbo": ModelPricing(input_per_1m=0.50, output_per_1m=1.50),
+    "o1": ModelPricing(input_per_1m=15.00, output_per_1m=60.00),
+    "o1-mini": ModelPricing(input_per_1m=3.00, output_per_1m=12.00),
+    "o3": ModelPricing(input_per_1m=10.00, output_per_1m=40.00),
+    "o3-mini": ModelPricing(input_per_1m=1.10, output_per_1m=4.40),
+    # Anthropic models
+    "claude-4-opus": ModelPricing(input_per_1m=15.00, output_per_1m=75.00),
+    "claude-4-sonnet": ModelPricing(input_per_1m=3.00, output_per_1m=15.00),
+    "claude-3-5-sonnet": ModelPricing(input_per_1m=3.00, output_per_1m=15.00),
+    "claude-3-5-haiku": ModelPricing(input_per_1m=0.80, output_per_1m=4.00),
+    "claude-3-opus": ModelPricing(input_per_1m=15.00, output_per_1m=75.00),
+    "claude-3-sonnet": ModelPricing(input_per_1m=3.00, output_per_1m=15.00),
+    "claude-3-haiku": ModelPricing(input_per_1m=0.25, output_per_1m=1.25),
+    # Google models
+    "gemini-2.0-flash": ModelPricing(input_per_1m=0.10, output_per_1m=0.40),
+    "gemini-2.0-pro": ModelPricing(input_per_1m=1.25, output_per_1m=10.00),
+    "gemini-1.5-pro": ModelPricing(input_per_1m=1.25, output_per_1m=5.00),
+    "gemini-1.5-flash": ModelPricing(input_per_1m=0.075, output_per_1m=0.30),
+}
+
+
+def calculate_cost(
+    model: str,
+    input_tokens: int,
+    output_tokens: int,
+) -> float | None:
+    """Calculate cost for a model invocation.
+
+    Args:
+        model: Model name (e.g., "gpt-4o").
+        input_tokens: Number of input tokens.
+        output_tokens: Number of output tokens.
+
+    Returns:
+        Cost in USD, or None if model pricing is unknown.
+    """
+    pricing = MODEL_PRICING.get(model)
+    if pricing is None:
+        return None
+
+    input_cost = (input_tokens / 1_000_000) * pricing.input_per_1m
+    output_cost = (output_tokens / 1_000_000) * pricing.output_per_1m
+    return input_cost + output_cost
+
+
+def get_model_pricing(model: str) -> ModelPricing | None:
+    """Get pricing for a model.
+
+    Args:
+        model: Model name.
+
+    Returns:
+        ModelPricing or None if unknown.
+    """
+    return MODEL_PRICING.get(model)

llm_observatory/tracer.py

@@ -0,0 +1,379 @@
+"""Core tracing engine for LLM Observatory."""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import logging
+import threading
+import time
+import uuid
+from collections.abc import Callable
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Context variable for current span
+_current_span: ContextVar[Span | None] = ContextVar("current_span", default=None)
+
+
+class SpanStatus(str, Enum):
+    """Status of a span."""
+
+    OK = "ok"
+    ERROR = "error"
+    UNSET = "unset"
+
+
+@dataclass
+class TokenUsage:
+    """Token usage statistics."""
+
+    input: int = 0
+    output: int = 0
+    total: int = 0
+
+
+@dataclass
+class Span:
+    """A single trace span representing an operation."""
+
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    trace_id: str = ""
+    parent_id: str | None = None
+    name: str = ""
+    span_type: str = "generic"
+    start_time: float = field(default_factory=time.time)
+    end_time: float | None = None
+    status: SpanStatus = SpanStatus.UNSET
+    input: dict[str, Any] | None = None
+    output: dict[str, Any] | None = None
+    tokens: TokenUsage | None = None
+    cost_usd: float | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    attributes: dict[str, Any] = field(default_factory=dict)
+
+    def end(self, status: SpanStatus = SpanStatus.OK) -> None:
+        """End the span."""
+        self.end_time = time.time()
+        self.status = status
+
+    def set_status(self, status: SpanStatus) -> None:
+        """Set the span status."""
+        self.status = status
+
+    def set_attribute(self, key: str, value: Any) -> None:
+        """Set a span attribute."""
+        self.attributes[key] = value
+
+    def set_input(self, data: dict[str, Any]) -> None:
+        """Set the span input."""
+        self.input = data
+
+    def set_output(self, data: dict[str, Any]) -> None:
+        """Set the span output."""
+        self.output = data
+
+    def set_token_usage(self, input_tokens: int, output_tokens: int) -> None:
+        """Set token usage for this span."""
+        self.tokens = TokenUsage(
+            input=input_tokens,
+            output=output_tokens,
+            total=input_tokens + output_tokens,
+        )
+
+    def set_cost(self, cost_usd: float) -> None:
+        """Set the cost in USD for this span."""
+        self.cost_usd = cost_usd
+
+    @property
+    def duration_ms(self) -> float | None:
+        """Get duration in milliseconds."""
+        if self.end_time is None:
+            return None
+        return (self.end_time - self.start_time) * 1000
+
+
+class Tracer:
+    """Main tracer class for creating and managing traces."""
+
+    def __init__(
+        self,
+        service_name: str = "llm-observatory",
+        endpoint: str | None = None,
+        api_key: str | None = None,
+        batch_size: int = 10,
+        flush_interval: float = 5.0,
+    ) -> None:
+        """Initialize the tracer.
+
+        Args:
+            service_name: Name of the service being traced.
+            endpoint: Endpoint URL for the observatory backend.
+            api_key: API key for authentication.
+            batch_size: Number of spans to buffer before flushing.
+            flush_interval: Seconds between automatic flushes.
+        """
+        self.service_name = service_name
+        self.endpoint = endpoint
+        self.api_key = api_key
+        self.batch_size = batch_size
+        self.flush_interval = flush_interval
+        self._spans: list[Span] = []
+        self._exporters: list[Any] = []
+        self._buffer: list[dict[str, Any]] = []
+        self._lock = threading.Lock()
+        self._flush_thread: threading.Thread | None = None
+        self._shutdown = False
+
+        # Auto-start flush thread if we have an endpoint
+        if endpoint:
+            self._start_flush_thread()
+
+    def _start_flush_thread(self) -> None:
+        """Start background flush thread."""
+        if self._flush_thread is not None:
+            return
+
+        def flush_loop() -> None:
+            while not self._shutdown:
+                time.sleep(self.flush_interval)
+                try:
+                    self.flush()
+                except Exception as e:
+                    logger.warning(f"Flush failed: {e}")
+
+        self._flush_thread = threading.Thread(target=flush_loop, daemon=True)
+        self._flush_thread.start()
+
+    def add_exporter(self, exporter: Any) -> None:
+        """Add an exporter to the tracer.
+
+        Args:
+            exporter: Exporter instance with an export(spans) method.
+        """
+        self._exporters.append(exporter)
+
+    def start_trace(self, name: str, **attributes: Any) -> Span:
+        """Start a new trace.
+
+        Args:
+            name: Name of the trace.
+            **attributes: Additional attributes for the trace.
+
+        Returns:
+            The root span of the trace.
+        """
+        span = Span(
+            trace_id=str(uuid.uuid4()),
+            name=name,
+            span_type="trace",
+            attributes=attributes,
+        )
+        self._spans.append(span)
+
+        # Auto-export if we have exporters
+        if self._exporters:
+            span_dict = self._span_to_dict(span)
+            with self._lock:
+                self._buffer.append(span_dict)
+                if len(self._buffer) >= self.batch_size:
+                    self._flush_buffer()
+
+        return span
+
+    def start_span(
+        self,
+        name: str,
+        span_type: str = "generic",
+        parent: Span | None = None,
+        **attributes: Any,
+    ) -> Span:
+        """Start a new span.
+
+        Args:
+            name: Name of the span.
+            span_type: Type of span (e.g., "llm", "tool", "agent").
+            parent: Parent span (defaults to current span).
+            **attributes: Additional attributes for the span.
+
+        Returns:
+            The new span.
+        """
+        parent_span = parent or _current_span.get()
+        span = Span(
+            trace_id=parent_span.trace_id if parent_span else str(uuid.uuid4()),
+            parent_id=parent_span.id if parent_span else None,
+            name=name,
+            span_type=span_type,
+            attributes=attributes,
+        )
+        self._spans.append(span)
+
+        # Auto-export if we have exporters
+        if self._exporters:
+            span_dict = self._span_to_dict(span)
+            with self._lock:
+                self._buffer.append(span_dict)
+                if len(self._buffer) >= self.batch_size:
+                    self._flush_buffer()
+
+        return span
+
+    def _span_to_dict(self, span: Span) -> dict[str, Any]:
+        """Convert a span to a dictionary for export."""
+        return {
+            "id": span.id,
+            "trace_id": span.trace_id,
+            "parent_id": span.parent_id,
+            "name": span.name,
+            "span_type": span.span_type,
+            "start_time": span.start_time,
+            "end_time": span.end_time,
+            "status": span.status.value,
+            "input": span.input,
+            "output": span.output,
+            "tokens_input": span.tokens.input if span.tokens else None,
+            "tokens_output": span.tokens.output if span.tokens else None,
+            "cost_usd": span.cost_usd,
+            "metadata": span.metadata,
+            "attributes": span.attributes,
+        }
+
+    def export(self) -> list[dict[str, Any]]:
+        """Export all spans as dictionaries.
+
+        Returns:
+            List of span dictionaries.
+        """
+        return [self._span_to_dict(span) for span in self._spans]
+
+    def flush(self) -> None:
+        """Flush buffered spans to exporters."""
+        with self._lock:
+            if not self._buffer:
+                return
+            spans_to_export = self._buffer.copy()
+            self._buffer.clear()
+
+        for exporter in self._exporters:
+            try:
+                exporter.export(spans_to_export)
+            except Exception as e:
+                logger.warning(f"Exporter failed: {e}")
+
+    def _flush_buffer(self) -> None:
+        """Flush buffer (must hold lock)."""
+        if not self._buffer:
+            return
+        spans_to_export = self._buffer.copy()
+        self._buffer.clear()
+
+        for exporter in self._exporters:
+            try:
+                exporter.export(spans_to_export)
+            except Exception as e:
+                logger.warning(f"Exporter failed: {e}")
+
+    def clear(self) -> None:
+        """Clear all collected spans."""
+        self._spans.clear()
+
+    def shutdown(self) -> None:
+        """Shutdown the tracer, flushing any remaining spans."""
+        self._shutdown = True
+        self.flush()
+        for exporter in self._exporters:
+            try:
+                exporter.flush()
+            except Exception:
+                pass
+
+
+def trace(
+    name: str | None = None,
+    span_type: str = "function",
+) -> Callable:
+    """Decorator to trace a function (sync or async).
+
+    Args:
+        name: Name for the trace (defaults to function name).
+        span_type: Type of span.
+
+    Returns:
+        Decorated function.
+    """
+
+    def decorator(func: Callable) -> Callable:
+        span_name = name or func.__name__
+
+        if asyncio.iscoroutinefunction(func):
+            # Async version
+            @functools.wraps(func)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                tracer = _get_global_tracer()
+                span = tracer.start_span(span_name, span_type=span_type)
+                token = _current_span.set(span)
+
+                try:
+                    result = await func(*args, **kwargs)
+                    span.set_status(SpanStatus.OK)
+                    return result
+                except Exception as e:
+                    span.set_status(SpanStatus.ERROR)
+                    span.set_attribute("error.message", str(e))
+                    raise
+                finally:
+                    span.end()
+                    _current_span.reset(token)
+
+            return async_wrapper
+        else:
+            # Sync version
+            @functools.wraps(func)
+            def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+                tracer = _get_global_tracer()
+                span = tracer.start_span(span_name, span_type=span_type)
+                token = _current_span.set(span)
+
+                try:
+                    result = func(*args, **kwargs)
+                    span.set_status(SpanStatus.OK)
+                    return result
+                except Exception as e:
+                    span.set_status(SpanStatus.ERROR)
+                    span.set_attribute("error.message", str(e))
+                    raise
+                finally:
+                    span.end()
+                    _current_span.reset(token)
+
+            return sync_wrapper
+
+    return decorator
+
+
+# Global tracer instance
+_global_tracer: Tracer | None = None
+
+
+def _get_global_tracer() -> Tracer:
+    """Get or create the global tracer instance."""
+    global _global_tracer
+    if _global_tracer is None:
+        _global_tracer = Tracer()
+    return _global_tracer
+
+
+def get_tracer() -> Tracer:
+    """Get the global tracer instance."""
+    return _get_global_tracer()
+
+
+def set_tracer(tracer: Tracer) -> None:
+    """Set the global tracer instance."""
+    global _global_tracer
+    _global_tracer = tracer

magic_lab_observer-0.1.1.dist-info/METADATA

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: magic-lab-observer
+Version: 0.1.1
+Summary: Python SDK for LLM Observatory - Open-source LLM observability
+Project-URL: Homepage, https://github.com/Magic-Lab-Studio/observer
+Project-URL: Repository, https://github.com/Magic-Lab-Studio/observer.git
+Project-URL: Issues, https://github.com/Magic-Lab-Studio/observer/issues
+Author: LLM Observatory Contributors
+License-Expression: Apache-2.0
+Keywords: anthropic,llm,observability,openai,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: all
+Requires-Dist: anthropic>=0.20.0; extra == 'all'
+Requires-Dist: langchain-core>=0.2.0; extra == 'all'
+Requires-Dist: openai>=1.0.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.20.0; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2.0; extra == 'langchain'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# LLM Observatory Python SDK
+
+Open-source LLM observability SDK for tracing and monitoring AI applications.
+
+## Installation
+
+```bash
+pip install magic-lab-observer
+```
+
+With optional integrations:
+
+```bash
+pip install magic-lab-observer[openai,anthropic,langchain]
+```
+
+## Quick Start
+
+The distribution name is `magic-lab-observer`; the stable Python import remains
+`llm_observatory`.
+
+```python
+from llm_observatory import instrument, trace
+
+# Auto-instrument LLM libraries
+instrument(openai=True, anthropic=True)
+
+# Or manually trace functions
+@trace(name="summarize")
+def summarize(text: str):
+    return openai.chat.completions.create(
+        model="gpt-4",
+        messages=[{"role": "user", "content": text}]
+    )
+```
+
+## License
+
+Apache License 2.0

magic_lab_observer-0.1.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+llm_observatory/__init__.py,sha256=t_ADSn7BZjHJLqnk0gOq-VxmhYkIwMM5v63RtI58i2M,686
+llm_observatory/pricing.py,sha256=wdfE-DmDgcsl0ZEKS1BTYbr4UY0eQuKvQyTwh2jwLTY,2756
+llm_observatory/tracer.py,sha256=iI4hd5pSQOtV-W4AtownqG707cuR2kmDilNalVraSow,11396
+llm_observatory/exporters/__init__.py,sha256=mmn_FJyUIXv4zVbDOWtbO372Q3_BmW5ImSfAZ0Cb0Vk,511
+llm_observatory/exporters/otlp.py,sha256=nvJpRqkhnC7SerUXwbT85QqyOOuf6Vyv6SiYDVJHH8M,2979
+llm_observatory/instrumentors/__init__.py,sha256=0MpihCy6fOt9WgfWXhzxD9FG6RPd0AbXIBlaGqfZaKA,1520
+llm_observatory/instrumentors/anthropic.py,sha256=8pD7VYj9g9Pb8o-RzngjA7lnCltFikjWt63i78wxkAA,4801
+llm_observatory/instrumentors/langchain.py,sha256=iKFzDn2ASY0T-7Ot-vXg2p5NIFxRfM4dwoK6ztD_t4k,6176
+llm_observatory/instrumentors/openai.py,sha256=45zJTGOLq4N-hkPsnq3re7dD_Oq_S76mJLTC7BPZUxI,4878
+magic_lab_observer-0.1.1.dist-info/METADATA,sha256=oA_RWE0h9Kl4P5xTDesWzmjoYBmZ_QyjdoHhKj1_uyE,2272
+magic_lab_observer-0.1.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+magic_lab_observer-0.1.1.dist-info/RECORD,,

magic_lab_observer-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any