unique_toolkit 1.68.13__tar.gz → 1.69.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-toolkit
-Version: 1.68.13
+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.13 → unique_toolkit-1.69.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_toolkit"
-version = "1.68.13"
+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.13 → 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