# `GEPA.LLM`
[🔗](https://github.com/nshkrdotcom/gepa_ex/blob/v0.3.0/lib/gepa/llm.ex#L1)

Behavior and facade for Language Model integrations.

GEPA optimizers talk to LLMs through this normalized facade rather than
provider-specific code. The facade accepts plain text prompts and
OpenAI-compatible chat/multimodal message lists; adapters can decide how much
of that surface they support.

# `completion_opts`

```elixir
@type completion_opts() :: keyword()
```

# `prompt`

```elixir
@type prompt() :: String.t() | [map()]
```

# `structured_result`

```elixir
@type structured_result() :: {:ok, map()} | {:error, term()}
```

# `t`

```elixir
@type t() :: module() | map() | GEPA.LLM.Client.t() | function()
```

# `complete`

```elixir
@callback complete(llm :: t(), prompt :: prompt(), opts :: completion_opts()) ::
  {:ok, String.t()} | {:error, term()}
```

# `complete_structured`
*optional* 

```elixir
@callback complete_structured(llm :: t(), prompt :: prompt(), opts :: completion_opts()) ::
  structured_result()
```

# `agent`

```elixir
@spec agent(
  atom(),
  keyword()
) :: GEPA.LLM.Client.t()
```

Builds a local CLI/agent client backed by Agent Session Manager.

# `complete`

```elixir
@spec complete(t(), prompt(), completion_opts()) ::
  {:ok, String.t()} | {:error, term()}
```

Convenience function to call complete/3 on any LLM implementation.

# `complete_structured`

```elixir
@spec complete_structured(t(), prompt(), completion_opts()) :: structured_result()
```

Completes a prompt and returns a structured map.

# `default`

```elixir
@spec default() :: t()
```

Returns the default LLM provider based on application configuration.

# `new`

```elixir
@spec new(
  :req_llm | :agent_session_manager | :asm,
  keyword()
) :: GEPA.LLM.Client.t()
```

Builds a normalized GEPA LLM client.

# `req_llm`

```elixir
@spec req_llm(
  atom(),
  keyword()
) :: GEPA.LLM.Client.t()
```

Builds a hosted-provider client backed by ReqLLM.

# `stream`

```elixir
@spec stream(t(), prompt(), completion_opts()) ::
  {:ok, Enumerable.t()} | {:error, term()}
```

Streams a prompt when the selected normalized client supports streaming.

# `track`

```elixir
@spec track(function() | t()) :: GEPA.LLM.Tracking.t() | t()
```

Wrap a one- or two-arity callable in a cost/token tracking LLM.

---

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