Skip to main content

pixie_pi/ai/
types.rs

1//! Core type system for the LLM abstraction layer.
2//!
3//! Mirrors `@earendil-works/pi-ai` types: messages, content blocks, usage,
4//! models, and tool schemas. These types are the boundary between the agent
5//! loop and the provider implementations.
6
7use serde::{Deserialize, Serialize};
8use serde_json::Value;
9
10/// Which wire protocol a model speaks. Beta targets only the Anthropic
11/// Messages API.
12#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
13#[serde(rename_all = "kebab-case")]
14pub enum Api {
15    #[default]
16    AnthropicMessages,
17}
18
19/// Why the assistant stopped generating.
20#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
21#[serde(rename_all = "camelCase")]
22pub enum StopReason {
23    #[default]
24    Stop,
25    Length,
26    ToolUse,
27    Error,
28    Aborted,
29}
30
31/// Reasoning/thinking level for models that support it.
32#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
33#[serde(rename_all = "lowercase")]
34pub enum ThinkingLevel {
35    Off,
36    Minimal,
37    Low,
38    #[default]
39    Medium,
40    High,
41    Xhigh,
42}
43
44impl ThinkingLevel {
45    pub fn parse(s: &str) -> Option<Self> {
46        Some(match s.to_ascii_lowercase().as_str() {
47            "off" => Self::Off,
48            "minimal" => Self::Minimal,
49            "low" => Self::Low,
50            "medium" => Self::Medium,
51            "high" => Self::High,
52            "xhigh" => Self::Xhigh,
53            _ => return None,
54        })
55    }
56}
57
58// ---------------------------------------------------------------------------
59// Content blocks
60// ---------------------------------------------------------------------------
61
62/// A single block within an assistant message. Mirrors pi's
63/// `TextContent | ThinkingContent | ToolCall`.
64#[derive(Debug, Clone, Serialize, Deserialize)]
65#[serde(tag = "type", rename_all = "camelCase")]
66pub enum ContentBlock {
67    Text {
68        text: String,
69    },
70    Thinking {
71        thinking: String,
72        thinking_signature: String,
73        #[serde(default)]
74        redacted: bool,
75    },
76    ToolCall {
77        id: String,
78        name: String,
79        arguments: Value,
80    },
81}
82
83impl ContentBlock {
84    pub fn as_text(&self) -> Option<&str> {
85        match self {
86            ContentBlock::Text { text } => Some(text),
87            _ => None,
88        }
89    }
90
91    pub fn is_tool_call(&self) -> bool {
92        matches!(self, ContentBlock::ToolCall { .. })
93    }
94
95    /// Returns (id, name, arguments) if this is a tool call.
96    pub fn as_tool_call(&self) -> Option<(&str, &str, &Value)> {
97        match self {
98            ContentBlock::ToolCall { id, name, arguments } => Some((id, name, arguments)),
99            _ => None,
100        }
101    }
102}
103
104/// A block within a user message. Mirrors `TextContent | ImageContent`.
105#[derive(Debug, Clone, Serialize, Deserialize)]
106#[serde(tag = "type", rename_all = "camelCase")]
107pub enum UserBlock {
108    Text { text: String },
109    Image { data: String, mime_type: String },
110}
111
112impl UserBlock {
113    pub fn text(s: impl Into<String>) -> Self {
114        UserBlock::Text { text: s.into() }
115    }
116}
117
118/// Content returned from a tool execution. Mirrors the tool-result content.
119#[derive(Debug, Clone, Serialize, Deserialize)]
120#[serde(tag = "type", rename_all = "camelCase")]
121pub enum ToolResultContent {
122    Text { text: String },
123    Image { data: String, mime_type: String },
124}
125
126impl ToolResultContent {
127    pub fn text(s: impl Into<String>) -> Self {
128        ToolResultContent::Text { text: s.into() }
129    }
130}
131
132// ---------------------------------------------------------------------------
133// Messages
134// ---------------------------------------------------------------------------
135
136/// A user-authored message.
137#[derive(Debug, Clone, Serialize, Deserialize)]
138pub struct UserMessage {
139    pub content: Vec<UserBlock>,
140    #[serde(default = "crate::ai::now_ms")]
141    pub timestamp: i64,
142}
143
144impl UserMessage {
145    pub fn new(content: Vec<UserBlock>) -> Self {
146        Self {
147            content,
148            timestamp: crate::ai::now_ms(),
149        }
150    }
151
152    pub fn text(text: impl Into<String>) -> Self {
153        Self::new(vec![UserBlock::text(text)])
154    }
155
156    /// Concatenated plain-text view (images omitted).
157    pub fn text_content(&self) -> String {
158        self.content
159            .iter()
160            .filter_map(|b| match b {
161                UserBlock::Text { text } => Some(text.as_str()),
162                _ => None,
163            })
164            .collect::<Vec<_>>()
165            .join("\n")
166    }
167}
168
169/// A message produced by the model.
170#[derive(Debug, Clone, Serialize, Deserialize)]
171pub struct AssistantMessage {
172    pub content: Vec<ContentBlock>,
173    #[serde(default)]
174    pub usage: Usage,
175    #[serde(default)]
176    pub stop_reason: StopReason,
177    #[serde(default, skip_serializing_if = "Option::is_none")]
178    pub error_message: Option<String>,
179    #[serde(default, skip_serializing_if = "Option::is_none")]
180    pub response_id: Option<String>,
181    #[serde(default)]
182    pub model: String,
183    #[serde(default)]
184    pub provider: String,
185    #[serde(default = "crate::ai::now_ms")]
186    pub timestamp: i64,
187}
188
189impl AssistantMessage {
190    pub fn empty() -> Self {
191        Self {
192            content: Vec::new(),
193            usage: Usage::default(),
194            stop_reason: StopReason::Stop,
195            error_message: None,
196            response_id: None,
197            model: String::new(),
198            provider: String::new(),
199            timestamp: crate::ai::now_ms(),
200        }
201    }
202
203    pub fn text_content(&self) -> String {
204        self.content
205            .iter()
206            .filter_map(|b| b.as_text())
207            .collect::<Vec<_>>()
208            .join("")
209    }
210}
211
212/// A tool-result message fed back to the model.
213#[derive(Debug, Clone, Serialize, Deserialize)]
214pub struct ToolResultMessage {
215    pub tool_call_id: String,
216    pub tool_name: String,
217    pub content: Vec<ToolResultContent>,
218    #[serde(default)]
219    pub is_error: bool,
220    #[serde(default = "crate::ai::now_ms")]
221    pub timestamp: i64,
222}
223
224/// The union of messages that make up a transcript.
225#[derive(Debug, Clone, Serialize, Deserialize)]
226#[serde(tag = "role", rename_all = "camelCase")]
227pub enum Message {
228    User(UserMessage),
229    Assistant(AssistantMessage),
230    ToolResult(ToolResultMessage),
231}
232
233impl Message {
234    pub fn role(&self) -> &'static str {
235        match self {
236            Message::User(_) => "user",
237            Message::Assistant(_) => "assistant",
238            Message::ToolResult(_) => "toolResult",
239        }
240    }
241}
242
243impl From<UserMessage> for Message {
244    fn from(m: UserMessage) -> Self {
245        Message::User(m)
246    }
247}
248impl From<AssistantMessage> for Message {
249    fn from(m: AssistantMessage) -> Self {
250        Message::Assistant(m)
251    }
252}
253impl From<ToolResultMessage> for Message {
254    fn from(m: ToolResultMessage) -> Self {
255        Message::ToolResult(m)
256    }
257}
258
259// ---------------------------------------------------------------------------
260// Usage / cost
261// ---------------------------------------------------------------------------
262
263#[derive(Debug, Clone, Default, Serialize, Deserialize)]
264pub struct Cost {
265    #[serde(default)]
266    pub input: f64,
267    #[serde(default)]
268    pub output: f64,
269    #[serde(default)]
270    pub cache_read: f64,
271    #[serde(default)]
272    pub cache_write: f64,
273    #[serde(default)]
274    pub total: f64,
275}
276
277#[derive(Debug, Clone, Default, Serialize, Deserialize)]
278pub struct Usage {
279    #[serde(default)]
280    pub input: u64,
281    #[serde(default)]
282    pub output: u64,
283    #[serde(default)]
284    pub cache_read: u64,
285    #[serde(default)]
286    pub cache_write: u64,
287    #[serde(default)]
288    pub total_tokens: u64,
289    #[serde(default)]
290    pub cost: Cost,
291}
292
293impl Usage {
294    pub fn add(&mut self, other: &Usage) {
295        self.input += other.input;
296        self.output += other.output;
297        self.cache_read += other.cache_read;
298        self.cache_write += other.cache_write;
299        self.total_tokens += other.total_tokens;
300        self.cost.input += other.cost.input;
301        self.cost.output += other.cost.output;
302        self.cost.cache_read += other.cost.cache_read;
303        self.cost.cache_write += other.cost.cache_write;
304        self.cost.total += other.cost.total;
305    }
306
307    pub fn recompute_total(&mut self) {
308        self.total_tokens = self.input + self.output + self.cache_read + self.cache_write;
309    }
310}
311
312// ---------------------------------------------------------------------------
313// Model
314// ---------------------------------------------------------------------------
315
316/// A resolved model definition used to drive provider requests.
317#[derive(Debug, Clone, Serialize, Deserialize)]
318pub struct Model {
319    pub id: String,
320    pub provider: String,
321    pub api: Api,
322    /// Maximum output tokens the model can produce in one turn.
323    pub max_tokens: usize,
324    /// Context window size in tokens.
325    pub context_window: usize,
326    /// Base URL (without trailing slash) the provider POSTs to.
327    pub base_url: String,
328    /// Whether the model supports extended thinking / reasoning.
329    pub reasoning: bool,
330    /// Adaptive-thinking models select effort rather than a token budget.
331    pub force_adaptive_thinking: bool,
332    /// Whether passing `temperature` is supported.
333    pub supports_temperature: bool,
334    /// Pricing per 1M tokens (USD).
335    pub input_cost_per_mtok: f64,
336    pub output_cost_per_mtok: f64,
337    pub cache_read_cost_per_mtok: f64,
338    pub cache_write_cost_per_mtok: f64,
339}
340
341impl Model {
342    /// Compute and attach the dollar cost for a usage record.
343    pub fn cost_for(&self, usage: &Usage) -> Cost {
344        let per = 1_000_000.0;
345        let input = usage.input as f64 / per * self.input_cost_per_mtok;
346        let output = usage.output as f64 / per * self.output_cost_per_mtok;
347        let cache_read = usage.cache_read as f64 / per * self.cache_read_cost_per_mtok;
348        let cache_write = usage.cache_write as f64 / per * self.cache_write_cost_per_mtok;
349        Cost {
350            input,
351            output,
352            cache_read,
353            cache_write,
354            total: input + output + cache_read + cache_write,
355        }
356    }
357}
358
359// ---------------------------------------------------------------------------
360// Tool schema (sent to the model)
361// ---------------------------------------------------------------------------
362
363/// The schema fragment sent to the model describing an available tool.
364#[derive(Debug, Clone, Serialize, Deserialize)]
365pub struct ToolSchema {
366    pub name: String,
367    pub description: String,
368    pub input_schema: Value,
369}