Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
openai-ergonomic
Ergonomic Rust wrapper for the OpenAI API, providing type-safe builder patterns and async/await support.
Features
- Type-safe - full type safety with fluent builder patterns
- Async/await - built on
tokioandreqwestfor modern async Rust - Streaming - first-class support for streaming responses
- Comprehensive - covers all
OpenAIAPI endpoints - Azure
OpenAI- seamless support for AzureOpenAIdeployments - Well-tested - extensive test coverage with mock support
- Well-documented - rich documentation with examples
Status
Status: under construction. The crate is still in active development and not yet ready for production use.
Quick Start
Add openai-ergonomic to your Cargo.toml:
[]
= "0.6"
= { = "1.0", = ["full"] }
Published version 0.6 uses openai-client-base 0.15.0. The 0.7 development line
targets openai-client-base 0.16.0. Both require Rust 1.88 or newer. Generated
request and response types follow their matching client release. Image generation
and editing require an explicit .model(...); choose the model before building
or sending those requests. See the 0.7 migration guide for
the generated request field changes.
Upgrading to 0.7
The generated request structs now use nested options for fields that distinguish
an omitted JSON property from an explicit null. Set values with two Somes,
use Some(None) for null, and leave fields at None to omit them. Read values
with .flatten(). Ergonomic builders generally omit unset optional fields and
preserve explicit values; RunBuilder defaults to sending stream: false.
use CreateCompletionRequest;
let mut request = new;
request.stream = Some;
request.stop = Some;
request.n = None;
let max_tokens: = request.max_tokens.flatten;
let json = to_value.unwrap;
assert_eq!;
assert!;
assert!;
Basic Usage
Set OPENAI_API_KEY before running this snippet. Documentation tests compile it
without reading credentials or making API calls.
use Client;
async
Langfuse Setup
The Langfuse integration (interceptor, exporter and context) lives behind the otel
cargo feature, which is enabled by default. The interceptor needs an OpenTelemetry tracer
and a Langfuse exporter:
= "0.7"
= { = "1", = ["full"] }
= { = "0.33.1", = ["trace"] }
= { = "0.33.1", = ["rt-tokio", "trace", "experimental_trace_batch_span_processor_with_async_runtime"] }
The README's no_run doctest checks the same Rust code against the current crate
source without credentials or a live service.
At runtime, set OPENAI_API_KEY, LANGFUSE_PUBLIC_KEY, and
LANGFUSE_SECRET_KEY. Optionally set LANGFUSE_HOST for a self-hosted instance.
This setup is compiled as a no_run doctest, so testing needs no credentials or
live services.
#
#
See the Langfuse integration guide for configuration and observability details.
Streaming Example
use Client;
use StreamExt;
async
Custom HTTP Client with Retry Logic
You can provide your own reqwest::Client with custom retry, timeout, and middleware configuration.
Note: When using a custom HTTP client, you must configure the timeout on the reqwest::Client itself:
use ;
use ClientBuilder;
use ;
use Duration;
async
Azure OpenAI Support
The crate seamlessly supports Azure OpenAI deployments. Azure-specific configuration can be provided through environment variables or programmatically.
Using Environment Variables
# Optional, defaults to 2024-02-01
use Client;
async
Manual Configuration
use ;
async
Note: The library automatically handles the differences between Azure OpenAI and standard OpenAI (authentication, URL paths, API versioning). You use the same API regardless of the provider.
Documentation
- Getting Started Guide
- Architecture Overview
- API Coverage Status - See what APIs are available
- Examples Index - Browse all examples by category
- Responses-First Workflows
- Tool Orchestration
- Tool Framework
- Vector Store Operations
- Langfuse Integration
- API Documentation
Examples
The examples/ directory contains comprehensive examples for all major OpenAI API features:
Core Examples
- quickstart.rs - Quick introduction to the library with basic usage patterns
- chat_streaming.rs - Real-time chat streaming with Server-Sent Events (SSE)
- tool_framework.rs - Unified tool framework with typed inputs and registry execution
- tool_framework_typed.rs - Strongly typed inputs/outputs and processing tool calls
- tool_calling_multiturn.rs - Multi-turn tool calling with proper conversation history management
- responses_comprehensive.rs - Complete responses API demonstration including function calling and web search
- responses_streaming.rs - Real-time streaming responses with progress indicators
- chat_comprehensive.rs - Full chat completions API with conversation history
- structured_outputs.rs - JSON mode and schema-based structured outputs
- vision_chat.rs - Image understanding with GPT-4 Vision
Media & AI Capabilities
- audio_speech.rs - Text-to-speech generation with multiple voices
- audio_transcription.rs - Speech-to-text transcription and translation
- images_comprehensive.rs - Image generation, editing, and variations
- embeddings.rs - Vector embeddings with similarity search patterns
Advanced APIs
- assistants_basic.rs - Introduction to the Assistants API with threads and tools
Run any example with:
# Set your OpenAI API key
# Run an example
Each example includes:
- Comprehensive documentation and inline comments
- Error handling best practices
- Real-world use cases and patterns
- Progressive complexity from basic to advanced usage
Contributing
We welcome contributions! Please see our Contributing Guide for details.
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.