Skip to main content

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}