oluso 1.0.0__py3-none-any.whl

oluso/__init__.py

@@ -0,0 +1,34 @@
+"""Oluso: AI-powered error monitoring for Python applications."""
+
+from .client import Oluso
+from .context import add_breadcrumb, scope, set_custom_context, set_user
+from .options import Options
+from .types import (
+    Breadcrumb,
+    BreadcrumbLevel,
+    ErrorContext,
+    ErrorReport,
+    RequestContext,
+    ServerContext,
+    Severity,
+    UserContext,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "Oluso",
+    "Options",
+    "scope",
+    "add_breadcrumb",
+    "set_user",
+    "set_custom_context",
+    "Breadcrumb",
+    "BreadcrumbLevel",
+    "ErrorContext",
+    "ErrorReport",
+    "RequestContext",
+    "ServerContext",
+    "Severity",
+    "UserContext",
+]

oluso/client.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+import logging
+import queue
+import threading
+import time
+import traceback
+from typing import Any, Dict, Optional, Tuple
+
+from .context import _snapshot
+from .fingerprint import generate_fingerprint
+from .options import Options
+from .queue import OfflineQueue
+from .rate_limiter import RateLimiter
+from .sanitizer import Sanitizer
+from .server_context import get_server_context
+from .transport import TransportError, send_error_report
+from .types import ErrorContext, ErrorReport, RequestContext, Severity
+
+logger = logging.getLogger("oluso")
+
+
+class Oluso:
+    """Reports errors to Oluso.
+
+    Sends run on a background daemon thread (tracked so `flush()` can drain
+    them before shutdown) rather than blocking the calling thread on network
+    I/O, since capture calls typically sit on a request-handling hot path.
+    """
+
+    def __init__(self, options: Options) -> None:
+        if not options.api_key:
+            raise ValueError("oluso: api_key is required")
+        self._options = options
+        self._sanitizer = Sanitizer(options.sensitive_keys)
+        self._rate_limiter = RateLimiter(options.max_errors_per_minute)
+        self._offline_queue = OfflineQueue(options.max_queue_size, options.queue_dir)
+
+        self._send_queue: "queue.Queue[Dict[str, Any]]" = queue.Queue()
+        self._pending = 0
+        self._pending_lock = threading.Lock()
+        self._all_sent = threading.Condition(self._pending_lock)
+        self._worker = threading.Thread(target=self._worker_loop, name="oluso-sender", daemon=True)
+        self._worker.start()
+
+    @property
+    def max_breadcrumbs(self) -> int:
+        """The configured max breadcrumbs per scope, for framework
+        integrations that open a scope themselves.
+        """
+        return self._options.max_breadcrumbs
+
+    @property
+    def sanitizer(self) -> Sanitizer:
+        """The Sanitizer configured for this client (respects
+        Options.sensitive_keys), for framework integrations that build a
+        RequestContext manually.
+        """
+        return self._sanitizer
+
+    def capture_exception(
+        self, error: BaseException, custom_context: Optional[Dict[str, Any]] = None
+    ) -> None:
+        """Report error, attaching any breadcrumbs/user/custom context on the
+        current scope (see `oluso.scope`), plus any custom_context given
+        here.
+        """
+        self._capture(error, http_info=None, custom_context=custom_context)
+
+    def capture_http_error(
+        self,
+        error: BaseException,
+        request_context: RequestContext,
+        status_code: int,
+        custom_context: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Like capture_exception but also attaches HTTP request context and
+        a response status code, for reporting an error with request context
+        from a framework integration.
+        """
+        self._capture(error, http_info=(request_context, status_code), custom_context=custom_context)
+
+    def _capture(
+        self,
+        error: BaseException,
+        http_info: Optional[Tuple[RequestContext, int]],
+        custom_context: Optional[Dict[str, Any]],
+    ) -> None:
+        if error is None:
+            return
+        if self._options.should_report and not self._options.should_report(error):
+            return
+        if not self._rate_limiter.can_send():
+            if self._options.log_to_console:
+                logger.warning("[Oluso] rate limit exceeded, error not reported")
+            return
+        if self._options.log_to_console:
+            logger.error("[Oluso] %s", error)
+
+        stack_trace = "".join(
+            traceback.format_exception(type(error), error, error.__traceback__)
+        )
+        err_ctx = self._build_error_context(http_info, custom_context)
+
+        if self._options.fingerprint:
+            fingerprint = self._options.fingerprint(error, err_ctx)
+        else:
+            fingerprint = generate_fingerprint(error, stack_trace)
+
+        severity = self._options.default_severity
+        if http_info is not None:
+            _, status_code = http_info
+            if status_code >= 500:
+                severity = Severity.CRITICAL
+            elif status_code >= 400:
+                severity = Severity.HIGH
+
+        report = ErrorReport(
+            title=_error_title(error),
+            message=str(error),
+            stack_trace=stack_trace,
+            environment=self._options.environment,
+            severity=severity.value if isinstance(severity, Severity) else severity,
+            tags=list(self._options.tags),
+            fingerprint=fingerprint,
+            context=err_ctx,
+            timestamp=int(time.time() * 1000),
+        )
+
+        with self._pending_lock:
+            self._pending += 1
+        self._send_queue.put(report.to_dict())
+
+    def _build_error_context(
+        self,
+        http_info: Optional[Tuple[RequestContext, int]],
+        custom_context: Optional[Dict[str, Any]],
+    ) -> ErrorContext:
+        breadcrumbs, user, custom = _snapshot()
+
+        if custom_context:
+            custom = {**custom, **custom_context}
+
+        err_ctx = ErrorContext(
+            server=get_server_context(),
+            user=user,
+            custom=custom,
+            breadcrumbs=breadcrumbs,
+        )
+
+        if http_info is not None:
+            err_ctx.request = http_info[0]
+
+        return err_ctx
+
+    def _worker_loop(self) -> None:
+        while True:
+            report = self._send_queue.get()
+            try:
+                self._send_report(report)
+            finally:
+                with self._pending_lock:
+                    self._pending -= 1
+                    if self._pending <= 0:
+                        self._all_sent.notify_all()
+                self._send_queue.task_done()
+
+    def _send_report(self, report: Dict[str, Any]) -> None:
+        try:
+            send_error_report(
+                self._options.endpoint, report, self._options.api_key, self._options.timeout
+            )
+        except TransportError as e:
+            if self._options.log_to_console:
+                logger.error("[Oluso] failed to send error report: %s", e)
+            if self._options.enable_offline_queue:
+                self._offline_queue.enqueue(report)
+            return
+
+        if self._options.enable_offline_queue and not self._offline_queue.is_empty():
+            self._offline_queue.process_queue(
+                lambda r: send_error_report(
+                    self._options.endpoint, r, self._options.api_key, self._options.timeout
+                )
+            )
+
+    def flush(self, timeout: Optional[float] = None) -> bool:
+        """Block until all in-flight and queued reports have been sent, or
+        timeout elapses (None waits indefinitely). Returns True if everything
+        was flushed before the timeout. Call this before your process exits
+        so a capture right before shutdown isn't lost.
+        """
+        with self._pending_lock:
+            deadline = None if timeout is None else time.time() + timeout
+            while self._pending > 0:
+                remaining = None if deadline is None else max(0.0, deadline - time.time())
+                if remaining == 0.0:
+                    return False
+                if not self._all_sent.wait(remaining):
+                    return False
+
+        if self._options.enable_offline_queue and not self._offline_queue.is_empty():
+            self._offline_queue.process_queue(
+                lambda r: send_error_report(
+                    self._options.endpoint, r, self._options.api_key, self._options.timeout
+                )
+            )
+        return True
+
+
+def _error_title(error: BaseException) -> str:
+    message = str(error)
+    first_line = message.splitlines()[0].strip() if message else ""
+    if first_line:
+        return first_line if len(first_line) <= 100 else first_line[:97] + "..."
+    return f"{type(error).__name__} error"

oluso/context.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import contextvars
+import threading
+import time
+from contextlib import contextmanager
+from typing import Any, Dict, Iterator, List, Optional, Tuple
+
+from .types import Breadcrumb, BreadcrumbLevel, UserContext
+
+_current_scope: "contextvars.ContextVar[Optional[_Scope]]" = contextvars.ContextVar(
+    "oluso_scope", default=None
+)
+
+
+class _Scope:
+    def __init__(self, max_breadcrumbs: int) -> None:
+        self._lock = threading.Lock()
+        self._max_breadcrumbs = max_breadcrumbs
+        self.breadcrumbs: List[Breadcrumb] = []
+        self.user: Optional[UserContext] = None
+        self.custom: Dict[str, Any] = {}
+        self.request_start: Optional[float] = None
+
+    def add_breadcrumb(self, breadcrumb: Breadcrumb) -> None:
+        with self._lock:
+            breadcrumb.timestamp = time.time()
+            self.breadcrumbs.append(breadcrumb)
+            if len(self.breadcrumbs) > self._max_breadcrumbs:
+                self.breadcrumbs.pop(0)
+
+    def set_user(self, user: UserContext) -> None:
+        with self._lock:
+            self.user = user
+
+    def set_custom(self, key: str, value: Any) -> None:
+        with self._lock:
+            self.custom[key] = value
+
+    def snapshot(self) -> Tuple[List[Breadcrumb], Optional[UserContext], Dict[str, Any]]:
+        with self._lock:
+            return list(self.breadcrumbs), self.user, dict(self.custom)
+
+
+@contextmanager
+def scope(max_breadcrumbs: int = 30) -> Iterator[None]:
+    """Context manager establishing an isolated breadcrumb/user/custom-data
+    scope for the code inside it -- Python's equivalent of the per-request
+    scope other Oluso SDKs build on Node's AsyncLocalStorage or Go's
+    context.Context, implemented with contextvars instead, since that's the
+    idiomatic mechanism for request/task-scoped state in Python (correctly
+    isolated per thread AND per asyncio task).
+
+    Framework integrations call this for you; call it yourself for
+    non-request work (a background job, a CLI command) where you still want
+    breadcrumbs/user context scoped to that one unit of work::
+
+        with oluso.scope():
+            oluso.add_breadcrumb("job started")
+            client.capture_exception(err)
+    """
+    token = _current_scope.set(_Scope(max_breadcrumbs))
+    try:
+        yield
+    finally:
+        _current_scope.reset(token)
+
+
+def add_breadcrumb(
+    message: str,
+    level: BreadcrumbLevel = BreadcrumbLevel.INFO,
+    category: Optional[str] = None,
+    data: Optional[Dict[str, Any]] = None,
+) -> None:
+    """Record a breadcrumb on the current scope. A no-op outside a scope()."""
+    s = _current_scope.get()
+    if s is None:
+        return
+    s.add_breadcrumb(Breadcrumb(message=message, level=level, category=category, data=data))
+
+
+def set_user(user: UserContext) -> None:
+    """Set the user context on the current scope. A no-op outside a scope()."""
+    s = _current_scope.get()
+    if s is not None:
+        s.set_user(user)
+
+
+def set_custom_context(key: str, value: Any) -> None:
+    """Set a custom key/value on the current scope. A no-op outside a scope()."""
+    s = _current_scope.get()
+    if s is not None:
+        s.set_custom(key, value)
+
+
+def _set_request_start_time(t: float) -> None:
+    s = _current_scope.get()
+    if s is not None:
+        s.request_start = t
+
+
+def _get_request_start_time() -> Optional[float]:
+    s = _current_scope.get()
+    return s.request_start if s is not None else None
+
+
+def _snapshot() -> Tuple[List[Breadcrumb], Optional[UserContext], Dict[str, Any]]:
+    s = _current_scope.get()
+    if s is None:
+        return [], None, {}
+    return s.snapshot()

oluso/fingerprint.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import hashlib
+import re
+from typing import Optional
+
+_RE_NUMBER = re.compile(r"\d+")
+_RE_UUID = re.compile(
+    r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}", re.IGNORECASE
+)
+_RE_PATH = re.compile(r"/[\w/.\-]+")
+_RE_URL = re.compile(r"https?://\S+")
+_RE_SPACE = re.compile(r"\s+")
+
+
+def generate_fingerprint(error: BaseException, stack_trace: Optional[str] = None) -> str:
+    """Produce a stable identifier for grouping similar errors together, from
+    the error's type, a normalized version of its message (with dynamic
+    values like IDs and paths stripped), and -- if provided -- a stack trace
+    signature.
+    """
+    components = [type(error).__name__, _normalize_message(str(error))]
+    if stack_trace:
+        components.append(_stack_signature(stack_trace))
+
+    digest = hashlib.sha256("|".join(components).encode("utf-8")).hexdigest()
+    return digest[:8]
+
+
+def _normalize_message(message: str) -> str:
+    message = _RE_NUMBER.sub("N", message)
+    message = _RE_UUID.sub("UUID", message)
+    message = _RE_PATH.sub("PATH", message)
+    message = _RE_URL.sub("URL", message)
+    message = _RE_SPACE.sub(" ", message)
+    return message.strip()
+
+
+def _stack_signature(stack: str, limit: int = 6) -> str:
+    """Extract just the call-site lines from a traceback (skipping the
+    indented "File ..., line N" detail lines Python's traceback module
+    produces), so the signature groups the same logical call site together
+    even as line numbers shift.
+    """
+    frames = []
+    for line in stack.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("File ") or stripped.startswith("Traceback"):
+            continue
+        frames.append(stripped)
+        if len(frames) >= limit:
+            break
+    return "->".join(frames)

oluso/integrations/flask.py

@@ -0,0 +1,151 @@
+"""Oluso integration for Flask (and any other WSGI application).
+
+Two hooks are combined here, deliberately:
+
+- A WSGI middleware wrapping the whole app, since that gives one
+  synchronous call frame per request -- the natural place to open a single
+  `oluso.scope()` context manager around it, and to catch 5xx responses that
+  don't come from a raised exception (e.g. a view returning `"", 500`
+  directly). As a side effect, this works for any WSGI app, not just Flask.
+- Flask's `got_request_exception` signal, since Flask/Werkzeug catches an
+  unhandled view exception *internally* and converts it to a 500 response
+  before it would ever reach the outer WSGI middleware's `except` clause --
+  without this signal, only a synthetic "server error: 500" message would
+  be reported instead of the real exception.
+
+Both paths mark the request as already-reported (via the WSGI environ, which
+both share) so a raised exception is never double-reported.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, Dict, Iterable, List, Optional, Tuple
+from urllib.parse import parse_qs
+
+from ..client import Oluso
+from ..context import _get_request_start_time, _set_request_start_time, add_breadcrumb, scope
+from ..types import BreadcrumbLevel, RequestContext
+
+StartResponse = Callable[..., Any]
+WSGIApp = Callable[[Dict[str, Any], StartResponse], Iterable[bytes]]
+
+_REPORTED_KEY = "oluso.reported"
+
+
+class OlusoMiddleware:
+    """WSGI middleware: scopes breadcrumbs to each request and auto-reports
+    5xx responses that aren't already covered by the `got_request_exception`
+    signal (see module docstring). Lets exceptions propagate normally
+    afterward -- this only observes and reports, it doesn't change how your
+    app responds to errors.
+
+    Note: status is captured from the synchronous `start_response` call, so
+    a view that defers setting its status code until a streamed response
+    body is iterated (uncommon in typical Flask apps) won't be captured
+    accurately.
+    """
+
+    def __init__(self, wsgi_app: WSGIApp, client: Oluso) -> None:
+        self.wsgi_app = wsgi_app
+        self.client = client
+
+    def __call__(self, environ: Dict[str, Any], start_response: StartResponse) -> Iterable[bytes]:
+        with scope(self.client.max_breadcrumbs):
+            _set_request_start_time(time.time())
+            method = environ.get("REQUEST_METHOD", "")
+            path = environ.get("PATH_INFO", "")
+
+            add_breadcrumb(
+                message=f"{method} {path}",
+                level=BreadcrumbLevel.INFO,
+                category="http",
+                data={"method": method, "url": path},
+            )
+
+            status_holder: Dict[str, int] = {}
+
+            def _start_response(status: str, headers: List[Tuple[str, str]], exc_info: Any = None) -> Any:
+                status_holder["code"] = _parse_status_code(status)
+                return start_response(status, headers, exc_info)
+
+            try:
+                result = self.wsgi_app(environ, _start_response)
+            except Exception as exc:
+                if not environ.get(_REPORTED_KEY):
+                    req_ctx = _build_request_context(self.client, environ)
+                    self.client.capture_http_error(exc, req_ctx, 500)
+                raise
+
+            status = status_holder.get("code", 200)
+            if status >= 500 and not environ.get(_REPORTED_KEY):
+                req_ctx = _build_request_context(self.client, environ)
+                error = RuntimeError(f"server error: {status} - {method} {path}")
+                self.client.capture_http_error(error, req_ctx, status)
+
+            add_breadcrumb(
+                message=f"Response {status} - {method} {path}",
+                level=BreadcrumbLevel.ERROR if status >= 400 else BreadcrumbLevel.INFO,
+                category="http",
+                data={"statusCode": status},
+            )
+
+            return result
+
+
+def init_app(app: Any, client: Oluso) -> None:
+    """Register Oluso on a Flask app: `oluso.integrations.flask.init_app(app, client)`."""
+    app.wsgi_app = OlusoMiddleware(app.wsgi_app, client)
+
+    from flask import got_request_exception  # local import: flask is an optional dependency
+
+    def _on_exception(sender: Any, exception: BaseException, **extra: Any) -> None:
+        from flask import request
+
+        request.environ[_REPORTED_KEY] = True
+        req_ctx = _build_request_context(client, request.environ)
+        client.capture_http_error(exception, req_ctx, 500)
+
+    got_request_exception.connect(_on_exception, app, weak=False)
+
+
+def _parse_status_code(status: str) -> int:
+    try:
+        return int(status.split(" ", 1)[0])
+    except (ValueError, IndexError):
+        return 200
+
+
+def _build_request_context(client: Oluso, environ: Dict[str, Any]) -> RequestContext:
+    method = environ.get("REQUEST_METHOD", "")
+    path = environ.get("PATH_INFO", "")
+    query_string = environ.get("QUERY_STRING", "")
+
+    headers: Dict[str, str] = {}
+    for key, value in environ.items():
+        if key.startswith("HTTP_"):
+            headers[key[5:].replace("_", "-").title()] = value
+    if environ.get("CONTENT_TYPE"):
+        headers["Content-Type"] = environ["CONTENT_TYPE"]
+    if environ.get("CONTENT_LENGTH"):
+        headers["Content-Length"] = environ["CONTENT_LENGTH"]
+
+    query: Dict[str, Any] = {}
+    if query_string:
+        for key, values in parse_qs(query_string).items():
+            query[key] = values[0] if len(values) == 1 else values
+
+    response_time_ms: Optional[int] = None
+    start = _get_request_start_time()
+    if start is not None:
+        response_time_ms = int((time.time() - start) * 1000)
+
+    return RequestContext(
+        url=path,
+        method=method,
+        headers=client.sanitizer.sanitize_headers(headers),
+        query=client.sanitizer.sanitize_query(query),
+        ip=environ.get("REMOTE_ADDR"),
+        user_agent=environ.get("HTTP_USER_AGENT"),
+        response_time_ms=response_time_ms,
+    )

