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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scope-analytics
-Version: 0.1.6
+Version: 0.1.8
 Summary: AI-powered analytics SDK for backend applications with automatic LLM tracking
 Home-page: https://scopeai.dev
 Author: Scope AI

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

@@ -4,16 +4,18 @@ AI-powered analytics with automatic LLM conversation tracking
 """
 
 import atexit
+import contextlib
 import logging
 import sys
 from typing import Any, Optional
 
 from .config import ScopeConfig, DEFAULT_REDACT_PATTERNS
-from .context import ScopeContext, accepted_user_id
+from .context import ScopeContext, accepted_link, accepted_user_id
 from .deployment import DeploymentContext
 from .events import EventFormatter
 from .queue import EventQueue
-from .client import ScopeAPIClient
+from .client import MAX_EVENTS_PER_REQUEST, ScopeAPIClient
+from .drops import DropCounts
 from .patches.openai_patch import OpenAIPatcher
 from .patches.anthropic_patch import AnthropicPatcher
 from .patches.gemini_patch import GeminiPatcher
@@ -83,6 +85,65 @@ def _set_sdk_instance(instance: "ScopeAnalytics") -> None:
     _global_sdk_instance = instance
 
 
+# Celery's task_prerun and task_postrun receivers (ScopeAnalytics._connect_celery): never into the task's way.
+def _celery_task_starts(task_id=None, **_kwargs):
+    try:
+        ScopeContext.task_starts(task_id)
+    except Exception:  # noqa: BLE001 - a task runs whatever the SDK does
+        pass
+
+
+def _celery_task_ends(task_id=None, **_kwargs):
+    try:
+        ScopeContext.task_ends(task_id)
+    except Exception:  # noqa: BLE001
+        pass
+
+
+def _run_first(signal, receiver) -> None:
+    """Move a receiver to the front of a Celery signal's receivers: Celery calls them in the order they were
+    connected, and under scope-run the SDK connects after the app (in each forked child, or at the first
+    identify). Scope's task start must run before the app's own task_prerun handlers — they set the task's
+    context, which Scope's start would otherwise keep (and hand back to the caller of an eager task) and then
+    clear. In place, under the signal's lock: a task tracer holds this very list. Never in a task's way."""
+    try:
+        receivers = signal.receivers
+
+        def ours(entry):
+            # (lookup key, receiver) — or longer, as Django's dispatcher (Celery's is a fork of it) grew to
+            return entry is receiver or (isinstance(entry, tuple) and len(entry) >= 2 and entry[1] is receiver)
+
+        lock = getattr(signal, "lock", None)
+        with lock if lock is not None else contextlib.nullcontext():
+            mine = [entry for entry in receivers if ours(entry)]
+            if mine:
+                receivers[:] = mine + [entry for entry in receivers if not ours(entry)]
+            cache = getattr(signal, "sender_receivers_cache", None)
+            if cache is not None:
+                cache.clear()
+            first = bool(receivers) and ours(receivers[0])
+    except Exception:  # noqa: BLE001 - a signal of another shape keeps its order (and that is said, once)
+        first = False
+    if not first:
+        _say_not_first()
+
+
+_said_not_first = False
+
+
+def _say_not_first() -> None:
+    """Once per process: Scope's task start could not be put before the app's own task_prerun handlers."""
+    global _said_not_first
+    if _said_not_first:
+        return
+    _said_not_first = True
+    logging.getLogger("scope_analytics").warning(
+        "Scope could not run its Celery task start before your own task_prerun handlers (this Celery keeps "
+        "its receivers in a shape Scope does not know): a context your handlers give a task may be cleared "
+        "before the task runs."
+    )
+
+
 class ScopeAnalytics:
     """
     Main SDK class for Scope Analytics
@@ -186,6 +247,7 @@ class ScopeAnalytics:
             config=self.config,
             event_enricher=self.deployment.stamp,
             on_fork=self._after_fork,
+            on_drop=self._note_drop,
         )
 
         # Initialize patchers
