The Module Macro

The function-authoring lane declares LM calls as bodyless Rust functions and whole pipelines as ordinary function bodies. #[predict] and #[cot] turn one function signature into one model call; #[module] compiles a function body that chains those calls into an IR Program. The macro reads each function once at expansion and emits both the runnable code and its program form, so the two cannot drift.

Steps

A step is one model call declared as a function with no body. The function is the contract; the framework writes the prompt and parses the answer.

use dspy_rs::predict;

/// Answer the question.
#[predict]
fn answer(question: String) -> String;

Call it like a normal async function:

let out = answer("What is DSRs?".to_string()).await?;
println!("{}", out.answer);

The mapping is the signature idea applied to a function:

You write	It becomes
The doc comment	The instruction the model reads
Each parameter	An input field, same name and type
The return type	One output field, named after the function

So fn answer(question: String) -> String gives the model an input called question and asks for an output called answer, which is why the result reads as out.answer. A step can take several inputs:

/// Judge whether the answer is correct.
#[predict]
fn judge(question: String, answer: String) -> bool;

Rules, each a compile error when broken: the function is bodyless and ends with ;; do not write async (the generated function is async automatically); no generics, no self, parameters must be plain identifiers; at least one input parameter and an explicit return type are required.

Chain of thought

#[cot] is the chain-of-thought variant of #[predict]: the model produces a reasoning field before the output. Same rules, same options. The result carries the extra field and auto-derefs to the output.

use dspy_rs::cot;

/// Summarize the text.
#[cot]
fn summarize(text: String) -> String;

let out = summarize(long_text).await?;
println!("{}", out.reasoning);   // the model's thinking
println!("{}", out.summarize);   // the answer

Model handles

Both attributes accept one option, model = "@name", which selects a declared model by reference; the leading @ is stripped, and anything else in the attribute is a compile error.

/// Write a warm, concrete reply to this support ticket.
#[cot(model = "@strong")]
fn draft(ticket: String, summary: String) -> String;

The name is a handle, not a hardcoded model id: which model strong really is gets decided by whoever runs the program. Steps with no model = ... ride the default model from your configure(...) line automatically. Named handles have no such fallback; see Named model binding.

The name is the link

The function name follows the step everywhere: fx::Params::set_instruction("answer", ...) overrides its instruction, trace spans record the same name, and the generated signature lives in a module of the same name (answer::Sig). One exception: when a step is called inside a #[module] body, the trace and step name is the let binding name for that call, so let drafter = draft(...).await?; records as drafter.

Modules

#[module] compiles an ordinary async Rust function body into an IR Program. One parse, two projections: the executable function (typed boundary, runs through the interpreter, reads the ambient overlay) and name::program(), the same pipeline as a servable, optimizable, printable artifact.

use dspy_rs::module;

#[dspy_rs::Schema]
#[derive(Debug)]
pub struct DeskOut {
    pub summary: String,
    pub reply: String,
}

#[module]
async fn frontdesk(ticket: String) -> Result<DeskOut, dspy_rs::ir::RunError> {
    // plain Rust: scrub email addresses before anything leaves
    let clean: String = {
        let t: String = ticket;
        t.split_whitespace()
            .map(|w| if w.contains('@') { "[email]" } else { w })
            .collect::<Vec<&str>>()
            .join(" ")
    };

    let sum = summarize(clean.clone()).await?;
    let drafter = draft(clean.clone(), sum.summarize.clone()).await?;

    Ok(DeskOut {
        summary: sum.summarize,
        reply: drafter.draft,
    })
}

It runs the way it reads:

let out = frontdesk(ticket).await?;
println!("{}", out.reply);

The function must be async, cannot be generic, and must return Result<Out, Err> where Err: From<dspy_rs::ir::RunError>. Two options: caps("...", ...) declares the program’s capability ceiling, and deny_holes makes any non-step expression a compile error instead of a hole.

Accepted body shapes

The body is straight-line only, built from three shapes:

let x = step(args).await?; where step is a #[predict], #[cot], or #[agent] function. Arguments must be ports: function parameters, prior binding.field accesses, or literals; .clone() and & wrappers are stripped.
let y: SimpleType = <any Rust expr>; for plain Rust. The type ascription is required and must be simple: String, bool, an integer width from i8 through i64 or u8 through u32, f32/f64, or Vec<...>/Option<...> of those. The expression becomes a typed extern hole, a named boundary around code the IR cannot describe as data; the hole page covers how holes bind and travel.
A tail expression Ok(Struct { field: port, ... }) giving the program’s output bindings.

