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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scope-analytics
-Version: 0.1.6
+Version: 0.1.7
 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.7}/scope_analytics/__init__.py

@@ -4,12 +4,13 @@ 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
@@ -83,6 +84,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
@@ -208,9 +268,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 +454,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
@@ -407,14 +468,21 @@ class ScopeAnalytics:
         # 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:
@@ -433,6 +501,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 +607,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 +617,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 +652,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,
         )
 

{scope_analytics-0.1.6 → scope_analytics-0.1.7}/scope_analytics/context.py

@@ -46,6 +46,33 @@ user_agent_context: contextvars.ContextVar[Optional[str]] = contextvars.ContextV
     'scope_user_agent', default=None
 )
 
+# What the SDK itself left in a context, as opposed to what a request or the app set there (0.1.7): the temp
+# session an event made up for want of one (ensure_session_id), and the user identify() bound. Outside a
+# request they are whoever came before — a worker's previous task, a script's previous person — so identify()
+# never links a person through them.
+_made_up_session_context: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
+    'scope_made_up_session', default=None
+)
+_bound_by_identify_context: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
+    'scope_bound_by_identify', default=None
+)
+
+# True for the length of a request a Scope middleware set up: every entry point reads the request's
+# identity from its headers (middleware._auto_set_identity_from_headers), and its values are that
+# request's, made up or not. Cleared with the request.
+_in_request_context: contextvars.ContextVar[bool] = contextvars.ContextVar(
+    'scope_in_request', default=False
+)
+
+# The Celery tasks this context is running, innermost last: (task id, the context kept for the code around it,
+# or None when the task runs inside a request) — ScopeContext.task_starts / task_ends. Never cleared by clear().
+_tasks_started_context: contextvars.ContextVar[tuple] = contextvars.ContextVar('scope_tasks_started', default=())
+
+# Everything a request — or a Celery task — has of its own: ScopeContext.clear() empties it, and a task
+# keeps it for the code around it (with the request mark, which clear() resets on its own).
+_PER_REQUEST = (session_id_context, user_id_context, anonymous_id_context, url_context, referrer_context,
+                thread_id_context, user_agent_context, _made_up_session_context, _bound_by_identify_context)
+
 # Recursion guard - prevents infinite loops when Scope tracks its own LLM calls
 # This is critical when Scope AI backend uses Scope SDK to track itself
 _in_scope_context: contextvars.ContextVar[bool] = contextvars.ContextVar(
@@ -132,6 +159,26 @@ def accepted_user_id(user_id: Any, call: str) -> Optional[str]:
     return text
 
 
+# Why an identify's link was not read, each said once per process (the type is named, never the value).
+_warned_refused_link: set = set()
+
+
+def accepted_link(link: Any) -> Optional[bool]:
+    """identify()'s ``link`` as Scope reads it: True or False, and None as the default, True (0.1.7). Anything
+    else is no answer: that identify is not sent, and why said once per process — a person linked to the wrong
+    activity stays linked, so a link Scope cannot read is never guessed either way."""
+    if link is None:
+        return True
+    if isinstance(link, bool):
+        return link
+    why = type(link).__name__
+    if why not in _warned_refused_link:
+        _warned_refused_link.add(why)
+        logging.getLogger("scope_analytics").warning(
+            "[Scope SDK] identify() takes link as True or False; an identify was not sent (a %s)", why)
+    return None
+
+
 class ScopeContext:
     """
     Manages request-scoped context using Python's contextvars.
@@ -149,6 +196,7 @@ class ScopeContext:
             session_id: Session ID from X-Scope-Session-ID header
         """
         session_id_context.set(session_id)
+        _made_up_session_context.set(None)
 
     @staticmethod
     def get_session_id() -> Optional[str]:
@@ -172,10 +220,49 @@ class ScopeContext:
         """
         if user_id is None:
             user_id_context.set(None)
+            _bound_by_identify_context.set(None)
             return
         accepted = accepted_user_id(user_id, "set_user_id")
         if accepted is not None:
             user_id_context.set(accepted)
+            _bound_by_identify_context.set(None)
+
+    @staticmethod
+    def bind_identified_user(user_id: str) -> None:
+        """Bind the user identify() named, so the rest of the request — or of the job — carries them (0.1.7:
+        marked as identify's own, never an earlier id for the next identify outside a request)."""
+        user_id_context.set(user_id)
+        _bound_by_identify_context.set(user_id)
+
+    @staticmethod
+    def enter_request() -> None:
+        """Mark this context as a request a Scope middleware set up, until the request clears it."""
+        _in_request_context.set(True)
+
+    @staticmethod
+    def in_request() -> bool:
+        """Whether this context is a request a Scope middleware set up."""
+        return _in_request_context.get()
+
+    @staticmethod
+    def earlier_identity() -> tuple:
+        """The earlier id and the session identify() links a person through: (earlier id, session or None).
+
+        Inside a request a Scope middleware set up (a WebSocket included, from 0.1.7), the request's own — its
+        browser's visitor id, else its user (its login token's, one the app set, or one an identify in it
+        bound), and its session — as before 0.1.7. Outside one (a job, a script, a webhook loop, a framework
+        Scope does not patch) only what the app set itself with set_anonymous_id / set_user_id / set_session_id: never the
+        user an earlier identify() bound, nor the temp session an earlier event made up — those belong to
+        whoever came before (0.1.7)."""
+        if _in_request_context.get():
+            return anonymous_id_context.get() or user_id_context.get(), session_id_context.get()
+        user = user_id_context.get()
+        if user is not None and user == _bound_by_identify_context.get():
+            user = None
+        session = session_id_context.get()
+        if session is not None and session == _made_up_session_context.get():
+            session = None
+        return anonymous_id_context.get() or user, session
 
     @staticmethod
     def get_user_id() -> Optional[str]:
@@ -247,13 +334,40 @@ class ScopeContext:
         Clear all context variables
         Should be called after request completes to prevent leaks
         """
-        session_id_context.set(None)
-        user_id_context.set(None)
-        anonymous_id_context.set(None)
-        url_context.set(None)
-        referrer_context.set(None)
-        thread_id_context.set(None)
-        user_agent_context.set(None)
+        for var in _PER_REQUEST:
+            var.set(None)
+        _in_request_context.set(False)
+
+    # A Celery task starts with none of what the task before it left — the user it identified, the session its
+    # AI calls made up, a session or user the app set for it — and whatever ran it gets its own context back when
+    # it ends: an eager task runs inline, in its caller's context (0.1.7). The contexts kept are a stack of the
+    # context's own (_tasks_started_context), innermost last: a task's end finds its own start even when nested
+    # eager tasks share an id, and threads (-P threads), greenlets and asyncio tasks each keep their own.
+
+    @staticmethod
+    def task_starts(task_id: Any) -> None:
+        """Celery's task_prerun: keep the context around the task, and start the task with an empty one. An
+        eager task run inside a request is part of that request, and keeps its context (its start still keeps
+        its place, so its end gives back nothing)."""
+        kept = None if _in_request_context.get() else tuple(var.get() for var in _PER_REQUEST)
+        _tasks_started_context.set(_tasks_started_context.get() + ((task_id, kept),))
+        if kept is not None:
+            ScopeContext.clear()
+
+    @staticmethod
+    def task_ends(task_id: Any) -> None:
+        """Celery's task_postrun: give back the context the task started from — and outside a request again.
+        A task whose end never came (a killed child) is dropped with it."""
+        started = _tasks_started_context.get()
+        for at in range(len(started) - 1, -1, -1):
+            if started[at][0] == task_id:
+                _tasks_started_context.set(started[:at])
+                kept = started[at][1]
+                if kept is not None:
+                    for var, value in zip(_PER_REQUEST, kept):
+                        var.set(value)
+                    _in_request_context.set(False)
+                return
 
     # 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
@@ -299,6 +413,7 @@ class ScopeContext:
         if not session_id:
             session_id = ScopeContext.generate_temp_session_id()
             session_id_context.set(session_id)
+            _made_up_session_context.set(session_id)
         return session_id
 
     @staticmethod