Imp.Prediction (Imp v0.5.0)

Structured output from an Imp program.

Predictions carry the named output fields produced by a program plus optional completions, score, and metadata. Program modules use fields for task answers, metrics use score or score-like fields when normalizing results, and traces live under metadata so debugging information stays separate from task output.

Like Imp.Example, a key keeps the type it was given and no string is turned into an atom; every function that takes a key compares keys by their text.

Example

iex> prediction =
...>   Imp.Prediction.new(%{"answer" => "Paris", "external_field" => 42},
...>     score: 1.0,
...>     metadata: %{trace: %{provider: :local}}
...>   )
iex> Imp.Prediction.get(prediction, :answer)
"Paris"
iex> Imp.Prediction.get(prediction, "external_field")
42
iex> {prediction.score, prediction.metadata.trace.provider}
{1.0, :local}

Summary

Types

t()

Functions

complete?(prediction)

Whether the program that made this prediction ended with its outputs.

fetch!(prediction, key)

Reads a prediction field or raises KeyError when it is missing.

from_example(example, opts \\ [])

Converts an example into a prediction, preserving fields and applying prediction options.

get(prediction, key, default \\ nil)

Reads a prediction field, returning default when it is missing.

get_lm_usage(prediction)

Returns the LM usage ledger for this prediction.

new(fields \\ %{}, opts \\ [])

Builds a prediction from fields and optional completions, score, and metadata.

put(prediction, key, value)

Returns a copy of the prediction with one field set.

to_map(prediction)

Returns the prediction field map.

Types

t()

@type t() :: %Imp.Prediction{
  completions: list(),
  fields: map(),
  metadata: map(),
  score: number() | nil
}

Functions

complete?(prediction)

@spec complete?(t()) :: boolean()

Whether the program that made this prediction ended with its outputs.

An Imp.Predict.ReActV2 turn that was interrupted and could not answer says so with termination_reason: :incomplete in the prediction's metadata, and its fields hold no outputs. Every other prediction is complete.

iex> Imp.Prediction.complete?(Imp.Prediction.new(%{answer: "Paris"}))
true
iex> Imp.Prediction.complete?(
...>   Imp.Prediction.new(%{}, metadata: %{termination_reason: :incomplete})
...> )
false

fetch!(prediction, key)

Reads a prediction field or raises KeyError when it is missing.

from_example(example, opts \\ [])

Converts an example into a prediction, preserving fields and applying prediction options.

get(prediction, key, default \\ nil)

Reads a prediction field, returning default when it is missing.

get_lm_usage(prediction)

Returns the LM usage ledger for this prediction.

Ports DSPy's Prediction.get_lm_usage(): a map of model key (for example "openai/gpt-4o-mini") to merged usage counters, populated when the :track_usage setting is true during the program call. Returns an empty map when usage was not tracked.

new(fields \\ %{}, opts \\ [])

Builds a prediction from fields and optional completions, score, and metadata.

fields may be a map or field pair list. Keys stay the atoms or strings they were given.

put(prediction, key, value)

Returns a copy of the prediction with one field set.

to_map(prediction)

Returns the prediction field map.