How it fits together

This page is the map. It names every piece of dspy4s once and shows how they compose, so the rest of the documentation can go deep on one piece at a time without re-explaining the whole.

The pieces

dspy4s has a small number of concepts. Each builds on the one before it.

Concept	What it is
Signature	A declaration of a task's inputs and outputs. It describes what, not how.
Module	A strategy for answering a signature by calling a language model: Predict, ChainOfThought, ReAct.
Program	A module you run, or several modules composed into a larger one. Programs are ordinary Scala values.
Adapter	Turns a signature plus inputs into prompt messages, and parses the reply back into the domain output: ChatAdapter, JSONAdapter.
Language model	The backend an adapter sends messages to: OpenAiLanguageModel and OpenAI-compatible servers.
Runtime context	The ambient configuration a program runs under: which language model, which adapter, and any callbacks.
Example	A labeled data point: some inputs and their expected outputs.
Metric	A function that scores a program's output against an Example.
Optimizer	Takes a program, a set of Examples, and a Metric, and returns an improved program.

Running a program

When you call a program, the work flows in one direction and comes back as a Scala value:

runtime context · language model · adapter · callbacks

Signatureinput/output

→

ModulePredict · CoT · ReAct

→

Adapterformat + parse

→

Language model

→

OutputEither[err, out]

1. You call program.apply(inputs) inside a runtime context.
2. The module asks the adapter to format the signature, the inputs, and any few-shot demonstrations into messages.
3. The adapter sends the messages to the language model.
4. The adapter parses the reply back into the signature's output type.
5. You get an Either[DspyError, Output], where Output is a named tuple with direct dot access.

The Quickstart shows this end to end in a few lines.

Improving a program

Optimization is a separate, offline step. You do not change your program's code; an optimizer searches for better few-shot demonstrations and instructions and hands back a new program with the same type:

Program

Examples

Metric

→

Optimizer

→

Improved program

The improved program can be saved to disk and loaded later, so optimization runs once and the result ships with your application.

The map

Read top to bottom, or jump to what you need:

• Programs define and run the work: Signatures, Modules, Tools & ReAct, Composing programs.
• Language models are the backend programs call, plus adapters, caching, and usage.
• Evaluation measures a program with Examples and a Metric.
• Optimization improves a program from that measurement.
• Runtime covers configuration, observability, persistence, and streaming.

If you already know Python DSPy, Coming from DSPy maps the two libraries.