unique_toolkit 1.68.12__tar.gz → 1.69.0__tar.gz

{unique_toolkit-1.68.12 → unique_toolkit-1.69.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-toolkit
-Version: 1.68.12
+Version: 1.69.0
 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>
@@ -38,9 +38,11 @@ Requires-Dist: openai>=1.105.0,<2 ; extra == 'langchain'
 Requires-Dist: langchain>=1.0.0,<2 ; extra == 'langchain'
 Requires-Dist: langchain-openai>=0.3.28 ; extra == 'langchain'
 Requires-Dist: langchain-core>=1.0.0,<2 ; extra == 'langchain'
+Requires-Dist: prometheus-client>=0.24.1,<1 ; extra == 'monitoring'
 Requires-Python: >=3.12
 Provides-Extra: fastapi
 Provides-Extra: langchain
+Provides-Extra: monitoring
 Description-Content-Type: text/markdown
 
 # Unique Toolkit

{unique_toolkit-1.68.12 → unique_toolkit-1.69.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_toolkit"
-version = "1.68.12"
+version = "1.69.0"
 description = ""
 readme = "README.md"
 requires-python = ">=3.12"
@@ -57,6 +57,9 @@ fastapi = [
     "starlette>=0.49.1",
     "uvicorn>=0.37.0,<0.38",
 ]
+monitoring = [
+    "prometheus_client>=0.24.1,<1",
+]
 
 [build-system]
 requires = ["uv_build>=0.8.14,<0.9.0"]

{unique_toolkit-1.68.12 → unique_toolkit-1.69.0}/unique_toolkit/agentic/tools/openai_builtin/code_interpreter/postprocessors/generated_files.py

@@ -164,7 +164,9 @@ class _FileProgressTracker:
         max_retries: int = 0,
         force_publish: bool = False,
     ) -> None:
+        lock_wait_t0 = time.monotonic()
         async with self._lock:
+            lock_wait_ms = (time.monotonic() - lock_wait_t0) * 1000
             state = self._states.get(filename)
             if state is None:
                 return
@@ -181,8 +183,31 @@ class _FileProgressTracker:
                 or now - self._last_publish_time >= self._min_interval
             )
             if should_publish:
+                publish_t0 = time.monotonic()
                 await self._publish()
+                publish_ms = (time.monotonic() - publish_t0) * 1000
                 self._last_publish_time = now
+                if lock_wait_ms > 100 or publish_ms > 500:
+                    lock_held_ms = (
+                        time.monotonic() - lock_wait_t0
+                    ) * 1000 - lock_wait_ms
+                    self._log.warning(
+                        "Tracker.update('%s', phase=%s): "
+                        "lock_wait=%.0fms, publish=%.0fms, "
+                        "lock_held=%.0fms",
+                        filename,
+                        phase,
+                        lock_wait_ms,
+                        publish_ms,
+                        lock_held_ms,
+                    )
+            elif lock_wait_ms > 100:
+                self._log.warning(
+                    "Tracker.update('%s', phase=%s): lock_wait=%.0fms (no publish)",
+                    filename,
+                    phase,
+                    lock_wait_ms,
+                )
 
     async def tick_elapsed(self, filename: str, elapsed_seconds: float) -> None:
         """Publish an elapsed-time update without changing percent or retry state.
@@ -190,15 +215,38 @@ class _FileProgressTracker:
         Used by the background ticker to show time-based progress while the
         OpenAI API hasn't started returning bytes yet.
         """
+        lock_wait_t0 = time.monotonic()
         async with self._lock:
+            lock_wait_ms = (time.monotonic() - lock_wait_t0) * 1000
             state = self._states.get(filename)
             if state is None or state.phase != "downloading":
                 return
             state.elapsed_seconds = elapsed_seconds
             now = time.monotonic()
             if now - self._last_publish_time >= self._min_interval:
+                publish_t0 = time.monotonic()
                 await self._publish()
+                publish_ms = (time.monotonic() - publish_t0) * 1000
                 self._last_publish_time = now
