OpenAI Rust Responses by SShift

🛠️ v0.4.3 Update: Code Quality Improvements - Fixed all Clippy warnings, added #[must_use] attributes, and improved code quality. Zero breaking changes - all improvements are internal enhancements. 🌊 v0.4.2 Update: Streaming Enhancements - Enhanced ResponseCreated event support with response ID tracking, improved streaming tests, and comprehensive helper methods. Full event type coverage for production-ready streaming. 🔐 v0.4.1 Update: MCP Authorization - Added with_bearer_token() convenience method for secure MCP server connections. Simplifies Bearer token authentication with automatic header formatting. Fully backward compatible. 🔌 v0.4.0 Update: Unified Tool Management - New ToolRegistry for seamlessly combining local Rust tools with remote MCP tools. Priority routing automatically handles tool dispatch. Added LocalTool trait. Fully backward compatible - all changes are additive. 🚀 v0.3.0 Update: GPT‑5 family support (flagship, mini, nano), new verbosity control, reasoning effort tuning for GPT‑5, structured/free‑form function improvements, and an expanded example. Note: source‑level break only for users constructing public structs with literals or exhaustively matching Model. 🛡️ v0.2.5 Update: Advanced Container Recovery System - Revolutionary error handling! SDK now automatically handles container expiration with configurable recovery policies. Choose from Default (auto-retry), Conservative (manual control), or Aggressive (maximum resilience) strategies. Zero breaking changes! 🎨 v0.2.4 Update: Image-Guided Generation - Revolutionary new feature! Use input images to guide image generation with the GPT Image 1 model. Create style transfers, combine multiple images into logos, and generate artistic interpretations. See the comprehensive new example! 🧑‍💻 v0.2.3 Update: Code Interpreter tool support! Run Python code in a secure container and get results directly from the model. See the new example and docs. 🔥 v0.2.0 Update: Major update to image generation! The SDK now supports the official built-in image_generation tool, replacing the previous function-based workaround. This is a breaking change. 🎉 v0.2.1 Update: Vision input landed! Supply images with input_image_url(...) and get descriptions from GPT-4o. 🚀 v0.2.2 Update: Multi-image vision! Compare or analyse multiple pictures with input_image_urls or push_image_url.

A comprehensive, async Rust SDK for the OpenAI Responses API with advanced reasoning capabilities, background processing, enhanced models, production-ready streaming, working image generation, and revolutionary image-guided generation.

✨ Features

🛡️ Advanced Container Recovery: Automatic handling of expired containers with configurable recovery policies
🎨 Image-Guided Generation: Use input images to guide image generation - style transfer, logo creation, artistic interpretation
🔄 Conversation Continuity: Use response IDs to maintain conversation context with smart context pruning
🌊 Production-Ready Streaming: HTTP chunked responses with proper parsing and real-time text generation
📁 File Operations: Upload, download, and manage files with full MIME support
🔍 Vector Stores: Semantic search and knowledge retrieval with attribute filtering
🛠️ Advanced Tools: Web search, file search, custom functions, built-in image generation, and MCP integration
🎨 Image Generation: Working implementation via direct API and the new built-in tool
📸 Image Input (Vision): Describe user-supplied images with GPT-4o Vision
🧠 Reasoning Parameters: Low/high effort reasoning with auto/concise/detailed summaries; GPT‑5 supports explicit reasoning effort
🔄 Background Processing: Async operation handling for long-running tasks
🎯 Enhanced Models: Support for GPT‑5 family, o3, o4-mini, all o1 variants, and GPT-4o family
⚡ Async/Await: Built on tokio and reqwest for high performance
🔒 Type Safety: Comprehensive error handling, type-safe includes, and compile-time validation
📊 Full API Parity: 85% coverage of OpenAI May 2025 specification with 100% backward compatibility
📚 Rich Documentation: Extensive examples and API documentation
🧑‍💻 Code Interpreter Tool: Run Python code and get results directly from the model

🧠 GPT‑5 at a glance (new)

use open_ai_rust_responses_by_sshift::{Client, Request, Model, ReasoningEffort, Verbosity};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::from_env()?;

    // Standard generation (no reasoning params required)
    let standard = Request::builder()
        .model(Model::GPT5Mini)
        .input("Summarize this paragraph in 2 bullet points.")
        .verbosity(Verbosity::Low) // Optional (GPT‑5 only): Low|Medium|High
        .build();

    // Reasoning-style control (maps to reasoning.effort on the wire)
    let reasoning = Request::builder()
        .model(Model::GPT5)
        .input("Plan a multi-step data migration with trade-offs.")
        .reasoning_effort(ReasoningEffort::High) // Minimal|Medium|High
        .build();

    let _ = client.responses.create(standard).await?;
    let _ = client.responses.create(reasoning).await?;
    Ok(())
}

See examples/gpt5_demo.rs for a complete, runnable showcase with function calling and usage reporting.

🆕 Advanced Capabilities

This SDK includes cutting-edge features with full API parity:

🔌 Model Context Protocol (MCP) Support (NEW in v0.3.4)

