scope-analytics 0.1.1__tar.gz → 0.1.2__tar.gz

{scope_analytics-0.1.1/scope_analytics.egg-info → scope_analytics-0.1.2}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: scope-analytics
-Version: 0.1.1
+Version: 0.1.2
 Summary: AI-powered analytics SDK for backend applications with automatic LLM tracking
-Home-page: https://github.com/scopeai/scope-analytics-python
+Home-page: https://scopeai.dev
 Author: Scope AI
 Author-email: support@scopeai.dev
 Classifier: Development Status :: 3 - Alpha
@@ -30,6 +30,10 @@ Provides-Extra: openai
 Requires-Dist: openai>=1.0.0; extra == "openai"
 Provides-Extra: anthropic
 Requires-Dist: anthropic>=0.18.0; extra == "anthropic"
+Provides-Extra: gemini
+Requires-Dist: google-generativeai>=0.3.0; extra == "gemini"
+Provides-Extra: google-genai
+Requires-Dist: google-genai>=1.0.0; extra == "google-genai"
 Provides-Extra: langchain
 Requires-Dist: langchain>=0.1.0; extra == "langchain"
 Dynamic: author

scope_analytics-0.1.2/scope_analytics/__init__.py

@@ -0,0 +1,481 @@
+"""
+Scope Analytics - Backend SDK
+AI-powered analytics with automatic LLM conversation tracking
+"""
+
+import atexit
+import logging
+from typing import Optional
+
+from .config import ScopeConfig, DEFAULT_REDACT_PATTERNS
+from .context import ScopeContext
+from .deployment import DeploymentContext
+from .events import EventFormatter
+from .queue import EventQueue
+from .client import ScopeAPIClient
+from .patches.openai_patch import OpenAIPatcher
+from .patches.anthropic_patch import AnthropicPatcher
+from .patches.gemini_patch import GeminiPatcher
+from .patches.google_genai_patch import GoogleGenaiPatcher
+from .middleware import (
+    ScopeSessionMiddleware,
+    FlaskScopeMiddleware,
+    init_flask_session_tracking,
+    DjangoScopeMiddleware,
+)
+
+def _resolve_version() -> str:
+    """Single source of truth: the installed distribution's own metadata.
+
+    Hardcoding this drifted once already — 0.1.1 shipped stamping every event as
+    "0.1.0", which made it impossible to tell from our own ingested data which SDK a
+    customer was running (exactly what you need to triage an SDK bug). Deriving it
+    means setup.py is the only place a version lives.
+    """
+    try:
+        from importlib.metadata import version, PackageNotFoundError
+        try:
+            return version("scope-analytics")
+        except PackageNotFoundError:
+            return "0.0.0+unknown"  # running from a source tree, not installed
+    except Exception:  # noqa: BLE001 - never let version lookup break an import
+        return "0.0.0+unknown"
+
+
+__version__ = _resolve_version()
+__all__ = [
+    "ScopeAnalytics",
+    "ScopeContext",
+    "ScopeConfig",
+    "DEFAULT_REDACT_PATTERNS",      # default credential-scrub patterns (on by default; [] to opt out)
+    "get_sdk_instance",
+    # Middleware exports
+    "ScopeSessionMiddleware",      # For FastAPI/Starlette
+    "FlaskScopeMiddleware",        # For Flask (WSGI wrapper)
+    "init_flask_session_tracking", # For Flask (hooks approach)
+    "DjangoScopeMiddleware",       # For Django
+]
+
+# Global SDK instance reference for middleware access
+# This allows middleware to capture HTTP request events without requiring
+# explicit SDK reference in user code
+_global_sdk_instance: Optional["ScopeAnalytics"] = None
+
+
+def get_sdk_instance() -> Optional["ScopeAnalytics"]:
+    """
+    Get the global SDK instance.
+
+    Returns:
+        ScopeAnalytics instance if initialized, None otherwise
+    """
+    return _global_sdk_instance
+
+
+def _set_sdk_instance(instance: "ScopeAnalytics") -> None:
+    """
+    Set the global SDK instance.
+    Called internally when ScopeAnalytics is initialized.
+    """
+    global _global_sdk_instance
+    _global_sdk_instance = instance
+
+
+class ScopeAnalytics:
+    """
+    Main SDK class for Scope Analytics
+
+    Usage:
+        scope = ScopeAnalytics(api_key="sk_live_...")
+
+        # SDK automatically patches OpenAI, Anthropic, LangChain
+        # All LLM calls are captured and sent to Scope AI
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        endpoint: Optional[str] = None,
+        auto_patch: bool = True,
+        batch_size: int = 10,
+        batch_timeout_seconds: int = 5,
+        max_queue_size: int = 1000,
+        debug: bool = False,
+        environment: Optional[str] = None,
+    ):
+        """
+        Initialize Scope Analytics SDK
+
+        A missing or malformed API key does NOT raise: the SDK emits one
+        always-visible warning and constructs itself disabled — no patching, no
+        event capture, every public method a no-op — so a config typo can never
+        take the host application down (PRODUCT.md §2, Robustness: analytics must never break
+        the host app; fail loudly, not silently).
+
+        Args:
+            api_key: Secret API key (sk_live_... or sk_test_...)
+            endpoint: API endpoint URL (default: https://api.scopeai.dev)
+            auto_patch: Automatically patch LLM libraries (default: True)
+            batch_size: Events per batch (default: 10)
+            batch_timeout_seconds: Max wait before sending partial batch (default: 5)
+            max_queue_size: Max events to queue (default: 1000)
+            debug: Enable debug logging (default: False)
+            environment: Environment name (default: production)
+        """
+        # Defined before anything can fail so every instance — including a
+        # disabled shell — carries it, and the no-op guards below never AttributeError.
+        self.enabled = True
+
+        # Initialize configuration. Only ValueError is caught: it is the specific,
+        # known config-validation failure (missing key, wrong prefix). Any other
+        # exception is an SDK bug and must still surface in development. The
+        # zero-code path (auto.py) already degrades this way; the manual path has
+        # to behave identically or a typo'd key crashes the app at startup.
+        try:
+            self.config = ScopeConfig(
+                api_key=api_key,
+                endpoint=endpoint,
+                auto_patch=auto_patch,
+                batch_size=batch_size,
+                batch_timeout_seconds=batch_timeout_seconds,
+                max_queue_size=max_queue_size,
+                debug=debug,
+                environment=environment,
+            )
+        except ValueError as e:
+            # self.config doesn't exist yet, so go straight to the same
+            # always-visible logger channel ScopeConfig.warn() uses.
+            logging.getLogger("scope_analytics").warning(
+                "[Scope SDK] %s Scope Analytics is DISABLED — no events will be "
+                "captured and no LLM libraries will be patched.",
+                e,
+            )
+            self.enabled = False
+            # Heavy components (formatter, client, deployment, queue, patchers)
+            # stay unconstructed: no background thread, no atexit hook, and no
+            # global registration — a disabled instance must never become the
+            # middleware's SDK.
+            self.patches = []
+            self.uncovered_llm_libraries = []
+            self._llm_sdks_detected = []
+            return
+
+        # Initialize components
+        self.event_formatter = EventFormatter(self.config)
+        self.client = ScopeAPIClient(self.config)
+
+        # Capture deployment + commit identity once at startup (PRODUCT.md §4.2).
+        # Its .stamp is wired as the queue enricher so git_sha/deployment_id land
+        # on every event through a single chokepoint.
+        self.deployment = DeploymentContext(self.config)
+
+        self.queue = EventQueue(
+            batch_size=self.config.batch_size,
+            batch_timeout_seconds=self.config.batch_timeout_seconds,
+            max_queue_size=self.config.max_queue_size,
+            flush_callback=self._flush_events,
+            config=self.config,
+            event_enricher=self.deployment.stamp,
+        )
+
+        # Initialize patchers
+        self.openai_patcher = OpenAIPatcher(self)
+        self.anthropic_patcher = AnthropicPatcher(self)
+        self.gemini_patcher = GeminiPatcher(self)            # legacy google-generativeai (EOL)
+        self.google_genai_patcher = GoogleGenaiPatcher(self)  # unified google-genai (modern)
+        self.patches = []  # List of successfully applied patches
+        self.uncovered_llm_libraries = []  # Known-uncovered LLM libs detected at startup
+        self._llm_sdks_detected = []  # Recognized SDKs whose import succeeded (≠ patched)
+
+        # Start queue background thread
+        self.queue.start()
+
+        # Register shutdown hook
+        atexit.register(self.shutdown)
+
+        self.config.log("Scope Analytics SDK initialized")
+        self.config.log(f"Configuration: {self.config.to_dict()}")
+
+        # Register as global instance for middleware access
+        _set_sdk_instance(self)
+
+        # Auto-patch LLM libraries if enabled
+        if self.config.auto_patch:
+            self._apply_patches()
+
+        # Emit a single deployment_detected event when this boot's commit differs
+        # from the previous boot's (PRODUCT.md §4.2). No-op when no SHA is known.
+        self._emit_deployment_detected()
+
+    def _emit_deployment_detected(self):
+        """Emit one deployment_detected event per new commit (best-effort)."""
+        try:
+            if self.deployment.should_emit_deployment_detected():
+                # Only claim a coverage snapshot when patching actually ran —
+                # auto_patch=False means "unknown", not "none". Package names
+                # throughout ('gemini' is the internal patcher key).
+                coverage = None
+                if self.config.auto_patch:
+                    name_map = {"gemini": "google-generativeai"}
+                    coverage = {
+                        "patched_llm_libraries": [name_map.get(p, p) for p in self.patches],
+                        "uncovered_llm_libraries": list(self.uncovered_llm_libraries),
+                    }
+                event = self.deployment.build_deployment_event(coverage=coverage)
+                if self.event_formatter.validate_event(event):
+                    self.queue.enqueue(event)
+                    self.config.log(
+                        f"Deployment detected: {self.deployment.deployment_id} "
+                        f"(git_sha={self.deployment.git_sha})"
+                    )
+        except Exception as e:
+            # Never let deployment detection break SDK startup.
+            self.config.log(f"Failed to emit deployment_detected: {e}")
+
+    def _apply_patches(self):
+        """Apply monkey patches to LLM libraries"""
+        self.config.log("Auto-patching enabled - will patch LLM libraries")
+
+        # Patch OpenAI
+        try:
+            import openai
+            self._llm_sdks_detected.append('openai')
+            self.config.log("OpenAI library detected - patching...")
+            if self.openai_patcher.patch():
+                self.patches.append('openai')
+            else:
+                # The library is present but we failed to instrument it: the app will run
+                # fine and capture NOTHING. Never let that pass silently.
+                self.config.warn(
+                    "openai is installed but Scope could not instrument it — "
+                    "LLM calls will NOT be captured. Set SCOPE_DEBUG=true for details."
+                )
+        except ImportError:
+            self.config.log("OpenAI library not installed - skipping patch")
+
+        # Patch Anthropic
+        try:
+            import anthropic
+            self._llm_sdks_detected.append('anthropic')
+            self.config.log("Anthropic library detected - patching...")
+            if self.anthropic_patcher.patch():
+                self.patches.append('anthropic')
+            else:
+                self.config.warn(
+                    "anthropic is installed but Scope could not instrument it — "
+                    "LLM calls will NOT be captured. Set SCOPE_DEBUG=true for details."
+                )
+        except ImportError:
+            self.config.log("Anthropic library not installed - skipping patch")
+
+        # Patch Google Gemini — legacy google-generativeai SDK (deprecated/EOL 2025-11-30) ...
+        try:
+            import google.generativeai
+            self._llm_sdks_detected.append('google-generativeai')
+            self.config.log("Google Generative AI (legacy) library detected - patching...")
+            if self.gemini_patcher.patch():
+                self.patches.append('gemini')
+            else:
+                self.config.warn(
+                    "google-generativeai is installed but Scope could not instrument it — "
+                    "LLM calls will NOT be captured. Set SCOPE_DEBUG=true for details."
+                )
+        except ImportError:
+            self.config.log("Google Generative AI (legacy) library not installed - skipping patch")
+
+        # ... and the modern unified google-genai SDK (the recommended replacement). Both are patched
+        # additively so legacy and new Gemini users are covered.
+        try:
+            import google.genai  # noqa: F401
+            self._llm_sdks_detected.append('google-genai')
+            self.config.log("google-genai (unified) library detected - patching...")
+            if self.google_genai_patcher.patch():
+                self.patches.append('google-genai')
+            else:
+                self.config.warn(
+                    "google-genai is installed but Scope could not instrument it — "
+                    "LLM calls will NOT be captured. Set SCOPE_DEBUG=true for details."
+                )
+        except ImportError:
+            self.config.log("google-genai (unified) library not installed - skipping patch")
+
+        self._report_coverage_gaps()
+
+    def _report_coverage_gaps(self):
+        """Coverage honesty at startup (rule b): a known gap must never look like
+        working coverage.
+
+        Two silences this kills: (1) a KNOWN-uncovered LLM library (litellm, cohere)
+        installed alongside — or instead of — the SDKs we patch; (2) no recognized LLM
+        SDK at all, where zero output is indistinguishable from zero traffic. Detection
+        is metadata-only (find_spec never imports the target) and totally fail-safe.
+        """
+        try:
+            import importlib.util
+            from .supported_versions import KNOWN_UNCOVERED
+            for lib, why in KNOWN_UNCOVERED.items():
+                try:
+                    if importlib.util.find_spec(lib) is not None:
+                        self.uncovered_llm_libraries.append(lib)
+                        self.config.warn(f"{lib} detected but NOT captured by Scope: {why}")
+                except Exception:
+                    continue  # one undetectable lib must not silence the others
+            if not self._llm_sdks_detected and not self.uncovered_llm_libraries:
+                self.config.warn(
+                    "No supported LLM SDK detected (openai / anthropic / google-genai / "
+                    "google-generativeai) — no LLM calls will be captured. Frontend and "
+                    "backend events still flow. If this app calls an LLM through another "
+                    "library, capture it manually with scope.track_event(...)."
+                )
+        except Exception as e:
+            # Coverage reporting must never break startup.
+            self.config.log(f"Coverage-gap check failed: {e}")
+
+    def track_event(self, event_type: str, properties: dict):
+        """
+        Manually track an event
+
+        Args:
+            event_type: Type of event (e.g., "llm_call", "external_api_call")
+            properties: Event properties
+        """
+        # Disabled construction has no formatter/queue (and possibly no config) —
+        # the one loud warning already fired at init, so just drop the event.
+        if not self.enabled:
+            return
+
+        self.config.log(f"Tracking event: {event_type}")
+
+        # Create event with standard fields
+        event = {
+            "event_type": event_type,
+            "source": self.config.sdk_source,
+            **properties
+        }
+
+        # Manual callers shouldn't need boilerplate: default the fields
+        # validate_event requires (never overriding caller-provided values).
+        # Without these defaults a bare track_event(...) call — exactly what the
+        # docs and the MCP coverage report tell users to write for uncovered
+        # libraries — was silently dropped at validation.
+        from datetime import datetime, timezone
+        event.setdefault("timestamp", datetime.now(timezone.utc).isoformat())
+        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
+            # per-request reset, that stitches every later event (manual AND
+            # auto-captured) into one bogus session. Same decision as events.py's
+            # http_request path. The lazy `if` also avoids evaluating any of this
+            # when the caller supplied a session_id.
+            event["session_id"] = (ScopeContext.get_session_id()
+                                   or ScopeContext.generate_temp_session_id())
+
+        # Validate and enqueue
+        if self.event_formatter.validate_event(event):
+            self.queue.enqueue(event)
+        else:
+            # A rejected manual event must not vanish silently.
+            self.config.warn(
+                f"Manual event '{event_type}' failed validation and was dropped."
+            )
+
+    def identify(self, user_id: str, traits: Optional[dict] = None):
+        """
+        Identify a user and stitch their prior anonymous activity to them.
+
+        Emits an ``identify`` event that the backend uses to merge the user's
+        anonymous session into this identified user — matched by the shared
+        ``session_id`` (the FE↔BE fingerprint) and/or the prior ``anonymous_id``
+        — and to attach the given traits. Also binds the identified user to the
+        current request context so subsequent events are attributed to them.
+
+        Args:
+            user_id: Unique user identifier (whatever your app uses — email, sub, etc.)
+            traits: Optional user traits (e.g., email, name, plan)
+        """
+        # 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:
+            self.config.log("identify() called without a user_id - ignoring")
+            return
+
+        # 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()
+
+        # Bind the identified user so later events in this request use it.
+        ScopeContext.set_user_id(user_id)
+
+        event = self.event_formatter.format_identify(
+            identified_user_id=user_id,
+            anonymous_id=anonymous_id,
+            session_id=session_id,
+            traits=traits,
+        )
+
+        if self.event_formatter.validate_event(event):
+            self.queue.enqueue(event)
+            self.config.log(
+                f"Identified user: {user_id} "
+                f"(anonymous_id={event.get('anonymous_id')}, session={event.get('session_id')})"
+            )
+            if traits:
+                self.config.log(f"User traits: {traits}")
+
+    def _flush_events(self, events: list):
+        """
+        Callback for flushing events to API
+        Called by event queue when batch is ready
+
+        Args:
+            events: List of events to flush
+        """
+        success = self.client.ship_events(events)
+
+        if not success:
+            self.config.log(f"⚠️ Failed to ship {len(events)} events")
+
+    def shutdown(self):
+        """
+        Gracefully shutdown SDK
+        Flushes remaining events and cleans up resources
+        """
+        # Disabled construction never started a queue, opened a client, or applied
+        # patches — nothing to tear down, so shutdown is a silent no-op.
+        if not self.enabled:
+            return
+
+        self.config.log("Shutting down Scope Analytics SDK...")
+
+        # Bound how long telemetry may delay process exit: the final synchronous
+        # flush ships with a short timeout (vs the 30s steady-state client timeout)
+        # 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
+
+        # Stop queue and flush remaining events
+        if self.queue:
+            self.queue.stop()
+
+        # Close HTTP client
+        if self.client:
+            self.client.close()
+
+        # Remove patches
+        if 'openai' in self.patches:
+            self.openai_patcher.unpatch()
+        if 'anthropic' in self.patches:
+            self.anthropic_patcher.unpatch()
+        if 'gemini' in self.patches:
+            self.gemini_patcher.unpatch()
+        if 'google-genai' in self.patches:
+            self.google_genai_patcher.unpatch()
+
+        self.config.log("Scope Analytics SDK shutdown complete")

{scope_analytics-0.1.1 → scope_analytics-0.1.2}/scope_analytics/auto.py

@@ -75,6 +75,13 @@ def _auto_init():
             auto_patch=True,  # Always auto-patch in auto mode
         )
 
+        if not getattr(_scope_instance, 'enabled', True):
+            # ScopeAnalytics self-disabled (bad key) and already warned loudly.
+            # Don't hold the disabled instance: is_initialized() must report the
+            # truth — nothing is being captured.
+            _scope_instance = None
+            return None
+
         _log("Scope Analytics initialized successfully")
 
         # Auto-inject session middleware for known frameworks

{scope_analytics-0.1.1 → scope_analytics-0.1.2}/scope_analytics/client.py

@@ -3,6 +3,8 @@ HTTP client for shipping events to Scope Analytics API
 Handles async communication with the backend API
 """
 
+import json
+
 import httpx
 from typing import List, Dict, Any
 
@@ -28,6 +30,10 @@ class ScopeAPIClient:
         self.config = config
         self.endpoint = f"{config.endpoint}/api/events"
 
+        # Per-request timeout override; shutdown sets this to a small value so the
+        # final synchronous flush can't hold process exit for the full 30s.
+        self.ship_timeout = None
+
         # Create HTTP client
         self.client = httpx.Client(
             timeout=30.0,
@@ -62,11 +68,24 @@ class ScopeAPIClient:
                 "source": self.config.sdk_source,
             }
 
+            # 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."
+                )
+
             # Send POST request
