ds_api/raw/mod.rs
1//! Raw API data structures
2//!
3//! This module provides the raw data structures that map directly to the DeepSeek API's JSON schema.
4//! These types are intended for users who need precise control over request and response payloads.
5//!
6//! # Module layout
7//!
8//! - [`request`]
9//! - [`response`]
10//!
11//! # Main types
12//!
13//! ## Request types
14//!
15//! - [`ChatCompletionRequest`]
16//! - [`Message`]
17//! - [`Model`]
18//! - [`Tool`]
19//! - [`ResponseFormat`]
20//! - [`Thinking`]
21//! - [`Stop`]
22//! - [`StreamOptions`]
23//!
24//! ## Response types
25//!
26//! - [`ChatCompletionResponse`]
27//! - [`ChatCompletionChunk`]
28//! - [`Choice`]
29//! - [`Usage`]
30//!
31//! # Use cases
32//!
33//! Use these raw structures when you need one of the following:
34//!
35//! 1. Full control over the API request payload (set every field explicitly).
36//! 2. Advanced features such as tool/function calls or reasoning modes.
37//! 3. Performance optimizations where avoiding builder overhead matters.
38//! 4. Integration with existing code that expects direct Serde serialization/deserialization.
39//!
40//! # Examples
41//!
42//! The following examples illustrate common usage patterns with the raw types.
43//!
44//! ```rust
45//! use ds_api::raw::{ChatCompletionRequest, Message, Model, Role};
46//! use serde_json::json;
47//!
48//! fn main() {
49//! // Example 1: Basic chat completion request
50//! let basic_request = ChatCompletionRequest {
51//! messages: vec![
52//! Message::new(Role::System, "You are a helpful assistant."),
53//! Message::new(Role::User, "What is the capital of France?"),
54//! ],
55//! model: Model::DeepseekChat,
56//! max_tokens: Some(100),
57//! temperature: Some(0.7),
58//! stream: Some(false),
59//! ..Default::default()
60//! };
61//!
62//! println!("Basic request JSON:");
63//! let json = serde_json::to_string_pretty(&basic_request).unwrap();
64//! println!("{}\n", json);
65//!
66//! // Example 2: Request with a tool/function definition
67//! use ds_api::raw::{Tool, ToolChoice, ToolChoiceType, ToolType, Function};
68//!
69//! let tool_request = ChatCompletionRequest {
70//! messages: vec![Message::new(Role::User, "What's the weather like in Tokyo?")],
71//! model: Model::DeepseekChat,
72//! max_tokens: Some(200),
73//! temperature: Some(0.8),
74//! stream: Some(false),
75//! tools: Some(vec![Tool {
76//! r#type: ToolType::Function,
77//! function: Function {
78//! name: "get_weather".to_string(),
79//! description: Some("Get the current weather for a location".to_string()),
80//! parameters: json!({
81//! "type": "object",
82//! "properties": {
83//! "location": {
84//! "type": "string",
85//! "description": "The city and country, e.g. Tokyo, Japan"
86//! }
87//! },
88//! "required": ["location"]
89//! }),
90//! strict: Some(true),
91//! },
92//! }]),
93//! tool_choice: Some(ToolChoice::String(ToolChoiceType::Auto)),
94//! ..Default::default()
95//! };
96//!
97//! println!("Tool request JSON:");
98//! let json = serde_json::to_string_pretty(&tool_request).unwrap();
99//! println!("{}\n", json);
100//!
101//! // Example 3: Using the Deepseek Reasoner model
102//! use ds_api::raw::{Thinking, ThinkingType};
103//!
104//! let reasoner_request = ChatCompletionRequest {
105//! messages: vec![
106//! Message::new(Role::System, "You are a helpful assistant that explains your reasoning."),
107//! Message::new(Role::User, "Solve this math problem: What is 15% of 200?"),
108//! ],
109//! model: Model::DeepseekReasoner,
110//! thinking: Some(Thinking {
111//! r#type: ThinkingType::Enabled,
112//! }),
113//! max_tokens: Some(150),
114//! temperature: Some(0.3),
115//! stream: Some(false),
116//! ..Default::default()
117//! };
118//!
119//! println!("Reasoner request JSON:");
120//! let json = serde_json::to_string_pretty(&reasoner_request).unwrap();
121//! println!("{}\n", json);
122//!
123//! // Example 4: JSON response format
124//! use ds_api::raw::{ResponseFormat, ResponseFormatType};
125//!
126//! let json_request = ChatCompletionRequest {
127//! messages: vec![
128//! Message::new(Role::System, "You are a helpful assistant that always responds in valid JSON format."),
129//! Message::new(Role::User, "Give me information about Paris in JSON format with fields: name, country, population, and landmarks."),
130//! ],
131//! model: Model::DeepseekChat,
132//! max_tokens: Some(200),
133//! temperature: Some(0.5),
134//! stream: Some(false),
135//! response_format: Some(ResponseFormat {
136//! r#type: ResponseFormatType::JsonObject,
137//! }),
138//! ..Default::default()
139//! };
140//!
141//! println!("JSON mode request:");
142//! let json = serde_json::to_string_pretty(&json_request).unwrap();
143//! println!("{}\n", json);
144//! }
145//! ```
146//!
147//! # Serialization / Deserialization
148//!
149//! All structs implement `Serialize` and `Deserialize` and can be used with `serde_json` directly:
150//!
151//! ```rust
152//! use ds_api::raw::{ChatCompletionRequest, Message, Model, Role};
153//!
154//! let request = ChatCompletionRequest {
155//! messages: vec![Message::new(Role::User, "Hello")],
156//! model: Model::DeepseekChat,
157//! ..Default::default()
158//! };
159//! let json_string = serde_json::to_string(&request).unwrap();
160//! let parsed_request: ChatCompletionRequest = serde_json::from_str(&json_string).unwrap();
161//! ```
162//!
163//! # Relationship to higher-level APIs
164//!
165//! The higher-level APIs (for example, the builder-style `Request` types) are implemented on top
166//! of these raw structures and provide ergonomic builders and validation. If you prefer an easier
167//! or more opinionated interface, consider using the higher-level APIs instead.
168pub mod request;
169pub mod response;
170
171pub use request::*;
172pub use response::*;