oluso/options.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+from .types import FingerprintFunc, Severity, ShouldReportFunc
+
+DEFAULT_ENDPOINT = "https://api.oluso.dev/api/v1/error/report"
+
+
+@dataclass
+class Options:
+    """Configures an :class:`~oluso.client.Oluso` client."""
+
+    # API key for authentication (sent as the x-oluso-signature header). Required.
+    api_key: str
+
+    # Override the ingestion endpoint. Useful for self-hosting.
+    endpoint: str = DEFAULT_ENDPOINT
+
+    environment: str = "production"
+    default_severity: Severity = Severity.MEDIUM
+    tags: List[str] = field(default_factory=list)
+
+    should_report: Optional[ShouldReportFunc] = None
+    fingerprint: Optional[FingerprintFunc] = None
+
+    # Timeout in seconds for each report request.
+    timeout: float = 5.0
+
+    log_to_console: bool = True
+
+    max_breadcrumbs: int = 30
+
+    enable_offline_queue: bool = True
+    max_queue_size: int = 100
+    # Override where the offline queue is persisted. Defaults to
+    # <tempdir>/oluso-queue.
+    queue_dir: Optional[str] = None
+
+    max_errors_per_minute: int = 60
+    sensitive_keys: List[str] = field(default_factory=list)

