jX NdZddlmZddlZddlZddlmZmZddlm Z ddl m Z m Z ddl mZmZmZmZmZddlmZdd lmZmZmZdd lmZmZer dd lmZdd lmZej>e Z!ed Z"e GddZ#ddddedddd ddZ$y)u<``EventSession`` — Track B's LangSmith ``RunTree`` builder. The integrations that observe a remote event stream (OpenAI Realtime, OpenAI Agents realtime, ADK Live) all face the same problem: the service hands them an event stream rather than emitting its own telemetry for the live loop, so the trace has to be built by hand with the LangSmith SDK — one root span per conversation, one child span per meaningful event. ``EventSession`` is everything that pattern needs and would otherwise be duplicated across the adapters: * a root ``realtime_session`` span carrying the running transcript (``outputs``) and the stereo conversation WAV (attachment); * a child span per event (``event_span``), optionally grouped into ``turn`` spans; * point-in-time ``llm`` spans for terminal model responses (``record_llm``); * timestamped audio recording and a ``finalize`` that rolls up stats + WAV. Each adapter keeps only what is genuinely provider-specific: which events count as ``inbound`` (user→model, so the payload lands in span ``inputs``) and how to label each event span. ) annotationsN)IteratorSequence)contextmanager) dataclassfield) TYPE_CHECKINGAnyLiteralOptionalcast)RunTree)DEFAULT_MAX_AUDIO_SECONDSbuild_stereo_session_wav session_wav_exceeds_duration_cap) dump_eventscrub)Client) WriteReplica)toolchainllm retriever embeddingpromptparserceZdZUdZded<ded<ded<ded <d Zd ed <eZd ed<ee jZ ded<ee Z ded<ee Zded<eddZded<eddZded<eddZded<dZded<ee Zded<ed dZded <eddZded!<eddZded"<eddZded#<d:d$Zd;d%Zd;d&Zdd*Zd;d+Zd?d,Z d@d-Z!e"d.d d d d d/ dAd0Z# dBd1d d d d2 dCd3Z$d.d d d4 dDd5Z%d d d d6 dEd7Z&dFd8Z'd;d9Z(y )G EventSessionuConversation-level tracing state. One per conversation. The root span carries roll-up stats in metadata, the running conversation transcript as its ``outputs`` (so the LangSmith preview pane shows the whole exchange at a glance — see ``add_message``), and the stereo conversation WAV as an attachment. Each received event becomes a child span via ``event_span`` — nested under the current ``turn`` span if the adapter opted into turn grouping (see ``start_turn``), otherwise directly under the root. rrunstr thread_id Optional[str] project_nameint sample_rateNz Optional[int]max_audio_bytesOptional[float]max_audio_seconds)default_factoryfloatt0zlist[tuple[float, bytes]] user_chunks agent_chunksrF)defaultinit _user_bytes _agent_bytesbool_audio_truncated event_countzlist[dict[str, str]]messagesRunTree | None _current_turn _turn_count_turn_msg_start _title_setcDtj|jz S)uDSeconds since the session started — the timeline used for the WAV.)time monotonicr+selfs k/var/www/html/Fitness-lenito-AI-main/venv/lib/python3.12/site-packages/langsmith/_internal/voice/session.pynowzEventSession.nowas~~$''))c |j|xjdz c_t|j|_|j j ddidgdd|jii}|j||_y)aOpen a new conversational-turn span, closing the previous one. Subsequent ``event_span`` calls nest under this turn until the next ``start_turn`` (or ``finalize``). The turn's ``outputs`` become the transcript lines added during it, so each turn previews its own exchange. Opt-in: an adapter that never calls this keeps the flat root layout. turnrmetadatanamerun_typeinputstagsextraN) _close_turnr8lenr5r9r create_childpostr7)r?rEs r@ start_turnzEventSession.start_turnes  A"4==1xx$$(8(89: %  !rBc|jy|j|jd}|jj|rd|ini|jj d|_y)z>End the currently open turn span, if any, with its transcript.Nr5outputs)r7r5r9endpatch)r?msgss r@rMzEventSession._close_turn{sb    % }}T1134 T D'9rJ   "!rBc|xsdj}|r(|jj|t|dyy)aAppend one transcript line to the conversation rollup. Empty/whitespace content is ignored (failed transcriptions, silent turns). Content is truncated like any other span payload (see ``scrub``) so an unexpectedly large blob never bloats the root span. )rolecontentN)stripr5appendr)r?rZr[s r@ add_messagezEventSession.add_messages9=b'')  MM $5>!J K rBc|j|j|}|sy|xjt|z c_|jj ||fy)zRecord a timestamped chunk of user (mic) PCM16 for the stereo WAV. Dropped once the user channel reaches ``max_audio_bytes`` (see that field) so a long session can't exhaust memory. N)_bounded_audio_chunkr0rNr,r]r?tdatachunks r@ record_userzEventSession.record_usersO ))$*:*:DA  CJ& E +rBc|j|j|}|sy|xjt|z c_|jj ||fy)zRecord a timestamped chunk of agent (playback) PCM16 for the WAV. Dropped once the agent channel reaches ``max_audio_bytes`` (see that field) so a long session can't exhaust memory. N)r`r1rNr-r]ras r@ record_agentzEventSession.record_agentsO ))$*;*;TB  SZ'   !U,rBc|j|S|j|z }||dzz}|dkr|jyt||kr|S|j|d|S)NrrB)r&_note_audio_truncatedrN)r? current_bytesrc remainings r@r`z!EventSession._bounded_audio_chunksq    'K((=8 Y]" >  & & ( t9 !K ""$JYrBcV|jryd|_tjdy)z)Flag once that recorded audio was capped.NTzpvoice tracing: audio capture hit the configured cap; further audio for this conversation is dropped from the WAV)r3loggerwarningr>s r@rjz"EventSession._note_audio_truncateds(   $ J rBc|xsdj}|r |jrytdt||j_d|_y)aName the conversation root from its first user utterance (first wins). The root's ``name`` is what LangSmith shows in the trace / threads list, so naming it after the opening utterance makes conversations scannable instead of all reading ``realtime_session``. Only the first non-empty utterance applies; scrubbed like any other payload. The new name rides along on the root's ``patch`` at ``finalize``. rYNr T)r\r:r rrrH)r?texts r@ set_titlezEventSession.set_titles? !!#t UE$K0 rBc |jy|jjxsi}t|jdxsi}|j |||d<||j_y)u>Merge key/values into the open turn span's metadata (no-op if none). For per-turn metrics not known when the turn opens — e.g. ``latency_to_first_audio_ms``, ``was_interrupted``. Applied to the currently open turn, so call it before the next ``start_turn`` closes that turn. NrF)r7rLdictgetupdate)r?kvrLrFs r@add_turn_metadatazEventSession.add_turn_metadatase    % ""((.B *-34$j#( rBr)rIrJrTusage_metadatarFc#4K|xjdz c_tt|} |duxs |duxs|dk7} dt|di} | r| | d<| r| j | | t|} n | ri} n|r| ni} |j xs |j }|j||| dgd| i }|j |||jtd | | r |j| t|ni n|j|rin| |jy#||jtd | | r |j| t|ni n|j|rin| |jwxYww) uBOpen a child span for one received event; close it on body exit. Wrapping the handler body means any real work done while handling the event (e.g. tool execution) nests inside this span — the same way a tool call nests under the step that triggered it in any traced app. By default the raw (scrubbed) event payload is the span's I/O — in ``inputs`` for user→model (``inbound``) events, in ``outputs`` otherwise. Pass curated ``inputs``/``outputs`` (and optionally a ``run_type`` like "llm" plus ``usage_metadata``) to give the span readable, conversation-shaped I/O instead; the full wire payload is then preserved under ``metadata.raw_event``. Curated values pass through ``scrub`` too, so no un-scrubbed event data ever reaches a span. rDNr received_at_s raw_eventeventrFrGr ryrS) r4rrroundrvr7rrOrPsetr rUrV)r?r~t_nowrHinboundrIrJrTryrFpayloadcuratedmd run_inputsparentrs r@ event_spanzEventSession.event_spans8 A 5)*$Rt(;Rx7?R-uUA? %B{O  IIh   #FmJ J$+J##/txx!!r" "    I)tE>'BC'2Eg2Ng7; IIK )tE>'BC'2Eg2Ng7; IIKs B?FD-A'F-A(FFmodel)rHrJryrFc |xs|jxs |j}|7t|j}|r|dj ddk(r|dd}d|i}|j |dt |dgd|xsii }|j||jtd | |jt | |jy) uRecord a point-in-time ``llm`` child span for a model response. Voice services deliver a response as a *terminal* event (e.g. Realtime's ``response.done``), so there's no model-inference duration to measure — but the token usage, assistant message, and finish status still belong on an ``llm``-kind run for cost rollup and readability. Kept point-in-time and separate from the surrounding handler span so local tool latency is never attributed to the model call. ``parent`` defaults to the current turn (or the root). When ``inputs`` is omitted, it defaults to the model's *effective prompt* — the conversation transcript so far minus the response being recorded (the trailing assistant message) — so the ``llm`` run reads like a normal model call instead of having empty inputs. ``usage_metadata`` must be passed here, not patched on afterwards: cost is derived when the run is finalized, so usage that lands on a later patch (after ``end``) is not reflected. Services that report tokens on a separate, later event should defer this call until the counts arrive. NrZ assistantr5rrrFrGr rrS) r7rlistr5rurOrrPrr rUrV) r?rrHrTrJryrFcontextrs r@ record_llmzEventSession.record_llm s<94--9 >4==)G72;??62kA!#2, '*F!!=x~2. "    % GG4~#>G ? g' rB)rIrJrFc |xjdz c_|jxs |j}|j||| t |nidgd|xsii}|j |S)uOpen a child span and return it for the caller to ``close_span`` later. Unlike ``event_span`` (a context manager that fixes its ``outputs`` up front), this is for work whose result is only known at a *later* event — e.g. a tool call that spans a ``tool_start``/``tool_end`` pair, where the wall-clock gap between the two events is the real tool latency. Nests under the current turn (or the root) and counts toward ``event_count``, like any other event span. The caller must pair every ``open_span`` with a ``close_span`` (see the adapters' teardown, which closes any that were left open). rDr~rFrG)r4r7rrOrrP)r?rHrIrJrFrrs r@ open_spanzEventSession.open_spanQss& A##/txx!!$*$65=Bx~2. "    rB)rTryrFcJ||jtd||rT|jxsi}t|j dxsi}|j t |||d<||_|j| t |ni|jy)uEnd and patch a span previously opened with ``open_span``. Any error already set on ``run`` (``run.error``) is preserved. Outputs pass through ``scrub`` like every other span payload. ``metadata`` is merged into the run's existing metadata at close — for detail only known when the span ends (e.g. the raw wire payload of the event that closed it), so an ``open_span`` span can preserve it the way ``event_span`` does. It passes through ``scrub`` like any other payload. Nr rrFrS) rr rLrtrurvrrUrV)r?rrTryrFrLmergeds r@ close_spanzEventSession.close_spanps"  % GG4~#>G ? IIOE%))J/526F MM%/ * &E* CI '*=g2F rBcnt|j|j|j|jSN)rr,r-r%r(r>s r@_audio_exceeds_duration_capz(EventSession._audio_exceeds_duration_caps3/           " "   rBc*|j|jr|j|jjxsi}t |j dxsi}|j|d<ttj|jz d|d<|jrd|d<||d<||j_ t|j|j|j |j"}|rd d |fi|j_|jj-|j.rd |j.ini|jj1y#t$$rt&j)dd d }YwxYw)aRoll up stats, attach the stereo WAV, and close the root span. Best-effort: a failure building the WAV must not stop the root span from being closed, and finalize as a whole must not raise into the caller's teardown (see the adapters' ``__aexit__``). rFr4ri duration_sTaudio_truncated)max_duration_secondsz*voice tracing: failed to build session WAV)exc_inforB conversationz audio/wavr5rSN)rMrrjrrLrtrur4rr<r=r+r3rr,r-r%r( Exceptionrnro attachmentsrUr5rV)r?rLrFwavs r@finalizezEventSession.finalizes[   + + -  & & ( $ 4"#' *(=(C#D"&"2"2!&t~~'7$'''A1!E  *.H& '$j *  !!  %)%;%; C  c 2$DHH  DMMj$--8r R #  NNGRVN WC  s7E--"FF)returnr*)rNone)rZr r[r rr)rbr*rcbytesrr)rkr$rcrrr)rqr rr)rwr rr)r~r rr*rHr rr2rIRunKindrJdict[str, Any] | NonerTrryrrFrrzIterator[RunTree]r)rr6rHr rTzdict[str, Any]rJrryrrFrrr) rHr rIrrJrrFrrr) rrrTrryrrFrrr)rr2))__name__ __module__ __qualname____doc____annotations__r&rr(rr<r=r+rr,r-r0r1r3r4r5r7r8r9r:rArQrMr^rergr`rjrrrxrrrrrrrrBr@rr3s LN &*O]))BBdnn5B5.34-HK*H.3D.IL+IQU3K3ae4L#4"5u=d=K&+4%@H"@%*$U$CM>CQU3K3 7OS7U7J7*"," L , -    ) $(,)-04*.@@@  @  @@&@'@.@(@ @@H"&/(,04*.// /  / & /./(/ /j$(,*.   &  (  F*.04*.  '  .  (  8 ,rBrrealtime_session)r#rKrFrHr(clientreplicasintegration_versionc d|d|xsi| | d} |d|ini} |d|ini} td |di|xsgd| i|d | | }|j|t||zd znd}t|||||| S) uXCreate and post the conversation root span, returning an ``EventSession``. ``project_name`` falls back to LangSmith's standard resolution (``LANGSMITH_PROJECT``) when omitted, like any other ``RunTree``. ``client`` is an optional LangSmith ``Client`` for all tracing writes; child spans inherit it via ``create_child``. ``None`` uses the SDK's standard env-based client resolution. ``replicas`` mirrors the conversation trace to additional destinations (see LangSmith's tracing replicas). Set on the root and inherited by child spans via ``create_child``; ``None`` disables replication. ``max_audio_seconds`` caps how much audio per channel is retained and how far into the session the stereo WAV can extend, guarding memory on long-running sessions. The default is bounded; pass ``None`` to keep all audio. It is converted to a per-channel byte budget at PCM16 (2 bytes/sample). ``integration`` / ``integration_version`` stamp ``ls_integration`` and ``ls_integration_version`` on the root (the convention the batch integrations use) so LangSmith can attribute the trace to a specific integration and the framework version in use. Set authoritatively — a caller cannot shadow them via ``metadata``. ``integration_version`` may be ``None`` when the framework version can't be resolved. audio) ls_modalityr!)ls_integrationls_integration_versionNr#rrrF)rHrIrJrKrLrri)rr!r#r%r&r(r)rrPr$r)r!r%r#rKrFrHr(rr integrationrrproject_kwargs client_kwargsrr&s r@ start_sessionrsV  >r &"5  B8D7Onl3UWN+1*rs.# .%(>> @ 0   8 $ V W LL Lf #' $)-")B#15)-OOO O  O ' O O'O O/OO'OOrB