feat: user-facing temperature setting (#2275)

* feat: user-facing temperature setting for LLM requests

Add a configurable default sampling temperature (0.0–2.0) that users
can set via the web settings UI or API. The setting flows into the
main conversational agent loop via ReasoningContext, replacing the
hardcoded 0.7 default. Per-request temperature (e.g. from the
OpenAI-compatible endpoint) still takes precedence.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: admin-scoped settings fallback for multi-tenant

Admin-set defaults now propagate to all members who haven't overridden
the value themselves. Three layers of change:

1. TenantScope::get_setting_with_admin_fallback() — checks user scope
   first, then falls back to __admin__ scope. Used by the dispatcher
   for temperature and selected_model.

2. Config::from_db_with_toml() — layers admin-scope settings between
   TOML and per-user DB settings during resolution. Priority:
   TOML < admin DB < per-user DB.

3. Settings API — GET/PUT/DELETE /api/settings/{key}?scope=admin lets
   admins read/write to the shared default scope. Non-admins get 403.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: clamp temperature to 0.0-2.0 before reaching provider

Address review comment on #2275: the backend must guard against
bad DB values and per-request overrides that bypass the frontend
range enforcement. Some providers reject out-of-range temperatures
outright.

Clamped at both the read site (dispatcher reading DB settings) and
the use site (reasoning.rs respond_with_tools) for defense in depth.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: address PR #2275 review feedback

- Strip admin-only LLM keys (ollama_base_url, openai_compatible_base_url,
  llm_builtin_overrides, llm_custom_providers) from the admin-scope merge
  in `Config::from_db_with_toml` and `Config::re_resolve_llm_with_secrets`
  when the resolving user is not an operator. Defense-in-depth so a
  non-admin member never inherits private/loopback provider endpoints
  from admin defaults.
- Preserve per-request `reason_ctx.temperature` precedence in the
  dispatcher: settings-derived temperature only applies when no value
  was already set by the API caller. Extract `resolve_settings_temperature`
  helper for direct unit testing.
- Add regression tests covering admin-scope strip behavior for both
  operator and non-operator paths, plus the temperature precedence rule
  including range clamping.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ilblackdragon

crates/ironclaw_gateway/static/app.js

@@ -7084,6 +7084,12 @@ function loadSettingsSubtab(subtab) {
 // --- Structured Settings Definitions ---
 
 var INFERENCE_SETTINGS = [
+  {
+    group: 'cfg.group.inference',
+    settings: [
+      { key: 'temperature', label: 'cfg.temperature.label', description: 'cfg.temperature.desc', type: 'float', min: 0, max: 2, step: 0.1 },
+    ]
+  },
   {
     group: 'cfg.group.embeddings',
     settings: [
@@ -7429,25 +7435,25 @@ function renderStructuredSettingsRow(def, value, activeValue) {
       return function() { saveSetting(k, el.value === '' ? null : el.value); };
     })(def.key, sel));
     inputWrap.appendChild(sel);
-  } else if (def.type === 'number') {
+  } else if (def.type === 'number' || def.type === 'float') {
     var numInp = document.createElement('input');
     numInp.type = 'number';
-    numInp.step = '1';
+    numInp.step = def.step !== undefined ? String(def.step) : (def.type === 'float' ? 'any' : '1');
     numInp.className = 'settings-input';
     numInp.setAttribute('aria-label', ariaLabel);
     numInp.value = (value === null || value === undefined) ? '' : value;
     if (!value && value !== 0) numInp.placeholder = placeholderText;
     if (def.min !== undefined) numInp.min = def.min;
     if (def.max !== undefined) numInp.max = def.max;
-    numInp.addEventListener('change', (function(k, el) {
+    numInp.addEventListener('change', (function(k, el, isFloat) {
       return function() {
         if (el.value === '') return saveSetting(k, null);
-        var parsed = parseInt(el.value, 10);
+        var parsed = isFloat ? parseFloat(el.value) : parseInt(el.value, 10);
         if (isNaN(parsed)) return;
         el.value = parsed;
         saveSetting(k, parsed);
       };
-    })(def.key, numInp));
+    })(def.key, numInp, def.type === 'float'));
     inputWrap.appendChild(numInp);
   } else if (def.type === 'list') {
     var listInp = document.createElement('input');

crates/ironclaw_gateway/static/i18n/en.js

@@ -521,6 +521,9 @@ I18n.register('en', {
   'cfg.llm_backend.desc': 'LLM inference provider',
   'cfg.selected_model.label': 'Model',
   'cfg.selected_model.desc': 'Model name or ID for the selected backend',
+  'cfg.temperature.label': 'Temperature',
+  'cfg.temperature.desc': 'Default sampling temperature (0.0–2.0). Lower = more deterministic, higher = more creative',
+  'cfg.group.inference': 'Inference',
   'cfg.ollama_base_url.label': 'Ollama URL',
   'cfg.ollama_base_url.desc': 'Base URL for Ollama API',
   'cfg.openai_compatible_base_url.label': 'OpenAI-compatible URL',

crates/ironclaw_gateway/static/i18n/ko.js

@@ -520,6 +520,9 @@ I18n.register('ko', {
   'cfg.llm_backend.desc': 'LLM 추론 공급자',
   'cfg.selected_model.label': '모델',
   'cfg.selected_model.desc': '선택한 백엔드의 모델 이름 또는 ID',
+  'cfg.temperature.label': '온도',
+  'cfg.temperature.desc': '기본 샘플링 온도 (0.0–2.0). 낮을수록 결정적, 높을수록 창의적',
+  'cfg.group.inference': '추론',
   'cfg.ollama_base_url.label': 'Ollama URL',
   'cfg.ollama_base_url.desc': 'Ollama API의 베이스 URL',
   'cfg.openai_compatible_base_url.label': 'OpenAI 호환 URL',

crates/ironclaw_gateway/static/i18n/zh-CN.js

@@ -520,6 +520,9 @@ I18n.register('zh-CN', {
   'cfg.llm_backend.desc': 'LLM 推理提供商',
   'cfg.selected_model.label': '模型',
   'cfg.selected_model.desc': '所选后端的模型名称或 ID',
+  'cfg.temperature.label': '温度',
+  'cfg.temperature.desc': '默认采样温度（0.0–2.0）。越低越确定性，越高越有创意',
+  'cfg.group.inference': '推理',
   'cfg.ollama_base_url.label': 'Ollama URL',
   'cfg.ollama_base_url.desc': 'Ollama API 基础 URL',
   'cfg.openai_compatible_base_url.label': 'OpenAI 兼容 URL',

src/agent/dispatcher.rs

@@ -27,6 +27,24 @@ fn selected_model_override(value: &serde_json::Value) -> Option<String> {
     crate::llm::normalized_model_override(value.as_str()).map(str::to_string)
 }
 
+/// Decide whether a settings-derived temperature should override the
+/// per-request value already on the reasoning context.
+///
+/// Returns `Some(new_value)` only when there is no per-request value yet
+/// AND the settings value parses as a number. The result is clamped to the
+/// supported `[0.0, 2.0]` range to guard against bad DB values.
+fn resolve_settings_temperature(
+    current: Option<f32>,
+    settings_value: Option<&serde_json::Value>,
+) -> Option<f32> {
+    if current.is_some() {
+        return None;
+    }
+    settings_value
+        .and_then(|v| v.as_f64())
+        .map(|t| (t as f32).clamp(0.0, 2.0))
+}
+
 /// Result of the agentic loop execution.
 pub(super) enum AgenticLoopResult {
     /// Completed with a response.
@@ -583,16 +601,31 @@ impl<'a> LoopDelegate for ChatDelegate<'a> {
             .into());
         }
 
-        // Apply per-user model override from settings (first iteration only
+        // Apply per-user overrides from settings (first iteration only
         // to avoid repeated DB lookups within the same agentic loop).
-        // Uses "selected_model" — the same key the /model command persists to
-        // via SettingsStore (per-user scoped via TenantScope).
+        // Uses admin-fallback so admin-set defaults propagate to members
+        // who haven't overridden the value themselves.
         if iteration == 0
             && let Some(store) = self.tenant.store()
-            && let Ok(Some(value)) = store.get_setting("selected_model").await
-            && let Some(model) = selected_model_override(&value)
         {
-            reason_ctx.model_override = Some(model);
+            // Model override: "selected_model" — the same key the /model command
+            // persists to via SettingsStore (per-user scoped via TenantScope).
+            if let Ok(Some(value)) = store
+                .get_setting_with_admin_fallback("selected_model")
+                .await
+                && let Some(model) = selected_model_override(&value)
+            {
+                reason_ctx.model_override = Some(model);
+            }
+
+            // Temperature override from user or admin settings. Per-request
+            // values already on the context take precedence over settings.
+            if let Ok(setting) = store.get_setting_with_admin_fallback("temperature").await
+                && let Some(t) =
+                    resolve_settings_temperature(reason_ctx.temperature, setting.as_ref())
+            {
+                reason_ctx.temperature = Some(t);
+            }
         }
 
         let output = match reasoning.respond_with_tools(reason_ctx).await {
@@ -1693,7 +1726,8 @@ mod tests {
 
     use super::{
         capture_auth_prompt, check_auth_required, extract_auth_prompt, parse_auth_result,
-        persist_selected_auth_prompt, restore_selected_auth_prompt, selected_model_override,
+        persist_selected_auth_prompt, resolve_settings_temperature, restore_selected_auth_prompt,
+        selected_model_override,
     };
     use crate::agent::session::PendingAuthPrompt;
 
@@ -3041,6 +3075,47 @@ mod tests {
         }
     }
 
+    #[test]
+    fn resolve_settings_temperature_keeps_per_request_value() {
+        // Regression: a per-request temperature already on the context must
+        // win over a settings-derived value, otherwise API callers cannot
+        // override the user/admin default for a single call.
+        assert_eq!(
+            resolve_settings_temperature(Some(0.42), Some(&serde_json::json!(1.5))),
+            None,
+            "must not return Some when current is set"
+        );
+    }
+
+    #[test]
+    fn resolve_settings_temperature_uses_settings_when_unset() {
+        assert_eq!(
+            resolve_settings_temperature(None, Some(&serde_json::json!(0.9))),
+            Some(0.9),
+        );
+    }
+
+    #[test]
+    fn resolve_settings_temperature_clamps_out_of_range_db_value() {
+        assert_eq!(
+            resolve_settings_temperature(None, Some(&serde_json::json!(9.0))),
+            Some(2.0),
+        );
+        assert_eq!(
+            resolve_settings_temperature(None, Some(&serde_json::json!(-1.0))),
+            Some(0.0),
+        );
+    }
+
+    #[test]
+    fn resolve_settings_temperature_returns_none_when_settings_missing() {
+        assert_eq!(resolve_settings_temperature(None, None), None);
+        assert_eq!(
+            resolve_settings_temperature(None, Some(&serde_json::json!("not-a-number"))),
+            None,
+        );
+    }
+
     #[test]
     fn selected_model_override_ignores_default_sentinel() {
         assert_eq!(selected_model_override(&serde_json::json!("default")), None);

src/channels/web/handlers/settings.rs

@@ -4,7 +4,7 @@ use std::sync::Arc;
 
 use axum::{
     Json,
-    extract::{Path, State},
+    extract::{Path, Query, State},
     http::StatusCode,
 };
 use secrecy::SecretString;
@@ -17,6 +17,31 @@ use crate::secrets::{CreateSecretParams, SecretsStore};
 /// Sentinel value the frontend sends to mean "key is unchanged, don't touch it".
 const API_KEY_UNCHANGED: &str = "••••••••";
 
+/// Resolve the effective user_id for a settings operation.
+///
+/// When `scope=admin`, the operation targets the shared admin-default scope
+/// (`__admin__`). Only admin users may use this scope; non-admins get 403.
+/// Without the scope parameter (or any other value), operations target the
+/// calling user's own settings.
+fn resolve_settings_scope(
+    user: &crate::channels::web::auth::UserIdentity,
+    query: &SettingScopeQuery,
+) -> Result<String, StatusCode> {
+    if query.scope.as_deref() == Some("admin") {
+        if user.role != "admin" {
+            tracing::warn!(
+                user_id = %user.user_id,
+                role = %user.role,
+                "Non-admin attempted to use scope=admin on settings endpoint"
+            );
+            return Err(StatusCode::FORBIDDEN);
+        }
+        Ok(crate::tools::permissions::ADMIN_SETTINGS_USER_ID.to_string())
+    } else {
+        Ok(user.user_id.clone())
+    }
+}
+
 pub async fn settings_list_handler(
     State(state): State<Arc<GatewayState>>,
     AuthenticatedUser(user): AuthenticatedUser,
@@ -68,13 +93,16 @@ pub async fn settings_get_handler(
     State(state): State<Arc<GatewayState>>,
     AuthenticatedUser(user): AuthenticatedUser,
     Path(key): Path<String>,
+    Query(query): Query<SettingScopeQuery>,
 ) -> Result<Json<SettingResponse>, StatusCode> {
+    let effective_user_id = resolve_settings_scope(&user, &query)?;
+
     let store = state
         .store
         .as_ref()
         .ok_or(StatusCode::SERVICE_UNAVAILABLE)?;
     let row = store
-        .get_setting_full(&user.user_id, &key)
+        .get_setting_full(&effective_user_id, &key)
         .await
         .map_err(|e| {
             tracing::error!("Failed to get setting '{}': {}", key, e);
@@ -88,7 +116,7 @@ pub async fn settings_get_handler(
         "llm_builtin_overrides" | "llm_custom_providers"
     ) {
         let mut map = std::collections::HashMap::from([(key.clone(), row.value.clone())]);
-        annotate_secret_key_presence(&state, &user.user_id, &mut map).await;
+        annotate_secret_key_presence(&state, &effective_user_id, &mut map).await;
         mask_settings_api_keys(&mut map);
         map.remove(&key).unwrap_or(row.value)
     } else {
@@ -106,8 +134,10 @@ pub async fn settings_set_handler(
     State(state): State<Arc<GatewayState>>,
     AuthenticatedUser(user): AuthenticatedUser,
     Path(key): Path<String>,
+    Query(query): Query<SettingScopeQuery>,
     Json(body): Json<SettingWriteRequest>,
 ) -> Result<StatusCode, StatusCode> {
+    let effective_user_id = resolve_settings_scope(&user, &query)?;
     ensure_setting_write_allowed(&user, &key)?;
 
     let store = state
@@ -117,24 +147,24 @@ pub async fn settings_set_handler(
 
     // Guard: cannot remove a custom provider that is currently active.
     if key == "llm_custom_providers" {
-        guard_active_provider_not_removed(store, &user.user_id, &body.value).await?;
+        guard_active_provider_not_removed(store, &effective_user_id, &body.value).await?;
         validate_custom_providers(&body.value)?;
     }
 
     // Extract API keys from LLM settings and vault them in the secrets store.
     // The sanitized value has api_key fields removed (stored encrypted instead).
     let sanitized_value = match key.as_str() {
         "llm_builtin_overrides" => {
-            extract_builtin_override_keys(&state, &user.user_id, &body.value).await?
+            extract_builtin_override_keys(&state, &effective_user_id, &body.value).await?
         }
         "llm_custom_providers" => {
-            extract_custom_provider_keys(&state, &user.user_id, &body.value).await?
+            extract_custom_provider_keys(&state, &effective_user_id, &body.value).await?
         }
         _ => body.value.clone(),
     };
 
     store
-        .set_setting(&user.user_id, &key, &sanitized_value)
+        .set_setting(&effective_user_id, &key, &sanitized_value)
         .await
         .map_err(|e| {
             tracing::error!("Failed to set setting '{}': {}", key, e);
@@ -241,7 +271,9 @@ pub async fn settings_delete_handler(
     State(state): State<Arc<GatewayState>>,
     AuthenticatedUser(user): AuthenticatedUser,
     Path(key): Path<String>,
+    Query(query): Query<SettingScopeQuery>,
 ) -> Result<StatusCode, StatusCode> {
+    let effective_user_id = resolve_settings_scope(&user, &query)?;
     ensure_setting_write_allowed(&user, &key)?;
 
     let store = state
@@ -252,12 +284,16 @@ pub async fn settings_delete_handler(
     // Guard: deleting llm_custom_providers is equivalent to setting it to [].
     // Reject if the active backend is a custom provider that would be removed.
     if key == "llm_custom_providers" {
-        guard_active_provider_not_removed(store, &user.user_id, &serde_json::Value::Array(vec![]))
-            .await?;
+        guard_active_provider_not_removed(
+            store,
+            &effective_user_id,
+            &serde_json::Value::Array(vec![]),
+        )
+        .await?;
     }
 
     store
-        .delete_setting(&user.user_id, &key)
+        .delete_setting(&effective_user_id, &key)
         .await
         .map_err(|e| {
             tracing::error!("Failed to delete setting '{}': {}", key, e);
@@ -1217,6 +1253,7 @@ mod tests {
                 workspace_read_scopes: Vec::new(),
             }),
             Path("ollama_base_url".to_string()),
+            Query(SettingScopeQuery::default()),
             Json(SettingWriteRequest {
                 value: serde_json::json!("http://192.168.1.50:11434"),
             }),
@@ -1240,6 +1277,7 @@ mod tests {
                 workspace_read_scopes: Vec::new(),
             }),
             Path("llm_custom_providers".to_string()),
+            Query(SettingScopeQuery::default()),
         )
         .await
         .unwrap_err();

src/channels/web/responses_api.rs

@@ -610,7 +610,7 @@ pub async fn create_response_handler(
     if req.temperature.is_some() {
         return Err(api_error(
             StatusCode::BAD_REQUEST,
-            "The 'temperature' field is not yet supported",
+            "Per-request 'temperature' is not supported on this endpoint; configure the default via settings",
             "invalid_request_error",
         ));
     }

src/channels/web/types.rs

@@ -911,6 +911,14 @@ pub struct SettingWriteRequest {
     pub value: serde_json::Value,
 }
 
+/// Query parameters for settings endpoints.
+/// `?scope=admin` writes to / reads from the admin-default scope.
+#[derive(Debug, Default, Deserialize)]
+pub struct SettingScopeQuery {
+    #[serde(default)]
+    pub scope: Option<String>,
+}
+
 #[derive(Debug, Deserialize)]
 pub struct SettingsImportRequest {
     pub settings: std::collections::HashMap<String, serde_json::Value>,