org.llm4s.llmconnect.model

@Stable

A response from the LLM, optionally containing text, tool-call requests, or both, and the reasoning the model produced before them.

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.

Thinking alone does not make a message well-formed.

Construct one with the companion apply and change it with the with* setters.

'''Sealed thinking.''' A signed ThinkingBlock.Text, a ThinkingBlock.Redacted or a ThinkingBlock.Opaque block is valid only in the conversation the provider produced it in. Anthropic signs a thinking block over everything sent before it - the system prompt, the tools and every earlier message - and rejects it once any of those changes; Bedrock documents its reasoning signature as a hash of all the messages in the conversation. Both also reject a block sent beside content or tool calls other than the ones it came with. Two rules keep llm4s from sending a signed turn that no longer holds:

'''Its own message.''' withContent and withToolCalls, given a value different from the current one, '''unseal''' the thinking: they drop redacted and opaque blocks, the signatures of text blocks and the binding, keeping the reasoning text.
'''Everything before it.''' The client that receives sealed thinking records, in thinkingBinding, a fingerprint of the request it answered and of who answered it: the provider and model, the system messages, the tools, the response format and every earlier message. When the message is sent again, the client replays its sealed thinking only if it is calling that provider and model and the conversation before it still has that fingerprint, and sends it unsealed otherwise - so a signature is never sent to a provider or model that did not produce it. So pruning, compression, summarisation, an edit or an insertion anywhere earlier in the history - by any code, through any API - unseals every later turn, without the code that made the change having to know about thinking.

Unsealed thinking keeps its text, which Anthropic and Bedrock leave out of the request and the other providers still receive. Earlier turns whose history is unchanged keep their sealed thinking, as Anthropic recommends: the blocks it accepts back are an unbroken run of the original sequence, and these rules never leave a gap, because unsealing one turn changes the history of every later one. To keep signed thinking, leave the message and everything before it as they are; to replace it deliberately, use withThinking.

Value parameters

contentOpt: Text portion of the response; None when the model produced only tool calls.
thinking: The model's reasoning, as the provider returned it; empty when there was none or the provider does not report it. Clients put it here so that it stays in the conversation history, and send it back where their provider accepts it (see ThinkingBlock).
thinkingBinding: A fingerprint of the request the sealed thinking was produced for, set by the client that received it; None when the thinking is not sealed or was not bound. Opaque. Sealed thinking without a binding matching the conversation before the message is not replayed (see "Sealed thinking" above).
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

@Stable

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

@Stable

Audio as mono float32 PCM with sample rate.

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

trait MMInput

class Object

trait Matchable

class Any
Show all

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: AudioInput.type

@Stable

A source a model cited in its answer, as a provider reports it: where the claim came from and, when the provider says, where in the answer the inline citation sits. Provider-neutral: a provider that does not report a field leaves it None, and nothing here is invented.

Models that search the web by themselves report citations (OpenAI's Chat Completions search models - gpt-5-search-api, since the *-search-preview models were retired on 2026-07-23 - and OpenRouter's :online models, both as url_citation annotations). They arrive on Completion.citations; a completion from any other model has none.

Value parameters

citedText: A passage of the source, when the provider returns one with the citation (OpenRouter's content). It describes the source, not the answer.
endIndex: Where the inline citation ends; see startIndex.
startIndex: Where the inline citation starts, as the provider reports it: a position in Completion.content. OpenAI documents the two indices as the first and last character "of the URL citation in the message": they locate the citation itself, and no provider documents them as the span of prose the source supports, so do not highlight the text between them as the supported claim. Whether endIndex is inclusive is also the provider's call: check its convention before cutting content with it.
title: The source's title, when the provider reports one.
url: The cited source's URL, exactly as the provider returned it.

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: Citation.type

@Stable

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

Value parameters

citations: The sources the model cited in its answer, when the provider reports them (see Citation); empty for a model that does not search or does not cite, and for a completion assembled from streamed chunks, which carry none.
content: The main content of the response.
created: When the completion was created. Providers that report a creation time (the OpenAI-format created field, epoch seconds) are converted at the wire boundary; providers that report none stamp the time the response was received.
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.
toolCalls: List of tool calls made by the assistant.
usage: Optional token usage statistics for the completion.

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: Completion.type

@Stable

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)

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: CompletionOptions.type

@Stable

One part of a user or tool message's content: text, an image, or a document.

Text is built directly. An image or a document is built with ContentPart.image or ContentPart.document, which check its source and return a Result:

'''Inline bytes are bounded''' by ContentPart.MaxInlineBytes (5 MiB), also when a part is read from JSON. An agent thread's every checkpoint is a full snapshot of its state, so each retained checkpoint keeps a copy of every inline part - base64-encoded, a third larger - for as long as the message stays in the thread. Larger media belongs at a org.llm4s.media.MediaSource.Url or in a org.llm4s.media.MediaSource.ProviderFile, which a message holds by reference.
'''A URL is absolute''', and not a data: URL: that is inline bytes by another name, and would escape the bound. Use org.llm4s.media.MediaSource.Inline.
'''A provider file''' names a provider and an id, neither blank.

