Module agentforge4j.llm
Package com.agentforge4j.llm

Interface LlmProviderOptions

public interface LlmProviderOptions
Validated, provider-specific configuration transport for the LLM SPI. Carries the provider-specific settings (beyond the common provider id / default model / connect timeout) that a provider factory needs, exposed through typed, validating accessors.

The backing key/value store is never exposed raw: callers read through string(java.lang.String), integer(java.lang.String), bool(java.lang.String), duration(java.lang.String), and secret(java.lang.String), each of which parses and validates. A type-parse failure throws LlmProviderConfigurationException naming the provider and offending key — never the value, in case it is a secret.

This type defines only the mechanism. The option-key vocabulary belongs to each provider module (for example openai-compatible documents auth.header.name, auth.header.prefix, responses.path). Unknown keys are not an error here (forward-compatibility); required-key validation is provider-owned.

  • Method Details

    • string

      Optional<String> string(String key)
      Returns the value for key exactly as configured (not trimmed — significant whitespace such as an auth header prefix "Bearer " is preserved), or empty when the key is absent or blank.
      Parameters:
      key - the option key
      Returns:
      the value, if present and non-blank

    • integer

      Optional<Integer> integer(String key)
      Returns the integer value for key.
      Parameters:
      key - the option key
      Returns:
      the value, if present
      Throws:
      LlmProviderConfigurationException - if the value is not a valid integer

    • bool

      Optional<Boolean> bool(String key)
      Returns the boolean value for key (strictly "true" or "false", case insensitive).
      Parameters:
      key - the option key
      Returns:
      the value, if present
      Throws:
      LlmProviderConfigurationException - if the value is not a strict boolean

    • duration

      Optional<Duration> duration(String key)
      Returns the Duration value for key, accepting either ISO-8601 (for example PT30S) or a compact shorthand — an amount plus an optional ns/us/ms/s/m/h/ d unit suffix, defaulting to milliseconds (for example 15s, 2m, 500ms).
      Parameters:
      key - the option key
      Returns:
      the value, if present
      Throws:
      LlmProviderConfigurationException - if the value is not a valid ISO-8601 or shorthand duration

    • decimal

      Optional<Double> decimal(String key)
      Returns the decimal value for key.
      Parameters:
      key - the option key
      Returns:
      the value, if present
      Throws:
      LlmProviderConfigurationException - if the value is not a valid decimal number

    • secret

      Optional<LlmSecretReference> secret(String key)
      Returns the value for key as a credential reference (see LlmSecretReference.parse(java.lang.String)).
      Parameters:
      key - the option key
      Returns:
      the reference, if present

    • keys

      Set<String> keys()
      Returns:
      the set of option keys present

    • providerName

      String providerName()
      Returns:
      the owning provider id, used in error messages

    • requireString

      default String requireString(String key)
      Returns the required string value for key.
      Parameters:
      key - the option key
      Returns:
      the value
      Throws:
      LlmProviderConfigurationException - if the key is absent or blank

    • requireInteger

      default int requireInteger(String key)
      Returns the required integer value for key.
      Parameters:
      key - the option key
      Returns:
      the value
      Throws:
      LlmProviderConfigurationException - if the key is absent, or not a valid integer

    • requireDuration

      default Duration requireDuration(String key)
      Returns the required Duration value for key.
      Parameters:
      key - the option key
      Returns:
      the value
      Throws:
      LlmProviderConfigurationException - if the key is absent, or not a valid ISO-8601 or shorthand duration

    • empty

      static LlmProviderOptions empty()
      Returns:
      an empty options instance

    • of

      static LlmProviderOptions of(String providerName, Map<String,String> values)
      Creates options backed by the given key/value map.
      Parameters:
      providerName - the owning provider id, used only for error messages; must not be null
      values - the option key/value pairs; must not be null
      Returns:
      validated options