providers_kit/
hosted.rs

1//! Closed provider-hosted request vocabulary and normalized hosted output.
2//!
3//! Declare [`HostedTool`] through [`crate::generation::ProviderToolSpec`]. The exact
4//! selected Model checks support and renders the request; no tools-kit executor is
5//! involved. [`HostedToolOutput`] retains reported activity without inventing
6//! missing status or execution proof. Code declarations alone do not establish
7//! execution, and hosted runtime failures may remain accepted result data.
8
9use serde::{Deserialize, Serialize};
10
11use crate::error::RemoteFailure;
12
13pub use crate::generation::{Artifact, Citation};
14
15/// Closed provider-hosted request declaration.
16#[derive(Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize)]
17#[serde(tag = "type", rename_all = "snake_case", deny_unknown_fields)]
18pub enum HostedTool {
19    /// Provider-managed web search.
20    WebSearch,
21    /// Provider-managed URL retrieval from URLs present in the request.
22    UrlContext,
23    /// Provider-managed search over exact provider store identifiers.
24    FileSearch {
25        /// Exact provider-native store identifiers to search.
26        store_ids: Vec<String>,
27    },
28    /// Provider-managed code execution.
29    CodeExecution,
30}
31
32/// Provider-managed hosted execution status.
33#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
34#[serde(tag = "state", rename_all = "snake_case")]
35pub enum HostedToolStatus {
36    /// The provider is still executing the hosted tool.
37    InProgress,
38    /// The provider reports that the tool operation completed.
39    ///
40    /// Runtime results may still contain execution failures; completion alone
41    /// does not establish that generated code ran successfully.
42    Completed,
43    /// Hosted execution ended without completing successfully.
44    Incomplete,
45    /// Hosted execution failed.
46    Failed {
47        /// Classified accepted failure with retained native evidence.
48        error: RemoteFailure,
49    },
50}
51
52/// Native action performed by hosted web research.
53#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
54#[serde(tag = "type", rename_all = "snake_case")]
55pub enum HostedWebSearchAction {
56    /// A search, retaining only queries and sources actually reported by the provider.
57    Search {
58        /// Primary query, when identified separately.
59        query: Option<String>,
60        /// Search queries reported by the provider.
61        queries: Vec<String>,
62        /// URL-bearing sources considered by the provider.
63        sources: Vec<HostedWebSearchSource>,
64    },
65    /// A page opened by the provider.
66    OpenPage {
67        /// Target URL, when returned by the provider.
68        url: Option<String>,
69    },
70    /// Text located within a page.
71    FindInPage {
72        /// Native target URL.
73        url: String,
74        /// Native search pattern.
75        pattern: String,
76    },
77}
78
79/// Source attached to hosted web search.
80///
81/// # Examples
82///
83/// ```
84/// use providers_kit::hosted::HostedWebSearchSource;
85/// let value = HostedWebSearchSource { title: None, url: "https://example.com/source".into() };
86/// assert_eq!(value.url, "https://example.com/source");
87/// ```
88///
89#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
90pub struct HostedWebSearchSource {
91    /// Source title, when available.
92    pub title: Option<String>,
93    /// Absolute source URL.
94    pub url: String,
95}
96
97/// One hosted web-search result.
98///
99/// # Examples
100///
101/// ```
102/// use providers_kit::hosted::HostedWebSearchResult;
103/// let value = HostedWebSearchResult { title: None, url: "https://example.com/source".into(), snippet: Some("excerpt".into()) };
104/// assert_eq!(value.url, "https://example.com/source");
105/// ```
106///
107#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
108pub struct HostedWebSearchResult {
109    /// Result title, when available.
110    pub title: Option<String>,
111    /// Absolute result URL.
112    pub url: String,
113    /// Result excerpt, when available.
114    pub snippet: Option<String>,
115}
116
117/// Executable code generated by a hosted runtime.
118///
119/// A code declaration alone does not prove that execution occurred or succeeded.
120/// Inspect separately returned execution status, results, and artifacts.
121///
122/// # Examples
123///
124/// ```
125/// use providers_kit::hosted::HostedExecutableCode;
126/// let value = HostedExecutableCode { language: Some("python".into()), code: "print(1 + 1)".into() };
127/// assert_eq!(value.code, "print(1 + 1)");
128/// ```
129///
130#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
131pub struct HostedExecutableCode {
132    /// Programming language, when reported.
133    pub language: Option<String>,
134    /// Provider-returned executable source declaration; execution requires separate evidence.
135    pub code: String,
136}
137
138/// Result produced by hosted code execution.
139///
140/// # Examples
141///
142/// ```
143/// use providers_kit::hosted::HostedCodeExecutionResult;
144/// let value = HostedCodeExecutionResult { status: None, logs: None, stdout: Some("2\n".into()), stderr: None, exit_code: Some(0) };
145/// assert_eq!(value.exit_code, Some(0));
146/// ```
147///
148#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
149pub struct HostedCodeExecutionResult {
150    /// Provider-authored execution status, when available.
151    pub status: Option<HostedToolStatus>,
152    /// Combined or otherwise unclassified runtime output, when returned.
153    ///
154    /// This is distinct from provider-identified stdout and stderr.
155    pub logs: Option<String>,
156    /// Captured standard output, when returned.
157    pub stdout: Option<String>,
158    /// Captured standard error, when returned.
159    pub stderr: Option<String>,
160    /// Process exit code, when reported.
161    pub exit_code: Option<i64>,
162}
163
164/// One hosted file-search result.
165///
166/// # Examples
167///
168/// ```
169/// use providers_kit::hosted::HostedFileSearchResult;
170/// let value = HostedFileSearchResult { file_id: "file-1".into(), file_name: None, text: Some("excerpt".into()), score: None };
171/// assert_eq!(value.file_id, "file-1");
172/// assert_eq!(value.text.as_deref(), Some("excerpt"));
173/// ```
174///
175#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
176pub struct HostedFileSearchResult {
177    /// Exact provider-native file identifier.
178    pub file_id: String,
179    /// File name, when returned.
180    pub file_name: Option<String>,
181    /// Matching text excerpt, when returned.
182    pub text: Option<String>,
183    /// Provider-reported relevance score, when returned.
184    pub score: Option<f64>,
185}
186
187/// One normalized provider-hosted operation or unpaired native activity.
188///
189/// Related invocation and result records are combined only when native identity
190/// or an unambiguous native ordering establishes the relationship. A result from
191/// an earlier turn can retain absent action or source fields. Opaque native replay
192/// remains in the returned assistant continuation, independently of this projection.
193#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
194#[serde(tag = "family", rename_all = "snake_case")]
195pub enum HostedToolOutput {
196    /// Provider-managed web-search output.
197    WebSearch {
198        /// Provider-authored execution status, when available.
199        status: Option<HostedToolStatus>,
200        /// Search action details, when returned.
201        action: Option<HostedWebSearchAction>,
202        /// Normalized search results.
203        results: Vec<HostedWebSearchResult>,
204        /// Citations returned by the provider.
205        citations: Vec<Citation>,
206    },
207    /// Provider-managed file-search output.
208    FileSearch {
209        /// Provider-authored execution status, when available.
210        status: Option<HostedToolStatus>,
211        /// Search queries issued by the provider.
212        queries: Vec<String>,
213        /// `None` means the provider omitted result details; `Some([])` means included-empty.
214        results: Option<Vec<HostedFileSearchResult>>,
215        /// Citations returned by the provider.
216        citations: Vec<Citation>,
217    },
218    /// Provider-managed code-execution output.
219    CodeExecution {
220        /// Provider-authored execution status, when available.
221        status: Option<HostedToolStatus>,
222        /// Provider-returned executable code declarations, independently of execution results.
223        code: Vec<HostedExecutableCode>,
224        /// Normalized execution results.
225        results: Vec<HostedCodeExecutionResult>,
226        /// Artifacts produced by execution.
227        artifacts: Vec<Artifact>,
228    },
229    /// Provider-managed URL-retrieval output.
230    UrlContext {
231        /// URL supplied to this tool invocation, when reported.
232        requested_url: Option<String>,
233        /// URL the provider attempted to retrieve, when reported.
234        retrieved_url: Option<String>,
235        /// Provider-authored execution status, when available.
236        status: Option<HostedToolStatus>,
237        /// Citations returned by the provider.
238        citations: Vec<Citation>,
239    },
240}
providers_kit/hosted.rs

providers_kit/
hosted.rs
