starweaver-model 0.5.0

Provider-neutral model protocol and wire adapters for Starweaver
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138

//! Canonical model message history items.

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use serde_json::Map;
use starweaver_core::{ConversationId, RunId};
use starweaver_usage::Usage;

use super::{
    ContentPart, FinishReason, Metadata, ModelRequestPart, ModelResponsePart, ProviderInfo,
    ToolCallPart,
};

/// Provider-neutral model history item.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum ModelMessage {
    /// A request sent to a model.
    Request(ModelRequest),
    /// A response returned by a model.
    Response(ModelResponse),
}

/// Request item in canonical model history.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
pub struct ModelRequest {
    /// Request parts sent in one model turn.
    pub parts: Vec<ModelRequestPart>,
    /// Creation timestamp.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub timestamp: Option<DateTime<Utc>>,
    /// Optional request-level instructions for the current model call.
    ///
    /// Provider mappers apply request-level instructions from the current instruction-bearing
    /// request, using Starweaver's request-level instruction behavior. Use
    /// `ModelRequestPart::SystemPrompt` for durable static system prompts, and use
    /// `ModelRequestPart::Instruction` metadata for structured instruction parts that need
    /// origin or dynamic-cache-boundary information, such as dynamic agent or toolset guidance.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub instructions: Option<String>,
    /// Run identifier.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub run_id: Option<RunId>,
    /// Conversation identifier.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub conversation_id: Option<ConversationId>,
    /// Application metadata.
    #[serde(default, skip_serializing_if = "Map::is_empty")]
    pub metadata: Metadata,
}

impl ModelRequest {
    /// Build a user request from text.
    #[must_use]
    pub fn user_text(text: impl Into<String>) -> Self {
        Self {
            parts: vec![ModelRequestPart::UserPrompt {
                content: vec![ContentPart::Text { text: text.into() }],
                name: None,
                metadata: Metadata::default(),
            }],
            timestamp: None,
            instructions: None,
            run_id: None,
            conversation_id: None,
            metadata: Metadata::default(),
        }
    }
}

/// Response item in canonical model history.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
pub struct ModelResponse {
    /// Response parts returned by the model.
    pub parts: Vec<ModelResponsePart>,
    /// Token and request usage.
    #[serde(default)]
    pub usage: Usage,
    /// Actual provider model name where known.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub model_name: Option<String>,
    /// Provider metadata.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub provider: Option<ProviderInfo>,
    /// Finish reason.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub finish_reason: Option<FinishReason>,
    /// Response timestamp.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub timestamp: Option<DateTime<Utc>>,
    /// Run identifier.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub run_id: Option<RunId>,
    /// Conversation identifier.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub conversation_id: Option<ConversationId>,
    /// Application metadata.
    #[serde(default, skip_serializing_if = "Map::is_empty")]
    pub metadata: Metadata,
}

impl ModelResponse {
    /// Build a text response.
    #[must_use]
    pub fn text(text: impl Into<String>) -> Self {
        Self {
            parts: vec![ModelResponsePart::Text { text: text.into() }],
            usage: Usage::default(),
            model_name: None,
            provider: None,
            finish_reason: None,
            timestamp: None,
            run_id: None,
            conversation_id: None,
            metadata: Metadata::default(),
        }
    }

    /// Concatenate all text response parts.
    #[must_use]
    pub fn text_output(&self) -> String {
        self.parts
            .iter()
            .filter_map(ModelResponsePart::text)
            .collect::<Vec<_>>()
            .join("")
    }

    /// Return all provider-neutral tool calls in the response.
    #[must_use]
    pub fn tool_calls(&self) -> Vec<ToolCallPart> {
        self.parts
            .iter()
            .filter_map(ModelResponsePart::tool_call)
            .cloned()
            .collect()
    }
}