Skip to content

armgit / dspy

Public Imported from GitHub
0

DSPy: The framework for programming—not prompting—language models

Python

Improve dspy.Example docstrings and examples (#9444)

Maxime Rivestb7d573b8224b
diff --git a/dspy/primitives/example.py b/dspy/primitives/example.py
index e4d8e10be..40eb1c18d 100644
--- a/dspy/primitives/example.py
+++ b/dspy/primitives/example.py
@@ -2,91 +2,106 @@ from pydantic import BaseModel
class Example:
- """A flexible data container for DSPy examples and training data.
+ """A flexible data container for DSPy examples and training data with named fields.
- The `Example` class is the standard data format used in DSPy evaluation and optimization.
+ An `Example` is roughly one row from a HuggingFace dataset or pandas
+ `DataFrame`. It behaves a lot like a dictionary or dot-access record: you
+ can read fields with `example["question"]` or `example.question`.
- Key features:
- - Dictionary-like access patterns (item access, iteration, etc.)
- - Flexible initialization from dictionaries, other `Example` instances, or keyword arguments
- - Input/output field separation for training data
- - Serialization support for saving/loading `Example` instances
- - Immutable operations that return new `Example` instances
+ In DSPy, lists of `Example` objects are your trainset, devset, and testset.
+ Most examples are built from keyword arguments or an existing record, then
+ tagged with `with_inputs(...)` to say which fields should be fed into a
+ module. The remaining fields are labels or metadata.
- Examples:
-
- Basic usage with keyword arguments:
-
- ```python
- import dspy
-
- # Create an example with input and output fields
- example = dspy.Example(
- question="What is the capital of France?",
- answer="Paris",
- )
- print(example.question) # "What is the capital of France?"
- print(example.answer) # "Paris"
- ```
-
- Initialize from a dictionary:
-
- ```python
- data = {"question": "What is 2+2?", "answer": "4"}
- example = dspy.Example(data)
- print(example["question"]) # "What is 2+2?"
- ```
-
- Copy from another Example:
-
- ```python
- original = dspy.Example(question="Hello", answer="World")
- copy = dspy.Example(original)
- print(copy.question) # "Hello"
- ```
-
- Working with input/output separation:
-
- ```python
- # Mark which fields are inputs for training
- example = dspy.Example(
- question="What is the weather?",
- answer="It's sunny",
- ).with_inputs("question")
-
- # Get only input fields
- inputs = example.inputs()
- print(inputs.question) # "What is the weather?"
-
- # Get only output fields (labels)
- labels = example.labels()
- print(labels.answer) # "It's sunny"
- ```
-
- Dictionary-like operations:
-
- ```python
- example = dspy.Example(name="Alice", age=30)
+ When you write evaluation code, custom optimizers, or training loops, use
+ `example.inputs()` for the fields you want to pass to a module, and use
+ `example.labels()` for the fields you want to compare against the module's
+ output.
- # Check if key exists
- if "name" in example:
- print("Name field exists")
-
- # Get with default value
- city = example.get("city", "Unknown")
- print(city) # "Unknown"
- ```
+ Examples:
+ Build one from keyword arguments:
+
+ >>> import dspy
+ >>> example = dspy.Example(
+ ... question="What is the capital of France?",
+ ... answer="Paris",
+ ... ).with_inputs("question")
+ >>> example.question
+ 'What is the capital of France?'
+ >>> example.answer
+ 'Paris'
+ >>> example.inputs().toDict()
+ {'question': 'What is the capital of France?'}
+
+ Build one from an existing record:
+
+ >>> record = {"question": "What is 2+2?", "answer": "4"}
+ >>> example = dspy.Example(**record).with_inputs("question")
+ >>> example["question"]
+ 'What is 2+2?'
+ >>> example.labels().answer
+ '4'
+
+ Mark which fields are inputs:
+
+ >>> example = dspy.Example(
+ ... question="What is the weather?",
+ ... answer="It's sunny",
+ ... ).with_inputs("question")
+ >>> example.inputs().question
+ 'What is the weather?'
+ >>> example.labels().answer
+ "It's sunny"
+
+ Use examples in a trainset:
+
+ >>> trainset = [
+ ... dspy.Example(question="What is 2+2?", answer="4").with_inputs("question"),
+ ... dspy.Example(question="What is 3+3?", answer="6").with_inputs("question"),
+ ... ]
+ >>> trainset[0].inputs().toDict()
+ {'question': 'What is 2+2?'}
+
+ Use an example in a metric:
+
+ >>> def exact_match_metric(example, pred, trace=None):
+ ... return example.answer.lower() == pred.answer.lower()
+ >>> gold = dspy.Example(question="What is 1+1?", answer="2").with_inputs("question")
+ >>> pred = dspy.Prediction(answer="2")
+ >>> exact_match_metric(gold, pred)
+ True
+
+ Use it like a dictionary:
+
+ >>> example = dspy.Example(name="Alice", age=30).with_inputs("name")
+ >>> "name" in example
+ True
+ >>> example.get("city", "Unknown")
+ 'Unknown'
+
+ See Also:
+ [`dspy.Evaluate`][dspy.Evaluate]: Evaluate a program on a list of
+ `Example`s.
+ [`Metrics`](../../learn/evaluation/metrics.md): Write metric functions
+ that compare an `Example` with a prediction.
"""
+ # TODO: Add a `dspy.datasets.DataLoader` API link once the datasets API
+ # pages exist.
def __init__(self, base=None, **kwargs):
- """Initialize an Example instance.
+ """Create an `Example` from fields or from an existing record.
+
+ In the common case, pass fields as keyword arguments, like
+ `dspy.Example(question="...", answer="...")`. Use `base` when you
+ already have a dictionary or another `Example` and want to copy its
+ fields before adding or overriding a few values.
Args:
- base: Optional base data source. Can be:
- - Another Example instance (copies its data)
- - A dictionary (copies its key-value pairs)
- - None (creates empty Example)
- **kwargs: Additional key-value pairs to store in the Example.
+ base: A dictionary or `Example` to copy fields from before applying
+ `**kwargs`. When `None`, starts with no fields.
+ **kwargs: Field names and values to store on the example. If a field
+ appears in both `base` and `**kwargs`, the value from
+ `**kwargs` wins.
"""
# Internal storage and other attributes
self._store = {}
@@ -147,23 +162,104 @@ class Example:
return hash(tuple(self._store.items()))
def keys(self, include_dspy=False):
+ """Return field names, like `dict.keys()`.
+
+ Args:
+ include_dspy: If `True`, include internal fields prefixed
+ with `dspy_`. Normally you can ignore these.
+
+ Examples:
+ >>> import dspy
+ >>> dspy.Example(question="Why?", answer="Because.").keys()
+ ['question', 'answer']
+ """
return [k for k in self._store.keys() if not k.startswith("dspy_") or include_dspy]
def values(self, include_dspy=False):
+ """Return field values, like `dict.values()`.
+
+ Args:
+ include_dspy: If `True`, include internal fields prefixed
+ with `dspy_`.
+
+ Examples:
+ >>> import dspy
+ >>> dspy.Example(question="Why?", answer="Because.").values()
+ ['Why?', 'Because.']
+ """
return [v for k, v in self._store.items() if not k.startswith("dspy_") or include_dspy]
def items(self, include_dspy=False):
+ """Return `(field_name, value)` pairs, like `dict.items()`.
+
+ Args:
+ include_dspy: If `True`, include internal fields prefixed
+ with `dspy_`.
+
+ Examples:
+ >>> import dspy
+ >>> dspy.Example(question="Why?", answer="Because.").items()
+ [('question', 'Why?'), ('answer', 'Because.')]
+ """
return [(k, v) for k, v in self._store.items() if not k.startswith("dspy_") or include_dspy]
def get(self, key, default=None):
+ """Return the value for `key`, or `default` if the field doesn't exist.
+
+ Args:
+ key: Field name to look up.
+ default: Value to return when `key` is missing.
+
+ Examples:
+ >>> import dspy
+ >>> ex = dspy.Example(name="Alice")
+ >>> ex.get("name")
+ 'Alice'
+ >>> ex.get("city", "Unknown")
+ 'Unknown'
+ """
return self._store.get(key, default)
def with_inputs(self, *keys):
+ """Mark which fields are inputs and return a new `Example`.
+
+ Fields not listed here are treated as labels (expected outputs).
+ DSPy optimizers and evaluators use this split: they pass
+ `example.inputs()` to your program and compare the output against
+ `example.labels()`.
+
+ Args:
+ *keys: Names of the input fields.
+
+ Returns:
+ A copy of this `Example` with the input keys set.
+
+ Examples:
+ >>> import dspy
+ >>> ex = dspy.Example(question="Why?", answer="Because.").with_inputs("question")
+ >>> ex.inputs().keys()
+ ['question']
+ >>> ex.labels().keys()
+ ['answer']
+ """
copied = self.copy()
copied._input_keys = set(keys)
return copied
def inputs(self):
+ """Return a new `Example` containing only the input fields.
+
+ Requires `with_inputs` to have been called first.
+
+ Raises:
+ ValueError: If `with_inputs` was not called on this example.
+
+ Examples:
+ >>> import dspy
+ >>> ex = dspy.Example(question="Why?", answer="Because.").with_inputs("question")
+ >>> ex.inputs()
+ Example({'question': 'Why?'}) (input_keys={'question'})
+ """
if self._input_keys is None:
raise ValueError("Inputs have not been set for this example. Use `example.with_inputs()` to set them.")
@@ -175,6 +271,17 @@ class Example:
return new_instance
def labels(self):
+ """Return a new `Example` containing only the label (non-input) fields.
+
+ Requires `with_inputs` to have been called first, since labels are
+ everything that is *not* an input.
+
+ Examples:
+ >>> import dspy
+ >>> ex = dspy.Example(question="Why?", answer="Because.").with_inputs("question")
+ >>> ex.labels()
+ Example({'answer': 'Because.'}) (input_keys=None)
+ """
# return items that are NOT in input_keys
input_keys = self.inputs().keys()
d = {key: self._store[key] for key in self._store if key not in input_keys}
@@ -184,15 +291,47 @@ class Example:
return iter(dict(self._store))
def copy(self, **kwargs):
+ """Return a shallow copy, optionally overriding fields.
+
+ Args:
+ **kwargs: Fields to add or override in the copy.
+
+ Examples:
+ >>> import dspy
+ >>> ex = dspy.Example(question="Why?", answer="Because.")
+ >>> ex.copy(answer="No reason.")
+ Example({'question': 'Why?', 'answer': 'No reason.'}) (input_keys=None)
+ """
return type(self)(base=self, **kwargs)
def without(self, *keys):
+ """Return a copy with the specified fields removed.
+
+ Args:
+ *keys: Field names to drop.
+
+ Examples:
+ >>> import dspy
+ >>> ex = dspy.Example(question="Why?", answer="Because.", source="web")
+ >>> ex.without("source")
+ Example({'question': 'Why?', 'answer': 'Because.'}) (input_keys=None)
+ """
copied = self.copy()
for key in keys:
del copied[key]
return copied
def toDict(self): # noqa: N802
+ """Convert to a plain dictionary, recursively serializing nested objects.
+
+ Nested `Example` objects, Pydantic models, lists, and dicts are
+ converted so the result is JSON-friendly.
+
+ Examples:
+ >>> import dspy
+ >>> dspy.Example(question="Why?", answer="Because.").toDict()
+ {'question': 'Why?', 'answer': 'Because.'}
+ """
def convert_to_serializable(value):
if hasattr(value, "toDict"):
return value.toDict()