xecurecode-python-sdk 0.1.0__py3-none-any.whl

xecurecode/__init__.py

@@ -0,0 +1,17 @@
+"""
+XecureCode SDK for Python
+"""
+
+from .config import ReliabilityConfig
+from .client import ReliabilityClient, init, get_client
+from .payload import create_error_payload
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ReliabilityConfig",
+    "ReliabilityClient",
+    "create_error_payload",
+    "init",
+    "get_client",
+]

xecurecode/client.py

@@ -0,0 +1,223 @@
+"""
+Reliability Client for Python SDK
+"""
+
+import asyncio
+import json
+import logging
+import os
+import sys
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Dict, Optional
+from urllib.request import Request, urlopen
+from urllib.error import URLError
+
+from .config import ReliabilityConfig
+from .payload import create_error_payload
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_ENDPOINT = "https://xecurecode-backend.agreeablemeadow-24a6afd4.centralindia.azurecontainerapps.io/api/v1/ingest"
+
+DEDUP_WINDOW_MS = 60000
+MIN_INTERVAL_MS = 100
+MAX_PENDING = 100
+
+
+class ReliabilityClient:
+    """Main reliability client for capturing and sending errors"""
+
+    def __init__(self, config: ReliabilityConfig):
+        self.config = config
+        self._executor = ThreadPoolExecutor(
+            max_workers=1, thread_name_prefix="reliability-sender"
+        )
+
+        # Rate limiting
+        self._last_sent_time = 0
+        self._pending_sends = 0
+        self._lock = threading.Lock()
+
+        # Deduplication cache
+        self._error_cache: Dict[str, float] = {}
+        self._cache_cleanup_interval = 60
+        self._start_cache_cleanup()
+
+        # Global exception handlers
+        self._setup_global_handlers()
+
+        logger.info(f"ReliabilityClient initialized for service: {config.service_id}")
+
+    def _setup_global_handlers(self):
+        """Setup global exception handlers"""
+        # Store original handlers
+        self._original_excepthook = sys.excepthook
+        self._original_thread_excepthook = threading.excepthook
+
+        # Set custom handlers
+        sys.excepthook = self._custom_excepthook
+        threading.excepthook = self._custom_thread_excepthook
+
+    def _custom_excepthook(self, exc_type, exc_value, exc_traceback):
+        """Custom uncaught exception handler"""
+        if issubclass(exc_type, Exception):
+            self.capture(exc_value)
+        # Call original handler
+        if self._original_excepthook:
+            self._original_excepthook(exc_type, exc_value, exc_traceback)
+
+    def _custom_thread_excepthook(self, args):
+        """Custom thread exception handler"""
+        if args.exc_type and issubclass(args.exc_type, Exception):
+            self.capture(args.exc_value)
+        if self._original_thread_excepthook:
+            self._original_thread_excepthook(args)
+
+    def _start_cache_cleanup(self):
+        """Start background cache cleanup"""
+
+        def cleanup():
+            while True:
+                time.sleep(self._cache_cleanup_interval)
+                self._cleanup_cache()
+
+        cleanup_thread = threading.Thread(target=cleanup, daemon=True)
+        cleanup_thread.start()
+
+    def _cleanup_cache(self):
+        """Remove old entries from cache"""
+        now = time.time() * 1000
+        expired_keys = [
+            k for k, v in self._error_cache.items() if now - v > DEDUP_WINDOW_MS
+        ]
+        for k in expired_keys:
+            self._error_cache.pop(k, None)
+
+    def _is_duplicate(self, fingerprint: str) -> bool:
+        """Check if error is duplicate"""
+        now = time.time() * 1000
+        last_time = self._error_cache.get(fingerprint)
+
+        if last_time is None:
+            self._error_cache[fingerprint] = now
+            return False
+
+        if now - last_time > DEDUP_WINDOW_MS:
+            self._error_cache[fingerprint] = now
+            return False
+
+        return True
+
+    def _can_send(self) -> bool:
+        """Check if we can send (rate limiting)"""
+        now = time.time() * 1000
+        with self._lock:
+            if now - self._last_sent_time < MIN_INTERVAL_MS:
+                return False
+            if self._pending_sends >= MAX_PENDING:
+                return False
+            return True
+
+    def capture(self, error: Exception, request: Any = None):
+        """Capture an error"""
+        if error is None:
+            return
+
+        payload = create_error_payload(
+            error, self.config.service_id, self.config.mode, request
+        )
+
+        if self._is_duplicate(payload["fingerprint"]):
+            logger.debug(f"Duplicate error, skipping: {error}")
+            return
+
+        if not self._can_send():
+            logger.debug(f"Rate limited, skipping: {error}")
+            return
+
+        with self._lock:
+            self._pending_sends += 1
+            self._last_sent_time = time.time() * 1000
+
+        # Send in background
+        self._executor.submit(self._send_to_backend, payload)
+
+    def _send_to_backend(self, payload: Dict[str, Any]):
+        """Send payload to backend with retry"""
+        max_retries = 3
+        retry_delay = 1
+        try:
+            for attempt in range(max_retries):
+                try:
+                    self._do_send(payload)
+                    logger.debug(f"Error sent successfully: {payload['message']}")
+                    break
+                except Exception as e:
+                    logger.warning(f"Failed to send error (attempt {attempt + 1}): {e}")
+                    if attempt < max_retries - 1:
+                        time.sleep(retry_delay * (attempt + 1))
+        finally:
+            with self._lock:
+                self._pending_sends -= 1
+
+    def _do_send(self, payload: Dict[str, Any]):
+        """Perform actual HTTP request"""
+        data = json.dumps(payload).encode("utf-8")
+
+        request = Request(
+            DEFAULT_ENDPOINT,
+            data=data,
+            headers={
+                "Content-Type": "application/json",
+                "x-api-key": self.config.api_key,
+            },
+            method="POST",
+        )
+
+        with urlopen(request, timeout=5) as response:
+            if response.status >= 400:
+                raise Exception(f"HTTP {response.status}")
+
+    def middleware(self):
+        """Create middleware for frameworks"""
+        return ReliabilityMiddleware(self)
+
+    async def flush(self):
+        """Flush pending sends"""
+        while self._pending_sends > 0:
+            time.sleep(0.1)
+
+    def shutdown(self):
+        """Shutdown the client"""
+        self._executor.shutdown(wait=True)
+
+
+class ReliabilityMiddleware:
+    """Middleware for FastAPI/Flask"""
+
+    def __init__(self, client: ReliabilityClient):
+        self.client = client
+
+    async def __call__(self, request, call_next):
+        """Process request"""
+        try:
+            response = await call_next(request)
+            return response
+        except Exception as e:
+            self.client.capture(e, request)
+            raise
+
+
+def get_client() -> ReliabilityClient:
+    """Get global client instance"""
+    if not hasattr(get_client, "_instance"):
+        raise RuntimeError("ReliabilityClient not initialized. Call init() first.")
+    return get_client._instance
+
+
+def init(config: ReliabilityConfig) -> ReliabilityClient:
+    """Initialize global client"""
+    get_client._instance = ReliabilityClient(config)
+    return get_client._instance

