# `Dsxir.Metric`

Metric contract used by `Dsxir.Evaluate` and the `Dsxir.Optimizer` family.

A metric is any 3-arity function:

    (Dsxir.Example.t(), Dsxir.Prediction.t(), trace :: nil | list()) ->
      number() | boolean()

The arity is fixed across v0+. The trace argument is `nil` outside
`Dsxir.with_trace/1` (populated by `Dsxir.with_trace/1` when that helper
lands); metrics that ignore it accept the positional argument and discard it.

`apply/4` is the only sanctioned way to invoke a metric. It coerces booleans
to floats and raises `Dsxir.Errors.Invalid.Metric` on any other return value
so callers never branch on the metric's return shape.

# `t`

```elixir
@type t() :: (Dsxir.Example.t(), Dsxir.Prediction.t(), nil | list() ->
          number() | boolean())
```

# `apply`

```elixir
@spec apply(t(), Dsxir.Example.t(), Dsxir.Prediction.t(), nil | list()) :: float()
```

Invoke `metric` and coerce its return into a `float()`. Booleans become
`1.0`/`0.0`; integers and floats pass through. Any other return raises
`Dsxir.Errors.Invalid.Metric`.

---

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