oluso/queue.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import threading
+import time
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, List, Optional
+
+
+@dataclass
+class _QueuedReport:
+    report: Dict[str, Any]
+    timestamp: float
+    retries: int = 0
+
+
+class OfflineQueue:
+    """Persists error reports that failed to send, for retry on the next
+    successful send.
+    """
+
+    def __init__(self, max_size: int = 100, queue_dir: Optional[str] = None) -> None:
+        self._max_size = max_size if max_size > 0 else 100
+        directory = queue_dir or os.path.join(tempfile.gettempdir(), "oluso-queue")
+        os.makedirs(directory, exist_ok=True)
+        self._file_path = os.path.join(directory, "error-queue.json")
+
+        self._lock = threading.Lock()
+        self._queue: List[_QueuedReport] = []
+        self._load()
+
+    def enqueue(self, report: Dict[str, Any]) -> None:
+        """report is an already-serialized report (see ErrorReport.to_dict())."""
+        with self._lock:
+            self._queue.append(_QueuedReport(report=report, timestamp=time.time()))
+            if len(self._queue) > self._max_size:
+                self._queue.pop(0)
+            self._save()
+
+    def size(self) -> int:
+        with self._lock:
+            return len(self._queue)
+
+    def is_empty(self) -> bool:
+        return self.size() == 0
+
+    def clear(self) -> None:
+        with self._lock:
+            self._queue = []
+            self._save()
+
+    def _load(self) -> None:
+        try:
+            with open(self._file_path, "r", encoding="utf-8") as f:
+                raw = json.load(f)
+        except (FileNotFoundError, json.JSONDecodeError, OSError):
+            return
+
+        cutoff = time.time() - 24 * 60 * 60
+        self._queue = [
+            _QueuedReport(report=item["report"], timestamp=item["timestamp"], retries=item.get("retries", 0))
+            for item in raw
+            if item.get("timestamp", 0) > cutoff
+        ]
+
+    def _save(self) -> None:
+        """Must be called with self._lock held."""
+        try:
+            payload = [
+                {"report": q.report, "timestamp": q.timestamp, "retries": q.retries} for q in self._queue
+            ]
+            with open(self._file_path, "w", encoding="utf-8") as f:
+                json.dump(payload, f)
+        except OSError:
+            pass
+
+    def process_queue(self, send_fn: Callable[[dict], None]) -> None:
+        """Attempt to send each queued report in order via send_fn (raises on
+        failure), stopping at the first failure (which is requeued at the
+        front with an incremented retry count, and dropped after 3 failed
+        attempts).
+
+        send_fn is called without holding the queue's lock, so enqueue() from
+        another thread isn't blocked for the duration of a slow or hanging
+        send.
+        """
+        while True:
+            with self._lock:
+                if not self._queue:
+                    return
+                item = self._queue[0]
+
+            try:
+                send_fn(item.report)
+            except Exception:
+                with self._lock:
+                    if not self._queue or self._queue[0] is not item:
+                        return  # queue mutated concurrently; bail out safely
+                    item.retries += 1
+                    if item.retries >= 3:
+                        self._queue.pop(0)
+                    self._save()
+                return
+
+            with self._lock:
+                if not self._queue or self._queue[0] is not item:
+                    return
+                self._queue.pop(0)
+                self._save()