Connect to any remote MCP server to extend your AI's capabilities with external tools and resources.

use open_ai_rust_responses_by_sshift::mcp::{McpClient, transport::HttpTransport};

// Connect to a remote MCP server via HTTP (without authentication)
let transport = HttpTransport::new("http://localhost:8000/mcp");
let client = McpClient::new(Box::new(transport));
client.initialize().await?;

// Or connect with Bearer token authentication
let transport = HttpTransport::new("http://localhost:8000/mcp")
    .with_bearer_token("your-api-token-here")?;
let client = McpClient::new(Box::new(transport));
client.initialize().await?;

// Or add custom headers
let transport = HttpTransport::new("http://localhost:8000/mcp")
    .with_header("X-Custom-Header", "value")?
    .with_bearer_token("your-api-token")?;

// HttpTransport implements Clone, so you can clone it for reuse
let transport = HttpTransport::new("http://localhost:8000/mcp")
    .with_bearer_token("your-api-token")?;
let cloned_transport = transport.clone(); // Clone preserves headers and configuration

// List available tools
let tools = client.list_tools().await?;

// Call a tool
let result = client.call_tool("read_file", json!({ "path": "/path/to/file.txt" })).await?;

⚡ Realtime API (WebSockets) (NEW in v0.3.4)

Interact with OpenAI's Realtime API for low-latency, multimodal experiences.

use open_ai_rust_responses_by_sshift::realtime::RealtimeClient;

// Connect to the Realtime API
let mut client = RealtimeClient::connect("sk-...", "gpt-4o-realtime-preview").await?;

// Send an event
client.send_event(json!({
    "type": "response.create",
    "response": {
        "modalities": ["text"],
        "instructions": "Hello, world!"
    }
})).await?;

// Receive events
while let Some(event) = client.receive_event().await? {
    println!("Received event: {:?}", event);
}

🛡️ Advanced Container Recovery System (NEW in v0.2.5) 🔥

Revolutionary error handling: SDK automatically detects and recovers from expired containers without breaking user flow!

🔁 Fine-tune retry behavior with RetryScope and inspect the active policy via client.responses.recovery_policy().
⚙️ Use Client::from_env_with_recovery_policy() to load optional overrides (OAI_RECOVERY_MAX_RETRIES, OAI_RECOVERY_AUTO_RETRY, OAI_RECOVERY_AUTO_PRUNE, OAI_RECOVERY_LOG, OAI_RECOVERY_SCOPE). Leaving them unset preserves legacy defaults.
🚫 Call create_no_recovery when you need the very first error without any retry loop.
📚 Read the full documentation »

use open_ai_rust_responses_by_sshift::{Client, RecoveryPolicy, Request, Tool, Container};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Choose your recovery strategy
    let policy = RecoveryPolicy::default()  // Auto-retry: 1 attempt
        .with_auto_retry(true)
        .with_notify_on_reset(true)
        .with_reset_message("Your session was refreshed for optimal performance.");
    
    let client = Client::new_with_recovery(&api_key, policy)?;

    // Make requests normally - container expiration handled automatically!
    let request = Request::builder()
        .model("gpt-4o-mini")
        .input("Continue our Python session from earlier...")
        .tools(vec![Tool::code_interpreter(Some(Container::auto_type()))])
        .previous_response_id("resp_123") // May reference expired container
        .build();

    // SDK automatically handles expiration and retries with fresh context
    let response = client.responses.create(request).await?;
    println!("Success: {}", response.output_text());
    Ok(())
}

// Inspect the policy currently in use
let policy = client.responses.recovery_policy();
println!("retry scope: {}", policy.retry_scope.as_str());

Recovery Policies:

// Default: Balanced approach (recommended)
let client = Client::new(&api_key)?; // Auto-retry enabled, 1 attempt

// Conservative: Full control
let policy = RecoveryPolicy::conservative(); // No auto-retry, notifications on
let client = Client::new_with_recovery(&api_key, policy)?;

// Aggressive: Maximum resilience  
let policy = RecoveryPolicy::aggressive(); // Auto-retry enabled, 3 attempts
let client = Client::new_with_recovery(&api_key, policy)?;

Advanced Recovery Information:

// Get detailed recovery information
let response_with_recovery = client.responses.create_with_recovery(request).await?;

if response_with_recovery.had_recovery() {
    println!("Recovery performed:");
    println!("- Attempts: {}", response_with_recovery.recovery_info.retry_count);
    println!("- Successful: {}", response_with_recovery.recovery_info.successful);
    if let Some(msg) = response_with_recovery.recovery_message() {
        println!("- Message: {}", msg);
    }
}

println!("Response: {}", response_with_recovery.response.output_text());

Skip Recovery When Needed:

// Surface the first failure without retrying
let response = client.responses.create_no_recovery(request).await?;

Manual Context Pruning:

// Proactively clean expired context
let cleaned_request = client.responses.prune_expired_context_manual(request);
let response = client.responses.create(cleaned_request).await?;

Debugging Retries:

let verbose_policy = RecoveryPolicy::default()
    .with_logging(true)
    .with_max_retries(2);

