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

{scope_analytics-0.1.7/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.7
+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.7 → scope_analytics-0.1.8}/scope_analytics/__init__.py

@@ -14,7 +14,8 @@ 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
@@ -246,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
@@ -464,6 +466,13 @@ 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
@@ -491,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.
@@ -691,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
@@ -713,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."
@@ -737,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.7 → 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

scope_analytics-0.1.8/scope_analytics/drops.py

@@ -0,0 +1,60 @@
+"""
+What this process gave up on before Scope had it, counted by kind and told to Scope on a later request
+(0.1.8): Setup, the nightly data watcher and the daily system check read it there. The kinds are Scope's
+own names (backend/app/services/arrival_counts.py DROP_REASONS); Scope ignores a kind it doesn't know.
+"""
+
+import threading
+from typing import Dict, Optional
+
+QUEUE_FULL = "queue_full"        # more events waiting than the queue holds: the oldest went
+REFUSED = "refused"              # Scope answered no for good (a wrong key, a request it will never take)
+UNSENDABLE = "unsendable"        # an event JSON cannot write even as text (a cycle, nesting too deep)
+UNREACHABLE = "unreachable"      # no answer: the connection failed, dropped, or timed out
+RATE_LIMITED = "rate_limited"    # Scope answered 429: more requests a minute than the key may send
+SERVER_ERROR = "server_error"    # Scope answered 5xx or 408: its own error, or no time to read the request
+
+# One report's count of one kind at most (Scope keeps no more of one); the rest waits for the next report.
+MAX_REPORTED = 50_000
+
+
+def failed_send_kind(status: Optional[int]) -> str:
+    """Why a batch was given up on, from Scope's answer to it (None: there was no answer)."""
+    if status is None:
+        return UNREACHABLE
+    if status == 429:
+        return RATE_LIMITED
+    if status == 408 or status >= 500:
+        return SERVER_ERROR
+    return REFUSED
+
+
+class DropCounts:
+    """Counts by kind, safe across the queue's shipping threads. A report taken into a request comes off
+    the counts; put back, it goes with a later request."""
+
+    def __init__(self):
+        self._lock = threading.Lock()
+        self._counts: Dict[str, int] = {}
+
+    def add(self, kind: str, n: int = 1) -> None:
+        if n > 0:
+            with self._lock:
+                self._counts[kind] = self._counts.get(kind, 0) + n
+
+    def take(self) -> Optional[Dict[str, int]]:
+        """The report for the request being built (None when nothing was dropped)."""
+        with self._lock:
+            report = {kind: min(n, MAX_REPORTED) for kind, n in self._counts.items() if n > 0}
+            for kind, n in report.items():
+                self._counts[kind] -= n
+        return report or None
+
+    def put_back(self, report: Optional[Dict[str, int]]) -> None:
+        for kind, n in (report or {}).items():
+            self.add(kind, n)
+
+    def counted(self) -> Dict[str, int]:
+        """What waits to be reported, by kind."""
+        with self._lock:
+            return {kind: n for kind, n in self._counts.items() if n > 0}

{scope_analytics-0.1.7 → scope_analytics-0.1.8}/scope_analytics/queue.py

@@ -10,6 +10,8 @@ import weakref
 from collections import deque
 from typing import Dict, Any, Callable, Optional
 
+from .drops import QUEUE_FULL
+
 
 class EventQueue:
     # Ceiling on concurrent shipping threads (see _flush_batch).
@@ -44,6 +46,7 @@ class EventQueue:
         config,
         event_enricher: Optional[Callable[[Dict[str, Any]], Dict[str, Any]]] = None,
         on_fork: Optional[Callable[[], None]] = None,
+        on_drop: Optional[Callable[[str, int], None]] = None,
     ):
         """
         Initialize event queue
@@ -61,6 +64,8 @@ class EventQueue:
             on_fork: Optional callable run in a forked CHILD right after this queue
                 restarts its flush thread there (the SDK uses it to replace the ship
                 client the child inherited).
+            on_drop: Optional callable told (kind, count) of events this queue lets go
+                (the SDK counts them for its next report to Scope; drops.py).
         """
         self.batch_size = batch_size
         self.batch_timeout_seconds = batch_timeout_seconds