oluso/rate_limiter.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import threading
+import time
+from typing import Callable, List
+
+
+class RateLimiter:
+    """Caps how many errors are reported within a rolling one-minute window."""
+
+    def __init__(self, max_per_minute: int = 60, now: Callable[[], float] = time.time) -> None:
+        self._max_per_minute = max_per_minute if max_per_minute > 0 else 60
+        self._now = now
+        self._timestamps: List[float] = []
+        self._lock = threading.Lock()
+
+    def can_send(self) -> bool:
+        with self._lock:
+            now = self._now()
+            cutoff = now - 60
+            self._timestamps = [ts for ts in self._timestamps if ts > cutoff]
+
+            if len(self._timestamps) < self._max_per_minute:
+                self._timestamps.append(now)
+                return True
+            return False
+
+    def count(self) -> int:
+        with self._lock:
+            cutoff = self._now() - 60
+            self._timestamps = [ts for ts in self._timestamps if ts > cutoff]
+            return len(self._timestamps)
+
+    def reset(self) -> None:
+        with self._lock:
+            self._timestamps = []

oluso/sanitizer.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, Iterable, Optional
+
+DEFAULT_SENSITIVE_KEYS = [
+    "password",
+    "passwd",
+    "pwd",
+    "secret",
+    "token",
+    "api_key",
+    "apikey",
+    "access_token",
+    "auth",
+    "credentials",
+    "mysql_pwd",
+    "private_key",
+    "privatekey",
+    "session",
+    "cookie",
+    "csrf",
+    "xsrf",
+    "authorization",
+    "bearer",
+    "jwt",
+    "ssn",
+    "social_security",
+    "credit_card",
+    "card_number",
+    "cvv",
+    "pin",
+]
+
+REDACTED = "[REDACTED]"
+
+
+class Sanitizer:
+    """Redacts sensitive values from request data before it's reported."""
+
+    def __init__(self, custom_sensitive_keys: Optional[Iterable[str]] = None) -> None:
+        keys = list(DEFAULT_SENSITIVE_KEYS) + list(custom_sensitive_keys or [])
+        self._patterns = [re.compile(re.escape(k), re.IGNORECASE) for k in keys]
+
+    def _is_sensitive_key(self, key: str) -> bool:
+        return any(p.search(key) for p in self._patterns)
+
+    def sanitize_headers(self, headers: Dict[str, str]) -> Dict[str, str]:
+        out: Dict[str, str] = {}
+        for key, value in headers.items():
+            lower = key.lower()
+            if lower in ("authorization", "cookie") or self._is_sensitive_key(key):
+                out[key] = REDACTED
+            else:
+                out[key] = str(value)
+        return out
+
+    def sanitize_query(self, query: Dict[str, Any]) -> Dict[str, str]:
+        out: Dict[str, str] = {}
+        for key, value in query.items():
+            if self._is_sensitive_key(key):
+                out[key] = REDACTED
+            elif isinstance(value, (list, tuple)):
+                out[key] = ", ".join(str(v) for v in value)
+            else:
+                out[key] = str(value)
+        return out
+
+    def sanitize_value(self, value: Any, max_depth: int = 10) -> Any:
+        """Recursively redact sensitive keys from arbitrary JSON-shaped data
+        (dicts, lists, and primitives). Data of this shape can't contain
+        cycles, so unlike sanitizing an arbitrary object graph, no
+        circular-reference guard is needed.
+        """
+        return self._sanitize(value, max_depth)
+
+    def _sanitize(self, value: Any, depth: int) -> Any:
+        if depth <= 0:
+            return "[Max Depth Reached]"
+
+        if isinstance(value, dict):
+            out: Dict[str, Any] = {}
+            for key, val in value.items():
+                if self._is_sensitive_key(str(key)):
+                    out[key] = REDACTED
+                else:
+                    out[key] = self._sanitize(val, depth - 1)
+            return out
+
+        if isinstance(value, (list, tuple)):
+            return [self._sanitize(item, depth - 1) for item in value]
+
+        return value
+
+
+def truncate_string(s: str, max_length: int = 1000) -> str:
+    """Limit a string's length to prevent huge payloads."""
+    if len(s) <= max_length:
+        return s
+    return s[:max_length] + "... [truncated]"

