unique-toolkit 2026.38.0.dev4__tar.gz → 2026.38.0.dev6__tar.gz

{unique_toolkit-2026.38.0.dev4 → unique_toolkit-2026.38.0.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-toolkit
-Version: 2026.38.0.dev4
+Version: 2026.38.0.dev6
 Summary: 
 Author: Cedric Klinkert, Martin Fadler, Sadique Sheik, Fabian Schläpfer, Pascal Hauri, Ejiroghene Oki-Peter, Rami Azouz, Ricardo Visini, Sanzio Monti
 Author-email: Cedric Klinkert <cedric.klinkert@unique.ch>, Martin Fadler <martin.fadler@unique.ch>, Sadique Sheik <sadique@unique.ch>, Fabian Schläpfer <fabian@unique.ch>, Pascal Hauri <pascal@unique.ch>, Ejiroghene Oki-Peter <oki-peter.ejiroghene@unique.ai>, Rami Azouz <rami.ext@unique.ch>, Ricardo Visini <ricardo.visini@unique.ch>, Sanzio Monti <sanzio.monti@unique.ai>
@@ -16,7 +16,7 @@ Requires-Dist: sseclient>=0.0.27,<0.0.28
 Requires-Dist: openai>=1.105.0,<3
 Requires-Dist: platformdirs>=4.0.0,<5
 Requires-Dist: pillow>=12.1.1
-Requires-Dist: unique-sdk>=2026.38.0.dev0,<2026.38.0rc0
+Requires-Dist: unique-sdk>=2026.38.0.dev1,<2026.38.0rc0
 Requires-Dist: jambo>=0.1.2,<0.2
 Requires-Dist: jinja2>=3.1.6,<4
 Requires-Dist: docxtpl>=0.20.1,<0.21

{unique_toolkit-2026.38.0.dev4 → unique_toolkit-2026.38.0.dev6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_toolkit"
-version = "2026.38.0.dev4"
+version = "2026.38.0.dev6"
 description = ""
 readme = "README.md"
 requires-python = ">=3.12"
@@ -28,7 +28,7 @@ dependencies = [
     "openai>=1.105.0,<3",
     "platformdirs>=4.0.0,<5",
     "pillow>=12.1.1",
-    "unique-sdk>=2026.38.0.dev0,<2026.38.0rc0",
+    "unique-sdk>=2026.38.0.dev1,<2026.38.0rc0",
     "jambo>=0.1.2,<0.2",
     "jinja2>=3.1.6,<4",
     "docxtpl>=0.20.1,<0.21",

{unique_toolkit-2026.38.0.dev4 → unique_toolkit-2026.38.0.dev6}/unique_toolkit/experimental/resources/feature_flags/_ttl_cache.py

@@ -17,14 +17,23 @@ class AsyncTTLCache:
     Both the value cache and the lock dict are bounded by ``maxsize``.
 
     Keys may be any hashable — strings, tuples, etc.
+
+    Set ``keep_stale=False`` when the caller never uses the stale fallback.
     """
 
-    def __init__(self, *, maxsize: int = 1024, ttl_ms: float = 5_000) -> None:
+    def __init__(
+        self, *, maxsize: int = 1024, ttl_ms: float = 5_000, keep_stale: bool = True
+    ) -> None:
         self._cache: TTLCache[Any, Any] = TTLCache(maxsize=maxsize, ttl=ttl_ms / 1000)
+        self._keep_stale = keep_stale
         self._stale: LRUCache[Any, Any] = LRUCache(maxsize=maxsize)
         self._locks: LRUCache[Any, asyncio.Lock] = LRUCache(maxsize=maxsize)
         self._dict_lock = asyncio.Lock()
 
+    def _set_stale(self, key: Any, value: Any) -> None:
+        if self._keep_stale:
+            self._stale[key] = value
+
     async def _get_key_lock(self, key: Any) -> asyncio.Lock:
         async with self._dict_lock:
             lock = self._locks.get(key)
@@ -41,7 +50,7 @@ class AsyncTTLCache:
         """Return ``(value, from_cache)``, fetching on a miss with per-key stampede protection."""
         cached = self._cache.get(key, _MISSING)
         if cached is not _MISSING:
-            self._stale[key] = cached  # keep stale warm while TTL cache is hot
+            self._set_stale(key, cached)
             return cached, True
 
         # Acquire per-key lock; re-check inside in case another waiter already fetched.
@@ -49,12 +58,12 @@ class AsyncTTLCache:
         async with key_lock:
             cached = self._cache.get(key, _MISSING)
             if cached is not _MISSING:
-                self._stale[key] = cached  # keep stale warm while TTL cache is hot
+                self._set_stale(key, cached)
                 return cached, True
 
             value = await fetcher()
             self._cache[key] = value
-            self._stale[key] = value
+            self._set_stale(key, value)
             return value, False
 
     def get_stale(self, key: Any) -> tuple[Any, bool]:

unique_toolkit-2026.38.0.dev6/unique_toolkit/monitoring/memory.py

@@ -0,0 +1,195 @@
+"""Process-level memory trimming and optional RSS ceiling monitoring."""
+
+from __future__ import annotations
+
+import ctypes
+import gc
+import logging
+import os
+import platform
+import signal
+import threading
+import time
+
+logger = logging.getLogger(__name__)
+
+_SAFETY_FACTOR = 0.9
+
+_libc = None
+
+
+def _get_libc():
+    global _libc
+    if _libc is None and platform.system() == "Linux":
+        try:
+            lib = ctypes.CDLL("libc.so.6", use_errno=True)
+            lib.malloc_trim.argtypes = [ctypes.c_size_t]
+            lib.malloc_trim.restype = ctypes.c_int
+            _libc = lib
+        except (AttributeError, OSError):
+            _libc = False
+    return _libc or None
+
+
+def _read_rss_mib() -> float | None:
+    """Return this process's resident set size in MiB, or None off Linux."""
+    try:
+        with open("/proc/self/status") as f:
+            for line in f:
+                if line.startswith("VmRSS:"):
+                    return int(line.split()[1]) / 1024
+    except OSError:
+        pass
+    return None
+
+
+def trim_memory(reason: str) -> None:
+    """Collect garbage and ask glibc to return free pages to the OS."""
+    before = _read_rss_mib()
+    t0 = time.time()
+
+    unreachable = gc.collect()
+
+    if os.getenv(
+        "MEMORY_TRIM_MALLOC_TRIM", "true"
+    ).lower() == "true" and "jemalloc" not in os.getenv("LD_PRELOAD", ""):
+        libc = _get_libc()
+        if libc is not None:
+            getattr(libc, "malloc_trim")(0)
+
+    after = _read_rss_mib()
+    reclaimed = before - after if before is not None and after is not None else None
+    logger.info(
+        "[MEMORY-TRIM:%s] rss: %s MiB | reclaimed: %s MiB | trim_ms: %.0f | "
+        "gc_unreachable: %d | gc_garbage: %d",
+        reason,
+        f"{after:.0f}" if after is not None else "n/a",
+        f"{reclaimed:.2f}" if reclaimed is not None else "n/a",
+        (time.time() - t0) * 1000,
+        unreachable,
+        len(gc.garbage),
+    )
+
+
+_trimmer_started = False
+_trimmer_lock = threading.Lock()
+
+
+def start_memory_trimmer() -> None:
+    """Start an idempotent daemon thread that periodically trims process memory."""
+    global _trimmer_started
+    with _trimmer_lock:
+        if _trimmer_started:
+            return
+        _trimmer_started = True
+
+    try:
+        interval = max(10, int(os.getenv("MEMORY_TRIM_INTERVAL_SECONDS", "120")))
+    except ValueError:
+        interval = 120
+
+    def _loop() -> None:
+        while True:
+            time.sleep(interval)
+            try:
+                trim_memory("periodic")
+            except Exception:
+                logger.exception("memory-trimmer cycle failed; continuing")
+
+    threading.Thread(target=_loop, name="memory-trimmer", daemon=True).start()
+    logger.info("[MEMORY-TRIM] periodic trimmer armed: interval=%ds", interval)
+
+
+def _resolve_max_rss_mib() -> int:
+    """Resolve the per-process RSS ceiling from environment variables."""
+    explicit = os.getenv("MEMORY_TRIM_MAX_RSS_MIB")
+    if explicit is not None:
+        try:
+            return int(explicit)
+        except ValueError:
+            logger.warning(
+                "[MEMORY-LIMIT] MEMORY_TRIM_MAX_RSS_MIB=%r is not a valid integer — ignoring",
+                explicit,
+            )
+
+    try:
+        limit_mib = int(os.getenv("CONTAINER_MEMORY_LIMIT_MIB", "0"))
+    except ValueError:
+        return 0
+    if limit_mib <= 0:
+        return 0
+
+    try:
+        process_count = max(1, int(os.getenv("MEMORY_TRIM_PROCESS_COUNT", "1")))
+    except ValueError:
+        process_count = 1
+    return int(limit_mib / process_count * _SAFETY_FACTOR)
+
+
+def _rss_check_tick(
+    rss_mib: float | None, max_rss_mib: int, consecutive_high: int
+) -> int | None:
+    """Update the over-limit streak and terminate after two high readings."""
+    if rss_mib is None:
+        return consecutive_high
+    if rss_mib <= max_rss_mib:
+        return 0
+
+    consecutive_high += 1
+    logger.info(
+        "[MEMORY-LIMIT] RSS %.0f MiB > limit %d MiB (strike %d/2)",
+        rss_mib,
+        max_rss_mib,
+        consecutive_high,
+    )
+    if consecutive_high >= 2:
+        logger.info("[MEMORY-LIMIT] RSS sustained above limit — sending SIGTERM")
+        os.kill(os.getpid(), signal.SIGTERM)
+        return None
+    return consecutive_high
+
+
+_watcher_started = False
+_watcher_lock = threading.Lock()
+
+
+def start_rss_ceiling_watcher() -> None:
+    """Start an idempotent daemon that SIGTERMs the process after high RSS readings."""
+    max_rss_mib = _resolve_max_rss_mib()
+    if max_rss_mib <= 0:
+        logger.info("[MEMORY-LIMIT] RSS ceiling watcher disabled (no limit configured)")
+        return
+
+    global _watcher_started
+    with _watcher_lock:
+        if _watcher_started:
+            return
+        _watcher_started = True
+
+    try:
+        interval = max(
+            5, int(os.getenv("MEMORY_TRIM_RSS_CHECK_INTERVAL_SECONDS", "30"))
+        )
+    except ValueError:
+        interval = 30
+
+    def _loop() -> None:
+        consecutive_high = 0
+        while True:
+            time.sleep(interval)
+            try:
+                next_consecutive_high = _rss_check_tick(
+                    _read_rss_mib(), max_rss_mib, consecutive_high
+                )
+                if next_consecutive_high is None:
+                    return
+                consecutive_high = next_consecutive_high
+            except Exception:
+                logger.exception("rss-ceiling-watcher cycle failed; continuing")
+
+    threading.Thread(target=_loop, name="rss-ceiling-watcher", daemon=True).start()
+    logger.info(
+        "[MEMORY-LIMIT] RSS ceiling watcher armed: max_rss_mib=%d interval=%ds",
+        max_rss_mib,
+        interval,
+    )