providers_kit/

hosted.rs

//! Closed provider-hosted request vocabulary and normalized hosted output.
//!
//! Declare [`HostedTool`] through [`crate::generation::ProviderToolSpec`]. The exact
//! selected Model checks support and renders the request; no tools-kit executor is
//! involved. [`HostedToolOutput`] retains reported activity without inventing
//! missing status or execution proof. Code declarations alone do not establish
//! execution, and hosted runtime failures may remain accepted result data.

use serde::{Deserialize, Serialize};

use crate::error::RemoteFailure;

pub use crate::generation::{Artifact, Citation};

/// Closed provider-hosted request declaration.
#[derive(Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize)]
#[serde(tag = "type", rename_all = "snake_case", deny_unknown_fields)]
pub enum HostedTool {
    /// Provider-managed web search.
    WebSearch,
    /// Provider-managed URL retrieval from URLs present in the request.
    UrlContext,
    /// Provider-managed search over exact provider store identifiers.
    FileSearch {
        /// Exact provider-native store identifiers to search.
        store_ids: Vec<String>,
    },
    /// Provider-managed code execution.
    CodeExecution,
}

/// Provider-managed hosted execution status.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "state", rename_all = "snake_case")]
pub enum HostedToolStatus {
    /// The provider is still executing the hosted tool.
    InProgress,
    /// The provider reports that the tool operation completed.
    ///
    /// Runtime results may still contain execution failures; completion alone
    /// does not establish that generated code ran successfully.
    Completed,
    /// Hosted execution ended without completing successfully.
    Incomplete,
    /// Hosted execution failed.
    Failed {
        /// Classified accepted failure with retained native evidence.
        error: RemoteFailure,
    },
}

/// Native action performed by hosted web research.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum HostedWebSearchAction {
    /// A search, retaining only queries and sources actually reported by the provider.
    Search {
        /// Primary query, when identified separately.
        query: Option<String>,
        /// Search queries reported by the provider.
        queries: Vec<String>,
        /// URL-bearing sources considered by the provider.
        sources: Vec<HostedWebSearchSource>,
    },
    /// A page opened by the provider.
    OpenPage {
        /// Target URL, when returned by the provider.
        url: Option<String>,
    },
    /// Text located within a page.
    FindInPage {
        /// Native target URL.
        url: String,
        /// Native search pattern.
        pattern: String,
    },
}

/// Source attached to hosted web search.
///
/// # Examples
///
/// ```
/// use providers_kit::hosted::HostedWebSearchSource;
/// let value = HostedWebSearchSource { title: None, url: "https://example.com/source".into() };
/// assert_eq!(value.url, "https://example.com/source");
/// ```
///
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct HostedWebSearchSource {
    /// Source title, when available.
    pub title: Option<String>,
    /// Absolute source URL.
    pub url: String,
}

/// One hosted web-search result.
///
/// # Examples
///
/// ```
/// use providers_kit::hosted::HostedWebSearchResult;
/// let value = HostedWebSearchResult {
///     title: None,
///     url: "https://example.com/source".into(),
///     snippet: Some("excerpt".into()),
/// };
/// assert_eq!(value.url, "https://example.com/source");
/// ```
///
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct HostedWebSearchResult {
    /// Result title, when available.
    pub title: Option<String>,
    /// Absolute result URL.
    pub url: String,
    /// Result excerpt, when available.
    pub snippet: Option<String>,
}

/// Executable code generated by a hosted runtime.
///
/// A code declaration alone does not prove that execution occurred or succeeded.
/// Inspect separately returned execution status, results, and artifacts.
///
/// # Examples
///
/// ```
/// use providers_kit::hosted::HostedExecutableCode;
/// let value = HostedExecutableCode { language: Some("python".into()), code: "print(1 + 1)".into() };
/// assert_eq!(value.code, "print(1 + 1)");
/// ```
///
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct HostedExecutableCode {
    /// Programming language, when reported.
    pub language: Option<String>,
    /// Provider-returned executable source declaration; execution requires separate evidence.
    pub code: String,
}

