AbstractRuntime 0.4.0__py3-none-any.whl → 0.4.1__py3-none-any.whl

abstractruntime/integrations/abstractcore/llm_client.py

@@ -15,14 +15,314 @@ from __future__ import annotations
 
 import ast
 import json
+import locale
+import os
 import re
+import threading
 from dataclasses import asdict, dataclass, is_dataclass
+from datetime import datetime
 from typing import Any, Dict, List, Optional, Protocol, Tuple
 
 from .logging import get_logger
 
 logger = get_logger(__name__)
 
+_LOCAL_GENERATE_LOCKS: Dict[Tuple[str, str], threading.Lock] = {}
+_LOCAL_GENERATE_LOCKS_LOCK = threading.Lock()
+_LOCAL_GENERATE_LOCKS_WARNED: set[Tuple[str, str]] = set()
+_LOCAL_GENERATE_LOCKS_WARNED_LOCK = threading.Lock()
+
+
+def _local_generate_lock(*, provider: str, model: str) -> Optional[threading.Lock]:
+    """Return a process-wide generation lock for providers that are not thread-safe.
+
+    MLX/Metal can crash the process when concurrent generations occur from multiple threads
+    (e.g. gateway ticking multiple runs concurrently). We serialize MLX generation per model
+    as a safety contract.
+    """
+
+    prov = str(provider or "").strip().lower()
+    if prov != "mlx":
+        return None
+    key = (prov, str(model or "").strip())
+    with _LOCAL_GENERATE_LOCKS_LOCK:
+        lock = _LOCAL_GENERATE_LOCKS.get(key)
+        if lock is None:
+            lock = threading.Lock()
+            _LOCAL_GENERATE_LOCKS[key] = lock
+        return lock
+
+
+def _warn_local_generate_lock_once(*, provider: str, model: str) -> None:
+    prov = str(provider or "").strip().lower()
+    key = (prov, str(model or "").strip())
+    with _LOCAL_GENERATE_LOCKS_WARNED_LOCK:
+        if key in _LOCAL_GENERATE_LOCKS_WARNED:
+            return
+        _LOCAL_GENERATE_LOCKS_WARNED.add(key)
+    logger.warning(
+        "Local provider generation is serialized for safety (prevents MLX/Metal crashes under concurrency).",
+        provider=prov,
+        model=key[1],
+    )
+
+_SYSTEM_CONTEXT_HEADER_RE = re.compile(
+    # ChatML-style user-turn grounding prefix, matching `chat-mlx.py` / `chat-hf.py`:
+    #   "[YYYY-MM-DD HH:MM:SS CC]" (optionally followed by whitespace + user text).
+    # Backward compatible with the historical "[YYYY/MM/DD HH:MM CC]" form.
+    r"^\[\d{4}[-/]\d{2}[-/]\d{2}\s+\d{2}:\d{2}(?::\d{2})?\s+[A-Z]{2}\](?:\s|$)",
+    re.IGNORECASE,
+)
+
+_LEGACY_SYSTEM_CONTEXT_HEADER_RE = re.compile(
+    r"^Grounding:\s*\d{4}/\d{2}/\d{2}\|\d{2}:\d{2}\|[A-Z]{2}$",
+    re.IGNORECASE,
+)
+
+_LEGACY_SYSTEM_CONTEXT_HEADER_PARSE_RE = re.compile(
+    r"^Grounding:\s*(\d{4}/\d{2}/\d{2})\|(\d{2}:\d{2})\|([A-Z]{2})$",
+    re.IGNORECASE,
+)
+
+_ZONEINFO_TAB_CANDIDATES = [
+    "/usr/share/zoneinfo/zone.tab",
+    "/usr/share/zoneinfo/zone1970.tab",
+    "/var/db/timezone/zoneinfo/zone.tab",
+    "/var/db/timezone/zoneinfo/zone1970.tab",
+]
+
+
+def _detect_timezone_name() -> Optional[str]:
+    """Best-effort IANA timezone name (e.g. 'Europe/Paris')."""
+
+    tz_env = os.environ.get("TZ")
+    if isinstance(tz_env, str):
+        tz = tz_env.strip().lstrip(":")
+        if tz and "/" in tz:
+            return tz
+
+    # Common on Debian/Ubuntu.
+    try:
+        with open("/etc/timezone", "r", encoding="utf-8", errors="ignore") as f:
+            line = f.readline().strip()
+        if line and "/" in line:
+            return line
+    except Exception:
+        pass
+
+    # Common on macOS + many Linux distros (symlink or copied file).
+    try:
+        real = os.path.realpath("/etc/localtime")
+    except Exception:
+        real = ""
+    if real:
+        match = re.search(r"/zoneinfo/(.+)$", real)
+        if match:
+            tz = match.group(1).strip()
+            if tz and "/" in tz:
+                return tz
+
+    return None
+
+
+def _country_from_zone_tab(*, zone_name: str, tab_paths: Optional[List[str]] = None) -> Optional[str]:
+    """Resolve ISO2 country code from zone.tab / zone1970.tab."""
+    zone = str(zone_name or "").strip()
+    if not zone:
+        return None
+
+    paths = list(tab_paths) if isinstance(tab_paths, list) and tab_paths else list(_ZONEINFO_TAB_CANDIDATES)
+    for tab_path in paths:
+        try:
+            with open(tab_path, "r", encoding="utf-8", errors="ignore") as f:
+                for raw_line in f:
+                    line = raw_line.strip()
+                    if not line or line.startswith("#"):
+                        continue
+                    parts = line.split("\t")
+                    if len(parts) < 3:
+                        continue
+                    cc_field = parts[0].strip()
+                    tz_field = parts[2].strip()
+                    if tz_field != zone:
+                        continue
+                    cc = cc_field.split(",", 1)[0].strip()
+                    if len(cc) == 2 and cc.isalpha():
+                        return cc.upper()
+        except Exception:
+            continue
+    return None
+
+
+def _detect_country() -> str:
+    """Best-effort 2-letter country code detection.
+
+    Order:
+    1) Explicit env override: ABSTRACT_COUNTRY / ABSTRACTFRAMEWORK_COUNTRY
+    2) Locale region from `locale.getlocale()` or locale env vars (LANG/LC_ALL/LC_CTYPE)
+    3) Timezone (IANA name) via zone.tab mapping
+
+    Notes:
+    - Avoid parsing encoding-only strings like `UTF-8` as a country (a common locale env pitfall).
+    - If no reliable region is found, return `XX` (unknown).
+    """
+
+    def _normalize_country_code(value: Optional[str]) -> Optional[str]:
+        if not isinstance(value, str):
+            return None
+        raw = value.strip()
+        if not raw:
+            return None
+
+        base = raw.split(".", 1)[0].split("@", 1)[0].strip()
+        if len(base) == 2 and base.isalpha():
+            return base.upper()
+
+        parts = [p.strip() for p in re.split(r"[_-]", base) if p.strip()]
+        for part in parts[1:]:
+            if len(part) == 2 and part.isalpha():
+                return part.upper()
+        return None
+
+    # Explicit override (preferred).
+    for key in ("ABSTRACT_COUNTRY", "ABSTRACTFRAMEWORK_COUNTRY"):
+        cc = _normalize_country_code(os.environ.get(key))
+        if cc is not None:
+            return cc
+
+    candidates: List[str] = []
+    try:
+        loc = locale.getlocale()[0]
+        if isinstance(loc, str) and loc.strip():
+            candidates.append(loc)
+    except Exception:
+        pass
+
+    for key in ("LC_ALL", "LANG", "LC_CTYPE"):
+        v = os.environ.get(key)
+        if isinstance(v, str) and v.strip():
+            candidates.append(v)
+
+    for cand in candidates:
+        cc = _normalize_country_code(cand)
+        if cc is not None:
+            return cc
+
+    tz_name = _detect_timezone_name()
+    if tz_name:
+        cc = _country_from_zone_tab(zone_name=tz_name)
+        if cc is not None:
+            return cc
+
+    return "XX"
+
+
+def _system_context_header() -> str:
+    # Use local datetime (timezone-aware) to match the user's environment.
+    # Format: "[YYYY-MM-DD HH:MM:SS CC]"
+    stamp = datetime.now().astimezone().strftime("%Y-%m-%d %H:%M:%S")
+    return f"[{stamp} {_detect_country()}]"
+
+def _strip_system_context_header(system_prompt: Optional[str]) -> Optional[str]:
+    """Remove a runtime-injected system-context header from the system prompt (best-effort).
+
+    Why:
+    - Historically AbstractRuntime injected a "Grounding: ..." line into the *system prompt*.
+    - Prompt/KV caching works best when stable prefixes (system/tools/history) do not contain per-turn entropy.
+    - We still want date/time/country per turn, but we inject it into the *current user turn* instead.
+    """
+    if not isinstance(system_prompt, str):
+        return system_prompt
+    raw = system_prompt
+    lines = raw.splitlines()
+    if not lines:
+        return None
+    first = lines[0].strip()
+    if not (_LEGACY_SYSTEM_CONTEXT_HEADER_RE.match(first) or _SYSTEM_CONTEXT_HEADER_RE.match(first)):
+        return raw
+    rest = "\n".join(lines[1:]).lstrip()
+    return rest if rest else None
+
+
+def _strip_internal_system_messages(messages: Optional[List[Dict[str, Any]]]) -> Optional[List[Dict[str, Any]]]:
+    """Remove internal system messages that should never leak into model outputs.
+
+    Today this is intentionally narrow and only strips the synthetic tool-activity
+    summaries that can be injected by some agent hosts:
+      "Recent tool activity (auto): ..."
+
+    Why:
+    - Some local/open models will echo system-message content verbatim.
+    - These tool-trace summaries are *operator/debug* context, not user-facing content.
+    """
+    if not isinstance(messages, list) or not messages:
+        return messages
+
+    out: List[Dict[str, Any]] = []
+    for m in messages:
+        if not isinstance(m, dict):
+            continue
+        role = str(m.get("role") or "").strip().lower()
+        if role == "system":
+            c = m.get("content")
+            if isinstance(c, str) and c.lstrip().startswith("Recent tool activity"):
+                continue
+        out.append(dict(m))
+
+    return out or None
+
+
+def _inject_turn_grounding(
+    *,
+    prompt: str,
+    messages: Optional[List[Dict[str, Any]]],
+) -> tuple[str, Optional[List[Dict[str, Any]]]]:
+    """Inject date/time/country into the *current user turn* (not the system prompt)."""
+    header = _system_context_header()
+
+    def _prefix_with_header(text: str) -> str:
+        """Prefix with the current header, or rewrite a legacy `Grounding:` prefix into bracket form."""
+        if not isinstance(text, str) or not text.strip():
+            return header
+        raw = str(text)
+        first = raw.lstrip().splitlines()[0].strip()
+        if _SYSTEM_CONTEXT_HEADER_RE.match(first):
+            return raw
+        legacy = _LEGACY_SYSTEM_CONTEXT_HEADER_PARSE_RE.match(first)
+        if legacy:
+            date_part, time_part, cc = legacy.group(1), legacy.group(2), legacy.group(3).upper()
+            date_part = date_part.replace("/", "-")
+            time_part = f"{time_part}:00" if len(time_part) == 5 else time_part
+            bracket = f"[{date_part} {time_part} {cc}]"
+            rest = "\n".join(raw.lstrip().splitlines()[1:]).lstrip()
+            return f"{bracket} {rest}" if rest else bracket
+        return f"{header} {raw}"
+
+    prompt_str = str(prompt or "")
+    if prompt_str.strip():
+        return _prefix_with_header(prompt_str), messages
+
+    if isinstance(messages, list) and messages:
+        out: List[Dict[str, Any]] = []
+        for m in messages:
+            out.append(dict(m) if isinstance(m, dict) else {"role": "user", "content": str(m)})
+
+        for i in range(len(out) - 1, -1, -1):
+            role = str(out[i].get("role") or "").strip().lower()
+            if role != "user":
+                continue
+            content = out[i].get("content")
+            content_str = content if isinstance(content, str) else str(content or "")
+            out[i]["content"] = _prefix_with_header(content_str)
+            return prompt_str, out
+
+        # No user message found; append a synthetic user turn.
+        out.append({"role": "user", "content": header})
+        return prompt_str, out
+
+    # No place to inject; best-effort no-op.
+    return prompt_str, messages
+
 
 def _maybe_parse_tool_calls_from_text(
     *,
@@ -102,6 +402,7 @@ class AbstractCoreLLMClient(Protocol):
         messages: Optional[List[Dict[str, str]]] = None,
         system_prompt: Optional[str] = None,
         tools: Optional[List[Dict[str, Any]]] = None,
+        media: Optional[List[Any]] = None,
         params: Optional[Dict[str, Any]] = None,
     ) -> Dict[str, Any]:
         """Return a JSON-safe dict with at least: content/tool_calls/usage/model."""
