# What happens internally:
candidates = ["output_1", "output_2", "output_3"]
scores = [metric(item, c) for c in candidates]  # [0.7, 0.9, 0.6]
best_idx = argmax(scores)  # 1
final_output = candidates[best_idx]  # "output_2"
```

The trace metadata includes:

* `n_requested`: Number of completions requested
* `candidates_scored`: Number of candidates evaluated
* `candidate_scores`: List of all scores (best\_by\_metric only)
* `candidate_logprobs`: List of logprob scores (max\_logprob only)
* `chosen_index`: Index of the selected candidate

## Cost Considerations

<Warning>
  Using `n > 1` increases API costs proportionally. With `n=3`, you pay roughly 3x the completion tokens per evaluation call.
</Warning>

| n value | Relative cost | Variance reduction |
| ------- | ------------- | ------------------ |
| 1       | 1x            | Baseline           |
| 3       | \~3x          | Significant        |
| 5       | \~5x          | High               |
| 10      | \~10x         | Very high          |

**Recommendations:**

* Start with `n=3` for most use cases
* Use `n=5-10` only for high-variance tasks
* Consider the total optimization budget when choosing N

## Limitations

<AccordionGroup>
  <Accordion title="Tool-calling forces n=1">
    When `allow_tool_use=True` and tools are defined, the optimizer forces `n=1`. This is because tool-calling requires maintaining a coherent message thread, which isn't compatible with multiple independent completions.

    ```python
    # Tool-calling prompt - n will be forced to 1
    prompt = ChatPrompt(
        model="gpt-4o-mini",
        messages=[...],
        tools=[...],
        model_parameters={"n": 3},  # Ignored when tools are used
    )
    ```
  </Accordion>

  <Accordion title="Some optimizers ignore n">
    Prompt synthesis steps that expect a single structured response (such as few-shot and parameter optimizers) ignore `n` to avoid returning multiple conflicting templates.
  </Accordion>

  <Accordion title="Not all providers support n">
    Some LLM providers don't support the `n` parameter. Check your provider's documentation. LiteLLM will drop unsupported parameters automatically.
  </Accordion>
</AccordionGroup>

## Full Example

```python
from opik_optimizer import ChatPrompt, MetaPromptOptimizer
from opik.evaluation.metrics import LevenshteinRatio