ltcai 8.9.0 → 9.0.0

package/latticeai/models/model_providers.py

@@ -0,0 +1,111 @@
+"""Cloud LLM provider catalog — static data split out of the router.
+
+Pure config dicts (OpenAI-compatible providers, per-provider model
+catalog, model→source family map). router.py re-exports these, so
+``from latticeai.models.router import OPENAI_COMPATIBLE_PROVIDERS`` and the
+model_runtime re-export chain are unaffected.
+"""
+
+from __future__ import annotations
+
+OPENAI_COMPATIBLE_PROVIDERS = {
+    "openai": {
+        "env_key": "OPENAI_API_KEY",
+        "base_url_env": "OPENAI_BASE_URL",
+        "default_model": "gpt-4o-mini",
+    },
+    "openrouter": {
+        "env_key": "OPENROUTER_API_KEY",
+        "base_url": "https://openrouter.ai/api/v1",
+        "default_model": "openai/gpt-4o-mini",
+    },
+    "groq": {
+        "env_key": "GROQ_API_KEY",
+        "base_url": "https://api.groq.com/openai/v1",
+        "default_model": "meta-llama/llama-4-scout-17b-16e-instruct",
+    },
+    "together": {
+        "env_key": "TOGETHER_API_KEY",
+        "base_url": "https://api.together.xyz/v1",
+        "default_model": "Qwen/Qwen3-VL-32B-Instruct",
+    },
+    "xai": {
+        "env_key": "XAI_API_KEY",
+        "base_url": "https://api.x.ai/v1",
+        "default_model": "grok-beta",
+    },
+    "ollama": {
+        "env_key": "OLLAMA_API_KEY",
+        "base_url_env": "OLLAMA_BASE_URL",
+        "base_url": "http://localhost:11434/v1",
+        "default_model": "hf.co/ggml-org/gemma-4-12B-it-GGUF:Q4_K_M",
+        "api_key_fallback": "ollama",
+    },
+    "vllm": {
+        "env_key": "VLLM_API_KEY",
+        "base_url_env": "VLLM_BASE_URL",
+        "base_url": "http://localhost:8000/v1",
+        "default_model": "Qwen/Qwen3-VL-8B-Instruct",
+        "api_key_fallback": "vllm",
+    },
+    "lmstudio": {
+        "env_key": "LMSTUDIO_API_KEY",
+        "base_url_env": "LMSTUDIO_BASE_URL",
+        "base_url": "http://localhost:1234/v1",
+        "default_model": "local-model",
+        "api_key_fallback": "lmstudio",
+    },
+    "llamacpp": {
+        "env_key": "LLAMACPP_API_KEY",
+        "base_url_env": "LLAMACPP_BASE_URL",
+        "base_url": "http://localhost:8080/v1",
+        "default_model": "llama.cpp-model",
+        "api_key_fallback": "llamacpp",
+    },
+}
+
+PROVIDER_MODEL_CATALOG = {
+    "openai": [
+        {"id": "gpt-5.5", "name": "GPT-5.5", "family": "GPT"},
+        {"id": "gpt-5.4", "name": "GPT-5.4", "family": "GPT"},
+        {"id": "gpt-5.4-mini", "name": "GPT-5.4 Mini", "family": "GPT"},
+        {"id": "gpt-5.4-nano", "name": "GPT-5.4 Nano", "family": "GPT"},
+        {"id": "gpt-4o-mini", "name": "GPT-4o Mini", "family": "GPT"},
+        {"id": "gpt-4o", "name": "GPT-4o", "family": "GPT"},
+        {"id": "gpt-4.1-mini", "name": "GPT-4.1 Mini", "family": "GPT"},
+        {"id": "gpt-4.1", "name": "GPT-4.1", "family": "GPT"},
+    ],
+    "openrouter": [
+        {"id": "openai/gpt-5.5", "name": "GPT-5.5 via OpenRouter", "family": "GPT"},
+        {"id": "openai/gpt-4o-mini", "name": "GPT-4o Mini via OpenRouter", "family": "GPT"},
+        {"id": "anthropic/claude-opus-4.7", "name": "Claude Opus 4.7 via OpenRouter", "family": "Claude"},
+        {"id": "anthropic/claude-sonnet-4.6", "name": "Claude Sonnet 4.6 via OpenRouter", "family": "Claude"},
+        {"id": "anthropic/claude-haiku-4.5", "name": "Claude Haiku 4.5 via OpenRouter", "family": "Claude"},
+        {"id": "qwen/qwen3-vl-235b-a22b-instruct", "name": "Qwen3-VL 235B A22B via OpenRouter", "family": "Qwen"},
+        {"id": "google/gemma-4-12b-it", "name": "Gemma 4 12B via OpenRouter", "family": "Gemma"},
+        {"id": "x-ai/grok-2", "name": "Grok 2 via OpenRouter", "family": "Grok"},
+        {"id": "meta-llama/llama-4-scout-17b-16e-instruct", "name": "Llama 4 Scout via OpenRouter", "family": "Llama"},
+        {"id": "google/gemini-2.5-flash", "name": "Gemini 2.5 Flash via OpenRouter", "family": "Gemini"},
+    ],
+    "groq": [
+        {"id": "meta-llama/llama-4-scout-17b-16e-instruct", "name": "Llama 4 Scout", "family": "Llama"},
+    ],
+    "together": [
+        {"id": "Qwen/Qwen3-VL-32B-Instruct", "name": "Qwen3-VL 32B", "family": "Qwen"},
+        {"id": "google/gemma-4-12b-it", "name": "Gemma 4 12B", "family": "Gemma"},
+        {"id": "meta-llama/Llama-4-Scout-17B-16E-Instruct", "name": "Llama 4 Scout", "family": "Llama"},
+    ],
+    "xai": [
+        {"id": "grok-beta", "name": "Grok Beta", "family": "Grok"},
+        {"id": "grok-vision-beta", "name": "Grok Vision Beta", "family": "Grok"},
+    ],
+}
+
+MODEL_SOURCE_BY_FAMILY = {
+    "GPT": ("미국", "OpenAI"),
+    "Claude": ("미국", "Anthropic"),
+    "Qwen": ("중국", "Alibaba"),
+    "Llama": ("미국", "Meta"),
+    "Gemini": ("미국", "Google"),
+    "Grok": ("미국", "xAI"),
+}

