phase: 172_thinking_level

All verification complete. Final report:

**Phase 172 final verification pass — all tasks (01–05) were already complete; verified the whole phase, no code fixes needed.**

- **Verified implementation:** `Settings.llm_thinking_level: str = "low"` + `CATALOG` row (`LLM (aipi)` / "Thinking level", plain: not secret/restart/overridable-exempt) + `.env.example` line under `BOR_LLM_CHAT_MODEL` + README table row; `_thinking_extra_body()` → `reasoning_effort` via `extra_body` on `chat()` + `chat_stream()` when trimmed-non-empty, key absent (byte-identical) when empty, embeddings untouched; per-turn line gains `thinking=<value>` (`-` when empty) before `thinking_chars`.
- **Tests/lint/coverage (all green):** `uv run pytest` → 4084 passed · `uv run pytest --cov=app --cov-report=term-missing` → 4084 passed, `app/` **99%** (>90%) · `uv run ruff check .` → All checks passed · `uv run pyright` → 0 errors, 0 warnings.
- **Completion criteria:** (1) `pytest -k "config and thinking"` 4 passed + `.env.example` grep ✓ (2) live `GET /api/admin/settings` curl shows the row (str, `low`, `default`) + integration PUT/DELETE round-trip ✓ (3) 9 mocked-client unit tests assert `extra_body` present/absent ✓ (4) log-line tests assert `low`/`high`/`-`/whitespace ✓ (5) suite + coverage + lint ✓ (6) `test_thinking_level.py` 3/3 in isolation; `test_admin_settings_panel.py` 12/12; `test_admin_settings_layout.py` 5/5 ✓ (7) atomic commit + phase move = the harness's job (task files already in `complete/`; I ran no git index/history commands).
- **Documentation:** README.md reviewed in full — verified consistent (env table complete vs `.env.example`, catalog restart/non-overridable claims re-verified at runtime); AGENTS.md reviewed in full — verified consistent (no rule affected, A5 = no UI change). No changes needed. **Flag (not fixable here):** PLAN.md §9's per-turn-line spec predates the phase-172 `thinking=` field; PLAN.md is off-limits per protocol.
- **Next pending phase:** none — `todo/` contains only phase 172 (the harness moves it on this pass's success).

app/api/chat.py

@@ -13,7 +13,10 @@ model's reasoning arrives ahead of the answer and is streamed as
 ``thinking`` events before the ``delta`` events of the same turn. Each
 turn's thinking is counted in the per-turn log line
 (``thinking_chars=N``); ``BOR_STREAM_THINKING=0`` suppresses the
-``thinking`` frames (the pieces are still counted).
+``thinking`` frames (the pieces are still counted). The per-turn log
+line records ``thinking=<level>`` (the effective
+``BOR_LLM_THINKING_LEVEL``, trimmed, ``-`` when empty) before
+``thinking_chars`` (phase 172, A6).
 
 Honesty gate (A8, revised 2026-09-14): LOW — deflection — only when
 ``best_cosine < BOR_RELEVANCE_THRESHOLD`` **and** (``fts_hits == 0``
@@ -1269,8 +1272,8 @@ async def chat(
                     "question=%r embed_ms=%d top_score=%.3f fts_hits=%d summary_hits=%d "
                     "suggested=%d tuning=%d "
                     "kb_chars=%d history_msgs=%d threshold=%.2f deflected=%s sources=%r "
-                    "thinking_chars=%d tool_calls=%d rounds=%d cap_hit=%d total_ms=%d "
-                    "retries=%d scaffold_stripped=%d",
+                    "thinking=%s thinking_chars=%d tool_calls=%d rounds=%d "
+                    "cap_hit=%d total_ms=%d retries=%d scaffold_stripped=%d",
                     request.message,
                     embed_ms,
                     plan.top_score,
@@ -1283,6 +1286,7 @@ async def chat(
                     settings.relevance_threshold,
                     plan.deflected,
                     source_paths,
+                    settings.llm_thinking_level.strip() or "-",  # phase 172 (A6)
                     thinking_chars,
                     holder.tool_calls,
                     holder.rounds,

app/config.py

@@ -105,6 +105,14 @@ class Settings(BaseSettings):
     #: Served by the same OpenAI-compatible endpoint — no new model
     #: management. Called via ``LLMClient.chat()``.
     llm_summary_model: str = "lite"
+    #: The model's thinking level (phase 172, ``BOR_LLM_THINKING_LEVEL``) —
+    #: pi-style reasoning effort, free-form text exactly like
+    #: ``llm_chat_model`` (no allowlist — the endpoint is the source of
+    #: truth). Default ``low``. Rides every chat-completions request to
+    #: aipi as the top-level ``reasoning_effort`` parameter
+    #: (``app/rag/llm.py``); the EMPTY value is the off switch — the
+    #: parameter is not sent at all.
+    llm_thinking_level: str = "low"
     #: Operator kill-switch for the ``thinking`` SSE events (phase 17,
     #: ``BOR_STREAM_THINKING``; ``0``/``false`` → off). When off, thinking
     #: pieces are still counted for the per-turn log line but never

app/core/settings_catalog.py

@@ -150,6 +150,9 @@ CATALOG: dict[str, SettingMeta] = {
     "llm_summary_model": SettingMeta(
         "llm_summary_model", "LLM (aipi)", "LLM summary model"
     ),
+    "llm_thinking_level": SettingMeta(
+        "llm_thinking_level", "LLM (aipi)", "Thinking level"
+    ),
     "stream_thinking": SettingMeta(
         "stream_thinking", "LLM (aipi)", "Stream thinking"
     ),

app/rag/llm.py

@@ -10,7 +10,13 @@ pipeline. Chat streaming yields typed :class:`StreamPiece` values
 its reasoning as ``delta.reasoning_content`` chunks (deepseek/litellm
 wire convention, verified live 2026-08-23) **before** the answer's
 ``delta.content`` chunks, and reasoning counts against ``max_tokens``
-(an answer can in principle be empty).
+(an answer can in principle be empty). The operator's thinking level
+(phase 172, ``BOR_LLM_THINKING_LEVEL``, default ``low``) rides every
+chat-completions request (one-shot ``chat`` and streaming ``chat_stream``)
+as the top-level ``reasoning_effort`` parameter (via the SDK's
+``extra_body``); an empty value is the off switch — the parameter is
+absent, the request is byte-identical to pre-phase-172, and the
+embeddings path never carries it.
 
 Fail-loud rule (PLAN A6): the ``chunks.embedding`` column is fixed at 768
 dimensions when the table is created, so a model that returns a different
@@ -40,6 +46,17 @@ if TYPE_CHECKING:
 logger = logging.getLogger("app.llm")
 
 
+def _thinking_extra_body(settings: Settings) -> dict[str, str] | None:
+    """The phase-172 thinking level as the chat-completions extra body.
+
+    Non-empty (trimmed) value → ``{"reasoning_effort": <value>}`` (the
+    OpenAI-standard top-level parameter, A1); empty/whitespace → ``None``
+    (the off switch — the parameter is ABSENT from the request, A2).
+    """
+    level = settings.llm_thinking_level.strip()
+    return {"reasoning_effort": level} if level else None
+
+
 class EmbeddingError(RuntimeError):
     """The embeddings endpoint failed (network, HTTP, or malformed reply)."""
 
@@ -412,6 +429,10 @@ class LLMClient:
         ``finish_reason``) for an empty reply — the one failure class
         :meth:`chat` retries — and :class:`LLMError` for everything else.
         """
+        extra = _thinking_extra_body(self.settings)
+        extra_kwargs: dict[str, Any] = (
+            {"extra_body": extra} if extra is not None else {}
+        )
         try:
             resp = await self._client.chat.completions.create(
                 model=model,
@@ -419,6 +440,9 @@ class LLMClient:
                 temperature=0.2,
                 max_tokens=2048,
                 stream=False,
+                # Phase 172 (A1/A2): the thinking level rides as
+                # reasoning_effort; the key is absent (never None) when off.
+                **extra_kwargs,
             )
         except LLMError:
             raise
@@ -598,6 +622,10 @@ class LLMClient:
         }
         if tools is not None:
             kwargs["tools"] = tools
+        if (extra := _thinking_extra_body(self.settings)) is not None:
+            # Phase 172 (A1/A2): the thinking level rides as
+            # reasoning_effort; the key is absent (never None) when off.
+            kwargs["extra_body"] = extra
         stream: AsyncStream[ChatCompletionChunk] | None = None
         try:
             stream = cast(