| 1 | package org.egothor.methodatlas.ai; | |
| 2 | ||
| 3 | import java.nio.file.Path; | |
| 4 | import java.time.Duration; | |
| 5 | import java.util.Objects; | |
| 6 | ||
| 7 | /** | |
| 8 | * Immutable configuration describing how AI-based enrichment should be | |
| 9 | * performed during a {@link org.egothor.methodatlas.MethodAtlasApp} execution. | |
| 10 | * | |
| 11 | * <p> | |
| 12 | * This record aggregates all runtime parameters required by the AI integration | |
| 13 | * layer, including provider selection, model identification, authentication | |
| 14 | * configuration, taxonomy selection, request limits, and retry behavior. | |
| 15 | * </p> | |
| 16 | * | |
| 17 | * <p> | |
| 18 | * Instances of this record are typically constructed using the associated | |
| 19 | * {@link Builder} and passed to the AI subsystem when initializing an | |
| 20 | * {@link AiSuggestionEngine}. The configuration is immutable once constructed | |
| 21 | * and therefore safe to share between concurrent components. | |
| 22 | * </p> | |
| 23 | * | |
| 24 | * <h2>Configuration Responsibilities</h2> | |
| 25 | * | |
| 26 | * <ul> | |
| 27 | * <li>AI provider selection and endpoint configuration</li> | |
| 28 | * <li>model name resolution</li> | |
| 29 | * <li>API key discovery</li> | |
| 30 | * <li>taxonomy configuration for security classification</li> | |
| 31 | * <li>input size limits for class source submission</li> | |
| 32 | * <li>network timeout configuration</li> | |
| 33 | * <li>retry policy for transient AI failures</li> | |
| 34 | * </ul> | |
| 35 | * | |
| 36 | * <p> | |
| 37 | * Default values are supplied by the {@link Builder} when parameters are not | |
| 38 | * explicitly provided. | |
| 39 | * </p> | |
| 40 | * | |
| 41 | * @param enabled whether AI enrichment is enabled | |
| 42 | * @param provider AI provider used to perform analysis | |
| 43 | * @param modelName provider-specific model identifier | |
| 44 | * @param baseUrl base API endpoint used by the selected provider | |
| 45 | * @param apiKey API key used for authentication, if provided directly | |
| 46 | * @param apiKeyEnv environment variable name containing the API key | |
| 47 | * @param taxonomyFile optional path to an external taxonomy definition | |
| 48 | * @param taxonomyMode built-in taxonomy mode to use when no file is provided | |
| 49 | * @param maxClassChars maximum number of characters allowed for class source | |
| 50 | * submitted to the AI provider | |
| 51 | * @param timeout request timeout applied to AI calls | |
| 52 | * @param maxRetries number of retry attempts for failed AI operations | |
| 53 | * @param confidence whether the AI provider should be asked to include a | |
| 54 | * confidence score for each security-relevant method | |
| 55 | * classification; requires model support and increases | |
| 56 | * token usage slightly | |
| 57 | * @param apiVersion Azure OpenAI REST API version used to construct the | |
| 58 | * deployment endpoint; only consulted when | |
| 59 | * {@link AiProvider#AZURE_OPENAI} is selected; defaults | |
| 60 | * to {@link #DEFAULT_API_VERSION} | |
| 61 | * | |
| 62 | * @see AiSuggestionEngine | |
| 63 | * @see Builder | |
| 64 | */ | |
| 65 | public record AiOptions(boolean enabled, AiProvider provider, String modelName, String baseUrl, String apiKey, | |
| 66 | String apiKeyEnv, Path taxonomyFile, TaxonomyMode taxonomyMode, int maxClassChars, Duration timeout, | |
| 67 | int maxRetries, boolean confidence, String apiVersion) { | |
| 68 | /** | |
| 69 | * Built-in taxonomy modes used for security classification. | |
| 70 | * | |
| 71 | * <p> | |
| 72 | * These modes determine which internal taxonomy definition is supplied to the | |
| 73 | * AI provider when an external taxonomy file is not configured. | |
| 74 | * </p> | |
| 75 | * | |
| 76 | * <ul> | |
| 77 | * <li>{@link #DEFAULT} – general-purpose taxonomy suitable for human | |
| 78 | * readability</li> | |
| 79 | * <li>{@link #OPTIMIZED} – compact taxonomy optimized for AI classification | |
| 80 | * accuracy</li> | |
| 81 | * </ul> | |
| 82 | */ | |
| 83 | public enum TaxonomyMode { | |
| 84 | /** | |
| 85 | * Standard taxonomy definition emphasizing clarity and documentation. | |
| 86 | */ | |
| 87 | DEFAULT, | |
| 88 | /** | |
| 89 | * Reduced taxonomy optimized for improved AI classification reliability. | |
| 90 | */ | |
| 91 | OPTIMIZED | |
| 92 | } | |
| 93 | ||
| 94 | /** | |
| 95 | * Default model identifier used when no model is explicitly configured. | |
| 96 | * | |
| 97 | * <p> | |
| 98 | * This constant is intentionally public so that governance processes can | |
| 99 | * locate and track the approved fallback model in version control without | |
| 100 | * searching through builder internals. | |
| 101 | * </p> | |
| 102 | */ | |
| 103 | public static final String DEFAULT_MODEL = "qwen2.5-coder:7b"; | |
| 104 | ||
| 105 | /** | |
| 106 | * Default Azure OpenAI REST API version used when {@link AiProvider#AZURE_OPENAI} | |
| 107 | * is selected and no explicit version is configured. | |
| 108 | * | |
| 109 | * <p> | |
| 110 | * This value targets the generally-available Chat Completions API. Newer | |
| 111 | * preview versions may be required to access features such as structured | |
| 112 | * outputs or reasoning models; override via {@link Builder#apiVersion(String)} | |
| 113 | * or the {@code apiVersion} YAML field when needed. | |
| 114 | * </p> | |
| 115 | */ | |
| 116 | public static final String DEFAULT_API_VERSION = "2024-02-01"; | |
| 117 | ||
| 118 | /** | |
| 119 | * Canonical constructor performing validation of configuration parameters. | |
| 120 | * | |
| 121 | * <p> | |
| 122 | * The constructor enforces basic invariants required for correct operation of | |
| 123 | * the AI integration layer. Invalid values result in an | |
| 124 | * {@link IllegalArgumentException}. | |
| 125 | * </p> | |
| 126 | * | |
| 127 | * @throws NullPointerException if required parameters such as | |
| 128 | * {@code provider}, {@code modelName}, | |
| 129 | * {@code timeout}, or {@code taxonomyMode} are | |
| 130 | * {@code null} | |
| 131 | * @throws IllegalArgumentException if configuration values violate required | |
| 132 | * constraints | |
| 133 | */ | |
| 134 | public AiOptions { | |
| 135 | Objects.requireNonNull(provider, "provider"); | |
| 136 | Objects.requireNonNull(modelName, "modelName"); | |
| 137 | Objects.requireNonNull(timeout, "timeout"); | |
| 138 | Objects.requireNonNull(taxonomyMode, "taxonomyMode"); | |
| 139 | ||
| 140 | if (baseUrl == null || baseUrl.isBlank()) { | |
| 141 | throw new IllegalArgumentException("baseUrl must not be blank"); | |
| 142 | } | |
| 143 | if (maxClassChars <= 0) { | |
| 144 | throw new IllegalArgumentException("maxClassChars must be > 0"); | |
| 145 | } | |
| 146 | if (maxRetries < 0) { | |
| 147 | throw new IllegalArgumentException("maxRetries must be >= 0"); | |
| 148 | } | |
| 149 | if (apiVersion == null || apiVersion.isBlank()) { | |
| 150 | throw new IllegalArgumentException("apiVersion must not be blank"); | |
| 151 | } | |
| 152 | } | |
| 153 | ||
| 154 | /** | |
| 155 | * Creates a new {@link Builder} used to construct {@link AiOptions} instances. | |
| 156 | * | |
| 157 | * <p> | |
| 158 | * The builder supplies sensible defaults for most configuration values and | |
| 159 | * allows incremental customization before producing the final immutable | |
| 160 | * configuration record. | |
| 161 | * </p> | |
| 162 | * | |
| 163 | * @return new builder instance | |
| 164 | */ | |
| 165 | public static Builder builder() { | |
| 166 |
1
1. builder : replaced return value with null for org/egothor/methodatlas/ai/AiOptions::builder → KILLED |
return new Builder(); |
| 167 | } | |
| 168 | ||
| 169 | /** | |
| 170 | * Resolves the effective API key used for authenticating AI provider requests. | |
| 171 | * | |
| 172 | * <p> | |
| 173 | * The resolution strategy is: | |
| 174 | * </p> | |
| 175 | * | |
| 176 | * <ol> | |
| 177 | * <li>If {@link #apiKey()} is defined and non-empty, it is returned.</li> | |
| 178 | * <li>If {@link #apiKeyEnv()} is defined, the corresponding environment | |
| 179 | * variable is resolved using {@link System#getenv(String)}.</li> | |
| 180 | * <li>If neither source yields a value, {@code null} is returned.</li> | |
| 181 | * </ol> | |
| 182 | * | |
| 183 | * @return resolved API key or {@code null} if none is available | |
| 184 | */ | |
| 185 | public String resolvedApiKey() { | |
| 186 |
4
1. resolvedApiKey : removed conditional - replaced equality check with false → KILLED 2. resolvedApiKey : removed conditional - replaced equality check with false → KILLED 3. resolvedApiKey : removed conditional - replaced equality check with true → KILLED 4. resolvedApiKey : removed conditional - replaced equality check with true → KILLED |
if (apiKey != null && !apiKey.isBlank()) { |
| 187 |
1
1. resolvedApiKey : replaced return value with "" for org/egothor/methodatlas/ai/AiOptions::resolvedApiKey → KILLED |
return apiKey; |
| 188 | } | |
| 189 |
4
1. resolvedApiKey : removed conditional - replaced equality check with false → SURVIVED 2. resolvedApiKey : removed conditional - replaced equality check with false → SURVIVED 3. resolvedApiKey : removed conditional - replaced equality check with true → SURVIVED 4. resolvedApiKey : removed conditional - replaced equality check with true → KILLED |
if (apiKeyEnv != null && !apiKeyEnv.isBlank()) { |
| 190 | String value = System.getenv(apiKeyEnv); | |
| 191 |
4
1. resolvedApiKey : removed conditional - replaced equality check with false → SURVIVED 2. resolvedApiKey : removed conditional - replaced equality check with true → NO_COVERAGE 3. resolvedApiKey : removed conditional - replaced equality check with false → NO_COVERAGE 4. resolvedApiKey : removed conditional - replaced equality check with true → KILLED |
if (value != null && !value.isBlank()) { |
| 192 |
1
1. resolvedApiKey : replaced return value with "" for org/egothor/methodatlas/ai/AiOptions::resolvedApiKey → NO_COVERAGE |
return value; |
| 193 | } | |
| 194 | } | |
| 195 |
1
1. resolvedApiKey : replaced return value with "" for org/egothor/methodatlas/ai/AiOptions::resolvedApiKey → KILLED |
return null; |
| 196 | } | |
| 197 | ||
| 198 | /** | |
| 199 | * Mutable builder used to construct validated {@link AiOptions} instances. | |
| 200 | * | |
| 201 | * <p> | |
| 202 | * The builder follows the conventional staged construction pattern, allowing | |
| 203 | * optional parameters to be supplied before producing the final immutable | |
| 204 | * configuration record via {@link #build()}. | |
| 205 | * </p> | |
| 206 | * | |
| 207 | * <p> | |
| 208 | * Reasonable defaults are provided for most parameters so that only | |
| 209 | * provider-specific details typically need to be configured explicitly. | |
| 210 | * </p> | |
| 211 | */ | |
| 212 | public static final class Builder { | |
| 213 | private boolean enabled; | |
| 214 | private AiProvider provider = AiProvider.AUTO; | |
| 215 | private String modelName = DEFAULT_MODEL; | |
| 216 | private String baseUrl; | |
| 217 | private String apiKey; | |
| 218 | private String apiKeyEnv; | |
| 219 | private Path taxonomyFile; | |
| 220 | private TaxonomyMode taxonomyMode = TaxonomyMode.DEFAULT; | |
| 221 | private int maxClassChars = 40_000; | |
| 222 | private Duration timeout = Duration.ofSeconds(90); | |
| 223 | private int maxRetries = 1; | |
| 224 | private boolean confidence; | |
| 225 | private String apiVersion = DEFAULT_API_VERSION; | |
| 226 | ||
| 227 | /** | |
| 228 | * Enables or disables AI enrichment. | |
| 229 | * | |
| 230 | * @param enabled {@code true} to enable AI integration | |
| 231 | * @return this builder | |
| 232 | */ | |
| 233 | public Builder enabled(boolean enabled) { | |
| 234 | this.enabled = enabled; | |
| 235 |
1
1. enabled : replaced return value with null for org/egothor/methodatlas/ai/AiOptions$Builder::enabled → KILLED |
return this; |
| 236 | } | |
| 237 | ||
| 238 | /** | |
| 239 | * Selects the AI provider. | |
| 240 | * | |
| 241 | * @param provider provider implementation to use | |
| 242 | * @return this builder | |
| 243 | */ | |
| 244 | public Builder provider(AiProvider provider) { | |
| 245 | this.provider = provider; | |
| 246 |
1
1. provider : replaced return value with null for org/egothor/methodatlas/ai/AiOptions$Builder::provider → KILLED |
return this; |
| 247 | } | |
| 248 | ||
| 249 | /** | |
| 250 | * Specifies the provider-specific model identifier. | |
| 251 | * | |
| 252 | * @param modelName name of the model to use | |
| 253 | * @return this builder | |
| 254 | */ | |
| 255 | public Builder modelName(String modelName) { | |
| 256 | this.modelName = modelName; | |
| 257 |
1
1. modelName : replaced return value with null for org/egothor/methodatlas/ai/AiOptions$Builder::modelName → KILLED |
return this; |
| 258 | } | |
| 259 | ||
| 260 | /** | |
| 261 | * Sets the base API endpoint used by the provider. | |
| 262 | * | |
| 263 | * @param baseUrl base URL of the provider API | |
| 264 | * @return this builder | |
| 265 | */ | |
| 266 | public Builder baseUrl(String baseUrl) { | |
| 267 | this.baseUrl = baseUrl; | |
| 268 |
1
1. baseUrl : replaced return value with null for org/egothor/methodatlas/ai/AiOptions$Builder::baseUrl → KILLED |
return this; |
| 269 | } | |
| 270 | ||
| 271 | /** | |
| 272 | * Sets the API key used for authentication. | |
| 273 | * | |
| 274 | * @param apiKey API key value | |
| 275 | * @return this builder | |
| 276 | */ | |
| 277 | public Builder apiKey(String apiKey) { | |
| 278 | this.apiKey = apiKey; | |
| 279 |
1
1. apiKey : replaced return value with null for org/egothor/methodatlas/ai/AiOptions$Builder::apiKey → KILLED |
return this; |
| 280 | } | |
| 281 | ||
| 282 | /** | |
| 283 | * Specifies the environment variable that stores the API key. | |
| 284 | * | |
| 285 | * @param apiKeyEnv environment variable name | |
| 286 | * @return this builder | |
| 287 | */ | |
| 288 | public Builder apiKeyEnv(String apiKeyEnv) { | |
| 289 | this.apiKeyEnv = apiKeyEnv; | |
| 290 |
1
1. apiKeyEnv : replaced return value with null for org/egothor/methodatlas/ai/AiOptions$Builder::apiKeyEnv → KILLED |
return this; |
| 291 | } | |
| 292 | ||
| 293 | /** | |
| 294 | * Specifies an external taxonomy definition file. | |
| 295 | * | |
| 296 | * @param taxonomyFile path to taxonomy definition | |
| 297 | * @return this builder | |
| 298 | */ | |
| 299 | public Builder taxonomyFile(Path taxonomyFile) { | |
| 300 | this.taxonomyFile = taxonomyFile; | |
| 301 |
1
1. taxonomyFile : replaced return value with null for org/egothor/methodatlas/ai/AiOptions$Builder::taxonomyFile → KILLED |
return this; |
| 302 | } | |
| 303 | ||
| 304 | /** | |
| 305 | * Selects the built-in taxonomy mode. | |
| 306 | * | |
| 307 | * @param taxonomyMode taxonomy variant | |
| 308 | * @return this builder | |
| 309 | */ | |
| 310 | public Builder taxonomyMode(TaxonomyMode taxonomyMode) { | |
| 311 | this.taxonomyMode = taxonomyMode; | |
| 312 |
1
1. taxonomyMode : replaced return value with null for org/egothor/methodatlas/ai/AiOptions$Builder::taxonomyMode → KILLED |
return this; |
| 313 | } | |
| 314 | ||
| 315 | /** | |
| 316 | * Sets the maximum size of class source submitted to the AI provider. | |
| 317 | * | |
| 318 | * @param maxClassChars maximum allowed character count | |
| 319 | * @return this builder | |
| 320 | */ | |
| 321 | public Builder maxClassChars(int maxClassChars) { | |
| 322 | this.maxClassChars = maxClassChars; | |
| 323 |
1
1. maxClassChars : replaced return value with null for org/egothor/methodatlas/ai/AiOptions$Builder::maxClassChars → KILLED |
return this; |
| 324 | } | |
| 325 | ||
| 326 | /** | |
| 327 | * Sets the timeout applied to AI requests. | |
| 328 | * | |
| 329 | * @param timeout request timeout | |
| 330 | * @return this builder | |
| 331 | */ | |
| 332 | public Builder timeout(Duration timeout) { | |
| 333 | this.timeout = timeout; | |
| 334 |
1
1. timeout : replaced return value with null for org/egothor/methodatlas/ai/AiOptions$Builder::timeout → KILLED |
return this; |
| 335 | } | |
| 336 | ||
| 337 | /** | |
| 338 | * Sets the retry limit for AI requests. | |
| 339 | * | |
| 340 | * @param maxRetries retry count | |
| 341 | * @return this builder | |
| 342 | */ | |
| 343 | public Builder maxRetries(int maxRetries) { | |
| 344 | this.maxRetries = maxRetries; | |
| 345 |
1
1. maxRetries : replaced return value with null for org/egothor/methodatlas/ai/AiOptions$Builder::maxRetries → KILLED |
return this; |
| 346 | } | |
| 347 | ||
| 348 | /** | |
| 349 | * Enables or disables AI confidence scoring. | |
| 350 | * | |
| 351 | * <p> | |
| 352 | * When enabled, the prompt instructs the AI provider to return a | |
| 353 | * {@code confidence} value for each method classification. The value is | |
| 354 | * included in the output as an {@code ai_confidence} column. | |
| 355 | * </p> | |
| 356 | * | |
| 357 | * @param confidence {@code true} to request confidence scores | |
| 358 | * @return this builder | |
| 359 | */ | |
| 360 | public Builder confidence(boolean confidence) { | |
| 361 | this.confidence = confidence; | |
| 362 |
1
1. confidence : replaced return value with null for org/egothor/methodatlas/ai/AiOptions$Builder::confidence → KILLED |
return this; |
| 363 | } | |
| 364 | ||
| 365 | /** | |
| 366 | * Sets the Azure OpenAI REST API version used to construct the deployment | |
| 367 | * endpoint. | |
| 368 | * | |
| 369 | * <p> | |
| 370 | * This value is only used when {@link AiProvider#AZURE_OPENAI} is selected. | |
| 371 | * It is appended as the {@code api-version} query parameter to the chat | |
| 372 | * completions URL. The default value is {@link AiOptions#DEFAULT_API_VERSION}. | |
| 373 | * </p> | |
| 374 | * | |
| 375 | * @param apiVersion REST API version string, for example {@code 2024-02-01} | |
| 376 | * @return this builder | |
| 377 | */ | |
| 378 | public Builder apiVersion(String apiVersion) { | |
| 379 | this.apiVersion = apiVersion; | |
| 380 |
1
1. apiVersion : replaced return value with null for org/egothor/methodatlas/ai/AiOptions$Builder::apiVersion → KILLED |
return this; |
| 381 | } | |
| 382 | ||
| 383 | /** | |
| 384 | * Builds the final immutable {@link AiOptions} configuration. | |
| 385 | * | |
| 386 | * <p> | |
| 387 | * If no base URL is explicitly supplied, a provider-specific default endpoint | |
| 388 | * is selected automatically. | |
| 389 | * </p> | |
| 390 | * | |
| 391 | * @return validated AI configuration | |
| 392 | */ | |
| 393 | public AiOptions build() { | |
| 394 |
2
1. build : removed conditional - replaced equality check with false → KILLED 2. build : removed conditional - replaced equality check with true → KILLED |
AiProvider effectiveProvider = provider == null ? AiProvider.AUTO : provider; |
| 395 | String effectiveBaseUrl = baseUrl; | |
| 396 | ||
| 397 |
4
1. build : removed conditional - replaced equality check with false → SURVIVED 2. build : removed conditional - replaced equality check with true → KILLED 3. build : removed conditional - replaced equality check with false → KILLED 4. build : removed conditional - replaced equality check with true → KILLED |
if (effectiveBaseUrl == null || effectiveBaseUrl.isBlank()) { |
| 398 |
1
1. build : Changed switch default to be first case → KILLED |
effectiveBaseUrl = switch (effectiveProvider) { |
| 399 | case AUTO, OLLAMA -> "http://localhost:11434"; | |
| 400 | case OPENAI -> "https://api.openai.com"; | |
| 401 | case OPENROUTER -> "https://openrouter.ai/api"; | |
| 402 | case ANTHROPIC -> "https://api.anthropic.com"; | |
| 403 | case GROQ -> "https://api.groq.com/openai"; | |
| 404 | case XAI -> "https://api.x.ai/v1"; | |
| 405 | case GITHUB_MODELS -> "https://models.inference.ai.azure.com"; | |
| 406 | case MISTRAL -> "https://api.mistral.ai/v1"; | |
| 407 | case AZURE_OPENAI -> throw new IllegalArgumentException( | |
| 408 | "baseUrl is required for AZURE_OPENAI: set it to https://<resource>.openai.azure.com"); | |
| 409 | }; | |
| 410 | } | |
| 411 | ||
| 412 |
1
1. build : replaced return value with null for org/egothor/methodatlas/ai/AiOptions$Builder::build → KILLED |
return new AiOptions(enabled, effectiveProvider, modelName, effectiveBaseUrl, apiKey, apiKeyEnv, |
| 413 | taxonomyFile, taxonomyMode, maxClassChars, timeout, maxRetries, confidence, apiVersion); | |
| 414 | } | |
| 415 | } | |
| 416 | } | |
Mutations | ||
| 166 |
1.1 |
|
| 186 |
1.1 2.2 3.3 4.4 |
|
| 187 |
1.1 |
|
| 189 |
1.1 2.2 3.3 4.4 |
|
| 191 |
1.1 2.2 3.3 4.4 |
|
| 192 |
1.1 |
|
| 195 |
1.1 |
|
| 235 |
1.1 |
|
| 246 |
1.1 |
|
| 257 |
1.1 |
|
| 268 |
1.1 |
|
| 279 |
1.1 |
|
| 290 |
1.1 |
|
| 301 |
1.1 |
|
| 312 |
1.1 |
|
| 323 |
1.1 |
|
| 334 |
1.1 |
|
| 345 |
1.1 |
|
| 362 |
1.1 |
|
| 380 |
1.1 |
|
| 394 |
1.1 2.2 |
|
| 397 |
1.1 2.2 3.3 4.4 |
|
| 398 |
1.1 |
|
| 412 |
1.1 |