package/latticeai/models/router.py

@@ -9,6 +9,7 @@ import io
 import json
 import os
 import re
+import threading
 import time
 from dataclasses import dataclass
 from pathlib import Path
@@ -21,6 +22,15 @@ from concurrent.futures import ThreadPoolExecutor
 from typing import AsyncIterator, Dict, Optional, Tuple, List
 from PIL import Image
 
+# Cloud provider catalog data lives in .model_providers; re-exported here so
+# ``from latticeai.models.router import OPENAI_COMPATIBLE_PROVIDERS`` (and the
+# model_runtime re-export chain) resolve unchanged after the split.
+from latticeai.models.model_providers import (  # noqa: F401
+    MODEL_SOURCE_BY_FAMILY,
+    OPENAI_COMPATIBLE_PROVIDERS,
+    PROVIDER_MODEL_CATALOG,
+)
+
 try:
     from openai import AsyncOpenAI
 except Exception:
@@ -76,108 +86,6 @@ def normalize_branding(text: Optional[str]) -> str:
         normalized = pattern.sub(replacement, normalized)
     return normalized
 
-OPENAI_COMPATIBLE_PROVIDERS = {
-    "openai": {
-        "env_key": "OPENAI_API_KEY",
-        "base_url_env": "OPENAI_BASE_URL",
-        "default_model": "gpt-4o-mini",
-    },
-    "openrouter": {
-        "env_key": "OPENROUTER_API_KEY",
-        "base_url": "https://openrouter.ai/api/v1",
-        "default_model": "openai/gpt-4o-mini",
-    },
-    "groq": {
-        "env_key": "GROQ_API_KEY",
-        "base_url": "https://api.groq.com/openai/v1",
-        "default_model": "meta-llama/llama-4-scout-17b-16e-instruct",
-    },
-    "together": {
-        "env_key": "TOGETHER_API_KEY",
-        "base_url": "https://api.together.xyz/v1",
-        "default_model": "Qwen/Qwen3-VL-32B-Instruct",
-    },
-    "xai": {
-        "env_key": "XAI_API_KEY",
-        "base_url": "https://api.x.ai/v1",
-        "default_model": "grok-beta",
-    },
-    "ollama": {
-        "env_key": "OLLAMA_API_KEY",
-        "base_url_env": "OLLAMA_BASE_URL",
-        "base_url": "http://localhost:11434/v1",
-        "default_model": "hf.co/ggml-org/gemma-4-12B-it-GGUF:Q4_K_M",
-        "api_key_fallback": "ollama",
-    },
-    "vllm": {
-        "env_key": "VLLM_API_KEY",
-        "base_url_env": "VLLM_BASE_URL",
-        "base_url": "http://localhost:8000/v1",
-        "default_model": "Qwen/Qwen3-VL-8B-Instruct",
-        "api_key_fallback": "vllm",
-    },
-    "lmstudio": {
-        "env_key": "LMSTUDIO_API_KEY",
-        "base_url_env": "LMSTUDIO_BASE_URL",
-        "base_url": "http://localhost:1234/v1",
-        "default_model": "local-model",
-        "api_key_fallback": "lmstudio",
-    },
-    "llamacpp": {
-        "env_key": "LLAMACPP_API_KEY",
-        "base_url_env": "LLAMACPP_BASE_URL",
-        "base_url": "http://localhost:8080/v1",
-        "default_model": "llama.cpp-model",
-        "api_key_fallback": "llamacpp",
-    },
-}
-
-PROVIDER_MODEL_CATALOG = {
-    "openai": [
-        {"id": "gpt-5.5", "name": "GPT-5.5", "family": "GPT"},
-        {"id": "gpt-5.4", "name": "GPT-5.4", "family": "GPT"},
-        {"id": "gpt-5.4-mini", "name": "GPT-5.4 Mini", "family": "GPT"},
-        {"id": "gpt-5.4-nano", "name": "GPT-5.4 Nano", "family": "GPT"},
-        {"id": "gpt-4o-mini", "name": "GPT-4o Mini", "family": "GPT"},
-        {"id": "gpt-4o", "name": "GPT-4o", "family": "GPT"},
-        {"id": "gpt-4.1-mini", "name": "GPT-4.1 Mini", "family": "GPT"},
-        {"id": "gpt-4.1", "name": "GPT-4.1", "family": "GPT"},
-    ],
-    "openrouter": [
-        {"id": "openai/gpt-5.5", "name": "GPT-5.5 via OpenRouter", "family": "GPT"},
-        {"id": "openai/gpt-4o-mini", "name": "GPT-4o Mini via OpenRouter", "family": "GPT"},
-        {"id": "anthropic/claude-opus-4.7", "name": "Claude Opus 4.7 via OpenRouter", "family": "Claude"},
-        {"id": "anthropic/claude-sonnet-4.6", "name": "Claude Sonnet 4.6 via OpenRouter", "family": "Claude"},
-        {"id": "anthropic/claude-haiku-4.5", "name": "Claude Haiku 4.5 via OpenRouter", "family": "Claude"},
-        {"id": "qwen/qwen3-vl-235b-a22b-instruct", "name": "Qwen3-VL 235B A22B via OpenRouter", "family": "Qwen"},
-        {"id": "google/gemma-4-12b-it", "name": "Gemma 4 12B via OpenRouter", "family": "Gemma"},
-        {"id": "x-ai/grok-2", "name": "Grok 2 via OpenRouter", "family": "Grok"},
-        {"id": "meta-llama/llama-4-scout-17b-16e-instruct", "name": "Llama 4 Scout via OpenRouter", "family": "Llama"},
-        {"id": "google/gemini-2.5-flash", "name": "Gemini 2.5 Flash via OpenRouter", "family": "Gemini"},
-    ],
-    "groq": [
-        {"id": "meta-llama/llama-4-scout-17b-16e-instruct", "name": "Llama 4 Scout", "family": "Llama"},
-    ],
-    "together": [
-        {"id": "Qwen/Qwen3-VL-32B-Instruct", "name": "Qwen3-VL 32B", "family": "Qwen"},
-        {"id": "google/gemma-4-12b-it", "name": "Gemma 4 12B", "family": "Gemma"},
-        {"id": "meta-llama/Llama-4-Scout-17B-16E-Instruct", "name": "Llama 4 Scout", "family": "Llama"},
-    ],
-    "xai": [
-        {"id": "grok-beta", "name": "Grok Beta", "family": "Grok"},
-        {"id": "grok-vision-beta", "name": "Grok Vision Beta", "family": "Grok"},
-    ],
-}
-
-MODEL_SOURCE_BY_FAMILY = {
-    "GPT": ("미국", "OpenAI"),
-    "Claude": ("미국", "Anthropic"),
-    "Qwen": ("중국", "Alibaba"),
-    "Llama": ("미국", "Meta"),
-    "Gemini": ("미국", "Google"),
-    "Grok": ("미국", "xAI"),
-}
-
 
 def source_metadata_for_model(provider: str, model: Dict[str, str], *, local_server: bool) -> Dict[str, str]:
     family = str(model.get("family") or "")
