scope-analytics 0.1.1__tar.gz → 0.1.3__tar.gz

{scope_analytics-0.1.1/scope_analytics.egg-info → scope_analytics-0.1.3}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: scope-analytics
-Version: 0.1.1
+Version: 0.1.3
 Summary: AI-powered analytics SDK for backend applications with automatic LLM tracking
-Home-page: https://github.com/scopeai/scope-analytics-python
+Home-page: https://scopeai.dev
 Author: Scope AI
 Author-email: support@scopeai.dev
 Classifier: Development Status :: 3 - Alpha
@@ -24,12 +24,19 @@ Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
 Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
+Requires-Dist: requests>=2.25.0; extra == "dev"
+Requires-Dist: aiohttp>=3.8.0; extra == "dev"
+Requires-Dist: httpx2>=2.0.0; extra == "dev"
 Requires-Dist: black>=23.0.0; extra == "dev"
 Requires-Dist: flake8>=6.0.0; extra == "dev"
 Provides-Extra: openai
 Requires-Dist: openai>=1.0.0; extra == "openai"
 Provides-Extra: anthropic
 Requires-Dist: anthropic>=0.18.0; extra == "anthropic"
+Provides-Extra: gemini
+Requires-Dist: google-generativeai>=0.3.0; extra == "gemini"
+Provides-Extra: google-genai
+Requires-Dist: google-genai>=1.0.0; extra == "google-genai"
 Provides-Extra: langchain
 Requires-Dist: langchain>=0.1.0; extra == "langchain"
 Dynamic: author
@@ -51,6 +58,7 @@ AI-powered analytics for backend applications with **zero-code LLM conversation
 ## Features
 
 - **Automatic LLM Tracking**: Captures OpenAI, Anthropic, and Gemini calls automatically
+- **Outbound Call Tracking**: Records the calls your app makes to other services (httpx, httpx2, requests, aiohttp, urllib) — destination, status, latency and failures. Never the request or response bodies.
 - **Session Correlation**: Links backend events to frontend user sessions via `X-Scope-Session-ID` header
 - **Conversation Intelligence**: Classifies LLM calls as user-facing vs background jobs
 - **Zero Code Changes**: Drop-in integration with automatic monkey-patching
@@ -167,6 +175,7 @@ scope-run --dry-run uvicorn main:app
 | `SCOPE_ENDPOINT` | No | Custom API endpoint |
 | `SCOPE_DEBUG` | No | Set to 'true' for debug logging |
 | `SCOPE_ENVIRONMENT` | No | Environment name (default: production) |
+| `SCOPE_CAPTURE_HTTP` | No | Capture outbound calls to other services (default: on; `false` turns it off) |
 
 ## Configuration (Code-Based)
 
@@ -177,6 +186,8 @@ scope = ScopeAnalytics(
     auto_patch=True,                    # Optional: Auto-patch LLM libraries (default: True)
     batch_size=10,                      # Optional: Events per batch (default: 10)
     batch_timeout_seconds=5,            # Optional: Max wait time (default: 5)
+    capture_http=True,                  # Optional: Capture outbound calls (default: True,
+                                        #   independent of auto_patch)
     debug=False,                        # Optional: Enable debug logging
     environment="production",           # Optional: Environment name
 )

{scope_analytics-0.1.1 → scope_analytics-0.1.3}/README.md

@@ -5,6 +5,7 @@ AI-powered analytics for backend applications with **zero-code LLM conversation
 ## Features
 
 - **Automatic LLM Tracking**: Captures OpenAI, Anthropic, and Gemini calls automatically
+- **Outbound Call Tracking**: Records the calls your app makes to other services (httpx, httpx2, requests, aiohttp, urllib) — destination, status, latency and failures. Never the request or response bodies.
 - **Session Correlation**: Links backend events to frontend user sessions via `X-Scope-Session-ID` header
 - **Conversation Intelligence**: Classifies LLM calls as user-facing vs background jobs
 - **Zero Code Changes**: Drop-in integration with automatic monkey-patching