@@ -230,6 +531,44 @@ def _normalize_tool_calls(tool_calls: Any) -> Optional[List[Dict[str, Any]]]:
 def _normalize_local_response(resp: Any) -> Dict[str, Any]:
     """Normalize an AbstractCore local `generate()` result into JSON."""
 
+    def _extract_reasoning_from_openai_like(raw: Any) -> Optional[str]:
+        """Best-effort extraction of model reasoning from OpenAI-style payloads.
+
+        LM Studio and some providers store reasoning in `choices[].message.reasoning_content`
+        while leaving `content` empty during tool-call turns.
+        """
+
+        def _from_message(msg: Any) -> Optional[str]:
+            if not isinstance(msg, dict):
+                return None
+            for key in ("reasoning", "reasoning_content", "thinking", "thinking_content"):
+                val = msg.get(key)
+                if isinstance(val, str) and val.strip():
+                    return val.strip()
+            return None
+
+        if isinstance(raw, dict):
+            # OpenAI chat completion: choices[].message
+            choices = raw.get("choices")
+            if isinstance(choices, list):
+                for c in choices:
+                    if not isinstance(c, dict):
+                        continue
+                    r = _from_message(c.get("message"))
+                    if r:
+                        return r
+                    # Streaming-style payloads may use `delta`.
+                    r = _from_message(c.get("delta"))
+                    if r:
+                        return r
+
+            # Some variants store a single message at the top level.
+            r = _from_message(raw.get("message"))
+            if r:
+                return r
+
+        return None
+
     # Dict-like already
     if isinstance(resp, dict):
         out = _jsonable(resp)