@@ -344,6 +252,12 @@ class LLMRouter:
         self._current: Optional[str] = None
         self._last_used: Dict[str, float] = {}
         self._max_local_models = max(1, int(os.getenv("LATTICEAI_MAX_LOCAL_MODELS", "1")))
+        # Guards the mutable model registry (_cache/_current/_last_used).
+        # Reentrant because the eviction path nests: _enforce_local_model_limit
+        # → unload_model → _release_memory. Never held across the heavy
+        # ``run_in_executor`` load (only the sync insert/read is guarded), so a
+        # long model load can't block a concurrent switch/unload from acquiring.
+        self._lock = threading.RLock()
 
     @property
     def current_model_id(self) -> Optional[str]:
@@ -354,33 +268,37 @@ class LLMRouter:
         return list(self._cache.keys())
 
     def switch_model(self, model_id: str) -> None:
-        if model_id not in self._cache:
-            raise KeyError(model_id)
-        self._current = model_id
-        self._touch(model_id)
+        with self._lock:
+            if model_id not in self._cache:
+                raise KeyError(model_id)
+            self._current = model_id
+            self._touch(model_id)
 
     def unload_model(self, model_id: str) -> None:
-        self._cache.pop(model_id, None)
-        self._last_used.pop(model_id, None)
-        if self._current == model_id:
-            self._current = next(iter(self._cache), None)
-        self._release_memory()
+        with self._lock:
+            self._cache.pop(model_id, None)
+            self._last_used.pop(model_id, None)
+            if self._current == model_id:
+                self._current = next(iter(self._cache), None)
+            self._release_memory()
 
     def unload_all(self) -> None:
