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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-explain-errors
-Version: 0.10.1
+Version: 0.11.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
@@ -35,6 +35,8 @@ Requires-Dist: python-dotenv>=1.0
 Requires-Dist: asgiref>=3.6
 Provides-Extra: rag
 Requires-Dist: sqlite-vec>=0.1.0; extra == "rag"
+Provides-Extra: local-embeddings
+Requires-Dist: sentence-transformers>=2.2; extra == "local-embeddings"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -91,20 +93,22 @@ better. This package is not trying to compete there.
 - Captures Django errors and exceptions
 - Shows the explanation on Django's debug page, directly under the
   exception headline (`EXPLAIN_ERRORS_INJECT_DEBUG_PAGE`, on by default)
+- Codebase-aware explanations via RAG over a local sqlite-vec index
+  (recommended; see "Codebase-aware explanations" below)
+  - Local embeddings via an optional extra: your codebase is indexed on your machine and never uploaded to an embeddings provider (only the traceback and a few relevant snippets reach your chat model; see [Privacy](#privacy))
+  - Separate embeddings provider config, so Anthropic users can use RAG
+- 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
+- Explanations in your language via `EXPLAIN_ERRORS_LANGUAGE`, with exception names,
+  identifiers, and code kept in English
 - Copy button on each code block in the explanation, so a suggested fix
   copies in one click
 - Prints the explanation to stdout, for terminal workflows and logs
   (`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 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,
-  identifiers, and code kept in English
-- Redacts secrets, tokens, and emails from tracebacks before sending
+- Redacts common secret patterns, tokens, and emails (see [Privacy](#privacy))
 - Rate limits API calls with a configurable sliding window
 - Works with both sync (WSGI) and async (ASGI) views
 - Manages the API key using environment variables
@@ -153,8 +157,9 @@ pip install django-explain-errors
 ## Production Safety
 
 This middleware is intended for local development only. When active, it sends exception
-tracebacks to the configured LLM provider, which may include source code, file paths, and
-local variable values. Keep it out of production.
+tracebacks to the configured LLM provider, which include file paths, the source line of each
+frame, and the exception message (which can contain values). Local variables are not sent.
+Keep it out of production.
 
 **Primary safeguard:** register the middleware only when `DEBUG` is on, or only in your
 development settings module:
@@ -195,15 +200,6 @@ python manage.py check --deploy --fail-level WARNING
     The view raised a ValueError because ...
    ```
 
-## Async Support
-
-The middleware exposes both `sync_capable = True` and `async_capable = True`. At initialization it inspects `get_response` to decide whether it is part of a sync or async chain:
-
-- Under WSGI (for example `runserver` with sync views), requests flow through the synchronous handler.
-- Under ASGI (for example with async views), requests are awaited through the async handler. The blocking model API call is offloaded with `asgiref.sync.sync_to_async` so the event loop is not blocked.
-
-No additional settings are needed. See Installation above for where to place the middleware in `MIDDLEWARE`.
-
 ## Debug page injection
 
 When Django renders its debug page for a 500, `explain_errors` also inserts a banner
@@ -243,6 +239,15 @@ what Django's debug page looks like: a new section appears above the request met
 table. If you rely on the debug page's exact markup (a scraper, a screenshot test), account
 for this.
 
+## Async Support
+
+The middleware exposes both `sync_capable = True` and `async_capable = True`. At initialization it inspects `get_response` to decide whether it is part of a sync or async chain:
+
+- Under WSGI (for example `runserver` with sync views), requests flow through the synchronous handler.
+- Under ASGI (for example with async views), requests are awaited through the async handler. The blocking model API call is offloaded with `asgiref.sync.sync_to_async` so the event loop is not blocked.
+
+No additional settings are needed. See Installation above for where to place the middleware in `MIDDLEWARE`.
+
 ## Compatibility
 
 How this middleware interacts with other error-handling and debugging tools, in the default
@@ -250,16 +255,14 @@ preserve mode and with `EXPLAIN_ERRORS_PRESERVE_DEBUG_PAGE=False`:
 
 | Package | Preserve mode (default) | `EXPLAIN_ERRORS_PRESERVE_DEBUG_PAGE=False` |
 | ------- | ------------------------ | ------------------------------------------- |
-| Django Debug Toolbar | Works — Django renders its debug page (with the explanation banner, unless `EXPLAIN_ERRORS_INJECT_DEBUG_PAGE = False`), and Debug Toolbar injects into it. | Broken — the JSON 500 response has no HTML to inject into. |
+| Django Debug Toolbar | Works. Django renders its debug page (with the explanation banner, unless `EXPLAIN_ERRORS_INJECT_DEBUG_PAGE = False`), and Debug Toolbar injects into it. Verified with the banner present, with the toolbar middleware before or after this one, on WSGI and ASGI. | Broken. The JSON 500 response has no HTML to inject into. |
 | Sentry, Rollbar | Work — the exception propagates and Django re-raises it, so `got_request_exception` fires. | Broken — returning a response ends exception handling before `got_request_exception` fires. |
 | Django REST Framework | Partial — only exceptions DRF does not already handle itself reach this middleware. | Partial, same reason. |
 | Silk and other profiling panels | Timings are inflated by the model API call, since `process_exception` blocks the request path. | Same. |
 | CORS, GZip, WhiteNoise | No interaction. | No interaction. |
 | `runserver_plus` / Werkzeug debugger | Works — returning `None` re-raises the original exception, and `django-extensions` replaces Django's debug-page renderer with one that re-raises instead, so Werkzeug's WSGI wrapper catches it and shows the interactive debugger. | Broken — the JSON 500 response ends exception handling before it reaches `runserver_plus`'s exception hook, so the Werkzeug debugger never appears. |
 
-Debug Toolbar, Sentry, and Werkzeug were verified empirically, on both Django 4.2 and Django
-6.1, in both modes. DRF, Silk, and CORS/GZip/WhiteNoise are reasoned from the mechanism
-rather than tested.
+Debug Toolbar, Sentry, and Werkzeug were verified empirically, on both Django 4.2 and Django 6.1, in both modes. The Debug Toolbar check was repeated with the explanation banner present (default preserve mode) on Django 4.2 and 6.1, under WSGI and ASGI, for sync and async views, with the toolbar middleware before and after this one. Both orderings work. Visual layout and toolbar JavaScript behavior were not checked. DRF, Silk, and CORS/GZip/WhiteNoise are reasoned from the mechanism rather than tested.
 
 One additional behavior worth knowing, also verified on both Django versions: when the
 explanation call itself fails (a bad key, a timeout, an unreachable endpoint), a
@@ -285,8 +288,8 @@ developer is actually investigating.
 | `OPENAI_BASE_URL` (env or settings) | No | Base URL for any OpenAI-compatible API (for example Ollama at `http://localhost:11434/v1`). When set, a missing API key is replaced with a placeholder since local servers do not require one. |
 | `EXPLAIN_ERRORS_MAX_CALLS` | No | Together with `EXPLAIN_ERRORS_WINDOW_SECONDS`, caps API spend to at most this many explanations within a rolling window; once the cap is hit, further errors in that window are not sent for explanation until an earlier call ages out. Defaults to `5`. |
 | `EXPLAIN_ERRORS_WINDOW_SECONDS` | No | Length in seconds of the rolling window `EXPLAIN_ERRORS_MAX_CALLS` is measured against. Defaults to `60` (with the defaults, at most 5 explanations per 60-second window). |
-| `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_PATTERNS` | No | Extra regex pattern strings (each passed to `re.compile`) applied to the traceback, the RAG query, and indexed chunks (see [Redaction](#redaction)), 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, RAG queries, and indexed chunks (see [Redaction](#redaction)). 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. |
 | `EXPLAIN_ERRORS_DEDUP` | No | When `True` (the default), a repeat of an error already explained in this process replays the earlier explanation instead of calling the model or using a throttle slot. Two errors are identical when they have the same exception type, the same exception message, and the same innermost project line (file, line number, and that line's source text); editing the line makes it a new error. Keeps the last 128 distinct errors per worker (least recently used entries are evicted first) and entries never expire on a timer. Set to `False` to explain every error. |
@@ -334,6 +337,59 @@ Reasoning models behind `OPENAI_BASE_URL` spend part of the token budget on inte
 before producing visible output. At a low `OPENAI_MAX_TOKENS`, the budget can be used up by
 reasoning alone, and the explanation comes back empty. Raise `OPENAI_MAX_TOKENS` if you see this.
 
+### RAG does not work with Anthropic alone
+
+The [RAG layer](#codebase-aware-explanations-rag) needs an embeddings endpoint, and
+Anthropic's OpenAI-compatible API has none: `POST /v1/embeddings` returns HTTP 404
+(`not_found_error`), and Anthropic does not offer its own embedding model. With only the
+config above, `build_error_index` fails with an error saying so, and retrieval at request
+time falls back to the traceback-only prompt.
+
+To use RAG with Claude, keep Anthropic for chat and point embeddings at an OpenAI-compatible
+provider with the `EXPLAIN_ERRORS_RAG_EMBED_*` settings:
+
+```python
+# Chat: Anthropic
+OPENAI_BASE_URL = "https://api.anthropic.com/v1/"
+OPENAI_API_KEY = "your_anthropic_api_key_here"
+OPENAI_MODEL = "..."
+
+# Embeddings: any OpenAI-compatible embeddings provider (OpenAI shown)
+EXPLAIN_ERRORS_RAG_ENABLED = True
+EXPLAIN_ERRORS_RAG_EMBED_BASE_URL = "https://api.openai.com/v1/"
+EXPLAIN_ERRORS_RAG_EMBED_API_KEY = "your_openai_api_key_here"
+EXPLAIN_ERRORS_RAG_EMBED_MODEL = "text-embedding-3-small"
+```
+
+Each of the three settings falls back to the chat value when unset, with one exception for
+safety: if `EXPLAIN_ERRORS_RAG_EMBED_BASE_URL` differs from the chat base URL,
+`EXPLAIN_ERRORS_RAG_EMBED_API_KEY` is required, and `ImproperlyConfigured` is raised without
+it. The chat key is never sent to a different provider. A local OpenAI-compatible
+embeddings server that ignores keys still needs a dummy value, for example
+`"sk-no-key-required"`.
+
+The embed settings are also read from environment variables of the same name, which take
+precedence over Django settings. Indexed source chunks are sent to the embeddings provider
+(after redaction), not to Anthropic.
+
+### No second key: local embeddings
+
+If you would rather not use a second provider, run the embeddings on your own machine
+instead. Chat stays on Anthropic and no embeddings API key is needed:
+
+```python
+# Chat: Anthropic
+OPENAI_BASE_URL = "https://api.anthropic.com/v1/"
+OPENAI_API_KEY = "your_anthropic_api_key_here"
+OPENAI_MODEL = "..."
+
+# Embeddings: on this machine
+EXPLAIN_ERRORS_RAG_ENABLED = True
+EXPLAIN_ERRORS_RAG_EMBED_BACKEND = "local"
+```
+
+See [Local embeddings](#local-embeddings) for the install command and what to expect.
+
 ### A note on API keys and 401s
 
 `explain_errors` reads `OPENAI_API_KEY` (see Configuration above); it does not read
@@ -345,6 +401,133 @@ 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.
 
+## Privacy
+
+This section describes what leaves your machine, when, and to which endpoint. It describes
+this package's behavior only. It makes no claims about what a provider does with data after
+receiving it; check your provider's own terms.
+
+### What is sent to the chat provider
+
+On each error that triggers an explanation, one request goes to the endpoint set by
+`OPENAI_BASE_URL` (OpenAI by default). Its contents:
+
+- A fixed system prompt, plus the language name if `EXPLAIN_ERRORS_LANGUAGE` is set.
+- The traceback: exception type and message, and for each frame the file path, line number,
+  and source line. Library frames are condensed to fit `OPENAI_MAX_TRACEBACK_CHARS`
+  (default 3000), and the result is redacted. Local variable values are not included, but the
+  exception message can contain values.
+- With RAG enabled, up to `EXPLAIN_ERRORS_RAG_TOP_K` (default 4) retrieved code chunks, each
+  under a header with its file path and line range. The traceback and chunks together are
+  capped at `EXPLAIN_ERRORS_RAG_MAX_PROMPT_CHARS` (default 6000).
+- The model name and token limit as request parameters, and your API key as the credential.
+
+Nothing else is added: not the request path, headers, body, session, or user, and not your
+Django settings. The request object is never passed to the prompt builder.
+
+Not every error causes a request. A repeat of an already explained error replays the cached
+explanation (`EXPLAIN_ERRORS_DEDUP`, on by default), and calls are limited per worker process
+to 5 per 60 seconds by default.
+
+### What is sent to the embeddings provider
+
+Only when RAG is enabled and the embeddings backend is not `local`:
+
+- **When you run `build_error_index`:** every chunk of every `.py`, `.html`, and `.txt` file
+  under `EXPLAIN_ERRORS_RAG_INCLUDE` (default: `BASE_DIR`), after redaction. Directories named
+  in `EXPLAIN_ERRORS_RAG_EXCLUDE` are skipped. The default is `migrations`, `venv`, `.venv`,
+  `env`, `node_modules`, `static`, `media`, and `.git`. Setting it replaces that list rather
+  than extending it, and it matches directory names only, not individual files. File paths
+  are not part of the embedded text.
+- **On each error (RAG enabled):** a query made of the exception type and message plus about
+  five lines of source on each side of the innermost project frame, after redaction.
+
+The index file itself stays on disk. It holds the redacted chunk text.
+
+### Summary by setup
+
+| Setup | Indexing (your codebase) | Each error (traceback + snippets) |
+|---|---|---|
+| OpenAI chat + OpenAI embeddings | Redacted chunks go to OpenAI embeddings | Query goes to OpenAI embeddings; redacted traceback and retrieved snippets go to OpenAI chat |
+| Anthropic chat + separate embeddings provider | Redacted chunks go to the embeddings provider only, not to Anthropic | Query goes to the embeddings provider; redacted traceback and retrieved snippets go to Anthropic |
+| Any chat + local embeddings | Stays on your machine | Query is embedded locally; redacted traceback and retrieved snippets go to your chat provider |
+| Local chat (e.g. Ollama) + local embeddings | Nothing leaves the machine* | Nothing leaves the machine* |
+| No RAG | Not applicable, no index is built | Redacted traceback goes to your chat provider |
+
+\* Assumes the chat endpoint is genuinely local; the package sends to whatever
+`OPENAI_BASE_URL` points at. The local embedding model is downloaded on first use (see
+[Local embeddings](#local-embeddings)), which transfers the model to you and none of your code.
+
+### Redaction
+
+Before any text is sent or stored, it passes through a regex-based redactor. By default it
+replaces the following with `[REDACTED]` (`EXPLAIN_ERRORS_REDACT_REPLACEMENT`):
+
+- **Secret-like assignments.** A name that starts with `secret`, `password`, `passwd`,
+  `token`, `api_key` (or `apikey`), or `auth`, followed by `=` or `:`, together with its
+  value. The name may continue after the keyword with `_` or `-` and more word characters,
+  or with a capitalized suffix, so `SECRET_KEY`, `AWS_SECRET_ACCESS_KEY`, `secret-key`, and
+  `apiKeyId` all match. A quote after the name is allowed, so dict keys such as
+  `'PASSWORD': 'x'` match. A quoted value is redacted whole, spaces included. Text before the
+  keyword stays: `AWS_SECRET_ACCESS_KEY = "x"` becomes `AWS_[REDACTED]`.
+- **Credentials in URLs.** In `scheme://user:pw@host`, the `user:pw` part. The scheme and
+  host stay.
+- **Known key shapes**, whatever the variable is called: `sk-` (OpenAI, and Anthropic's
+  `sk-ant-`), Stripe `sk_live_` and `sk_test_`, GitHub `ghp_`, `gho_`, `ghu_`, `ghs_`,
+  `ghr_`, and `github_pat_`, Slack `xoxb-`, `xoxa-`, `xoxp-`, `xoxr-`, and `xoxs-`, AWS
+  `AKIA`, and Google `AIza`. Each needs a minimum run of characters after the prefix (for
+  example 20 after `sk-`), so short strings do not match.
+- `Authorization` header values and `Bearer` tokens.
+- Email addresses.
+
+Five Django settings start with a keyword but hold no secret, so they are never redacted:
+`AUTH_USER_MODEL`, `AUTHENTICATION_BACKENDS`, `AUTH_PASSWORD_VALIDATORS`, `PASSWORD_HASHERS`,
+and `PASSWORD_RESET_TIMEOUT`. The match is on the exact name.
+
+It is applied to the traceback (after truncation), to the RAG query text, and to every chunk
+at index time, before the chunk is embedded or written to the index. It is not applied to file
+paths, which appear in tracebacks and in chunk headers.
+
+Add your own regexes with `EXPLAIN_ERRORS_REDACT_PATTERNS`. They run after the defaults.
+`EXPLAIN_ERRORS_REDACT_DISABLE_DEFAULTS = True` turns the defaults off.
+
+**Limits.** This is pattern matching, not a secret scanner. Treat it as a safety net.
+
+- A secret is only caught if its name contains one of the keywords above or its value has a
+  known shape. A bare `key`, `private_key`, or `credentials` is not redacted, so
+  `private_key = "abc123"` passes through. A bare `key` is left alone on purpose, because redacting it
+  would also hide ordinary code such as dict keys and cache keys.
+- Keys with an unknown prefix, or shorter than the length each shape requires, are not
+  caught unless the name matches.
+- An unquoted value with spaces is redacted up to the first space only, and a value that
+  spans lines (a triple-quoted string, a PEM block) is not redacted past its first line.
+- Some harmless names are redacted too. Any name that starts with a keyword followed by `_`,
+  `-`, or a capital letter matches, so `token_count` and `PASSWORD_FIELD` lose their values
+  even though they are not secrets. Names that only begin with the same letters, such as
+  `author`, `authors`, and `tokenizer`, are left alone.
+- Names, IP addresses, phone numbers, other personal data, and file paths (which can contain
+  your username) are not redacted. Neither are values inside exception messages unless a
+  pattern happens to match them.
+- `settings.py` normally sits under `BASE_DIR`, so it is indexed by default. Its
+  `SECRET_KEY` and `DATABASES` password are caught, but a secret stored under a name with no
+  keyword may not be. Add a pattern for your own naming, for example
+  `EXPLAIN_ERRORS_REDACT_PATTERNS = [r"(?i)(?:private_key|credentials)\w*\s*=\s*\S+"]`, leave
+  the settings directory out of `EXPLAIN_ERRORS_RAG_INCLUDE`, or use local embeddings.
+
+### DEBUG only
+
+The middleware does nothing when `DEBUG` is `False`: no client is created and no request is
+made. One thing is not tied to `DEBUG`: `manage.py build_error_index` is a command, so it
+sends chunks to a non-local embeddings provider whenever you run it. For keeping the
+middleware out of production, see [Production Safety](#production-safety).
+
+### Telemetry
+
+This package's own code contains no telemetry or analytics and makes no network requests
+other than to the chat and embeddings endpoints you configure. Nothing is sent to the
+maintainer. Its dependencies (`openai`, and optionally `sqlite-vec` and
+`sentence-transformers`) are separate projects and are not covered by this statement.
+
 ## Explanation language
 
 By default, explanations are written in English. Set `EXPLAIN_ERRORS_LANGUAGE` to
@@ -396,6 +579,11 @@ also retrieves the most relevant chunks of your own project's source code
 from a local vector index and includes them in the prompt, so explanations
 can reference your actual functions and classes instead of guessing at them.
 
+RAG needs a provider with an embeddings endpoint. Anthropic's OpenAI-compatible API has
+none, so Claude users must configure a separate embeddings provider or use
+[local embeddings](#local-embeddings); see
+[RAG does not work with Anthropic alone](#rag-does-not-work-with-anthropic-alone).
+
 Recommended for most projects. It is opt-in only because setup takes three
 steps (install the extra, build the index, enable it), and it adds no
 dependencies or behavior until you do.
@@ -420,8 +608,8 @@ python manage.py build_error_index
 ```
 
 This walks your project, chunks Python files by top-level function/class
-(and other text files by fixed-size line windows), embeds each chunk with
-the configured endpoint's embeddings API, and writes them to a local index file. Re-run it
+(and other text files by fixed-size line windows), embeds each chunk through the configured embeddings provider (or on this machine with the
+[local backend](#local-embeddings)), and writes them to a local index file. Re-run it
 whenever your source changes meaningfully. Indexing is not automatic.
 Rebuilding is idempotent: it builds into a temp file and atomically replaces
 the previous index.
@@ -441,16 +629,15 @@ EXPLAIN_ERRORS_RAG_ENABLED = True
 | `EXPLAIN_ERRORS_RAG_ENABLED` | `False` | Master switch for the RAG layer. |
 | `EXPLAIN_ERRORS_RAG_INDEX_PATH` | `<BASE_DIR>/.explain_errors_index.db` | Path to the local vector index file. |
 | `EXPLAIN_ERRORS_RAG_TOP_K` | `4` | Number of chunks retrieved and injected into the prompt. |
-| `EXPLAIN_ERRORS_RAG_EMBED_MODEL` | `"text-embedding-3-small"` | Embedding model used for indexing and retrieval. Must exist on the configured endpoint. |
+| `EXPLAIN_ERRORS_RAG_EMBED_BACKEND` | `"openai"` | `"openai"` embeds through an OpenAI-compatible endpoint. `"local"` embeds on this machine with sentence-transformers and needs no API key (see [Local embeddings](#local-embeddings)). Also read from the environment, which takes precedence. |
+| `EXPLAIN_ERRORS_RAG_EMBED_MODEL` | `"text-embedding-3-small"` (`"all-MiniLM-L6-v2"` with the `local` backend) | Embedding model used for indexing and retrieval. Must exist on the configured endpoint, or be a sentence-transformers model name for the `local` backend. |
+| `EXPLAIN_ERRORS_RAG_EMBED_BASE_URL` | chat `OPENAI_BASE_URL` | Base URL of the embeddings provider. Ignored by the `local` backend. Also read from the environment. Set it when chat and embeddings use different providers (see the Anthropic section). |
+| `EXPLAIN_ERRORS_RAG_EMBED_API_KEY` | chat `OPENAI_API_KEY` | Key for the embeddings provider. Ignored by the `local` backend. Also read from the environment. Required when the embed base URL differs from the chat one. |
 | `EXPLAIN_ERRORS_RAG_INCLUDE` | `None` (defaults to `BASE_DIR`) | List of directories to index. |
 | `EXPLAIN_ERRORS_RAG_EXCLUDE` | migrations, venvs, `node_modules`, static, media, `.git` | Directory names to skip while indexing. |
 | `EXPLAIN_ERRORS_RAG_MAX_PROMPT_CHARS` | `6000` | Combined character budget for the traceback + retrieved source sections of the prompt. |
 
-Every chunk of source code and every retrieval query is passed through the
-same `sanitize_traceback()` redaction used for tracebacks, which strips
-patterns that look like secrets, tokens, and emails before anything is sent to the model API or written to the index. It's a pattern-based filter, not a
-guarantee: it catches recognizable secret shapes, not arbitrary sensitive
-data that doesn't match one.
+Chunks and queries are redacted before they are sent or written to the index; see [Privacy](#privacy) for what is and isn't caught.
 
 If RAG is enabled but the index is missing, `sqlite-vec` isn't installed, or
 retrieval fails for any reason, the middleware logs a warning and falls back
@@ -458,6 +645,50 @@ to the traceback-only prompt. It never breaks error reporting.
 
 RAG-grounded explanations tend to be longer than traceback-only ones. The default `OPENAI_MAX_TOKENS` already leaves generous headroom for this, but if you've lowered it, raise it back up when RAG is enabled so explanations are not truncated.
 
+### Local embeddings
+
+Embeddings can run on your own machine, with no embeddings provider and no second API key.
+This also works with Anthropic for chat (see [Using Anthropic](#using-anthropic-claude-models)).
+
+Install the extra alongside `rag`:
+
+```bash
+pip install django-explain-errors[rag,local-embeddings]
+```
+
+Then set one setting:
+
+```python
+EXPLAIN_ERRORS_RAG_ENABLED = True
+EXPLAIN_ERRORS_RAG_EMBED_BACKEND = "local"
+```
+
+Then build the index as usual with `python manage.py build_error_index`.
+
+What to expect:
+
+- **Install size.** The extra pulls in `sentence-transformers` and PyTorch. With the default
+  PyTorch wheels on Linux that is roughly 1 to 2 GB; a CPU-only PyTorch build is much smaller.
+  The core install and the `rag` extra are unchanged.
+- **First index build.** The default model, `all-MiniLM-L6-v2`, is downloaded the first time
+  it is used (about 90 MB), then cached by `sentence-transformers`. Set
+  `EXPLAIN_ERRORS_RAG_EMBED_MODEL` to use a different sentence-transformers model.
+- **First explanation after server start.** The model is loaded once per process, so the first
+  explanation that uses RAG after the dev server starts pays a one-time load. Later ones do not.
+- **Rebuild the index when you switch.** Vectors from different models are not comparable. The
+  index records its backend, model, and vector size. If the current settings do not match, the
+  middleware logs one warning per process telling you to rerun `build_error_index` and falls
+  back to the traceback-only prompt. It never queries a mismatched index. An index built before
+  this feature existed counts as an `openai` index.
+- **A leftover OpenAI model name.** If `EXPLAIN_ERRORS_RAG_EMBED_MODEL` is still set to an
+  OpenAI model such as `text-embedding-3-small`, the `local` backend raises
+  `ImproperlyConfigured`. Unset it, or name a local model.
+- `EXPLAIN_ERRORS_RAG_EMBED_BASE_URL` and `EXPLAIN_ERRORS_RAG_EMBED_API_KEY` are ignored by the
+  local backend.
+
+**Privacy.** Local embeddings keep your source off any embeddings API, but the traceback and
+retrieved snippets still go to your chat provider; see [Privacy](#privacy).
+
 ### .gitignore
 
 The index file is a local build artifact, not something to commit. Add it