xecurecode/config.py

@@ -0,0 +1,22 @@
+"""
+Reliability Config for Python SDK
+"""
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class ReliabilityConfig:
+    api_key: str
+    service_id: str
+    mode: str = "development"
+    timeout: int = 5000
+
+    def __post_init__(self):
+        if not self.api_key:
+            raise ValueError("API Key is required")
+        if not self.service_id:
+            raise ValueError("Service ID is required")
+        if self.mode not in ["development", "production"]:
+            raise ValueError("Mode must be 'development' or 'production'")

xecurecode/django_integration.py

@@ -0,0 +1,71 @@
+"""
+Django Integration
+"""
+
+# To use with Django, add this to your settings.py:
+#
+# RELIABILITY_API_KEY = 'your-api-key'
+# RELIABILITY_SERVICE_ID = 'your-service'
+# RELIABILITY_MODE = 'development'
+#
+# And add to MIDDLEWARE:
+# 'reliability.django_integration.ReliabilityMiddleware'
+
+import logging
+from django.core.exceptions import MiddlewareMixin
+
+from ..client import ReliabilityClient
+from ..config import ReliabilityConfig
+
+logger = logging.getLogger(__name__)
+
+_client = None
+
+
+def get_client() -> ReliabilityClient:
+    """Get or create Django client"""
+    global _client
+    if _client is None:
+        from django.conf import settings
+
+        api_key = getattr(settings, "RELIABILITY_API_KEY", None)
+        service_id = getattr(settings, "RELIABILITY_SERVICE_ID", None)
+        mode = getattr(settings, "RELIABILITY_MODE", "development")
+
+        if not api_key or not service_id:
+            logger.warning(
+                "Reliability SDK not configured. Add API_KEY and SERVICE_ID to settings."
+            )
+            return None
+
+        config = ReliabilityConfig(api_key=api_key, service_id=service_id, mode=mode)
+        _client = ReliabilityClient(config)
+
+    return _client
+
+
+class ReliabilityMiddleware(MiddlewareMixin):
+    """Django middleware for error capture"""
+
+    def process_exception(self, request, exception):
+        """Capture exceptions"""
+        client = get_client()
+        if client:
+            client.capture(exception, request)
+        return None
+
+
+# Django signals for automatic capture
+def setup_django_signals():
+    """Setup Django signals for automatic error capture"""
+    try:
+        from django.core.signals import exception_handler
+        from django.dispatch import receiver
+
+        @receiver(exception_handler)
+        def capture_exception(**kwargs):
+            client = get_client()
+            if client and "request" in kwargs:
+                client.capture(kwargs["exception"], kwargs["request"])
+    except ImportError:
+        pass