@@ -240,6 +579,21 @@ def _normalize_local_response(resp: Any) -> Dict[str, Any]:
             # Some providers place reasoning under metadata (e.g. LM Studio gpt-oss).
             if "reasoning" not in out and isinstance(meta, dict) and isinstance(meta.get("reasoning"), str):
                 out["reasoning"] = meta.get("reasoning")
+            if (
+                (not isinstance(out.get("reasoning"), str) or not str(out.get("reasoning") or "").strip())
+                and isinstance(out.get("raw_response"), dict)
+            ):
+                extracted = _extract_reasoning_from_openai_like(out.get("raw_response"))
+                if extracted:
+                    out["reasoning"] = extracted
+            if (not isinstance(out.get("reasoning"), str) or not str(out.get("reasoning") or "").strip()) and isinstance(out.get("raw"), dict):
+                extracted = _extract_reasoning_from_openai_like(out.get("raw"))
+                if extracted:
+                    out["reasoning"] = extracted
+            if (not isinstance(out.get("reasoning"), str) or not str(out.get("reasoning") or "").strip()) and isinstance(out.get("choices"), list):
+                extracted = _extract_reasoning_from_openai_like(out)
+                if extracted:
+                    out["reasoning"] = extracted
         return out
 
     # Pydantic structured output
