Skip to main content

hyprstream_core/api/
openai_compat.rs

1//! OpenAI API compatibility layer
2
3use hyprstream_rpc_std::inference_client::ToolCall;
4use serde::{Deserialize, Serialize};
5
6// Type aliases for API compatibility
7pub use ChatCompletionRequest as OpenAIRequest;
8pub use ChatCompletionResponse as OpenAIResponse;
9
10/// Chat completion streaming response
11pub type ChatCompletionStreamResponse = OpenAIStreamResponse;
12
13/// OpenAI Chat Completion Request
14#[derive(Debug, Clone, Serialize, Deserialize)]
15pub struct ChatCompletionRequest {
16    pub model: String,
17    pub messages: Vec<ChatMessage>,
18    pub temperature: Option<f32>,
19    pub top_p: Option<f32>,
20    pub n: Option<i32>,
21    pub stream: Option<bool>,
22    pub stop: Option<Vec<String>>,
23    pub max_tokens: Option<usize>,
24    pub presence_penalty: Option<f32>,
25    pub frequency_penalty: Option<f32>,
26    pub repeat_penalty: Option<f32>,
27    pub repeat_last_n: Option<usize>,
28    pub top_k: Option<usize>,
29    pub logit_bias: Option<std::collections::HashMap<String, f32>>,
30    pub user: Option<String>,
31    pub tools: Option<Vec<Tool>>,
32    pub tool_choice: Option<ToolChoice>,
33}
34
35/// Chat message
36#[derive(Debug, Clone, Serialize, Deserialize)]
37pub struct ChatMessage {
38    pub role: String,
39    pub content: Option<String>,
40    pub tool_calls: Option<Vec<ToolCall>>,
41    pub tool_call_id: Option<String>,
42}
43
44impl From<&ChatCompletionRequest> for crate::config::SamplingParams {
45    fn from(req: &ChatCompletionRequest) -> Self {
46        Self {
47            temperature: req.temperature,
48            top_p: req.top_p,
49            top_k: req.top_k,
50            max_tokens: req.max_tokens,
51            repeat_penalty: req.repeat_penalty,
52            repeat_last_n: req.repeat_last_n,
53            stop_tokens: req.stop.clone(),
54            seed: None,
55            length_penalty: None,
56            typical_p: None,
57            epsilon_cutoff: None,
58            eta_cutoff: None,
59            do_sample: None,
60            timeout_ms: None,
61        }
62    }
63}
64
65/// Tool definition (OpenAI format)
66#[derive(Debug, Clone, Serialize, Deserialize)]
67pub struct Tool {
68    #[serde(rename = "type")]
69    pub tool_type: String, // "function"
70    pub function: ToolFunction,
71}
72
73/// Tool function definition
74#[derive(Debug, Clone, Serialize, Deserialize)]
75pub struct ToolFunction {
76    pub name: String,
77    pub description: Option<String>,
78    pub parameters: serde_json::Value, // JSON Schema
79}
80
81/// Tool choice parameter
82#[derive(Debug, Clone, Serialize, Deserialize)]
83#[serde(untagged)]
84pub enum ToolChoice {
85    String(String), // "none", "auto", "required"
86    Specific {
87        #[serde(rename = "type")]
88        tool_type: String, // "function"
89        function: ToolChoiceFunction,
90    },
91}
92
93/// Specific tool choice
94#[derive(Debug, Clone, Serialize, Deserialize)]
95pub struct ToolChoiceFunction {
96    pub name: String,
97}
98
99/// Chat Completion Response
100#[derive(Debug, Clone, Serialize, Deserialize)]
101pub struct ChatCompletionResponse {
102    pub id: String,
103    pub object: String,
104    pub created: i64,
105    pub model: String,
106    pub choices: Vec<ChatChoice>,
107    pub usage: Option<Usage>,
108}
109
110/// Chat choice
111#[derive(Debug, Clone, Serialize, Deserialize)]
112pub struct ChatChoice {
113    pub index: i32,
114    pub message: ChatMessage,
115    pub finish_reason: Option<String>,
116}
117
118impl ChatChoice {
119    /// Check if this choice contains tool calls
120    pub fn has_tool_calls(&self) -> bool {
121        self.message
122            .tool_calls
123            .as_ref()
124            .is_some_and(|tc| !tc.is_empty())
125    }
126}
127
128/// Text Completion Request
129#[derive(Debug, Clone, Serialize, Deserialize)]
130pub struct CompletionRequest {
131    pub model: String,
132    pub prompt: String,
133    pub suffix: Option<String>,
134    pub max_tokens: Option<usize>,
135    pub temperature: Option<f32>,
136    pub top_p: Option<f32>,
137    pub n: Option<i32>,
138    pub stream: Option<bool>,
139    pub logprobs: Option<i32>,
140    pub echo: Option<bool>,
141    pub stop: Option<Vec<String>>,
142    pub presence_penalty: Option<f32>,
143    pub frequency_penalty: Option<f32>,
144    pub repeat_penalty: Option<f32>,
145    pub repeat_last_n: Option<usize>,
146    pub top_k: Option<usize>,
147    pub best_of: Option<i32>,
148    pub logit_bias: Option<std::collections::HashMap<String, f32>>,
149    pub user: Option<String>,
150}
151
152impl From<&CompletionRequest> for crate::config::SamplingParams {
153    fn from(req: &CompletionRequest) -> Self {
154        Self {
155            temperature: req.temperature,
156            top_p: req.top_p,
157            top_k: req.top_k,
158            max_tokens: req.max_tokens,
159            repeat_penalty: req.repeat_penalty,
160            repeat_last_n: req.repeat_last_n,
161            stop_tokens: req.stop.clone(),
162            seed: None,
163            length_penalty: None,
164            typical_p: None,
165            epsilon_cutoff: None,
166            eta_cutoff: None,
167            do_sample: None,
168            timeout_ms: None,
169        }
170    }
171}
172
173/// Completion Response
174#[derive(Debug, Clone, Serialize, Deserialize)]
175pub struct CompletionResponse {
176    pub id: String,
177    pub object: String,
178    pub created: i64,
179    pub model: String,
180    pub choices: Vec<CompletionChoice>,
181    pub usage: Option<Usage>,
182}
183
184/// Completion choice
185#[derive(Debug, Clone, Serialize, Deserialize)]
186pub struct CompletionChoice {
187    pub text: String,
188    pub index: i32,
189    pub logprobs: Option<LogProbs>,
190    pub finish_reason: Option<String>,
191}
192
193/// Log probabilities
194#[derive(Debug, Clone, Serialize, Deserialize)]
195pub struct LogProbs {
196    pub tokens: Vec<String>,
197    pub token_logprobs: Vec<f32>,
198    pub top_logprobs: Vec<std::collections::HashMap<String, f32>>,
199    pub text_offset: Vec<i32>,
200}
201
202/// Embedding Request
203#[derive(Debug, Clone, Serialize, Deserialize)]
204pub struct EmbeddingRequest {
205    pub model: String,
206    pub input: Vec<String>,
207    pub user: Option<String>,
208}
209
210/// Embedding Response
211#[derive(Debug, Clone, Serialize, Deserialize)]
212pub struct EmbeddingResponse {
213    pub object: String,
214    pub data: Vec<EmbeddingData>,
215    pub model: String,
216    pub usage: Usage,
217}
218
219/// Embedding data
220#[derive(Debug, Clone, Serialize, Deserialize)]
221pub struct EmbeddingData {
222    pub object: String,
223    pub embedding: Vec<f32>,
224    pub index: usize,
225}
226
227/// Usage statistics
228#[derive(Debug, Clone, Serialize, Deserialize)]
229pub struct Usage {
230    pub prompt_tokens: usize,
231    pub completion_tokens: usize,
232    pub total_tokens: usize,
233    /// Online training details (hyprstream extension, follows OpenAI's *_details pattern)
234    #[serde(skip_serializing_if = "Option::is_none")]
235    pub online_training_details: Option<OnlineTrainingDetails>,
236}
237
238/// Online training (TTT) adaptation summary for usage reporting.
239///
240/// Nested inside `usage` following OpenAI's `completion_tokens_details` pattern.
241/// Contains the essential metrics identified by TTT literature:
242/// - Loss trajectory (avg_loss, loss_improvement) -- convergence signal
243/// - Perplexity change (initial/final) -- primary quality metric
244/// - Compute budget (steps, time) -- overhead transparency
245/// - Action signal (pending, recommendation) -- commit/rollback decision
246#[derive(Debug, Clone, Serialize, Deserialize)]
247pub struct OnlineTrainingDetails {
248    pub avg_loss: f32,
249    pub loss_improvement: f32,
250    pub initial_perplexity: f32,
251    pub final_perplexity: f32,
252    pub steps_performed: usize,
253    pub adaptation_time_ms: u64,
254    pub pending: bool,
255    pub recommendation: bool,
256    pub skipped: bool,
257    #[serde(skip_serializing_if = "Option::is_none")]
258    pub skip_reason: Option<String>,
259}
260
261impl From<&crate::config::TTTMetrics> for OnlineTrainingDetails {
262    fn from(m: &crate::config::TTTMetrics) -> Self {
263        Self {
264            avg_loss: m.avg_loss,
265            loss_improvement: m.loss_improvement,
266            initial_perplexity: m.initial_perplexity,
267            final_perplexity: m.final_perplexity,
268            steps_performed: m.steps_performed,
269            adaptation_time_ms: m.adaptation_time_ms,
270            pending: m.pending,
271            recommendation: m.recommendation,
272            skipped: m.skipped,
273            skip_reason: m.skip_reason.clone(),
274        }
275    }
276}
277
278/// List Models Response
279#[derive(Debug, Clone, Serialize, Deserialize)]
280pub struct ListModelsResponse {
281    pub object: String,
282    pub data: Vec<Model>,
283}
284
285/// Model information
286#[derive(Debug, Clone, Serialize, Deserialize)]
287pub struct Model {
288    pub id: String,
289    pub object: String,
290    pub created: i64,
291    pub owned_by: String,
292}
293
294/// Streaming response for SSE
295#[derive(Debug, Clone, Serialize, Deserialize)]
296pub struct OpenAIStreamResponse {
297    pub id: String,
298    pub object: String,
299    pub created: i64,
300    pub model: String,
301    pub choices: Vec<StreamChoice>,
302}
303
304/// Streaming choice
305#[derive(Debug, Clone, Serialize, Deserialize)]
306pub struct StreamChoice {
307    pub index: i32,
308    pub delta: Delta,
309    pub finish_reason: Option<String>,
310}
311
312/// Delta content for streaming
313#[derive(Debug, Clone, Serialize, Deserialize)]
314pub struct Delta {
315    pub role: Option<String>,
316    pub content: Option<String>,
317}
318
319/// Error response
320#[derive(Debug, Clone, Serialize, Deserialize)]
321pub struct ErrorResponse {
322    pub error: ErrorDetail,
323}
324
325/// Error detail
326#[derive(Debug, Clone, Serialize, Deserialize)]
327pub struct ErrorDetail {
328    pub message: String,
329    pub r#type: String,
330    pub param: Option<String>,
331    pub code: Option<String>,
332}
333
334#[cfg(test)]
335#[allow(clippy::unwrap_used, clippy::expect_used)]
336mod tests {
337    use super::*;
338
339    #[test]
340    fn test_multi_turn_message_serialization() {
341        // Build a 3-turn conversation and verify JSON round-trip
342        let messages = vec![
343            ChatMessage {
344                role: "user".into(),
345                content: Some("Hello".into()),
346                tool_calls: None,
347                tool_call_id: None,
348            },
349            ChatMessage {
350                role: "assistant".into(),
351                content: Some("Hi! How can I help?".into()),
352                tool_calls: None,
353                tool_call_id: None,
354            },
355            ChatMessage {
356                role: "user".into(),
357                content: Some("Tell me about Rust.".into()),
358                tool_calls: None,
359                tool_call_id: None,
360            },
361        ];
362
363        // Serialize to JSON
364        let json = serde_json::to_string(&messages).unwrap();
365
366        // Deserialize back
367        let parsed: Vec<ChatMessage> = serde_json::from_str(&json).unwrap();
368        assert_eq!(parsed.len(), 3);
369        assert_eq!(parsed[0].role, "user");
370        assert_eq!(parsed[0].content.as_deref(), Some("Hello"));
371        assert_eq!(parsed[1].role, "assistant");
372        assert_eq!(parsed[2].content.as_deref(), Some("Tell me about Rust."));
373    }
374
375    #[test]
376    fn test_tool_use_conversation_flow_serialization() {
377        // Full tool use conversation matching OpenAI API format
378        let request_json = r#"{
379            "model": "qwen3:main",
380            "messages": [
381                {"role": "user", "content": "What's the weather in NYC?"},
382                {"role": "assistant", "content": null, "tool_calls": [
383                    {"id": "call_123", "type": "function", "function": {"name": "get_weather", "arguments": "{\"location\":\"NYC\"}"}}
384                ]},
385                {"role": "tool", "content": "{\"temperature\": 72}", "tool_call_id": "call_123"},
386                {"role": "user", "content": "And in LA?"}
387            ],
388            "tools": [
389                {"type": "function", "function": {"name": "get_weather", "description": "Get weather", "parameters": {"type": "object"}}}
390            ]
391        }"#;
392
393        // Deserialize the full request
394        let request: ChatCompletionRequest = serde_json::from_str(request_json).unwrap();
395
396        assert_eq!(request.messages.len(), 4);
397        assert_eq!(request.model, "qwen3:main");
398
399        // Verify user message
400        assert_eq!(request.messages[0].role, "user");
401        assert_eq!(
402            request.messages[0].content.as_deref(),
403            Some("What's the weather in NYC?")
404        );
405
406        // Verify assistant message with tool calls
407        assert_eq!(request.messages[1].role, "assistant");
408        assert!(
409            request.messages[1].content.is_none(),
410            "assistant content should be null for tool-call-only"
411        );
412        let tool_calls = request.messages[1].tool_calls.as_ref().unwrap();
413        assert_eq!(tool_calls.len(), 1);
414        assert_eq!(tool_calls[0].id, "call_123");
415        assert_eq!(tool_calls[0].function.name, "get_weather");
416
417        // Verify tool response
418        assert_eq!(request.messages[2].role, "tool");
419        assert_eq!(
420            request.messages[2].tool_call_id.as_deref(),
421            Some("call_123")
422        );
423        assert!(request.messages[2].content.as_ref().unwrap().contains("72"));
424
425        // Verify follow-up
426        assert_eq!(request.messages[3].role, "user");
427        assert_eq!(request.messages[3].content.as_deref(), Some("And in LA?"));
428
429        // Verify tools
430        let tools = request.tools.as_ref().unwrap();
431        assert_eq!(tools.len(), 1);
432        assert_eq!(tools[0].function.name, "get_weather");
433    }
434}