xecurecode/fastapi_integration.py

@@ -0,0 +1,36 @@
+"""
+FastAPI Integration
+"""
+
+from fastapi import FastAPI, Request, Response
+from fastapi.responses import JSONResponse
+from starlette.middleware.base import BaseHTTPMiddleware
+from typing import Callable
+
+from .client import ReliabilityClient
+
+
+class FastAPIMiddleware(BaseHTTPMiddleware):
+    """FastAPI middleware for error capture"""
+
+    def __init__(self, app: FastAPI, client: ReliabilityClient):
+        super().__init__(app)
+        self.client = client
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        try:
+            response = await call_next(request)
+            return response
+        except Exception as e:
+            self.client.capture(e, request)
+            raise
+
+
+def setup_fastapi(app: FastAPI, client: ReliabilityClient):
+    """Setup FastAPI integration"""
+    app.add_middleware(FastAPIMiddleware, client=client)
+
+
+def create_fastapi_middleware(client: ReliabilityClient):
+    """Create FastAPI middleware for manual use"""
+    return FastAPIMiddleware

xecurecode/flask_integration.py

@@ -0,0 +1,55 @@
+"""
+Flask Integration
+"""
+
+from flask import Flask, Request, Response
+from typing import Callable
+
+from .client import ReliabilityClient
+
+
+class FlaskMiddleware:
+    """Flask middleware for error capture"""
+
+    def __init__(self, client: ReliabilityClient):
+        self.client = client
+
+    def __call__(self, environ: dict, start_response: Callable) -> Response:
+        # Wrap start_response to capture exceptions
+        def wrapped_start_response(status, headers, exc_info=None):
+            return start_response(status, headers, exc_info)
+
+        try:
+            # Use Flask's internal mechanism
+            from flask import g
+
+            return self.app(environ, wrapped_start_response)
+        except Exception as e:
+            # Get request object from Flask
+            from flask import request
+
+            self.client.capture(e, request)
+            raise
+
+
+def init_flask(app: Flask, client: ReliabilityClient):
+    """Initialize Flask integration"""
+
+    @app.errorhandler(Exception)
+    def handle_error(error):
+        from flask import request
+
+        client.capture(error, request)
+        return {"error": str(error)}, 500
+
+
+def create_flask_error_handler(client: ReliabilityClient):
+    """Create Flask error handler for manual use"""
+
+    def handle_error(error):
+        from flask import request
+
+        client.capture(error, request)
+        return {"error": str(error)}, 500
+
+    return handle_error

