~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
Add embedding model and hardware guidance to library pages (#7895)
LearningCircuit42255b46071b
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.mdindex 20c5277265..5561a3fc82 100644--- a/docs/CONFIGURATION.md+++ b/docs/CONFIGURATION.md@@ -78,6 +78,7 @@ They are not available in the Web UI because they are needed to start the applic| `app.warnings.dismiss_context_truncation_history` | `LDR_APP_WARNINGS_DISMISS_CONTEXT_TRUNCATION_HISTORY` | `false` | Dismiss warnings about historical context truncation | APP || `app.warnings.dismiss_egress_policy` | `LDR_APP_WARNINGS_DISMISS_EGRESS_POLICY` | `false` | Permanently hide the 'public search egress enabled' banner (the fresh-install informational one). The critical cloud-LLM and cloud-embeddings banners have their OWN dismiss flags so this can't silently hide them. | APP || `app.warnings.dismiss_elasticsearch_public_url` | `LDR_APP_WARNINGS_DISMISS_ELASTICSEARCH_PUBLIC_URL` | `false` | Permanently hide the 'Elasticsearch points at a non-private host' banner that appears when the Elasticsearch engine is active but its hosts (or cloud_id) do not look like private/local addresses (document queries would leave the machine; a private-only egress scope excludes the engine). Dismiss when a hosted endpoint such as Elastic Cloud is intentional. | APP |+| `app.warnings.dismiss_embedding_performance` | `LDR_APP_WARNINGS_DISMISS_EMBEDDING_PERFORMANCE` | `false` | Hide embedding performance tips on collection and embedding settings pages. Turn off to show the tips again. | APP || `app.warnings.dismiss_high_context` | `LDR_APP_WARNINGS_DISMISS_HIGH_CONTEXT` | `false` | Permanently hide the warning shown when your local LLM context window is set above 8,192 tokens, which may cause memory issues on some hardware. | APP || `app.warnings.dismiss_legacy_config` | `LDR_APP_WARNINGS_DISMISS_LEGACY_CONFIG` | `false` | Dismiss warnings about the deprecated server_config.json file | APP || `app.warnings.dismiss_model_mismatch` | `LDR_APP_WARNINGS_DISMISS_MODEL_MISMATCH` | `false` | Permanently hide the warning shown when using a large model (70B+ parameters) with a local provider and high context window, which may exceed available GPU memory. | APP |diff --git a/docs/embedding-performance.md b/docs/embedding-performance.mdnew file mode 100644index 0000000000..4ad58c76cf--- /dev/null+++ b/docs/embedding-performance.md@@ -0,0 +1,54 @@+# Choosing embeddings for your hardware++If you have never changed your embedding settings and indexing makes your+computer slow or keeps CPU usage high, try a smaller embedding model. With a+supported GPU and enough free VRAM, Ollama can also be a useful option.++Use the × button on a performance tip to hide these tips for your account across+collection and embedding settings pages. To show them again, turn off+**Dismiss Embedding Performance Tips** in Settings. This preference only hides+the tips; it does not change your embedding configuration.++## Use a smaller model on CPU++Open **Library → Embedding Settings** (`/library/embedding-settings`). Select+**Sentence Transformers** and try **all-MiniLM-L6-v2**, a lightweight model+available in the model dropdown. Use **Test Embedding Model** before indexing;+settings save automatically.++Smaller models can trade retrieval quality and context length for lower resource+use. This model accepts up to 256 tokens per chunk, so review your chunk size:+longer chunks may be truncated. Try a small collection and check search results+before rebuilding a large one.++## Consider Ollama with GPU acceleration++Ollama supports local embedding models and can use supported GPUs. Check+[Ollama hardware support](https://docs.ollama.com/gpu) for your GPU and drivers.+Leave enough free VRAM for the embedding model, its working memory, and any LLM+running at the same time. Switching providers alone does not guarantee lower CPU+usage or faster indexing.++1. Start Ollama and download an embedding model, for example with+ `ollama pull nomic-embed-text`.+2. In **Embedding Settings**, select **Ollama**, configure its server URL, and+ select the downloaded embedding model. The URL must be reachable from LDR;+ in Docker, `localhost` refers to the LDR container itself.+3. Use **Test Embedding Model**, then try indexing a small collection.+4. Check GPU usage while indexing to confirm that acceleration is active.++Use an embedding model rather than a chat model. See+[Ollama embeddings](https://docs.ollama.com/capabilities/embeddings) for background.++## Apply changes to existing collections++Saved defaults apply to new collections. Existing collections retain their+embedding settings until you choose **Re-Index All Documents** on the collection+page to rebuild with the current settings. A full rebuild processes every+document and can take time; keep it running until it completes. Cancelling before+publication preserves the previous index and its settings, if any.++If indexing is already making your computer unresponsive, use **Cancel Indexing**+on the collection page before changing settings and starting a rebuild.++See [Library and RAG](library-and-rag.md#rag-indexing) for more about indexing.diff --git a/docs/library-and-rag.md b/docs/library-and-rag.mdindex 650351f685..41d12f9aac 100644--- a/docs/library-and-rag.md+++ b/docs/library-and-rag.md@@ -238,6 +238,9 @@ Document → Split into Chunks → Generate Embeddings → Store in Vector Index2. **Embedding** - Each chunk converted to a vector using AI model3. **Indexing** - Vectors stored in FAISS for fast similarity search+For high CPU usage, smaller models, and Ollama GPU options, see+[Choosing embeddings for your hardware](embedding-performance.md).+### Indexing a Collection1. Go to **Library** → **Collections**diff --git a/src/local_deep_research/defaults/default_settings.json b/src/local_deep_research/defaults/default_settings.jsonindex 5124798691..813df710bf 100644--- a/src/local_deep_research/defaults/default_settings.json+++ b/src/local_deep_research/defaults/default_settings.json@@ -4398,6 +4398,20 @@"value": true,"visible": true},+ "app.warnings.dismiss_embedding_performance": {+ "category": "warnings",+ "description": "Hide embedding performance tips on collection and embedding settings pages. Turn off to show the tips again.",+ "editable": true,+ "max_value": null,+ "min_value": null,+ "name": "Dismiss Embedding Performance Tips",+ "options": null,+ "step": null,+ "type": "APP",+ "ui_element": "checkbox",+ "value": false,+ "visible": true+ },"app.warnings.dismiss_high_context": {"category": "warnings","description": "Permanently hide the warning shown when your local LLM context window is set above 8,192 tokens, which may cause memory issues on some hardware.",diff --git a/src/local_deep_research/web/routers/rag.py b/src/local_deep_research/web/routers/rag.pyindex a30fed22d0..c50479bd50 100644--- a/src/local_deep_research/web/routers/rag.py+++ b/src/local_deep_research/web/routers/rag.py@@ -492,10 +492,19 @@ def embedding_settings_page(request: Request, username: Annotated[str, Depends(require_auth)]):"""Render the Embedding Settings page."""+ from ...embeddings.sentence_transformer_models import (+ SENTENCE_TRANSFORMER_MODELS,+ )+return templates.TemplateResponse(request=request,name="pages/embedding_settings.html",- context={"request": request, "active_page": "embedding-settings"},+ context={+ "request": request,+ "active_page": "embedding-settings",+ "sentence_transformer_models": SENTENCE_TRANSFORMER_MODELS,+ "default_sentence_transformer_model": DEFAULT_LOCAL_SEARCH_MODEL,+ },)diff --git a/src/local_deep_research/web/static/js/embedding_performance_hint.js b/src/local_deep_research/web/static/js/embedding_performance_hint.jsnew file mode 100644index 0000000000..c6feb61583--- /dev/null+++ b/src/local_deep_research/web/static/js/embedding_performance_hint.js@@ -0,0 +1,118 @@+/** Account-scoped dismissal for the shared embedding performance tip. */+(function() {+ 'use strict';++ const hints = Array.from(document.querySelectorAll('[data-embedding-performance-hint]'));+ if (hints.length === 0) return;++ const settingUrl = '/settings/api/app.warnings.dismiss_embedding_performance';+ const buttons = hints.map(hint => hint.querySelector('[data-dismiss-embedding-hint]')).filter(Boolean);+ const errorTargets = hints.map(hint => hint.querySelector('[data-embedding-hint-error]')).filter(Boolean);++ // Controls that point at a hint's text (data-embedding-hint-describedby)+ // reference it through aria-describedby only while the tip is shown, so a+ // hidden or dismissed tip is not still announced. Controls may also carry a+ // tip-augmented title (data-embedding-hint-title) that replaces their base+ // title only while the tip is shown.+ const hintTextIds = new Set(+ hints.flatMap(hint => Array.from(hint.querySelectorAll('[id]'), el => el.id))+ );+ const describers = Array.from(document.querySelectorAll('[data-embedding-hint-describedby]'))+ .filter(el => hintTextIds.has(el.dataset.embeddingHintDescribedby));+ const titled = Array.from(document.querySelectorAll('[data-embedding-hint-title]'));+ const baseTitles = new Map(titled.map(el => [el, el.getAttribute('title')]));++ function syncReferences(visible) {+ describers.forEach(el => {+ const hintId = el.dataset.embeddingHintDescribedby;+ const tokens = (el.getAttribute('aria-describedby') || '')+ .split(/\s+/).filter(token => token && token !== hintId);+ if (visible) tokens.push(hintId);+ if (tokens.length) el.setAttribute('aria-describedby', tokens.join(' '));+ else el.removeAttribute('aria-describedby');+ });+ titled.forEach(el => {+ const title = visible ? el.dataset.embeddingHintTitle : baseTitles.get(el);+ if (title) el.setAttribute('title', title);+ else el.removeAttribute('title');+ });+ }++ function setVisible(visible) {+ hints.forEach(hint => { hint.hidden = !visible; });+ syncReferences(visible);+ }++ function removeDismissControls() {+ // Removed rather than hidden: .ldr-btn's display rule would+ // override the hidden attribute.+ buttons.forEach(button => button.remove());+ }++ function showError(message) {+ errorTargets.forEach(target => { target.textContent = message; });+ }++ async function serverError(response) {+ try {+ const data = await response.json();+ const message = data && (data.error || data.detail);+ return typeof message === 'string' ? message : '';+ } catch {+ return '';+ }+ }++ async function dismiss() {+ buttons.forEach(button => { button.disabled = true; });+ showError('');+ try {+ const response = await safeFetchWithAuth(settingUrl, {+ method: 'PUT',+ headers: {+ 'Content-Type': 'application/json',+ 'X-CSRFToken': window.api ? window.api.getCsrfToken() : ''+ },+ body: JSON.stringify({ value: true })+ });+ if (!response.ok) {+ const message = await serverError(response);+ showError(message+ ? `Could not save dismissal: ${message}`+ : 'Could not save dismissal. Please try again.');+ return;+ }+ setVisible(false);+ } catch {+ showError('Could not save dismissal. Please try again.');+ } finally {+ buttons.forEach(button => { button.disabled = false; });+ }+ }++ buttons.forEach(button => button.addEventListener('click', dismiss));++ // The tip is rendered hidden so a dismissed tip never flashes in and+ // shifts the layout; it is revealed once the preference says it is+ // wanted. Loading failures fail open: guidance and dismissal are shown.+ async function loadPreference() {+ let data = null;+ try {+ const response = await safeFetchWithAuth(settingUrl);+ if (response.ok) data = await response.json();+ } catch {+ data = null;+ }+ if (data && data.value === true) {+ setVisible(false);+ return;+ }+ // A locked setting (e.g. an LDR_* env override) rejects every save,+ // so do not offer a dismissal control that can never succeed.+ if (data && data.editable === false) removeDismissControls();+ setVisible(true);+ }++ setVisible(false);+ loadPreference();+})();diff --git a/src/local_deep_research/web/templates/components/embedding_performance_hint.html b/src/local_deep_research/web/templates/components/embedding_performance_hint.htmlnew file mode 100644index 0000000000..46878e54b5--- /dev/null+++ b/src/local_deep_research/web/templates/components/embedding_performance_hint.html@@ -0,0 +1,14 @@+<div data-embedding-performance-hint hidden>+<button type="button" class="ldr-btn ldr-btn-sm" data-dismiss-embedding-hint aria-label="Dismiss embedding performance tip" title="Don't show this tip again">×</button>+<p class="ldr-form-text ldr-text-muted"{% if embedding_hint_id %} id="{{ embedding_hint_id }}"{% endif %}>+ <i aria-hidden="true" class="fas fa-info-circle"></i>+ If you haven't changed your embedding settings, the default model may be demanding on your CPU.+ Indexing can take a while; keeping the default is fine if the resource use works for you.+ If indexing slows down your computer, consider a smaller model in+ <a href="/library/embedding-settings">Embedding Settings</a>.+ Ollama may help with a supported GPU and enough free VRAM.+ Existing collections need a full re-index to use changed settings.+ <a href="https://github.com/LearningCircuit/local-deep-research/blob/main/docs/embedding-performance.md" target="_blank" rel="noopener noreferrer">Embedding performance guide ↗</a>+</p>+<span class="ldr-form-text" data-embedding-hint-error role="status"></span>+</div>diff --git a/src/local_deep_research/web/templates/pages/collection_details.html b/src/local_deep_research/web/templates/pages/collection_details.htmlindex 2c008f263c..3b7af183fd 100644--- a/src/local_deep_research/web/templates/pages/collection_details.html+++ b/src/local_deep_research/web/templates/pages/collection_details.html@@ -33,16 +33,19 @@<a href="/library/collections/{{ collection_id }}/upload" class="ldr-btn-collections ldr-btn-collections-primary ldr-btn-lg ldr-btn-featured" title="Add PDF, TXT, MD, or HTML files to this collection"><i aria-hidden="true" class="fas fa-upload"></i> Upload Files</a>- <button id="index-collection-btn" class="ldr-btn-collections ldr-btn-collections-success ldr-btn-lg" title="Create searchable embeddings for unindexed documents">+ <button id="index-collection-btn" class="ldr-btn-collections ldr-btn-collections-success ldr-btn-lg" data-embedding-hint-describedby="index-embedding-performance-hint" title="Create searchable embeddings for unindexed documents" data-embedding-hint-title="Create searchable embeddings for unindexed documents. High CPU usage? Consider a smaller embedding model or Ollama with a supported GPU and enough free VRAM."><i aria-hidden="true" class="fas fa-sync"></i> Index All Documents</button>- <button id="reindex-collection-btn" class="ldr-btn-collections ldr-btn-collections-warning ldr-btn-lg" title="Re-process all documents. Use after changing embedding settings.">+ <button id="reindex-collection-btn" data-embedding-hint-describedby="index-embedding-performance-hint" class="ldr-btn-collections ldr-btn-collections-warning ldr-btn-lg" title="Re-process all documents. Use after changing embedding settings."><i aria-hidden="true" class="fas fa-redo"></i> Re-Index All Documents</button><button id="delete-collection-btn" class="ldr-btn-collections ldr-btn-collections-danger ldr-btn-lg" title="Delete this collection and its embeddings. Documents also in other collections are kept; documents only in this collection are deleted with it."><i aria-hidden="true" class="fas fa-trash"></i> Delete Collection</button></div>+ {% with embedding_hint_id="index-embedding-performance-hint" %}+ {% include "components/embedding_performance_hint.html" %}+ {% endwith %}</div><!-- Privacy & Egress -->@@ -163,6 +166,8 @@<p id="progress-text" class="ldr-progress-text">Starting...</p></div>+ {% include "components/embedding_performance_hint.html" %}+<div id="progress-log" class="ldr-progress-log"></div></div>@@ -228,3 +233,7 @@<script defer src="/static/js/components/library_search.js"></script><script defer src="/static/js/collection_details.js"></script>{% endblock %}++{% block page_scripts %}+<script defer src="/static/js/embedding_performance_hint.js"></script>+{% endblock %}diff --git a/src/local_deep_research/web/templates/pages/collections.html b/src/local_deep_research/web/templates/pages/collections.htmlindex 6f779c08cf..7df0f9838c 100644--- a/src/local_deep_research/web/templates/pages/collections.html+++ b/src/local_deep_research/web/templates/pages/collections.html@@ -14,6 +14,8 @@<p class="ldr-subtitle">Manage your document collections for {{ tooltip("RAG-enabled searches", "Upload your documents, index them, then select a collection as 'search engine' when researching. AI will search YOUR files instead of the web.") }}</p></div>+ {% include "components/embedding_performance_hint.html" %}+<!-- How Collections Work Help Panel -->{% call help_panel('collections-how', 'Understanding Document Collections', icon='folder-open', collapsed=true, dismissible=true) %}<div class="ldr-help-steps">@@ -70,3 +72,7 @@<script defer src="/static/js/collections_manager.js"></script>{% endblock %}++{% block page_scripts %}+<script defer src="/static/js/embedding_performance_hint.js"></script>+{% endblock %}diff --git a/src/local_deep_research/web/templates/pages/embedding_settings.html b/src/local_deep_research/web/templates/pages/embedding_settings.htmlindex 96876a04d7..89e7a17648 100644--- a/src/local_deep_research/web/templates/pages/embedding_settings.html+++ b/src/local_deep_research/web/templates/pages/embedding_settings.html@@ -35,12 +35,32 @@</p><p style="margin: 0;"><i aria-hidden="true" class="fas fa-lock"></i> Once a collection is indexed, its embedding settings are locked.- To change settings for an existing collection, you must re-index the entire collection, which will delete the current index.+ To change settings for an existing collection, use Re-Index All Documents to build a replacement index. The current index stays available until the replacement is ready.</p></div></div></div>+ <div class="ldr-rag-config-panel">+ <h2>Supported Sentence Transformers models</h2>+ <p class="ldr-text-muted">+ These are the models available directly through the Sentence Transformers provider.+ Indexing a large collection can take a while; keeping the default is fine if the resource use works for you.+ Choose a smaller model if CPU load or memory use interferes with other work.+ Each link opens the model's Hugging Face page with more details.+ </p>+ <ul>+ {% for model_name, model in sentence_transformer_models.items() %}+ <li><a href="https://huggingface.co/{{ model.repository }}" target="_blank" rel="noopener noreferrer">{{ model_name }}</a>{% if model_name == default_sentence_transformer_model %} (default){% endif %}: {{ model.description }} Input limit: {{ model.max_seq_length }} tokens.</li>+ {% endfor %}+ </ul>+ <p class="ldr-form-text ldr-text-muted">+ Models have different input limits; long chunks may be truncated. Review chunk size when switching models.+ For more locally managed model choices, use Ollama.+ <a href="https://github.com/LearningCircuit/local-deep-research/blob/main/docs/embedding-performance.md" target="_blank" rel="noopener noreferrer">Embedding performance guide ↗</a>+ </p>+ </div>+<!-- Test Panel --><div class="ldr-rag-operations-panel"><h2><i aria-hidden="true" class="fas fa-vial"></i> Test Configuration</h2>@@ -214,6 +234,8 @@</div></div>+ {% include "components/embedding_performance_hint.html" %}+<!-- Provider Information Panel --><div class="ldr-rag-stats-panel"><h2><i aria-hidden="true" class="fas fa-info-circle"></i> Provider Information</h2>@@ -227,3 +249,7 @@<script defer src="/static/js/embedding_settings.js"></script>{% endblock %}++{% block page_scripts %}+<script defer src="/static/js/embedding_performance_hint.js"></script>+{% endblock %}diff --git a/tests/js/embedding-performance-hint.test.js b/tests/js/embedding-performance-hint.test.jsnew file mode 100644index 0000000000..cfb31f05cc--- /dev/null+++ b/tests/js/embedding-performance-hint.test.js@@ -0,0 +1,167 @@+import { readFileSync } from 'node:fs';+import { resolve } from 'node:path';+import DOMPurify from 'dompurify';++const template = readFileSync(resolve(__dirname, '../../src/local_deep_research/web/templates/components/embedding_performance_hint.html'), 'utf8');+const component = template+ .replace(/\{%[\s\S]*?%\}/g, '')+ .replace(/\{\{[\s\S]*?\}\}/g, '');+// Same component rendered with an embedding_hint_id, as collection_details.html does.+const componentWithId = template+ .replace(/\{% if embedding_hint_id %\}([\s\S]*?)\{% endif %\}/g, '$1')+ .replace(/\{\{\s*embedding_hint_id\s*\}\}/g, 'index-hint')+ .replace(/\{%[\s\S]*?%\}/g, '');+const baseTitle = 'Create searchable embeddings';+const tipTitle = 'Create searchable embeddings. High CPU usage?';+const describedControls = `+ <button id="index-btn" data-embedding-hint-describedby="index-hint" title="${baseTitle}" data-embedding-hint-title="${tipTitle}">Index</button>+ <button id="reindex-btn" aria-describedby="other-help" data-embedding-hint-describedby="index-hint" title="Re-index">Re-Index</button>+ <span id="other-help">Other help</span>`;+const settingUrl = '/settings/api/app.warnings.dismiss_embedding_performance';+const response = (value, ok = true, extra = {}) => ({ ok, json: async () => ({ value, editable: true, ...extra }) });+const errorResponse = body => ({ ok: false, json: async () => body });+const hints = () => Array.from(document.querySelectorAll('[data-embedding-performance-hint]'));+const buttons = () => Array.from(document.querySelectorAll('[data-dismiss-embedding-hint]'));+const allVisible = () => hints().every(hint => !hint.hidden);+const allHidden = () => hints().every(hint => hint.hidden);++beforeEach(() => {+ vi.resetModules();+ document.body.innerHTML = DOMPurify.sanitize(component + component);+ window.api = { getCsrfToken: () => 'test-csrf' };+ globalThis.safeFetchWithAuth = vi.fn().mockResolvedValue(response(false));+});++afterEach(() => {+ document.body.innerHTML = '';+ delete window.api;+});++async function start() {+ await import('../../src/local_deep_research/web/static/js/embedding_performance_hint.js');+ await vi.waitFor(() => expect(safeFetchWithAuth).toHaveBeenCalledWith(settingUrl));+}++it('renders hidden and stays hidden until the preference has loaded', async () => {+ expect(allHidden()).toBe(true);+ let finishLoad;+ safeFetchWithAuth.mockImplementation(() => new Promise(complete => { finishLoad = complete; }));+ await start();+ expect(allHidden()).toBe(true);+ finishLoad(response(false));+ await vi.waitFor(() => expect(allVisible()).toBe(true));+});++it('keeps every copy hidden when the account has dismissed the tip', async () => {+ safeFetchWithAuth.mockResolvedValue(response(true));+ await start();+ await new Promise(r => setTimeout(r, 0));+ expect(allHidden()).toBe(true);+});++it.each([false, 'false'])('reveals tips for preference %s', async value => {+ safeFetchWithAuth.mockResolvedValue(response(value));+ await start();+ await vi.waitFor(() => expect(allVisible()).toBe(true));+ expect(buttons()).toHaveLength(2);+});++it('removes the dismiss control when the setting is not editable', async () => {+ safeFetchWithAuth.mockResolvedValue(response(false, true, { editable: false }));+ await start();+ await vi.waitFor(() => expect(allVisible()).toBe(true));+ expect(buttons()).toHaveLength(0);+});++it('saves with CSRF and hides all copies only after the save succeeds', async () => {+ let finishSave;+ safeFetchWithAuth.mockImplementation((_url, options) => {+ if (options) return new Promise(complete => { finishSave = complete; });+ return Promise.resolve(response(false));+ });+ await start();+ await vi.waitFor(() => expect(allVisible()).toBe(true));+ buttons()[0].click();+ expect(buttons().every(button => button.disabled)).toBe(true);+ expect(allVisible()).toBe(true);+ expect(safeFetchWithAuth).toHaveBeenLastCalledWith(settingUrl, {+ method: 'PUT',+ headers: { 'Content-Type': 'application/json', 'X-CSRFToken': 'test-csrf' },+ body: JSON.stringify({ value: true })+ });+ finishSave(response(true));+ await vi.waitFor(() => expect(allHidden()).toBe(true));+});++it('reports a rejected save and allows retry without hiding the tips', async () => {+ await start();+ await vi.waitFor(() => expect(allVisible()).toBe(true));+ safeFetchWithAuth.mockResolvedValueOnce(errorResponse(null));+ buttons()[0].click();+ await vi.waitFor(() => expect(buttons().every(button => !button.disabled)).toBe(true));+ expect(allVisible()).toBe(true);+ expect(document.querySelector('[data-embedding-hint-error]').textContent).toContain('Please try again');+ safeFetchWithAuth.mockResolvedValueOnce(response(true));+ buttons()[0].click();+ await vi.waitFor(() => expect(allHidden()).toBe(true));+});++it('surfaces the server error message when a save is refused', async () => {+ await start();+ await vi.waitFor(() => expect(allVisible()).toBe(true));+ safeFetchWithAuth.mockResolvedValueOnce(errorResponse({ error: 'Settings are locked' }));+ buttons()[0].click();+ await vi.waitFor(() => expect(buttons().every(button => !button.disabled)).toBe(true));+ expect(allVisible()).toBe(true);+ expect(document.querySelector('[data-embedding-hint-error]').textContent)+ .toBe('Could not save dismissal: Settings are locked');+});++it('fails open when the preference request is not ok', async () => {+ safeFetchWithAuth.mockResolvedValue(errorResponse({ error: 'Failed to retrieve settings' }));+ await start();+ await vi.waitFor(() => expect(allVisible()).toBe(true));+ expect(buttons()).toHaveLength(2);+});++it('fails open when preference loading rejects', async () => {+ safeFetchWithAuth.mockRejectedValue(new Error('Offline'));+ await start();+ await vi.waitFor(() => expect(allVisible()).toBe(true));+});++describe('controls described by the tip', () => {+ beforeEach(() => {+ document.body.innerHTML = DOMPurify.sanitize(describedControls + componentWithId);+ });++ const indexBtn = () => document.getElementById('index-btn');+ const reindexBtn = () => document.getElementById('reindex-btn');++ it('reference the tip only while it is shown and drop it on dismissal', async () => {+ expect(document.getElementById('index-hint')).not.toBeNull();+ await start();+ await vi.waitFor(() => expect(allVisible()).toBe(true));+ expect(indexBtn().getAttribute('aria-describedby')).toBe('index-hint');+ expect(indexBtn().getAttribute('title')).toBe(tipTitle);+ expect(reindexBtn().getAttribute('aria-describedby')).toBe('other-help index-hint');++ safeFetchWithAuth.mockResolvedValueOnce(response(true));+ buttons()[0].click();+ await vi.waitFor(() => expect(allHidden()).toBe(true));+ expect(indexBtn().hasAttribute('aria-describedby')).toBe(false);+ expect(indexBtn().getAttribute('title')).toBe(baseTitle);+ expect(reindexBtn().getAttribute('aria-describedby')).toBe('other-help');+ expect(reindexBtn().getAttribute('title')).toBe('Re-index');+ });++ it('never reference an already-dismissed tip', async () => {+ safeFetchWithAuth.mockResolvedValue(response(true));+ await start();+ await new Promise(r => setTimeout(r, 0));+ expect(allHidden()).toBe(true);+ expect(indexBtn().hasAttribute('aria-describedby')).toBe(false);+ expect(indexBtn().getAttribute('title')).toBe(baseTitle);+ expect(reindexBtn().getAttribute('aria-describedby')).toBe('other-help');+ });+});diff --git a/tests/settings/golden_master_settings.json b/tests/settings/golden_master_settings.jsonindex c9e5982574..f8bdbb01e4 100644--- a/tests/settings/golden_master_settings.json+++ b/tests/settings/golden_master_settings.json@@ -482,6 +482,20 @@"value": false,"visible": true},+ "app.warnings.dismiss_embedding_performance": {+ "category": "warnings",+ "description": "Hide embedding performance tips on collection and embedding settings pages. Turn off to show the tips again.",+ "editable": true,+ "max_value": null,+ "min_value": null,+ "name": "Dismiss Embedding Performance Tips",+ "options": null,+ "step": null,+ "type": "APP",+ "ui_element": "checkbox",+ "value": false,+ "visible": true+ },"app.warnings.dismiss_high_context": {"category": "warnings","description": "Permanently hide the warning shown when your local LLM context window is set above 8,192 tokens, which may cause memory issues on some hardware.",diff --git a/tests/settings/test_shipped_defaults_contracts.py b/tests/settings/test_shipped_defaults_contracts.pyindex 59b8162a92..984d637f9b 100644--- a/tests/settings/test_shipped_defaults_contracts.py+++ b/tests/settings/test_shipped_defaults_contracts.py@@ -418,6 +418,8 @@ DOCUMENTED_PERMISSIVE_DEFAULTS: Dict[str, Tuple[Any, str]] = {# unclassified match fails rather than being quietly skipped.NOT_A_SECURITY_CONTROL = frozenset({+ # Informational performance tip only; dismissal changes no policy.+ "app.warnings.dismiss_embedding_performance","app.host", # notification URL building only -- see its own test"app.port","web.port",diff --git a/tests/test_constants.py b/tests/test_constants.pyindex 3aeeb7b351..c9410c9d60 100644--- a/tests/test_constants.py+++ b/tests/test_constants.py@@ -165,10 +165,13 @@ def test_injected_frontend_local_search_constants_match_defaults():def test_embedding_settings_template_renders_without_syntax_error():- """pages/embedding_settings.html must compile and render properly."""+ """The page route renders defaults and the shared model catalog."""from starlette.requests import Request+ from local_deep_research.embeddings.sentence_transformer_models import (+ SENTENCE_TRANSFORMER_MODELS,+ )from local_deep_research.web.fastapi_app import _setup_template_globals- from local_deep_research.web.template_config import templates+ from local_deep_research.web.routers.rag import embedding_settings_page_setup_template_globals()req = Request(@@ -180,14 +183,26 @@ def test_embedding_settings_template_renders_without_syntax_error():"session": {},})- ctx = {"request": req, "active_page": "embedding-settings"}- resp = templates.TemplateResponse(- request=req,- name="pages/embedding_settings.html",- context=ctx,- )+ resp = embedding_settings_page(req, username="testuser")html = resp.body.decode()+ assert resp.status_code == 200+ assert html.index("/static/js/security/safe-fetch.js") < html.index(+ "/static/js/embedding_performance_hint.js"+ )+ assert (+ resp.context["sentence_transformer_models"]+ is SENTENCE_TRANSFORMER_MODELS+ )+ assert html.count('href="https://huggingface.co/') == len(+ SENTENCE_TRANSFORMER_MODELS+ )+ for model_name, model in SENTENCE_TRANSFORMER_MODELS.items():+ assert f'href="https://huggingface.co/{model.repository}"' in html+ assert f">{model_name}</a>" in html+ assert model.description in html+ assert f"Input limit: {model.max_seq_length} tokens." in html+ assert f">{DEFAULT_LOCAL_SEARCH_MODEL}</a> (default)" in htmlassert "Default Embedding Settings" in htmlassert 'id="text-separators"' in htmlassert (diff --git a/tests/web/test_template_script_placement.py b/tests/web/test_template_script_placement.pyindex 0d0fdbea9c..bba363bf9b 100644--- a/tests/web/test_template_script_placement.py+++ b/tests/web/test_template_script_placement.py@@ -30,6 +30,7 @@ _PAGES = (# Components whose synchronous init depends on base.html's deferred shared# scripts (safeFetchWithAuth from safe-fetch.js)._SAFE_FETCH_COMPONENTS = (+ "embedding_performance_hint.js","components/annotation_surface.js","components/document_notes.js","components/research_notes.js",@@ -83,9 +84,12 @@ def test_safe_fetch_components_load_from_page_scripts_block():def test_known_consumers_still_covered():- # The three templates that load these components today. If one stops+ # The templates that load these components today. If one stops# loading them, this list (not the invariant) needs updating.expected = {+ "collections.html": {"embedding_performance_hint.js"},+ "collection_details.html": {"embedding_performance_hint.js"},+ "embedding_settings.html": {"embedding_performance_hint.js"},"document_details.html": {"components/document_notes.js"},"document_text.html": {"components/annotation_surface.js",