feat(realism/llm): DB-backed LLMConfig, factory DB-first dispatch, Ollama HTTP mode

decnet/realism/llm/config.py

@@ -0,0 +1,123 @@
+"""DB-backed LLM provider configuration for the realism subsystem.
+
+The module holds a process-level cached backend that callers obtain via
+:func:`decnet.realism.llm.factory.get_llm`.  The cache is populated by:
+
+* The API process: :func:`load_from_db` called on first GET, then
+  ``apply`` on each successful PUT.
+* The orchestrator worker: :func:`load_from_db` called on the same
+  periodic tick that refreshes planner weights.
+
+``get_llm()`` falls back to the env-var path when the cache is ``None``
+(i.e. the DB row does not exist yet or has never been loaded).
+"""
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+from decnet.logging import get_logger
+
+log = get_logger("realism.llm.config")
+
+_SUPPORTED_PROVIDERS = {"ollama", "fake"}
+_HTTP_RE = re.compile(r"^https?://", re.IGNORECASE)
+
+# Process-level singleton — rebuilt by apply(), read by get_llm().
+_cached_backend: Optional[Any] = None
+
+_CONFIG_KEY = "llm"
+
+
+class LLMConfig(BaseModel):
+    """Operator-tunable LLM provider settings stored in ``realism_config``."""
+
+    provider: str = Field(default="ollama")
+    base_url: Optional[str] = Field(default=None)
+    model: str = Field(default="llama3.1")
+    timeout: float = Field(default=60.0, gt=0)
+    # Never returned to callers — encrypted Fernet token, write-only.
+    api_key_ciphertext: Optional[str] = Field(default=None)
+
+    @field_validator("provider")
+    @classmethod
+    def _validate_provider(cls, v: str) -> str:
+        if v not in _SUPPORTED_PROVIDERS:
+            raise ValueError(
+                f"provider must be one of {sorted(_SUPPORTED_PROVIDERS)}, got {v!r}"
+            )
+        return v
+
+    @field_validator("base_url")
+    @classmethod
+    def _validate_base_url(cls, v: Optional[str]) -> Optional[str]:
+        if v is None or v == "":
+            return None
+        if not _HTTP_RE.match(v):
+            raise ValueError("base_url must start with http:// or https://")
+        return v.rstrip("/")
+
+
+def get_cached_backend() -> Optional[Any]:
+    """Return the cached LLMBackend, or ``None`` if not yet hydrated."""
+    return _cached_backend
+
+
+def apply(cfg: LLMConfig) -> None:
+    """Build a backend from *cfg* and install it as the process cache.
+
+    Existing circuit-breaker state is NOT reset — don't wipe a tripped
+    breaker just because the operator tuned a URL.
+    """
+    global _cached_backend
+
+    if cfg.provider == "fake":
+        from decnet.realism.llm.impl.fake import FakeBackend
+        _cached_backend = FakeBackend(model="fake-model")
+        log.info("realism.llm.config: applied provider=fake")
+        return
+
+    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)
+
+        from decnet.realism.llm.impl.ollama import OllamaBackend
+        _cached_backend = OllamaBackend(
+            model=cfg.model,
+            timeout=cfg.timeout,
+            base_url=cfg.base_url,
+            api_key=api_key,
+        )
+        log.info(
+            "realism.llm.config: applied provider=ollama model=%s base_url=%s",
+            cfg.model, cfg.base_url or "(subprocess)",
+        )
+        return
+
+    raise ValueError(f"apply: unsupported provider {cfg.provider!r}")
+
+
+async def load_from_db(repo: Any) -> Optional[LLMConfig]:
+    """Load the ``key='llm'`` RealismConfig row and return a parsed config.
+
+    Returns ``None`` when the row doesn't exist or the JSON is malformed;
+    callers fall back to env-var defaults in both cases.
+    """
+    try:
+        row = await repo.get_realism_config(_CONFIG_KEY)
+    except Exception as exc:  # noqa: BLE001
+        log.warning("realism.llm.config: DB read failed: %s", exc)
+        return None
+    if row is None:
+        return None
+    try:
+        data = json.loads(row.get("value") or "{}")
+        return LLMConfig(**data)
+    except Exception as exc:  # noqa: BLE001
+        log.warning("realism.llm.config: malformed config row: %s", exc)
+        return None

decnet/realism/llm/factory.py

@@ -24,7 +24,14 @@ from decnet.realism.llm.base import LLMBackend
 
 
 def get_llm(*, model: str | None = None, **kwargs: Any) -> LLMBackend:
-    """Instantiate the LLM backend selected by environment.
+    """Instantiate the LLM backend selected by DB config or environment.
+
+    Resolution order:
+    1. Process-level cached backend (populated by the DB config row via
+       :func:`decnet.realism.llm.config.apply`).  Returned as-is when
+       *model* and *kwargs* are both absent — the common case.
+    2. Env-var path (``DECNET_REALISM_LLM`` / ``DECNET_REALISM_MODEL`` /
+       ``DECNET_REALISM_TIMEOUT``) — legacy / default-install fallback.
 
     *model* (when provided) overrides whatever the backend's own default
     is — e.g. for :class:`OllamaBackend` that's ``llama3.1`` unless
