serdes_ai_output/
lib.rs

1//! # serdes-ai-output
2//!
3//! Output schema validation and structured output support for serdes-ai.
4//!
5//! This crate provides the infrastructure for parsing, validating, and
6//! handling structured output from language models.
7//!
8//! ## Core Concepts
9//!
10//! - **[`OutputMode`]**: How the model generates structured output (text, native, prompted, tool)
11//! - **[`OutputSchema`]**: Trait for parsing and validating model responses
12//! - **[`TextOutputSchema`]**: For plain text output with optional constraints
13//! - **[`StructuredOutputSchema`]**: For typed structured output using serde
14//! - **[`OutputValidator`]**: Additional validation logic after parsing
15//! - **[`OutputToolset`]**: Internal toolset for capturing output via tool calls
16//!
17//! ## Output Modes
18//!
19//! Different models support different ways of generating structured output:
20//!
21//! - **Text**: Free-form text, parsed by the application
22//! - **Native**: Model's built-in JSON mode (e.g., OpenAI's response_format)
23//! - **Prompted**: JSON output requested via system prompt
24//! - **Tool**: Output captured via a "result" tool call (most reliable)
25//!
26//! ## Example
27//!
28//! ```rust
29//! use serdes_ai_output::{StructuredOutputSchema, OutputSchema, OutputMode};
30//! use serdes_ai_tools::{ObjectJsonSchema, PropertySchema};
31//! use serde::Deserialize;
32//!
33//! #[derive(Deserialize)]
34//! struct Person {
35//!     name: String,
36//!     age: u32,
37//! }
38//!
39//! // Define the JSON schema
40//! let schema = ObjectJsonSchema::new()
41//!     .with_property("name", PropertySchema::string("Person's name").build(), true)
42//!     .with_property("age", PropertySchema::integer("Person's age").build(), true);
43//!
44//! // Create the output schema
45//! let output_schema: StructuredOutputSchema<Person> = StructuredOutputSchema::new(schema)
46//!     .with_tool_name("submit_person")
47//!     .with_description("Submit the person's information");
48//!
49//! // Parse output from a tool call
50//! let args = serde_json::json!({"name": "Alice", "age": 30});
51//! let person: Person = output_schema.parse_tool_call("submit_person", &args).unwrap();
52//! assert_eq!(person.name, "Alice");
53//! ```
54//!
55//! ## Text Output with Validation
56//!
57//! ```rust
58//! use serdes_ai_output::{TextOutputSchema, OutputSchema};
59//!
60//! let schema = TextOutputSchema::new()
61//!     .with_min_length(10)
62//!     .with_max_length(1000)
63//!     .with_pattern(r"^[A-Z]").unwrap() // Must start with uppercase
64//!     .trim();
65//!
66//! let result = schema.parse_text("  Hello, World!  ").unwrap();
67//! assert_eq!(result, "Hello, World!");
68//! ```
69
70#![warn(missing_docs)]
71#![deny(unsafe_code)]
72
73pub mod error;
74pub mod mode;
75pub mod parser;
76pub mod schema;
77pub mod spec;
78pub mod structured;
79pub mod text;
80pub mod toolset;
81pub mod types;
82pub mod validator;
83
84// Re-exports
85pub use error::{OutputParseError, OutputValidationError, ParseResult, ValidationResult};
86pub use mode::OutputMode;
87pub use parser::{extract_json_from_text, looks_like_json, parse_json_from_text, parse_json_value};
88pub use schema::{BoxedOutputSchema, OutputSchema, OutputSchemaWrapper};
89pub use spec::{IntoOutputSpec, OutputSpec, OutputSpecBuilder};
90pub use structured::{
91    extract_json, AnyJsonSchema, StructuredOutputSchema, DEFAULT_OUTPUT_TOOL_DESCRIPTION,
92    DEFAULT_OUTPUT_TOOL_NAME,
93};
94pub use text::{TextOutputSchema, TextOutputSchemaBuilder};
95pub use toolset::{OutputCaptured, OutputToolset};
96pub use types::{NativeOutput, PromptedOutput, StructuredDict, TextOutput, ToolOutput};
97pub use validator::{
98    async_validator, sync_validator, BoxedValidator, NoOpValidator, OutputValidator,
99    RejectValidator, RetryValidator, SyncValidator, ValidatorChain,
100};
101
102/// Prelude for common imports.
103pub mod prelude {
104    pub use crate::{
105        extract_json_from_text, looks_like_json, parse_json_from_text, AnyJsonSchema,
106        BoxedOutputSchema, IntoOutputSpec, NativeOutput, NoOpValidator, OutputMode,
107        OutputParseError, OutputSchema, OutputSpec, OutputToolset, OutputValidationError,
108        OutputValidator, PromptedOutput, StructuredDict, StructuredOutputSchema, TextOutput,
109        TextOutputSchema, ToolOutput, ValidatorChain,
110    };
111}
serdes_ai_output/lib.rs

serdes_ai_output/
lib.rs
