org.llm4s.llmconnect.model

A response from the LLM, optionally containing text, tool-call requests, or both.

content always returns a non-null String; it returns "" when the LLM response contains only tool calls and no accompanying text (contentOpt is None). Code that displays assistant output should check for an empty string rather than null-guarding.

A well-formed AssistantMessage must satisfy at least one of:

contentOpt.exists(_.trim.nonEmpty) — the LLM produced text.
toolCalls.nonEmpty — the LLM requested one or more tool invocations.

Value parameters

contentOpt: Text portion of the response; None when the model produced only tool calls.
toolCalls: Tool invocations requested by the model; each carries an id that must be matched by a subsequent ToolMessage.

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

trait Message

class Object

trait Matchable

class Any
Show all

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: AssistantMessage.type

Audio content (e.g. WAV, MP3), processed via local audio encoders.

Attributes

Supertypes: trait Singleton

trait Product

trait Mirror

trait Serializable

trait Product

trait Equals

trait Modality

class Object

trait Matchable

class Any
Show all
Self type: Audio.type

Audio as mono float32 PCM with sample rate.

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

trait MMInput

class Object

trait Matchable

class Any
Show all

Delta information for streaming chunks

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: ChunkDelta.type

Represents a completion response from an LLM. This includes the ID, creation timestamp, the assistant's message, and optional token usage statistics.

Value parameters

content: The main content of the response.
created: Timestamp of when the completion was created.
estimatedCost: Optional estimated cost of this completion in USD. Computed from token usage and model pricing when available.
id: Unique identifier for the completion.
message: The assistant's message in response to the user's input.
model: The model that generated this completion.
thinking: Optional thinking/reasoning content from extended thinking models. Present when using reasoning modes with Claude or o1/o3 models.
toolCalls: List of tool calls made by the assistant.
usage: Optional token usage statistics for the completion.

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Represents a streaming chunk of completion data

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Represents options for a completion request.

Value parameters

budgetTokens: Optional explicit budget for thinking tokens (Anthropic Claude). If set, overrides the default budget from reasoning effort level.
frequencyPenalty: Penalizes new tokens based on their existing frequency in the text so far, discouraging repetition.
maxTokens: Optional maximum number of tokens to generate in the completion.
presencePenalty: Penalizes new tokens based on whether they appear in the text so far, encouraging new topics.
reasoning: Optional reasoning effort level for models that support extended thinking (o1/o3, Claude). For non-reasoning models, this setting is silently ignored.
responseFormat: Optional structured output format (e.g. JSON or JSON schema). Support is provider- and model-dependent; see capability validation in RequestTransformer.
temperature: Controls the randomness of the output. Higher values make the output more random. Note: Reasoning models (o1/o3) ignore this setting.
tools: Optional sequence of tool function definitions that can be requested by the LLM during a completion.
topP: Controls the diversity of the output. Lower values make the output more focused.

Attributes

Example

import org.llm4s.llmconnect.model._
// Enable high reasoning for complex tasks
val options = CompletionOptions()
 .withReasoning(ReasoningEffort.High)
 .copy(maxTokens = Some(4096))
// For Anthropic, set explicit thinking budget
val anthropicOptions = CompletionOptions()
 .withBudgetTokens(16000)
// Request JSON output (provider-dependent)
val jsonOptions = CompletionOptions().withResponseFormat(ResponseFormat.Json)

Supertypes

trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any

Show all

Represents the message stream in a conversation. Typically this will be a sequence of system prompt, then a series of user message and assistant responses. After the system message we have a user message. The next message is the assistant response. If the conversation is ongoing, the next message will be a user message, or if the previous AssistantMessage requested one or more tool calls it will be followed by ToolMessages in response to each requested tool.

Value parameters

messages: Sequence of messages in the conversation.

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: Conversation.type

EmbeddingError represents a structured error returned from an embedding provider (e.g., OpenAI or VoyageAI) or local encoders/extractors.

Value parameters

code: Optional error code, typically an HTTP status (e.g., "401", "400").
message: Human-readable error message from the provider or client.
provider: Source component ("openai", "voyage", "encoder", "extractor", etc.)

Attributes

Supertypes: trait LLMError

trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Text-only embedding request used by HTTP providers (OpenAI/Voyage).

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Successful response carrying embedding vectors and lightweight metadata.

Value parameters

dim

Optional dimensionality, if convenient to surface at response-level.

embeddings

One vector per input text/chunk (or per item).

metadata

Provider/model info etc. (e.g., "provider" -> "openai", "model" -> "...").

modality

Optional overall modality tag (Text, Audio, Video) when known.

usage

Optional token usage statistics (available from providers like OpenAI). Notes:

Defaults on metadata, modality, dim, and usage keep old call-sites source-compatible.
Providers can set modality/dim/usage when they know it; callers can ignore safely.

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: EmbeddingResponse.type

Token usage statistics for an embedding request.

Value parameters

promptTokens: Number of tokens in the input text(s).
totalTokens: Total tokens used (same as promptTokens for embeddings).

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

ExtractorError represents failures during file/media extraction.

Value parameters

message: Human-readable explanation of the failure.
path: Optional path to the problematic file for debugging.
type: Coarse category (e.g., "FileNotFound", "UnsupportedType", "PDF", "DOCX", "PlainText", "ImageReadError", "AudioUnsupported", "AudioError", "VideoUnsupported").

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Image content (e.g. PNG, JPEG), processed via local image encoders.

Attributes

Supertypes: trait Singleton

trait Product

trait Mirror

trait Serializable

trait Product

trait Equals

trait Modality

class Object

trait Matchable

class Any
Show all
Self type: Image.type

Image as raw bytes (e.g., RGB or BGR interleaved) with basic shape metadata.

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

trait MMInput

class Object

trait Matchable

class Any
Show all

Typed payloads for multimedia inputs. Keep lightweight, encode-friendly.

Attributes

Supertypes: class Object

trait Matchable

class Any
Known subtypes: class AudioInput

class ImageInput

class RawMediaInput

class TextChunkInput

class VideoInput

A single turn in an LLM conversation.

Conversations are sequences of Message values passed to org.llm4s.llmconnect.LLMClient. Each concrete subtype corresponds to one participant role: UserMessage, SystemMessage, AssistantMessage, ToolMessage.

content is always a non-null, non-empty string for well-formed messages — use validate or the smart constructors on the Message companion to ensure this invariant. AssistantMessage.content returns "" rather than null when the LLM response contains only tool calls and no text.

Attributes

Companion: object
Supertypes: class Object

trait Matchable

class Any
Known subtypes: class AssistantMessage

class SystemMessage

class ToolMessage

class UserMessage

Companion object providing smart constructors and conversation-level validation.

The smart constructors (system, user, assistant, tool) return Left(ValidationError) on blank content so callers get typed errors instead of runtime exceptions. Prefer these over the case-class constructors in application code; use case-class constructors directly only in tests or when content is guaranteed non-blank.

Attributes

Companion: trait
Supertypes: trait Sum

trait Mirror

class Object

trait Matchable

class Any
Self type: Message.type

Identifies the participant that authored a Message.

Maps directly to the role field in provider API payloads. The string representation returned by toString is the lowercase name forwarded verbatim to the provider (e.g. "user", "assistant").

Attributes

Companion: object
Supertypes: class Object

trait Matchable

class Any
Known subtypes: object Assistant

object System

object Tool

object User

Attributes

Companion: trait
Supertypes: trait Sum

trait Mirror

class Object

trait Matchable

class Any
Self type: MessageRole.type

Represents the type of content that can be embedded or processed.

Used by the embedding and extraction subsystems to select the appropriate encoder or extractor for a given piece of content. Each modality maps to a distinct processing pipeline (e.g. text embedding via an API provider, image embedding via a local CLIP model).

Attributes

Supertypes: class Object

trait Matchable

class Any
Known subtypes: object Audio

object Image

object Text

object Video

Multimedia request (co-located in the same file to avoid new source files). Used by local encoders/facades (e.g., UniversalEncoder). Not sent to HTTP providers.

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Raw, unparsed bytes representing the media object. Provided for generic multimodal HTTP providers.

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

trait MMInput

class Object

trait Matchable

class Any
Show all

Represents the level of reasoning effort to request from the LLM.

Different providers implement reasoning in different ways:

OpenAI o1/o3 models: Uses reasoning_effort parameter
Anthropic Claude: Uses extended thinking with budget_tokens

For non-reasoning models, this setting is silently ignored.

Attributes

Example

import org.llm4s.llmconnect.model._
// Use high reasoning for complex tasks
val options = CompletionOptions().withReasoning(ReasoningEffort.High)
// Parse from string
val effort = ReasoningEffort.fromString("medium")

Companion

object

Supertypes

class Object

trait Matchable

class Any

Known subtypes

object High

object Low

object Medium

object None

Attributes

Companion: trait
Supertypes: trait Sum

trait Mirror

class Object

trait Matchable

class Any
Self type: ReasoningEffort.type

Requested format for LLM completion output (structured output).

When set in CompletionOptions.responseFormat, the provider is asked to return output in the specified format. Support is provider- and model-dependent; see CompletionOptions ScalaDoc for capability validation and fallback behavior.