-        self._cache.clear()
-        self._last_used.clear()
-        self._current = None
-        self._release_memory()
+        with self._lock:
+            self._cache.clear()
+            self._last_used.clear()
+            self._current = None
+            self._release_memory()
 
     def unload_idle_models(self, idle_seconds: int) -> List[str]:
         if idle_seconds <= 0:
             return []
         now = time.monotonic()
         unloaded = []
-        for model_id, last_used in list(self._last_used.items()):
-            if now - last_used >= idle_seconds:
-                self.unload_model(model_id)
-                unloaded.append(model_id)
+        with self._lock:
+            for model_id, last_used in list(self._last_used.items()):
+                if now - last_used >= idle_seconds:
+                    self.unload_model(model_id)
+                    unloaded.append(model_id)
         return unloaded
 
     def model_memory_policy(self) -> Dict[str, object]:
@@ -400,14 +318,15 @@ class LLMRouter:
         return cached is not None and not isinstance(cached, CloudModel)
 
     def _enforce_local_model_limit(self, incoming_key: str) -> None:
-        local_ids = [model_id for model_id in self._cache if self._is_local_model(model_id)]
-        while len(local_ids) >= self._max_local_models:
-            victim = min(local_ids, key=lambda model_id: self._last_used.get(model_id, 0))
-            if victim == incoming_key:
-                break
-            print(f"🧹 Unloading local model to stay within memory policy: {victim}")
-            self.unload_model(victim)
+        with self._lock:
             local_ids = [model_id for model_id in self._cache if self._is_local_model(model_id)]
