feat(core): few-shot demos and optimizers (LabeledFewShot, BootstrapFewShot)

[ardada2468]

What

Predict had no few-shot support, and Example was exported with zero call sites anywhere in the repo. This wires both up and adds the optimizers that make "TypeScript DSPy" a description rather than an homage.

1. Demos in Predict

new Predict(Sig, { lm, demos }) renders Examples into the prompt as worked examples before the real input. The original (signature, lm) form still works — the second argument is discriminated structurally, and an object carrying only half an ILanguageModel is rejected loudly rather than silently falling back to the globally configured model.

withDemos() and withLM() return configured copies, preserving the concrete subclass, so ChainOfThought.withDemos() returns a ChainOfThought and an optimizer never mutates the student it was handed.

Demos render in whichever shape the reply is expected to take: labelled field: value for a text provider (exactly what parseOutput() reads back), JSON for a provider with native structured output — where constrained decoding means labelled examples would model a shape the model is forbidden to emit. All three shipped providers take the structured path, so this is the common case, not an edge one.

A prompt built with no demos is byte-for-byte what it was before; parsing.test.ts is untouched and green.

2. LabeledFewShot

Selects k of your own labelled examples. No model calls, so compiling is free and instant.

3. BootstrapFewShot

Runs the module over a labelled trainset, scores each attempt with a metric, and promotes the runs that passed into demos. An optional teacher model generates the demos that a cheaper student then imitates — you pay for the strong model once, at compile time.

• Deterministic given a seed. Seeded shuffle (mulberry32), results collected in input order, and the batch boundary that enables early stopping is also what guarantees the successes collected so far really are the first ones in trainset order.
• Bounded concurrency, and it stops as soon as it has maxBootstrappedDemos — a 500-row trainset does not cost 500 teacher calls to keep 4 demos.
• Failures are skipped, not fatal. A provider error, a reply that fails validation, or a throwing metric is reported as an error event and skipped. A throwing onProgress callback is swallowed too — an observer must not be able to lose a compile.
• maxBootstrappedDemos: 0 with maxLabeledDemos set is a labels-only compile that makes no model calls at all.
• no-console respected: progress goes through an optional callback.

The Metric type is defined locally in optimizers/types.ts rather than imported from the sibling evaluate/ PR, so the two can land in either order and be unified in a follow-up.

Verification

• npm run build / lint / typecheck / format:check / verify:packaging all clean.
• 229 tests pass, including predict.test.ts, chain-of-thought.test.ts, and parsing.test.ts unchanged.
• A throwaway consumer script (deleted before commit) imported from the built @ts-dspy/core package and asserted that a bootstrapped module's next prompt contains the demos whose metric passed and none of the rows that failed, that two compiles with the same seed produce identical demos, and that a teacher does the compile-time work while the student carries the result.

Docs

New section 21 #optimizers in site/docs.html, plus its TOC entry. No existing section renumbered. README's DSPy framing now mentions that optimization exists. examples/optimizer.ts and an example:optimizer npm script.

🤖 Generated with Claude Code