let client = Client::new_with_recovery(&api_key, verbose_policy)?;

DEBUG Preparing to send attempt 1 (retry_count=0, has_last_error=false)
DEBUG handle_error_with_retry: classification=container_expired, scope=all_recoverable, retry_count=0->1, retry_after=1s, decision=Continue
DEBUG Preparing to send attempt 2 (retry_count=1, has_last_error=true)
INFO  Successfully recovered after 1 attempt(s) (classification=container_expired)

Environment Overrides:

use open_ai_rust_responses_by_sshift::{Client, RecoveryPolicy};

// Load defaults, overriding only when specific env vars are provided
let policy = RecoveryPolicy::from_env();

// OPENAI_API_KEY is still required, but recovery env vars are optional
let client = Client::from_env_with_recovery_policy()?;

Environment variables only adjust the fields you set—everything else keeps the library defaults. Supported overrides include:

OAI_RECOVERY_MAX_RETRIES (u32)
OAI_RECOVERY_AUTO_RETRY (bool)
OAI_RECOVERY_AUTO_PRUNE (bool)
OAI_RECOVERY_LOG (bool)
OAI_RECOVERY_SCOPE (all, container, or transient)

Key Benefits:

🔄 Transparent Recovery: Container expiration handled automatically
⚙️ Configurable Policies: Choose the strategy that fits your app
🔍 Detailed Feedback: Optional recovery information for monitoring
🔒 Zero Breaking Changes: All existing code works with enhanced error handling
🎯 Production Ready: Enterprise-grade error recovery with logging and callbacks

Test Container Expiration:

cargo run --example container_expiration_test

🎨 Image-Guided Generation (NEW in v0.2.4) 🔥

Revolutionary feature: Use input images to guide image generation with the GPT Image 1 model!

use open_ai_rust_responses_by_sshift::{Client, InputItem, Request, Tool, Model};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::from_env()?;

    // Example: Style transfer - transform an image into Van Gogh style
    let reference_image = "https://example.com/landscape.jpg";
    
    let request = Request::builder()
        .model(Model::GPT4o)
        .input_items(vec![
            // System message for context
            InputItem::message("system", vec![
                InputItem::content_text("You are an expert in artistic style transfer.")
            ]),
            // User message with image and instructions
            InputItem::message("user", vec![
                InputItem::content_text("Transform this landscape into Van Gogh's Starry Night style - swirling skies, bold brushstrokes, vibrant blues and yellows."),
                InputItem::content_image_with_detail(reference_image, "high")
            ])
        ])
        .tools(vec![Tool::image_generation()])
        .temperature(0.8)
        .build();

    let response = client.responses.create(request).await?;
    // Generated image is in response.output as ImageGenerationCall
    println!("Style transfer complete: {}", response.output_text());
    Ok(())
}

Multi-Image Logo Creation:

// Combine elements from multiple reference images
let request = Request::builder()
    .model(Model::GPT4o)
    .input_items(vec![
        InputItem::message("user", vec![
            InputItem::content_text("Create a modern logo combining the natural serenity from the first image with the character from the second image."),
            InputItem::content_image_with_detail(nature_image, "high"),
            InputItem::content_image_with_detail(character_image, "high")
        ])
    ])
    .tools(vec![Tool::image_generation()])
    .build();

Real-World Applications:

🎨 Style Transfer: Transform photos into artistic styles
🏷️ Logo Design: Combine multiple visual references
🎯 Product Design: Create concepts from inspiration images
✨ Creative Enhancement: Add artistic elements to existing images
🔄 Image Variations: Generate multiple interpretations

Run the comprehensive example:

cargo run --example image_guided_generation

🎨 Image Generation (Overhauled in v0.2.0)

use open_ai_rust_responses_by_sshift::{Client, ImageGenerateRequest};

// Method 1: Direct image generation via Images API
let image_request = ImageGenerateRequest::new("A serene mountain landscape")
    .with_size("1024x1024")
    .with_quality("high");
let image_response = client.images.generate(image_request).await?;
if let Some(url) = &image_response.data[0].url {
    println!("Image URL: {}", url);
}

// Method 2: AI-triggered image generation via the new built-in tool
let request = Request::builder()
    .model(Model::GPT4oMini)
    .input("Create an image of a futuristic city")
    .tools(vec![Tool::image_generation()]) // Use the new, simple tool
    .build();

// The model handles image generation and returns the data directly
let response = client.responses.create(request).await?;
// See examples/image_generation_builtin.rs for how to save the image

📸 Image Input (Vision) (Updated in v0.2.2)

use open_ai_rust_responses_by_sshift::{Client, Request, Model};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::from_env()?;

    // Public demo image
    let image_url = "https://storage.googleapis.com/sshift-gpt-bucket/ledger-app/generated-image-1746132697428.png";

    let request = Request::builder()
        .model(Model::GPT4o)            // GPT-4o or GPT-4oMini for vision
        .input_image_url(image_url)     // New helper does all the heavy lifting
        .instructions("Describe the image in detail, mentioning colours, objects, and composition.")
        .build();

    let response = client.responses.create(request).await?;
    println!("Description: {}", response.output_text());

    Ok(())
}