+                if lock_wait_ms > 100 or publish_ms > 500:
+                    lock_held_ms = (
+                        time.monotonic() - lock_wait_t0
+                    ) * 1000 - lock_wait_ms
+                    self._log.warning(
+                        "Tracker.tick_elapsed('%s'): "
+                        "lock_wait=%.0fms, publish=%.0fms, "
+                        "lock_held=%.0fms",
+                        filename,
+                        lock_wait_ms,
+                        publish_ms,
+                        lock_held_ms,
+                    )
+            elif lock_wait_ms > 100:
+                self._log.warning(
+                    "Tracker.tick_elapsed('%s'): lock_wait=%.0fms (no publish)",
+                    filename,
+                    lock_wait_ms,
+                )
 
     async def publish_initial(self) -> None:
         """Send the first progress update (marks all files as pending)."""
@@ -211,7 +259,15 @@ class _FileProgressTracker:
     async def _publish(self) -> None:
         text = self._build_progress_text()
         try:
+            t0 = time.monotonic()
             await self._chat_service.modify_assistant_message_async(content=text)
+            publish_ms = (time.monotonic() - t0) * 1000
+            if publish_ms > 500:
+                self._log.warning(
+                    "modify_assistant_message_async took %.0fms "
+                    "(SDK singleton / backend contention suspected)",
+                    publish_ms,
+                )
         except Exception:
             self._log.debug("Failed to publish progress update", exc_info=True)
 
@@ -660,6 +716,13 @@ class DisplayCodeInterpreterFilesPostProcessor(
                 hide_in_chat=True,
             )
             upload_ms = (time.monotonic() - upload_t0) * 1000
