uncaughtdev 0.1.0__tar.gz

uncaughtdev-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+node_modules/
+dist/
+.turbo/
+.uncaught/
+*.tsbuildinfo
+.env
+.env.local
+.next/
+.DS_Store
+.claude/
+__pycache__/
+*.pyc
+target/
+*.class

uncaughtdev-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: uncaughtdev
+Version: 0.1.0
+Summary: Local-first, AI-ready error monitoring for Python — catch bugs, get AI-powered fixes
+Project-URL: Homepage, https://github.com/ajeeshworkspace/uncaught
+Project-URL: Documentation, https://github.com/ajeeshworkspace/uncaught
+Project-URL: Repository, https://github.com/ajeeshworkspace/uncaught
+Author: Uncaught Dev
+License-Expression: MIT
+Keywords: ai,debugging,error-monitoring,mcp,vibe-coding
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Debuggers
+Requires-Python: >=3.9
+Provides-Extra: all
+Requires-Dist: django>=3.2; extra == 'all'
+Requires-Dist: fastapi>=0.68.0; extra == 'all'
+Requires-Dist: flask>=2.0.0; extra == 'all'
+Requires-Dist: sqlalchemy>=1.4.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=3.2; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.68.0; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=2.0.0; extra == 'flask'
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy>=1.4.0; extra == 'sqlalchemy'
+Description-Content-Type: text/markdown
+
+# uncaught
+
+Local-first, AI-ready error monitoring for Python. Zero-config error capture with automatic fix prompts.
+
+## Install
+
+```bash
+pip install uncaught
+```
+
+## Quick Start
+
+```python
+from uncaught import init_uncaught
+
+client = init_uncaught({
+    "environment": "development",
+})
+
+# Errors are automatically captured via sys.excepthook
+# Or capture manually:
+try:
+    risky_operation()
+except Exception as e:
+    client.capture_error(e)
+```
+
+## Framework Integrations
+
+### FastAPI
+
+```python
+from fastapi import FastAPI
+from uncaught.integrations.fastapi import UncaughtMiddleware
+
+app = FastAPI()
+app.add_middleware(UncaughtMiddleware)
+```
+
+### Flask
+
+```python
+from flask import Flask
+from uncaught.integrations.flask import init_app
+
+app = Flask(__name__)
+init_app(app)
+```
+
+### Django
+
+Add to `MIDDLEWARE` in `settings.py`:
+
+```python
+MIDDLEWARE = [
+    "uncaught.integrations.django.UncaughtMiddleware",
+    # ...
+]
+```
+
+### SQLAlchemy
+
+```python
+from uncaught.integrations.sqlalchemy import setup_sqlalchemy
+
+setup_sqlalchemy(engine)
+```
+
+## How It Works
+
+Errors are written to a local `.uncaught/` directory with AI-ready fix prompts. Use the MCP server to query errors from Claude, Cursor, or any MCP-compatible AI tool.
+
+## License
+
+MIT

uncaughtdev-0.1.0/README.md

@@ -0,0 +1,75 @@
+# uncaught
+
+Local-first, AI-ready error monitoring for Python. Zero-config error capture with automatic fix prompts.
+
+## Install
+
+```bash
+pip install uncaught
+```
+
+## Quick Start
+
+```python
+from uncaught import init_uncaught
+
+client = init_uncaught({
+    "environment": "development",
+})
+
+# Errors are automatically captured via sys.excepthook
+# Or capture manually:
+try:
+    risky_operation()
+except Exception as e:
+    client.capture_error(e)
+```
+
+## Framework Integrations
+
+### FastAPI
+
+```python
+from fastapi import FastAPI
+from uncaught.integrations.fastapi import UncaughtMiddleware
+
+app = FastAPI()
+app.add_middleware(UncaughtMiddleware)
+```
+
+### Flask
+
+```python
+from flask import Flask
+from uncaught.integrations.flask import init_app
+
+app = Flask(__name__)
+init_app(app)
+```
+
+### Django
+
+Add to `MIDDLEWARE` in `settings.py`:
+
+```python
+MIDDLEWARE = [
+    "uncaught.integrations.django.UncaughtMiddleware",
+    # ...
+]
+```
+
+### SQLAlchemy
+
+```python
+from uncaught.integrations.sqlalchemy import setup_sqlalchemy
+
+setup_sqlalchemy(engine)
+```
+
+## How It Works
+
+Errors are written to a local `.uncaught/` directory with AI-ready fix prompts. Use the MCP server to query errors from Claude, Cursor, or any MCP-compatible AI tool.
+
+## License
+
+MIT

