DSRs (DSPy Rust)

A .dsrs file is the canonical text representation of a program. It consists of declarations followed by exactly one main block. The program's identity (hash) is derived from this text, excluding the lineage block.

General Syntax Rules:

• // starts a comment.
• Whitespace is insignificant (except inside js``` ``` code fences).
• Strings must be JSON strings.
• Reserved Words: You cannot use any of the following as names: dsrs program caps model sig class enum tool lineage main in out predict cot agent hole seq fork join route retry refine loop else js demos string int float bool map true false null while carry.

File Skeleton:

dsrs 1
program qa

caps { net:search }

model fast = "openai:gpt-4o-mini" { temperature 0.2 }

sig Main {
  in  question: string
  out answer: string
}

main: Main = seq {
  ...
  out { answer = ... }
}

The DSRs API is distributed across several specialized crates. For full signatures, method details, and trait implementations, refer to the official documentation on docs.rs for each specific crate:

• dspy-rs: The primary crate containing core signatures, predictors, modules, Intermediate Representation (IR), traces, and optimizers.
• dsrs-tools: Provides sandboxed tool execution and Code Mode capabilities.
• dsrs-macros: Contains the procedural macros used for the derive and attribute syntax.
• dsrs-syntax: Defines the shared .dsrs lexer and structural grammar used by all frontends.

A Signature is a typed contract between a module and a Language Model (LM). It defines named input fields, named output fields, and instructions. This declarative approach allows the framework to handle prompt construction, output parsing, and type validation automatically.

Key Concept: A Signature is a class, not an instance. When you define or create a signature, you are working with a new type (a dynamically-created Pydantic BaseModel subclass). Operations like prepend, with_instructions, or delete do not mutate the existing signature; instead, they return a new Signature class.

Code Mode is a high-efficiency alternative to standard JSON tool calling. Instead of the model making multiple round trips to the host for each tool invocation, it uses a single meta-tool called run_js.

In Code Mode, the model sees your tools as a JavaScript API. It writes a single script that calls these tools as global functions, composes their results, and returns a final value. This reduces latency and token usage by replacing multiple model turns with a single execution step.

Key Benefits:

• Reduced Latency: One model round trip instead of $N$ trips for $N$ tools.
• Reduced Token Usage: Intermediate tool results stay within the sandbox and don't necessarily need to flow through the model's context.
• Composition: The model can easily pipe the output of one tool into the input of another using standard JavaScript logic.

DSPy is a framework for programming with language models where you declare what you want using typed signatures, rather than manually constructing prompts. The framework manages prompt construction, output parsing, and automatic optimization of prompts and few-shot examples.

At its core, DSPy is built on the Predict primitive. A Predict instance takes a typed signature (defining input and output fields), uses an Adapter to format it into a prompt, calls a Language Model (LM), and parses the response back into typed outputs. Higher-level modules like ChainOfThought or ReAct are simply orchestrations of multiple Predict instances.

GEPA is a reflective prompt optimizer that evolves instructions using textual feedback provided by your metrics. Unlike optimizers that rely solely on scalar scores, GEPA uses detailed explanations of failures to drive an LLM-based reflection process. It maintains a Pareto frontier of candidates, meaning it preserves a diverse set of instructions that excel on different subsets of examples, preventing premature convergence to a single mediocre solution.

Key features include:

• Rich Textual Feedback: Uses detailed explanations (e.g., why a classification failed) instead of just numbers.
• Pareto-based Selection: Keeps candidates with complementary strengths.
• LLM-driven Reflection: Uses a prompt_model to propose targeted instruction rewrites based on feedback and execution traces.
• Inference-time Search: Capable of optimizing at test time.

The DSRs system is completed by several key mechanisms that manage security, observability, and optimization:

• Capabilities: These gate what a program is allowed to do. The program declares its requirements in the .dsrs artifact, and the host must grant them. Loading fails if there is a mismatch.
• Traces: These record every execution. They allow for Strict Replay (reproducing a run with zero live calls for deterministic testing) and Until-divergence Replay (re-running only the steps affected by a specific change).
• Evaluation & Optimizers: These create a feedback loop. An Evaluation metric scores outputs, and Optimizers use those scores to search for better instruction sets and demonstration (few-shot) candidates.