Expand description
Typed prompt engineering and LM program optimization.
dsir is a Rust port of DSPy: you declare what
you want the LM to produce (a Signature), pick a prompting strategy (a Module
like Predict or ChainOfThought), and let an Optimizer tune the program’s
instructions and demos on your training data. The type system enforces correctness
at every layer — field types, strategy swaps, and augmentation composition are all
compile-time checked.
§The mental model
Three concepts, three layers:
| Layer | Concept | Key types | Who |
|---|---|---|---|
| Signatures | “Given these inputs, produce these outputs” | Signature, #[derive(Signature)] | Everyone |
| Modules | Prompting strategies that implement a signature | Module, Predict, ChainOfThought | Everyone |
| Optimization | Auto-tuning instructions and demos | Optimizer, COPRO, GEPA, MIPROv2 | When you need better results |
A Predict is the leaf — the only thing that actually calls the LM. Every other
module (ChainOfThought, custom pipelines) delegates to one or more Predict leaves.
Optimizers discover these leaves automatically via Facet reflection and mutate their
instructions and few-shot demos.
§Quick start
use dsir::*;
#[derive(Signature, Clone, Debug)]
/// Answer questions accurately and concisely.
struct QA {
#[input] question: String,
#[output] answer: String,
}
// 1. Configure the LM
let lm = LM::builder()
.model("openai:gpt-4o-mini".to_string())
.build()
.await
.unwrap();
dsir::configure(lm, ChatAdapter);
// 2. Pick a strategy
let cot = ChainOfThought::<QA>::new();
// 3. Call it
let result = cot.call(QAInput { question: "What is 2+2?".into() }).await?;
println!("{}", result.reasoning); // chain-of-thought text
println!("{}", result.answer); // the actual answer, via DerefChainOfThought<QA> returns Predicted<WithReasoning<QAOutput>>, not
Predicted<QAOutput>. You access .reasoning directly and .answer through auto-deref
(WithReasoning<O> derefs to O). This pattern holds for all augmentations — the
compiler tells you what changed when you swap strategies.
§What doesn’t work (yet)
- Typed MIPRO is still instruction-only on the static
Optimizer::compilepath (TODO(trace-demos)). The dyn path (MIPROv2::compile_dyn) seeds demos from successful traces. CallMetadatais not extensible. Modules can’t attach custom metadata (e.g. “which attempt won in BestOfN”). This should probably be a trait with associated types, but it isn’t.- Container traversal is partial. The optimizer walker handles
Option,Vec,HashMap<String, _>, andBox.Rc/ArccontainingPredictleaves return explicit container errors (not silent skips).
§Dynamic runtime path
For runtime-configurable programs use DynSignature (JSON schema or string DSL),
DynPredict / DynModule, ProgramGraph / StrategyFactory, and
Lab with compile_dyn optimizers. Typed #[derive(Signature)]
remains the primary API for static Rust programs.
User guides (repository docs/user/):
- Dynamic signatures —
building-blocks/dyn-signatures.md - Program graph —
dynamic-programs/program-graph.md - Lab —
lab/overview.md - compile_dyn —
optimizers/compile-dyn.md
§Examples
Runnable examples live in crates/dsir/examples/:
cargo run -p dsir --example 01_predict # Signature → Predict (live LM)
cargo run -p dsir --example 04_bootstrap # BootstrapFewShot (offline)
cargo run -p dsir --example 05_lab # Lab workflow (offline)
cargo run -p dsir --example 06_graph # ProgramGraph (offline)See docs/user/guides/examples.md for the full index.
§Crate organization
adapter— Prompt formatting and LM response parsing (ChatAdapter)core—Moduletrait,Signature/DynSignature,SignatureSchema, LM clientpredictors—Predict,DynPredict, typedExamplegraph—ProgramGraph,StrategyFactory, structural searchmodules—ChainOfThought,ReAct,BestOfN,Refine,Agentevaluate—TypedMetric,DynMetric,evaluate_trainsetoptimizer—Optimizer,COPRO,GEPA,MIPROv2,compile_dynlab— self-improvement authoring, compare, promote, registry clientdata—DataLoaderfor JSON/CSV/Parquet/HuggingFace datasetstrace— Execution graph recording for debuggingutils— Response caching
Re-exports§
pub use data::RawExample as UntypedExample;pub use adapter::chat::*;pub use augmentation::*;pub use core::*;pub use data::dataloader::*;pub use data::prediction::*;pub use data::serialize::*;pub use data::utils::*;pub use evaluate::*;pub use graph::*;pub use lab::*;pub use modules::*;pub use optimizer::*;pub use persistence::*;pub use predictors::*;pub use utils::*;
Modules§
- adapter
- Prompt formatting and LM response parsing.
- augmentation
- core
- The foundational abstractions everything else is built on.
- data
- Data loading and runtime row types.
- evaluate
- Evaluation and metrics for measuring module performance.
- graph
- Type-erased program graphs, strategy factories, and structural search.
- lab
- Self-improvement lab: author, optimize, compare, promote, persist.
- modules
- optimizer
- Automatic prompt optimization.
- persistence
- Program-level save/load of optimized predictor state.
- predictors
- trace
- Execution graph recording for debugging and inspection.
- utils
- LM response caching.
Macros§
- field
- hashmap
- Source: https://github.com/wholesome-ghoul/hashmap_macro/blob/master/src/lib.rs Author: https://github.com/wholesome-ghoul License: MIT Description: This macro creates a HashMap from a list of key-value pairs. Reason for Reuse: Want to avoid adding a dependency for a simple macro.
- sign
Structs§
- Baml
Convert Error - Error during BamlValue ↔ Rust conversion.
- Constraint
- Output
Format Content - Render
Options - Response
Check - The user-visible schema for a failed check.
- Shape
- Schema for reflection of a type — the core type in facet. Contains everything needed to inspect, allocate, and manipulate values at runtime.
Enums§
Traits§
- Baml
Type - Runtime trait for types that expose BAML schema + conversion entry points.
- Facet
- Allows querying the
Shapeof a type, which in turn lets us inspect any fields, build a value of this type progressively, etc.
Type Aliases§
- TypeIR
- A convenience type alias for BAML types in the IR.
Attribute Macros§
- Baml
Type - Attribute macro that makes a struct or enum usable with BAML.