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

{scope_analytics-0.1.5/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.5
+Version: 0.1.7
 Summary: AI-powered analytics SDK for backend applications with automatic LLM tracking
 Home-page: https://scopeai.dev
 Author: Scope AI
@@ -185,7 +185,7 @@ 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) |
 

{scope_analytics-0.1.5 → scope_analytics-0.1.7}/README.md

@@ -130,7 +130,7 @@ 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) |
 

{scope_analytics-0.1.5 → 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 Optional
+from typing import Any, Optional
 
 from .config import ScopeConfig, DEFAULT_REDACT_PATTERNS
-from .context import ScopeContext
+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):
         """
@@ -503,6 +582,12 @@ class ScopeAnalytics:
         # 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
@@ -522,7 +607,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, link: Optional[bool] = True):
         """
         Identify a user and stitch their prior anonymous activity to them.
 
@@ -532,34 +617,68 @@ 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, 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)
+            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.
         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
+        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.5 → scope_analytics-0.1.7}/scope_analytics/client.py

@@ -42,6 +42,8 @@ class ScopeAPIClient:
 
         # Discard reasons already said (see _note_discard) — once each, not per batch.
         self._warned_discard_reasons = set()
+        # Single events refused or changed, by (kind, field, reason), already said (_note_refusals).
+        self._warned_refusals = set()
 
         # Create HTTP client
         self.client = self._build_http_client(config)
@@ -156,6 +158,7 @@ class ScopeAPIClient:
             # 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
             else:
@@ -181,7 +184,8 @@ class ScopeAPIClient:
         ``{"status": "discarded", "reason": ...}`` for a batch it will not keep — an IP the
         project excludes, for instance. Reading only the status code made such batches
         vanish without a word (the SDK logged "shipped"; the dashboard showed nothing).
-        Said once per reason, with where to look."""
+        Said once per reason, with where to look. (Single events it refused or changed:
+        _note_refusals.)"""
         try:
             body = response.json()
         except Exception:  # noqa: BLE001 - a non-JSON 200 is a stored batch as far as we know
@@ -193,8 +197,8 @@ class ScopeAPIClient:
             return
         self._warned_discard_reasons.add(reason)
         # The ingest's IP-exclusion reasons are user_excluded_ip and auto_excluded_login_ip
-        # (datacenter_ip exists but never fires for backend events); anything else gets the
-        # generic pointer rather than a guess.
+        # (the datacenter filter that never ran was removed from ingest on 2026-10-09); anything
+        # else gets the generic pointer rather than a guess.
         if reason.endswith("_ip"):
             where = (
                 "Events from this machine's IP are excluded for this project — see Setup → "
@@ -208,6 +212,37 @@ class ScopeAPIClient:
             f"This is said once per reason."
         )
 