uncaughtdev-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "uncaughtdev"
+version = "0.1.0"
+description = "Local-first, AI-ready error monitoring for Python — catch bugs, get AI-powered fixes"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Uncaught Dev" }]
+keywords = ["error-monitoring", "debugging", "ai", "mcp", "vibe-coding"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: FastAPI",
+    "Framework :: Flask",
+    "Framework :: Django",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "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",
+    "Topic :: Software Development :: Debuggers",
+]
+dependencies = []
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.68.0"]
+flask = ["flask>=2.0.0"]
+django = ["django>=3.2"]
+sqlalchemy = ["sqlalchemy>=1.4.0"]
+all = ["fastapi>=0.68.0", "flask>=2.0.0", "django>=3.2", "sqlalchemy>=1.4.0"]
+dev = ["pytest>=7.0", "pytest-asyncio>=0.21.0"]
+
+[project.urls]
+Homepage = "https://github.com/ajeeshworkspace/uncaught"
+Documentation = "https://github.com/ajeeshworkspace/uncaught"
+Repository = "https://github.com/ajeeshworkspace/uncaught"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/uncaught"]

uncaughtdev-0.1.0/src/uncaught/__init__.py

@@ -0,0 +1,14 @@
+"""Uncaught — local-first, AI-ready error monitoring for Python."""
+
+from uncaught.client import UncaughtClient, init_uncaught, get_client
+from uncaught.types import UncaughtConfig, SeverityLevel
+
+__version__ = "0.1.0"
+__all__ = [
+    "UncaughtClient",
+    "init_uncaught",
+    "get_client",
+    "UncaughtConfig",
+    "SeverityLevel",
+    "__version__",
+]

uncaughtdev-0.1.0/src/uncaught/breadcrumbs.py

@@ -0,0 +1,43 @@
+"""Ring-buffer breadcrumb store."""
+
+from __future__ import annotations
+
+import copy
+from collections import deque
+
+from uncaught.types import Breadcrumb
+from uncaught.utils import iso_timestamp
+
+
+class BreadcrumbStore:
+    """Thread-safe ring buffer for breadcrumbs."""
+
+    def __init__(self, max_breadcrumbs: int = 20) -> None:
+        self._buffer: deque[Breadcrumb] = deque(maxlen=max_breadcrumbs)
+
+    def add(self, crumb: dict) -> None:
+        """Append a breadcrumb, auto-adding a timestamp if missing."""
+        entry: Breadcrumb = {
+            "type": crumb.get("type", "custom"),
+            "category": crumb.get("category", ""),
+            "message": crumb.get("message", ""),
+            "timestamp": crumb.get("timestamp", iso_timestamp()),
+        }
+        if crumb.get("data"):
+            entry["data"] = crumb["data"]
+        if crumb.get("level"):
+            entry["level"] = crumb["level"]
+        self._buffer.append(entry)
+
+    def get_all(self) -> list[Breadcrumb]:
+        """Return all stored breadcrumbs in chronological order (copies)."""
+        return [copy.deepcopy(b) for b in self._buffer]
+
+    def get_last(self, n: int) -> list[Breadcrumb]:
+        """Return the most recent n breadcrumbs (copies)."""
+        items = list(self._buffer)[-n:]
+        return [copy.deepcopy(b) for b in items]
+
+    def clear(self) -> None:
+        """Empty the buffer."""
+        self._buffer.clear()

uncaughtdev-0.1.0/src/uncaught/client.py