/// Result produced by hosted code execution.
///
/// # Examples
///
/// ```
/// use providers_kit::hosted::HostedCodeExecutionResult;
/// let value = HostedCodeExecutionResult {
///     status: None,
///     logs: None,
///     stdout: Some("2\n".into()),
///     stderr: None,
///     exit_code: Some(0),
/// };
/// assert_eq!(value.exit_code, Some(0));
/// ```
///
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct HostedCodeExecutionResult {
    /// Provider-authored execution status, when available.
    pub status: Option<HostedToolStatus>,
    /// Combined or otherwise unclassified runtime output, when returned.
    ///
    /// This is distinct from provider-identified stdout and stderr.
    pub logs: Option<String>,
    /// Captured standard output, when returned.
    pub stdout: Option<String>,
    /// Captured standard error, when returned.
    pub stderr: Option<String>,
    /// Process exit code, when reported.
    pub exit_code: Option<i64>,
}

/// One hosted file-search result.
///
/// # Examples
///
/// ```
/// use providers_kit::hosted::HostedFileSearchResult;
/// let value = HostedFileSearchResult {
///     file_id: "file-1".into(),
///     file_name: None,
///     text: Some("excerpt".into()),
///     score: None,
/// };
/// assert_eq!(value.file_id, "file-1");
/// assert_eq!(value.text.as_deref(), Some("excerpt"));
/// ```
///
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct HostedFileSearchResult {
    /// Exact provider-native file identifier.
    pub file_id: String,
    /// File name, when returned.
    pub file_name: Option<String>,
    /// Matching text excerpt, when returned.
    pub text: Option<String>,
    /// Provider-reported relevance score, when returned.
    pub score: Option<f64>,
}

/// One normalized provider-hosted operation or unpaired native activity.
///
/// Related invocation and result records are combined only when native identity
/// or an unambiguous native ordering establishes the relationship. A result from
/// an earlier turn can retain absent action or source fields. Opaque native replay
/// remains in the returned assistant continuation, independently of this projection.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(tag = "family", rename_all = "snake_case")]
pub enum HostedToolOutput {
    /// Provider-managed web-search output.
    WebSearch {
        /// Provider-authored execution status, when available.
        status: Option<HostedToolStatus>,
        /// Search action details, when returned.
        action: Option<HostedWebSearchAction>,
        /// Normalized search results.
        results: Vec<HostedWebSearchResult>,
        /// Citations returned by the provider.
        citations: Vec<Citation>,
    },
    /// Provider-managed file-search output.
    FileSearch {
        /// Provider-authored execution status, when available.
        status: Option<HostedToolStatus>,
        /// Search queries issued by the provider.
        queries: Vec<String>,
        /// `None` means the provider omitted result details; `Some([])` means included-empty.
        results: Option<Vec<HostedFileSearchResult>>,
        /// Citations returned by the provider.
        citations: Vec<Citation>,
    },
    /// Provider-managed code-execution output.
    CodeExecution {
        /// Provider-authored execution status, when available.
        status: Option<HostedToolStatus>,
        /// Provider-returned executable code declarations, independently of execution results.
        code: Vec<HostedExecutableCode>,
        /// Normalized execution results.
        results: Vec<HostedCodeExecutionResult>,
        /// Artifacts produced by execution.
        artifacts: Vec<Artifact>,
    },
    /// Provider-managed URL-retrieval output.
    UrlContext {
        /// URL supplied to this tool invocation, when reported.
        requested_url: Option<String>,
        /// URL the provider attempted to retrieve, when reported.
        retrieved_url: Option<String>,
        /// Provider-authored execution status, when available.
        status: Option<HostedToolStatus>,
        /// Citations returned by the provider.
        citations: Vec<Citation>,
    },
}