Run it:

cargo run --example image_input --features stream

🧑‍💻 Code Interpreter Tool (NEW in v0.2.3)

use open_ai_rust_responses_by_sshift::{Client, Request, Model, Tool};
use open_ai_rust_responses_by_sshift::types::Container;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::from_env()?;
    let request = Request::builder()
        .model(Model::GPT4o)
        .input("Calculate the 47th digit of pi using Python.")
        .tools(vec![Tool::code_interpreter(Some(Container::auto_type()))])
        .build();
    let response = client.responses.create(request).await?;
    println!("Result: {}", response.output_text());
    Ok(())
}

🧠 Reasoning Parameters

use open_ai_rust_responses_by_sshift::types::{ReasoningParams, Effort, SummarySetting};

// Optimized configuration - fast and cost-effective
let request = Request::builder()
    .model(Model::O4Mini)  // Specialized reasoning model
    .input("Solve this complex problem step by step")
    .reasoning(ReasoningParams::new()
        .with_effort(Effort::Low)              // Fast responses
        .with_summary(SummarySetting::Auto))   // Auto-generated summaries
    .max_output_tokens(2000)  // Reasoning models need more tokens
    // Note: O4Mini doesn't support temperature (built-in optimization)
    .build();

🔄 Background Processing

use open_ai_rust_responses_by_sshift::types::BackgroundHandle;

// Enable background mode for long-running tasks
let request = Request::builder()
    .model(Model::O4Mini)  // Efficient for background tasks
    .input("Perform comprehensive analysis...")
    .reasoning(ReasoningParams::new().with_effort(Effort::Low))
    .background(true)  // Returns HTTP 202 with handle for polling
    .build();

// Would return BackgroundHandle for status polling
let response = client.responses.create(request).await?;

🎯 Enhanced Model Support

// Recommended models for different use cases
Model::GPT4oMini      // Best default choice (recommended for most use cases)
Model::GPT4o          // Advanced conversations
Model::O4Mini         // Efficient reasoning tasks (2000 token default)
Model::O3             // Complex reasoning (most capable)
Model::O1             // Original reasoning model
Model::O1Mini         // Compact reasoning
Model::O1Preview      // Preview version
Model::GPT4o20241120  // Specific version
// ... and more

🔒 Type-Safe Includes

use open_ai_rust_responses_by_sshift::types::Include;

// Compile-time validated includes (API-compatible values)
let request = Request::builder()
    .model(Model::GPT4oMini)
    .input("Search and analyze")
    .include(vec![
        Include::FileSearchResults,         // file_search_call.results
        Include::WebSearchResults,          // web_search_call.results
        Include::ReasoningEncryptedContent, // reasoning.encrypted_content
    ])
    .build();

📊 Enhanced Response Fields (Phase 1 Complete)

// New response fields for comprehensive monitoring
let response = client.responses.create(request).await?;

// Status tracking
println!("Status: {}", response.status);  // "completed", "in_progress", etc.
println!("Complete: {}", response.is_complete());
println!("Has errors: {}", response.has_errors());

// Token analytics
if let Some(usage) = &response.usage {
    println!("Total tokens: {}", usage.total_tokens);
    if let Some(details) = &usage.output_tokens_details {
        println!("Reasoning tokens: {:?}", details.reasoning_tokens);
    }
}

// Parameter echoing
println!("Temperature used: {:?}", response.temperature);
println!("Max output tokens: {:?}", response.max_output_tokens);

🚀 Quick Start

30-Second Demo

Want to try it right now?

# Add to Cargo.toml
cargo add open-ai-rust-responses-by-sshift tokio --features tokio/full

# Set your API key
export OPENAI_API_KEY=sk-your-api-key

# Run the comprehensive demo
cargo run --example comprehensive_demo --features stream

Installation

Add this to your Cargo.toml:

[dependencies]
open-ai-rust-responses-by-sshift = "0.4.3"
tokio = { version = "1.0", features = ["full"] }

# Optional: Enable streaming
# open-ai-rust-responses-by-sshift = { version = "0.4.3", features = ["stream"] }

Basic Usage

use open_ai_rust_responses_by_sshift::{Client, Request, Model, Input};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create client with API key
    let client = Client::new("sk-your-api-key")?;
    
    // Or use environment variable
    let client = Client::from_env()?;
    
    // Create a simple request
    let request = Request::builder()
        .model(Model::GPT4oMini)  // Recommended default model
        .input("Hello, how are you today?")
        .temperature(0.7)
        .max_output_tokens(500)  // Optimized for completion
        .build();
    
    // Get response
    let response = client.responses.create(request).await?;
    println!("Response: {}", response.output_text());
    
    Ok(())
}

Conversation Continuity