xecurecode/payload.py

@@ -0,0 +1,148 @@
+"""
+Error Payload for Python SDK
+"""
+
+import hashlib
+import platform
+import os
+from typing import Dict, Any, Optional, List
+from datetime import datetime
+
+
+def _generate_fingerprint(error: Exception, stack: Optional[str] = None) -> str:
+    """Generate deterministic fingerprint for error"""
+    signature = str(error)
+    if stack:
+        first_line = stack.split("\n")[0] if stack else ""
+        signature += first_line
+
+    return hashlib.sha256(signature.encode()).hexdigest()
+
+
+def _classify_error(error: Exception) -> str:
+    """Classify error type based on message"""
+    msg = str(error).lower()
+
+    if any(
+        keyword in msg
+        for keyword in ["database", "sql", "psycopg", "mysql", "sqlite", "connection"]
+    ):
+        return "DATABASE"
+    if any(
+        keyword in msg
+        for keyword in ["network", "http", "socket", "connection", "timeout", "ssl"]
+    ):
+        return "NETWORK"
+    if any(
+        keyword in msg
+        for keyword in ["validation", "invalid", "required", "constraint", "type"]
+    ):
+        return "VALIDATION"
+    if any(
+        keyword in msg
+        for keyword in ["permission", "denied", "forbidden", "unauthorized"]
+    ):
+        return "AUTH"
+
+    return "RUNTIME"
+
+
+def _determine_severity(error: Exception) -> str:
+    """Determine error severity"""
+    msg = str(error).lower()
+
+    if any(
+        keyword in msg
+        for keyword in ["database", "connection", "timeout", "fatal", "crash"]
+    ):
+        return "critical"
+    return "warning"
+
+
+def _format_stack_trace(stack: Optional[str]) -> Optional[str]:
+    """Format stack trace"""
+    if not stack:
+        return None
+
+    if isinstance(stack, str):
+        return stack
+
+    if hasattr(stack, "__traceback__"):
+        import traceback
+
+        return "".join(traceback.format_tb(stack.__traceback__))
+
+    return str(stack)
+
+
+def _build_service_context() -> Dict[str, Any]:
+    """Build service context"""
+    return {
+        "pid": os.getpid(),
+        "python_version": platform.python_version(),
+        "platform": platform.platform(),
+        "hostname": platform.node() or os.environ.get("HOSTNAME", "unknown"),
+    }
+
+
+def _extract_request_context(request: Optional[Any] = None) -> Optional[Dict[str, Any]]:
+    """Extract request context from various frameworks"""
+    if request is None:
+        return None
+
+    context = {}
+
+    # FastAPI/Starlette
+    if hasattr(request, "method"):
+        context["method"] = request.method
+
+    if hasattr(request, "url"):
+        context["url"] = str(request.url)
+
+    if hasattr(request, "client") and request.client:
+        context["ip"] = request.client.host
+
+    # Flask
+    if hasattr(request, "remote_addr"):
+        context["ip"] = request.remote_addr
+
+    if hasattr(request, "path"):
+        context["url"] = context.get("url", request.path)
+
+    # Django
+    if hasattr(request, "META"):
+        context["ip"] = request.META.get("REMOTE_ADDR")
+        context["method"] = request.method
+        context["url"] = request.path
+
+    # Generic headers
+    if hasattr(request, "headers"):
+        forwarded = request.headers.get("x-forwarded-for")
+        if forwarded and not context.get("ip"):
+            context["ip"] = forwarded.split(",")[0].strip()
+
+    return context if context else None
+
+
+def create_error_payload(
+    error: Exception, service_id: str, mode: str, request: Optional[Any] = None
+) -> Dict[str, Any]:
+    """Create structured error payload"""
+
+    stack = _format_stack_trace(error.__traceback__)
+    fingerprint = _generate_fingerprint(error, stack)
+
+    return {
+        "message": str(error),
+        "name": type(error).__name__,
+        "stack": stack,
+        "fingerprint": fingerprint,
+        "timestamp": int(datetime.now().timestamp() * 1000),
+        "service_id": service_id,
+        "environment": mode,
+        "occurrence_count": 1,
+        "severity": _determine_severity(error),
+        "error_type": _classify_error(error),
+        "service_context": _build_service_context(),
+        "request_context": _extract_request_context(request),
+    }

