otelzero 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,214 @@
1
+ """Rewrite third-party GenAI spans into the current conventions on their way out.
2
+
3
+ Some frameworks trace themselves through their own OpenTelemetry bridge rather
4
+ than through an otelzero import hook -- LangChain via the ``langsmith`` SDK --
5
+ and the dialect those bridges speak lags the conventions otelzero emits. The
6
+ pieces here sit in the OpenTelemetry pipeline and close that gap without
7
+ touching the agent code:
8
+
9
+ * :class:`TranslatingExporter` wraps any ``SpanExporter`` and hands each
10
+ finished span through :func:`translate` before passing it on. A finished
11
+ span is read-only, so a translated one is rebuilt rather than edited.
12
+ * :class:`IdentitySpanProcessor` stamps ``gen_ai.conversation.id`` and
13
+ ``user.name`` onto the bridge's spans at start, and records which spans are
14
+ the bridge's, so the exporter can tell a run's root from its steps even when
15
+ the run started inside an application's own span.
16
+
17
+ :func:`otelzero.otel.init_tracing` installs both, so an otelzero user who also
18
+ turns on a framework's bridge gets translated spans for free. A process that
19
+ builds its own ``TracerProvider`` wires them in by hand.
20
+
21
+ Each framework's mapping is a pure function over plain dicts in its own
22
+ module (:mod:`otelzero.translate.langsmith`), so a server ingesting raw OTLP
23
+ can run the identical mapping on the receiving side.
24
+ """
25
+
26
+ import threading
27
+ from collections import OrderedDict
28
+ from typing import Any, Callable, Optional, Sequence, Set, Tuple
29
+
30
+ from opentelemetry.context import Context
31
+ from opentelemetry.sdk.trace import ReadableSpan, SpanProcessor
32
+ from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
33
+ from opentelemetry.trace import Status, StatusCode
34
+
35
+ from otelzero import semconv
36
+ from otelzero.context import current_scope
37
+ from otelzero.translate import langsmith
38
+
39
+ # The bridge's tracer: ``get_tracer("langsmith")``.
40
+ LANGSMITH_SCOPE = "langsmith"
41
+
42
+
43
+ def _is_bridge_span(span: Any) -> bool:
44
+ name = getattr(getattr(span, "instrumentation_scope", None), "name", None)
45
+ return isinstance(name, str) and name.startswith(LANGSMITH_SCOPE)
46
+
47
+
48
+ class _BridgeSpans:
49
+ """Which span ids, per trace, the bridge started (bounded; oldest traces go first).
50
+
51
+ A run's root is the bridge span whose parent is *not* a bridge span: none
52
+ at all, or an application span the run was started inside (a web
53
+ request's, say). Parentage alone can't tell those apart at export, so the
54
+ processor records the bridge's spans as they start. The bridge always
55
+ starts a parent before its children.
56
+ """
57
+
58
+ MAX_TRACES = 2048
59
+
60
+ def __init__(self):
61
+ self._traces: "OrderedDict[int, Set[int]]" = OrderedDict()
62
+ self._lock = threading.Lock()
63
+
64
+ def add(self, trace_id: int, span_id: int) -> None:
65
+ with self._lock:
66
+ spans = self._traces.get(trace_id)
67
+ if spans is None:
68
+ spans = self._traces[trace_id] = set()
69
+ while len(self._traces) > self.MAX_TRACES:
70
+ self._traces.popitem(last=False)
71
+ spans.add(span_id)
72
+
73
+ def parent_is_bridge_span(self, span: Any) -> Optional[bool]:
74
+ """Whether the span's parent is the bridge's; ``None`` if this trace was never seen."""
75
+ with self._lock:
76
+ spans = self._traces.get(span.context.trace_id)
77
+ if spans is None:
78
+ return None
79
+ return span.parent.span_id in spans
80
+
81
+
82
+ _bridge_spans = _BridgeSpans()
83
+
84
+
85
+ def _is_root(span: ReadableSpan) -> bool:
86
+ if span.parent is None or not span.parent.is_valid:
87
+ return True
88
+ known = _bridge_spans.parent_is_bridge_span(span)
89
+ # Without the processor (a provider wired by hand, a server translating
90
+ # raw OTLP) there is nothing to go on but parentage.
91
+ return known is False
92
+
93
+
94
+ def translate(span: ReadableSpan) -> ReadableSpan:
95
+ """The span rewritten into the current conventions, or itself if not foreign."""
96
+ attributes = dict(span.attributes or {})
97
+ if not langsmith.is_langsmith(attributes):
98
+ return span
99
+ status = span.status
100
+ is_error = status is not None and status.status_code is StatusCode.ERROR
101
+ # The bridge marks every successful run OK; the conventions say a span that
102
+ # ended without error MUST leave its status unset.
103
+ if status is not None and status.status_code is StatusCode.OK:
104
+ status = Status(StatusCode.UNSET)
105
+ name, attributes = langsmith.translate_attributes(
106
+ span.name,
107
+ attributes,
108
+ is_root=_is_root(span),
109
+ is_error=is_error,
110
+ exception_message=_exception_message(span) if is_error else None,
111
+ )
112
+ return ReadableSpan(
113
+ name=name,
114
+ context=span.context,
115
+ parent=span.parent,
116
+ resource=span.resource,
117
+ attributes=attributes,
118
+ events=span.events,
119
+ links=span.links,
120
+ kind=span.kind,
121
+ status=status,
122
+ start_time=span.start_time,
123
+ end_time=span.end_time,
124
+ instrumentation_scope=span.instrumentation_scope,
125
+ )
126
+
127
+
128
+ def _exception_message(span: ReadableSpan) -> Optional[str]:
129
+ for event in span.events or ():
130
+ if event.name == "exception":
131
+ message = (event.attributes or {}).get("exception.message")
132
+ if isinstance(message, str):
133
+ return message
134
+ return None
135
+
136
+
137
+ class TranslatingExporter(SpanExporter):
138
+ """A ``SpanExporter`` that translates foreign spans before delegating."""
139
+
140
+ def __init__(self, inner: SpanExporter):
141
+ self.inner = inner
142
+
143
+ def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:
144
+ return self.inner.export([translate(span) for span in spans])
145
+
146
+ def shutdown(self) -> None:
147
+ self.inner.shutdown()
148
+
149
+ def force_flush(self, timeout_millis: int = 30000) -> bool:
150
+ return self.inner.force_flush(timeout_millis)
151
+
152
+
153
+ Identity = Callable[[], Tuple[Optional[str], Optional[str]]]
154
+
155
+
156
+ def _scope_identity() -> Tuple[Optional[str], Optional[str]]:
157
+ """``(user, conversation_id)`` from the active :func:`run_context`, if any."""
158
+ scope = current_scope()
159
+ if scope is None:
160
+ return None, None
161
+ return scope.user, scope.conversation_id
162
+
163
+
164
+ class IdentitySpanProcessor(SpanProcessor):
165
+ """Stamp identity onto the LangSmith bridge's spans, and record them.
166
+
167
+ Only the bridge's spans (instrumentation scope ``langsmith``) are touched.
168
+ otelzero's own hooks set ``gen_ai.conversation.id`` and ``user.name`` on the
169
+ spans they open, and frameworks traced natively (ADK, say) manage their
170
+ own; stamping theirs at start would pre-empt values they set later.
171
+
172
+ ``identity`` returns ``(user, conversation_id)`` -- a
173
+ :meth:`TelemetryClient.run_identity`-style callable -- and defaults to
174
+ reading the active :func:`~otelzero.context.run_context`. A span that
175
+ already carries a value keeps it.
176
+
177
+ The bridge builds its spans on a background tracing thread after the fact,
178
+ where no ``run_context`` is visible, so what this stamps is the client's
179
+ default identity. A LangChain run names its own user and thread through its
180
+ config metadata instead, which :mod:`otelzero.translate.langsmith` maps at
181
+ export, replacing the default.
182
+ """
183
+
184
+ def __init__(self, identity: Optional[Callable[[], Any]] = None):
185
+ self._identity = identity or _scope_identity
186
+
187
+ def on_start(self, span: Any, parent_context: Optional[Context] = None) -> None:
188
+ if not _is_bridge_span(span):
189
+ return
190
+ try:
191
+ _bridge_spans.add(span.context.trace_id, span.context.span_id)
192
+ except Exception: # pragma: no cover - a span without a context
193
+ pass
194
+ try:
195
+ user, conversation_id = self._identity()[:2]
196
+ except Exception: # pragma: no cover - never break a span for identity
197
+ return
198
+ attributes = span.attributes or {}
199
+ if conversation_id and not attributes.get(semconv.GEN_AI_CONVERSATION_ID):
200
+ span.set_attribute(semconv.GEN_AI_CONVERSATION_ID, conversation_id)
201
+ if user and not attributes.get(semconv.USER_NAME):
202
+ span.set_attribute(semconv.USER_NAME, user)
203
+
204
+ def on_end(self, span: ReadableSpan) -> None:
205
+ pass
206
+
207
+ def shutdown(self) -> None:
208
+ pass
209
+
210
+ def force_flush(self, timeout_millis: int = 30000) -> bool:
211
+ return True
212
+
213
+
214
+ __all__ = ["IdentitySpanProcessor", "TranslatingExporter", "translate"]
@@ -0,0 +1,401 @@
1
+ """Map LangSmith's OpenTelemetry spans onto the current GenAI conventions.
2
+
3
+ LangChain traces itself through the ``langsmith`` SDK, whose OpenTelemetry
4
+ bridge (``LANGSMITH_OTEL_ENABLED``) emits one span per run. Those spans speak
5
+ an older dialect of the GenAI conventions, and three things in it mislead a
6
+ backend that reads the current one:
7
+
8
+ * ``gen_ai.operation.name`` carries LangSmith's *run type* (``chain``,
9
+ ``parser``), and a prompt-template step is labelled ``chat`` -- so a backend
10
+ counting ``chat`` spans over-counts model calls.
11
+ * ``gen_ai.system`` is the deprecated attribute, and it holds ``langchain``
12
+ (the framework) unless the bridge can guess a provider from the model name.
13
+ * ``gen_ai.prompt`` / ``gen_ai.completion`` carry LangChain's internal JSON
14
+ unconditionally -- prompts leave the process even without the content opt-in.
15
+
16
+ :func:`translate_attributes` rewrites one span's name and attributes into the
17
+ vocabulary of :mod:`otelzero.semconv`. It is a pure function over plain dicts
18
+ -- no SDK types -- so the same mapping can run in the client's exporter (see
19
+ :mod:`otelzero.translate`) and in a server's OTLP ingest. Rules:
20
+
21
+ ================================== ===========================================
22
+ LangSmith Translated
23
+ ================================== ===========================================
24
+ root span of a trace ``invoke_agent {run name}``; the run name
25
+ (``langsmith.trace.name``) becomes
26
+ ``gen_ai.agent.name``
27
+ ``langsmith.span.kind = llm`` ``chat {model}``; ``gen_ai.provider.name``
28
+ from ``ls_provider``; decoded messages
29
+ ``langsmith.span.kind = tool`` ``execute_tool {tool}``
30
+ ``retriever`` / ``embedding`` ``retrieval`` / ``embeddings``
31
+ nested ``chain``/``prompt``/parser no ``gen_ai.operation.name`` at all: they
32
+ are not GenAI operations
33
+ ``gen_ai.system`` dropped
34
+ ``gen_ai.prompt`` / ``completion`` decoded into ``gen_ai.input.messages``,
35
+ ``gen_ai.output.messages`` and
36
+ ``gen_ai.system_instructions`` -- only when
37
+ the content opt-in is set; dropped otherwise
38
+ ``gen_ai.usage.total_tokens`` ``otelzero.usage.total_tokens``
39
+ ``ls_model_name`` ``gen_ai.request.model`` (if not set)
40
+ ``LANGSMITH_*``, ``revision_id``, dropped: configuration echoed onto every
41
+ ``lc_versions``, ``gen_ai.serialized.*`` span
42
+ metadata ``conversation_id`` / ``gen_ai.conversation.id`` / ``user.name``:
43
+ ``thread_id`` / ``session_id``, how a LangChain run names its thread and
44
+ ``user_name`` / ``user_id`` user (``config={"metadata": {...}}``); wins
45
+ over the identity stamped at span start
46
+ ================================== ===========================================
47
+
48
+ Every other attribute -- including the ``langsmith.*`` ones a LangSmith user
49
+ expects to keep -- passes through untouched. The span's status, events, timing
50
+ and identity are not this module's concern; the only error-related change is
51
+ filling in ``error.type``, which the conventions require on a failed span and
52
+ the bridge leaves out.
53
+ """
54
+
55
+ import json
56
+ import re
57
+ from typing import Any, Dict, Iterable, List, Optional, Tuple
58
+
59
+ from otelzero import semconv
60
+ from otelzero.hooks import _content
61
+
62
+ # --- LangSmith's vocabulary --------------------------------------------------
63
+ SPAN_KIND = "langsmith.span.kind"
64
+ TRACE_NAME = "langsmith.trace.name"
65
+ METADATA_PREFIX = "langsmith.metadata."
66
+ LS_PROVIDER = METADATA_PREFIX + "ls_provider"
67
+ LS_MODEL_NAME = METADATA_PREFIX + "ls_model_name"
68
+ LEGACY_PROMPT = "gen_ai.prompt"
69
+ LEGACY_COMPLETION = "gen_ai.completion"
70
+ LEGACY_TOTAL_TOKENS = "gen_ai.usage.total_tokens"
71
+
72
+ # Per-run identity rides LangChain's run metadata (``config={"metadata":
73
+ # {...}}``), which the bridge copies onto every span of the run. The keys are
74
+ # the ones LangSmith itself groups threads by, plus the obvious user spellings;
75
+ # the first present wins.
76
+ CONVERSATION_KEYS = ("conversation_id", "thread_id", "session_id")
77
+ USER_KEYS = ("user_name", "user_id", "user")
78
+ # Kept under their old names; otelzero.hooks._langsmith reads the public ones so
79
+ # a run's events and its spans name the same thread and user.
80
+ _CONVERSATION_KEYS = CONVERSATION_KEYS
81
+ _USER_KEYS = USER_KEYS
82
+
83
+ # Run types -> GenAI operations, where one exists. A root ``chain`` is the
84
+ # agent run; a nested chain/prompt/parser is a step with no operation of its own.
85
+ _KIND_OPERATIONS = {
86
+ "llm": semconv.OP_CHAT,
87
+ "tool": semconv.OP_EXECUTE_TOOL,
88
+ "retriever": semconv.OP_RETRIEVAL,
89
+ "embedding": semconv.OP_EMBEDDINGS,
90
+ }
91
+
92
+ # Attributes the bridge sets that the translation replaces or has no use for.
93
+ _DROP_EXACT = {
94
+ semconv.LEGACY_GEN_AI_SYSTEM,
95
+ semconv.GEN_AI_OPERATION_NAME,
96
+ LEGACY_PROMPT,
97
+ LEGACY_COMPLETION,
98
+ LEGACY_TOTAL_TOKENS,
99
+ METADATA_PREFIX + "revision_id",
100
+ METADATA_PREFIX + "lc_versions",
101
+ }
102
+ _DROP_PREFIXES = (METADATA_PREFIX + "LANGSMITH_", "gen_ai.serialized.")
103
+
104
+ # The bridge's exception event says ``exception.type = Exception`` and puts the
105
+ # real class in the message, as ``RuntimeError('...')``.
106
+ _EXC_CLASS = re.compile(r"^\s*([A-Za-z_][A-Za-z0-9_.]*)\(")
107
+
108
+
109
+ def is_langsmith(attributes: Optional[Dict[str, Any]]) -> bool:
110
+ """True for a span the LangSmith bridge produced."""
111
+ return bool(attributes) and SPAN_KIND in attributes
112
+
113
+
114
+ def translate_attributes(
115
+ name: str,
116
+ attributes: Dict[str, Any],
117
+ *,
118
+ is_root: bool,
119
+ is_error: bool = False,
120
+ exception_message: Optional[str] = None,
121
+ ) -> Tuple[str, Dict[str, Any]]:
122
+ """Rewrite one LangSmith span's ``(name, attributes)`` into the current conventions.
123
+
124
+ ``is_root`` says whether the span has no parent in its trace, which is what
125
+ makes a ``chain`` run *the* agent invocation. ``is_error`` and the bridge's
126
+ exception message feed ``error.type``. A span that is not LangSmith's is
127
+ returned unchanged.
128
+ """
129
+ if not is_langsmith(attributes):
130
+ return name, dict(attributes or {})
131
+
132
+ kind = attributes.get(SPAN_KIND)
133
+ out = {
134
+ key: value
135
+ for key, value in attributes.items()
136
+ if key not in _DROP_EXACT and not key.startswith(_DROP_PREFIXES)
137
+ }
138
+ # Opt-In in the conventions, unconditional in the bridge.
139
+ if not semconv.capture_content_enabled():
140
+ out.pop(semconv.GEN_AI_TOOL_DEFINITIONS, None)
141
+
142
+ if kind == "llm":
143
+ name = _translate_llm(name, attributes, out)
144
+ elif kind == "tool":
145
+ tool = attributes.get(semconv.GEN_AI_TOOL_NAME) or name
146
+ out[semconv.GEN_AI_OPERATION_NAME] = semconv.OP_EXECUTE_TOOL
147
+ out[semconv.GEN_AI_TOOL_NAME] = tool
148
+ name = semconv.span_name(semconv.OP_EXECUTE_TOOL, tool)
149
+ elif kind in _KIND_OPERATIONS:
150
+ out[semconv.GEN_AI_OPERATION_NAME] = _KIND_OPERATIONS[kind]
151
+ name = semconv.span_name(_KIND_OPERATIONS[kind], name)
152
+ elif is_root:
153
+ agent = attributes.get(TRACE_NAME) or name
154
+ out[semconv.GEN_AI_OPERATION_NAME] = semconv.OP_INVOKE_AGENT
155
+ out[semconv.GEN_AI_AGENT_NAME] = agent
156
+ name = semconv.span_name(semconv.OP_INVOKE_AGENT, agent)
157
+ inputs, outputs = _root_messages(
158
+ attributes.get(LEGACY_PROMPT), attributes.get(LEGACY_COMPLETION)
159
+ )
160
+ _set_content(
161
+ out,
162
+ input_messages=_content.messages_from(inputs, "user") if inputs else None,
163
+ output_messages=_content.messages_from(outputs, "assistant") if outputs else None,
164
+ )
165
+
166
+ _take_identity(out, _CONVERSATION_KEYS, semconv.GEN_AI_CONVERSATION_ID)
167
+ _take_identity(out, _USER_KEYS, semconv.USER_NAME)
168
+
169
+ total = attributes.get(LEGACY_TOTAL_TOKENS)
170
+ if isinstance(total, int):
171
+ out[semconv.OTELZERO_USAGE_TOTAL_TOKENS] = total
172
+
173
+ if is_error and semconv.ERROR_TYPE not in out:
174
+ out[semconv.ERROR_TYPE] = _error_type(exception_message)
175
+
176
+ return name, {k: v for k, v in out.items() if v is not None}
177
+
178
+
179
+ # --- Model calls -------------------------------------------------------------
180
+
181
+
182
+ def _translate_llm(name: str, attributes: Dict[str, Any], out: Dict[str, Any]) -> str:
183
+ model = attributes.get(semconv.GEN_AI_REQUEST_MODEL) or attributes.get(LS_MODEL_NAME)
184
+ out[semconv.GEN_AI_OPERATION_NAME] = semconv.OP_CHAT
185
+ if model:
186
+ out[semconv.GEN_AI_REQUEST_MODEL] = model
187
+ # ``ls_provider`` is what the integration says about itself; the bridge's
188
+ # ``gen_ai.system`` is only a guess from the model name, and ``langchain``
189
+ # there means it had no guess.
190
+ provider = attributes.get(LS_PROVIDER)
191
+ legacy = attributes.get(semconv.LEGACY_GEN_AI_SYSTEM)
192
+ if not provider and legacy and legacy != "langchain":
193
+ provider = legacy
194
+ if provider:
195
+ out[semconv.GEN_AI_PROVIDER_NAME] = provider
196
+
197
+ prompt = _loads(attributes.get(LEGACY_PROMPT))
198
+ completion = _loads(attributes.get(LEGACY_COMPLETION))
199
+ system, history = _split_system(_prompt_messages(prompt))
200
+ replies, reasons = _completion_messages(completion)
201
+ _set_content(
202
+ out,
203
+ input_messages=_content.messages_from(history, "user") if history else None,
204
+ output_messages=_content.messages_from(replies, "assistant") if replies else None,
205
+ system_instructions=_system_parts(system),
206
+ )
207
+ # Stop reasons are not content: recorded whether or not the user opted in,
208
+ # unless the bridge already read them off the response.
209
+ if semconv.GEN_AI_RESPONSE_FINISH_REASONS not in out:
210
+ out[semconv.GEN_AI_RESPONSE_FINISH_REASONS] = semconv.finish_reasons(reasons)
211
+ return semconv.span_name(semconv.OP_CHAT, model)
212
+
213
+
214
+ def _loads(raw: Any) -> Any:
215
+ if isinstance(raw, bytes):
216
+ raw = raw.decode("utf-8", "replace")
217
+ if not isinstance(raw, str) or not raw:
218
+ return None
219
+ try:
220
+ return json.loads(raw)
221
+ except ValueError:
222
+ return None
223
+
224
+
225
+ def _lc_message(obj: Any) -> Any:
226
+ """A serialised LangChain message as a ``role``/``content`` dict.
227
+
228
+ The bridge serialises messages two ways: the ``{"lc": 1, "id": [...,
229
+ "HumanMessage"], "kwargs": {...}}`` constructor envelope, and a plain
230
+ ``{"content": ..., "type": "human"}`` dump. Both carry the role under
231
+ ``type``; :mod:`otelzero.hooks._content` reads it from ``role``.
232
+ """
233
+ if isinstance(obj, dict) and obj.get("lc") == 1 and isinstance(obj.get("kwargs"), dict):
234
+ obj = obj["kwargs"]
235
+ if isinstance(obj, dict) and "role" not in obj and isinstance(obj.get("type"), str):
236
+ return {**obj, "role": obj["type"]}
237
+ return obj
238
+
239
+
240
+ def _prompt_messages(prompt: Any) -> List[Any]:
241
+ """The messages of an LLM run's ``gen_ai.prompt``.
242
+
243
+ A chat model records ``{"messages": [[...], ...]}`` -- one list per prompt
244
+ in the batch -- and a text-completion model ``{"prompts": ["..."]}``.
245
+ """
246
+ if not isinstance(prompt, dict):
247
+ return []
248
+ batches = prompt.get("messages")
249
+ if isinstance(batches, list):
250
+ return [_lc_message(m) for batch in batches for m in _flatten(batch)]
251
+ prompts = prompt.get("prompts")
252
+ if isinstance(prompts, list):
253
+ return [{"role": "user", "content": p} for p in prompts if isinstance(p, str)]
254
+ return []
255
+
256
+
257
+ def _flatten(batch: Any) -> Iterable[Any]:
258
+ return batch if isinstance(batch, list) else [batch]
259
+
260
+
261
+ def _split_system(messages: List[Any]) -> Tuple[List[Any], List[Any]]:
262
+ """System messages go to ``gen_ai.system_instructions``, the rest to the input."""
263
+ system = [m for m in messages if isinstance(m, dict) and m.get("role") == "system"]
264
+ history = [m for m in messages if m not in system]
265
+ return system, history
266
+
267
+
268
+ def _system_parts(system: List[Any]) -> Optional[List[dict]]:
269
+ parts: List[dict] = []
270
+ for message in system:
271
+ folded = _content.messages_from(message, "system")
272
+ for shaped in folded or []:
273
+ parts.extend(shaped.get("parts") or [])
274
+ return parts or None
275
+
276
+
277
+ def _completion_messages(completion: Any) -> Tuple[List[Any], List[str]]:
278
+ """The replies and stop reasons of an LLM run's ``gen_ai.completion``.
279
+
280
+ An ``LLMResult``: ``generations`` is a list (one per prompt) of lists (one
281
+ per choice) of ``{"text", "message", "generation_info"}``.
282
+ """
283
+ if not isinstance(completion, dict):
284
+ return [], []
285
+ replies: List[Any] = []
286
+ reasons: List[str] = []
287
+ for generation in _flatten(completion.get("generations") or []):
288
+ for choice in _flatten(generation):
289
+ if not isinstance(choice, dict):
290
+ continue
291
+ message = choice.get("message")
292
+ if message is not None:
293
+ replies.append(_lc_message(message))
294
+ elif isinstance(choice.get("text"), str):
295
+ replies.append({"role": "assistant", "content": choice["text"]})
296
+ info = choice.get("generation_info")
297
+ if isinstance(info, dict):
298
+ reason = _content.finish_reason(
299
+ info.get("finish_reason") or info.get("stop_reason")
300
+ )
301
+ if reason:
302
+ reasons.append(reason)
303
+ return replies, reasons
304
+
305
+
306
+ # --- Shared helpers ----------------------------------------------------------
307
+
308
+
309
+ def _take_identity(out: Dict[str, Any], keys: Iterable[str], attribute: str) -> None:
310
+ """Move the first present ``langsmith.metadata.<key>`` to ``attribute``.
311
+
312
+ The metadata names *this run's* thread and user, so it replaces whatever
313
+ the span was stamped with when it started. That stamp can only be the
314
+ client's process-wide default, because the bridge starts its spans on a
315
+ background thread where no ``run_context`` is in scope. Every matching key
316
+ is consumed; the first one present wins.
317
+ """
318
+ found = None
319
+ for key in keys:
320
+ value = out.pop(METADATA_PREFIX + key, None)
321
+ if value is not None and found is None:
322
+ found = str(value)
323
+ if found is not None:
324
+ out[attribute] = found
325
+
326
+
327
+ def _pair_message(obj: Any) -> Any:
328
+ """A ``[role, text]`` pair (how the bridge dumps a ``("user", "...")`` tuple) as a dict."""
329
+ if (
330
+ isinstance(obj, (list, tuple))
331
+ and len(obj) == 2
332
+ and isinstance(obj[0], str)
333
+ and isinstance(obj[1], str)
334
+ ):
335
+ return {"role": obj[0], "content": obj[1]}
336
+ return _lc_message(obj)
337
+
338
+
339
+ def _root_messages(prompt_raw: Any, completion_raw: Any) -> Tuple[Any, Any]:
340
+ """The input and output of a root run, as messages or text.
341
+
342
+ A graph or ``create_agent`` agent runs on a message state: the inputs are
343
+ ``{"messages": [...]}`` and the outputs ``{"messages": [...]}`` hold the
344
+ whole conversation, inputs first, so the run's own output is what follows
345
+ them. A chain's inputs and outputs are a ``{"input": ...}`` /
346
+ ``{"output": ...}`` payload instead.
347
+ """
348
+ prompt = _loads(prompt_raw)
349
+ completion = _loads(completion_raw)
350
+ inputs: Any = None
351
+ if isinstance(prompt, dict) and isinstance(prompt.get("messages"), list):
352
+ inputs = [_pair_message(m) for m in prompt["messages"]]
353
+ outputs: Any = None
354
+ if isinstance(completion, dict) and isinstance(completion.get("messages"), list):
355
+ history = [_pair_message(m) for m in completion["messages"]]
356
+ outputs = history[len(inputs):] if inputs is not None else history[-1:]
357
+ return (
358
+ inputs if inputs is not None else _io_text(prompt_raw, "input"),
359
+ outputs if outputs is not None else _io_text(completion_raw, "output"),
360
+ )
361
+
362
+
363
+ def _io_text(raw: Any, key: str) -> Optional[str]:
364
+ """The text of a chain run's ``{"input": ...}`` / ``{"output": ...}`` payload."""
365
+ data = _loads(raw)
366
+ if isinstance(data, dict):
367
+ value = data.get(key)
368
+ if isinstance(value, str):
369
+ return value or None
370
+ if isinstance(value, dict):
371
+ for inner in ("input", "question", "query", "prompt", "output", "answer"):
372
+ found = value.get(inner)
373
+ if isinstance(found, str) and found:
374
+ return found
375
+ elif isinstance(data, str):
376
+ return data or None
377
+ return None
378
+
379
+
380
+ def _set_content(
381
+ out: Dict[str, Any],
382
+ *,
383
+ input_messages=None,
384
+ output_messages=None,
385
+ system_instructions=None,
386
+ ) -> None:
387
+ """Land shaped content as the Opt-In attributes (``None`` sets nothing)."""
388
+ out[semconv.GEN_AI_INPUT_MESSAGES] = semconv.input_messages(input_messages)
389
+ out[semconv.GEN_AI_OUTPUT_MESSAGES] = semconv.output_messages(output_messages)
390
+ out[semconv.GEN_AI_SYSTEM_INSTRUCTIONS] = semconv.system_instructions(
391
+ system_instructions
392
+ )
393
+
394
+
395
+ def _error_type(exception_message: Optional[str]) -> str:
396
+ """A low-cardinality ``error.type``: the exception class, else the spec's fallback."""
397
+ if isinstance(exception_message, str):
398
+ match = _EXC_CLASS.match(exception_message)
399
+ if match:
400
+ return match.group(1).rsplit(".", 1)[-1]
401
+ return "_OTHER"