switchyard_protocol/
lib.rs

1// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2// SPDX-License-Identifier: Apache-2.0
3
4#![warn(missing_docs)]
5#![doc = include_str!("../README.md")]
6
7pub mod category;
8pub mod client;
9pub mod envelope;
10pub mod format;
11pub mod llm;
12pub mod metadata;
13pub mod model_id;
14pub mod stream;
15
16pub use category::*;
17pub use client::*;
18pub use envelope::*;
19pub use format::*;
20pub use llm::*;
21pub use metadata::*;
22pub use model_id::*;
23pub use stream::*;
24
25/// Builds a single-turn request: one user message carrying `prompt`, for `model`.
26///
27/// This deliberately creates only the common text shape. Construct [`LlmRequest`]
28/// directly for instructions, tools, multimodal content, or sampling controls.
29pub fn text_request(model: Option<String>, prompt: impl Into<String>) -> LlmRequest {
30    LlmRequest {
31        model,
32        messages: vec![Message::text(Role::User, prompt)],
33        ..LlmRequest::default()
34    }
35}
36
37/// Returns a lossy text view of all user messages, joined by newlines.
38///
39/// Only text and refusal blocks are included. Instructions, tool content,
40/// reasoning, and media are omitted. Returns an empty string when no user text exists.
41pub fn prompt_text(request: &LlmRequest) -> String {
42    request
43        .messages
44        .iter()
45        .filter(|message| message.role == Role::User)
46        .filter_map(|message| message.text_content("\n"))
47        .collect::<Vec<_>>()
48        .join("\n")
49}
50
51/// Builds a single-turn response: one assistant message carrying `completion`, for `model`.
52///
53/// Construct [`AggLlmResponse`] directly when usage, tools, reasoning, or multiple
54/// output items must be represented.
55pub fn text_response(model: Option<String>, completion: impl Into<String>) -> AggLlmResponse {
56    AggLlmResponse {
57        model,
58        outputs: vec![ResponseOutput {
59            role: Role::Assistant,
60            content: vec![ContentBlock::Text {
61                text: completion.into(),
62            }],
63            stop_reason: None,
64        }],
65        ..AggLlmResponse::default()
66    }
67}
68
69/// Returns a lossy text view of the first assistant output.
70///
71/// Only text blocks from the first output are concatenated. Refusals, reasoning,
72/// tools, media, and additional outputs are omitted. Returns an empty string when
73/// no such text exists.
74pub fn completion_text(response: &AggLlmResponse) -> String {
75    response
76        .outputs
77        .first()
78        .map(|output| {
79            output
80                .content
81                .iter()
82                .filter_map(|block| match block {
83                    ContentBlock::Text { text } => Some(text.as_str()),
84                    _ => None,
85                })
86                .collect::<String>()
87        })
88        .unwrap_or_default()
89}
90
91#[cfg(test)]
92mod tests {
93    use super::*;
94
95    #[test]
96    fn request_round_trips_prompt_text() {
97        let req = text_request(Some("m".to_string()), "hello world");
98        assert_eq!(req.model.as_deref(), Some("m"));
99        assert_eq!(prompt_text(&req), "hello world");
100    }
101
102    #[test]
103    fn response_round_trips_completion_text() {
104        let resp = text_response(None, "the answer");
105        assert_eq!(completion_text(&resp), "the answer");
106    }
107
108    #[test]
109    fn empty_text_helpers_are_empty_strings() {
110        assert_eq!(prompt_text(&LlmRequest::default()), "");
111        assert_eq!(completion_text(&AggLlmResponse::default()), "");
112    }
113}
switchyard_protocol/lib.rs

switchyard_protocol/
lib.rs
