Package org.egothor.methodatlas.ai

Record Class AiOptions

java.lang.Object
java.lang.Record
org.egothor.methodatlas.ai.AiOptions
Record Components:
enabled - whether AI enrichment is enabled
provider - AI provider used to perform analysis
modelName - provider-specific model identifier
baseUrl - base API endpoint used by the selected provider
apiKey - API key used for authentication, if provided directly
apiKeyEnv - environment variable name containing the API key
taxonomyFile - optional path to an external taxonomy definition
taxonomyMode - built-in taxonomy mode to use when no file is provided
maxClassChars - maximum number of characters allowed for class source submitted to the AI provider
timeout - request timeout applied to AI calls
maxRetries - number of retry attempts for failed AI operations
confidence - whether the AI provider should be asked to include a confidence score for each security-relevant method classification; requires model support and increases token usage slightly
public record AiOptions(boolean enabled, AiProvider provider, String modelName, String baseUrl, String apiKey, String apiKeyEnv, Path taxonomyFile, AiOptions.TaxonomyMode taxonomyMode, int maxClassChars, Duration timeout, int maxRetries, boolean confidence) extends Record
Immutable configuration describing how AI-based enrichment should be performed during a MethodAtlasApp execution.

This record aggregates all runtime parameters required by the AI integration layer, including provider selection, model identification, authentication configuration, taxonomy selection, request limits, and retry behavior.

Instances of this record are typically constructed using the associated AiOptions.Builder and passed to the AI subsystem when initializing an AiSuggestionEngine. The configuration is immutable once constructed and therefore safe to share between concurrent components.

Configuration Responsibilities

  • AI provider selection and endpoint configuration
  • model name resolution
  • API key discovery
  • taxonomy configuration for security classification
  • input size limits for class source submission
  • network timeout configuration
  • retry policy for transient AI failures

Default values are supplied by the AiOptions.Builder when parameters are not explicitly provided.

See Also:

  • Field Details

    • DEFAULT_MODEL

      public static final String DEFAULT_MODEL
      Default model identifier used when no model is explicitly configured.

      This constant is intentionally public so that governance processes can locate and track the approved fallback model in version control without searching through builder internals.

      See Also:

  • Constructor Details

    • AiOptions

      public AiOptions(boolean enabled, AiProvider provider, String modelName, String baseUrl, String apiKey, String apiKeyEnv, Path taxonomyFile, AiOptions.TaxonomyMode taxonomyMode, int maxClassChars, Duration timeout, int maxRetries, boolean confidence)
      Canonical constructor performing validation of configuration parameters.

      The constructor enforces basic invariants required for correct operation of the AI integration layer. Invalid values result in an IllegalArgumentException.

      Throws:
      NullPointerException - if required parameters such as provider, modelName, timeout, or taxonomyMode are null
      IllegalArgumentException - if configuration values violate required constraints

  • Method Details

    • builder

      public static AiOptions.Builder builder()
      Creates a new AiOptions.Builder used to construct AiOptions instances.

      The builder supplies sensible defaults for most configuration values and allows incremental customization before producing the final immutable configuration record.

      Returns:
      new builder instance

    • resolvedApiKey

      public String resolvedApiKey()
      Resolves the effective API key used for authenticating AI provider requests.

      The resolution strategy is:

      1. If apiKey() is defined and non-empty, it is returned.
      2. If apiKeyEnv() is defined, the corresponding environment variable is resolved using System.getenv(String).
      3. If neither source yields a value, null is returned.
      Returns:
      resolved API key or null if none is available

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with '=='.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • enabled

      public boolean enabled()
      Returns the value of the enabled record component.
      Returns:
      the value of the enabled record component

    • provider

      public AiProvider provider()
      Returns the value of the provider record component.
      Returns:
      the value of the provider record component

    • modelName

      public String modelName()
      Returns the value of the modelName record component.
      Returns:
      the value of the modelName record component

    • baseUrl

      public String baseUrl()
      Returns the value of the baseUrl record component.
      Returns:
      the value of the baseUrl record component

    • apiKey

      public String apiKey()
      Returns the value of the apiKey record component.
      Returns:
      the value of the apiKey record component

    • apiKeyEnv

      public String apiKeyEnv()
      Returns the value of the apiKeyEnv record component.
      Returns:
      the value of the apiKeyEnv record component

    • taxonomyFile

      public Path taxonomyFile()
      Returns the value of the taxonomyFile record component.
      Returns:
      the value of the taxonomyFile record component

    • taxonomyMode

      public AiOptions.TaxonomyMode taxonomyMode()
      Returns the value of the taxonomyMode record component.
      Returns:
      the value of the taxonomyMode record component

    • maxClassChars

      public int maxClassChars()
      Returns the value of the maxClassChars record component.
      Returns:
      the value of the maxClassChars record component

    • timeout

      public Duration timeout()
      Returns the value of the timeout record component.
      Returns:
      the value of the timeout record component

    • maxRetries

      public int maxRetries()
      Returns the value of the maxRetries record component.
      Returns:
      the value of the maxRetries record component

    • confidence

      public boolean confidence()
      Returns the value of the confidence record component.
      Returns:
      the value of the confidence record component