+            if upload_ms > 2000:
+                self._log.warning(
+                    "SDK upload for '%s' took %.0fms — "
+                    "backend contention or slow blob storage suspected",
+                    container_file.filename,
+                    upload_ms,
+                )
 
             if tracker:
                 await tracker.update(
@@ -796,14 +859,26 @@ class DisplayCodeInterpreterFilesPostProcessor(
             total = int(content_length) if content_length else None
             chunks: list[bytes] = []
             downloaded = 0
+            last_chunk_time = time.monotonic()
             async for chunk in response.iter_bytes(
                 chunk_size=self._config.download_chunk_size
             ):
+                now = time.monotonic()
+                chunk_gap_ms = (now - last_chunk_time) * 1000
+                if chunk_gap_ms > 500:
+                    self._log.warning(
+                        "Download chunk gap for '%s': %.0fms "
+                        "(downloaded=%d bytes so far)",
+                        container_file.filename,
+                        chunk_gap_ms,
+                        downloaded,
+                    )
                 chunks.append(chunk)
                 downloaded += len(chunk)
                 if tracker:
                     pct = (downloaded * 100 // total) if total else None
                     elapsed = time.monotonic() - download_start
+                    update_t0 = time.monotonic()
                     await tracker.update(
                         container_file.filename,
                         "downloading",
@@ -812,6 +887,15 @@ class DisplayCodeInterpreterFilesPostProcessor(
                         retry_attempt=retry_attempt,
                         max_retries=self._config.max_download_retries,
                     )
+                    update_ms = (time.monotonic() - update_t0) * 1000
+                    if update_ms > 200:
+                        self._log.warning(
+                            "tracker.update() blocked download stream for '%s' "
+                            "for %.0fms (lock contention or slow modify_message)",
+                            container_file.filename,
+                            update_ms,
+                        )
+                last_chunk_time = time.monotonic()
             transfer_ms = (time.monotonic() - t0) * 1000 - first_byte_ms
             self._log.info(
                 "Stream complete for '%s' — transfer=%.0fms, total=%d bytes",

{unique_toolkit-1.68.12 → unique_toolkit-1.69.0}/unique_toolkit/app/fast_api_factory.py

@@ -63,6 +63,21 @@ def build_unique_custom_app(
         """Health check endpoint."""
         return JSONResponse(content={"status": "healthy", "service": title})
 
+    from unique_toolkit.monitoring import _MONITORING_AVAILABLE
+
+    if _MONITORING_AVAILABLE:
+        from starlette.responses import Response as StarletteResponse
+
+        from unique_toolkit.monitoring import get_metrics
+
+        @app.get(path="/metrics")
+        async def metrics_endpoint() -> StarletteResponse:
+            """Prometheus metrics endpoint."""
+            return StarletteResponse(
+                content=get_metrics(),
+                media_type="text/plain; version=0.0.4; charset=utf-8",
+            )
+
     @app.post(path=webhook_path)
     async def webhook_handler(
         request: Request, background_tasks: BackgroundTasks

unique_toolkit-1.69.0/unique_toolkit/monitoring/__init__.py

@@ -0,0 +1,39 @@
+try:
+    from prometheus_client import CollectorRegistry  # noqa: F401
+
+    _MONITORING_AVAILABLE = True
+except ImportError:
+    _MONITORING_AVAILABLE = False
+
+
+def _check_monitoring_available() -> None:
+    if not _MONITORING_AVAILABLE:
+        raise ImportError(
+            "prometheus_client is not installed. "
+            "Install it with: pip install unique_toolkit[monitoring]"
+        )
+
+
+if _MONITORING_AVAILABLE:
+    from unique_toolkit.monitoring.middleware import MetricsMiddleware
+    from unique_toolkit.monitoring.registry import (
+        REGISTRY,
+        MetricNamespace,
+        get_metrics,
+        metric_scope,
+        track_execution,
+    )
+
+    __all__ = [
+        "REGISTRY",
+        "MetricNamespace",
+        "MetricsMiddleware",
+        "get_metrics",
+        "metric_scope",
+        "track_execution",
+        "_MONITORING_AVAILABLE",
+    ]
+else:
+
+    def __getattr__(name: str):
+        _check_monitoring_available()

unique_toolkit-1.69.0/unique_toolkit/monitoring/middleware.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import time
+
+from prometheus_client import Counter, Gauge, Histogram
+
+from .registry import REGISTRY
+
+_http_requests_total = Counter(
+    "http_requests_total",
+    "Total HTTP requests",
+    ["method", "path", "status_code"],
+    registry=REGISTRY,
+)
+_http_request_duration_seconds = Histogram(
+    "http_request_duration_seconds",
+    "HTTP request duration",
+    ["method", "path"],
+    registry=REGISTRY,
+)
+_http_requests_in_progress = Gauge(
+    "http_requests_in_progress",
+    "In-flight HTTP requests",
+    ["method"],
+    registry=REGISTRY,
+)
+
+_DEFAULT_EXCLUDED_PATHS = frozenset({"/health", "/metrics", "/"})
+
+
+class MetricsMiddleware:
+    """ASGI middleware that tracks HTTP request metrics.
+
+    Works with any ASGI app (FastAPI, Quart, Starlette).
+
+    Handles:
+    - Non-HTTP scopes (WebSocket, lifespan) — passed through, not tracked
+    - Excluded paths (health, metrics) — passed through, not tracked
+    - App exceptions — duration + error still recorded, in-progress gauge cleaned up
+    - Streaming responses — status captured from first http.response.start message
+
+    Usage::
+
+        # FastAPI
+        app.add_middleware(MetricsMiddleware)
+
+        # Quart
+        app.asgi_app = MetricsMiddleware(app.asgi_app)
+    """
+
+    def __init__(self, app, excluded_paths: set[str] | None = None):
+        self.app = app
+        self._excluded_paths = (
+            excluded_paths if excluded_paths is not None else _DEFAULT_EXCLUDED_PATHS
+        )
+
+    async def __call__(self, scope, receive, send):
+        # Pass through non-HTTP (WebSocket, lifespan)
+        if scope["type"] != "http":
+            return await self.app(scope, receive, send)
+
+        path = scope.get("path", "/")
+
+        # Pass through excluded paths (health checks, metrics endpoint)
+        if path in self._excluded_paths:
+            return await self.app(scope, receive, send)
+
+        method = scope.get("method", "UNKNOWN")
+        status_code = "500"  # Default if app crashes before sending response
+
+        _http_requests_in_progress.labels(method=method).inc()
+        start = time.perf_counter()
+
+        async def send_wrapper(message):
+            nonlocal status_code
+            if message["type"] == "http.response.start":
+                status_code = str(message["status"])
+            await send(message)
+
+        try:
+            await self.app(scope, receive, send_wrapper)
+        finally:
+            duration = time.perf_counter() - start
+            _http_requests_in_progress.labels(method=method).dec()
+            _http_request_duration_seconds.labels(method=method, path=path).observe(
+                duration
+            )
+            _http_requests_total.labels(
+                method=method, path=path, status_code=status_code
+            ).inc()

unique_toolkit-1.69.0/unique_toolkit/monitoring/registry.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import asyncio
+import functools
+import time
+from contextlib import contextmanager
+from typing import Callable
+
+from prometheus_client import (
+    CollectorRegistry,
+    Counter,
+    Gauge,
+    Histogram,
+    generate_latest,
+)
+
+REGISTRY = CollectorRegistry()
+
+
+def get_metrics() -> bytes:
+    """Returns all registered metrics in Prometheus text format."""
+    return generate_latest(REGISTRY)
+
+
+class MetricNamespace:
+    """Factory that auto-prefixes metric names and auto-registers to REGISTRY.
+
+    Usage::
+
+        m = MetricNamespace("unique_web_search")
+        search_duration = m.histogram("search_duration_seconds", "Search API latency", ["engine"])
+        search_total    = m.counter("search_total", "Search calls by engine", ["engine"])
+    """
+
+    def __init__(self, prefix: str) -> None:
+        self._prefix = prefix
+
+    def histogram(self, name: str, description: str, labels: list[str]) -> Histogram:
+        return Histogram(
+            f"{self._prefix}_{name}", description, labels, registry=REGISTRY
+        )
+
+    def counter(self, name: str, description: str, labels: list[str]) -> Counter:
+        return Counter(f"{self._prefix}_{name}", description, labels, registry=REGISTRY)
+
+    def gauge(self, name: str, description: str, labels: list[str]) -> Gauge:
+        return Gauge(f"{self._prefix}_{name}", description, labels, registry=REGISTRY)
+
+
+@contextmanager
+def metric_scope(duration: Histogram, errors: Counter | None = None, **labels):
+    """Context manager that auto-times a block and records metrics.
+
+    Use when labels are dynamic (determined at runtime).
+
+    Example — search engine with dynamic engine label::
+
+        with metric_scope(search_duration, search_errors, engine=self.engine_name):
+            results = await self._execute_search(query)
+
+    Example — LLM call with purpose label::
+
+        with metric_scope(llm_duration, llm_errors, purpose="snippet_judge"):
+            response = await lm_service.complete_async(...)
+    """
+    start = time.perf_counter()
+    try:
+        yield
+    except Exception as e:
+        if errors:
+            errors.labels(**labels, error_type=type(e).__name__).inc()
+        raise
+    finally:
+        duration.labels(**labels).observe(time.perf_counter() - start)
+
+
+def track_execution(
+    duration: Histogram,
+    errors: Counter | None = None,
+    **labels,
+) -> Callable:
+    """Decorator that auto-tracks duration + errors for an entire function.
+
+    Use when labels are static (known at definition time).
+    Works with both sync and async functions.
+
+    Example — crawl with fixed crawler name::
+
+        @track_execution(crawl_duration, crawl_errors, crawler="basic")
+        async def crawl(self, urls):
+            ...
+    """
+
+    def decorator(func):
+        @functools.wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            with metric_scope(duration, errors, **labels):
+                return await func(*args, **kwargs)
+
+        @functools.wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            with metric_scope(duration, errors, **labels):
+                return func(*args, **kwargs)
+
+        return async_wrapper if asyncio.iscoroutinefunction(func) else sync_wrapper
+
+    return decorator