The printed program

println!("{}", frontdesk::program().to_dsrs());

The output below was captured from a real run of this pipeline:

dsrs 1
program frontdesk

// model and signature declarations trimmed

main: Main = seq {
  clean = hole clean_hole (ticket = $.ticket) caps [] extern "a90e86e4381f68a9"
  sum = predict summarize @default (ticket = clean.clean)
  drafter = cot draft @strong (ticket = clean.clean, summary = sum.summarize)
  out { summary = sum.summarize, reply = drafter.draft }
}

Every step appears under its let binding name (sum, drafter), so the program speaks in your vocabulary. Every wire is a line of Rust written as a connection: sum.summarize flowing into draft’s summary input is the sum.summarize.clone() argument. The @strong handle survives intact, and the privacy scrub prints as hole clean_hole with an extern fingerprint in place of its code. This is the build-time design point stated plainly: the macro reads the function once at expansion and emits both the runnable function and the Program. The two are projections of one source, so they cannot drift. The printed text is the canonical .dsrs form; its grammar and identity rules live in The .dsrs file.

Generated items

For a step #[predict] fn answer(question: String) -> String;:

Item	What it is
`answer::Sig`, `answer::SigInput`, `answer::SigOutput`	The derived signature and its input and output structs.
`answer::__dsrs_step()`	Step metadata, consumed when the call is lowered inside a `#[module]` body.
`async fn answer(question: String) -> Result<Predicted<answer::SigOutput>, PredictError>`	The callable function. It calls `fx::predict` with the function’s name as its params slot.

#[cot] generates the same items; its function returns Result<Predicted<WithReasoning<answer::SigOutput>>, PredictError>, and WithReasoning auto-derefs to the output. For #[module] async fn frontdesk(...), inside a module named after the function:

Item	What it is
`OPACITY`	A constant slice of `HoleReport` entries, one per hole-ized expression (name, kind, source excerpt, reason).
`program()`	The lowered `&'static Program`, linked at first use. Panics on link errors.
`try_program()`	The non-panicking form, returning `Result<&'static Program, &'static ModuleBuildError>`.
`env()`	The `RuntimeEnv` the module needs: its declared caps granted, the `default` model bound from the global settings when configured, `#[tool]` implementations bound, and extracted host holes bound.
generated test	A `#[cfg(test)]` test named `module_program_links_and_validates` that prints every `OPACITY` entry and fails the suite if `try_program()` errors.

It also emits the executable async fn itself, which loads the interpreter once, reads the ambient overlay via current_overlay(), and runs with a default budget.

Named model binding

Steps with no model = ... ride the default model from your configure(...) line automatically. A named handle has no such fallback, by design: bind it at load with frontdesk::env().bind_model("strong", strong) and run through Interpreter::load, or the load refuses, by name. The runnable example 22-frontdesk-module.rs does exactly this.

Common mistakes

Adding async to a step. The generated function is already async. Writing async fn on a #[predict] or #[cot] step is a compile error with a clear message: remove async.

// Wrong
#[predict]
async fn draft(question: String) -> String;

// Right
#[predict]
fn draft(question: String) -> String;

Adding a body to a step. A step has no body; the framework builds the behavior from the signature. If you want to write the body yourself, you want a tool, not a step. Forgetting the return type. The return type is the output field. Without it there is nothing for the model to produce, so it is a compile error. No inputs. A step needs at least one input parameter.

Get Started

Building Blocks

Programs as Data

Tools & Agents

Evaluation & Optimization

Utilities

The Module Macro

Steps

Chain of thought

Model handles

The name is the link

Modules

Accepted body shapes

The printed program

Generated items

Named model binding

Common mistakes

See also

​Steps

​Chain of thought

​Model handles

​The name is the link

​Modules

​Accepted body shapes

​The printed program

​Generated items

​Named model binding

​Common mistakes

​See also

Steps

Chain of thought

Model handles

The name is the link

Modules

Accepted body shapes

The printed program

Generated items

Named model binding

Common mistakes

See also