-            response = self.client.post(
-                self.endpoint,
-                json=payload
-            )
+            kwargs = {"content": body}
+            if self.ship_timeout is not None:
+                kwargs["timeout"] = self.ship_timeout
+            response = self.client.post(self.endpoint, **kwargs)
 
             # Check response
             if response.status_code == 200:

{scope_analytics-0.1.1 → scope_analytics-0.1.2}/scope_analytics/config.py

@@ -3,6 +3,7 @@ Configuration management for Scope Analytics SDK
 """
 
 import os
+import logging
 from typing import Optional, Dict, Any
 from dotenv import load_dotenv
 
@@ -10,6 +11,22 @@ from dotenv import load_dotenv
 load_dotenv()
 
 
+# Default credential-redaction patterns — applied BY DEFAULT (see ScopeConfig.redact_patterns; pass
+# redact_patterns=[] to opt out and store raw). Each captures the KEY as group 1 and matches the
+# secret VALUE *outside* the group, so the substitution r"\1***REDACTED***" keeps the key and DROPS
+# the value: "password=hunter2" -> "password=***REDACTED***". Credential strings have no analytical
+# value, so scrubbing them by default is a safe net for accidental secrets. Best-effort over free
+# text (prompt + response + message contents) — NOT a structural guarantee: it won't catch secrets in
+# non-"key=value" shapes (e.g. JSON '"api_key":"..."'), so it's a safety net, not a privacy guarantee.
+# Broader PII / content redaction stays opt-in (supply your own patterns).
+DEFAULT_REDACT_PATTERNS = [
+    r"(password\s*=\s*['\"]?)[^'\"\s]+",
+    r"(api[_-]?key\s*=\s*['\"]?)[^'\"\s]+",
+    r"(token\s*=\s*['\"]?)[^'\"\s]+",
+    r"(secret\s*=\s*['\"]?)[^'\"\s]+",
+]
+
+
 class ScopeConfig:
     """Configuration for Scope Analytics SDK"""
 
@@ -37,7 +54,10 @@ class ScopeConfig:
             max_queue_size: Maximum events to queue (oldest dropped if exceeded)
             debug: Enable debug logging
             environment: Environment name (production, staging, development)
-            redact_patterns: List of regex patterns to redact from events
+            redact_patterns: Regex patterns to scrub from prompt/response/bodies. Default None =
+                credential scrub ON (DEFAULT_REDACT_PATTERNS — password/api_key/token/secret in
+                key=value form). Pass [] to opt out and store raw at full fidelity, or your own
+                patterns to scrub more (each must capture the key as group 1).
         """
         # API Key - required
         self.api_key = api_key or os.getenv("SCOPE_API_KEY")