@@ -121,6 +122,7 @@ scope-run --dry-run uvicorn main:app
 | `SCOPE_ENDPOINT` | No | Custom API endpoint |
 | `SCOPE_DEBUG` | No | Set to 'true' for debug logging |
 | `SCOPE_ENVIRONMENT` | No | Environment name (default: production) |
+| `SCOPE_CAPTURE_HTTP` | No | Capture outbound calls to other services (default: on; `false` turns it off) |
 
 ## Configuration (Code-Based)
 
@@ -131,6 +133,8 @@ scope = ScopeAnalytics(
     auto_patch=True,                    # Optional: Auto-patch LLM libraries (default: True)
     batch_size=10,                      # Optional: Events per batch (default: 10)
     batch_timeout_seconds=5,            # Optional: Max wait time (default: 5)
+    capture_http=True,                  # Optional: Capture outbound calls (default: True,
+                                        #   independent of auto_patch)
     debug=False,                        # Optional: Enable debug logging
     environment="production",           # Optional: Environment name
 )

scope_analytics-0.1.3/scope_analytics/__init__.py

@@ -0,0 +1,547 @@
+"""
+Scope Analytics - Backend SDK
+AI-powered analytics with automatic LLM conversation tracking
+"""
+
+import atexit
+import logging
+from typing import Optional
+
+from .config import ScopeConfig, DEFAULT_REDACT_PATTERNS
+from .context import ScopeContext
+from .deployment import DeploymentContext
+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 .patches.google_genai_patch import GoogleGenaiPatcher
+from .patches.http_patch import HTTPPatcher
+from .middleware import (
+    ScopeSessionMiddleware,
+    FlaskScopeMiddleware,
+    init_flask_session_tracking,
+    DjangoScopeMiddleware,
+)
+
+def _resolve_version() -> str:
+    """Single source of truth: the installed distribution's own metadata.
+
+    Hardcoding this drifted once already — 0.1.1 shipped stamping every event as
+    "0.1.0", which made it impossible to tell from our own ingested data which SDK a
+    customer was running (exactly what you need to triage an SDK bug). Deriving it
+    means setup.py is the only place a version lives.
+    """
+    try:
+        from importlib.metadata import version, PackageNotFoundError
+        try:
+            return version("scope-analytics")
+        except PackageNotFoundError:
+            return "0.0.0+unknown"  # running from a source tree, not installed
+    except Exception:  # noqa: BLE001 - never let version lookup break an import
+        return "0.0.0+unknown"
+
+
+__version__ = _resolve_version()
+__all__ = [
+    "ScopeAnalytics",
+    "ScopeContext",
+    "ScopeConfig",
+    "DEFAULT_REDACT_PATTERNS",      # default credential-scrub patterns (on by default; [] to opt out)
+    "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,
+        capture_http: Optional[bool] = None,
+    ):
+        """
+        Initialize Scope Analytics SDK
+
+        A missing or malformed API key does NOT raise: the SDK emits one
+        always-visible warning and constructs itself disabled — no patching, no
+        event capture, every public method a no-op — so a config typo can never
+        take the host application down (PRODUCT.md §2, Robustness: analytics must never break
+        the host app; fail loudly, not silently).
+
+        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)
+            capture_http: Capture the outbound calls this app makes to other services
+                (default: on; SCOPE_CAPTURE_HTTP=false turns it off). Destination, status,
+                latency and failures only — never request or response bodies.
+        """
+        # Defined before anything can fail so every instance — including a
+        # disabled shell — carries it, and the no-op guards below never AttributeError.
+        self.enabled = True
+
+        # Initialize configuration. Only ValueError is caught: it is the specific,
+        # known config-validation failure (missing key, wrong prefix). Any other
+        # exception is an SDK bug and must still surface in development. The
+        # zero-code path (auto.py) already degrades this way; the manual path has
+        # to behave identically or a typo'd key crashes the app at startup.
+        try:
+            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,
+                capture_http=capture_http,
+            )
+        except ValueError as e:
+            # self.config doesn't exist yet, so go straight to the same
+            # always-visible logger channel ScopeConfig.warn() uses.
+            logging.getLogger("scope_analytics").warning(
+                "[Scope SDK] %s Scope Analytics is DISABLED — no events will be "
+                "captured and no LLM libraries will be patched.",
+                e,
+            )
+            self.enabled = False
+            # Heavy components (formatter, client, deployment, queue, patchers)
+            # stay unconstructed: no background thread, no atexit hook, and no
+            # global registration — a disabled instance must never become the
+            # middleware's SDK.
+            self.patches = []
+            self.uncovered_llm_libraries = []
+            self.outbound_http_libraries = []
+            self._warned_ship_failure = False
+            self._llm_sdks_detected = []
+            return
+
+        # Initialize components
+        self.event_formatter = EventFormatter(self.config)
+        self.client = ScopeAPIClient(self.config)
+
+        # Capture deployment + commit identity once at startup (PRODUCT.md §4.2).
+        # Its .stamp is wired as the queue enricher so git_sha/deployment_id land
+        # on every event through a single chokepoint.
+        self.deployment = DeploymentContext(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,
+            event_enricher=self.deployment.stamp,
+        )
+
+        # Initialize patchers
+        self.openai_patcher = OpenAIPatcher(self)
+        self.anthropic_patcher = AnthropicPatcher(self)
+        self.gemini_patcher = GeminiPatcher(self)            # legacy google-generativeai (EOL)
+        self.google_genai_patcher = GoogleGenaiPatcher(self)  # unified google-genai (modern)
+        self.http_patcher = HTTPPatcher(self)                 # outbound calls to other services
+        self._warned_ship_failure = False  # the delivery-failure warning fires once
+        self.patches = []  # List of successfully applied LLM patches (LLM ONLY — see below)
+        self.uncovered_llm_libraries = []  # Known-uncovered LLM libs detected at startup
+        # Outbound HTTP coverage is tracked separately and deliberately NOT in self.patches:
+        # that list is reported to the backend as `patched_llm_libraries`, and an HTTP client
+        # in it would claim LLM coverage this SDK does not have.
+        self.outbound_http_libraries = []
+        self._llm_sdks_detected = []  # Recognized SDKs whose import succeeded (≠ patched)
+
+        # 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()
+
+        # Outbound capture runs on its own switch (see _apply_http_capture).
+        self._apply_http_capture()
+
+        # Emit a single deployment_detected event when this boot's commit differs
+        # from the previous boot's (PRODUCT.md §4.2). No-op when no SHA is known.
+        self._emit_deployment_detected()
+
+    def _emit_deployment_detected(self):
+        """Emit one deployment_detected event per new commit (best-effort)."""
+        try:
+            if self.deployment.should_emit_deployment_detected():
+                # Only claim a coverage snapshot when patching actually ran —
+                # auto_patch=False means "unknown", not "none". Package names
+                # throughout ('gemini' is the internal patcher key).
+                coverage = None
+                if self.config.auto_patch:
+                    name_map = {"gemini": "google-generativeai"}
+                    coverage = {
+                        "patched_llm_libraries": [name_map.get(p, p) for p in self.patches],
+                        "uncovered_llm_libraries": list(self.uncovered_llm_libraries),
+                        # Which HTTP clients this deploy captures outbound calls through.
+                        # Empty when capture is switched off — the record that distinguishes
+                        # "this app makes no outbound calls" from "we were not looking".
+                        # Stored on the deploy event; the coverage report reads live
+                        # presence today and could read this receipt as well.
+                        "outbound_http_libraries": list(self.outbound_http_libraries),
+                    }
+                event = self.deployment.build_deployment_event(coverage=coverage)
+                if self.event_formatter.validate_event(event):
+                    self.queue.enqueue(event)
+                    self.config.log(
+                        f"Deployment detected: {self.deployment.deployment_id} "
+                        f"(git_sha={self.deployment.git_sha})"
+                    )
+        except Exception as e:
+            # Never let deployment detection break SDK startup.
+            self.config.log(f"Failed to emit deployment_detected: {e}")
+
+    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._llm_sdks_detected.append('openai')
+            self.config.log("OpenAI library detected - patching...")
+            if self.openai_patcher.patch():
+                self.patches.append('openai')
+            else:
+                # The library is present but we failed to instrument it: the app will run
+                # fine and capture NOTHING. Never let that pass silently.
+                self.config.warn(
+                    "openai is installed but Scope could not instrument it — "
+                    "LLM calls will NOT be captured. Set SCOPE_DEBUG=true for details."
+                )
+        except ImportError:
+            self.config.log("OpenAI library not installed - skipping patch")
+
+        # Patch Anthropic
+        try:
+            import anthropic
+            self._llm_sdks_detected.append('anthropic')
+            self.config.log("Anthropic library detected - patching...")
+            if self.anthropic_patcher.patch():
+                self.patches.append('anthropic')
+            else:
+                self.config.warn(
+                    "anthropic is installed but Scope could not instrument it — "
+                    "LLM calls will NOT be captured. Set SCOPE_DEBUG=true for details."
+                )
+        except ImportError:
+            self.config.log("Anthropic library not installed - skipping patch")
+
+        # Patch Google Gemini — legacy google-generativeai SDK (deprecated/EOL 2025-11-30) ...
+        try:
+            import google.generativeai
+            self._llm_sdks_detected.append('google-generativeai')
+            self.config.log("Google Generative AI (legacy) library detected - patching...")
+            if self.gemini_patcher.patch():
+                self.patches.append('gemini')
+            else:
+                self.config.warn(
+                    "google-generativeai is installed but Scope could not instrument it — "
+                    "LLM calls will NOT be captured. Set SCOPE_DEBUG=true for details."
+                )
+        except ImportError:
+            self.config.log("Google Generative AI (legacy) library not installed - skipping patch")
+
+        # ... and the modern unified google-genai SDK (the recommended replacement). Both are patched
+        # additively so legacy and new Gemini users are covered.
+        try:
+            import google.genai  # noqa: F401
+            self._llm_sdks_detected.append('google-genai')
+            self.config.log("google-genai (unified) library detected - patching...")
+            if self.google_genai_patcher.patch():
+                self.patches.append('google-genai')
+            else:
+                self.config.warn(
+                    "google-genai is installed but Scope could not instrument it — "
+                    "LLM calls will NOT be captured. Set SCOPE_DEBUG=true for details."
+                )
+        except ImportError:
+            self.config.log("google-genai (unified) library not installed - skipping patch")
+
+        self._report_coverage_gaps()
+
+    def _apply_http_capture(self):
+        """Capture the calls this app makes TO other services.
+
+        Its own switch, deliberately not `auto_patch`: that one is about instrumenting LLM
+        libraries, and an app that turns it off (custom provider handling, an unsupported
+        SDK) still wants to know which services it calls and how they are behaving.
+        SCOPE_CAPTURE_HTTP=false is the knob for this one.
+
+        Coverage is tracked apart from self.patches, which is reported to the backend as
+        `patched_llm_libraries`: a patched HTTP client says nothing about whether this
+        app's LLM calls are covered, and letting it silence the "no LLM SDK detected"
+        warning would hide a real gap.
+        """
+        if not self.config.capture_http:
+            self.config.log("Outbound HTTP capture disabled (SCOPE_CAPTURE_HTTP=false)")
+            return
+        if self.http_patcher.patch():
+            self.outbound_http_libraries = list(self.http_patcher.patched_libraries)
+        else:
+            # httpx ships with this SDK, so reaching here means the shape we instrument
+            # has moved — outbound calls silently stop being captured. Say so.
+            self.config.warn(
+                "Scope could not instrument any HTTP client — the outbound calls this app "
+                "makes to other services will NOT be captured. Set SCOPE_DEBUG=true for details."
+            )
+
+    def _report_coverage_gaps(self):
+        """Coverage honesty at startup (rule b): a known gap must never look like
+        working coverage.
+
+        Two silences this kills: (1) a KNOWN-uncovered LLM library (litellm, cohere)
+        installed alongside — or instead of — the SDKs we patch; (2) no recognized LLM
+        SDK at all, where zero output is indistinguishable from zero traffic. Detection
+        is metadata-only (find_spec never imports the target) and totally fail-safe.
+        """
+        try:
+            import importlib.util
+            from .supported_versions import KNOWN_UNCOVERED
+            for lib, why in KNOWN_UNCOVERED.items():
+                try:
+                    if importlib.util.find_spec(lib) is not None:
+                        self.uncovered_llm_libraries.append(lib)
+                        self.config.warn(f"{lib} detected but NOT captured by Scope: {why}")
+                except Exception:
+                    continue  # one undetectable lib must not silence the others
+            if not self._llm_sdks_detected and not self.uncovered_llm_libraries:
+                self.config.warn(
+                    "No supported LLM SDK detected (openai / anthropic / google-genai / "
+                    "google-generativeai) — no LLM calls will be captured. Frontend and "
+                    "backend events still flow. If this app calls an LLM through another "
+                    "library, capture it manually with scope.track_event(...)."
+                )
+        except Exception as e:
+            # Coverage reporting must never break startup.
+            self.config.log(f"Coverage-gap check failed: {e}")
+
+    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
+        """
+        # Disabled construction has no formatter/queue (and possibly no config) —
+        # the one loud warning already fired at init, so just drop the event.
+        if not self.enabled:
+            return
+
+        self.config.log(f"Tracking event: {event_type}")
+
+        # Create event with standard fields
+        event = {
+            "event_type": event_type,
+            "source": self.config.sdk_source,
+            **properties
+        }
+
+        # Manual callers shouldn't need boilerplate: default the fields
+        # validate_event requires (never overriding caller-provided values).
+        # Without these defaults a bare track_event(...) call — exactly what the
+        # docs and the MCP coverage report tell users to write for uncovered
+        # libraries — was silently dropped at validation.
+        from datetime import datetime, timezone
+        event.setdefault("timestamp", datetime.now(timezone.utc).isoformat())
+        if "session_id" not in event:
+            # generate_temp (NOT ensure_session_id): ensure_ would PIN the temp id
+            # into the contextvar as a side effect — in a long-lived worker with no
+            # per-request reset, that stitches every later event (manual AND
+            # auto-captured) into one bogus session. Same decision as events.py's
+            # http_request path. The lazy `if` also avoids evaluating any of this
+            # when the caller supplied a session_id.
+            event["session_id"] = (ScopeContext.get_session_id()
+                                   or ScopeContext.generate_temp_session_id())
+
+        # Validate and enqueue
+        if self.event_formatter.validate_event(event):
+            self.queue.enqueue(event)
+        else:
+            # A rejected manual event must not vanish silently.
+            self.config.warn(
+                f"Manual event '{event_type}' failed validation and was dropped."
+            )
+
+    def identify(self, user_id: str, traits: Optional[dict] = None):
+        """
+        Identify a user and stitch their prior anonymous activity to them.
+
+        Emits an ``identify`` event that the backend uses to merge the user's
+        anonymous session into this identified user — matched by the shared
+        ``session_id`` (the FE↔BE fingerprint) and/or the prior ``anonymous_id``
+        — and to attach the given traits. Also binds the identified user to the
+        current request context so subsequent events are attributed to them.
+
+        Args:
+            user_id: Unique user identifier (whatever your app uses — email, sub, etc.)
+            traits: Optional user traits (e.g., email, name, plan)
+        """
+        # Disabled construction has no formatter/queue (and possibly no config) —
+        # the one loud warning already fired at init, so just drop the identify.
+        if not self.enabled:
+            return
+
+        if not user_id:
+            self.config.log("identify() called without a user_id - ignoring")
+            return
+
+        # Capture the prior (anonymous) identity BEFORE overwriting the context,
+        # so the stitcher can link pre-identification events to this user. Prefer
+        # the bridged frontend anonymous id (the durable cross-visit visitor id)
+        # over the request's user_id, so the merge works even when this request
+        # already carries an authenticated user_id (e.g. a JWT issued at signup).
+        anonymous_id = ScopeContext.get_anonymous_id() or ScopeContext.get_user_id()
+        session_id = ScopeContext.get_session_id()
+
+        # Bind the identified user so later events in this request use it.
+        ScopeContext.set_user_id(user_id)
+
+        event = self.event_formatter.format_identify(
+            identified_user_id=user_id,
+            anonymous_id=anonymous_id,
+            session_id=session_id,
+            traits=traits,
+        )
+
+        if self.event_formatter.validate_event(event):
+            self.queue.enqueue(event)
+            self.config.log(
+                f"Identified user: {user_id} "
+                f"(anonymous_id={event.get('anonymous_id')}, session={event.get('session_id')})"
+            )
+            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")
+            if not self._warned_ship_failure:
+                # Event LOSS: a batch the backend refused (rate limit, auth, outage) is
+                # dropped, and until now that was visible only in debug mode. It matters
+                # more since outbound capture: more events means the per-IP ingest limit
+                # is reachable, and a dropped batch takes llm_call events with it.
+                self._warned_ship_failure = True
+                self.config.warn(
+                    f"Could not deliver {len(events)} events to Scope — they were dropped. "
+                    f"Check the API key and the endpoint; if this is volume, "
+                    f"SCOPE_CAPTURE_HTTP=false turns off outbound HTTP capture. "
+                    f"This warning is shown once."
+                )
+
+    def shutdown(self):
+        """
+        Gracefully shutdown SDK
+        Flushes remaining events and cleans up resources
+        """
+        # Disabled construction never started a queue, opened a client, or applied
+        # patches — nothing to tear down, so shutdown is a silent no-op.
+        if not self.enabled:
+            return
+
+        self.config.log("Shutting down Scope Analytics SDK...")
+
+        # Bound how long telemetry may delay process exit: the final synchronous
+        # flush ships with a short timeout (vs the 30s steady-state client timeout)
+        # so a hung/cold backend can't hold a customer's CLI or cron job hostage.
+        if self.client:
+            self.client.ship_timeout = 5.0
+
+        # Remove the outbound-HTTP wrappers FIRST: anything captured after the queue
+        # stops is appended to a queue that will never ship it, and the customer's own
+        # atexit handlers can still be making calls at this point.
+        self.http_patcher.unpatch()
+
+        # 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()
+        if 'google-genai' in self.patches:
+            self.google_genai_patcher.unpatch()
+
+        self.config.log("Scope Analytics SDK shutdown complete")

{scope_analytics-0.1.1 → scope_analytics-0.1.3}/scope_analytics/auto.py

@@ -75,6 +75,13 @@ def _auto_init():
             auto_patch=True,  # Always auto-patch in auto mode
         )
 
+        if not getattr(_scope_instance, 'enabled', True):
+            # ScopeAnalytics self-disabled (bad key) and already warned loudly.
+            # Don't hold the disabled instance: is_initialized() must report the
+            # truth — nothing is being captured.
+            _scope_instance = None
+            return None
+
         _log("Scope Analytics initialized successfully")
 
         # Auto-inject session middleware for known frameworks

{scope_analytics-0.1.1 → scope_analytics-0.1.3}/scope_analytics/cli.py

@@ -221,8 +221,25 @@ Environment Variables:
         print(f"[Scope SDK] Starting with auto-instrumentation...")
         print(f"[Scope SDK] Command: {' '.join(final_command)}")
 
-    # Execute the wrapped command
+    # Execute the wrapped command.
+    #
+    # POSIX: replace this process (exec) instead of spawning a child. scope-run's whole job is
+    # done once the environment is prepared, and staying resident as a wrapper breaks graceful
+    # shutdown in containers: as PID 1 it neither installs handlers nor forwards signals, so
+    # `docker stop`/Cloud Run/K8s SIGTERM is swallowed, the runtime escalates to SIGKILL, and
+    # the SDK's synchronous shutdown flush never runs — silently losing the final event batch
+    # on every instance stop. After exec the app itself is PID 1 and owns its signals.
+    #
+    # The sitecustomize temp dir outlives this process by design — reload/fork respawns
+    # (e.g. `uvicorn --reload`) re-import it from PYTHONPATH — so no cleanup is attempted
+    # (atexit couldn't run in a replaced process anyway; the OS tmp reaper collects it).
+    #
+    # Windows: exec* detaches from the waiting console/parent, so keep the subprocess wrapper.
     try:
+        if os.name == 'posix':
+            sys.stdout.flush()
+            sys.stderr.flush()
+            os.execvpe(final_command[0], final_command, env)
         result = subprocess.run(final_command, env=env)
         return result.returncode
     except FileNotFoundError: