GEPA.LLM behaviour (GEPA v0.3.0)

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.

Summary

Types

completion_opts()

prompt()

structured_result()

t()

Callbacks

complete(llm, prompt, opts)

complete_structured(llm, prompt, opts)

Functions

agent(provider, opts \\ [])

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

complete(llm, prompt, opts \\ [])

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

complete_structured(llm, prompt, opts \\ [])

Completes a prompt and returns a structured map.

default()

Returns the default LLM provider based on application configuration.

new(adapter, opts)

Builds a normalized GEPA LLM client.

req_llm(provider, opts \\ [])

Builds a hosted-provider client backed by ReqLLM.

stream(client, prompt, opts \\ [])

Streams a prompt when the selected normalized client supports streaming.

track(tracking)

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

Types

completion_opts()

@type completion_opts() :: keyword()

prompt()

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

structured_result()

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

t()

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

Callbacks

complete(llm, prompt, opts)

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

complete_structured(llm, prompt, opts)

(optional)

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

Functions

agent(provider, opts \\ [])

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

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

complete(llm, prompt, opts \\ [])

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

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

complete_structured(llm, prompt, opts \\ [])

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

Completes a prompt and returns a structured map.

default()

@spec default() :: t()

Returns the default LLM provider based on application configuration.

new(adapter, opts)

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

Builds a normalized GEPA LLM client.

req_llm(provider, opts \\ [])

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

Builds a hosted-provider client backed by ReqLLM.

stream(client, prompt, opts \\ [])

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

Streams a prompt when the selected normalized client supports streaming.

track(tracking)

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

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