AttractorEx.LLM.Client (attractor_phoenix v0.1.0)

Provider-agnostic LLM client used by codergen nodes and agent sessions.

The client resolves providers, applies middleware, delegates to adapter modules, and supports both request/response and streaming flows.

Beyond the low-level complete/2 and stream/2 APIs, the module also exposes:

from_env/1 for runtime construction from application config
module-level default-client helpers
spec-aligned convenience wrappers such as generate/2
stream accumulation helpers for callers that want a final normalized response
JSON object generation helpers layered on top of the normalized response surface

Summary

Types

middleware()

t()

Functions

accumulate_stream(request)

Consumes a raw event stream and returns a normalized final response.

accumulate_stream(client, request)

Consumes a raw event stream and returns a normalized final response.

accumulate_stream_with_request(client, request)

Consumes a raw event stream and returns the accumulated response plus resolved request.

clear_default()

Clears the module-level default client.

complete(request)

Executes a completion request via the configured module-level default client.

complete(client, request)

Executes a completion request and returns either a response or an error tuple.

complete_with_request(client, request)

Executes a completion request and also returns the resolved request.

default()

Returns the configured module-level default client, or nil.

from_env(opts \\ [])

Builds a client from application config, with direct opts taking precedence.

generate(request)

Spec-style completion alias for complete/2.

generate(client, request)

Spec-style completion alias for complete/2.

generate_object(request)

Generates a JSON object via the configured module-level default client.

generate_object(client, request)

Generates a JSON object from a non-streaming response.

generate_object_with_request(client, request)

Generates a JSON object from a non-streaming response and also returns transport data.

generate_with_request(client, request)

Spec-style completion alias for complete_with_request/2.

new(opts \\ [])

Builds a client from keyword options.

put_default(client)

Stores a module-level default client used by the arity-1 helpers.

stream(request)

Executes a streaming request via the configured module-level default client.

stream(client, request)

Executes a streaming request and returns the event stream or an error tuple.

stream_object(request)

Generates a JSON object from a streamed response via the default client.

stream_object(client, request)

Generates a JSON object by first accumulating a streamed response.

stream_object_deltas(request)

Streams normalized events with inserted :object_delta JSON events.

stream_object_deltas(client, request)

Streams normalized events with inserted :object_delta JSON events.

stream_object_deltas_with_request(client, request)

Streams normalized events with inserted :object_delta JSON events and returns the resolved request.

stream_object_with_request(client, request)

Generates a JSON object by first accumulating a streamed response and also returns the normalized response plus resolved request.

stream_with_request(client, request)

Executes a streaming request and also returns the resolved request.

Types

middleware()

@type middleware() ::
  (AttractorEx.LLM.Request.t(), (AttractorEx.LLM.Request.t() -> any()) -> any())

t()

@type t() :: %AttractorEx.LLM.Client{
  default_provider: String.t() | nil,
  middleware: [middleware()],
  providers: %{optional(String.t()) => module()},
  retry_policy: AttractorEx.LLM.RetryPolicy.t() | nil,
  streaming_middleware: [middleware()]
}

Functions

accumulate_stream(request)

@spec accumulate_stream(AttractorEx.LLM.Request.t()) ::
  AttractorEx.LLM.Response.t() | {:error, term()}

Consumes a raw event stream and returns a normalized final response.

This is useful for callers that want provider streaming for latency but still need a single accumulated AttractorEx.LLM.Response.

accumulate_stream(client, request)

@spec accumulate_stream(t(), AttractorEx.LLM.Request.t()) ::
  AttractorEx.LLM.Response.t() | {:error, term()}

Consumes a raw event stream and returns a normalized final response.

accumulate_stream_with_request(client, request)

@spec accumulate_stream_with_request(t(), AttractorEx.LLM.Request.t()) ::
  {:ok, AttractorEx.LLM.Response.t(), AttractorEx.LLM.Request.t()}
  | {:error, term()}

Consumes a raw event stream and returns the accumulated response plus resolved request.

clear_default()

@spec clear_default() :: :ok

Clears the module-level default client.

complete(request)

