diff --git a/crates/hermesllm/src/apis/anthropic.rs b/crates/hermesllm/src/apis/anthropic.rs
new file mode 100644
index 00000000..7ae085d5
--- /dev/null
+++ b/crates/hermesllm/src/apis/anthropic.rs
@@ -0,0 +1,568 @@
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use serde_with::skip_serializing_none;
+use std::collections::HashMap;
+
+use super::ApiDefinition;
+
+// Enum for all supported Anthropic APIs
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum AnthropicApi {
+    Messages,
+    // Future APIs can be added here:
+    // Embeddings,
+    // etc.
+}
+
+impl ApiDefinition for AnthropicApi {
+    fn endpoint(&self) -> &'static str {
+        match self {
+            AnthropicApi::Messages => "/v1/messages",
+        }
+    }
+
+    fn from_endpoint(endpoint: &str) -> Option<Self> {
+        match endpoint {
+            "/v1/messages" => Some(AnthropicApi::Messages),
+            _ => None,
+        }
+    }
+
+    fn supports_streaming(&self) -> bool {
+        match self {
+            AnthropicApi::Messages => true,
+        }
+    }
+
+    fn supports_tools(&self) -> bool {
+        match self {
+            AnthropicApi::Messages => true,
+        }
+    }
+
+    fn supports_vision(&self) -> bool {
+        match self {
+            AnthropicApi::Messages => true,
+        }
+    }
+
+    fn all_variants() -> Vec<Self> {
+        vec![
+            AnthropicApi::Messages,
+        ]
+    }
+}
+
+// Service tier enum for request priority
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum ServiceTier {
+    Auto,
+    StandardOnly,
+}
+
+// Thinking configuration
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct ThinkingConfig {
+    pub enabled: bool,
+}
+
+// MCP Server types
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
+#[serde(rename_all = "lowercase")]
+pub enum McpServerType {
+    Url,
+}
+
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct McpToolConfiguration {
+    pub allowed_tools: Option<Vec<String>>,
+    pub enabled: Option<bool>,
+}
+
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct McpServer {
+    pub name: String,
+    #[serde(rename = "type")]
+    pub server_type: McpServerType,
+    pub url: String,
+    pub authorization_token: Option<String>,
+    pub tool_configuration: Option<McpToolConfiguration>,
+}
+
+
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct MessagesRequest {
+    pub model: String,
+    pub messages: Vec<MessagesMessage>,
+    pub max_tokens: u32,
+    pub container: Option<String>,
+    pub mcp_servers: Option<Vec<McpServer>>,
+    pub system: Option<MessagesSystemPrompt>,
+    pub metadata: Option<HashMap<String, Value>>,
+    pub service_tier: Option<ServiceTier>,
+    pub thinking: Option<ThinkingConfig>,
+
+    pub temperature: Option<f32>,
+    pub top_p: Option<f32>,
+    pub top_k: Option<u32>,
+    pub stream: Option<bool>,
+    pub stop_sequences: Option<Vec<String>>,
+    pub tools: Option<Vec<MessagesTool>>,
+    pub tool_choice: Option<MessagesToolChoice>,
+
+}
+
+
+// Messages API specific types
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
+#[serde(rename_all = "lowercase")]
+pub enum MessagesRole {
+    User,
+    Assistant,
+}
+
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+#[serde(rename_all = "snake_case")]
+#[serde(tag = "type")]
+pub enum MessagesContentBlock {
+    Text {
+        text: String,
+    },
+    Thinking {
+        text: String,
+    },
+    Image {
+        source: MessagesImageSource,
+    },
+    Document {
+        source: MessagesDocumentSource,
+    },
+    ToolUse {
+        id: String,
+        name: String,
+        input: Value,
+    },
+    ToolResult {
+        tool_use_id: String,
+        is_error: Option<bool>,
+        content: Vec<MessagesContentBlock>,
+    },
+    ServerToolUse {
+        id: String,
+        name: String,
+        input: Value,
+    },
+    WebSearchToolResult {
+        tool_use_id: String,
+        is_error: Option<bool>,
+        content: Vec<MessagesContentBlock>,
+    },
+    CodeExecutionToolResult {
+        tool_use_id: String,
+        is_error: Option<bool>,
+        content: Vec<MessagesContentBlock>,
+    },
+    McpToolUse {
+        id: String,
+        name: String,
+        input: Value,
+    },
+    McpToolResult {
+        tool_use_id: String,
+        is_error: Option<bool>,
+        content: Vec<MessagesContentBlock>,
+    },
+    ContainerUpload {
+        id: String,
+        name: String,
+        media_type: String,
+        data: String,
+    },
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+#[serde(rename_all = "snake_case")]
+pub enum MessagesImageSource {
+    Base64 {
+        media_type: String,
+        data: String,
+    },
+    Url {
+        url: String,
+    },
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+#[serde(rename_all = "snake_case")]
+pub enum MessagesDocumentSource {
+    Base64 {
+        media_type: String,
+        data: String,
+    },
+    Url {
+        url: String,
+    },
+    File {
+        file_id: String,
+    },
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+#[serde(untagged)]
+pub enum MessagesMessageContent {
+    Single(String),
+    Blocks(Vec<MessagesContentBlock>),
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+#[serde(untagged)]
+pub enum MessagesSystemPrompt {
+    Single(String),
+    Blocks(Vec<MessagesContentBlock>),
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct MessagesMessage {
+    pub role: MessagesRole,
+    pub content: MessagesMessageContent,
+}
+
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct MessagesTool {
+    pub name: String,
+    pub description: Option<String>,
+    pub input_schema: Value,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+#[serde(rename_all = "snake_case")]
+pub enum MessagesToolChoiceType {
+    Auto,
+    Any,
+    Tool,
+    None,
+}
+
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct MessagesToolChoice {
+    #[serde(rename = "type")]
+    pub kind: MessagesToolChoiceType,
+    pub name: Option<String>,
+    pub disable_parallel_tool_use: Option<bool>,
+}
+
+
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum MessagesStopReason {
+    EndTurn,
+    MaxTokens,
+    StopSequence,
+    ToolUse,
+    PauseTurn,
+    Refusal,
+}
+
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct MessagesUsage {
+    pub input_tokens: u32,
+    pub output_tokens: u32,
+    pub cache_creation_input_tokens: Option<u32>,
+    pub cache_read_input_tokens: Option<u32>,
+}
+
+// Container response object
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct MessagesContainer {
+    pub id: String,
+    #[serde(rename = "type")]
+    pub container_type: String,
+    pub name: String,
+    pub status: String,
+}
+
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct MessagesResponse {
+    pub id: String,
+    #[serde(rename = "type")]
+    pub obj_type: String,
+    pub role: MessagesRole,
+    pub content: Vec<MessagesContentBlock>,
+    pub model: String,
+    pub stop_reason: MessagesStopReason,
+    pub stop_sequence: Option<String>,
+    pub usage: MessagesUsage,
+    pub container: Option<MessagesContainer>,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+#[serde(rename_all = "snake_case")]
+#[serde(tag = "type")]
+pub enum MessagesStreamEvent {
+    MessageStart {
+        message: MessagesStreamMessage,
+    },
+    ContentBlockStart {
+        index: u32,
+        content_block: MessagesContentBlock,
+    },
+    ContentBlockDelta {
+        index: u32,
+        delta: MessagesContentDelta,
+    },
+    ContentBlockStop {
+        index: u32,
+    },
+    MessageDelta {
+        delta: MessagesMessageDelta,
+        usage: MessagesUsage,
+    },
+    MessageStop,
+    Ping,
+}
+
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct MessagesStreamMessage {
+    pub id: String,
+    #[serde(rename = "type")]
+    pub obj_type: String,
+    pub role: MessagesRole,
+    pub content: Vec<Value>, // Initially empty
+    pub model: String,
+    pub stop_reason: Option<MessagesStopReason>,
+    pub stop_sequence: Option<String>,
+    pub usage: MessagesUsage,
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+#[serde(tag = "type")]
+pub enum MessagesContentDelta {
+    #[serde(rename = "text_delta")]
+    TextDelta { text: String },
+    #[serde(rename = "input_json_delta")]
+    InputJsonDelta { partial_json: String },
+}
+
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct MessagesMessageDelta {
+    pub stop_reason: MessagesStopReason,
+    pub stop_sequence: Option<String>,
+}
+
+// Helper functions for API detection and conversion
+impl MessagesRequest {
+    pub fn api_type() -> AnthropicApi {
+        AnthropicApi::Messages
+    }
+}
+
+impl MessagesResponse {
+    pub fn api_type() -> AnthropicApi {
+        AnthropicApi::Messages
+    }
+}
+
+impl MessagesStreamEvent {
+    pub fn api_type() -> AnthropicApi {
+        AnthropicApi::Messages
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json;
+
+    #[test]
+    fn test_anthropic_skip_serializing_none_annotations() {
+        // Test that skip_serializing_none works correctly for MessagesRequest
+        let request = MessagesRequest {
+            model: "claude-3-sonnet-20240229".to_string(),
+            system: None,  // Should be skipped
+            messages: vec![MessagesMessage {
+                role: MessagesRole::User,
+                content: MessagesMessageContent::Single("Hello".to_string()),
+            }],
+            max_tokens: 100,
+            container: None,  // Should be skipped
+            mcp_servers: None,  // Should be skipped
+            service_tier: None,  // Should be skipped
+            thinking: None,  // Should be skipped
+            temperature: None,  // Should be skipped
+            top_p: Some(0.9),   // Should be included
+            top_k: None,        // Should be skipped
+            stream: None,       // Should be skipped
+            stop_sequences: None,  // Should be skipped
+            tools: None,        // Should be skipped
+            tool_choice: None,  // Should be skipped
+            metadata: None,     // Should be skipped
+        };
+
+        let json = serde_json::to_value(&request).unwrap();
+        let obj = json.as_object().unwrap();
+
+        // Verify that None fields are not present in the JSON
+        assert!(!obj.contains_key("system"));
+        assert!(!obj.contains_key("container"));
+        assert!(!obj.contains_key("mcp_servers"));
+        assert!(!obj.contains_key("service_tier"));
+        assert!(!obj.contains_key("thinking"));
+        assert!(!obj.contains_key("temperature"));
+        assert!(!obj.contains_key("top_k"));
+        assert!(!obj.contains_key("stream"));
+        assert!(!obj.contains_key("stop_sequences"));
+        assert!(!obj.contains_key("tools"));
+        assert!(!obj.contains_key("tool_choice"));
+        assert!(!obj.contains_key("metadata"));
+
+        // Verify that required fields and Some fields are present
+        assert!(obj.contains_key("model"));
+        assert!(obj.contains_key("messages"));
+        assert!(obj.contains_key("max_tokens"));
+        assert!(obj.contains_key("top_p"));  // This was Some(0.9)
+    }
+
+    #[test]
+    fn test_anthropic_tool_serialization() {
+        // Test MessagesTool with skip_serializing_none
+        let tool = MessagesTool {
+            name: "get_weather".to_string(),
+            description: None,  // Should be skipped
+            input_schema: serde_json::json!({
+                "type": "object",
+                "properties": {
+                    "location": {"type": "string"}
+                }
+            }),
+        };
+
+        let json = serde_json::to_value(&tool).unwrap();
+        let obj = json.as_object().unwrap();
+
+        assert!(obj.contains_key("name"));
+        assert!(obj.contains_key("input_schema"));
+        assert!(!obj.contains_key("description"));  // Should be skipped
+
+        // Test with description present
+        let tool_with_desc = MessagesTool {
+            name: "get_weather".to_string(),
+            description: Some("Get weather information".to_string()),
+            input_schema: serde_json::json!({"type": "object"}),
+        };
+
+        let json_with_desc = serde_json::to_value(&tool_with_desc).unwrap();
+        let obj_with_desc = json_with_desc.as_object().unwrap();
+
+        assert!(obj_with_desc.contains_key("description"));  // Should be included
+    }
+
+    #[test]
+    fn test_mcp_server_serialization() {
+        // Test McpServer with skip_serializing_none
+        let mcp_server = McpServer {
+            name: "test-server".to_string(),
+            server_type: McpServerType::Url,
+            url: "https://example.com/mcp".to_string(),
+            authorization_token: None,  // Should be skipped
+            tool_configuration: Some(McpToolConfiguration {
+                allowed_tools: Some(vec!["tool1".to_string(), "tool2".to_string()]),
+                enabled: None,  // Should be skipped
+            }),
+        };
+
+        let json = serde_json::to_value(&mcp_server).unwrap();
+        let obj = json.as_object().unwrap();
+
+        // Verify required fields are present
+        assert!(obj.contains_key("name"));
+        assert!(obj.contains_key("type"));
+        assert!(obj.contains_key("url"));
+        assert!(obj.contains_key("tool_configuration"));
+
+        // Verify None fields are not present
+        assert!(!obj.contains_key("authorization_token"));
+
+        // Check tool_configuration
+        let tool_config = obj.get("tool_configuration").unwrap().as_object().unwrap();
+        assert!(tool_config.contains_key("allowed_tools"));
+        assert!(!tool_config.contains_key("enabled"));  // Should be skipped
+
+        // Verify type serialization
+        assert_eq!(obj.get("type").unwrap().as_str().unwrap(), "url");
+    }
+
+    #[test]
+    fn test_service_tier_and_thinking_serialization() {
+        // Test with service_tier and thinking enabled
+        let request_with_fields = MessagesRequest {
+            model: "claude-3-sonnet".to_string(),
+            system: None,
+            messages: vec![MessagesMessage {
+                role: MessagesRole::User,
+                content: MessagesMessageContent::Single("Hello".to_string()),
+            }],
+            max_tokens: 100,
+            container: None,
+            mcp_servers: None,
+            service_tier: Some(ServiceTier::Auto),
+            thinking: Some(ThinkingConfig { enabled: true }),
+            temperature: None,
+            top_p: None,
+            top_k: None,
+            stream: None,
+            stop_sequences: None,
+            tools: None,
+            tool_choice: None,
+            metadata: None,
+        };
+
+        let json = serde_json::to_value(&request_with_fields).unwrap();
+        let obj = json.as_object().unwrap();
+
+        // Verify that Some fields are present
+        assert!(obj.contains_key("service_tier"));
+        assert!(obj.contains_key("thinking"));
+
+        // Verify service_tier serialization
+        assert_eq!(obj.get("service_tier").unwrap().as_str().unwrap(), "auto");
+
+        // Verify thinking serialization
+        let thinking = obj.get("thinking").unwrap().as_object().unwrap();
+        assert!(thinking.contains_key("enabled"));
+        assert_eq!(thinking.get("enabled").unwrap().as_bool().unwrap(), true);
+    }
+
+    #[test]
+    fn test_anthropic_api_provider_trait_implementation() {
+        use super::ApiDefinition;
+
+        // Test that AnthropicApi implements ApiDefinition trait correctly
+        let api = AnthropicApi::Messages;
+
+        // Test trait methods
+        assert_eq!(ApiDefinition::endpoint(&api), "/v1/messages");
+        assert!(ApiDefinition::supports_streaming(&api));
+        assert!(ApiDefinition::supports_tools(&api));
+        assert!(ApiDefinition::supports_vision(&api));
+
+        // Test from_endpoint trait method
+        let found_api = AnthropicApi::from_endpoint("/v1/messages");
+        assert_eq!(found_api, Some(AnthropicApi::Messages));
+
+        let not_found = AnthropicApi::from_endpoint("/v1/unknown");
+        assert_eq!(not_found, None);
+    }
+}
diff --git a/crates/hermesllm/src/apis/mod.rs b/crates/hermesllm/src/apis/mod.rs
new file mode 100644
index 00000000..78b634d5
--- /dev/null
+++ b/crates/hermesllm/src/apis/mod.rs
@@ -0,0 +1,197 @@
+pub mod anthropic;
+pub mod openai;
+
+// Re-export all types for convenience
+pub use anthropic::*;
+pub use openai::*;
+
+/// Common trait that all API definitions must implement
+///
+/// This trait ensures consistency across different AI provider API definitions
+/// and makes it easy to add new providers like Gemini, Claude, etc.
+///
+/// Note: This is different from the `ApiProvider` enum in `clients::endpoints`
+/// which represents provider identification, while this trait defines API capabilities.
+///
+/// # Benefits
+///
+/// - **Consistency**: All API providers implement the same interface
+/// - **Extensibility**: Easy to add new providers without breaking existing code
+/// - **Type Safety**: Compile-time guarantees that all providers implement required methods
+/// - **Discoverability**: Clear documentation of what capabilities each API supports
+///
+/// # Example implementation for a new provider:
+///
+/// ```rust,ignore
+/// use serde::{Deserialize, Serialize};
+/// use super::ApiDefinition;
+///
+/// #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+/// pub enum GeminiApi {
+///     GenerateContent,
+///     ChatCompletions,
+/// }
+///
+/// impl GeminiApi {
+///     pub fn endpoint(&self) -> &'static str {
+///         match self {
+///             GeminiApi::GenerateContent => "/v1/models/gemini-pro:generateContent",
+///             GeminiApi::ChatCompletions => "/v1/models/gemini-pro:chat",
+///         }
+///     }
+///
+///     pub fn from_endpoint(endpoint: &str) -> Option<Self> {
+///         match endpoint {
+///             "/v1/models/gemini-pro:generateContent" => Some(GeminiApi::GenerateContent),
+///             "/v1/models/gemini-pro:chat" => Some(GeminiApi::ChatCompletions),
+///             _ => None,
+///         }
+///     }
+///
+///     pub fn supports_streaming(&self) -> bool {
+///         match self {
+///             GeminiApi::GenerateContent => true,
+///             GeminiApi::ChatCompletions => true,
+///         }
+///     }
+///
+///     pub fn supports_tools(&self) -> bool {
+///         match self {
+///             GeminiApi::GenerateContent => true,
+///             GeminiApi::ChatCompletions => false,
+///         }
+///     }
+///
+///     pub fn supports_vision(&self) -> bool {
+///         match self {
+///             GeminiApi::GenerateContent => true,
+///             GeminiApi::ChatCompletions => false,
+///         }
+///     }
+/// }
+///
+/// impl ApiDefinition for GeminiApi {
+///     fn endpoint(&self) -> &'static str {
+///         self.endpoint()
+///     }
+///
+///     fn from_endpoint(endpoint: &str) -> Option<Self> {
+///         Self::from_endpoint(endpoint)
+///     }
+///
+///     fn supports_streaming(&self) -> bool {
+///         self.supports_streaming()
+///     }
+///
+///     fn supports_tools(&self) -> bool {
+///         self.supports_tools()
+///     }
+///
+///     fn supports_vision(&self) -> bool {
+///         self.supports_vision()
+///     }
+/// }
+///
+/// // Now you can use generic code that works with any API:
+/// fn print_api_info<T: ApiDefinition>(api: &T) {
+///     println!("Endpoint: {}", api.endpoint());
+///     println!("Supports streaming: {}", api.supports_streaming());
+///     println!("Supports tools: {}", api.supports_tools());
+///     println!("Supports vision: {}", api.supports_vision());
+/// }
+///
+/// // Works with both OpenAI and Anthropic (and future Gemini)
+/// print_api_info(&OpenAIApi::ChatCompletions);
+/// print_api_info(&AnthropicApi::Messages);
+/// print_api_info(&GeminiApi::GenerateContent);
+/// ```
+pub trait ApiDefinition {
+    /// Returns the endpoint path for this API
+    fn endpoint(&self) -> &'static str;
+
+    /// Creates an API instance from an endpoint path
+    fn from_endpoint(endpoint: &str) -> Option<Self>
+    where
+        Self: Sized;
+
+    /// Returns whether this API supports streaming responses
+    fn supports_streaming(&self) -> bool;
+
+    /// Returns whether this API supports tool/function calling
+    fn supports_tools(&self) -> bool;
+
+    /// Returns whether this API supports vision/image processing
+    fn supports_vision(&self) -> bool;
+
+    /// Returns all variants of this API enum
+    fn all_variants() -> Vec<Self>
+    where
+        Self: Sized;
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_generic_api_functionality() {
+        // Test that our generic API functionality works with both providers
+        fn test_api<T: ApiDefinition>(api: &T) {
+            let endpoint = api.endpoint();
+            assert!(!endpoint.is_empty());
+            assert!(endpoint.starts_with('/'));
+        }
+
+        test_api(&OpenAIApi::ChatCompletions);
+        test_api(&AnthropicApi::Messages);
+    }
+
+    #[test]
+    fn test_api_detection_from_endpoints() {
+        // Test that we can detect APIs from endpoints using the trait
+        let endpoints = vec![
+            "/v1/chat/completions",
+            "/v1/messages",
+            "/v1/unknown"
+        ];
+
+        let mut detected_apis = Vec::new();
+
+        for endpoint in endpoints {
+            if let Some(api) = OpenAIApi::from_endpoint(endpoint) {
+                detected_apis.push(format!("OpenAI: {:?}", api));
+            } else if let Some(api) = AnthropicApi::from_endpoint(endpoint) {
+                detected_apis.push(format!("Anthropic: {:?}", api));
+            } else {
+                detected_apis.push("Unknown API".to_string());
+            }
+        }
+
+        assert_eq!(detected_apis, vec![
+            "OpenAI: ChatCompletions",
+            "Anthropic: Messages",
+            "Unknown API"
+        ]);
+    }
+
+    #[test]
+    fn test_all_variants_method() {
+        // Test that all_variants returns the expected variants
+        let openai_variants = OpenAIApi::all_variants();
+        assert_eq!(openai_variants.len(), 1);
+        assert!(openai_variants.contains(&OpenAIApi::ChatCompletions));
+
+        let anthropic_variants = AnthropicApi::all_variants();
+        assert_eq!(anthropic_variants.len(), 1);
+        assert!(anthropic_variants.contains(&AnthropicApi::Messages));
+
+        // Verify each variant has a valid endpoint
+        for variant in openai_variants {
+            assert!(!variant.endpoint().is_empty());
+        }
+
+        for variant in anthropic_variants {
+            assert!(!variant.endpoint().is_empty());
+        }
+    }
+}
diff --git a/crates/hermesllm/src/apis/openai.rs b/crates/hermesllm/src/apis/openai.rs
new file mode 100644
index 00000000..eb270510
--- /dev/null
+++ b/crates/hermesllm/src/apis/openai.rs
@@ -0,0 +1,1303 @@
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use serde_with::skip_serializing_none;
+use std::collections::HashMap;
+
+use super::ApiDefinition;
+
+// ============================================================================
+// OPENAI API ENUMERATION
+// ============================================================================
+
+/// Enum for all supported OpenAI APIs
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub enum OpenAIApi {
+    ChatCompletions,
+    // Future APIs can be added here:
+    // Embeddings,
+    // FineTuning,
+    // etc.
+}
+
+impl ApiDefinition for OpenAIApi {
+    fn endpoint(&self) -> &'static str {
+        match self {
+            OpenAIApi::ChatCompletions => "/v1/chat/completions",
+        }
+    }
+
+    fn from_endpoint(endpoint: &str) -> Option<Self> {
+        match endpoint {
+            "/v1/chat/completions" => Some(OpenAIApi::ChatCompletions),
+            _ => None,
+        }
+    }
+
+    fn supports_streaming(&self) -> bool {
+        match self {
+            OpenAIApi::ChatCompletions => true,
+        }
+    }
+
+    fn supports_tools(&self) -> bool {
+         match self {
+            OpenAIApi::ChatCompletions => true,
+        }
+    }
+
+    fn supports_vision(&self) -> bool {
+        match self {
+            OpenAIApi::ChatCompletions => true,
+        }
+    }
+
+    fn all_variants() -> Vec<Self> {
+        vec![
+            OpenAIApi::ChatCompletions,
+        ]
+    }
+}
+
+/// Chat completions API request
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct ChatCompletionsRequest {
+    pub messages: Vec<Message>,
+    pub model: String,
+    // pub auduio: Option<Audio> // GOOD FIRST ISSUE: future support for audio input
+    pub frequency_penalty: Option<f32>,
+    // Function calling configuration has been deprecated, but we keep it for compatibility
+    pub function_call: Option<FunctionChoice>,
+    pub functions: Option<Vec<Tool>>,
+    pub logit_bias: Option<HashMap<String, i32>>,
+    pub logprobs: Option<bool>,
+    pub max_completion_tokens: Option<u32>,
+    // Maximum tokens in the response has been deprecated, but we keep it for compatibility
+    pub max_tokens: Option<u32>,
+    pub modalities: Option<Vec<String>>,
+    pub metadata: Option<HashMap<String, String>>,
+    pub n: Option<u32>,
+    pub presence_penalty: Option<f32>,
+    pub parallel_tool_calls: Option<bool>,
+    pub prediction: Option<StaticContent>,
+    // pub reasoning_effect: Option<bool>, // GOOD FIRST ISSUE: Future support for reasoning effects
+    pub response_format: Option<Value>,
+    // pub safety_identifier: Option<String>, // GOOD FIRST ISSUE: Future support for safety identifiers
+    pub seed: Option<i32>,
+    pub service_tier: Option<String>,
+    pub stop: Option<Vec<String>>,
+    pub store: Option<bool>,
+    pub stream: Option<bool>,
+    pub stream_options: Option<StreamOptions>,
+    pub temperature: Option<f32>,
+    pub tool_choice: Option<ToolChoice>,
+    pub tools: Option<Vec<Tool>>,
+    pub top_p: Option<f32>,
+    pub top_logprobs: Option<u32>,
+    pub user: Option<String>,
+    // pub web_search: Option<bool>, // GOOD FIRST ISSUE: Future support for web search
+}
+
+// ============================================================================
+// CHAT COMPLETIONS API TYPES
+// ============================================================================
+
+/// Message role in a chat conversation
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
+#[serde(rename_all = "lowercase")]
+pub enum Role {
+    System,
+    User,
+    Assistant,
+    Tool,
+}
+
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct Message {
+    pub role: Role,
+    pub content: MessageContent,
+    pub name: Option<String>,
+    /// Tool calls made by the assistant (only present for assistant role)
+    pub tool_calls: Option<Vec<ToolCall>>,
+    /// ID of the tool call that this message is responding to (only present for tool role)
+    pub tool_call_id: Option<String>,
+}
+
+
+
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct ResponseMessage {
+    pub role: Role,
+    /// The contents of the message (can be null for some cases)
+    pub content: Option<String>,
+    /// The refusal message generated by the model
+    pub refusal: Option<String>,
+    /// Annotations for the message, when applicable, as when using the web search tool
+    pub annotations: Option<Vec<Value>>,
+    /// If the audio output modality is requested, this object contains data about the audio response
+    pub audio: Option<Value>,
+    /// Deprecated and replaced by tool_calls. The name and arguments of a function that should be called
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub function_call: Option<FunctionCall>,
+    /// The tool calls generated by the model, such as function calls
+    pub tool_calls: Option<Vec<ToolCall>>,
+}
+
+impl ResponseMessage {
+    /// Convert ResponseMessage to Message for internal processing
+    /// This is useful for transformations that need to work with the request Message type
+    pub fn to_message(&self) -> Message {
+        Message {
+            role: self.role.clone(),
+            content: self.content.as_ref()
+                .map(|s| MessageContent::Text(s.clone()))
+                .unwrap_or(MessageContent::Text(String::new())),
+            name: None, // Response messages don't have names in the same way request messages do
+            tool_calls: self.tool_calls.clone(),
+            tool_call_id: None, // Response messages don't have tool_call_id
+        }
+    }
+}
+
+/// In the OpenAI API, this is represented as either:
+/// - A string for simple text content
+/// - An array of content parts for multimodal content (text + images)
+#[derive(Serialize, Deserialize, Debug, Clone)]
+#[serde(untagged)]
+pub enum MessageContent {
+    Text(String),
+    Parts(Vec<ContentPart>),
+}
+
+/// Individual content part within a message (text or image)
+#[derive(Serialize, Deserialize, Debug, Clone)]
+#[serde(tag = "type")]
+pub enum ContentPart {
+    #[serde(rename = "text")]
+    Text { text: String },
+    #[serde(rename = "image_url")]
+    ImageUrl { image_url: ImageUrl },
+}
+
+/// Image URL configuration for vision capabilities
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct ImageUrl {
+    pub url: String,
+    pub detail: Option<String>,
+}
+
+/// A single message in a chat conversation
+
+
+/// A tool call made by the assistant
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+pub struct ToolCall {
+    pub id: String,
+    #[serde(rename = "type")]
+    pub call_type: String,
+    pub function: FunctionCall,
+}
+
+/// Function call within a tool call
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
+pub struct FunctionCall {
+    pub name: String,
+    pub arguments: String,
+}
+
+/// Tool definition for function calling
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct Tool {
+    #[serde(rename = "type")]
+    pub tool_type: String,
+    pub function: Function,
+}
+
+/// Function definition within a tool
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct Function {
+    pub name: String,
+    pub description: Option<String>,
+    pub parameters: Value,
+    pub strict: Option<bool>,
+}
+
+/// Tool choice configuration
+#[derive(Serialize, Deserialize, Debug, Clone)]
+#[serde(untagged)]
+pub enum ToolChoice {
+    String(String), // "none", "auto", "required"
+    Function {
+        #[serde(rename = "type")]
+        choice_type: String,
+        function: FunctionChoice,
+    },
+}
+
+/// Specific function choice
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct FunctionChoice {
+    pub name: String,
+}
+
+/// Static content for prediction/prefill functionality
+///
+/// Static predicted output content, such as the content of a text file
+/// that is being regenerated.
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct StaticContent {
+    /// The type of the predicted content you want to provide.
+    /// This type is currently always "content".
+    #[serde(rename = "type")]
+    pub content_type: String,
+    /// The content that should be matched when generating a model response.
+    /// If generated tokens would match this content, the entire model response
+    /// can be returned much more quickly.
+    ///
+    /// Can be either:
+    /// - A string for simple text content
+    /// - An array of content parts for structured content
+    pub content: StaticContentType,
+}
+
+/// Content type for static/predicted content
+#[derive(Serialize, Deserialize, Debug, Clone)]
+#[serde(untagged)]
+pub enum StaticContentType {
+    /// Simple text content - the content used for a Predicted Output.
+    /// This is often the text of a file you are regenerating with minor changes.
+    Text(String),
+    /// An array of content parts with a defined type.
+    /// Can contain text inputs and other supported content types.
+    Parts(Vec<ContentPart>),
+}
+
+
+/// Chat completions API response
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct ChatCompletionsResponse {
+    pub id: String,
+    pub object: String,
+    pub created: u64,
+    pub model: String,
+    pub choices: Vec<Choice>,
+    pub usage: Usage,
+    pub system_fingerprint: Option<String>,
+}
+
+/// Finish reason for completion
+#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum FinishReason {
+    Stop,
+    Length,
+    ToolCalls,
+    ContentFilter,
+    FunctionCall, // Legacy
+}
+
+/// Token usage information
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct Usage {
+    pub prompt_tokens: u32,
+    pub completion_tokens: u32,
+    pub total_tokens: u32,
+    pub prompt_tokens_details: Option<PromptTokensDetails>,
+    pub completion_tokens_details: Option<CompletionTokensDetails>,
+}
+
+/// Detailed breakdown of prompt tokens
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct PromptTokensDetails {
+    pub cached_tokens: Option<u32>,
+    pub audio_tokens: Option<u32>,
+}
+
+/// Detailed breakdown of completion tokens
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct CompletionTokensDetails {
+    pub reasoning_tokens: Option<u32>,
+    pub audio_tokens: Option<u32>,
+    pub accepted_prediction_tokens: Option<u32>,
+    pub rejected_prediction_tokens: Option<u32>,
+}
+
+/// A single choice in the response
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct Choice {
+    pub index: u32,
+    pub message: ResponseMessage,
+    pub finish_reason: Option<FinishReason>,
+    pub logprobs: Option<Value>,
+}
+
+
+// ============================================================================
+// STREAMING API TYPES
+// ============================================================================
+
+/// Streaming response from chat completions API
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct ChatCompletionsStreamResponse {
+    pub id: String,
+    pub object: String,
+    pub created: u64,
+    pub model: String,
+    pub choices: Vec<StreamChoice>,
+    pub usage: Option<Usage>, // Only in final chunk
+    pub system_fingerprint: Option<String>,
+    /// Specifies the processing type used for serving the request
+    pub service_tier: Option<String>,
+}
+
+
+/// A choice in a streaming response
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct StreamChoice {
+    pub index: u32,
+    pub delta: MessageDelta,
+    pub finish_reason: Option<FinishReason>,
+    pub logprobs: Option<Value>,
+}
+
+/// Message delta for streaming updates
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct MessageDelta {
+    pub role: Option<Role>,
+    pub content: Option<String>,
+    /// The refusal message generated by the model
+    pub refusal: Option<String>,
+    /// Deprecated and replaced by tool_calls. The name and arguments of a function that should be called
+    pub function_call: Option<FunctionCall>,
+    pub tool_calls: Option<Vec<ToolCallDelta>>,
+}
+
+/// Tool call delta for streaming tool call updates
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct ToolCallDelta {
+    pub index: u32,
+    pub id: Option<String>,
+    #[serde(rename = "type")]
+    pub call_type: Option<String>,
+    pub function: Option<FunctionCallDelta>,
+}
+
+/// Function call delta for streaming function call updates
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct FunctionCallDelta {
+    pub name: Option<String>,
+    pub arguments: Option<String>,
+}
+
+
+// ============================================================================
+// LEGACY COMPATIBILITY & TYPE ALIASES
+// ============================================================================
+
+/// Stream options for controlling streaming behavior
+#[skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct StreamOptions {
+    pub include_usage: Option<bool>,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn test_improved_naming_structure() {
+        // Test that the new clean naming works well
+        let message = Message {
+            role: Role::User,
+            content: MessageContent::Text("Hello, world!".to_string()),
+            name: None,
+            tool_calls: None,
+            tool_call_id: None,
+        };
+
+        let request = ChatCompletionsRequest {
+            model: "gpt-4".to_string(),
+            messages: vec![message],
+            temperature: Some(0.7),
+            top_p: None,
+            max_tokens: Some(100),
+            max_completion_tokens: None,
+            stream: Some(false),
+            stream_options: None,
+            stop: None,
+            tools: None,
+            tool_choice: None,
+            parallel_tool_calls: None,
+            user: None,
+            presence_penalty: None,
+            frequency_penalty: None,
+            logit_bias: None,
+            logprobs: None,
+            top_logprobs: None,
+            n: None,
+            seed: None,
+            response_format: None,
+            service_tier: None,
+            store: None,
+            metadata: None,
+            modalities: None,
+            function_call: None,
+            functions: None,
+            prediction: None,
+        };
+
+        assert_eq!(request.model, "gpt-4");
+        assert_eq!(request.messages.len(), 1);
+        assert_eq!(request.messages[0].role, Role::User);
+    }
+
+    #[test]
+    fn test_tool_structure() {
+        let tool = Tool {
+            tool_type: "function".to_string(),
+            function: Function {
+                name: "get_weather".to_string(),
+                description: Some("Get weather information".to_string()),
+                parameters: json!({
+                    "type": "object",
+                    "properties": {
+                        "location": {"type": "string"}
+                    }
+                }),
+                strict: None,
+            },
+        };
+
+        assert_eq!(tool.function.name, "get_weather");
+        assert!(tool.function.description.is_some());
+    }
+
+    #[test]
+    fn test_content_parts() {
+        let text_part = ContentPart::Text {
+            text: "Describe this image".to_string(),
+        };
+
+        let image_part = ContentPart::ImageUrl {
+            image_url: ImageUrl {
+                url: "https://example.com/image.jpg".to_string(),
+                detail: Some("high".to_string()),
+            },
+        };
+
+        let content = MessageContent::Parts(vec![text_part, image_part]);
+
+        if let MessageContent::Parts(parts) = content {
+            assert_eq!(parts.len(), 2);
+
+            if let ContentPart::Text { text } = &parts[0] {
+                assert_eq!(text, "Describe this image");
+            } else {
+                panic!("Expected text part");
+            }
+
+            if let ContentPart::ImageUrl { image_url } = &parts[1] {
+                assert_eq!(image_url.url, "https://example.com/image.jpg");
+                assert_eq!(image_url.detail, Some("high".to_string()));
+            } else {
+                panic!("Expected image part");
+            }
+        } else {
+            panic!("Expected parts content");
+        }
+    }
+
+    #[test]
+    fn test_api_enum() {
+        let api = OpenAIApi::ChatCompletions;
+        assert_eq!(api.endpoint(), "/v1/chat/completions");
+        assert!(api.supports_streaming());
+        assert!(api.supports_tools());
+        assert!(api.supports_vision());
+
+        let found_api = OpenAIApi::from_endpoint("/v1/chat/completions");
+        assert_eq!(found_api, Some(OpenAIApi::ChatCompletions));
+    }
+
+    #[test]
+    fn test_api_specific_naming() {
+        // Test that the API-specific naming is clear and intuitive
+        let request = ChatCompletionsRequest {
+            model: "gpt-4".to_string(),
+            messages: vec![Message {
+                role: Role::User,
+                content: MessageContent::Text("Test message".to_string()),
+                name: None,
+                tool_calls: None,
+                tool_call_id: None,
+            }],
+            temperature: Some(0.7),
+            top_p: None,
+            max_tokens: Some(100),
+            max_completion_tokens: None,
+            stream: Some(false),
+            stream_options: None,
+            stop: None,
+            tools: None,
+            tool_choice: None,
+            parallel_tool_calls: None,
+            user: None,
+            presence_penalty: None,
+            frequency_penalty: None,
+            logit_bias: None,
+            logprobs: None,
+            top_logprobs: None,
+            n: None,
+            seed: None,
+            response_format: None,
+            service_tier: None,
+            store: None,
+            metadata: None,
+            modalities: None,
+            function_call: None,
+            functions: None,
+            prediction: None,
+        };
+
+        let response = ChatCompletionsResponse {
+            id: "chatcmpl-123".to_string(),
+            object: "chat.completion".to_string(),
+            created: 1234567890,
+            model: "gpt-4".to_string(),
+            choices: vec![Choice {
+                index: 0,
+                message: ResponseMessage {
+                    role: Role::Assistant,
+                    content: Some("Hello!".to_string()),
+                    refusal: None,
+                    annotations: None,
+                    audio: None,
+                    function_call: None,
+                    tool_calls: None,
+                },
+                finish_reason: Some(FinishReason::Stop),
+                logprobs: None,
+            }],
+            usage: Usage {
+                prompt_tokens: 10,
+                completion_tokens: 5,
+                total_tokens: 15,
+                prompt_tokens_details: None,
+                completion_tokens_details: None,
+            },
+            system_fingerprint: None,
+        };
+
+        let stream_response = ChatCompletionsStreamResponse {
+            id: "chatcmpl-stream-123".to_string(),
+            object: "chat.completion.chunk".to_string(),
+            created: 1234567890,
+            model: "gpt-4".to_string(),
+            choices: vec![StreamChoice {
+                index: 0,
+                delta: MessageDelta {
+                    role: Some(Role::Assistant),
+                    content: Some("Hello".to_string()),
+                    refusal: None,
+                    function_call: None,
+                    tool_calls: None,
+                },
+                finish_reason: None,
+                logprobs: None,
+            }],
+            usage: None,
+            system_fingerprint: None,
+            service_tier: None,
+        };
+
+        // Assert the naming makes sense
+        assert_eq!(request.model, "gpt-4");
+        assert_eq!(response.choices[0].message.role, Role::Assistant);
+        assert_eq!(stream_response.object, "chat.completion.chunk");
+    }
+
+    #[test]
+    fn test_skip_serializing_none_annotations() {
+        // Test that skip_serializing_none works correctly
+        let message = Message {
+            role: Role::User,
+            content: MessageContent::Text("Hello".to_string()),
+            name: None,  // Should be skipped
+            tool_calls: None,  // Should be skipped
+            tool_call_id: None,  // Should be skipped
+        };
+
+        let json = serde_json::to_value(&message).unwrap();
+
+        // Verify that None fields are not present in the JSON
+        assert!(!json.as_object().unwrap().contains_key("name"));
+        assert!(!json.as_object().unwrap().contains_key("tool_calls"));
+        assert!(!json.as_object().unwrap().contains_key("tool_call_id"));
+
+        // Verify that required fields are present
+        assert!(json.as_object().unwrap().contains_key("role"));
+        assert!(json.as_object().unwrap().contains_key("content"));
+
+        // Test with Some values to ensure they are included
+        let message_with_name = Message {
+            role: Role::Assistant,
+            content: MessageContent::Text("Hello back".to_string()),
+            name: Some("assistant".to_string()),
+            tool_calls: None,
+            tool_call_id: None,
+        };
+
+        let json_with_name = serde_json::to_value(&message_with_name).unwrap();
+        assert!(json_with_name.as_object().unwrap().contains_key("name"));
+        assert!(!json_with_name.as_object().unwrap().contains_key("tool_calls"));
+    }
+
+    #[test]
+    fn test_api_provider_trait_implementation() {
+        use super::ApiDefinition;
+
+        // Test that OpenAIApi implements ApiDefinition trait correctly
+        let api = OpenAIApi::ChatCompletions;
+
+        // Test trait methods
+        assert_eq!(ApiDefinition::endpoint(&api), "/v1/chat/completions");
+        assert!(ApiDefinition::supports_streaming(&api));
+        assert!(ApiDefinition::supports_tools(&api));
+        assert!(ApiDefinition::supports_vision(&api));
+
+        // Test from_endpoint trait method
+        let found_api = OpenAIApi::from_endpoint("/v1/chat/completions");
+        assert_eq!(found_api, Some(OpenAIApi::ChatCompletions));
+
+        let not_found = OpenAIApi::from_endpoint("/v1/unknown");
+        assert_eq!(not_found, None);
+    }
+
+    #[test]
+    fn test_new_api_fields() {
+        // Test that new fields are properly handled
+        let request = ChatCompletionsRequest {
+            model: "gpt-4".to_string(),
+            messages: vec![Message {
+                role: Role::User,
+                content: MessageContent::Text("Test".to_string()),
+                name: None,
+                tool_calls: None,
+                tool_call_id: None,
+            }],
+            temperature: Some(0.7),
+            top_p: None,
+            max_tokens: Some(100),
+            max_completion_tokens: Some(150), // New field
+            stream: Some(true),
+            stream_options: Some(StreamOptions {
+                include_usage: Some(true), // New field
+            }),
+            stop: None,
+            tools: None,
+            tool_choice: None,
+            parallel_tool_calls: None,
+            user: None,
+            presence_penalty: None,
+            frequency_penalty: None,
+            logit_bias: None,
+            logprobs: None,
+            top_logprobs: None,
+            n: None,
+            seed: None,
+            response_format: None,
+            service_tier: Some("default".to_string()), // New field
+            store: Some(true), // New field
+            metadata: Some(HashMap::from([
+                ("user_id".to_string(), "123".to_string()),
+                ("session_id".to_string(), "abc".to_string()),
+            ])), // New field
+            modalities: None,
+            function_call: None,
+            functions: None,
+            prediction: None,
+        };
+
+        // Test serialization works
+        let json = serde_json::to_value(&request).unwrap();
+        assert!(json.as_object().unwrap().contains_key("max_completion_tokens"));
+        assert!(json.as_object().unwrap().contains_key("stream_options"));
+        assert!(json.as_object().unwrap().contains_key("service_tier"));
+        assert!(json.as_object().unwrap().contains_key("store"));
+        assert!(json.as_object().unwrap().contains_key("metadata"));
+
+        // Test that None fields are skipped
+        let minimal_request = ChatCompletionsRequest {
+            model: "gpt-4".to_string(),
+            messages: vec![Message {
+                role: Role::User,
+                content: MessageContent::Text("Test".to_string()),
+                name: None,
+                tool_calls: None,
+                tool_call_id: None,
+            }],
+            temperature: None,
+            top_p: None,
+            max_tokens: None,
+            max_completion_tokens: None,
+            stream: None,
+            stream_options: None,
+            stop: None,
+            tools: None,
+            tool_choice: None,
+            parallel_tool_calls: None,
+            user: None,
+            presence_penalty: None,
+            frequency_penalty: None,
+            logit_bias: None,
+            logprobs: None,
+            top_logprobs: None,
+            n: None,
+            seed: None,
+            response_format: None,
+            service_tier: None,
+            store: None,
+            metadata: None,
+            modalities: None,
+            function_call: None,
+            functions: None,
+            prediction: None,
+        };
+
+        let minimal_json = serde_json::to_value(&minimal_request).unwrap();
+        let obj = minimal_json.as_object().unwrap();
+
+        // These new fields should not be present when None
+        assert!(!obj.contains_key("max_completion_tokens"));
+        assert!(!obj.contains_key("stream_options"));
+        assert!(!obj.contains_key("service_tier"));
+        assert!(!obj.contains_key("store"));
+        assert!(!obj.contains_key("metadata"));
+    }
+
+    #[test]
+    fn test_token_usage_details() {
+        // Test that the detailed token usage types work correctly
+        let usage_with_details = Usage {
+            prompt_tokens: 100,
+            completion_tokens: 50,
+            total_tokens: 150,
+            prompt_tokens_details: Some(PromptTokensDetails {
+                cached_tokens: Some(20),
+                audio_tokens: Some(10),
+            }),
+            completion_tokens_details: Some(CompletionTokensDetails {
+                reasoning_tokens: Some(30),
+                audio_tokens: Some(5),
+                accepted_prediction_tokens: Some(15),
+                rejected_prediction_tokens: Some(3),
+            }),
+        };
+
+        let json = serde_json::to_value(&usage_with_details).unwrap();
+        let obj = json.as_object().unwrap();
+
+        assert!(obj.contains_key("prompt_tokens_details"));
+        assert!(obj.contains_key("completion_tokens_details"));
+
+        // Test basic usage without details
+        let basic_usage = Usage {
+            prompt_tokens: 100,
+            completion_tokens: 50,
+            total_tokens: 150,
+            prompt_tokens_details: None,
+            completion_tokens_details: None,
+        };
+
+        let basic_json = serde_json::to_value(&basic_usage).unwrap();
+        let basic_obj = basic_json.as_object().unwrap();
+
+        // None fields should be skipped
+        assert!(!basic_obj.contains_key("prompt_tokens_details"));
+        assert!(!basic_obj.contains_key("completion_tokens_details"));
+    }
+
+    #[test]
+    fn test_message_content_serialization() {
+        // Test that MessageContent serializes correctly for OpenAI API
+
+        // Test simple text content
+        let text_message = Message {
+            role: Role::User,
+            content: MessageContent::Text("Hello, how are you?".to_string()),
+            name: None,
+            tool_calls: None,
+            tool_call_id: None,
+        };
+
+        let text_json = serde_json::to_value(&text_message).unwrap();
+        let content_value = &text_json["content"];
+
+        // Should serialize as a simple string
+        assert!(content_value.is_string());
+        assert_eq!(content_value.as_str().unwrap(), "Hello, how are you?");
+
+        // Test multimodal content with text and image
+        let parts_message = Message {
+            role: Role::User,
+            content: MessageContent::Parts(vec![
+                ContentPart::Text {
+                    text: "What's in this image?".to_string(),
+                },
+                ContentPart::ImageUrl {
+                    image_url: ImageUrl {
+                        url: "https://example.com/image.jpg".to_string(),
+                        detail: Some("high".to_string()),
+                    },
+                },
+            ]),
+            name: None,
+            tool_calls: None,
+            tool_call_id: None,
+        };
+
+        let parts_json = serde_json::to_value(&parts_message).unwrap();
+        let parts_content_value = &parts_json["content"];
+
+        // Should serialize as an array
+        assert!(parts_content_value.is_array());
+        let parts_array = parts_content_value.as_array().unwrap();
+        assert_eq!(parts_array.len(), 2);
+
+        // First part should be text
+        assert_eq!(parts_array[0]["type"], "text");
+        assert_eq!(parts_array[0]["text"], "What's in this image?");
+
+        // Second part should be image
+        assert_eq!(parts_array[1]["type"], "image_url");
+        assert_eq!(parts_array[1]["image_url"]["url"], "https://example.com/image.jpg");
+        assert_eq!(parts_array[1]["image_url"]["detail"], "high");
+
+        // Test deserialization back
+        let deserialized_text: Message = serde_json::from_value(text_json).unwrap();
+        if let MessageContent::Text(text) = deserialized_text.content {
+            assert_eq!(text, "Hello, how are you?");
+        } else {
+            panic!("Expected text content");
+        }
+
+        let deserialized_parts: Message = serde_json::from_value(parts_json).unwrap();
+        if let MessageContent::Parts(parts) = deserialized_parts.content {
+            assert_eq!(parts.len(), 2);
+            if let ContentPart::Text { text } = &parts[0] {
+                assert_eq!(text, "What's in this image?");
+            } else {
+                panic!("Expected text part");
+            }
+        } else {
+            panic!("Expected parts content");
+        }
+    }
+
+    #[test]
+    fn test_static_content_serialization() {
+        // Test StaticContent serialization for prediction functionality
+
+        // Test simple text static content
+        let text_static = StaticContent {
+            content_type: "content".to_string(),
+            content: StaticContentType::Text("This is the predicted text output".to_string()),
+        };
+
+        let text_json = serde_json::to_value(&text_static).unwrap();
+        assert_eq!(text_json["type"], "content");
+        assert_eq!(text_json["content"], "This is the predicted text output");
+
+        // Test structured static content with parts
+        let parts_static = StaticContent {
+            content_type: "content".to_string(),
+            content: StaticContentType::Parts(vec![
+                ContentPart::Text {
+                    text: "First part of predicted content".to_string(),
+                },
+                ContentPart::Text {
+                    text: "Second part of predicted content".to_string(),
+                },
+            ]),
+        };
+
+        let parts_json = serde_json::to_value(&parts_static).unwrap();
+        assert_eq!(parts_json["type"], "content");
+        assert!(parts_json["content"].is_array());
+
+        let content_array = parts_json["content"].as_array().unwrap();
+        assert_eq!(content_array.len(), 2);
+        assert_eq!(content_array[0]["type"], "text");
+        assert_eq!(content_array[0]["text"], "First part of predicted content");
+        assert_eq!(content_array[1]["type"], "text");
+        assert_eq!(content_array[1]["text"], "Second part of predicted content");
+
+        // Test in a ChatCompletionsRequest
+        let request_with_prediction = ChatCompletionsRequest {
+            model: "gpt-4".to_string(),
+            messages: vec![Message {
+                role: Role::User,
+                content: MessageContent::Text("Continue this file:".to_string()),
+                name: None,
+                tool_calls: None,
+                tool_call_id: None,
+            }],
+            prediction: Some(text_static),
+            temperature: Some(0.1),
+            // ... other fields as None
+            top_p: None,
+            max_tokens: None,
+            max_completion_tokens: None,
+            stream: None,
+            stream_options: None,
+            stop: None,
+            tools: None,
+            tool_choice: None,
+            parallel_tool_calls: None,
+            user: None,
+            presence_penalty: None,
+            frequency_penalty: None,
+            logit_bias: None,
+            logprobs: None,
+            top_logprobs: None,
+            n: None,
+            seed: None,
+            response_format: None,
+            service_tier: None,
+            store: None,
+            metadata: None,
+            modalities: None,
+            function_call: None,
+            functions: None,
+        };
+
+        let request_json = serde_json::to_value(&request_with_prediction).unwrap();
+        assert!(request_json.as_object().unwrap().contains_key("prediction"));
+
+        let prediction_value = &request_json["prediction"];
+        assert_eq!(prediction_value["type"], "content");
+        assert_eq!(prediction_value["content"], "This is the predicted text output");
+
+        // Test deserialization
+        let deserialized: StaticContent = serde_json::from_value(text_json).unwrap();
+        assert_eq!(deserialized.content_type, "content");
+        if let StaticContentType::Text(content) = deserialized.content {
+            assert_eq!(content, "This is the predicted text output");
+        } else {
+            panic!("Expected text static content");
+        }
+    }
+
+    #[test]
+    fn test_role_specific_message_fields() {
+        // Test that tool_calls and tool_call_id are properly serialized/skipped based on role
+
+        // User message - should not have tool_calls or tool_call_id
+        let user_message = Message {
+            role: Role::User,
+            content: MessageContent::Text("Hello!".to_string()),
+            name: None,
+            tool_calls: None,
+            tool_call_id: None,
+        };
+
+        let user_json = serde_json::to_value(&user_message).unwrap();
+        let user_obj = user_json.as_object().unwrap();
+
+        assert_eq!(user_obj["role"], "user");
+        assert_eq!(user_obj["content"], "Hello!");
+        // These should be omitted when None
+        assert!(!user_obj.contains_key("tool_calls"));
+        assert!(!user_obj.contains_key("tool_call_id"));
+        assert!(!user_obj.contains_key("name"));
+
+        // Assistant message with tool calls
+        let assistant_message = Message {
+            role: Role::Assistant,
+            content: MessageContent::Text("I'll help you with that.".to_string()),
+            name: None,
+            tool_calls: Some(vec![ToolCall {
+                id: "call_123".to_string(),
+                call_type: "function".to_string(),
+                function: FunctionCall {
+                    name: "get_weather".to_string(),
+                    arguments: r#"{"location": "San Francisco"}"#.to_string(),
+                },
+            }]),
+            tool_call_id: None,
+        };
+
+        let assistant_json = serde_json::to_value(&assistant_message).unwrap();
+        let assistant_obj = assistant_json.as_object().unwrap();
+
+        assert_eq!(assistant_obj["role"], "assistant");
+        assert_eq!(assistant_obj["content"], "I'll help you with that.");
+        assert!(assistant_obj.contains_key("tool_calls"));
+        assert!(!assistant_obj.contains_key("tool_call_id")); // Should be omitted for assistant
+
+        let tool_calls = assistant_obj["tool_calls"].as_array().unwrap();
+        assert_eq!(tool_calls.len(), 1);
+        assert_eq!(tool_calls[0]["id"], "call_123");
+
+        // Tool message responding to a tool call
+        let tool_message = Message {
+            role: Role::Tool,
+            content: MessageContent::Text("The weather in San Francisco is sunny, 72°F".to_string()),
+            name: None,
+            tool_calls: None,
+            tool_call_id: Some("call_123".to_string()),
+        };
+
+        let tool_json = serde_json::to_value(&tool_message).unwrap();
+        let tool_obj = tool_json.as_object().unwrap();
+
+        assert_eq!(tool_obj["role"], "tool");
+        assert_eq!(tool_obj["content"], "The weather in San Francisco is sunny, 72°F");
+        assert_eq!(tool_obj["tool_call_id"], "call_123");
+        assert!(!tool_obj.contains_key("tool_calls")); // Should be omitted for tool messages
+
+        // Test deserialization
+        let deserialized_tool: Message = serde_json::from_value(tool_json).unwrap();
+        assert_eq!(deserialized_tool.role, Role::Tool);
+        assert_eq!(deserialized_tool.tool_call_id, Some("call_123".to_string()));
+        assert!(deserialized_tool.tool_calls.is_none());
+    }
+
+    #[test]
+    fn test_request_vs_response_messages() {
+        // Test the difference between request Message and response ResponseMessage
+
+        // Request message (used in ChatCompletionsRequest)
+        let request_message = Message {
+            role: Role::User,
+            content: MessageContent::Text("What's the weather like?".to_string()),
+            name: Some("user123".to_string()),
+            tool_calls: None,
+            tool_call_id: None,
+        };
+
+        let request_json = serde_json::to_value(&request_message).unwrap();
+        let request_obj = request_json.as_object().unwrap();
+
+        // Request messages have complex content (MessageContent enum)
+        assert_eq!(request_obj["role"], "user");
+        assert_eq!(request_obj["content"], "What's the weather like?");
+        assert_eq!(request_obj["name"], "user123");
+        assert!(!request_obj.contains_key("refusal"));
+        assert!(!request_obj.contains_key("annotations"));
+        assert!(!request_obj.contains_key("audio"));
+
+        // Response message (used in ChatCompletionsResponse)
+        let response_message = ResponseMessage {
+            role: Role::Assistant,
+            content: Some("It's sunny and 75°F in San Francisco.".to_string()),
+            refusal: None,
+            annotations: Some(vec![serde_json::json!({"type": "web_search", "query": "San Francisco weather"})]),
+            audio: None,
+            function_call: None,
+            tool_calls: Some(vec![ToolCall {
+                id: "call_456".to_string(),
+                call_type: "function".to_string(),
+                function: FunctionCall {
+                    name: "get_weather".to_string(),
+                    arguments: r#"{"location": "San Francisco"}"#.to_string(),
+                },
+            }]),
+        };
+
+        let response_json = serde_json::to_value(&response_message).unwrap();
+        let response_obj = response_json.as_object().unwrap();
+
+        // Response messages have simple string content and additional fields
+        assert_eq!(response_obj["role"], "assistant");
+        assert_eq!(response_obj["content"], "It's sunny and 75°F in San Francisco.");
+        assert!(response_obj.contains_key("annotations"));
+        assert!(response_obj.contains_key("tool_calls"));
+        assert!(!response_obj.contains_key("name")); // Response messages don't have names
+        assert!(!response_obj.contains_key("tool_call_id")); // Only for tool messages in requests
+
+        // Test conversion from ResponseMessage to Message
+        let converted_message = response_message.to_message();
+        assert_eq!(converted_message.role, Role::Assistant);
+        if let MessageContent::Text(text) = converted_message.content {
+            assert_eq!(text, "It's sunny and 75°F in San Francisco.");
+        } else {
+            panic!("Expected text content");
+        }
+        assert_eq!(converted_message.tool_calls, response_message.tool_calls);
+
+        // Test response message with refusal
+        let refusal_message = ResponseMessage {
+            role: Role::Assistant,
+            content: None,
+            refusal: Some("I cannot provide information about that topic.".to_string()),
+            annotations: None,
+            audio: None,
+            function_call: None,
+            tool_calls: None,
+        };
+
+        let refusal_json = serde_json::to_value(&refusal_message).unwrap();
+        let refusal_obj = refusal_json.as_object().unwrap();
+
+        assert_eq!(refusal_obj["role"], "assistant");
+        // Content is None and gets skipped by #[skip_serializing_none]
+        assert!(!refusal_obj.contains_key("content"));
+        // Check if refusal field exists and has the expected value
+        if let Some(refusal_value) = refusal_obj.get("refusal") {
+            assert_eq!(refusal_value, "I cannot provide information about that topic.");
+        } else {
+            panic!("Expected refusal field to be present");
+        }
+    }
+
+    #[test]
+    fn test_streaming_types_completeness() {
+        // Test that streaming types include all fields from OpenAI API spec
+
+        // Test ChatCompletionsStreamResponse with all fields
+        let stream_response = ChatCompletionsStreamResponse {
+            id: "chatcmpl-stream-456".to_string(),
+            object: "chat.completion.chunk".to_string(),
+            created: 1234567890,
+            model: "gpt-4".to_string(),
+            choices: vec![StreamChoice {
+                index: 0,
+                delta: MessageDelta {
+                    role: Some(Role::Assistant),
+                    content: Some("Hello there!".to_string()),
+                    refusal: None,
+                    function_call: Some(FunctionCall {
+                        name: "get_weather".to_string(),
+                        arguments: r#"{"location": "NYC"}"#.to_string(),
+                    }),
+                    tool_calls: Some(vec![ToolCallDelta {
+                        index: 0,
+                        id: Some("call_789".to_string()),
+                        call_type: Some("function".to_string()),
+                        function: Some(FunctionCallDelta {
+                            name: Some("get_temperature".to_string()),
+                            arguments: Some(r#"{"city": "Boston"}"#.to_string()),
+                        }),
+                    }]),
+                },
+                finish_reason: Some(FinishReason::ToolCalls),
+                logprobs: None,
+            }],
+            usage: Some(Usage {
+                prompt_tokens: 25,
+                completion_tokens: 15,
+                total_tokens: 40,
+                prompt_tokens_details: None,
+                completion_tokens_details: None,
+            }),
+            system_fingerprint: Some("fp_12345".to_string()),
+            service_tier: Some("default".to_string()),
+        };
+
+        let json = serde_json::to_value(&stream_response).unwrap();
+        let obj = json.as_object().unwrap();
+
+        // Test all top-level fields are present
+        assert_eq!(obj["id"], "chatcmpl-stream-456");
+        assert_eq!(obj["object"], "chat.completion.chunk");
+        assert_eq!(obj["created"], 1234567890);
+        assert_eq!(obj["model"], "gpt-4");
+        assert_eq!(obj["system_fingerprint"], "fp_12345");
+        assert_eq!(obj["service_tier"], "default");
+        assert!(obj.contains_key("choices"));
+        assert!(obj.contains_key("usage"));
+
+        // Test choice structure
+        let choices = obj["choices"].as_array().unwrap();
+        assert_eq!(choices.len(), 1);
+        let choice = &choices[0];
+        assert_eq!(choice["index"], 0);
+        assert_eq!(choice["finish_reason"], "tool_calls");
+
+        // Test delta structure with all fields
+        let delta = &choice["delta"];
+        assert_eq!(delta["role"], "assistant");
+        assert_eq!(delta["content"], "Hello there!");
+        assert!(delta.as_object().unwrap().contains_key("function_call"));
+        assert!(delta.as_object().unwrap().contains_key("tool_calls"));
+        // refusal is None so should be skipped
+        assert!(!delta.as_object().unwrap().contains_key("refusal"));
+
+        // Test tool call delta structure
+        let tool_calls = delta["tool_calls"].as_array().unwrap();
+        assert_eq!(tool_calls.len(), 1);
+        let tool_call = &tool_calls[0];
+        assert_eq!(tool_call["index"], 0);
+        assert_eq!(tool_call["id"], "call_789");
+        assert_eq!(tool_call["type"], "function");
+
+        let function = &tool_call["function"];
+        assert_eq!(function["name"], "get_temperature");
+        assert_eq!(function["arguments"], r#"{"city": "Boston"}"#);
+
+        // Test minimal streaming response (like final chunk)
+        let minimal_response = ChatCompletionsStreamResponse {
+            id: "chatcmpl-stream-456".to_string(),
+            object: "chat.completion.chunk".to_string(),
+            created: 1234567890,
+            model: "gpt-4".to_string(),
+            choices: vec![], // Can be empty for final chunk with usage
+            usage: Some(Usage {
+                prompt_tokens: 25,
+                completion_tokens: 15,
+                total_tokens: 40,
+                prompt_tokens_details: None,
+                completion_tokens_details: None,
+            }),
+            system_fingerprint: None,
+            service_tier: None,
+        };
+
+        let minimal_json = serde_json::to_value(&minimal_response).unwrap();
+        let minimal_obj = minimal_json.as_object().unwrap();
+
+        // Empty choices array should be present
+        assert_eq!(minimal_obj["choices"].as_array().unwrap().len(), 0);
+        assert!(minimal_obj.contains_key("usage"));
+        // None fields should be skipped
+        assert!(!minimal_obj.contains_key("system_fingerprint"));
+        assert!(!minimal_obj.contains_key("service_tier"));
+
+        // Test delta with refusal
+        let refusal_delta = MessageDelta {
+            role: Some(Role::Assistant),
+            content: None,
+            refusal: Some("I can't help with that request.".to_string()),
+            function_call: None,
+            tool_calls: None,
+        };
+
+        let refusal_json = serde_json::to_value(&refusal_delta).unwrap();
+        let refusal_obj = refusal_json.as_object().unwrap();
+
+        assert_eq!(refusal_obj["role"], "assistant");
+        assert_eq!(refusal_obj["refusal"], "I can't help with that request.");
+        // None fields should be skipped
+        assert!(!refusal_obj.contains_key("content"));
+        assert!(!refusal_obj.contains_key("function_call"));
+        assert!(!refusal_obj.contains_key("tool_calls"));
+    }
+}