DSPy From First Principles on Programmer.ie

DSPy From First Principles 01: Why Are We Still Hand-Writing Prompts?

Fri, 28 Aug 2026 10:00:00 +0100

Why Are We Still Hand-Writing Prompts?

A common language-model application begins as one string.

That is not a mistake. A prompt is the fastest way to discover whether a model can help with a task. It lets us work directly with the behavior instead of building a framework before we know the shape of the problem.

But the prompt often survives too long.

In this chapter we will build a small editorial assistant around a handwritten prompt. The task is realistic: given one sentence from a chapter, improve the sentence without changing its meaning or voice. This is a simplified version of the kind of sentence-improvement work that appears in Writer, where candidates, evidence packets, provider identity, fallback state, and later review decisions are all tracked explicitly.

DSPy From First Principles 02: A Prompt Is Not Yet a Program

Fri, 28 Aug 2026 10:05:00 +0100

A Prompt Is Not Yet a Program

In chapter 1 we built a reasonable handwritten prompt and found the real problem: one prompt string was carrying the task semantics, role and behavioral framing, output request, and model assumptions at the same time.

The next move is not to make a more elaborate prompt. It is to decide what properties an LM component needs before we should reasonably call it a program.

DSPy From First Principles 03: Define the Contract

Fri, 28 Aug 2026 10:10:00 +0100

Define the Contract

In chapter 2 we stopped treating the prompt string as the program. We defined a small DSPy module around a signature:

sentence
editorial_goal
local_context
    ↓
rewritten_text
rationale
confidence

That is better than a handwritten prompt, but it raises the next problem. The program boundary is only as good as the contract we put at that boundary.

This chapter is about signatures from first principles. A signature is not a prompt template. It is a task contract.

DSPy From First Principles 04: Separate What From How

Fri, 28 Aug 2026 10:15:00 +0100

Separate What From How

In chapter 3 we designed a stronger contract for sentence improvement. The signature names the inputs and outputs. It says what the LM should consume and produce.

It still does not say how the LM should execute the task.

That distinction is the main subject of this chapter.

                SAME CONTRACT

input ────────> Signature ────────> output
                    │
             execution policy
              /           \
         Predict       ChainOfThought

Changing the task contract and changing the execution strategy are different operations. Treating them as the same operation is one reason prompt experiments become impossible to interpret.

DSPy From First Principles 05: Build Programs From Programs

Fri, 28 Aug 2026 10:20:00 +0100

Build Programs From Programs

In chapter 4 we ran the same signature with different execution policies. That helped isolate one question:

Should this behavior be attempted directly or with intermediate reasoning?

Real applications usually ask a larger question. A sentence-improvement system may need to find what is wrong, generate a candidate, assess risk, and return something the rest of the product can store.

That is where a single LM call starts to hide several distinct operations.

DSPy From First Principles 06: Your Model Is a Dependency

Fri, 28 Aug 2026 10:25:00 +0100

Your Model Is a Dependency

In chapter 5 we composed several LM operations into one small editorial program. It can analyze a sentence, rewrite it, assess risk, and return structured fields.

One assumption remains hidden:

Which model executed the program?

That question is not operational trivia. A language-model program is not fully described by its Python class and signature. Its behavior depends on the LM boundary.

DSPy program
      ↓
LM boundary
   /      \
local     hosted
model     model

This chapter treats the model as a dependency: configured, recorded, tested, and replaced deliberately.

DSPy From First Principles 07: Examples Are Data, Not Decoration

Fri, 28 Aug 2026 10:30:00 +0100

Examples Are Data, Not Decoration

Chapter 6 gave the program a model boundary. We can now say what the program is, which LM dependency ran it, and whether fallback output contaminated the record.

That still leaves the unresolved problem:

program
   ↓
no disciplined evidence
   ↓
"seems better"

The next six chapters build one deliberately small teaching experiment. We will keep the editorial sentence-improvement program, create a dataset, measure a baseline, design a metric, compile candidate programs, and compare them against a held-out case.

DSPy From First Principles 08: You Cannot Optimize What You Cannot Measure

Fri, 28 Aug 2026 10:35:00 +0100

You Cannot Optimize What You Cannot Measure

Chapter 7 turned examples into data. We now have rows, labels, provenance, and splits.

That does not yet give us evidence. It gives us the material from which evidence can be produced.

The next step is a baseline evaluation:

frozen program
      +
frozen cases
      +
metric
      ↓
per-case results
      ↓
aggregate result
      ↓
failure inspection

No optimization happens in this chapter. Evaluation answers one question:

DSPy From First Principles 09: The Metric Is Part of the Program

Fri, 28 Aug 2026 10:40:00 +0100

The Metric Is Part of the Program

Chapter 8 gave us a baseline harness. It deliberately used a weak smoke-test metric because the first job was to make evaluation run.

Now the dangerous part begins.

During optimization, DSPy searches for program states that score well under the metric we provide. The optimizer does not know whether the score is a faithful proxy for the behavior we actually want.

1. The metric ladder

Different tasks tolerate different metrics.

DSPy From First Principles 10: Compile the Program

Fri, 28 Aug 2026 10:45:00 +0100

Compile the Program

Chapter 9 gave the optimizer something to pursue: a metric. That does not mean we should let an optimizer mutate the accepted program.

Compilation in DSPy is the process of taking a program, optimizer-visible evidence, a metric, and an optimizer, then producing a candidate program state.

1. Baseline and candidate are different objects

Before compiling, name the boundary:

A candidate is not the new production program. It is a proposed program version that must be evaluated.

