scope-analytics 0.1.0__py3-none-any.whl

scope_analytics/cli.py

@@ -0,0 +1,240 @@
+#!/usr/bin/env python
+"""
+scope-run: No-code instrumentation CLI for Scope Analytics
+
+Usage:
+    scope-run python app.py
+    scope-run uvicorn main:app --reload
+    scope-run gunicorn app:app -w 4
+    scope-run flask run --port 5000
+    scope-run celery -A tasks worker
+
+This CLI wrapper automatically instruments your Python application
+with Scope Analytics tracking - no code changes required.
+
+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 subprocess
+import argparse
+import tempfile
+import atexit
+from typing import List, Optional
+
+# Track temp files for cleanup
+_temp_files: List[str] = []
+
+
+def _cleanup_temp_files():
+    """Clean up temporary bootstrap files on exit"""
+    for path in _temp_files:
+        try:
+            os.unlink(path)
+        except (OSError, FileNotFoundError):
+            pass
+
+
+atexit.register(_cleanup_temp_files)
+
+
+def _create_bootstrap_file() -> str:
+    """
+    Create a temporary bootstrap file that imports scope_analytics.auto
+
+    This file is used for PYTHONSTARTUP to ensure instrumentation
+    happens before the user's code runs.
+    """
+    bootstrap_code = '''# Scope Analytics Auto-Bootstrap
+import os
+if os.environ.get('SCOPE_AUTO_INSTRUMENT') == 'true':
+    try:
+        import scope_analytics.auto
+    except Exception as e:
+        import sys
+        print(f"[Scope SDK] Warning: Auto-instrumentation failed: {e}", file=sys.stderr)
+'''
+
+    fd, path = tempfile.mkstemp(suffix='.py', prefix='scope_bootstrap_')
+    with os.fdopen(fd, 'w') as f:
+        f.write(bootstrap_code)
+
+    _temp_files.append(path)
+    return path
+
+
+def _create_sitecustomize_dir() -> str:
+    """
+    Create a temporary directory with sitecustomize.py for auto-instrumentation.
+
+    sitecustomize.py is automatically imported by Python at startup,
+    making it ideal for pre-application instrumentation.
+    """
+    import tempfile
+
+    # Create temp directory
+    temp_dir = tempfile.mkdtemp(prefix='scope_site_')
+    _temp_files.append(temp_dir)
+
+    # Create sitecustomize.py
+    sitecustomize_path = os.path.join(temp_dir, 'sitecustomize.py')
+    sitecustomize_code = '''# Scope Analytics Sitecustomize
+import os
+if os.environ.get('SCOPE_AUTO_INSTRUMENT') == 'true':
+    try:
+        import scope_analytics.auto
+    except ImportError:
+        pass  # scope-analytics not installed, skip silently
+    except Exception as e:
+        import sys
+        print(f"[Scope SDK] Warning: Auto-instrumentation failed: {e}", file=sys.stderr)
+'''
+
+    with open(sitecustomize_path, 'w') as f:
+        f.write(sitecustomize_code)
+
+    return temp_dir
+
+
+def _get_version() -> str:
+    """Get the SDK version"""
+    try:
+        from scope_analytics import __version__
+        return __version__
+    except ImportError:
+        return "unknown"
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    """
+    Main entry point for scope-run CLI
+
+    Args:
+        argv: Command line arguments (defaults to sys.argv[1:])
+
+    Returns:
+        Exit code from the wrapped command
+    """
+    parser = argparse.ArgumentParser(
+        prog='scope-run',
+        description='Run Python application with Scope Analytics auto-instrumentation',
+        epilog='''
+Examples:
+  scope-run python app.py              # Run a Python script
+  scope-run uvicorn main:app --reload  # Run uvicorn server
+  scope-run gunicorn app:app -w 4      # Run gunicorn server
+  scope-run flask run --port 5000      # Run Flask dev server
+  scope-run python -m mypackage        # Run a module
+
+Environment Variables:
+  SCOPE_API_KEY      Your Scope Analytics API key (required)
+  SCOPE_ENDPOINT     Custom API endpoint (optional)
+  SCOPE_DEBUG        Set to 'true' for debug logging
+  SCOPE_ENVIRONMENT  Environment name (default: production)
+''',
+        formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+
+    parser.add_argument(
+        '--version', '-v',
+        action='store_true',
+        help='Show version and exit'
+    )
+
+    parser.add_argument(
+        '--debug', '-d',
+        action='store_true',
+        help='Enable debug logging'
+    )
+
+    parser.add_argument(
+        '--dry-run',
+        action='store_true',
+        help='Show what would be executed without running'
+    )
+
+    parser.add_argument(
+        'command',
+        nargs=argparse.REMAINDER,
+        help='Command to run (e.g., python app.py, uvicorn main:app)'
+    )
+
+    args = parser.parse_args(argv)
+
+    # Handle --version
+    if args.version:
+        print(f"scope-analytics {_get_version()}")
+        return 0
+
+    # Require a command
+    if not args.command:
+        parser.print_help()
+        print("\nError: No command specified. Usage: scope-run python app.py", file=sys.stderr)
+        return 1
+
+    # Check for API key
+    api_key = os.environ.get('SCOPE_API_KEY')
+    if not api_key:
+        print("[Scope SDK] Warning: SCOPE_API_KEY not set. Instrumentation will be disabled.", file=sys.stderr)
+        print("[Scope SDK] Set your API key: export SCOPE_API_KEY='sk_live_...'", file=sys.stderr)
+
+    # Set up environment for auto-instrumentation
+    env = os.environ.copy()
+    env['SCOPE_AUTO_INSTRUMENT'] = 'true'
+
+    if args.debug:
+        env['SCOPE_DEBUG'] = 'true'
+
+    # Determine the best injection strategy based on the command
+    command = args.command
+    executable = command[0] if command else ''
+
+    # Use sitecustomize approach - works with all Python programs
+    site_dir = _create_sitecustomize_dir()
+
+    # Prepend to PYTHONPATH so sitecustomize.py is found
+    existing_path = env.get('PYTHONPATH', '')
+    if existing_path:
+        env['PYTHONPATH'] = f"{site_dir}{os.pathsep}{existing_path}"
+    else:
+        env['PYTHONPATH'] = site_dir
+
+    # Build the final command
+    final_command = command
+
+    if args.dry_run:
+        print("[Scope SDK] Dry run - would execute:")
+        print(f"  SCOPE_AUTO_INSTRUMENT=true")
+        print(f"  PYTHONPATH={env['PYTHONPATH']}")
+        if args.debug:
+            print(f"  SCOPE_DEBUG=true")
+        print(f"  {' '.join(final_command)}")
+        return 0
+
+    # Print startup message if debug enabled
+    if args.debug or env.get('SCOPE_DEBUG', '').lower() == 'true':
+        print(f"[Scope SDK] Starting with auto-instrumentation...")
+        print(f"[Scope SDK] Command: {' '.join(final_command)}")
+
+    # Execute the wrapped command
+    try:
+        result = subprocess.run(final_command, env=env)
+        return result.returncode
+    except FileNotFoundError:
+        print(f"[Scope SDK] Error: Command not found: {executable}", file=sys.stderr)
+        return 127
+    except KeyboardInterrupt:
+        print("\n[Scope SDK] Interrupted")
+        return 130
+    except Exception as e:
+        print(f"[Scope SDK] Error executing command: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())

scope_analytics/client.py

@@ -0,0 +1,121 @@
+"""
+HTTP client for shipping events to Scope Analytics API
+Handles async communication with the backend API
+"""
+
+import httpx
+from typing import List, Dict, Any
+
+
+class ScopeAPIClient:
+    """
+    Async HTTP client for Scope Analytics API
+
+    Handles:
+    - Event shipping to /api/events endpoint
+    - Authentication with secret API key
+    - Retry logic with exponential backoff
+    - Error handling
+    """
+
+    def __init__(self, config):
+        """
+        Initialize API client
+
+        Args:
+            config: SDK configuration
+        """
+        self.config = config
+        self.endpoint = f"{config.endpoint}/api/events"
+
+        # Create HTTP client
+        self.client = httpx.Client(
+            timeout=30.0,
+            headers={
+                "Authorization": f"Bearer {config.api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": f"scope-analytics-python/{config.sdk_version}",
+            }
+        )
+
+        self.config.log(f"API client initialized: {self.endpoint}")
+
+    def ship_events(self, events: List[Dict[str, Any]]) -> bool:
+        """
+        Ship batch of events to API
+
+        Args:
+            events: List of event dictionaries
+
+        Returns:
+            True if successful, False otherwise
+        """
+        if not events:
+            return True
+
+        try:
+            self.config.log(f"Shipping {len(events)} events to {self.endpoint}")
+
+            # Prepare payload
+            payload = {
+                "events": events,
+                "source": self.config.sdk_source,
+            }
+
+            # Send POST request
+            response = self.client.post(
+                self.endpoint,
+                json=payload
+            )
+
+            # Check response
+            if response.status_code == 200:
+                self.config.log(f"✅ Successfully shipped {len(events)} events")
+                return True
+            else:
+                self.config.log(
+                    f"❌ Failed to ship events: HTTP {response.status_code} - {response.text}"
+                )
+                return False
+
+        except httpx.TimeoutException:
+            self.config.log("❌ Request timeout while shipping events")
+            return False
+
+        except httpx.HTTPError as e:
+            self.config.log(f"❌ HTTP error while shipping events: {e}")
+            return False
+
+        except Exception as e:
+            self.config.log(f"❌ Unexpected error while shipping events: {e}")
+            return False
+
+    def test_connection(self) -> bool:
+        """
+        Test connection to API
+
+        Returns:
+            True if connection successful, False otherwise
+        """
+        try:
+            self.config.log("Testing API connection...")
+
+            # Simple health check (could be a ping endpoint)
+            # For now, just verify we can reach the endpoint
+            response = self.client.get(f"{self.config.endpoint}/health")
+
+            if response.status_code == 200:
+                self.config.log("✅ API connection successful")
+                return True
+            else:
+                self.config.log(f"⚠️ API returned status {response.status_code}")
+                return False
+
+        except Exception as e:
+            self.config.log(f"⚠️ Could not connect to API: {e}")
+            return False
+
+    def close(self):
+        """Close HTTP client"""
+        self.client.close()
+        self.config.log("API client closed")

scope_analytics/config.py

@@ -0,0 +1,101 @@
+"""
+Configuration management for Scope Analytics SDK
+"""
+
+import os
+from typing import Optional, Dict, Any
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv()
+
+
+class ScopeConfig:
+    """Configuration for Scope Analytics SDK"""
+
+    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,
+        redact_patterns: Optional[list] = None,
+    ):
+        """
+        Initialize Scope SDK configuration
+
+        Args:
+            api_key: Secret API key (sk_live_... or sk_test_...)
+            endpoint: API endpoint URL
+            auto_patch: Whether to automatically patch LLM libraries
+            batch_size: Number of events to batch before sending
+            batch_timeout_seconds: Maximum time to wait before sending partial batch
+            max_queue_size: Maximum events to queue (oldest dropped if exceeded)
+            debug: Enable debug logging
+            environment: Environment name (production, staging, development)
+            redact_patterns: List of regex patterns to redact from events
+        """
+        # API Key - required
+        self.api_key = api_key or os.getenv("SCOPE_API_KEY")
+        if not self.api_key:
+            raise ValueError(
+                "API key is required. Pass api_key parameter or set SCOPE_API_KEY environment variable."
+            )
+
+        # Validate API key format
+        if not (self.api_key.startswith("sk_live_") or self.api_key.startswith("sk_test_")):
+            raise ValueError(
+                "Invalid API key format. Backend SDK requires secret keys starting with 'sk_live_' or 'sk_test_'."
+            )
+
+        # Endpoint
+        self.endpoint = endpoint or os.getenv(
+            "SCOPE_ENDPOINT",
+            "https://api.scopeai.dev"
+        )
+
+        # Patching
+        self.auto_patch = auto_patch
+
+        # Batching
+        self.batch_size = batch_size
+        self.batch_timeout_seconds = batch_timeout_seconds
+        self.max_queue_size = max_queue_size
+
+        # Environment
+        self.debug = debug or os.getenv("SCOPE_DEBUG", "").lower() == "true"
+        self.environment = environment or os.getenv("SCOPE_ENVIRONMENT", "production")
+
+        # Privacy
+        self.redact_patterns = redact_patterns or [
+            r"password\s*=\s*['\"]?([^'\">\s]+)",
+            r"api[_-]?key\s*=\s*['\"]?([^'\">\s]+)",
+            r"token\s*=\s*['\"]?([^'\">\s]+)",
+            r"secret\s*=\s*['\"]?([^'\">\s]+)",
+        ]
+
+        # SDK metadata
+        self.sdk_version = "0.1.0"
+        self.sdk_source = "backend_sdk"
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert config to dictionary"""
+        return {
+            "endpoint": self.endpoint,
+            "auto_patch": self.auto_patch,
+            "batch_size": self.batch_size,
+            "batch_timeout_seconds": self.batch_timeout_seconds,
+            "max_queue_size": self.max_queue_size,
+            "debug": self.debug,
+            "environment": self.environment,
+            "sdk_version": self.sdk_version,
+        }
+
+    def log(self, message: str):
+        """Log debug message if debug mode enabled"""
+        if self.debug:
+            print(f"[Scope SDK] {message}")