Each provider sends the parts its API takes and fails the request with an org.llm4s.error.UnsupportedContentPartError for any other; nothing is dropped or turned into text. Which provider takes which parts is listed in docs/guide/multimodal.md.

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all
Known subtypes: class Document

class Image

class Text

Attributes

Companion: trait
Supertypes: trait Sum

trait Mirror

class Object

trait Matchable

class Any
Self type: ContentPart.type

@Stable

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.

Build one with Conversation.apply or a factory such as Conversation.fromPrompts, and change it with withMessages, addMessage and addMessages; the constructor and copy are private, so a new field never breaks callers.

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

@Stable

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

Companion: object
Supertypes: trait LLMError

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: EmbeddingError.type

@Stable

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

Value parameters

input: the texts to embed, one vector per text, in order
model: the embedding model and its dimensions
purpose: whether the texts are documents to index or queries to run against them; defaults to InputPurpose.Document. Providers whose models embed the two differently (Voyage, Jina, Cohere) map it onto their own parameter; the rest ignore it.

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: EmbeddingRequest.type

@Stable

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). Providers can set modality/dim/usage when they know it; callers can ignore safely. Build one with EmbeddingResponse.apply and change it with the with* setters (an Option field's setter takes the value or an Option); the constructor and copy are private, so a new field never breaks callers.

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

@Stable

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). Build one with EmbeddingUsage.apply and change it with the with* setters; the constructor and copy are private, so a new field never breaks callers.

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: EmbeddingUsage.type

@Stable

Represents a dense embedding vector produced by an embedding model.

Value parameters

dim: dimensionality of the embedding vector
id: unique identifier for this embedding (e.g. document or chunk ID)
meta: optional key-value metadata associated with this embedding Build one with EmbeddingVector.apply and change it with the with* setters; the constructor and copy are private, so a new field never breaks callers.
modality: the input modality that was embedded (e.g. text, image)
model: name of the embedding model that produced this vector
values: raw float values of the embedding vector

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: EmbeddingVector.type

@Stable

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

@Stable

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

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

trait MMInput

class Object

trait Matchable

class Any
Show all

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: ImageInput.type

@Stable

What a text being embedded is for: a document to be indexed, or a query to be run against documents that were indexed.

Several embedding models are trained to embed the two differently, and a mismatch between how texts were indexed and how a query is embedded quietly degrades retrieval. Jina calls the distinction task, Cohere and Voyage call it input_type. A caller always knows which side it is on - indexing or querying - so the request says so, through EmbeddingRequest.purpose, and each provider maps it onto its own parameter.

A provider whose models embed both alike (OpenAI, Ollama) ignores it. A provider author does not need to handle it unless the vendor's API has an equivalent; see the provider guide.

Document is the default of every EmbeddingRequest, so code that does not say which side it is on keeps embedding documents, as it always did.

Attributes

Supertypes: trait Enum

trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

@Stable

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

@Stable

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.

A UserMessage and a ToolMessage carry ContentParts - text, images and documents; a SystemMessage and an AssistantMessage carry text. content is a message's text: for a user or tool message, its text parts joined by newlines, so "" for one that is all media. Use validate or the smart constructors on the Message companion to ensure a message has content. 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: class Object

trait Matchable

class Any
Self type: Message.type

@Stable

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

@Stable

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

@Stable

Accumulates token and cost statistics for a single model across one or more requests.

totalCost is stored as BigDecimal to avoid floating-point accumulation drift that would occur when summing many Double values; incoming Option[Double] costs are converted once via BigDecimal.decimal on first contact.

Value parameters

inputTokens: cumulative prompt tokens sent to the model
outputTokens: cumulative completion tokens received from the model
requestCount: number of API calls attributed to this model
thinkingTokens: cumulative extended-thinking tokens (Anthropic only; zero for other providers)
totalCost: cumulative estimated cost in USD; BigDecimal(0) when cost data is unavailable Build one with ModelUsage.apply and change it with the with* setters; the constructor and copy are private, so a new field never breaks callers. The constructor keeps its defaults because the JSON codec fills a missing key from them.

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: ModelUsage.type

@Stable

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

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: MultimediaEmbeddingRequest.type

@Stable

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

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

trait MMInput

class Object

trait Matchable

class Any
Show all

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: RawMediaInput.type

@Stable

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

@Stable

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

@Stable

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

@Stable

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

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: StreamedChunk.type

@Stable

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

@Stable

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

@Stable

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

@Stable

