org.llm4s.config

@Stable

Environment-variable names recognised by llm4s-anthropic.

These were ConfigKeys.ANTHROPIC_* in llm4s-core until the provider moved to its own module (#1132): a key belongs with the code that reads it, so that ConfigKeys does not name variables for a provider that may not be on the classpath.

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: AnthropicConfigKeys.type

@Stable

Model lister for the Anthropic provider, using the paginated /v1/models endpoint.

Anthropic does not serve the OpenAI-compatible /models shape, so it cannot use ProviderModelListers.openAICompatible (in llm4s-openai-compatible). This was ProviderModelListers.Anthropic until the provider moved to llm4s-anthropic (#1132).

Attributes

Supertypes: trait ProviderModelLister

class Object

trait Matchable

class Any
Self type: AnthropicModelLister.type

@Stable

Where a named chat section's API key comes from.

A section that sets no apiKey of its own uses its vendor's shared key, llm4s.credentials.<providerId>.apiKey. That is the convenient default - set OPENAI_API_KEY and every OpenAI section works - and also the way a section meant for a second account, missing its key, silently bills the first. Llm4sConfig.apiKeySources reports which sections do which, so a policy can insist on explicit keys in production.

Attributes

Supertypes: trait Enum

trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

The environment variables llm4s-bedrock suggests, and the names of the provider-specific keys of a provider = "bedrock" section.

Named sections read no environment variable by themselves, so the variables here are the conventional AWS ones a user binds in the section (region = ${?AWS_REGION}); they appear in the missing-key error message as that binding. A key belongs with the code that reads it, so they are not in ConfigKeys.

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: BedrockConfigKeys.type

Configuration data for Brave Search tool.

This configuration is loaded from application.conf at the edge (via ToolsConfigLoader) and passed to BraveSearchTool.create() when instantiating the tool.

Value parameters

apiKey: The Brave Search API key
apiUrl: The base URL for the Brave Search API (default: https://api.search.brave.com/res/v1)
count: The number of search results to return per request
safeSearch: The safe search level (off, moderate, or strict)

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Environment-variable names recognised by llm4s-cohere.

A key belongs with the code that reads it, so these live here and not in ConfigKeys, which must not name variables for a provider that may not be on the classpath. They are bound in this module's reference.conf: the key under the shared llm4s.credentials.cohere, the base URL and model under llm4s.embeddings.cohere.

COHERE_API_KEY is also bound by llm4s-openai-compatible (Cohere chat) and llm4s-rag (the Cohere reranker), so one key serves all three; it is bound here too so that llm4s-cohere works without either.

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: CohereEmbeddingConfigKeys.type

@Stable

Canonical environment-variable names bound by llm4s-core's reference.conf.

Each is read through a ${?VAR} substitution under the llm4s config tree, so the config key it feeds can also be set directly in application.conf or as a JVM system property. This object centralises the names to avoid typos and make grep-friendly references possible.

== Quick reference ==

Chat providers: a named section under llm4s.providers sets no key of its own by default; it uses its vendor's llm4s.credentials.<id>.apiKey, which the provider's module binds to the vendor's variable (llm4s-openai binds OPENAI_API_KEY, see OpenAIConfigKeys). Nothing reads LLM_MODEL.
TRACING_MODE — optional; console (default) or none, or a backend module's mode: langfuse (llm4s-observability), opentelemetry (llm4s-observability-otel).
EMBEDDING_MODEL — required when using embeddings; format provider/model.

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: ConfigKeys.type

@Stable

Model lister for the DeepSeek provider, using its OpenAI-compatible /models endpoint.

This was ProviderModelListers.DeepSeek until the provider moved to llm4s-openai-compatible (#1132).

Attributes

Supertypes: trait ProviderModelLister

class Object

trait Matchable

class Any
Self type: DeepSeekModelLister.type

@Stable

A model discovered from a provider's live model-listing endpoint.

Value parameters

metadata: optional key/value pairs of additional model metadata (e.g. display name, token limits)
name: the model identifier as reported by the provider
provider: the ProviderId that owns this model

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Configuration data for DuckDuckGo Search tool.

This configuration is loaded from application.conf at the edge (via ToolsConfigLoader) and passed to DuckDuckGoSearchTool.create() when instantiating the tool.

Value parameters

apiUrl: The base URL for the DuckDuckGo API (default: https://api.duckduckgo.com)

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Configuration data for Exa Search tool.

Value parameters

apiKey: The Exa API key
apiUrl: Base URL (default: https://api.exa.ai)
maxCharacters: Maximum characters for text content
numResults: Number of results to return
searchType: Search type (auto, neural, fast, deep)

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

@Stable

Environment-variable names recognised by llm4s-gemini.

Google's GenAI SDKs read two variables for the Gemini API key and prefer GOOGLE_API_KEY when both are set (google-genai's _get_env_api_key: "Both GOOGLE_API_KEY and GEMINI_API_KEY are set. Using GOOGLE_API_KEY."). llm4s-gemini's reference.conf binds both to the shared llm4s.credentials.gemini.apiKey, in that precedence.

Vertex AI has no entry: it authenticates with OAuth2 - Application Default Credentials, or a service-account file named by a section's apiKey - not with an API key.

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: GeminiConfigKeys.type

@Stable

Model lister for the Gemini provider, using the paginated models endpoint.

Gemini does not serve the OpenAI-compatible /models shape, so it cannot use ProviderModelListers.openAICompatible (in llm4s-openai-compatible). This was ProviderModelListers.Gemini until the provider moved to llm4s-gemini (#1132).

Attributes

Supertypes: trait ProviderModelLister

class Object

trait Matchable

class Any
Self type: GeminiModelLister.type

Loads the llm4s.jev block into a org.llm4s.jev.JevConfig.

It lives in org.llm4s.config, the one package that reads configuration; org.llm4s.jev.JevClient takes the typed config it returns and reads nothing itself.

llm4s-jev's reference.conf binds TYPESAFE_BASE_URL to baseUrl and TYPESAFE_DEFAULT_MODEL to model (the variables TypeSafe's own SDKs read), and TYPESAFE_API_KEY to llm4s.credentials.typesafe.apiKey. The key is llm4s.jev.apiKey when that is set and the shared llm4s.credentials.typesafe.apiKey otherwise, so one variable serves every client of the vendor. Everything but the key has a default.

llm4s.jev {
 model   = "jev-1.13.0"        # pin the answers; the default is the alias jev-latest
 timeout = 20 seconds
 retry { maxRetries = 3 }
}

for
 config <- JevConfigLoader.default()
 client <- JevClient(config)
yield client

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: JevConfigLoader.type

Environment-variable names recognised by llm4s-jina.

A key belongs with the code that reads it, so these live here and not in ConfigKeys, which must not name variables for a provider that may not be on the classpath. They are bound in this module's reference.conf: the key under the shared llm4s.credentials.jina, the base URL and model under llm4s.embeddings.jina.

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: JinaConfigKeys.type

Environment-variable names recognised by llm4s-observability, each bound under llm4s.tracing.langfuse by this module's reference.conf.

These were ConfigKeys.LANGFUSE_* in llm4s-core until Langfuse moved to this module (#1133): a key belongs with the code that reads it, so that ConfigKeys does not name variables for a backend that may not be on the classpath.

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: LangfuseConfigKeys.type

Loads org.llm4s.llmconnect.config.LangfuseConfig from llm4s.tracing.langfuse, whatever TRACING_MODE selects.

The tracing backend does not need this: with TRACING_MODE=langfuse the block reaches it as TracingSettings.extras. This is for code that talks to Langfuse alongside another tracer - RAGASLangfuseObserver in llm4s-rag, or a TracingComposer.combine of Langfuse with Console:

for
 langfuse <- LangfuseConfigLoader.default()
yield TracingComposer.combine(LangfuseTracing.from(langfuse), new ConsoleTracing())

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: LangfuseConfigLoader.type

@Stable

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

Supertypes

class Object

trait Matchable

class Any

Self type

Llm4sConfig.type

Loads the Prometheus metrics backend from llm4s.metrics: a org.llm4s.metrics.MetricsCollector, plus the org.llm4s.metrics.PrometheusEndpoint serving it when one was started.

This replaces Llm4sConfig.metrics(), which left core with Prometheus (#1133): MetricsConfigLoader.default() is the same call against the same keys.

Configuration keys, with their defaults in this module's reference.conf:

llm4s.metrics.enabled: enable metrics collection (default: false)
llm4s.metrics.prometheus.enabled: use the Prometheus backend when metrics are enabled (default: true)
llm4s.metrics.prometheus.port: port for the /metrics HTTP endpoint (default: 9090)

Example application.conf:

llm4s {
 metrics {
   enabled = true
   prometheus {
     enabled = true
     port = 9090
   }
 }
}

When enabled, loading starts the HTTP endpoint; stop it with PrometheusEndpoint.stop(). Other code should receive the MetricsCollector by dependency injection rather than read these keys itself.

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: MetricsConfigLoader.type

@Stable

Model lister for the Mistral provider: GET <api base>/models, where the API base is the one chat posts /chat/completions under - org.llm4s.llmconnect.config.MistralConfig.apiBaseUrl of the section's baseUrl (the API root, https://api.mistral.ai by default), so https://api.mistral.ai and https://api.mistral.ai/v1 both list /v1/models.

This was ProviderModelListers.Mistral until the provider moved to llm4s-openai-compatible (#1132).

Attributes

Supertypes: trait ProviderModelLister

class Object

trait Matchable

class Any
Self type: MistralModelLister.type

@Stable

Environment-variable names recognised by llm4s-ollama.

These were ConfigKeys.OLLAMA_* in llm4s-core until the provider moved to its own module (#1132): a key belongs with the code that reads it, so that ConfigKeys does not name variables for a provider that may not be on the classpath.

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: OllamaConfigKeys.type

@Stable

Model lister for the Ollama provider, using the local /api/tags endpoint.

Ollama does not serve the OpenAI-compatible /models shape, so unlike most providers it cannot use ProviderModelListers.openAICompatible (in llm4s-openai-compatible). This was ProviderModelListers.Ollama until the provider moved to llm4s-ollama (#1132).

Attributes

Supertypes: trait ProviderModelLister

class Object

trait Matchable

class Any
Self type: OllamaModelLister.type

@Stable

Environment-variable names recognised by llm4s-openai-compatible.

These were ConfigKeys.OPENROUTER_BASE_URL, ConfigKeys.DEEPSEEK_* and ConfigKeys.MISTRAL_* in llm4s-core until the providers moved to their own module (#1132): a key belongs with the code that reads it, so that ConfigKeys does not name variables for a provider that may not be on the classpath.

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: OpenAICompatibleConfigKeys.type

@Stable

Model lister for the generic openai-compatible provider: GET <baseUrl>/models.

The section's baseUrl is required - there is no default endpoint - and its apiKey is optional, as it is for chat: a local server such as vLLM, LM Studio or llama.cpp lists its models without one. The section's headers are sent too. The section is validated exactly as chat validates it - the lister builds its config through the provider's own buildConfig path - before any request, so a section with auth and a plain-http baseUrl or tokenUrl is refused without exchanging the identity token.

Attributes

Supertypes: trait ProviderModelLister

class Object

trait Matchable

class Any
Self type: OpenAICompatibleModelLister.type

@Stable

Environment-variable names recognised by llm4s-openai: OpenAI, Requesty, Azure OpenAI and OpenAI embeddings.

These were ConfigKeys.OPENAI_*, ConfigKeys.REQUESTY_BASE_URL and ConfigKeys.AZURE_* in llm4s-core until the providers moved to their own module (#1132): a key belongs with the code that reads it, so that ConfigKeys does not name variables for a provider that may not be on the classpath. OpenRouter's alias is OpenAICompatibleConfigKeys.OPENROUTER_BASE_URL in llm4s-openai-compatible.

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: OpenAIConfigKeys.type

@Stable

Model lister for the OpenAI provider, using the OpenAI /models endpoint. The section's organization, if set, is sent as the OpenAI-Organization header.

This was ProviderModelListers.OpenAI until the provider moved to llm4s-openai (#1132).

Attributes

Supertypes: trait ProviderModelLister

class Object

trait Matchable

class Any
Self type: OpenAIModelLister.type

@Stable

Model lister for the OpenRouter provider, sending the HTTP-Referer and X-Title headers OpenRouter asks for, and the section's organization, if set, as OpenAI-Organization, as it always has.

This was ProviderModelListers.OpenRouter until the provider moved to llm4s-openai-compatible (#1132).

Attributes

Supertypes: trait ProviderModelLister

class Object

trait Matchable

class Any
Self type: OpenRouterModelLister.type

Loader that builds a org.llm4s.rag.permissions.SearchIndex.PgConfig from a PureConfig pureconfig.ConfigSource.

Reads the llm4s.rag.permissions.pg config tree to obtain PostgreSQL connection details (host, port, database, credentials) and table names used by the RAG permission-aware search index.

Use default to read the ambient environment; Llm4sConfig cannot expose this because SearchIndex lives in llm4s-rag and Llm4sConfig lives in llm4s-core.

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: PgSearchIndexConfigLoader.type

@Stable

Discovers available models from a provider's live API endpoint.

llm4s-core ships no provider and so no lister: each provider module supplies one on its descriptor. Most call ProviderModelListers.openAICompatible in llm4s-openai-compatible, the factory for the OpenAI /models shape; the rest implement this trait.

Attributes

Supertypes: class Object

trait Matchable

class Any
Known subtypes: object AnthropicModelLister

object DeepSeekModelLister

object GeminiModelLister

object MistralModelLister

object OllamaModelLister

object OpenAICompatibleModelLister

object OpenAIModelLister

object OpenRouterModelLister

object RequestyModelLister
Show all

@Stable

The factory behind the model listers of providers serving the OpenAI /models shape.

llm4s-core holds only the ProviderModelLister contract. This factory lived there too until it was found to read a vendor field - OpenAI's organization - straight off NamedProviderConfig; it moved here, with the OpenAI wire format, when that field became a provider-specific key (#1133). Its package is unchanged. A provider module that serves the same shape depends on llm4s-openai-compatible and calls openAICompatible; one that does not implements ProviderModelLister.

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: ProviderModelListers.type

@Stable

Shared model types and configuration data structures for the multi-provider configuration system.

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: ProvidersConfigModel.type

@Stable

Model lister for the Requesty provider, using its OpenAI-compatible /models endpoint. The section's organization, if set, is sent as the OpenAI-Organization header.

This was ProviderModelListers.Requesty until the provider moved to llm4s-openai (#1132).

Attributes

Supertypes: trait ProviderModelLister

class Object

trait Matchable

class Any
Self type: RequestyModelLister.type

Loads the reranker selected under llm4s.rerank into a org.llm4s.reranker.RerankProviderConfig.

llm4s-rag's reference.conf binds RERANK_PROVIDER, COHERE_RERANK_BASE_URL and COHERE_RERANK_MODEL there. The Cohere key is llm4s.rerank.cohere.apiKey when that is set, and otherwise Cohere's shared llm4s.credentials.cohere.apiKey, bound to COHERE_API_KEY - the key the Cohere chat provider uses too, so one variable serves both.

for
 reranker <- RerankerConfigLoader.default()
 rag      <- RAG.build(config, resolveRerankerConfig = () => Right(reranker))
yield rag

Only Cohere is configured here. llm reranking needs an LLMClient, which config cannot supply: select it in code with RAGConfig.withLLMReranking or RerankerFactory.llm.

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: RerankerConfigLoader.type

Environment variables bound by llm4s-agent-tools' reference.conf under llm4s.tools.*.

BRAVE_SEARCH_API_KEY was ConfigKeys.BRAVE_SEARCH_API_KEY in llm4s-core; it moved with the search tools (#1242), as the Langfuse keys moved to LangfuseConfigKeys.

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: ToolsConfigKeys.type

Loads the search tools' configuration from llm4s.tools.*.

This follows the "config at the edge" pattern used throughout llm4s: the application loads a tool's config here and passes it to the tool's create(), so the tools themselves never read configuration.

for
 config <- ToolsConfigLoader.loadBraveSearchTool()
 tool   <- BraveSearchTool.create(config)
yield tool

It replaces Llm4sConfig.loadBraveSearchTool(), loadDuckDuckGoSearchTool() and loadExaSearchTool(), which left llm4s-core with the tools (#1242): the calls are the same, on this object. The llm4s.tools block and its BRAVE_SEARCH_* / EXA_* bindings ship in llm4s-agent-tools' reference.conf.

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: ToolsConfigLoader.type

Environment-variable names recognised by llm4s-voyage.

These were ConfigKeys.VOYAGE_* in llm4s-core until Voyage moved to its own module (#1132): a key belongs with the code that reads it, so that ConfigKeys does not name variables for a provider that may not be on the classpath. They are bound in this module's reference.conf: the key under the shared llm4s.credentials.voyage, the base URL and model under llm4s.embeddings.voyage.

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: VoyageConfigKeys.type

org.llm4s.config

Members list

Type members

Classlikes

Attributes

Attributes

Attributes

Attributes

Value parameters

Attributes

Attributes

Attributes

Attributes

Value parameters

Attributes

Value parameters

Attributes

Value parameters

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes