openrouter_rs/types/
mod.rs

1//! # Core Types and Data Structures
2//!
3//! This module contains all the core types, enums, and data structures used
4//! throughout the OpenRouter SDK. These types provide type-safe representations
5//! of API requests, responses, and configuration options.
6//!
7//! ## 📋 Type Categories
8//!
9//! ### Request/Response Types ([`completion`])
10//! - **Chat Completions**: Modern conversational AI request/response structures
11//! - **Text Completions**: Legacy prompt-based completion types
12//! - **Streaming**: Types for handling real-time response streams
13//! - **Reasoning**: Advanced reasoning and chain-of-thought structures
14//!
15//! ### Provider Information ([`provider`])
16//! - **Model Metadata**: Provider-specific model information
17//! - **Capabilities**: Model feature and parameter support
18//! - **Pricing**: Cost information and token usage
19//!
20//! ### Response Formatting ([`response_format`])
21//! - **JSON Schema**: Structured output formatting
22//! - **Content Types**: Different response content formats
23//! - **Validation**: Response format validation rules
24//!
25//! ## 🎯 Core Enums
26//!
27//! ### Role
28//! Defines the role of a message in a conversation:
29//!
30//! ```rust
31//! use openrouter_rs::types::Role;
32//!
33//! let system_role = Role::System;    // System instructions
34//! let user_role = Role::User;        // User input
35//! let assistant_role = Role::Assistant; // AI response
36//! let tool_role = Role::Tool;        // Tool/function results
37//! let developer_role = Role::Developer; // Developer context
38//! ```
39//!
40//! ### Effort
41//! Specifies reasoning effort levels for chain-of-thought models:
42//!
43//! ```rust
44//! use openrouter_rs::types::Effort;
45//!
46//! let high_effort = Effort::High;    // Maximum reasoning depth
47//! let medium_effort = Effort::Medium; // Balanced reasoning
48//! let low_effort = Effort::Low;      // Quick reasoning
49//! ```
50//!
51//! ## 🔧 Configuration Types
52//!
53//! ### ReasoningConfig
54//! Configuration for advanced reasoning capabilities:
55//!
56//! ```rust
57//! use openrouter_rs::types::{ReasoningConfig, Effort};
58//!
59//! let reasoning = ReasoningConfig::builder()
60//!     .enabled(true)
61//!     .effort(Effort::High)
62//!     .max_tokens(1000)
63//!     .build()?;
64//! # Ok::<(), Box<dyn std::error::Error>>(())
65//! ```
66//!
67//! ### ProviderPreferences
68//! Specify preferences for model provider selection:
69//!
70//! ```rust
71//! use openrouter_rs::types::ProviderPreferences;
72//!
73//! let prefs = ProviderPreferences {
74//!     allow_fallbacks: true,
75//!     require_parameters: Some(vec!["tools".to_string()]),
76//!     data_collection: Some("deny".to_string()),
77//! };
78//! ```
79//!
80//! ## 📊 Model Categories
81//!
82//! Categories for filtering and organizing models:
83//!
84//! ```rust
85//! use openrouter_rs::types::ModelCategory;
86//!
87//! // Filter models by use case
88//! let programming_models = ModelCategory::Programming;
89//! let reasoning_models = ModelCategory::Reasoning;
90//! let image_models = ModelCategory::Image;
91//! ```
92//!
93//! ## 🏗️ Builder Patterns
94//!
95//! Most complex types support the builder pattern for ergonomic construction:
96//!
97//! ```rust
98//! use openrouter_rs::types::{ReasoningConfig, Effort};
99//!
100//! let config = ReasoningConfig::builder()
101//!     .enabled(true)
102//!     .effort(Effort::High)
103//!     .max_tokens(2000)
104//!     .exclude(false)
105//!     .build()?;
106//! # Ok::<(), Box<dyn std::error::Error>>(())
107//! ```
108//!
109//! ## 🔄 Serialization Support
110//!
111//! All types implement `Serialize` and `Deserialize` for JSON compatibility:
112//!
113//! ```rust
114//! use openrouter_rs::types::Role;
115//! use serde_json;
116//!
117//! let role = Role::Assistant;
118//! let json = serde_json::to_string(&role)?;
119//! let parsed: Role = serde_json::from_str(&json)?;
120//! # Ok::<(), Box<dyn std::error::Error>>(())
121//! ```
122//!
123//! ## 🎨 Display Formatting
124//!
125//! Common enums implement `Display` for human-readable output:
126//!
127//! ```rust
128//! use openrouter_rs::types::{Role, Effort};
129//!
130//! println!("Role: {}", Role::User);        // "user"
131//! println!("Effort: {}", Effort::High);    // "high"
132//! ```
133
134pub mod completion;
135pub mod provider;
136pub mod response_format;
137
138use std::fmt::Display;
139
140use serde::{Deserialize, Serialize};
141
142pub use {completion::*, provider::*, response_format::*};
143
144#[derive(Serialize, Deserialize, Debug)]
145pub struct ApiResponse<T> {
146    pub data: T,
147}
148
149/// Message role in a conversation
150///
151/// Specifies who or what is sending a message in a chat completion.
152/// Different roles have different behaviors and restrictions.
153///
154/// # Examples
155///
156/// ```rust
157/// use openrouter_rs::types::Role;
158/// use openrouter_rs::api::chat::Message;
159///
160/// let system_msg = Message::new(Role::System, "You are a helpful assistant");
161/// let user_msg = Message::new(Role::User, "Hello, world!");
162/// let assistant_msg = Message::new(Role::Assistant, "Hello! How can I help?");
163/// ```
164#[derive(Serialize, Deserialize, Debug, Clone)]
165#[serde(rename_all = "lowercase")]
166pub enum Role {
167    /// System instructions that guide the AI's behavior
168    System,
169    /// Developer/admin context (provider-specific)
170    Developer,
171    /// User input or questions
172    User,
173    /// AI assistant responses
174    Assistant,
175    /// Results from tool/function calls
176    Tool,
177}
178
179impl Display for Role {
180    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
181        match self {
182            Role::System => write!(f, "system"),
183            Role::Developer => write!(f, "developer"),
184            Role::User => write!(f, "user"),
185            Role::Assistant => write!(f, "assistant"),
186            Role::Tool => write!(f, "tool"),
187        }
188    }
189}
190
191/// Reasoning effort level for chain-of-thought models
192///
193/// Controls how much computational effort the model should put into
194/// reasoning through problems. Higher effort levels typically produce
195/// more detailed reasoning but take longer and cost more.
196///
197/// # Examples
198///
199/// ```rust
200/// use openrouter_rs::types::Effort;
201/// use openrouter_rs::api::chat::ChatCompletionRequest;
202///
203/// let request = ChatCompletionRequest::builder()
204///     .model("deepseek/deepseek-r1")
205///     .reasoning_effort(Effort::High)  // Maximum reasoning depth
206///     // ... other fields
207///     .build()?;
208/// # Ok::<(), Box<dyn std::error::Error>>(())
209/// ```
210#[derive(Serialize, Deserialize, Debug, Clone)]
211#[serde(rename_all = "lowercase")]
212pub enum Effort {
213    /// Maximum reasoning depth and thoroughness
214    High,
215    /// Balanced reasoning effort
216    Medium,
217    /// Quick, lightweight reasoning
218    Low,
219}
220
221impl Display for Effort {
222    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
223        match self {
224            Effort::High => write!(f, "high"),
225            Effort::Medium => write!(f, "medium"),
226            Effort::Low => write!(f, "low"),
227        }
228    }
229}
230
231#[derive(Serialize, Deserialize, Debug, Clone)]
232pub struct ReasoningConfig {
233    #[serde(skip_serializing_if = "Option::is_none")]
234    pub effort: Option<Effort>,
235    #[serde(skip_serializing_if = "Option::is_none")]
236    pub max_tokens: Option<u32>,
237    #[serde(skip_serializing_if = "Option::is_none")]
238    pub exclude: Option<bool>,
239    #[serde(skip_serializing_if = "Option::is_none")]
240    pub enabled: Option<bool>,
241}
242
243impl ReasoningConfig {
244    /// Create a new ReasoningConfig with default enabled settings (medium effort)
245    pub fn enabled() -> Self {
246        Self {
247            effort: None,
248            max_tokens: None,
249            exclude: None,
250            enabled: Some(true),
251        }
252    }
253
254    /// Create a ReasoningConfig with specific effort level
255    pub fn with_effort(effort: Effort) -> Self {
256        Self {
257            effort: Some(effort),
258            max_tokens: None,
259            exclude: None,
260            enabled: None,
261        }
262    }
263
264    /// Create a ReasoningConfig with max tokens limit
265    pub fn with_max_tokens(max_tokens: u32) -> Self {
266        Self {
267            effort: None,
268            max_tokens: Some(max_tokens),
269            exclude: None,
270            enabled: None,
271        }
272    }
273
274    /// Create a ReasoningConfig that excludes reasoning from response
275    pub fn excluded() -> Self {
276        Self {
277            effort: None,
278            max_tokens: None,
279            exclude: Some(true),
280            enabled: None,
281        }
282    }
283
284    /// Set effort level
285    pub fn effort(mut self, effort: Effort) -> Self {
286        self.effort = Some(effort);
287        self
288    }
289
290    /// Set max tokens
291    pub fn max_tokens(mut self, max_tokens: u32) -> Self {
292        self.max_tokens = Some(max_tokens);
293        self
294    }
295
296    /// Set exclude flag
297    pub fn exclude(mut self, exclude: bool) -> Self {
298        self.exclude = Some(exclude);
299        self
300    }
301}
302
303#[derive(Serialize, Deserialize, Debug, Clone)]
304#[serde(rename_all = "lowercase")]
305pub enum ModelCategory {
306    Roleplay,
307    Programming,
308    Marketing,
309    #[serde(rename = "marketing/seo")]
310    MarketingSeo,
311    Technology,
312    Science,
313    Translation,
314    Legal,
315    Finance,
316    Health,
317    Trivia,
318    Academia,
319}
320
321impl Display for ModelCategory {
322    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
323        match self {
324            ModelCategory::Roleplay => write!(f, "roleplay"),
325            ModelCategory::Programming => write!(f, "programming"),
326            ModelCategory::Marketing => write!(f, "marketing"),
327            ModelCategory::MarketingSeo => write!(f, "marketing/seo"),
328            ModelCategory::Technology => write!(f, "technology"),
329            ModelCategory::Science => write!(f, "science"),
330            ModelCategory::Translation => write!(f, "translation"),
331            ModelCategory::Legal => write!(f, "legal"),
332            ModelCategory::Finance => write!(f, "finance"),
333            ModelCategory::Health => write!(f, "health"),
334            ModelCategory::Trivia => write!(f, "trivia"),
335            ModelCategory::Academia => write!(f, "academia"),
336        }
337    }
338}
339
340impl ModelCategory {
341    pub fn all() -> Vec<ModelCategory> {
342        vec![
343            ModelCategory::Roleplay,
344            ModelCategory::Programming,
345            ModelCategory::Marketing,
346            ModelCategory::MarketingSeo,
347            ModelCategory::Technology,
348            ModelCategory::Science,
349            ModelCategory::Translation,
350            ModelCategory::Legal,
351            ModelCategory::Finance,
352            ModelCategory::Health,
353            ModelCategory::Trivia,
354            ModelCategory::Academia,
355        ]
356    }
357}
358
359#[derive(Serialize, Deserialize, Debug, Clone)]
360#[serde(rename_all = "snake_case")]
361pub enum SupportedParameters {
362    Tools,
363    Temperature,
364    TopP,
365    TopK,
366    MinP,
367    TopA,
368    FrequencyPenalty,
369    PresencePenalty,
370    RepetitionPenalty,
371    MaxTokens,
372    LogitBias,
373    Logprobs,
374    TopLogprobs,
375    Seed,
376    ResponseFormat,
377    StructuredOutputs,
378    Stop,
379    IncludeReasoning,
380    Reasoning,
381    WebSearchOptions,
382}
383
384impl Display for SupportedParameters {
385    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
386        match self {
387            SupportedParameters::Tools => write!(f, "tools"),
388            SupportedParameters::Temperature => write!(f, "temperature"),
389            SupportedParameters::TopP => write!(f, "top_p"),
390            SupportedParameters::TopK => write!(f, "top_k"),
391            SupportedParameters::MinP => write!(f, "min_p"),
392            SupportedParameters::TopA => write!(f, "top_a"),
393            SupportedParameters::FrequencyPenalty => write!(f, "frequency_penalty"),
394            SupportedParameters::PresencePenalty => write!(f, "presence_penalty"),
395            SupportedParameters::RepetitionPenalty => write!(f, "repetition_penalty"),
396            SupportedParameters::MaxTokens => write!(f, "max_tokens"),
397            SupportedParameters::LogitBias => write!(f, "logit_bias"),
398            SupportedParameters::Logprobs => write!(f, "logprobs"),
399            SupportedParameters::TopLogprobs => write!(f, "top_logprobs"),
400            SupportedParameters::Seed => write!(f, "seed"),
401            SupportedParameters::ResponseFormat => write!(f, "response_format"),
402            SupportedParameters::StructuredOutputs => write!(f, "structured_outputs"),
403            SupportedParameters::Stop => write!(f, "stop"),
404            SupportedParameters::IncludeReasoning => write!(f, "include_reasoning"),
405            SupportedParameters::Reasoning => write!(f, "reasoning"),
406            SupportedParameters::WebSearchOptions => write!(f, "web_search_options"),
407        }
408    }
409}
410
411impl SupportedParameters {
412    pub fn all() -> Vec<SupportedParameters> {
413        vec![
414            SupportedParameters::Tools,
415            SupportedParameters::Temperature,
416            SupportedParameters::TopP,
417            SupportedParameters::TopK,
418            SupportedParameters::MinP,
419            SupportedParameters::TopA,
420            SupportedParameters::FrequencyPenalty,
421            SupportedParameters::PresencePenalty,
422            SupportedParameters::RepetitionPenalty,
423            SupportedParameters::MaxTokens,
424            SupportedParameters::LogitBias,
425            SupportedParameters::Logprobs,
426            SupportedParameters::TopLogprobs,
427            SupportedParameters::Seed,
428            SupportedParameters::ResponseFormat,
429            SupportedParameters::StructuredOutputs,
430            SupportedParameters::Stop,
431            SupportedParameters::IncludeReasoning,
432            SupportedParameters::Reasoning,
433            SupportedParameters::WebSearchOptions,
434        ]
435    }
436}
openrouter_rs/types/mod.rs

openrouter_rs/types/
mod.rs
