Skip to main content

Crate dsir

Crate dsir 

Source
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:

LayerConceptKey typesWho
Signatures“Given these inputs, produce these outputs”Signature, #[derive(Signature)]Everyone
ModulesPrompting strategies that implement a signatureModule, Predict, ChainOfThoughtEveryone
OptimizationAuto-tuning instructions and demosOptimizer, COPRO, GEPA, MIPROv2When 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 Deref

ChainOfThought<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::compile path (TODO(trace-demos)). The dyn path (MIPROv2::compile_dyn) seeds demos from successful traces.
  • CallMetadata is 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, _>, and Box. Rc/Arc containing Predict leaves 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

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§

BamlConvertError
Error during BamlValue ↔ Rust conversion.
Constraint
OutputFormatContent
RenderOptions
ResponseCheck
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§

BamlValue
ConstraintLevel
Flag
StreamingMode

Traits§

BamlType
Runtime trait for types that expose BAML schema + conversion entry points.
Facet
Allows querying the Shape of 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§

BamlType
Attribute macro that makes a struct or enum usable with BAML.

Derive Macros§

Augmentation
Facet
Signature