dsir/lib.rs
1//! Typed prompt engineering and LM program optimization.
2//!
3//! dsir is a Rust port of [DSPy](https://github.com/stanfordnlp/dspy): you declare what
4//! you want the LM to produce (a [`Signature`]), pick a prompting strategy (a [`Module`]
5//! like [`Predict`] or [`ChainOfThought`]), and let an [`Optimizer`] tune the program's
6//! instructions and demos on your training data. The type system enforces correctness
7//! at every layer — field types, strategy swaps, and augmentation composition are all
8//! compile-time checked.
9//!
10//! # The mental model
11//!
12//! Three concepts, three layers:
13//!
14//! | Layer | Concept | Key types | Who |
15//! |-------|---------|-----------|-----|
16//! | **Signatures** | "Given these inputs, produce these outputs" | [`Signature`], `#[derive(Signature)]` | Everyone |
17//! | **Modules** | Prompting strategies that implement a signature | [`Module`], [`Predict`], [`ChainOfThought`] | Everyone |
18//! | **Optimization** | Auto-tuning instructions and demos | [`Optimizer`], [`COPRO`], [`GEPA`], [`MIPROv2`] | When you need better results |
19//!
20//! A [`Predict`] is the leaf — the only thing that actually calls the LM. Every other
21//! module ([`ChainOfThought`], custom pipelines) delegates to one or more `Predict` leaves.
22//! Optimizers discover these leaves automatically via Facet reflection and mutate their
23//! instructions and few-shot demos.
24//!
25//! # Quick start
26//!
27//! ```no_run
28//! use dsir::*;
29//!
30//! #[derive(Signature, Clone, Debug)]
31//! /// Answer questions accurately and concisely.
32//! struct QA {
33//! #[input] question: String,
34//! #[output] answer: String,
35//! }
36//!
37//! # async fn example() -> Result<(), PredictError> {
38//! // 1. Configure the LM
39//! let lm = LM::builder()
40//! .model("openai:gpt-4o-mini".to_string())
41//! .build()
42//! .await
43//! .unwrap();
44//! dsir::configure(lm, ChatAdapter);
45//!
46//! // 2. Pick a strategy
47//! let cot = ChainOfThought::<QA>::new();
48//!
49//! // 3. Call it
50//! let result = cot.call(QAInput { question: "What is 2+2?".into() }).await?;
51//! println!("{}", result.reasoning); // chain-of-thought text
52//! println!("{}", result.answer); // the actual answer, via Deref
53//! # Ok(())
54//! # }
55//! ```
56//!
57//! `ChainOfThought<QA>` returns [`Predicted<WithReasoning<QAOutput>>`](Predicted), not
58//! `Predicted<QAOutput>`. You access `.reasoning` directly and `.answer` through auto-deref
59//! ([`WithReasoning<O>`] derefs to `O`). This pattern holds for all augmentations — the
60//! compiler tells you what changed when you swap strategies.
61//!
62//! # What doesn't work (yet)
63//!
64//! - **Typed MIPRO is still instruction-only** on the static `Optimizer::compile` path
65//! (`TODO(trace-demos)`). The dyn path ([`MIPROv2::compile_dyn`](crate::MIPROv2::compile_dyn))
66//! seeds demos from successful traces.
67//! - **`CallMetadata` is not extensible.** Modules can't attach custom metadata (e.g.
68//! "which attempt won in BestOfN"). This should probably be a trait with associated
69//! types, but it isn't.
70//! - **Container traversal is partial.** The optimizer walker handles `Option`, `Vec`,
71//! `HashMap<String, _>`, and `Box`. `Rc`/`Arc` containing `Predict` leaves return
72//! explicit container errors (not silent skips).
73//!
74//! # Dynamic runtime path
75//!
76//! For runtime-configurable programs use [`DynSignature`] (JSON schema or string DSL),
77//! [`DynPredict`] / [`DynModule`], [`ProgramGraph`] / [`StrategyFactory`], and
78//! [`Lab`](crate::Lab) with `compile_dyn` optimizers. Typed `#[derive(Signature)]`
79//! remains the primary API for static Rust programs.
80//!
81//! User guides (repository `docs/user/`):
82//! - Dynamic signatures — `building-blocks/dyn-signatures.md`
83//! - Program graph — `dynamic-programs/program-graph.md`
84//! - Lab — `lab/overview.md`
85//! - compile_dyn — `optimizers/compile-dyn.md`
86//!
87//! # Examples
88//!
89//! Runnable examples live in `crates/dsir/examples/`:
90//!
91//! ```bash
92//! cargo run -p dsir --example 01_predict # Signature → Predict (live LM)
93//! cargo run -p dsir --example 04_bootstrap # BootstrapFewShot (offline)
94//! cargo run -p dsir --example 05_lab # Lab workflow (offline)
95//! cargo run -p dsir --example 06_graph # ProgramGraph (offline)
96//! ```
97//!
98//! See `docs/user/guides/examples.md` for the full index.
99//!
100//! # Crate organization
101//!
102//! - [`adapter`] — Prompt formatting and LM response parsing ([`ChatAdapter`])
103//! - [`core`] — [`Module`] trait, [`Signature`] / [`DynSignature`], [`SignatureSchema`], LM client
104//! - [`predictors`] — [`Predict`], [`DynPredict`], typed [`Example`]
105//! - [`graph`] — [`ProgramGraph`], [`StrategyFactory`], structural search
106//! - [`modules`] — [`ChainOfThought`], [`ReAct`], [`BestOfN`], [`Refine`], [`Agent`]
107//! - [`evaluate`] — [`TypedMetric`], [`DynMetric`], [`evaluate_trainset`]
108//! - [`optimizer`] — [`Optimizer`], [`COPRO`], [`GEPA`], [`MIPROv2`], `compile_dyn`
109//! - [`lab`] — self-improvement authoring, compare, promote, registry client
110//! - [`data`] — [`DataLoader`] for JSON/CSV/Parquet/HuggingFace datasets
111//! - [`trace`] — Execution graph recording for debugging
112//! - [`utils`] — Response caching
113
114// TODO(dsrs-facet-lint-scope): remove this crate-level allow once Facet's generated
115// extension-attr dispatch no longer triggers rust-lang/rust#52234 on in-crate usage.
116#![allow(macro_expanded_macro_exports_accessed_by_absolute_paths)]
117
118extern crate self as dsir;
119
120pub mod adapter;
121pub mod augmentation;
122pub mod core;
123pub mod data;
124pub mod evaluate;
125pub mod graph;
126pub mod lab;
127pub mod modules;
128pub mod optimizer;
129pub mod persistence;
130pub mod predictors;
131pub mod trace;
132pub mod utils;
133
134pub use adapter::chat::*;
135pub use augmentation::*;
136pub use core::*;
137pub use data::dataloader::*;
138pub(crate) use data::example::Example as RawExample;
139pub use data::RawExample as UntypedExample;
140pub use data::prediction::*;
141pub use data::serialize::*;
142pub use data::utils::*;
143pub use evaluate::*;
144pub use graph::*;
145pub use lab::*;
146pub use modules::*;
147pub use optimizer::*;
148pub use persistence::*;
149pub use predictors::*;
150pub use utils::*;
151
152pub use bamltype::BamlConvertError;
153pub use bamltype::BamlType; // attribute macro
154pub use bamltype::Shape;
155pub use bamltype::baml_types::{
156 BamlValue, Constraint, ConstraintLevel, ResponseCheck, StreamingMode, TypeIR,
157};
158pub use bamltype::internal_baml_jinja::types::{OutputFormatContent, RenderOptions};
159pub use bamltype::jsonish::deserializer::deserialize_flags::Flag;
160pub use dsir_macros::*;
161pub use facet::Facet;
162
163/// Pre-built signature for use in doc examples. Not part of the public API.
164#[doc(hidden)]
165pub mod doctest {
166 #[derive(crate::Signature, Clone, Debug)]
167 /// Answer questions accurately and concisely.
168 pub struct QA {
169 #[input]
170 pub question: String,
171 #[output]
172 pub answer: String,
173 }
174}
175
176#[doc(hidden)]
177pub mod __macro_support {
178 pub use anyhow;
179 pub use bamltype;
180 pub use indexmap;
181 pub use schemars;
182 pub use serde;
183 pub use serde_json;
184}
185
186#[macro_export]
187macro_rules! field {
188 // Example Usage: field! {
189 // input["Description"] => question: String
190 // }
191 //
192 // Example Output:
193 //
194 // {
195 // "question": {
196 // "type": "String",
197 // "desc": "Description",
198 // "schema": ""
199 // },
200 // ...
201 // }
202
203 // Pattern for field definitions with descriptions
204 { $($field_type:ident[$desc:literal] => $field_name:ident : $field_ty:ty),* $(,)? } => {{
205 use $crate::__macro_support::serde_json::json;
206
207 let mut result = $crate::__macro_support::serde_json::Map::new();
208
209 $(
210 let type_str = stringify!($field_ty);
211 let schema = {
212 let schema = $crate::__macro_support::schemars::schema_for!($field_ty);
213 let schema_json = $crate::__macro_support::serde_json::to_value(schema).unwrap();
214 // Extract just the properties if it's an object schema
215 if let Some(obj) = schema_json.as_object() {
216 if obj.contains_key("properties") {
217 schema_json["properties"].clone()
218 } else {
219 "".to_string().into()
220 }
221 } else {
222 "".to_string().into()
223 }
224 };
225 result.insert(
226 stringify!($field_name).to_string(),
227 json!({
228 "type": type_str,
229 "desc": $desc,
230 "schema": schema,
231 "__dsrs_field_type": stringify!($field_type)
232 })
233 );
234 )*
235
236 $crate::__macro_support::serde_json::Value::Object(result)
237 }};
238
239 // Pattern for field definitions without descriptions
240 { $($field_type:ident => $field_name:ident : $field_ty:ty),* $(,)? } => {{
241 use $crate::__macro_support::serde_json::json;
242
243 let mut result = $crate::__macro_support::serde_json::Map::new();
244
245 $(
246 let type_str = stringify!($field_ty);
247 let schema = {
248 let schema = $crate::__macro_support::schemars::schema_for!($field_ty);
249 let schema_json = $crate::__macro_support::serde_json::to_value(schema).unwrap();
250 // Extract just the properties if it's an object schema
251 if let Some(obj) = schema_json.as_object() {
252 if obj.contains_key("properties") {
253 schema_json["properties"].clone()
254 } else {
255 "".to_string().into()
256 }
257 } else {
258 "".to_string().into()
259 }
260 };
261 result.insert(
262 stringify!($field_name).to_string(),
263 json!({
264 "type": type_str,
265 "desc": "",
266 "schema": schema,
267 "__dsrs_field_type": stringify!($field_type)
268 })
269 );
270 )*
271
272 $crate::__macro_support::serde_json::Value::Object(result)
273 }};
274}
275
276#[macro_export]
277macro_rules! sign {
278 // Example Usage: signature! {
279 // question: String, random: bool -> answer: String
280 // }
281 //
282 // Example Output:
283 //
284 // #[derive(Signature, Clone)]
285 // struct InlineSignature {
286 // #[input]
287 // question: String,
288 // #[input]
289 // random: bool,
290 // #[output]
291 // answer: String,
292 // }
293 //
294 // Predict::<InlineSignature>::new()
295
296 // Pattern: input fields -> output fields
297 { ($($input_name:ident : $input_type:ty),* $(,)?) -> $($output_name:ident : $output_type:ty),* $(,)? } => {{
298 #[derive($crate::Signature, Clone)]
299 struct __InlineSignature {
300 $(
301 #[input]
302 $input_name: $input_type,
303 )*
304 $(
305 #[output]
306 $output_name: $output_type,
307 )*
308 }
309
310 $crate::Predict::<__InlineSignature>::new()
311 }};
312}
313
314/// Source: <https://github.com/wholesome-ghoul/hashmap_macro/blob/master/src/lib.rs>
315/// Author: <https://github.com/wholesome-ghoul>
316/// License: MIT
317/// Description: This macro creates a HashMap from a list of key-value pairs.
318/// Reason for Reuse: Want to avoid adding a dependency for a simple macro.
319#[macro_export]
320macro_rules! hashmap {
321 () => {
322 ::std::collections::HashMap::new()
323 };
324
325 ($($key:expr => $value:expr),+ $(,)?) => {
326 ::std::collections::HashMap::from([ $(($key, $value)),* ])
327 };
328}