@@ -273,6 +627,10 @@ def _normalize_local_response(resp: Any) -> Dict[str, Any]:
         r = metadata.get("reasoning")
         if isinstance(r, str) and r.strip():
             reasoning = r.strip()
+    if reasoning is None and raw_response is not None:
+        extracted = _extract_reasoning_from_openai_like(_jsonable(raw_response))
+        if extracted:
+            reasoning = extracted
 
     return {
         "content": content,
@@ -441,6 +799,9 @@ class LocalAbstractCoreLLMClient:
 
         self._provider = provider
         self._model = model
+        self._generate_lock = _local_generate_lock(provider=self._provider, model=self._model)
+        if self._generate_lock is not None:
+            _warn_local_generate_lock_once(provider=self._provider, model=self._model)
         kwargs = dict(llm_kwargs or {})
         kwargs.setdefault("enable_tracing", True)
         if kwargs.get("enable_tracing"):
@@ -457,10 +818,15 @@ class LocalAbstractCoreLLMClient:
         messages: Optional[List[Dict[str, str]]] = None,
         system_prompt: Optional[str] = None,
         tools: Optional[List[Dict[str, Any]]] = None,
+        media: Optional[List[Any]] = None,
         params: Optional[Dict[str, Any]] = None,
     ) -> Dict[str, Any]:
         params = dict(params or {})
 