@@ -70,16 +90,18 @@ class ScopeConfig:
         self.debug = debug or os.getenv("SCOPE_DEBUG", "").lower() == "true"
         self.environment = environment or os.getenv("SCOPE_ENVIRONMENT", "production")
 
-        # Privacy
-        self.redact_patterns = redact_patterns or [
-            r"password\s*=\s*['\"]?([^'\">\s]+)",
-            r"api[_-]?key\s*=\s*['\"]?([^'\">\s]+)",
-            r"token\s*=\s*['\"]?([^'\">\s]+)",
-            r"secret\s*=\s*['\"]?([^'\">\s]+)",
-        ]
+        # Privacy — a credential scrub (password/api_key/token/secret in key=value form) is applied
+        # BY DEFAULT, since those strings carry no analytical value. Pass redact_patterns=[] to opt
+        # out and store raw, or your own patterns to scrub more. None (unset) = the default scrub.
+        self.redact_patterns = (
+            list(DEFAULT_REDACT_PATTERNS)  # copy so the shared module default can't be mutated
+            if redact_patterns is None
+            else redact_patterns
+        )
 
-        # SDK metadata
-        self.sdk_version = "0.1.0"
+        # SDK metadata. Derived, never hardcoded — see scope_analytics.__version__.
+        from . import __version__ as _sdk_version
+        self.sdk_version = _sdk_version
         self.sdk_source = "backend_sdk"
 
     def to_dict(self) -> Dict[str, Any]:
@@ -99,3 +121,13 @@ class ScopeConfig:
         """Log debug message if debug mode enabled"""
         if self.debug:
             print(f"[Scope SDK] {message}")
+
+    def warn(self, message: str):
+        """Always-visible warning. Deliberately NOT gated on ``debug``.
+
+        An observability SDK that fails to instrument and says nothing is
+        indistinguishable from one that is working — the single worst failure mode we
+        can have, and precisely how a "captures zero OpenAI calls on openai>=2" bug
+        survived a full release. PRODUCT.md §2 (Robustness): "fail loudly, not silently."
+        """
+        logging.getLogger("scope_analytics").warning("[Scope SDK] %s", message)