@@ -0,0 +1,245 @@
+"""Core Uncaught client — the main error capture pipeline."""
+
+from __future__ import annotations
+
+import re
+import sys
+import traceback
+from typing import Any
+
+from uncaught.breadcrumbs import BreadcrumbStore
+from uncaught.env_detector import detect_environment
+from uncaught.fingerprint import generate_fingerprint
+from uncaught.prompt_builder import build_fix_prompt
+from uncaught.rate_limiter import RateLimiter
+from uncaught.sanitizer import sanitize
+from uncaught.transport import ConsoleTransport, LocalFileTransport
+from uncaught.types import Breadcrumb, UncaughtConfig, UncaughtEvent
+from uncaught.utils import generate_uuid, iso_timestamp
+
+# Global singleton
+_client: UncaughtClient | None = None
+
+SDK_NAME = "uncaught-python"
+SDK_VERSION = "0.1.0"
+
+
+class UncaughtClient:
+    """The main Uncaught client that captures, processes, and stores errors."""
+
+    def __init__(self, config: UncaughtConfig | None = None) -> None:
+        config = config or {}
+        self._config = config
+        self._enabled = config.get("enabled", True)
+        self._debug = config.get("debug", False)
+        self._environment = config.get("environment")
+        self._release = config.get("release")
+        self._before_send = config.get("before_send")
+        self._sanitize_keys = config.get("sanitize_keys", [])
+        self._ignore_errors = config.get("ignore_errors", [])
+        self._webhook_url = config.get("webhook_url")
+
+        self._breadcrumbs = BreadcrumbStore(config.get("max_breadcrumbs", 20))
+        self._rate_limiter = RateLimiter(config.get("max_events_per_minute", 30))
+        self._seen_fingerprints: set[str] = set()
+
+        # Setup transport
+        transport_mode = config.get("transport", "local")
+        if transport_mode == "console":
+            self._transport = ConsoleTransport()
+        else:
+            self._transport = LocalFileTransport(config.get("local_output_dir"))
+
+        # Set user context
+        self._user: dict[str, Any] = {}
+
+    def capture_error(
+        self,
+        error: BaseException | str | dict | Any,
+        *,
+        level: str = "error",
+        request: dict | None = None,
+        operation: dict | None = None,
+        user: dict | None = None,
+    ) -> str | None:
+        """Capture an error through the full processing pipeline.
+
+        Returns the event ID if sent, None if dropped.
+        """
+        if not self._enabled:
+            return None
+
+        try:
+            # Normalise the error
+            error_info = self._normalise_error(error)
+
+            # Check ignore list
+            if self._should_ignore(error_info.get("message", "")):
+                return None
+
+            # Generate fingerprint
+            fingerprint = generate_fingerprint(error_info)
+
+            # Rate limit
+            if not self._rate_limiter.should_allow(fingerprint):
+                if self._debug:
+                    print(f"[uncaught] Rate limited: {fingerprint}")
+                return None
+
+            # Build event
+            event: UncaughtEvent = {
+                "eventId": generate_uuid(),
+                "timestamp": iso_timestamp(),
+                "level": level,
+                "fingerprint": fingerprint,
+                "error": error_info,
+                "breadcrumbs": self._breadcrumbs.get_all(),
+                "environment": detect_environment(),
+                "sdk": {"name": SDK_NAME, "version": SDK_VERSION},
+            }
+
+            if self._release:
+                event["release"] = self._release
+            if self._environment:
+                event["environment"]["deploy"] = self._environment
+            if request:
+                event["request"] = request
+            if operation:
+                event["operation"] = operation
+            if user or self._user:
+                event["user"] = {**self._user, **(user or {})}
+            if self._config.get("project_key"):
+                event["projectKey"] = self._config["project_key"]
+
+            # Build fix prompt
+            event["fixPrompt"] = build_fix_prompt(event)
+
+            # Sanitize
+            event = sanitize(event, self._sanitize_keys)
+
+            # Before send hook
+            if self._before_send:
+                result = self._before_send(event)
+                if result is None:
+                    return None
+                event = result
+
+            # Send
+            self._transport.send(event)
+
+            # Webhook on first occurrence
+            if self._webhook_url and fingerprint not in self._seen_fingerprints:
+                self._seen_fingerprints.add(fingerprint)
+                self._send_webhook(event)
+
+            if self._debug:
+                print(f"[uncaught] Captured: {error_info.get('type')}: {error_info.get('message')} ({fingerprint})")
+
+            return event["eventId"]
+
+        except Exception as e:
+            if self._debug:
+                print(f"[uncaught] Internal error: {e}")
+            return None
+
+    def capture_exception(self, **kwargs: Any) -> str | None:
+        """Capture the current exception from sys.exc_info()."""
+        exc_info = sys.exc_info()
+        if exc_info[1] is not None:
+            return self.capture_error(exc_info[1], **kwargs)
+        return None
+
+    def add_breadcrumb(self, crumb: dict) -> None:
+        """Add a breadcrumb to the ring buffer."""
+        self._breadcrumbs.add(crumb)
+
+    def set_user(self, user: dict[str, Any]) -> None:
+        """Set user context for all subsequent events."""
+        self._user = user
+
+    def flush(self) -> None:
+        """Flush pending events."""
+        self._transport.flush()
+
+    def _normalise_error(self, error: BaseException | str | dict | Any) -> dict:
+        """Normalise any error type into a structured ErrorInfo dict."""
+        if isinstance(error, BaseException):
+            tb = "".join(traceback.format_exception(type(error), error, error.__traceback__))
+            return {
+                "message": str(error),
+                "type": type(error).__name__,
+                "stack": tb,
+            }
+        if isinstance(error, str):
+            return {"message": error, "type": "Error"}
+        if isinstance(error, dict):
+            return {
+                "message": error.get("message", str(error)),
+                "type": error.get("type", "Error"),
+                "stack": error.get("stack", ""),
+            }
+        return {"message": str(error), "type": type(error).__name__}
+
+    def _should_ignore(self, message: str) -> bool:
+        """Check if the error message matches any ignore pattern."""
+        for pattern in self._ignore_errors:
+            if isinstance(pattern, str):
+                if pattern in message:
+                    return True
+            else:
+                try:
+                    if re.search(pattern, message):
+                        return True
+                except Exception:
+                    pass
+        return False
+
+    def _send_webhook(self, event: UncaughtEvent) -> None:
+        """Fire-and-forget webhook notification."""
+        try:
+            import urllib.request
+            import json
+            error = event.get("error", {})
+            payload = json.dumps({
+                "title": error.get("message", ""),
+                "errorType": error.get("type", ""),
+                "fingerprint": event.get("fingerprint", ""),
+                "level": event.get("level", ""),
+                "timestamp": event.get("timestamp", ""),
+                "release": event.get("release"),
+                "environment": event.get("environment", {}).get("deploy"),
+                "fixPrompt": event.get("fixPrompt", ""),
+            }).encode("utf-8")
+            req = urllib.request.Request(
+                self._webhook_url,
+                data=payload,
+                headers={"Content-Type": "application/json"},
+            )
+            urllib.request.urlopen(req, timeout=5)
+        except Exception:
+            pass  # Fire and forget
+
+    def _setup_global_handlers(self) -> None:
+        """Install global exception hooks."""
+        original_excepthook = sys.excepthook
+
+        def uncaught_excepthook(exc_type: type, exc_value: BaseException, exc_tb: Any) -> None:
+            self.capture_error(exc_value, level="fatal")
+            original_excepthook(exc_type, exc_value, exc_tb)
+
+        sys.excepthook = uncaught_excepthook
+
+
+def init_uncaught(config: UncaughtConfig | None = None) -> UncaughtClient:
+    """Initialize the global Uncaught client singleton."""
+    global _client
+    _client = UncaughtClient(config)
+    _client._setup_global_handlers()
+    return _client
+
+
+def get_client() -> UncaughtClient:
+    """Get the global Uncaught client. Raises if not initialized."""
+    if _client is None:
+        raise RuntimeError("Uncaught not initialized. Call init_uncaught() first.")
+    return _client