One block of the reasoning a model produced before its answer, as carried on AssistantMessage.thinking so that it can be sent back in later requests.

Most providers report thinking as plain text - Ollama's thinking, DeepSeek's and Z.ai's reasoning_content, OpenRouter's reasoning, Mistral's thinking chunks - and a message then holds a single ThinkingBlock.Text with no signature. Anthropic (directly or through Bedrock) returns one or more blocks, each signed, and some redacted; it requires them back unchanged, in order, when a thinking model's turn ends in tool calls. So the blocks are kept as the provider returned them, and a client replays only what its provider accepts: Anthropic and Bedrock send signed and redacted blocks and leave unsigned text out (they would reject it), the other providers send the text.

A provider whose replay data does not fit those two shapes - OpenRouter's reasoning_details, whose items carry ids, formats, indices, summaries and encrypted payloads - is kept as ThinkingBlock.Opaque blocks, which only that provider's client sends back.

Attributes

Companion: object
Supertypes: trait Enum

trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Companion: enum
Supertypes: trait Sum

trait Mirror

class Object

trait Matchable

class Any
Self type: ThinkingBlock.type

@Stable

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

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: TokenUsage.type

@Stable

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. Its numbers are doubles, so a whole number above 2^53 is already rounded; a tool that takes large identifiers declares them as strings. 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

@Stable

The result of a tool call: text, images and documents, as ContentParts.

ToolMessage(text, toolCallId) is the one-part result. A provider that cannot send one of the parts in a tool result fails the request with an org.llm4s.error.UnsupportedContentPartError.

Not a case class, for the reason UserMessage gives: case ToolMessage(content, id) => does not compile. Match case t: ToolMessage and read t.content or t.parts. Equality is by parts and id.

Value parameters

parts: the result, in order; usually one text part, e.g. a JSON response.
toolCallId: Unique identifier for the tool call (as provided by the ToolCall).

Attributes

Companion: object
Supertypes: trait Serializable

trait Message

class Object

trait Matchable

class Any

Attributes

Companion: class
Supertypes: class Object

trait Matchable

class Any
Self type: ToolMessage.type

@Stable

Aggregates token and cost statistics across all models used in an agent run.

The top-level fields (requestCount, inputTokens, etc.) are roll-ups across every model. The byModel map breaks the same figures down per model name (e.g. "claude-sonnet-4-5-latest", "gpt-4o"), allowing cost attribution per provider in multi-model pipelines.

totalCost uses BigDecimal rather than Double to keep cumulative sums deterministic regardless of the number of requests.

AgentResult.usage (llm4s-agent) carries one for its thread; CostTracker (llm4s-observability) builds one from recorded metrics. It lives here, beside TokenUsage, so that neither needs the other (#1242).

Value parameters

byModel: per-model breakdown; keyed by the model identifier string Build one with UsageSummary.apply and change it with the with* setters; the constructor and copy are private, so a new field never breaks callers. The constructor keeps its defaults because the JSON codec fills a missing key from them.
inputTokens: total prompt tokens sent across all models
outputTokens: total completion tokens received across all models
requestCount: total API calls across all models
thinkingTokens: total extended-thinking tokens (non-zero only for Anthropic models)
totalCost: total estimated cost in USD; BigDecimal(0) when unavailable

Attributes

See also: ModelUsage for the per-model record type
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: UsageSummary.type

@Stable

A user message: text, images and documents, as ContentParts.

UserMessage(text) is the one-part message. A provider that cannot send one of the parts fails the request with an org.llm4s.error.UnsupportedContentPartError.

'''Not a case class, on purpose.''' It has no extractor, so case UserMessage(content) => does not compile: before content parts that pattern bound the text, and an extractor of the parts would have kept code compiling that used the binder only in a string - and so sent Vector(Text(...)) as the text, or silently dropped the media. Match the type, case u: UserMessage, and read u.content (the text) or u.parts. Equality is by parts.

Value parameters

parts: the message's content, in order.

Attributes

Companion: object
Supertypes: trait Serializable

trait Message

class Object

trait Matchable

class Any

Attributes

Companion: class
Supertypes: class Object

trait Matchable

class Any
Self type: UserMessage.type

@Stable

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

@Stable

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

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

trait MMInput

class Object

trait Matchable

class Any
Show all

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: VideoInput.type

org.llm4s.llmconnect.model

Members list

Type members

Classlikes

Value parameters

Attributes

Attributes

Attributes

Attributes

Attributes

Value parameters

Attributes

Attributes

Value parameters

Attributes

Attributes

Value parameters

Attributes

Attributes

Attributes

Attributes

Value parameters

Attributes

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

Value parameters

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Value parameters

Attributes

Attributes

Value parameters

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Value parameters

Attributes

Attributes

Value parameters

Attributes

Attributes

Value parameters

Attributes

Attributes