devlite 0.1.0__tar.gz

devlite-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ishvexa Hub
+
+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.

devlite-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: devlite
+Version: 0.1.0
+Summary: DevLite Python SDK — AI-powered observability with a 2-line integration. Automatic error grouping, source context, user impact tracking, and sensitive-data scrubbing built in.
+License: MIT
+Project-URL: Homepage, https://devlite.io
+Project-URL: Repository, https://github.com/Ishimwe-Kevin/devlite-app
+Keywords: observability,monitoring,apm,error-tracking,error-monitoring,logging,ai,devlite
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: flask
+Requires-Dist: flask>=2.0; extra == "flask"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# devlite — Python SDK
+
+AI-powered observability for Python. Add two lines, get automatic request tracking, error capture, error grouping, source context, user tracking, and slow-endpoint detection — no config files, no manual instrumentation, **zero runtime dependencies**.
+
+This is the Python counterpart of [`@devlite/nodejs`](https://www.npmjs.com/package/@devlite/nodejs) — both SDKs speak the same batch protocol to the [DevLite ingest API](https://github.com/Ishimwe-Kevin/devlite-app).
+
+## Install
+
+```bash
+pip install devlite            # core (Flask optional)
+pip install "devlite[flask]"   # + Flask instrumentation
+```
+
+## 60-second quickstart (Flask)
+
+```python
+from flask import Flask
+import devlite
+
+devlite.init(api_key="dl_live_xxxxx")
+
+app = Flask(__name__)
+devlite.instrument_flask(app)
+```
+
+That's it — every HTTP request, slow endpoint, and unhandled exception is now captured automatically, with:
+
+- **Grouped errors** — the same bug occurring 1,000 times shows up as one issue, not 1,000
+- **Real source code context** — the actual lines around the crash, read live from disk
+- **Automatic sensitive-data scrubbing** — emails, tokens, passwords redacted before anything leaves your process
+- **User impact tracking** — know exactly which users hit which bugs
+
+Point `api_key`/`endpoint` at your own DevLite ingest instance (Supabase-backed) to start seeing data.
+
+## Manual capture API
+
+```python
+# Capture a handled error with extra context
+devlite.capture_error(err, {"userId": "123", "action": "checkout"})
+devlite.capture_error(err, {"fingerprint": "payment-timeout"})  # force grouping key
+
+# Non-error event
+devlite.capture_message("Payment retried after timeout", "warning")
+
+# Custom metric — feeds forecasting/anomaly detection
+devlite.report_metric("order.total", 42.5, unit="USD", tags={"region": "lagos"})
+
+# Structured log line
+devlite.capture_log("checkout completed", "info", {"orderId": "ord_123", "durationMs": 250})
+
+# Trace a unit of work
+span = devlite.start_span("checkout.process", {"trace_id": "abc"})
+span.end("ok")  # "ok" | "error"
+
+# Tell DevLite about a deployment (powers before/after performance views)
+devlite.report_deployment(version="v2.1.3", commit_sha="a1b2c3d")
+
+# Breadcrumbs attach to the next captured error, improving AI root-cause
+devlite.add_breadcrumb({"type": "business_event", "note": "user started checkout"})
+
+# Tag all subsequent events
+devlite.set_tag("region", "lagos")
+```
+
+## User impact tracking
+
+`set_user()` is scoped to the current request (via `contextvars`, so concurrent requests never leak each other's identity):
+
+```python
+from flask import request
+
+@app.before_request
+def identify():
+    devlite.set_user({"id": request.remote_addr, "email": request.headers.get("X-User-Email")})
+```
+
+## Configuration options
+
+```python
+devlite.init({
+    "api_key": "dl_live_xxxxx",        # required
+    "environment": "production",        # default: $DEVLITE_ENVIRONMENT or "development"
+    "service_name": "payments-api",     # default: $DEVLITE_SERVICE_NAME or current folder
+    "release": "v2.1.3",                # e.g. git sha, shown in deployment views
+    "sample_rate": 1.0,                 # 0.0–1.0. Sampling is COHERENT: a sampled-out
+                                        # request drops its errors/spans/logs/metrics together.
+    "capture_body": False,              # capture (redacted) request headers — off by default
+    "flush_interval_ms": 5000,          # how often batched events are sent
+    "gzip": True,                       # compress request bodies (Content-Encoding: gzip)
+    "debug": False,                     # log SDK internals
+    "on_error": lambda err: print(err), # SDK-internal send failures
+})
+```
+
+All of `api_key`, `service_name`, `release`, and `endpoint` can also be set via environment variables (`DEVLITE_API_KEY`, `DEVLITE_SERVICE_NAME`, `DEVLITE_RELEASE`, `DEVLITE_ENDPOINT`).
+
+## Serverless / short-lived processes
+
+Events are batched, so call `flush()` before your function returns:
+
+```python
+devlite.flush()
+```
+
+## Graceful shutdown
+
+The SDK flushes remaining events on interpreter exit (`atexit`). If you manage shutdown yourself:
+
+```python
+devlite.close()
+```
+
+## What makes this competitive
+
+- **Automatic error grouping** — the same underlying bug, however many times it fires, is fingerprinted and grouped into one issue, instead of flooding your dashboard with duplicates.
+- **Source code context** — every captured error includes the actual lines of code around the crash, read live from disk, not just a bare stack trace.
+- **Automatic sensitive-data scrubbing** — on by default. Emails, JWTs, bearer tokens, AWS keys, credit card numbers, and any field literally named `password`/`token`/`secret` are redacted before anything leaves your process.
+- **Never blocks your app** — all sends are async (background thread), batched, and retried with backoff. If DevLite's backend is unreachable, your app keeps running.
+- **Zero dependencies** — pure Python standard library.
+
+## Development
+
+```bash
+pip install -e ".[flask,test]"
+python -m pytest
+```
+
+## License
+
+MIT

devlite-0.1.0/README.md

@@ -0,0 +1,130 @@
+# devlite — Python SDK
+
+AI-powered observability for Python. Add two lines, get automatic request tracking, error capture, error grouping, source context, user tracking, and slow-endpoint detection — no config files, no manual instrumentation, **zero runtime dependencies**.
+
+This is the Python counterpart of [`@devlite/nodejs`](https://www.npmjs.com/package/@devlite/nodejs) — both SDKs speak the same batch protocol to the [DevLite ingest API](https://github.com/Ishimwe-Kevin/devlite-app).
+
+## Install
+
+```bash
+pip install devlite            # core (Flask optional)
+pip install "devlite[flask]"   # + Flask instrumentation
+```
+
+## 60-second quickstart (Flask)
+
+```python
+from flask import Flask
+import devlite
+
+devlite.init(api_key="dl_live_xxxxx")
+
+app = Flask(__name__)
+devlite.instrument_flask(app)
+```
+
+That's it — every HTTP request, slow endpoint, and unhandled exception is now captured automatically, with:
+
+- **Grouped errors** — the same bug occurring 1,000 times shows up as one issue, not 1,000
+- **Real source code context** — the actual lines around the crash, read live from disk
+- **Automatic sensitive-data scrubbing** — emails, tokens, passwords redacted before anything leaves your process
+- **User impact tracking** — know exactly which users hit which bugs
+
+Point `api_key`/`endpoint` at your own DevLite ingest instance (Supabase-backed) to start seeing data.
+
+## Manual capture API
+
+```python
+# Capture a handled error with extra context
+devlite.capture_error(err, {"userId": "123", "action": "checkout"})
+devlite.capture_error(err, {"fingerprint": "payment-timeout"})  # force grouping key
+
+# Non-error event
+devlite.capture_message("Payment retried after timeout", "warning")
+
+# Custom metric — feeds forecasting/anomaly detection
+devlite.report_metric("order.total", 42.5, unit="USD", tags={"region": "lagos"})
+
+# Structured log line
+devlite.capture_log("checkout completed", "info", {"orderId": "ord_123", "durationMs": 250})
+
+# Trace a unit of work
+span = devlite.start_span("checkout.process", {"trace_id": "abc"})
+span.end("ok")  # "ok" | "error"
+
+# Tell DevLite about a deployment (powers before/after performance views)
+devlite.report_deployment(version="v2.1.3", commit_sha="a1b2c3d")
+
+# Breadcrumbs attach to the next captured error, improving AI root-cause
+devlite.add_breadcrumb({"type": "business_event", "note": "user started checkout"})
+
+# Tag all subsequent events
+devlite.set_tag("region", "lagos")
+```
+
+## User impact tracking
+
+`set_user()` is scoped to the current request (via `contextvars`, so concurrent requests never leak each other's identity):
+
+```python
+from flask import request
+
+@app.before_request
+def identify():
+    devlite.set_user({"id": request.remote_addr, "email": request.headers.get("X-User-Email")})
+```
+
+## Configuration options
+
+```python
+devlite.init({
+    "api_key": "dl_live_xxxxx",        # required
+    "environment": "production",        # default: $DEVLITE_ENVIRONMENT or "development"
+    "service_name": "payments-api",     # default: $DEVLITE_SERVICE_NAME or current folder
+    "release": "v2.1.3",                # e.g. git sha, shown in deployment views
+    "sample_rate": 1.0,                 # 0.0–1.0. Sampling is COHERENT: a sampled-out
+                                        # request drops its errors/spans/logs/metrics together.
+    "capture_body": False,              # capture (redacted) request headers — off by default
+    "flush_interval_ms": 5000,          # how often batched events are sent
+    "gzip": True,                       # compress request bodies (Content-Encoding: gzip)
+    "debug": False,                     # log SDK internals
+    "on_error": lambda err: print(err), # SDK-internal send failures
+})
+```
+
+All of `api_key`, `service_name`, `release`, and `endpoint` can also be set via environment variables (`DEVLITE_API_KEY`, `DEVLITE_SERVICE_NAME`, `DEVLITE_RELEASE`, `DEVLITE_ENDPOINT`).
+
+## Serverless / short-lived processes
+
+Events are batched, so call `flush()` before your function returns:
+
+```python
+devlite.flush()
+```
+
+## Graceful shutdown
+
+The SDK flushes remaining events on interpreter exit (`atexit`). If you manage shutdown yourself:
+
+```python
+devlite.close()
+```
+
+## What makes this competitive
+
+- **Automatic error grouping** — the same underlying bug, however many times it fires, is fingerprinted and grouped into one issue, instead of flooding your dashboard with duplicates.
+- **Source code context** — every captured error includes the actual lines of code around the crash, read live from disk, not just a bare stack trace.
+- **Automatic sensitive-data scrubbing** — on by default. Emails, JWTs, bearer tokens, AWS keys, credit card numbers, and any field literally named `password`/`token`/`secret` are redacted before anything leaves your process.
+- **Never blocks your app** — all sends are async (background thread), batched, and retried with backoff. If DevLite's backend is unreachable, your app keeps running.
+- **Zero dependencies** — pure Python standard library.
+
+## Development
+
+```bash
+pip install -e ".[flask,test]"
+python -m pytest
+```
+
+## License
+
+MIT

devlite-0.1.0/devlite/__init__.py

@@ -0,0 +1,147 @@
+"""DevLite Python SDK — AI-powered observability with a 2-line integration.
+
+    import devlite
+
+    devlite.init({api_key: "dl_live_xxxxx"})
+
+Automatic request tracking, error grouping, source context, user impact
+tracking, and sensitive-data scrubbing — mirroring the @devlite/nodejs npm
+SDK, with zero runtime dependencies.
+
+Public API (all Pythonic snake_case):
+    init, capture_error, capture_message, report_metric, capture_log,
+    start_span, report_span, report_deployment, add_breadcrumb, set_tag,
+    set_user, run_with_context, start_host_metrics, instrument_flask,
+    flush, close
+"""
+
+from ._client import Client, HostMetricsHandle, Span
+from ._context import run_with_context
+
+__version__ = "0.1.0"
+
+_client = None
+
+
+def init(options=None):
+    """Initialize DevLite. The only required call.
+
+    Args:
+        options: dict with keys like api_key, environment, service_name,
+            release, sample_rate, gzip, debug, endpoint, on_error, ...
+            `api_key` is required (or set DEVLITE_API_KEY env var).
+    """
+    global _client
+    if _client is not None:
+        import warnings
+
+        warnings.warn("[DevLite] init() called more than once — ignoring subsequent call.")
+        return
+    _client = Client(options or {})
+
+
+def _require_client():
+    if _client is None:
+        raise RuntimeError("[DevLite] SDK not initialized. Call devlite.init(api_key=...) first.")
+    return _client
+
+
+def capture_error(error, extra=None):
+    """Capture a handled error with optional extra context."""
+    _require_client().capture_error(error, extra=extra)
+
+
+def capture_message(message, level="info", extra=None):
+    """Capture a non-error event, e.g. a business-logic message."""
+    _require_client().capture_message(message, level=level, extra=extra)
+
+
+def report_metric(name, value, unit=None, tags=None):
+    """Report a metric data point (feeds forecasting/anomaly detection)."""
+    _require_client().report_metric(name, value, unit=unit, tags=tags)
+
+
+def capture_log(message, level="info", fields=None):
+    """Capture a structured log line with arbitrary fields."""
+    _require_client().capture_log(message, level=level, fields=fields)
+
+
+def start_span(name, options=None):
+    """Start a trace span; returns an object with id/trace_id and end(status)."""
+    return _require_client().start_span(name, options=options)
+
+
+def report_span(name, trace_id=None, parent_id=None, tags=None, start_time=None, end_time=None, duration_ms=None, status="ok"):
+    """Report a finished span if you track timing yourself."""
+    _require_client().report_span(
+        name,
+        trace_id=trace_id,
+        parent_id=parent_id,
+        tags=tags,
+        start_time=start_time,
+        end_time=end_time,
+        duration_ms=duration_ms,
+        status=status,
+    )
+
+
+def report_deployment(version=None, commit_sha=None, notes=None):
+    """Report a deployment — powers performance before/after deployment views."""
+    _require_client().report_deployment(version=version, commit_sha=commit_sha, notes=notes)
+
+
+def add_breadcrumb(entry):
+    """Add a manual breadcrumb (e.g. 'user started checkout') for richer AI context."""
+    _require_client().add_breadcrumb(entry)
+
+
+def set_tag(key, value):
+    """Tag all subsequent events, e.g. set_tag('region', 'lagos')."""
+    _require_client().set_tag(key, value)
+
+
+def set_user(user):
+    """Identify the user for the CURRENT request (scoped to the request)."""
+    _require_client().set_user(user)
+
+
+def start_host_metrics(interval_ms=15000):
+    """Start sampling host CPU/memory (plus network/disk on Linux) as metrics."""
+    return _require_client().start_host_metrics(interval_ms=interval_ms)
+
+
+def instrument_flask(app):
+    """Wire automatic request/error/user tracking into a Flask app."""
+    return _require_client().instrument_flask(app)
+
+
+def flush():
+    """Force-send whatever is currently queued (useful in serverless)."""
+    _require_client().flush()
+
+
+def close():
+    """Cleanly stop the SDK — flushes remaining events."""
+    if _client is not None:
+        _client.close()
+
+
+__all__ = [
+    "__version__",
+    "init",
+    "capture_error",
+    "capture_message",
+    "report_metric",
+    "capture_log",
+    "start_span",
+    "report_span",
+    "report_deployment",
+    "add_breadcrumb",
+    "set_tag",
+    "set_user",
+    "run_with_context",
+    "start_host_metrics",
+    "instrument_flask",
+    "flush",
+    "close",
+]

devlite-0.1.0/devlite/_client.py

@@ -0,0 +1,184 @@
+"""DevLite client — the singleton that owns config, transport, and context."""
+
+import atexit
+import threading
+import uuid
+
+from ._config import build_config
+from ._context import Context, get_user, now_ms, run_with_context
+from ._errors import build_error_event
+from ._metrics import collect_host_metrics
+from ._scrub import scrub_deep
+from ._transport import Transport
+
+
+def _new_hex(nbytes):
+    return uuid.uuid4().hex[: nbytes * 2]
+
+
+class Span:
+    """A trace span you can end() once the work completes."""
+
+    def __init__(self, client, name, options=None):
+        options = options or {}
+        self.client = client
+        self.type = "span"
+        self.id = options.get("id") or _new_hex(6)
+        self.name = name
+        self.trace_id = options.get("trace_id") or _new_hex(8)
+        self.parent_id = options.get("parent_id")
+        self.tags = options.get("tags") or {}
+        self.start_time = now_ms()
+        self.end_time = None
+        self.duration_ms = None
+        self.status = None
+
+    def end(self, status="ok"):
+        self.end_time = now_ms()
+        self.duration_ms = self.end_time - self.start_time
+        self.status = status
+        event = {
+            "type": "span",
+            "id": self.id,
+            "name": self.name,
+            "traceId": self.trace_id,
+            "parentId": self.parent_id,
+            "tags": self.tags,
+            "startTime": self.start_time,
+            "endTime": self.end_time,
+            "durationMs": self.duration_ms,
+            "status": status,
+        }
+        self.client._enqueue_scubbed(event)
+
+
+class HostMetricsHandle:
+    def __init__(self, client, interval_ms):
+        self.client = client
+        self.interval_ms = max(1000, interval_ms)
+        self._stop = threading.Event()
+        self._thread = threading.Thread(target=self._run, daemon=True, name="devlite-host-metrics")
+        self._thread.start()
+
+    def _run(self):
+        self._sample()
+        while not self._stop.wait(self.interval_ms / 1000.0):
+            self._sample()
+
+    def _sample(self):
+        try:
+            for metric in collect_host_metrics():
+                self.client._transport.enqueue(metric)
+        except Exception:
+            pass
+
+    def stop(self):
+        self._stop.set()
+
+
+class _NoopHandle:
+    def stop(self):
+        pass
+
+
+class Client:
+    def __init__(self, options):
+        self.config = build_config(options)
+        self.context = Context()
+        self.transport = Transport(self.config)
+        self._host_metrics = None
+        self._closed = False
+        atexit.register(self.close)
+
+    # --- public API (also exposed at package top level) -------------------
+
+    def capture_error(self, error, extra=None):
+        event = build_error_event(
+            error,
+            self.config,
+            breadcrumbs=self.context.snapshot().get("breadcrumbs", []),
+            user=get_user(),
+            extra=extra or {},
+        )
+        self.transport.enqueue(event)
+
+    def capture_message(self, message, level="info", extra=None):
+        raw = {"type": "message", "level": level, "message": message, "extra": extra or {}, "timestamp": now_ms()}
+        self.transport.enqueue(scrub_deep(raw) if self._should_scrub() else raw)
+
+    def report_metric(self, name, value, unit=None, tags=None):
+        if not isinstance(name, str) or not name:
+            raise ValueError("[DevLite] report_metric() requires a string `name`.")
+        if not isinstance(value, (int, float)):
+            raise ValueError("[DevLite] report_metric() requires a numeric `value`.")
+        raw = {"type": "metric", "name": name, "value": value, "unit": unit or None, "tags": tags or {}, "timestamp": now_ms()}
+        self.transport.enqueue(scrub_deep(raw) if self._should_scrub() else raw)
+
+    def capture_log(self, message, level="info", fields=None):
+        raw = {"type": "log", "level": level, "message": message, "fields": fields or {}, "timestamp": now_ms()}
+        self.transport.enqueue(scrub_deep(raw) if self._should_scrub() else raw)
+
+    def start_span(self, name, options=None):
+        return Span(self, name, options)
+
+    def report_span(self, name, trace_id=None, parent_id=None, tags=None, start_time=None, end_time=None, duration_ms=None, status="ok"):
+        raw = {
+            "type": "span",
+            "id": _new_hex(6),
+            "name": name,
+            "traceId": trace_id or _new_hex(8),
+            "parentId": parent_id,
+            "tags": tags or {},
+            "startTime": start_time,
+            "endTime": end_time,
+            "durationMs": duration_ms,
+            "status": status,
+            "timestamp": now_ms(),
+        }
+        self.transport.enqueue(scrub_deep(raw) if self._should_scrub() else raw)
+
+    def report_deployment(self, version=None, commit_sha=None, notes=None):
+        self.transport.enqueue(
+            {"type": "deployment", "version": version, "commitSha": commit_sha, "notes": notes, "timestamp": now_ms()}
+        )
+
+    def add_breadcrumb(self, entry):
+        self.context.add_breadcrumb(entry or {})
+
+    def set_tag(self, key, value):
+        self.context.set_tag(key, value)
+
+    def set_user(self, user):
+        from ._context import set_user as _set_user
+
+        _set_user(user)
+
+    def start_host_metrics(self, interval_ms=15000):
+        if self._host_metrics:
+            return _NoopHandle()  # no-op if already running
+        self._host_metrics = HostMetricsHandle(self, interval_ms)
+        return self._host_metrics
+
+    def instrument_flask(self, app):
+        from ._flask import instrument_flask
+
+        return instrument_flask(app, self.transport, self.context, self.config)
+
+    def flush(self):
+        self.transport.flush()
+
+    def close(self):
+        if self._closed:
+            return
+        self._closed = True
+        if self._host_metrics:
+            self._host_metrics.stop()
+        self.transport.close()
+
+    # --- internals --------------------------------------------------------
+
+    def _should_scrub(self):
+        return self.config.get("scrub_sensitive_data", True) is not False
+
+    def _enqueue_scubbed(self, event):
+        self.transport.enqueue(scrub_deep(event) if self._should_scrub() else event)