# `Agentic.Loop.Stage`

Behaviour for loop pipeline stages.

Each stage receives a context and a `next` function representing the rest of
the pipeline. Stages can:

- **Pass through**: call `next.(context)` to continue the pipeline
- **Short-circuit**: return `{:done, result}` to stop the pipeline
- **Transform**: modify context before calling `next`
- **Loop**: call `next` multiple times (e.g. ModeRouter)

Stages optionally declare a `model_tier/0` if they need an LLM model.

# `context`

```elixir
@type context() :: map()
```

# `next`

```elixir
@type next() :: (context() -> result())
```

# `result`

```elixir
@type result() :: {:ok, context()} | {:done, map()} | {:error, term()}
```

# `call`

```elixir
@callback call(context(), next()) :: result()
```

Execute this stage. Call `next.(context)` to continue the pipeline.

# `model_tier`
*optional* 

```elixir
@callback model_tier() :: atom() | nil
```

The model tier this stage needs (e.g. :primary, :lightweight, :image, :vision).
Return `nil` if no model is needed.

---

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