+        system_prompt = _strip_system_context_header(system_prompt)
+        prompt, messages = _inject_turn_grounding(prompt=str(prompt or ""), messages=messages)
+        messages = _strip_internal_system_messages(messages)
+
         stream_raw = params.pop("stream", None)
         if stream_raw is None:
             stream_raw = params.pop("streaming", None)
@@ -476,19 +842,39 @@ class LocalAbstractCoreLLMClient:
         params.pop("_provider", None)
         params.pop("_model", None)
 
-        resp = self._llm.generate(
-            prompt=str(prompt or ""),
-            messages=messages,
-            system_prompt=system_prompt,
-            tools=tools,
-            stream=stream,
-            **params,
-        )
-        if stream and hasattr(resp, "__next__"):
-            result = _normalize_local_streaming_response(resp)
+        lock = getattr(self, "_generate_lock", None)
+        if lock is None:
+            resp = self._llm.generate(
+                prompt=str(prompt or ""),
+                messages=messages,
+                system_prompt=system_prompt,
+                tools=tools,
+                media=media,
+                stream=stream,
+                **params,
+            )
+            if stream and hasattr(resp, "__next__"):
+                result = _normalize_local_streaming_response(resp)
+            else:
+                result = _normalize_local_response(resp)
+            result["tool_calls"] = _normalize_tool_calls(result.get("tool_calls"))
         else:
-            result = _normalize_local_response(resp)
-        result["tool_calls"] = _normalize_tool_calls(result.get("tool_calls"))
+            # Serialize generation for non-thread-safe providers (e.g. MLX).
+            with lock:
+                resp = self._llm.generate(
+                    prompt=str(prompt or ""),
+                    messages=messages,
+                    system_prompt=system_prompt,
+                    tools=tools,
+                    media=media,
+                    stream=stream,
+                    **params,
+                )
+                if stream and hasattr(resp, "__next__"):
+                    result = _normalize_local_streaming_response(resp)
+                else:
+                    result = _normalize_local_response(resp)
+                result["tool_calls"] = _normalize_tool_calls(result.get("tool_calls"))
 
         # Durable observability: ensure a provider request payload exists even when the
         # underlying provider does not attach `_provider_request` metadata.
@@ -547,14 +933,16 @@ class LocalAbstractCoreLLMClient:
         for resource tracking and warnings.
 
         Returns:
