Package org.egothor.methodatlas.ai

Interface AiSuggestionEngine

All Known Implementing Classes:
AiSuggestionEngineImpl, ManualConsumeEngine
public interface AiSuggestionEngine
High-level AI orchestration contract for security classification of parsed test classes.

This interface defines the provider-agnostic entry point used by MethodAtlasApp to request AI-generated security tagging suggestions for a single parsed JUnit test class. Implementations coordinate taxonomy selection, provider resolution, request submission, response normalization, and conversion into the application's internal result model.

Responsibilities

  • accepting a fully qualified class name and corresponding class source
  • submitting the class for AI-based security analysis
  • normalizing provider-specific responses into AiClassSuggestion
  • surfacing failures through AiSuggestionException

The interface intentionally hides provider-specific protocol details so that the rest of the application can depend on a stable abstraction independent of the selected AI backend.

See Also:

  • Method Details

    • suggestForClass

      AiClassSuggestion suggestForClass(String fileStem, String fqcn, String classSource, List<PromptBuilder.TargetMethod> targetMethods) throws AiSuggestionException
      Requests AI-generated security classification for a single parsed test class.

      The supplied source code is analyzed in the context of the configured taxonomy and AI provider. The returned result may contain both class-level and method-level suggestions, including security relevance, display name proposals, taxonomy tags, and optional explanatory rationale.

      The method expects the complete source of the class being analyzed, rather than a single method fragment, so that the AI engine can evaluate test intent using full class context.

      The fileStem parameter is a dot-separated identifier derived from the source file's path relative to the scan root (e.g. module-a.src.test.java.com.acme.FooTest). Automated provider implementations ignore it; the ManualConsumeEngine uses it to locate the operator-saved response file (<fileStem>.response.txt).

      Parameters:
      fileStem - dot-separated path stem identifying the source file; used by file-based engines to locate response files
      fqcn - fully qualified class name of the parsed test class
      classSource - complete source code of the class to analyze
      targetMethods - deterministically extracted JUnit test methods that must be classified
      Returns:
      normalized AI classification result for the class and its methods
      Throws:
      AiSuggestionException - if analysis fails due to provider communication errors, invalid responses, provider unavailability, or normalization failures
      See Also: