diff --git a/packages/uipath-llamaindex/pyproject.toml b/packages/uipath-llamaindex/pyproject.toml index e2ae5189..c326adb5 100644 --- a/packages/uipath-llamaindex/pyproject.toml +++ b/packages/uipath-llamaindex/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "uipath-llamaindex" -version = "0.6.2" +version = "0.6.3" description = "Python SDK that enables developers to build and deploy LlamaIndex agents to the UiPath Cloud Platform" readme = { file = "README.md", content-type = "text/markdown" } requires-python = ">=3.11" @@ -11,8 +11,8 @@ dependencies = [ "llama-index-embeddings-azure-openai>=0.4.1", "llama-index-llms-azure-openai>=0.4.2", "openinference-instrumentation-llama-index>=4.3.9", - "uipath>=2.14.41, <2.15.0", - "uipath-platform>=0.2.19, <0.3.0", + "uipath>=2.15.1, <2.16.0", + "uipath-platform>=0.3.2, <0.4.0", "uipath-runtime>=0.13.5, <0.14.0", ] classifiers = [ diff --git a/packages/uipath-llamaindex/src/uipath_llamaindex/_trace_context.py b/packages/uipath-llamaindex/src/uipath_llamaindex/_trace_context.py new file mode 100644 index 00000000..c51f55d4 --- /dev/null +++ b/packages/uipath-llamaindex/src/uipath_llamaindex/_trace_context.py @@ -0,0 +1,44 @@ +"""LLM Gateway trace context for UiPath LlamaIndex models. + +By default every UiPath model sends the caller's trace and span to the LLM +Gateway, which records the model call itself ("Model run", with its governance +and guardrail spans) inside the agent's trace. The client-side LLM span would +duplicate it, so the runtime doesn't create one. + +``UIPATH_USE_CLIENT_LLM_SPANS=true`` turns that around, for agents whose models +don't go through the Gateway: the client-side LLM span is kept and the +traceparent isn't sent, so the Gateway's spans stay out of the trace. The +baggage (folder / agent / job attribution) is still sent. +""" + +import logging +import os + +from uipath.platform.chat.llm_trace_context import build_trace_context_headers + +logger = logging.getLogger(__name__) + +USE_CLIENT_LLM_SPANS_ENV = "UIPATH_USE_CLIENT_LLM_SPANS" +TRACEPARENT_HEADER = "x-uipath-traceparent-id" +_TRACE_SOURCE = "source=llamaindex" + + +def use_client_llm_spans() -> bool: + """Whether the client-side LLM span is kept instead of the Gateway's.""" + return os.environ.get(USE_CLIENT_LLM_SPANS_ENV, "").strip().lower() in ( + "1", + "true", + "yes", + ) + + +def trace_context_headers() -> dict[str, str]: + """Headers for one LLM Gateway request, built from the active span.""" + try: + headers = build_trace_context_headers(extra_baggage=[_TRACE_SOURCE]) + except Exception: + logger.debug("could not build trace context headers", exc_info=True) + return {} + if use_client_llm_spans(): + headers.pop(TRACEPARENT_HEADER, None) + return headers diff --git a/packages/uipath-llamaindex/src/uipath_llamaindex/llms/_openai.py b/packages/uipath-llamaindex/src/uipath_llamaindex/llms/_openai.py index e47f74a0..3c3641f9 100644 --- a/packages/uipath-llamaindex/src/uipath_llamaindex/llms/_openai.py +++ b/packages/uipath-llamaindex/src/uipath_llamaindex/llms/_openai.py @@ -10,11 +10,13 @@ from uipath.platform.constants import HEADER_AGENTHUB_CONFIG from uipath.utils import EndpointManager +from .._trace_context import trace_context_headers from .supported_models import OpenAIModel class _UiPathSyncURLRewriteTransport(httpx.HTTPTransport): def handle_request(self, request: httpx.Request) -> httpx.Response: + request.headers.update(trace_context_headers()) original_url = str(request.url) if "/openai/deployments/" in original_url: @@ -31,6 +33,7 @@ def handle_request(self, request: httpx.Request) -> httpx.Response: class _UiPathAsyncURLRewriteTransport(httpx.AsyncHTTPTransport): async def handle_async_request(self, request: httpx.Request) -> httpx.Response: + request.headers.update(trace_context_headers()) original_url = str(request.url) if "/openai/deployments/" in original_url: diff --git a/packages/uipath-llamaindex/src/uipath_llamaindex/llms/bedrock.py b/packages/uipath-llamaindex/src/uipath_llamaindex/llms/bedrock.py index 328489de..b4faa278 100644 --- a/packages/uipath-llamaindex/src/uipath_llamaindex/llms/bedrock.py +++ b/packages/uipath-llamaindex/src/uipath_llamaindex/llms/bedrock.py @@ -6,6 +6,7 @@ from uipath.platform.constants import HEADER_AGENTHUB_CONFIG from uipath.utils import EndpointManager +from .._trace_context import trace_context_headers from .supported_models import BedrockModel logger = logging.getLogger(__name__) @@ -143,6 +144,7 @@ def _modify_request(self, request, **kwargs): if process_key: headers["X-UiPath-ProcessKey"] = process_key + headers.update(trace_context_headers()) request.headers.update(headers) diff --git a/packages/uipath-llamaindex/src/uipath_llamaindex/llms/vertex.py b/packages/uipath-llamaindex/src/uipath_llamaindex/llms/vertex.py index 109d78bb..a0502db4 100644 --- a/packages/uipath-llamaindex/src/uipath_llamaindex/llms/vertex.py +++ b/packages/uipath-llamaindex/src/uipath_llamaindex/llms/vertex.py @@ -10,6 +10,7 @@ from uipath.platform.constants import HEADER_AGENTHUB_CONFIG from uipath.utils import EndpointManager +from .._trace_context import trace_context_headers from .supported_models import GeminiModel logger = logging.getLogger(__name__) @@ -72,6 +73,7 @@ def _rewrite_request_for_gateway( # Design-time runs meter as CodedAgents.Playground; deployed -> AgentHub.LLM. if agenthub_config := resolve_coded_agenthub_config(): headers[HEADER_AGENTHUB_CONFIG] = agenthub_config + headers.update(trace_context_headers()) # Update host header to match the gateway URL gateway_url_parsed = httpx.URL(gateway_url) headers["host"] = gateway_url_parsed.host diff --git a/packages/uipath-llamaindex/src/uipath_llamaindex/runtime/_llm_spans.py b/packages/uipath-llamaindex/src/uipath_llamaindex/runtime/_llm_spans.py new file mode 100644 index 00000000..e65b2057 --- /dev/null +++ b/packages/uipath-llamaindex/src/uipath_llamaindex/runtime/_llm_spans.py @@ -0,0 +1,192 @@ +"""Leave the LLM span to the LLM Gateway. + +UiPath models send the trace-context headers, and the LLM Gateway records the +model call ("Model run") under the span they name. OpenInference's client-side +LLM span would duplicate it, so it isn't created, unless +``UIPATH_USE_CLIENT_LLM_SPANS`` is true (checked on every call). + +LlamaIndex nests spans by its own span ids, not by OTel context: each call gets +an id, and OpenInference looks its parent up by id. So an LLM call without a +span still needs three things, which the handlers below provide: + +* whatever it calls nests under its nearest ancestor that has a span; +* its exit and events are ignored, rather than logged as a missing span; +* the traceparent names that ancestor (``current_span``), so the Gateway's + span lands under the workflow step or agent that made the call. +""" + +from typing import Any, Optional + +from llama_index.core.base.llms.base import BaseLLM +from llama_index.core.instrumentation.events.exception import ExceptionEvent +from llama_index.core.instrumentation.events.llm import ( + LLMChatEndEvent, + LLMChatInProgressEvent, + LLMCompletionEndEvent, + LLMCompletionInProgressEvent, +) +from llama_index.core.instrumentation.span import active_span_id +from openinference.instrumentation.llama_index import ( + LlamaIndexInstrumentor, + get_current_span, +) +from openinference.instrumentation.llama_index._handler import ( + EventHandler, + _SpanHandler, +) +from opentelemetry.trace import Span + +from uipath_llamaindex._trace_context import use_client_llm_spans + +# What llama-index's chat / completion wrapper emits for a stream after the +# call has returned: one per chunk, then an end or (failed, closed) exception. +_STREAM_EVENTS = ( + LLMChatInProgressEvent, + LLMCompletionInProgressEvent, + LLMChatEndEvent, + LLMCompletionEndEvent, + ExceptionEvent, +) + + +class _SkippedLlmCalls: + """LLM calls with no span that are running, and where they nest instead. + + A call is kept only while it runs: llama-index always reports its exit or + drop, so nothing outlives it. A stream it returned emits more events with + its id later; those are recognised by their type (``_STREAM_EVENTS`` for a + span OpenInference doesn't know), so a stream that is never read costs + nothing. + """ + + def __init__(self) -> None: + self._parents: dict[str, Optional[str]] = {} + + def __contains__(self, span_id: object) -> bool: + return span_id in self._parents + + def __len__(self) -> int: + return len(self._parents) + + def skip(self, span_id: str, parent_id: Optional[str]) -> None: + self._parents[span_id] = parent_id + + def nearest_created(self, span_id: Optional[str]) -> Optional[str]: + """The span itself if it was created, otherwise its nearest ancestor.""" + if span_id in self._parents: + return self._parents[span_id] + return span_id + + def forget(self, span_id: str) -> None: + self._parents.pop(span_id, None) + + def clear(self) -> None: + self._parents.clear() + + +_skipped = _SkippedLlmCalls() + + +class _SkipLlmSpanHandler(_SpanHandler): + """OpenInference's span handler, without the spans of LLM calls.""" + + def new_span( + self, + id_: str, + bound_args: Any, + instance: Optional[Any] = None, + parent_span_id: Optional[str] = None, + tags: Optional[dict[str, Any]] = None, + **kwargs: Any, + ) -> Any: + parent_span_id = _skipped.nearest_created(parent_span_id) + if isinstance(instance, BaseLLM) and not use_client_llm_spans(): + _skipped.skip(id_, parent_span_id) + return None + return super().new_span( + id_, bound_args, instance, parent_span_id, tags, **kwargs + ) + + def prepare_to_exit_span( + self, + id_: str, + bound_args: Any, + instance: Optional[Any] = None, + result: Optional[Any] = None, + **kwargs: Any, + ) -> Any: + if id_ in _skipped: + _skipped.forget(id_) + return None + return super().prepare_to_exit_span(id_, bound_args, instance, result, **kwargs) + + def prepare_to_drop_span( + self, + id_: str, + bound_args: Any, + instance: Optional[Any] = None, + err: Optional[BaseException] = None, + **kwargs: Any, + ) -> Any: + if id_ in _skipped: + _skipped.forget(id_) + return None + return super().prepare_to_drop_span(id_, bound_args, instance, err, **kwargs) + + def knows(self, span_id: str) -> bool: + """Whether OpenInference has a span for this id, open or still streaming.""" + with self.lock: + if span_id in self.open_spans: + return True + return self._export_queue.find(span_id) is not None + + +class _SkipLlmEventHandler(EventHandler): + """OpenInference's event handler, ignoring events of LLM calls with no span.""" + + def handle(self, event: Any, **kwargs: Any) -> Any: + if event.span_id in _skipped: + return event + # A stream returned by a call with no span: the call is gone, and its + # later events would otherwise be logged as a missing span. + span_handler = self._span_handler + if ( + event.span_id + and isinstance(event, _STREAM_EVENTS) + and isinstance(span_handler, _SkipLlmSpanHandler) + and not span_handler.knows(event.span_id) + ): + return event + return super().handle(event, **kwargs) + + +def skip_client_llm_spans(instrumentor: LlamaIndexInstrumentor) -> None: + """Make an instrumented ``LlamaIndexInstrumentor`` skip LLM spans. Idempotent. + + OpenInference builds its handlers inside ``instrument()``, so we can't hand + it ours; instead the instances it built, already registered with + llama-index's dispatcher, become the subclasses above. + """ + span_handler = getattr(instrumentor, "_span_handler", None) + event_handler = getattr(instrumentor, "_event_handler", None) + if isinstance(span_handler, _SpanHandler): + object.__setattr__(span_handler, "__class__", _SkipLlmSpanHandler) + if isinstance(event_handler, EventHandler): + object.__setattr__(event_handler, "__class__", _SkipLlmEventHandler) + + +def current_span() -> Optional[Span]: + """The innermost span that was created: what the traceparent names. + + Inside an LLM call with no span, that's the workflow step or agent span + that made the call. + """ + span_id = active_span_id.get() + if span_id not in _skipped: + return get_current_span() + span_handler = getattr(LlamaIndexInstrumentor(), "_span_handler", None) + ancestor = _skipped.nearest_created(span_id) + if span_handler is None or ancestor is None: + return None + open_span = span_handler.open_spans.get(ancestor) + return open_span._otel_span if open_span is not None else None diff --git a/packages/uipath-llamaindex/src/uipath_llamaindex/runtime/factory.py b/packages/uipath-llamaindex/src/uipath_llamaindex/runtime/factory.py index 6ac6282f..0ffc94cc 100644 --- a/packages/uipath-llamaindex/src/uipath_llamaindex/runtime/factory.py +++ b/packages/uipath-llamaindex/src/uipath_llamaindex/runtime/factory.py @@ -3,10 +3,7 @@ import asyncio import os -from openinference.instrumentation.llama_index import ( - LlamaIndexInstrumentor, - get_current_span, -) +from openinference.instrumentation.llama_index import LlamaIndexInstrumentor from uipath.core.tracing import UiPathSpanUtils, UiPathTraceManager from uipath.platform.resume_triggers import UiPathResumeTriggerHandler from uipath.runtime import ( @@ -19,6 +16,7 @@ from uipath.runtime.errors import UiPathErrorCategory from workflows import Workflow +from uipath_llamaindex.runtime._llm_spans import current_span, skip_client_llm_spans from uipath_llamaindex.runtime._telemetry import ( ToolCallAttributeNormalizer, ) @@ -59,8 +57,12 @@ def __init__( def _setup_instrumentation(self, trace_manager: UiPathTraceManager | None) -> None: """Setup tracing and instrumentation.""" - LlamaIndexInstrumentor().instrument() - UiPathSpanUtils.register_current_span_provider(get_current_span) + instrumentor = LlamaIndexInstrumentor() + instrumentor.instrument() + # The LLM Gateway records "Model run", so the client-side LLM span + # isn't created (unless UIPATH_USE_CLIENT_LLM_SPANS is true). + skip_client_llm_spans(instrumentor) + UiPathSpanUtils.register_current_span_provider(current_span) if trace_manager: trace_manager.tracer_provider.add_span_processor( diff --git a/packages/uipath-llamaindex/testcases/template-agent/expected_traces.json b/packages/uipath-llamaindex/testcases/template-agent/expected_traces.json index dbb796b8..a79cf85d 100644 --- a/packages/uipath-llamaindex/testcases/template-agent/expected_traces.json +++ b/packages/uipath-llamaindex/testcases/template-agent/expected_traces.json @@ -36,12 +36,6 @@ "attributes": { "openinference.span.kind": "TOOL" } - }, - { - "name": ["UiPathChatBedrockConverse.achat", "UiPathOpenAI.achat", "UiPathVertex.achat"], - "attributes": { - "openinference.span.kind": "LLM" - } } ] } diff --git a/packages/uipath-llamaindex/tests/runtime/test_trace_context.py b/packages/uipath-llamaindex/tests/runtime/test_trace_context.py new file mode 100644 index 00000000..e363c73a --- /dev/null +++ b/packages/uipath-llamaindex/tests/runtime/test_trace_context.py @@ -0,0 +1,412 @@ +"""LLM Gateway trace context and client-side LLM spans. + +* every UiPath model sends the trace-context headers on each Gateway request; +* OpenInference no longer opens the client-side LLM span the Gateway's + "Model run" replaces, and the traceparent names the span that made the call; +* with ``UIPATH_USE_CLIENT_LLM_SPANS`` true, it's the other way around: the + client-side LLM span is kept and the traceparent isn't sent (the baggage is). +""" + +import asyncio +import gc +import logging +from collections.abc import Iterator +from types import SimpleNamespace +from typing import Any +from unittest.mock import patch + +import httpx +import pytest +from llama_index.core.instrumentation.events import BaseEvent +from llama_index.core.instrumentation.events.exception import ExceptionEvent +from llama_index.core.instrumentation.events.llm import ( + LLMChatEndEvent, + LLMChatInProgressEvent, + LLMChatStartEvent, + LLMCompletionEndEvent, + LLMCompletionInProgressEvent, +) +from llama_index.core.llms import ChatMessage, ChatResponse, CompletionResponse, MockLLM +from openinference.instrumentation.llama_index import LlamaIndexInstrumentor +from openinference.instrumentation.llama_index import _handler as _oi_handler +from opentelemetry.sdk.trace import ReadableSpan, Span, SpanProcessor, TracerProvider +from uipath.core.tracing import UiPathSpanUtils +from uipath.runtime import UiPathRuntimeContext +from workflows import Context, Workflow, step +from workflows.events import StartEvent, StopEvent + +from uipath_llamaindex._trace_context import ( + TRACEPARENT_HEADER, + USE_CLIENT_LLM_SPANS_ENV, + trace_context_headers, +) +from uipath_llamaindex.llms._openai import _UiPathSyncURLRewriteTransport +from uipath_llamaindex.llms.bedrock import AwsBedrockCompletionsPassthroughClient +from uipath_llamaindex.llms.vertex import _rewrite_request_for_gateway +from uipath_llamaindex.runtime import _llm_spans +from uipath_llamaindex.runtime._llm_spans import ( + _SkipLlmEventHandler, + _SkipLlmSpanHandler, + current_span, + skip_client_llm_spans, +) +from uipath_llamaindex.runtime.factory import UiPathLlamaIndexRuntimeFactory + +_TRACE_ID = "aabbccddeeff00112233445566778899" +_HEADERS = { + TRACEPARENT_HEADER: f"00-{_TRACE_ID}-1122334455667788-01", + "x-uipath-tracebaggage": "source=llamaindex", +} + +# What the model saw while generating: the headers a request would carry. +_seen: list[dict[str, str]] = [] + + +class _RecordingLLM(MockLLM): + def complete(self, prompt: str, formatted: bool = False, **kwargs: Any) -> Any: + _seen.append(trace_context_headers()) + return CompletionResponse(text="ok") + + +class _FailingLLM(MockLLM): + def complete(self, prompt: str, formatted: bool = False, **kwargs: Any) -> Any: + raise RuntimeError("gateway said no") + + +class _AskWorkflow(Workflow): + def __init__(self, llm: MockLLM, **kwargs: Any) -> None: + super().__init__(**kwargs) + self._llm = llm + + @step + async def ask(self, ctx: Context, ev: StartEvent) -> StopEvent: + reply = await self._llm.acomplete("hi") + return StopEvent(result=reply.text) + + +class _Recorder(SpanProcessor): + """Captures spans at start (what live tracking sees) and at end.""" + + def __init__(self) -> None: + self.started: list[Span] = [] + self.ended: list[ReadableSpan] = [] + + def on_start(self, span: Span, parent_context: Any = None) -> None: + self.started.append(span) + + def on_end(self, span: ReadableSpan) -> None: + self.ended.append(span) + + def kinds(self) -> list[Any]: + return [ + (s.attributes or {}).get("openinference.span.kind") for s in self.started + ] + + +@pytest.fixture(autouse=True) +def _reset(monkeypatch: pytest.MonkeyPatch) -> Iterator[None]: + monkeypatch.delenv(USE_CLIENT_LLM_SPANS_ENV, raising=False) + monkeypatch.setenv("UIPATH_TRACE_ID", _TRACE_ID) + _seen.clear() + _llm_spans._skipped.clear() + yield + _llm_spans._skipped.clear() + + +@pytest.fixture +def recorder() -> Iterator[_Recorder]: + """Instrument against a local provider, as the factory does.""" + instrumentor = LlamaIndexInstrumentor() + instrumentor.uninstrument() + provider = TracerProvider() + rec = _Recorder() + provider.add_span_processor(rec) + instrumentor.instrument(tracer_provider=provider) + skip_client_llm_spans(instrumentor) + UiPathSpanUtils.register_current_span_provider(current_span) + yield rec + instrumentor.uninstrument() + + +@pytest.fixture +def missing_span_warnings() -> Iterator[list[str]]: + """OpenInference's "Open span is missing" warnings, read off its logger. + + Not via caplog: other tests in the suite leave logging disabled or not + propagating, which would make an assertion on caplog pass vacuously. + """ + seen: list[str] = [] + + def record(msg: object, *args: Any, **kwargs: Any) -> None: + if "Open span is missing" in str(msg): + seen.append(str(msg)) + + with patch.object(_oi_handler.logger, "warning", side_effect=record): + yield seen + + +def _event_handler() -> _oi_handler.EventHandler: + handler = LlamaIndexInstrumentor()._event_handler + assert handler is not None + return handler + + +async def _run(llm: MockLLM) -> Any: + return await _AskWorkflow(llm=llm, timeout=10).run() + + +class TestSkipClientLlmSpans: + async def test_never_starts_client_llm_span(self, recorder: _Recorder) -> None: + assert await _run(_RecordingLLM(max_tokens=None)) == "ok" + + # Not just dropped at export: never started, so live tracking can't + # leave it behind as "running". + assert "LLM" not in recorder.kinds() + assert "_AskWorkflow.ask" in [s.name for s in recorder.started] + + async def test_traceparent_names_the_step_that_made_the_call( + self, recorder: _Recorder + ) -> None: + await _run(_RecordingLLM(max_tokens=None)) + + step_span = next(s for s in recorder.ended if s.name == "_AskWorkflow.ask") + span_id = format(step_span.context.span_id, "016x") + assert _seen[0][TRACEPARENT_HEADER] == f"00-{_TRACE_ID}-{span_id}-01" + assert "source=llamaindex" in _seen[0]["x-uipath-tracebaggage"] + + async def test_skipped_spans_log_no_missing_span_warnings( + self, recorder: _Recorder, caplog: pytest.LogCaptureFixture + ) -> None: + with caplog.at_level(logging.WARNING): + await _run(_RecordingLLM(max_tokens=None)) + + assert not [r for r in caplog.records if "Open span is missing" in r.message] + + async def test_model_error_still_propagates(self, recorder: _Recorder) -> None: + llm = _FailingLLM(max_tokens=None) + with pytest.raises(Exception, match="gateway said no"): + await _run(llm) + + step_span = next(s for s in recorder.ended if s.name == "_AskWorkflow.ask") + assert not step_span.status.is_ok + assert "LLM" not in recorder.kinds() + + async def test_skipped_spans_are_forgotten_when_the_call_ends( + self, recorder: _Recorder + ) -> None: + await _run(_RecordingLLM(max_tokens=None)) + assert not _llm_spans._skipped + + llm = _FailingLLM(max_tokens=None) + with pytest.raises(Exception, match="gateway said no"): + await _run(llm) + assert not _llm_spans._skipped + + async def test_streamed_call_is_forgotten_when_it_returns( + self, recorder: _Recorder, caplog: pytest.LogCaptureFixture + ) -> None: + with caplog.at_level(logging.WARNING): + stream = await MockLLM(max_tokens=None).astream_complete("a b c") + # The call has returned: nothing is kept, though iterating still + # emits its events. + assert not _llm_spans._skipped + chunks = [chunk.delta async for chunk in stream] + + assert "".join(c or "" for c in chunks) == "a b c" + assert "LLM" not in recorder.kinds() + assert not [r for r in caplog.records if "Open span is missing" in r.message] + assert not _llm_spans._skipped + + async def test_abandoned_async_stream_closes_without_warnings( + self, recorder: _Recorder, caplog: pytest.LogCaptureFixture + ) -> None: + with caplog.at_level(logging.WARNING): + stream = await MockLLM(max_tokens=None).astream_complete("a b c") + await anext(stream) + # Dropped half-way: the event loop closes it later, after it's + # collected, and closing emits an ExceptionEvent for its span id. + del stream + gc.collect() + for _ in range(5): + await asyncio.sleep(0) + + assert not [r for r in caplog.records if "Open span is missing" in r.message] + assert not _llm_spans._skipped + + def test_abandoned_sync_stream_closes_without_warnings( + self, recorder: _Recorder, caplog: pytest.LogCaptureFixture + ) -> None: + with caplog.at_level(logging.WARNING): + stream = MockLLM(max_tokens=None).stream_complete("a b c") + next(stream) + del stream + gc.collect() + + assert not [r for r in caplog.records if "Open span is missing" in r.message] + assert not _llm_spans._skipped + + async def test_async_stream_never_read_keeps_nothing( + self, recorder: _Recorder, caplog: pytest.LogCaptureFixture + ) -> None: + with caplog.at_level(logging.WARNING): + # Never iterated, so no end event will ever come for it. + stream = await MockLLM(max_tokens=None).astream_complete("a b c") + assert not _llm_spans._skipped + del stream + gc.collect() + for _ in range(5): + await asyncio.sleep(0) + + assert not [r for r in caplog.records if "Open span is missing" in r.message] + assert not _llm_spans._skipped + + def test_sync_stream_never_read_keeps_nothing( + self, recorder: _Recorder, caplog: pytest.LogCaptureFixture + ) -> None: + with caplog.at_level(logging.WARNING): + stream = MockLLM(max_tokens=None).stream_complete("a b c") + assert not _llm_spans._skipped + del stream + gc.collect() + + assert not [r for r in caplog.records if "Open span is missing" in r.message] + assert not _llm_spans._skipped + + @pytest.mark.parametrize( + "event", + [ + LLMChatInProgressEvent( + messages=[], response=ChatResponse(message=ChatMessage()) + ), + LLMChatEndEvent(messages=[], response=None), + LLMCompletionInProgressEvent( + prompt="", response=CompletionResponse(text="") + ), + LLMCompletionEndEvent(prompt="", response=CompletionResponse(text="")), + ExceptionEvent(exception=GeneratorExit()), + ], + ids=lambda e: type(e).__name__, + ) + def test_late_stream_event_of_unknown_span_is_ignored( + self, recorder: _Recorder, missing_span_warnings: list[str], event: Any + ) -> None: + # What a skipped call's stream emits after the call has returned. + event.span_id = "MockLLM.stream_chat-gone" + _event_handler().handle(event) + + assert not missing_span_warnings + + @pytest.mark.parametrize( + "event", + [ + LLMChatStartEvent(messages=[], additional_kwargs={}, model_dict={}), + BaseEvent(), + ], + ids=lambda e: type(e).__name__, + ) + def test_other_events_of_unknown_span_still_reach_openinference( + self, recorder: _Recorder, missing_span_warnings: list[str], event: Any + ) -> None: + # Only stream events are ignored: anything else for a span OpenInference + # doesn't know is still reported as missing. + event.span_id = "Something.else-gone" + _event_handler().handle(event) + + assert missing_span_warnings + + @pytest.mark.parametrize("value", ["true", "TRUE", "1", "yes"]) + async def test_client_llm_spans_env_keeps_span_and_drops_traceparent( + self, recorder: _Recorder, monkeypatch: pytest.MonkeyPatch, value: str + ) -> None: + monkeypatch.setenv(USE_CLIENT_LLM_SPANS_ENV, value) + await _run(_RecordingLLM(max_tokens=None)) + + assert "LLM" in recorder.kinds() + assert TRACEPARENT_HEADER not in _seen[0] + assert "source=llamaindex" in _seen[0]["x-uipath-tracebaggage"] + + @pytest.mark.parametrize("value", ["false", "0", ""]) + async def test_client_llm_spans_env_not_true_skips_span( + self, recorder: _Recorder, monkeypatch: pytest.MonkeyPatch, value: str + ) -> None: + monkeypatch.setenv(USE_CLIENT_LLM_SPANS_ENV, value) + await _run(_RecordingLLM(max_tokens=None)) + + assert "LLM" not in recorder.kinds() + assert TRACEPARENT_HEADER in _seen[0] + + async def test_skipping_twice_is_harmless(self, recorder: _Recorder) -> None: + skip_client_llm_spans(LlamaIndexInstrumentor()) + await _run(_RecordingLLM(max_tokens=None)) + + assert type(LlamaIndexInstrumentor()._span_handler) is _SkipLlmSpanHandler + assert "LLM" not in recorder.kinds() + + def test_factory_installs_the_skip(self, tmp_path: Any) -> None: + # Guards the private OpenInference handlers we subclass: if an upgrade + # renames them, this fails instead of client LLM spans silently coming back. + instrumentor = LlamaIndexInstrumentor() + instrumentor.uninstrument() + try: + UiPathLlamaIndexRuntimeFactory( + UiPathRuntimeContext( + runtime_dir=str(tmp_path), state_file=str(tmp_path / "state.db") + ) + ) + assert isinstance(instrumentor._span_handler, _SkipLlmSpanHandler) + assert isinstance(instrumentor._event_handler, _SkipLlmEventHandler) + finally: + instrumentor.uninstrument() + + +class TestModelsSendTraceHeaders: + def test_openai_transport(self) -> None: + request = httpx.Request( + "POST", "https://gw/openai/deployments/gpt/chat/completions" + ) + with ( + patch( + "uipath_llamaindex._trace_context.build_trace_context_headers", + return_value=dict(_HEADERS), + ), + patch.object( + httpx.HTTPTransport, "handle_request", return_value=httpx.Response(200) + ) as sent, + ): + _UiPathSyncURLRewriteTransport().handle_request(request) + + headers = sent.call_args.args[0].headers + assert headers[TRACEPARENT_HEADER] == _HEADERS[TRACEPARENT_HEADER] + assert headers["x-uipath-tracebaggage"] == "source=llamaindex" + + def test_bedrock_request_hook(self, monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("UIPATH_URL", "https://cloud.uipath.com") + request = SimpleNamespace(url="https://aws/model/m/converse", headers={}) + with patch( + "uipath_llamaindex._trace_context.build_trace_context_headers", + return_value=dict(_HEADERS), + ): + AwsBedrockCompletionsPassthroughClient( + "m", "tok", "converse" + )._modify_request(request) + + assert _HEADERS.items() <= request.headers.items() + + def test_vertex_request_rewrite(self) -> None: + request = httpx.Request( + "POST", "https://vertex/models/gemini:generateContent", content=b"{}" + ) + with patch( + "uipath_llamaindex._trace_context.build_trace_context_headers", + return_value=dict(_HEADERS), + ): + rewritten = _rewrite_request_for_gateway(request, "https://gw/vertex") + + assert rewritten.headers[TRACEPARENT_HEADER] == _HEADERS[TRACEPARENT_HEADER] + + def test_header_errors_never_break_the_request(self) -> None: + with patch( + "uipath_llamaindex._trace_context.build_trace_context_headers", + side_effect=RuntimeError("boom"), + ): + assert trace_context_headers() == {} diff --git a/packages/uipath-llamaindex/uv.lock b/packages/uipath-llamaindex/uv.lock index 8778c9fd..067f1ca8 100644 --- a/packages/uipath-llamaindex/uv.lock +++ b/packages/uipath-llamaindex/uv.lock @@ -3497,7 +3497,7 @@ wheels = [ [[package]] name = "uipath" -version = "2.14.41" +version = "2.15.1" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "applicationinsights" }, @@ -3522,23 +3522,23 @@ dependencies = [ { name = "uipath-platform" }, { name = "uipath-runtime" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/99/b3/a1eb57b26c1c36b4142470dc35c7daba55e5311eb243b1dc98915ea217d1/uipath-2.14.41.tar.gz", hash = "sha256:4a03cfd36517388b70b34f74a9fd4f1276aef07458abc902d1f063d312ddf26a", size = 4598519, upload-time = "2026-10-19T15:32:19.85Z" } +sdist = { url = "https://files.pythonhosted.org/packages/09/dd/4eba149cd1f3169193b33b0b5f61724996ee16b582eb8132f3eeda516516/uipath-2.15.1.tar.gz", hash = "sha256:88d5fe1ee06d949eaf441e2ea26ce4b801deb79df6f7d0756225a9fe7fc5bbb2", size = 4609499, upload-time = "2026-11-06T14:37:13.671Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/6e/47/ff05433a790bfc8138b52af0c356187e592d700ebb7134d3bc9dbb161417/uipath-2.14.41-py3-none-any.whl", hash = "sha256:d15592f1551b7cd3f912f59d4a785809e8965165280f961774a8045f1e87b7b9", size = 455996, upload-time = "2026-10-19T15:32:17.234Z" }, + { url = "https://files.pythonhosted.org/packages/ae/e7/b5c8f42e63c0aa64902074fe35a4aaa280f0742c1ed61bcbf57ff5d7f73d/uipath-2.15.1-py3-none-any.whl", hash = "sha256:86204534049005bbd2b33df4eced75798779ef2a0a5d2629780c2e07ed373da5", size = 459942, upload-time = "2026-11-06T14:37:11.033Z" }, ] [[package]] name = "uipath-core" -version = "0.5.33" +version = "0.5.34" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "opentelemetry-instrumentation" }, { name = "opentelemetry-sdk" }, { name = "pydantic" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/c6/32/8a254ae086cfa0ca9808d36b9084cffeea151b4250e77e84eed8c9dcde17/uipath_core-0.5.33.tar.gz", hash = "sha256:f533a3145131ce93bde78a264f98a796134dcd7a6ebf3211d8247a49d3b3eebc", size = 131308, upload-time = "2026-10-06T19:39:30.247Z" } +sdist = { url = "https://files.pythonhosted.org/packages/fc/7e/4e41e9278249a82cd8e14fbe5e407de480be338cde79fe4d09b647fdcaca/uipath_core-0.5.34.tar.gz", hash = "sha256:6511d72989e87f24d3ed3ac3649379c78bce0f82663300357354819d729a4ad8", size = 131912, upload-time = "2026-11-02T11:12:43.798Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/7a/15/3aa01f0011515c0508e966eabf6b0949d61d8c2c326cf83f943616733ec3/uipath_core-0.5.33-py3-none-any.whl", hash = "sha256:13c541c9b684e3f7556c830442b9fa48a3a42a36a38a3086195b10eeb4360ffb", size = 55133, upload-time = "2026-10-06T19:39:28.9Z" }, + { url = "https://files.pythonhosted.org/packages/b7/38/8f1b0db5987ad3607ba81bdd576fe71e5d941b2d9cf31ead262813c5efaf/uipath_core-0.5.34-py3-none-any.whl", hash = "sha256:f3e1168e4ae440cf425703f50986e5d29f635c5c6d4025b3b1f0eebad0e3622c", size = 55393, upload-time = "2026-11-02T11:12:42.089Z" }, ] [[package]] @@ -3552,7 +3552,7 @@ wheels = [ [[package]] name = "uipath-llamaindex" -version = "0.6.2" +version = "0.6.3" source = { editable = "." } dependencies = [ { name = "aiosqlite" }, @@ -3612,8 +3612,8 @@ requires-dist = [ { name = "llama-index-llms-google-genai", marker = "extra == 'vertex'", specifier = ">=0.8.0" }, { name = "llama-index-workflows", specifier = ">=2.18.0,<3.0.0" }, { name = "openinference-instrumentation-llama-index", specifier = ">=4.3.9" }, - { name = "uipath", specifier = ">=2.14.41,<2.15.0" }, - { name = "uipath-platform", specifier = ">=0.2.19,<0.3.0" }, + { name = "uipath", specifier = ">=2.15.1,<2.16.0" }, + { name = "uipath-platform", specifier = ">=0.3.2,<0.4.0" }, { name = "uipath-runtime", specifier = ">=0.13.5,<0.14.0" }, ] provides-extras = ["bedrock", "vertex"] @@ -3640,7 +3640,7 @@ dev = [ [[package]] name = "uipath-platform" -version = "0.2.40" +version = "0.3.2" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "anyio" }, @@ -3651,9 +3651,9 @@ dependencies = [ { name = "truststore" }, { name = "uipath-core" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/9f/a1/2a5c0f5be03e387802ab5347824e4a4830883734f07689b95da6f3f62ca9/uipath_platform-0.2.40.tar.gz", hash = "sha256:d694efd59a1be61d3b805ecec3e6604eb9d8272d952ed58a0812ebd814f8345d", size = 457625, upload-time = "2026-10-16T13:25:56.301Z" } +sdist = { url = "https://files.pythonhosted.org/packages/9b/bf/93244ad08e046ff0ae6f0286045899f0bcafc5dd5f0cff1bfc4efd76cf4e/uipath_platform-0.3.2.tar.gz", hash = "sha256:d763bbbd53a3d71aca82dd99f07bc8fd096b403dccd4dbcbfc30944e41b0fa64", size = 489635, upload-time = "2026-11-09T12:20:20.105Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/f6/e3/f66486aefa82b9c2db971213462bf051026705e928f27b7e7f063473ec16/uipath_platform-0.2.40-py3-none-any.whl", hash = "sha256:a652a210969ca844de65c9c672a0eb6f561bdc7575d1d6c05048fc0b5e673894", size = 295681, upload-time = "2026-10-16T13:25:54.739Z" }, + { url = "https://files.pythonhosted.org/packages/65/3d/8d84ede6aa14923a25c6b0a7c835469bc30e84a0bb69effefd040ba219fa/uipath_platform-0.3.2-py3-none-any.whl", hash = "sha256:f3a0e70352406e4aff937d2639bc29fdeb1a2535b92d5f0585be2b0edcc45380", size = 312480, upload-time = "2026-11-09T12:20:18.019Z" }, ] [[package]]