scope-analytics 0.1.0__tar.gz

scope_analytics-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Scope AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scope_analytics-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include README.md
+recursive-include scope_analytics *.py

scope_analytics-0.1.0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: scope-analytics
+Version: 0.1.0
+Summary: AI-powered analytics SDK for backend applications with automatic LLM tracking
+Home-page: https://github.com/scopeai/scope-analytics-python
+Author: Scope AI
+Author-email: support@scopeai.dev
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.18.0; extra == "anthropic"
+Provides-Extra: langchain
+Requires-Dist: langchain>=0.1.0; extra == "langchain"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# 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
+- **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
+
+```bash
+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**
+```bash
+export SCOPE_API_KEY="sk_live_..."
+```
+
+**Step 2: Run with scope-run**
+```bash
+# 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
+# Run:          scope-run gunicorn app:app -w 4
+
+# 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).
+
+### Option B: Code-Based Installation
+
+Add 2 lines to your app for more control.
+
+```python
+from scope_analytics import ScopeAnalytics
+scope = ScopeAnalytics(api_key="sk_live_...")
+```
+
+For session correlation with frontend, add middleware:
+
+**FastAPI:**
+```python
+from fastapi import FastAPI
+from scope_analytics import ScopeAnalytics, ScopeSessionMiddleware
+
+app = FastAPI()
+app.add_middleware(ScopeSessionMiddleware)
+scope = ScopeAnalytics(api_key="sk_live_...")
+```
+
+**Flask:**
+```python
+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:**
+```python
+# settings.py
+MIDDLEWARE = [
+    'scope_analytics.middleware.DjangoScopeMiddleware',
+    # ... other middleware
+]
+```
+
+## Installation Comparison
+
+| Feature | No-Code (`scope-run`) | Code-Based |
+|---------|----------------------|------------|
+| Code changes required | **None** | 2 lines minimum |
+| LLM tracking | ✅ Automatic | ✅ Automatic |
+| Session correlation | ✅ Automatic (FastAPI/Flask/Django) | Manual middleware |
+| Custom configuration | Via env vars | Full Python API |
+| Best for | Quick start, CI/CD, ops teams | Developers wanting control |
+
+## CLI Usage
+
+```bash
+# 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
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `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) |
+
+## Configuration (Code-Based)
+
+```python
+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)
+    debug=False,                        # Optional: Enable debug logging
+    environment="production",           # Optional: Environment name
+)
+```
+
+## Framework Support Matrix
+
+| Framework | Auto-Injection | Session Correlation | How |
+|-----------|----------------|---------------------|-----|
+| FastAPI | ✅ Automatic | ✅ Full | Patches `FastAPI.__init__` |
+| Starlette | ✅ Automatic | ✅ Full | Patches `Starlette.__init__` |
+| Flask | ✅ Automatic | ✅ Full | Patches `Flask.__init__` |
+| Django | ✅ Automatic | ✅ Full | Modifies `settings.MIDDLEWARE` |
+| Other ASGI | ⚠️ Manual | ✅ With 1 line | Add `ScopeSessionMiddleware` |
+| Other WSGI | ⚠️ Manual | ✅ With 1 line | Call `ScopeContext.set_session_id()` |
+| No framework | ⚠️ Manual | ✅ With 1 line | Call `ScopeContext.set_session_id()` |
+
+## Manual Session Correlation (For Other Frameworks)
+
+```python
+# 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:
+
+```html
+<script src="https://cdn.scopeai.dev/v1/sdk.js"
+        data-api-key="pk_live_your_public_key"></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
+
+| Feature | Scope (`scope-run`) | DataDog (`ddtrace-run`) | New Relic |
+|---------|---------------------|-------------------------|-----------|
+| No code changes | ✅ | ✅ | ✅ |
+| Env var config | ✅ `SCOPE_API_KEY` | ✅ `DD_API_KEY` | ✅ `NEW_RELIC_LICENSE_KEY` |
+| Works with uvicorn | ✅ | ✅ | ✅ |
+| Works with gunicorn | ✅ | ✅ | ✅ |
+| LLM call capture | ✅ | ❌ | ❌ |
+| Session correlation | ✅ | ❌ | ❌ |
+| Debug mode | ✅ `--debug` | ✅ `--info` | ✅ |
+
+## Full Documentation
+
+See [SDK Installation Guide](../docs/sdk-installation-guide.md) for complete documentation including:
+- Detailed configuration options
+- Troubleshooting guide
+- Complete example applications
+- Verification steps
+
+## License
+
+MIT

scope_analytics-0.1.0/README.md

@@ -0,0 +1,207 @@
+# 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
+- **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
+
+```bash
+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**
+```bash
+export SCOPE_API_KEY="sk_live_..."
+```
+
+**Step 2: Run with scope-run**
+```bash
+# 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
+# Run:          scope-run gunicorn app:app -w 4
+
+# 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).
+
+### Option B: Code-Based Installation
+
+Add 2 lines to your app for more control.
+
+```python
+from scope_analytics import ScopeAnalytics
+scope = ScopeAnalytics(api_key="sk_live_...")
+```
+
+For session correlation with frontend, add middleware:
+
+**FastAPI:**
+```python
+from fastapi import FastAPI
+from scope_analytics import ScopeAnalytics, ScopeSessionMiddleware
+
+app = FastAPI()
+app.add_middleware(ScopeSessionMiddleware)
+scope = ScopeAnalytics(api_key="sk_live_...")
+```
+
+**Flask:**
+```python
+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:**
+```python
+# settings.py
+MIDDLEWARE = [
+    'scope_analytics.middleware.DjangoScopeMiddleware',
+    # ... other middleware
+]
+```
+
+## Installation Comparison
+
+| Feature | No-Code (`scope-run`) | Code-Based |
+|---------|----------------------|------------|
+| Code changes required | **None** | 2 lines minimum |
+| LLM tracking | ✅ Automatic | ✅ Automatic |
+| Session correlation | ✅ Automatic (FastAPI/Flask/Django) | Manual middleware |
+| Custom configuration | Via env vars | Full Python API |
+| Best for | Quick start, CI/CD, ops teams | Developers wanting control |
+
+## CLI Usage
+
+```bash
+# 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
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `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) |
+
+## Configuration (Code-Based)
+
+```python
+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)
+    debug=False,                        # Optional: Enable debug logging
+    environment="production",           # Optional: Environment name
+)
+```
+
+## Framework Support Matrix
+
+| Framework | Auto-Injection | Session Correlation | How |
+|-----------|----------------|---------------------|-----|
+| FastAPI | ✅ Automatic | ✅ Full | Patches `FastAPI.__init__` |
+| Starlette | ✅ Automatic | ✅ Full | Patches `Starlette.__init__` |
+| Flask | ✅ Automatic | ✅ Full | Patches `Flask.__init__` |
+| Django | ✅ Automatic | ✅ Full | Modifies `settings.MIDDLEWARE` |
+| Other ASGI | ⚠️ Manual | ✅ With 1 line | Add `ScopeSessionMiddleware` |
+| Other WSGI | ⚠️ Manual | ✅ With 1 line | Call `ScopeContext.set_session_id()` |
+| No framework | ⚠️ Manual | ✅ With 1 line | Call `ScopeContext.set_session_id()` |
+
+## Manual Session Correlation (For Other Frameworks)
+
+```python
+# 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:
+
+```html
+<script src="https://cdn.scopeai.dev/v1/sdk.js"
+        data-api-key="pk_live_your_public_key"></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
+
+| Feature | Scope (`scope-run`) | DataDog (`ddtrace-run`) | New Relic |
+|---------|---------------------|-------------------------|-----------|
+| No code changes | ✅ | ✅ | ✅ |
+| Env var config | ✅ `SCOPE_API_KEY` | ✅ `DD_API_KEY` | ✅ `NEW_RELIC_LICENSE_KEY` |
+| Works with uvicorn | ✅ | ✅ | ✅ |
+| Works with gunicorn | ✅ | ✅ | ✅ |
+| LLM call capture | ✅ | ❌ | ❌ |
+| Session correlation | ✅ | ❌ | ❌ |
+| Debug mode | ✅ `--debug` | ✅ `--info` | ✅ |
+
+## Full Documentation
+
+See [SDK Installation Guide](../docs/sdk-installation-guide.md) for complete documentation including:
+- Detailed configuration options
+- Troubleshooting guide
+- Complete example applications
+- Verification steps
+
+## License
+
+MIT