# `Mnemosyne.Pipeline.Episode`
[🔗](https://github.com/edlontech/mnemosyne/blob/main/lib/mnemosyne/pipeline/episode.ex#L1)

Functional core for managing in-progress episodes.

An episode tracks a sequence of observation-action steps organized
into trajectories. Trajectory boundaries are detected when subgoal
embedding similarity drops below a threshold.

# `step`

```elixir
@type step() :: %{
  index: non_neg_integer(),
  observation: String.t(),
  action: String.t(),
  subgoal: String.t(),
  state: String.t() | nil,
  reward: float() | nil,
  embedding: [float()] | nil,
  trajectory_id: String.t()
}
```

A single observation-action step within an episode

# `t`

```elixir
@type t() :: %Mnemosyne.Pipeline.Episode{
  closed: boolean(),
  current_subgoal_embedding: [float()] | nil,
  current_trajectory_id: String.t(),
  goal: String.t(),
  id: String.t(),
  steps: [step()],
  trajectories: [trajectory()]
}
```

# `trajectory`

```elixir
@type trajectory() :: %{id: String.t(), steps: [step()], subgoal: String.t()}
```

A completed trajectory segment

# `append`

```elixir
@spec append(t(), String.t(), String.t(), keyword()) ::
  {:ok, t(), Mnemosyne.Notifier.Trace.Episode.t()}
  | {:error, Mnemosyne.Errors.error()}
```

Appends an observation-action step, inferring subgoal, reward, and state via LLM.

# `build_trajectory_from_steps`

```elixir
@spec build_trajectory_from_steps([step()]) :: trajectory()
```

Builds a trajectory struct from a list of steps sharing the same trajectory_id.

# `close`

```elixir
@spec close(t()) :: {:ok, t()} | {:error, Mnemosyne.Errors.Invalid.EpisodeError.t()}
```

Closes the episode, grouping steps into trajectory segments.

# `new`

```elixir
@spec new(String.t()) :: t()
```

Creates a new open episode targeting the given goal.

# `score_pending_reward`

```elixir
@spec score_pending_reward(
  t(),
  keyword()
) :: {:ok, t()} | {:error, Mnemosyne.Errors.Invalid.EpisodeError.t()}
```

Scores the reward for the last step using a sentinel next-observation. Call before close.

---

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