-            Dict with model capabilities. Always includes 'max_tokens' (default 32768).
+            Dict with model capabilities. Always includes 'max_tokens' (default: DEFAULT_MAX_TOKENS).
         """
         try:
             from abstractcore.architectures.detection import get_model_capabilities
             return get_model_capabilities(self._model)
         except Exception:
             # Safe fallback if detection fails
-            return {"max_tokens": 32768}
+            from abstractruntime.core.vars import DEFAULT_MAX_TOKENS
+
+            return {"max_tokens": DEFAULT_MAX_TOKENS}
 
 
 class MultiLocalAbstractCoreLLMClient:
@@ -590,6 +978,15 @@ class MultiLocalAbstractCoreLLMClient:
             self._clients[key] = client
         return client
 
+    def get_provider_instance(self, *, provider: str, model: str) -> Any:
+        """Return the underlying AbstractCore provider instance for (provider, model)."""
+        client = self._get_client(str(provider or ""), str(model or ""))
+        return getattr(client, "_llm", None)
+
+    def list_loaded_clients(self) -> List[Tuple[str, str]]:
+        """Return (provider, model) pairs loaded in this process (best-effort)."""
+        return list(self._clients.keys())
+
     def generate(
         self,
         *,
@@ -597,6 +994,7 @@ class MultiLocalAbstractCoreLLMClient:
         messages: Optional[List[Dict[str, str]]] = None,
         system_prompt: Optional[str] = None,
         tools: Optional[List[Dict[str, Any]]] = None,
+        media: Optional[List[Any]] = None,
         params: Optional[Dict[str, Any]] = None,
     ) -> Dict[str, Any]:
         params = dict(params or {})
@@ -614,6 +1012,7 @@ class MultiLocalAbstractCoreLLMClient:
             messages=messages,
             system_prompt=system_prompt,
             tools=tools,
+            media=media,
             params=params,
         )
 
@@ -690,12 +1089,20 @@ class RemoteAbstractCoreLLMClient:
         messages: Optional[List[Dict[str, str]]] = None,
         system_prompt: Optional[str] = None,
         tools: Optional[List[Dict[str, Any]]] = None,
+        media: Optional[List[Any]] = None,
         params: Optional[Dict[str, Any]] = None,
     ) -> Dict[str, Any]:
         params = dict(params or {})
+        if media:
+            raise ValueError(
+                "RemoteAbstractCoreLLMClient does not support media yet (artifact-backed attachments require local/hybrid execution)."
+            )
         req_headers = dict(self._headers)
 
         trace_metadata = params.pop("trace_metadata", None)
+        system_prompt = _strip_system_context_header(system_prompt)
+        prompt, messages = _inject_turn_grounding(prompt=str(prompt or ""), messages=messages)
+
         if isinstance(trace_metadata, dict) and trace_metadata:
             req_headers["X-AbstractCore-Trace-Metadata"] = json.dumps(
                 trace_metadata, ensure_ascii=False, separators=(",", ":")
@@ -735,6 +1142,10 @@ class RemoteAbstractCoreLLMClient:
         if base_url:
             body["base_url"] = base_url
 
+        prompt_cache_key = params.get("prompt_cache_key")
+        if isinstance(prompt_cache_key, str) and prompt_cache_key.strip():
+            body["prompt_cache_key"] = prompt_cache_key.strip()
+
         # Pass through common OpenAI-compatible parameters.
         for key in (
             "temperature",
@@ -745,6 +1156,20 @@ class RemoteAbstractCoreLLMClient:
             "presence_penalty",
         ):
             if key in params and params[key] is not None:
+                if key == "seed":
+                    try:
+                        seed_i = int(params[key])
+                    except Exception:
+                        continue
+                    if seed_i >= 0:
+                        body[key] = seed_i
+                    continue
+                if key == "temperature":
+                    try:
+                        body[key] = float(params[key])
+                    except Exception:
+                        continue
+                    continue
                 body[key] = params[key]
 
         if tools is not None:
@@ -765,9 +1190,16 @@ class RemoteAbstractCoreLLMClient:
             }
             if trace_id:
                 meta["trace_id"] = trace_id
+            reasoning = msg.get("reasoning")
+            if not isinstance(reasoning, str) or not reasoning.strip():
+                reasoning = msg.get("reasoning_content")
+            if not isinstance(reasoning, str) or not reasoning.strip():
+                reasoning = msg.get("thinking")
+            if not isinstance(reasoning, str) or not reasoning.strip():
+                reasoning = msg.get("thinking_content")
             result = {
                 "content": msg.get("content"),
-                "reasoning": msg.get("reasoning"),
+                "reasoning": reasoning,
                 "data": None,
                 "raw_response": _jsonable(resp) if resp is not None else None,
                 "tool_calls": _jsonable(msg.get("tool_calls")) if msg.get("tool_calls") is not None else None,

abstractruntime/integrations/abstractcore/mcp_worker.py

@@ -23,6 +23,7 @@ def _truncate(text: str, *, limit: int) -> str:
     s = "" if text is None else str(text)
     if limit <= 0 or len(s) <= limit:
         return s
+    #[WARNING:TRUNCATION] bounded preview for stderr log lines (never used for durable data)
     return s[:limit] + "…"