scope-analytics 0.1.0__py3-none-any.whl

scope_analytics/__init__.py

@@ -0,0 +1,244 @@
+"""
+Scope Analytics - Backend SDK
+AI-powered analytics with automatic LLM conversation tracking
+"""
+
+import atexit
+from typing import Optional
+
+from .config import ScopeConfig
+from .context import ScopeContext
+from .events import EventFormatter
+from .queue import EventQueue
+from .client import ScopeAPIClient
+from .patches.openai_patch import OpenAIPatcher
+from .patches.anthropic_patch import AnthropicPatcher
+from .patches.gemini_patch import GeminiPatcher
+from .middleware import (
+    ScopeSessionMiddleware,
+    FlaskScopeMiddleware,
+    init_flask_session_tracking,
+    DjangoScopeMiddleware,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "ScopeAnalytics",
+    "ScopeContext",
+    "get_sdk_instance",
+    # Middleware exports
+    "ScopeSessionMiddleware",      # For FastAPI/Starlette
+    "FlaskScopeMiddleware",        # For Flask (WSGI wrapper)
+    "init_flask_session_tracking", # For Flask (hooks approach)
+    "DjangoScopeMiddleware",       # For Django
+]
+
+# Global SDK instance reference for middleware access
+# This allows middleware to capture HTTP request events without requiring
+# explicit SDK reference in user code
+_global_sdk_instance: Optional["ScopeAnalytics"] = None
+
+
+def get_sdk_instance() -> Optional["ScopeAnalytics"]:
+    """
+    Get the global SDK instance.
+
+    Returns:
+        ScopeAnalytics instance if initialized, None otherwise
+    """
+    return _global_sdk_instance
+
+
+def _set_sdk_instance(instance: "ScopeAnalytics") -> None:
+    """
+    Set the global SDK instance.
+    Called internally when ScopeAnalytics is initialized.
+    """
+    global _global_sdk_instance
+    _global_sdk_instance = instance
+
+
+class ScopeAnalytics:
+    """
+    Main SDK class for Scope Analytics
+
+    Usage:
+        scope = ScopeAnalytics(api_key="sk_live_...")
+
+        # SDK automatically patches OpenAI, Anthropic, LangChain
+        # All LLM calls are captured and sent to Scope AI
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        endpoint: Optional[str] = None,
+        auto_patch: bool = True,
+        batch_size: int = 10,
+        batch_timeout_seconds: int = 5,
+        max_queue_size: int = 1000,
+        debug: bool = False,
+        environment: Optional[str] = None,
+    ):
+        """
+        Initialize Scope Analytics SDK
+
+        Args:
+            api_key: Secret API key (sk_live_... or sk_test_...)
+            endpoint: API endpoint URL (default: https://api.scopeai.dev)
+            auto_patch: Automatically patch LLM libraries (default: True)
+            batch_size: Events per batch (default: 10)
+            batch_timeout_seconds: Max wait before sending partial batch (default: 5)
+            max_queue_size: Max events to queue (default: 1000)
+            debug: Enable debug logging (default: False)
+            environment: Environment name (default: production)
+        """
+        # Initialize configuration
+        self.config = ScopeConfig(
+            api_key=api_key,
+            endpoint=endpoint,
+            auto_patch=auto_patch,
+            batch_size=batch_size,
+            batch_timeout_seconds=batch_timeout_seconds,
+            max_queue_size=max_queue_size,
+            debug=debug,
+            environment=environment,
+        )
+
+        # Initialize components
+        self.event_formatter = EventFormatter(self.config)
+        self.client = ScopeAPIClient(self.config)
+        self.queue = EventQueue(
+            batch_size=self.config.batch_size,
+            batch_timeout_seconds=self.config.batch_timeout_seconds,
+            max_queue_size=self.config.max_queue_size,
+            flush_callback=self._flush_events,
+            config=self.config,
+        )
+
+        # Initialize patchers
+        self.openai_patcher = OpenAIPatcher(self)
+        self.anthropic_patcher = AnthropicPatcher(self)
+        self.gemini_patcher = GeminiPatcher(self)
+        self.patches = []  # List of successfully applied patches
+
+        # Start queue background thread
+        self.queue.start()
+
+        # Register shutdown hook
+        atexit.register(self.shutdown)
+
+        self.config.log("Scope Analytics SDK initialized")
+        self.config.log(f"Configuration: {self.config.to_dict()}")
+
+        # Register as global instance for middleware access
+        _set_sdk_instance(self)
+
+        # Auto-patch LLM libraries if enabled
+        if self.config.auto_patch:
+            self._apply_patches()
+
+    def _apply_patches(self):
+        """Apply monkey patches to LLM libraries"""
+        self.config.log("Auto-patching enabled - will patch LLM libraries")
+
+        # Patch OpenAI
+        try:
+            import openai
+            self.config.log("OpenAI library detected - patching...")
+            if self.openai_patcher.patch():
+                self.patches.append('openai')
+        except ImportError:
+            self.config.log("OpenAI library not installed - skipping patch")
+
+        # Patch Anthropic
+        try:
+            import anthropic
+            self.config.log("Anthropic library detected - patching...")
+            if self.anthropic_patcher.patch():
+                self.patches.append('anthropic')
+        except ImportError:
+            self.config.log("Anthropic library not installed - skipping patch")
+
+        # Patch Google Gemini
+        try:
+            import google.generativeai
+            self.config.log("Google Generative AI library detected - patching...")
+            if self.gemini_patcher.patch():
+                self.patches.append('gemini')
+        except ImportError:
+            self.config.log("Google Generative AI library not installed - skipping patch")
+
+    def track_event(self, event_type: str, properties: dict):
+        """
+        Manually track an event
+
+        Args:
+            event_type: Type of event (e.g., "llm_call", "external_api_call")
+            properties: Event properties
+        """
+        self.config.log(f"Tracking event: {event_type}")
+
+        # Create event with standard fields
+        event = {
+            "event_type": event_type,
+            "source": self.config.sdk_source,
+            **properties
+        }
+
+        # Validate and enqueue
+        if self.event_formatter.validate_event(event):
+            self.queue.enqueue(event)
+
+    def identify(self, user_id: str, traits: Optional[dict] = None):
+        """
+        Identify a user and optionally set traits
+
+        Args:
+            user_id: Unique user identifier
+            traits: Optional user traits (e.g., email, name, plan)
+        """
+        ScopeContext.set_user_id(user_id)
+        self.config.log(f"Identified user: {user_id}")
+
+        # TODO: Send identify event to API
+        if traits:
+            self.config.log(f"User traits: {traits}")
+
+    def _flush_events(self, events: list):
+        """
+        Callback for flushing events to API
+        Called by event queue when batch is ready
+
+        Args:
+            events: List of events to flush
+        """
+        success = self.client.ship_events(events)
+
+        if not success:
+            self.config.log(f"⚠️ Failed to ship {len(events)} events")
+
+    def shutdown(self):
+        """
+        Gracefully shutdown SDK
+        Flushes remaining events and cleans up resources
+        """
+        self.config.log("Shutting down Scope Analytics SDK...")
+
+        # Stop queue and flush remaining events
+        if self.queue:
+            self.queue.stop()
+
+        # Close HTTP client
+        if self.client:
+            self.client.close()
+
+        # Remove patches
+        if 'openai' in self.patches:
+            self.openai_patcher.unpatch()
+        if 'anthropic' in self.patches:
+            self.anthropic_patcher.unpatch()
+        if 'gemini' in self.patches:
+            self.gemini_patcher.unpatch()
+
+        self.config.log("Scope Analytics SDK shutdown complete")

scope_analytics/auto.py

@@ -0,0 +1,335 @@
+"""
+Auto-instrumentation module for Scope Analytics
+
+Import this module to automatically initialize Scope Analytics
+with configuration from environment variables.
+
+Usage:
+    import scope_analytics.auto  # That's it!
+
+Or via CLI:
+    scope-run python app.py
+
+Environment Variables:
+    SCOPE_API_KEY: Required. Your Scope Analytics API key
+    SCOPE_ENDPOINT: Optional. Custom API endpoint
+    SCOPE_DEBUG: Optional. Set to 'true' for debug logging
+    SCOPE_ENVIRONMENT: Optional. Environment name (default: production)
+"""
+
+import os
+import sys
+import warnings
+import atexit
+
+# Only initialize once
+_initialized = False
+_scope_instance = None
+
+
+def _log(message: str) -> None:
+    """Log a message if debug mode is enabled"""
+    if os.environ.get('SCOPE_DEBUG', '').lower() == 'true':
+        print(f"[Scope SDK] {message}", file=sys.stderr)
+
+
+def _auto_init():
+    """
+    Automatically initialize Scope Analytics from environment variables.
+
+    This function:
+    1. Reads configuration from environment variables
+    2. Initializes ScopeAnalytics with auto-patching enabled
+    3. Sets up auto-middleware injection for known frameworks
+    """
+    global _initialized, _scope_instance
+
+    if _initialized:
+        return _scope_instance
+
+    _initialized = True  # Set early to prevent re-entry
+
+    api_key = os.environ.get('SCOPE_API_KEY')
+
+    if not api_key:
+        # No API key - skip initialization with a warning
+        warnings.warn(
+            "SCOPE_API_KEY not set - Scope Analytics disabled. "
+            "Set SCOPE_API_KEY environment variable to enable tracking.",
+            UserWarning,
+            stacklevel=2
+        )
+        _log("No API key found - instrumentation disabled")
+        return None
+
+    try:
+        from scope_analytics import ScopeAnalytics
+
+        _log("Initializing Scope Analytics...")
+
+        _scope_instance = ScopeAnalytics(
+            api_key=api_key,
+            endpoint=os.environ.get('SCOPE_ENDPOINT'),
+            debug=os.environ.get('SCOPE_DEBUG', '').lower() == 'true',
+            environment=os.environ.get('SCOPE_ENVIRONMENT', 'production'),
+            auto_patch=True,  # Always auto-patch in auto mode
+        )
+
+        _log("Scope Analytics initialized successfully")
+
+        # Auto-inject session middleware for known frameworks
+        _auto_inject_middleware()
+
+        return _scope_instance
+
+    except ValueError as e:
+        # Invalid API key format or missing required config
+        warnings.warn(
+            f"Scope Analytics initialization failed: {e}",
+            UserWarning,
+            stacklevel=2
+        )
+        _log(f"Initialization failed: {e}")
+        return None
+
+    except Exception as e:
+        # Unexpected error - don't crash the user's app
+        warnings.warn(
+            f"Scope Analytics initialization failed unexpectedly: {e}",
+            UserWarning,
+            stacklevel=2
+        )
+        _log(f"Unexpected error during initialization: {e}")
+        return None
+
+
+def _auto_inject_middleware():
+    """
+    Automatically inject session middleware for known frameworks.
+    This happens at RUNTIME - no user code changes required.
+
+    Supports: FastAPI/Starlette, Flask, Django
+
+    The middleware extracts X-Scope-Session-ID headers and makes
+    session correlation work automatically between frontend and backend.
+    """
+    _log("Setting up auto-middleware injection...")
+
+    injected = False
+
+    # Try FastAPI/Starlette
+    if _try_inject_fastapi():
+        _log("Prepared session middleware injection for FastAPI/Starlette")
+        injected = True
+
+    # Try Flask
+    if _try_inject_flask():
+        _log("Prepared session hooks injection for Flask")
+        injected = True
+
+    # Try Django
+    if _try_inject_django():
+        _log("Prepared session middleware injection for Django")
+        injected = True
+
+    if not injected:
+        _log(
+            "No known framework detected - session middleware not auto-injected. "
+            "LLM tracking still works. For session correlation with custom frameworks, "
+            "see docs on manual ScopeContext.set_session_id()"
+        )
+
+
+def _try_inject_fastapi() -> bool:
+    """
+    Inject session middleware into FastAPI/Starlette apps at runtime.
+
+    We patch the __init__ method of FastAPI and Starlette classes
+    so that when the user creates an app, our middleware is automatically added.
+    """
+    patched = False
+
+    # Try patching Starlette first (FastAPI extends it)
+    try:
+        from starlette.applications import Starlette
+
+        if not hasattr(Starlette.__init__, '_scope_patched'):
+            original_starlette_init = Starlette.__init__
+
+            def patched_starlette_init(self, *args, **kwargs):
+                original_starlette_init(self, *args, **kwargs)
+                # Add our middleware after app is initialized
+                try:
+                    from scope_analytics.middleware import ScopeSessionMiddleware
+                    self.add_middleware(ScopeSessionMiddleware)
+                    _log(f"Auto-injected ScopeSessionMiddleware into Starlette app")
+                except Exception as e:
+                    _log(f"Failed to inject middleware into Starlette: {e}")
+
+            patched_starlette_init._scope_patched = True
+            Starlette.__init__ = patched_starlette_init
+            patched = True
+            _log("Patched Starlette.__init__ for auto-middleware injection")
+
+    except ImportError:
+        pass
+
+    # Also patch FastAPI specifically (more common)
+    try:
+        from fastapi import FastAPI
+
+        if not hasattr(FastAPI.__init__, '_scope_patched'):
+            original_fastapi_init = FastAPI.__init__
+
+            def patched_fastapi_init(self, *args, **kwargs):
+                original_fastapi_init(self, *args, **kwargs)
+                # Add our middleware after app is initialized
+                try:
+                    from scope_analytics.middleware import ScopeSessionMiddleware
+                    # Check if middleware already added (from Starlette patch)
+                    has_scope_middleware = any(
+                        getattr(m, 'cls', None) == ScopeSessionMiddleware
+                        for m in getattr(self, 'user_middleware', [])
+                    )
+                    if not has_scope_middleware:
+                        self.add_middleware(ScopeSessionMiddleware)
+                        _log(f"Auto-injected ScopeSessionMiddleware into FastAPI app")
+                except Exception as e:
+                    _log(f"Failed to inject middleware into FastAPI: {e}")
+
+            patched_fastapi_init._scope_patched = True
+            FastAPI.__init__ = patched_fastapi_init
+            patched = True
+            _log("Patched FastAPI.__init__ for auto-middleware injection")
+
+    except ImportError:
+        pass
+
+    return patched
+
+
+def _try_inject_flask() -> bool:
+    """
+    Inject session hooks into Flask apps at runtime.
+
+    We patch Flask's __init__ to register before/after request hooks
+    that handle session ID extraction.
+    """
+    try:
+        from flask import Flask
+
+        if hasattr(Flask.__init__, '_scope_patched'):
+            return True
+
+        original_flask_init = Flask.__init__
+
+        def patched_flask_init(self, *args, **kwargs):
+            original_flask_init(self, *args, **kwargs)
+            # Register session tracking hooks after app is created
+            try:
+                from scope_analytics.middleware import init_flask_session_tracking
+                init_flask_session_tracking(self)
+                _log(f"Auto-injected session hooks into Flask app")
+            except Exception as e:
+                _log(f"Failed to inject session hooks into Flask: {e}")
+
+        patched_flask_init._scope_patched = True
+        Flask.__init__ = patched_flask_init
+        _log("Patched Flask.__init__ for auto-middleware injection")
+        return True
+
+    except ImportError:
+        return False
+
+
+def _try_inject_django() -> bool:
+    """
+    Inject session middleware into Django apps at runtime.
+
+    Django is trickier - middleware is configured in settings.py.
+    We hook into Django's setup to add our middleware.
+    """
+    try:
+        import django
+        from django.conf import settings
+
+        # Check if Django is configured
+        if not settings.configured:
+            # Django not configured yet - set up a hook for when it is
+            _log("Django detected but not configured - deferring middleware injection")
+
+            # We can hook into django.setup() to add middleware when called
+            if not hasattr(django.setup, '_scope_patched'):
+                original_setup = django.setup
+
+                def patched_setup(*args, **kwargs):
+                    result = original_setup(*args, **kwargs)
+                    _inject_django_middleware()
+                    return result
+
+                patched_setup._scope_patched = True
+                django.setup = patched_setup
+                _log("Patched django.setup() for deferred middleware injection")
+
+            return True
+
+        # Django is already configured - inject middleware now
+        return _inject_django_middleware()
+
+    except ImportError:
+        return False
+    except Exception as e:
+        _log(f"Error setting up Django middleware injection: {e}")
+        return False
+
+
+def _inject_django_middleware() -> bool:
+    """
+    Actually inject the middleware into Django's MIDDLEWARE setting.
+    """
+    try:
+        from django.conf import settings
+
+        if not settings.configured:
+            return False
+
+        middleware_class = 'scope_analytics.middleware.DjangoScopeMiddleware'
+
+        if hasattr(settings, 'MIDDLEWARE'):
+            middleware_list = list(settings.MIDDLEWARE)
+            if middleware_class not in middleware_list:
+                # Insert at the beginning for earliest access to request
+                middleware_list.insert(0, middleware_class)
+                settings.MIDDLEWARE = middleware_list
+                _log(f"Auto-injected {middleware_class} into Django MIDDLEWARE")
+            return True
+
+        return False
+
+    except Exception as e:
+        _log(f"Failed to inject Django middleware: {e}")
+        return False
+
+
+def get_instance():
+    """
+    Get the auto-initialized ScopeAnalytics instance.
+
+    Returns:
+        ScopeAnalytics instance or None if not initialized
+    """
+    return _scope_instance
+
+
+def is_initialized() -> bool:
+    """
+    Check if auto-instrumentation has been initialized.
+
+    Returns:
+        True if initialized, False otherwise
+    """
+    return _initialized and _scope_instance is not None
+
+
+# Auto-initialize on import
+_auto_init()