scope_analytics/context.py

@@ -0,0 +1,173 @@
+"""
+Context management for Scope Analytics SDK using contextvars
+Handles session ID propagation across async boundaries
+"""
+
+import contextvars
+from typing import Optional
+from contextlib import contextmanager
+import uuid
+
+# Context variables for tracking current request context
+session_id_context: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
+    'scope_session_id', default=None
+)
+
+user_id_context: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
+    'scope_user_id', default=None
+)
+
+# Recursion guard - prevents infinite loops when Scope tracks its own LLM calls
+# This is critical when Scope AI backend uses Scope SDK to track itself
+_in_scope_context: contextvars.ContextVar[bool] = contextvars.ContextVar(
+    'scope_in_scope_context', default=False
+)
+
+
+class ScopeContext:
+    """
+    Manages request-scoped context using Python's contextvars.
+
+    This ensures session IDs are properly isolated across concurrent requests
+    and propagated through async operations.
+    """
+
+    @staticmethod
+    def set_session_id(session_id: str) -> None:
+        """
+        Set the session ID for the current context
+
+        Args:
+            session_id: Session ID from X-Scope-Session-ID header
+        """
+        session_id_context.set(session_id)
+
+    @staticmethod
+    def get_session_id() -> Optional[str]:
+        """
+        Get the session ID from current context
+
+        Returns:
+            Session ID if set, None otherwise
+        """
+        return session_id_context.get()
+
+    @staticmethod
+    def set_user_id(user_id: str) -> None:
+        """
+        Set the user ID for the current context
+
+        Args:
+            user_id: User ID from backend application
+        """
+        user_id_context.set(user_id)
+
+    @staticmethod
+    def get_user_id() -> Optional[str]:
+        """
+        Get the user ID from current context
+
+        Returns:
+            User ID if set, None otherwise
+        """
+        return user_id_context.get()
+
+    @staticmethod
+    def clear() -> None:
+        """
+        Clear all context variables
+        Should be called after request completes to prevent leaks
+        """
+        session_id_context.set(None)
+        user_id_context.set(None)
+
+    @staticmethod
+    def generate_temp_session_id() -> str:
+        """
+        Generate a temporary session ID for requests without X-Scope-Session-ID header
+
+        Returns:
+            Temporary session ID with 'temp_' prefix
+        """
+        return f"temp_{uuid.uuid4().hex[:16]}"
+
+    @staticmethod
+    def ensure_session_id() -> str:
+        """
+        Get session ID from context, or generate temporary one if missing
+
+        Returns:
+            Session ID (either from context or temporary)
+        """
+        session_id = session_id_context.get()
+        if not session_id:
+            session_id = ScopeContext.generate_temp_session_id()
+            session_id_context.set(session_id)
+        return session_id
+
+    @staticmethod
+    def get_context_dict() -> dict:
+        """
+        Get all context variables as dictionary
+
+        Returns:
+            Dictionary with current context values
+        """
+        return {
+            "session_id": session_id_context.get(),
+            "user_id": user_id_context.get(),
+        }
+
+    # =========================================================================
+    # Recursion Guard - Prevents infinite loops when Scope tracks itself
+    # =========================================================================
+
+    @staticmethod
+    def is_in_scope_context() -> bool:
+        """
+        Check if we're currently inside Scope SDK code.
+
+        This prevents infinite recursion when:
+        1. Scope backend uses OpenAI for embeddings
+        2. Scope backend has Scope SDK installed
+        3. Without this guard, embedding calls would be captured → sent to API → trigger more embeddings
+
+        Returns:
+            True if inside Scope context, False otherwise
+        """
+        return _in_scope_context.get()
+
+    @staticmethod
+    def enter_scope_context() -> None:
+        """
+        Mark that we're entering Scope SDK internal code.
+        LLM calls made while in this context will NOT be captured.
+        """
+        _in_scope_context.set(True)
+
+    @staticmethod
+    def exit_scope_context() -> None:
+        """
+        Mark that we're exiting Scope SDK internal code.
+        """
+        _in_scope_context.set(False)
+
+    @staticmethod
+    @contextmanager
+    def scope_internal():
+        """
+        Context manager for Scope internal operations.
+
+        Usage:
+            with ScopeContext.scope_internal():
+                # LLM calls here will NOT be tracked
+                embedding = openai.embeddings.create(...)
+
+        This is used by Scope's own backend to prevent recursion.
+        """
+        previous = _in_scope_context.get()
+        _in_scope_context.set(True)
+        try:
+            yield
+        finally:
+            _in_scope_context.set(previous)