+    def _note_refusals(self, response) -> None:
+        """The ingest judges each event on its own: one it cannot keep is refused alone, and one
+        it keeps with a change (an id it cannot keep, half of a character) is stored without it
+        — and the 200 says so, under ``rejected`` and ``repaired``: each event's place in the
+        batch, the field and the reason. Until the ingest judged each event, one such event
+        refused the whole batch. Said once per (field, reason), like a discard."""
+        try:
+            body = response.json()
+        except Exception:  # noqa: BLE001 - a non-JSON 200 is a stored batch as far as we know
+            return
+        if not isinstance(body, dict):
+            return
+        said = {
+            "rejected": "Scope refused an event ({why}); each event of a batch is judged on its own. "
+                        "This is said once per reason.",
+            "repaired": "Scope stored an event with a change ({why}). This is said once per reason.",
+        }
+        for kind, text in said.items():
+            problems = body.get(kind)
+            for problem in problems if isinstance(problems, list) else []:
+                if not isinstance(problem, dict):
+                    continue
+                field, reason = problem.get("field"), problem.get("reason")
+                # a reply not shaped as ours is not ours to say (nor to fail the shipped batch over)
+                if not isinstance(reason, str) or not (field is None or isinstance(field, str)):
+                    continue
+                if (kind, field, reason) in self._warned_refusals:
+                    continue
+                self._warned_refusals.add((kind, field, reason))
+                self.config.warn(text.format(why=f"{field}: {reason}" if field else reason))
+
     def test_connection(self) -> bool:
         """
         Test connection to API

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

@@ -6,7 +6,9 @@ Handles session ID propagation across async boundaries
 import contextvars
 import functools
 import inspect
-from typing import Optional
+import logging
+import numbers
+from typing import Any, Optional
 from contextlib import contextmanager
 import uuid
 
@@ -44,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(
@@ -70,6 +99,86 @@ _provider_call_in_flight: contextvars.ContextVar[bool] = contextvars.ContextVar(
 )
 
 
+# The longest id Scope keeps — a session, a visitor, a user: the ingest refuses a longer one (the Node
+# SDK's MAX_ID_LENGTH).
+MAX_ID_LENGTH = 100
+
+
+def fit_id(value: Any) -> Optional[str]:
+    """A session or visitor id from a request header as Scope keeps it: the text without the spaces
+    around it, of 1 to MAX_ID_LENGTH characters, else None — never cut, since a cut id could name
+    another session or visitor (0.1.6; the Node SDK's fitId). A session header that is not one falls
+    back to a temp session, as a missing one does."""
+    if not isinstance(value, str):
+        return None
+    value = value.strip()
+    return value if 0 < len(value) <= MAX_ID_LENGTH else None
+
+
+# Why an app's id was ignored, each said once per process (a refused type is named, never the id).
+_warned_refused_user_id: set = set()
+
+
+def _refused(call: str, why: str) -> None:
+    if why not in _warned_refused_user_id:
+        _warned_refused_user_id.add(why)
+        logging.getLogger("scope_analytics").warning(
+            "[Scope SDK] %s() takes your app's id for the user — text, a whole number, a UUID or an ObjectId, "
+            "up to %d characters; one was ignored (%s)", call, MAX_ID_LENGTH, why)
+    return None
+
+
+def accepted_user_id(user_id: Any, call: str) -> Optional[str]:
+    """The app's id for a user as Scope keeps it — its text, of 1 to MAX_ID_LENGTH characters — or None,
+    and why said once per process (0.1.6). Text is kept as given; a whole number becomes its digits (42
+    and "42" are one person: a number used to ride the event as a number, and identify(0) was ignored as
+    if no id had been given); a UUID or an ObjectId (a Mongo id, Beanie's too) becomes its text, as 0.1.5
+    sent it. True/False, a float, a list and any other object are no id: Scope would keep whatever its
+    text happens to be (the Node SDK's rule refuses an object for the same reason; it keeps any number).
+    None gives no id and says nothing."""
+    if user_id is None:
+        return None
+    if isinstance(user_id, bool):
+        return _refused(call, "true/false")
+    if isinstance(user_id, numbers.Integral):
+        # past 100 digits it is no id; refused before it is turned into text, which Python 3.11+ refuses
+        # for one of more than 4,300 digits by raising — into the app's own call
+        if int(user_id).bit_length() > 333:   # 10**100 is 333 bits: anything longer has over 100 digits
+            return _refused(call, f"over {MAX_ID_LENGTH} characters")
+        text = str(int(user_id))
+    elif isinstance(user_id, str):
+        text = user_id
+    elif isinstance(user_id, uuid.UUID) or any(c.__name__ == "ObjectId" for c in type(user_id).__mro__):
+        text = str(user_id)
+    else:
+        return _refused(call, f"a {type(user_id).__name__}")
+    if not text:
+        return _refused(call, "empty")
+    if len(text) > MAX_ID_LENGTH:
+        return _refused(call, f"over {MAX_ID_LENGTH} characters")
+    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.
@@ -87,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]:
@@ -99,14 +209,60 @@ class ScopeContext:
         return session_id_context.get()
 
     @staticmethod
-    def set_user_id(user_id: str) -> None:
+    def set_user_id(user_id: Any) -> None:
         """
         Set the user ID for the current context
 
         Args:
-            user_id: User ID from backend application
+            user_id: The app's id for the user — text, a whole number (kept as its digits), a UUID or an
+                ObjectId, up to 100 characters; anything else is ignored, and why said once (0.1.6). None
+                clears it.
         """
+        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]:
@@ -178,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
@@ -230,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

{scope_analytics-0.1.5 → scope_analytics-0.1.7}/scope_analytics/events.py

@@ -153,6 +153,10 @@ class EventFormatter:
             "timestamp": datetime.now(timezone.utc).isoformat(),
             "session_id": session_id or ScopeContext.ensure_session_id(),
             "user_id": user_id,
+            # the browser's visitor id (X-Scope-Anonymous-ID), when a page running Scope's script made the
+            # request — beside user_id, which a login token's user replaces (0.1.6): the sign-in and the
+            # browser it was used in, recorded together. None when no page sent one.
+            "anonymous_id": ScopeContext.get_anonymous_id(),
 
             # Request context for conversation correlation
             # This enables the fallback chain: thread_id → session_id+url → session_id
@@ -234,6 +238,7 @@ class EventFormatter:
             "timestamp": datetime.now(timezone.utc).isoformat(),
             "session_id": session_id or ScopeContext.ensure_session_id(),
             "user_id": user_id,
+            "anonymous_id": ScopeContext.get_anonymous_id(),   # as on llm_call (0.1.6)
 
             # HTTP request specific fields
             "method": method,
@@ -330,6 +335,7 @@ class EventFormatter:
             # count. One background session per process says what actually happened.
             "session_id": session_id or ScopeContext.background_session_id(),
             "user_id": user_id,
+            "anonymous_id": ScopeContext.get_anonymous_id(),   # as on llm_call (0.1.6)
 
             # API call specific fields
             "method": method,