Agentic.LLM (agentic v0.2.2)

Copy Markdown

Top-level entry point for chat and embedding calls.

Wraps Agentic.LLM.Provider with two conveniences:

Both flavours route through the configured provider stack and return canonical %Response{} / {:ok, vectors, model_id} shapes.

Embed return shape

embed/2 and embed_tier/3 always return a list of vectors, even when called with a single string input. The third tuple element is the model id used to produce the vectors so callers (e.g. recollect's reembed pipeline) can store provenance.

{:ok, [vector, ...], "text-embedding-3-small"} | {:error, %Error{}}

Summary

Types

embed_result()

Functions

chat(params, opts \\ [])

Chat completion via a provider module + canonical params.

chat_tier(params, tier, opts \\ [])

Chat completion via tier resolution with full failover.

embed(text_or_list, opts \\ [])

Generate embeddings for one or more strings via an explicit provider.

embed_tier(text_or_list, tier \\ :embeddings, opts \\ [])

Generate embeddings via tier-based model resolution.

Types

embed_result()

@type embed_result() ::
  {:ok, [[float()]], String.t()} | {:error, Agentic.LLM.Error.t()}

Functions

chat(params, opts \\ [])

Chat completion via a provider module + canonical params.

chat_tier(params, tier, opts \\ [])

Chat completion via tier resolution with full failover.

Resolves every healthy route in tier from the ModelRouter and walks them in priority order with error classification and health reporting. Accepts an optional llm_chat callback (same shape as the loop callback) for callers that want to customise dispatch (e.g. host app credential injection). Falls back to direct provider dispatch when no callback is provided. Returns {:ok, %Response{}} or {:error, %Error{}}.

Options

  • :llm_chat — (map() -> {:ok, response} | {:error, term()}) callback. When provided, each route is injected as params["_route"] and the callback is invoked. Otherwise direct Provider.chat/3 is used.

embed(text_or_list, opts \\ [])

@spec embed(
  String.t() | [String.t()],
  keyword()
) :: embed_result()

Generate embeddings for one or more strings via an explicit provider.

Required opts:

  • :provider — provider id atom (e.g. :openai)
  • :model — model id string (e.g. "text-embedding-3-small")

embed_tier(text_or_list, tier \\ :embeddings, opts \\ [])

@spec embed_tier(String.t() | [String.t()], atom(), keyword()) :: embed_result()

Generate embeddings via tier-based model resolution.

Tier resolution order:

  1. Explicit opts[:model] + opts[:provider] (skips Catalog)
  2. Catalog.find(has: :embeddings, tier: tier) → first match
  3. Fallback to first model with the :embeddings capability