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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scope-analytics
-Version: 0.1.4
+Version: 0.1.6
 Summary: AI-powered analytics SDK for backend applications with automatic LLM tracking
 Home-page: https://scopeai.dev
 Author: Scope AI
@@ -27,6 +27,8 @@ 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: gunicorn>=20.0; extra == "dev"
+Requires-Dist: flask>=2.0; extra == "dev"
 Requires-Dist: black>=23.0.0; extra == "dev"
 Requires-Dist: flake8>=6.0.0; extra == "dev"
 Provides-Extra: openai
@@ -91,15 +93,24 @@ export SCOPE_API_KEY="sk_live_..."
 # Instead of:   uvicorn main:app --reload
 # Run:          scope-run uvicorn main:app --reload
 
-# Instead of:   gunicorn app:app -w 4
+# Instead of:   gunicorn app:app -w 4                                   (Flask, Django)
 # Run:          scope-run gunicorn app:app -w 4
 
+# Instead of:   gunicorn main:app -w 4 -k uvicorn_worker.UvicornWorker  (FastAPI; pip install uvicorn-worker)
+# Run:          scope-run gunicorn main:app -w 4 -k uvicorn_worker.UvicornWorker
+
 # Instead of:   flask run --port 5000
 # Run:          scope-run flask run --port 5000
 ```
 
 That's it! Your LLM calls are now automatically tracked AND correlated
-with frontend sessions (for FastAPI, Flask, Django).
+with frontend sessions (for FastAPI, Flask, Django). Workers forked by gunicorn or
+Celery ship on their own timer (0.1.5). LangChain / LangGraph, LlamaIndex, PydanticAI,
+Instructor and the OpenAI Agents SDK are captured through the SDK they call
+(LangChain needs 0.1.5).
+
+**Serverless / notebooks** — no start command to prefix: create `scope = ScopeAnalytics()`
+at module import and call `scope.flush(timeout=2.0)` before the handler returns (0.1.5).
 
 ### Option B: Code-Based Installation
 
@@ -174,8 +185,9 @@ scope-run --dry-run uvicorn main:app
 | `SCOPE_API_KEY` | Yes | Your Scope Analytics API key |
 | `SCOPE_ENDPOINT` | No | Custom API endpoint |
 | `SCOPE_DEBUG` | No | Set to 'true' for debug logging |
-| `SCOPE_ENVIRONMENT` | No | Environment name (default: production) |
+| `SCOPE_ENVIRONMENT` | No | Environment tag on every event (default: production). When it is unset or `production`, events sent with a key you created for Staging or Development (Setup → Keys) are tagged with that key's environment instead |
 | `SCOPE_CAPTURE_HTTP` | No | Capture outbound calls to other services (default: on; `false` turns it off) |
+| `HTTPS_PROXY` / `NO_PROXY` / `SSL_CERT_FILE` | No | Honoured for the SDK's own connection to Scope (read from the environment only) |
 
 ## Configuration (Code-Based)
 
@@ -230,8 +242,7 @@ def my_request_handler(request):
 Add the frontend SDK to link user interactions with backend LLM calls:
 
 ```html
-<script src="https://cdn.scopeai.dev/v1/sdk.js"
-        data-api-key="pk_live_your_public_key"></script>
+<script src="https://cdn.scopeai.dev/v1/sdk.js?token=pk_live_your_public_key" async></script>
 ```
 
 The frontend SDK automatically:

{scope_analytics-0.1.4 → scope_analytics-0.1.6}/README.md

@@ -38,15 +38,24 @@ export SCOPE_API_KEY="sk_live_..."
 # Instead of:   uvicorn main:app --reload
 # Run:          scope-run uvicorn main:app --reload
 
-# Instead of:   gunicorn app:app -w 4
+# Instead of:   gunicorn app:app -w 4                                   (Flask, Django)
 # Run:          scope-run gunicorn app:app -w 4
 
+# Instead of:   gunicorn main:app -w 4 -k uvicorn_worker.UvicornWorker  (FastAPI; pip install uvicorn-worker)
+# Run:          scope-run gunicorn main:app -w 4 -k uvicorn_worker.UvicornWorker
+
 # Instead of:   flask run --port 5000
 # Run:          scope-run flask run --port 5000
 ```
 
 That's it! Your LLM calls are now automatically tracked AND correlated
