Scope Analytics - Backend SDK

AI-powered analytics for backend applications with zero-code LLM conversation tracking.

Features

• Automatic LLM Tracking: Captures OpenAI, Anthropic, and Gemini calls automatically
• Outbound Call Tracking: Records the calls your app makes to other services (httpx, httpx2, requests, aiohttp, urllib) — destination, status, latency and failures. Never the request or response bodies.
• Session Correlation: Links backend events to frontend user sessions via X-Scope-Session-ID header
• Conversation Intelligence: Classifies LLM calls as user-facing vs background jobs
• Zero Code Changes: Drop-in integration with automatic monkey-patching
• Async & Non-Blocking: Events shipped in background without affecting performance

Installation

pip install scope-analytics

Quick Start

Choose your installation method:

Option A: No-Code Installation (Recommended)

Zero code changes required - just change how you run your app.

Step 1: Set your API key

export SCOPE_API_KEY="sk_live_..."

Step 2: Run with scope-run

# Instead of:   python app.py
# Run:          scope-run python app.py

# Instead of:   uvicorn main:app --reload
# Run:          scope-run uvicorn main:app --reload

# Instead of:   gunicorn app:app -w 4                                   (Flask, Django)
# Run:          scope-run gunicorn app:app -w 4

# Instead of:   gunicorn main:app -w 4 -k uvicorn_worker.UvicornWorker  (FastAPI; pip install uvicorn-worker)
# Run:          scope-run gunicorn main:app -w 4 -k uvicorn_worker.UvicornWorker

# Instead of:   flask run --port 5000
# Run:          scope-run flask run --port 5000

That's it! Your LLM calls are now automatically tracked AND correlated with frontend sessions (for FastAPI, Flask, Django). Workers forked by gunicorn or Celery ship on their own timer (0.1.5). LangChain / LangGraph, LlamaIndex, PydanticAI, Instructor and the OpenAI Agents SDK are captured through the SDK they call (LangChain needs 0.1.5).

Serverless / notebooks — no start command to prefix: create scope = ScopeAnalytics() at module import and call scope.flush(timeout=2.0) before the handler returns (0.1.5).

Option B: Code-Based Installation

Add 2 lines to your app for more control.

from scope_analytics import ScopeAnalytics
scope = ScopeAnalytics(api_key="sk_live_...")

For session correlation with frontend, add middleware:

FastAPI:

from fastapi import FastAPI
from scope_analytics import ScopeAnalytics, ScopeSessionMiddleware

app = FastAPI()
app.add_middleware(ScopeSessionMiddleware)
scope = ScopeAnalytics(api_key="sk_live_...")

Flask:

from flask import Flask
from scope_analytics import ScopeAnalytics, init_flask_session_tracking

app = Flask(__name__)
init_flask_session_tracking(app)
scope = ScopeAnalytics(api_key="sk_live_...")

Django:

# settings.py
MIDDLEWARE = [
    'scope_analytics.middleware.DjangoScopeMiddleware',
    # ... other middleware
]

Installation Comparison

CLI Usage

# Show version
scope-run --version

# Show help
scope-run --help

# Run with debug logging
scope-run --debug python app.py

# Dry run (show what would be executed)
scope-run --dry-run uvicorn main:app

Environment Variables

Configuration (Code-Based)

scope = ScopeAnalytics(
    api_key="sk_live_...",              # Required: Your secret API key
    endpoint="https://api.scopeai.dev", # Optional: API endpoint
    auto_patch=True,                    # Optional: Auto-patch LLM libraries (default: True)
    batch_size=10,                      # Optional: Events per batch (default: 10)
    batch_timeout_seconds=5,            # Optional: Max wait time (default: 5)
    capture_http=True,                  # Optional: Capture outbound calls (default: True,
                                        #   independent of auto_patch)
    debug=False,                        # Optional: Enable debug logging
    environment="production",           # Optional: Environment name
)

Framework Support Matrix

Manual Session Correlation (For Other Frameworks)

# Option A: ASGI middleware (for ASGI frameworks)
from scope_analytics import ScopeSessionMiddleware
app = ScopeSessionMiddleware(app)

# Option B: Manual context (for any framework)
from scope_analytics import ScopeContext

def my_request_handler(request):
    # Extract session from header and set context
    ScopeContext.set_session_id(request.headers.get('X-Scope-Session-ID'))

    # Your code - LLM calls will now have session_id attached
    response = openai.chat.completions.create(...)

Key Point: Even without middleware, LLM tracking STILL WORKS. The middleware is only needed for correlating backend events with frontend sessions via X-Scope-Session-ID.

Frontend SDK

Add the frontend SDK to link user interactions with backend LLM calls:

<script src="https://cdn.scopeai.dev/v1/sdk.js?token=pk_live_your_public_key" async></script>

The frontend SDK automatically:

• Tracks clicks, page views, form submissions
• Generates session IDs (stored in localStorage)
• Sends X-Scope-Session-ID header with API requests

Comparison with Industry Tools

Full Documentation

See SDK Installation Guide for complete documentation including:

• Detailed configuration options
• Troubleshooting guide
• Complete example applications
• Verification steps

License

MIT