shadow-debugger 0.1.0__py3-none-any.whl

shadow_debugger/throttler.py

@@ -0,0 +1,64 @@
+"""Deduplicates identical errors so the LLM is not called repeatedly for the same bug."""
+
+from __future__ import annotations
+
+import hashlib
+import threading
+import time
+from collections import OrderedDict
+from typing import Any, Callable, Dict, Tuple
+
+
+class ErrorThrottler:
+    """Thread-safe, memory-bounded (LRU) cooldown tracker keyed by error fingerprint."""
+
+    def __init__(
+        self,
+        cooldown_seconds: float = 300,
+        max_entries: int = 1000,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self.cooldown_seconds = cooldown_seconds
+        self.max_entries = max_entries
+        self._clock = clock
+        self._lock = threading.Lock()
+        # fingerprint -> [last_analyzed_timestamp, occurrence_count]
+        self._seen: "OrderedDict[str, list]" = OrderedDict()
+
+    @staticmethod
+    def compute_fingerprint(error_context: Dict[str, Any]) -> str:
+        if error_context.get("fingerprint"):
+            return str(error_context["fingerprint"])
+        exc_type = str(error_context.get("exception_type", ""))
+        filepath = str(error_context.get("file", ""))
+        lineno = str(error_context.get("line", ""))
+        raw_key = f"{exc_type}:{filepath}:{lineno}"
+        return hashlib.sha256(raw_key.encode("utf-8")).hexdigest()[:16]
+
+    def hit(self, fingerprint: str) -> Tuple[bool, int]:
+        """Record an occurrence. Returns ``(should_analyze, occurrence_count)``."""
+        now = self._clock()
+        with self._lock:
+            record = self._seen.get(fingerprint)
+            if record is None:
+                self._seen[fingerprint] = [now, 1]
+                if len(self._seen) > self.max_entries:
+                    self._seen.popitem(last=False)
+                return True, 1
+
+            self._seen.move_to_end(fingerprint)
+            record[1] += 1
+            if now - record[0] >= self.cooldown_seconds:
+                record[0] = now
+                return True, record[1]
+            return False, record[1]
+
+    def should_analyze(self, error_context: Dict[str, Any]) -> Tuple[bool, str, int]:
+        """Check and update cooldown state for ``error_context``."""
+        fingerprint = self.compute_fingerprint(error_context)
+        allowed, count = self.hit(fingerprint)
+        return allowed, fingerprint, count
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._seen)

shadow_debugger-0.1.0.dist-info/METADATA