-with frontend sessions (for FastAPI, Flask, Django).
+with frontend sessions (for FastAPI, Flask, Django). Workers forked by gunicorn or
+Celery ship on their own timer (0.1.5). LangChain / LangGraph, LlamaIndex, PydanticAI,
+Instructor and the OpenAI Agents SDK are captured through the SDK they call
+(LangChain needs 0.1.5).
+
+**Serverless / notebooks** — no start command to prefix: create `scope = ScopeAnalytics()`
+at module import and call `scope.flush(timeout=2.0)` before the handler returns (0.1.5).
 
 ### Option B: Code-Based Installation
 
@@ -121,8 +130,9 @@ scope-run --dry-run uvicorn main:app
 | `SCOPE_API_KEY` | Yes | Your Scope Analytics API key |
 | `SCOPE_ENDPOINT` | No | Custom API endpoint |
 | `SCOPE_DEBUG` | No | Set to 'true' for debug logging |
-| `SCOPE_ENVIRONMENT` | No | Environment name (default: production) |
+| `SCOPE_ENVIRONMENT` | No | Environment tag on every event (default: production). When it is unset or `production`, events sent with a key you created for Staging or Development (Setup → Keys) are tagged with that key's environment instead |
 | `SCOPE_CAPTURE_HTTP` | No | Capture outbound calls to other services (default: on; `false` turns it off) |
+| `HTTPS_PROXY` / `NO_PROXY` / `SSL_CERT_FILE` | No | Honoured for the SDK's own connection to Scope (read from the environment only) |
 
 ## Configuration (Code-Based)
 
@@ -177,8 +187,7 @@ def my_request_handler(request):
 Add the frontend SDK to link user interactions with backend LLM calls:
 
 ```html
-<script src="https://cdn.scopeai.dev/v1/sdk.js"
-        data-api-key="pk_live_your_public_key"></script>
+<script src="https://cdn.scopeai.dev/v1/sdk.js?token=pk_live_your_public_key" async></script>
 ```
 
 The frontend SDK automatically:

{scope_analytics-0.1.4 → scope_analytics-0.1.6}/scope_analytics/__init__.py

@@ -5,10 +5,11 @@ AI-powered analytics with automatic LLM conversation tracking
 
 import atexit
 import logging
-from typing import Optional
+import sys
+from typing import Any, Optional
 
 from .config import ScopeConfig, DEFAULT_REDACT_PATTERNS
-from .context import ScopeContext
+from .context import ScopeContext, accepted_user_id
 from .deployment import DeploymentContext
 from .events import EventFormatter
 from .queue import EventQueue
@@ -45,7 +46,7 @@ def _resolve_version() -> str:
 
 __version__ = _resolve_version()
 __all__ = [
-    "ScopeAnalytics",
+    "ScopeAnalytics",               # .flush(timeout=) ships queued events now (serverless, notebooks)
     "ScopeContext",
     "ScopeConfig",
     "DEFAULT_REDACT_PATTERNS",      # default credential-scrub patterns (on by default; [] to opt out)
@@ -184,6 +185,7 @@ class ScopeAnalytics:
             flush_callback=self._flush_events,
             config=self.config,
             event_enricher=self.deployment.stamp,
+            on_fork=self._after_fork,
         )
 
         # Initialize patchers
@@ -200,10 +202,16 @@ class ScopeAnalytics:
         # 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)
+        self._celery_hooked = False
 
         # Start queue background thread
         self.queue.start()
 
+        # A Celery worker already loaded? Then the prefork children's shutdown signal
+        # flushes their last batch (see _connect_celery_shutdown). Workers started through
+        # scope-run load Celery AFTER this point; the fork hook connects it in each child.
+        self._connect_celery_shutdown()
+
         # Register shutdown hook
         atexit.register(self.shutdown)
 
