switchyard_protocol/
envelope.rs

1// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2// SPDX-License-Identifier: Apache-2.0
3
4//! The request/response envelope: the normalized [`LlmRequest`]/[`LlmResponse`] paired
5//! with the original provider payload and correlation [`Metadata`].
6
7use crate::{LlmRequest, LlmResponse, Metadata, ModelId};
8
9/// A request an algorithm routes: the normalized [`LlmRequest`] plus optional
10/// host-owned raw data and correlation [`Metadata`].
11#[derive(Clone, Default)]
12pub struct Request {
13    /// The normalized request an algorithm routes.
14    pub llm_request: LlmRequest,
15    /// An optional whole request body retained by the host. libsy and the translation
16    /// codecs do not read it. Exact same-format codec replay instead uses
17    /// [`LlmRequest::preservation`].
18    pub raw_request: Option<serde_json::Value>,
19    /// Correlation metadata carried through the request.
20    pub metadata: Option<Metadata>,
21}
22
23impl Request {
24    /// Returns the model currently carried by the request, when present.
25    ///
26    /// On ingress this is the name supplied by the client. Before an offloaded model call, the
27    /// routing driver replaces it with the selected target.
28    pub fn model_id(&self) -> Option<ModelId> {
29        self.llm_request.model.as_deref().map(ModelId::from)
30    }
31}
32
33/// A response an algorithm returns: the [`LlmResponse`] (streamed or aggregate) plus
34/// optional correlation [`Metadata`].
35///
36/// Not `Clone` — `llm_response` may own a live stream.
37pub struct Response {
38    /// The neutral model response — a chunk stream or the buffered aggregate.
39    pub llm_response: LlmResponse,
40    /// Correlation metadata carried through the response.
41    pub metadata: Option<Metadata>,
42}
43
44impl Response {
45    /// Returns the model recorded by a buffered response.
46    ///
47    /// Returns `None` for a live stream because inspecting its `MessageStart`
48    /// event would require consuming the stream.
49    pub fn selected_model(&self) -> Option<&str> {
50        self.llm_response.selected_model()
51    }
52
53    /// Returns the Switchyard target that successfully served this response.
54    ///
55    /// Unlike [`Self::selected_model`], this is available for streamed responses because the
56    /// client records the target when it receives the stream handle.
57    pub fn served_model(&self) -> Option<&ModelId> {
58        self.metadata.as_ref()?.served_model.as_ref()
59    }
60
61    /// Records the Switchyard target that successfully served this response.
62    pub fn set_served_model(&mut self, model: &ModelId) {
63        self.metadata.get_or_insert_default().served_model = Some(model.clone());
64    }
65}
66
67#[cfg(test)]
68mod tests {
69    use super::*;
70    use crate::text_response;
71
72    #[test]
73    fn served_model_round_trips_through_response_metadata() {
74        let mut response = Response {
75            llm_response: LlmResponse::Agg(text_response(None, "answer")),
76            metadata: None,
77        };
78
79        assert_eq!(response.served_model(), None);
80        response.set_served_model(&ModelId::from("first"));
81        assert_eq!(response.served_model().map(ModelId::as_str), Some("first"));
82        response.set_served_model(&ModelId::from("fallback"));
83        assert_eq!(
84            response.served_model().map(ModelId::as_str),
85            Some("fallback")
86        );
87    }
88}
switchyard_protocol/envelope.rs

switchyard_protocol/
envelope.rs