@@ -69,6 +74,7 @@ class EventQueue:
         self.config = config
         self.event_enricher = event_enricher
         self.on_fork = on_fork
+        self.on_drop = on_drop
 
         self.queue = deque(maxlen=max_queue_size)
         self._warned_full = False  # the queue-full warning is emitted once, not per event
@@ -201,6 +207,7 @@ class EventQueue:
                         f"Raise max_queue_size, or reduce volume (SCOPE_CAPTURE_HTTP=false "
                         f"turns off outbound HTTP capture). This warning is shown once."
                     )
+                self._note_drop(QUEUE_FULL, 1)  # the deque lets the oldest go as this one goes in
 
             self.queue.append(event)
 
@@ -312,8 +319,17 @@ class EventQueue:
             self.config.log(f"Error flushing batch: {e}")
             # Re-queue events on failure
             with self.lock:
+                # past the queue's size, the deque lets go of what came in last (counted)
+                self._note_drop(QUEUE_FULL, len(self.queue) + len(batch) - self.max_queue_size)
                 self.queue.extendleft(reversed(batch))
 
+    def _note_drop(self, kind: str, count: int) -> None:
+        if count > 0 and self.on_drop is not None:
+            try:
+                self.on_drop(kind, count)
+            except Exception:  # noqa: BLE001 - counting a drop must never lose an event
+                pass
+
     def size(self) -> int:
         """Get current queue size"""
         with self.lock:

{scope_analytics-0.1.7 → scope_analytics-0.1.8}/scope_analytics/supported_versions.py

@@ -37,9 +37,10 @@ SUPPORTED_VERSIONS = {
         # both capture surfaces are unchanged — verified by the contract cells below (3.8.0 at
         # 0.1.3; 3.14.1 at 0.1.4; 3.24.0 at 0.1.5, which also added the with_raw_response cells; 3.26.1
         # by the 0.1.5 publish dry run, 2026-10-09 — the whole suite green on it but this drift check;
-        # 3.42.1 by the 0.1.6 publish dry run, 2026-11-03, the same way, and its contract cell).
-        "max_tested": "3.42.1",
-        "ci_matrix": ["1.0.0", "1.30.0", "1.57.0", "2.41.0", "2.46.0", "3.8.0", "3.14.1", "3.24.0", "3.26.1", "3.42.1"],
+        # 3.42.1 by the 0.1.6 publish dry run, 2026-11-03, the same way, and its contract cell; 3.44.0 by
+        # the 0.1.8 publish dry run, 2026-11-04, the same way, and its contract cell).
+        "max_tested": "3.44.0",
+        "ci_matrix": ["1.0.0", "1.30.0", "1.57.0", "2.41.0", "2.46.0", "3.8.0", "3.14.1", "3.24.0", "3.26.1", "3.42.1", "3.44.0"],
     },
     "anthropic": {
         "import_name": "anthropic",

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scope-analytics
-Version: 0.1.7
+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.7 → scope_analytics-0.1.8}/scope_analytics.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ scope_analytics/client.py
 scope_analytics/config.py
 scope_analytics/context.py
 scope_analytics/deployment.py
+scope_analytics/drops.py
 scope_analytics/events.py
 scope_analytics/middleware.py
 scope_analytics/queue.py
@@ -35,6 +36,7 @@ tests/test_client_ip.py
 tests/test_coverage_honesty.py
 tests/test_deployment.py
 tests/test_discard_reply.py
+tests/test_drop_reports_0_1_8.py
 tests/test_fork_safety.py
 tests/test_frameworks_langchain.py
 tests/test_http_patch.py
@@ -47,6 +49,7 @@ tests/test_manual_event_and_debug_output.py
 tests/test_patch_versions.py
 tests/test_query_scrub.py
 tests/test_redaction.py
+tests/test_shipping_pinned.py
 tests/test_tracking_0_1_7.py
 tests/test_tracking_pinned.py
 tests/test_user_facing.py

{scope_analytics-0.1.7 → scope_analytics-0.1.8}/setup.py

@@ -11,7 +11,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="scope-analytics",
-    version="0.1.7",
+    version="0.1.8",
     author="Scope AI",
     author_email="support@scopeai.dev",
     description="AI-powered analytics SDK for backend applications with automatic LLM tracking",