xecurecode_python_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: xecurecode-python-sdk
+Version: 0.1.0
+Summary: AI-driven reliability SDK for Python applications
+Author-email: Xel Team <team@xel.io>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == "fastapi"
+Provides-Extra: flask
+Requires-Dist: flask>=2.0; extra == "flask"
+Provides-Extra: django
+Requires-Dist: django>=3.0; extra == "django"
+
+# XecureTrace Reliability SDK - Python
+
+AI-driven reliability SDK for Python applications.
+
+The official Python SDK for the XecureTrace Reliability Platform — a human-first failure analysis and recovery recommendation system.
+
+---
+
+## Why This SDK Exists
+
+Modern backend systems fail in unpredictable ways.
+
+This SDK:
+
+- Captures structured runtime errors
+- Generates deterministic fingerprints
+- Classifies error types (DATABASE, NETWORK, VALIDATION, etc.)
+- Determines severity
+- Sends non-blocking telemetry to your backend
+- Never crashes your application
+
+**AI assists. Humans decide. Nothing executes automatically.**
+
+---
+
+## Requirements
+
+- Python 3.8+
+- FastAPI, Flask, or Django (optional)
+
+---
+
+## Installation
+
+```bash
+pip install xecurecode-python-sdk
+```
+
+Or install with framework support:
+
+```bash
+pip install xecurecode-python-sdk[fastapi,flask,django]
+```
+
+---
+
+## Quick Start
+
+### 1️⃣ Initialize the SDK
+
+```python
+from reliability import ReliabilityClient, ReliabilityConfig
+
+config = ReliabilityConfig(
+    api_key="your-api-key",
+    service_id="your-service",
+    mode="development"
+)
+client = ReliabilityClient(config)
+```
+
+**Configuration Options:**
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `api_key` | Yes | Your API key |
+| `service_id` | Yes | Service identifier |
+| `mode` | Yes | `development` or `production` |
+| `timeout` | No | Request timeout (default: 5000ms) |
+
+---
+
+### 2️⃣ Automatic Global Error Capture
+
+The SDK automatically handles:
+- Uncaught exceptions
+- Thread exceptions
+
+```python
+# This will be automatically captured
+raise ValueError("Database timeout")
+```
+
+---
+
+### 3️⃣ FastAPI Integration
+
+```python
+from fastapi import FastAPI
+from reliability import ReliabilityClient, ReliabilityConfig
+from reliability.fastapi_integration import FastAPIMiddleware
+
+config = ReliabilityConfig(...)
+client = ReliabilityClient(config)
+
+app = FastAPI()
+app.add_middleware(FastAPIMiddleware, client=client)
+```
+
+---
+
+### 4️⃣ Flask Integration
+
+```python
+from flask import Flask
+from reliability import ReliabilityClient, ReliabilityConfig
+from reliability.flask_integration import init_flask
+
+config = ReliabilityConfig(...)
+client = ReliabilityClient(config)
+
+app = Flask(__name__)
+init_flask(app, client)
+```
+
+---
+
+### 5️⃣ Django Integration
+
+In `settings.py`:
+
+```python
+RELIABILITY_API_KEY = "your-api-key"
+RELIABILITY_SERVICE_ID = "your-service"
+RELIABILITY_MODE = "development"
+```
+
+In `settings.py` MIDDLEWARE:
+
+```python
+MIDDLEWARE = [
+    ...
+    'reliability.django_integration.ReliabilityMiddleware',
+    ...
+]
+```
+
+---
+
+### 6️⃣ Manual Capture
+
+```python
+try:
+    risky_operation()
+except Exception as e:
+    client.capture(e)
+
+# With request context
+client.capture(e, request)
+```
+
+---
+
+## What Gets Sent
+
+Example structured payload:
+
+```json
+{
+  "message": "Database connection failed",
+  "name": "ValueError",
+  "fingerprint": "a8c39c21...",
+  "timestamp": 1700000000000,
+  "service_id": "my-service",
+  "environment": "development",
+  "severity": "critical",
+  "error_type": "DATABASE",
+  "service_context": {
+    "pid": 12345,
+    "python_version": "3.11.0",
+    "platform": "Linux-5.10.0",
+    "hostname": "server-01"
+  },
+  "request_context": {
+    "method": "GET",
+    "url": "/api/users",
+    "ip": "10.0.0.5"
+  },
+  "occurrence_count": 1
+}
+```
+
+---
+
+## Error Classification
+
+| Type | Example |
+|------|---------|
+| DATABASE | Timeout, SQL errors, connection issues |
+| NETWORK | HTTP failures, socket errors |
+| VALIDATION | Invalid input, type errors |
+| AUTH | Permission denied |
+| RUNTIME | Standard Python errors |
+
+---
+
+## Severity Detection
+
+- **Critical** → Database, timeout, connection errors
+- **Warning** → Validation, recoverable issues
+
+---
+
+## Design Guarantees
+
+- Non-blocking HTTP calls
+- Timeout protected (5s default)
+- Retry logic (3 attempts)
+- Deduplication (1-minute window)
+- Rate limiting (max 100 concurrent)
+- Never throws inside SDK
+- Never crashes host application
+- Works with FastAPI, Flask, Django
+
+---
+
+## License
+
+MIT

