# `Tinkex.Types.RegularizerSpec`
[🔗](https://github.com/North-Shore-AI/tinkex/blob/v0.4.0/lib/tinkex/types/regularizer_spec.ex#L1)

Specification for a single regularizer in the composition pipeline.

## Fields

- `:fn` - The regularizer function. Must accept `(data, logprobs)` and
  return `{loss_tensor, metrics_map}`. For async regularizers, should
  return a `Task.t()` that resolves to the same tuple.

- `:weight` - Non-negative float multiplier for the regularizer loss.
  The contribution to total loss is `weight * regularizer_loss`.

- `:name` - String identifier for telemetry and metrics. Must be unique
  within a regularizer list.

- `:async` - Boolean flag indicating whether `fn` returns a Task (default: false).
  When true, the executor will `Task.await/2` the result.

## Examples

    # Synchronous regularizer
    %RegularizerSpec{
      fn: fn _data, logprobs ->
        {Nx.sum(Nx.abs(logprobs)), %{"l1" => 1.0}}
      end,
      weight: 0.01,
      name: "l1_sparsity"
    }

    # Async regularizer (I/O-bound)
    %RegularizerSpec{
      fn: fn data, _logprobs ->
        Task.async(fn ->
          result = external_api_call(data)
          {Nx.tensor(result.penalty), %{"validated" => true}}
        end)
      end,
      weight: 0.1,
      name: "external_validation",
      async: true
    }

# `async_regularizer_fn`

```elixir
@type async_regularizer_fn() :: ([Tinkex.Types.Datum.t()], Nx.Tensor.t() -> Task.t())
```

# `regularizer_fn`

```elixir
@type regularizer_fn() :: ([Tinkex.Types.Datum.t()], Nx.Tensor.t() ->
                       regularizer_result())
```

# `regularizer_result`

```elixir
@type regularizer_result() :: {Nx.Tensor.t(), %{required(String.t()) => number()}}
```

# `t`

```elixir
@type t() :: %Tinkex.Types.RegularizerSpec{
  async: boolean(),
  fn: regularizer_fn() | async_regularizer_fn(),
  name: String.t(),
  weight: number()
}
```

# `new`

```elixir
@spec new(map() | keyword()) :: t()
```

Create a new RegularizerSpec with validation.

## Examples

    RegularizerSpec.new(%{
      fn: &my_regularizer/2,
      weight: 0.01,
      name: "l1"
    })

    RegularizerSpec.new(fn: &my_reg/2, weight: 0.5, name: "entropy")

# `validate!`

```elixir
@spec validate!(map()) :: :ok
```

Validate regularizer spec attributes.

Raises `ArgumentError` if any validation fails.

## Validations

- `:fn` must be a function of arity 2
- `:weight` must be a non-negative number
- `:name` must be a non-empty string
- `:async` must be a boolean (if provided)

---

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