# `ExAthena.Provider`
[🔗](https://github.com/udin-io/ex_athena/blob/v0.7.1/lib/ex_athena/provider.ex#L1)

Behaviour every provider must implement.

A provider is a thin adapter between `ExAthena.Request` and a remote (or
local) inference endpoint. It is expected to:

  1. Normalise the request into the provider's native wire format.
  2. Perform the HTTP call (or SDK call, for Claude).
  3. Parse the response (or stream) back into an `ExAthena.Response` /
     `ExAthena.Streaming.Event` sequence.
  4. Surface errors as `{:error, %ExAthena.Error{}}` tuples using the
     canonical kinds.

## Capabilities

Each provider declares its capabilities statically. The loop uses these to
decide the tool-call protocol and fallback strategy. See
`ExAthena.Capabilities` for the shape.

# `capabilities`

```elixir
@callback capabilities() :: ExAthena.Capabilities.t()
```

Static capability map for this provider.

# `query`

```elixir
@callback query(ExAthena.Request.t(), opts :: keyword()) ::
  {:ok, ExAthena.Response.t()} | {:error, term()}
```

Perform a one-shot request and return the final response.

# `stream`
*optional* 

```elixir
@callback stream(
  ExAthena.Request.t(),
  (ExAthena.Streaming.Event.t() -> term()),
  opts :: keyword()
) ::
  {:ok, ExAthena.Response.t()} | {:error, term()}
```

Stream a request; `callback` is invoked with each `Streaming.Event`. Must
still return `{:ok, final_response}` when the stream completes normally.

---

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