use open_ai_rust_responses_by_sshift::{Client, Request, Model};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::from_env()?;
    
    // First message
    let request = Request::builder()
        .model(Model::GPT4oMini)  // Recommended default
        .input("My name is Alice. What's a good recipe for pasta?")
        .build();
    
    let response1 = client.responses.create(request).await?;
    println!("Chef: {}", response1.output_text());
    
    // Continue conversation with response ID
    let request2 = Request::builder()
        .model(Model::GPT4oMini)
        .input("Can you make it vegetarian?")
        .previous_response_id(response1.id())
        .build();
    
    let response2 = client.responses.create(request2).await?;
    println!("Chef: {}", response2.output_text());
    
    Ok(())
}

Image Generation Example

use open_ai_rust_responses_by_sshift::{Client, Request, Model, Tool, ImageGenerateRequest};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::from_env()?;
    
    // Method 1: Direct image generation
    let image_req = ImageGenerateRequest::new("A beautiful sunset over mountains")
        .with_size("1024x1024")
        .with_quality("high");
    
    let image_response = client.images.generate(image_req).await?;
    if let Some(url) = &image_response.data[0].url {
        println!("Generated image: {}", url);
    }
    
    // Method 2: AI-triggered image generation
    let request = Request::builder()
        .model(Model::GPT4oMini)
        .input("Create an image of a robot learning to paint")
        .tools(vec![Tool::image_generation()])  // Use the new built-in tool
        .build();
    
    let response = client.responses.create(request).await?;
    // The AI will automatically call the image generation tool
    
    Ok(())
}

Streaming Responses

Enable the stream feature:

[dependencies]
open-ai-rust-responses-by-sshift = { version = "0.4.3", features = ["stream"] }

Basic Streaming

use open_ai_rust_responses_by_sshift::{Client, Request, Model, StreamEvent};
use futures::StreamExt;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::from_env()?;
    
    let request = Request::builder()
        .model(Model::GPT4oMini)  // Excellent for streaming performance
        .input("Tell me a story about a robot.")
        .max_output_tokens(500)  // Optimized for streaming
        .build();
    
    let mut stream = client.responses.stream(request);
    
    while let Some(event) = stream.next().await {
        match event? {
            StreamEvent::TextDelta { content, .. } => {
                print!("{}", content);
            }
            StreamEvent::Done => break,
            _ => {}
        }
    }
    
    Ok(())
}

Advanced Streaming with Response ID Tracking

Track response IDs during streaming for continuation requests:

use open_ai_rust_responses_by_sshift::{Client, Request, Model, StreamEvent};
use futures::StreamExt;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::from_env()?;
    
    let request = Request::builder()
        .model(Model::GPT4oMini)
        .input("Count from 1 to 5")
        .max_output_tokens(500)
        .build();
    
    let mut stream = client.responses.stream(request);
    let mut response_id: Option<String> = None;
    
    while let Some(event) = stream.next().await {
        match event? {
            StreamEvent::ResponseCreated { id } => {
                response_id = Some(id.clone());
                println!("📝 Response ID: {id}");
            }
            StreamEvent::TextDelta { content, .. } => {
                print!("{content}");
            }
            StreamEvent::ImageProgress { url, .. } => {
                if let Some(url) = url {
                    println!("\n📸 Image: {url}");
                }
            }
            StreamEvent::ToolCallCreated { name, .. } => {
                println!("\n🔧 Tool: {name}");
            }
            StreamEvent::Done => break,
            _ => {}
        }
    }
    
    // Use response_id for continuation if needed
    if let Some(id) = response_id {
        println!("\nResponse ID: {id}");
    }
    
    Ok(())
}

Helper Methods

Use convenient helper methods for stream events:

while let Some(event) = stream.next().await {
    let event = event?;
    
    // Extract text content
    if let Some(text) = event.as_text_delta() {
        print!("{text}");
    }
    
    // Extract response ID
    if let Some(id) = event.as_response_id() {
        println!("Response ID: {id}");
    }
    
    // Extract image URL
    if let Some(url) = event.as_image_progress() {
        println!("Image: {url}");
    }
    
    // Check if done
    if event.is_done() {
        break;
    }
}

File Operations

use open_ai_rust_responses_by_sshift::Client;
use open_ai_rust_responses_by_sshift::files::FilePurpose;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::from_env()?;
    
    // Upload a file
    let file = client.files
        .upload_file("./data/document.pdf", FilePurpose::Assistants, None)
        .await?;
    
    println!("Uploaded file: {} ({})", file.filename, file.id);
    
    // List files
    let files = client.files.list(None).await?;
    println!("You have {} files", files.len());
    
    // Download file content
    let content = client.files.download(&file.id).await?;
    println!("Downloaded {} bytes", content.len());
    
    Ok(())
}

Function Calling & Tool Outputs

The Responses API handles function calling differently from the Assistants API. There is no submit_tool_outputs endpoint. Instead, tool outputs are submitted as input items in a new request:

