# `ReqAI.Provider`
[🔗](https://github.com/benjreinhart/req_ai/blob/v0.0.1-rc.3/lib/req_ai/provider.ex#L1)

Defines the adapter contract and represents a configured AI provider.

Providers build the `Req.Request` used to execute provider-native request
data. An optional `ReqAI.Translator` can translate application values at the
provider boundary.

## Custom providers

Implement `c:build/3` to support generation. For example, an application-owned
JSON endpoint can use the same calling convention as the built-in providers:

    defmodule MyApp.Provider do
      @behaviour ReqAI.Provider

      @impl true
      def build(req, request, _opts) do
        Req.merge(req,
          method: :post,
          url: "https://llm.example.com/generate",
          json: request
        )
      end
    end

    ReqAI.generate(MyApp.Provider, %{prompt: "Say hello"})

To support streaming, also implement `c:decode_event/3` and use `opts[:stream]`
in `c:build/3` to select the endpoint's streaming mode. The decoder returns a
list of events; returning `[]` drops an event. Req handles transport framing
such as SSE, while the provider decodes the native payload.

# `t`

```elixir
@type t() :: %ReqAI.Provider{
  module: module(),
  opts: keyword(),
  req: Req.Request.t(),
  telemetry: module() | false,
  telemetry_metadata: map(),
  translator: module() | nil
}
```

# `build`

```elixir
@callback build(req :: Req.Request.t(), request :: map() | keyword(), opts :: keyword()) ::
  Req.Request.t()
```

Builds the HTTP request for a provider-native request body.

# `decode_event`
*optional* 

```elixir
@callback decode_event(event :: term(), response :: Req.Response.t(), opts :: keyword()) ::
  [term()]
```

Decodes a raw stream event produced by Req (an SSE event map, an NDJSON
line, ...) into zero or more application events.

This callback is optional. Providers must implement it to support `ReqAI.stream/4`.

# `new`

```elixir
@spec new(module :: module(), opts :: keyword()) :: t()
```

Creates a configured provider using `module` as its adapter.

If no additional options are needed, pass the module directly to
`ReqAI.generate/2` or `ReqAI.stream/4`. Create and reuse a provider
explicitly to retain its configuration or supply extension options.

`module` must implement the `ReqAI.Provider` behaviour.

The `:req` option contains options passed to `Req.new/2`. These are
merged with any `:req` options configured for the adapter under
`config :req_ai, :providers`, with explicit options taking precedence.
Configuration is read when the provider is created. Only `:req` is read from
application configuration; extension options must be passed here directly.
After extracting `:req`, `:translator`, `:telemetry`, and
`:telemetry_metadata`, remaining options are stored on the provider and
passed to `c:build/3` and the configured translator callbacks for each request.

Built-in adapters take body parameters, including `:model`, from the request
passed to `ReqAI.generate/2` or `ReqAI.stream/4`. They do not merge provider
options into that body. Configure authentication through `:req`, using Req's
`:auth` or `:headers` options as appropriate for the provider.

The optional `:translator` must implement the `ReqAI.Translator` behaviour.

The `:telemetry` option selects a module implementing any of the optional
`ReqAI.Telemetry` callbacks and defaults to the provider module. Set it to
`false` to disable telemetry emission. The `:telemetry_metadata` option
accepts a map that is passed to the telemetry callbacks.

---

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