unique_toolkit 2026.34.0.dev2__py3-none-any.whl → 2026.34.0.dev4__py3-none-any.whl

unique_toolkit/monitoring/__init__.py

@@ -1,3 +1,19 @@
+from unique_toolkit.monitoring.tracing import (
+    TraceContextMiddleware,
+    TraceExporter,
+    TracingSettings,
+    configure_tracing,
+    inject_trace_headers,
+)
+
+__all__ = [
+    "TraceContextMiddleware",
+    "TraceExporter",
+    "TracingSettings",
+    "configure_tracing",
+    "inject_trace_headers",
+]
+
 _MONITORING_AVAILABLE = False
 try:
     from prometheus_client import (  # pyright: ignore[reportMissingImports]
@@ -27,7 +43,7 @@ if _MONITORING_AVAILABLE:
         track_execution,
     )
 
-    __all__ = [
+    __all__ += [
         "REGISTRY",
         "MetricNamespace",
         "MetricsMiddleware",

unique_toolkit/monitoring/tracing.py

@@ -0,0 +1,201 @@
+"""OpenTelemetry tracing bootstrap for toolkit consumers."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Iterable, MutableMapping
+from enum import StrEnum
+from typing import TYPE_CHECKING, ClassVar, Self, TypeAlias, cast
+
+from pydantic import AliasChoices, Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+if TYPE_CHECKING:
+    from opentelemetry.trace.propagation.tracecontext import (
+        TraceContextTextMapPropagator,
+    )
+
+# Keep ASGI aliases local; tracing should not depend on asgiref solely for typing.
+ASGIScope: TypeAlias = MutableMapping[str, object]
+ASGIMessage: TypeAlias = MutableMapping[str, object]
+ASGIReceive: TypeAlias = Callable[[], Awaitable[ASGIMessage]]
+ASGISend: TypeAlias = Callable[[ASGIMessage], Awaitable[None]]
+ASGIApp: TypeAlias = Callable[[ASGIScope, ASGIReceive, ASGISend], Awaitable[None]]
+
+_OTEL_EXTRA_MESSAGE = (
+    "OpenTelemetry tracing requires the unique_toolkit[otel] extra. "
+    "Install it with: uv add 'unique-toolkit[otel]'"
+)
+
+
+class TraceExporter(StrEnum):
+    """Trace exporters supported by the toolkit bootstrap."""
+
+    NONE = "none"
+    CONSOLE = "console"
+    OTLP = "otlp"
+
+
+class TracingSettings(BaseSettings):
+    """Environment settings for optional OpenTelemetry tracing."""
+
+    model_config: ClassVar[SettingsConfigDict] = SettingsConfigDict(
+        env_prefix="OTEL_",
+        env_ignore_empty=True,
+        extra="ignore",
+    )
+
+    traces_exporter: TraceExporter | None = None
+    service_name: str | None = None
+    service_version: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("OTEL_SERVICE_VERSION", "VERSION"),
+    )
+    otlp_endpoint: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices(
+            "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
+            "OTEL_EXPORTER_OTLP_ENDPOINT",
+        ),
+    )
+    span_processor: TraceExporter | None = None
+    enabled: bool | None = Field(
+        default=None,
+        validation_alias="ENABLE_OPENTELEMETRY",
+    )
+
+    @property
+    def exporter(self) -> TraceExporter | None:
+        """Resolve standard OTel settings with Node service compatibility aliases."""
+        if self.traces_exporter:
+            return self.traces_exporter
+        if self.otlp_endpoint:
+            return TraceExporter.OTLP
+        if self.enabled is False:
+            return None
+        if self.enabled is True:
+            return self.span_processor or TraceExporter.OTLP
+        return None
+
+    @classmethod
+    def try_load(cls) -> Self | None:
+        """Load env settings, or ``None`` when tracing cannot be enabled."""
+        settings = cls()
+        if settings.exporter in {None, TraceExporter.NONE}:
+            return None
+        return settings
+
+
+def _missing_otel_extra() -> ImportError:
+    """Create a consistent error for an unavailable optional tracing dependency."""
+    return ImportError(_OTEL_EXTRA_MESSAGE)
+
+
+def _trace_context_propagator() -> TraceContextTextMapPropagator:
+    """Return a W3C trace-context propagator without forwarding baggage."""
+    try:
+        from opentelemetry.trace.propagation.tracecontext import (
+            TraceContextTextMapPropagator,
+        )
+    except ImportError as error:
+        raise _missing_otel_extra() from error
+    return TraceContextTextMapPropagator()
+
+
+class TraceContextMiddleware:
+    """ASGI middleware that continues W3C trace context with one server span."""
+
+    def __init__(self, app: ASGIApp, span_name: str = "HTTP request") -> None:
+        self.app: ASGIApp = app
+        self._span_name: str = span_name
+
+    async def __call__(
+        self, scope: ASGIScope, receive: ASGIReceive, send: ASGISend
+    ) -> None:
+        if scope["type"] != "http":
+            return await self.app(scope, receive, send)
+
+        try:
+            from opentelemetry import trace
+            from opentelemetry.trace import SpanKind
+        except ImportError as error:
+            raise _missing_otel_extra() from error
+
+        headers: dict[str, str] = {}
+        raw_headers = cast(Iterable[tuple[bytes, bytes]], scope.get("headers", ()))
+        for name, value in raw_headers:
+            key = name.decode("latin-1").lower()
+            if key not in {"traceparent", "tracestate"}:
+                continue
+            header_value = value.decode("latin-1")
+            if key == "tracestate" and key in headers:
+                headers[key] = f"{headers[key]},{header_value}"
+            elif key not in headers:
+                headers[key] = header_value
+        parent_context = _trace_context_propagator().extract(headers)
+        with trace.get_tracer(__name__).start_as_current_span(
+            self._span_name,
+            context=parent_context,
+            kind=SpanKind.SERVER,
+        ):
+            return await self.app(scope, receive, send)
+
+
+def inject_trace_headers(headers: MutableMapping[str, str]) -> None:
+    """Inject the active W3C trace context into outgoing request headers."""
+    _trace_context_propagator().inject(headers)
+
+
+def configure_tracing(
+    *,
+    service_name: str | None = None,
+    service_version: str | None = None,
+) -> bool:
+    """Install an OpenTelemetry trace provider from standard and Node-compatible env.
+
+    ``OTEL_TRACES_EXPORTER`` takes precedence. When it is unset,
+    ``ENABLE_OPENTELEMETRY`` and ``OTEL_SPAN_PROCESSOR`` mirror the Node service
+    tracing configuration. Prometheus metrics and application logging remain
+    separate, so ``OTEL_METRICS_READER`` and ``OTEL_LOGS_PROCESSOR`` are ignored.
+    """
+    settings = TracingSettings.try_load()
+    if settings is None:
+        return False
+    exporter = settings.exporter
+    assert exporter is not None  # try_load guarantees a concrete exporter
+
+    try:
+        from opentelemetry import trace
+        from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
+            OTLPSpanExporter,
+        )
+        from opentelemetry.sdk.resources import Resource
+        from opentelemetry.sdk.trace import TracerProvider
+        from opentelemetry.sdk.trace.export import (
+            BatchSpanProcessor,
+            ConsoleSpanExporter,
+            SimpleSpanProcessor,
+        )
+        from opentelemetry.trace import ProxyTracerProvider
+    except ImportError as error:
+        raise _missing_otel_extra() from error
+
+    if not isinstance(trace.get_tracer_provider(), ProxyTracerProvider):
+        return True
+
+    name = service_name if service_name is not None else settings.service_name
+    version = (
+        service_version if service_version is not None else settings.service_version
+    )
+    attributes = {
+        key: value
+        for key, value in (("service.name", name), ("service.version", version))
+        if value is not None
+    }
+
+    provider = TracerProvider(resource=Resource.create(attributes))
+    if exporter is TraceExporter.CONSOLE:
+        provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
+    else:
+        provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
+    trace.set_tracer_provider(provider)
+    return True

{unique_toolkit-2026.34.0.dev2.dist-info → unique_toolkit-2026.34.0.dev4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-toolkit
-Version: 2026.34.0.dev2
+Version: 2026.34.0.dev4
 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.34.0.dev0,<2026.34.0rc0
+Requires-Dist: unique-sdk>=2026.34.0.dev1,<2026.34.0rc0
 Requires-Dist: jambo>=0.1.2,<0.2
 Requires-Dist: jinja2>=3.1.6,<4
 Requires-Dist: docxtpl>=0.20.1,<0.21
@@ -42,10 +42,13 @@ 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-Dist: opentelemetry-sdk>=1.27,<2 ; extra == 'otel'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27,<2 ; extra == 'otel'
 Requires-Python: >=3.12
 Provides-Extra: fastapi
 Provides-Extra: langchain
 Provides-Extra: monitoring
+Provides-Extra: otel
 Description-Content-Type: text/markdown
 
 # Unique Toolkit

{unique_toolkit-2026.34.0.dev2.dist-info → unique_toolkit-2026.34.0.dev4.dist-info}/RECORD

@@ -402,10 +402,11 @@ unique_toolkit/language_model/service.py,sha256=hDoJBBgG_wWs8WuC_c8tnmK8cNu8o5Eh
 unique_toolkit/language_model/settings.py,sha256=7szohExI-qmTfUf2Zp5AB5TzrsZy1UekAGyXx_UaPMc,1524
 unique_toolkit/language_model/stream_transform.py,sha256=iNNGpLY_7G6Bpp9Y4KtbIkQm3WB4yZt75BXcqx0DVkI,2775
 unique_toolkit/language_model/utils.py,sha256=bPQ4l6_YO71w-zaIPanUUmtbXC1_hCvLK0tAFc3VCRc,1902
-unique_toolkit/monitoring/__init__.py,sha256=z1gkOCLxGcg936MFuLSeWFa0tREcBFSUbV09NxilBw4,1065
+unique_toolkit/monitoring/__init__.py,sha256=auxvvOBwYrCD3TqEX0sIupDYx9nbCt2u4XN0Sy55qKI,1376
 unique_toolkit/monitoring/gunicorn.py,sha256=urTFFS5zYHKoxb1TEQHcLqb2byi-aYgFRHGwgYRzYYI,844
 unique_toolkit/monitoring/middleware.py,sha256=MNsUuKgt74mSnUwttXTB_AxX546Pz2zKoAP9OewVrwQ,4531
 unique_toolkit/monitoring/registry.py,sha256=De2Bx5QBBRJQY2MM3xtntiJ2JU2FoKkVT7rNMG7ewgA,5874
+unique_toolkit/monitoring/tracing.py,sha256=86yUIF8HrHVrkegOBOM7GqpbmVrYP07AZ4HtP-3X9QY,7128
 unique_toolkit/protocols/support.py,sha256=x5edzbBmKAUuvm3oLFh52gkgQsqR5LU7M0t8RHK0DZk,5161
 unique_toolkit/services/__init__.py,sha256=b9Wl7Wvz1JmZDbDexIZzBoXZ0wscXuczGAH8LoL-Qak,572
 unique_toolkit/services/chat_service.py,sha256=ofhNHCW7kz6xXN4pUTBdDEYovZ7PXhUglPDgez8Qov0,99142
@@ -419,6 +420,6 @@ unique_toolkit/short_term_memory/service.py,sha256=2JMBEBn6GoyK-a0xvdcWpPft-3C74
 unique_toolkit/smart_rules/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 unique_toolkit/smart_rules/compile.py,sha256=vRe0aMJWuVIK-VsqomgxQImzke7MDmwgSxxJfYCa7zw,1386
 unique_toolkit/test_utilities/events.py,sha256=FLrhMh0A_mQutAUjoD0FdMcVQ4Gq31r35OVGzRjvLro,6760
-unique_toolkit-2026.34.0.dev2.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
-unique_toolkit-2026.34.0.dev2.dist-info/METADATA,sha256=sSnbBxt3xMhYRWjORpXENMgfFSyVIc6ibCmenVbxoco,7494
-unique_toolkit-2026.34.0.dev2.dist-info/RECORD,,
+unique_toolkit-2026.34.0.dev4.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+unique_toolkit-2026.34.0.dev4.dist-info/METADATA,sha256=Rm135S4RxNJaS3bLkzg-PWh3tfyJBB2IyjCVUUgACT0,7656
+unique_toolkit-2026.34.0.dev4.dist-info/RECORD,,