django-explain-errors 0.11.0__tar.gz → 0.11.1__tar.gz

{django_explain_errors-0.11.0/django_explain_errors.egg-info → django_explain_errors-0.11.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-explain-errors
-Version: 0.11.0
+Version: 0.11.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
@@ -272,6 +272,10 @@ catches the exception internally, so it never becomes an unhandled exception, bu
 than relying on `got_request_exception`. That event is unrelated to whatever error the
 developer is actually investigating.
 
+OpenAI reasoning models are supported. They reject `max_tokens`, so when the API rejects it
+the middleware retries once with `max_completion_tokens` (same value, `OPENAI_MAX_TOKENS`)
+and keeps using that for later calls. Other providers keep receiving `max_tokens`.
+
 ## Configuration
 
 | Setting / variable | Required | Description |

{django_explain_errors-0.11.0 → django_explain_errors-0.11.1}/README.md

@@ -220,6 +220,10 @@ catches the exception internally, so it never becomes an unhandled exception, bu
 than relying on `got_request_exception`. That event is unrelated to whatever error the
 developer is actually investigating.
 
+OpenAI reasoning models are supported. They reject `max_tokens`, so when the API rejects it
+the middleware retries once with `max_completion_tokens` (same value, `OPENAI_MAX_TOKENS`)
+and keeps using that for later calls. Other providers keep receiving `max_tokens`.
+
 ## Configuration
 
 | Setting / variable | Required | Description |

{django_explain_errors-0.11.0 → django_explain_errors-0.11.1/django_explain_errors.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-explain-errors
-Version: 0.11.0
+Version: 0.11.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
@@ -272,6 +272,10 @@ catches the exception internally, so it never becomes an unhandled exception, bu
 than relying on `got_request_exception`. That event is unrelated to whatever error the
 developer is actually investigating.
 
+OpenAI reasoning models are supported. They reject `max_tokens`, so when the API rejects it
+the middleware retries once with `max_completion_tokens` (same value, `OPENAI_MAX_TOKENS`)
+and keeps using that for later calls. Other providers keep receiving `max_tokens`.
+
 ## Configuration
 
 | Setting / variable | Required | Description |

{django_explain_errors-0.11.0 → django_explain_errors-0.11.1}/django_explain_errors.egg-info/SOURCES.txt

@@ -38,5 +38,6 @@ tests/test_rag.py
 tests/test_sanitize.py
 tests/test_signals.py
 tests/test_throttle.py
+tests/test_token_param_fallback.py
 tests/test_tracebacks.py
 tests/test_truncation.py

{django_explain_errors-0.11.0 → django_explain_errors-0.11.1}/explain_errors/middleware.py

@@ -3,6 +3,7 @@ import logging
 import threading
 from collections import OrderedDict
 
+import openai
 from django.conf import settings
 from django.http import JsonResponse
 from asgiref.sync import markcoroutinefunction, sync_to_async
@@ -81,6 +82,9 @@ class ExplainErrorsMiddleware:
             # above this one runs in sync mode and receives a coroutine.
             markcoroutinefunction(self)
         self.openai_client = None
+        # Output-cap parameter sent to the model. Reasoning models reject
+        # max_tokens; _create_completion switches this once, per instance.
+        self._token_param = "max_tokens"
         self.throttle = None
         self.dedup_enabled = False
         self._explanation_cache = OrderedDict()
@@ -251,6 +255,39 @@ class ExplainErrorsMiddleware:
 
         return prompt
 
+    def _create_completion(self, messages):
+        """Send the chat completion, adapting to the model's output-cap parameter.
+
+        Sends max_tokens by default. If the API rejects exactly that parameter
+        (OpenAI reasoning models require max_completion_tokens), retries once
+        with max_completion_tokens and remembers the choice on this instance.
+        Any other error, or a failed retry, propagates to the caller.
+        """
+
+        def create(token_param):
+            return self.openai_client.chat.completions.create(
+                model=self.model,
+                messages=messages,
+                **{token_param: self.max_tokens},
+            )
+
+        try:
+            return create(self._token_param)
+        except openai.BadRequestError as exc:
+            if self._token_param != "max_tokens" or not (
+                getattr(exc, "param", None) == "max_tokens"
+                and getattr(exc, "code", None) == "unsupported_parameter"
+            ):
+                raise
+        response = create("max_completion_tokens")
+        self._token_param = "max_completion_tokens"
+        logger.info(
+            "explain_errors: model %s rejected max_tokens; using "
+            "max_completion_tokens instead",
+            self.model,
+        )
+        return response
+
     def _generate_explanation(self, prompt):
         """Call the model and return the explanation text, or None on failure.
 
@@ -260,13 +297,11 @@ class ExplainErrorsMiddleware:
         explanation = None
         try:
             # Call model API
-            response = self.openai_client.chat.completions.create(
-                model=self.model,
-                messages=[
+            response = self._create_completion(
+                [
                     {"role": "system", "content": self.system_prompt},
                     {"role": "user", "content": prompt},
-                ],
-                max_tokens=self.max_tokens,
+                ]
             )
             explanation = response.choices[0].message.content
             usage = getattr(response, "usage", None)
@@ -276,11 +311,23 @@ class ExplainErrorsMiddleware:
                 getattr(usage, "completion_tokens", None),
             )
             if response.choices[0].finish_reason == "length":
+                hint = ""
+                if self._token_param == "max_completion_tokens":
+                    hint = (
+                        " (reasoning tokens count against this limit; raise it "
+                        "if explanations come back short or empty)"
+                    )
                 logger.warning(
-                    "explain_errors: explanation truncated by OPENAI_MAX_TOKENS=%s",
+                    "explain_errors: explanation truncated by OPENAI_MAX_TOKENS=%s%s",
                     self.max_tokens,
+                    hint,
                 )
 
+            if not explanation or not explanation.strip():
+                # Reasoning can consume the whole budget and leave no text.
+                explanation = None
+                raise ValueError("the model returned an empty response")
+
             if getattr(settings, "EXPLAIN_ERRORS_PRINT_STDOUT", True):
                 print(f"Error explanation ({self.model}):\n", explanation)
         except Exception as e:

{django_explain_errors-0.11.0 → django_explain_errors-0.11.1}/setup.py

@@ -10,7 +10,7 @@ with open('README.md', encoding='utf-8') as f:
 
 setup(
     name='django-explain-errors',
-    version='0.11.0',
+    version='0.11.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.11.0 → django_explain_errors-0.11.1}/tests/test_eval_judge.py

@@ -391,3 +391,161 @@ class CompareClaimsGuardTest(unittest.TestCase):
         )
 
         self.assertFalse(result["judge_failure"])
+
+
+def _openai_error(cls, status=None):
+    """An instance of the openai exception class without constructing its
+    httpx request/response (which httpx package openai imports varies by
+    openai version).
+    """
+    exc = Exception.__new__(cls)
+    exc.args = ("boom",)
+    if status is not None:
+        exc.status_code = status
+    return exc
+
+
+def _flaky_client(errors, then=VALID_RESPONSE):
+    """Raises each of `errors` in turn, then returns `then`."""
+    client = MagicMock()
+    ok = MagicMock(
+        choices=[MagicMock(message=MagicMock(content=then))],
+        usage=MagicMock(prompt_tokens=7, completion_tokens=3),
+    )
+    client.chat.completions.create.side_effect = list(errors) + [ok]
+    return client
+
+
+class CompareRetryTest(unittest.TestCase):
+
+    def test_pre_drawn_position_is_used_and_rng_untouched(self):
+        fixture = _make_fixture()
+        client = _client_returning(VALID_RESPONSE)
+
+        class ExplodingRng:
+            def random(self):
+                raise AssertionError("rng must not be drawn when rag_on_is_a is given")
+
+        result = compare(
+            client, "m", "tb", fixture, "src", "off", "on",
+            rng=ExplodingRng(), rag_on_is_a=False,
+        )
+
+        self.assertFalse(result["rag_on_is_a"])
+
+    def test_rate_limit_is_retried_and_counted(self):
+        import openai
+
+        fixture = _make_fixture()
+        errors = [_openai_error(openai.RateLimitError, 429)] * 2
+        client = _flaky_client(errors)
+        sleeps = []
+
+        result = compare(
+            client, "m", "tb", fixture, "src", "off", "on",
+            rng=_FixedRng(0.1), sleep=sleeps.append,
+        )
+
+        self.assertFalse(result["judge_failure"])
+        self.assertEqual(result["retries"], 2)
+        self.assertEqual(len(sleeps), 2)
+        self.assertEqual(client.chat.completions.create.call_count, 3)
+        self.assertEqual(result["prompt_tokens"], 7)
+
+    def test_backoff_grows_and_is_capped(self):
+        import openai
+
+        from evals import judge
+
+        fixture = _make_fixture()
+        client = _flaky_client([_openai_error(openai.InternalServerError, 503)] * 4)
+        ceilings = []
+
+        class RecordingJitter:
+            def uniform(self, low, high):
+                ceilings.append(high)
+                return high
+
+        original = judge._jitter_rng
+        judge._jitter_rng = RecordingJitter()
+        self.addCleanup(setattr, judge, "_jitter_rng", original)
+
+        compare(
+            client, "m", "tb", fixture, "src", "off", "on",
+            rng=_FixedRng(0.1), max_attempts=5, sleep=lambda s: None,
+        )
+
+        self.assertEqual(ceilings, [1.0, 2.0, 4.0, 8.0])
+
+    def test_timeout_and_connection_errors_are_retried(self):
+        import openai
+
+        fixture = _make_fixture()
+        client = _flaky_client(
+            [_openai_error(openai.APITimeoutError), _openai_error(openai.APIConnectionError)]
+        )
+
+        result = compare(
+            client, "m", "tb", fixture, "src", "off", "on",
+            rng=_FixedRng(0.1), sleep=lambda s: None,
+        )
+
+        self.assertFalse(result["judge_failure"])
+        self.assertEqual(result["retries"], 2)
+
+    def test_exhausted_retries_is_a_judge_failure_with_retries_recorded(self):
+        import openai
+
+        fixture = _make_fixture()
+        client = MagicMock()
+        client.chat.completions.create.side_effect = _openai_error(openai.RateLimitError, 429)
+
+        result = compare(
+            client, "m", "tb", fixture, "src", "off", "on",
+            rng=_FixedRng(0.1), max_attempts=3, sleep=lambda s: None,
+        )
+
+        self.assertTrue(result["judge_failure"])
+        self.assertEqual(result["retries"], 2)
+        self.assertEqual(client.chat.completions.create.call_count, 3)
+        self.assertIn("boom", result["error"])
+        self.assertIn("rag_on_is_a", result)
+
+    def test_non_transient_error_is_not_retried(self):
+        import openai
+
+        fixture = _make_fixture()
+        client = MagicMock()
+        client.chat.completions.create.side_effect = _openai_error(
+            openai.AuthenticationError, 401
+        )
+
+        result = compare(
+            client, "m", "tb", fixture, "src", "off", "on",
+            rng=_FixedRng(0.1), sleep=lambda s: self.fail("must not sleep"),
+        )
+
+        self.assertTrue(result["judge_failure"])
+        self.assertEqual(result["retries"], 0)
+        self.assertEqual(client.chat.completions.create.call_count, 1)
+
+    def test_malformed_response_is_not_retried(self):
+        fixture = _make_fixture()
+        client = _client_returning("not json")
+
+        result = compare(
+            client, "m", "tb", fixture, "src", "off", "on",
+            rng=_FixedRng(0.1), sleep=lambda s: self.fail("must not sleep"),
+        )
+
+        self.assertTrue(result["judge_failure"])
+        self.assertEqual(result["retries"], 0)
+        self.assertEqual(client.chat.completions.create.call_count, 1)
+
+    def test_clean_call_records_zero_retries(self):
+        fixture = _make_fixture()
+        client = _client_returning(VALID_RESPONSE)
+
+        result = compare(client, "m", "tb", fixture, "src", "off", "on", rng=_FixedRng(0.1))
+
+        self.assertEqual(result["retries"], 0)

{django_explain_errors-0.11.0 → django_explain_errors-0.11.1}/tests/test_eval_run.py

@@ -8,9 +8,22 @@ import json
 import os
 import subprocess
 import sys
+import random
+import runpy
+import threading
+import time
 import unittest
-
-from evals.run import estimate_cost_usd, tally_judgments, tally_latency, tally_usage
+from unittest.mock import patch
+
+from evals.fixtures import FIXTURES_BY_NAME
+from evals.run import (
+    estimate_cost_usd,
+    judge_all,
+    tally_judgments,
+    tally_latency,
+    tally_retries,
+    tally_usage,
+)
 
 REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 
@@ -197,6 +210,11 @@ class TallyLatencyAndUsageTest(unittest.TestCase):
         cost = estimate_cost_usd("gpt-4o-mini", 1000, 1000)
         self.assertAlmostEqual(cost, 0.00015 + 0.0006)
 
+    def test_estimate_cost_for_gpt_6_luna(self):
+        cost = estimate_cost_usd("gpt-6-luna", 1000, 1000)
+        self.assertIsNotNone(cost)
+        self.assertAlmostEqual(cost, 0.0001 + 0.0005)
+
 
 class BuildJudgeSourceTest(unittest.TestCase):
     """Runs tests/_eval_judge_source_helper.py in a subprocess -- see its
@@ -279,6 +297,161 @@ class BuildJudgeSourceTest(unittest.TestCase):
         self.assertFalse(any(label.endswith(".html") for label in labels))
 
 
+class JudgeAllConcurrencyTest(unittest.TestCase):
+    """judge_all with a fake judge: position draws happen up front, in
+    order, independent of concurrency, and results keep job order.
+    """
+
+    FIXTURE_NAMES = ("none_attribute", "str_recursion", "bad_lookup")
+    RUNS = 3
+    SEED = 20260711
+
+    def _calls(self):
+        return [
+            {
+                "fixture": name,
+                "rag_enabled": rag,
+                "run_index": run,
+                "traceback": "tb",
+                "explanation": f"{name}/{rag}/{run}",
+            }
+            for name in self.FIXTURE_NAMES
+            for rag in (False, True)
+            for run in range(self.RUNS)
+        ]
+
+    def _run(self, concurrency, scramble=True):
+        """Returns (judgments, draws_before_first_call, call_order)."""
+        fixtures = [FIXTURES_BY_NAME[n] for n in self.FIXTURE_NAMES]
+        draws = []
+        lock = threading.Lock()
+        state = {"draws_at_first_call": None}
+        call_order = []
+
+        class CountingRandom(random.Random):
+            def random(self):
+                value = super().random()
+                draws.append(value)
+                return value
+
+        def fake_compare(client, model, tb, fixture, source, off, on, rag_on_is_a=None, **kw):
+            with lock:
+                if state["draws_at_first_call"] is None:
+                    state["draws_at_first_call"] = len(draws)
+                call_order.append((fixture.name, off))
+            if scramble:
+                # Finish out of submission order: later jobs return sooner.
+                time.sleep(0.02 if off.endswith("/0") else 0.0)
+            return {
+                "fixture": fixture.name,
+                "run_index": None,
+                "rag_on_is_a": rag_on_is_a,
+                "off": off,
+                "on": on,
+                "retries": 0,
+            }
+
+        with patch("evals.judge.get_judge_client", return_value=object()), patch(
+            "evals.judge.get_judge_model", return_value="m"
+        ), patch("evals.judge.compare", side_effect=fake_compare), patch(
+            "evals.run._build_judge_source", return_value=[]
+        ), patch("evals.run.random.Random", CountingRandom):
+            judgments = judge_all(
+                fixtures, self._calls(), {}, concurrency=concurrency, seed=self.SEED
+            )
+        return judgments, state["draws_at_first_call"], call_order
+
+    def test_all_draws_happen_before_the_first_judge_call(self):
+        total = len(self.FIXTURE_NAMES) * self.RUNS
+        for n in (1, 4, 8):
+            _, draws_at_first_call, _ = self._run(n)
+            self.assertEqual(draws_at_first_call, total, f"N={n}")
+
+    def test_positions_match_the_seeded_rng_in_fixture_then_run_order(self):
+        reference = random.Random(self.SEED)
+        expected = [
+            reference.random() < 0.5
+            for _ in range(len(self.FIXTURE_NAMES) * self.RUNS)
+        ]
+        for n in (1, 2, 8, 32):
+            judgments, _, _ = self._run(n)
+            self.assertEqual([j["rag_on_is_a"] for j in judgments], expected, f"N={n}")
+
+    def test_results_keep_comparison_order_even_when_completion_order_differs(self):
+        expected_order = [
+            (name, run) for name in self.FIXTURE_NAMES for run in range(self.RUNS)
+        ]
+        for n in (1, 8):
+            judgments, _, _ = self._run(n)
+            self.assertEqual(
+                [(j["fixture"], j["run_index"]) for j in judgments], expected_order, f"N={n}"
+            )
+            self.assertEqual(
+                [j["off"] for j in judgments],
+                [f"{name}/False/{run}" for name, run in expected_order],
+            )
+
+    def test_concurrency_one_calls_in_order(self):
+        _, _, call_order = self._run(1)
+        self.assertEqual(
+            [name for name, _ in call_order],
+            [name for name in self.FIXTURE_NAMES for _ in range(self.RUNS)],
+        )
+
+    def test_concurrency_actually_overlaps_calls(self):
+        active = {"now": 0, "peak": 0}
+        lock = threading.Lock()
+
+        def fake_compare(*args, **kwargs):
+            with lock:
+                active["now"] += 1
+                active["peak"] = max(active["peak"], active["now"])
+            time.sleep(0.05)
+            with lock:
+                active["now"] -= 1
+            return {"fixture": "x", "retries": 0}
+
+        fixtures = [FIXTURES_BY_NAME[n] for n in self.FIXTURE_NAMES]
+        with patch("evals.judge.get_judge_client", return_value=object()), patch(
+            "evals.judge.get_judge_model", return_value="m"
+        ), patch("evals.judge.compare", side_effect=fake_compare), patch(
+            "evals.run._build_judge_source", return_value=[]
+        ):
+            judge_all(fixtures, self._calls(), {}, concurrency=4, seed=1)
+        self.assertGreater(active["peak"], 1)
+        self.assertLessEqual(active["peak"], 4)
+
+
+class TallyRetriesTest(unittest.TestCase):
+
+    def test_sums_per_judgment_retries_and_tolerates_missing(self):
+        self.assertEqual(
+            tally_retries([{"retries": 2}, {"retries": 0}, {}, {"retries": None}, {"retries": 1}]),
+            3,
+        )
+
+
+class FixtureSettingsModelTest(unittest.TestCase):
+    """The fixture app's settings resolve OPENAI_MODEL from the environment."""
+
+    SETTINGS_PATH = os.path.join(REPO_ROOT, "evals", "fixture_app", "settings.py")
+
+    def _model(self, **env):
+        with patch.dict(os.environ, env):
+            if "OPENAI_MODEL" not in env:
+                os.environ.pop("OPENAI_MODEL", None)
+            return runpy.run_path(self.SETTINGS_PATH)["OPENAI_MODEL"]
+
+    def test_reads_env_var(self):
+        self.assertEqual(self._model(OPENAI_MODEL="some-other-model"), "some-other-model")
+
+    def test_unset_falls_back_to_default(self):
+        self.assertEqual(self._model(), "gpt-4o-mini")
+
+    def test_empty_string_falls_back_to_default(self):
+        self.assertEqual(self._model(OPENAI_MODEL=""), "gpt-4o-mini")
+
+
 class EvalHarnessEndToEndTest(unittest.TestCase):
     """Runs evals.run.main() in a subprocess with the generator (chat +
     embeddings) and the judge fully mocked
@@ -326,10 +499,17 @@ class EvalHarnessEndToEndTest(unittest.TestCase):
             "generator_model",
             "judge_model",
             "runs",
+            "seed",
+            "timing",
+            "judge_retries_total",
             "calls",
             "judgments",
         ):
             self.assertIn(key, data)
+        self.assertEqual(data["judge_retries_total"], 0)
+        self.assertEqual(data["timing"]["judge_concurrency"], 8)
+        self.assertGreaterEqual(data["timing"]["generator_seconds"], 0)
+        self.assertGreaterEqual(data["timing"]["judge_seconds"], 0)
 
         self.assertEqual(data["generator_model"], "gpt-4o-mini")
         self.assertEqual(data["judge_model"], "judge-test-model")
@@ -369,6 +549,7 @@ class EvalHarnessEndToEndTest(unittest.TestCase):
             "b",
             "reasoning",
             "run_index",
+            "retries",
         }
         for judgment in data["judgments"]:
             self.assertTrue(judgment_keys.issubset(judgment.keys()), judgment)

django_explain_errors-0.11.1/tests/test_token_param_fallback.py

@@ -0,0 +1,249 @@
+from unittest.mock import MagicMock, patch
+
+import openai
+from django.test import AsyncClient, Client, SimpleTestCase, override_settings
+
+
+def _bad_request(param, code):
+    body = {
+        "message": "Unsupported parameter",
+        "type": "invalid_request_error",
+        "param": param,
+        "code": code,
+    }
+    response = MagicMock(status_code=400)
+    return openai.BadRequestError("Unsupported parameter", response=response, body=body)
+
+
+def _ok_response(text="Mocked explanation.", finish_reason="stop"):
+    return MagicMock(
+        choices=[
+            MagicMock(message=MagicMock(content=text), finish_reason=finish_reason)
+        ]
+    )
+
+
+def _rejects_max_tokens(**kwargs):
+    if "max_tokens" in kwargs:
+        raise _bad_request("max_tokens", "unsupported_parameter")
+    return _ok_response()
+
+
+@override_settings(
+    DEBUG=True,
+    OPENAI_API_KEY="test-key",
+    OPENAI_MAX_TOKENS=321,
+    EXPLAIN_ERRORS_DEDUP=False,
+    ROOT_URLCONF="tests.urls_debug_page",
+    MIDDLEWARE=["explain_errors.middleware.ExplainErrorsMiddleware"],
+)
+class TokenParamFallbackBase(SimpleTestCase):
+    def setUp(self):
+        patcher = patch("openai.OpenAI")
+        mock_cls = patcher.start()
+        self.addCleanup(patcher.stop)
+        self.create = MagicMock(return_value=_ok_response())
+        mock_cls.return_value.chat.completions.create = self.create
+
+    def sent(self):
+        return [call.kwargs for call in self.create.call_args_list]
+
+    def assertTokenParam(self, kwargs, expected):
+        other = (
+            "max_completion_tokens" if expected == "max_tokens" else "max_tokens"
+        )
+        self.assertEqual(kwargs[expected], 321)
+        self.assertNotIn(other, kwargs)
+
+    def assertEmptyContentHandled(self, mock_print, response):
+        firsts = [call.args[0] for call in mock_print.call_args_list if call.args]
+        self.assertEqual(
+            firsts.count("Failed to get an explanation from the model API:"), 1
+        )
+        self.assertFalse([f for f in firsts if str(f).startswith("Error explanation")])
+        self.assertNotIn('id="explain-errors"', response.content.decode())
+
+
+class SyncTokenParamFallbackTest(TokenParamFallbackBase):
+    def trigger(self):
+        client = getattr(self, "_client", None)
+        if client is None:
+            client = self._client = Client(raise_request_exception=False)
+        return client.get("/boom/")
+
+    def test_default_sends_max_tokens_only(self):
+        self.trigger()
+        calls = self.sent()
+        self.assertEqual(len(calls), 1)
+        self.assertTokenParam(calls[0], "max_tokens")
+
+    def test_rejection_retries_once_with_max_completion_tokens(self):
+        self.create.side_effect = _rejects_max_tokens
+        with self.assertLogs("explain_errors.middleware", level="INFO") as logs:
+            response = self.trigger()
+        calls = self.sent()
+        self.assertEqual(len(calls), 2)
+        self.assertTokenParam(calls[0], "max_tokens")
+        self.assertTokenParam(calls[1], "max_completion_tokens")
+        self.assertIn("Mocked explanation.", response.content.decode())
+        self.assertEqual(len(logs.records), 1)
+        self.assertIn("max_tokens", logs.records[0].getMessage())
+        self.assertIn("max_completion_tokens", logs.records[0].getMessage())
+
+    def test_next_call_uses_max_completion_tokens_directly(self):
+        self.create.side_effect = _rejects_max_tokens
+        self.trigger()
+        self.create.reset_mock()
+        self.trigger()
+        calls = self.sent()
+        self.assertEqual(len(calls), 1)
+        self.assertTokenParam(calls[0], "max_completion_tokens")
+
+    def test_other_param_does_not_retry(self):
+        self.create.side_effect = _bad_request("temperature", "unsupported_parameter")
+        self.trigger()
+        self.assertEqual(len(self.sent()), 1)
+
+    def test_other_code_does_not_retry(self):
+        self.create.side_effect = _bad_request("max_tokens", "invalid_value")
+        self.trigger()
+        self.assertEqual(len(self.sent()), 1)
+
+    def test_failed_retry_does_not_loop_and_uses_failure_handling(self):
+        self.create.side_effect = [
+            _bad_request("max_tokens", "unsupported_parameter"),
+            RuntimeError("api down"),
+        ]
+        with patch("builtins.print") as mock_print:
+            self.trigger()
+        self.assertEqual(len(self.sent()), 2)
+        self.assertIn(
+            "Failed to get an explanation from the model API:",
+            [call.args[0] for call in mock_print.call_args_list],
+        )
+        # The switch was not remembered after a failed retry.
+        self.create.reset_mock()
+        self.create.side_effect = None
+        self.create.return_value = _ok_response()
+        self.trigger()
+        self.assertTokenParam(self.sent()[0], "max_tokens")
+
+    def test_length_warning_hints_at_reasoning_tokens_after_fallback(self):
+        self.create.side_effect = _rejects_max_tokens
+        self.trigger()
+        self.create.side_effect = None
+        self.create.return_value = _ok_response(finish_reason="length")
+        with self.assertLogs("explain_errors.middleware", level="WARNING") as logs:
+            self.trigger()
+        self.assertEqual(
+            logs.records[0].getMessage(),
+            "explain_errors: explanation truncated by OPENAI_MAX_TOKENS=321 "
+            "(reasoning tokens count against this limit; raise it if "
+            "explanations come back short or empty)",
+        )
+
+    def test_length_warning_unchanged_without_fallback(self):
+        self.create.return_value = _ok_response(finish_reason="length")
+        with self.assertLogs("explain_errors.middleware", level="WARNING") as logs:
+            self.trigger()
+        self.assertEqual(
+            logs.records[0].getMessage(),
+            "explain_errors: explanation truncated by OPENAI_MAX_TOKENS=321",
+        )
+
+    def test_empty_content_uses_failure_message_and_no_banner(self):
+        for content in (None, "", "  \n"):
+            with self.subTest(content=content):
+                self.create.return_value = _ok_response(content)
+                with patch("builtins.print") as mock_print:
+                    response = self.trigger()
+                self.assertEmptyContentHandled(mock_print, response)
+
+
+class AsyncTokenParamFallbackTest(TokenParamFallbackBase):
+    async def trigger(self):
+        client = getattr(self, "_client", None)
+        if client is None:
+            client = self._client = AsyncClient(raise_request_exception=False)
+        return await client.get("/boom-async/")
+
+    async def test_default_sends_max_tokens_only(self):
+        await self.trigger()
+        calls = self.sent()
+        self.assertEqual(len(calls), 1)
+        self.assertTokenParam(calls[0], "max_tokens")
+
+    async def test_rejection_retries_once_with_max_completion_tokens(self):
+        self.create.side_effect = _rejects_max_tokens
+        with self.assertLogs("explain_errors.middleware", level="INFO") as logs:
+            response = await self.trigger()
+        calls = self.sent()
+        self.assertEqual(len(calls), 2)
+        self.assertTokenParam(calls[0], "max_tokens")
+        self.assertTokenParam(calls[1], "max_completion_tokens")
+        self.assertIn("Mocked explanation.", response.content.decode())
+        self.assertEqual(len(logs.records), 1)
+
+    async def test_next_call_uses_max_completion_tokens_directly(self):
+        self.create.side_effect = _rejects_max_tokens
+        await self.trigger()
+        self.create.reset_mock()
+        await self.trigger()
+        calls = self.sent()
+        self.assertEqual(len(calls), 1)
+        self.assertTokenParam(calls[0], "max_completion_tokens")
+
+    async def test_other_param_does_not_retry(self):
+        self.create.side_effect = _bad_request("temperature", "unsupported_parameter")
+        await self.trigger()
+        self.assertEqual(len(self.sent()), 1)
+
+    async def test_other_code_does_not_retry(self):
+        self.create.side_effect = _bad_request("max_tokens", "invalid_value")
+        await self.trigger()
+        self.assertEqual(len(self.sent()), 1)
+
+    async def test_failed_retry_does_not_loop_and_uses_failure_handling(self):
+        self.create.side_effect = [
+            _bad_request("max_tokens", "unsupported_parameter"),
+            RuntimeError("api down"),
+        ]
+        with patch("builtins.print") as mock_print:
+            await self.trigger()
+        self.assertEqual(len(self.sent()), 2)
+        self.assertIn(
+            "Failed to get an explanation from the model API:",
+            [call.args[0] for call in mock_print.call_args_list],
+        )
+        # The switch was not remembered after a failed retry.
+        self.create.reset_mock()
+        self.create.side_effect = None
+        self.create.return_value = _ok_response()
+        await self.trigger()
+        self.assertTokenParam(self.sent()[0], "max_tokens")
+
+    async def test_length_warning_hints_at_reasoning_tokens_after_fallback(self):
+        self.create.side_effect = _rejects_max_tokens
+        await self.trigger()
+        self.create.side_effect = None
+        self.create.return_value = _ok_response(finish_reason="length")
+        with self.assertLogs("explain_errors.middleware", level="WARNING") as logs:
+            await self.trigger()
+        self.assertIn("reasoning tokens count", logs.records[0].getMessage())
+
+    async def test_length_warning_unchanged_without_fallback(self):
+        self.create.return_value = _ok_response(finish_reason="length")
+        with self.assertLogs("explain_errors.middleware", level="WARNING") as logs:
+            await self.trigger()
+        self.assertEqual(
+            logs.records[0].getMessage(),
+            "explain_errors: explanation truncated by OPENAI_MAX_TOKENS=321",
+        )
+
+    async def test_empty_content_uses_failure_message_and_no_banner(self):
+        for content in (None, "", "  \n"):
+            with self.subTest(content=content):
+                self.create.return_value = _ok_response(content)
+                with patch("builtins.print") as mock_print:
+                    response = await self.trigger()
+                self.assertEmptyContentHandled(mock_print, response)