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
