> ## Documentation Index
> Fetch the complete documentation index at: https://dsrs.herumbshandilya.com/llms.txt
> Use this file to discover all available pages before exploring further.
# The Module Macro
> Author LM calls as bodyless functions and whole pipelines as function bodies: #[predict], #[cot], and #[module]
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](/docs/components/program-and-nodes). 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.
```rust theme={null}
use dspy_rs::predict;
/// Answer the question.
#[predict]
fn answer(question: String) -> String;
```
Call it like a normal async function:
```rust theme={null}
let out = answer("What is DSRs?".to_string()).await?;
println!("{}", out.answer);
```
The mapping is the [signature](/docs/components/signatures) 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:
```rust theme={null}
/// 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.
```rust theme={null}
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.
```rust theme={null}
/// 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](#named-model-binding).
### The name is the link
The function name follows the step everywhere: [`fx::Params::set_instruction("answer", ...)`](/docs/components/fx) 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.
```rust theme={null}
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 {
// 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::>()
.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:
```rust theme={null}
let out = frontdesk(ticket).await?;
println!("{}", out.reply);
```
The function must be `async`, cannot be generic, and must return `Result` where `Err: From`. Two options: `caps("...", ...)` declares the program's [capability](/docs/components/capabilities) 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]`](/docs/components/tools-and-agents) function. Arguments must be ports: function parameters, prior `binding.field` accesses, or literals; `.clone()` and `&` wrappers are stripped.
* `let y: SimpleType = ;` 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](/docs/components/holes), 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
```rust theme={null}
println!("{}", frontdesk::program().to_dsrs());
```
The output below was captured from a real run of this pipeline:
```text theme={null}
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](/docs/components/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, PredictError>` | The callable function. It calls [`fx::predict`](/docs/components/fx) with the function's name as its params slot. |
`#[cot]` generates the same items; its function returns `Result>, 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`](/docs/components/runtime) 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](https://github.com/krypticmouse/DSRs/blob/main/crates/dspy-rs/examples/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`.
```rust theme={null}
// 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](/docs/components/tools-and-agents), 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.
## See also
* [Signatures](/docs/components/signatures) for the struct form of the same contract
* [Holes](/docs/components/holes) for what plain Rust inside a module becomes
* [Program and nodes](/docs/components/program-and-nodes) for what `program()` returns in memory
* [The .dsrs file](/docs/components/dsrs-file) for the printed text form and its grammar
* [Runtime](/docs/components/runtime) for `RuntimeEnv`, binding, and `Interpreter::load`
* Example: [22-frontdesk-module.rs](https://github.com/krypticmouse/DSRs/blob/main/crates/dspy-rs/examples/22-frontdesk-module.rs)