llm4s-docs
API
Generated with
llm4s-docs/org.llm4s/org.llm4s.config/Llm4sConfig

Llm4sConfig

org.llm4s.config.Llm4sConfig
@Stable
object Llm4sConfig

Application-edge configuration loader for LLM4S.

Reads runtime configuration through PureConfig's default source: JVM system properties, then application.conf, then the reference.conf of every llm4s module on the classpath. Environment variables are read only where a ${?VAR} substitution binds them - in a module's reference.conf (tracing, embeddings, tools, and each provider module's vendor key) or in the application's own application.conf. Nothing reads LLM_MODEL. This is the single authorised entry point for configuration in application and test code — never read sys.env, System.getenv, or ConfigFactory.load() directly.

== Provider setup == Define named providers under llm4s.providers.<name> and optionally set llm4s.providers.provider to choose the default provider. Then call defaultProvider or resolve a named provider directly with provider.

== API keys == A client's key is its own apiKey when it sets one - in its chat section llm4s.providers.<name>, embeddings block llm4s.embeddings.<id> or reranker block - and otherwise its vendor's shared llm4s.credentials.<providerId>.apiKey. Each provider module binds that shared key to the vendor's conventional variable (llm4s-openai binds OPENAI_API_KEY), so with the variable set a section needs only provider and model. A section for a second account sets its own apiKey = ${?OTHER_VAR}. Where each key came from is logged at INFO - the path, never the value - and apiKeySources reports it for a policy check.

Then call defaultProvider to obtain a org.llm4s.llmconnect.config.ProviderConfig ready for org.llm4s.llmconnect.LLMConnect.getClient. Apps that need multiple configured providers can call provider directly.

== Which providers can be resolved == Every method that reads llm4s.providers takes an implicit org.llm4s.llmconnect.spi.ProviderRegistry, which decides what a provider = "..." entry can resolve to. With none in scope it is ProviderRegistry.default: everything found on the classpath through META-INF/services. Pass one explicitly to restrict or extend that set — Llm4sConfig.defaultProvider()(using ProviderRegistry.of(MyProvider)).

Attributes

See also

org.llm4s.config.ConfigKeys for the environment variables core's reference.conf binds.

Example 
for {
 registry <- Llm4sConfig.modelRegistryService()
 cfg      <- Llm4sConfig.defaultProvider()
 client   <- LLMConnect.getClient(cfg)(using registry)
 agent    <- Agent.builder("assistant", client).build()   // llm4s-agent
 result   <- agent.run("Hello")
} yield result.answer
Graph
Supertypes
class Object
trait Matchable
class Any
Self type

Members list

Type members

Classlikes

final case class EmbeddingsChunkingSettings(enabled: Boolean, size: Int, overlap: Int)

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class EmbeddingsInputSettings(inputPath: Option[String], inputPaths: Option[String], query: Option[String])

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class EmbeddingsUiSettings(maxRowsPerFile: Int, topDimsPerRow: Int, globalTopK: Int, showGlobalTop: Boolean, colorEnabled: Boolean, tableWidth: Int)

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class TextEmbeddingModelSettings(provider: String, modelName: String, dimensions: Int)

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all

Value members

Concrete methods

def apiKeySources()(using ProviderRegistry): Result[Map[ProviderName, ApiKeySource]]

Where each named chat section's API key comes from: its own apiKey, or its vendor's shared llm4s.credentials.<providerId>.apiKey.

Where each named chat section's API key comes from: its own apiKey, or its vendor's shared llm4s.credentials.<providerId>.apiKey.

A section with no key of its own silently uses the shared one - convenient for the default account, and a billing mistake for a section meant for a second account that forgot its key. The config-policy prod preset uses this to require explicit keys. Only sections whose provider requires a key are listed; no section is validated.

Attributes

def defaultProvider()(using ProviderRegistry): Result[ProviderConfig]

Loads the configured default named provider as a runtime ProviderConfig.

Loads the configured default named provider as a runtime ProviderConfig.

Only the default section is validated: another section's problem does not fail this.

Attributes

def defaultProviderName(): Result[ProviderName]

Loads the configured default provider name from llm4s.providers.provider.

Loads the configured default provider name from llm4s.providers.provider.

Fails if no default is set or no section has that name. No section is validated.

Attributes

def embeddings()(using ProviderRegistry): Result[(String, EmbeddingProviderConfig)]

Loads the active embedding provider and its configuration from the current environment.

Loads the active embedding provider and its configuration from the current environment.

Reads EMBEDDING_MODEL in provider/model format (e.g. "openai/text-embedding-3-small", "voyage/voyage-3", "ollama/nomic-embed-text"). Returns the provider name and typed config.

The provider is resolved through the given org.llm4s.llmconnect.spi.ProviderRegistry, so an embedding provider supplied by a module - or registered explicitly - is configurable here without llm4s-core knowing it exists.

Attributes

Returns

a pair of (providerName, EmbeddingProviderConfig), or a org.llm4s.error.ConfigurationError when EMBEDDING_MODEL is absent or the provider is unrecognised.

def exchangeLogging(): Result[ProviderExchangeLogging]

Loads provider exchange logging configuration from the current environment.

Loads provider exchange logging configuration from the current environment.

Reads the optional llm4s.exchangeLogging section. When absent or disabled, exchange logging remains off. When enabled, a JSONL sink is constructed from a configured directory and writes to a new per-run file.

Attributes

def experimentalStubsEnabled: Boolean

Returns true when experimental embedding stubs are enabled.

Returns true when experimental embedding stubs are enabled.

Controlled by the llm4s.embeddings.experimentalStubs config key. Defaults to false when the key is absent.

Attributes

def listModels()(using ProviderRegistry): Result[List[DiscoveredModel]]

Lists models for the configured default named provider.

Lists models for the configured default named provider.

Attributes

def listModels(name: String)(using ProviderRegistry): Result[List[DiscoveredModel]]

Lists models for a named provider configured under llm4s.providers.<name>.

Lists models for a named provider configured under llm4s.providers.<name>.

Attributes

def loadEmbeddingsChunking(): Result[EmbeddingsChunkingSettings]

Loads text-chunking settings for the embeddings pipeline from the current environment.

Loads text-chunking settings for the embeddings pipeline from the current environment.

Reads CHUNK_SIZE, CHUNK_OVERLAP, and CHUNKING_ENABLED, applying defaults of 1000, 100, and true respectively when variables are absent.

Attributes

Returns

chunking settings; always returns Right — missing variables fall back to defaults rather than failing.

def loadEmbeddingsInputs(): Result[EmbeddingsInputSettings]

Loads input path and query settings for the embeddings pipeline from the current environment.

Loads input path and query settings for the embeddings pipeline from the current environment.

Reads EMBEDDING_INPUT_PATH, llm4s.embeddings.inputPaths, and EMBEDDING_QUERY. All fields are optional; returns Right with None values when variables are absent.

Attributes

def loadEmbeddingsUiSettings(): Result[EmbeddingsUiSettings]

Loads UI display settings for the embeddings explorer from the current environment.

Loads UI display settings for the embeddings explorer from the current environment.

Applies defaults when variables are absent: maxRowsPerFile=200, topDimsPerRow=6, globalTopK=10, showGlobalTop=false, colorEnabled=true, tableWidth=120.

Attributes

Returns

UI settings; always returns Right — missing variables fall back to defaults rather than failing.

def loadTextEmbeddingModel()(using ProviderRegistry): Result[TextEmbeddingModelSettings]

Loads and resolves the active embedding model, including its output dimensions.

Loads and resolves the active embedding model, including its output dimensions.

Reads EMBEDDING_MODEL and looks up the known dimension count for the provider/model combination from the bundled dimension registry.

Resolves the provider through embeddings, and so through the given org.llm4s.llmconnect.spi.ProviderRegistry: a provider that is configurable there is configurable here, by the same registry.

Attributes

Returns

the resolved settings, or a org.llm4s.error.ConfigurationError when EMBEDDING_MODEL is absent or unrecognised.

def localEmbeddingModels(): Result[LocalEmbeddingModels]

Loads configuration for locally-available embedding models from the current environment.

Loads configuration for locally-available embedding models from the current environment.

Attributes

Returns

the local model configuration, or a org.llm4s.error.ConfigurationError when required variables are missing.

def provider(name: String)(using ProviderRegistry): Result[ProviderConfig]

Loads a named provider from llm4s.providers.<name>.

Loads a named provider from llm4s.providers.<name>.

Useful for applications that need to resolve multiple configured provider instances, including multiple accounts for the same provider type.

Attributes

def providers()(using ProviderRegistry): Result[ProvidersConfig]

Loads the full validated named-providers configuration from llm4s.providers.

Loads the full validated named-providers configuration from llm4s.providers.

Every section is validated, so this fails if any one of them is invalid - a ${?VAR} key left unset, a provider whose module is not on the classpath. Resolving one provider with provider or defaultProvider validates only that provider's section, and providerConfigs reports each section's problem separately.

Attributes

def tracing(): Result[TracingSettings]

Loads tracing configuration from the current environment.

Loads tracing configuration from the current environment.

Reads TRACING_MODE (console, none, or a backend module's mode such as langfuse or opentelemetry) and hands the selected mode's llm4s.tracing.<mode> block to its backend as TracingSettings.extras. The backend's own module binds that block's variables (LANGFUSE_* in llm4s-observability, OTEL_* in llm4s-observability-otel) and validates it when Tracing.fromSettings builds the tracer.

Attributes

Returns

the tracing settings, or a org.llm4s.error.ConfigurationError when the llm4s.tracing tree cannot be parsed, or when the selected mode's llm4s.tracing.<mode> is present but is not an object (an absent block is fine: the backend applies its defaults).

Generated with