scope-analytics 0.1.2__tar.gz → 0.1.4__tar.gz

{scope_analytics-0.1.2/scope_analytics.egg-info → scope_analytics-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scope-analytics
-Version: 0.1.2
+Version: 0.1.4
 Summary: AI-powered analytics SDK for backend applications with automatic LLM tracking
 Home-page: https://scopeai.dev
 Author: Scope AI
@@ -24,6 +24,9 @@ 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
@@ -55,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
@@ -171,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)
 
@@ -181,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.2 → scope_analytics-0.1.4}/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.2 → scope_analytics-0.1.4}/scope_analytics/__init__.py

@@ -17,6 +17,7 @@ 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,
@@ -102,6 +103,7 @@ class ScopeAnalytics:
         max_queue_size: int = 1000,
         debug: bool = False,
         environment: Optional[str] = None,
+        capture_http: Optional[bool] = None,
     ):
         """
         Initialize Scope Analytics SDK
@@ -121,6 +123,9 @@ class ScopeAnalytics:
             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.
@@ -141,6 +146,7 @@ class ScopeAnalytics:
                 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
@@ -157,6 +163,8 @@ class ScopeAnalytics:
             # middleware's SDK.
             self.patches = []
             self.uncovered_llm_libraries = []
+            self.outbound_http_libraries = []
+            self._warned_ship_failure = False
             self._llm_sdks_detected = []
             return
 
@@ -183,8 +191,14 @@ class ScopeAnalytics:
         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.patches = []  # List of successfully applied patches
+        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
@@ -203,6 +217,9 @@ class ScopeAnalytics:
         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()
@@ -220,6 +237,12 @@ class ScopeAnalytics:
                     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):
@@ -301,6 +324,32 @@ class ScopeAnalytics:
 
         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.
@@ -441,6 +490,18 @@ class ScopeAnalytics:
 
         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):
         """
@@ -460,6 +521,11 @@ class ScopeAnalytics:
         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()

{scope_analytics-0.1.2 → scope_analytics-0.1.4}/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:

{scope_analytics-0.1.2 → scope_analytics-0.1.4}/scope_analytics/client.py

@@ -8,6 +8,8 @@ import json
 import httpx
 from typing import List, Dict, Any
 
+from .context import ScopeContext
+
 
 class ScopeAPIClient:
     """
@@ -59,6 +61,17 @@ class ScopeAPIClient:
         if not events:
             return True
 
+        # Shipping is Scope's OWN outbound HTTP. The marker below is what stops the
+        # outbound-HTTP patcher from capturing this POST — which would enqueue an event,
+        # which would trigger another POST, forever. It is set HERE rather than at the
+        # queue because this method is also called directly by the final shutdown flush,
+        # and because a contextvar set on the caller's thread would not be visible on the
+        # queue's background thread (contexts do not cross threads); setting it inside the
+        # call means it is always set on whichever thread is actually shipping.
+        with ScopeContext.scope_internal():
+            return self._ship(events)
+
+    def _ship(self, events: List[Dict[str, Any]]) -> bool:
         try:
             self.config.log(f"Shipping {len(events)} events to {self.endpoint}")
 
@@ -119,9 +132,11 @@ class ScopeAPIClient:
         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")
+            # Same reason as ship_events: Scope's own traffic is never captured.
+            with ScopeContext.scope_internal():
+                # 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")

{scope_analytics-0.1.2 → scope_analytics-0.1.4}/scope_analytics/config.py

@@ -27,6 +27,20 @@ DEFAULT_REDACT_PATTERNS = [
 ]
 
 
+def _env_flag(name: str, default: bool) -> bool:
+    """Read a boolean SCOPE_* env var. Unset (or unrecognized) keeps the default, so a
+    typo'd value can never silently turn a default-on feature off."""
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    value = raw.strip().lower()
+    if value in ("true", "1", "yes", "on"):
+        return True
+    if value in ("false", "0", "no", "off"):
+        return False
+    return default
+
+
 class ScopeConfig:
     """Configuration for Scope Analytics SDK"""
 
@@ -41,6 +55,7 @@ class ScopeConfig:
         debug: bool = False,
         environment: Optional[str] = None,
         redact_patterns: Optional[list] = None,
+        capture_http: Optional[bool] = None,
     ):
         """
         Initialize Scope SDK configuration
@@ -54,6 +69,9 @@ class ScopeConfig:
             max_queue_size: Maximum events to queue (oldest dropped if exceeded)
             debug: Enable debug logging
             environment: Environment name (production, staging, development)
+            capture_http: Capture the outbound HTTP calls the app makes to other services.
+                Default None = on (SCOPE_CAPTURE_HTTP=false turns it off). Method, URL, status,
+                latency and errors only — never request or response bodies.
             redact_patterns: Regex patterns to scrub from prompt/response/bodies. Default None =
                 credential scrub ON (DEFAULT_REDACT_PATTERNS — password/api_key/token/secret in
                 key=value form). Pass [] to opt out and store raw at full fidelity, or your own
@@ -81,6 +99,16 @@ class ScopeConfig:
         # Patching
         self.auto_patch = auto_patch
 
+        # Outbound HTTP capture — ON by default, because an install that silently skips
+        # the app's calls to other services would leave a hole the user never hears about
+        # (an upstream API's failures would simply not exist). Off is one env var away for
+        # an app whose outbound volume it doesn't want: SCOPE_CAPTURE_HTTP=false.
+        self.capture_http = (
+            _env_flag("SCOPE_CAPTURE_HTTP", default=True)
+            if capture_http is None
+            else bool(capture_http)
+        )
+
         # Batching
         self.batch_size = batch_size
         self.batch_timeout_seconds = batch_timeout_seconds
@@ -109,6 +137,7 @@ class ScopeConfig:
         return {
             "endpoint": self.endpoint,
             "auto_patch": self.auto_patch,
+            "capture_http": self.capture_http,
             "batch_size": self.batch_size,
             "batch_timeout_seconds": self.batch_timeout_seconds,
             "max_queue_size": self.max_queue_size,

{scope_analytics-0.1.2 → scope_analytics-0.1.4}/scope_analytics/context.py

@@ -4,6 +4,8 @@ Handles session ID propagation across async boundaries
 """
 
 import contextvars