'''Json''': Generic JSON object mode; the model is instructed to return valid JSON.
'''JsonSchema(schema)''': Provider-specific JSON schema; the model's output is constrained to match the given schema where supported.

Attributes

Companion: object
Supertypes: class Object

trait Matchable

class Any
Known subtypes: object Json

class JsonSchema

Attributes

Companion: trait
Supertypes: trait Sum

trait Mirror

class Object

trait Matchable

class Any
Self type: ResponseFormat.type

Maps ResponseFormat to provider-specific request payloads.

Used internally by provider clients; no provider names leak in the public API.

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: ResponseFormatMapper.type

Represents a streamed chunk of completion data.

Value parameters

content: Optional text content delta.
finishReason: Optional reason for stream completion.
id: Unique identifier for the stream.
thinkingDelta: Optional thinking/reasoning content delta. Present when streaming extended thinking content.
toolCall: Optional tool call information.

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Represents a system message, which is typically used to set context or instructions for the LLM.

A system prompt provides the foundational instructions and behavioral guidelines that shape how the LLM should respond to a user request, including its personality, capabilities, constraints, and communication style. It acts as the model's "operating manual," establishing context about what it should and shouldn't do, how to handle various scenarios, and what information it has access to.

Value parameters

content: Content of the system message.

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

trait Message

class Object

trait Matchable

class Any
Show all

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: SystemMessage.type

Plain text content, the primary modality for LLM embedding providers.

Attributes

Supertypes: trait Singleton

trait Product

trait Mirror

trait Serializable

trait Product

trait Equals

trait Modality

class Object

trait Matchable

class Any
Show all
Self type: Text.type

Text as pre-chunked strings (optional helper for local text paths).

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

trait MMInput

class Object

trait Matchable

class Any
Show all

Token usage statistics for a completion request.

Value parameters

cacheCreationTokens: Optional number of tokens written into the provider's prompt cache. When present, these tokens are billed at the cache-creation rate, which is typically higher than the normal input rate.
cachedTokens: Optional number of tokens served from the provider's prompt cache (cache read). When present, these tokens are billed at the cheaper cache-read rate.
completionTokens: Number of tokens in the completion (output).
promptTokens: Number of tokens in the prompt (input).
thinkingTokens: Optional number of tokens used for thinking/reasoning. Present when using reasoning modes with Claude or o1/o3 models. These tokens count toward billing but are separate from completion tokens.
totalTokens: Total tokens (prompt + completion).

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

A single tool invocation requested by the LLM.

The LLM generates id to correlate this request with its ToolMessage response; the agent framework forwards id unchanged when constructing ToolMessage values, so do not modify it.

arguments is a parsed ujson.Value (typically a JSON object), not a raw string. Use arguments.obj to access fields or pass it directly to org.llm4s.toolapi.ToolRegistry.execute via a org.llm4s.toolapi.ToolCallRequest.

Value parameters

arguments: Parsed JSON arguments; the schema is defined by the tool's org.llm4s.toolapi.Schema.
id: Provider-generated identifier; matched by the corresponding ToolMessage.toolCallId.
name: Name of the tool to invoke; must match a registered org.llm4s.toolapi.ToolFunction.

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: ToolCall.type

Represents a message from a tool, typically containing the result of a tool call.

Value parameters

content: Content of the tool message, usually the result of the tool execution, e.g. a json response.
toolCallId: Unique identifier for the tool call (as provided by the ToolCall).

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

trait Message

class Object

trait Matchable

class Any
Show all

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: ToolMessage.type

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: TraceHelper.type

Represents a user message in the conversation.

Value parameters

content: Content of the user message.

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

trait Message

class Object

trait Matchable

class Any
Show all

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: UserMessage.type

Video content (e.g. MP4), processed via local video encoders.

Attributes

Supertypes: trait Singleton

trait Product

trait Mirror

trait Serializable

trait Product

trait Equals

trait Modality

class Object

trait Matchable

class Any
Show all
Self type: Video.type

Video as a sequence of RGB frames (byte arrays), plus basic shape & fps.

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

trait MMInput

class Object

trait Matchable

class Any
Show all

org.llm4s.llmconnect.model

Members list

Type members

Classlikes

Value parameters

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Value parameters

Attributes

Attributes

Value parameters

Attributes

Value parameters

Attributes

Attributes

Value parameters

Attributes

Attributes

Value parameters

Attributes

Attributes

Value parameters

Attributes

Attributes

Value parameters

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Value parameters

Attributes

Value parameters

Attributes

Attributes

Attributes

Attributes

Value parameters

Attributes

Value parameters

Attributes

Attributes

Value parameters

Attributes

Attributes

Attributes

Value parameters

Attributes

Attributes

Attributes

Attributes