use open_ai_rust_responses_by_sshift::{Client, Request, Model, Tool, ToolChoice};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::from_env()?;
    
    // 1. Define function tools
    let calculator_tool = Tool::function(
        "calculate",
        "Perform basic arithmetic calculations",
        json!({
            "type": "object",
            "properties": {
                "expression": {
                    "type": "string",
                    "description": "Mathematical expression to evaluate"
                }
            },
            "required": ["expression"]
        }),
    );
    
    // 2. Initial request with tools
    let request = Request::builder()
        .model(Model::GPT4oMini)  // Excellent for function calling
        .input("Calculate 15 * 7 + 23")
        .tools(vec![calculator_tool.clone()])
        .tool_choice(ToolChoice::auto())
        .build();
    
    let response = client.responses.create(request).await?;
    
    // 3. Check for tool calls and execute functions
    let tool_calls = response.tool_calls();
    if !tool_calls.is_empty() {
        let mut function_outputs = Vec::new();
        
        for tool_call in &tool_calls {
            if tool_call.name == "calculate" {
                // Execute your function here
                let result = "128"; // Calculate 15 * 7 + 23 = 128
                function_outputs.push((tool_call.call_id.clone(), result.to_string()));
            }
        }
        
        // 4. Submit tool outputs by creating a new request
        // This is the correct pattern for the Responses API
        let continuation_request = Request::builder()
            .model(Model::GPT4oMini)
            .with_function_outputs(response.id(), function_outputs)
            .tools(vec![calculator_tool])
            .build();
        
        let final_response = client.responses.create(continuation_request).await?;
        println!("Final response: {}", final_response.output_text());
    }
    
    Ok(())
}

Key Points for Function Calling:

❌ No submit_tool_outputs endpoint (unlike Assistants API)
✅ Use with_function_outputs() to submit tool results
✅ Include previous_response_id to maintain conversation context
✅ Match call_id from tool calls to function outputs
✅ Create new request for each tool output submission

See examples/function_calling.rs for a complete working example.

🔧 Configuration

Environment Variables

# Required
OPENAI_API_KEY=sk-your-api-key

# Optional
OPENAI_BASE_URL=https://api.openai.com/v1  # Custom base URL
OPENAI_ORG_ID=org-your-organization-id     # Organization ID

Custom Configuration

use open_ai_rust_responses_by_sshift::{Client, Config};

let config = Config::new("sk-your-api-key")
    .with_base_url("https://api.openai.com/v1")
    .with_organization_id("org-your-org-id");

let client = Client::new_with_config(config)?;

📊 Examples

Check out the examples/ directory for comprehensive examples:

basic.rs - Simple request/response
conversation.rs - Multi-turn conversations
streaming.rs - Real-time streaming
function_calling.rs - Function calling and tool outputs
image_generation.rs - Image generation via direct API and AI tools
image_input.rs - Image input / vision description
comprehensive_demo.rs - Complete feature showcase (files, vector stores, tools, images, etc.)

Quick Start with Full Demo

Create a .env file with your API key:

echo "OPENAI_API_KEY=sk-your-api-key-here" > .env

Run the comprehensive demo to see all features:

cargo run --example comprehensive_demo --features stream

Code Interpreter example

cargo run --example code_interpreter

This demo showcases ALL major features:

🔄 Conversation Continuity - Response ID linking with 100% success rate
🌊 Streaming Responses - Real-time text generation with optimized tokens
📁 File Operations - Upload, download, delete
🔍 Vector Stores - Semantic search and knowledge retrieval
🌐 Web Search Tool - Built-in web searching capability
📄 File Search Tool - Search through uploaded documents
⚙️ Custom Functions - Define and call custom tools
🎨 Image Generation - Direct API and AI-triggered generation
🧪 Resource Management - Proper cleanup and deletion testing

Other examples:

cargo run --example basic
cargo run --example conversation
cargo run --example streaming --features stream
cargo run --example function_calling
cargo run --example image_generation  # NEW: Image generation demo

🎯 API Coverage

This crate provides comprehensive coverage of the OpenAI Responses API:

Feature	Status	Notes
Responses	✅	Create, retrieve, cancel, delete, 21 new fields
Streaming	✅	Server-sent events with `futures::Stream`
Conversation Continuity	✅	Response ID linking, 100% success rate
Messages	✅	Message CRUD operations
Files	✅	Upload, download, list, delete
Vector Stores	✅	Create, search, manage
Tools	✅	Built-in and custom function calling
Image Generation	✅	Direct API + AI function tools (hosted tool pending)
Image Input (Vision)	✅	Describe user-supplied images
Phase 1 Spec	✅	85% May 2025 spec coverage

🚦 Error Handling

The crate uses comprehensive error types:

use open_ai_rust_responses_by_sshift::{Client, Error};

match client.responses.create(request).await {
    Ok(response) => println!("Success: {}", response.output_text()),
    Err(Error::Api { message, error_type, code }) => {
        eprintln!("API Error: {} ({})", message, error_type);
    }
    Err(Error::Http(e)) => {
        eprintln!("HTTP Error: {}", e);
    }
    Err(Error::Json(e)) => {
        eprintln!("JSON Error: {}", e);
    }
    Err(Error::Stream(msg)) => {
        eprintln!("Stream Error: {}", msg);
    }
}

⚡ Performance Tips

Reuse the client: Client is designed to be reused across requests
Connection pooling: The underlying reqwest client pools connections automatically
Streaming: Use streaming for long responses to get results faster
Async: Always use in an async context for best performance
Token optimization:
- General responses: 500 tokens (optimized from 200)
- Reasoning tasks: 2000 tokens (O4Mini)
- Streaming: 500 tokens for smooth output