oluso/server_context.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import os
+import platform
+import threading
+import time
+
+from .types import ServerContext
+
+_process_start = time.time()
+
+try:
+    import resource
+
+    def _memory_rss_bytes() -> int:
+        # ru_maxrss is KB on Linux, bytes on macOS/BSD.
+        rss = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
+        return rss * 1024 if platform.system() != "Darwin" else rss
+except ImportError:  # resource is POSIX-only; not available on Windows
+
+    def _memory_rss_bytes() -> int:
+        return 0
+
+
+def get_server_context() -> ServerContext:
+    return ServerContext(
+        hostname=platform.node(),
+        platform=f"{platform.system()} {platform.release()}",
+        python_version=platform.python_version(),
+        process_id=os.getpid(),
+        memory_rss=_memory_rss_bytes(),
+        thread_count=threading.active_count(),
+        uptime_seconds=time.time() - _process_start,
+    )

oluso/transport.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any, Dict
+
+
+class TransportError(Exception):
+    """Raised when a report fails to send. Carries no special data -- callers
+    only need to know it failed, so it can be queued for retry.
+    """
+
+
+def send_error_report(
+    endpoint: str, report: Dict[str, Any], api_key: str, timeout: float
+) -> None:
+    """POST report to endpoint. Raises TransportError on any failure
+    (network error, timeout, or non-2xx status) so callers can decide how to
+    handle it (e.g. enqueue for retry) -- this never fails silently the way
+    a fire-and-forget call would.
+    """
+    body = json.dumps(report).encode("utf-8")
+    req = urllib.request.Request(
+        endpoint,
+        data=body,
+        method="POST",
+        headers={
+            "Content-Type": "application/json",
+            "x-oluso-signature": api_key,
+        },
+    )
+
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            status = resp.status
+            if status < 200 or status >= 300:
+                raise TransportError(f"oluso: reporting failed with status {status}")
+    except urllib.error.HTTPError as e:
+        raise TransportError(f"oluso: reporting failed with status {e.code}") from e
+    except urllib.error.URLError as e:
+        raise TransportError(f"oluso: send report: {e.reason}") from e
+    except TimeoutError as e:
+        raise TransportError(f"oluso: send report timed out: {e}") from e

