ޠjX \SrSSKJr SSKrSSKrSSKJrJr SSKJ r SSK J r J r SSK JrJrJrJrJr SSKJr SS KJrJrJr SS KJrJr \(a SS KJr SS KJr \R>"\ 5r!\S r"\ "SS55r#SSSS\SSSS.SSjjr$g)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 embeddingpromptparserc\rSrSr%SrS\S'S\S'S\S'S \S 'S rS \S '\rS\S'\ "\ RS9r S\S'\ "\ S9rS\S'\ "\ S9rS\S'\ "SSS9rS \S'\ "SSS9rS \S'\ "SSS9rS\S'SrS \S'\ "\ S9rS\S'\ "S SS9rS \S!'\ "SSS9rS \S"'\ "SSS9rS \S#'\ "SSS9rS\S$'SS(jrS?S)jrS?S*jrS@S+jrS=S,jr SAS-jr!SBS.jr"\#S/S S S S S0.SCS1jj5r$SDS2S S S S3.SES4jjjr%S/S S S5.SFS6jjr&S S S S7.SGS8jjr'SHS9jr(S=S:jr)S;r*g )I EventSession3uConversation-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_setcF[R"5UR- $)uDSeconds since the session started — the timeline used for the WAV.)time monotonicr,selfs [/var/www/html/gaurav/venv/lib/python3.13/site-packages/langsmith/_internal/voice/session.pynowEventSession.nowas~~$''))c UR5 U=RS- sl[UR5UlUR R SS0S/SSUR00S9nUR5 Xlg)aWOpen 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_turnr9lenr6r:r create_childpostr8)r@rGs rA start_turnEventSession.start_turnes}  A"4==1xx$$(8(89: %  !rDcURcgURURSnURRU(aSU0O0S9 URR 5 SUlg)z>End the currently open turn span, if any, with its transcript.Nr6outputs)r8r6r:endpatch)r@msgss rArOEventSession._close_turn{sb    % }}T1134 T D'9rJ   "!rDcU=(d SR5nU(a(URRU[U5S.5 gg)zAppend 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)stripr6appendr)r@r^r_s rA add_messageEventSession.add_messages9=b'')  MM $5>!J K rDcURURU5nU(dgU=R[U5- slURR X45 g)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_chunkr1rPr-rar@tdatachunks rA record_userEventSession.record_usersM ))$*:*:DA  CJ&  +rDcURURU5nU(dgU=R[U5- slURR X45 g)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)rer2rPr.rarfs rA record_agentEventSession.record_agentsM ))$*;*;TB  SZ'   !,rDcURcU$URU- nX3S--nUS::aUR5 g[U5U::aU$UR5 USU$)NrrD)r'_note_audio_truncatedrP)r@ current_bytesrh remainings rAre!EventSession._bounded_audio_chunkso    'K((=8 ]" >  & & ( t9 !K ""$JYrDc`UR(agSUl[RS5 g)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)r4loggerwarningr?s rArq"EventSession._note_audio_truncateds(   $ J rDcU=(d SR5nU(aUR(ag[S[U55URlSUlg)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``. r]Nr!T)r`r;r rr rJ)r@texts rA set_titleEventSession.set_titles? !!#t UE$K0 rDc URcgURR=(d 0n[URS5=(d 05nUR U5 X2S'X Rlg)uMerge 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. NrH)r8rNdictgetupdate)r@kvrNrHs rAadd_turn_metadataEventSession.add_turn_metadatasa    % ""((.B *-34$j#( rDr)rKrLrWusage_metadatarHc## U=RS- sl[[U55n USL=(d USL=(d US:gn S[US50n U (aXS'U (aU R U 5 Ub [U5n OU (a0n O U(aU O0n UR =(d UR nURUUU S/SU 0S 9nUR5 Uv UbUR[S U5S 9 U (aURUb [U5O0S 9 OURU(a0OU S 9 UR5 g!UbUR[S U5S 9 U (aURUb [U5O0S 9 OURU(a0OU S 9 UR5 f=f7f) uOpen 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. rFNr received_at_s raw_eventeventrHrIr rrV) r5rrroundrr8r rQrRsetr rXrY)r@rt_nowrJinboundrKrLrWrrHpayloadcuratedmd run_inputsparentr s rA event_spanEventSession.event_spans8 A 5)*$Rt(;Rx7?R-uUA? %{O  IIh   #FmJ J$+J##/txx!!r" "    I)tE>'BC'2Eg2Ng7; IIK )tE>'BC'2Eg2Ng7; IIKs CF>"E&A*F>A+F;;F>model)rJrLrrHc U=(d UR=(d URnUc=[UR5nU(aUSR S5S:XaUSSnSU0nUR US[ U5S/SU=(d 00S 9nUR5 UbUR[S U5S 9 UR[ U5S 9 UR5 g) u1Record 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. Nr^ assistantr6rrrHrIr rrV) r8r listr6rrQrrRrr rXrY) r@rrJrWrLrrHcontextr s rA record_llmEventSession.record_llm s<94--9 >4==)G72;??62kA!#2, '*F!!=x~2. "    % GG4~#>G ? g' rD)rKrLrHc U=RS- slUR=(d URnURUUUb [ U5O0S/SU=(d 00S9nUR 5 U$)uQOpen 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). rFrrHrI)r5r8r rQrrR)r@rJrKrLrHrr s rA open_spanEventSession.open_spanQss& A##/txx!!$*$65=Bx~2. "    rD)rWrrHc\UbUR[SU5S9 U(a\UR=(d 0n[UR S5=(d 05nUR [ U55 XeS'XQlURUb [ U5O0S9 UR5 g)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 rrHrV) rr rNr~rrrrXrY)r@r rWrrHrNmergeds rA close_spanEventSession.close_spanps"  % GG4~#>G ? IIOE%))J/526F MM%/ * &* I '*=g2F rDcn[URURURUR5$N)rr-r.r&r)r?s rA_audio_exceeds_duration_cap(EventSession._audio_exceeds_duration_caps3/           " "   rDcTUR5 UR5(aUR5 URR=(d 0n[ UR S5=(d 05nURUS'[[R"5UR- S5US'UR(aSUS'X!S'XRl[URURUR UR"S9nU(aS S U40URlURR-UR.(aS UR.0O0S9 URR15 g![$a [&R)SSS 9 S nNf=f)zRoll 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__``). rHr5rp duration_sTaudio_truncated)max_duration_secondsz*voice tracing: failed to build session WAV)exc_inforD conversationz audio/wavr6rVN)rOrrqr rNr~rr5rr=r>r,r4rr-r.r&r) Exceptionrvrw attachmentsrXr6rY)r@rNrHwavs rAfinalizeEventSession.finalizesZ   + + - -  & & ( $ 4"#' *(=(C#D"&"2"2!&t~~'7$'''A1!E  *.H& '$j *  !!  %)%;%; C  c 2$DHH  DMMj$--8r R #  NNGRVN WC  s!4F F'&F')r4r8r;r:)returnr+)rNone)r^r!r_r!rr)rgr+rhbytesrr)rrr%rhrrr)rzr!rr)rr rr)rr rr+rJr!rr3rKRunKindrLdict[str, Any] | NonerWrrrrHrrzIterator[RunTree]r)rr7rJr!rWzdict[str, Any]rLrrrrHrrr) rJr!rKrrLrrHrrr) r rrWrrrrHrrr)rr3)+__name__ __module__ __qualname____firstlineno____doc____annotations__r'rr)rr=r>r,rr-r.r1r2r4r5r6r8r9r:r;rBrSrOrbrjrmrerqr{rrrrrrrr__static_attributes__rDrArr3s 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 ,rDrrealtime_session)r$rMrHrJr)clientreplicasintegration_versionc SUS.U=(d 0EU U S.En UbSU0O0n UbSU0O0n [S US0U=(d /SU 0US .U DU D6nUR5 Ub[Xa-S -5OSn[UUUUUUS 9$) u Create 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$rrrH)rJrKrLrMrNrrp)r r"r$r&r'r)r)rrRr%r)r"r&r$rMrHrJr)rr integrationrrproject_kwargs client_kwargsr r's rA start_sessionrsV  >r &"5  B8D7Onl3UWN+1*rs.# .%(>> @ 0   8 $ V W LL Lf #' $)-")B#15)-OOO O  O ' O O'O O/OO'OOrD