@@ -208,9 +270,10 @@ class ScopeAnalytics:
         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()
+        # flushes their last batch, and each task starts clean (see _connect_celery). Workers
+        # started through scope-run load Celery AFTER this point; the fork hook connects it in
+        # each child, and an identify in a worker that never forks.
+        self._connect_celery()
 
         # Register shutdown hook
         atexit.register(self.shutdown)
@@ -393,7 +456,7 @@ class ScopeAnalytics:
         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)."""
+        a Celery child flushes on its own shutdown signal (see _connect_celery)."""
         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
@@ -403,18 +466,32 @@ class ScopeAnalytics:
             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}")
+            # What the parent dropped is the parent's to report: the child counts its own (new
+            # counts, never the inherited lock, which the parent's threads may have held)
+            try:
+                self.client.drops = DropCounts()
+                self.client._hold_reports = False
+            except Exception:  # noqa: BLE001
+                pass
         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()
+        self._connect_celery()
 
-    def _connect_celery_shutdown(self):
+    def _connect_celery(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."""
+        limit, so a broken network can never hold a worker's shutdown.
+
+        And each task starts with none of what the task before it left in the SDK's context —
+        the user it identified, the session its AI calls made up — while whatever ran it gets its
+        own context back when it ends (``task_prerun`` / ``task_postrun``; an eager task runs
+        inline, inside its caller's context). A worker's tasks are for different people (0.1.7).
+        Scope's start runs first, before the app's own task_prerun handlers, whenever it was
+        connected; its end runs after the handlers the app connected before it."""
         if self._celery_hooked or "celery" not in sys.modules:
             return
         try:
@@ -423,6 +500,9 @@ class ScopeAnalytics:
             return
 
         def _on_worker_process_shutdown(**_kwargs):
+            client = getattr(self, "client", None)
+            if client is not None:
+                client.exiting = True   # the child's last sends carry what it gave up on
             self.flush(timeout=2.0)
 
         # Celery holds signal receivers weakly by default; keep a strong reference.
@@ -433,6 +513,17 @@ class ScopeAnalytics:
             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}")
+        for name, receiver in (("task_prerun", _celery_task_starts), ("task_postrun", _celery_task_ends)):
+            signal = getattr(signals, name, None)
+            if signal is None:
+                continue
+            try:
+                signal.connect(receiver, weak=False)   # module functions: connected once whatever the instance
+            except Exception as e:  # noqa: BLE001
+                self.config.log(f"Could not connect the Celery {name} hook: {e}")
+                continue
+            if receiver is _celery_task_starts:
+                _run_first(signal, receiver)
 
     def flush(self, timeout: Optional[float] = None):
         """
@@ -528,7 +619,7 @@ class ScopeAnalytics:
                 f"Manual event '{event_type}' failed validation and was dropped."
             )
 
-    def identify(self, user_id: Any, traits: Optional[dict] = None):
+    def identify(self, user_id: Any, traits: Optional[dict] = None, link: Optional[bool] = True):
         """
         Identify a user and stitch their prior anonymous activity to them.
 
@@ -538,11 +629,29 @@ class ScopeAnalytics:
         — and to attach the given traits. Also binds the identified user to the
         current request context so subsequent events are attributed to them.
 
+        What it links through is what the request — or your own code — established
+        (ScopeContext.earlier_identity): in a request Scope's middleware set up — a
+        WebSocket included, from its handshake — the browser's visitor id, else the
+        request's user, and its session; outside one (a job, a script, a webhook loop,
+        a framework Scope does not patch) only an id or session your code set with
+        ScopeContext, never
+        the user an earlier identify bound nor a session an earlier event made up —
+        those are the person before (0.1.7). Call it in the request where the person
+        signs up or signs in.
+
+        To record someone other than the request's person — a teammate an admin
+        invites from the admin's own request — pass ``link=False``: the person and
+        their traits are recorded, nothing is linked to them (no earlier id, a session
+        of the identify's own), and the request stays the admin's (0.1.7).
+
         Args:
             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)