🔐 Security

API keys are never logged or exposed in error messages
All requests use HTTPS by default
Supports custom certificate validation
Environment variable support for secure key management

🧪 Testing

To run the test suite:

# Run unit and integration tests
cargo test

# Run tests with all features
cargo test --all-features

# Run integration tests that need API key (streaming, actual API calls)
OPENAI_API_KEY=sk-your-key cargo test --features stream -- --ignored --nocapture

# Run the comprehensive demo (requires API key)
OPENAI_API_KEY=sk-your-key cargo run --example comprehensive_demo --features stream

Streaming Test Output

The --nocapture flag is important for streaming tests because it allows you to see the real-time streaming output. The streaming test will show:

🌊 Starting streaming test...
📖 Response: 1, 2, 3, 4, 5...
✅ Stream completed!
📊 Test results:
   Events received: 12
   Content length: 45 characters

For detailed test coverage and results, see TEST_REPORT.md.

🔧 Troubleshooting

Common API Issues (Fixed in v0.1.7)

Include Field Errors

If you see errors like "Unknown include field", use the type-safe Include enum:

// ❌ Don't use raw strings (may break with API updates)
.include_strings(vec!["file_search.results".to_string()])

// ✅ Use type-safe includes (recommended)
use open_ai_rust_responses_by_sshift::types::Include;
.include(vec![Include::FileSearchResults])  // Maps to file_search_call.results

Temperature Parameter Errors with Reasoning Models

Reasoning models (O4Mini, O3, O1 series) don't support temperature:

// ❌ This will cause API errors
let request = Request::builder()
    .model(Model::O4Mini)
    .temperature(0.7)  // Error: O4Mini doesn't support temperature
    .build();

// ✅ Correct usage for reasoning models
let request = Request::builder()
    .model(Model::O4Mini)
    .reasoning(ReasoningParams::new().with_effort(Effort::Low))
    .max_output_tokens(2000)  // Reasoning needs more tokens
    // No temperature parameter - built-in optimization
    .build();

// ✅ For general models that support temperature
let request = Request::builder()
    .model(Model::GPT4oMini)  // Recommended default
    .temperature(0.7)  // GPT4oMini supports temperature
    .max_output_tokens(500)  // Optimized for general use
    .build();

Incomplete Responses

Fixed in v0.1.7 by optimizing token allocations:

// ❌ Old defaults caused truncation (200 tokens)
// ✅ New optimized defaults:
Model::GPT4oMini => 500 tokens    // General responses
Model::O4Mini => 2000 tokens       // Reasoning tasks
// Success rate improved from 50% to 100%

Image Generation Tool Errors

Native hosted tool pending, use function tool bridge:

// ❌ This doesn't work yet (pending OpenAI release)
Tool::image_generation(None)  // Hosted tool not available

// ✅ Use the function tool bridge (working now)
Tool::image_generation_function()  // Pre-made function tool

Tests Show "ignored" - Is This an Error?

No! ✅ Tests marked ignored are intentional:

ignored = Integration tests that need API keys (expensive/slow)
Regular tests = Unit tests (fast, no API needed)
Use --ignored flag to run integration tests when you have an API key

Not Seeing Streaming Output?

Make sure to use both flags:

cargo test test_create_stream --features stream -- --ignored --nocapture
#                                               ^^^^^^^^^ ^^^^^^^^^
#                                               run ignored  show output

API Key Issues?

# Check if set
echo $OPENAI_API_KEY

# Set for current session
export OPENAI_API_KEY=sk-your-api-key

# Or use .env file
echo "OPENAI_API_KEY=sk-your-api-key" > .env

📖 Documentation

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with tokio and reqwest
Inspired by the official OpenAI Python client
Thanks to the Rust community for excellent async ecosystem
Phase 1 implementation based on OpenAI May 2025 specification

🌟 Projects Built with This SDK

This SDK powers real-world applications and services. Here are some notable projects:

Nova

Nova is a sophisticated AI-powered Telegram bot ecosystem with deep blockchain integration on Aptos. Built using this SDK, Nova provides:

AI-Powered Conversations: Access to advanced language models (GPT-5, GPT-5-mini) with tool-calling capabilities
Blockchain Integration: Native Aptos blockchain support for transparent payments and transactions
Market Data Tools: Real-time cryptocurrency prices, trending pools, DEX data, and more
Image Generation: AI-powered image creation capabilities
Community Management: Automated moderation, DAO voting, and payment systems

Nova demonstrates the SDK's capabilities in production, handling real-time AI interactions, tool calling, and streaming responses for Telegram users and groups.

Learn more about Nova →

📦 Migration notes

0.4.2 → 0.4.3

Fully backward compatible - All changes are internal code quality improvements. No API changes or breaking changes.

Code Quality Improvements

