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

Behaviour for fitness evaluation functions.

Fitness functions determine how well an entity performs
against the optimization criteria.

# `context`

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

# `entity`

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

# `eval_result`

```elixir
@type eval_result() :: {:ok, score()} | {:ok, score_map()} | {:error, term()}
```

# `metadata`

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

# `score`

```elixir
@type score() :: float()
```

# `score_map`

```elixir
@type score_map() :: %{:score => score(), optional(:metadata) => metadata()}
```

# `batch_evaluate`
*optional* 

```elixir
@callback batch_evaluate([entity()], context()) ::
  {:ok, [{entity(), score()}]} | {:error, term()}
```

Batch evaluate multiple entities for efficiency.

Default implementation calls evaluate/2 for each entity.
Override for performance when batch evaluation is available.

# `compare`
*optional* 

```elixir
@callback compare(entity(), entity(), context()) :: :better | :worse | :equal
```

Compare two entities directly without computing scores.

This can be more efficient than scoring both entities
when only relative fitness matters.

# `evaluate`

```elixir
@callback evaluate(entity(), context()) :: eval_result()
```

Evaluate a single entity's fitness.

Returns either a simple score or a score with metadata.
Higher scores indicate better fitness.

## Examples

    def evaluate(text, _context) do
      similarity = String.jaro_distance(text, @target)
      {:ok, similarity}
    end

    def evaluate(text, _context) do
      score = String.jaro_distance(text, @target)
      {:ok, %{score: score, metadata: %{length: String.length(text)}}}
    end

# `batch_evaluate`

```elixir
@spec batch_evaluate(module(), [entity()], context()) :: {:ok, [{entity(), score()}]}
```

Shared batch evaluation implementation.

Evaluates multiple entities using the provided module's evaluate/2 callback.

# `score_or_raise!`

```elixir
@spec score_or_raise!(eval_result()) :: score()
```

Extract score from evaluate/2 result, raising on invalid format.

Handles both simple scores and score maps with optional metadata.

---

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