+import functools
+import inspect
 from typing import Optional
 from contextlib import contextmanager
 import uuid
@@ -48,6 +50,25 @@ _in_scope_context: contextvars.ContextVar[bool] = contextvars.ContextVar(
     'scope_in_scope_context', default=False
 )
 
+# "A provider call this SDK is already capturing is running right now."
+#
+# The LLM patchers set this for the duration of the provider method they wrap (and
+# for the deferred stream helpers, while the stream is being opened/consumed inside
+# our own proxies). The outbound-HTTP patcher reads it and stays silent: the HTTP
+# request underneath a captured provider call is already recorded as the llm_call
+# itself, and recording it a second time as an external_api_call would double every
+# AI app's dominant traffic.
+#
+# WHY A FLAG AND NOT A HOST LIST: a list of provider hostnames is wrong in both
+# directions. It hides real outbound calls when an app points its OpenAI client at
+# Azure, OpenRouter, a proxy or a local model (base_url overrides are common), and it
+# silences calls to a provider we did NOT manage to instrument — exactly the gap the
+# user needs to see. The flag excludes precisely what we actually captured, and it
+# stays correct when a new provider is added.
+_provider_call_in_flight: contextvars.ContextVar[bool] = contextvars.ContextVar(
+    'scope_provider_call_in_flight', default=False
+)
+
 
 class ScopeContext:
     """
@@ -165,6 +186,22 @@ class ScopeContext:
         thread_id_context.set(None)
         user_agent_context.set(None)
 
+    # One id for everything this process does with no visitor attached. Machine-driven
+    # events (a cron job's outbound calls, a worker's retries) have no session, but the
+    # event schema needs one — and minting a fresh temp id per call would file 10,000
+    # calls as 10,000 one-event "sessions", which is what every session count in the
+    # product would then report. One per process is the truthful shape: this was one
+    # background process, not ten thousand visits. Still `temp_`, so it reads as "no
+    # visitor" everywhere a temp session already does.
+    _background_session_id = None
+
+    @staticmethod
+    def background_session_id() -> str:
+        """The stable temp session id for this process's context-less events."""
+        if ScopeContext._background_session_id is None:
+            ScopeContext._background_session_id = f"temp_bg_{uuid.uuid4().hex[:12]}"
+        return ScopeContext._background_session_id
+
     @staticmethod
     def generate_temp_session_id() -> str:
         """
@@ -241,6 +278,33 @@ class ScopeContext:
         """
         _in_scope_context.set(False)
 
+    # =========================================================================
+    # Provider-call marker - lets outbound-HTTP capture skip what is already an llm_call
+    # =========================================================================
+
+    @staticmethod
+    def is_provider_call_in_flight() -> bool:
+        """True while a provider call this SDK captures as an ``llm_call`` is executing.
+
+        Read by the outbound-HTTP patcher so one LLM request is one event, not two.
+        """
+        return _provider_call_in_flight.get()
+
+    @staticmethod
+    @contextmanager
+    def provider_call():
+        """Mark the enclosed block as a provider call Scope already captures.
+
+        Re-entrant (nested provider calls restore the previous value), context-local
+        (a concurrent request or task is unaffected), and total — the flag is always
+        restored, including when the provider raises.
+        """
+        token = _provider_call_in_flight.set(True)
+        try:
+            yield
+        finally:
+            _provider_call_in_flight.reset(token)
+
     @staticmethod
     @contextmanager
     def scope_internal():
@@ -260,3 +324,46 @@ class ScopeContext:
             yield
         finally:
             _in_scope_context.set(previous)
+
+
+def mark_provider_call(func):
+    """Wrap a provider method so everything it does — including the HTTP request it
+    issues underneath — runs marked as "already captured as an llm_call".
+
+    Applied by every LLM patcher at the moment it wraps a provider method, so the
+    outbound-HTTP patcher records one event per LLM call instead of two. Transparent:
+    the provider's own return value, exceptions and signature pass through untouched.
+
+    Two shapes are handled because provider SDKs use both. A true ``async def`` is
+    wrapped as a coroutine function. A *sync* function that RETURNS an awaitable —
+    openai's ``@required_args`` decorator produces exactly this, so
+    ``iscoroutinefunction`` reads False on its async resources — has the mark
+    re-entered around the await, because the flag must be set while the request is
+    actually in flight, not merely while the coroutine is being constructed.
+
+    A sync function that returns a lazily-opened STREAM is deliberately not covered
+    here: nothing is requested yet at return time. Those are marked where the stream
+    is opened and consumed instead (patches/_streaming.py, and the anthropic stream
+    helper), which is the moment the connection is really made.
+    """
+    if inspect.iscoroutinefunction(func):
+
+        @functools.wraps(func)
+        async def async_marked(*args, **kwargs):
+            with ScopeContext.provider_call():
+                return await func(*args, **kwargs)
+
+        return async_marked
+
+    @functools.wraps(func)
+    def marked(*args, **kwargs):
+        with ScopeContext.provider_call():
+            result = func(*args, **kwargs)
+        if inspect.isawaitable(result):
+            async def awaited():
+                with ScopeContext.provider_call():
+                    return await result
+            return awaited()
+        return result
+
+    return marked