DSPy From First Principles 11: Few-Shot Optimization

Fri, 28 Aug 2026 10:50:00 +0100

Few-Shot Optimization

Chapter 10 established the compilation boundary. The optimizer may propose a candidate program. It may not promote itself.

Now we inspect the first mechanism: few-shot optimization.

The question is practical:

Can we improve the program by selecting or constructing better demonstrations rather than rewriting the program ourselves?

A demonstration is attached to a predictor, so its fields need to make sense for that predictor’s signature.

For a one-step rewrite predictor, a demonstration might look like:

DSPy From First Principles 12: Optimize the Instructions

Fri, 28 Aug 2026 10:55:00 +0100

Optimize the Instructions

Chapter 11 let the optimizer change predictor behavior through bootstrapped demonstrations. That changes the examples shown to the LM, but the predictor instructions remain mostly fixed.

Now we expand the allowed mutation surface:

1. What MIPROv2 searches

Current MIPROv2 builds candidate few-shot sets, proposes instruction candidates for predictors, and searches combinations against validation evidence. Its current implementation uses an Optuna-backed search over prompt parameters.

Conceptually:

2. A MIPROv2 compile shape

Current docs show MIPROv2(metric=..., auto="light" | "medium" | "heavy"). Its compile method accepts trainset and valset; internally, the optimizer validates those datasets, builds an evaluator over the validation set, and searches prompt parameters against that development evidence.

DSPy From First Principles 13: Let the Program Reflect

Fri, 28 Aug 2026 11:00:00 +0100

Let the Program Reflect

Chapter 12 ended with a hard limitation. MIPROv2 can search instructions and demonstrations, but the metric we built mostly returns a number.

candidate
   ↓
metric
   ↓
0.42

That number can select among candidates. It cannot explain how the program should change.

The next mechanism is feedback-shaped evaluation:

prediction
    ↓
metric
    ↓
score + diagnostic feedback
    ↓
reflection
    ↓
instruction mutation
    ↓
candidate

Current DSPy describes GEPA as a reflection-driven instruction optimizer. It maintains a population of candidate instruction states, evaluates them on validation examples, and uses textual feedback plus execution traces to propose new instructions for selected predictors.

DSPy From First Principles 14: Agents Are Programs Too

Fri, 28 Aug 2026 11:05:00 +0100

Agents Are Programs Too

Chapter 13 gave failures language. The optimizer can receive feedback, reflect, and propose better instructions.

The next limitation is access. Our editorial program receives a sentence and local context. A repository repair program cannot be handed the whole world as one input and expected to behave.

The naive shape is:

issue
+
huge repository context
       ↓
model
       ↓
patch

The stronger shape gives the program bounded capabilities rather than one giant input:

DSPy From First Principles 15: Search, Memory and Long Context

Fri, 28 Aug 2026 11:10:00 +0100

Search, Memory and Long Context

Chapter 14 gave the program tools. It can inspect an environment instead of receiving all evidence up front.

Now we face the selection problem:

When the necessary evidence is too large to place directly in the prompt, how should the program decide what to inspect?

Several mechanisms are often collapsed into one word: context. They are different.

1. Put context directly in the prompt
2. Retrieve context before the LM call
3. Let an agent choose retrieval tools
4. Retrieve previous cases / memory
5. Let a model programmatically explore a large context

Each creates a different evidence-selection boundary, with different costs, failure modes, and leakage risks.

DSPy From First Principles 16: Don't Let the Optimizer Cheat

Fri, 28 Aug 2026 11:15:00 +0100

Don’t Let the Optimizer Cheat

Chapter 15 expanded the program’s access. It can search repositories, retrieve memory, use tools, and maybe explore large contexts programmatically.

That power threatens the experiment.

The central question:

How can an optimization experiment appear valid while the program or optimizer has quietly gained access to the answer?

Cheating is often accidental. A field named validation_result slips into generation inputs. A memory tool returns the historical accepted patch. A retriever indexes a later repository revision. A GEPA feedback string includes the exact gold answer. A developer inspects holdout failures, changes instructions, and evaluates on the same holdout again.

DSPy From First Principles 17: From Experiment to Production

Fri, 28 Aug 2026 11:20:00 +0100

From Experiment to Production

Chapter 16 gave us a candidate that can be evaluated without obvious leakage.

That still does not mean:

optimizer.compile(...)
        ↓
production

The lifecycle is closer to:

1. Offline win is insufficient

A candidate may beat an aggregate metric and still be unacceptable:

2. CoCoder’s promotion boundary

CoCoder stores separate records:

ProgramEvaluationCaseResultDTO
ProgramEvaluationDTO
ProgramComparisonDTO
ProgramPromotionDTO

The docs summarize the invariant:

optimizer proposes
CoCoder evaluates
CoCoder compares
operator/system policy promotes

Promotion requires a persisted comparison, a promote recommendation unless there is an explicit override, the comparison baseline still being the single active version, the target still being a candidate, and optimizer lineage—when present—matching that active baseline.

DSPy From First Principles 18: Build a Self-Improving Engineering Program

Fri, 28 Aug 2026 11:25:00 +0100

Build a Self-Improving Engineering Program

We can now assemble the book.

The target is not an autonomous runtime that rewrites itself, judges its own work, and deploys the result. That collapses proposal, evidence, and authority into one component.

The stronger meaning is:

A self-improving engineering program participates in a governed evidence loop: production and evaluation create auditable evidence, optimizers propose new program state, independent comparison tests the proposal, and a separate promotion boundary decides what may become active.