+            while len(local_ids) >= self._max_local_models:
+                victim = min(local_ids, key=lambda model_id: self._last_used.get(model_id, 0))
+                if victim == incoming_key:
+                    break
+                print(f"🧹 Unloading local model to stay within memory policy: {victim}")
+                self.unload_model(victim)
+                local_ids = [model_id for model_id in self._cache if self._is_local_model(model_id)]
 
     def _release_memory(self) -> None:
         gc.collect()
@@ -434,10 +353,11 @@ class LLMRouter:
             raise RuntimeError("MLX is not available in this process. Run on Apple Silicon with Metal access.")
 
         cache_key = f"{model_id}_{draft_model_id}" if draft_model_id else model_id
-        if cache_key in self._cache:
-            self._current = cache_key
-            self._touch(cache_key)
-            return f"Cached: {cache_key}"
+        with self._lock:
+            if cache_key in self._cache:
+                self._current = cache_key
+                self._touch(cache_key)
+                return f"Cached: {cache_key}"
 
         self._enforce_local_model_limit(cache_key)
         print(f"⏳ Loading local model stack: {cache_key}...")
@@ -479,9 +399,10 @@ class LLMRouter:
         try:
             # Use the dedicated single-thread executor to ensure MLX GPU streams match during inference
             model, tokenizer, draft_model, loader_kind = await loop.run_in_executor(executor, _load)
-            self._cache[cache_key] = (model, tokenizer, draft_model, loader_kind)
-            self._current = cache_key
-            self._touch(cache_key)
+            with self._lock:
+                self._cache[cache_key] = (model, tokenizer, draft_model, loader_kind)
+                self._current = cache_key
+                self._touch(cache_key)
             print(f"✅ Fully Loaded: {cache_key} ({loader_kind})")
             return f"Success: {cache_key} ({loader_kind})"
         except Exception as e:
@@ -507,9 +428,10 @@ class LLMRouter:
 
         cache_owner = owner or "global"
         cache_key = f"{provider}:{model}::{cache_owner}"
-        self._cache[cache_key] = CloudModel(provider=provider, model=model, client=AsyncOpenAI(**client_kwargs), cache_key=cache_key)
-        self._current = cache_key
-        self._touch(cache_key)
+        with self._lock:
+            self._cache[cache_key] = CloudModel(provider=provider, model=model, client=AsyncOpenAI(**client_kwargs), cache_key=cache_key)
+            self._current = cache_key
+            self._touch(cache_key)
         return f"Cloud provider ready: {cache_key}"
 
     def detected_cloud_models(self) -> List[Dict[str, str]]:

package/latticeai/runtime/audit_runtime.py

@@ -5,10 +5,11 @@ Returns dict of get_audit_log / append_audit_event for legacy namespace.
 from __future__ import annotations
 
 import json
-from datetime import datetime
 from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional
 