Clippy compliance: All Clippy warnings resolved
- Added #[must_use] attribute to stream() method (no functional change)
- Fixed redundant closure warning (internal optimization)
- Suppressed complexity warnings for long functions (documented with #[allow])
Zero breaking changes: All improvements are internal only
No migration required: Existing code continues to work identically

0.4.1 → 0.4.2

Fully backward compatible - All changes are additive. Existing code continues to work without modification.

New Optional Features

Enhanced Streaming Support: Improved streaming event handling and response ID tracking
- Optional: ResponseCreated events now include response IDs for continuation requests
- New helper methods: as_response_id(), is_done() for easier event processing
- Enhanced test coverage for all streaming event types
- Existing streaming code continues to work unchanged

No Breaking Changes

All existing streaming APIs remain unchanged
Existing stream event handling continues to work
No changes to request/response structures
Runtime behavior is identical

0.4.0 → 0.4.1

Fully backward compatible - All changes are additive. Existing code continues to work without modification.

New Optional Features

with_bearer_token() method: New convenience method for Bearer token authentication
- Optional: You can continue using with_header("Authorization", "Bearer <token>") as before
- To use: HttpTransport::new(url).with_bearer_token("your-token")?
- Simplifies authentication setup with automatic Bearer prefix formatting
- Can be chained with other header methods

No Breaking Changes

All existing MCP client APIs remain unchanged
Existing with_header() usage continues to work
No changes to request/response structures
Runtime behavior is identical

0.3.x → 0.4.0

Fully backward compatible - All changes are additive. Existing code continues to work without modification.

New Optional Features

ToolRegistry: New unified tool management system for combining local and MCP tools
- Optional: You can continue using McpClient directly as before
- To use: Import ToolRegistry from mcp module and register your tools
- See examples/local_and_mcp_tools.rs for usage examples
LocalTool Trait: New trait for defining local Rust-based tools
- Optional: Only needed if you want to create custom local tools
- Implement the trait and register with ToolRegistry
MCP Authorization Support: Added header support for secure MCP connections
- Optional enhancement: Use HttpTransport::with_bearer_token() for Bearer token authentication
- Use HttpTransport::with_header() for custom headers
- Methods can be chained: HttpTransport::new(url).with_bearer_token(token)?.with_header(key, value)?
- Existing HttpTransport::new() continues to work without headers

No Breaking Changes

All existing MCP client APIs remain unchanged
Existing tool definitions continue to work
No changes to request/response structures
Runtime behavior is identical

0.2.x → 0.3.0

Additive, but potentially source‑breaking in two cases:
- If you use struct literals for public types (Tool, TextConfig, ReasoningParams), add ..Default::default() or switch to the builders/constructors.
- If you exhaustively match on Model, add arms for GPT‑5 variants or a wildcard.
Runtime behavior for existing models is unchanged.

Name		Name	Last commit message	Last commit date
Latest commit History 151 Commits
.github/workflows		.github/workflows
examples		examples
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Cargo.toml		Cargo.toml
DOCUMENTATION.md		DOCUMENTATION.md
LICENSE		LICENSE
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

OpenAI Rust Responses by SShift

✨ Features

🧠 GPT‑5 at a glance (new)

🆕 Advanced Capabilities

🔌 Model Context Protocol (MCP) Support (NEW in v0.3.4)

⚡ Realtime API (WebSockets) (NEW in v0.3.4)

🛡️ Advanced Container Recovery System (NEW in v0.2.5) 🔥

🎨 Image-Guided Generation (NEW in v0.2.4) 🔥

🎨 Image Generation (Overhauled in v0.2.0)

📸 Image Input (Vision) (Updated in v0.2.2)

🧑‍💻 Code Interpreter Tool (NEW in v0.2.3)

🧠 Reasoning Parameters

🔄 Background Processing

🎯 Enhanced Model Support

🔒 Type-Safe Includes

📊 Enhanced Response Fields (Phase 1 Complete)

🚀 Quick Start

30-Second Demo

Installation

Basic Usage

Conversation Continuity

Image Generation Example

Streaming Responses

Basic Streaming

Advanced Streaming with Response ID Tracking

Helper Methods

File Operations

Function Calling & Tool Outputs

🔧 Configuration

Environment Variables

Custom Configuration

📊 Examples

Quick Start with Full Demo

Code Interpreter example

🎯 API Coverage

🚦 Error Handling

⚡ Performance Tips

🔐 Security

🧪 Testing

Streaming Test Output

🔧 Troubleshooting

Common API Issues (Fixed in v0.1.7)

Include Field Errors

Temperature Parameter Errors with Reasoning Models

Incomplete Responses

Image Generation Tool Errors

Tests Show "ignored" - Is This an Error?

Not Seeing Streaming Output?

API Key Issues?

📖 Documentation

🤝 Contributing

📄 License

🙏 Acknowledgments

🌟 Projects Built with This SDK

Nova

📦 Migration notes

0.4.2 → 0.4.3

Code Quality Improvements

0.4.1 → 0.4.2

New Optional Features

No Breaking Changes

0.4.0 → 0.4.1

New Optional Features

No Breaking Changes

0.3.x → 0.4.0

New Optional Features

No Breaking Changes

0.2.x → 0.3.0

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages