oluso 1.0.0__tar.gz

oluso-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check src tests
+      - run: mypy src
+      - run: pytest -v --cov=oluso --cov-report=term-missing

oluso-1.0.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+build/
+dist/
+.venv/
+venv/
+.DS_Store

oluso-1.0.0/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.

oluso-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,97 @@
+# 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/examples/flask_app.py

@@ -0,0 +1,50 @@
+"""Minimal example of wiring Oluso into a Flask app.
+
+    pip install "oluso[flask]"
+    OLUSO_API_KEY=your-api-key python examples/flask_app.py
+"""
+
+import atexit
+import os
+
+from flask import Flask
+
+from oluso import Oluso, Options, add_breadcrumb
+from oluso.integrations.flask import init_app
+
+client = Oluso(Options(api_key=os.environ.get("OLUSO_API_KEY", ""), environment="development"))
+atexit.register(lambda: client.flush(timeout=5))
+
+app = Flask(__name__)
+init_app(app, client)
+
+
+@app.route("/")
+def index():
+    add_breadcrumb("handling root request")
+    return "ok"
+
+
+@app.route("/boom")
+def boom():
+    # Middleware auto-reports both raised exceptions and 5xx responses, so
+    # a deliberately failing view needs no manual capture at all.
+    raise RuntimeError("something went wrong")
+
+
+@app.route("/manual")
+def manual():
+    try:
+        do_work()
+    except Exception as err:
+        client.capture_exception(err, {"step": "manual example"})
+        return "internal error", 500
+    return "ok"
+
+
+def do_work():
+    raise ValueError("work failed")
+
+
+if __name__ == "__main__":
+    app.run(port=8080)

oluso-1.0.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "oluso"
+version = "1.0.0"
+description = "AI-powered error monitoring for Python applications: automatic error reporting, breadcrumb tracking, and intelligent error grouping."
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "David Ezeh" }]
+requires-python = ">=3.9"
+keywords = [
+    "error",
+    "monitoring",
+    "reporting",
+    "error-tracking",
+    "error-monitoring",
+    "ai",
+    "crash-reporting",
+    "logging",
+    "debugging",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+# Core has zero required third-party dependencies -- it uses only the
+# standard library (urllib for transport, contextvars for scoping), the same
+# "framework-agnostic core, opt-in everything else" design as the Node/Go
+# SDKs. Framework integrations declare their own deps as extras below.
+dependencies = []
+
+[project.optional-dependencies]
+flask = ["flask>=2.3"]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov",
+    "flask>=2.3",
+    "mypy",
+    "ruff",
+]
+
+[project.urls]
+Homepage = "https://github.com/olusodotdev/oluso-py"
+Repository = "https://github.com/olusodotdev/oluso-py"
+Issues = "https://github.com/olusodotdev/oluso-py/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/oluso"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.mypy]
+# The installed mypy version's oldest supported check target; the package's
+# actual floor is still requires-python = ">=3.9" above -- Python 3.9
+# natively supports the PEP 585 generics (dict[str, Any], etc.) used here.
+python_version = "3.10"
+ignore_missing_imports = true

oluso-1.0.0/src/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-1.0.0/src/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"