django-explain-errors 0.9.0__tar.gz → 0.9.1__tar.gz

{django_explain_errors-0.9.0/django_explain_errors.egg-info → django_explain_errors-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-explain-errors
-Version: 0.9.0
+Version: 0.9.1
 Summary: Django middleware that explains unhandled exceptions in DEBUG using an LLM, optionally grounded in your own project source via a local vector index. Works with OpenAI, Claude, or any OpenAI-compatible endpoint including local models.
 Home-page: https://github.com/topunix/django-explain-errors
 Author: topunix
@@ -42,37 +42,31 @@ Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
 
-# Django Explain Errors Middleware
-
-When debug mode is on, this Django middleware sends each unhandled exception
-to a language model and shows its explanation of what went wrong and how to
-fix it on Django's debug page, directly under the exception headline. The
-explanation is also printed to stdout. The middleware works with the OpenAI
-API out of the box, with Anthropic's Claude models through Anthropic's
-OpenAI-compatible endpoint, and with any other OpenAI-compatible endpoint
-(Ollama, LM Studio, Azure, or a corporate gateway) by setting a base URL, so
-explanations can run entirely on a local model if you prefer not to send
-code off your machine.
-
-Enabling RAG is strongly recommended. With it, the middleware retrieves the
-relevant parts of your own project source from a local vector index, so
-explanations name the actual file and function that failed instead of
-guessing. In the package's eval harness, RAG-grounded explanations won 35
-of 43 blind comparisons, with the gap concentrated in pointing at the right
-fix location and not inventing details (see "Does RAG actually help?"
-below). It is off by default because it needs an optional extra and a
-one-time index build.
-
-The middleware supports both synchronous (WSGI) and asynchronous (ASGI)
-views. It auto-detects the view chain at startup and routes requests through
-the matching path, so no extra configuration is required for either server
-type. Tracebacks are sanitized before leaving the process, and API calls are
-rate limited.
-
-![Django debug page with the explanation banner under the exception headline](https://raw.githubusercontent.com/topunix/django-explain-errors/main/docs/images/debug-page-banner.png)
-
-*Real `gpt-4o-mini` output with RAG enabled, recorded by the eval harness
-on its `missing_fk` fixture.*
+# Django Explain Errors
+
+Explains Django exceptions on the debug page, pointing at the real fix in your own source code.
+
+<p align="center">
+  <a href="https://pypi.org/project/django-explain-errors/"><img src="https://img.shields.io/pypi/v/django-explain-errors" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/django-explain-errors/"><img src="https://img.shields.io/pypi/pyversions/django-explain-errors" alt="Python versions"></a>
+  <a href="https://github.com/topunix/django-explain-errors/actions/workflows/test.yml"><img src="https://github.com/topunix/django-explain-errors/actions/workflows/test.yml/badge.svg?branch=main" alt="Tests"></a>
+  <a href="https://github.com/topunix/django-explain-errors/blob/main/LICENSE"><img src="https://img.shields.io/pypi/l/django-explain-errors" alt="License"></a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/topunix/django-explain-errors/main/docs/images/debug-page-banner.png" width="800"
+       alt="Django debug page with the explanation banner under the exception headline">
+</p>
+
+*The traceback held only Django and SQLite internals. With RAG enabled, the explanation names the
+failing function (`clone_latest_post`) and gives the one-line fix. Real `gpt-4o-mini` output from
+the eval harness.*
+
+- **Strongly recommended:** enable RAG over your project, so explanations name the actual file and function instead of guessing ([measured in the eval harness](#does-rag-actually-help)). It is off by default only because [setup](#codebase-aware-explanations-rag) takes three steps.
+- Works with OpenAI, Claude, or any OpenAI-compatible endpoint, including local models via Ollama
+- Explanations in your language via `EXPLAIN_ERRORS_LANGUAGE`, with code and identifiers kept in English
+- Sync and async views, traceback redaction, rate limiting
+- Local development only: requires `DEBUG = True`
 
 ## Scope
 
@@ -85,8 +79,6 @@ If a coding agent is doing the debugging, it does not need this. Agents read tra
 and tools that expose live runtime state (debugger-over-MCP servers, `mcp-django`) serve that case
 better. This package is not trying to compete there.
 
-Local development only. It requires `DEBUG = True` and is inert otherwise.
-
 ## Features
 
 - Captures Django errors and exceptions
@@ -98,8 +90,9 @@ Local development only. It requires `DEBUG = True` and is inert otherwise.
   (`EXPLAIN_ERRORS_PRINT_STDOUT`, on by default)
 - Optional JSON 500 response instead of the debug page
   (`EXPLAIN_ERRORS_PRESERVE_DEBUG_PAGE = False`)
-- Explains errors using OpenAI, Anthropic's Claude models, or any other
-  OpenAI-compatible endpoint (Ollama, LM Studio, Azure, gateways) via `OPENAI_BASE_URL`
+- Explains errors using OpenAI out of the box, Anthropic's Claude models, or any other
+  OpenAI-compatible endpoint (Ollama, LM Studio, Azure, gateways) via `OPENAI_BASE_URL`,
+  including fully local models, so no code has to leave your machine
 - Codebase-aware explanations via RAG over a local sqlite-vec index
   (recommended; see "Codebase-aware explanations" below)
 - Explanations in your language via `EXPLAIN_ERRORS_LANGUAGE`, with exception names,

{django_explain_errors-0.9.0 → django_explain_errors-0.9.1}/README.md

@@ -1,34 +1,28 @@
-# Django Explain Errors Middleware
-
-When debug mode is on, this Django middleware sends each unhandled exception
-to a language model and shows its explanation of what went wrong and how to
-fix it on Django's debug page, directly under the exception headline. The
-explanation is also printed to stdout. The middleware works with the OpenAI
-API out of the box, with Anthropic's Claude models through Anthropic's
-OpenAI-compatible endpoint, and with any other OpenAI-compatible endpoint
-(Ollama, LM Studio, Azure, or a corporate gateway) by setting a base URL, so
-explanations can run entirely on a local model if you prefer not to send
-code off your machine.
-
-Enabling RAG is strongly recommended. With it, the middleware retrieves the
-relevant parts of your own project source from a local vector index, so
-explanations name the actual file and function that failed instead of
-guessing. In the package's eval harness, RAG-grounded explanations won 35
-of 43 blind comparisons, with the gap concentrated in pointing at the right
-fix location and not inventing details (see "Does RAG actually help?"
-below). It is off by default because it needs an optional extra and a
-one-time index build.
-
-The middleware supports both synchronous (WSGI) and asynchronous (ASGI)
-views. It auto-detects the view chain at startup and routes requests through
-the matching path, so no extra configuration is required for either server
-type. Tracebacks are sanitized before leaving the process, and API calls are
-rate limited.
-
-![Django debug page with the explanation banner under the exception headline](https://raw.githubusercontent.com/topunix/django-explain-errors/main/docs/images/debug-page-banner.png)
-
-*Real `gpt-4o-mini` output with RAG enabled, recorded by the eval harness
-on its `missing_fk` fixture.*
+# Django Explain Errors
+
+Explains Django exceptions on the debug page, pointing at the real fix in your own source code.
+
+<p align="center">
+  <a href="https://pypi.org/project/django-explain-errors/"><img src="https://img.shields.io/pypi/v/django-explain-errors" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/django-explain-errors/"><img src="https://img.shields.io/pypi/pyversions/django-explain-errors" alt="Python versions"></a>
+  <a href="https://github.com/topunix/django-explain-errors/actions/workflows/test.yml"><img src="https://github.com/topunix/django-explain-errors/actions/workflows/test.yml/badge.svg?branch=main" alt="Tests"></a>
+  <a href="https://github.com/topunix/django-explain-errors/blob/main/LICENSE"><img src="https://img.shields.io/pypi/l/django-explain-errors" alt="License"></a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/topunix/django-explain-errors/main/docs/images/debug-page-banner.png" width="800"
+       alt="Django debug page with the explanation banner under the exception headline">
+</p>
+
+*The traceback held only Django and SQLite internals. With RAG enabled, the explanation names the
+failing function (`clone_latest_post`) and gives the one-line fix. Real `gpt-4o-mini` output from
+the eval harness.*
+
+- **Strongly recommended:** enable RAG over your project, so explanations name the actual file and function instead of guessing ([measured in the eval harness](#does-rag-actually-help)). It is off by default only because [setup](#codebase-aware-explanations-rag) takes three steps.
+- Works with OpenAI, Claude, or any OpenAI-compatible endpoint, including local models via Ollama
+- Explanations in your language via `EXPLAIN_ERRORS_LANGUAGE`, with code and identifiers kept in English
+- Sync and async views, traceback redaction, rate limiting
+- Local development only: requires `DEBUG = True`
 
 ## Scope
 
@@ -41,8 +35,6 @@ If a coding agent is doing the debugging, it does not need this. Agents read tra
 and tools that expose live runtime state (debugger-over-MCP servers, `mcp-django`) serve that case
 better. This package is not trying to compete there.
 
-Local development only. It requires `DEBUG = True` and is inert otherwise.
-
 ## Features
 
 - Captures Django errors and exceptions
@@ -54,8 +46,9 @@ Local development only. It requires `DEBUG = True` and is inert otherwise.
   (`EXPLAIN_ERRORS_PRINT_STDOUT`, on by default)
 - Optional JSON 500 response instead of the debug page
   (`EXPLAIN_ERRORS_PRESERVE_DEBUG_PAGE = False`)
-- Explains errors using OpenAI, Anthropic's Claude models, or any other
-  OpenAI-compatible endpoint (Ollama, LM Studio, Azure, gateways) via `OPENAI_BASE_URL`
+- Explains errors using OpenAI out of the box, Anthropic's Claude models, or any other
+  OpenAI-compatible endpoint (Ollama, LM Studio, Azure, gateways) via `OPENAI_BASE_URL`,
+  including fully local models, so no code has to leave your machine
 - Codebase-aware explanations via RAG over a local sqlite-vec index
   (recommended; see "Codebase-aware explanations" below)
 - Explanations in your language via `EXPLAIN_ERRORS_LANGUAGE`, with exception names,

{django_explain_errors-0.9.0 → django_explain_errors-0.9.1/django_explain_errors.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-explain-errors
-Version: 0.9.0
+Version: 0.9.1
 Summary: Django middleware that explains unhandled exceptions in DEBUG using an LLM, optionally grounded in your own project source via a local vector index. Works with OpenAI, Claude, or any OpenAI-compatible endpoint including local models.
 Home-page: https://github.com/topunix/django-explain-errors
 Author: topunix
@@ -42,37 +42,31 @@ Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
 
-# Django Explain Errors Middleware
-
-When debug mode is on, this Django middleware sends each unhandled exception
-to a language model and shows its explanation of what went wrong and how to
-fix it on Django's debug page, directly under the exception headline. The
-explanation is also printed to stdout. The middleware works with the OpenAI
-API out of the box, with Anthropic's Claude models through Anthropic's
-OpenAI-compatible endpoint, and with any other OpenAI-compatible endpoint
-(Ollama, LM Studio, Azure, or a corporate gateway) by setting a base URL, so
-explanations can run entirely on a local model if you prefer not to send
-code off your machine.
-
-Enabling RAG is strongly recommended. With it, the middleware retrieves the
-relevant parts of your own project source from a local vector index, so
-explanations name the actual file and function that failed instead of
-guessing. In the package's eval harness, RAG-grounded explanations won 35
-of 43 blind comparisons, with the gap concentrated in pointing at the right
-fix location and not inventing details (see "Does RAG actually help?"
-below). It is off by default because it needs an optional extra and a
-one-time index build.
-
-The middleware supports both synchronous (WSGI) and asynchronous (ASGI)
-views. It auto-detects the view chain at startup and routes requests through
-the matching path, so no extra configuration is required for either server
-type. Tracebacks are sanitized before leaving the process, and API calls are
-rate limited.
-
-![Django debug page with the explanation banner under the exception headline](https://raw.githubusercontent.com/topunix/django-explain-errors/main/docs/images/debug-page-banner.png)
-
-*Real `gpt-4o-mini` output with RAG enabled, recorded by the eval harness
-on its `missing_fk` fixture.*
+# Django Explain Errors
+
+Explains Django exceptions on the debug page, pointing at the real fix in your own source code.
+
+<p align="center">
+  <a href="https://pypi.org/project/django-explain-errors/"><img src="https://img.shields.io/pypi/v/django-explain-errors" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/django-explain-errors/"><img src="https://img.shields.io/pypi/pyversions/django-explain-errors" alt="Python versions"></a>
+  <a href="https://github.com/topunix/django-explain-errors/actions/workflows/test.yml"><img src="https://github.com/topunix/django-explain-errors/actions/workflows/test.yml/badge.svg?branch=main" alt="Tests"></a>
+  <a href="https://github.com/topunix/django-explain-errors/blob/main/LICENSE"><img src="https://img.shields.io/pypi/l/django-explain-errors" alt="License"></a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/topunix/django-explain-errors/main/docs/images/debug-page-banner.png" width="800"
+       alt="Django debug page with the explanation banner under the exception headline">
+</p>
+
+*The traceback held only Django and SQLite internals. With RAG enabled, the explanation names the
+failing function (`clone_latest_post`) and gives the one-line fix. Real `gpt-4o-mini` output from
+the eval harness.*
+
+- **Strongly recommended:** enable RAG over your project, so explanations name the actual file and function instead of guessing ([measured in the eval harness](#does-rag-actually-help)). It is off by default only because [setup](#codebase-aware-explanations-rag) takes three steps.
+- Works with OpenAI, Claude, or any OpenAI-compatible endpoint, including local models via Ollama
+- Explanations in your language via `EXPLAIN_ERRORS_LANGUAGE`, with code and identifiers kept in English
+- Sync and async views, traceback redaction, rate limiting
+- Local development only: requires `DEBUG = True`
 
 ## Scope
 
@@ -85,8 +79,6 @@ If a coding agent is doing the debugging, it does not need this. Agents read tra
 and tools that expose live runtime state (debugger-over-MCP servers, `mcp-django`) serve that case
 better. This package is not trying to compete there.
 
-Local development only. It requires `DEBUG = True` and is inert otherwise.
-
 ## Features
 
 - Captures Django errors and exceptions
@@ -98,8 +90,9 @@ Local development only. It requires `DEBUG = True` and is inert otherwise.
   (`EXPLAIN_ERRORS_PRINT_STDOUT`, on by default)
 - Optional JSON 500 response instead of the debug page
   (`EXPLAIN_ERRORS_PRESERVE_DEBUG_PAGE = False`)
-- Explains errors using OpenAI, Anthropic's Claude models, or any other
-  OpenAI-compatible endpoint (Ollama, LM Studio, Azure, gateways) via `OPENAI_BASE_URL`
+- Explains errors using OpenAI out of the box, Anthropic's Claude models, or any other
+  OpenAI-compatible endpoint (Ollama, LM Studio, Azure, gateways) via `OPENAI_BASE_URL`,
+  including fully local models, so no code has to leave your machine
 - Codebase-aware explanations via RAG over a local sqlite-vec index
   (recommended; see "Codebase-aware explanations" below)
 - Explanations in your language via `EXPLAIN_ERRORS_LANGUAGE`, with exception names,

{django_explain_errors-0.9.0 → django_explain_errors-0.9.1}/explain_errors/rag/indexer.py

@@ -1,5 +1,6 @@
 """File discovery, chunking, and embedding for the RAG source index."""
 import ast
+import contextlib
 import os
 
 from django.conf import settings
@@ -167,16 +168,21 @@ def build_index():
         os.remove(tmp_path)
 
     dimensions = len(embeddings[0]) if embeddings else 1536
-    with VectorStore(tmp_path) as store:
-        store.create(dimensions)
-        store.add(
-            (file_path, start_line, end_line, sanitized_text, embedding)
-            for (file_path, start_line, end_line, _text), sanitized_text, embedding in zip(
-                raw_chunks, sanitized_texts, embeddings
+    try:
+        with VectorStore(tmp_path) as store:
+            store.create(dimensions)
+            store.add(
+                (file_path, start_line, end_line, sanitized_text, embedding)
+                for (file_path, start_line, end_line, _text), sanitized_text, embedding in zip(
+                    raw_chunks, sanitized_texts, embeddings
+                )
             )
-        )
 
-    os.replace(tmp_path, index_path)
+        os.replace(tmp_path, index_path)
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.remove(tmp_path)
+        raise
 
     return {
         "files_scanned": len(files),

{django_explain_errors-0.9.0 → django_explain_errors-0.9.1}/setup.py

@@ -10,7 +10,7 @@ with open('README.md', encoding='utf-8') as f:
 
 setup(
     name='django-explain-errors',
-    version='0.9.0',
+    version='0.9.1',
     packages=find_packages(exclude=['tests', 'tests.*', 'evals', 'evals.*']),
     description='Django middleware that explains unhandled exceptions in DEBUG using an LLM, optionally grounded in your own project source via a local vector index. Works with OpenAI, Claude, or any OpenAI-compatible endpoint including local models.',
     long_description_content_type='text/markdown',

{django_explain_errors-0.9.0 → django_explain_errors-0.9.1}/tests/test_rag.py

@@ -174,6 +174,76 @@ class IndexerBuildTest(SimpleTestCase):
             ]
             self.assertEqual(leftovers, [])
 
+    def test_failed_rebuild_keeps_previous_index_and_removes_temp_file(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            with open(os.path.join(tmp, "app.py"), "w") as f:
+                f.write(SAMPLE_MODULE)
+
+            index_path = os.path.join(tmp, "index.db")
+
+            with override_settings(
+                EXPLAIN_ERRORS_RAG_INCLUDE=[tmp],
+                EXPLAIN_ERRORS_RAG_INDEX_PATH=index_path,
+            ):
+                with patch(
+                    "explain_errors.rag.indexer.get_openai_client",
+                    return_value=_mock_embed_client([0.1, 0.2, 0.3]),
+                ):
+                    build_index()
+
+                    with open(index_path, "rb") as f:
+                        original_bytes = f.read()
+                    with VectorStore(index_path) as store:
+                        original_count = store.count()
+                    self.assertGreater(original_count, 0)
+
+                    with patch.object(
+                        VectorStore, "add", side_effect=RuntimeError("add failed")
+                    ):
+                        with self.assertRaisesRegex(RuntimeError, "add failed"):
+                            build_index()
+
+            with open(index_path, "rb") as f:
+                self.assertEqual(f.read(), original_bytes)
+            with VectorStore(index_path) as store:
+                self.assertEqual(store.count(), original_count)
+
+            leftovers = [
+                name for name in os.listdir(tmp) if name.startswith("index.db.tmp-")
+            ]
+            self.assertEqual(leftovers, [])
+
+    def test_build_index_redacts_secrets_in_stored_chunk_text(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            src = os.path.join(tmp, "src")
+            os.makedirs(src)
+            with open(os.path.join(src, "config.py"), "w") as f:
+                f.write(
+                    "def load():\n"
+                    "    api_key = 'sk-index-secret-value'\n"
+                    "    return api_key\n"
+                )
+
+            index_path = os.path.join(tmp, "index.db")
+            embed_client = _mock_embed_client([0.1, 0.2, 0.3])
+
+            with override_settings(
+                EXPLAIN_ERRORS_RAG_INCLUDE=[src],
+                EXPLAIN_ERRORS_RAG_INDEX_PATH=index_path,
+            ):
+                with patch(
+                    "explain_errors.rag.indexer.get_openai_client",
+                    return_value=embed_client,
+                ):
+                    build_index()
+
+            with VectorStore(index_path) as store:
+                rows = store.query([0.1, 0.2, 0.3], 10)
+
+        self.assertEqual(len(rows), 1)
+        self.assertNotIn("sk-index-secret-value", rows[0]["chunk_text"])
+        self.assertIn("[REDACTED]", rows[0]["chunk_text"])
+
 
 def _raise_json_error():
     return json.loads("{not valid json")
@@ -192,6 +262,35 @@ class RetrieverFrameExtractionTest(SimpleTestCase):
         self.assertTrue(any(name.endswith("test_rag.py") for name in filenames))
         self.assertFalse(any("json" in os.path.basename(name) for name in filenames))
 
+    def test_extract_project_frames_excludes_site_packages_frame(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            site_dir = os.path.join(tmp, "venv-lib", "site-packages")
+            os.makedirs(site_dir)
+            lib_path = os.path.join(site_dir, "thirdparty.py")
+            app_path = os.path.join(tmp, "app.py")
+            with open(lib_path, "w") as f:
+                f.write("def boom():\n    raise ValueError('lib failure')\n")
+            with open(app_path, "w") as f:
+                f.write("def call(fn):\n    return fn()\n")
+
+            namespaces = {}
+            for path in (lib_path, app_path):
+                ns = {}
+                with open(path) as f:
+                    exec(compile(f.read(), path, "exec"), ns)
+                namespaces[path] = ns
+
+            # site-packages sits inside the include dir, so only the
+            # site-packages rule can exclude it.
+            with override_settings(EXPLAIN_ERRORS_RAG_INCLUDE=[tmp]):
+                try:
+                    namespaces[app_path]["call"](namespaces[lib_path]["boom"])
+                except ValueError as exc:
+                    frames = extract_project_frames(exc)
+
+        filenames = [frame.filename for frame in frames]
+        self.assertEqual(filenames, [app_path])
+
     def test_extract_project_frames_empty_without_traceback(self):
         self.assertEqual(extract_project_frames(ValueError("no traceback")), [])
 
@@ -229,6 +328,50 @@ class RetrieverTopKTest(SimpleTestCase):
         self.assertEqual(retrieve_chunks(ValueError("boom")), [])
 
 
+class RetrieverQuerySanitizationTest(SimpleTestCase):
+
+    @requires_sqlite_vec
+    def test_query_text_is_sanitized_before_embedding(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            module_path = os.path.join(tmp, "leaky.py")
+            with open(module_path, "w") as f:
+                f.write(
+                    "def fail():\n"
+                    "    password = 'hunter2-source-secret'; raise ValueError(\n"
+                    "        'token=msg-secret-value')\n"
+                )
+
+            index_path = os.path.join(tmp, "index.db")
+            with VectorStore(index_path) as store:
+                store.create(3)
+                store.add([("leaky.py", 1, 3, "chunk", [1.0, 0.0, 0.0])])
+
+            namespace = {}
+            exec(compile(open(module_path).read(), module_path, "exec"), namespace)
+            try:
+                namespace["fail"]()
+            except ValueError as exc:
+                captured = exc
+
+            embed_client = _mock_embed_client([1.0, 0.0, 0.0])
+            with override_settings(
+                EXPLAIN_ERRORS_RAG_ENABLED=True,
+                EXPLAIN_ERRORS_RAG_INDEX_PATH=index_path,
+                EXPLAIN_ERRORS_RAG_INCLUDE=[tmp],
+            ):
+                with patch(
+                    "explain_errors.rag.retriever.get_openai_client",
+                    return_value=embed_client,
+                ):
+                    retrieve_chunks(captured)
+
+        embed_client.embeddings.create.assert_called_once()
+        (query_text,) = embed_client.embeddings.create.call_args.kwargs["input"]
+        self.assertNotIn("msg-secret-value", query_text)
+        self.assertNotIn("hunter2-source-secret", query_text)
+        self.assertIn("[REDACTED]", query_text)
+
+
 @override_settings(DEBUG=True, OPENAI_API_KEY="test-key")
 class MiddlewareRagIntegrationTest(SimpleTestCase):