Skip to main content

armillae_core/
completion.rs

1use std::{collections::BTreeMap, fmt};
2
3use schemars::JsonSchema;
4use serde::{Deserialize, Deserializer, Serialize, Serializer, de};
5use serde_json::Value;
6
7use crate::{ContentPart, Message, TextContent, TokenUsage, ToolCall};
8
9/// A complete, single model-call request.
10#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
11pub struct CompletionRequest {
12    pub messages: Vec<Message>,
13    pub tools: Vec<crate::ToolDefinition>,
14    pub tool_choice: Option<crate::ToolChoice>,
15    pub output_format: Option<OutputFormat>,
16    pub generation: GenerationOptions,
17    pub extensions: ProviderExtensions,
18}
19
20/// A requested output representation.
21#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
22#[serde(tag = "type", rename_all = "snake_case")]
23#[non_exhaustive]
24pub enum OutputFormat {
25    Text,
26    JsonObject,
27    /// Legacy wire-format request without Bridge-side result validation.
28    /// Use `Structured` to require an explicit enforcement mode and validation.
29    JsonSchema {
30        name: String,
31        schema: Value,
32        strict: bool,
33    },
34    /// An explicit enforcement mode with final client-side validation.
35    Structured {
36        name: String,
37        schema: Value,
38        mode: StructuredOutputMode,
39    },
40}
41
42/// Where a structured response's schema is enforced during generation.
43#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
44#[serde(rename_all = "snake_case")]
45#[non_exhaustive]
46pub enum StructuredOutputMode {
47    /// The Provider must constrain generation using the supplied schema.
48    NativeStrict,
49    /// The Provider generates JSON; the Bridge validates the result locally.
50    JsonObjectValidated,
51}
52
53/// Generation controls with cross-provider meaning.
54#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
55pub struct GenerationOptions {
56    pub temperature: Option<f64>,
57    pub max_output_tokens: Option<u64>,
58    pub stop: Vec<String>,
59    pub seed: Option<u64>,
60}
61
62/// Namespaced request values understood by a specific Adapter.
63#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
64pub struct ProviderExtensions {
65    pub values: BTreeMap<String, Value>,
66}
67
68impl ProviderExtensions {
69    pub fn is_empty(&self) -> bool {
70        self.values.is_empty()
71    }
72}
73
74/// The normalized result of one model call.
75#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
76pub struct CompletionResponse {
77    pub id: Option<String>,
78    pub model: Option<String>,
79    pub content: Vec<AssistantContent>,
80    /// The Provider-reported reason, or `None` when the Provider did not report one.
81    pub finish_reason: Option<FinishReason>,
82    pub usage: Option<TokenUsage>,
83    pub provider_metadata: Value,
84}
85
86impl CompletionResponse {
87    pub fn as_assistant_message(&self) -> Message {
88        Message::assistant(
89            self.content
90                .iter()
91                .cloned()
92                .map(ContentPart::from)
93                .collect(),
94        )
95    }
96
97    pub fn tool_calls(&self) -> impl Iterator<Item = &ToolCall> {
98        self.content.iter().filter_map(|item| match item {
99            AssistantContent::ToolCall(call) => Some(call),
100            AssistantContent::Text(_) | AssistantContent::ProviderData(_) => None,
101        })
102    }
103}
104
105/// An ordered item emitted by the assistant.
106#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
107#[serde(tag = "type", rename_all = "snake_case")]
108#[non_exhaustive]
109pub enum AssistantContent {
110    Text(TextContent),
111    ToolCall(ToolCall),
112    ProviderData(ProviderData),
113}
114
115impl From<AssistantContent> for ContentPart {
116    fn from(value: AssistantContent) -> Self {
117        match value {
118            AssistantContent::Text(text) => Self::Text(text),
119            AssistantContent::ToolCall(call) => Self::ToolCall(call),
120            AssistantContent::ProviderData(data) => Self::ProviderData(data),
121        }
122    }
123}
124
125/// Why the Provider ended generation.
126#[derive(Clone, Debug, PartialEq, Eq, JsonSchema)]
127#[schemars(with = "String")]
128#[non_exhaustive]
129pub enum FinishReason {
130    Stop,
131    Length,
132    ToolCall,
133    ContentFilter,
134    Cancelled,
135    Unknown(String),
136}
137
138impl FinishReason {
139    pub fn as_str(&self) -> &str {
140        match self {
141            Self::Stop => "stop",
142            Self::Length => "length",
143            Self::ToolCall => "tool_call",
144            Self::ContentFilter => "content_filter",
145            Self::Cancelled => "cancelled",
146            Self::Unknown(value) => value,
147        }
148    }
149}
150
151impl Serialize for FinishReason {
152    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
153    where
154        S: Serializer,
155    {
156        serializer.serialize_str(self.as_str())
157    }
158}
159
160impl<'de> Deserialize<'de> for FinishReason {
161    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
162    where
163        D: Deserializer<'de>,
164    {
165        deserializer.deserialize_string(FinishReasonVisitor)
166    }
167}
168
169struct FinishReasonVisitor;
170
171impl de::Visitor<'_> for FinishReasonVisitor {
172    type Value = FinishReason;
173
174    fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
175        formatter.write_str("a finish reason string")
176    }
177
178    fn visit_string<E>(self, value: String) -> Result<Self::Value, E>
179    where
180        E: de::Error,
181    {
182        Ok(match value.as_str() {
183            "stop" => FinishReason::Stop,
184            "length" => FinishReason::Length,
185            "tool_call" => FinishReason::ToolCall,
186            "content_filter" => FinishReason::ContentFilter,
187            "cancelled" => FinishReason::Cancelled,
188            _ => FinishReason::Unknown(value),
189        })
190    }
191
192    fn visit_str<E>(self, value: &str) -> Result<Self::Value, E>
193    where
194        E: de::Error,
195    {
196        self.visit_string(value.to_owned())
197    }
198}
199
200/// Provider-specific data that has no normalized representation yet.
201#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
202pub struct ProviderData {
203    pub provider: String,
204    pub kind: String,
205    pub value: Value,
206}