+            link: True (the default) links the person's earlier activity, as above; False links
+                nothing and binds no one; None is read as True. Anything else is no answer: the
+                identify is not sent, and why said once (0.1.7)
         """
         # Disabled construction has no formatter/queue (and possibly no config) —
         # the one loud warning already fired at init, so just drop the identify.
@@ -555,22 +664,33 @@ class ScopeAnalytics:
         user_id = accepted_user_id(user_id, "identify")
         if user_id is None:
             return
+        link = accepted_link(link)
+        if link is None:
+            return
+
+        # A Celery loaded after the SDK (a worker started through scope-run with no fork: the solo or
+        # threads pool) gets its task hooks here, so the next task starts clean.
+        self._connect_celery()
 
         # 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()
+        # Outside a request, never what the SDK left there for whoever came before (0.1.7).
+        # link=False: someone other than the request's person — nothing is linked to them, and
+        # the request (or the job) stays whoever it was.
+        anonymous_id, session_id = ScopeContext.earlier_identity() if link else (None, None)
 
         # Bind the identified user so later events in this request use it.
-        ScopeContext.set_user_id(user_id)
+        if link:
+            ScopeContext.bind_identified_user(user_id)
 
         event = self.event_formatter.format_identify(
             identified_user_id=user_id,
             anonymous_id=anonymous_id,
-            session_id=session_id,
+            # a session of its own when there is none to link through, never one left in the context
+            session_id=session_id or ScopeContext.generate_temp_session_id(),
             traits=traits,
         )
 
@@ -583,6 +703,13 @@ class ScopeAnalytics:
             if traits:
                 self.config.log(f"User traits: {traits}")
 
+    def _note_drop(self, kind: str, count: int) -> None:
+        """Events the queue let go, counted where the next request's report is taken (the ship client's —
+        read at call time: a forked child has its own)."""
+        client = getattr(self, "client", None)
+        if client is not None:
+            client.drops.add(kind, count)
+
     def _flush_events(self, events: list, timeout: Optional[float] = None):
         """
         Callback for flushing events to API
@@ -605,8 +732,9 @@ class ScopeAnalytics:
                 # 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
