Crate rstructor 

rstructor: get structured, validated data out of LLMs as native Rust structs and enums

Overview

rstructor gets structured, validated data out of large language models (LLMs) as native Rust structs and enums. It generates JSON Schema from your types, prompts the model, parses the response, and validates the result — retrying automatically when validation fails.

Key features:

• Derive macro for automatic JSON Schema generation
• Built-in clients for OpenAI, Anthropic, Google Gemini, and xAI Grok
• Validation of responses against schemas
• Type-safe conversion from LLM outputs to Rust structs and enums
• Customizable client configurations

Quick Start

use rstructor::{LLMClient, OpenAIClient, Instructor};
use serde::{Serialize, Deserialize};

#[derive(Instructor, Serialize, Deserialize, Debug)]
struct Person {
    name: String,
    age: u8,
    bio: String,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a client
    let client = OpenAIClient::new("your-openai-api-key")?;

    // Extract a structured response
    let person: Person = client.extract("Describe a fictional person").await?;

    println!("Name: {}", person.name);
    println!("Age: {}", person.age);
    println!("Bio: {}", person.bio);

    Ok(())
}

Re-exports

pub use error::ApiErrorKind;

pub use error::RStructorError;

pub use error::Result;

pub use error::StreamErrorKind;

pub use model::Instructor;

pub use schema::CustomTypeSchema;

pub use schema::Schema;

pub use schema::SchemaBuilder;

pub use schema::SchemaType;

Modules

client

error

logging

Logging functionality for rstructor

model

schema

telemetry

OpenTelemetry-compatible GenAI tracing fields.

Macros

impl_client_builder_methods

Macro to generate standard builder methods for LLM clients.

Structs

AnthropicClient

Anthropic client for generating completions

AttemptRecord

Immutable record of one materialization attempt.

ChatMessage

A chat message for conversation history.

Extraction

A validated value and its complete available extraction report.

ExtractionError

A failed extraction and the same report shape returned on success.

ExtractionReport

Run metadata shared by successful and failed structured extractions.

Fixture

A versioned collection of sanitized, ordered request/response interactions.

FixtureRecorder

An LLMClient wrapper that records sanitized non-streaming interactions.

FixtureSanitizer

Mandatory privacy boundary used before requests and responses enter a fixture.

FnTool

A Tool built from a closure.

GeminiClient

Gemini client for generating completions

GenerateResult

Result of a generate call, containing the text and optional usage information.

GrokClient

Grok client for generating completions

MaterializeFailure

Failed structured-output run with available usage and attempt metadata.

MaterializeReport

Successful structured-output run with usage and available attempt metadata.

MaterializeResult

Result of a materialize call, containing both the data and optional usage information.

MediaFile

File reference for media-aware prompts (e.g., Gemini file URI or inline data).

MockClient

An in-memory LLMClient for offline tests.

MockRequestView

A borrowed view of an incoming request, passed to a responder closure so it can branch on the prompt/target type without cloning. Mirrors RecordedRequest.

ModelInfo

Information about an available model from an LLM provider.

OpenAIClient

OpenAI client for generating completions

RecordedRequest

A single request the mock received, captured for assertions.

ReplayClient

Strict, ordered, offline replay of a Fixture.

Request

A fluent request being built against a client. Created via RequestExt.

ResponseBodyCapture

Opt-in, caller-controlled response-body capture.

ResponseMetadata

HTTP metadata retained for one provider response.

RunUsage

Cumulative token usage across every provider response in one materialization run.

SanitizedResponseBody

A response body that has passed through a caller-provided sanitizer.

Schemars

Transparent adapter from a schemars model to rstructor’s Instructor.

TokenUsage

Token usage information from an LLM API call.

Toolbox

A collection of tools made available to the model.

Enums

AnthropicModel

Anthropic models available for completion

AnyClient

A provider-agnostic client chosen at runtime.

AttemptKind

Whether an attempt reached structured-output validation.

AttemptOutcome

Outcome of one materialization attempt.

ChatRole

Role of a chat message participant.

FixtureError

File-format and replay-completion errors for fixtures.

GeminiModel

Gemini models available for completion

GrokModel

Grok models available for completion

MockResponse

One scripted reply the mock will hand back for a call.

OpenAIModel

OpenAI models available for completion

Provider

Identifies an LLM provider for runtime selection via AnyClient.

RequestKind

Which LLMClient (or extension) method produced a RecordedRequest.

RetryDisposition

Why execution did or did not continue after a failed attempt.

StreamedObject

An item yielded by a streaming structured (“object”) request.

ThinkingLevel

Thinking level configuration for models that support extended reasoning.

Constants

DEFAULT_CONNECT_TIMEOUT

Default timeout for establishing a TCP connection to an LLM provider (30 seconds).

DEFAULT_REQUEST_TIMEOUT

Default timeout for an entire HTTP request to an LLM provider (5 minutes).

FIXTURE_SCHEMA_VERSION

Current on-disk fixture schema version.

Traits

DynTool

Object-safe, type-erased view of a Tool, used to store heterogeneous tools in a Toolbox. Implemented automatically for every Tool.

LLMClient

LLMClient trait defines the interface for all LLM API clients.

RequestExt

Fluent request entry points, available on every LLMClient.

Tool

A typed tool the model can call.

Functions

client

Build a client from a provider/model string.

client_from_env

Build a client for the first provider whose API key is configured.

parse_client_spec

Parse a provider/model client specification without reading the environment.

Type Aliases

ExtractionResult

The advanced structured-extraction result type.

ItemStream

A boxed stream of fully-parsed items, one per element of a streamed JSON array.

ObjectStream

A boxed stream of StreamedObject items for a streaming structured request.

TextStream

A boxed stream of text deltas. Each item is either an incremental piece of the model’s text output or a transport/decode error.

Derive Macros

Instructor

Derive macro for implementing Instructor and SchemaType