@@ -32,6 +39,13 @@ def get_llm(*, model: str | None = None, **kwargs: Any) -> LLMBackend:
     ``decnet orchestrate --model gpt-oss`` without each backend having
     to know about CLI flags.
     """
+    # Fast path: DB-configured cached backend.
+    if model is None and not kwargs:
+        from decnet.realism.llm.config import get_cached_backend
+        cached = get_cached_backend()
+        if cached is not None:
+            return cached
+
     backend_key = os.environ.get("DECNET_REALISM_LLM", "ollama").lower()
 
     if backend_key == "ollama":

decnet/realism/llm/impl/ollama.py

@@ -1,18 +1,17 @@
-"""Ollama subprocess backend.
+"""Ollama backend — subprocess (local) or HTTP (remote).
 
-Shells out to ``ollama run <model>`` with the prompt fed via stdin.
+**Subprocess mode** (default, ``base_url=None``)
+  Shells out to ``ollama run <model>`` with the prompt on stdin.
+  Works on any host where Ollama is reachable however it's bound —
+  unix socket, unusual TCP port, remote-mount — because ``ollama run``
+  resolves all of that transparently.
 
-Why subprocess and not the Ollama HTTP API:
-* No new dependency (``ollama`` Python lib is optional).
-* Works on hosts where Ollama is bound to a unix socket, an unusual TCP
-  port, or behind a remote-mount layer — `ollama run` resolves all that.
-* Same path the operator uses by hand (``ollama run llama3.1``); easier
-  to debug discrepancies between worker output and a console session.
-
-Cost: per-call process spawn (~50ms on a warm box).  Acceptable for
-realism tick rates (one body per ~5 minutes per persona by default).
-When that cost matters, swap to an HTTP-API backend; the seam is in
-:mod:`decnet.realism.llm.factory`.
+**HTTP mode** (``base_url`` set, e.g. ``http://10.0.0.1:11434``)
+  POSTs to ``{base_url}/api/generate`` via httpx (non-streaming).
+  Required when targeting a remote Ollama daemon.  ``api_key`` is sent
+  as ``Authorization: Bearer`` when provided (for reverse-proxy setups).
+  No shell metacharacters ever reach the network call — base_url is
+  validated by :class:`decnet.realism.llm.config.LLMConfig` before storage.
 """
 from __future__ import annotations
 
@@ -32,18 +31,93 @@ _DEFAULT_TIMEOUT = float(os.environ.get("DECNET_REALISM_TIMEOUT", "60"))
 
 
 class OllamaBackend(LLMBackend):
-    """Concrete :class:`LLMBackend` that shells out to ``ollama run``."""
+    """Concrete :class:`LLMBackend` for Ollama — subprocess or HTTP."""
 
     def __init__(
         self,
         *,
         model: Optional[str] = None,
         timeout: Optional[float] = None,
+        base_url: Optional[str] = None,
+        api_key: Optional[str] = None,
     ) -> None:
         self.model = model or _DEFAULT_MODEL
         self.timeout = timeout if timeout is not None else _DEFAULT_TIMEOUT
+        self.base_url = base_url or None
+        self.api_key = api_key or None
 
     async def generate(self, prompt: str) -> LLMResult:
+        if self.base_url:
+            return await self._generate_http(prompt)
+        return await self._generate_subprocess(prompt)
+
+    async def _generate_http(self, prompt: str) -> LLMResult:
+        import httpx
+
+        url = f"{self.base_url}/api/generate"
+        headers: dict[str, str] = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        payload = {"model": self.model, "prompt": prompt, "stream": False}
+
+        t0 = time.monotonic()
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                resp = await client.post(url, json=payload, headers=headers)
+        except httpx.TimeoutException as exc:
+            raise LLMTimeout(
+                f"ollama HTTP {self.model} exceeded {self.timeout}s"
+            ) from exc
+        except Exception as exc:  # noqa: BLE001
+            latency_ms = int((time.monotonic() - t0) * 1000)
+            log.warning("ollama HTTP error model=%s exc=%s", self.model, exc)
+            return LLMResult(
+                success=False,
+                text="",
+                model=self.model,
+                latency_ms=latency_ms,
+                extra={"error": str(exc)},
+            )
+
+        latency_ms = int((time.monotonic() - t0) * 1000)
+        if resp.status_code != 200:
+            log.warning(
+                "ollama HTTP non-200 model=%s status=%d body=%r",
+                self.model, resp.status_code, resp.text[:200],
+            )
+            return LLMResult(
+                success=False,
+                text="",
+                model=self.model,
+                latency_ms=latency_ms,
+                extra={"status": resp.status_code, "body": resp.text[:256]},
+            )
+
+        try:
+            data = resp.json()
+            text = data.get("response", "")
+        except Exception:
+            text = resp.text
+
+        if not text.strip():
+            log.warning("ollama HTTP empty response model=%s", self.model)
+            return LLMResult(
+                success=False,
+                text=text,
+                model=self.model,
+                latency_ms=latency_ms,
+                extra={"status": resp.status_code},
+            )
+
+        return LLMResult(
+            success=True,
+            text=text,
+            model=self.model,
+            latency_ms=latency_ms,
+            extra={"status": resp.status_code},
+        )
+
+    async def _generate_subprocess(self, prompt: str) -> LLMResult:
         t0 = time.monotonic()
         try:
             proc = await asyncio.create_subprocess_exec(