+                some = "some of " if len(events) > MAX_EVENTS_PER_REQUEST else ""  # a flush sent as several
                 self.config.warn(
-                    f"Could not deliver {len(events)} events to Scope — they were dropped. "
+                    f"Could not deliver {some}{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."
@@ -629,6 +757,7 @@ class ScopeAnalytics:
         # 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
+            self.client.exiting = True   # its last sends carry what it gave up on (drops.py)
 
         # 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

{scope_analytics-0.1.6 → scope_analytics-0.1.8}/scope_analytics/client.py

@@ -13,6 +13,15 @@ import httpx
 from typing import List, Dict, Any, Optional
 
 from .context import ScopeContext
+from .drops import UNREACHABLE, UNSENDABLE, DropCounts, failed_send_kind
+
+# The ingest takes at most this many events in one request and refuses a larger batch whole (the
+# backend's MAX_BATCH_EVENTS); a flush of more goes as several requests.
+MAX_EVENTS_PER_REQUEST = 1_000
+
+# How one send ended (_ship): Scope took its batch, answered without taking it (or it was never made), or
+# never answered.
+_TAKEN, _NOT_TAKEN, _UNANSWERED = "taken", "not taken", "unanswered"
 
 
 class ScopeAPIClient:
@@ -22,7 +31,8 @@ class ScopeAPIClient:
     Handles:
     - Event shipping to /api/events endpoint
     - Authentication with secret API key
-    - Retry logic with exponential backoff
+    - Each batch sent once; what is given up on is counted by why and reported to Scope with a later
+      request (0.1.8, drops.py)
     - Error handling
     """
 
@@ -45,6 +55,20 @@ class ScopeAPIClient:
         # Single events refused or changed, by (kind, field, reason), already said (_note_refusals).
         self._warned_refusals = set()
 
+        # What this process gave up on, told to Scope on a later request (0.1.8; drops.py). A forked
+        # child builds its own client, so it never reports its parent's counts again.
+        self.drops = DropCounts()
+        # The last send did not get its batch taken (no answer, or an answer that refused it). Until one
+        # does, no report rides a request: Scope counts a report only with a batch it takes, and a report
+        # whose request got no answer is not sent again (it may have arrived; a count is never sent
+        # twice) — so while Scope is failing, a report riding every request would be lost with the
+        # first that goes unanswered.
+        self._hold_reports = False
+        # The process is ending (shutdown(), a Celery child's exit): no later send will come, so its last
+        # sends carry the counts whatever the hold.
+        self.exiting = False
+        self._warned_unsendable = False
+
         # Create HTTP client
         self.client = self._build_http_client(config)
 
@@ -123,61 +147,151 @@ class ScopeAPIClient:
         # 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, timeout)
-
-    def _ship(self, events: List[Dict[str, Any]], timeout: Optional[float] = None) -> bool:
+            if len(events) <= MAX_EVENTS_PER_REQUEST:
+                return self._ship(events, timeout) == _TAKEN
+            # A flush of more than one request takes (a queue raised past it) goes as several (0.1.8; until
+            # then Scope refused it whole)
+            delivered = True
+            for start in range(0, len(events), MAX_EVENTS_PER_REQUEST):
+                outcome = self._ship(events[start:start + MAX_EVENTS_PER_REQUEST], timeout)
+                delivered = delivered and outcome == _TAKEN
+                if outcome == _UNANSWERED:
+                    # Scope didn't answer: each request left would wait as long again (at shutdown, past the
+                    # bound it keeps), so the rest are given up on now, counted as the unanswered one was
+                    self.drops.add(UNREACHABLE, max(0, len(events) - start - MAX_EVENTS_PER_REQUEST))
+                    break
+            return delivered
+
+    def _ship(self, events: List[Dict[str, Any]], timeout: Optional[float] = None) -> str:
+        report = None
+        posting = False
         try:
             self.config.log(f"Shipping {len(events)} events to {self.endpoint}")
 
-            # Prepare payload
+            # Prepare payload — with what this process gave up on since its last report that got through
             payload = {
                 "events": events,
                 "source": self.config.sdk_source,
             }
+            report = None if self._hold_reports and not self.exiting else self.drops.take()
+            if report:
+                payload["dropped"] = report
 
-            # Strict-first serialization with a LOUD lossy fallback: events are
-            # sanitized at build time, so the strict path should always win — but a
-            # single stray non-JSON value must degrade to its string form (with a
-            # warning), never lose the whole batch.
-            try:
-                body = json.dumps(payload)
-            except (TypeError, ValueError):
-                body = json.dumps(payload, default=str)
-                self.config.warn(
-                    "Non-JSON value in event batch — coerced via str(). "
-                    "This indicates an event-sanitization gap; please report it."
-                )
+            body, events, left_out = self._serialized(payload)
+            self.drops.add(UNSENDABLE, left_out)
+            if body is None:
+                # no event JSON could write (each is counted): nothing to send, and the report waits
+                self.drops.put_back(report)
+                return _TAKEN
 
             # Send POST request
             kwargs = {"content": body}
             limit = timeout if timeout is not None else self.ship_timeout
             if limit is not None:
                 kwargs["timeout"] = limit
+            posting = True
             response = self.client.post(self.endpoint, **kwargs)
+            self._hold_reports = response.status_code != 200
 
             # Check response
             if response.status_code == 200:
                 self._note_discard(response, len(events))
                 self._note_refusals(response)
                 self.config.log(f"✅ Successfully shipped {len(events)} events")
-                return True
+                return _TAKEN
             else:
+                # Scope answered without taking the batch: the report goes with a later request, and
+                # the batch's events are counted by why they were given up on
+                self.drops.put_back(report)
+                self.drops.add(failed_send_kind(response.status_code), len(events))
                 self.config.log(
                     f"❌ Failed to ship events: HTTP {response.status_code} - {response.text}"
                 )
-                return False
+                return _NOT_TAKEN
 
-        except httpx.TimeoutException:
+        except httpx.TimeoutException as e:
             self.config.log("❌ Request timeout while shipping events")
-            return False
+            return self._gave_up_unanswered(report, e, posting, len(events))
 
         except httpx.HTTPError as e:
             self.config.log(f"❌ HTTP error while shipping events: {e}")
-            return False
+            return self._gave_up_unanswered(report, e, posting, len(events))
 
         except Exception as e:
             self.config.log(f"❌ Unexpected error while shipping events: {e}")
-            return False
+            return self._gave_up_unanswered(report, e, posting, len(events))
+
+    # A send that failed with one of these never left this machine: no connection was made.
+    _NEVER_LEFT = (httpx.ConnectError, httpx.ConnectTimeout, httpx.PoolTimeout, httpx.ProxyError,
+                   httpx.UnsupportedProtocol)
+
+    def _gave_up_unanswered(self, report, error: Exception, posting: bool, count: int) -> str:
+        """A send that got no answer; its events are counted. A report whose request may have arrived is
+        not sent again (a count is never sent twice); one whose request never left goes with a later
+        request. A request that went to Scope unanswered holds the reports until a batch is taken; a
+        send that failed before its request was made (building it raised) says nothing about Scope, and
+        its events count as unsendable."""
+        if not posting:
+            self.drops.put_back(report)
+            self.drops.add(UNSENDABLE, count)
+            return _NOT_TAKEN
+        self._hold_reports = True
+        if isinstance(error, self._NEVER_LEFT):
+            self.drops.put_back(report)
+        self.drops.add(UNREACHABLE, count)
+        return _UNANSWERED
+
+    def _serialized(self, payload: Dict[str, Any]):
+        """The request body, the events in it and how many were left out — the body None when no event
+        could be written.
+
+        Strict-first serialization with a LOUD lossy fallback: events are sanitized at build time, so the
+        strict path should always win — but a single stray non-JSON value must degrade to its string form
+        (with a warning), never lose the whole batch. An event JSON cannot write even as text — a cycle,
+        nesting too deep, a value whose text form raises — is left out alone (0.1.8; in 0.1.7 it lost the
+        whole batch before it was sent). The caller counts what was left out once the body is built."""
+        events = payload["events"]
+        try:
+            return json.dumps(payload), events, 0
+        except Exception:  # noqa: BLE001 - a value JSON cannot write as it is
+            pass
+        left_out = 0
+        try:
+            body = json.dumps(payload, default=str)
+        except Exception:  # noqa: BLE001 - a cycle, nesting too deep, a str() that raises
+            kept = self._writable(events)
+            left_out = len(events) - len(kept)
+            if not kept:
+                return None, kept, left_out
+            events, payload = kept, {**payload, "events": kept}
+            try:
+                return json.dumps(payload), events, left_out
+            except Exception:  # noqa: BLE001
+                body = json.dumps(payload, default=str)
+        self.config.warn(
+            "Non-JSON value in event batch — coerced via str(). "
+            "This indicates an event-sanitization gap; please report it."
+        )
+        return body, events, left_out
+
+    def _writable(self, events: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """The events JSON can write, at least as text, where they sit in a request; what is left out is
+        said once."""
+        kept = []
+        for event in events:
+            try:
+                json.dumps({"events": [event]}, default=str)  # as deep as it sits in the request
+                kept.append(event)
+            except Exception:  # noqa: BLE001 - a cycle, nesting too deep, a str() that raises
+                pass
+        if len(kept) < len(events) and not self._warned_unsendable:
+            self._warned_unsendable = True
+            self.config.warn(
+                f"{len(events) - len(kept)} event(s) held a value JSON cannot write even as text (a cycle, "
+                f"nesting too deep, or a value whose text form raises) and were left out; the rest of the "
+                f"batch was sent. Scope is told how many on a later request. This warning is shown once."
+            )
+        return kept
 
     def _note_discard(self, response, count: int) -> None:
         """A 200 can still mean "received and thrown away": the ingest service answers