~tjX 0dZddlmZddlZddlZddlmZmZddlm Z ddl m Z m Z ddl mZmZmZmZmZddlmZdd lmZmZmZdd lmZmZer dd lmZdd lmZeje Z!ed Z"e GddZ#ddddeddddd'd&Z$dS)(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 j Z ded<ee Z ded<ee Zded<eddZded<eddZded<eddZded<dZded<ee Zded<ed dZded <eddZded!<eddZded"<eddZded#<dSd%ZdTd'ZdTd(ZdUd+ZdVd/ZdVd0ZdWd2ZdTd3ZdXd5Z dYd8Z!e"d9d d d d d:dZdGZ# d[dHd d d dId\dLZ$d9d d dMd]dNZ%d d d dOd^dPZ&d_dQZ'dTdRZ(d S)` 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_setreturnc8tj|jz S)uDSeconds since the session started — the timeline used for the WAV.)time monotonicr+selfs _/var/www/html/CA-Chatbot/venv/lib/python3.11/site-packages/langsmith/_internal/voice/session.pynowzEventSession.nowas~$'))Nonec ||xjdz c_t|j|_|jddidgdd|jii}|||_dS)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@rGs rA start_turnzEventSession.start_turnes  A"4=11x$$(89: %   !rCc|jdS|j|jd}|j|rd|ini|jd|_dS)z>End the currently open turn span, if any, with its transcript.Nr5outputs)r7r5r9endpatch)r@msgss rArOzEventSession._close_turn{sq   % F}T1334 T'I D'9'9rJJJ   """!rCrolecontentc|pd}|r,|j|t|ddSdS)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. )rZr[N)stripr5appendr)r@rZr[s rA add_messagezEventSession.add_messagesX=b''))  L M $5>>!J!J K K K K K L LrCtdatabytesc||j|}|sdS|xjt|z c_|j||fdS)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_chunkr0rPr,r_r@rarbchunks rA record_userzEventSession.record_usersd ))$*:DAA  F CJJ& E +++++rCc||j|}|sdS|xjt|z c_|j||fdS)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)rer1rPr-r_rfs rA record_agentzEventSession.record_agentsd ))$*;TBB  F SZZ'   !U,,,,,rC current_bytesc|j|S|j|z }||dzz}|dkr|dSt||kr|S||d|S)NrrC)r&_note_audio_truncatedrP)r@rkrb remainings rArez!EventSession._bounded_audio_chunks   'K(=8 Y]" >>  & & ( ( (3 t99 ! !K ""$$$JYJrCcZ|jrdSd|_tddS)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 rArnz"EventSession._note_audio_truncateds@    F $ J     rCtextc|pd}|r|jrdStdt||j_d|_dS)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 rrrJ)r@rss rA set_titlezEventSession.set_titlesS !!## t  FUE$KK00 rCkvr c |jdS|jjpi}t|dpi}||||d<||j_dS)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. NrH)r7rNdictgetupdate)r@rvrNrHs rAadd_turn_metadatazEventSession.add_turn_metadatasm   % F"(.B *--344$j#(   rCr)rKrLrVusage_metadatarHeventt_nowrJinboundrKRunKindrLdict[str, Any] | NonerVr|rHIterator[RunTree]c#K|xjdz c_tt|} |dup |dup|dk} dt|di} | r| | d<| r| | |t|} n | ri} n|r| ni} |jp|j}|||| dgd| i }| |V|$| td | | r(| |t|ni n| |rin| | dS#|$| td | | r(| |t|ni n| |rin| | wxYw) 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. rFNr received_at_s raw_eventr}rHrIr r|rU) r4rrroundrzr7rrQrRsetr rWrX)r@r}r~rJrrKrLrVr|rHpayloadcuratedmd run_inputsparentrs rA event_spanzEventSession.event_spans8 A 5))**$Rt(;Rx7?R-uUA?  &%B{O  IIh     #FmmJJ  4JJ$+3J#/tx!!r" "     III)tE>'B'BCCC <'2Eg2NNNNg :7;;; IIKKKKK )tE>'B'BCCC <'2Eg2NNNNg :7;;; IIKKKKs EBGmodel)rJrLr|rHrdict[str, Any]c|p |jp|j}|Ct|j}|r)|dddkr |dd}d|i}||dt |dgd|pii }||$|td | | t | | dS) 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 assistantr5rrrHrIr rrU) r7rlistr5ryrQrrRrr rWrX) r@rrJrVrLr|rHcontextrs rA record_llmzEventSession.record_llm s<94-9 >4=))G '72;??622kAA!#2#, '*F!!==x~2. "     % GG4~#>#>G ? ? ? g''' rC)rKrLrHc|xjdz c_|jp|j}||||t |nidgd|pii}||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). rFNr}rHrI)r4r7rrQrrR)r@rJrKrLrHrrs rA open_spanzEventSession.open_spanQs~& A#/tx!!$*$65===Bx~2. "     rC)rVr|rHc|$|td||r[|jpi}t|dpi}|t |||d<||_||t |ni|dS)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 rrHrU) rr rNrxryrzrrWrX)r@rrVr|rHrNmergeds rA close_spanzEventSession.close_spanps"  % GG4~#>#>G ? ? ?  IOE%))J//5266F MM%// * * * &E* CI '*=g2FFF rCcNt|j|j|j|jSN)rr,r-r%r(r?s rA_audio_exceeds_duration_capz(EventSession._audio_exceeds_duration_caps,/        "    rCc||r||jjpi}t |dpi}|j|d<ttj |j z d|d<|j rd|d<||d<||j_ t|j|j|j|j}n.#t$$r!t&dd d }YnwxYw|rd d |fi|j_|j|jr d |jini|jdS)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__``). rHr4rm duration_sTaudio_truncated)max_duration_secondsz*voice tracing: failed to build session WAV)exc_inforC conversationz audio/wavr5rUN)rOrrnrrNrxryr4rr=r>r+r3rr,r-r%r( Exceptionrqrr attachmentsrWr5rX)r@rNrHwavs rAfinalizezEventSession.finalizes   + + - - )  & & ( ( ( $ 4"#' *(=(=(C#D#D"&"2!&t~'7'7$''A1!E!E   /*.H& '$j * ! %)%; CC     NNGRVN W W WCCC     c 2$DH  DMQj$-88r RRR s'C++(DD)r;r*)r;rD)rZr r[r r;rD)rar*rbrcr;rD)rkr$rbrcr;rc)rsr r;rD)rvr r;rD)r}r r~r*rJr rr2rKrrLrrVrr|rrHrr;rr)rr6rJr rVrrLrr|rrHrr;rD) rJr rKrrLrrHrr;r) rrrVrr|rrHrr;rD)r;r2))__name__ __module__ __qualname____doc____annotations__r&rr(rr=r>r+rr,r-r0r1r3r4r5r7r8r9r:rBrSrOr`rhrjrernrur{rrrrrrrrCrArr3sLLLNNN &*O)))))BBBBBdn555B5555.3U4-H-H-HKHHHH.3eD.I.I.ILIIIIuQU333K3333ae444L4444"U5u=======K&+U4%@%@%@H@@@@%*E$U$C$C$CMCCCCuQU333K3333 5777O7777uU777J7777****"""","""" L L L L , , , , - - - -             )))) $(,)-04*.@@@@@^@H"&/(,04*.//////j$(,*. F*.04*. 8    ,,,,,,rCrrealtime_session)r#rMrHrJr(clientreplicasintegration_versionr!r r%r$r#r"rMOptional[list[str]]rHOptional[dict[str, Any]]rJr(r'rOptional[Client]r Optional[Sequence[WriteReplica]] integrationrr;c d|d|pi| | d} |d|ini} |d|ini} td |di|pgd| i|d | | }||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#rrrH)rJrKrLrMrNrrm)rr!r#r%r&r(r)rrRr$r)r!r%r#rMrHrJr(rrrrrproject_kwargs client_kwargsrr&s rA start_sessionrsV   >r &"5    B8D7Onl33UWN+1*rs.#""""" ........%%%%%%((((((((>>>>>>>>>>>>>> @???????1      000000  8 $ $ V W LLLLLLL Lf #' $)-")B#15)-OOOOOOOOrC