@spec complete(AttractorEx.LLM.Request.t()) ::
  AttractorEx.LLM.Response.t() | {:error, term()}

Executes a completion request via the configured module-level default client.

complete(client, request)

Executes a completion request and returns either a response or an error tuple.

complete_with_request(client, request)

Executes a completion request and also returns the resolved request.

default()

@spec default() :: t() | nil

Returns the configured module-level default client, or nil.

from_env(opts \\ [])

@spec from_env(keyword()) :: t()

Builds a client from application config, with direct opts taking precedence.

Supported config shape:

config :attractor_phoenix, :attractor_ex_llm,
  providers: %{"openai" => MyApp.OpenAIAdapter},
  default_provider: "openai"

generate(request)

@spec generate(AttractorEx.LLM.Request.t()) ::
  AttractorEx.LLM.Response.t() | {:error, term()}

Spec-style completion alias for complete/2.

generate(client, request)

@spec generate(t(), AttractorEx.LLM.Request.t()) ::
  AttractorEx.LLM.Response.t() | {:error, term()}

Spec-style completion alias for complete/2.

generate_object(request)

@spec generate_object(AttractorEx.LLM.Request.t()) ::
  {:ok, map() | list()} | {:error, term()}

Generates a JSON object via the configured module-level default client.

generate_object(client, request)

@spec generate_object(t(), AttractorEx.LLM.Request.t()) ::
  {:ok, map() | list()} | {:error, term()}

Generates a JSON object from a non-streaming response.

The response body is decoded from response.text.

generate_object_with_request(client, request)

@spec generate_object_with_request(t(), AttractorEx.LLM.Request.t()) ::
  {:ok, map() | list(), AttractorEx.LLM.Response.t(),
   AttractorEx.LLM.Request.t()}
  | {:error, term()}

Generates a JSON object from a non-streaming response and also returns transport data.

generate_with_request(client, request)

@spec generate_with_request(t(), AttractorEx.LLM.Request.t()) ::
  {:ok, AttractorEx.LLM.Response.t(), AttractorEx.LLM.Request.t()}
  | {:error, term()}

Spec-style completion alias for complete_with_request/2.

new(opts \\ [])

@spec new(keyword()) :: t()

Builds a client from keyword options.

put_default(client)

@spec put_default(t()) :: t()

Stores a module-level default client used by the arity-1 helpers.

stream(request)

@spec stream(AttractorEx.LLM.Request.t()) :: Enumerable.t() | {:error, term()}

Executes a streaming request via the configured module-level default client.

stream(client, request)

Executes a streaming request and returns the event stream or an error tuple.

stream_object(request)

@spec stream_object(AttractorEx.LLM.Request.t()) ::
  {:ok, map() | list()} | {:error, term()}

Generates a JSON object from a streamed response via the default client.

stream_object(client, request)

@spec stream_object(t(), AttractorEx.LLM.Request.t()) ::
  {:ok, map() | list()} | {:error, term()}

Generates a JSON object by first accumulating a streamed response.

stream_object_deltas(request)

@spec stream_object_deltas(AttractorEx.LLM.Request.t()) ::
  Enumerable.t() | {:error, term()}

Streams normalized events with inserted :object_delta JSON events.

stream_object_deltas(client, request)

@spec stream_object_deltas(t(), AttractorEx.LLM.Request.t()) ::
  Enumerable.t() | {:error, term()}

Streams normalized events with inserted :object_delta JSON events.

stream_object_deltas_with_request(client, request)

@spec stream_object_deltas_with_request(t(), AttractorEx.LLM.Request.t()) ::
  {:ok, Enumerable.t(), AttractorEx.LLM.Request.t()} | {:error, term()}

Streams normalized events with inserted :object_delta JSON events and returns the resolved request.

stream_object_with_request(client, request)

@spec stream_object_with_request(t(), AttractorEx.LLM.Request.t()) ::
  {:ok, map() | list(), AttractorEx.LLM.Response.t(),
   AttractorEx.LLM.Request.t()}
  | {:error, term()}

Generates a JSON object by first accumulating a streamed response and also returns the normalized response plus resolved request.

stream_with_request(client, request)

Executes a streaming request and also returns the resolved request.