# `Aludel.Interfaces.LLM.Behaviour`
[🔗](https://github.com/ccarvalho-eng/aludel/blob/main/lib/aludel/interfaces/llm/behaviour.ex#L1)

Behaviour for LLM provider implementations.

Each provider must implement `generate/4` to handle text generation
with provider-specific logic (authentication, configuration, etc.).

# `error_reason`

```elixir
@type error_reason() ::
  :missing_api_key
  | {:auth_error, String.t()}
  | {:rate_limit, non_neg_integer() | nil}
  | {:invalid_request, String.t()}
  | {:api_error, non_neg_integer(), String.t()}
  | {:network_error, term()}
```

# `response`

```elixir
@type response() :: %{
  content: String.t(),
  input_tokens: non_neg_integer(),
  output_tokens: non_neg_integer()
}
```

# `generate`

```elixir
@callback generate(
  model :: String.t(),
  prompt :: String.t(),
  config :: map(),
  opts :: keyword()
) :: {:ok, response()} | {:error, error_reason()}
```

Generates text using the LLM provider.

## Parameters
  - model: Model identifier (e.g., "gpt-4o", "claude-3-5-sonnet")
  - prompt: Text prompt to send to the model
  - config: Provider configuration (API keys, temperature, etc.)
  - opts: Additional options (e.g., documents for vision models)

## Returns
  - `{:ok, response}` with content and token usage
  - `{:error, reason}` if generation fails

---

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