graphiti-core 0.12.0rc1__py3-none-any.whl → 0.24.3__py3-none-any.whl

graphiti_core/telemetry/__init__.py

@@ -0,0 +1,9 @@
+"""
+Telemetry module for Graphiti.
+
+This module provides anonymous usage analytics to help improve Graphiti.
+"""
+
+from .telemetry import capture_event, is_telemetry_enabled
+
+__all__ = ['capture_event', 'is_telemetry_enabled']

graphiti_core/telemetry/telemetry.py

@@ -0,0 +1,117 @@
+"""
+Telemetry client for Graphiti.
+
+Collects anonymous usage statistics to help improve the product.
+"""
+
+import contextlib
+import os
+import platform
+import sys
+import uuid
+from pathlib import Path
+from typing import Any
+
+# PostHog configuration
+# Note: This is a public API key intended for client-side use and safe to commit
+# PostHog public keys are designed to be exposed in client applications
+POSTHOG_API_KEY = 'phc_UG6EcfDbuXz92neb3rMlQFDY0csxgMqRcIPWESqnSmo'
+POSTHOG_HOST = 'https://us.i.posthog.com'
+
+# Environment variable to control telemetry
+TELEMETRY_ENV_VAR = 'GRAPHITI_TELEMETRY_ENABLED'
+
+# Cache directory for anonymous ID
+CACHE_DIR = Path.home() / '.cache' / 'graphiti'
+ANON_ID_FILE = CACHE_DIR / 'telemetry_anon_id'
+
+
+def is_telemetry_enabled() -> bool:
+    """Check if telemetry is enabled."""
+    # Disable during pytest runs
+    if 'pytest' in sys.modules:
+        return False
+
+    # Check environment variable (default: enabled)
+    env_value = os.environ.get(TELEMETRY_ENV_VAR, 'true').lower()
+    return env_value in ('true', '1', 'yes', 'on')
+
+
+def get_anonymous_id() -> str:
+    """Get or create anonymous user ID."""
+    try:
+        # Create cache directory if it doesn't exist
+        CACHE_DIR.mkdir(parents=True, exist_ok=True)
+
+        # Try to read existing ID
+        if ANON_ID_FILE.exists():
+            try:
+                return ANON_ID_FILE.read_text().strip()
+            except Exception:
+                pass
+
+        # Generate new ID
+        anon_id = str(uuid.uuid4())
+
+        # Save to file
+        with contextlib.suppress(Exception):
+            ANON_ID_FILE.write_text(anon_id)
+
+        return anon_id
+    except Exception:
+        return 'UNKNOWN'
+
+
+def get_graphiti_version() -> str:
+    """Get Graphiti version."""
+    try:
+        # Try to get version from package metadata
+        import importlib.metadata
+
+        return importlib.metadata.version('graphiti-core')
+    except Exception:
+        return 'unknown'
+
+
+def initialize_posthog():
+    """Initialize PostHog client."""
+    try:
+        import posthog
+
+        posthog.api_key = POSTHOG_API_KEY
+        posthog.host = POSTHOG_HOST
+        return posthog
+    except ImportError:
+        # PostHog not installed, silently disable telemetry
+        return None
+    except Exception:
+        # Any other error, silently disable telemetry
+        return None
+
+
+def capture_event(event_name: str, properties: dict[str, Any] | None = None) -> None:
+    """Capture a telemetry event."""
+    if not is_telemetry_enabled():
+        return
+
+    try:
+        posthog_client = initialize_posthog()
+        if posthog_client is None:
+            return
+
+        # Get anonymous ID
+        user_id = get_anonymous_id()
+
+        # Prepare event properties
+        event_properties = {
+            '$process_person_profile': False,
+            'graphiti_version': get_graphiti_version(),
+            'architecture': platform.machine(),
+            **(properties or {}),
+        }
+
+        # Capture the event
+        posthog_client.capture(distinct_id=user_id, event=event_name, properties=event_properties)
+    except Exception:
+        # Silently handle all telemetry errors to avoid disrupting the main application
+        pass

graphiti_core/tracer.py

