# `Jido.Evolve.Mutation`
[🔗](https://github.com/agentjido/jido_evolve/blob/v1.0.0/lib/jido_evolve/mutation.ex#L1)

Behaviour for mutation strategies.

Mutation introduces variation into the population by
modifying entities in various ways.

# `entity`

```elixir
@type entity() :: term()
```

# `feedback`

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

# `opts`

```elixir
@type opts() :: keyword()
```

# `mutate`

```elixir
@callback mutate(entity(), opts()) :: {:ok, entity()} | {:error, term()}
```

Mutate an entity.

The mutation should introduce variation while preserving
the general structure of the entity.

## Options

- `:rate` - Mutation rate (0.0 to 1.0), defaults to 0.1
- `:strength` - Mutation strength (0.0 to 1.0), defaults to 0.5

## Examples

    def mutate(entity, opts) do
      rate = Keyword.get(opts, :rate, 0.1)
      # Apply mutations based on rate
      {:ok, mutated_entity}
    end

# `mutate_with_feedback`
*optional* 

```elixir
@callback mutate_with_feedback(entity(), feedback(), opts()) ::
  {:ok, entity()} | {:error, term()}
```

Mutate an entity with feedback from previous evaluations.

This allows for more intelligent mutations that take into
account what has worked well in the past.

# `mutation_strength`
*optional* 

```elixir
@callback mutation_strength(integer()) :: float()
```

Calculate mutation strength based on generation number.

This allows for adaptive mutation rates that change over time,
typically starting high for exploration and decreasing for exploitation.

---

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