@@ -0,0 +1,292 @@
+Metadata-Version: 2.4
+Name: shadow-debugger
+Version: 0.1.0
+Summary: Non-blocking AI-powered background error diagnosis and root-cause analysis for Python applications and web APIs.
+Author: GaspareDev
+License: MIT
+Project-URL: Homepage, https://github.com/GaspareDev/shadow-debugger
+Project-URL: Repository, https://github.com/GaspareDev/shadow-debugger
+Project-URL: Issues, https://github.com/GaspareDev/shadow-debugger/issues
+Project-URL: Changelog, https://github.com/GaspareDev/shadow-debugger/blob/main/CHANGELOG.md
+Keywords: debugging,error-tracking,observability,llm,ai,gemini,ollama,openai,anthropic,fastapi,flask,django
+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: 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 :: Bug Tracking
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: gemini
+Requires-Dist: google-genai>=2.22.0; extra == "gemini"
+Provides-Extra: openai
+Requires-Dist: openai>=1.50.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40.0; extra == "anthropic"
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100.0; extra == "fastapi"
+Provides-Extra: flask
+Requires-Dist: flask>=2.2.0; extra == "flask"
+Requires-Dist: blinker>=1.6.0; extra == "flask"
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == "django"
+Provides-Extra: all
+Requires-Dist: google-genai>=2.22.0; extra == "all"
+Requires-Dist: openai>=1.50.0; extra == "all"
+Requires-Dist: anthropic>=0.40.0; extra == "all"
+Requires-Dist: fastapi>=0.100.0; extra == "all"
+Requires-Dist: flask>=2.2.0; extra == "all"
+Requires-Dist: blinker>=1.6.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: httpx>=0.27.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: mypy>=1.11.0; extra == "dev"
+Dynamic: license-file
+
+# shadow-debugger
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+
+Background error diagnosis for Python apps and web APIs.
+
+When an exception or HTTP 500 happens, `shadow-debugger` captures the stack frame from your code, strips secrets from local variables and request data, and sends the context to an LLM in a background worker thread. Your app returns its normal response right away; a few seconds later you get a Markdown postmortem in `./shadow_reports/`.
+
+It works offline with **Ollama** (zero external dependencies) or with **Gemini**, **OpenAI** (including OpenAI-compatible endpoints like Groq, vLLM, LM Studio), and **Anthropic**.
+
+---
+
+## What a report looks like
+
+Given a crashing endpoint:
+
+```python
+@app.get("/checkout/{order_id}")
+async def checkout(order_id: int, discount_items: int = 0):
+    unit_discount = 50 / discount_items
+    return {"order_id": order_id, "discount": unit_discount}
+```
+
+`shadow-debugger` writes `shadow_reports/incident_20261018_103012_ZeroDivisionError_9f2a1c4b.md`:
+
+````markdown
+# Shadow Debugger Incident Report
+
+**Timestamp:** 2026-10-18T10:30:12.418290+00:00  
+**Exception:** `ZeroDivisionError`: division by zero  
+**Location:** `app/routes.py:42` in `checkout`  
+**Fingerprint:** `9f2a1c4b8e1032d1` (occurrences so far: 1)  
+
+---
+
+### 1. Root Cause Summary
+`checkout()` divides `50` by `discount_items` without checking for `0`. When the query parameter is omitted or set to `0`, Python raises `ZeroDivisionError`.
+
+### 2. Trigger Condition
+`GET /checkout/1042?discount_items=0` with local state `{"order_id": 1042, "discount_items": 0}`.
+
+### 3. Proposed Fix
+```python
+unit_discount = 50 / discount_items if discount_items > 0 else 0.0
+```
+```diff
+-    unit_discount = 50 / discount_items
++    unit_discount = 50 / discount_items if discount_items > 0 else 0.0
+```
+
+### 4. Prevention Advice
+Validate numeric query parameters with `Query(gt=0)` in FastAPI or guard denominators before dividing.
+````
+
+---
+
+## Installation
+
+```bash
+# Core package (stdlib only — works with local Ollama out of the box)
+pip install shadow-debugger
+
+# Or install with the provider / framework you use:
+pip install "shadow-debugger[gemini]"
+pip install "shadow-debugger[openai]"
+pip install "shadow-debugger[anthropic]"
+pip install "shadow-debugger[fastapi]"
+pip install "shadow-debugger[flask]"
+pip install "shadow-debugger[django]"
+```
+
+---
+
+## Quick start
+
+### Local with Ollama (no API key)
+
+```python
+import shadow_debugger
+
+shadow_debugger.init(
+    provider="ollama",
+    model="llama3.2",
+    print_to_console=True,
+)
+```
+
+### Cloud providers
+
+```python
+import shadow_debugger
+
+# Uses GEMINI_API_KEY
+shadow_debugger.init(provider="gemini", model="gemini-3.8-flash")
+
+# Uses OPENAI_API_KEY (or pass base_url=... for Groq / vLLM / LM Studio)
+shadow_debugger.init(provider="openai", model="gpt-5.4-nano")
+
+# Uses ANTHROPIC_API_KEY
+shadow_debugger.init(provider="anthropic", model="claude-haiku-5-5")
+```
+
+---
+
+## Web frameworks
+
+### FastAPI / Starlette
+
+```python
+from fastapi import FastAPI
+import shadow_debugger
+
+shadow_debugger.init(provider="ollama", model="llama3.2")
+
+app = FastAPI()
+app.add_middleware(shadow_debugger.FastAPIWatcherMiddleware)
+```
+
+### Flask
+
+```python
+from flask import Flask
+import shadow_debugger
+
+app = Flask(__name__)
+shadow_debugger.init(provider="ollama", model="llama3.2")
+shadow_debugger.init_flask(app)
+```
+
+`init_flask` hooks into `got_request_exception`, so normal 404/4xx responses are left untouched.
+
+### Django
+
+In `settings.py`:
+
+```python
+MIDDLEWARE = [
+    "shadow_debugger.integrations.DjangoWatcherMiddleware",
+    # ...
+]
+```
+
+---
+
+## Decorator & manual capture
+
+`@watch` works on both regular and `async def` functions:
+
+```python
+import shadow_debugger
+
+@shadow_debugger.watch(reraise=False)
+async def process_order(payload: dict):
+    return payload["items"]["price"] / payload["items"]["quantity"]
+
+# Or inside an existing try/except block:
+try:
+    sync_inventory()
+except Exception as exc:
+    shadow_debugger.capture_exception(exc, extra_metadata={"job": "inventory"})
+```
+
+---
+
+## Privacy & what gets sent
+
+If you use a cloud provider, the prompt includes the traceback, the 5 lines of source around the error, and the local variables of the failing function. To keep sensitive data out of prompts:
+
+- **Variable & header names** matching common secret names (`password`, `secret`, `token`, `api_key`, `authorization`, `cookie`, etc.) are replaced with `[REDACTED]`.
+- **String values** matching JWTs, API keys (`sk-...`, `AIza...`, `AKIA...`, `ghp_...`), `Bearer` tokens, PEM private keys, and URL query tokens (`?access_token=...`) are scrubbed across variables, tracebacks, and exception messages.
+- **Lazy objects** (like Django `QuerySet`s) are inspected via `__dict__` without calling `repr()`/`str()`, so capturing an error won't trigger extra database queries.
+- You can turn off parts of the payload with `send_locals=False` or `send_source_code=False`, add your own regexes via `redact_keys=[...]` and `redact_patterns=[...]`, or run everything locally with `provider="ollama"`.
+- Proposed code patches are only checked with `ast.parse()` — generated code is never executed.
+
+---
+
+## Configuration
+
+All options can be passed to `shadow_debugger.init(...)`:
+
+| Option | Default | Description |
+| :--- | :--- | :--- |
+| `provider` | `"gemini"` | `"gemini"`, `"ollama"`, `"openai"`, `"anthropic"`, or a `Provider` instance. |
+| `model` | `None` | Model name. Uses the provider default if omitted. |
+| `api_key` | `None` | API key (falls back to `GEMINI_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`). |
+| `base_url` | `None` | Custom URL for Ollama (`OLLAMA_HOST`) or OpenAI-compatible servers. |
+| `output_dir` | `"./shadow_reports"` | Folder for Markdown reports (`None` disables file output). |
+| `print_to_console` | `False` | Print diagnoses to `stderr` (handy in local dev). |
+| `cooldown_seconds` | `300.0` | Minimum seconds before re-analyzing the same error at the same line. |
+| `send_source_code` | `True` | Include source lines around the crash. |
+| `send_locals` | `True` | Include redacted local variables. |
+| `redact_keys` | `()` | Extra regexes for variable/key names to redact. |
+| `redact_patterns` | `()` | Extra regexes for secret value patterns to scrub. |
+| `request_timeout` | `60.0` | Timeout in seconds for LLM calls. |
+| `shutdown_timeout` | `10.0` | Seconds to wait on process exit for pending reports to finish. |
+| `max_queue_size` | `100` | Max queued incidents before dropping new ones. |
+| `catch_uncaught` | `True` | Hook `sys.excepthook` and `threading.excepthook`. |
+
+---
+
+## Writing a custom provider
+
+```python
+import shadow_debugger
+from shadow_debugger import Provider, register_provider
+
+@register_provider("my-gateway")
+class MyGatewayProvider(Provider):
+    default_model = "my-model"
+    env_key = "MY_GATEWAY_KEY"
+
+    def complete(self, system: str, prompt: str) -> str:
+        self.check_configuration()
+        # Call your LLM endpoint and return Markdown
+        return "..."
+
+shadow_debugger.init(provider="my-gateway")
+```
+
+---
+
+## Roadmap & contributing
+
+I'm actively looking for feedback and contributors. A few areas where PRs are very welcome:
+
+- [ ] Webhook / notification sinks (Slack, Discord, Telegram, GitHub Issues)
+- [ ] Additional providers (Mistral, LiteLLM, AWS Bedrock)
+- [ ] Structured JSON output option alongside Markdown reports
+- [ ] Celery / background worker task integration
+- [ ] CLI command to browse and filter local reports in `./shadow_reports`
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup instructions.
+
+## License
+
+[MIT](LICENSE)