@@ -0,0 +1,193 @@
+"""
+Copyright 2024, Zep Software, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+from abc import ABC, abstractmethod
+from collections.abc import Generator
+from contextlib import AbstractContextManager, contextmanager, suppress
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from opentelemetry.trace import Span, StatusCode
+
+try:
+    from opentelemetry.trace import Span, StatusCode
+
+    OTEL_AVAILABLE = True
+except ImportError:
+    OTEL_AVAILABLE = False
+
+
+class TracerSpan(ABC):
+    """Abstract base class for tracer spans."""
+
+    @abstractmethod
+    def add_attributes(self, attributes: dict[str, Any]) -> None:
+        """Add attributes to the span."""
+        pass
+
+    @abstractmethod
+    def set_status(self, status: str, description: str | None = None) -> None:
+        """Set the status of the span."""
+        pass
+
+    @abstractmethod
+    def record_exception(self, exception: Exception) -> None:
+        """Record an exception in the span."""
+        pass
+
+
+class Tracer(ABC):
+    """Abstract base class for tracers."""
+
+    @abstractmethod
+    def start_span(self, name: str) -> AbstractContextManager[TracerSpan]:
+        """Start a new span with the given name."""
+        pass
+
+
+class NoOpSpan(TracerSpan):
+    """No-op span implementation that does nothing."""
+
+    def add_attributes(self, attributes: dict[str, Any]) -> None:
+        pass
+
+    def set_status(self, status: str, description: str | None = None) -> None:
+        pass
+
+    def record_exception(self, exception: Exception) -> None:
+        pass
+
+
+class NoOpTracer(Tracer):
+    """No-op tracer implementation that does nothing."""
+
+    @contextmanager
+    def start_span(self, name: str) -> Generator[NoOpSpan, None, None]:
+        """Return a no-op span."""
+        yield NoOpSpan()
+
+
+class OpenTelemetrySpan(TracerSpan):
+    """Wrapper for OpenTelemetry span."""
+
+    def __init__(self, span: 'Span'):
+        self._span = span
+
+    def add_attributes(self, attributes: dict[str, Any]) -> None:
+        """Add attributes to the OpenTelemetry span."""
+        try:
+            # Filter out None values and convert all values to appropriate types
+            filtered_attrs = {}
+            for key, value in attributes.items():
+                if value is not None:
+                    # Convert to string if not a primitive type
+                    if isinstance(value, str | int | float | bool):
+                        filtered_attrs[key] = value
+                    else:
+                        filtered_attrs[key] = str(value)
+
+            if filtered_attrs:
+                self._span.set_attributes(filtered_attrs)
+        except Exception:
+            # Silently ignore tracing errors
+            pass
+
+    def set_status(self, status: str, description: str | None = None) -> None:
+        """Set the status of the OpenTelemetry span."""
+        try:
+            if OTEL_AVAILABLE:
+                if status == 'error':
+                    self._span.set_status(StatusCode.ERROR, description)
+                elif status == 'ok':
+                    self._span.set_status(StatusCode.OK, description)
+        except Exception:
+            # Silently ignore tracing errors
+            pass
+
+    def record_exception(self, exception: Exception) -> None:
+        """Record an exception in the OpenTelemetry span."""
+        with suppress(Exception):
+            self._span.record_exception(exception)
+
+
+class OpenTelemetryTracer(Tracer):
+    """Wrapper for OpenTelemetry tracer with configurable span name prefix."""
+
+    def __init__(self, tracer: Any, span_prefix: str = 'graphiti'):
+        """
+        Initialize the OpenTelemetry tracer wrapper.
+
+        Parameters
+        ----------
+        tracer : opentelemetry.trace.Tracer
+            The OpenTelemetry tracer instance.
+        span_prefix : str, optional
+            Prefix to prepend to all span names. Defaults to 'graphiti'.
+        """
+        if not OTEL_AVAILABLE:
+            raise ImportError(
+                'OpenTelemetry is not installed. Install it with: pip install opentelemetry-api'
+            )
+        self._tracer = tracer
+        self._span_prefix = span_prefix.rstrip('.')
+
+    @contextmanager
+    def start_span(self, name: str) -> Generator[OpenTelemetrySpan | NoOpSpan, None, None]:
+        """Start a new OpenTelemetry span with the configured prefix."""
+        try:
+            full_name = f'{self._span_prefix}.{name}'
+            with self._tracer.start_as_current_span(full_name) as span:
+                yield OpenTelemetrySpan(span)
+        except Exception:
+            # If tracing fails, yield a no-op span to prevent breaking the operation
+            yield NoOpSpan()
+
+
+def create_tracer(otel_tracer: Any | None = None, span_prefix: str = 'graphiti') -> Tracer:
+    """
+    Create a tracer instance.
+
+    Parameters
+    ----------
+    otel_tracer : opentelemetry.trace.Tracer | None, optional
+        An OpenTelemetry tracer instance. If None, a no-op tracer is returned.
+    span_prefix : str, optional
+        Prefix to prepend to all span names. Defaults to 'graphiti'.
+
+    Returns
+    -------
+    Tracer
+        A tracer instance (either OpenTelemetryTracer or NoOpTracer).
+
+    Examples
+    --------
+    Using with OpenTelemetry:
+
+    >>> from opentelemetry import trace
+    >>> otel_tracer = trace.get_tracer(__name__)
+    >>> tracer = create_tracer(otel_tracer, span_prefix='myapp.graphiti')
+
+    Using no-op tracer:
+
+    >>> tracer = create_tracer()  # Returns NoOpTracer
+    """
+    if otel_tracer is None:
+        return NoOpTracer()
+
+    if not OTEL_AVAILABLE:
+        return NoOpTracer()
+
+    return OpenTelemetryTracer(otel_tracer, span_prefix)