django-explain-errors 0.5.0__tar.gz → 0.6.0__tar.gz

{django_explain_errors-0.5.0 → django_explain_errors-0.6.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: django-explain-errors
-Version: 0.5.0
-Summary: Django middleware that captures errors and exceptions, sends them to OpenAI for a detailed explanation, and prints the explanation to stdout when debug mode is enabled. Supports both sync and async views.
+Version: 0.6.0
+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
 Author-email: topunixguy@gmail.com
@@ -9,12 +9,6 @@ License: MIT
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Web Environment
 Classifier: Framework :: Django
-Classifier: Framework :: Django :: 4.2
-Classifier: Framework :: Django :: 5.0
-Classifier: Framework :: Django :: 5.1
-Classifier: Framework :: Django :: 5.2
-Classifier: Framework :: Django :: 6.0
-Classifier: Framework :: Django :: 6.1
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
@@ -86,6 +80,8 @@ Local development only. It requires `DEBUG = True` and is inert otherwise.
 - Explains errors using OpenAI, Anthropic's Claude models, or any other
   OpenAI-compatible endpoint (Ollama, LM Studio, Azure, gateways) via `OPENAI_BASE_URL`
 - Optional codebase-aware explanations (RAG) backed by a local sqlite-vec index (see the RAG section below)
+- Explanations in your language via `EXPLAIN_ERRORS_LANGUAGE`, with exception names,
+  identifiers, and code kept in English
 - Redacts secrets, tokens, and emails from tracebacks before sending
 - Rate limits API calls with a configurable sliding window
 - Works with both sync (WSGI) and async (ASGI) views
@@ -185,7 +181,7 @@ developer is actually investigating.
 | `OPENAI_API_KEY` (env or settings) | Yes, unless `OPENAI_BASE_URL` points at an endpoint that does not authenticate | API key used to authenticate with the configured endpoint. Read first from the environment, then from `settings`. |
 | `DEBUG` | Yes | The middleware is only active when `DEBUG=True`. When `False`, requests pass through untouched. |
 | `OPENAI_MODEL` | No | Model used for explanations. Defaults to `gpt-4o-mini`. |
-| `OPENAI_MAX_TOKENS` | No | Ceiling on tokens generated for the explanation, not a target — the system prompt itself asks for a concise answer. Defaults to `1000`. |
+| `OPENAI_MAX_TOKENS` | No | Ceiling on tokens generated for the explanation, not a target — the system prompt itself asks for a concise answer. Defaults to `1000`; scales up automatically when `EXPLAIN_ERRORS_LANGUAGE` is set (see below), unless you set this explicitly, which always overrides the scaling. |
 | `OPENAI_TIMEOUT` | No | Request timeout in seconds for the OpenAI client. Defaults to `10`. |
 | `OPENAI_MAX_TRACEBACK_CHARS` | No | Traceback is trimmed to its last N characters before being sent. Defaults to `3000`. |
 | `EXPLAIN_ERRORS_PRESERVE_DEBUG_PAGE` | No | When `True` (the default), the middleware prints the explanation to stdout and returns `None`, so exception handling continues normally and Django renders its standard debug page. Set to `False` to instead return a JSON 500 response, which ends exception handling early (see Compatibility above). |
@@ -195,6 +191,7 @@ developer is actually investigating.
 | `EXPLAIN_ERRORS_REDACT_PATTERNS` | No | Extra regex pattern strings (each passed to `re.compile`) applied to the traceback, appended after the built-in secret/token/email patterns. An invalid pattern is skipped with a warning rather than raising. Defaults to `[]`. |
 | `EXPLAIN_ERRORS_REDACT_DISABLE_DEFAULTS` | No | When `True`, skips the built-in secret/token/email redaction patterns entirely and redacts only what `EXPLAIN_ERRORS_REDACT_PATTERNS` specifies. Turning this on removes the default protection against leaking secrets and PII in tracebacks. Defaults to `False`. |
 | `EXPLAIN_ERRORS_REDACT_REPLACEMENT` | No | Replacement string substituted for anything matched by the redaction patterns. Defaults to `"[REDACTED]"`. |
+| `EXPLAIN_ERRORS_LANGUAGE` | No | Language the explanation prose is written in, as a plain name or code (for example `"Spanish"` or `"es"`). Defaults to `None`, meaning English. Exception names, identifiers, code, file paths, and tracebacks always stay in English regardless of this setting. |
 
 ## Using local models (Ollama)
 
@@ -250,6 +247,37 @@ and rejected, so a missing `OPENAI_API_KEY` shows up as an opaque `401 Unauthori
 than a clear configuration error. If you see a 401 with `OPENAI_BASE_URL` pointed at a remote
 provider, check that `OPENAI_API_KEY` — not a provider-specific variable — is actually set.
 
+## Explanation language
+
+By default, explanations are written in English. Set `EXPLAIN_ERRORS_LANGUAGE` to
+read them in another language instead:
+
+```python
+EXPLAIN_ERRORS_LANGUAGE = "Spanish"  # or the code form, "es"
+```
+
+This is independent of Django's own `LANGUAGE_CODE`, which controls the language your
+site serves to its users, not the language you read explanations in. Regardless of
+`EXPLAIN_ERRORS_LANGUAGE`, exception type names, Django and Python identifiers, code,
+file paths, and tracebacks are always kept in English, so they stay greppable and
+matchable against documentation and search results. Only the explanatory prose is
+translated.
+
+**Known limitation:** small local models behind `OPENAI_BASE_URL` (see "Using local
+models" above) tend to degrade sharply outside English. Output quality with
+`EXPLAIN_ERRORS_LANGUAGE` set does not transfer uniformly across providers — it is
+generally solid against OpenAI and Anthropic's APIs, but a small local model that
+writes fluent English explanations may produce broken or mixed-language output once
+asked to switch languages.
+
+When a language is configured, the token ceiling (`OPENAI_MAX_TOKENS`) is scaled up
+automatically so explanations in languages that tokenize less efficiently than English
+aren't cut off mid-sentence. This scaling is deliberately generous — billing follows
+tokens actually generated, so unused headroom costs nothing — rather than precise: the
+underlying tokens-per-word figures are estimates, not direct measurements, and the
+default model (`gpt-4o-mini`) uses the `o200k_base` tokenizer, which handles non-Latin
+scripts considerably better than the `cl100k_base`-era ratios these estimates lean on.
+
 ## Codebase-aware explanations (RAG)
 
 By default, explanations are generated from the traceback alone. With the

django_explain_errors-0.5.0/django_explain_errors.egg-info/PKG-INFO → django_explain_errors-0.6.0/README.md

@@ -1,53 +1,3 @@
-Metadata-Version: 2.4
-Name: django-explain-errors
-Version: 0.5.0
-Summary: Django middleware that captures errors and exceptions, sends them to OpenAI for a detailed explanation, and prints the explanation to stdout when debug mode is enabled. Supports both sync and async views.
-Home-page: https://github.com/topunix/django-explain-errors
-Author: topunix
-Author-email: topunixguy@gmail.com
-License: MIT
-Classifier: Development Status :: 4 - Beta
-Classifier: Environment :: Web Environment
-Classifier: Framework :: Django
-Classifier: Framework :: Django :: 4.2
-Classifier: Framework :: Django :: 5.0
-Classifier: Framework :: Django :: 5.1
-Classifier: Framework :: Django :: 5.2
-Classifier: Framework :: Django :: 6.0
-Classifier: Framework :: Django :: 6.1
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python
-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 :: Internet :: WWW/HTTP
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: Django>=4.2
-Requires-Dist: openai<4.0,>=1.0
-Requires-Dist: python-dotenv>=1.0
-Requires-Dist: asgiref>=3.6
-Provides-Extra: rag
-Requires-Dist: sqlite-vec>=0.1.0; extra == "rag"
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license
-Dynamic: license-file
-Dynamic: provides-extra
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
-
 # Django Explain Errors Middleware
 
 This Django middleware captures unhandled errors and exceptions, sends them
@@ -86,6 +36,8 @@ Local development only. It requires `DEBUG = True` and is inert otherwise.
 - Explains errors using OpenAI, Anthropic's Claude models, or any other
   OpenAI-compatible endpoint (Ollama, LM Studio, Azure, gateways) via `OPENAI_BASE_URL`
 - Optional codebase-aware explanations (RAG) backed by a local sqlite-vec index (see the RAG section below)
+- Explanations in your language via `EXPLAIN_ERRORS_LANGUAGE`, with exception names,
+  identifiers, and code kept in English
 - Redacts secrets, tokens, and emails from tracebacks before sending
 - Rate limits API calls with a configurable sliding window
 - Works with both sync (WSGI) and async (ASGI) views
@@ -185,7 +137,7 @@ developer is actually investigating.
 | `OPENAI_API_KEY` (env or settings) | Yes, unless `OPENAI_BASE_URL` points at an endpoint that does not authenticate | API key used to authenticate with the configured endpoint. Read first from the environment, then from `settings`. |
 | `DEBUG` | Yes | The middleware is only active when `DEBUG=True`. When `False`, requests pass through untouched. |
 | `OPENAI_MODEL` | No | Model used for explanations. Defaults to `gpt-4o-mini`. |
-| `OPENAI_MAX_TOKENS` | No | Ceiling on tokens generated for the explanation, not a target — the system prompt itself asks for a concise answer. Defaults to `1000`. |
+| `OPENAI_MAX_TOKENS` | No | Ceiling on tokens generated for the explanation, not a target — the system prompt itself asks for a concise answer. Defaults to `1000`; scales up automatically when `EXPLAIN_ERRORS_LANGUAGE` is set (see below), unless you set this explicitly, which always overrides the scaling. |
 | `OPENAI_TIMEOUT` | No | Request timeout in seconds for the OpenAI client. Defaults to `10`. |
 | `OPENAI_MAX_TRACEBACK_CHARS` | No | Traceback is trimmed to its last N characters before being sent. Defaults to `3000`. |
 | `EXPLAIN_ERRORS_PRESERVE_DEBUG_PAGE` | No | When `True` (the default), the middleware prints the explanation to stdout and returns `None`, so exception handling continues normally and Django renders its standard debug page. Set to `False` to instead return a JSON 500 response, which ends exception handling early (see Compatibility above). |
@@ -195,6 +147,7 @@ developer is actually investigating.
 | `EXPLAIN_ERRORS_REDACT_PATTERNS` | No | Extra regex pattern strings (each passed to `re.compile`) applied to the traceback, appended after the built-in secret/token/email patterns. An invalid pattern is skipped with a warning rather than raising. Defaults to `[]`. |
 | `EXPLAIN_ERRORS_REDACT_DISABLE_DEFAULTS` | No | When `True`, skips the built-in secret/token/email redaction patterns entirely and redacts only what `EXPLAIN_ERRORS_REDACT_PATTERNS` specifies. Turning this on removes the default protection against leaking secrets and PII in tracebacks. Defaults to `False`. |
 | `EXPLAIN_ERRORS_REDACT_REPLACEMENT` | No | Replacement string substituted for anything matched by the redaction patterns. Defaults to `"[REDACTED]"`. |
+| `EXPLAIN_ERRORS_LANGUAGE` | No | Language the explanation prose is written in, as a plain name or code (for example `"Spanish"` or `"es"`). Defaults to `None`, meaning English. Exception names, identifiers, code, file paths, and tracebacks always stay in English regardless of this setting. |
 
 ## Using local models (Ollama)
 
@@ -250,6 +203,37 @@ and rejected, so a missing `OPENAI_API_KEY` shows up as an opaque `401 Unauthori
 than a clear configuration error. If you see a 401 with `OPENAI_BASE_URL` pointed at a remote
 provider, check that `OPENAI_API_KEY` — not a provider-specific variable — is actually set.
 
+## Explanation language
+
+By default, explanations are written in English. Set `EXPLAIN_ERRORS_LANGUAGE` to
+read them in another language instead:
+
+```python
+EXPLAIN_ERRORS_LANGUAGE = "Spanish"  # or the code form, "es"
+```
+
+This is independent of Django's own `LANGUAGE_CODE`, which controls the language your
+site serves to its users, not the language you read explanations in. Regardless of
+`EXPLAIN_ERRORS_LANGUAGE`, exception type names, Django and Python identifiers, code,
+file paths, and tracebacks are always kept in English, so they stay greppable and
+matchable against documentation and search results. Only the explanatory prose is
+translated.
+
+**Known limitation:** small local models behind `OPENAI_BASE_URL` (see "Using local
+models" above) tend to degrade sharply outside English. Output quality with
+`EXPLAIN_ERRORS_LANGUAGE` set does not transfer uniformly across providers — it is
+generally solid against OpenAI and Anthropic's APIs, but a small local model that
+writes fluent English explanations may produce broken or mixed-language output once
+asked to switch languages.
+
+When a language is configured, the token ceiling (`OPENAI_MAX_TOKENS`) is scaled up
+automatically so explanations in languages that tokenize less efficiently than English
+aren't cut off mid-sentence. This scaling is deliberately generous — billing follows
+tokens actually generated, so unused headroom costs nothing — rather than precise: the
+underlying tokens-per-word figures are estimates, not direct measurements, and the
+default model (`gpt-4o-mini`) uses the `o200k_base` tokenizer, which handles non-Latin
+scripts considerably better than the `cl100k_base`-era ratios these estimates lean on.
+
 ## Codebase-aware explanations (RAG)
 
 By default, explanations are generated from the traceback alone. With the

django_explain_errors-0.5.0/README.md → django_explain_errors-0.6.0/django_explain_errors.egg-info/PKG-INFO

@@ -1,3 +1,47 @@
+Metadata-Version: 2.4
+Name: django-explain-errors
+Version: 0.6.0
+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
+Author-email: topunixguy@gmail.com
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+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 :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django>=4.2
+Requires-Dist: openai<4.0,>=1.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: asgiref>=3.6
+Provides-Extra: rag
+Requires-Dist: sqlite-vec>=0.1.0; extra == "rag"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
 # Django Explain Errors Middleware
 
 This Django middleware captures unhandled errors and exceptions, sends them
@@ -36,6 +80,8 @@ Local development only. It requires `DEBUG = True` and is inert otherwise.
 - Explains errors using OpenAI, Anthropic's Claude models, or any other
   OpenAI-compatible endpoint (Ollama, LM Studio, Azure, gateways) via `OPENAI_BASE_URL`
 - Optional codebase-aware explanations (RAG) backed by a local sqlite-vec index (see the RAG section below)
+- Explanations in your language via `EXPLAIN_ERRORS_LANGUAGE`, with exception names,
+  identifiers, and code kept in English
 - Redacts secrets, tokens, and emails from tracebacks before sending
 - Rate limits API calls with a configurable sliding window
 - Works with both sync (WSGI) and async (ASGI) views
@@ -135,7 +181,7 @@ developer is actually investigating.
 | `OPENAI_API_KEY` (env or settings) | Yes, unless `OPENAI_BASE_URL` points at an endpoint that does not authenticate | API key used to authenticate with the configured endpoint. Read first from the environment, then from `settings`. |
 | `DEBUG` | Yes | The middleware is only active when `DEBUG=True`. When `False`, requests pass through untouched. |
 | `OPENAI_MODEL` | No | Model used for explanations. Defaults to `gpt-4o-mini`. |
-| `OPENAI_MAX_TOKENS` | No | Ceiling on tokens generated for the explanation, not a target — the system prompt itself asks for a concise answer. Defaults to `1000`. |
+| `OPENAI_MAX_TOKENS` | No | Ceiling on tokens generated for the explanation, not a target — the system prompt itself asks for a concise answer. Defaults to `1000`; scales up automatically when `EXPLAIN_ERRORS_LANGUAGE` is set (see below), unless you set this explicitly, which always overrides the scaling. |
 | `OPENAI_TIMEOUT` | No | Request timeout in seconds for the OpenAI client. Defaults to `10`. |
 | `OPENAI_MAX_TRACEBACK_CHARS` | No | Traceback is trimmed to its last N characters before being sent. Defaults to `3000`. |
 | `EXPLAIN_ERRORS_PRESERVE_DEBUG_PAGE` | No | When `True` (the default), the middleware prints the explanation to stdout and returns `None`, so exception handling continues normally and Django renders its standard debug page. Set to `False` to instead return a JSON 500 response, which ends exception handling early (see Compatibility above). |
@@ -145,6 +191,7 @@ developer is actually investigating.
 | `EXPLAIN_ERRORS_REDACT_PATTERNS` | No | Extra regex pattern strings (each passed to `re.compile`) applied to the traceback, appended after the built-in secret/token/email patterns. An invalid pattern is skipped with a warning rather than raising. Defaults to `[]`. |
 | `EXPLAIN_ERRORS_REDACT_DISABLE_DEFAULTS` | No | When `True`, skips the built-in secret/token/email redaction patterns entirely and redacts only what `EXPLAIN_ERRORS_REDACT_PATTERNS` specifies. Turning this on removes the default protection against leaking secrets and PII in tracebacks. Defaults to `False`. |
 | `EXPLAIN_ERRORS_REDACT_REPLACEMENT` | No | Replacement string substituted for anything matched by the redaction patterns. Defaults to `"[REDACTED]"`. |
+| `EXPLAIN_ERRORS_LANGUAGE` | No | Language the explanation prose is written in, as a plain name or code (for example `"Spanish"` or `"es"`). Defaults to `None`, meaning English. Exception names, identifiers, code, file paths, and tracebacks always stay in English regardless of this setting. |
 
 ## Using local models (Ollama)
 
@@ -200,6 +247,37 @@ and rejected, so a missing `OPENAI_API_KEY` shows up as an opaque `401 Unauthori
 than a clear configuration error. If you see a 401 with `OPENAI_BASE_URL` pointed at a remote
 provider, check that `OPENAI_API_KEY` — not a provider-specific variable — is actually set.
 
+## Explanation language
+
+By default, explanations are written in English. Set `EXPLAIN_ERRORS_LANGUAGE` to
+read them in another language instead:
+
+```python
+EXPLAIN_ERRORS_LANGUAGE = "Spanish"  # or the code form, "es"
+```
+
+This is independent of Django's own `LANGUAGE_CODE`, which controls the language your
+site serves to its users, not the language you read explanations in. Regardless of
+`EXPLAIN_ERRORS_LANGUAGE`, exception type names, Django and Python identifiers, code,
+file paths, and tracebacks are always kept in English, so they stay greppable and
+matchable against documentation and search results. Only the explanatory prose is
+translated.
+
+**Known limitation:** small local models behind `OPENAI_BASE_URL` (see "Using local
+models" above) tend to degrade sharply outside English. Output quality with
+`EXPLAIN_ERRORS_LANGUAGE` set does not transfer uniformly across providers — it is
+generally solid against OpenAI and Anthropic's APIs, but a small local model that
+writes fluent English explanations may produce broken or mixed-language output once
+asked to switch languages.
+
+When a language is configured, the token ceiling (`OPENAI_MAX_TOKENS`) is scaled up
+automatically so explanations in languages that tokenize less efficiently than English
+aren't cut off mid-sentence. This scaling is deliberately generous — billing follows
+tokens actually generated, so unused headroom costs nothing — rather than precise: the
+underlying tokens-per-word figures are estimates, not direct measurements, and the
+default model (`gpt-4o-mini`) uses the `o200k_base` tokenizer, which handles non-Latin
+scripts considerably better than the `cl100k_base`-era ratios these estimates lean on.
+
 ## Codebase-aware explanations (RAG)
 
 By default, explanations are generated from the traceback alone. With the

{django_explain_errors-0.5.0 → django_explain_errors-0.6.0}/django_explain_errors.egg-info/SOURCES.txt

@@ -21,6 +21,7 @@ explain_errors/rag/retriever.py
 explain_errors/rag/store.py
 tests/test_build_error_index.py
 tests/test_client.py
+tests/test_language.py
 tests/test_middleware.py
 tests/test_rag.py
 tests/test_sanitize.py

{django_explain_errors-0.5.0 → django_explain_errors-0.6.0}/explain_errors/middleware.py

@@ -25,6 +25,30 @@ SYSTEM_PROMPT = (
     "why, and how to fix it. Be concrete and skip preamble."
 )
 
+# Appended to SYSTEM_PROMPT only when EXPLAIN_ERRORS_LANGUAGE is set, so the
+# default (unset) prompt stays byte-identical to what ships today.
+LANGUAGE_CLAUSE_TEMPLATE = (
+    " Answer in {language}. Keep exception type names, Django and Python "
+    "identifiers, attribute names, settings names, code, file paths, and "
+    "tracebacks in English."
+)
+
+# Some languages tokenize far worse than English for equivalent content, so
+# the fixed EXPLANATION_WORD_BUDGET can consume proportionally more of
+# DEFAULT_MAX_TOKENS. The ceiling is billed on tokens generated, not on the
+# cap itself, so unused headroom is free — there is no reason to ration it
+# per language, and a per-language table would silently truncate every
+# language it didn't anticipate. Apply the worst-case multiplier from the
+# languages estimated (see the report in docs/tasks/explain-errors-language.md)
+# to any configured language, known or not.
+LANGUAGE_MAX_TOKENS_MULTIPLIER = 3.0
+
+
+def _default_max_tokens_for_language(language):
+    if not language:
+        return DEFAULT_MAX_TOKENS
+    return int(DEFAULT_MAX_TOKENS * LANGUAGE_MAX_TOKENS_MULTIPLIER)
+
 
 class ExplainErrorsMiddleware:
     """
@@ -49,7 +73,21 @@ class ExplainErrorsMiddleware:
 
             # Configurable via settings, with sensible defaults.
             self.model = getattr(settings, "OPENAI_MODEL", "gpt-4o-mini")
-            self.max_tokens = getattr(settings, "OPENAI_MAX_TOKENS", DEFAULT_MAX_TOKENS)
+            self.language = getattr(settings, "EXPLAIN_ERRORS_LANGUAGE", None)
+
+            configured_max_tokens = getattr(settings, "OPENAI_MAX_TOKENS", None)
+            if configured_max_tokens is not None:
+                self.max_tokens = configured_max_tokens
+            else:
+                self.max_tokens = _default_max_tokens_for_language(self.language)
+
+            if self.language:
+                self.system_prompt = SYSTEM_PROMPT + LANGUAGE_CLAUSE_TEMPLATE.format(
+                    language=self.language
+                )
+            else:
+                self.system_prompt = SYSTEM_PROMPT
+
             timeout = getattr(settings, "OPENAI_TIMEOUT", 10)
 
             self.openai_client = get_openai_client(timeout=timeout)
@@ -128,7 +166,7 @@ class ExplainErrorsMiddleware:
                 response = self.openai_client.chat.completions.create(
                     model=self.model,
                     messages=[
-                        {"role": "system", "content": SYSTEM_PROMPT},
+                        {"role": "system", "content": self.system_prompt},
                         {"role": "user", "content": prompt},
                     ],
                     max_tokens=self.max_tokens,

{django_explain_errors-0.5.0 → django_explain_errors-0.6.0}/setup.py

@@ -10,9 +10,9 @@ with open('README.md', encoding='utf-8') as f:
 
 setup(
     name='django-explain-errors',
-    version='0.5.0',
+    version='0.6.0',
     packages=find_packages(exclude=['tests', 'tests.*']),
-    description='Django middleware that captures errors and exceptions, sends them to OpenAI for a detailed explanation, and prints the explanation to stdout when debug mode is enabled. Supports both sync and async views.',
+    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',
     long_description=long_description,
     python_requires='>=3.9',
@@ -35,12 +35,6 @@ setup(
         'Development Status :: 4 - Beta',
         'Environment :: Web Environment',
         'Framework :: Django',
-        'Framework :: Django :: 4.2',
-        'Framework :: Django :: 5.0',
-        'Framework :: Django :: 5.1',
-        'Framework :: Django :: 5.2',
-        'Framework :: Django :: 6.0',
-        'Framework :: Django :: 6.1',
         'Intended Audience :: Developers',
         'License :: OSI Approved :: MIT License',
         'Operating System :: OS Independent',

django_explain_errors-0.6.0/tests/test_language.py

@@ -0,0 +1,158 @@
+from unittest.mock import MagicMock, patch
+
+from django.test import RequestFactory, SimpleTestCase, override_settings
+
+from explain_errors.middleware import (
+    DEFAULT_MAX_TOKENS,
+    EXPLANATION_WORD_BUDGET,
+    LANGUAGE_MAX_TOKENS_MULTIPLIER,
+    SYSTEM_PROMPT,
+    ExplainErrorsMiddleware,
+)
+
+
+def _mock_openai():
+    patcher = patch("openai.OpenAI")
+    mock_cls = patcher.start()
+    client = MagicMock()
+    client.chat.completions.create.return_value = MagicMock(
+        choices=[
+            MagicMock(message=MagicMock(content="Mocked explanation."), finish_reason="stop")
+        ]
+    )
+    mock_cls.return_value = client
+    return patcher, client
+
+
+@override_settings(DEBUG=True, OPENAI_API_KEY="test-key")
+class LanguageUnsetTest(SimpleTestCase):
+    """Case 1: no EXPLAIN_ERRORS_LANGUAGE must not change existing output."""
+
+    def setUp(self):
+        self.factory = RequestFactory()
+        self.patcher, self.client = _mock_openai()
+        self.addCleanup(self.patcher.stop)
+
+    def test_system_prompt_byte_identical_when_language_unset(self):
+        mw = ExplainErrorsMiddleware(lambda r: None)
+        mw.process_exception(self.factory.get("/"), Exception("x"))
+
+        messages = self.client.chat.completions.create.call_args.kwargs["messages"]
+        self.assertEqual(messages[0]["content"], SYSTEM_PROMPT)
+
+    def test_user_prompt_byte_identical_when_language_unset(self):
+        # Invariant 10: the language clause belongs in the system message
+        # only. Confirm the user-message prompt is unaffected.
+        mw = ExplainErrorsMiddleware(lambda r: None)
+        request = self.factory.get("/")
+
+        try:
+            raise ValueError("boom")
+        except ValueError as exc:
+            mw.process_exception(request, exc)
+
+        messages = self.client.chat.completions.create.call_args.kwargs["messages"]
+        # Re-derive what the traceback-only prompt should look like: same
+        # approach as tests/test_rag.py's byte-identical check.
+        expected_prefix = "Explain the following Django error in simple terms:\n\n"
+        self.assertTrue(messages[1]["content"].startswith(expected_prefix))
+        self.assertIn("ValueError", messages[1]["content"])
+        self.assertIn("boom", messages[1]["content"])
+
+
+@override_settings(
+    DEBUG=True, OPENAI_API_KEY="test-key", EXPLAIN_ERRORS_LANGUAGE="Spanish"
+)
+class LanguageConfiguredTest(SimpleTestCase):
+    """Cases 2 & 3: the language clause and identifier-preservation
+    instruction appear in the system prompt when configured."""
+
+    def setUp(self):
+        self.factory = RequestFactory()
+        self.patcher, self.client = _mock_openai()
+        self.addCleanup(self.patcher.stop)
+
+    def test_language_clause_appears_in_system_prompt(self):
+        mw = ExplainErrorsMiddleware(lambda r: None)
+        mw.process_exception(self.factory.get("/"), Exception("x"))
+
+        messages = self.client.chat.completions.create.call_args.kwargs["messages"]
+        system_prompt = messages[0]["content"]
+        self.assertIn("Spanish", system_prompt)
+        self.assertTrue(system_prompt.startswith(SYSTEM_PROMPT))
+
+    def test_identifier_preservation_instruction_appears(self):
+        mw = ExplainErrorsMiddleware(lambda r: None)
+        mw.process_exception(self.factory.get("/"), Exception("x"))
+
+        system_prompt = self.client.chat.completions.create.call_args.kwargs["messages"][
+            0
+        ]["content"]
+        self.assertIn("Django and Python", system_prompt)
+        self.assertIn("English", system_prompt)
+
+    def test_user_prompt_still_byte_identical_when_language_configured(self):
+        # Invariant 10: configuring a language must not touch the
+        # traceback-only user-message prompt.
+        mw = ExplainErrorsMiddleware(lambda r: None)
+        request = self.factory.get("/")
+
+        with patch(
+            "explain_errors.middleware.sanitize_traceback",
+            side_effect=lambda tb: tb,
+        ):
+            try:
+                raise ValueError("boom")
+            except ValueError as exc:
+                mw.process_exception(request, exc)
+
+        messages = self.client.chat.completions.create.call_args.kwargs["messages"]
+        self.assertTrue(
+            messages[1]["content"].startswith(
+                "Explain the following Django error in simple terms:\n\n"
+            )
+        )
+        self.assertNotIn("Spanish", messages[1]["content"])
+
+
+@override_settings(DEBUG=True, OPENAI_API_KEY="test-key")
+class MaxTokensLanguageScalingTest(SimpleTestCase):
+    """Case 4: the scaled ceiling covers the word budget, and applies
+    uniformly to any configured language rather than only ones anticipated
+    in advance — that's the no-cliff property a per-language table would
+    have broken."""
+
+    def setUp(self):
+        self.patcher, self.client = _mock_openai()
+        self.addCleanup(self.patcher.stop)
+
+    def test_default_ceiling_used_when_language_unset(self):
+        mw = ExplainErrorsMiddleware(lambda r: None)
+        self.assertEqual(mw.max_tokens, DEFAULT_MAX_TOKENS)
+
+    def test_scaled_ceiling_covers_word_budget(self):
+        scaled = int(DEFAULT_MAX_TOKENS * LANGUAGE_MAX_TOKENS_MULTIPLIER)
+        self.assertGreaterEqual(scaled, EXPLANATION_WORD_BUDGET * 4)
+
+    def test_scaled_ceiling_applies_for_an_estimated_language(self):
+        with override_settings(EXPLAIN_ERRORS_LANGUAGE="Japanese"):
+            mw = ExplainErrorsMiddleware(lambda r: None)
+            self.assertEqual(
+                mw.max_tokens, int(DEFAULT_MAX_TOKENS * LANGUAGE_MAX_TOKENS_MULTIPLIER)
+            )
+
+    def test_scaled_ceiling_applies_for_a_language_not_in_the_estimate(self):
+        # No per-language table to fall through: Chinese was never
+        # estimated, and still gets the same scaled ceiling as Japanese.
+        with override_settings(EXPLAIN_ERRORS_LANGUAGE="Chinese"):
+            mw = ExplainErrorsMiddleware(lambda r: None)
+            self.assertEqual(
+                mw.max_tokens, int(DEFAULT_MAX_TOKENS * LANGUAGE_MAX_TOKENS_MULTIPLIER)
+            )
+
+    def test_explicit_openai_max_tokens_overrides_language_scaling(self):
+        with override_settings(
+            EXPLAIN_ERRORS_LANGUAGE="Hindi", OPENAI_MAX_TOKENS=42
+        ):
+            mw = ExplainErrorsMiddleware(lambda r: None)
+            self.assertEqual(mw.max_tokens, 42)