+from latticeai.core import timezones
+
 
 def build_audit_runtime(
     *,
@@ -17,18 +18,33 @@ def build_audit_runtime(
     redact_fn: Optional[Callable[[str], str]] = None,
 ) -> Dict[str, Any]:
     _audit_lock: Any = __import__("threading").Lock()
+    audit_jsonl = audit_file.with_suffix(audit_file.suffix + ".jsonl")
 
     def _read_audit() -> List[Dict[str, Any]]:
+        events: List[Dict[str, Any]] = []
         if not audit_file.exists():
-            return []
-        try:
-            data = json.loads(audit_file.read_text(encoding="utf-8"))
-            return data if isinstance(data, list) else []
-        except Exception:
-            return []
+            data = []
+        else:
+            try:
+                data = json.loads(audit_file.read_text(encoding="utf-8"))
+            except Exception:
+                data = []
+        if isinstance(data, list):
+            events.extend(item for item in data if isinstance(item, dict))
+        if audit_jsonl.exists():
+            try:
+                for line in audit_jsonl.read_text(encoding="utf-8").splitlines():
+                    if not line.strip():
+                        continue
+                    item = json.loads(line)
+                    if isinstance(item, dict):
+                        events.append(item)
+            except Exception:
+                pass
+        return events[-5000:]
 
     def _append(event_type: str, **payload: Any) -> None:
-        entry = {"event_type": event_type, "timestamp": datetime.now().isoformat()}
+        entry = {"event_type": event_type, "timestamp": timezones.now_iso()}
         if payload:
             entry.update(payload)
         if redact_fn:
@@ -39,15 +55,10 @@ def build_audit_runtime(
             except Exception:
                 pass
         with _audit_lock:
-            events = _read_audit()
-            events.append(entry)
-            # keep last N to bound size (legacy behavior)
-            if len(events) > 5000:
-                events = events[-5000:]
             audit_file.parent.mkdir(parents=True, exist_ok=True)
-            tmp = audit_file.with_suffix(".tmp")
-            tmp.write_text(json.dumps(events, ensure_ascii=False, indent=2), encoding="utf-8")
-            tmp.replace(audit_file)
+            with audit_jsonl.open("a", encoding="utf-8") as fh:
+                fh.write(json.dumps(entry, ensure_ascii=False, default=str))
+                fh.write("\n")
 
     def get_audit_log() -> List[Dict[str, Any]]:
         return _read_audit()

package/latticeai/runtime/automation_runtime.py

@@ -40,12 +40,21 @@ def build_automation_runtime(
         review_sink=review_queue,
         tz_name=tz_name,
     )
+    def _memory_ingest(**kwargs):
+        try:
+            # Delegate to store's upsert (enriches memories + KG automatically via internal graph.ingest_event)
+            return store.upsert_memory(**kwargs)
+        except Exception:
+            return None
+
     agent_runtime = AgentRuntime(
         store=store,
         orchestrator_factory=platform.build_orchestrator,
         workspace_graph=workspace_graph,
         append_audit_event=append_audit_event,
         hooks=hooks,
+        memory_ingest=_memory_ingest,
+        review_sink=review_queue,
     )
     run_executor = RunExecutor(
         store=store,

package/latticeai/runtime/history_runtime.py

@@ -0,0 +1,163 @@
+"""Conversation-history query/clear seam extracted from the app factory.
+
+The read and clear helpers (scope resolution, ``get_history``, conversation
+grouping, and the clear operations) used to be defined inline in
+``app_factory._build``. They are behaviour-preserving closures over the durable
+conversation store and the workspace service; moving them here keeps the factory
+a wiring path. Names are returned unchanged for the legacy ``server_app``
+compatibility namespace.
+
+Note: ``save_to_history`` (the *write* path) stays in the factory — it is bound
+up with redaction, audit, and the ingestion pipeline that are assembled around
+it — so only the query/clear side moves here.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, List, Optional
+
+
+def build_history_query_runtime(
+    *,
+    conversations: Any,
+    workspace_service: Any,
+    require_auth: bool,
+    logging: Any,
+) -> Dict[str, Any]:
+    """Return the history scope/query/clear helpers as a name → callable dict."""
+
+    def _history_allowed_workspaces_for(user_email: Optional[str]):
+        if not require_auth or not user_email:
+            return None
+        try:
+            return set(workspace_service.readable_workspaces(user_email))
+        except Exception as exc:
+            logging.warning("history workspace scope resolution failed for %s: %s", user_email, exc)
+            return set()
+
+    def _history_include_legacy_global(user_email: Optional[str]) -> bool:
+        return not require_auth or not user_email
+
+    def get_history(
+        user_email: Optional[str] = None,
+        allowed_workspaces=None,
+        include_legacy_global: Optional[bool] = None,
+    ):
+        try:
+            if allowed_workspaces is None and user_email:
+                allowed_workspaces = _history_allowed_workspaces_for(user_email)
+            if include_legacy_global is None:
+                include_legacy_global = _history_include_legacy_global(user_email)
+            return conversations.history(
+                user_email=user_email,
+                allowed_workspaces=allowed_workspaces,
+                include_legacy_global=include_legacy_global,
+            )
+        except Exception as e:
+            logging.warning("get_history failed: %s", e)
+            return []
+
+    def conversation_title(item: Dict) -> str:
+        content = str(item.get("content") or "").strip()
+        content = re.sub(r"\s+", " ", content)
+        return content[:48] or "새 대화"
+
+    def group_history_conversations(history: Optional[List[Dict]] = None) -> List[Dict]:
+        history = history if history is not None else get_history()
+        grouped: Dict[str, Dict] = {}
+        order: List[str] = []
+
+        for index, item in enumerate(history):
+            conv_id = item.get("conversation_id")
+            if not conv_id:
+                conv_id = "legacy-previous-history"
+
+            if conv_id not in grouped:
+                grouped[conv_id] = {
+                    "id": conv_id,
+                    "title": "이전 대화 기록" if conv_id == "legacy-previous-history" else conversation_title(item),
+                    "created_at": item.get("timestamp"),
+                    "updated_at": item.get("timestamp"),
+                    "message_count": 0,
+                    "last_message": "",
+                    "source": item.get("source"),
+                }
+                order.append(conv_id)
+
+            conv = grouped[conv_id]
+            conv["message_count"] += 1
+            conv["updated_at"] = item.get("timestamp") or conv.get("updated_at")
+            conv["last_message"] = conversation_title(item)
+            if conv_id != "legacy-previous-history" and item.get("role") == "user" and (not conv.get("title") or conv["title"] == "새 대화"):
+                conv["title"] = conversation_title(item)
+
+        return sorted((grouped[key] for key in order), key=lambda item: item.get("updated_at") or "", reverse=True)
+
+    def get_conversation_messages(
+        conversation_id: str,
+        *,
+        user_email: Optional[str] = None,
+        allowed_workspaces=None,
+        include_legacy_global: Optional[bool] = None,
+    ) -> List[Dict]:
+        history = get_history(
+            user_email=user_email,
+            allowed_workspaces=allowed_workspaces,
+            include_legacy_global=include_legacy_global,
+        )
+        if conversation_id == "legacy-previous-history":
+            return [item for item in history if not item.get("conversation_id")]
+        return [item for item in history if item.get("conversation_id") == conversation_id]
+
+    def clear_history(
+        keep_last: int = 0,
+        *,
+        user_email: Optional[str] = None,
+        allowed_workspaces=None,
+        include_legacy_global: Optional[bool] = None,
+    ) -> Dict:
+        if allowed_workspaces is None and user_email:
+            allowed_workspaces = _history_allowed_workspaces_for(user_email)
+        if include_legacy_global is None:
+            include_legacy_global = _history_include_legacy_global(user_email)
+        return conversations.clear_all(
+            keep_last=keep_last,
+            user_email=user_email,
+            allowed_workspaces=allowed_workspaces,
+            include_legacy_global=include_legacy_global,
+        )
+
+    def clear_conversation(
+        conversation_id: str,
+        started_at: Optional[str] = None,
+        *,
+        user_email: Optional[str] = None,
+        allowed_workspaces=None,
+        include_legacy_global: Optional[bool] = None,
+    ) -> Dict:
+        if allowed_workspaces is None and user_email:
+            allowed_workspaces = _history_allowed_workspaces_for(user_email)
+        if include_legacy_global is None:
+            include_legacy_global = _history_include_legacy_global(user_email)
+        return conversations.clear_conversation(
+            conversation_id,
+            started_at=started_at,
+            user_email=user_email,
+            allowed_workspaces=allowed_workspaces,
+            include_legacy_global=include_legacy_global,
+        )
+
+    return {
+        "_history_allowed_workspaces_for": _history_allowed_workspaces_for,
+        "_history_include_legacy_global": _history_include_legacy_global,
+        "get_history": get_history,
+        "conversation_title": conversation_title,
+        "group_history_conversations": group_history_conversations,
+        "get_conversation_messages": get_conversation_messages,
+        "clear_history": clear_history,
+        "clear_conversation": clear_conversation,
+    }
+
+
+__all__ = ["build_history_query_runtime"]