xecurecode_python_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+xecurecode/__init__.py,sha256=Lr91KhibWBdQiEDS5gGgtuEWLYTd91rU2aEEoDCFf8s,317
+xecurecode/client.py,sha256=mI49C1ZB1uckghC0ArMmkJKWufzrH6_tUPnzQD9fQiA,6940
+xecurecode/config.py,sha256=DEMBw0oEysZGpzMHi_dJ2_rimLrBijLvYJOCjXeN4Tk,566
+xecurecode/django_integration.py,sha256=4A2qCoQR5jdOWKG2Boqi_C9kiqfCHHcSfMLUl2Ar2Io,2005
+xecurecode/fastapi_integration.py,sha256=nmrLYQI5Blpg6qSnignzNHznpUoNcggxPZ-1KY0R5gw,1021
+xecurecode/flask_integration.py,sha256=_ILiUkR3zBHIxkOB9sopux3yjK8f8gcJiQriDYvZQTc,1435
+xecurecode/payload.py,sha256=t1D6One_bb8m2WYALy0oJt3LOfe2yvQMnMvL9MtPyCA,4078
+xecurecode_python_sdk-0.1.0.dist-info/METADATA,sha256=B4IHwJZ25Jgm9-fTnU34OJWEDHNwgi64ik6TZaluA5g,4962
+xecurecode_python_sdk-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+xecurecode_python_sdk-0.1.0.dist-info/top_level.txt,sha256=7OncyRHpCaDE2-r_4RIvGbITjwenEIapFFO8vFjkD7w,11
+xecurecode_python_sdk-0.1.0.dist-info/RECORD,,

xecurecode_python_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

xecurecode_python_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+xecurecode