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.
== 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)).
== A config the application already has == Every method here reads the process-wide default configuration. To read a com.typesafe.config.Config the application loaded itself - Play's Configuration.underlying, a Pekko ActorSystem.settings.config, a config parsed per test or per tenant - call from and use the returned Llm4sSettings, which has the same methods.
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.
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.
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.
The llm4s settings of config instead of the process-wide application.conf.
The llm4s settings of config instead of the process-wide application.conf.
config takes the place of application.conf and nothing else changes: JVM system properties still override it, every llm4s module's reference.conf still sits beneath it (so llm4s.credentials.<providerId>.apiKey and each module's defaults apply), and ${?VAR} substitutions are resolved against the process environment - what ConfigFactory.load(config) does. A config that is already loaded and resolved, such as Play's or Pekko's, is accepted as is. Each call reads only its own config, so two settings in one JVM are independent.
Value parameters
config
the application's configuration; its llm4s block is read
Experimental: it takes a Typesafe Config, a third-party type, so whether that is the entry point to freeze is open until the API baseline (#2340, #1281).
The proxy and TLS settings of the llm4s.http block: what every provider client loaded through this object uses, unless its section's own http block overrides it. Pass them to Llm4sHttpClient.create(network) for an HTTP client of your own - a tool, a vector store - that should take the same route.
The proxy and TLS settings of the llm4s.http block: what every provider client loaded through this object uses, unless its section's own http block overrides it. Pass them to Llm4sHttpClient.create(network) for an HTTP client of your own - a tool, a vector store - that should take the same route.
A missing trust or key store, or a wrong password, is a ConfigurationError naming the key.
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.
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.
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).