feat(realism/llm): GET/PUT /api/v1/realism/llm + worker hot-reload tick

decnet/orchestrator/worker.py

@@ -129,6 +129,7 @@ async def orchestrator_worker(
     # operator's intent rather than the baked-in defaults. A failure
     # here logs and falls through; the planner already holds defaults.
     await _refresh_realism_config(repo)
+    await _refresh_llm_config(repo)
 
     shutdown = asyncio.Event()
     heartbeat_task = asyncio.create_task(
@@ -161,6 +162,7 @@ async def orchestrator_worker(
                 await _periodic_prune(repo)
             if tick_n % _REALISM_CONFIG_REFRESH_TICKS == 0:
                 await _refresh_realism_config(repo)
+                await _refresh_llm_config(repo)
     finally:
         for t in (heartbeat_task, control_task, probe_task):
             t.cancel()
@@ -223,6 +225,18 @@ async def _refresh_realism_config(repo: BaseRepository) -> None:
         logger.warning("realism config refresh: rejected payload: %s", exc)
 
 
+async def _refresh_llm_config(repo: BaseRepository) -> None:
+    """Pull operator-tuned LLM config from realism_config into the backend cache."""
+    from decnet.realism.llm.config import apply, load_from_db
+    cfg = await load_from_db(repo)
+    if cfg is None:
+        return
+    try:
+        apply(cfg)
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("llm config refresh: apply failed: %s", exc)
+
+
 def _roll_action_kind(rng: secrets.SystemRandom) -> str:
     total = sum(w for _, w in _ACTION_WEIGHTS)
     target = rng.randint(1, total)

decnet/realism/llm/config.py

@@ -83,8 +83,14 @@ def apply(cfg: LLMConfig) -> None:
     if cfg.provider == "ollama":
         api_key: Optional[str] = None
         if cfg.api_key_ciphertext:
-            from decnet.web.db.secrets import decrypt_secret
-            api_key = decrypt_secret(cfg.api_key_ciphertext)
+            try:
+                from decnet.web.db.secrets import decrypt_secret
+                api_key = decrypt_secret(cfg.api_key_ciphertext)
+            except RuntimeError as exc:
+                log.warning(
+                    "realism.llm.config: DECNET_SECRET_KEY unavailable, "
+                    "api_key will not be passed to backend: %s", exc,
+                )
 
         from decnet.realism.llm.impl.ollama import OllamaBackend
         _cached_backend = OllamaBackend(

decnet/web/router/__init__.py

@@ -40,6 +40,7 @@ from .orchestrator.api_list_events import router as orchestrator_list_router
 from .orchestrator.api_events import router as orchestrator_events_router
 from .orchestrator.api_event_stats import router as orchestrator_stats_router
 from .realism.api_config import router as realism_config_router
+from .realism.api_llm import router as realism_llm_router
 from .realism.api_personas import router as realism_personas_router
 from .realism.api_synthetic_files import router as realism_synthetic_files_router
 from .transcripts import transcripts_router
@@ -145,6 +146,7 @@ api_router.include_router(orchestrator_stats_router)
 api_router.include_router(realism_personas_router)
 api_router.include_router(realism_synthetic_files_router)
 api_router.include_router(realism_config_router)
+api_router.include_router(realism_llm_router)
 
 # Observability
 api_router.include_router(stats_router)

decnet/web/router/realism/api_llm.py

@@ -0,0 +1,173 @@
+"""GET/PUT ``/api/v1/realism/llm`` — LLM provider configuration.
+
+Reads accept viewer; writes are admin (same trust level as the existing
+``/realism/config`` surface — LLM provider config controls all AI-generated
+honeypot content).
+
+GET returns the current config **without** the encrypted API key — only
+``api_key_set: bool`` is surfaced so the operator can see whether one is
+stored without ever exfiltrating it.
+
+PUT body fields (all optional — unset fields keep their current value):
+
+* ``provider``:  ``"ollama"`` (only supported provider today)
+* ``base_url``:  Ollama daemon URL, or ``""``/``null`` to clear
+* ``model``:     Ollama model tag
+* ``timeout``:   Generation timeout in seconds (float, > 0)
+* ``api_key``:   Plaintext; ``null`` / absent = leave unchanged, ``""`` = clear
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from decnet.logging import get_logger
+from decnet.realism.llm import config as llm_config
+from decnet.realism.llm.config import LLMConfig, _CONFIG_KEY
+from decnet.telemetry import traced as _traced
+from decnet.web.dependencies import repo, require_admin, require_viewer
+
+router = APIRouter()
+log = get_logger("api.realism.llm")
+
+_hydrated = False
+_hydrate_lock = asyncio.Lock()
+
+_SENTINEL = object()
+
+
+def _cfg_to_response(cfg: LLMConfig, api_key_set: bool) -> dict[str, Any]:
+    return {
+        "provider": cfg.provider,
+        "base_url": cfg.base_url,
+        "model": cfg.model,
+        "timeout": cfg.timeout,
+        "api_key_set": api_key_set,
+    }
+
+
+async def _load_and_apply_from_db() -> LLMConfig:
+    """Load DB row into process cache; return current effective config."""
+    cfg = await llm_config.load_from_db(repo)
+    if cfg is not None:
+        try:
+            llm_config.apply(cfg)
+        except Exception as exc:  # noqa: BLE001
+            log.warning("api.realism.llm: apply on hydrate failed: %s", exc)
+    return cfg or LLMConfig()
+
+
+@router.get(
+    "/realism/llm",
+    tags=["Realism"],
+    responses={
+        401: {"description": "Could not validate credentials"},
+        403: {"description": "Insufficient permissions"},
+    },
+)
+@_traced("api.realism.get_llm")
+async def get_llm_config(
+    user: dict = Depends(require_viewer),
+) -> dict[str, Any]:
+    """Return the live LLM provider config (API key masked as ``api_key_set``)."""
+    global _hydrated
+    if not _hydrated:
+        async with _hydrate_lock:
+            if not _hydrated:
+                await _load_and_apply_from_db()
+                _hydrated = True
+
+    row = await repo.get_realism_config(_CONFIG_KEY)
+    if row is not None:
+        try:
+            stored: dict[str, Any] = json.loads(row.get("value") or "{}")
+        except json.JSONDecodeError:
+            stored = {}
+    else:
+        stored = {}
+
+    cfg = LLMConfig(**stored) if stored else LLMConfig()
+    api_key_set = bool(stored.get("api_key_ciphertext"))
+    return _cfg_to_response(cfg, api_key_set)
+
+
+@router.put(
+    "/realism/llm",
+    tags=["Realism"],
+    responses={
+        400: {"description": "Invalid config payload"},
+        401: {"description": "Could not validate credentials"},
+        403: {"description": "Insufficient permissions"},
+    },
+)
+@_traced("api.realism.put_llm")
+async def put_llm_config(
+    body: dict[str, Any],
+    user: dict = Depends(require_admin),
+) -> dict[str, Any]:
+    """Replace LLM provider config.  Persists and hot-reloads the backend.
+
+    ``api_key`` handling:
+
+    * absent or not in body → leave existing encrypted key unchanged
+    * ``null`` or ``""``    → clear the stored key
+    * non-empty string      → encrypt and store
+    """
+    global _hydrated
+
+    if not isinstance(body, dict):
+        raise HTTPException(status_code=400, detail="body must be an object")
+
+    # Load the current persisted config so we can merge partial updates.
+    row = await repo.get_realism_config(_CONFIG_KEY)
+    current: dict[str, Any] = {}
+    if row is not None:
+        try:
+            current = json.loads(row.get("value") or "{}") or {}
+        except json.JSONDecodeError:
+            current = {}
+
+    api_key_raw: Any = body.pop("api_key", _SENTINEL)
+
+    # Merge incoming fields over the current persisted state.
+    merged = {**current, **body}
+
+    # Handle api_key: absent=keep, null/empty=clear, string=encrypt.
+    if api_key_raw is _SENTINEL:
+        pass  # leave current api_key_ciphertext in merged unchanged
+    elif not api_key_raw:
+        merged.pop("api_key_ciphertext", None)
+    else:
+        try:
+            from decnet.web.db.secrets import encrypt_secret
+            merged["api_key_ciphertext"] = encrypt_secret(str(api_key_raw))
+        except RuntimeError as exc:
+            raise HTTPException(
+                status_code=500,
+                detail=f"Secret encryption unavailable: {exc}",
+            ) from exc
+
+    try:
+        cfg = LLMConfig(**merged)
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    try:
+        llm_config.apply(cfg)
+    except Exception as exc:
+        raise HTTPException(
+            status_code=400, detail=f"Backend init failed: {exc}"
+        ) from exc
+
+    await repo.set_realism_config(_CONFIG_KEY, json.dumps(merged))
+    _hydrated = True
+
+    log.info(
+        "api.realism.put_llm user=%s provider=%s model=%s base_url=%s",
+        user.get("username", user.get("uuid")),
+        cfg.provider, cfg.model, cfg.base_url,
+    )
+    return _cfg_to_response(cfg, bool(merged.get("api_key_ciphertext")))