Add grok (#9)

* feat: add Grok (xAI) client implementation

- Implement GrokClient with OpenAI-compatible API interface
- Add Grok model enum with latest model variants
- Enable configurable timeouts matching other clients
- Update feature flags to include grok by default
- Add documentation and examples for Grok client usage

* docs: add model list maintenance guidelines

- Add comprehensive documentation for model list updates
- Include official documentation links for OpenAI, Anthropic, and xAI
- Update Grok models with latest model variants (Grok-3, Grok-4)
- Add validation test for Grok client implementation
- Update model enum documentation with reference links

* docs: update model lists with latest versions

- Update OpenAI models with GPT-5 and O1 series
- Update Anthropic models with Claude 4 and 4.5 series
- Add comprehensive model maintenance guidelines
- Update examples and tests to use latest models

* feat: add markdown code block JSON extraction

- Add helper function to extract JSON from markdown code blocks
- Apply extraction before JSON parsing in Anthropic client
- Improve error messages with extracted content
- Maintain fallback to raw content when no code blocks found

Author: clifton

CLAUDE.md

@@ -37,4 +37,55 @@
 - Never use JSON serialized strings for attribute values (e.g., do not use `examples = r#"["value1"]"#`)
 - Parse container attributes individually without relying on JSON parsing
 - Support multiple attribute specification styles that feel natural in Rust
-- For multi-value attributes, support both parentheses and array syntax
+- For multi-value attributes, support both parentheses and array syntax
+
+## Model List Maintenance Guidelines
+
+**CRITICAL**: Model lists must be kept up-to-date with provider releases. When adding new providers or updating existing ones, always refer to the official documentation sources below:
+
+### Official Model Documentation Sources
+
+**OpenAI:**
+- Model Documentation: https://platform.openai.com/docs/models
+- Models API Endpoint: https://platform.openai.com/docs/api-reference/models/list
+
+**Anthropic:**
+- All Models Overview: https://docs.anthropic.com/en/docs/about-claude/models/all-models
+- Models List API: https://docs.anthropic.com/en/api/models-list
+
+**xAI (Grok):**
+- Models Documentation: https://docs.x.ai/docs/models
+
+### Update Process
+
+**CRITICAL RULES:**
+1. **ALWAYS use API endpoints to get current models** - Never guess or rely on web search. Use the official API endpoints:
+   - **OpenAI**: `GET https://api.openai.com/v1/models` (requires `Authorization: Bearer $OPENAI_API_KEY`)
+   - **Anthropic**: `GET https://api.anthropic.com/v1/models` (requires `x-api-key: $ANTHROPIC_API_KEY` and `anthropic-version: 2023-06-01`)
+   - **xAI (Grok)**: Check `https://docs.x.ai/docs/models` or use their API if available
+2. **NEVER guess model identifiers** - Always get exact model names from API responses or official documentation
+3. **NEVER rely on web search results** - Web search often returns outdated, incorrect, or speculative information
+4. **ALWAYS use exact API identifiers** - Model identifiers must match exactly what the API expects (e.g., `gpt-5-chat-latest`, `claude-sonnet-4-5-20250929`, `grok-4-0709`)
+5. **If API key is not available**: Ask the user to provide the exact model identifiers from the API endpoint, rather than guessing
+6. **Verify date stamps make sense** - If version X.Y is newer than X.Z, its date stamp should be later (e.g., Claude 3.7 date should be after Claude 3.5 date)
+7. **Check for new major versions** - Don't assume only minor version updates; check for major version releases (e.g., Claude 4, GPT-5)
+8. **Verify model name format** - Different providers may use different naming conventions (e.g., `claude-sonnet-4-20250514` vs `claude-4-sonnet-20250514`)
+9. **Filter for chat completion models** - Only include models suitable for chat completions (exclude specialized models like search-api, codex, audio, etc. unless specifically needed)
+
+**Steps:**
+1. **Get current models from API**: Use `curl` or API calls to fetch the latest model list from the provider's `/v1/models` endpoint
+2. **Parse API response**: Extract model `id` fields from the JSON response
+3. **Filter appropriate models**: For chat completions, include main chat models and exclude specialized variants unless needed
+4. **Verify model identifiers**: Ensure date stamps and version numbers are correct (e.g., Claude 3.7 should have a date later than Claude 3.5)
+5. **When updating**: Add new models to the appropriate enum (`Model`, `AnthropicModel`, `GrokModel`) in the respective backend files, ordered newest to oldest
+6. **Remove deprecated models**: Check API response for models that are no longer available and remove them
+7. **Default models**: Update default model selection to use the latest recommended model when appropriate
+8. **Documentation**: Update rustdoc comments to reference the official documentation links
+9. **Testing**: Ensure new models work correctly with integration tests
+
+### Periodic Review Schedule
+
+- Review model lists quarterly or when new models are announced
+- Check for deprecated models and remove or mark them as deprecated
+- Update default model selections to use the latest recommended models
+- Verify all model identifiers match current API documentation

Cargo.toml

@@ -37,9 +37,10 @@ chrono = "0.4" # For date/time validation in examples
 
 # Feature flags
 [features]
-default = ["openai", "anthropic", "derive", "logging"]
+default = ["openai", "anthropic", "grok", "derive", "logging"]
 openai = ["reqwest", "tokio"]
 anthropic = ["reqwest", "tokio"]
+grok = ["reqwest", "tokio"]
 derive = ["rstructor_derive"]
 logging = ["tracing-subscriber", "tracing-futures"]
 

README.md

@@ -16,7 +16,7 @@ Think of it as the Rust equivalent of [Instructor + Pydantic](https://github.com
 - **📝 Type-Safe Definitions**: Define data models as standard Rust structs/enums with attributes
 - **🔄 JSON Schema Generation**: Auto-generates JSON Schema from your Rust types
 - **✅ Built-in Validation**: Type checking plus custom business rule validation
-- **🔌 Multiple LLM Providers**: Support for OpenAI and Anthropic, with an extensible backend system
+- **🔌 Multiple LLM Providers**: Support for OpenAI, Anthropic, and Grok (xAI), with an extensible backend system
 - **🧩 Complex Data Structures**: Support for nested objects, arrays, optional fields, and deeply nested enums
 - **🧠 Schema Fidelity**: Heuristic-free JSON Schema generation that preserves nested struct and enum detail
 - **🔍 Custom Validation Rules**: Add domain-specific validation with automatically detected `validate` methods
@@ -471,16 +471,24 @@ let openai_client = OpenAIClient::new(openai_api_key)?
 
 // Using Anthropic
 let anthropic_client = AnthropicClient::new(anthropic_api_key)?
-    .model(AnthropicModel::Claude3Sonnet)
+    .model(AnthropicModel::ClaudeSonnet4)
     .temperature(0.0)
     .max_tokens(2000)
     .with_timeout(Duration::from_secs(60))  // Optional: set 60 second timeout
     .build();
+
+// Using Grok (xAI) - automatically uses XAI_API_KEY env var if empty string provided
+let grok_client = GrokClient::new("")?  // Uses XAI_API_KEY env var
+    .model(GrokModel::Grok4)
+    .temperature(0.0)
+    .max_tokens(1500)
+    .with_timeout(Duration::from_secs(60))  // Optional: set 60 second timeout
+    .build();
 ```
 
 ### Configuring Request Timeouts
 
-Both `OpenAIClient` and `AnthropicClient` support configurable timeouts for HTTP requests using the builder pattern:
+All clients (`OpenAIClient`, `AnthropicClient`, and `GrokClient`) support configurable timeouts for HTTP requests using the builder pattern:
 
 ```rust
 use std::time::Duration;
@@ -668,12 +676,13 @@ Configure RStructor with feature flags:
 
 ```toml
 [dependencies]
-rstructor = { version = "0.1.0", features = ["openai", "anthropic"] }
+rstructor = { version = "0.1.0", features = ["openai", "anthropic", "grok"] }
 ```
 
 Available features:
 - `openai`: Include the OpenAI client
 - `anthropic`: Include the Anthropic client
+- `grok`: Include the Grok (xAI) client
 - `derive`: Include the derive macro (enabled by default)
 - `logging`: Enable tracing integration with default subscriber
 

examples/event_planner.rs

@@ -317,7 +317,7 @@ async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
         println!("\nProcessing your request with Anthropic...\n");
 
         let client = AnthropicClient::new(api_key)?
-            .model(AnthropicModel::Claude3Sonnet)
+            .model(AnthropicModel::ClaudeSonnet4)
             .temperature(0.3)
             .build();
 

examples/nested_objects_example.rs

@@ -204,7 +204,7 @@ CRITICAL REQUIREMENTS - ALL FIELDS ARE REQUIRED:
         println!("Using Anthropic to generate recipe...");
 
         let client = AnthropicClient::new(api_key)?
-            .model(AnthropicModel::Claude3Sonnet) // Using more capable model for complex structure
+            .model(AnthropicModel::ClaudeSonnet4) // Using more capable model for complex structure
             .temperature(0.2)
             .build();
 

examples/news_article_categorizer.rs

@@ -146,7 +146,7 @@ async fn analyze_article(
         println!("Using Anthropic for article analysis...");
 
         let client = AnthropicClient::new(api_key)?
-            .model(AnthropicModel::Claude3Sonnet)
+            .model(AnthropicModel::ClaudeSonnet4)
             .temperature(0.0)
             .build();
 

examples/recipe_extractor.rs

@@ -190,7 +190,7 @@ async fn get_recipe_from_anthropic(recipe_name: &str) -> rstructor::Result<Recip
 
     // Create Anthropic client
     let client = AnthropicClient::new(api_key)?
-        .model(AnthropicModel::Claude35Sonnet) // Use Claude 3.5 Sonnet for better recipes
+        .model(AnthropicModel::ClaudeSonnet45) // Use Claude Sonnet 4.5 for better recipes
         .temperature(0.1) // Lower temperature for more consistent results
         .build();
 

src/backend/anthropic.rs

@@ -8,22 +8,65 @@ use crate::backend::LLMClient;
 use crate::error::{RStructorError, Result};
 use crate::model::Instructor;
 
+/// Extract JSON from markdown code blocks if present, otherwise return the content as-is
+fn extract_json_from_markdown(content: &str) -> String {
+    // Check if content is wrapped in markdown code blocks
+    let trimmed = content.trim();
+
+    // Match ```json ... ``` or ``` ... ```
+    if trimmed.starts_with("```") {
+        // Find the first newline after ```
+        if let Some(start_idx) = trimmed.find('\n') {
+            let after_start = &trimmed[start_idx + 1..];
+            // Find the closing ```
+            if let Some(end_idx) = after_start.rfind("```") {
+                return after_start[..end_idx].trim().to_string();
+            }
+        }
+    }
+
+    // If no markdown code blocks found, return as-is
+    trimmed.to_string()
+}
+
 /// Anthropic models available for completion
+///
+/// For the latest available models and their identifiers, check the
+/// [Anthropic Models Documentation](https://docs.anthropic.com/en/docs/about-claude/models/all-models).
 #[derive(Debug, Clone)]
 pub enum AnthropicModel {
+    /// Claude Haiku 4.5 (latest fastest model)
+    ClaudeHaiku45,
+    /// Claude Sonnet 4.5 (latest balanced model)
+    ClaudeSonnet45,
+    /// Claude Opus 4.1 (enhanced reasoning capabilities)
+    ClaudeOpus41,
+    /// Claude Opus 4 (high-intelligence model)
+    ClaudeOpus4,
+    /// Claude Sonnet 4 (balanced performance model)
+    ClaudeSonnet4,
+    /// Claude Sonnet 3.7 (enhanced reasoning)
+    Claude37Sonnet,
+    /// Claude Haiku 3.5 (fast, cost-effective model)
+    Claude35Haiku,
+    /// Claude Haiku 3 (fast, cost-effective model)
     Claude3Haiku,
-    Claude3Sonnet,
+    /// Claude Opus 3 (most capable model for complex tasks)
     Claude3Opus,
-    Claude35Sonnet, // Added Claude 3.5 Sonnet
 }
 
 impl AnthropicModel {
     pub fn as_str(&self) -> &'static str {
         match self {
+            AnthropicModel::ClaudeHaiku45 => "claude-haiku-4-5-20251001",
+            AnthropicModel::ClaudeSonnet45 => "claude-sonnet-4-5-20250929",
+            AnthropicModel::ClaudeOpus41 => "claude-opus-4-1-20250805",
+            AnthropicModel::ClaudeOpus4 => "claude-opus-4-20250514",
+            AnthropicModel::ClaudeSonnet4 => "claude-sonnet-4-20250514",
+            AnthropicModel::Claude37Sonnet => "claude-3-7-sonnet-20250219",
+            AnthropicModel::Claude35Haiku => "claude-3-5-haiku-20241022",
             AnthropicModel::Claude3Haiku => "claude-3-haiku-20240307",
-            AnthropicModel::Claude3Sonnet => "claude-3-sonnet-20240229",
             AnthropicModel::Claude3Opus => "claude-3-opus-20240229",
-            AnthropicModel::Claude35Sonnet => "claude-3-5-sonnet-20240620", // Claude 3.5 Sonnet model ID
         }
     }
 }
@@ -80,15 +123,15 @@ struct CompletionResponse {
 
 impl AnthropicClient {
     /// Create a new Anthropic client with default configuration
-    #[instrument(name = "anthropic_client_new", skip(api_key), fields(model = ?AnthropicModel::Claude35Sonnet))]
+    #[instrument(name = "anthropic_client_new", skip(api_key), fields(model = ?AnthropicModel::ClaudeSonnet45))]
     pub fn new(api_key: impl Into<String>) -> Result<Self> {
         let api_key = api_key.into();
         info!("Creating new Anthropic client");
         trace!("API key length: {}", api_key.len());
 
         let config = AnthropicConfig {
             api_key,
-            model: AnthropicModel::Claude35Sonnet, // Default to Claude 3.5 Sonnet
+            model: AnthropicModel::ClaudeSonnet45, // Default to Claude Sonnet 4.5 (latest flagship)
             temperature: 0.0,
             max_tokens: None,
             timeout: None, // Default: no timeout (uses reqwest's default)
@@ -306,17 +349,19 @@ impl LLMClient for AnthropicClient {
         };
 
         // Try to parse the content as JSON
-        trace!(json = %content, "Attempting to parse response as JSON");
-        let result: T = match serde_json::from_str(content) {
+        // First, try to extract JSON from markdown code blocks if present
+        let json_content = extract_json_from_markdown(content);
+        trace!(json = %json_content, "Attempting to parse response as JSON");
+        let result: T = match serde_json::from_str(&json_content) {
             Ok(parsed) => parsed,
             Err(e) => {
                 let error_msg = format!(
                     "Failed to parse response as JSON: {}\nPartial JSON: {}",
-                    e, content
+                    e, json_content
                 );
                 error!(
                     error = %e,
-                    content = %content,
+                    content = %json_content,
                     "JSON parsing error"
                 );
                 return Err(RStructorError::ValidationError(error_msg));

src/backend/client.rs

@@ -16,6 +16,7 @@ use crate::model::Instructor;
 /// The library includes implementations for popular LLM providers:
 /// - `OpenAIClient` for OpenAI's GPT models (gpt-3.5-turbo, gpt-4, etc.)
 /// - `AnthropicClient` for Anthropic's Claude models
+/// - `GrokClient` for xAI's Grok models (uses `XAI_API_KEY` env var by default)
 ///
 /// # Examples
 ///