uncaughtdev-0.1.0/src/uncaught/env_detector.py

@@ -0,0 +1,50 @@
+"""Environment detection for Python runtimes and frameworks."""
+
+from __future__ import annotations
+
+import platform
+import sys
+
+from uncaught.types import EnvironmentInfo
+
+
+def detect_environment() -> EnvironmentInfo:
+    """Detect the current Python runtime, framework, and platform."""
+    info: EnvironmentInfo = {
+        "runtime": "Python",
+        "runtimeVersion": platform.python_version(),
+        "platform": sys.platform,
+        "os": platform.system(),
+    }
+
+    # Detect framework
+    if "fastapi" in sys.modules:
+        try:
+            import fastapi
+            info["framework"] = "FastAPI"
+            info["frameworkVersion"] = fastapi.__version__
+        except (ImportError, AttributeError):
+            pass
+    elif "flask" in sys.modules:
+        try:
+            import flask
+            info["framework"] = "Flask"
+            info["frameworkVersion"] = flask.__version__
+        except (ImportError, AttributeError):
+            pass
+    elif "django" in sys.modules:
+        try:
+            import django
+            info["framework"] = "Django"
+            info["frameworkVersion"] = django.get_version()
+        except (ImportError, AttributeError):
+            pass
+    elif "starlette" in sys.modules:
+        try:
+            import starlette
+            info["framework"] = "Starlette"
+            info["frameworkVersion"] = starlette.__version__
+        except (ImportError, AttributeError):
+            pass
+
+    return info