@@ -380,6 +388,87 @@ class ScopeAnalytics:
             # Coverage reporting must never break startup.
             self.config.log(f"Coverage-gap check failed: {e}")
 
+    def _after_fork(self):
+        """Runs in a forked CHILD once the queue has restarted its flush thread there.
+        The inherited ship client shares its pooled sockets with the parent — two
+        processes writing one TCP connection interleave bytes — so the child gets its
+        own. The background session id is per process, so the child mints its own. And
+        a Celery child flushes on its own shutdown signal (see _connect_celery_shutdown)."""
+        try:
+            # The inherited client is dropped, never closed: httpx's pool close() takes
+            # the pool's thread lock, and if the parent's flush thread held it at the
+            # instant of the fork the child would block forever inside this hook (the
+            # thread that holds it does not exist here). Unreferenced, the sockets close
+            # by garbage collection, which takes no pool lock.
+            self.client = ScopeAPIClient(self.config)
+        except Exception as e:  # noqa: BLE001 - never let a fork hook break the child
+            self.config.log(f"Could not rebuild the ship client after fork: {e}")
+        ScopeContext.reset_background_session()
+        # A receiver connected in the parent is inherited and works here (it closes over
+        # this same instance), so connect only if nothing was connected before the fork
+        # — e.g. the scope-run path, where Celery was not yet imported at init.
+        self._connect_celery_shutdown()
+
+    def _connect_celery_shutdown(self):
+        """Celery's prefork children exit through os._exit(), which skips atexit — so
+        their last partial batch (under batch_size, under batch_timeout) would be lost.
+        When Celery is loaded (checked in sys.modules; never imported here to find out),
+        the child's ``worker_process_shutdown`` signal flushes with a hard two-second
+        limit, so a broken network can never hold a worker's shutdown."""
+        if self._celery_hooked or "celery" not in sys.modules:
+            return
+        try:
+            from celery import signals
+        except Exception:  # noqa: BLE001 - a half-imported celery is not ours to break
+            return
+
+        def _on_worker_process_shutdown(**_kwargs):
+            self.flush(timeout=2.0)
+
+        # Celery holds signal receivers weakly by default; keep a strong reference.
+        self._celery_shutdown_handler = _on_worker_process_shutdown
+        try:
+            signals.worker_process_shutdown.connect(_on_worker_process_shutdown, weak=False)
+            self._celery_hooked = True
+            self.config.log("Celery worker_process_shutdown hook connected")
+        except Exception as e:  # noqa: BLE001
+            self.config.log(f"Could not connect the Celery shutdown hook: {e}")
+
+    def flush(self, timeout: Optional[float] = None):
+        """
+        Ship every queued event now.
+
+        For the places the background timer can't be trusted to fire: a serverless
+        handler about to be frozen, a notebook cell, a worker process about to exit.
+        Without ``timeout`` the events are shipped on the calling thread and the call
+        returns when they are delivered (the client's normal request timeout applies).
+        With ``timeout`` the call returns within that many seconds whatever the network
+        does: the delivery runs on a helper thread with that limit per request and the
+        caller waits for it only until the deadline, so a slow batch still lands if the
+        process lives on, and a stuck one never holds the caller past the budget.
+        Batches already in flight on the batch-size path are waited for within the same
+        budget. Capture stays live afterwards — unlike shutdown(), which also unpatches.
+
+        Args:
+            timeout: Optional hard limit, in seconds, on how long this call may take.
+        """
+        if not self.enabled:
+            return
+        if timeout is None:
+            self.queue.flush(synchronous=True)
+            self.queue.wait_inflight(self.client.ship_timeout or 30.0)
+            return
+        import threading
+        import time
+        deadline = time.monotonic() + timeout
+        worker = threading.Thread(
+            target=self.queue.flush, kwargs={"synchronous": True, "timeout": timeout},
+            daemon=True, name="ScopeAnalytics-Flush",
+        )
+        worker.start()
+        worker.join(max(0.0, deadline - time.monotonic()))
+        self.queue.wait_inflight(max(0.0, deadline - time.monotonic()))
+
     def track_event(self, event_type: str, properties: dict):
         """
         Manually track an event
@@ -409,6 +498,17 @@ class ScopeAnalytics:
         # libraries — was silently dropped at validation.
         from datetime import datetime, timezone
         event.setdefault("timestamp", datetime.now(timezone.utc).isoformat())
+        # The two stamps every auto-captured event carries, so a manual event is the same
+        # to the SDK-status and environment views (a manual-only install used to show no
+        # version at all).
+        event.setdefault("sdk_version", self.config.sdk_version)
+        event.setdefault("environment", self.config.environment)
+        # The browser's visitor id rides an event the app records in a request a page running Scope's
+        # script made, as on the SDK's own events (0.1.6) — only then: a manual event's fields are the
+        # caller's.
+        anonymous_id = ScopeContext.get_anonymous_id()
+        if anonymous_id:
+            event.setdefault("anonymous_id", anonymous_id)
         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
@@ -428,7 +528,7 @@ class ScopeAnalytics:
                 f"Manual event '{event_type}' failed validation and was dropped."
             )
 
-    def identify(self, user_id: str, traits: Optional[dict] = None):
+    def identify(self, user_id: Any, traits: Optional[dict] = None):
         """
         Identify a user and stitch their prior anonymous activity to them.
 
