dspy.Prediction¶

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)

@classmethod
def from_completions(cls, list_or_dict, signature=None):
    obj = cls()
    obj._completions = Completions(list_or_dict, signature=signature)
    obj._store = {k: v[0] for k, v in obj._completions.items()}

    return obj

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 get_lm_usage(self):
    return self._lm_usage

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.")

    # return items that are in input_keys
    d = {key: self._store[key] for key in self._store if key in self._input_keys}
    # return type(self)(d)
    new_instance = type(self)(base=d)
    new_instance._input_keys = self._input_keys  # Preserve input_keys in new instance
    return new_instance

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 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 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}
    return type(self)(d)

def set_lm_usage(self, value):
    self._lm_usage = value

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()
        elif isinstance(value, BaseModel):
            # Handle Pydantic models (e.g., dspy.History)
            return value.model_dump()
        elif isinstance(value, list):
            return [convert_to_serializable(item) for item in value]
        elif isinstance(value, dict):
            return {k: convert_to_serializable(v) for k, v in value.items()}
        else:
            return value

    serializable_store = {}
    for k, v in self._store.items():
        serializable_store[k] = convert_to_serializable(v)

    return serializable_store

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 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 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