Skip to content

~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.

fix(llm): address audit findings from PR #3670 (#3767)

LearningCircuit571141e47238
diff --git a/README.md b/README.md
index ccd68ec6f7..a6bf8ee0cc 100644
--- a/README.md
+++ b/README.md
@@ -471,7 +471,7 @@ search(query="copyright fair use precedents", engine="openclaw")
### Upgrading from earlier versions
-- **`llm.model` no longer has a default.** Pre-1.7 installs auto-filled `gemma3:12b` (Ollama) when no model was configured, which silently downloaded a multi-GB binary. The field is now empty by default — pick a model in Settings → LLM, or research will fail loudly with a clear error.
+- **`llm.model` no longer has a default.** Pre-1.6.3 installs auto-filled `gemma3:12b` (Ollama) when no model was configured, which silently downloaded a multi-GB binary. The field is now empty by default — pick a model in Settings → LLM, or research will fail loudly with a clear error.
- **The `auto` and `parallel` meta search engines were removed.** The default langgraph-agent strategy selects engines dynamically per query, which replaces them. Stored settings are migrated automatically (removed values become `searxng`); update any explicit `search_tool="auto"` API calls or `LDR_SEARCH_TOOL=auto` env overrides to a concrete engine such as `searxng`.
- **The `llamacpp` provider now uses HTTP instead of in-process loading.** If you previously set `llm.llamacpp_model_path` to a local `.gguf` file, that setting is no longer read. Instead, run `llama-server -m <your-model.gguf>` (it ships with every modern llama.cpp build) and the default `llm.llamacpp.url` of `http://localhost:8080/v1` will pick it up. Optional API key support is available via `llm.llamacpp.api_key` if you put `llama-server` behind an auth proxy.
diff --git a/changelog.d/3767.bugfix.md b/changelog.d/3767.bugfix.md
new file mode 100644
index 0000000000..25715b0328
--- /dev/null
+++ b/changelog.d/3767.bugfix.md
@@ -0,0 +1 @@
+Starting a follow-up research with no LLM model configured now fails immediately with a clear "Model is required" error (HTTP 400) instead of spawning a worker that dies and leaves the research stuck IN_PROGRESS.
diff --git a/changelog.d/3767.security.md b/changelog.d/3767.security.md
new file mode 100644
index 0000000000..a79eeb88ff
--- /dev/null
+++ b/changelog.d/3767.security.md
@@ -0,0 +1 @@
+News recommendation logging now sanitizes externally-derived topic strings (and search error text) before interpolating them into log records, closing a log-injection vector where crafted news content could forge log lines or inject terminal escape sequences.
diff --git a/docs/release_notes/1.6.3.md b/docs/release_notes/1.6.3.md
new file mode 100644
index 0000000000..63b69fcaaf
--- /dev/null
+++ b/docs/release_notes/1.6.3.md
@@ -0,0 +1,60 @@
+# 1.6.3 — release notes
+
+LLM provider rework shipped by [#3670](https://github.com/LearningCircuit/local-deep-research/pull/3670). 1.6.3 was tagged without release notes; this file documents its breaking changes retroactively.
+
+## BREAKING — `llm.model` no longer auto-fills `gemma3:12b`
+
+Before this release, leaving the **Language Model** field empty in Settings caused fresh installs to silently download a 7–12 GB Ollama binary (`gemma3:12b`) the user had not asked for. The default is now an empty string (`""`), and `get_llm()` raises `ValueError("LLM model not configured...")` when the field is unset for any provider that requires a model name.
+
+### Impact
+
+- **Fresh installs**: open Settings → LLM, pick a provider, and choose a model name (e.g. `llama3.1:8b` for Ollama, `gpt-4o-mini` for OpenAI, `claude-3-5-sonnet-20241022` for Anthropic). The model field shows a yellow inline warning while empty so the requirement is discoverable.
+- **Existing installs**: any user who already had `llm.model` saved (including `gemma3:12b`) keeps their value — `import_settings(overwrite=False)` at `settings/manager.py:1129` preserves any non-`None` DB value, so only fresh DBs and never-written rows pick up the new empty default.
+- The corresponding HTTP endpoint `/api/check/ollama_model` now returns HTTP 400 with `error_type: "model_not_configured"` when neither the query parameter nor `llm.model` is set, instead of silently substituting `gemma3:12b`.
+
+## BREAKING — `llamacpp` provider switched to HTTP
+
+The `llamacpp` provider no longer loads `.gguf` files in-process via `langchain_community.llms.LlamaCpp`. It now talks HTTP to llama.cpp's OpenAI-compatible `llama-server`, mirroring the LM Studio integration.
+
+### Migration steps for existing llamacpp users
+
+1. Install `llama.cpp` (https://github.com/ggerganov/llama.cpp) if you do not already have it.
+2. Start the server:
+ ```
+ llama-server -m /path/to/your/model.gguf
+ ```
+ Default port is `8080`.
+3. Open Settings → LLM and confirm `llm.llamacpp.url` is `http://localhost:8080/v1` (or wherever your server runs). Set `llm.llamacpp.api_key` only if your server is behind an auth proxy.
+4. Set `llm.model` to the model name `llama-server` is hosting (e.g. `llama-3.1-8b-instruct`).
+
+### Removed settings
+
+The four old in-process settings are gone:
+
+- `llm.llamacpp_model_path`
+- `llm.llamacpp_n_gpu_layers`
+- `llm.llamacpp_n_batch`
+- `llm.llamacpp_f16_kv`
+
+Existing rows for these keys remain in the per-user DB but are no longer read by any code path; they will be silently ignored. Tuning that previously lived in these settings now belongs to the `llama-server` command line.
+
+### New settings
+
+- `llm.llamacpp.url` — HTTP endpoint URL (default `http://localhost:8080/v1`).
+- `llm.llamacpp.api_key` — optional, only needed if you put an auth proxy in front of `llama-server`.
+
+## Cross-provider default-model cleanup
+
+All built-in providers (`anthropic`, `google`, `openrouter`, `xai`, `ionos`, `openai`, `ollama`, `lmstudio`, `llamacpp`, `openai_endpoint`) now have `default_model = ""` and refuse to silently substitute. Where a user-specified model is missing, the central check in `get_llm()` raises a `ValueError` with an actionable message naming the offending setting key. 73 tests were updated to pass `model_name=...` explicitly rather than relying on the old defaults.
+
+## Better error message when local LLM servers are not running
+
+When a user selects `llamacpp`, `lmstudio`, `openai_endpoint` (or another OpenAI-compatible provider) and the configured server is not reachable, the raw `openai`/`httpx` connection error is rewritten — by the friendly-error layer added in #4027 — into a message that names the provider and base URL, e.g. `Cannot reach <provider> at <url>. Check that the server is running and the URL is correct.` so the user sees something actionable instead of a stack trace.
+
+## Optional API keys for `lmstudio` and `llamacpp`
+
+Both providers now support an optional `api_key` setting (`llm.lmstudio.api_key`, `llm.llamacpp.api_key`) for users who put their local server behind an auth proxy. If left blank, the providers use a placeholder key that bare `llama-server` / LM Studio ignore. No action required for default setups.
+
+## Settings UI
+
+The **LLM Provider** dropdown now lists `llama.cpp (Local)` as a selectable option (it was reachable only by manual config-edit in 1.6.2). The empty-`llm.model` warning live-updates on both keystroke and dropdown selection, mirroring the API-key-not-configured pattern in `openai_base.py`.
diff --git a/src/local_deep_research/followup_research/routes.py b/src/local_deep_research/followup_research/routes.py
index 7621d32de7..b1c79cc176 100644
--- a/src/local_deep_research/followup_research/routes.py
+++ b/src/local_deep_research/followup_research/routes.py
@@ -214,6 +214,24 @@ def start_followup():
f"No password available for metrics access for user {username}"
)
+ # Pre-flight: refuse to spawn a research thread (and create an
+ # orphan ResearchHistory row) when llm.model is empty. Mirrors the
+ # empty-model check in research_routes.start_research — same
+ # contract: HTTP 400 with an actionable message before any DB
+ # writes or thread spawning. (This blueprint uses success/error
+ # response keys rather than status/message, matching the followup
+ # API convention used by the other returns in this function.)
+ if not settings_snapshot.get("llm.model", {}).get("value"):
+ logger.error(
+ "Follow-up research blocked: llm.model is not configured"
+ )
+ return jsonify(
+ {
+ "success": False,
+ "error": "Model is required. Please configure a model in the settings.",
+ }
+ ), 400
+
# Generate new research ID
research_id = str(uuid.uuid4())
diff --git a/src/local_deep_research/news/recommender/topic_based.py b/src/local_deep_research/news/recommender/topic_based.py
index a9ad773f46..80b2dc4a8b 100644
--- a/src/local_deep_research/news/recommender/topic_based.py
+++ b/src/local_deep_research/news/recommender/topic_based.py
@@ -10,6 +10,7 @@ from .base_recommender import BaseRecommender
from ..core.base_card import NewsCard
from ..core.card_factory import CardFactory
from ...search_system import AdvancedSearchSystem
+from ...security import sanitize_for_log
from ...security.egress.policy import PolicyDeniedError
@@ -87,7 +88,7 @@ class TopicBasedRecommender(BaseRecommender):
except Exception:
logger.exception(
- f"Error creating recommendation for topic '{topic}'"
+ f"Error creating recommendation for topic '{sanitize_for_log(topic)}'"
)
continue
@@ -233,8 +234,11 @@ class TopicBasedRecommender(BaseRecommender):
# not a runtime fault. Log a single concise warning per
# scheduled topic — no stack trace, since this scheduler
# runs repeatedly and we don't want to spam the log.
+ # Topic is externally derived (news content); sanitize
+ # before interpolation to prevent log injection.
logger.warning(
- f"Skipping news recommendation for topic '{topic}': "
+ f"Skipping news recommendation for topic "
+ f"'{sanitize_for_log(topic)}': "
"LLM not configured. Set llm.model in Settings."
)
return None
@@ -243,7 +247,8 @@ class TopicBasedRecommender(BaseRecommender):
# background path + non-local provider). Recurring
# scheduler — log concisely, do not retry.
logger.warning(
- f"Skipping news recommendation for topic '{topic}': "
+ f"Skipping news recommendation for topic "
+ f"'{sanitize_for_log(topic)}': "
f"LLM blocked by egress policy ({exc.decision.reason}). "
"Use a local provider (ollama/lmstudio/llamacpp) or "
"thread settings_snapshot through this caller."
@@ -259,7 +264,8 @@ class TopicBasedRecommender(BaseRecommender):
if "error" in results:
logger.error(
- f"Search failed for topic '{topic}': {results['error']}"
+ f"Search failed for topic '{sanitize_for_log(topic)}': "
+ f"{sanitize_for_log(str(results['error']))}"
)
return None
@@ -275,7 +281,9 @@ class TopicBasedRecommender(BaseRecommender):
}
if not news_items:
- logger.warning(f"No news items found for topic '{topic}'")
+ logger.warning(
+ f"No news items found for topic '{sanitize_for_log(topic)}'"
+ )
return None
# Create card using factory
@@ -313,7 +321,8 @@ class TopicBasedRecommender(BaseRecommender):
except Exception:
logger.exception(
- f"Error creating recommendation card for topic '{topic}'"
+ f"Error creating recommendation card for topic "
+ f"'{sanitize_for_log(topic)}'"
)
return None
finally:
diff --git a/tests/followup_research/test_routes_coverage.py b/tests/followup_research/test_routes_coverage.py
index 7cc25b47ba..7f0f54acc4 100644
--- a/tests/followup_research/test_routes_coverage.py
+++ b/tests/followup_research/test_routes_coverage.py
@@ -381,6 +381,61 @@ class TestStartFollowupSuccess:
assert data["message"] == "Follow-up research started"
+class TestStartFollowupModelRequired:
+ """start_followup rejects an empty llm.model before spawning anything."""
+
+ def test_empty_model_returns_400_before_spawn(self, app):
+ """Empty ``llm.model`` returns HTTP 400 with an actionable message
+ *before* any ResearchHistory row is written or worker thread spawned,
+ mirroring research_routes.start_research. Without this guard the
+ worker thread dies and leaves an orphan IN_PROGRESS row.
+ """
+ mock_service = Mock()
+ mock_service.perform_followup.return_value = {
+ "query": "follow-up question",
+ "max_iterations": 2,
+ "questions_per_iteration": 4,
+ "delegate_strategy": "source-based",
+ "research_context": {"summary": "context"},
+ "parent_research_id": "parent-1",
+ }
+
+ # Settings snapshot with an empty model — the regression under test.
+ snapshot = _fake_settings_snapshot()
+ snapshot["llm.model"] = {"value": ""}
+ mock_sm = Mock()
+ mock_sm.get_all_settings.return_value = snapshot
+
+ with (
+ patch(AUTH_DB_MANAGER, _mock_auth()),
+ patch(SETTINGS_MANAGER, return_value=mock_sm),
+ _mock_db_session_ctx(),
+ patch(
+ f"{MODULE}.FollowUpResearchService", return_value=mock_service
+ ),
+ patch(START_RESEARCH) as mock_start,
+ patch(RUN_RESEARCH) as mock_run,
+ patch(RESEARCH_HISTORY) as mock_history,
+ patch(SESSION_PWD_STORE) as mock_pwd_store,
+ ):
+ mock_pwd_store.retrieve.return_value = "secret-password"
+ resp = _authed_post(
+ app,
+ "/api/followup/start",
+ {"parent_research_id": "parent-1", "question": "details?"},
+ extra_session={"session_id": "sess-123"},
+ )
+
+ assert resp.status_code == 400
+ data = resp.get_json()
+ assert data["success"] is False
+ assert "Model is required" in data["error"]
+ # No orphan ResearchHistory row and no worker thread were created.
+ mock_history.assert_not_called()
+ mock_start.assert_not_called()
+ mock_run.assert_not_called()
+
+
# ---------------------------------------------------------------------------
# start_followup: password fallback to g.user_password (lines 251-253)
# ---------------------------------------------------------------------------
diff --git a/tests/news/test_topic_based_recommender_extended.py b/tests/news/test_topic_based_recommender_extended.py
index 2bcb1fe846..c379f92cdc 100644
--- a/tests/news/test_topic_based_recommender_extended.py
+++ b/tests/news/test_topic_based_recommender_extended.py
@@ -448,10 +448,17 @@ class TestCreateRecommendationCard:
def test_returns_none_when_llm_not_configured(self):
"""Returns None when get_llm() raises ValueError; does NOT proceed to construct
AdvancedSearchSystem. Scheduler runs repeatedly — must not propagate stack trace.
+
+ Strengthened to distinguish the specific `except ValueError` path from the
+ outer `except Exception` swallow: this asserts that the *warning* log was
+ emitted (specific path) rather than `logger.exception` (catch-all path).
+ Without this assertion, removing the targeted `except ValueError` block
+ would still let the test pass — the outer handler would also return None.
"""
from local_deep_research.news.recommender.topic_based import (
TopicBasedRecommender,
)
+ from local_deep_research.security import sanitize_for_log
with (
patch(
@@ -460,20 +467,40 @@ class TestCreateRecommendationCard:
patch(
"local_deep_research.news.recommender.topic_based.AdvancedSearchSystem"
) as MockSearch,
+ patch(
+ "local_deep_research.news.recommender.topic_based.logger"
+ ) as mock_logger,
):
mock_get_llm.side_effect = ValueError(
"LLM model not configured. ..."
)
+ # Topic carries a CRLF log-injection payload; the warning must
+ # interpolate the *sanitized* form. Binding it to a variable (and
+ # deriving the expected substring from it) removes the previous
+ # assertion's coupling to a hard-coded "AI" literal.
+ topic = "AI\r\ninjected-fake-log-line"
recommender = TopicBasedRecommender()
result = recommender._create_recommendation_card(
- "AI", "query", "user1"
+ topic, "query", "user1"
)
assert result is None
mock_get_llm.assert_called_once()
# Critical: we returned before building the search system.
MockSearch.assert_not_called()
+ # The targeted except-ValueError path uses logger.warning; the
+ # catch-all `except Exception` would use logger.exception. Asserting
+ # warning was called and exception was NOT pins the code path.
+ mock_logger.warning.assert_called_once()
+ warning_msg = mock_logger.warning.call_args[0][0]
+ assert "LLM not configured" in warning_msg
+ # The sanitized topic is interpolated; the raw CR/LF payload never
+ # reaches the log line (this is the log-injection guarantee).
+ assert sanitize_for_log(topic) in warning_msg
+ assert "\r" not in warning_msg
+ assert "\n" not in warning_msg
+ mock_logger.exception.assert_not_called()
class TestSearchBasedRecommender: