# `Puck.Eval.Trajectory`
[🔗](https://github.com/bradleygolden/puck/blob/v0.2.25/lib/puck/eval/trajectory.ex#L82)

Captures what happened during an agent execution.

A trajectory is a sequence of `Puck.Eval.Step` structs representing each
LLM call made during the execution of an agent. Use `Puck.Eval.Collector.collect/1`
to automatically capture trajectories via telemetry.

## Fields

  * `:steps` - List of `Puck.Eval.Step` structs in execution order
  * `:total_steps` - Count of steps
  * `:total_tokens` - Sum of all tokens used
  * `:total_duration_ms` - Total time for all LLM calls

## Example

    # Capture trajectory automatically
    {output, trajectory} = Puck.Eval.Collector.collect(fn ->
      MyAgent.run("Find John's email")
    end)

    trajectory.total_steps   # => 2
    trajectory.total_tokens  # => 385

    # Inspect individual steps
    Enum.each(trajectory.steps, fn step ->
      IO.puts("Action: #{inspect(step.output)}")
    end)

# `t`

```elixir
@type t() :: %Puck.Eval.Trajectory{
  steps: [Puck.Eval.Step.t()],
  total_duration_ms: non_neg_integer(),
  total_steps: non_neg_integer(),
  total_tokens: non_neg_integer()
}
```

# `add_step`

Adds a step to the trajectory.

Returns a new trajectory with the step appended and totals recalculated.

# `empty`

Returns an empty trajectory.

# `first_step`

Returns the first step in the trajectory, or nil if empty.

# `last_step`

Returns the last step in the trajectory, or nil if empty.

# `new`

Creates a new Trajectory from a list of steps.

Automatically calculates `total_steps`, `total_tokens`, and `total_duration_ms`
from the provided steps.

## Example

    steps = [
      Step.new(input: "Hello", output: "Hi", tokens: %{total: 10}, duration_ms: 100),
      Step.new(input: "Bye", output: "Goodbye", tokens: %{total: 15}, duration_ms: 80)
    ]

    trajectory = Trajectory.new(steps)
    trajectory.total_steps      # => 2
    trajectory.total_tokens     # => 25
    trajectory.total_duration_ms # => 180

# `outputs`

Returns all outputs from the trajectory steps.

---

*Consult [api-reference.md](api-reference.md) for complete listing*