@@ -439,7 +539,9 @@ class ScopeAnalytics:
         current request context so subsequent events are attributed to them.
 
         Args:
-            user_id: Unique user identifier (whatever your app uses — email, sub, etc.)
+            user_id: Unique user identifier (whatever your app uses — email, sub, a database id) — text,
+                a whole number (kept as its digits, so 42 and "42" are one person), a UUID or an ObjectId,
+                up to 100 characters; anything else is ignored, and why said once (0.1.6)
             traits: Optional user traits (e.g., email, name, plan)
         """
         # Disabled construction has no formatter/queue (and possibly no config) —
@@ -447,9 +549,12 @@ class ScopeAnalytics:
         if not self.enabled:
             return
 
-        if not user_id:
+        if user_id is None:
             self.config.log("identify() called without a user_id - ignoring")
             return
+        user_id = accepted_user_id(user_id, "identify")
+        if user_id is None:
+            return
 
         # Capture the prior (anonymous) identity BEFORE overwriting the context,
         # so the stitcher can link pre-identification events to this user. Prefer
@@ -478,15 +583,19 @@ class ScopeAnalytics:
             if traits:
                 self.config.log(f"User traits: {traits}")
 
-    def _flush_events(self, events: list):
+    def _flush_events(self, events: list, timeout: Optional[float] = None):
         """
         Callback for flushing events to API
         Called by event queue when batch is ready
 
         Args:
             events: List of events to flush
