unique-toolkit 2026.34.0.dev2__tar.gz → 2026.34.0.dev4__tar.gz

{unique_toolkit-2026.34.0.dev2 → unique_toolkit-2026.34.0.dev4}/PKG-INFO

@@ -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 → unique_toolkit-2026.34.0.dev4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_toolkit"
-version = "2026.34.0.dev2"
+version = "2026.34.0.dev4"
 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.34.0.dev0,<2026.34.0rc0",
+    "unique-sdk>=2026.34.0.dev1,<2026.34.0rc0",
     "jambo>=0.1.2,<0.2",
     "jinja2>=3.1.6,<4",
     "docxtpl>=0.20.1,<0.21",
@@ -63,6 +63,10 @@ fastapi = [
 monitoring = [
     "prometheus_client>=0.24.1,<1",
 ]
+otel = [
+    "opentelemetry-sdk>=1.27,<2",
+    "opentelemetry-exporter-otlp-proto-http>=1.27,<2",
+]
 [build-system]
 requires = ["uv_build>=0.8.14,<0.9.0"]
 build-backend = "uv_build"
@@ -73,6 +77,8 @@ module-root = ""
 [dependency-groups]
 dev = [
     "types-cachetools>=5.0,<6",
+    "opentelemetry-sdk>=1.27,<2",
+    "opentelemetry-exporter-otlp-proto-http>=1.27,<2",
 ]
 
 [tool.uv]
@@ -119,7 +125,14 @@ known_first_party = ["unique_toolkit"]
 extend_exclude = ["docs", "tests", "unique_toolkit/.*/test", "unique_toolkit/.*/tests"]
 
 [tool.deptry.per_rule_ignores]
-DEP002 = ["langchain", "fastapi", "starlette", "uvicorn"]
+DEP002 = [
+    "langchain",
+    "fastapi",
+    "starlette",
+    "uvicorn",
+    "opentelemetry-sdk",
+    "opentelemetry-exporter-otlp-proto-http",
+]
 DEP004 = ["langchain_openai", "langchain_core"]
 
 # -----------------------------------------------------------------------------

{unique_toolkit-2026.34.0.dev2 → unique_toolkit-2026.34.0.dev4}/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-2026.34.0.dev4/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