oluso/types.py

@@ -0,0 +1,168 @@
+"""Data types for Oluso error reports.
+
+These serialize to the same wire format the Node and Go SDKs use (camelCase
+JSON keys, with the historical exception of ``stack_trace``), since all
+Oluso SDKs report to the same backend API.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Callable, Optional
+
+
+class Severity(str, Enum):
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+class BreadcrumbLevel(str, Enum):
+    DEBUG = "debug"
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+
+
+def _omit_none(d: dict[str, Any]) -> dict[str, Any]:
+    return {k: v for k, v in d.items() if v is not None}
+
+
+@dataclass
+class Breadcrumb:
+    message: str
+    level: BreadcrumbLevel = BreadcrumbLevel.INFO
+    category: Optional[str] = None
+    data: Optional[dict[str, Any]] = None
+    timestamp: Optional[float] = None  # unix seconds, set when recorded
+
+    def to_dict(self) -> dict[str, Any]:
+        return _omit_none(
+            {
+                "timestamp": int(self.timestamp * 1000) if self.timestamp else None,
+                "message": self.message,
+                "level": self.level.value if isinstance(self.level, BreadcrumbLevel) else self.level,
+                "category": self.category,
+                "data": self.data,
+            }
+        )
+
+
+@dataclass
+class UserContext:
+    id: Optional[str] = None
+    email: Optional[str] = None
+    username: Optional[str] = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return _omit_none(
+            {
+                "id": self.id,
+                "email": self.email,
+                "username": self.username,
+                "extra": self.extra or None,
+            }
+        )
+
+
+@dataclass
+class RequestContext:
+    url: str
+    method: str
+    headers: Optional[dict[str, str]] = None
+    query: Optional[dict[str, str]] = None
+    body: Any = None
+    ip: Optional[str] = None
+    user_agent: Optional[str] = None
+    response_time_ms: Optional[int] = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return _omit_none(
+            {
+                "url": self.url,
+                "method": self.method,
+                "headers": self.headers,
+                "query": self.query,
+                "body": self.body,
+                "ip": self.ip,
+                "userAgent": self.user_agent,
+                "responseTime": self.response_time_ms,
+            }
+        )
+
+
+@dataclass
+class ServerContext:
+    hostname: str
+    platform: str
+    python_version: str
+    process_id: int
+    memory_rss: int
+    thread_count: int
+    uptime_seconds: float
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "hostname": self.hostname,
+            "platform": self.platform,
+            "pythonVersion": self.python_version,
+            "processId": self.process_id,
+            "memoryUsed": self.memory_rss,
+            "threadCount": self.thread_count,
+            "uptime": self.uptime_seconds,
+        }
+
+
+@dataclass
+class ErrorContext:
+    request: Optional[RequestContext] = None
+    user: Optional[UserContext] = None
+    server: Optional[ServerContext] = None
+    custom: dict[str, Any] = field(default_factory=dict)
+    breadcrumbs: list[Breadcrumb] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return _omit_none(
+            {
+                "request": self.request.to_dict() if self.request else None,
+                "user": self.user.to_dict() if self.user else None,
+                "server": self.server.to_dict() if self.server else None,
+                "custom": self.custom or None,
+                "breadcrumbs": [b.to_dict() for b in self.breadcrumbs] or None,
+            }
+        )
+
+
+@dataclass
+class ErrorReport:
+    title: str
+    message: str
+    stack_trace: Optional[str] = None
+    environment: Optional[str] = None
+    severity: Optional[str] = None
+    tags: list[str] = field(default_factory=list)
+    fingerprint: Optional[str] = None
+    context: Optional[ErrorContext] = None
+    timestamp: Optional[int] = None  # unix millis
+
+    def to_dict(self) -> dict[str, Any]:
+        return _omit_none(
+            {
+                "title": self.title,
+                "message": self.message,
+                "stack_trace": self.stack_trace,
+                "environment": self.environment,
+                "severity": self.severity,
+                "tags": self.tags or None,
+                "fingerprint": self.fingerprint,
+                "context": self.context.to_dict() if self.context else None,
+                "timestamp": self.timestamp,
+            }
+        )
+
+
+ShouldReportFunc = Callable[[BaseException], bool]
+FingerprintFunc = Callable[[BaseException, Optional[ErrorContext]], str]

oluso-1.0.0.dist-info/METADATA

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: oluso
+Version: 1.0.0
+Summary: AI-powered error monitoring for Python applications: automatic error reporting, breadcrumb tracking, and intelligent error grouping.
+Project-URL: Homepage, https://github.com/olusodotdev/oluso-py
+Project-URL: Repository, https://github.com/olusodotdev/oluso-py
+Project-URL: Issues, https://github.com/olusodotdev/oluso-py/issues
+Author: David Ezeh
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,crash-reporting,debugging,error,error-monitoring,error-tracking,logging,monitoring,reporting
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: flask>=2.3; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: flask
+Requires-Dist: flask>=2.3; extra == 'flask'
+Description-Content-Type: text/markdown
+
+# oluso-py
+
+AI-powered error monitoring for Python applications: automatic error reporting, breadcrumb tracking, and intelligent error grouping.
+
+## Installation
+
+```bash
+pip install oluso
+
+# With a framework integration
+pip install "oluso[flask]"
+```
+
+## Usage with Flask
+
+```python
+from flask import Flask
+from oluso import Oluso, Options
+from oluso.integrations.flask import init_app
+
+app = Flask(__name__)
+
+client = Oluso(Options(api_key="your-api-key", environment="production"))
+init_app(app, client)
+
+@app.route("/")
+def index():
+    raise RuntimeError("something went wrong")  # captured and reported automatically
+```
+
+`init_app` wraps `app.wsgi_app`, so it works with any WSGI application, not just Flask. It scopes breadcrumbs to each request, auto-reports unhandled exceptions and 5xx responses, then re-raises so Flask/Werkzeug's own error handling still runs — Oluso only observes and reports, it never changes how your app responds to errors.
+
+## Breadcrumbs & User Context
+
+Breadcrumbs and user context are scoped per request using `contextvars` — Python's idiomatic equivalent of the `AsyncLocalStorage`-based scoping the Node SDK uses (and Go's `context.Context`), correctly isolated per thread *and* per asyncio task:
+
+```python
+from oluso import add_breadcrumb, set_user
+
+@app.route("/checkout")
+def checkout():
+    add_breadcrumb("user started checkout", category="action")
+    set_user(UserContext(id="user_456"))
+
+    try:
+        do_checkout()
+    except Exception as err:
+        client.capture_exception(err, {"cartId": "cart_123"})
+```
+
+For non-request work (a background job, a CLI command) where you still want a scope, open one yourself:
+
+```python
+from oluso import scope, add_breadcrumb
+
+with scope():
+    add_breadcrumb("job started")
+    client.capture_exception(err)
+```
+
+## Manual Reporting
+
+```python
+client.capture_exception(err, {"customMeta": "extra-info"})
+```
+
+## Advanced Configuration
+
+```python
+from oluso import Oluso, Options, Severity
+
+client = Oluso(Options(
+    api_key="your-api-key",
+    endpoint="https://api.oluso.dev/api/v1/error/report",  # override for self-hosting
+    environment="staging",
+    default_severity=Severity.MEDIUM,
+    max_breadcrumbs=50,
+    max_errors_per_minute=100,
+    sensitive_keys=["ssn", "internal_id"],
+    should_report=lambda err: "expected" not in str(err),
+))
+```
+
+Call `client.flush(timeout=5)` before your process exits so a capture right before shutdown isn't lost.
+
+## Error Report Structure
+
+Reports sent to the API include:
+
+- **Metadata**: Title, message, stack trace, severity, tags.
+- **Context**: Request details (URL, method, headers, etc.), server details (hostname, Python version, memory, thread count).
+- **History**: Breadcrumbs leading up to the error.
+- **Identification**: Fingerprint for deduplication and user ID.
+
+## License
+
+MIT

oluso-1.0.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+oluso/__init__.py,sha256=0oPV61l3CYTNi7m6pxuMHnSb7L81v9dYn8TmvDdjWGw,661
+oluso/client.py,sha256=jD92oyDeQSs8sfU941xLAEvi7t7fxngMdKSkPfY1Mc0,7937
+oluso/context.py,sha256=XwZkAbNSmO0V7tiZPRT6m2hMr_pz--4b9pnFxzpBmcc,3644
+oluso/fingerprint.py,sha256=hLVQH83T0_0MPzmzB2nZzG3ZOokxlWVFmFT9l0ZiwjM,1843
+oluso/options.py,sha256=ZuvOzZ1DZ9yLf4zLI2JyhhXKMQ2h8sw2Ol28SyHmdaE,1207
+oluso/queue.py,sha256=9GwyNcRuyART8vu2LzrWLCEX8qtgtLn29XKURTI8rug,3652
+oluso/rate_limiter.py,sha256=LDYzDji3Veg7AJ0WXW_33uq_s7WDoMUlKsCNIkdSYbE,1134
+oluso/sanitizer.py,sha256=kI1FHPCblvmA7tY0uY4xj6ia6Wys93xFHNCAA-wsfxI,2972
+oluso/server_context.py,sha256=JYHLqlSSMBlLcC4kgZjl01BLYagruiCiN1tKT2F89O8,928
+oluso/transport.py,sha256=RUcrCNTCUQre6GEB4bUwfGEbeCnQK-wG8wTe3fLdJNI,1522
+oluso/types.py,sha256=9AszCW1ttgclKkLn6R4iBg7rqUWo_C0Uf5oVe7KZ_Ow,4843
+oluso/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+oluso/integrations/flask.py,sha256=veV8VX9N7pSIv9mTeFSi6CTtFTPtJwG1wnANj9D5qqk,6006
+oluso-1.0.0.dist-info/METADATA,sha256=RAc2aMhalql78siW8lqBL9grzqvRmFRnG3-OfEF1FEk,4267
+oluso-1.0.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+oluso-1.0.0.dist-info/licenses/LICENSE,sha256=MdjdOgyMeHkqBppsOqxjWO-RTFx-uYrPvuRTSMJEFm4,1067
+oluso-1.0.0.dist-info/RECORD,,

oluso-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

oluso-1.0.0.dist-info/licenses/LICENSE

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