+            timeout: Per-request limit for this batch only (set by ``flush(timeout=)``)
         """
-        success = self.client.ship_events(events)
+        # The limit is passed on only when set, so a one-argument stand-in for ship_events
+        # (tests, custom sinks) keeps working.
+        success = (self.client.ship_events(events) if timeout is None
+                   else self.client.ship_events(events, timeout=timeout))
 
         if not success:
             self.config.log(f"⚠️ Failed to ship {len(events)} events")

{scope_analytics-0.1.4 → scope_analytics-0.1.6}/scope_analytics/cli.py

@@ -21,6 +21,7 @@ Environment Variables:
 
 import os
 import sys
+import shutil
 import subprocess
 import argparse
 import tempfile
@@ -88,8 +89,31 @@ import os
 if os.environ.get('SCOPE_AUTO_INSTRUMENT') == 'true':
     try:
         import scope_analytics.auto
-    except ImportError:
-        pass  # scope-analytics not installed, skip silently
+        _launcher = os.environ.get('SCOPE_RUN_VERSION')
+        _running = getattr(scope_analytics, '__version__', None)
+        if _launcher and _running and _launcher != _running:
+            # The app's interpreter found a DIFFERENT copy of scope-analytics than the one
+            # scope-run was launched from (a global uvicorn next to an un-activated venv is
+            # the usual shape). That copy is what instruments the app; say so.
+            import sys
+            print(
+                "[Scope SDK] scope-run is scope-analytics " + _launcher + " but the interpreter "
+                "running your app (" + sys.executable + ") imported scope-analytics " + _running
+                + " — that copy is what instruments the app. To run " + _launcher + " here: "
+                + sys.executable + " -m pip install scope-analytics==" + _launcher,
+                file=sys.stderr,
+            )
+    except ImportError as e:
+        # The interpreter running the app is not the one scope-analytics was installed into
+        # (a pyenv shim, a system python, a multi-stage image). The user ran scope-run to be
+        # instrumented, so silence here would be the worst outcome: say it, once, loudly.
+        import sys
+        print(
+            "[Scope SDK] scope-analytics could not be imported by this interpreter ("
+            + sys.executable + "): " + str(e) + " — NOTHING is instrumented. Install it for "
+            "this interpreter: " + sys.executable + " -m pip install scope-analytics",
+            file=sys.stderr,
+        )
     except Exception as e:
         import sys
         print(f"[Scope SDK] Warning: Auto-instrumentation failed: {e}", file=sys.stderr)
@@ -187,6 +211,38 @@ Environment Variables:
     env = os.environ.copy()
     env['SCOPE_AUTO_INSTRUMENT'] = 'true'
 
+    # The command is resolved on PATH, so scope-run invoked from a virtualenv that is not
+    # activated (its absolute path in a Procfile, a Dockerfile, a systemd unit) used to
+    # launch whatever `uvicorn` / `gunicorn` came first on PATH — a different interpreter
+    # with a different scope-analytics, or none — and nothing said so. The launcher's own
+    # bin directory goes first, which is exactly what activating the virtualenv does; and
+    # the sitecustomize compares this version with the one the app's interpreter imports,
+    # saying so on stderr if they differ.
+    launcher_bin = os.path.dirname(os.path.abspath(sys.executable))
+    env['PATH'] = launcher_bin + os.pathsep + env.get('PATH', '')
+    version = _get_version()
+    if version != 'unknown' and not version.startswith('0.0.0'):
+        env['SCOPE_RUN_VERSION'] = version
+
+    # macOS: a Python process that runs a thread (the SDK's flush thread) and then forks
+    # workers — gunicorn, Celery's prefork pool, multiprocessing — trips the Objective-C
+    # runtime's fork-safety check in every child the first time it touches a system
+    # framework (the app's own HTTP client doing its proxy lookup is enough), and the child
+    # aborts: "+[NSCharacterSet initialize] may have been in progress in another thread when
+    # fork() was called". Measured with `scope-run gunicorn -w 2`: 0 of 10 runs healthy
+    # without this, 8 of 8 with it. This variable is the documented remedy for Python-and-fork
+    # on macOS; it means nothing anywhere else, so a Linux deployment is untouched. A value
+    # the user already set wins — and when scope-run sets it, it says so: nothing silent.
+    if sys.platform == 'darwin' and 'OBJC_DISABLE_INITIALIZE_FORK_SAFETY' not in env:
+        env['OBJC_DISABLE_INITIALIZE_FORK_SAFETY'] = 'YES'
+        print(
+            "[Scope SDK] macOS: set OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES for this command — "
+            "without it a server that forks workers (gunicorn, Celery) aborts in every child on "
+            "macOS's Objective-C fork-safety check. Set the variable yourself, to any value, to "
+            "choose otherwise.",
+            file=sys.stderr,
+        )
+
     if args.debug:
         env['SCOPE_DEBUG'] = 'true'
 
@@ -211,6 +267,7 @@ Environment Variables:
         print("[Scope SDK] Dry run - would execute:")
         print(f"  SCOPE_AUTO_INSTRUMENT=true")
         print(f"  PYTHONPATH={env['PYTHONPATH']}")
+        print(f"  {executable} resolves to: {shutil.which(executable, path=env['PATH']) or '(not found on PATH)'}")
         if args.debug:
             print(f"  SCOPE_DEBUG=true")
         print(f"  {' '.join(final_command)}")