shadow_debugger-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+shadow_debugger/__init__.py,sha256=VUITE75G6KBvXZ3RbIhnEMVnVNFF3Xj8582rwf0cDZ4,9366
+shadow_debugger/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+shadow_debugger/analyzer.py,sha256=0g9IBoTUORJ2yb-Gr9BmAR9MJYAD2wg7RZXACC39Kg4,4049
+shadow_debugger/config.py,sha256=Osh37V4SPZ5u88c9T1PeZ-4dx04fL4YEiPOMBEubgCg,1847
+shadow_debugger/core.py,sha256=99J79AsAVsEoQRshBhzWiNvvchC8OyVQJH99jWM2TlE,9439
+shadow_debugger/inspector.py,sha256=8ixEwvG2FtQiMMv6x-Ny6Du9AWvLFenGLHv0CyBiBIY,6294
+shadow_debugger/patch_check.py,sha256=sy6mtJk6pNWrtdDkR64SrrGvvAP_o04uOgADwF3pIsM,1837
+shadow_debugger/py.typed,sha256=ZSegze1ahS5tlaVlEVAF0HG-jTkkScOwTjUnglYQOS8,22
+shadow_debugger/redaction.py,sha256=CwQQVO65EJl2IcwiGbb1M2eW5QHojxoFZ0kv558SRsI,6555
+shadow_debugger/reporter.py,sha256=TawWb-Vh7jV_6kKPpthqD0vRPhD_44pT0Yax6bU1rAU,5485
+shadow_debugger/throttler.py,sha256=EOPC_Z1ikbFGRBf0sjSc7TojuKgtqs3IL1h-JGyTrYc,2403
+shadow_debugger/integrations/__init__.py,sha256=0tv-_AU5v7PEmhqZbUvMESL7TmllNvhKRu__6v1hkNM,7565
+shadow_debugger/providers/__init__.py,sha256=R7MPArkRWxcu-NyhGcgbq77f3Lgg9ow-nPDrGOiD30c,607
+shadow_debugger/providers/anthropic.py,sha256=R79gClpjwHz6j6w5ELzHfZtTUf2G0NzINYoRfP1mq_s,2031
+shadow_debugger/providers/base.py,sha256=W66umF4drjd_MX9GAhzi3UPCNUWSFtFBUNlzLNlD67I,3071
+shadow_debugger/providers/gemini.py,sha256=CUNJspEQsTZQ6rQ9SP4TmU3euABbXEBpchECKY7_9wk,2573
+shadow_debugger/providers/ollama.py,sha256=Kn037q78PreDqUBYMIoFhxZkDQhxRXHGP-Zg_7-rvoQ,2378
+shadow_debugger/providers/openai.py,sha256=Qqakyt9__nTmE1qG6oDr6ITa9c3xiBwegUDQkfxu6LA,2223
+shadow_debugger-0.1.0.dist-info/licenses/LICENSE,sha256=DTl2sA7c-JVs06AF-1nxjdmE4Xycbe4GlcdpO-HP_o4,1067
+shadow_debugger-0.1.0.dist-info/METADATA,sha256=wbD7bncP3VchW6a8WXXf9I8hsQ1Hp6UsZI2qcw3-tj8,10161
+shadow_debugger-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+shadow_debugger-0.1.0.dist-info/top_level.txt,sha256=uydI_u61yAjtl6_x4rkzQ9Z-RV5QyH0Jn24bq5Rc680,16
+shadow_debugger-0.1.0.dist-info/RECORD,,

shadow_debugger-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

shadow_debugger-0.1.0.dist-info/licenses/LICENSE

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

shadow_debugger-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+shadow_debugger