DSPy: The framework for programming—not prompting—language models
Python
docs: revamp home page and restructure learning + reference docs (#9855)
Drew Breunigccf375e7e4e9
diff --git a/docs/docs/diving-deeper/adapters.md b/docs/docs/diving-deeper/adapters.mdnew file mode 100644index 000000000..da08cb8b5--- /dev/null+++ b/docs/docs/diving-deeper/adapters.md@@ -0,0 +1,163 @@+# Adapters: how signatures become prompts++## Intent++An adapter is the layer between a `Signature` and the LM. It formats the signature’s instructions, fields, and demos into chat messages, sends the call, and parses the LM’s response back into typed Python values. Different adapters use different prompt shapes — chat markers, JSON, XML, or a two-stage extract — so the same Signature can run against models with widely different formatting strengths.++Read this when you want to know what the prompt looks like on the wire, why a typed field parses one way and not another, where the `[[ ## field_name ## ]]` markers come from, or which adapter to switch to when ChatAdapter is misbehaving.++## Design decisions++### 1. Adapters are pluggable++Same Signature, different prompt shape, no Signature changes. LMs vary a lot in what they prefer to read and produce: a model trained on instruction-following with markers loves ChatAdapter’s `[[ ## field ## ]]` format; a model with native structured-output mode does best with JSONAdapter; a reasoning model that formats unreliably wants TwoStepAdapter. Putting this decision behind one interface means Signatures, modules, and optimizers don’t have to know which family of LM they’re running against.++### 2. ChatAdapter is the default++Text-only, model-agnostic, uses `[[ ## field ## ]]` markers. It needs no special LM features — no JSON mode, no function calling, no native structured outputs. That breadth is why it’s the default. It also includes a safety net: when its regex parser fails, it falls back to JSONAdapter automatically (toggle with `use_json_adapter_fallback=False`).++### 3. Every adapter follows a fixed lifecycle++preprocess → format → LM call → postprocess → parse. You can debug any adapter by walking these five steps. Preprocess adapts the signature for native LM features (function calling, reasoning). Format builds the messages. The LM call returns raw outputs. Postprocess pulls out tool calls and native-typed responses (Reasoning, Citations). Parse runs `parse_value` on each declared output field.++### 4. Type coercion is centralized++`dspy/adapters/utils.py::parse_value` is the single function every adapter delegates to. Adapters differ in how they *find* a field’s value in the LM’s output (regex marker, JSON key, XML tag), but once they have the raw string they all call the same `parse_value(value, annotation)`. That keeps coercion rules consistent across adapter swaps and gives you one place to look when a typed field misbehaves.++### 5. Custom types own their own serialization++`Image`, `Audio`, `Code`, `Reasoning`, `Tool`, `ToolCalls`, and any user subclass of `dspy.Type` plug in their own `format()` and optional `parse_lm_response()`. The adapter doesn’t special-case images or audio. When the field’s annotation is a `dspy.Type` subclass, the adapter calls `type.format()` to render it into the provider’s content-block format and `type.parse_lm_response()` to read it back. Adding a new modality means writing a new subclass — no adapter changes.++### 6. Native LM features are surfaced through types++Function calling, structured outputs, and reasoning ride on `adapt_to_native_lm_feature()` and `parse_lm_response()` hooks on the type. A `dspy.Reasoning` output field, for example, tells the adapter “set `reasoning_effort` in `lm_kwargs` and pull the reasoning from `response['reasoning_content']` instead of regex-parsing it.” Model-specific feature integration lives at the type layer, where it’s reusable across adapters.++### 7. ChatAdapter falls back to JSONAdapter on parse error++Toggleable; on by default. The first time the LM produces malformed `[[ ## ## ]]` output, ChatAdapter catches the parse error and re-runs the request through JSONAdapter. This is more lenient than the right behavior for new code — you’d prefer to see the error — but it’s the default because it makes ChatAdapter usable against a wider range of models out of the box. Set `use_json_adapter_fallback=False` in tests.++### 8. JSONAdapter prefers structured output mode++It checks `lm.supported_params` and falls through tiers: OpenAI-style `response_format: json_schema` first, then `json_object` mode, then plain text JSON. The first tier is the most reliable because the model is constrained at decoding time, not only instructed.++### 9. TwoStepAdapter splits generation from extraction++For reasoning models that produce free-form text but format unreliably. Stage one: the main LM gets the task as plain prose, no field markers, and produces whatever shape it wants. Stage two: a smaller extractor LM with ChatAdapter reads the output and pulls out the declared fields. Useful for o1, o3-mini, and similar models where formatting reliability is the bottleneck.++### 10. Field marker format is hard-coded++`[[ ## name ## ]]` is the pattern, chosen for low collision and clean regex. The brackets-plus-hashes shape is unlikely to appear in real text or code, and the symmetry makes the parser simple. There’s no config knob to change it. JSONAdapter and XMLAdapter use their own formats; if you want a different chat-style format, subclass `Adapter`.++### 11. Finetuning data export is per-adapter++`format_finetune_data` is implemented on ChatAdapter (OpenAI message format); JSONAdapter raises `NotImplementedError`; TwoStepAdapter doesn’t support it either. If you’re using `BootstrapFinetune`, stay on ChatAdapter or implement `format_finetune_data` on the adapter of your choice.++## API walkthrough++Grouped by what you’re trying to do.++### The adapters++**`dspy.ChatAdapter(callbacks=None, use_native_function_calling=False, native_response_types=None, use_json_adapter_fallback=True)`**+The default. Builds a chat-style prompt with field markers, parses the response with a regex over the same markers, and (by default) falls back to JSONAdapter if the regex misses. Set `use_json_adapter_fallback=False` when you want a hard error in tests.++**`dspy.JSONAdapter(callbacks=None, use_native_function_calling=True)`**+Outputs structured JSON. Internally extends ChatAdapter — formatting is similar, but the output instruction asks for JSON and parsing uses `json_repair`. The constructor’s `use_native_function_calling=True` default flips when tool calling is wired in.++**`dspy.XMLAdapter(callbacks=None)`**+`<field_name>value</field_name>` tags. The parser is a regex (`r"<(\w+)>(.*?)</\1>"` with `DOTALL`); it’s robust to whitespace but doesn’t tolerate nested tags of the same name.++**`dspy.TwoStepAdapter(extraction_model: BaseLM, **kwargs)`**+Two LM calls per inference. Use it when the main LM is a reasoning model that’s bad at formatting — the extractor is usually a cheap general-purpose LM with ChatAdapter. Doesn’t support finetuning yet.++**`dspy.BAMLAdapter`**+JSON-backed, but renders the output schema in BAML-style commented Pydantic form. Worth trying when JSONAdapter’s raw JSON schema is too verbose for complex nested types.++**`dspy.Adapter`**+The base class. Subclass it when you want a new prompt shape — implement `format()`, `parse()`, and (optionally) `format_finetune_data()`.++### Adapter lifecycle++You’ll only override these methods when writing a custom adapter, but reading them helps when debugging a malformed prompt or a parse failure.++**`Adapter.__call__(lm, lm_kwargs, signature, demos, inputs)` / `Adapter.acall(...)`**+Public entry. The flow inside is preprocess → format → LM call → postprocess. `lm_kwargs` (temperature, max_tokens, response_format, etc.) is where adapters reach during preprocess to request structured output or function calling.++**`Adapter.format(signature, demos, inputs)` → `list[dict]`**+Turns the signature, demos, and inputs into chat messages. The pieces it composes from:++- `format_system_message(signature)` — the system message: field descriptions + format template + instructions.+- `format_field_description(signature)` — the per-field list with types and constraints.+- `format_field_structure(signature)` — the explanation of the marker format.+- `format_task_description(signature)` — `signature.instructions`.+- `format_demos(signature, demos)` — each demo becomes a user/assistant pair.+- `format_user_message_content(signature, inputs)` — the current call’s inputs.+- `format_assistant_message_content(signature, outputs)` — used inside demos.+- `format_conversation_history(signature, history)` — when a field has type `dspy.History`, expand it into turn messages instead of stuffing it into one field’s value.++**`Adapter.parse(signature, completion)` → `dict`**+Extracts typed field values from the LM’s response. ChatAdapter regex-matches the marker pattern, splits by field, and delegates each value to `parse_value`. JSONAdapter parses the JSON object and pulls values by key. XMLAdapter walks tags.++**`Adapter.format_finetune_data(signature, demos, inputs, outputs)`**+Serializes a demo into the LM provider’s finetune format. ChatAdapter writes OpenAI message format. Other adapters raise `NotImplementedError`.++### Type coercion++The single function every adapter calls when turning an LM-produced string into a typed value.++**`parse_value(value, annotation)` in `dspy/adapters/utils.py`**+Strategy: if the annotation is `str`, pass through. If it’s an `Enum` or `Literal`, match against allowed values. Otherwise: try `json_repair.loads`, fall back to `ast.literal_eval`, fall back to the raw string; then validate with `TypeAdapter(annotation)`. If validation fails and the annotation is a `dspy.Type` subclass, retry with the raw value so the type’s own parser can take a shot.++Other helpers in the same file you’ll see in tracebacks:++- `format_field_value(field_info, value, assume_text=True)` — the inverse of parse: serializes a typed value for the prompt.+- `serialize_for_json(value)` — Pydantic-aware JSON serialization, used by JSONAdapter.+- `translate_field_type(field_info)` — generates the constraint string the prompt shows (“greater than: 0”).+- `get_field_description_string(fields)` — the field-list rendering.+- `find_enum_member(enum_cls, raw)` — resolves an enum by name or value.++### Custom type wrappers++Types adapters know how to render and parse beyond Python’s standard ones. Each implements `format()`; some implement `parse_lm_response()` and `adapt_to_native_lm_feature()` for native LM hooks.++**`dspy.adapters.types.Type`**+The base class. Subclass it (it’s a `pydantic.BaseModel`) and implement `format()` to plug in a new type. Adapters wrap the output of `format()` with `<<CUSTOM-TYPE-START-IDENTIFIER>>...<<END-IDENTIFIER>>` so multi-modal content can be inserted into a single message stream and later split out.++**`dspy.Image(url, download=False, verify=True)`**+URL, local path, bytes, or PIL image. `format()` returns the provider’s image content block (`{"type": "image_url", "image_url": {"url": ...}}`). `download=True` fetches the image and base64-encodes it, useful when the LM provider can’t reach the URL.++**`dspy.Audio(data, audio_format)`**+Base64 audio data plus format string (`"wav"`, `"mp3"`). Renders as the provider’s audio content block.++**`dspy.File(file_data=None, file_id=None, filename=None)`**+Either a data URI or a file ID (some providers preupload files and reference them by ID).++**`dspy.Code(code, language="python")`**+Code with a class-level `language` parameter. `dspy.Code["java"]` produces a Code subclass typed for Java. `format()` returns the raw string — no wrapper, no fencing.++**`dspy.History(messages)`**+Conversation turns. When the adapter sees this type on a field, it expands the messages into real user/assistant messages instead of stuffing them into one field’s value. Use this when you want the LM to see prior turns as messages.++**`dspy.Reasoning(content)`**+String-like wrapper. When the LM supports a reasoning mode (o1, o3-mini, GPT-5 thinking variants), `Reasoning.adapt_to_native_lm_feature()` sets `reasoning_effort` in `lm_kwargs` and removes the field from the signature; `parse_lm_response()` pulls the reasoning out of the native response field. When the LM doesn’t support native reasoning, it falls back to a regular text field and behaves like the `reasoning` field `ChainOfThought` adds.++**`dspy.Tool(func, name=None, desc=None, args=None, arg_types=None, arg_desc=None)`**+Wraps a Python callable. Auto-introspects the function signature if you don’t pass `args`/`arg_types`/`arg_desc`. Used by `ReAct` and anywhere modules accept tools. The full tool story lives in the Tools / ReAct / MCP DD page.++**`dspy.adapters.types.tool.ToolCalls.from_dict_list(...)`**+The list of tool calls the LM produced, parsed from native function-calling responses.++**`dspy.adapters.types.Citations`**+Declared as a default native response type. When the provider returns citations natively (e.g., Anthropic), adapters extract them through the type’s `parse_lm_response`.++### Configuring which adapter to use++- **`dspy.configure(adapter=dspy.JSONAdapter())`** — process-wide default.+- **`with dspy.context(adapter=dspy.XMLAdapter()): ...`** — scoped override.+- **No automatic LM-based selection.** ChatAdapter is the default and stays the default until you set otherwise. Some teleprompts (e.g., `BootstrapFinetune`) accept an `adapter` dict keyed by LM, so different LMs in a finetuning loop can use different adapters.++## Cross-links++- [Signatures in depth](signatures-in-depth.md) — what the adapter consumes.+- [Settings and context()](settings-and-context.md) — how `configure` and `context` propagate the adapter choice.+- Tools, ReAct, and MCP DD page — `Tool` and `ToolCalls` are adapter-formatted but module-driven.diff --git a/docs/docs/diving-deeper/bootstrap-fewshot-family.md b/docs/docs/diving-deeper/bootstrap-fewshot-family.mdnew file mode 100644index 000000000..44392eb86--- /dev/null+++ b/docs/docs/diving-deeper/bootstrap-fewshot-family.md@@ -0,0 +1,139 @@+# BootstrapFewShot family++## Intent++The BootstrapFewShot family — `LabeledFewShot`, `BootstrapFewShot`, `BootstrapFewShotWithRandomSearch` (aliased `BootstrapRS`), `KNNFewShot`, and `InferRules` — are DSPy’s demo-tuning optimizers. They all share one mechanic: collect (or sample) example traces and stuff them into each predictor’s `demos` list. They differ in *how* the demos are chosen — passive sampling, metric-filtered bootstrap, random search across demo sets, KNN retrieval at inference, or rule extraction from bootstrapped traces.++Read this when you’ve picked a family member off the selection guide and want to understand how the variants relate, what each one adds over the base, and what failure modes to watch for.++## Design decisions++### 1. Demos live on the predictor, not on the optimizer++Every variant in this family writes to `predictor.demos` — a plain Python list attached to each `Predict`. The optimizer is the loader; the predictor is the storage. Once compiled, the program’s behavior is fully encoded in its predictors’ demos and signatures; the optimizer object can be discarded. `program.save(path)` pickles the demos along with the program.++### 2. `LabeledFewShot` is the no-LM baseline++Random sample (or deterministic slice) of the trainset, no teacher, no metric, no LM calls. Reach for it to confirm whether demos alone help — if `LabeledFewShot(k=16)` already gets you to your target, anything heavier is wasted effort.++### 3. `BootstrapFewShot` filters traces through a metric++The teacher runs each training example; the metric judges each completion; passing traces become demos. Every variant above the baseline uses some version of this loop. The metric is the lever — make it strict and you get few high-quality demos; make it loose and you get many lower-quality ones.++### 4. The teacher defaults to a deepcopy of the student++When you don’t pass `teacher=`, `BootstrapFewShot` calls `student.deepcopy()`. The copy is what runs against the trainset, not the original. The reason: the teacher gets `LabeledFewShot` demos applied to it (so it has examples to bootstrap from), and you don’t want those leaking into the student’s compiled state. Passing a stronger model as `teacher=` is the standard upgrade path when single-LM bootstrapping plateaus.++### 5. `max_rounds` re-runs the teacher with a fresh rollout per round++Each round bumps `rollout_id` and forces `temperature=1.0`, which busts the LM’s cache and triggers a new sample. Multiple rounds give a single example multiple chances to produce a passing trace. Don’t set `max_rounds` higher than 2 or 3 unless your metric is genuinely stringent — additional rounds compound LM cost linearly.++### 6. `max_bootstrapped_demos` caps the bootstrapped slots; `max_labeled_demos` caps the combined total++The first `max_bootstrapped_demos` slots go to traced and validated demos; the remaining slots up to `max_labeled_demos` fill with raw labeled examples from the trainset. Default `max_bootstrapped_demos=4, max_labeled_demos=16` gives 4 bootstrapped + up to 12 raw, per predictor. The raw demos act as ballast against bootstrap overfitting.++### 7. The example being bootstrapped is removed from the teacher’s demos first++Right before running the teacher on example `e`, the optimizer strips `e` from every predictor’s demo list. Without this, the teacher could “succeed” by retrieving `e`‘s answer from its own demos. The cleanup happens once per example and is silently undone for the next round.++### 8. `BootstrapRS` is `BootstrapFewShot` run N times, then evaluated++The randomness comes from shuffling the trainset and varying the bootstrap demo count per candidate. Three of the N seeds are pinned baselines (zero-shot, labeled-only, unshuffled bootstrap); the rest are randomized. The valset (defaults to trainset) is the tiebreaker — the highest-scoring candidate wins. Use it when one bootstrap pass produces inconsistent demo quality.++### 9. `KNNFewShot` picks demos at inference time, not compile time++The trainset is embedded once at construction. Each forward call embeds the new input, retrieves the `k` nearest training examples, and runs `BootstrapFewShot` on that micro-trainset before invoking the program. Per-call demo selection means different inputs see different demos — the right call when one demo set can’t generalize, expensive when called often because every forward pays for a mini-compilation.++### 10. `InferRules` extracts interpretable rules from the bootstrapped demos++On top of `BootstrapFewShot`, it asks a teacher LM to read the bootstrapped demos and produce `num_rules` natural-language rules. Those rules get appended to each predictor’s signature instructions. The win is interpretability: you can read the rules, decide whether they generalize, and edit them before saving.++### 11. A flaky metric corrupts the family++Every variant above the baseline depends on the metric to filter traces. If the metric is non-deterministic (calls an LM, depends on retrieval randomness), bootstrap discovers whichever traces happened to pass on that particular run. The demos you end up with are a function of metric noise as much as program quality. Make metrics deterministic where you can; when you can’t, accept that you should also use `BootstrapRS` and a held-out valset to average over the noise.++### 12. Compiled programs are pickled, demos and all++`program.save(path)` serializes the predictors with their `demos` lists in place. No special demo-extraction step is needed. The portability story is the same as for the spine modules: compile once, save, reload.++## API walkthrough++Grouped by family role.++### `LabeledFewShot` — the no-LM baseline++**`dspy.LabeledFewShot(k=16)`**+**`.compile(student, *, trainset, sample=True)`**++No teacher, no metric, no bootstrap loop. `.compile` samples up to `min(k, len(trainset))` examples from `trainset` — random (seeded with `Random(0)`) when `sample=True`, deterministic (first-k) when `sample=False` — and attaches the same set to each predictor’s `demos`. Single pass over the trainset; no LM calls.++### `BootstrapFewShot` — the core bootstrapper++**`dspy.BootstrapFewShot(metric=None, metric_threshold=None, teacher_settings=None, max_bootstrapped_demos=4, max_labeled_demos=16, max_rounds=1, max_errors=None)`**+**`.compile(student, *, teacher=None, trainset)`**++On `.compile`, the optimizer:++1. **Initializes the teacher.** If no teacher passed, `student.deepcopy()`. If the teacher is uncompiled and `max_labeled_demos > 0`, applies `LabeledFewShot(k=max_labeled_demos)` so the teacher has demos to bootstrap from.+2. **Walks the trainset.** For each example, runs up to `max_rounds` attempts. Each round strips the current example from every predictor’s demos, copies the LM with `rollout_id=round, temperature=1.0`, and calls the teacher.+3. **Scores via the metric.** Calls `metric(example, prediction, trace)`. A truthy return (or numeric `>= metric_threshold` when set) marks the trace as passing. Exceptions in the teacher or metric increment an error counter; exceeding `max_errors` raises.+4. **Extracts demos from passing traces.** For each predictor invocation in the trace, builds a `dspy.Example(augmented=True, **inputs, **outputs)` and stores it under that predictor’s name.+5. **Assigns demos.** For each predictor: the first `max_bootstrapped_demos` slots get augmented demos; the rest, up to `max_labeled_demos`, get raw labeled examples sampled from the unbootstrapped portion of the trainset.++Returns a new compiled module; the student is unmodified.++**`metric_threshold`** is a numeric floor for float-returning metrics. Without it, the metric’s return is coerced to bool. Pass `metric_threshold=0.5` to mean “pass if score >= 0.5.”++**`teacher_settings`** is a dict merged onto `dspy.settings` for the duration of teacher calls — useful when the teacher needs a different LM or adapter than the student.++### `BootstrapFewShotWithRandomSearch` (`BootstrapRS`) — candidate search++**`dspy.BootstrapFewShotWithRandomSearch(metric, teacher_settings=None, max_bootstrapped_demos=4, max_labeled_demos=16, max_rounds=1, num_candidate_programs=16, num_threads=None, max_errors=None, stop_at_score=None, metric_threshold=None)`**+**`.compile(student, *, teacher=None, trainset, valset=None, restrict=None, labeled_sample=True)`**++Generates `num_candidate_programs` candidates and picks the winner. Three of those seeds are pinned baselines:++- `seed=-3`: zero-shot (no demos).+- `seed=-2`: `LabeledFewShot(k=max_labeled_demos)` alone.+- `seed=-1`: `BootstrapFewShot` with the unshuffled trainset.++The remaining seeds shuffle the trainset and vary the bootstrap demo count. Each candidate gets evaluated on `valset` (defaults to trainset). Returns the highest-scoring candidate, with `best_program.candidate_programs` carrying the full ranked list of `(seed, program, score, subscores)` tuples for inspection.++`stop_at_score=N` short-circuits once a candidate’s valset score meets `N`. Use this when “good enough” is well-defined and you’d rather save the rest of the budget.++`num_threads` parallelizes candidate evaluation, not the bootstrap step.++### `KNNFewShot` — inference-time demo retrieval++**`dspy.KNNFewShot(k, trainset, vectorizer, **bootstrap_kwargs)`**+**`.compile(student, *, teacher=None)`**++The constructor embeds the entire trainset via `vectorizer` (a `dspy.Embedder`) and stores a `dspy.KNN(k, trainset, vectorizer)` instance. `.compile` overrides the student’s `forward` so each call:++1. Embeds the new input.+2. Retrieves the `k` nearest training examples.+3. Constructs a fresh `BootstrapFewShot(**bootstrap_kwargs)` and compiles a one-call program against those `k` examples.+4. Runs the compiled program on the input.++The trainset embedding is fixed at construction; changing the trainset means re-constructing the optimizer. Inference cost is amplified: every forward call runs a mini-compilation.++### `InferRules` — rule extraction on top of bootstrap++**`dspy.InferRules(num_candidates=10, num_rules=10, num_threads=None, teacher_settings=None, **bootstrap_kwargs)`**+**`.compile(student, *, teacher=None, trainset, valset=None)`**++Extends `BootstrapFewShot`. After running the base bootstrap once, it:++1. **Copies the bootstrapped student** `num_candidates` times.+2. **For each copy**, asks the teacher LM to read the bootstrapped demos and produce `num_rules` natural-language rules per predictor. The rules come from a `ChainOfThought` over a `RulesInductionProgram` signature (`examples_text -> natural_language_rules`).+3. **Appends the rules** to each predictor’s `signature.instructions`, after a “Please adhere to the following rules...” preamble.+4. **Evaluates each candidate on `valset`** and returns the best.++The rules are visible and editable — you can read them, decide which to keep, and treat the optimizer’s output as a starting point rather than a finished program.++## Cross-links++- [Optimizers: choosing one](choosing-an-optimizer.md) — the selection guide; describes when each family member wins against optimizers outside the family.+- [Metrics and evaluation](metrics-and-evaluation.md) — the metric shape every bootstrap variant uses, and the failure-score behavior that keeps one bad example from breaking a long bootstrap.+- [Modules: composing your own](modules.md) — `predictor.demos`, `_compiled` flags, and `deepcopy()` behavior, all of which the bootstrap family relies on.+- [GEPA in depth](gepa-in-depth.md) — the instruction-optimization counterpart; combine via `dspy.BetterTogether` when both knobs need to turn.diff --git a/docs/docs/diving-deeper/built-in-module-variants.md b/docs/docs/diving-deeper/built-in-module-variants.mdnew file mode 100644index 000000000..f5b00d5ee--- /dev/null+++ b/docs/docs/diving-deeper/built-in-module-variants.md@@ -0,0 +1,101 @@+# Built-in module variants++## Intent++`Predict`, `ChainOfThought`, and `ReAct` cover most programs, but DSPy ships a handful of other modules for situations where one LM call is not enough, or where reasoning needs a Python runtime, or where you want to fan out across examples. This page collects those modules, groups them by what they’re for, and gives selection guidance so you know which one to reach for when.++Read this when a plain `Predict` or `ChainOfThought` isn’t getting you there and you’re trying to decide between sampling more, comparing drafts, executing code, or running the same module in parallel.++## Design decisions++### 1. These variants wrap the spine; they don’t replace it++`BestOfN` and `Refine` take a module and sample it. `MultiChainComparison` consumes completions produced by an outer `Predict`. `ProgramOfThought` and `CodeAct` hold internal `ChainOfThought` predictors. The variants are recipes built on the spine, not parallel implementations of it. Before reaching for one, ask whether the question is “I need more of what `Predict` already does” or “I need something `Predict` can’t do at all” — the answer is usually the former, and that’s the case these handle.++### 2. Sampling-and-aggregating modules vary one thing: the rollout ID++Both `BestOfN` and `Refine` deep-copy the wrapped module per attempt and swap in an LM copy with `rollout_id = start + i` and `temperature=1.0`. The rollout ID is what makes each sample produce a different output despite the same inputs — DSPy threads it into the LM cache key so the model resamples instead of replaying a cached response. Temperature is forced to 1.0 regardless of the LM’s default, because sampling is the point.++### 3. Reward functions are metrics graded at inference time++The signature `reward_fn(args, pred) -> float` mirrors the inference-time metric shape, but it does not need a gold example — it scores the prediction against the call’s inputs. The same function shape is reusable as a training metric, but a reward is graded *now* and decides which sample to keep, while a metric is graded *later* and decides which program to keep. The two roles overlap in shape and diverge in purpose.++### 4. `MultiChainComparison` expects pre-generated completions as its input++`forward(completions, **kwargs)` takes the completions as a positional argument rather than producing them. The caller produces M samples through a separate `Predict` (typically with `n=M`) and hands them in. Splitting sampling from judging keeps the two concerns independent: the completions could come from different LMs, from cache, or from earlier signatures — none of which `MultiChainComparison` needs to know about.++### 5. `ProgramOfThought` and `CodeAct` ship with a Python interpreter++Both rely on `PythonInterpreter`, which runs LM-generated code in a sandbox via Deno’s WASM runtime. Deno isolation is the reason: the LM’s code runs in a process with no filesystem or network access by default, so executing untrusted output is bounded. Installing Deno is a hard dependency for both modules; the constructor raises if Deno isn’t available.++### 6. `CodeAct` is `ReAct` plus a code sandbox++The class literally inherits from both: `class CodeAct(ReAct, ProgramOfThought)`. The combination matters because some tasks need both the iterative loop of ReAct (think → act → observe) and the expressive power of writing Python (loops, list comprehensions, library calls). Tools are passed as plain `def` functions and dropped into the sandbox via `inspect.getsource`, so the LM calls them as regular Python rather than as JSON-shaped tool calls.++### 7. `Parallel` is a runner, not a `Module`++It exposes a `forward(exec_pairs)` method but isn’t a `Module` subclass. It doesn’t hold predictors, doesn’t serialize, doesn’t appear in `named_predictors`. The work isn’t “an LM call I’m doing on your behalf” — it’s “a batch of LM calls you’ve assembled, run in parallel.” Keeping it outside the Module tree means optimizers and `dump_state` ignore it, which is what you’d want from a runner.++### 8. `dspy.Parallel` and `Module.batch` overlap on purpose++Both run modules in parallel using the same `ParallelExecutor` underneath. The difference is what they accept: `Module.batch(examples)` takes one module and many examples; `dspy.Parallel()(exec_pairs)` takes many `(module, example)` pairs. Use `Module.batch` for the common case — evaluating one program on a dataset; reach for `Parallel` when the modules differ across examples or you want fine-grained control over which pair runs where.++### 9. `majority` is the no-LM aggregator++A plain function — no LM call, no signature, no `dspy.Module`. It tallies completions and returns the most-common normalized value (with `default_normalize` folding case and whitespace). Aggregation should not look like a step that calls a model, so the API is a function call, not a module constructor. Pair it with a multi-sample `Predict` or with `BestOfN`‘s `pred.completions` when the task has a discrete answer.++### 10. `RLM` is marked experimental for a reason++The class is decorated with `@experimental` and the interface is still in flux. It composes a code sandbox with built-in `llm_query` / `llm_query_batched` tools that let generated code call a separate sub-LM mid-execution. The mental model is a Python REPL the LM drives, with another LM available as a callable inside. Useful, but the boundary conditions — max call counts, sandbox lifetime, error recovery — are still being worked out.++## API walkthrough++Grouped by what you’re trying to do.++### Sampling and aggregating++For when one LM call has too much variance. Sample several, then pick or combine.++**`dspy.BestOfN(module, N, reward_fn, threshold, fail_count=None)`**+On `forward(**kwargs)`, `BestOfN` deep-copies the wrapped module per attempt, swaps in a fresh LM with `rollout_id = start + i` and `temperature=1.0`, and runs the call inside a `dspy.context(trace=[])` block so the per-attempt trace is isolated. It scores `reward_fn(kwargs, pred)`, keeps the best so far, and short-circuits when a reward meets `threshold`. After the loop, the winning attempt’s trace is merged back into the parent `dspy.settings.trace` — so a caller inspecting the trace sees the winning path, not all `N`. Failures decrement `fail_count` (defaults to `N`); exhausting it re-raises.++**`dspy.Refine(module, N, reward_fn, threshold, fail_count=None)`**+Same shape as `BestOfN`, with feedback generation between attempts. After a failed attempt, `Refine` builds a snapshot — the module’s source code, per-predictor signatures, per-predictor I/O from the trace, the reward function’s source — and feeds it to an internal `dspy.Predict(OfferFeedback)`. That call returns advice keyed by module name. On the next attempt, `Refine` wraps the active adapter so each sub-predictor’s signature gains a `hint_` input field carrying its slice of the advice. The wrapping is scoped via `dspy.context(adapter=...)`, so the wrapped adapter exists only for that attempt and the hints don’t leak into the final trace.++**`dspy.majority(prediction_or_completions, normalize=default_normalize, field=None)`**+A standalone function. Accepts a `Prediction` (it uses `prediction.completions`), a `Completions` object, or a plain list. The `field` defaults to the *last* output field of the signature — the convention being that the last field is the answer. Values pass through `normalize` (lowercase + whitespace by default) and the most-common normalized value wins; ties go to the earlier completion. Returns a single-completion `Prediction` wrapping the winner.++### Comparing pre-generated drafts++**`dspy.MultiChainComparison(signature, M=3, temperature=0.7, **config)`**+The constructor mutates the input signature: it prepends one output field (a synthesized `rationale`) and appends M input fields named `reasoning_attempt_1` through `reasoning_attempt_M`. It then builds an internal `Predict` over the modified signature. At call time, `forward(completions, **kwargs)` reads each completion’s `rationale` (or `reasoning`) and the last output field, formats them as one-line attempt strings, and supplies them as the new inputs. The LM is asked to reason holistically across attempts and produce one synthesized answer in the original output field. The number of supplied completions must equal `M`; an assertion enforces this.++### Generating and running code++For tasks where the answer is best computed, not narrated.++**`dspy.ProgramOfThought(signature, max_iters=3, interpreter=None)`**+Holds three internal `ChainOfThought` predictors: `code_generate` produces Python, `code_regenerate` rewrites it after an execution error, and `generate_output` extracts the declared output fields from the run’s printed result. The forward loop asks `code_generate` for code, runs it through the `PythonInterpreter`, and on error feeds the error message back to `code_regenerate` for up to `max_iters` rounds. Once execution succeeds, `generate_output` produces the signature’s output fields. If `max_iters` is exhausted, the module raises.++**`dspy.CodeAct(signature, tools, max_iters=5, interpreter=None)`**+Multiple inheritance from `ReAct` and `ProgramOfThought`. Tools must be plain `def` functions, not callable objects — the module reads `inspect.getsource(tool.func)` and injects each definition into the sandbox at the start of every `forward`. Each iteration: an inner `codeact` predictor produces Python plus a `finished` boolean; the interpreter runs the code; the trajectory dict gains a `generated_code_i` and `code_output_i` (or `observation_i` on parse/execution error). The loop exits when the LM sets `finished=True` or `max_iters` is reached. A `ChainOfThought` extractor then reads the trajectory and produces the declared outputs.++**`dspy.RLM(signature, max_iterations=20, max_llm_calls=50, max_output_chars=10_000, verbose=False, tools=None, sub_lm=None, interpreter=None)`**+Experimental. A REPL-style code agent that exposes two built-in tools — `llm_query` and `llm_query_batched` — so generated code can call a separate `sub_lm` mid-execution. A shared counter across iterations enforces `max_llm_calls`; tool names are validated as Python identifiers; `SandboxSerializable` inputs encode into the sandbox so large contexts don’t have to be re-marshalled each turn. If the loop ends without an explicit submission, the extractor pass produces the final outputs from the trajectory.++### Running modules in parallel++**`dspy.Parallel(num_threads=None, max_errors=None, access_examples=True, return_failed_examples=False, provide_traceback=None, disable_progress_bar=False, timeout=120, straggler_limit=3)`**+Wraps `ParallelExecutor` and submits each `(module, example)` pair to a thread pool. The example can be a `dspy.Example` (unpacked via `.inputs()` when `access_examples=True`), a `dict` (unpacked as kwargs), a tuple (unpacked positionally), or a list (passed through when the module is itself a `Parallel`). The executor snapshots the parent’s `thread_local_overrides` and re-applies it inside each worker, so a surrounding `dspy.context(...)` is honored. Returns predictions in input order; with `return_failed_examples=True`, returns a `(results, failed_examples, exceptions)` tuple.++### Related modules covered elsewhere++**`dspy.KNN`** is a retrieval helper, not a generation module — see the Retrievers reference page.++**`dspy.ReAct`** is the canonical tool-using loop and has its own page: [Tools, ReAct, and MCP](tools-react-and-mcp.md). The wrapping machinery there is what `CodeAct` and `RLM` reuse.++## Cross-links++- [Modules: composing your own](modules.md) — every variant here is a `dspy.Module` (except `Parallel` and `majority`), so the composition rules apply.+- [Tools, ReAct, and MCP](tools-react-and-mcp.md) — `CodeAct` and `RLM` use the same tool-wrapping machinery as `ReAct`.+- [Settings and `context()`](settings-and-context.md) — how `Parallel` and `Module.batch` snapshot the active overrides into each worker.diff --git a/docs/docs/diving-deeper/choosing-an-optimizer.md b/docs/docs/diving-deeper/choosing-an-optimizer.mdnew file mode 100644index 000000000..cca090c54--- /dev/null+++ b/docs/docs/diving-deeper/choosing-an-optimizer.md@@ -0,0 +1,144 @@+# Optimizers: choosing one++## Intent++DSPy ships a dozen optimizers (teleprompters), and the most-asked DSPy question is “which one should I use?” This page is the selection guide: what each optimizer tunes, what it needs at compile time, what it costs, and when it wins against the alternatives.++Read this once you have a working program and a metric, and you’re trying to decide what to compile against. The deep-dive pages on individual optimizers (GEPA, the BootstrapFewShot family, BootstrapFinetune) live alongside this one.++## Design decisions++### 1. Every optimizer tunes one or more of: instructions, demos, or weights++The three knobs cover every search space DSPy exposes. Instructions are the natural-language docstring on each predictor’s signature. Demos are the in-context examples each predictor sees at call time. Weights are the model parameters when the LM is tunable. Each optimizer picks one or two of these and leaves the rest alone; the API walkthrough below groups them by which knob they turn.++### 2. `.compile()` returns a new copy; the original student isn’t mutated++The first thing every optimizer does is `student.reset_copy()` — a deepcopy that also clears inherited `_compiled` flags. The compiled program is returned; the original you passed in stays untouched. You can re-run `.compile()` on the same student with different optimizers, datasets, or budgets and compare results without worrying about state leak between runs.++### 3. `_compiled=True` is the flag that tells future optimizers to leave a sub-module alone++After a successful `.compile()`, the optimizer sets `_compiled = True` on the returned module. When you wrap that compiled module inside a bigger program and run a second optimizer on the outer one, `named_parameters()` skips the inner compiled module — its predictors stay as the first optimizer left them. The flag is what enables “optimize inner → embed in outer → optimize outer.”++### 4. Every optimizer takes a `metric`, but the required metric shape varies++All optimizers read a numeric score per example. Most are happy with a bare float or boolean. GEPA additionally needs `Prediction(score, feedback)` because it threads the natural-language critique into its proposals. Picking the wrong metric shape for the wrong optimizer is the most common configuration mistake — check the optimizer’s page when in doubt.++### 5. GEPA is the only optimizer that reads `Prediction(score, feedback)` per predictor++The other instruction optimizers (COPRO, MIPROv2) treat the metric as a black-box scalar — they only know whether candidate-A scored higher than candidate-B. GEPA reads `feedback` from each metric call and threads it into the next instruction proposal. The other side of the same coin: when you don’t have a feedback-rich metric, COPRO or MIPROv2 may give better mileage than GEPA on the same budget.++### 6. Prompt-only optimizers work with any LM; finetune optimizers need a tunable model++BootstrapFewShot, COPRO, MIPROv2, GEPA, and most others mutate prompts and demos — the LM stays untouched, so closed-source providers are fair game. `BootstrapFinetune` writes new model weights and requires an LM that exposes a fine-tuning API (a local trainer, an open-source model, or a provider like OpenAI’s fine-tuning endpoint). The split decides which optimizers are even available to you.++### 7. Demo-tuning tends to overfit; instruction-tuning tends to generalize++A demo set learned on 50 training examples describes that specific trainset. Inputs that don’t resemble those examples may not benefit. An instruction rewrite, by contrast, captures patterns at a level above the examples and tends to transfer. Not a universal law, but a useful default: if your evaluation set is small or skewed, lean toward instruction optimization.++### 8. Most teams start prompt-only and graduate to finetune only when prompt-only plateaus++Prompt-only optimization costs LM tokens. Finetune costs LM tokens plus training compute plus deployment of new weights. The marginal lift of finetune over GEPA or MIPROv2 is usually small and sometimes negative, while the marginal cost is much larger. Treat finetune as the last lever, not the first.++### 9. The “compile once, save, reload” loop is what makes the optimizer cost amortize++`.compile()` is expensive — GEPA and MIPROv2 can spend hundreds of dollars in LM calls on a single run. The output is a portable artifact (`program.save(path)`); inference against it is cheap. The economics work only when you compile once per program version and serve the saved artifact many times.++### 10. There’s no LM-based auto-selection — you choose++DSPy doesn’t introspect your task or LM to pick an optimizer. The `auto` knobs on MIPROv2 and GEPA only control budget within an optimizer, not which optimizer to use. The selection cheat sheet at the bottom of this page is the closest thing to a recommendation engine.++## A two-axis decision++Two questions narrow the field fast.++**What’s the bottleneck — instructions, demos, or weights?**+If the prompt wording is wrong, instruction optimizers (COPRO, GEPA, MIPROv2) help. If the model needs examples to anchor format and style, demo optimizers (BootstrapFewShot, BootstrapRS) help. If the model itself is the limit and you can fine-tune it, weight tuning (BootstrapFinetune) is the lever.++**What’s your compute budget?**+Zero-config baselines (LabeledFewShot, BootstrapFewShot) cost almost nothing. Search-based optimizers (BootstrapRS, MIPROv2, GEPA) cost real money. Combined optimizers (BetterTogether) pay both bills.++## API walkthrough++Grouped by what each optimizer tunes.++### Start here++The two-line baselines. Try one of these before reaching for anything heavier.++**`dspy.LabeledFewShot(k=16)`**+No LM calls during `.compile()`. Samples up to `k` examples from the trainset (random by default, deterministic when `sample=False`) and attaches them as demos to each predictor. Reach for it as the honest baseline: if `LabeledFewShot` already gets you where you need to be, heavier optimization is wasted effort.++**`dspy.BootstrapFewShot(metric=None, metric_threshold=None, teacher_settings=None, max_bootstrapped_demos=4, max_labeled_demos=16, max_rounds=1)`**+Runs the program (or a `teacher` you supply) on training examples, scores each completion with the metric, and keeps the traces where the metric passes. Those successful traces become the demos. The combined set mixes up to `max_bootstrapped_demos` bootstrapped traces with up to `max_labeled_demos` raw labeled examples per predictor. Almost always beats zero-shot when the metric is reliable; the safe first try.++### Search across demo sets++When one bootstrap pass isn’t enough.++**`dspy.BootstrapFewShotWithRandomSearch(metric, max_bootstrapped_demos=4, max_labeled_demos=16, max_rounds=1, num_candidate_programs=16, num_threads=None, stop_at_score=None)`**+Aliased as `dspy.BootstrapRS`. Runs `BootstrapFewShot` `num_candidate_programs` times with different random seeds, evaluates each candidate on a valset, and returns the highest-scoring one. The randomness comes from which traces get bootstrapped first — different seeds discover different demo subsets. `stop_at_score` short-circuits when a candidate clears a target.++**`dspy.KNNFewShot(k, trainset, vectorizer, **bootstrap_kwargs)`**+The demos are chosen at *inference* time, not compile time. At construction, the trainset is embedded via `vectorizer` and cached. On each call, the input is embedded, the `k` nearest training examples are retrieved, and those become the demos for that single call. Worth the indirection when no single demo set generalizes across the input distribution.++### Optimize instructions++When the prompt wording — not the examples — is what’s holding you back.++**`dspy.COPRO(prompt_model=None, metric=None, breadth=10, depth=3, init_temperature=1.4, track_stats=False)`**+A breadth-first proposer. At each of `depth` levels, COPRO uses `prompt_model` to generate `breadth` candidate instructions per predictor, scores them against the trainset, and keeps the best. Total LM cost is roughly `breadth × depth × num_predictors`. Lightweight; especially good when demos are already strong and you only need to fix wording.++**`dspy.GEPA(metric, auto=None, max_full_evals=None, max_metric_calls=None, reflection_lm=None, skip_perfect_score=True, instruction_proposer=None, use_merge=True, num_threads=None)`**+Evolutionary instruction search guided by reflection. GEPA maintains a population of programs, runs each on the trainset, reads the per-predictor `feedback` from the metric, and uses `reflection_lm` to propose edits informed by that feedback. It returns the best candidate from a Pareto frontier. Wins on prompt-only optimization when you have a strong reflection LM and a feedback-shaped metric; see [GEPA in depth](gepa-in-depth.md) for the full mechanics.++### Optimize instructions and demos together++**`dspy.MIPROv2(metric, prompt_model=None, task_model=None, teacher_settings=None, max_bootstrapped_demos=4, max_labeled_demos=4, auto="light", num_candidates=None, num_threads=None, init_temperature=1.0, track_stats=True)`**+Bayesian-optimization search over the joint instruction + demo space. The `prompt_model` (often a stronger LM) proposes instructions; the `task_model` (your student) runs the program. `auto` (`"light"` / `"medium"` / `"heavy"`) translates into a budget for both proposals and evaluations. State of the art when both instructions and demos need tuning together.++**`dspy.SIMBA(metric, bsize=32, num_candidates=6, max_steps=8, max_demos=4, prompt_model=None, teacher_settings=None, num_threads=None)`**+Mini-batch SGD-flavored search. Each step samples a `bsize` minibatch, finds the worst-scoring examples, and uses `prompt_model` to propose either a natural-language rule (instruction patch) or a new demo to address them. The mini-batch focus makes SIMBA reactive: each step targets the current weak spot rather than the average case.++**`dspy.InferRules(num_candidates=10, num_rules=10, num_threads=None, **bootstrap_kwargs)`**+Extends `BootstrapFewShot`. After bootstrapping demos, asks a teacher LM to read them and extract `num_rules` general rules, then appends those rules to the predictor’s instructions. The rules are interpretable — you can read them and decide whether to keep them. Useful when the task has patterns you want stated explicitly rather than inferred from examples.++### Fine-tune the weights++**`dspy.BootstrapFinetune(metric=None, multitask=True, train_kwargs=None, adapter=None, exclude_demos=False, num_threads=None)`**+Bootstraps successful traces the same way `BootstrapFewShot` does, then writes them as training data and fine-tunes the student LM on them. Requires an LM with a `.finetune()` method — open-source LMs through providers like Together AI, OpenAI’s fine-tuning API, or a local trainer. `multitask=True` trains one model across all predictors; `False` trains a separate model per predictor.++### Compose optimizers++**`dspy.BetterTogether(metric, **optimizers)`**+A meta-optimizer that runs a sequence specified as a string like `"p -> w -> p"` — prompt optimization, then weight tuning, then prompt optimization again. The `optimizers` kwargs map letters to optimizer instances (`p=GEPA(...)`, `w=BootstrapFinetune(...)`). Defaults to `BootstrapRS` for `p` and `BootstrapFinetune` for `w`. Reach for it when prompt-only and weight-only have both been tried and you suspect they compose.++**`dspy.Ensemble(reduce_fn=None, size=None, deterministic=False)`**+Not an optimizer in the usual sense — it composes already-compiled programs into one. `.compile(programs)` returns a module that runs each input through every program in parallel and reduces with `reduce_fn` (a custom function; defaults to majority voting via `dspy.majority`). Useful when several optimizer runs each produce a competent candidate and you want to combine them at inference time.++### Specialized++**`dspy.AvatarOptimizer(metric, max_iters=10, lower_bound=0, upper_bound=1, max_positive_inputs=10, max_negative_inputs=10, optimize_for="max")`**+Built for agent-style programs. Partitions the trainset by metric into positive examples (high scores) and negative examples (low scores). On each iteration, asks an LM to read positive and negative examples and propose instruction edits that explain the difference, then evaluates the new instructions. Niche but useful when the metric is a clean pass/fail and you need readable agent instructions.++## Selection cheat sheet++| Situation | Try |+|---|---|+| Just starting; no idea what helps | `BootstrapFewShot` |+| Demos vary in quality across attempts | `BootstrapFewShotWithRandomSearch` |+| Large trainset; inputs need different demos | `KNNFewShot` |+| Instructions look wrong; demos look fine | `COPRO` or `GEPA` |+| Both look weak; you have budget | `MIPROv2` or `GEPA` |+| Failure cases share a pattern you can name | `SIMBA` or `InferRules` |+| Prompt-only has plateaued; the model is tunable | `BootstrapFinetune` |+| You want to combine prompt + weight tuning | `BetterTogether` |+| You have multiple competent programs to combine | `Ensemble` |+| Agent / tool-use task | `AvatarOptimizer` or `GEPA` |++## Cross-links++- [Metrics and evaluation](metrics-and-evaluation.md) — every optimizer compiles against a metric defined there; the `Prediction(score, feedback)` shape GEPA expects is documented there.+- [GEPA in depth](gepa-in-depth.md) — the deep dive on the optimizer above.+- [BootstrapFewShot family](bootstrap-fewshot-family.md) — the deep dive on `BootstrapFewShot` and its random-search variants.+- Fine-tuning with `BootstrapFinetune` — the deep dive on weight tuning.diff --git a/docs/docs/diving-deeper/gepa-in-depth.md b/docs/docs/diving-deeper/gepa-in-depth.mdnew file mode 100644index 000000000..eaae78034--- /dev/null+++ b/docs/docs/diving-deeper/gepa-in-depth.md@@ -0,0 +1,139 @@+# GEPA in depth++## Intent++GEPA is DSPy’s reflection-driven instruction optimizer. It maintains a population of candidate programs, scores each on a validation set, and uses an LLM “reflection” step to propose instruction edits informed by per-predictor natural-language feedback from your metric. The Pareto-frontier sampling and reflective proposal mechanics are what distinguish it from COPRO and MIPROv2; the metric contract — `dspy.Prediction(score, feedback)` — is what makes the feedback channel work at all.++Read this when the selection guide has pointed you at GEPA and you want the full mechanics: how the budget translates into evaluations, how feedback reaches the reflection LM, what `auto` modes actually buy, and what `detailed_results` carries when you track stats.++## Design decisions++### 1. The metric is the feedback channel — return `Prediction(score, feedback)`, not a bare float++GEPA reads the metric’s `feedback` field directly into the reflection prompt. A plain-float metric still works, but the proposer sees only a generic “This trajectory got a score of {n}” caption — concrete failure modes never reach it. GEPA doesn’t error on a float; it just gives you a much weaker version of itself.++### 2. Reflection is the proposal mechanism, not the evaluation mechanism++`reflection_lm` is called once per mutation to read low-scoring traces and emit a new instruction. Score evaluation runs through whatever LM the program is configured with (`task_model`). Two roles, two budgets: reflection is rare and benefits from a strong LM; evaluation is frequent and benefits from a cheap one. Passing `reflection_lm=dspy.LM("openai/gpt-4o")` while running the program on `gpt-4o-mini` is the standard configuration.++### 3. Only one of `auto`, `max_full_evals`, or `max_metric_calls` may be set++GEPA enforces this at construction. The three knobs are different units of the same budget: `auto` is a preset (light / medium / heavy), `max_full_evals` is “this many passes over trainset + valset,” `max_metric_calls` is the raw ceiling on metric invocations. Pick one shape and let GEPA derive the others.++### 4. The Pareto frontier is the search space; the aggregate score is the winner++GEPA tracks every candidate it ever proposed, with per-example scores. When picking the next program to mutate, it samples stochastically from the per-example Pareto frontier — programs that score best on at least one example. When returning a winner from `.compile()`, it picks the single program with the highest aggregate score. The frontier is for exploration; the aggregate is for selection.++### 5. Per-predictor feedback comes through `pred_name` and `pred_trace`++For each predictor GEPA wants to update, it calls the metric twice: once at module level (`pred_name=None`, `pred_trace=None`) for the aggregate score, and once with `pred_name="my_predictor"` and `pred_trace=[(predictor, inputs, outputs)]` (the sub-trace of just that predictor’s call). The metric can grade that step in isolation; most users return the same module-level score for both, and that’s fine. `warn_on_score_mismatch=True` (default) logs when the two diverge.++### 6. `skip_perfect_score=True` keeps reflection focused on what’s broken++Examples scoring at `perfect_score` (default `1.0`) drop out of the reflective minibatch. The reflection LM then sees only failures, which is what you want — proposals informed by perfect runs would suggest changes to working behavior. Lower `perfect_score` if your metric saturates below `1.0`.++### 7. `use_merge=True` combines successful candidates++When two candidates each win on different examples, merging proposes a new candidate that inherits instructions from both. Merging costs one re-evaluation per attempt; `max_merge_invocations` (default 5) caps the total. Set it to `None` to disable. Worth keeping on for most runs — merges find combinations the proposer wouldn’t.++### 8. The default `component_selector` is round-robin across predictors++On each iteration, GEPA picks one predictor to update. Round-robin cycles through them. `"all"` updates every predictor at once — saves iterations when predictors are tightly coupled. A custom `ReflectionComponentSelector` lets you target hot predictors. Round-robin is the safe default.++### 9. Threading is per-batch, not per-mutation++`num_threads` parallelizes the metric calls inside each evaluation pass; the mutation loop itself is serial. Scaling threads helps when the valset is large and the metric is slow, not when the reflection step is the bottleneck. If `reflection_lm` is your slow path, more threads do nothing.++### 10. `detailed_results` is the audit trail++When `track_stats=True`, the compiled program’s `detailed_results` carries every candidate, every parent in the lineage, every per-example score, and when each candidate was discovered. Use it to understand whether GEPA exhausted its budget productively or burned cycles on near-duplicates.++### 11. The winner’s instructions overwrite the student’s signatures++`.compile()` returns a Module with the best candidate’s instructions baked into each predictor’s `signature.instructions`. Nothing else moves — demos, callbacks, and sub-modules stay as the student had them. `program.save(path)` writes the instructions; loading on a different machine reapplies them.++### 12. Reflection LM cost dominates if you’re not careful++A `medium` budget on a 2-predictor / 100-example task means ~12 mutations, each spawning 1–3 reflection calls depending on minibatch size and number of components — so ~12–36 calls to `reflection_lm`. With `gpt-4o` reflecting and `gpt-4o-mini` running the program, reflection often costs more than evaluation. Budget accordingly.++## API walkthrough++Grouped by what you’re trying to do.++### The optimizer++**`dspy.GEPA(metric, *, auto=None, max_full_evals=None, max_metric_calls=None, reflection_minibatch_size=3, candidate_selection_strategy="pareto", reflection_lm=None, skip_perfect_score=True, add_format_failure_as_feedback=False, instruction_proposer=None, component_selector="round_robin", use_merge=True, max_merge_invocations=5, num_threads=None, failure_score=0.0, perfect_score=1.0, log_dir=None, track_stats=False, use_wandb=False, use_mlflow=False, seed=0, ...)`**++Takes a feedback-shaped metric, a budget (exactly one of `auto` / `max_full_evals` / `max_metric_calls`), and a `reflection_lm` (defaults to the globally-configured LM — you’ll often want to pass a stronger one). `candidate_selection_strategy="current_best"` switches off Pareto sampling and turns GEPA into greedy local search. `failure_score` is the score assigned when the metric raises; `perfect_score` is the threshold for `skip_perfect_score`.++**`GEPA.compile(student, *, trainset, valset=None, ...)`** → `dspy.Module`+Runs the search. `valset` defaults to `trainset` when not provided. Returns a fresh Module whose predictors carry the best candidate’s instructions; sets `_compiled = True`.++### Budget translation++How a budget number turns into LM calls.++**`auto`** — light / medium / heavy preset+Maps to `num_candidates = 6 / 12 / 18` and derives the metric-call budget from your valset size. The conversion accounts for the initial full eval, bootstrapping (`5 × num_candidates`), per-candidate minibatch evals, and periodic full evals every 5 steps. On a 2-predictor / 100-example task: light ≈ 1330 calls, medium ≈ 1740, heavy ≈ 2045.++**`max_full_evals`** — pass-count budget+Each “full eval” is one walk through the union of trainset and valset. GEPA computes `max_metric_calls = max_full_evals × (len(trainset) + len(valset))` internally.++**`max_metric_calls`** — raw cap+Direct ceiling on metric invocations. Use this when you’ve measured per-call cost and want a hard dollar cap.++### The reflective loop++**Metric shape** — `metric(gold, pred, trace, pred_name, pred_trace) -> dspy.Prediction(score, feedback)`+Called twice per evaluated example: once at module level (`pred_name=None`, `pred_trace=None`) for the aggregate, once per predictor under mutation (`pred_name="..."`, `pred_trace=[(predictor, inputs, outputs)]`) for per-predictor feedback. Return `dspy.Prediction(score: float, feedback: str)`. The `feedback` string is what reaches the reflection prompt verbatim.++**`reflection_lm`** — the LM that proposes new instructions+Reads a minibatch of low-scoring traces and emits a candidate instruction for the selected predictor. Defaults to the globally configured LM; passing a stronger one explicitly is the most common GEPA tuning. Called serially per mutation — threading doesn’t help here.++**`reflection_minibatch_size`** — examples shown to the reflection LM per mutation+Default `3`. Larger minibatches give the proposer more context (better proposals) at the cost of longer reflection prompts (more tokens).++**`instruction_proposer`** — custom proposer hook+A callable matching the `gepa.ProposalFn` protocol: takes a `{predictor_name: current_instruction}` dict, a reflective dataset of low-scoring examples, and a list of components to update; returns a new `{predictor_name: new_instruction}` dict. Override when the default proposer doesn’t handle your modality (signatures with `dspy.Image` fields, say) or when you want domain-specific constraints on the instructions.++### Population dynamics++**`candidate_selection_strategy`** — `"pareto"` (default) or `"current_best"`+`"pareto"` samples next-mutation candidates stochastically from the per-example Pareto frontier. `"current_best"` always mutates the highest-aggregate candidate. Pareto explores more; current-best converges faster on simple tasks.++**`component_selector`** — `"round_robin"` (default), `"all"`, or a custom `ReflectionComponentSelector`+Which predictor to update on each iteration. Round-robin cycles; `"all"` updates every predictor at once. Custom selectors can target predictors by historical regret or any other policy.++**`use_merge` / `max_merge_invocations`**+Merging combines instructions from two successful candidates into a new candidate. Costs one re-evaluation per merge; `max_merge_invocations` (default 5) caps the total.++**`skip_perfect_score` / `perfect_score`**+Examples at `perfect_score` drop out of the reflective minibatch. Default `perfect_score=1.0`; set lower if your metric saturates below 1.++### Inspecting the run++**`compiled_program.detailed_results`** (when `track_stats=True`) → `DspyGEPAResult`++- `candidates: list[Module]` — every program ever proposed+- `parents: list[list[int] | None]` — lineage (`None` for seed, otherwise parent indices)+- `val_aggregate_scores: list[float]` — one per candidate+- `val_subscores: list[list[float]]` — per-candidate, per-example scores+- `per_val_instance_best_candidates: list[set[int]]` — which candidates won which example+- `discovery_eval_counts: list[int]` — metric calls consumed before each candidate appeared+- `best_idx: int` — index of the returned winner+- `best_candidate: Module` — same module GEPA returned from `.compile()`++Convert to a JSON-safe dict via `.to_dict()`.++**`log_dir`** — disk-side logging+When set, GEPA writes per-iteration logs to that directory: candidates, scores, proposed instructions. Useful for post-mortem on what the reflection LM was suggesting.++**`use_wandb` / `use_mlflow`**+Stream search progress to Weights & Biases or MLflow. Each candidate’s aggregate score is logged as an iteration step.++## Cross-links++- [Optimizers: choosing one](choosing-an-optimizer.md) — the selection guide that recommends GEPA for feedback-rich tasks.+- [Metrics and evaluation](metrics-and-evaluation.md) — the `Prediction(score, feedback)` shape GEPA requires, and the LLM-as-judge pattern for building one.+- [Modules: composing your own](modules.md) — `_compiled` propagation and the deepcopy-then-mutate pattern GEPA uses on the student.+- [BootstrapFewShot family](bootstrap-fewshot-family.md) — the demo-tuning alternative; pair with GEPA via `BetterTogether` when both knobs need to turn.diff --git a/docs/docs/diving-deeper/metrics-and-evaluation.md b/docs/docs/diving-deeper/metrics-and-evaluation.mdnew file mode 100644index 000000000..56eb8fc8c--- /dev/null+++ b/docs/docs/diving-deeper/metrics-and-evaluation.md@@ -0,0 +1,113 @@+# Metrics and evaluation++## Intent++A DSPy metric is the function that turns a prediction into a number an optimizer can chase, and `dspy.Evaluate` is the harness that runs that metric across a dataset in parallel. This page covers the metric contract optimizers expect, the built-in string and LLM-judge metrics that ship with DSPy, and how `Evaluate` orchestrates a scoring run.++Read this when you’re writing your own metric, swapping in an LLM-as-judge for a rule-based one, choosing knobs on `Evaluate`, or troubleshooting why an optimizer reads your metric the way it does.++## Design decisions++### 1. A metric is any callable that takes `(gold, pred, ...)` and returns a score++The contract is duck-typed. No base class to subclass, no decorator to register a metric, no `@metric` marker. `Evaluate` calls whatever you pass it; the optimizer does the same. The benefit: an existing scoring function from any NLP or QA library wraps as a DSPy metric in one line. The price: the contract isn’t enforced — a callable that returns the wrong type fails at evaluation time, not at registration.++### 2. The full optimizer-facing signature is `(gold, pred, trace=None, pred_name=None, pred_trace=None)`++Most metrics declare only `(gold, pred)` and Python’s default-arg rules let optimizers pass the rest harmlessly. The optimizer fills in `trace` when it wants the metric to see how the program reached its answer, and fills in `pred_name` / `pred_trace` when it wants per-predictor scoring (GEPA does both). A metric written today against `(gold, pred)` keeps working when a future optimizer wants more — that’s why the extra args are tail-positioned defaults.++### 3. The return type can be `bool`, `float`, or `dspy.Prediction(score, feedback)` — each is handled differently++`Evaluate` aggregates booleans into a percentage and floats into a mean. A `Prediction` return is unpacked: `score` is averaged like a float, `feedback` is read only by GEPA. The three-shape return matters because the simplest metrics shouldn’t have to ceremoniously wrap their output in `Prediction`, but the optimizers that need richer signals shouldn’t be locked out either.++### 4. The `feedback` channel is for GEPA, not for `Evaluate`‘s score++A metric can attach a natural-language explanation to every score; only GEPA’s reflective loop reads it. `Evaluate` ignores it. The split keeps two concerns clean: “how good was this prediction” is one signal, “what’s a useful critique” is a different signal that costs nothing to omit when no optimizer is listening.++### 5. `trace` is the lever that lets a metric behave one way inside an optimizer and another way at eval time++The `SemanticF1` and `CompleteAndGrounded` judges return the raw F1 when `trace is None` (evaluation) and a binarized `score >= threshold` when `trace is not None` (optimization). The pattern: at eval time you want a continuous score; at optimization time you want a clean pass/fail signal the search can chase. The `trace` argument tells the metric which mode it’s in without forcing two separate functions.++### 6. Built-in string metrics centralize on `normalize_text`++`EM`, `F1`, `HotPotF1`, and the metric-shaped wrappers all call `normalize_text` on both prediction and reference: NFD-unicode, lowercase, drop English articles (`a` / `an` / `the`), strip punctuation, collapse whitespace. A single canonical normalization keeps token-level F1 and exact match operating on identical inputs — which matters because `answer_exact_match` switches between them based on its `frac` argument.++### 7. LLM judges are `dspy.Module` subclasses, not plain functions++`SemanticF1` and `CompleteAndGrounded` subclass `dspy.Module` so they can be inspected, traced, and even optimized like any other DSPy program. You could write a judge as a free function around `dspy.Predict`, but you’d lose the trace and history a Module gives you for free. The pattern: write a `dspy.Signature` whose outputs include `score: float` (and optionally `feedback: str`), wrap it in a Module whose `forward` returns a `Prediction(score, feedback)`.++### 8. `Evaluate` parallelizes through `ParallelExecutor`, not its own thread pool++The same executor that `dspy.Parallel` and `Module.batch` use. The benefit: settings propagation, error counting, straggler detection, and progress reporting are one implementation. A `dspy.context(lm=...)` block around an `Evaluate` call is honored inside every worker, because `ParallelExecutor` snapshots and re-applies `thread_local_overrides`.++### 9. Metric failures get a `failure_score`, not an exception++When the metric raises (or returns `None`), `Evaluate` substitutes `failure_score` (default `0.0`) for that example and keeps going. The reason: in a long evaluation, one bad example shouldn’t lose the score on the other 999. A `max_errors` knob caps how many failures the harness will tolerate before stopping.++### 10. `EvaluationResult` is the single return shape++`.score` is the aggregate (percent of `True` for booleans, mean for floats and `Prediction.score`), `.results` is the list of `(example, prediction, score)` triples. The legacy `return_outputs` / `return_all_scores` constructor kwargs were removed; passing them now raises `ValueError` with a migration message. One return shape means downstream code doesn’t have to switch on which keyword the caller used.++## API walkthrough++Grouped by what you’re trying to do.++### Metric anatomy++How DSPy calls your metric and what it expects back.++**The call signature** — `metric(gold, pred, trace=None, pred_name=None, pred_trace=None)`+`gold` is the labeled `dspy.Example`; `pred` is the `dspy.Prediction` the program produced. `trace` is a list of `(predictor, inputs, outputs)` triples covering the whole execution — filled in by optimizers when they want the metric to see how the program got there. `pred_name` and `pred_trace` narrow the same view to one predictor; GEPA uses these when scoring a single step of a multi-step program.++**`dspy.Prediction(score, feedback)`** — the score-with-feedback return shape+A `Prediction` with at least a `score` field, optionally a `feedback` field. `Evaluate` reads only `score`; GEPA reads both. Returning `Prediction(score=...)` from a plain metric works fine — `feedback` is optional, and the wrapper costs almost nothing when you only want a score.++### Built-in metrics for strings and tokens++The standard library of rule-based metrics, in `dspy/evaluate/metrics.py`.++**`dspy.evaluate.normalize_text(s: str)` → `str`**+NFD-unicode, lowercase, strip the English articles `a` / `an` / `the`, strip punctuation, collapse whitespace. The single canonical normalization shared by every string-comparison metric below.++**`dspy.evaluate.EM(prediction, answers_list)` → `bool`**+Exact match after `normalize_text` is applied to both sides. Returns `True` if any reference in `answers_list` matches. Raises if `answers_list` isn’t a list. The smallest metric primitive; useful as a building block in custom wrappers.++**`dspy.evaluate.answer_exact_match(example, pred, trace=None, frac=1.0)` → `bool`**+The metric-shaped wrapper. Reads `pred.answer` and `example.answer`, normalizes both, and dispatches to `EM` when `frac >= 1.0` or to F1-thresholded matching when `frac < 1.0`. Handles `example.answer` being a single string or a list of acceptable references.++**`dspy.evaluate.answer_passage_match(example, pred, trace=None)` → `bool`**+Retrieval evaluation. Returns `True` if any passage in `pred.context` contains any reference from `example.answer`. Uses a DPR-style normalizer for passages (which preserves more text) while still using `normalize_text` for answers.++**`F1` / `HotPotF1`** — token-level scorers (internal)+`F1` does token-level F1 over normalized strings, picking the max across references. `HotPotF1` adds one HotPotQA-specific rule: if either normalized side is `yes` / `no` / `noanswer` and the two disagree, return `0`. Both feed into `answer_exact_match` and are rarely called directly.++### LLM-as-judge metrics++For tasks where rule-based scoring can’t capture the right notion of correctness. Both live in `dspy/evaluate/auto_evaluation.py` and are `dspy.Module` subclasses.++**`dspy.evaluate.SemanticF1(threshold=0.66, decompositional=False)`**+A Module. `forward(example, pred, trace=None)` runs a `ChainOfThought` over `SemanticRecallPrecision` (or the decompositional variant) and asks the LM for `precision` and `recall` against `example.response` and `pred.response`. Computes `f1_score(precision, recall)`. Returns `Prediction(score=f1)` at eval time and `Prediction(score=(f1 >= threshold))` at optimization time — the same instance serves both modes.++**`dspy.evaluate.CompleteAndGrounded(threshold=0.66)`**+Runs two `ChainOfThought` calls: one for completeness (does `pred.response` cover `example.response`?), one for groundedness (is `pred.response` supported by `pred.context`?). Returns `Prediction(score=f1_score(groundedness, completeness))` with the same trace-based binarization as `SemanticF1`. Designed for retrieval-augmented programs.++**The general LLM-judge pattern.** Write a `dspy.Signature` whose outputs include `score: float` (and optionally `feedback: str`). Wrap it in a `dspy.Module` whose `forward(example, pred, trace=None)` calls the judge predictor and returns `Prediction(score, feedback)`. Use the `trace is None` toggle when you want different behavior inside optimization. That’s the whole recipe — both built-in judges are 20-line modules over this shape.++### The Evaluate harness++The runner that takes a program + metric + dataset and produces a score.++**`dspy.Evaluate(*, devset, metric=None, num_threads=None, display_progress=False, display_table=False, max_errors=None, provide_traceback=None, failure_score=0.0, save_as_csv=None, save_as_json=None)`**+Keyword-only constructor. `metric` can be passed here or deferred to the call. `display_table=N` truncates the displayed DataFrame to `N` rows; `display_table=True` shows the whole thing; `False` shows nothing. `save_as_csv` / `save_as_json` write per-example results to disk for later inspection. Passing the removed `return_outputs` kwarg raises a `ValueError`.++**`Evaluate.__call__(program, metric=None, devset=None, ...)`** → `EvaluationResult`+Submits `(program, example)` pairs to a `ParallelExecutor`. Each worker re-applies the parent’s `thread_local_overrides` and runs `program(**example.inputs())`, then calls the metric with `(example, prediction)`. The aggregate becomes `.score`: percent of `True` for boolean returns, mean for float returns, mean of `score` for `Prediction` returns. Per-example results land in `.results` as `(example, prediction, score)` triples.++**`dspy.evaluate.EvaluationResult`**+A `dspy.Prediction` subclass with two fields: `.score` (aggregate) and `.results` (list of triples). `repr` shows the score and the result count rather than dumping the full list, so logging an `EvaluationResult` doesn’t print a megabyte of output.++## Cross-links++- [Settings and `context()`](settings-and-context.md) — how `Evaluate`‘s workers inherit a `dspy.context(...)` override around the call.+- [Built-in module variants](built-in-module-variants.md) — `dspy.Parallel` and `Module.batch` use the same `ParallelExecutor` under the hood.+- [Optimizers: choosing one](choosing-an-optimizer.md) — every optimizer compiles against a metric defined here; the `Prediction(score, feedback)` shape GEPA expects is documented above.diff --git a/docs/docs/diving-deeper/modules.md b/docs/docs/diving-deeper/modules.mdnew file mode 100644index 000000000..195fc31e3--- /dev/null+++ b/docs/docs/diving-deeper/modules.md@@ -0,0 +1,141 @@+# Modules: composing your own++## Intent++A `dspy.Module` is the unit of composition: subclass it, define some sub-modules in `__init__`, and write a `forward()` that pipes inputs through them. Modules are how custom logic — control flow, branching, multiple LM calls, post-processing — fits into the DSPy ecosystem in a way that optimizers, save/load, settings overrides, and parallel execution all keep working.++Read this when you’ve outgrown `Predict` / `ChainOfThought` / `ReAct` on their own and want to compose them, or when you want to understand what `__call__` does to your `forward()` behind the scenes.++## Design decisions++### 1. Subclass and override `forward()`++That’s the contract: define sub-modules in `__init__`, do the work in `forward`, let `__call__` wrap it. The split exists because the framework needs predictable places to attach infrastructure. `__init__` is where sub-modules are visible for tree-walking and serialization; `forward` is where the runtime concerns (settings stack, usage tracking, callbacks) wrap your code. Mixing the two muddies what the optimizer sees and what `dump_state` saves.++### 2. Sub-modules are discovered by walking `self.__dict__`, not registered++Assignment is the registration. There’s no `register_module()` call and no inheritance trick. The tree-walk methods (`named_predictors`, `named_parameters`, `named_sub_modules`) inspect `self.__dict__` at call time and recurse into lists and dicts as well as direct attributes. Discovery being lazy means you don’t have to remember to register, but it also means a sub-module hidden inside a closure or a non-walked container is invisible to optimizers and to `dump_state`.++### 3. `Parameter` is the marker that flags an attribute as optimizer-visible++When you assign `self.max_iters = 5`, the tree walk skips it. When you assign `self.predict = dspy.Predict(...)`, it’s a `Parameter` and gets included. This keeps `dump_state` small and the optimizer’s search space focused — only the things that should learn are exposed. `Predict` is a `Parameter`; `Retrieve` is too; plain Python attributes are not.++### 4. `__call__` wraps `forward()` with infrastructure++Going through `__call__` is what pushes `self` onto `settings.caller_modules`, opens a usage-tracking context when `settings.track_usage` is true, and runs the callback decorator chain. Calling `forward()` directly bypasses all of that — usage doesn’t get tallied, callbacks don’t fire, the caller stack doesn’t update. The deprecation warning on direct `forward` calls is there for that reason. Always invoke a module as `module(...)`.++### 5. Async sits alongside sync via `acall()` / `aforward()`++`acall` mirrors `__call__`‘s infrastructure for async; `aforward` is the async counterpart to `forward`. A module that doesn’t define `aforward` falls back to running the sync `forward` in a worker thread via `asyncify`. That gives you a path from “sync only” to “fully async” without rewriting the world — async one sub-module at a time, leave the rest as-is.++### 6. Settings propagate via context, not constructor args++Sub-modules read `dspy.settings.lm` (and `.adapter`, `.callbacks`) at call time. The consequence: `with dspy.context(lm=other_lm): result = my_module(...)` swaps the LM for every sub-module inside, no rewiring needed. The price is implicit state — a sub-module’s behavior depends on whoever calls it, not only on what was assigned in `__init__`. The composition story is worth the tradeoff.++### 7. `_compiled=True` freezes a sub-module’s parameters from optimizers++`named_parameters` checks the `_compiled` flag and skips compiled children. This lets you optimize a sub-module on its own, save the result, drop it into a larger program, and run a fresh optimizer on the outer program without disturbing the inner one. You rarely set this by hand; teleprompts set it when they finish compiling.++### 8. The metaclass `ProgramMeta` enforces `super().__init__()`++`ProgramMeta` installs a fallback `_base_init` that runs before your `__init__`, so the bookkeeping (history, callbacks, the `_compiled` flag) is in place even if your subclass forgets `super().__init__()`. You won’t subclass or instantiate the metaclass; it’s a guardrail. When an error trace lands inside it, the cause is usually a missing `super().__init__()` call.++### 9. `deepcopy()` is hand-written++Modules can hold closures and callbacks that confuse Python’s default `copy.deepcopy`. `Module.deepcopy()` tries `copy.deepcopy` first and falls back to attribute-by-attribute copying on `TypeError`. Optimizers use this to fork candidate programs, and the fallback is what makes that reliable across the variety of things a `Module` subclass might hold.++## API walkthrough++Grouped by what you’re trying to do.++### Defining a module++**`dspy.Module(callbacks=None)`**+Subclass it. The base stores `callbacks`, `history`, and the `_compiled` flag — nothing more. The interesting behavior is in `__call__` and the tree-walk methods.++**`Module.__call__(*args, **kwargs)`**+Pushes `self` onto `settings.caller_modules`, opens a usage-tracking context if `settings.track_usage`, runs `forward` (decorated with `@with_callbacks`), and returns the `Prediction`. If `forward` returns something other than a `Prediction`, you’ll get a warning — usage tracking relies on the `Prediction` return type. Direct calls to `module.forward(...)` log a deprecation warning.++**`Module.forward(**kwargs)`**+What you override. Accept signature inputs as keyword arguments, do your work, return a `Prediction`. Don’t put settings reads in `__init__` — read them inside `forward` so the current LM and adapter are picked up at call time, not at construction time.++**`Module.acall(*args, **kwargs)` / `Module.aforward(**kwargs)`**+Async variants. `acall` is the public entry; `aforward` is what you override. If you don’t define `aforward`, `acall` falls back to running `forward` inside `asyncify`. Useful when one sub-module is async-only — you can `await` it from `aforward` without making the rest of the program async.++**`ProgramMeta`**+The metaclass on `Module`. You won’t subclass or instantiate it. It installs `_base_init` as a fallback so `super().__init__()` isn’t strictly required. When an error trace lands inside it, the cause is usually a missing `super().__init__()`.++### Walking the module tree++All of these rely on the same primitive: walk `self.__dict__`, recurse into lists and dicts, yield anything that matches the target type.++**`Module.named_predictors()` / `Module.predictors()`**+Discovers every `Predict` instance under this module. Used by optimizers to find what to optimize. Order is the order of discovery (depth-first through `__dict__`).++**`Module.named_parameters()` / `Module.parameters()`**+Discovers every `Parameter`. Honors `_compiled`: a sub-module marked compiled is skipped, and the optimizer leaves its parameters alone.++**`Module.named_sub_modules(type_=BaseModule, skip_compiled=False)`**+The generator the others build on. Use it directly when you want a custom walk — every `ReAct` instance, every sub-module of a specific user class, anything you can filter by `type_`.++**`Module.map_named_predictors(func)`**+Applies `func` to each predictor and replaces it in place. The hook teleprompts use when swapping in optimized predictors. You’ll rarely need it directly.++### Setting and getting the LM++**`Module.set_lm(lm)`**+Walks every predictor in the tree and assigns `lm`. Useful when you’ve built a program with one LM and want to re-evaluate it on another without changing settings globally.++**`Module.get_lm()` → `LM`**+Returns the LM if every predictor agrees on one. Raises `ValueError` on a mix. A sanity check before fine-tuning or saving, when you want to confirm the whole program is on one model.++### State and copies++The save/load surface. The full lifecycle — JSON vs PKL, full-program vs state-only, `save_program=True` — lives in [Saving and loading](saving-and-loading.md); the methods here are what that page is about.++**`Module.dump_state(json_mode=True)` / `Module.load_state(state, allow_unsafe_lm_state=False)`**+Round-trips the optimizer-visible state: per-predictor demos, traces, signature instructions, LM config. Not the Python class itself.++**`Module.save(path, save_program=False, modules_to_serialize=None)` / `Module.load(path, allow_pickle=False, allow_unsafe_lm_state=False)`**+The user-facing pair. `save_program=True` cloudpickles the whole module to a directory; the default writes state-only JSON or PKL.++**`Module.deepcopy()`**+Tries `copy.deepcopy`, falls back to attribute-by-attribute copy on `TypeError`. Optimizers use this to fork candidate programs.++**`Module.reset_copy()`**+`deepcopy()` then `reset()` on every parameter. Use it for a fresh program — same structure, no optimizer state.++### Batch execution++**`Module.batch(examples, num_threads=None, max_errors=None, return_failed_examples=False, ...)`**+Runs the module against many examples in parallel. Internally wraps `dspy.Parallel`, which snapshots `dspy.settings` and re-applies the snapshot inside each worker thread (so an outer `dspy.context(lm=...)` is honored). Returns predictions in input order. Use it for evaluation, demo collection, and any embarrassingly-parallel inference.++### Debugging++**`Module.history` / `Module.inspect_history(n=1, file=None)`**+`history` is the list of LM call records attached to this module. `inspect_history` pretty-prints the last `n`. Both are excluded from pickled and JSON state, so a multi-megabyte history doesn’t ride along with your saved program.++**`Module.callbacks`**+Registered callback handlers. Also excluded from saved state.++### The return type++**`dspy.Prediction(**fields)`**+A field container. Access with `result.haiku` or `result["haiku"]`. Inherits `dspy.Example`‘s storage but drops the input/output split.++**`dspy.Prediction.from_completions(list_or_dict, signature=None)`**+Builds a Prediction from multiple LM completions. `BestOfN`, `MultiChainComparison`, and any module that samples more than once uses this.++**`Prediction.completions`**+A `Completions` object when the prediction came from `n > 1` samples; `pred.completions[i]` returns the i-th completion as its own `Prediction`. `None` for single-sample calls.++**`Prediction.get_lm_usage()` / `Prediction.set_lm_usage(tokens_dict)`**+Token-usage accounting. Populated when the prediction ran under `dspy.settings(track_usage=True)`.++**Comparison to `dspy.Example`.** Same storage layer; different intent. `Example` is for training data — it carries `_demos` and `_input_keys`, and `.with_inputs` returns a filtered copy. `Prediction` is for module outputs — no input/output split, plus completions and usage. Use `Example` for what goes in, `Prediction` for what comes out.++## Cross-links++- Each built-in module subclass has its own DD page: see the predictor zoo, ReAct, and the optimizer-specific pages.+- [Saving and loading](saving-and-loading.md) covers the persistence story in detail.+- [Settings and context()](settings-and-context.md) covers how LM / adapter / callback overrides propagate into a module’s sub-modules.diff --git a/docs/docs/diving-deeper/saving-and-loading.md b/docs/docs/diving-deeper/saving-and-loading.mdnew file mode 100644index 000000000..ad389c42b--- /dev/null+++ b/docs/docs/diving-deeper/saving-and-loading.md@@ -0,0 +1,135 @@+# Saving and loading++## Intent++Saving a DSPy program preserves what an optimizer produced: the rewritten signature instructions, the few-shot demos, the LM config, and whatever state each predictor needs to recreate its behavior. There are two paths — save the state alone and re-load it into a freshly-instantiated program, or pickle the whole program so the loading side doesn’t need your class definitions at all.++Read this when you’re shipping an optimized program to another team, version-controlling optimizer output, or trying to figure out why a `.json` save round-trips but a `.pkl` save needs an extra flag to load.++## Design decisions++### 1. Two paths: state-only and full-program++State-only saves the optimizer’s work — demos, signature instructions, LM config — and assumes the loading side has your class definitions. Full-program saves the whole module via cloudpickle, so the loader doesn’t need to import your code. Use state-only by default; reach for full-program when shipping to a process that doesn’t have your source.++### 2. JSON by default++State-only saves to JSON when the path ends in `.json`. Human-readable, diff-able in version control, no code-execution risk on load. The `.pkl` state form is there for state that doesn’t serialize cleanly to JSON (custom Pydantic objects in demos, for instance), but the JSON path is the one you’ll reach for almost every time.++### 3. `save_program=True` exists for the “no class on the loading side” case++When the loader doesn’t have your `class HaikuEnsemble(dspy.Module)` definition available — a different repo, a different team, a different service — full-program mode bundles the class with the state. The loader calls `dspy.load(path)` and gets a usable module back without ever importing your code. The price is cloudpickle, which means the load path must trust the file.++### 4. `allow_pickle` is deliberate friction++Loading any pickle — state-PKL or full-program — requires `allow_pickle=True`. The default is `False` so an unsuspecting caller can’t deserialize an arbitrary file and silently execute code. The flag is a forcing function: it makes the trust decision explicit at the call site, not buried in defaults.++### 5. `allow_unsafe_lm_state` strips endpoints by default++When loading state, three LM-config keys are dropped unless you opt in: `api_base`, `base_url`, and `model_list`. The reasoning: a saved program might point at an internal endpoint that the loading side shouldn’t be talking to, or that’s no longer reachable. Pass `allow_unsafe_lm_state=True` when you want the original endpoint configuration to ride along.++### 6. API keys are never serialized++`LM.dump_state` explicitly excludes `api_key` from the saved kwargs, and there’s no flag to re-enable it. The LM client always needs its credentials configured fresh on the loading side. Anything else would be a credential leak waiting to happen.++### 7. `load_state` is transactional++When you call `Module.load_state(state)`, DSPy runs the load against a deep copy of the module first, and only commits the change to the live module if the trial succeeded. If a state file is corrupt or incompatible, the original module is left untouched — no half-loaded state, no module stuck between two configurations.++### 8. Callbacks and history are excluded from saved state++Both are runtime-only: callbacks are hooks the caller registers per process, and history is a growing log of LM calls. They’re dropped in `__getstate__` so they don’t ride along with pickled programs and don’t bloat state files. After loading, re-register callbacks if you need them; history starts fresh.++### 9. Metadata sits in a separate file++When you save a full program, the directory contains `program.pkl` and `metadata.json`. The metadata file holds dependency versions (Python, DSPy, cloudpickle) so you can read them without unpickling. State-only JSON saves embed the same metadata under a `"metadata"` key in the JSON dict.++### 10. Version mismatches warn, don’t block++If you load a program saved under an older DSPy, you get a warning logged with the version delta — but the load proceeds. The save format aims for backward compatibility, and a hard version check would force users to keep stale virtualenvs around to load old programs.++### 11. `modules_to_serialize` embeds user-defined classes by value++By default, cloudpickle serializes user classes by import path (`mymodule.MyClass`). If the loading side doesn’t have `mymodule` importable, the load fails. Passing `modules_to_serialize=[MyClass.__module__]` (or the module object) registers it with `cloudpickle.register_pickle_by_value`, embedding the class code in the pickle. Useful when you’re saving a program defined in a script rather than a package.++## API walkthrough++Grouped by what you’re trying to do.++### Saving++Three call shapes; the path’s suffix (or lack of one) chooses the mode.++**`Module.save("path.json")`**+State-only JSON. Writes `Module.dump_state(json_mode=True)` plus a `metadata` block of dependency versions. Pretty-printed via `orjson`. Diff-friendly.++**`Module.save("path.pkl")`**+State-only PKL. Cloudpickle of the same state dict. Use when the state contains objects that don’t round-trip through JSON. Logs a warning at save time noting that loading requires `allow_pickle=True`.++**`Module.save("path/", save_program=True)`**+Full program. Writes two files into the directory: `program.pkl` (cloudpickle of `self`) and `metadata.json` (dependency versions). The path must be directory-shaped — passing a `path.suffix` raises an error. Creates the directory if it doesn’t exist.++**`modules_to_serialize=[...]` (full-program mode only)**+Registers each entry with `cloudpickle.register_pickle_by_value` before pickling. Pass the modules that define your custom `Module` subclasses; otherwise the pickle stores them by import path, which breaks when the loader can’t import them.++### Loading++Two entry points, matching the two save modes.++**`Module.load(path, allow_pickle=False, allow_unsafe_lm_state=False)`**+Loads state into an existing module instance. You instantiate the program the same way you built it, then call `.load()` on it. JSON paths load freely; `.pkl` paths require `allow_pickle=True`. `allow_unsafe_lm_state=True` keeps `api_base`, `base_url`, and `model_list` instead of stripping them.++```python+program = HaikuEnsemble(n=5) # same construction as when saved+program.load("haiku_ensemble.json") # state slots in+```++**`dspy.load(path, allow_pickle=False)`**+Loads a full-program directory and returns the rehydrated module. No prior instantiation needed — cloudpickle reconstructs the object graph. Always requires `allow_pickle=True` in practice (pickle is the only loading path here); the flag is the user’s acknowledgment that the directory is trusted.++```python+program = dspy.load("haiku_ensemble/", allow_pickle=True)+```++### Underlying state surface++You rarely call these directly — `Module.save` / `Module.load` are the user-facing pair — but knowing what they round-trip helps when debugging a state file.++**`Module.dump_state(json_mode=True)` → `dict`**+Returns `{name: parameter.dump_state(...)}` for every named parameter in the tree. `json_mode=True` (the default) forces JSON-serializable shapes; `False` allows pickle-only objects through (used internally by the `.pkl` save path).++**`Module.load_state(state, *, allow_unsafe_lm_state=False)`**+Applies a state dict. Runs the load on a deep copy first to validate, then commits to the live module. Failure on the trial leaves the live module unchanged.++**`Predict.dump_state(json_mode=True)`**+A single predictor’s state: `{"traces": [...], "train": [...], "demos": [...], "signature": {...}, "lm": {...}}`. Demos are serialized via a `serialize_object` helper that recursively converts Pydantic objects to plain dicts.++**`Signature.dump_state()`**+`{"instructions": str, "fields": [{"prefix": str, "description": str}, ...]}`. The instructions are the docstring — what optimizers like GEPA rewrite. Field metadata (prefix, description) round-trips too; field names and types are reconstructed from the live Signature class on load.++**`LM.dump_state()`**+Model name, `model_type`, cache flag, retry count, kwargs (minus `api_key`), and finetuning-related fields. The omission of `api_key` is hard-coded; there’s no flag to opt back in.++### Security flags++Two flags, two different concerns.++**`allow_pickle=False` (default)**+Refuses to load any `.pkl` or full-program directory. Loading a pickle can execute arbitrary code; the flag forces the caller to acknowledge that the file is trusted. Applies to both `Module.load` and `dspy.load`.++**`allow_unsafe_lm_state=False` (default)**+On state load, drops `api_base`, `base_url`, and `model_list` from the LM config. Pass `True` to restore the original endpoint configuration. The split exists because a saved program’s endpoint may not match where the loader wants to run — an internal-only URL, a deprecated host, a model list that’s no longer available.++API keys are never re-enabled by either flag. The loading side configures credentials fresh.++### Metadata and versioning++Every save writes dependency versions: Python, DSPy, cloudpickle. Full-program saves put them in `metadata.json` next to `program.pkl`; state-only saves embed them under a `"metadata"` key in the JSON / PKL state.++On load, the runtime compares versions to the current process. A mismatch logs a warning and proceeds. The save format aims for backward compatibility, so old saves load against newer DSPy versions — but a warning is your hint to check the release notes if something behaves differently.++## Cross-links++- [Modules: composing your own](modules.md) — `Module.save` / `load` are inherited from `BaseModule`; the tree-walk that gathers state is the same one optimizers use.+- [Signatures in depth](signatures-in-depth.md) — `Signature.dump_state` / `load_state` are what carry an optimizer’s rewritten instructions through a round-trip.+- [Settings and `context()`](settings-and-context.md) — `dspy.settings.save` / `dspy.load_settings` are a parallel surface for the settings singleton.diff --git a/docs/docs/diving-deeper/settings-and-context.md b/docs/docs/diving-deeper/settings-and-context.mdnew file mode 100644index 000000000..f8962b01e--- /dev/null+++ b/docs/docs/diving-deeper/settings-and-context.md@@ -0,0 +1,125 @@+# Settings and `context()`++## Intent++`dspy.settings` is the singleton that holds the language model, the adapter, the retriever, the callbacks, and a handful of runtime flags every other component reads. You configure it once at startup with `dspy.configure(...)` and override it locally with `with dspy.context(...)`. This page covers what’s in there, how the global and scoped layers interact, and how overrides do (and don’t) propagate across threads and async tasks.++Read this when you need to swap LMs mid-program, run different branches under different adapters, debug why a parallel worker isn’t seeing your context override, or write a new module that needs to read from settings.++## Design decisions++### 1. Two entry points by design++`configure` is for process-wide, one-time setup; `context` is for scoped overrides. They behave differently and have different ownership rules. `configure` mutates the global dict; `context` pushes onto a ContextVar. Splitting them makes the intent of each call clear, and lets the framework enforce one-time setup for the global while allowing freely-nested overrides for the scoped one.++### 2. Two layers underneath++A global `main_thread_config` dict and a `thread_local_overrides` ContextVar. Reads check the override first, then the global. A `dspy.context(lm=alt_lm)` block doesn’t touch the global config — it shadows it for the duration of the block, on the current execution context. Every read goes through the same merge, which is why an adapter swap inside a context block is honored even by sub-modules constructed before the block opened.++### 3. `configure` has an owner thread++The first thread to call it owns it; calls from other threads raise `RuntimeError`. The intent is to make `configure` look like Python module-level initialization. If multiple threads were allowed to reconfigure mid-program, you’d get races where one thread’s `lm` swap silently appeared in another thread’s prediction. IPython is exempt — interactive sessions need the flexibility.++### 4. `context` uses Python’s `contextvars`++Overrides propagate correctly across `await` and `asyncio.create_task`. `threading.local()` would have lost the override at the first `await`. `contextvars` ties the override to the execution context, not the thread, and the standard library copies it automatically to tasks spawned within. That’s what makes `with dspy.context(lm=alt): await my_async_module(...)` work the way you’d hope.++### 5. DSPy’s executors snapshot and re-apply++`dspy.Parallel`, `Module.batch`, and `asyncify` capture the parent’s overrides and re-set them inside each worker thread. Plain ContextVar inheritance doesn’t survive crossing into a new OS thread — Python only auto-propagates across `asyncio` task boundaries. So the executors do it themselves: grab `thread_local_overrides.get()` at submission, `.set()` it inside the worker before running user code, and reset on the way out. `usage_tracker` is deep-copied per worker so each thread accounts independently.++### 6. Plain Python threads do not inherit overrides++`threading.Thread` and bare `concurrent.futures.ThreadPoolExecutor` won’t see your `with dspy.context(...)` block. This trips people up. If you spin up your own thread pool and run DSPy modules in the workers, the context override stays in the parent. The fix: capture `dspy.settings.thread_local_overrides.get()` in the parent and re-set it inside each worker, or use `dspy.Parallel`, which does it for you.++### 7. Settings are read lazily at call sites++Predict reads `settings.lm` at call time; Adapter reads `settings.adapter`; Module reads `settings.track_usage`. No constructor takes a `settings` argument. The cost is implicit dependency — a module’s behavior depends on whatever context surrounds the call. The benefit is composition: settings overrides flow into every sub-module without rewiring.++### 8. Some knobs live on `dspy.LM`, not settings++`temperature`, `max_tokens`, `api_base`, retries. The split is intentional. Settings is for orchestration knobs that apply across LMs — which LM is the default, what adapter to use, whether usage is being tracked. LM-instance knobs (sampling parameters, endpoint, retry policy) live on the LM itself, because a program might use several different LMs with different settings.++### 9. Locking is minimal++A single `Lock` guards only `_ensure_configure_allowed`. Reads are unsynchronized. The lock serializes ownership checks during `configure`; the read path doesn’t take it. CPython dict-item access is atomic enough for the read pattern, and adding locking would have hurt every Predict call. `configure` is meant to be called once at startup; once it has settled, reads are uncontended.++## API walkthrough++Grouped by what you’re trying to do.++### Setting things up++**`dspy.configure(**kwargs)`**+Merges `kwargs` into the global `main_thread_config` dict. Thread-safe via owner-thread enforcement: calls from other threads raise `RuntimeError`. Same restriction applies across async tasks, with the IPython exception. Use it once at startup; for a mid-program swap, prefer `context`.++**`dspy.context(**kwargs)`**+Context manager. On entry, pushes `kwargs` onto the `thread_local_overrides` ContextVar; on exit, resets the ContextVar token. Safe to call from any thread or async task; nests cleanly. Use it inside parallel branches, inside `asyncify`-wrapped functions, anywhere you need a scoped override.++**`dspy.settings`**+The singleton. Read attributes directly: `dspy.settings.lm`, `dspy.settings.adapter`. Reads merge global + override on every access — no caching, so a context-block change is visible immediately to every sub-module that reads.++**`dspy.settings.copy()` / `dspy.settings.config`**+Return a merged dotdict of the current effective config. Useful when you want to snapshot settings — to pass to a worker, to log, to compare before/after.++**`dspy.load_settings(path, allow_pickle=False)` / `dspy.settings.save(path, modules_to_serialize=None, exclude_keys=None)`**+Round-trip the settings dict to disk via cloudpickle. `exclude_keys` lets you drop sensitive fields (API keys aren’t in settings, but custom keys you’ve added might be).++### What you can configure++Standard keys (defined in `DEFAULT_CONFIG`):++| Key | Default | Purpose |+|---|---|---|+| `lm` | `None` | Default LM for every `Predict`. |+| `adapter` | `None` (falls back to `ChatAdapter()`) | Adapter used to format and parse. |+| `rm` | `None` | Default retriever for `dspy.Retrieve()`. |+| `callbacks` | `[]` | Callback handlers fired around module calls. |+| `track_usage` | `False` | Enable token-usage accounting. |+| `num_threads` | `8` | Default thread count for `dspy.Parallel` / `Module.batch`. |+| `async_max_workers` | `8` | Concurrency cap for `asyncify`. |+| `max_errors` | `10` | Parallel-job error threshold before cancellation. |+| `provide_traceback` | `False` | Include tracebacks in parallel error logs. |+| `disable_history` | `False` | Skip recording call history on modules. |+| `warn_on_type_mismatch` | `True` | Warn when an input doesn’t match the signature’s declared type. |+| `max_history_size` / `max_trace_size` | `10000` each | Trim limits for module history and per-call trace. |+| `stream_listeners` / `send_stream` | `[]` / `None` | Streaming wiring. |+| `allow_tool_async_sync_conversion` | `False` | Permit running async tools inside sync code. |+| `branch_idx` | `0` | Rollout / branch index used by some optimizers. |++Set-by-DSPy keys (don’t set these yourself):++- `caller_predict`, `caller_modules` — the current call stack, used by callbacks and tracing.+- `usage_tracker`, `trace` — populated by the relevant contexts and read inside modules.++### How overrides propagate++The mechanics that decide which threads and tasks see an override.++**ContextVar propagation**+`dspy.context(...)` sets a `contextvars.ContextVar`. Python copies the active context automatically to `asyncio.create_task`, `asyncio.gather`, and inherits it across `await`. No DSPy code needed for this — it’s how `contextvars` works.++**`dspy.Parallel` / `Module.batch`**+At submission time, captures the parent’s `thread_local_overrides.get()` and hands the dict to each worker. The worker calls `thread_local_overrides.set(parent_overrides)` before running user code and resets on the way out. `usage_tracker` is deep-copied per worker so each thread accounts independently rather than racing on a shared object.++**`dspy.asyncify(fn)`**+Runs a sync DSPy module on a worker thread via `anyio.to_thread.run_sync`. Same snapshot-and-reapply trick: capture parent overrides at call time, re-apply in the worker, reset on exit.++**Plain `threading.Thread` / `concurrent.futures.ThreadPoolExecutor`**+Does not inherit. The override lives in a ContextVar that the new OS thread doesn’t see. Workaround: capture `dspy.settings.thread_local_overrides.get()` in the parent and `set` it inside the worker, or wrap the work in `dspy.Parallel`.++### Ownership and locking++**Owner thread**+First call to `dspy.configure` records `config_owner_thread_id`. Later calls from a different thread (or, in async, a different task) raise `RuntimeError`. Multiple `configure` calls from the owner are allowed and overwrite in place.++**IPython exception**+Multiple `configure` calls from different async tasks in the same IPython session are allowed, detected via `get_ipython()`. The reason: notebook cells often run in fresh task contexts, and forcing each to be single-shot would break interactive use.++**The lock**+A single `threading.Lock` guards `_ensure_configure_allowed`. The read path doesn’t take it; mutations rely on dict-item assignment being atomic in CPython. Reads inside `Predict` and `Adapter` are uncontended, which matters because they happen on every call.++## Cross-links++- [Saving and loading](saving-and-loading.md) — settings serialization sits next to module serialization.+- Reference: `clients.md` — LM-instance knobs (`temperature`, `max_tokens`, `api_base`, retries) that intentionally don’t live in settings.diff --git a/docs/docs/diving-deeper/signatures-in-depth.md b/docs/docs/diving-deeper/signatures-in-depth.mdnew file mode 100644index 000000000..08fa4eb97--- /dev/null+++ b/docs/docs/diving-deeper/signatures-in-depth.md@@ -0,0 +1,134 @@+# Signatures in depth++## Intent++A signature is the declarative contract between your program and the language model: the input fields it accepts, the output fields it produces, and the instructions describing the task. This page covers what the class-based form gives you over strings, how typed fields move through DSPy, how to modify signatures at runtime, and the design decisions that shape it all.++Read this when you’ve outgrown the string-form `"a, b -> c"` mini-language and want to know what the class-based form adds, how typed fields are coerced, and how optimizers and modules manipulate signatures behind the scenes.++## Design decisions++### 1. Pydantic underneath++Every field on a Signature is a pydantic `FieldInfo`, and the base `Signature` class extends `pydantic.BaseModel`. DSPy-specific metadata lives in `json_schema_extra` on each field. Pydantic ships what DSPy would otherwise build by hand — type validation, JSON-schema generation, and a `TypeAdapter` that the adapter layer uses to coerce LM output into the declared type.++A useful consequence: any pydantic constraint (`gt`, `lt`, `min_length`, …) works on a field. They get stringified into `json_schema_extra["constraints"]` and the adapter mentions them in the prompt.++### 2. Dual API, one class++String form (`dspy.Signature("a, b -> c")`) and class form (`class HaikuBot(dspy.Signature)`) produce the same kind of object: a `Signature` subclass. Inline calls want a one-liner; richer specs want a docstring, typed `InputField`/`OutputField` attributes, and sometimes imported types. Collapsing both to a single class type means modules, adapters, and optimizers only ever handle one shape.++The metaclass `SignatureMeta` intercepts `dspy.Signature("...")` calls and routes them through `make_signature`. You never construct a Signature instance; the class itself is the object that gets passed around.++### 3. Docstring becomes the task instructions++The metaclass cleandocs the class docstring and stores it as `__doc__`; the `Signature.instructions` property reads it back. Absent a docstring, DSPy generates `"Given the fields X, produce the fields Y."` and uses that. The adapter renders this string into the prompt’s system message above the field schema.++Instructions belong next to the fields they describe, and optimizers need a single, well-defined string to rewrite. Treat the docstring as the place to express task intent in prose; keep field names and types short and structural, and put anything that doesn’t fit in the docstring.++### 4. Instructions live on the signature, not the module++A Signature carries its own instructions and field schema. The module (`Predict`, `ChainOfThought`, `ReAct`) supplies the call-time strategy: how many LM calls to make, what to reason about, when to stop. The same Signature can be handed to any of them, which makes it cheap to compare modules on the same task or rewrite the instructions without changing how the call is made.++If you find yourself rewriting the docstring every time you swap modules, the instructions probably contain control-flow detail that belongs in the module instead.++### 5. Immutability by deepcopy++Every mutation method (`with_instructions`, `with_updated_fields`, `prepend`, `append`, `insert`, `delete`) deep-copies the existing field dict, applies the change, and returns a new Signature class. The original stays as it was.++Optimizers run many candidate variants of the same program. If a predictor mutated its signature in place, candidates would clobber each other through shared state. Don’t try to mutate fields by reaching into `Signature.fields` directly — go through the methods. For equality, use `Signature.equals(other)`; plain `==` compares class identity, which usually isn’t what you want.++### 6. Field order is meaningful++The metaclass extracts field order from the class namespace and exposes inputs first, then outputs, via `Signature.fields`. The adapter walks that same dict when rendering the prompt, so what you see in `Signature.fields.keys()` is the order the LM sees. Reorder inputs or outputs and the prompt changes.++When inserting new fields with `prepend` / `append` / `insert`, the position argument targets the field’s own section (input or output), not the full field list.++### 7. Types are declared here but coerced elsewhere++A Signature only declares the annotation: `season: Literal["spring", ...]`, `haikus: list[str]`, a custom Pydantic model. The parsing happens in `dspy/adapters/utils.py::parse_value`, which tries `json_repair`, falls back to `ast.literal_eval`, then validates against `TypeAdapter(annotation)`. For `dspy.Type` subclasses, the adapter retries with the raw string if pydantic validation fails, letting the type’s custom parser take over.++This split exists because multiple adapters (Chat, JSON, XML, TwoStep) need to coerce the same Signature differently. JSON adapters can lean on the model’s JSON mode; XML adapters parse from tags. Keeping coercion in the adapter layer means Signatures stay lean and the parser logic isn’t duplicated. When a typed field misbehaves at parse time, look at the adapter’s output and `parse_value`, not the Signature. See [Adapters: how signatures become prompts](adapters.md).++### 8. Custom types are resolved by walking the caller’s stack frames++When the string parser sees `subject: MyType` and `MyType` isn’t a built-in or `dspy.*` class, `SignatureMeta._detect_custom_types_from_caller` walks up to 100 frames of the call stack, looking the name up in each frame’s locals and globals. This lets you write `dspy.Predict("subject: MyType -> output")` inline without importing or registering anything.++The 100-frame bound is a guardrail. In stripped or optimized Python where frames aren’t available, you’ll get a warning and need to pass `custom_types={"MyType": MyType}` to `make_signature` explicitly. The same fallback works any time you don’t want to rely on frame introspection.++### 9. Field names and descriptions are inert to optimizers++GEPA and the other instruction optimizers rewrite the Signature’s docstring. They don’t touch field names, `desc`, or `prefix`. The only way those change is `with_updated_fields`.++Field names are part of the program’s public interface: caller code reads `result.haiku`, downstream modules look up `"haiku"` by name. An optimizer that renamed them would break the program around it. So name your fields carefully — the optimizer can’t fix `result` into `haiku` later. The same goes for field descriptions when you write them.++## API walkthrough++Grouped by what you’re trying to do.++### Declaring a signature++**`dspy.Signature`**+Subclass it once you have more than two or three fields, want a docstring, or need richer types. Calling `dspy.Signature("a, b -> c")` directly is shorthand: the metaclass intercepts the call and routes through the string parser. Both produce real Signature subclasses (not instances) — you don’t instantiate them.++**`dspy.InputField(*, desc=None, prefix=None, **pydantic_kwargs)`**+**`dspy.OutputField(*, desc=None, prefix=None, **pydantic_kwargs)`**+Thin factories over `pydantic.Field`. They accept every pydantic constraint (`gt`, `min_length`, …) plus the DSPy-specific `desc` and `prefix`. `prefix=` overrides the auto-inferred label; omit it and `infer_prefix` derives one from the attribute name. The deprecated `format` and `parser` args still accept values but no longer do anything — they predate the adapter layer.++**`dspy.make_signature(signature, instructions=None, signature_name="StringSignature", custom_types=None)`**+The actual constructor. Two input shapes: a string (parsed by `_parse_signature`) or a dict of `{name: (type, FieldInfo)}` (used by the mutation methods to rebuild a class from its own pieces). `signature_name` sets the resulting class’s `__name__`, which surfaces in logs and inspection tools.++**`dspy.ensure_signature(signature, instructions=None)`**+A no-op on already-built Signature classes; runs `make_signature` on strings. Use it when writing a module that should accept either form. It doesn’t memoize, so don’t call it in a hot loop on the same string — every call constructs a new class.++**`SignatureMeta`**+The metaclass behind `Signature`. You won’t subclass or instantiate it. What it does: parses docstrings into instructions, validates that every field is tagged `input` or `output`, infers missing `prefix=` values, and runs the custom-type frame walk during string parsing. Most “weird signature” errors originate here.++### Introspecting a signature++**`Signature.input_fields` / `Signature.output_fields` / `Signature.fields`** → `dict[str, FieldInfo]`+Dicts keyed by field name. The `FieldInfo`‘s `.annotation` is the declared type; `json_schema_extra` carries DSPy’s metadata, including the `__dspy_field_type` tag and the `IS_TYPE_UNDEFINED` marker (set when a string-form field has no explicit type — Predict uses it to coerce `None` to an empty string).++**`Signature.instructions`** → `str`+The cleandoc’d docstring. The property is settable, but prefer `with_instructions(...)` so you get a fresh class.++**`Signature.signature`** → `str`+Round-trips the class to its string form (e.g., `"location, season, mood -> haiku"`) for display. Useful in logs and inspection; not used for parsing.++**`Signature.equals(other)`** → `bool`+Compares instructions and every field’s `json_schema_extra`. This is the equality predicate optimizers and tests use. Plain `==` compares class identity, which is usually not what you want.++### Mutating a signature++Every method here returns a new Signature class via deep-copy.++**`Signature.with_instructions(instructions: str)`**+New class, same fields, replaced docstring.++**`Signature.with_updated_fields(name, type_=None, **json_schema_extra)`**+Replaces the field’s metadata by merging the keyword arguments onto its existing `json_schema_extra`. Pass `desc=...` to change the description, `prefix=...` to change the label, or any custom key your adapter or optimizer reads. If you change `type_`, the new annotation replaces the old; if you also pass `IS_TYPE_UNDEFINED=False`, you clear the “treat None as empty string” behavior Predict relies on for unannotated string-form fields.++**`Signature.prepend(name, field, type_=None)`**+**`Signature.append(name, field, type_=None)`**+**`Signature.insert(index, name, field, type_=None)`**+The field’s section (input or output) is determined by its `__dspy_field_type` tag — set when you built the field with `InputField` or `OutputField`. The position arg targets within that section, not across all fields. `insert` accepts negative indices; out-of-range raises `ValueError`.++**`Signature.delete(name)`**+Silently no-ops when the field is absent. Check `name in cls.fields` first if you want loud failure.++### Persisting a signature++**`Signature.dump_state()`** → `dict`+**`Signature.load_state(state)`** → Signature class+Round-trip the parts that change across optimization runs: instructions, plus each field’s annotation, prefix, desc, and `__dspy_field_type` tag. The Signature class itself isn’t serialized — the assumption is that the consuming process re-instantiates it first (usually via the parent module’s saved state). `Module.save()` and `dspy.load()` use these under the hood; you rarely call them directly.++### Naming utility++**`dspy.infer_prefix(attribute_name)`** → `str`+Splits the name on camelCase and snake_case boundaries and capitalizes the result. The metaclass calls it when a field omits `prefix=`. Rarely useful on its own.++## Cross-links++- [Adapters: how signatures become prompts](adapters.md) — what `desc`, `prefix`, and types look like on the wire, and where `parse_value` does its work.+- [Modules: composing your own](modules.md) — how `Predict`, `ChainOfThought`, and your own subclasses consume signatures.+- GEPA and the Optimizers selection guide — how the docstring gets rewritten and why field names stay fixed.diff --git a/docs/docs/diving-deeper/tools-react-and-mcp.md b/docs/docs/diving-deeper/tools-react-and-mcp.mdnew file mode 100644index 000000000..c786ab112--- /dev/null+++ b/docs/docs/diving-deeper/tools-react-and-mcp.md@@ -0,0 +1,119 @@+# Tools, ReAct, and MCP++## Intent++A DSPy program “uses a tool” when an LM picks a named Python function from a list, supplies arguments to it, sees the result, and reasons over the result on the next turn. `dspy.Tool` is the wrapper that makes a plain callable usable this way; `dspy.ReAct` is the module that runs the thought / tool / observation loop; and `dspy.utils.mcp` (with `Tool.from_mcp_tool`) bridges remote MCP servers into the same interface.++Read this when you want to give your program tools, when you want to understand the ReAct loop’s mechanics (trajectory, finish step, truncation), or when you want to attach an MCP server’s tools to a DSPy program.++## Design decisions++### 1. A `Tool` is a Pydantic model over a callable, not a wrapper class++`Tool` is a `dspy.Type` (which is itself a `pydantic.BaseModel`), and `func`, `name`, `desc`, `args`, `arg_types`, and `arg_desc` are model fields. This matters because the same `Tool` instance is what adapters read to render the prompt, what `ToolCall.execute` resolves by name, and what serializes when a program with tools is saved. Being a Pydantic model plugs into all of that without bespoke code.++### 2. Schema, types, and description are introspected by default++The constructor walks `inspect.signature(func)` and `get_type_hints(func)` to build the JSON schema (`args`), the type-hint dict (`arg_types`), and the description (from the docstring). Pydantic models in the type hints are inlined: their JSON schemas replace the `$ref` paths so the LM sees a flat schema. Explicit values you pass to the constructor override inference, field by field — hand-tune one and the rest stay inferred.++### 3. Async vs sync is detected at call time, not at construction++`Tool.__call__` invokes `func(**kwargs)` and checks the result with `asyncio.iscoroutine`. The check lives at call time because the same `func` could be wrapped, decorated, or be a generic callable whose async-ness isn’t visible from the outside. A runtime check is the only signal that always works.++### 4. `allow_tool_async_sync_conversion` is the opt-in bridge++An async tool called from a sync entry point raises by default. Setting `settings.allow_tool_async_sync_conversion=True` (or scoping it via `dspy.context`) makes `__call__` run the coroutine through `asyncio.run` or the active loop’s `run_until_complete`. Opt-in matters because sync-from-async conversion is a deadlock risk inside many runtime environments; consent is explicit.++### 5. ReAct’s loop is thought → tool name → tool args → observation++On each iteration the LM produces three output fields: `next_thought` (free text), `next_tool_name` (a `Literal` over the registered tools), and `next_tool_args` (a `dict`). ReAct looks up the tool, calls it with `next_tool_args` as kwargs, appends four trajectory entries (`thought_i`, `tool_name_i`, `tool_args_i`, `observation_i`), and loops. The `Literal` type on `next_tool_name` means the adapter constrains the LM to known tool names, not free-text guesses.++### 6. The `finish` tool is auto-added and is how the loop terminates++ReAct registers an extra `finish` tool — a no-arg callable — and the loop exits when the LM selects it. Making termination a tool rather than a special-cased flag keeps the LM’s choice uniform: pick from the same list every turn, no extra parsing logic. A separate `max_iters` cap is the hard upper bound for cases where the LM never selects `finish`.++### 7. The trajectory is a dict; the adapter decides how it’s rendered++`ReAct._format_trajectory` builds a throwaway signature with one field per trajectory key, then asks the active adapter to render it via `format_user_message_content`. With `ChatAdapter` the trajectory comes out with `[[ ## thought_i ## ]]` markers; with `JSONAdapter` it comes out as a JSON object; with `XMLAdapter` it comes out as tags. ReAct never hand-formats — the adapter does, and the format stays consistent with the rest of the prompt.++### 8. Tool execution errors become observations, not crashes++A raised exception from a tool is caught inside `forward` and recorded as `observation_i = "Execution error in <tool>: <traceback>"`. The LM sees the error text on the next iteration and can react to it. Surfacing failures into the LM’s reasoning loop, rather than terminating the program, is the default an agent expects — the model is supposed to recover.++### 9. A separate extractor module produces the declared outputs++After the loop ends, ReAct hands the trajectory to a `dspy.ChainOfThought` over a fallback signature that includes the original output fields plus a `trajectory` input. The extractor’s job is to read the trajectory and produce the signature’s declared outputs in their correct types. Decoupling navigation (the loop) from extraction (the typed answer) makes both halves easier to optimize and easier to debug.++### 10. Trajectory truncation drops the oldest tool call on context overflow++When `_call_with_potential_trajectory_truncation` catches a `ContextWindowExceededError`, it calls `truncate_trajectory`, which removes the first four keys (one full tool-call’s worth) and retries — up to three rounds. The heuristic: recent observations are most informative for the next step, older context can go. Override `truncate_trajectory` in a subclass to keep summaries, slide a window, or anything else.++### 11. MCP tools are always async; `Tool.from_mcp_tool` is the canonical bridge++`convert_mcp_tool` builds an async `func` that awaits `session.call_tool(name, args)`. Sync access goes through `acall` or the `allow_tool_async_sync_conversion` switch. MCP is async-only because the underlying `mcp.ClientSession` is built on `anyio` task groups and exposes an async API; bridging it sync would block the I/O loop.++### 12. Native function calling is opt-in on adapters, not on tools++Whether the LM gets a `tools=` payload (OpenAI-style function calling) or a text-rendered prompt is the adapter’s decision, not the tool’s. `Tool.format_as_litellm_function_call()` produces the function-calling descriptor; `ChatAdapter`‘s `use_native_function_calling=True` constructor flag opts in. The split exists because the same `Tool` object should work whether or not the LM supports native tool calling — only the wire format changes.++## API walkthrough++Grouped by what you’re trying to do.++### Wrapping a callable as a tool++**`dspy.Tool(func, name=None, desc=None, args=None, arg_types=None, arg_desc=None)`**+A Pydantic model with `func` as its primary field. The constructor calls `_parse_function`, which walks the callable’s signature with `inspect.signature` and `get_type_hints`, derives the JSON schema with `pydantic.TypeAdapter`, and resolves `$ref` paths into inline schemas via `_resolve_json_schema_reference`. Explicit kwargs take precedence: pass `args={...}` and the inference for `args` is skipped, but `arg_types` and `desc` still come from inspection.++**`Tool.__call__(**kwargs)` / `Tool.acall(**kwargs)`**+Both go through `_validate_and_parse_args`, which JSON-schema-validates each kwarg then wraps it in a one-field Pydantic model to coerce nested types like `list[list[MyModel]]`. `__call__` runs the function and inspects the return: if it’s a coroutine, behavior depends on `settings.allow_tool_async_sync_conversion`. `acall` awaits a coroutine return or returns the synchronous value directly — so the async path tolerates sync tools.++**`Tool.format_as_litellm_function_call()`** → `dict`+Returns the OpenAI/LiteLLM tool descriptor: `{"type": "function", "function": {"name", "description", "parameters": {"type": "object", "properties": args, "required": list(args)}}}`. Every declared arg is marked `required` — Pydantic-level defaults aren’t surfaced as optional in the function descriptor.++**`Tool.from_mcp_tool(session, tool)`** → `Tool`+Class method. Delegates to `dspy.utils.mcp.convert_mcp_tool`. Takes a live `mcp.ClientSession` and an `mcp.types.Tool` and returns an async DSPy tool wired to that session.++**`Tool.from_langchain(tool)`** → `Tool`+Class method. Wraps a LangChain `BaseTool` so it can be passed to DSPy modules that accept a `tools=` list. Implementation lives in `dspy.utils.langchain_tool`.++### The ReAct module++**`dspy.ReAct(signature, tools, max_iters=20)`**+On construction, ReAct coerces every entry in `tools` to a `dspy.Tool`, registers the auto-generated `finish` tool, and builds two internal modules: a `dspy.Predict` over a signature whose outputs are `next_thought`, `next_tool_name` (a `Literal` over the tool names), and `next_tool_args` (a `dict`); and a `dspy.ChainOfThought` extractor whose signature contains the original output fields plus a `trajectory` input. The system instructions are assembled with a numbered tool list and embedded into the predict’s signature.++**`ReAct.forward(**inputs)` / `ReAct.aforward(**inputs)`**+Runs the loop described above. Each iteration formats the trajectory through the current adapter and passes it as the `trajectory` input to the predict; tool exceptions are caught and stringified into the trajectory; the loop exits when the LM picks `finish` or `max_iters` is reached. The extractor then reads the final trajectory and produces the declared outputs. Returns a `dspy.Prediction` carrying both the trajectory and the extracted fields.++**`ReAct.truncate_trajectory(trajectory)`**+Removes the first four keys of the trajectory dict — one complete tool call. Called from `_call_with_potential_trajectory_truncation` after a `ContextWindowExceededError`, with up to three rounds before the module raises. Override to keep summaries, slide a window, or implement any other policy.++### Tool calls in the LM response++When an adapter supports native function calling, the LM’s output contains structured tool-call objects rather than text markers. These types model that surface.++**`dspy.ToolCalls(tool_calls: list[ToolCall])`**+A `pydantic.BaseModel` whose single field is a list of `ToolCall` items. A validator accepts several input shapes — a list of dicts, a `{"tool_calls": [...]}` dict, or a single `{"name", "args"}` dict — so adapters parsing from different providers can route through the same constructor.++**`ToolCalls.ToolCall(name, args)`**+A single named function call with its arguments. Nested class, accessible as `dspy.ToolCalls.ToolCall`.++**`ToolCall.execute(functions=None)`** → `Any`+Looks up the named function in a `{name: func}` dict, a list of `Tool` objects, or — when `functions=None` — the caller’s locals and globals (resolved via `inspect.currentframe().f_back`). Raises `ValueError` when the name isn’t found and `RuntimeError` when the underlying function throws.++**`ToolCalls.from_dict_list(tool_calls_dicts)`** → `ToolCalls`+Constructor helper. Builds a `ToolCalls` from a list of `{"name", "args"}` dicts — the shape adapters produce from a provider’s native response.++### MCP bridge++**`dspy.utils.mcp.convert_mcp_tool(session, tool)`** → `Tool`+Builds a `Tool` whose `func` is an `async def` closure: it awaits `session.call_tool(tool.name, arguments=kwargs)` and unpacks the result. The unpacker pulls text from any `TextContent` entries (returning a single string when there’s one, a list otherwise) and returns non-text entries as-is. An `isError=True` response raises `RuntimeError`. The MCP tool’s `inputSchema` is mapped to DSPy’s `args`/`arg_types`/`arg_desc` via `convert_input_schema_to_tool_args`.++**`dspy.utils.mcp.convert_input_schema_to_tool_args(schema)`** → `(args, arg_types, arg_desc)`+Walks an MCP-style JSON schema and produces the three dicts a `Tool` needs. Resolves `$defs`, picks up `description` fields as `arg_desc`, and translates JSON-schema types to Python types via a `_TYPE_MAPPING` table. Exported in case callers want to write their own bridge against a non-MCP protocol with similar JSON-schema arguments.++## Cross-links++- [Adapters: how signatures become prompts](adapters.md) — where `Tool` and `ToolCalls` are formatted onto the wire, and where native function calling is opted into.+- [Built-in module variants](built-in-module-variants.md) — `CodeAct` and `RLM` use the same tool-wrapping machinery in a code-execution context.+- [Modules: composing your own](modules.md) — `ReAct` is a `Module`, so trace, history, and `set_lm` all apply.diff --git a/docs/docs/getting-started/changing-modules.md b/docs/docs/getting-started/changing-modules.mdnew file mode 100644index 000000000..a7dc8154f--- /dev/null+++ b/docs/docs/getting-started/changing-modules.md@@ -0,0 +1,35 @@+# Change inference strategies by changing the module++In our previous examples, we used the `Predict` module to execute our signature.++Other modules define different strategies for executing a task, and trying them out is very simple:++```py+reasoning_haiku_bot = dspy.ChainOfThought(HaikuBot)+result = reasoning_haiku_bot(location="Bodega Bay", mood="mysterious", season="autumn")+print(result.haiku)+```++Which yields:++```+Fog curls over waves+Leaves whisper, gulls glide at night+Moon pierces deep mist+```++Instead of `Predict` we used `ChainOfThought`, a module that prompts the LM to reason before delivering a final answer. Our signature, the class-based `HaikuBot`, is the same. The function call, identical.++But behind the scenes, DSPy modified our signature to prompt the model to reason before producing its final poem. The newly added signature output field, `reasoning`, is now populated by the model’s rationale.++We can view this by printing `result.reasoning`:++```+Bodega Bay in autumn evokes a cool, misty atmosphere, and the mysterious mood invites subtle, haunting imagery. I chose fog, waves, and gulls to ground the poem in the specific coastal setting, while autumnal leaves signal the season. The haiku’s 5‑7‑5 syllable structure preserves the traditional form, allowing each image to resonate briefly. The first line establishes the misty shoreline, the second line introduces quiet, nocturnal movement, and the third line offers a luminous, almost spectral image of the moon cutting through the fog—capturing mystery and the fleeting quality of autumn evenings.+```++`ChainOfThought` is simple, but nicely demonstrates the flexibility of DSPy’s module layer. [Other modules](../diving-deeper/built-in-module-variants.md) implement other strategies, including model ensembles, coding sandboxes, and *tool-calling*, which the next section explores.++---++**Next:** [Tools with ReAct →](react-and-tools.md)diff --git a/docs/docs/getting-started/class-based-signatures.md b/docs/docs/getting-started/class-based-signatures.mdnew file mode 100644index 000000000..992ac49a7--- /dev/null+++ b/docs/docs/getting-started/class-based-signatures.md@@ -0,0 +1,104 @@+# Writing a class-based signature++## Adding instructional nuance with class-based signatures++A class-based signature details the same structure a string signature can, but adds a few levers for adding additional nuance. Here’s our haiku writer string signature rephrased as a class-based signature:++```py+class HaikuBot(dspy.Signature):+ """+ Write a classical haiku given the provided inputs.+ """+ location: str = dspy.InputField(desc="The setting of the poem")+ mood: str = dspy.InputField()+ haiku: str = dspy.OutputField()+```++We have the same fields (`location`, `mood`, and the `haiku` output) typed as strings, but we now have the ability to add descriptions to each. Field descriptions allow us to add nuance that might not fit within a field name.++Class-based signatures also let us write a docstring, the string at the start of the class, which DSPy uses as task instructions when preparing prompts.++We pass class-based signatures to modules just like we passed string signatures:++```py+haiku_bot = dspy.Predict(HaikuBot)+result = haiku_bot(location="a quiet library", mood="mysterious")+print(result.haiku)+```++This call renders and sends similar instructions to the LM, with two exceptions. The docstring and any field descriptions are used when building the system instructions, like so:++```+Your input fields are:+1. `location` (str): The setting of the poem+2. `mood` (str):+Your output fields are:+1. `haiku` (str):+All interactions will be structured in the following way, with the appropriate values filled in.++[[ ## location ## ]]+{location}++[[ ## mood ## ]]+{mood}++[[ ## haiku ## ]]+{haiku}++[[ ## completed ## ]]+In adhering to this structure, your objective is:+ Write a classical haiku given the provided inputs.+```++Signature docstrings and field descriptions are optional, but they are handy levers when field names don’t provide sufficient context for a task. However, resist the urge to restate what the signature already says or write prescriptive tutorials. Expansive rules, watch-outs, and guidance are what optimizers are for (more on that later).++Though it’s worth noting: field descriptions are not touched by the optimizers, so mind your naming. A poorly chosen field name can’t be adjusted by optimizers.++## Tightening signature fields with richer types++Sometimes a plain `str` is too loose. When a value should come from a small fixed set, we’d rather pin it down so the LM (and the caller) can’t drift outside it. This is the unit-test framing from Section 3 made stricter: not just *some string*, but *one of these specific strings*.++We can use `typing`, from Python’s standard lib, to add richer types.++Typing `season` as `Literal["spring", "summer", "autumn", "winter"]` does exactly that. DSPy now accepts only those four values, both at call time and when parsing the LM’s response.++```py+from typing import Literal++Season = Literal[+ "spring", "summer", "autumn", "winter",+]++class HaikuBot(dspy.Signature):+ """+ Write a classical haiku given the provided inputs.+ """+ location: str = dspy.InputField()+ mood: str = dspy.InputField()+ season: Season = dspy.InputField()+ haiku: str = dspy.OutputField()++haiku_bot = dspy.Predict(HaikuBot)+result = haiku_bot(location="Bodega Bay", mood="mysterious", season="autumn")+print(result.haiku)+```++This yields:++```+Fog drifts over waves,+Crimson leaves swirl by the pier—+Night whispers secrets.+```++But if we pass `season="fall"`, we get a warning explaining the mismatch:++```+WARNING dspy.predict.predict: Type mismatch for field 'season': expected Literal['spring', 'summer', 'autumn', 'winter'] based on given Signature, but the provided value is incompatible: fall.+```++See [Signatures in depth](../diving-deeper/signatures-in-depth.md) for the rest of the surface — output validators, multi-output composition, and richer Pydantic patterns.++---++**Next:** [Changing modules →](changing-modules.md)diff --git a/docs/docs/getting-started/composing-modules.md b/docs/docs/getting-started/composing-modules.mdnew file mode 100644index 000000000..b2d080c33--- /dev/null+++ b/docs/docs/getting-started/composing-modules.md@@ -0,0 +1,143 @@+# Composing your own module++Switching to `dspy.ReAct` turned our single-step program into a multi-step agent. It’s a significant change, but `ReAct` itself is simple to understand.++Inside [`dspy.ReAct`](../diving-deeper/tools-react-and-mcp.md), other DSPy modules are composed together. Each step where the model considers its inputs and picks the next tool is a `dspy.Predict` module. A bit of code manages the control flow, looping through `Predict` calls until the model calls `finish` or hits `max_iters`. The synthesis step that follows, where the model assembles the answer from everything it’s learned, is a `ChainOfThought` module.++Modules are modular. We can compose them together and they just *work*.++To illustrate, let’s build a custom module for our haiku writer composed of two modules: one to generate several candidate haikus and one to pick the best verse.++## Composing modules to build an ensemble++LLM-written poems are a roll of the dice. Sometimes their haikus are evocative; other times they’re predictable and bland. To increase our program’s odds of success, we’re going to roll the dice several times, then select the best candidate.++Here’s what this looks like:++```py+class HaikuEnsemble(dspy.Module):+ def __init__(self, n: int = 3):+ super().__init__()+ self.n = n+ # Module 1 generates several haikus+ self.writer = dspy.ReAct(+ "location, season, mood, num_haikus: int -> haikus: list[str]",+ tools=[wikipedia_search, get_wikipedia_page],+ max_iters=5+ )+ # Module 2 picks the most evocative+ self.judge = dspy.ChainOfThought(+ "location, season, mood, candidates: list[str] -> most_evocative_index: int"+ )++ def forward(self, location: str, season: str, mood: str) -> dspy.Prediction:+ candidates = self.writer(+ location=location, season=season, mood=mood, num_haikus=self.n,+ ).haikus+ verdict = self.judge(+ location=location, season=season, mood=mood, candidates=candidates,+ )+ return dspy.Prediction(+ haiku=candidates[verdict.most_evocative_index],+ candidates=candidates,+ reasoning=verdict.reasoning,+ )+```++When constructing a module, we need to write two functions:++1. `__init__` sets up our initial state and defines our submodules.+2. `forward` handles what happens when we call our program, accepting inputs and shepherding through our submodules before returning an assembled output.++Our `HaikuEnsemble` defines two submodules in `__init__`.++1. `writer` is similar to our last `ReAct` program. We’ve added a new input field, `num_haikus`, specifying how many haikus we want the model to draft. And we’ve changed our output field to return a `list` of strings.+2. `judge` is entirely new. It accepts the `location`, `season`, and `mood` inputs in addition to the candidate `haikus`. It selects the most evocative of the bunch.++When we call this program, our `forward` method runs each module in sequence, then returns a single `dspy.Prediction` object containing our results.++If we call:++```py+ensemble = HaikuEnsemble(n=5)+result = ensemble(location="Bodega Bay", season="autumn", mood="inspired")+```++We get the following selected haiku:++```+Mist hugs the harbor+Crimson gulls glide over tide+Leaves whisper to fog+```++And the following reasoning:++```+The prompt asks for the candidate that most vividly evokes Bodega Bay in autumn with an inspired mood.++Bodega Bay is characterized by its foggy harbor, sea gulls, and a crisp coastal environment.++The first candidate (“Mist hugs the harbor\nCrimson gulls glide over tide\nLeaves whisper to fog”) captures the mist‑laden harbor and the motion of gulls, tying the leaves’ whisper to the tide—a direct reference to the coastal setting and autumnal atmosphere.++Other candidates highlight fog or forest imagery, sea‑scapes, or harvest motifs but do not simultaneously convey the harbor, gulls, and mist as strongly. Therefore, the first candidate best aligns with the location, season, and mood.+```++## Using a bigger model as our judge++To make this module a true ensemble, let’s use a different model to grade the work of our haiku writer. We only need to add one line:++```py+class HaikuEnsemble(dspy.Module):+ def __init__(self, n: int = 3):+ super().__init__()+ self.n = n+ # Module 1 generates several haikus+ self.writer = dspy.ReAct(+ "location, season, mood, num_haikus: int -> haikus: list[str]",+ tools=[wikipedia_search, get_wikipedia_page],+ max_iters=5+ )+ # Module 2 picks the most evocative+ self.judge = dspy.ChainOfThought(+ "location, season, mood, candidates: list[str] -> most_evocative_index: int"+ )++ def forward(self, location: str, season: str, mood: str):+ candidates = self.writer(+ location=location, season=season, mood=mood, num_haikus=self.n,+ ).haikus+ # Call a much larger model to evaluate our haikus+ with dspy.context(lm=dspy.LM("openai/gpt-5.4")):+ verdict = self.judge(+ location=location, season=season, mood=mood, candidates=candidates,+ )+ return dspy.Prediction(+ haiku=candidates[verdict.most_evocative_index],+ candidates=candidates,+ reasoning=verdict.reasoning,+ )+```++The [`with dspy.context()`](../diving-deeper/settings-and-context.md) statement allows us to define a new context that sets a new model for the judge call.++## Decompose to isolate, reuse, govern, and optimize++Our haiku task is a small example, but building `HaikuEnsemble` demonstrates how easily we can decompose our programs when necessary. There’s no esoteric chaining API; modules are just Python and the DSPy primitives `Signature`, `Module`, and `LM`.++Reasons to decompose appear as our AI programs grow in complexity and we learn their failure modes. For example, we can use custom modules to:++- **Isolate context:** A wandering investigation step can entertain many candidate subjects, but the final haiku writing call should only see the chosen one. Splitting them keeps each module focused on its own job.+- **Reusable parts across programs:** A well-tuned Wikipedia-research submodule isn’t haiku-specific; it could assist any program that needs trusted grounding. Decomposing lets us reuse it across programs.+- **Route easy work to cheaper models:** Lots of small model calls can gather grounding details quickly and cheaply, while a single call to a stronger model handles the final, nuanced composition.+- **Design custom control flow:** We could run the final haiku through a syllable-count check with an NLP library, and call the writer again if the meter is off.+- **Govern independently inspect steps:** Each submodule is its own object, and each call lands in `inspect_history` separately. When the agent does something surprising, we can call one submodule on its own to see exactly what it returned. For haiku writing this is less of a concern, but for high-risk tasks this ability to audit is critical.+- **More easily evaluate and optimize:** Scoring a single haiku in isolation is hard; “good” cuts across too many dimensions to grade cleanly. Picking the best of three is much easier. Decomposing isolates subtasks we can actually score, which enables evaluation and optimization.++See [Modules: composing your own](../diving-deeper/modules.md) for control-flow patterns (branching, retry loops, parallel calls) and composition beyond this example.++Speaking of evaluation and optimization, it’s time for the next section.++---++**Next:** [Metrics →](metrics.md)diff --git a/docs/docs/getting-started/expanding-signatures.md b/docs/docs/getting-started/expanding-signatures.mdnew file mode 100644index 000000000..b0fb1f0bb--- /dev/null+++ b/docs/docs/getting-started/expanding-signatures.md@@ -0,0 +1,107 @@+# Expanding your signature: more inputs and adding types++## Adding additional inputs and outputs++Adding more fields to signature strings is as easy as separating field names with commas. For example, let’s update our program to accept two inputs, a `location` and `mood`:++```py+haiku_bot = dspy.Predict("location, mood -> haiku")+result = haiku_bot(location="a quiet library", mood="mysterious")+print(result.haiku)+```++This yields:++```+Books whisper in hush+Ink curls in soft dim corners+Night reads in quiet+```++Defining additional outputs works identically:++```py+haiku_bot = dspy.Predict("location, mood -> haiku, haiku_title")+result = haiku_bot(location="a quiet library", mood="mysterious")+print(result.haiku_title)+print("- - -")+print(result.haiku)+```++Yielding:++```+Where the Pages Breath+- - -+Books whisper in hush+Ink curls in soft dim corners+Night reads in quiet+```++## Hone your signature by mindfully naming your fields++The field names we choose aren’t just for our own readability. Unlike traditional programming, where variable names are purely identifiers, the LM reads them too, and uses them to infer what each input and output means.++If we replaced `"location, mood -> haiku"` with `"a, b -> c"`, the LM would be lost. Let’s try it:++```py+haiku_bot = dspy.Predict("a, b -> c")+result = haiku_bot(a="a quiet library", b="mysterious")+print(result.c)+```++This produces:++```+In the quiet library, a mysterious presence seemed to linger between the shelves, as if it had been waiting for someone to notice.+```++Our model doesn’t know we want a haiku, so it just makes a guess.++Naming is the cheapest optimization in DSPy. A field called `research_request` will produce better completions than one called `request`, with no other changes. Signatures are easy to edit; take advantage.++## Typing your fields yields more reliable programs++We can add more specificity to our task by *typing* our fields using the format `name: type`. For example, the signature `"location, mood, contains_pun: bool -> haiku"` accepts a boolean to indicate whether we want our poem to include a pun:++```py+haiku_bot = dspy.Predict("location, mood, contains_pun: bool -> haiku")+result = haiku_bot(location="a quiet library", mood="mysterious", contains_pun=True)+print(result.haiku)+```++Which yields:++```+Dusty hush of books+Spine turns to hush of riddles+Novel jokes echo+```++Inline types instruct DSPy to coerce the LM’s output into the types we ask for, and surface clear warnings when they can’t. This catches a class of silent failures that prompt-only systems hide.++Types also let us communicate structural details that are easier to express in code than in natural language. [Richer types](../diving-deeper/signatures-in-depth.md) – like Pydantic models, `TypedDicts`, or `dataclasses` – can pack plenty of details that help LMs correctly complete a task.++This is especially helpful when typing output fields. For example, if we wanted to modify our program to generate several haikus we could make our output field name plural and type it as a `list[str]`:++```+haiku_bot = dspy.Predict("location, mood -> haikus:list[str]")+result = haiku_bot(location="a sunny beach", mood="relaxed")+print(f"Generated {len(result.haikus)} haikus, here's the first:")+print(result.haikus[0])+```++Which yields:++```+Generated 3 haikus, here's the first:+Sun on sandy toes,+waves breathe slow, worries drift away—+soft light, easy air.+```++Once a program accrues several fields or we want to add nuanced instructions, it’s likely time to graduate to a class-based signature.++---++**Next:** [Class-based signatures →](class-based-signatures.md)diff --git a/docs/docs/getting-started/first-program.md b/docs/docs/getting-started/first-program.mdnew file mode 100644index 000000000..41ca3f177--- /dev/null+++ b/docs/docs/getting-started/first-program.md@@ -0,0 +1,96 @@+# Writing our first DSPy program++In this tutorial we’re building a haiku-generating program, extending it in each section to introduce new DSPy concepts and capabilities.++Let’s start by writing the simplest version of our program and run it, then walk through everything DSPy is doing behind the scenes:++```py+haiku_signature = "subject -> haiku"+haiku_generator = dspy.Predict(haiku_signature)+result = haiku_generator(subject="computer science")+print(result.haiku)+```++The first line specifies our `Signature`. Signature is a core concept in DSPy, and it’s how we define our task. Similar to function signatures in programming, a DSPy Signature describes the inputs a function accepts and the outputs it returns.++The simplest way to define a DSPy Signature is with a string of the form `"inputs -> outputs"`. In our case, we want to provide a `subject` and get back a `haiku`.++Because we are programming with language models, the names of our variables matter. They both define the interface for our program and give the model a hint at our intent. If we change `haiku` to `limerick`, the model would note our cue and produce a limerick instead. Additionally, our program’s output would be accessible as `result.limerick`, rather than `result.haiku`.++To turn our Signature into a callable function, we use `dspy.Predict`. Predict is a kind of [DSPy `Module`](../diving-deeper/modules.md). If Signatures specify *what* we want, Modules define *how* we aim to achieve it. They implement a call-time strategy, manage the control flow, tools, and more.++`Predict` is the foundational Module. Let’s look at what happens when we call `dspy.Predict(haiku_signature)`:++1. The string, `"subject -> haiku"` is parsed into a Signature class, with input and output fields defaulting to type `str`.+2. A default instruction string is generated for the `Signature` instance, in this case: “Given the fields `subject`, produce the fields `haiku`.”+3. A `Predict` module is instantiated with this `Signature`.++`haiku_generator` is now callable. Calling `haiku_generator(subject="computer science")` kicks off the following process:++1. The DSPy settings are checked to ensure an `LM` is configured.+2. An [`Adapter`](../diving-deeper/adapters.md) is used to render the `Signature` and its inputs into messages the `LM` can consume. By default, this is the `ChatAdapter`, but there are JSON, XML, and other variants to format your messages suitable for a given `LM`.+3. The `ChatAdapter` builds the prompt, which includes the `Signature` instructions, the field schema describing the inputs and outputs, formatting instructions, and the provided input (in this case, “computer science”).+4. The messages are sent to the `LM`. Caching is enabled by default so identical calls return cached responses.+5. A response is returned, which the `ChatAdapter` parses to extract the output fields.+6. The `Predict` module returns a `Prediction` object with accessible output fields. Calling `result.haiku` returns the generated haiku.+7. The call is recorded in `LM` history, which can be inspected later with `dspy.inspect_history()`.++Running `print(result.haiku)` produces:++```+Silent code unfolds+Logic threads through hidden paths+Bugs bloom, then resolve+```++In just four lines we built an AI-powered program that reads like software and acts like a function.++DSPy manages all the prompting and templating. Call `dspy.inspect_history(n=1)` to take a look at the formatted prompt our program produced and the string the `lm` returned.++First, DSPy generated the system instructions:++```+Your input fields are:+1. `subject` (str):+Your output fields are:+1. `haiku` (str):+All interactions will be structured in the following way, with the appropriate values filled in.++[[ ## subject ## ]]+{subject}++[[ ## haiku ## ]]+{haiku}++[[ ## completed ## ]]+In adhering to this structure, your objective is:+ Given the fields `subject`, produce the fields `haiku`.+```++The brackets and hashes style is how the default `ChatAdapter` structures the prompt, demarcating inputs and sections.++Next, the adapter templated our input into a user message:++```+[[ ## subject ## ]]+computer science++Respond with the corresponding output fields, starting with the field `[[ ## haiku ## ]]`, and then ending with the marker for `[[ ## completed ## ]]`.+```++DSPy sent both to the `lm`, which produced this response:++```+[[ ## haiku ## ]]+Silent code unfolds+Logic threads through hidden paths+Bugs bloom, then resolve++[[ ## completed ## ]]+```++In DSPy, to produce a prompt you compose a signature and the messages are written for you.++---++**Next:** [Expanding signatures →](expanding-signatures.md)diff --git a/docs/docs/getting-started/gepa-optimization.md b/docs/docs/getting-started/gepa-optimization.mdnew file mode 100644index 000000000..0778c26ef--- /dev/null+++ b/docs/docs/getting-started/gepa-optimization.md@@ -0,0 +1,167 @@+# Prompt Optimizing with GEPA++## Why we optimize prompts++Different language models respond differently to the same prompt. A request that gets clean structured output from one model can confuse another into rambling. Phrasing that works on today’s model can stop working when the provider ships an update next month. [Sometimes a model can’t stop talking about goblins](https://openai.com/index/where-the-goblins-came-from/), for some reason. Learning each model’s quirks by hand is slow, and the work doesn’t transfer.++And even if we stuck with only *one* model, the potential permutations of our word choices and instructions are nearly infinite.++Prompt optimization replaces that hand-tuning loop. We give DSPy a training set and a metric. It then generates variations of your instructions (using an LM), runs your examples with these candidate instructions, and keeps the highest-scoring prompts. We don’t have to know which prompt tricks a particular model responds to; the optimizer finds them.++The savings can be large. An optimized program on a smaller, cheaper model can often match a hand-prompted large model on the same task. Reliability improves as well, because the optimizer selects for what the metric rewards.++[Shopify converted a single-prompt GPT-5 task to DSPy](https://www.youtube.com/watch?v=bxToahwOVpY&t=1404s), moved to a small Qwen model, and optimized with GEPA, yielding a solution \~75x cheaper and \~2x more reliable. [Dropbox used DSPy and prompt optimizers](https://dropbox.tech/machine-learning/optimizing-dropbox-dash-relevance-judge-with-dspy) to move to a smaller model and double program accuracy, labeling “10-100 times more data at the same cost.”++Better yet: when a new model launches next week, we can rerun the optimizer against it and immediately determine if it’s worth swapping in.++## GEPA uses reflection to improve instructions++DSPy ships with [several prompt optimizers](../diving-deeper/choosing-an-optimizer.md), but today we’re going to focus on GEPA.++There are many reasons to like GEPA, but a key feature is it allows our metric to provide text feedback which the LM uses to inform subsequent instructions. Let’s update our original metric to demonstrate how this works:++```py+def haiku_score_gepa(example, prediction, trace=None, pred_name=None, pred_trace=None):+ """+ Penalize verbatim use of the input season string.+ A haiku should evoke the season through imagery, not name it+ directly.+ """+ text = prediction.haiku.lower()+ if example.season.strip().lower() in text:+ return dspy.Prediction(+ score=0.0,+ feedback="Don't reference the input season verbatim."+ )+ return dspy.Prediction(score=1.0, feedback=None)+```++Instead of just returning a score, we can tell the instruction-writing LM *why* a prediction failed or succeeded. Our example here is a bit silly, but this feedback ability is powerful. When labeling data to train against, labelers can jot down notes explaining a nuance in a specific record, which can then be passed to GEPA to guide future instructions. When training with an LM judge, the judge can provide detailed feedback for why a prediction didn’t meet the criteria.++## Expanding our haiku metric++To give our model more of a challenge, we’ve built out our metric to check for many conditions we expect from our haikus, specifically:++- Does it have the correct number of lines?+- Does it have the correct syllable count in each line?+- Does it avoid repeating inputs verbatim?+- Does it avoid the first-person voice?+- Does it have a balanced ratio of parts-of-speech?+- Does it use few adjectives?+- Does it use few articles?+- Does it use the present tense?++We can use the natural-language processing library [spaCy](https://spacy.io/) to assist with most of these measures.++All of these conditions make our metric too long to drop into this walkthrough, but [the code is available here](https://gist.github.com/dbreunig/228848f9b34bcdad6be37fc5f85ec1a0). Drop `haiku_metric.py` next to your notebook and add `from haiku_metric import haiku_metric` to follow along.++## Compiling our optimization++With our metric defined, it’s time to configure our optimizer:++```py+from haiku_metric import haiku_metric++reflection_lm = dspy.LM("openai/gpt-5.4")++optimizer = dspy.GEPA(+ metric=haiku_metric,+ reflection_lm=reflection_lm,+ auto="light",+ num_threads=2,+)+```++The first thing to note here is `reflection_lm`. GEPA lets us choose a separate LM for reflection and instruction writing. This LM looks at our examples and how they score, then rewrites our prompt in an attempt to improve our scores.++When optimizing smaller models, it’s worthwhile to use a larger model as the `reflection_lm`. They’re better reasoners and prompters, and their cost isn’t a concern since they’re called a handful of times during optimization.++In addition to a `reflection_lm`, we set our metric and number of threads. For now we’re using two, but depending on your inference provider you may have to tweak this to avoid any rate limits.++The `auto` argument sets our budget. `auto="light"` evaluates around six candidate prompts before stopping. `"medium"` and `"heavy"` options go further, and our GEPA deep dive covers additional levers we can set.++Finally, we compile our optimized program:++```py+optimized_haiku_bot = optimizer.compile(haiku_bot, trainset=train, valset=val)+```++Now it’s time to grab a beverage and wait.++Behind the scenes, compile runs an iterative loop.++1. GEPA executes our program on training examples with the student LM and scores each result with our metric.+2. Examples and their metric results are sent to the reflection LM, which proposes new instructions.+3. GEPA runs the program again with the new instructions, scores again, and keeps the instruction candidates that score best.++This loop repeats until the budget runs out.++Running this optimizer with `gpt-5.4-nano` and using `gpt-5.4` as our reflection LM, we saw our score climb from 78.1% to 90.1% against our full haiku metric. Compare this to baseline score of `gpt-5.4`, 82.4%.++Once optimized with GEPA, our smaller model is faster, cheaper, and *better* than an unoptimized frontier model.++Let’s quickly save our optimized program, then take a look at how our prompt changed.++```py+optimized_haiku_bot.save("react_gpt_nano_haiku_optimized.json")+```++## GEPA’s improved prompt++As previously discussed, `ReAct` is composed of a `Predict` module that reasons and decides what tools to call and a `ChainOfThought` module that synthesizes the final output. GEPA prompt optimized *both* of these modules.++Inside the JSON file containing our saved program state, we can see both improved instructions.++Our program’s synthesis step started off with these instructions, which we defined in our signature docstring:++```+Write a classical haiku given the provided inputs.+```++After compile, these became:++```+Write a classical haiku from three inputs:++Inputs:+- location+- season+- mood++Output requirements:+- Return only the haiku itself.+- Exactly 3 lines.+- No title, no labels, no explanation, no reasoning, no quotation marks.++Primary success criteria, in order:+1. Exact 5-7-5 syllable counts, one line per count.+2. Exactly 3 lines.+3. A concrete seasonal image or cue appropriate to the given season.+4. Do not repeat the input season or mood words verbatim.+5. Keep diction sparse and image-heavy, with strong noun/verb focus.++Haiku style requirements:+- Use a classical haiku approach: brief, image-centered, present tense, emotionally restrained.+- Evoke the location, season, and mood indirectly through concrete imagery rather than naming them outright.+- Build the poem around one small, observable moment tied to the location.+- Prefer concrete nouns and active present-tense verbs.+- Favor lexical density: most words should carry imagery or action.+- Keep adjectives very sparse; avoid piling on descriptors.+- Avoid abstraction, explanation, commentary, and explicit emotional naming.+- Do not use first-person pronouns.+- Keep article use minimal.++Location handling:+- Anchor the poem clearly in the given location with at least one concrete object, surface, sound, or visual detail from that place.+- If the location is unusual or man-made, pair one specific man-made image from the setting with one seasonal sign.+```++It continues, covering season and mood handling, common failure modes, and detailing a final quality check before output.++Fascinatingly, the same program will optimize differently depending on the model.++See [GEPA in depth](../diving-deeper/gepa-in-depth.md) for the full mechanics: Pareto sampling, per-predictor feedback, `auto` budget translation, and the `detailed_results` audit trail.++---++**Next:** [Saving and loading →](saving-and-loading.md)diff --git a/docs/docs/getting-started/installation.md b/docs/docs/getting-started/installation.mdnew file mode 100644index 000000000..ae99ca10d--- /dev/null+++ b/docs/docs/getting-started/installation.md@@ -0,0 +1,52 @@+# Setting up DSPy++Install DSPy with `pip install dspy` or run `uv add dspy` to add DSPy to a virtual environment. DSPy works in Python 3.10+ environments.++## Connecting to a language model++DSPy connects to language models with the `dspy.LM` class. To set up a language model, we provide a `"provider/model"` format string and an API key:++```py+import dspy++# Pass the key explicitly...+lm = dspy.LM("openai/gpt-5-nano", api_key="YOUR_OPENAI_API_KEY")++dspy.configure(lm=lm)+```++Behind the scenes, DSPy uses the [LiteLLM](https://docs.litellm.ai/docs/#litellm-python-sdk) library to normalize inference providers into a single format. This allows you to provide a LiteLLM model string and connect to nearly any model and its provider. [Click here to search for the full list](https://models.litellm.ai/).++For this tutorial, we could replace the `"openai/gpt-5-nano"` model string and our OpenAI API key with options from Anthropic, Google, OpenRouter, and more. All the examples below will work with any LiteLLM model string, without code changes.++Once we have an `LM`, calling `dspy.configure(lm=lm)` sets our `LM` as the default provider for every DSPy program in the process. This sets our `LM` globally, but we can selectively override this with [`dspy.context`](../diving-deeper/settings-and-context.md) when more granular control is needed.++Let’s ensure everything works by manually calling the model:++```py+messages = [+ {+ "role": "system",+ "content": "You are a helpful assistant"+ },+ {+ "role": "user",+ "content": "What is the capital of France?"+ }+]++print(lm(messages = messages))++```++Which returns:++```+['The capital of France is Paris.']+```++With an `LM` configured, we can proceed to writing our first program.++---++**Next:** [Your first program →](first-program.md)diff --git a/docs/docs/getting-started/metrics.md b/docs/docs/getting-started/metrics.mdnew file mode 100644index 000000000..cb593d7eb--- /dev/null+++ b/docs/docs/getting-started/metrics.md@@ -0,0 +1,87 @@+# Building metrics for evaluation and optimization++## Why optimizers need metrics++Before DSPy can improve our program automatically, we need to tell it what “better” means. That starts with a metric and a baseline evaluation. In this section we’ll see why optimization beats hand-tuning, design a quantifiable metric for our haiku task, and run a baseline score so we have something to beat.++So far we’ve written DSPy programs by hand. Our signatures and instructions are only as good as what we type, with no examples to learn from. The quality of our haikus depends on the base knowledge a given model has about locations and writing haikus.++*Optimizers* close that gap. An optimizer is an algorithm that improves your program automatically, and [DSPy ships several](../diving-deeper/choosing-an-optimizer.md). Some select small input/output pairs (few-shot examples) to include in the prompt as demonstrations. Others rewrite the natural-language instructions in your signatures. A few go further and fine-tune the underlying model. What they share is a loop: run your program many times, keep the version that scores best.++To decide what “better” means, an optimizer needs a *metric*: a Python function that scores a single prediction.++Outside DSPy, evaluation code often spends real effort on structural checks — did the model return valid JSON, are the right fields filled, does the output parse. Signatures already handle structure for us, so our metrics focus on the goal of the task: did the haiku evoke the place, did the answer reach the right conclusion, did the agent do what we asked. Rubrics, judges, and dataset comparisons all aim at that.++There are many ways to define your metric, but most use one or more of these patterns:++- **Labeled data comparisons:** Compare the prediction against a “gold” output, usually labeled by a human expert. For example, a dataset of five-haiku arrays each paired with one ideal pick would let us evaluate and optimize the ensemble judge.+- **Rule-based checks:** Evaluate with code that checks verifiable properties. For our haiku program, this might involve counting lines and syllables in a haiku.+- **[LLM judges](../diving-deeper/metrics-and-evaluation.md):** Evaluate with another, usually larger, model. We might ask a frontier model how well a smaller model’s haiku evokes a place and season, similar to our ensemble’s judge. But here the optimizer bakes those judgments into the smaller model’s instructions once, instead of calling the judge with every inference.++You can get creative and clever with these patterns. For example, we could measure our program’s ability to evoke a specific place by generating sets of haikus from varied location inputs, presenting an LLM judge with the array, and asking it to pick the verse matching a given location.++Today, however, we’re going to keep it simple. We’re going to use a *quantifiable metric* that checks a haiku’s syllable count, line count, tense, first-person usage, and whether it echoes our input terms verbatim.++## Preparing examples from the haiku dataset++We’ve created a dataset of example inputs by randomly grouping locations, seasons, and mood strings. Click here to download the JSONL file, containing 800 rows.++To prepare them for an evaluation or optimization, we need to convert each record into a `dspy.Example` object, like so:++```py+import json++examples = []+with open("haiku_examples.jsonl") as f:+ for line in f:+ row = json.loads(line)+ examples.append(+ dspy.Example(+ location=row["location"],+ season=row["season"],+ mood=row["mood"],+ ).with_inputs("location", "season", "mood")+ )++n = len(examples)+train_end = int(n * 0.75)+val_end = int(n * 0.875)+train, val, test = examples[:train_end], examples[train_end:val_end], examples[val_end:]+```++`.with_inputs` is how you tell DSPy which fields of an `Example` should be passed to the program at call time. In this dataset every field is an input, because our metric will score the haiku against its own rules rather than against a labeled answer. A question-answering dataset is the more typical shape: each row carries `(question, answer)`, you’d call `.with\_inputs(“question”)`, and DSPy would pass only the question to the program while holding `answer` back for the metric.++## Building our evaluation metric++A metric function for `dspy.Evaluate` accepts the original `example` and the program’s `prediction`, and returns a single float. By convention, scores fall in between 0.0 and 1.0 (higher is better).++For our evaluation metrics, let’s keep it super simple and only check if our season or mood inputs are being used verbatim in the haiku:++```py+def haiku_score(example, prediction) -> float:+ """+ Penalize verbatim use of the input season string.+ A haiku should evoke the season through imagery, not name it+ directly.+ """+ text = prediction.haiku.lower()+ if example.season.strip().lower() in text:+ return 0.0+ return 1.0+```++Then we call `Evaluate`:++```py+evaluate = dspy.Evaluate(devset=val, metric=haiku_score)+baseline_score = evaluate(haiku_bot)+print(baseline_score)+```++Our `dspy.ReAct` haiku writer, powered by `gpt-5.4-nano`, scores only 30% on this metric. And that makes sense. Our rule isn’t a hard and fast rule of haikus, so our model won’t adhere to it driven only by its weights. And our signatures gave no clues this was our objective.++See [Metrics and evaluation](../diving-deeper/metrics-and-evaluation.md) for composite scoring, LLM judges, and test-set hygiene.++---++**Next:** [GEPA optimization →](gepa-optimization.md)diff --git a/docs/docs/getting-started/program-dont-prompt.md b/docs/docs/getting-started/program-dont-prompt.mdnew file mode 100644index 000000000..44915644f--- /dev/null+++ b/docs/docs/getting-started/program-dont-prompt.md@@ -0,0 +1,24 @@+# Program, don’t prompt++DSPy is a declarative way to build with LLMs.++We describe our tasks as structured inputs and outputs. Often, we compose multiple tasks into multi-step programs and agents where each piece stays independently inspectable, swappable, and tunable. DSPy handles prompt construction, context management, and optimization that tunes each step to improve the whole program.++When a step needs to act on the world (to search, fetch, or compute), we give it tools as plain Python functions. Functions also serve as metrics: you define one to grade the output, and DSPy generates a better program accordingly. The optimizer tunes the prompt for any model you pick, so a small, cheap model can often match or beat a hand-prompted frontier one..++DSPy helps us program LLMs, rather than prompting them, creating modular, maintainable and optimizable AI software.++## What we’ll learn today++In this tutorial we’ll build a haiku-writing program that starts with four lines of Python and grows into a tool-using, prompt-optimized agent. Along the way we’ll touch each of DSPy’s core components. We’ll learn:++- How to install DSPy, configure a **language model** and write a simple DSPy program.+- What a **Signature** is, and why DSPy uses signatures instead of hand-written prompt strings.+- What a **Module** is, how `Predict`, `ChainOfThought`, and `ReAct` differ, and when to reach for each.+- How to compose a custom `dspy.Module` that decomposes a task into named, independent stages.+- How to write **metrics** and use **optimizers** to compile better versions of our program.+- How to save optimized programs and reload them.++---++**Next:** [Setting up DSPy →](installation.md)diff --git a/docs/docs/getting-started/react-and-tools.md b/docs/docs/getting-started/react-and-tools.mdnew file mode 100644index 000000000..3e7f60919--- /dev/null+++ b/docs/docs/getting-started/react-and-tools.md@@ -0,0 +1,99 @@+# Give the program tools with `dspy.ReAct`++## Grounding our program with tools++Our haiku writer is competent, but it could use more information about the locations we name. When asked for a haiku set in Bodega Bay in autumn, our LM makes plausible guesses about the weather, but sometimes gets them wrong. Giving the program tools allows our program to research and ground its references before writing its verse.++## Tools are just Python functions++A DSPy tool is a standard Python function, with type-hinted parameters and a docstring. DSPy reads the name, parameters, and docstring of a function to assemble the instructions it sends to an LM.++For example, let’s define a tool that lets an agent search Wikipedia using the [`wikipedia`](https://pypi.org/project/wikipedia/) library (run `pip install wikipedia`, if you’re following along):++```py+import wikipedia++def wikipedia_search(query: str) -> list[str]:+ """Search Wikipedia for the given query and return a list of page titles."""+ return wikipedia.search(query)+```++The `dspy.ReAct` module presents it like so:++```+When selecting the next_tool_name and its next_tool_args, the tool must be one of:++(1) wikipedia_search, whose description is <desc>Search Wikipedia for the given query and return a list of page titles.</desc>. It takes arguments {'query': {'type': 'string'}}.+(2) finish, whose description is <desc>Marks the task as complete. That is, signals that all information for producing the outputs, i.e. `haiku`, are now available to be extracted.</desc>. It takes arguments {}.+```++Note how DSPy presents the function name, docstring, and parameters to the model. Writing tools, like signatures, requires being mindful about naming. `wikipedia_search` and the parameter `query` are helpful names, that clearly describe their function and role.++Note that there’s a tool in the mix that we didn’t define. `finish` is a special tool used by `dspy.ReAct` that the model calls when it’s done. `dspy.ReAct` populates that one for us.++## Defining our Wikipedia-wielding haiku bot++In addition to searching Wikipedia, we’ll need a tool that lets our agent fetch a given page:++```py+def get_wikipedia_page(title: str) -> str:+ """Get the content of a Wikipedia page given its title."""+ return wikipedia.page(title).content+```++With these two tools and our existing `HaikuBot` signature, we have all we need to define our agent:++```py+haiku_bot = dspy.ReAct(HaikuBot, tools=[wikipedia_search, get_wikipedia_page])+result = haiku_bot(location="Camp Meeker", mood="pensive", season="summer")+print(result.haiku)+```++When we called `haiku_bot` it:++1. Searched Wikipedia for “Camp Meeker”, which yielded nine relevant results, including “Camp Meeker, California”.+2. Fetched the page content for “Camp Meeker, California”.+3. Called `finish`, then synthesized its outputs.++The code above yields:++```+Redwood shadows breathe+Summer creek whispers old tales+Quiet mind lingers+```++Printing `result.reasoning` produces:++```+I gathered context about Camp Meeker, California—its redwood forest, Dutch Bill Creek, and the quiet summer atmosphere—from the Wikipedia page. I focused on a pensive mood and the summer season, weaving in imagery of towering trees and a gently flowing creek. The haiku follows the traditional 5‑7‑5 syllable structure, evoking the stillness and reflection of a summer day among the redwoods.+```++## ReAct manages an agentic loop++ReAct is a test-time (or inference time) loop strategy. We hand the model a set of tools and a task. The `dspy.ReAct` module instructs the model to reason then act using its tools. When the model calls `finish`, DSPy stops the loop and runs one last synthesis pass to produce the declared output fields.++The model decides how many loops to run, but we can cap the number with the `max_iters` parameter, like so:++```+haiku_bot = dspy.ReAct(HaikuBot, tools=[wikipedia_search, get_wikipedia_page], max_iters=4)+```++While testing this program, we saw runs where the model made as many as 8 tool calls (investigating Vermont syrup farming) and runs where it skipped research entirely.++## Inspecting the ReAct trajectory++ReAct’s returned `Prediction` instance carries a `trajectory` field: a dictionary that records each thought, tool call, and observation (what the tool returned) in order. When an agent does something surprising, the trajectory is the first thing to read.++We can print it like so:++```py+for step, value in result.trajectory.items():+ print(f"{step}: {value}")+```++For tool authoring patterns, MCP integration, and trajectory debugging, see [Tools, ReAct, and MCP](../diving-deeper/tools-react-and-mcp.md).++---++**Next:** [Composing modules →](composing-modules.md)diff --git a/docs/docs/getting-started/saving-and-loading.md b/docs/docs/getting-started/saving-and-loading.mdnew file mode 100644index 000000000..842e300fc--- /dev/null+++ b/docs/docs/getting-started/saving-and-loading.md@@ -0,0 +1,38 @@+# Saving a program and reloading it++## Saving the optimized state, or the entire program++`.save(path)` has two modes. Pointing it at a `.json` file stores just the program’s learned *state*, the optimized instructions and few-shot demos, not the program’s *structure*. Pointing it at a directory with `save_program=True` writes the entire module as a pickled artifact, structure and state together.++The state-only mode is what you usually want. The JSON is small, human-readable, safe to share, and easy to diff in version control. To reload it, you instantiate your program in code as usual and call `.load()` to apply the saved state on top.++Reach for `save_program=True` when whoever is loading the program won’t have your Python class definitions handy. Shipping an optimized program to another team is one example; serving it from a different repo than the one you developed it in is another. The cost is that the saved directory contains executable Python, so only load programs from sources you trust.++```py+# state-only — small file, requires re-instantiating the program before loading+optimized_haiku_bot.save("haiku_bot.json")++# whole program — directory, rehydrates without you re-defining the class+optimized_haiku_bot.save("haiku_bot/", save_program=True)+```++## Reloading a saved program++For the directory form, `dspy.load(path)` rehydrates the full module in one call. For the state-only form, you build a fresh copy of the program in code and call `.load(path)` on it to apply the saved state.++```py+# whole program+loaded = dspy.load("haiku_bot/")++# state-only+fresh = dspy.ReAct(HaikuBot, tools=[wikipedia_search, get_wikipedia_page])+fresh.load("haiku_bot.json")+```++The save file contains the optimized instructions, demos, and signature metadata. It does not contain the LM client configuration: your API keys, your provider choice, your temperature. That separation is intentional: configure your LM as usual after loading and the same program targets whichever model you point it at today.++See [Saving and loading](../diving-deeper/saving-and-loading.md) for versioning saved programs, swapping models against the same checkpoint, and managing demo lifecycles.++---++**Next:** [Where to go next →](where-to-go-next.md)diff --git a/docs/docs/getting-started/where-to-go-next.md b/docs/docs/getting-started/where-to-go-next.mdnew file mode 100644index 000000000..dd54fb8ec--- /dev/null+++ b/docs/docs/getting-started/where-to-go-next.md@@ -0,0 +1,25 @@+# Where to go next++## Compose harder pipelines++If you want multi-step modules with branching control flow, the [Modules: composing your own](../diving-deeper/modules.md) guide picks up where Section 7 left off.++## Building richer metrics++Our haiku metric was intentionally simple. Programs usually need composite scores that blend syntax checks, semantic similarity, and/or LLM-as-judge rubrics. The [Metrics: designing and composing](../diving-deeper/metrics-and-evaluation.md) guide walks through weighting sub-scores, preventing keyword-stuffing, and validating that your metric truly captures what you care about before you let an optimizer chase it.++## Go deeper on GEPA++The [GEPA in depth](../diving-deeper/gepa-in-depth.md) guide covers Pareto sampling, per-predictor feedback, `auto` budget translation, and the `detailed_results` audit trail.++## Try a different optimizer++If GEPA didn’t fit your task, the [Optimizers: choosing one](../diving-deeper/choosing-an-optimizer.md) guide walks through when to reach for `BootstrapFewShot`, `MIPROv2`, `BootstrapFinetune`, and the rest.++## Debug a run++Calls and traces are inspectable with `dspy.inspect_history()` and callbacks — see the [Observability and debugging](../tutorials/observability/index.md) guide.++## Serve in production++Programs can be made async, streamed, and parallelized. The [Async, streaming, and parallel](../tutorials/async/index.md) guide covers the surface.diff --git a/docs/docs/index.md b/docs/docs/index.mdindex adcc20e14..3fb1f8ede 100644--- a/docs/docs/index.md+++ b/docs/docs/index.md@@ -1,453 +1,6 @@----sidebar_position: 1+template: home.htmlhide:- navigation- toc------{ width="200", align=left }--# _Programming_—not prompting—_LMs_--[](https://pepy.tech/projects/dspy) [](https://pepy.tech/projects/dspy)--DSPy is a declarative framework for building modular AI software. It allows you to **iterate fast on structured code**, rather than brittle strings, and offers algorithms that **compile AI programs into effective prompts and weights** for your language models, whether you're building simple classifiers, sophisticated RAG pipelines, or Agent loops.--Instead of wrangling prompts or training jobs, DSPy (Declarative Self-improving Python) enables you to **build AI software from natural-language modules** and to _generically compose them_ with different models, inference strategies, or learning algorithms. This makes AI software **more reliable, maintainable, and portable** across models and strategies.--*tl;dr* Think of DSPy as a higher-level language for AI programming, like the shift from assembly to C or pointer arithmetic to SQL. Meet the community, seek help, or start contributing via [GitHub](https://github.com/stanfordnlp/dspy) and [Discord](https://discord.gg/XCGy2WDCQB).--<!-- Its abstractions make your AI software more reliable and maintainable, and allow it to become more portable as new models and learning techniques emerge. It's also just rather elegant! -->--!!! info "Getting Started I: Install DSPy and set up your LM"-- ```bash- > pip install -U dspy- ```-- === "OpenAI"- You can authenticate by setting the `OPENAI_API_KEY` env variable or passing `api_key` below.-- ```python linenums="1"- import dspy- lm = dspy.LM("openai/gpt-5-mini", api_key="YOUR_OPENAI_API_KEY")- dspy.configure(lm=lm)- ```-- === "Anthropic"- You can authenticate by setting the `ANTHROPIC_API_KEY` env variable or passing `api_key` below.-- ```python linenums="1"- import dspy- lm = dspy.LM("anthropic/claude-sonnet-4-5-20250929", api_key="YOUR_ANTHROPIC_API_KEY")- dspy.configure(lm=lm)- ```-- === "Databricks"- If you're on the Databricks platform, authentication is automatic via their SDK. If not, you can set the env variables `DATABRICKS_API_KEY` and `DATABRICKS_API_BASE`, or pass `api_key` and `api_base` below.-- ```python linenums="1"- import dspy- lm = dspy.LM(- "databricks/databricks-llama-4-maverick",- api_key="YOUR_DATABRICKS_ACCESS_TOKEN",- api_base="YOUR_DATABRICKS_WORKSPACE_URL", # e.g.: https://dbc-64bf4923-e39e.cloud.databricks.com/serving-endpoints- )- dspy.configure(lm=lm)- ```-- === "Gemini"- You can authenticate by setting the `GEMINI_API_KEY` env variable or passing `api_key` below.-- ```python linenums="1"- import dspy- lm = dspy.LM("gemini/gemini-2.5-flash", api_key="YOUR_GEMINI_API_KEY")- dspy.configure(lm=lm)- ```-- === "Local LMs on your laptop"- First, install [Ollama](https://github.com/ollama/ollama) and launch its server with your LM.-- ```bash- > curl -fsSL https://ollama.ai/install.sh | sh- > ollama run llama3.2:1b- ```-- Then, connect to it from your DSPy code.-- ```python linenums="1"- import dspy- lm = dspy.LM("ollama_chat/llama3.2:1b", api_base="http://localhost:11434", api_key="")- dspy.configure(lm=lm)- ```-- === "Local LMs on a GPU server"- First, install [SGLang](https://docs.sglang.ai/get_started/install.html) and launch its server with your LM.-- ```bash- > pip install "sglang[all]"- > pip install flashinfer -i https://flashinfer.ai/whl/cu121/torch2.4/-- > CUDA_VISIBLE_DEVICES=0 python -m sglang.launch_server --port 7501 --model-path meta-llama/Llama-3.1-8B-Instruct- ```-- If you don't have access from Meta to download `meta-llama/Llama-3.1-8B-Instruct`, use `Qwen/Qwen2.5-7B-Instruct` for example.-- Next, connect to your local LM from your DSPy code as an `OpenAI`-compatible endpoint.-- ```python linenums="1"- lm = dspy.LM("openai/meta-llama/Llama-3.1-8B-Instruct",- api_base="http://localhost:7501/v1", # ensure this points to your port- api_key="local", model_type="chat")- dspy.configure(lm=lm)- ```-- === "Other providers"- In DSPy, you can use any of the dozens of [LLM providers supported by LiteLLM](https://docs.litellm.ai/docs/providers). Simply follow their instructions for which `{PROVIDER}_API_KEY` to set and how to write pass the `{provider_name}/{model_name}` to the constructor.-- Some examples:-- - `anyscale/mistralai/Mistral-7B-Instruct-v0.1`, with `ANYSCALE_API_KEY`- - `together_ai/togethercomputer/llama-2-70b-chat`, with `TOGETHERAI_API_KEY`- - `sagemaker/<your-endpoint-name>`, with `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION_NAME`- - `azure/<your_deployment_name>`, with `AZURE_API_KEY`, `AZURE_API_BASE`, `AZURE_API_VERSION`, and the optional `AZURE_AD_TOKEN` and `AZURE_API_TYPE`--- If your provider offers an OpenAI-compatible endpoint, just add an `openai/` prefix to your full model name.-- ```python linenums="1"- import dspy- lm = dspy.LM("openai/your-model-name", api_key="PROVIDER_API_KEY", api_base="YOUR_PROVIDER_URL")- dspy.configure(lm=lm)- ```--??? "Calling the LM directly."-- Idiomatic DSPy involves using _modules_, which we define in the rest of this page. However, it's still easy to call the `lm` you configured above directly. This gives you a unified API and lets you benefit from utilities like automatic caching.-- ```python linenums="1"- lm("Say this is a test!", temperature=0.7) # => ['This is a test!']- lm(messages=[{"role": "user", "content": "Say this is a test!"}]) # => ['This is a test!']- ```---## 1) **Modules** help you describe AI behavior as _code_, not strings.--To build reliable AI systems, you must iterate fast. But maintaining prompts makes that hard: it forces you to tinker with strings or data _every time you change your LM, metrics, or pipeline_. Having built over a dozen best-in-class compound LM systems since 2020, we learned this the hard way—and so built DSPy to decouple AI system design from messy incidental choices about specific LMs or prompting strategies.--DSPy shifts your focus from tinkering with prompt strings to **programming with structured and declarative natural-language modules**. For every AI component in your system, you specify input/output behavior as a _signature_ and select a _module_ to assign a strategy for invoking your LM. DSPy expands your signatures into prompts and parses your typed outputs, so you can compose different modules together into ergonomic, portable, and optimizable AI systems.---!!! info "Getting Started II: Build DSPy modules for various tasks"- Try the examples below after configuring your `lm` above. Adjust the fields to explore what tasks your LM can do well out of the box. Each tab below sets up a DSPy module, like `dspy.Predict`, `dspy.ChainOfThought`, or `dspy.ReAct`, with a task-specific _signature_. For example, `question -> answer: float` tells the module to take a question and to produce a `float` answer.-- === "Math"-- ```python linenums="1"- math = dspy.ChainOfThought("question -> answer: float")- math(question="Two dice are tossed. What is the probability that the sum equals two?")- ```-- **Possible Output:**- ```text- Prediction(- reasoning='When two dice are tossed, each die has 6 faces, resulting in a total of 6 x 6 = 36 possible outcomes. The sum of the numbers on the two dice equals two only when both dice show a 1. This is just one specific outcome: (1, 1). Therefore, there is only 1 favorable outcome. The probability of the sum being two is the number of favorable outcomes divided by the total number of possible outcomes, which is 1/36.',- answer=0.0277776- )- ```-- === "RAG"-- ```python linenums="1"- def search_wikipedia(query: str) -> list[str]:- results = dspy.ColBERTv2(url="http://20.102.90.50:2017/wiki17_abstracts")(query, k=3)- return [x["text"] for x in results]-- rag = dspy.ChainOfThought("context, question -> response")-- question = "What's the name of the castle that David Gregory inherited?"- rag(context=search_wikipedia(question), question=question)- ```-- **Possible Output:**- ```text- Prediction(- reasoning='The context provides information about David Gregory, a Scottish physician and inventor. It specifically mentions that he inherited Kinnairdy Castle in 1664. This detail directly answers the question about the name of the castle that David Gregory inherited.',- response='Kinnairdy Castle'- )- ```-- === "Classification"-- ```python linenums="1"- from typing import Literal-- class Classify(dspy.Signature):- """Classify sentiment of a given sentence."""-- sentence: str = dspy.InputField()- sentiment: Literal["positive", "negative", "neutral"] = dspy.OutputField()- toxicity: float = dspy.OutputField()-- classify = dspy.Predict(Classify)- classify(sentence="This book was super fun to read, though not the last chapter.")- ```-- **Possible Output:**-- ```text- Prediction(- sentiment='positive',- toxicity=0.15- )- ```-- === "Information Extraction"-- ```python linenums="1"- class ExtractInfo(dspy.Signature):- """Extract structured information from text."""-- text: str = dspy.InputField()- title: str = dspy.OutputField()- headings: list[str] = dspy.OutputField()- entities: list[dict[str, str]] = dspy.OutputField(desc="a list of entities and their metadata")-- module = dspy.Predict(ExtractInfo)-- text = "Apple Inc. announced its latest iPhone 14 today." \- "The CEO, Tim Cook, highlighted its new features in a press release."- response = module(text=text)-- print(response.title)- print(response.headings)- print(response.entities)- ```-- **Possible Output:**- ```text- Apple Inc. Announces iPhone 14- ['Introduction', "CEO's Statement", 'New Features']- [{'name': 'Apple Inc.', 'type': 'Organization'}, {'name': 'iPhone 14', 'type': 'Product'}, {'name': 'Tim Cook', 'type': 'Person'}]- ```-- === "Agents"-- ```python linenums="1"- def evaluate_math(expression: str):- return dspy.PythonInterpreter({}).execute(expression)-- def search_wikipedia(query: str):- results = dspy.ColBERTv2(url="http://20.102.90.50:2017/wiki17_abstracts")(query, k=3)- return [x["text"] for x in results]-- react = dspy.ReAct("question -> answer: float", tools=[evaluate_math, search_wikipedia])-- pred = react(question="What is 9362158 divided by the year of birth of David Gregory of Kinnairdy castle?")- print(pred.answer)- ```-- **Possible Output:**-- ```text- 5761.328- ```-- === "Multi-Stage Pipelines"-- ```python linenums="1"- class Outline(dspy.Signature):- """Outline a thorough overview of a topic."""-- topic: str = dspy.InputField()- title: str = dspy.OutputField()- sections: list[str] = dspy.OutputField()- section_subheadings: dict[str, list[str]] = dspy.OutputField(desc="mapping from section headings to subheadings")-- class DraftSection(dspy.Signature):- """Draft a top-level section of an article."""-- topic: str = dspy.InputField()- section_heading: str = dspy.InputField()- section_subheadings: list[str] = dspy.InputField()- content: str = dspy.OutputField(desc="markdown-formatted section")-- class DraftArticle(dspy.Module):- def __init__(self):- self.build_outline = dspy.ChainOfThought(Outline)- self.draft_section = dspy.ChainOfThought(DraftSection)-- def forward(self, topic):- outline = self.build_outline(topic=topic)- sections = []- for heading, subheadings in outline.section_subheadings.items():- section, subheadings = f"## {heading}", [f"### {subheading}" for subheading in subheadings]- section = self.draft_section(topic=outline.title, section_heading=section, section_subheadings=subheadings)- sections.append(section.content)- return dspy.Prediction(title=outline.title, sections=sections)-- draft_article = DraftArticle()- article = draft_article(topic="World Cup 2002")- ```-- **Possible Output:**-- A 1500-word article on the topic, e.g.-- ```text- ## Qualification Process-- The qualification process for the 2002 FIFA World Cup involved a series of..... [shortened here for presentation].-- ### UEFA Qualifiers-- The UEFA qualifiers involved 50 teams competing for 13..... [shortened here for presentation].-- .... [rest of the article]- ```-- Note that DSPy makes it straightforward to optimize multi-stage modules like this. As long as you can evaluate the _final_ output of the system, every DSPy optimizer can tune all of the intermediate modules.--??? "Using DSPy in practice: from quick scripting to building sophisticated systems."-- Standard prompts conflate interface ("what should the LM do?") with implementation ("how do we tell it to do that?"). DSPy isolates the former as _signatures_ so we can infer the latter or learn it from data — in the context of a bigger program.-- Even before you start using optimizers, DSPy's modules allow you to script effective LM systems as ergonomic, portable _code_. Across many tasks and LMs, we maintain _signature test suites_ that assess the reliability of the built-in DSPy adapters. Adapters are the components that map signatures to prompts prior to optimization. If you find a task where a simple prompt consistently outperforms idiomatic DSPy for your LM, consider that a bug and [file an issue](https://github.com/stanfordnlp/dspy/issues). We'll use this to improve the built-in adapters.---## 2) **Optimizers** tune the prompts and weights of your AI modules.--DSPy provides you with the tools to compile high-level code with natural language annotations into the low-level computations, prompts, or weight updates that align your LM with your program's structure and metrics. If you change your code or your metrics, you can simply re-compile accordingly.--Given a few tens or hundreds of representative _inputs_ of your task and a _metric_ that can measure the quality of your system's outputs, you can use a DSPy optimizer. Different optimizers in DSPy work by **synthesizing good few-shot examples** for every module, like `dspy.BootstrapRS`,<sup>[1](https://arxiv.org/abs/2310.03714)</sup> **proposing and intelligently exploring better natural-language instructions** for every prompt, like [`dspy.GEPA`](https://dspy.ai/tutorials/gepa_ai_program/)<sup>[2](https://arxiv.org/abs/2507.19457)</sup>, `dspy.MIPROv2`,<sup>[3](https://arxiv.org/abs/2406.11695)</sup> and **building datasets for your modules and using them to finetune the LM weights** in your system, like `dspy.BootstrapFinetune`.<sup>[4](https://arxiv.org/abs/2407.10930)</sup> For detailed tutorials on running `dspy.GEPA`, please take a look at [dspy.GEPA tutorials](https://dspy.ai/tutorials/gepa_ai_program/).---!!! info "Getting Started III: Optimizing the LM prompts or weights in DSPy programs"- A typical simple optimization run costs on the order of $2 USD and takes around 20 minutes, but be careful when running optimizers with very large LMs or very large datasets.- Optimization can cost as little as a few cents or up to tens of dollars, depending on your LM, dataset, and configuration.-- Examples below rely on HuggingFace/datasets, you can install it by the command below.-- ```bash- > pip install -U datasets- ```-- === "Optimizing prompts for a ReAct agent"- This is a minimal but fully runnable example of setting up a `dspy.ReAct` agent that answers questions via- search from Wikipedia and then optimizing it using `dspy.MIPROv2` in the cheap `light` mode on 500- question-answer pairs sampled from the `HotPotQA` dataset.-- ```python linenums="1"- import dspy- from dspy.datasets import HotPotQA-- dspy.configure(lm=dspy.LM("openai/gpt-4o-mini"))-- def search_wikipedia(query: str) -> list[str]:- results = dspy.ColBERTv2(url="http://20.102.90.50:2017/wiki17_abstracts")(query, k=3)- return [x["text"] for x in results]-- trainset = [x.with_inputs('question') for x in HotPotQA(train_seed=2024, train_size=500).train]- react = dspy.ReAct("question -> answer", tools=[search_wikipedia])-- tp = dspy.MIPROv2(metric=dspy.evaluate.answer_exact_match, auto="light", num_threads=24)- optimized_react = tp.compile(react, trainset=trainset)- ```-- An informal run like this raises ReAct's score from 24% to 51%, by teaching `gpt-4o-mini` more about the specifics of the task.-- === "Optimizing prompts for RAG"- Given a retrieval index to `search`, your favorite `dspy.LM`, and a small `trainset` of questions and ground-truth responses, the following code snippet can optimize your RAG system with long outputs against the built-in `SemanticF1` metric, which is implemented as a DSPy module.-- ```python linenums="1"- class RAG(dspy.Module):- def __init__(self, num_docs=5):- self.num_docs = num_docs- self.respond = dspy.ChainOfThought("context, question -> response")-- def forward(self, question):- context = search(question, k=self.num_docs) # defined in tutorial linked below- return self.respond(context=context, question=question)-- tp = dspy.MIPROv2(metric=dspy.evaluate.SemanticF1(decompositional=True), auto="medium", num_threads=24)- optimized_rag = tp.compile(RAG(), trainset=trainset, max_bootstrapped_demos=2, max_labeled_demos=2)- ```-- For a complete RAG example that you can run, start this [tutorial](tutorials/rag/index.ipynb). It improves the quality of a RAG system over a subset of StackExchange communities by 10% relative gain.-- === "Optimizing weights for Classification"- <details><summary>Click to show dataset setup code.</summary>-- ```python linenums="1"- import random- from typing import Literal-- from datasets import load_dataset-- import dspy- from dspy.datasets import DataLoader-- # Load the Banking77 dataset.- CLASSES = load_dataset("PolyAI/banking77", split="train", trust_remote_code=True).features["label"].names- kwargs = {"fields": ("text", "label"), "input_keys": ("text",), "split": "train", "trust_remote_code": True}-- # Load the first 2000 examples from the dataset, and assign a hint to each *training* example.- trainset = [- dspy.Example(x, hint=CLASSES[x.label], label=CLASSES[x.label]).with_inputs("text", "hint")- for x in DataLoader().from_huggingface(dataset_name="PolyAI/banking77", **kwargs)[:2000]- ]- random.Random(0).shuffle(trainset)- ```- </details>-- ```python linenums="1"- import dspy- lm=dspy.LM('openai/gpt-4o-mini-2024-07-18')-- # Define the DSPy module for classification. It will use the hint at training time, if available.- signature = dspy.Signature("text, hint -> label").with_updated_fields("label", type_=Literal[tuple(CLASSES)])- classify = dspy.ChainOfThought(signature)- classify.set_lm(lm)-- # Optimize via BootstrapFinetune.- optimizer = dspy.BootstrapFinetune(metric=(lambda x, y, trace=None: x.label == y.label), num_threads=24)- optimized = optimizer.compile(classify, trainset=trainset)-- optimized(text="What does a pending cash withdrawal mean?")-- # For a complete fine-tuning tutorial, see: https://dspy.ai/tutorials/classification_finetuning/- ```-- **Possible Output (from the last line):**- ```text- Prediction(- reasoning='A pending cash withdrawal indicates that a request to withdraw cash has been initiated but has not yet been completed or processed. This status means that the transaction is still in progress and the funds have not yet been deducted from the account or made available to the user.',- label='pending_cash_withdrawal'- )- ```-- An informal run similar to this on DSPy 2.5.29 raises GPT-4o-mini's score 66% to 87%.---??? "What's an example of a DSPy optimizer? How do different optimizers work?"-- Take the `dspy.MIPROv2` optimizer as an example. First, MIPRO starts with the **bootstrapping stage**. It takes your program, which may be unoptimized at this point, and runs it many times across different inputs to collect traces of input/output behavior for each one of your modules. It filters these traces to keep only those that appear in trajectories scored highly by your metric. Second, MIPRO enters its **grounded proposal stage**. It previews your DSPy program's code, your data, and traces from running your program, and uses them to draft many potential instructions for every prompt in your program. Third, MIPRO launches the **discrete search stage**. It samples mini-batches from your training set, proposes a combination of instructions and traces to use for constructing every prompt in the pipeline, and evaluates the candidate program on the mini-batch. Using the resulting score, MIPRO updates a surrogate model that helps the proposals get better over time.-- One thing that makes DSPy optimizers so powerful is that they can be composed. You can run `dspy.MIPROv2` and use the produced program as an input to `dspy.MIPROv2` again or, say, to `dspy.BootstrapFinetune` to get better results. This is partly the essence of `dspy.BetterTogether`. Alternatively, you can run the optimizer and then extract the top-5 candidate programs and build a `dspy.Ensemble` of them. This allows you to scale _inference-time compute_ (e.g., ensembles) as well as DSPy's unique _pre-inference time compute_ (i.e., optimization budget) in highly systematic ways.----<!-- Future:-BootstrapRS or MIPRO on ??? with a local SGLang LM-BootstrapFS on MATH with a tiny LM like Llama-3.2 with Ollama (maybe with a big teacher) -->----## 3) **DSPy's Ecosystem** advances open-source AI research.--Compared to monolithic LMs, DSPy's modular paradigm enables a large community to improve the compositional architectures, inference-time strategies, and optimizers for LM programs in an open, distributed way. This gives DSPy users more control, helps them iterate much faster, and allows their programs to get better over time by applying the latest optimizers or modules.--The DSPy research effort started at Stanford NLP in Feb 2022, building on what we had learned from developing early [compound LM systems](https://bair.berkeley.edu/blog/2024/02/18/compound-ai-systems/) like [ColBERT-QA](https://arxiv.org/abs/2007.00814), [Baleen](https://arxiv.org/abs/2101.00436), and [Hindsight](https://arxiv.org/abs/2110.07752). The first version was released as [DSP](https://arxiv.org/abs/2212.14024) in Dec 2022 and evolved by Oct 2023 into [DSPy](https://arxiv.org/abs/2310.03714). Thanks to [250 contributors](https://github.com/stanfordnlp/dspy/graphs/contributors), DSPy has introduced hundreds of thousands of people to building and optimizing modular LM programs.--Since then, DSPy's community has produced a large body of work on optimizers, like [MIPROv2](https://arxiv.org/abs/2406.11695), [BetterTogether](https://arxiv.org/abs/2407.10930), and [LeReT](https://arxiv.org/abs/2410.23214), on program architectures, like [STORM](https://arxiv.org/abs/2402.14207), [IReRa](https://arxiv.org/abs/2401.12178), and [DSPy Assertions](https://arxiv.org/abs/2312.13382), and on successful applications to new problems, like [PAPILLON](https://arxiv.org/abs/2410.17127), [PATH](https://arxiv.org/abs/2406.11706), [WangLab@MEDIQA](https://arxiv.org/abs/2404.14544), [UMD's Prompting Case Study](https://arxiv.org/abs/2406.06608), and [Haize's Red-Teaming Program](https://blog.haizelabs.com/posts/dspy/), in addition to many open-source projects, [production applications](community/use-cases.md), and other [community work](community/built-with-dspy.md).diff --git a/docs/docs/js/copy-as-markdown.js b/docs/docs/js/copy-as-markdown.jsdeleted file mode 100644index a9c69a544..000000000--- a/docs/docs/js/copy-as-markdown.js+++ /dev/null@@ -1,161 +0,0 @@-/**- * "Copy page" button for MkDocs Material pages.- *- * Adds a clipboard button next to the existing "Edit this page" action.- * Clicking the button fetches the raw Markdown source (or Jupyter notebook)- * from GitHub and copies it to the user's clipboard as Markdown.- */-document.addEventListener("DOMContentLoaded", function () {- // The raw-content base URL derived from the repo + edit_uri in mkdocs.yml.- // edit links look like: .../blob/main/docs/docs/<path>.md- // raw links look like: .../raw/main/docs/docs/<path>.md- var REPO_RAW_BASE =- "https://raw.githubusercontent.com/stanfordnlp/dspy/main/docs/docs/";-- // Clipboard icon (Material Design "content_copy")- var ICON =- '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">' +- '<path d="M16 1H4c-1.1 0-2 .9-2 2v14h2V3h12V1zm3 4H8c-1.1 0-2 .9-2 2v14' +- "c0 1.1.9 2 2 2h11c1.1 0 2-.9 2-2V7c0-1.1-.9-2-2-2zm0 16H8V7h11v14z" +- '"/></svg>';-- /**- * Convert raw Jupyter Notebook JSON into readable Markdown.- * Markdown cells are kept as-is; code cells are wrapped in fenced blocks.- */- function notebookToMarkdown(json) {- var nb = JSON.parse(json);- var cells = nb.cells || [];- var parts = [];- for (var i = 0; i < cells.length; i++) {- var cell = cells[i];- var source = (cell.source || []).join("");- if (cell.cell_type === "markdown") {- parts.push(source);- } else if (cell.cell_type === "code") {- parts.push("```python\n" + source + "\n```");- }- }- return parts.join("\n\n");- }-- function getMarkdownPath() {- // Try to derive the .md path from the existing "Edit this page" link- var editLink = document.querySelector('a[title="Edit this page"]');- if (editLink) {- var href = editLink.getAttribute("href") || "";- // href example: https://github.com/stanfordnlp/dspy/blob/main/docs/docs/api/modules/RLM.md- var marker = "docs/docs/";- var idx = href.indexOf(marker);- if (idx !== -1) {- return href.substring(idx + marker.length);- }- }-- // Fallback: build the path from the current URL- var path = window.location.pathname.replace(/\/$/, "");- if (path === "" || path === "/") {- return "index.md";- }- // /api/modules/RLM/ -> api/modules/RLM.md (directory style)- // /faqs/ -> faqs.md- // Try stripping leading slash- path = path.replace(/^\//, "");-- // If it already ends with .md, keep it- if (path.endsWith(".md")) {- return path;- }-- // MkDocs can serve /foo/ from either foo.md or foo/index.md.- // We try foo.md first, then foo/index.md as a fallback inside copyMarkdown().- return path + ".md";- }-- function createButton() {- // Find the article actions area (where Edit lives)- var actionsContainer = document.querySelector(".md-content__button");- if (!actionsContainer) return;-- var wrapper = actionsContainer.parentElement;- if (!wrapper) return;-- var btn = document.createElement("a");- btn.className = "md-content__button md-icon copy-md-btn";- btn.title = "Copy page as Markdown";- btn.href = "#";- btn.setAttribute("aria-label", "Copy page as Markdown");- btn.innerHTML = ICON + " Copy page";-- btn.addEventListener("click", function (e) {- e.preventDefault();- copyMarkdown(btn);- });-- // Insert before the first existing action button- wrapper.insertBefore(btn, actionsContainer);- }-- function copyMarkdown(btn) {- var mdPath = getMarkdownPath();- var url = REPO_RAW_BASE + mdPath;-- btn.classList.add("copy-md-btn--loading");-- fetch(url)- .then(function (res) {- if (!res.ok) {- // Retry with /index.{md,ipynb} suffix (MkDocs directory pages)- var isNotebook = mdPath.endsWith(".ipynb");- var altPath = isNotebook- ? mdPath.replace(/\.ipynb$/, "/index.ipynb")- : mdPath.replace(/\.md$/, "/index.md");- return fetch(REPO_RAW_BASE + altPath).then(function (res2) {- if (!res2.ok) {- throw new Error("Could not fetch markdown source");- }- // Update mdPath so the notebook check below uses the correct extension- mdPath = altPath;- return res2.text();- });- }- return res.text();- })- .then(function (text) {- // Convert Jupyter notebooks to readable Markdown- if (mdPath.endsWith(".ipynb")) {- text = notebookToMarkdown(text);- }- return navigator.clipboard.writeText(text);- })- .then(function () {- showFeedback(btn, true);- })- .catch(function () {- showFeedback(btn, false);- });- }-- function showFeedback(btn, success) {- btn.classList.remove("copy-md-btn--loading");- btn.classList.add(success ? "copy-md-btn--success" : "copy-md-btn--error");- btn.innerHTML = ICON + (success ? " Copied!" : " Failed to copy");-- setTimeout(function () {- btn.classList.remove("copy-md-btn--success", "copy-md-btn--error");- btn.innerHTML = ICON + " Copy page";- }, 2000);- }-- // MkDocs Material uses instant loading — re-run on every page navigation- if (typeof document$ !== "undefined") {- document$.subscribe(function () {- // Remove any previously injected button (instant navigation re-renders)- var existing = document.querySelector(".copy-md-btn");- if (existing) existing.remove();- createButton();- });- } else {- createButton();- }-});diff --git a/docs/docs/js/hero-interactive.js b/docs/docs/js/hero-interactive.jsnew file mode 100644index 000000000..b47fa160f--- /dev/null+++ b/docs/docs/js/hero-interactive.js@@ -0,0 +1,300 @@+(function () {+ "use strict";++ var state = { lm: 0, field: 0, agent: false };++ function k(t) { return '<span class="tok-k">' + t + "</span>"; }+ function s(t) { return '<span class="tok-s">' + t + "</span>"; }+ function m(t) { return '<span class="tok-m">' + t + "</span>"; }+ function tp(t) { return '<span class="tok-t">' + t + "</span>"; }+ function cm(t) { return '<span class="tok-cm">' + t + "</span>"; }+ function num(t) { return '<span class="tok-num">' + t + "</span>"; }++ var lmConfigs = [+ { line: "lm = dspy." + m("LM") + "(" + s('"openai/gpt-5.4-nano"') + ")" },+ { line: "lm = dspy." + m("LM") + "(" + s('"anthropic/claude-sonnet-4-20250514"') + ")" },+ { line: "lm = dspy." + m("LM") + "(" + s('"openrouter/deepseek/deepseek-r1"') + ")" },+ { line: "lm = dspy." + m("LM") + "(" + s('"ollama_chat/llama3.2"') + ", api_base=" + s('"http://localhost:11434"') + ")" },+ ];++ var fieldConfigs = [+ {+ name: "location",+ code: " location: " + tp("str") + " = dspy." + m("OutputField") + "()",+ output: " location=" + s('"Building 4, Room 201"'),+ isInput: false,+ },+ {+ name: "rsvp_required",+ code: " rsvp_required: " + tp("bool") + " = dspy." + m("OutputField") + "()",+ output: " rsvp_required=" + num("True"),+ isInput: false,+ },+ {+ name: "attendees",+ code: " attendees: " + tp("list") + "[" + tp("str") + "] = dspy." + m("OutputField") + "()",+ output: " attendees=[" + s('"Alice"') + ", " + s('"Bob"') + ", " + s('"Carol"') + "]",+ isInput: false,+ },+ {+ name: "urgency",+ code: " urgency: " + tp("Literal") + "[" + s('"low"') + ", " + s('"medium"') + ", " + s('"high"') + "] = dspy." + m("OutputField") + "()",+ output: " urgency=" + s('"medium"'),+ isInput: false,+ },+ {+ name: "duration_minutes",+ code: " duration_minutes: " + tp("int") + " = dspy." + m("OutputField") + "()",+ output: " duration_minutes=" + num("60"),+ isInput: false,+ },+ {+ name: "is_virtual",+ code: " is_virtual: " + tp("bool") + " = dspy." + m("OutputField") + "()",+ output: " is_virtual=" + num("False"),+ isInput: false,+ },+ {+ name: "calendar",+ code: " calendar: " + tp("Literal") + "[" + s('"work"') + ", " + s('"personal"') + "] = dspy." + m("OutputField") + "()",+ output: " calendar=" + s('"work"'),+ isInput: false,+ },+ {+ name: "subject",+ code: " subject: " + tp("str") + " = dspy." + m("InputField") + "()",+ output: null,+ isInput: true,+ },+ ];++ var toolLines = [+ k("def") + " " + m("check_calendar") + "(date: " + tp("str") + ") -> " + tp("bool") + ":",+ " " + s('"""Check for scheduling conflicts."""'),+ " " + k("return") + " calendar.has_conflict(date)",+ ];++ var classLines = [+ k("class") + " " + tp("ExtractEvent") + "(dspy.Signature):",+ " " + s('"""Extract event details from an email."""'),+ " email: " + tp("str") + " = dspy." + m("InputField") + "()",+ " event_name: " + tp("str") + " = dspy." + m("OutputField") + "()",+ " date: " + tp("str") + " = dspy." + m("OutputField") + "()",+ ];++ function buildCodeLines() {+ var lines = [];++ lines.push(lmConfigs[state.lm].line);+ lines.push(" ");++ for (var i = 0; i < classLines.length; i++) {+ lines.push(classLines[i]);+ }++ if (state.field > 0) {+ lines.push(fieldConfigs[state.field - 1].code);+ }++ lines.push(" ");++ if (state.agent) {+ for (var j = 0; j < toolLines.length; j++) {+ lines.push(toolLines[j]);+ }+ lines.push(" ");+ lines.push("extract = dspy." + m("ReAct") + "(ExtractEvent, tools=[check_calendar])");+ } else {+ lines.push("extract = dspy." + m("Predict") + "(ExtractEvent)");+ }++ if (state.field === 8) {+ lines.push("extract(email=inbox_message, subject=" + s('"Team Offsite"') + ")");+ } else {+ lines.push("extract(email=inbox_message)");+ }++ return lines;+ }++ function buildOutputLines() {+ var lines = [];+ var fc = state.field > 0 ? fieldConfigs[state.field - 1] : null;+ var hasExtraOutput = fc && !fc.isInput;++ lines.push("Prediction(");+ lines.push(" event_name=" + s('"Team Offsite"') + ",");++ if (hasExtraOutput || state.agent) {+ lines.push(" date=" + s('"Thursday, June 5"') + ",");+ } else {+ lines.push(" date=" + s('"Thursday, June 5"'));+ }++ if (hasExtraOutput && state.agent) {+ lines.push(fc.output + ",");+ lines.push(" has_conflict=" + num("False"));+ } else if (hasExtraOutput) {+ lines.push(fc.output);+ } else if (state.agent) {+ lines.push(" has_conflict=" + num("False"));+ }++ lines.push(")");+ return lines;+ }++ function linesToHTML(lines) {+ var html = "";+ for (var i = 0; i < lines.length; i++) {+ html += '<div class="line">' + lines[i] + "</div>";+ }+ return html;+ }++ function updateLineNumbers(count) {+ var el = document.getElementById("hp-hero-linenums");+ if (!el) return;+ var html = "";+ for (var i = 1; i <= count; i++) {+ html += "<span>" + i + "</span>";+ }+ el.innerHTML = html;+ }++ function diffAndHighlight(container, newHTML, skipHeader) {+ var oldLines = container.querySelectorAll(".line");+ var oldContents = [];+ for (var i = 0; i < oldLines.length; i++) {+ oldContents.push(oldLines[i].innerHTML);+ }++ if (skipHeader) {+ var header = container.querySelector(".hp-code-output-header");+ container.innerHTML = (header ? header.outerHTML : "") + newHTML;+ } else {+ container.innerHTML = newHTML;+ }++ var newLines = container.querySelectorAll(".line");+ for (var j = 0; j < newLines.length; j++) {+ var txt = newLines[j].textContent.trim();+ if (txt && (j >= oldContents.length || newLines[j].innerHTML !== oldContents[j])) {+ newLines[j].classList.add("hp-line-flash");+ }+ }+ }++ function silentRender() {+ var codeEl = document.getElementById("hp-hero-code");+ var outputEl = document.getElementById("hp-hero-output");+ if (!codeEl || !outputEl) return;++ var codeLines = buildCodeLines();+ var outputLines = buildOutputLines();++ codeEl.innerHTML = linesToHTML(codeLines);+ var header = outputEl.querySelector(".hp-code-output-header");+ outputEl.innerHTML = (header ? header.outerHTML : "") + linesToHTML(outputLines);+ updateLineNumbers(codeLines.length);+ updateButtons();+ }++ function render() {+ var codeEl = document.getElementById("hp-hero-code");+ var outputEl = document.getElementById("hp-hero-output");+ if (!codeEl || !outputEl) return;++ var codeLines = buildCodeLines();+ var outputLines = buildOutputLines();++ diffAndHighlight(codeEl, linesToHTML(codeLines), false);+ diffAndHighlight(outputEl, linesToHTML(outputLines), true);+ updateLineNumbers(codeLines.length);+ updateButtons();+ }++ function updateButtons() {+ var lmBtn = document.getElementById("hp-btn-lm");+ var fieldBtn = document.getElementById("hp-btn-field");+ var agentBtn = document.getElementById("hp-btn-agent");+ if (!lmBtn || !fieldBtn || !agentBtn) return;++ lmBtn.classList.remove("active");++ if (state.field === 0) {+ fieldBtn.textContent = "Add a Field";+ fieldBtn.classList.remove("active");+ } else {+ fieldBtn.textContent = "Swap a Field";+ fieldBtn.classList.add("active");+ }++ if (state.agent) {+ agentBtn.classList.add("active");+ } else {+ agentBtn.classList.remove("active");+ }+ }++ function track(eventName, params) {+ if (typeof window.gtag === "function") {+ window.gtag("event", eventName, params || {});+ }+ }++ function init() {+ var lmBtn = document.getElementById("hp-btn-lm");+ var fieldBtn = document.getElementById("hp-btn-field");+ var agentBtn = document.getElementById("hp-btn-agent");+ if (lmBtn && fieldBtn && agentBtn) {+ lmBtn.addEventListener("click", function () {+ state.lm = (state.lm + 1) % lmConfigs.length;+ render();+ track("hero_code_button_click", {+ button: "change_llm",+ lm_index: state.lm,+ lm_provider: ["openai", "anthropic", "openrouter", "ollama"][state.lm],+ });+ });++ fieldBtn.addEventListener("click", function () {+ state.field = (state.field + 1) % (fieldConfigs.length + 1);+ render();+ var fieldName = state.field === 0 ? "removed" : fieldConfigs[state.field - 1].name;+ track("hero_code_button_click", {+ button: "add_field",+ field_index: state.field,+ field_name: fieldName,+ });+ });++ agentBtn.addEventListener("click", function () {+ state.agent = !state.agent;+ render();+ track("hero_code_button_click", {+ button: "make_agent",+ agent_enabled: state.agent,+ });+ });++ silentRender();+ }++ var tabIds = ["extract", "agent", "pipeline", "multimodal", "optimize"];+ tabIds.forEach(function (id) {+ var label = document.querySelector('label[for="hp-tab-' + id + '"]');+ if (label) {+ label.addEventListener("click", function () {+ track("example_tab_click", { tab: id });+ });+ }+ });+ }++ if (document.readyState === "loading") {+ document.addEventListener("DOMContentLoaded", init);+ } else {+ init();+ }+})();diff --git a/docs/docs/static/dspy-logo.svg b/docs/docs/static/dspy-logo.svgnew file mode 100644index 000000000..4e12cdb21--- /dev/null+++ b/docs/docs/static/dspy-logo.svg@@ -0,0 +1,14 @@+<?xml version="1.0" encoding="UTF-8"?>+<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="0 0 2000 2000">+ <defs>+ <style>+ .cls-1 {+ fill: #ef4036;+ stroke-width: 0px;+ }+ </style>+ </defs>+ <path class="cls-1" d="M1299.28,1931.08c-39.73,0-72.08-.26-92.58-.89-111.94-3.44-301.46-3.48-430.82-1.73-93.78,1.27-372.9-8.16-539.67-13.79-58.1-1.96-108.27-3.66-115.39-3.66h-3.37c-24.43-.07-81.38.23-88.45-77.46-2.03-22.26-.76-174.48,1.66-441.59,1.59-175.9,3.39-375.28,3.39-503.13,0-281.59,3.45-639.26,5.25-718.29.59-25.78,4.29-54.76,27.29-74.24,18.65-15.78,39.93-17.21,60.51-18.58,8.88-.59,18.07-1.21,28.67-2.86,42.43-6.63,252.04-6.08,521.67-4.68,64.65.34,125.72.65,169.38.65s117.12-.32,201.88-.69c277.02-1.2,656.41-2.85,733.19,2.54,14.63,1.03,28,1.69,40.93,2.34,39.47,1.97,70.65,3.53,95.78,14.21,24.89,10.57,54.35,34.79,53.36,90.11-1.19,66.55-.74,285.75-.35,479.13.18,89.51.35,174.21.35,237.34,0,144.1-5.27,545.49-8.43,785.31-1.18,90.26-2.04,155.47-2.04,164.07,0,15.2,0,46.83-27.06,66.06-18.53,13.17-40.9,14.22-68.22,14.22-11.35,0-52.65.54-109.8,1.28-131.97,1.72-331.48,4.32-457.15,4.32ZM956.92,1837.56c92.32,0,185.93.86,252.55,2.91,83.36,2.56,384.18-1.36,545.79-3.47,57.5-.75,99.04-1.29,110.97-1.29,2.03,0,3.89-.01,5.59-.03.23-22.28.96-78.14,1.98-155.75,2.94-223.89,8.42-640.62,8.42-784.13,0-63.08-.17-147.72-.35-237.15-.39-193.81-.84-413.47.36-480.92.05-3-.09-5.14-.27-6.58-10.64-3.84-39.79-5.29-63.61-6.48-12.74-.64-27.19-1.36-42.73-2.45-73.45-5.16-466.46-3.46-726.52-2.32-84.86.37-158.16.69-202.27.69s-105.08-.32-169.85-.65c-186.63-.97-468.65-2.44-507.35,3.61-14.52,2.27-26.74,3.09-36.55,3.74-1.24.08-2.54.17-3.85.26-.08,1.48-.14,3.15-.19,5.03h0c-1.79,78.69-5.23,435.26-5.23,716.26,0,128.25-1.8,327.85-3.4,503.94-1.74,192.87-3.54,391.99-2.24,428.49h2.63c8.27,0,44.27,1.2,118.42,3.7,155.09,5.24,443.79,15.04,535.43,13.75,53.67-.73,117.65-1.14,182.25-1.14Z"/>+ <path class="cls-1" d="M517.89,1258.35c-50.83,0-87.48-6.92-115.52-21.41-41.35-21.37-63.76-58.32-68.51-112.97-3.19-36.7,1.5-69.02,8.21-94.5-23.05-2.86-50.13-5.71-74.68-7-58.1-3.07-185.75,1.59-187.02,1.63l-3.31-89.7c5.4-.2,132.95-4.83,195.05-1.57,62.55,3.3,136.42,15.29,139.53,15.8,14.82,2.42,27.62,11.79,33.82,25.46,6.2,13.67,5.33,29.24-2.61,41.98-.07.13-24.53,43.03-19.56,100.12,2.8,32.21,5.22,60.06,139.39,50.67,36.4-2.54,46.8-16.29,50.22-20.81,22.58-29.87,9.4-92.73,3.78-119.57l-.93-4.45c-6.18-29.84-1.12-53.65,15.03-70.74,25.11-26.58,61.25-21.22,87.62-17.32l5.8.85c7.44,1.06,25.36,3.89,52.49,8.17,95.11,14.99,293.02,46.19,365.85,52.36,47.23,4,95.22,3.81,130.18,2.71-1.55-8.08-3-16.67-4.21-25.54-9.25-67.81.03-115.06,28.36-144.44,57.27-59.39,209.64-85.12,299.27-29.36,66.39,41.31,58,126.93,41.2,187.74,115.64-6.78,282.55-26.08,284.59-26.32l10.36,89.16c-10.28,1.2-252.87,29.25-359.86,29.25-15.39,0-29.7-7.88-37.93-20.88-8.23-13-9.22-29.31-2.63-43.22,22.76-48.43,40.21-124.98,16.85-139.52-23.96-14.91-62.58-20.87-103.34-15.95-41.68,5.03-72.71,19.81-83.89,31.4-3.27,3.39-10.38,22.37-4.19,68.92,4.72,35.44,14.57,66.91,14.67,67.22,4.1,13.01,2.08,27.21-5.53,38.54-7.6,11.33-19.94,18.61-33.53,19.74-4.07.34-100.89,8.23-197.96,0-76.04-6.44-276.1-37.98-372.25-53.13-25.78-4.06-44.41-7-51.2-7.97l-3.9-.57c3.5,18.01,7.33,41.82,7.75,67.06.74,44.94-9.63,81.95-30.84,110-25.51,33.74-64.39,52.67-115.58,56.24-18.46,1.29-35.42,1.94-51.04,1.94ZM702.94,998.81h0s0,0,0,0Z"/>+ <path class="cls-1" d="M1017.82,1886.52l-89.77-.66c.02-2.24,1.62-224.98.03-267.92-.52-13.88-2.08-56.12,30.81-78.69,31.88-21.89,72.39-9.08,104.11,4.51,33.61,14.41,67.96,17.25,87.52,7.25,7.54-3.85,18.19-11.85,23.77-36.69,13.4-59.78,1.93-115.99-16.32-140.62-8.49-11.46-15.11-11.95-17.28-12.12-45.46-3.4-110.65,16.98-131.95,25.12-20.8,7.96-44.34-.53-55.22-19.96-5.2-9.26-30.83-62.27-25.55-196.47,3.39-86.35,26.74-233.2,43.78-340.42,6.93-43.57,14.07-88.51,15.38-102.99-43.08,6.66-101.53,2.29-144.98-30.15-25.61-19.12-56.89-56.24-60.48-124.51-3.52-66.9,10.46-120.09,41.55-158.09,32.97-40.3,74.7-50.73,96.64-53.37,25.75-3.1,50.66-.23,70.55,2.73,4.69-52.06,7.87-157.65,8.38-248.69l89.77.5c0,.74-.44,74.87-2.91,148.45-1.46,43.66-3.36,78.77-5.62,104.34-3.49,39.4-7.1,80.14-45.76,87.83-14.72,2.92-30.18.52-48.1-2.27-17.73-2.76-37.82-5.9-55.61-3.76-41.32,4.96-62.92,47.83-59.24,117.61,1.43,27.29,9.46,46.04,24.55,57.29,24.08,17.98,64.82,16.82,86.34,11.66,12.49-2.99,45.67-10.96,71.54,10.37,25.87,21.32,24.48,53.19,23.26,81.3-.65,15.03-6.14,50.06-16.6,115.84-15.75,99.08-39.55,248.82-42.74,329.86-2.09,53.22,1.32,90.16,5.4,114.1,34.14-9.39,81.56-19.02,124.33-15.83,32.55,2.44,61.14,19.1,82.69,48.19,37.17,50.16,49.65,134.04,31.79,213.7-12.75,56.88-45.37,84.13-70.49,96.98-64.67,33.07-141.69,4.79-163.75-4.67-3.61-1.55-6.82-2.83-9.64-3.9,1.3,57.89-.13,255.35-.19,264.15Z"/>+</svg>\ No newline at end of filediff --git a/docs/docs/stylesheets/extra.css b/docs/docs/stylesheets/extra.cssindex 2287d4fa3..0b833949c 100644--- a/docs/docs/stylesheets/extra.css+++ b/docs/docs/stylesheets/extra.css@@ -10,9 +10,28 @@object-fit: contain !important;}-/* Adjust header to accommodate logo */+/* Header: comfortable vertical breathing room with horizontal padding+ matching Material's default content gutter. */.md-header__inner {- padding: 0.5rem !important;+ padding: 0.65rem 1rem !important;+}++/* Subtle bottom divider so the header doesn't bleed into the content area. */+.md-header {+ border-bottom: 1px solid var(--md-default-fg-color--lightest);+ box-shadow: none;+}++/* Tighten the gap between the logo glyph and the "DSPy" wordmark.+ The SVG canvas is square (2000×2000) with internal whitespace, so without+ this the title sits noticeably far from the icon. */+.md-header__title {+ margin-left: 0.25rem;+}++/* Breathing room between the tabs row and the first content element. */+.md-main__inner {+ margin-top: 2rem;}/* Responsive adjustments */@@ -46,12 +65,13 @@}-/* Justified text for main content */+/* Main content: left-align (ragged right) for screen readability.+ Justified text causes uneven word spacing without proper hyphenation. */.md-content__inner p {- text-align: justify;+ text-align: left;}-/* Left-aligned text for grid cards */+/* Grid cards already left-aligned (kept for clarity) */.md-content__inner .grid.cards p {text-align: left;}@@ -218,12 +238,13 @@ h2.doc-heading {/* Ensure code is readable */.highlight code {- font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;- font-size: 0.75em;+ font-family: "Fira Mono", "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;+ font-size: 0.82em;+ line-height: 1.55;}.highlight .linenos {- font-size: 0.75em;+ font-size: 0.82em;}/* Copy button styling */@@ -384,26 +405,117 @@ h2.doc-heading {display: inline-block;}-/* Copy-page button – matches the native "Edit this page" action style */-.copy-md-btn {- cursor: pointer;-}--.copy-md-btn svg {- fill: currentColor;- vertical-align: text-bottom;-}--.copy-md-btn--loading {- opacity: 0.5;- pointer-events: none;+/* =========================================================================+ Readability tuning (applies site-wide)+ - Cap prose at ~70 characters per line (Bringhurst: 45–75 ideal)+ - Slight line-height bump for body text+ - Breathing room before the prev/next footer+ - Wrap plain (non-language) code blocks so long output lines don't scroll+ - Higher-contrast Pygments tokens for Python in light mode+ - Darker body text and heavier headings for stronger hierarchy+ ========================================================================= */++/* Stronger body text contrast (light mode).+ Material's default is hsla(0, 0%, 0%, 0.87) which renders softer than a+ solid near-black. */+[data-md-color-scheme="default"] {+ --md-default-fg-color: #1f2328;+ --md-default-fg-color--light: #424950;+ --md-default-fg-color--lighter:#6e7681;+ --md-typeset-color: #1f2328;+}++/* Heavier, more solid headings. Plex Sans at 600 has presence without+ shouting; 700 for h1 sets a clear top of hierarchy. */+.md-typeset h1 { font-weight: 700; letter-spacing: -0.01em; }+.md-typeset h2 { font-weight: 600; letter-spacing: -0.005em; }+.md-typeset h3 { font-weight: 600; }+.md-typeset h4,+.md-typeset h5,+.md-typeset h6 { font-weight: 600; }++/* Cap prose line-length for comfortable reading. Code blocks, tables, and+ admonitions keep the full content width. */+.md-content__inner > p,+.md-content__inner > ul,+.md-content__inner > ol,+.md-content__inner > blockquote,+.md-content__inner > h1,+.md-content__inner > h2,+.md-content__inner > h3,+.md-content__inner > h4,+.md-content__inner > h5,+.md-content__inner > h6 {+ max-width: 44rem;+}++/* Body text typography (Butterick: line-height 120–145%, body 15–25px).+ 1.5 sits just above the upper bound for screen comfort; 17px sits a tick+ above Material's 16px default. */+.md-typeset {+ font-size: 17px;+ font-kerning: normal;+ text-rendering: optimizeLegibility;+ font-feature-settings: "kern", "liga";+ letter-spacing: -0.005em;+}++.md-typeset p,+.md-typeset li {+ line-height: 1.5;}-.copy-md-btn--success {- color: #4caf50 !important;+/* Paragraph spacing ~12pt at 17px body — inside Butterick's "4–10pt + indent+ OR 4–10pt space, not both" guidance (we use space, no indent). */+.md-typeset p {+ margin-bottom: 0.7em;}-.copy-md-btn--error {- color: #f44336 !important;-}+/* Breathing room between the last paragraph and the dark prev/next footer */+.md-content {+ padding-bottom: 3.5rem;+}++/* Wrap plain text / output blocks (no language tag).+ Python and other language-tagged blocks keep horizontal scroll. */+.md-typeset pre > code:not([class*="language-"]),+.md-typeset pre > code.language-text {+ white-space: pre-wrap;+ overflow-wrap: anywhere;+ word-break: break-word;+}++/* ----- Higher-contrast Python syntax (light mode) -----+ Inspired by GitHub Primer; all colors pass WCAG AA on white. */+[data-md-color-scheme="default"] .highlight .k,+[data-md-color-scheme="default"] .highlight .kn,+[data-md-color-scheme="default"] .highlight .kd,+[data-md-color-scheme="default"] .highlight .kr { color: #cf222e; } /* keyword */+[data-md-color-scheme="default"] .highlight .kc { color: #0550ae; font-weight: 600; } /* True / False / None */+[data-md-color-scheme="default"] .highlight .nb { color: #6639ba; } /* builtin (print, len) */+[data-md-color-scheme="default"] .highlight .nf,+[data-md-color-scheme="default"] .highlight .fm { color: #8250df; } /* function name */+[data-md-color-scheme="default"] .highlight .nc { color: #953800; } /* class name */+[data-md-color-scheme="default"] .highlight .nd { color: #8250df; } /* decorator */+[data-md-color-scheme="default"] .highlight .s,+[data-md-color-scheme="default"] .highlight .s1,+[data-md-color-scheme="default"] .highlight .s2,+[data-md-color-scheme="default"] .highlight .sb,+[data-md-color-scheme="default"] .highlight .sa { color: #0a3069; } /* strings */+[data-md-color-scheme="default"] .highlight .sd { color: #57606a; font-style: italic; } /* docstring */+[data-md-color-scheme="default"] .highlight .se { color: #cf222e; } /* string escape */+[data-md-color-scheme="default"] .highlight .si { color: #0a3069; font-weight: 600; } /* string interp */+[data-md-color-scheme="default"] .highlight .mi,+[data-md-color-scheme="default"] .highlight .mf,+[data-md-color-scheme="default"] .highlight .mh,+[data-md-color-scheme="default"] .highlight .mo { color: #0550ae; } /* numbers */+[data-md-color-scheme="default"] .highlight .c,+[data-md-color-scheme="default"] .highlight .c1,+[data-md-color-scheme="default"] .highlight .cm,+[data-md-color-scheme="default"] .highlight .ch { color: #57606a; font-style: italic; } /* comments */+[data-md-color-scheme="default"] .highlight .o,+[data-md-color-scheme="default"] .highlight .ow { color: #24292f; } /* operators */+[data-md-color-scheme="default"] .highlight .p { color: #24292f; } /* punctuation */+[data-md-color-scheme="default"] .highlight .bp { color: #6639ba; } /* self */+[data-md-color-scheme="default"] .highlight .n { color: #1f2328; } /* default identifier */diff --git a/docs/docs/stylesheets/home.css b/docs/docs/stylesheets/home.cssnew file mode 100644index 000000000..8639a9388--- /dev/null+++ b/docs/docs/stylesheets/home.css@@ -0,0 +1,827 @@+/* ============================================================================+ DSPy Landing Page+ Loaded only on the home page via template override.+ All classes prefixed hp- (home page) to avoid Material conflicts.+ ============================================================================ */++/* --- Variables --- */+.dspy-home {+ --hp-accent: #c24d2c;+ --hp-accent-bg: rgba(194, 77, 44, 0.08);+ --hp-line: var(--md-default-fg-color--lightest);+ --hp-fg: var(--md-default-fg-color);+ --hp-fg-2: var(--md-default-fg-color--light);+ --hp-fg-3: var(--md-default-fg-color--lighter);+ --hp-bg: var(--md-default-bg-color);+ --hp-bg-2: var(--md-code-bg-color);+ --hp-ok: #1a7f37;+ --hp-warn: #9a6700;+ --hp-mono: 'Fira Mono', ui-monospace, monospace;+}+[data-md-color-scheme="slate"] .dspy-home {+ --hp-accent: #e8805a;+ --hp-accent-bg: rgba(232, 128, 90, 0.12);+ --hp-ok: #7ee787;+ --hp-warn: #d29922;+}++/* --- Container Reset --- */+.md-main:has(.dspy-home) .md-main__inner {+ margin-top: 0 !important;+ max-width: none !important;+ padding: 0 !important;+}+.md-main:has(.dspy-home) .md-content {+ max-width: none !important;+ padding: 0 !important;+}+.md-main:has(.dspy-home) .md-content__inner {+ max-width: none !important;+ margin: 0 !important;+ padding: 0 !important;+}++/* --- Base --- */+.hp-container {+ max-width: 1280px;+ margin: 0 auto;+ padding-left: 40px;+ padding-right: 40px;+}+.hp-mono { font-family: var(--hp-mono); }+.hp-hl { color: var(--hp-accent); }+.hp-section { border-bottom: 1px solid var(--hp-line); }++/* --- Section Labels --- */+.hp-section-label {+ font-family: var(--hp-mono);+ display: flex;+ align-items: center;+ gap: 12px;+ font-size: 11px;+ letter-spacing: 1.4px;+ text-transform: uppercase;+ color: var(--hp-fg-3);+}+.hp-section-label .hp-num { color: var(--hp-accent); }+.hp-section-label .hp-rule { width: 22px; height: 1px; background: var(--hp-fg-3); display: inline-block; }+.hp-section-title {+ font-weight: 700;+ font-size: clamp(28px, 3.4vw, 40px);+ letter-spacing: -0.5px;+ line-height: 1.15;+ margin: 0 !important;+ max-width: 820px;+ color: var(--hp-fg);+}++/* ===== HERO ===== */+.hp-hero { padding: 32px 0 64px; }+.hp-hero-grid {+ display: grid;+ grid-template-columns: 1.05fr 1fr;+ gap: 56px;+ align-items: start;+}+.hp-hero-badge {+ font-family: var(--hp-mono);+ font-size: 11px;+ letter-spacing: 1.4px;+ text-transform: uppercase;+ color: var(--hp-fg-3);+ display: flex;+ align-items: center;+ gap: 10px;+ margin-bottom: 36px;+}+.hp-hero-badge .hp-dot {+ width: 6px; height: 6px;+ background: var(--hp-accent);+ border-radius: 50%;+ display: inline-block;+ flex-shrink: 0;+}+.dspy-home .hp-hero-badge a,+.md-typeset .hp-hero-badge a {+ color: var(--hp-fg-2) !important;+ text-decoration: none !important;+ border-bottom: 1px solid var(--hp-line);+}+.hp-hero-title {+ font-weight: 700;+ font-size: clamp(36px, 4.6vw, 60px);+ line-height: 1.08;+ letter-spacing: -1px;+ margin: 0 0 28px;+ text-wrap: balance;+ color: var(--hp-fg);+}+.hp-hero-sub {+ font-size: 19px;+ line-height: 1.4;+ color: var(--hp-fg-2);+ max-width: 540px;+ margin: 0 0 48px;+}+.hp-hero-actions {+ display: flex;+ gap: 12px;+ flex-wrap: wrap;+ margin-bottom: 36px;+}+.dspy-home .hp-btn-primary,+.md-typeset .hp-btn-primary {+ font-family: var(--hp-mono) !important;+ background: var(--hp-accent) !important;+ color: #fff !important;+ padding: 14px 24px !important;+ text-decoration: none !important;+ font-weight: 600;+ font-size: 14px;+ letter-spacing: 0.3px;+ display: inline-flex;+ align-items: center;+ gap: 10px;+ transition: opacity 0.15s;+ border: none;+}+.dspy-home .hp-btn-primary:hover,+.md-typeset .hp-btn-primary:hover { opacity: 0.85; color: #fff !important; }+.hp-btn-primary .hp-dollar { opacity: 0.5; }+.dspy-home .hp-btn-outline,+.md-typeset .hp-btn-outline {+ font-family: var(--hp-mono) !important;+ background: var(--hp-bg) !important;+ color: var(--hp-fg) !important;+ padding: 14px 24px !important;+ text-decoration: none !important;+ font-weight: 600;+ font-size: 14px;+ letter-spacing: 0.3px;+ border: 2px solid var(--hp-fg) !important;+ transition: background 0.15s;+}+.dspy-home .hp-btn-outline:hover,+.md-typeset .hp-btn-outline:hover {+ background: var(--hp-fg) !important;+ color: var(--hp-bg) !important;+}+.hp-hero-meta {+ font-family: var(--hp-mono);+ font-size: 12px;+ color: var(--hp-fg-3);+ display: flex;+ gap: 28px;+ flex-wrap: wrap;+ padding-top: 24px;+ border-top: 1px solid var(--hp-line);+}+.hp-hero-meta strong { color: var(--hp-fg); font-weight: 600; }+.dspy-home .hp-hero-meta a,+.md-typeset .hp-hero-meta a {+ color: var(--hp-fg-2) !important;+ text-decoration: none !important;+ border-bottom: 1px dotted var(--hp-fg-3);+}++/* ===== CODE WINDOW ===== */+.hp-code-window {+ background: #1a1f2b;+ border-radius: 8px;+ overflow: hidden;+ box-shadow: 0 4px 24px rgba(0, 0, 0, 0.2);+}+.hp-code-chrome {+ display: flex;+ align-items: center;+ background: #212734;+ border-bottom: 1px solid #2d3545;+}+.hp-dots {+ display: none;+}+.hp-dots span {+ display: none;+}+.hp-code-title {+ font-family: var(--hp-mono);+ padding: 0;+ font-size: 12px;+ color: #8b949e;+ flex: 1;+}+.hp-code-title strong {+ display: inline-block;+ padding: 10px 16px;+ color: #e6edf3;+ font-weight: 500;+ background: #1a1f2b;+ border-top: 2px solid var(--hp-accent);+ border-right: 1px solid #2d3545;+}+.hp-code-body {+ display: grid;+ grid-template-columns: 40px 1fr;+}+.hp-line-nums {+ padding: 18px 0;+ border-right: 1px solid #2d3545;+ color: #505a6e;+ text-align: right;+ user-select: none;+ font-family: var(--hp-mono);+ font-size: 12px;+ opacity: 1;+}+.hp-line-nums span { display: block; padding: 0 8px; line-height: 1.7; }+.hp-code-content {+ padding: 18px 20px;+ font-family: var(--hp-mono);+ font-size: 13px;+ line-height: 1.7;+ overflow: hidden;+ color: #e6edf3;+}+.hp-code-content .line {+ white-space: pre;+ min-height: 1em;+}+.hp-code-caption {+ border-top: 1px solid #21262d;+ padding: 12px 16px;+ display: flex;+ justify-content: space-between;+ align-items: center;+ font-family: var(--hp-mono);+ font-size: 11px;+ color: #8b949e;+ letter-spacing: 0.3px;+}++.hp-code-output {+ border-top: 1px solid #2d3545;+ background: #141820;+ padding: 14px 20px;+ font-family: var(--hp-mono);+ font-size: 12.5px;+ line-height: 1.7;+ color: #8b949e;+}+.hp-code-output .line {+ white-space: pre;+ min-height: 1em;+}+.hp-code-output-header {+ font-family: var(--hp-mono);+ font-size: 10px;+ letter-spacing: 1.4px;+ text-transform: uppercase;+ color: #505a6e;+ margin-bottom: 8px;+}+.hp-code-output .tok-s { color: #a5d6ff; }+.hp-code-output .tok-num { color: #d2a8ff; }++/* ===== HERO INTERACTIVE BUTTONS ===== */+.hp-code-buttons {+ display: flex;+ gap: 8px;+ margin-bottom: 10px;+}+.hp-code-btn {+ flex: 1;+ text-align: center;+ font-family: var(--hp-mono);+ font-size: 11px;+ letter-spacing: 0.3px;+ color: var(--hp-fg-2);+ background: var(--hp-bg-2);+ border: 1px solid var(--hp-line);+ border-radius: 999px;+ padding: 8px 14px;+ cursor: pointer;+ transition: color 0.15s, border-color 0.15s, background 0.15s;+ white-space: nowrap;+}+.hp-code-btn:hover {+ color: var(--hp-fg);+ border-color: var(--hp-fg-3);+}+.hp-code-btn.active {+ color: var(--hp-fg);+ border-color: var(--hp-accent);+ background: var(--hp-accent-bg);+}+.hp-line-flash {+ background-color: rgba(194, 77, 44, 0.14);+}+[data-md-color-scheme="slate"] .hp-line-flash {+ background-color: rgba(232, 128, 90, 0.14);+}++/* Hero code dark syntax tokens — needs .dspy-home prefix to beat general token rules */+.dspy-home .hp-code-window .tok-k { color: #ff7b72; font-weight: 600; }+.dspy-home .hp-code-window .tok-s { color: #a5d6ff; }+.dspy-home .hp-code-window .tok-cm { color: #8b949e; font-style: italic; }+.dspy-home .hp-code-window .tok-num { color: #d2a8ff; }+.dspy-home .hp-code-window .tok-n { color: #e6edf3; }+.dspy-home .hp-code-window .tok-m { color: #d2a8ff; }+.dspy-home .hp-code-window .tok-t { color: #7ee787; }++/* ===== STATS STRIP ===== */+.hp-stats {+ background: var(--hp-bg-2);+ padding: 32px 0;+}+.hp-stats-grid {+ display: grid;+ grid-template-columns: repeat(3, 1fr) 1.6fr;+ align-items: stretch;+}+.hp-stat { padding: 22px 28px; }+.hp-stat + .hp-stat { border-left: 1px solid var(--hp-line); }+.hp-stat-num {+ font-family: var(--hp-mono);+ font-size: 34px;+ font-weight: 600;+ letter-spacing: -1px;+ color: var(--hp-fg);+}+.hp-stat-label {+ font-family: var(--hp-mono);+ font-size: 11px;+ letter-spacing: 0.4px;+ color: var(--hp-fg-3);+ text-transform: uppercase;+ margin-top: 4px;+}+.hp-stat-production {+ border-left: 1px solid var(--hp-line);+ padding: 22px 28px;+ display: flex;+ flex-direction: column;+ justify-content: center;+ gap: 14px;+}+.hp-stat-production-label {+ font-family: var(--hp-mono);+ font-size: 11px;+ letter-spacing: 1.4px;+ text-transform: uppercase;+ color: var(--hp-fg-3);+}+.hp-logos {+ display: flex;+ gap: 24px;+ align-items: center;+ flex-wrap: nowrap;+}+.dspy-home .hp-logo-img,+.md-typeset .hp-logo-img {+ height: 20px !important;+ width: auto !important;+ max-width: 120px !important;+ max-height: 20px !important;+ object-fit: contain;+ opacity: 0.7;+ filter: grayscale(1);+ display: inline-block;+ vertical-align: middle;+}+.dspy-home .hp-logo-img[alt="Shopify"] { height: 24px !important; max-height: 24px !important; }+.dspy-home .hp-logo-img[alt="Dropbox"] { height: 18px !important; max-height: 18px !important; max-width: 100px !important; }+[data-md-color-scheme="slate"] .dspy-home .hp-logo-img {+ filter: grayscale(1) brightness(0) invert(1);+ opacity: 0.6;+}++/* ===== FEATURES (THREE PRIMITIVES) ===== */+.hp-features { padding: 64px 0; }+.hp-features-grid {+ display: grid;+ grid-template-columns: repeat(3, minmax(0, 1fr));+ grid-template-rows: repeat(5, auto);+ gap: 0 20px;+ margin-top: 40px;+}+.hp-feature {+ border: 1px solid var(--hp-line);+ padding: 28px 28px 0;+ display: grid;+ grid-template-rows: subgrid;+ grid-row: span 5;+ min-width: 0;+ overflow: hidden;+}+.hp-feature-header {+ display: flex;+ justify-content: space-between;+ align-items: center;+ margin-bottom: 24px;+}+.hp-feature-num {+ font-family: var(--hp-mono);+ font-size: 11px;+ letter-spacing: 1px;+ color: var(--hp-fg-3);+}+.hp-feature-api {+ font-family: var(--hp-mono);+ font-size: 11px;+ letter-spacing: 0.3px;+ color: var(--hp-accent);+}+.dspy-home .hp-feature h3 {+ font-size: 28px;+ font-weight: 700;+ letter-spacing: -0.3px;+ margin: 0 0 4px;+ color: var(--hp-fg);+}+.hp-feature-tagline {+ font-family: var(--hp-mono);+ font-size: 13px;+ color: var(--hp-accent);+ margin-bottom: 14px;+}+.dspy-home .hp-feature p {+ color: var(--hp-fg-2);+ font-size: 15px;+ line-height: 1.45;+ margin: 0;+ max-width: none;+}+.hp-feature-cta {+ padding: 16px 0;+ align-self: start;+}+.dspy-home .hp-cta-link,+.md-typeset .hp-cta-link {+ font-family: var(--hp-mono) !important;+ font-size: 13px;+ font-weight: 600;+ color: var(--hp-accent) !important;+ text-decoration: none !important;+ padding: 8px 16px;+ border: 1.5px solid var(--hp-accent);+ display: inline-block;+ transition: background 0.15s, color 0.15s;+}+.dspy-home .hp-cta-link:hover,+.md-typeset .hp-cta-link:hover {+ background: var(--hp-accent);+ color: #fff !important;+}+.hp-feature-code {+ font-family: var(--hp-mono);+ background: var(--hp-bg-2);+ border-top: 1px solid var(--hp-line);+ margin: 0 -28px 0;+ padding: 16px 22px;+ font-size: 11.5px;+ line-height: 1.7;+ align-self: stretch;+ overflow: hidden;+}+.hp-feature-code .line { white-space: pre; min-height: 1em; overflow: hidden; text-overflow: ellipsis; }++/* ===== EXAMPLES (TABBED) ===== */+.hp-examples {+ background: var(--hp-bg-2);+ padding: 64px 0;+}+.hp-examples-header {+ display: flex;+ justify-content: space-between;+ align-items: flex-end;+ flex-wrap: wrap;+ gap: 20px;+ margin: 0 0 40px;+}+.hp-examples-note {+ font-family: var(--hp-mono);+ font-size: 12px;+ color: var(--hp-fg-3);+}++/* Pure CSS tabs via radio buttons */+.hp-tabs input[type="radio"] { display: none; }+.hp-tabs-wrapper {+ border: 1px solid var(--hp-line);+ background: var(--hp-bg);+}+.hp-tabs-bar {+ display: flex;+ border-bottom: 1px solid var(--hp-line);+}+.hp-tabs-bar label {+ font-family: var(--hp-mono);+ padding: 14px 22px;+ font-size: 13px;+ font-weight: 500;+ cursor: pointer;+ border-right: 1px solid var(--hp-line);+ border-bottom: 2px solid transparent;+ margin-bottom: -1px;+ color: var(--hp-fg-3);+ white-space: nowrap;+ transition: color 0.15s;+}+.hp-tabs-bar label:hover { color: var(--hp-fg-2); }+.hp-tab-panel { display: none; grid-template-columns: 1.2fr 1fr; }+.hp-tab-code {+ border-right: 1px solid var(--hp-line);+ padding: 22px 28px;+ font-family: var(--hp-mono);+ font-size: 13px;+ line-height: 1.75;+ overflow: hidden;+}+.hp-tab-code .line { white-space: pre; min-height: 1em; }+.hp-tab-output {+ background: var(--hp-bg-2);+ padding: 22px 28px;+ font-family: var(--hp-mono);+ font-size: 12.5px;+ line-height: 1.7;+ overflow: hidden;+}+.hp-tab-output-header {+ display: flex;+ justify-content: space-between;+ align-items: center;+ margin-bottom: 12px;+ font-family: var(--hp-mono);+ font-size: 10px;+ letter-spacing: 1.4px;+ text-transform: uppercase;+ color: var(--hp-fg-3);+}+.hp-tab-output .line { white-space: pre; min-height: 1em; }+.hp-tab-footer {+ border-top: 1px solid var(--hp-line);+ padding: 12px 18px;+ display: flex;+ justify-content: space-between;+ align-items: center;+}+.hp-tab-footer-caption {+ font-family: var(--hp-mono);+ font-size: 11px;+ font-style: italic;+ color: var(--hp-fg-3);+}+.dspy-home .hp-tab-footer a,+.md-typeset .hp-tab-footer a {+ font-family: var(--hp-mono);+ font-size: 11px;+ color: var(--hp-fg-2) !important;+ text-decoration: none !important;+ border-bottom: 1px solid var(--hp-line);+}++/* Tab active states */+.hp-tab-caption { display: none; }+.hp-tab-link { display: none; }++#hp-tab-extract:checked ~ .hp-tabs-wrapper .hp-tabs-bar label[for="hp-tab-extract"],+#hp-tab-agent:checked ~ .hp-tabs-wrapper .hp-tabs-bar label[for="hp-tab-agent"],+#hp-tab-pipeline:checked ~ .hp-tabs-wrapper .hp-tabs-bar label[for="hp-tab-pipeline"],+#hp-tab-multimodal:checked ~ .hp-tabs-wrapper .hp-tabs-bar label[for="hp-tab-multimodal"],+#hp-tab-optimize:checked ~ .hp-tabs-wrapper .hp-tabs-bar label[for="hp-tab-optimize"] {+ color: var(--hp-fg);+ font-weight: 600;+ border-bottom-color: var(--hp-accent);+ background: var(--hp-bg);+}+#hp-tab-extract:checked ~ .hp-tabs-wrapper .hp-tab-panels #hp-panel-extract { display: grid; }+#hp-tab-agent:checked ~ .hp-tabs-wrapper .hp-tab-panels #hp-panel-agent { display: grid; }+#hp-tab-pipeline:checked ~ .hp-tabs-wrapper .hp-tab-panels #hp-panel-pipeline { display: grid; }+#hp-tab-multimodal:checked ~ .hp-tabs-wrapper .hp-tab-panels #hp-panel-multimodal { display: grid; }+#hp-tab-optimize:checked ~ .hp-tabs-wrapper .hp-tab-panels #hp-panel-optimize { display: grid; }++#hp-tab-extract:checked ~ .hp-tabs-wrapper .hp-tab-caption[data-tab="extract"] { display: inline; }+#hp-tab-agent:checked ~ .hp-tabs-wrapper .hp-tab-caption[data-tab="agent"] { display: inline; }+#hp-tab-pipeline:checked ~ .hp-tabs-wrapper .hp-tab-caption[data-tab="pipeline"] { display: inline; }+#hp-tab-multimodal:checked ~ .hp-tabs-wrapper .hp-tab-caption[data-tab="multimodal"] { display: inline; }+#hp-tab-optimize:checked ~ .hp-tabs-wrapper .hp-tab-caption[data-tab="optimize"] { display: inline; }++#hp-tab-extract:checked ~ .hp-tabs-wrapper .hp-tab-link[data-tab="extract"] { display: inline; }+#hp-tab-agent:checked ~ .hp-tabs-wrapper .hp-tab-link[data-tab="agent"] { display: inline; }+#hp-tab-pipeline:checked ~ .hp-tabs-wrapper .hp-tab-link[data-tab="pipeline"] { display: inline; }+#hp-tab-multimodal:checked ~ .hp-tabs-wrapper .hp-tab-link[data-tab="multimodal"] { display: inline; }+#hp-tab-optimize:checked ~ .hp-tabs-wrapper .hp-tab-link[data-tab="optimize"] { display: inline; }++/* ===== ECOSYSTEM ===== */+.hp-ecosystem { padding: 64px 0; }+.hp-eco-grid {+ display: grid;+ grid-template-columns: 1fr 1fr;+ gap: 56px;+ margin-top: 20px;+}+.dspy-home .hp-eco-title {+ font-weight: 700;+ font-size: clamp(26px, 3vw, 36px);+ letter-spacing: -0.5px;+ line-height: 1.15;+ margin: 0 0 16px;+ max-width: 520px;+ color: var(--hp-fg);+}+.hp-eco-desc {+ color: var(--hp-fg-2);+ font-size: 15px;+ line-height: 1.45;+ max-width: 520px;+ margin: 0 0 32px;+}+.hp-papers {+ font-family: var(--hp-mono);+ display: grid;+ grid-template-columns: auto 1fr auto;+ font-size: 13px;+}+.hp-papers > div { padding: 14px 0; border-top: 1px solid var(--hp-line); }+.hp-paper-date { color: var(--hp-fg-3); white-space: nowrap; padding-right: 20px !important; }+.hp-paper-title { color: var(--hp-fg); font-weight: 500; }+.hp-paper-link { white-space: nowrap; padding-left: 20px !important; text-align: right; }+.dspy-home .hp-paper-link a,+.md-typeset .hp-paper-link a {+ color: var(--hp-fg-2) !important;+ text-decoration: none !important;+ border-bottom: 1px dotted var(--hp-fg-3);+}+.hp-papers-end { border-top: 1px solid var(--hp-line); grid-column: 1 / -1; }++.dspy-home .hp-eco-right h3 {+ font-family: var(--hp-mono);+ font-weight: 600;+ font-size: 18px;+ letter-spacing: -0.3px;+ margin: 8px 0 20px;+ color: var(--hp-fg-2);+}+.hp-built-grid {+ display: grid;+ grid-template-columns: 1fr 1fr;+ border: 1px solid var(--hp-line);+ border-bottom: none;+ border-right: none;+}+.hp-built-item {+ padding: 22px 24px;+ border-right: 1px solid var(--hp-line);+ border-bottom: 1px solid var(--hp-line);+}+.hp-built-item-header {+ display: flex;+ justify-content: space-between;+ align-items: center;+ margin-bottom: 6px;+}+.hp-built-name { font-family: var(--hp-mono); font-size: 15px; font-weight: 600; }+.dspy-home a.hp-built-name,+.md-typeset a.hp-built-name {+ color: var(--hp-fg) !important;+ text-decoration: none !important;+ border-bottom: 1px dotted var(--hp-fg-3);+}+.dspy-home a.hp-built-name:hover { color: var(--hp-accent) !important; border-bottom-color: var(--hp-accent); }+.hp-built-kind {+ font-family: var(--hp-mono);+ font-size: 10px;+ letter-spacing: 0.6px;+ text-transform: uppercase;+ color: var(--hp-fg-3);+ border: 1px solid var(--hp-line);+ padding: 2px 7px;+}+.hp-built-blurb { color: var(--hp-fg-3); font-size: 13px; margin-bottom: 3px; }+.hp-built-who { font-family: var(--hp-mono); color: var(--hp-fg-3); font-size: 11px; opacity: 0.8; }+.dspy-home a.hp-built-more,+.md-typeset a.hp-built-more {+ color: var(--hp-fg) !important;+ text-decoration: none !important;+ border-bottom: 1px dotted var(--hp-fg-3);+}+.dspy-home a.hp-built-more:hover { color: var(--hp-accent) !important; border-bottom-color: var(--hp-accent); }++.hp-community {+ margin-top: 40px;+ padding: 24px;+ border: 1px solid var(--hp-line);+ background: var(--hp-bg-2);+}+.hp-community-label {+ font-family: var(--hp-mono);+ font-size: 11px;+ letter-spacing: 1.2px;+ text-transform: uppercase;+ color: var(--hp-fg-3);+ margin-bottom: 10px;+}+.hp-community-stats { display: grid; grid-template-columns: 1fr 1fr; gap: 14px; }+.hp-community-stat-num { font-family: var(--hp-mono); font-size: 22px; font-weight: 600; letter-spacing: -0.4px; }+.hp-community-stat-label {+ font-family: var(--hp-mono);+ font-size: 10.5px;+ letter-spacing: 0.4px;+ text-transform: uppercase;+ color: var(--hp-fg-3);+}+.hp-community-links { display: flex; gap: 10px; margin-top: 18px; flex-wrap: wrap; }+.dspy-home .hp-community-links a,+.md-typeset .hp-community-links a {+ font-family: var(--hp-mono);+ font-size: 12px;+ color: var(--hp-fg-2) !important;+ text-decoration: none !important;+ padding: 6px 12px;+ border: 1px solid var(--hp-line);+ transition: border-color 0.15s;+}+.dspy-home .hp-community-links a:hover { border-color: var(--hp-fg-3); }++/* ===== SYNTAX TOKENS ===== */+.dspy-home .tok-k { color: var(--hp-accent); font-weight: 600; }+.dspy-home .tok-s { color: var(--hp-ok); }+.dspy-home .tok-cm { color: var(--hp-fg-3); font-style: italic; }+.dspy-home .tok-num { color: var(--hp-warn); }+.dspy-home .tok-n { color: var(--hp-fg); }+.dspy-home .tok-m { color: var(--hp-fg); }+.dspy-home .tok-t { color: var(--hp-fg); }+.dspy-home .tok-p { color: var(--hp-fg-2); }++/* ===== RESPONSIVE ===== */+@media (max-width: 960px) {+ .hp-container { padding-left: 24px; padding-right: 24px; }+ .hp-hero { padding: 32px 0 40px; }+ .hp-hero-grid {+ grid-template-columns: 1fr;+ gap: 40px;+ }+ .hp-hero-title { font-size: clamp(32px, 6vw, 48px); }+ .hp-hero-sub { margin-bottom: 32px; }+ .hp-hero-actions { margin-bottom: 24px; }+ .hp-hero-meta { gap: 16px; padding-top: 16px; }+ .hp-stats-grid { grid-template-columns: repeat(3, 1fr); }+ .hp-stat-production { display: none; }+ .hp-features { padding: 40px 0; }+ .hp-features .hp-section-title { margin-bottom: 0; }+ .hp-features-grid {+ grid-template-columns: 1fr;+ grid-template-rows: auto;+ border: none;+ gap: 20px;+ margin-top: 24px;+ }+ .hp-feature {+ grid-row: auto;+ grid-template-rows: auto;+ border: 1px solid var(--hp-line);+ padding: 24px 24px 0;+ }+ .hp-feature-code { margin-left: -24px; margin-right: -24px; }+ .hp-feature + .hp-feature .hp-feature-code { border-left: none; }+ .hp-examples { padding: 40px 0; }+ .hp-tab-panel { grid-template-columns: 1fr !important; }+ .hp-tab-code { border-right: none; border-bottom: 1px solid var(--hp-line); }+ .hp-ecosystem { padding: 40px 0; }+ .hp-eco-grid { grid-template-columns: 1fr; gap: 40px; }+ .hp-examples-header { flex-direction: column; align-items: flex-start; }+ .hp-tab-footer { flex-direction: column; align-items: flex-start; gap: 4px; }+}++@media (max-width: 600px) {+ .hp-container { padding-left: 24px; padding-right: 24px; }+ .hp-hero { padding: 24px 0 40px; }+ .hp-hero-badge { margin-bottom: 24px; }+ .hp-hero-title { font-size: 28px; letter-spacing: -1px; margin-bottom: 20px; }+ .hp-hero-sub { font-size: 16px; margin-bottom: 24px; }+ .hp-hero-actions { flex-direction: column; margin-bottom: 20px; }+ .hp-btn-primary, .hp-btn-outline { text-align: center; justify-content: center; }+ .hp-hero-meta { gap: 12px; padding-top: 14px; }+ .hp-code-buttons { flex-wrap: wrap; }+ .hp-code-btn { padding: 12px 14px; font-size: 12px; min-height: 44px; }+ .hp-stats { padding: 28px 0; }+ .hp-stats-grid { grid-template-columns: 1fr; }+ .hp-stat { padding: 16px 24px 10px; }+ .hp-stat + .hp-stat { border-left: none; border-top: 1px solid var(--hp-line); }+ .hp-stat-num { font-size: 28px; }+ .hp-features { padding: 48px 0; }+ .hp-features-grid { margin-top: 40px; }+ .hp-section-title { font-size: 24px; }+ .hp-built-grid { grid-template-columns: 1fr; }+ .hp-community-stats { grid-template-columns: 1fr; }+ .hp-tabs-bar { overflow-x: auto; -webkit-overflow-scrolling: touch; }+ .hp-tabs-bar label { padding: 12px 16px; font-size: 12px; }+ .hp-tab-code, .hp-tab-output { padding: 16px; }+ .hp-feature { padding: 20px 20px 0; }+ .hp-feature-code { margin-left: -20px; margin-right: -20px; padding: 14px 16px; }+ .dspy-home .hp-feature h3 { font-size: 22px; }+ .hp-examples { padding: 48px 0; }+ .hp-ecosystem { padding: 48px 0; }+ .hp-eco-grid { margin-top: 0; }+ .dspy-home .hp-eco-title { margin-bottom: 36px; }+}diff --git a/docs/hooks/fetch_stats.py b/docs/hooks/fetch_stats.pynew file mode 100644index 000000000..cd0f12c0c--- /dev/null+++ b/docs/hooks/fetch_stats.py@@ -0,0 +1,172 @@+"""MkDocs hook: fetch live stats at build time and inject into config.extra.stats.++Hits GitHub, PyPI, and Discord APIs once per build. Results are cached to+.cache/stats.json for 1 hour so dev-server rebuilds don't hammer rate limits.+Falls back to cached (or hardcoded) values on any API failure.+"""++import json+import os+import re+import time+import logging+from datetime import datetime, timedelta+from pathlib import Path+from urllib.request import Request, urlopen+from urllib.error import URLError++log = logging.getLogger("mkdocs.hooks.fetch_stats")++REPO = "stanfordnlp/dspy"+DISCORD_INVITE = "XCGy2WDCQB"+CACHE_DIR = Path(__file__).parent.parent / ".cache"+CACHE_FILE = CACHE_DIR / "stats.json"+CACHE_TTL = 3600 # 1 hour++DEFAULTS = {+ "release_version": "3.2.1",+ "release_major_minor": "3.2",+ "release_date": "May 2025",+ "release_blurb": "Improved tool calling and more",+ "monthly_downloads": "7.5M+",+ "contributors": "400+",+ "stars": "34.6k",+ "discord_members": "8.4k",+ "merged_prs_yr": "420+",+}++GITHUB_HEADERS = {"Accept": "application/vnd.github.v3+json"}+++def _get(url, headers=None, timeout=10):+ req = Request(url, headers=headers or {})+ with urlopen(req, timeout=timeout) as resp:+ return json.loads(resp.read()), resp.headers+++def _fmt(n):+ if n >= 1_000_000:+ v = n / 1_000_000+ return f"{v:.1f}M+" if v < 10 else f"{v:.0f}M+"+ if n >= 1_000:+ v = n / 1_000+ return f"{v:.1f}k" if v < 10 else f"{v:.0f}k"+ return f"{n}+"+++def _load_cache():+ try:+ if CACHE_FILE.exists():+ data = json.loads(CACHE_FILE.read_text())+ if time.time() - data.get("_ts", 0) < CACHE_TTL:+ log.info("Using cached stats (age: %ds)", int(time.time() - data["_ts"]))+ return data+ except Exception:+ pass+ return None+++def _save_cache(stats):+ try:+ CACHE_DIR.mkdir(parents=True, exist_ok=True)+ stats["_ts"] = time.time()+ CACHE_FILE.write_text(json.dumps(stats, indent=2))+ except Exception as e:+ log.warning("Could not write stats cache: %s", e)+++def _fetch_release():+ data, _ = _get(+ f"https://api.github.com/repos/{REPO}/releases/latest",+ headers=GITHUB_HEADERS,+ )+ tag = data["tag_name"].lstrip("v")+ parts = tag.split(".")+ major_minor = f"{parts[0]}.{parts[1]}" if len(parts) >= 2 else tag+ pub = datetime.fromisoformat(data["published_at"].replace("Z", "+00:00"))+ return {+ "release_version": tag,+ "release_major_minor": major_minor,+ "release_date": pub.strftime("%b %Y"),+ }+++def _fetch_pypi_downloads():+ data, _ = _get("https://pypistats.org/api/packages/dspy/recent")+ return {"monthly_downloads": _fmt(data["data"]["last_month"])}+++def _fetch_stars():+ data, _ = _get(+ f"https://api.github.com/repos/{REPO}",+ headers=GITHUB_HEADERS,+ )+ return {"stars": _fmt(data["stargazers_count"])}+++def _fetch_contributors():+ _, headers = _get(+ f"https://api.github.com/repos/{REPO}/contributors?per_page=1&anon=true",+ headers=GITHUB_HEADERS,+ )+ link = headers.get("Link", "")+ m = re.search(r'page=(\d+)>; rel="last"', link)+ if m:+ return {"contributors": _fmt(int(m.group(1)))}+ return {}+++def _fetch_discord():+ data, _ = _get(+ f"https://discord.com/api/v9/invites/{DISCORD_INVITE}?with_counts=true"+ )+ return {"discord_members": _fmt(data["approximate_member_count"])}+++def _fetch_merged_prs():+ one_year_ago = (datetime.now() - timedelta(days=365)).strftime("%Y-%m-%d")+ q = f"repo:{REPO}+is:pr+is:merged+merged:>{one_year_ago}"+ data, _ = _get(+ f"https://api.github.com/search/issues?q={q}&per_page=1",+ headers=GITHUB_HEADERS,+ )+ return {"merged_prs_yr": _fmt(data["total_count"])}+++FETCHERS = [+ ("release", _fetch_release),+ ("pypi", _fetch_pypi_downloads),+ ("stars", _fetch_stars),+ ("contributors", _fetch_contributors),+ ("discord", _fetch_discord),+ ("merged_prs", _fetch_merged_prs),+]+++def _fetch_all():+ stats = dict(DEFAULTS)+ for name, fn in FETCHERS:+ try:+ result = fn()+ stats.update(result)+ log.info(" %s: %s", name, result)+ except Exception as e:+ log.warning(" %s failed, using fallback: %s", name, e)+ return stats+++# ── MkDocs hook entry point ──────────────────────────────────────────────────++def on_config(config):+ log.info("Fetching live stats for home page...")++ cached = _load_cache()+ if cached:+ stats = {k: v for k, v in cached.items() if not k.startswith("_")}+ else:+ stats = _fetch_all()+ _save_cache(stats)++ config.setdefault("extra", {})["stats"] = stats+ log.info("Stats injected: %s", stats)+ return configdiff --git a/docs/mkdocs.yml b/docs/mkdocs.ymlindex 182845e5a..133f6c681 100644--- a/docs/mkdocs.yml+++ b/docs/mkdocs.yml@@ -9,24 +9,32 @@ edit_uri: blob/main/docs/docs/docs_dir: "docs/"nav:- - Get Started: index.md- - Learn DSPy:- - Learning DSPy: learn/index.md- - DSPy Programming:- - Programming Overview: learn/programming/overview.md- - Language Models: learn/programming/language_models.md- - Signatures: learn/programming/signatures.md- - Modules: learn/programming/modules.md- - Adapters: learn/programming/adapters.md- - Tools: learn/programming/tools.md- - MCP: learn/programming/mcp.md- - DSPy Evaluation:- - Evaluation Overview: learn/evaluation/overview.md- - Data Handling: learn/evaluation/data.md- - Metrics: learn/evaluation/metrics.md- - DSPy Optimization:- - Optimization Overview: learn/optimization/overview.md- - Optimizers: learn/optimization/optimizers.md+ - Overview: index.md+ - Getting Started:+ - Program, don't prompt: getting-started/program-dont-prompt.md+ - Setting up DSPy: getting-started/installation.md+ - Your first program: getting-started/first-program.md+ - Expanding signatures: getting-started/expanding-signatures.md+ - Class-based signatures: getting-started/class-based-signatures.md+ - Changing modules: getting-started/changing-modules.md+ - Tools with ReAct: getting-started/react-and-tools.md+ - Composing modules: getting-started/composing-modules.md+ - Metrics: getting-started/metrics.md+ - GEPA optimization: getting-started/gepa-optimization.md+ - Saving and loading: getting-started/saving-and-loading.md+ - Where to go next: getting-started/where-to-go-next.md+ - Diving Deeper:+ - Signatures in depth: diving-deeper/signatures-in-depth.md+ - "Modules: composing your own": diving-deeper/modules.md+ - Built-in module variants: diving-deeper/built-in-module-variants.md+ - "Tools, ReAct, and MCP": diving-deeper/tools-react-and-mcp.md+ - Metrics and evaluation: diving-deeper/metrics-and-evaluation.md+ - "Optimizers: choosing one": diving-deeper/choosing-an-optimizer.md+ - GEPA in depth: diving-deeper/gepa-in-depth.md+ - BootstrapFewShot family: diving-deeper/bootstrap-fewshot-family.md+ - "Adapters: how signatures become prompts": diving-deeper/adapters.md+ - "Settings and context()": diving-deeper/settings-and-context.md+ - Saving and loading: diving-deeper/saving-and-loading.md- Tutorials:- Tutorials Overview: tutorials/index.md- Build AI Programs with DSPy:@@ -78,8 +86,6 @@ nav:- Email Information Extraction: tutorials/email_extraction/index.md- Code Generation for Unfamiliar Libraries: tutorials/sample_code_generation/index.md- Building a Creative Text-Based AI Game: tutorials/ai_text_game/index.md- - Deployment:- - Deploying DSPy: production/index.md- Community:- Use Cases: community/use-cases.md- Built with DSPy: community/built-with-dspy.md@@ -178,13 +184,15 @@ nav:theme:name: materialcustom_dir: overrides+ font:+ text: Inter+ code: Fira Monofeatures:- navigation.tabs- navigation.path- navigation.indexes- navigation.expand- toc.follow- - toc.integrate- navigation.top- search.suggest- search.highlight@@ -192,7 +200,6 @@ theme:- content.code.annotation- content.code.copy- navigation.footer- - content.action.editlanguage: enpalette:- scheme: default@@ -211,7 +218,7 @@ theme:repo: fontawesome/brands/git-altedit: material/pencilview: material/eye- logo: static/img/dspy_logo.png+ logo: static/dspy-logo.svgfavicon: static/img/logo.pngextra_css:@@ -269,6 +276,35 @@ plugins:"community/community-ports.md": "community/built-with-dspy.md""production/companies.md": "community/use-cases.md"++ # Redirect old learn/ pages to the new Getting Started tutorial+ "learn/index.md": "getting-started/program-dont-prompt.md"+ "learn/programming/overview.md": "getting-started/first-program.md"+ "learn/programming/language_models.md": "getting-started/installation.md"+ "learn/programming/signatures.md": "getting-started/expanding-signatures.md"+ "learn/programming/modules.md": "getting-started/changing-modules.md"+ "learn/programming/adapters.md": "getting-started/first-program.md"+ "learn/programming/tools.md": "getting-started/react-and-tools.md"+ "learn/programming/mcp.md": "getting-started/react-and-tools.md"+ "learn/evaluation/overview.md": "getting-started/metrics.md"+ "learn/evaluation/data.md": "getting-started/metrics.md"+ "learn/evaluation/metrics.md": "getting-started/metrics.md"+ "learn/optimization/overview.md": "getting-started/gepa-optimization.md"+ "learn/optimization/optimizers.md": "getting-started/gepa-optimization.md"++ # Redirect old numbered Getting Started URLs to the new kebab-case paths+ "getting_started/01_program_dont_prompt.md": "getting-started/program-dont-prompt.md"+ "getting_started/02_installation.md": "getting-started/installation.md"+ "getting_started/03_first_program.md": "getting-started/first-program.md"+ "getting_started/04_expanding_signatures.md": "getting-started/expanding-signatures.md"+ "getting_started/05_class_based_signatures.md": "getting-started/class-based-signatures.md"+ "getting_started/06_changing_modules.md": "getting-started/changing-modules.md"+ "getting_started/07_react_and_tools.md": "getting-started/react-and-tools.md"+ "getting_started/08_composing_modules.md": "getting-started/composing-modules.md"+ "getting_started/09_metrics.md": "getting-started/metrics.md"+ "getting_started/10_gepa_optimization.md": "getting-started/gepa-optimization.md"+ "getting_started/11_saving_and_loading.md": "getting-started/saving-and-loading.md"+ "getting_started/12_where_to_go_next.md": "getting-started/where-to-go-next.md"- llmstxt:markdown_description: >DSPy is the framework for programming—rather than prompting—language models.@@ -278,16 +314,10 @@ plugins:sections:Get Started:- index.md: DSPy overview and quick start guide- Learn DSPy - Learning DSPy:- - learn/index.md: Three stages of building AI systems - programming, evaluation, and optimization- Learn DSPy - DSPy Programming:- - learn/programming/**.md- Learn DSPy - DSPy Evaluation:- - learn/evaluation/**.md- Learn DSPy - DSPy Optimization:- - learn/optimization/**.md- # Since we don't have a learn/**.md, future sections within learn/ should be added here- # to ensure they show up in the llms.txt navigation+ Getting Started:+ - getting-started/**.md+ Diving Deeper:+ - diving-deeper/**.mdTutorials - Docs:- tutorials/**.mdTutorials - Notebooks:@@ -300,6 +330,9 @@ plugins:API Reference:- api/**.md+hooks:+ - hooks/fetch_stats.py+extra:social:- icon: fontawesome/brands/github@@ -310,9 +343,10 @@ extra:extra_javascript:- "js/runllm-widget.js"- "js/tutorial-nav.js"- - "js/copy-as-markdown.js"+ - "js/hero-interactive.js"markdown_extensions:+ - smarty- toc:permalink: truetoc_depth: 3@@ -336,4 +370,4 @@ markdown_extensions:emoji_generator: !!python/name:material.extensions.emoji.to_svgcopyright: |- © 2025 <a href="https://github.com/stanfordnlp" target="_blank" rel="noopener">DSPy</a>\ No newline at end of file+ © 2026 <a href="https://github.com/stanfordnlp" target="_blank" rel="noopener">DSPy</a>\ No newline at end of filediff --git a/docs/overrides/home.html b/docs/overrides/home.htmlindex f8698a749..c48aab411 100644--- a/docs/overrides/home.html+++ b/docs/overrides/home.html@@ -1,147 +1,496 @@-{% extends "base.html" %}+{% extends "main.html" %}++{# Hide the site-wide announcement banner on the landing page only #}+{% block announce %}{% endblock %}++{% block styles %}+ {{ super() }}+ <link rel="stylesheet" href="{{ 'stylesheets/home.css' | url }}">+{% endblock %}{% block content %}-<style>- .md-main__inner .md-grid {- padding: 0;- margin: 0;- }-- .content-container {- max-width: 100%;- margin: 0;- padding: 0;- }-- .hero {- text-align: center;- padding: 4rem 2rem;- margin: 0;- background-color: #f5f6f77a;- color: white;- }-- .hero-logo {- max-width: 15rem;- height: auto;- margin: 0 auto;- }-- .hero-subtitle {- font-size: 1.2rem;- margin: 1.5rem 0;- color: #e2e8f0;- }-- .cta-button {- display: inline-block;- padding: 0.75rem 1.5rem;- background-color: transparent;- color: black;- text-decoration: none;- border-radius: 0.375rem;- font-weight: 600;- border: 2px solid black;- transition: all 0.3s ease;- }-- .cta-button:hover {- background-color: white;- color: black;- border: 2px solid white;- }-- .features-section {- padding: 4rem 2rem;- }-- .features-title {- text-align: center;- font-size: 2rem;- font-weight: 700;- margin-bottom: 3rem;- color: #1a202c;- }-- .features-grid {- display: grid;- grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));- gap: 3rem;- max-width: 1200px;- margin: 0 auto;- }-- .feature-card {- text-align: center;- padding: 1.5rem;- }-- .feature-image {- width: 10rem;- height: auto;- margin: 0 auto 1.5rem;- }-- .feature-title {- font-size: 1.25rem;- font-weight: 700;- margin-bottom: 1rem;- color: #2d3748;- }-- .feature-description {- color: #4a5568;- line-height: 1.5;- }-- @media (max-width: 768px) {- .hero {- padding: 3rem 1rem;- }-- .hero-logo {- max-width: 10rem;- }-- .features-grid {- grid-template-columns: 1fr;- gap: 2rem;- }-- .feature-card {- padding: 1rem;- }- }-</style>--<div class="content-container">- <div class="hero">- <img src="{{ 'static/img/dspy_logo.png' | url }}" alt="DSPy Logo" class="hero-logo">- <p class="hero-subtitle">Programming—not prompting—Language Models</p>- <a href="{{ 'quick-start/getting-started-1' | url }}" class="cta-button">Get Started with DSPy</a>+<div class="dspy-home">++ <!-- ===== HERO ===== -->+ <section class="hp-section hp-hero">+ <div class="hp-container hp-hero-grid">+ <div class="hp-hero-text">+ <div class="hp-hero-badge">+ <span class="hp-dot"></span>+ DSPy {{ config.extra.stats.release_major_minor }} — {{ config.extra.stats.release_blurb }}+ <span style="color:var(--hp-fg-3)">·</span>+ <a href="https://github.com/stanfordnlp/dspy/releases">learn more →</a>+ </div>++ <h1 class="hp-hero-title">+ <span class="hp-hl">Program</span>, don’t prompt,<br>your LLMs.+ </h1>++ <p class="hp-hero-sub">+ DSPy is a Python framework for building AI systems. Express your+ tasks as structured signatures, not prompts, to produce+ maintainable, modular, and optimizable programs.+ </p>++ <div class="hp-hero-actions">+ <a href="{{ 'getting-started/installation/' | url }}" class="hp-btn-primary">+ <span class="hp-dollar">$</span> pip install -U dspy+ </a>+ <a href="{{ 'getting-started/program-dont-prompt/' | url }}" class="hp-btn-outline">+ Getting Started →+ </a>+ </div>++ <div class="hp-hero-meta">+ <span><strong>python</strong> ≥ 3.10</span>+ <span>MIT license</span>+ <span>Stanford NLP</span>+ <span><a href="https://github.com/stanfordnlp/dspy">github.com/stanfordnlp/dspy</a></span>+ </div>+ </div>++ <div class="hp-hero-code">+ <div class="hp-code-buttons">+ <button class="hp-code-btn" id="hp-btn-lm">Change LLM</button>+ <button class="hp-code-btn" id="hp-btn-field">Add a Field</button>+ <button class="hp-code-btn" id="hp-btn-agent">Make it an Agent</button>+ </div>+ <div class="hp-code-window">+ <div class="hp-code-chrome">+ <div class="hp-dots"><span></span><span></span><span></span></div>+ <div class="hp-code-title">+ <strong>extract_events.py</strong>+ </div>+ </div>+ <div class="hp-code-body">+ <div class="hp-line-nums" id="hp-hero-linenums">+ <span>1</span><span>2</span><span>3</span><span>4</span><span>5</span>+ <span>6</span><span>7</span><span>8</span><span>9</span><span>10</span>+ </div>+ <div class="hp-code-content" id="hp-hero-code">+ <div class="line">lm = dspy.<span class="tok-m">LM</span>(<span class="tok-s">"openai/gpt-5.4-nano"</span>)</div>+ <div class="line"> </div>+ <div class="line"><span class="tok-k">class</span> <span class="tok-t">ExtractEvent</span>(dspy.Signature):</div>+ <div class="line"> <span class="tok-s">"""Extract event details from an email."""</span></div>+ <div class="line"> email: <span class="tok-t">str</span> = dspy.<span class="tok-m">InputField</span>()</div>+ <div class="line"> event_name: <span class="tok-t">str</span> = dspy.<span class="tok-m">OutputField</span>()</div>+ <div class="line"> date: <span class="tok-t">str</span> = dspy.<span class="tok-m">OutputField</span>()</div>+ <div class="line"> </div>+ <div class="line">extract = dspy.<span class="tok-m">Predict</span>(ExtractEvent)</div>+ <div class="line">extract(email=inbox_message)</div>+ </div>+ </div>+ <div class="hp-code-output" id="hp-hero-output">+ <div class="hp-code-output-header">output</div>+ <div class="line">Prediction(</div>+ <div class="line"> event_name=<span class="tok-s">"Team Offsite"</span>,</div>+ <div class="line"> date=<span class="tok-s">"Thursday, June 5"</span></div>+ <div class="line">)</div>+ </div>+ </div>+ </div></div>+ </section>++ <!-- ===== STATS STRIP ===== -->+ <section class="hp-section hp-stats">+ <div class="hp-container hp-stats-grid">+ <div class="hp-stat">+ <div class="hp-stat-num">{{ config.extra.stats.monthly_downloads }}</div>+ <div class="hp-stat-label">monthly downloads</div>+ </div>+ <div class="hp-stat">+ <div class="hp-stat-num">{{ config.extra.stats.contributors }}</div>+ <div class="hp-stat-label">contributors</div>+ </div>+ <div class="hp-stat">+ <div class="hp-stat-num">{{ config.extra.stats.stars }}</div>+ <div class="hp-stat-label">github stars</div>+ </div>+ <div class="hp-stat-production">+ <div class="hp-stat-production-label">in production at</div>+ <div class="hp-logos">+ <img src="{{ 'static/img/logos/databricks-wordmark.svg' | url }}" alt="Databricks" class="hp-logo-img">+ <img src="{{ 'static/img/logos/shopify-wordmark.svg' | url }}" alt="Shopify" class="hp-logo-img">+ <img src="{{ 'static/img/logos/dropbox-wordmark.svg' | url }}" alt="Dropbox" class="hp-logo-img">+ </div>+ </div>+ </div>+ </section>++ <!-- ===== THREE PRIMITIVES ===== -->+ <section class="hp-section hp-features">+ <div class="hp-container">+ <h2 class="hp-section-title">+ Compose programs with reusable <span class="hp-hl">primitives</span>.+ </h2>++ <div class="hp-features-grid">+ <!-- Signatures -->+ <div class="hp-feature">+ <h3>Signatures</h3>+ <div class="hp-feature-tagline">Declare your task.</div>+ <p>+ Define your task as typed inputs and outputs instead of managing+ messy prompts. Portable, maintainable, and easy to iterate on.+ </p>+ <div class="hp-feature-cta">+ <a href="{{ 'getting-started/expanding-signatures/' | url }}" class="hp-cta-link">Learn about Signatures →</a>+ </div>+ <div class="hp-feature-code">+ <div class="line"><span class="tok-k">class</span> <span class="tok-t">Triage</span>(dspy.Signature):</div>+ <div class="line"> <span class="tok-s">"""Route a support ticket."""</span></div>+ <div class="line"> ticket: <span class="tok-t">str</span> = dspy.<span class="tok-m">InputField</span>()</div>+ <div class="line"> urgency: <span class="tok-t">Literal</span>[<span class="tok-s">"low"</span>, <span class="tok-s">"high"</span>] = dspy.<span class="tok-m">OutputField</span>()</div>+ <div class="line"> team: <span class="tok-t">str</span> = dspy.<span class="tok-m">OutputField</span>()</div>+ </div>+ </div>++ <!-- Modules -->+ <div class="hp-feature">+ <h3>Modules</h3>+ <div class="hp-feature-tagline">Same interface, different strategy.</div>+ <p>+ Modules control how your signature executes. Reason, run+ ensembles, use tools, add a REPL, and more without rewriting your task.+ </p>+ <div class="hp-feature-cta">+ <a href="{{ 'getting-started/changing-modules/' | url }}" class="hp-cta-link">Explore Modules →</a>+ </div>+ <div class="hp-feature-code">+ <div class="line"><span class="tok-cm"># Direct completion</span></div>+ <div class="line">classify = dspy.<span class="tok-m">Predict</span>(Triage)</div>+ <div class="line"> </div>+ <div class="line"><span class="tok-cm"># Add step-by-step reasoning</span></div>+ <div class="line">classify = dspy.<span class="tok-m">ChainOfThought</span>(Triage)</div>+ <div class="line"> </div>+ <div class="line"><span class="tok-cm"># Add tools and a reasoning loop</span></div>+ <div class="line">classify = dspy.<span class="tok-m">ReAct</span>(Triage, tools=[search])</div>+ </div>+ </div>++ <!-- Optimizers -->+ <div class="hp-feature">+ <h3>Optimizers</h3>+ <div class="hp-feature-tagline">Compile your program against a metric.</div>+ <p>+ Give DSPy examples and a scoring function. It tunes your+ prompts automatically until quality converges.+ </p>+ <div class="hp-feature-cta">+ <a href="{{ 'getting-started/gepa-optimization/' | url }}" class="hp-cta-link">Try Optimizers →</a>+ </div>+ <div class="hp-feature-code">+ <div class="line">tp = dspy.<span class="tok-m">GEPA</span>(</div>+ <div class="line"> metric=semantic_f1,</div>+ <div class="line"> auto=<span class="tok-s">"medium"</span>)</div>+ <div class="line">opt = tp.<span class="tok-m">compile</span>(rag, trainset)</div>+ <div class="line"> </div>+ <div class="line"><span class="tok-cm"># Before: 0.41 F1</span></div>+ <div class="line"><span class="tok-cm"># After: 0.63 F1</span></div>+ <div class="line"> </div>+ <div class="line">opt.<span class="tok-m">save</span>(<span class="tok-s">"rag.v2.json"</span>)</div>+ </div>+ </div>+ </div>+ </div>+ </section>++ <!-- ===== IN PRACTICE (TABBED EXAMPLES) ===== -->+ <section class="hp-section hp-examples">+ <div class="hp-container">+ <div class="hp-examples-header">+ <h2 class="hp-section-title" style="margin-top:16px">+ Define a task. Grow it into a system.+ </h2>+ </div>++ <div class="hp-tabs">+ <input type="radio" name="hp-tab" id="hp-tab-extract" checked>+ <input type="radio" name="hp-tab" id="hp-tab-agent">+ <input type="radio" name="hp-tab" id="hp-tab-pipeline">+ <input type="radio" name="hp-tab" id="hp-tab-multimodal">+ <input type="radio" name="hp-tab" id="hp-tab-optimize">++ <div class="hp-tabs-wrapper">+ <div class="hp-tabs-bar">+ <label for="hp-tab-extract">Extract</label>+ <label for="hp-tab-agent">Agent</label>+ <label for="hp-tab-pipeline">Pipeline</label>+ <label for="hp-tab-multimodal">Multimodal</label>+ <label for="hp-tab-optimize">Optimize</label>+ </div>++ <div class="hp-tab-panels">+ <!-- Extract -->+ <div class="hp-tab-panel" id="hp-panel-extract">+ <div class="hp-tab-code">+ <div class="line"><span class="tok-k">class</span> <span class="tok-t">Extract</span>(dspy.Signature):</div>+ <div class="line"> <span class="tok-s">"""Extract contact info."""</span></div>+ <div class="line"> message: <span class="tok-t">str</span> = dspy.<span class="tok-m">InputField</span>()</div>+ <div class="line"> name: <span class="tok-t">str</span> = dspy.<span class="tok-m">OutputField</span>()</div>+ <div class="line"> email: <span class="tok-t">Optional</span>[<span class="tok-t">str</span>] = dspy.<span class="tok-m">OutputField</span>()</div>+ <div class="line"> intent: <span class="tok-t">Literal</span>[</div>+ <div class="line"> <span class="tok-s">"meeting"</span>, <span class="tok-s">"intro"</span>, <span class="tok-s">"follow-up"</span></div>+ <div class="line"> ] = dspy.<span class="tok-m">OutputField</span>()</div>+ <div class="line"> </div>+ <div class="line">extract = dspy.<span class="tok-m">Predict</span>(Extract)</div>+ <div class="line">extract(message=<span class="tok-s">"I'm Sarah"</span></div>+ <div class="line"> <span class="tok-s">"([email protected]). Meet Thursday?"</span>)</div>+ </div>+ <div class="hp-tab-output">+ <div class="hp-tab-output-header"><span>output</span><span>stdout</span></div>+ <div class="line">Prediction(</div>+ <div class="line"> name=<span class="tok-s">"Sarah"</span>,</div>+ <div class="line"> email=<span class="tok-s">"[email protected]"</span>,</div>+ <div class="line"> intent=<span class="tok-s">"meeting"</span></div>+ <div class="line">)</div>+ </div>+ </div>- <div class="features-section">- <h2 class="features-title">The Way of DSPy</h2>- <div class="features-grid">- <div class="feature-card">- <img src="{{ 'static/img/optimize.png' | url }}" alt="Systematic Optimization" class="feature-image">- <h3 class="feature-title">Systematic Optimization</h3>- <p class="feature-description">Choose from a range of optimizers to enhance your program. Whether it's generating refined instructions, or fine-tuning weights, DSPy's optimizers are engineered to maximize efficiency and effectiveness.</p>- </div>-- <div class="feature-card">- <img src="{{ 'static/img/modular.png' | url }}" alt="Modular Approach" class="feature-image">- <h3 class="feature-title">Modular Approach</h3>- <p class="feature-description">With DSPy, you can build your system using predefined modules, replacing intricate prompting techniques with straightforward, effective solutions.</p>- </div>-- <div class="feature-card">- <img src="{{ 'static/img/universal_compatibility.png' | url }}" alt="Cross-LM Compatibility" class="feature-image">- <h3 class="feature-title">Cross-LM Compatibility</h3>- <p class="feature-description">Whether you're working with powerhouse models like GPT-3.5 or GPT-4, or local models such as T5-base or Llama2-13b, DSPy seamlessly integrates and enhances their performance in your system.</p>+ <!-- Agent -->+ <div class="hp-tab-panel" id="hp-panel-agent">+ <div class="hp-tab-code">+ <div class="line"><span class="tok-k">def</span> <span class="tok-m">search</span>(query: <span class="tok-t">str</span>) -> <span class="tok-t">list</span>[<span class="tok-t">str</span>]:</div>+ <div class="line"> <span class="tok-s">"""Search a knowledge base."""</span></div>+ <div class="line"> <span class="tok-k">return</span> kb.query(query, k=<span class="tok-num">3</span>)</div>+ <div class="line"> </div>+ <div class="line"><span class="tok-k">def</span> <span class="tok-m">calc</span>(expr: <span class="tok-t">str</span>) -> <span class="tok-t">float</span>:</div>+ <div class="line"> <span class="tok-s">"""Evaluate a math expression."""</span></div>+ <div class="line"> <span class="tok-k">return</span> dspy.<span class="tok-m">PythonInterpreter</span>({}).execute(expr)</div>+ <div class="line"> </div>+ <div class="line">agent = dspy.<span class="tok-m">ReAct</span>(</div>+ <div class="line"> <span class="tok-s">"question -> answer"</span>,</div>+ <div class="line"> tools=[search, calc])</div>+ <div class="line">agent(question=<span class="tok-s">"GDP per capita of France?"</span>)</div>+ </div>+ <div class="hp-tab-output">+ <div class="hp-tab-output-header"><span>output</span><span>stdout</span></div>+ <div class="line"><span class="tok-cm"># thought 1: I need France's GDP and population.</span></div>+ <div class="line"><span class="tok-cm"># action 1: search("France GDP") → ...</span></div>+ <div class="line"><span class="tok-cm"># thought 2: Now divide GDP by population.</span></div>+ <div class="line"><span class="tok-cm"># action 2: calc("3.13e12 / 68e6") → 46029.4</span></div>+ <div class="line">Prediction(answer=<span class="tok-s">"$46,029"</span>)</div>+ </div></div>++ <!-- Pipeline -->+ <div class="hp-tab-panel" id="hp-panel-pipeline">+ <div class="hp-tab-code">+ <div class="line"><span class="tok-k">class</span> <span class="tok-t">FactCheck</span>(dspy.Module):</div>+ <div class="line"> <span class="tok-k">def</span> <span class="tok-m">__init__</span>(self):</div>+ <div class="line"> self.find = dspy.<span class="tok-m">ChainOfThought</span>(</div>+ <div class="line"> <span class="tok-s">"article -> claims: list[str]"</span>)</div>+ <div class="line"> self.verify = dspy.<span class="tok-m">ChainOfThought</span>(</div>+ <div class="line"> <span class="tok-s">"claim, source -> verdict"</span>)</div>+ <div class="line"> </div>+ <div class="line"> <span class="tok-k">def</span> <span class="tok-m">forward</span>(self, article):</div>+ <div class="line"> found = self.find(article=article)</div>+ <div class="line"> <span class="tok-k">return</span> [</div>+ <div class="line"> self.verify(claim=c, source=article)</div>+ <div class="line"> <span class="tok-k">for</span> c <span class="tok-k">in</span> found.claims]</div>+ </div>+ <div class="hp-tab-output">+ <div class="hp-tab-output-header"><span>output</span><span>stdout</span></div>+ <div class="line"><span class="tok-cm"># >>> FactCheck()(article=news_article)</span></div>+ <div class="line">[Prediction(verdict=<span class="tok-s">"supported"</span>),</div>+ <div class="line"> Prediction(verdict=<span class="tok-s">"unsupported"</span>),</div>+ <div class="line"> Prediction(verdict=<span class="tok-s">"supported"</span>)]</div>+ </div>+ </div>++ <!-- Multimodal -->+ <div class="hp-tab-panel" id="hp-panel-multimodal">+ <div class="hp-tab-code">+ <div class="line"><span class="tok-k">class</span> <span class="tok-t">AnalyzeChart</span>(dspy.Signature):</div>+ <div class="line"> <span class="tok-s">"""Describe the trend and key data points in a chart."""</span></div>+ <div class="line"> chart: dspy.<span class="tok-t">Image</span> = dspy.<span class="tok-m">InputField</span>()</div>+ <div class="line"> title: <span class="tok-t">str</span> = dspy.<span class="tok-m">OutputField</span>()</div>+ <div class="line"> trend: <span class="tok-t">str</span> = dspy.<span class="tok-m">OutputField</span>()</div>+ <div class="line"> data_points: <span class="tok-t">list</span>[<span class="tok-t">dict</span>] = dspy.<span class="tok-m">OutputField</span>()</div>+ <div class="line"> </div>+ <div class="line">analyze = dspy.<span class="tok-m">Predict</span>(AnalyzeChart)</div>+ <div class="line">analyze(chart=dspy.<span class="tok-m">Image</span>(<span class="tok-s">"quarterly_revenue.png"</span>))</div>+ </div>+ <div class="hp-tab-output">+ <div class="hp-tab-output-header"><span>output</span><span>stdout</span></div>+ <div class="line">Prediction(</div>+ <div class="line"> title=<span class="tok-s">"Quarterly Revenue (2024)"</span>,</div>+ <div class="line"> trend=<span class="tok-s">"Steady growth, Q3 dip, strong Q4 recovery"</span>,</div>+ <div class="line"> data_points=[{<span class="tok-s">"q"</span>: <span class="tok-s">"Q1"</span>, <span class="tok-s">"rev"</span>: <span class="tok-s">"$4.2M"</span>}, ...]</div>+ <div class="line">)</div>+ </div>+ </div>++ <!-- Optimize -->+ <div class="hp-tab-panel" id="hp-panel-optimize">+ <div class="hp-tab-code">+ <div class="line">optimizer = dspy.<span class="tok-m">GEPA</span>(</div>+ <div class="line"> metric=accuracy, auto=<span class="tok-s">"medium"</span>)</div>+ <div class="line">optimized = optimizer.<span class="tok-m">compile</span>(</div>+ <div class="line"> extract, trainset=labeled_emails)</div>+ <div class="line"> </div>+ <div class="line">optimized.<span class="tok-m">save</span>(<span class="tok-s">"extract_v2.json"</span>)</div>+ </div>+ <div class="hp-tab-output">+ <div class="hp-tab-output-header"><span>output</span><span>stdout</span></div>+ <div class="line"><span class="tok-cm"># Baseline 62% (gpt-5.4-mini, zero-shot)</span></div>+ <div class="line"><span class="tok-cm"># Optimized 89% (gpt-5.4-mini + GEPA compile)</span></div>+ <div class="line"><span class="tok-cm"># Cost $2.18 · 200 examples</span></div>+ <div class="line"><span class="tok-cm"># Saved to → extract_v2.json</span></div>+ </div>+ </div>+ </div>++ <div class="hp-tab-footer">+ <span class="hp-tab-footer-caption">+ <span class="hp-tab-caption" data-tab="extract">Signatures define tasks and enforce output types</span>+ <span class="hp-tab-caption" data-tab="agent">Define tools as functions and pass them to a ReAct module</span>+ <span class="hp-tab-caption" data-tab="pipeline">Compose multiple Signatures into new modules with plain Python control flow</span>+ <span class="hp-tab-caption" data-tab="multimodal">Images are a Signature field types, enabling multimodal tasks</span>+ <span class="hp-tab-caption" data-tab="optimize">Optimizers improve your program against a defined metric</span>+ </span>+ <span>+ <a class="hp-tab-link" data-tab="extract" href="{{ 'getting-started/expanding-signatures/' | url }}">Learn more about Signatures →</a>+ <a class="hp-tab-link" data-tab="agent" href="{{ 'getting-started/react-and-tools/' | url }}">Learn how to add tools →</a>+ <a class="hp-tab-link" data-tab="pipeline" href="{{ 'getting-started/composing-modules/' | url }}">Learn how to compose modules →</a>+ <a class="hp-tab-link" data-tab="multimodal" href="{{ 'tutorials/image_generation_prompting/' | url }}">Learn how to build multimodal programs →</a>+ <a class="hp-tab-link" data-tab="optimize" href="{{ 'getting-started/gepa-optimization/' | url }}">Learn how to write metrics and optimize →</a>+ </span>+ </div></div>+ </div></div>+ </section>++ <!-- ===== ECOSYSTEM ===== -->+ <section class="hp-section hp-ecosystem">+ <div class="hp-container">+ <div class="hp-eco-grid">+ <div class="hp-eco-left">+ <h2 class="hp-eco-title">+ Built in the open, since <span class="hp-hl">Dec 2022</span>.+ </h2>+ <p class="hp-eco-desc">+ DSPy started at Stanford NLP and grew into a research community.+ New optimizers and module types land here first — then+ show up in production systems at companies you’ve heard of.+ </p>+ <div class="hp-papers">+ <div class="hp-paper-date">Dec 2025</div>+ <div class="hp-paper-title">Recursive Language Models</div>+ <div class="hp-paper-link"><a href="https://arxiv.org/abs/2512.24601">arxiv →</a></div>++ <div class="hp-paper-date">Jul 2025</div>+ <div class="hp-paper-title">GEPA: Reflective Prompt Evolution</div>+ <div class="hp-paper-link"><a href="https://arxiv.org/abs/2507.19457">arxiv →</a></div>++ <div class="hp-paper-date">Jul 2024</div>+ <div class="hp-paper-title">BetterTogether: Fine-Tuning + Prompt Opt.</div>+ <div class="hp-paper-link"><a href="https://arxiv.org/abs/2407.10930">arxiv →</a></div>++ <div class="hp-paper-date">Jun 2024</div>+ <div class="hp-paper-title">MIPROv2: Optimizing Instructions & Demos</div>+ <div class="hp-paper-link"><a href="https://arxiv.org/abs/2406.11695">arxiv →</a></div>++ <div class="hp-paper-date">Feb 2024</div>+ <div class="hp-paper-title">STORM: Writing Wikipedia-like Articles</div>+ <div class="hp-paper-link"><a href="https://arxiv.org/abs/2402.14207">arxiv →</a></div>++ <div class="hp-paper-date">Oct 2023</div>+ <div class="hp-paper-title">DSPy: Compiling Declarative LM Calls</div>+ <div class="hp-paper-link"><a href="https://arxiv.org/abs/2310.03714">arxiv →</a></div>++ <div class="hp-paper-date">Dec 2022</div>+ <div class="hp-paper-title">Demonstrate-Search-Predict</div>+ <div class="hp-paper-link"><a href="https://arxiv.org/abs/2212.14024">arxiv →</a></div>++ <div class="hp-papers-end"></div>+ </div>+ </div>++ <div class="hp-eco-right">+ <h3>DSPy in production</h3>+ <div class="hp-built-grid">+ <div class="hp-built-item">+ <div class="hp-built-item-header">+ <a href="https://www.youtube.com/watch?v=bxToahwOVpY" class="hp-built-name">Shopify</a>+ </div>+ <div class="hp-built-blurb">Metadata extraction across all shops; ~550× cost reduction</div>+ </div>+ <div class="hp-built-item">+ <div class="hp-built-item-header">+ <a href="https://dropbox.tech/machine-learning/optimizing-dropbox-dash-relevance-judge-with-dspy" class="hp-built-name">Dropbox</a>+ </div>+ <div class="hp-built-blurb">Optimized Dash relevance judge for ranking and evaluation</div>+ </div>+ <div class="hp-built-item">+ <div class="hp-built-item-header">+ <a href="https://aws.amazon.com/blogs/machine-learning/improve-amazon-nova-migration-performance-with-data-aware-prompt-optimization/" class="hp-built-name">AWS</a>+ </div>+ <div class="hp-built-blurb">Prompt migration from larger to smaller models on Amazon Nova</div>+ </div>+ <div class="hp-built-item">+ <div class="hp-built-item-header">+ <a href="https://www.databricks.com/blog/optimizing-databricks-llm-pipelines-dspy" class="hp-built-name">JetBlue</a>+ </div>+ <div class="hp-built-blurb">Multiple chatbot use cases on Databricks</div>+ </div>+ <div class="hp-built-item">+ <div class="hp-built-item-header">+ <a href="https://blog.replit.com/code-repair" class="hp-built-name">Replit</a>+ </div>+ <div class="hp-built-blurb">Code repair pipeline using code LLMs to synthesize diffs</div>+ </div>+ <div class="hp-built-item">+ <div class="hp-built-item-header">+ <a href="https://www.databricks.com/blog/dspy-databricks" class="hp-built-name">Databricks</a>+ </div>+ <div class="hp-built-blurb">LM judges, RAG, classification, and customer solutions</div>+ </div>+ <div class="hp-built-item">+ <div class="hp-built-item-header">+ <a href="https://github.com/NousResearch/hermes-agent-self-evolution" class="hp-built-name">Nous Research</a>+ </div>+ <div class="hp-built-blurb">Evolutionary self-improvement for the Hermes agent</div>+ </div>+ <div class="hp-built-item">+ <div class="hp-built-item-header">+ <a href="{{ 'community/use-cases/' | url }}" class="hp-built-name hp-built-more">More →</a>+ </div>+ <div class="hp-built-blurb">See all companies using DSPy in production</div>+ </div>+ </div>++ <div class="hp-community">+ <div class="hp-community-label">Community</div>+ <div class="hp-community-stats">+ <div>+ <div class="hp-community-stat-num">{{ config.extra.stats.contributors }}</div>+ <div class="hp-community-stat-label">contributors</div>+ </div>+ <div>+ <div class="hp-community-stat-num">{{ config.extra.stats.discord_members }}</div>+ <div class="hp-community-stat-label">discord members</div>+ </div>+ <div>+ <div class="hp-community-stat-num">{{ config.extra.stats.merged_prs_yr }}</div>+ <div class="hp-community-stat-label">merged PRs / yr</div>+ </div>+ <div>+ <div class="hp-community-stat-num">60+</div>+ <div class="hp-community-stat-label">tutorials & recipes</div>+ </div>+ </div>+ <div class="hp-community-links">+ <a href="https://github.com/stanfordnlp/dspy">GitHub →</a>+ <a href="https://discord.gg/XCGy2WDCQB">Discord →</a>+ </div>+ </div>+ </div>+ </div>+ </div>+ </section>+</div>-{% endblock %}\ No newline at end of file+{% endblock %}diff --git a/docs/overrides/main.html b/docs/overrides/main.htmlindex ae6bb982b..fcd4ca2dd 100644--- a/docs/overrides/main.html+++ b/docs/overrides/main.html@@ -1,42 +1,67 @@{% extends "base.html" %}{% block announce %}- <strong>DSPy.LM API migration:</strong>- We are planning the typed <code>BaseLM</code> transition for DSPy 3.3–3.6/4.0.- <a href="{{ 'community/normalized-lm-api-migration/' | url }}">Review the plan and share feedback.</a>+ <strong>DSPy.LM improvements:</strong>+ we've added a typed <code>BaseLM</code> that will become the default interface.+ <a href="{{ 'community/normalized-lm-api-migration/' | url }}">Read the plan and share feedback</a>{% endblock %}{% block extrahead %}<style>- [data-md-color-scheme="default"] .md-banner {- background: #eef5ff;- border-bottom: 1px solid #c9ddff;- color: #1f2937;+ /* Announcement banner — restyled to fit the home-page aesthetic:+ quiet warm band, single rust accent, thin rule. Sans text; mono only for code.+ Spacing uses padding (not margin) so no top margin collapses out and exposes+ a white stripe above the band. */+ .md-banner {+ display: flex;+ align-items: center;+ min-height: 38px;+ }+ .md-banner__inner {+ margin: 0 auto;+ padding-top: 0.25rem;+ padding-bottom: 0.25rem;+ font-size: 13px;+ line-height: 1.55;+ }+ .md-banner strong { font-weight: 600; }+ .md-banner code {+ font-family: 'Fira Mono', ui-monospace, monospace;+ padding: 1px 5px;+ border-radius: 3px;+ font-size: 0.92em;}- [data-md-color-scheme="default"] .md-banner a {- color: #2457c5;+ .md-banner a {font-weight: 600;- text-decoration: underline;- text-underline-offset: 0.12em;+ text-decoration: none;+ border-bottom: 1px solid transparent;+ transition: border-color 0.15s;}++ [data-md-color-scheme="default"] .md-banner {+ background: #f3f7fc;+ border-bottom: 1px solid var(--md-default-fg-color--lightest);+ color: var(--md-default-fg-color--light);+ }+ [data-md-color-scheme="default"] .md-banner strong { color: #4870aa; }+ [data-md-color-scheme="default"] .md-banner a { color: #4870aa; }+ [data-md-color-scheme="default"] .md-banner a:hover { border-bottom-color: #4870aa; }[data-md-color-scheme="default"] .md-banner code {- background: rgba(36, 87, 197, 0.1);- color: #1e3a8a;+ background: rgba(52, 95, 158, 0.09);+ color: #2c4f86;}+[data-md-color-scheme="slate"] .md-banner {- background: #0f2747;- border-bottom: 1px solid #24496f;- color: #eef6ff;- }- [data-md-color-scheme="slate"] .md-banner a {- color: #9dccff;- font-weight: 600;- text-decoration: underline;- text-underline-offset: 0.12em;+ background: #151e2b;+ border-bottom: 1px solid var(--md-default-fg-color--lightest);+ color: var(--md-default-fg-color--light);}+ [data-md-color-scheme="slate"] .md-banner strong { color: #87aad8; }+ [data-md-color-scheme="slate"] .md-banner a { color: #87aad8; }+ [data-md-color-scheme="slate"] .md-banner a:hover { border-bottom-color: #87aad8; }[data-md-color-scheme="slate"] .md-banner code {- background: rgba(157, 204, 255, 0.14);- color: #d6ebff;+ background: rgba(143, 184, 236, 0.14);+ color: #a9c8f0;}</style><script async src="https://www.googletagmanager.com/gtag/js?id=G-G728W2L8KQ"></script>diff --git a/docs/vercel.json b/docs/vercel.jsonindex 9e4754e93..9cad5af98 100644--- a/docs/vercel.json+++ b/docs/vercel.json@@ -1,4 +1,8 @@{+ "framework": null,+ "installCommand": "uv venv && uv pip install -r requirements.txt",+ "buildCommand": ".venv/bin/mkdocs build",+ "outputDirectory": "site","trailingSlash": true,"headers": [{