Package org.egothor.methodatlas.command

Class AiRuntimeBuilder

java.lang.Object
org.egothor.methodatlas.command.AiRuntimeBuilder
public final class AiRuntimeBuilder extends Object
Constructs the per-run AI infrastructure: the suggestion engine, the result cache, and the human-readable taxonomy descriptor.

The builder is stateless and may be shared across commands. It returns null from buildEngine(org.egothor.methodatlas.ai.AiOptions) when AI is disabled — the orchestration layer relies on this sentinel rather than building a no-op engine, because most commands change behaviour entirely when AI is off (no extra columns, no confidence threshold, no taxonomy in metadata).

Failure handling

Engine construction can fail when an external provider cannot be reached or the configured model is unknown. Such failures are wrapped in an IllegalStateException, because they indicate a misconfigured run rather than a recoverable I/O fault: the user must change configuration before retrying.

Cache loading reads an arbitrary CSV produced by a previous run; a malformed file is reported as IllegalArgumentException so that the offending path appears in the user-facing CLI error.

Since:
1.0.0
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    AiRuntimeBuilder()
    Creates a new builder.

  • Method Summary

    Modifier and Type
    Method
    Description
    AiResultCache
    buildCache(Path cacheFile)
    Loads the AI result cache from a previous MethodAtlas CSV output, or returns the empty no-op cache when no cache file was configured.
    org.egothor.methodatlas.ai.AiSuggestionEngine
    buildEngine(org.egothor.methodatlas.ai.AiOptions aiOptions)
    Creates the AI suggestion engine for the current run, or returns null when AI support is disabled.
    String
    resolveTaxonomyInfo(org.egothor.methodatlas.ai.AiOptions aiOptions, boolean aiActive)
    Produces a human-readable string identifying which taxonomy configuration is in effect, for inclusion in scan-metadata output.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • AiRuntimeBuilder

      public AiRuntimeBuilder()
      Creates a new builder. Stateless; safe to share across commands.

  • Method Details

    • buildEngine

      public org.egothor.methodatlas.ai.AiSuggestionEngine buildEngine(org.egothor.methodatlas.ai.AiOptions aiOptions)
      Creates the AI suggestion engine for the current run, or returns null when AI support is disabled.

      The orchestration layer treats null as a sentinel meaning "skip every AI step": no per-class submission, no taxonomy resolution, no confidence filtering. Returning a no-op engine would force every call site to check a different way; returning null keeps the decision in one place.

      Parameters:
      aiOptions - AI configuration for the current run; must not be null
      Returns:
      initialised AI engine, or null when aiOptions reports AI as disabled
      Throws:
      IllegalStateException - if engine initialisation fails — typically an unknown provider or unreachable endpoint

    • buildCache

      public AiResultCache buildCache(Path cacheFile)
      Loads the AI result cache from a previous MethodAtlas CSV output, or returns the empty no-op cache when no cache file was configured.

      The empty no-op cache is a sentinel: every lookup returns absent and isActive() returns false, which lets the scan loop short-circuit cache work entirely without per-call null checks.

      Parameters:
      cacheFile - path to a previous run's CSV output (must include the content_hash column), or null to disable caching
      Returns:
      loaded cache, or the empty no-op cache; never null
      Throws:
      IllegalArgumentException - if the cache file exists but cannot be read or parsed

    • resolveTaxonomyInfo

      public String resolveTaxonomyInfo(org.egothor.methodatlas.ai.AiOptions aiOptions, boolean aiActive)
      Produces a human-readable string identifying which taxonomy configuration is in effect, for inclusion in scan-metadata output.

      Output forms:

      • "n/a (AI disabled)" when no AI engine is active for the run
      • "file:<absolute path>" when aiOptions names an external taxonomy file
      • "built-in/<mode>" (for example built-in/default or built-in/optimized) when no external file was supplied

      The string is intended for human eyes — auditors checking which taxonomy a particular scan run used. It is emitted by -emit-metadata into the CSV preamble and into SARIF run properties.

      Parameters:
      aiOptions - AI configuration for the current run; must not be null
      aiActive - whether an AI engine is active for this run
      Returns:
      taxonomy descriptor string; never null