Package org.machanism.machai.ai.provider

Class AbstractAIProvider

java.lang.Object
org.machanism.machai.ai.provider.AbstractAIProvider
All Implemented Interfaces:
Genai
Direct Known Subclasses:
AnthropicProvider, OpenAIProvider, ToolsProvider
public abstract class AbstractAIProvider extends Object implements Genai
Base implementation of the Genai contract shared by concrete provider integrations.

This class centralizes common configuration handling, request input logging, tool invocation safety, MCP/web-search bootstrap logic, and usage accounting state used by subclasses such as OpenAI- and Claude-based providers.

  • Field Details

    • logger

      static org.slf4j.Logger logger
      Logger instance for this provider.

    • ERROR_TOOL_RESULT_PREFIX

      public static final String ERROR_TOOL_RESULT_PREFIX
      Prefix prepended to tool invocation error messages that are returned back to the LLM.
      See Also:

    • USERNAME_PROP_NAME

      public static final String USERNAME_PROP_NAME
      Environment variable name for authenticating with the GenAI provider.
      See Also:

    • PASSWORD_PROP_NAME

      public static final String PASSWORD_PROP_NAME
      Environment variable name for authenticating with the GenAI provider.
      See Also:

    • LOG_LINE_LENG

      public static final int LOG_LINE_LENG
      Maximum length for log lines. Configures the truncation threshold when logging tool parameters and result strings.
      See Also:

    • LINE_SEPARATOR

      public static final String LINE_SEPARATOR
      Line separator used when composing prompts.
      See Also:

    • PARAGRAPH_SEPARATOR

      public static final String PARAGRAPH_SEPARATOR
      Paragraph separator used when composing prompts.
      See Also:

    • MCP_PROP_NAME_PREFIX

      protected static final String MCP_PROP_NAME_PREFIX
      Prefix for MCP property names.
      See Also:

    • MAX_OUTPUT_TOKENS

      public static final long MAX_OUTPUT_TOKENS
      Default maximum number of tokens the model may generate.
      See Also:

    • DEFAULT_WEBSEARCH_TYPE_NAME

      public static final String DEFAULT_WEBSEARCH_TYPE_NAME
      Default web search type name.
      See Also:

    • PROJECT_DIR_PARAM_NAME

      public static final String PROJECT_DIR_PARAM_NAME
      Name of the project directory parameter.
      See Also:

    • chatModel

      protected String chatModel
      Active model identifier used in Genai.perform().

    • projectDir

      protected File projectDir
      Working directory passed to tool handlers as contextual information.

    • timeoutSec

      protected Long timeoutSec
      Request timeout in seconds; 0 means SDK defaults are used.

    • instructions

      protected String instructions
      Optional instructions applied to the request.

    • maxOutputTokens

      protected Long maxOutputTokens
      Maximum number of output tokens for responses.

    • maxToolCalls

      protected Long maxToolCalls
      Maximum number of tool calls permitted per response.

    • config

      private Configurator config
      Configuration source used to initialize clients and provider features.

    • errorHandling

      private boolean errorHandling
      Flag indicating if standard runtime exceptions should be wrapped or handled conversationally.

    • enabledTools

      private String[] enabledTools
      List of specific tool names that are enabled on this provider instance.

  • Constructor Details

    • AbstractAIProvider

      public AbstractAIProvider()
      Creates a provider base instance.

      Subclasses are expected to complete initialization in init(String, Configurator).

  • Method Details

    • init

      public void init(String model, Configurator config)
      Initializes the provider from the given configuration.
      Specified by:
      init in interface Genai
      Parameters:
      model - the model identifier to use
      config - provider configuration source

    • addMcpServers

      protected void addMcpServers()
      Reads sequential MCP server configuration groups and registers them with the concrete provider implementation.

      The method looks for configuration keys named MCP.*, then MCP_1.*, MCP_2.*, and so on until no further URL is found.

    • addMcpServer

      protected void addMcpServer(String label, String url, String authorization, String description)
      Registers one MCP server/tool with the underlying provider SDK.

      This is an optional lifecycle method intended to be overridden by subclasses that natively support the Model Context Protocol (MCP).

      Parameters:
      label - provider-visible MCP server label
      url - server endpoint URL
      authorization - optional authorization token/value
      description - optional human-readable description

    • addWebSearch

      protected void addWebSearch()
      Registers a web-search capability when enabled in configuration.

      The default implementation reads configuration values and delegates the actual SDK-specific registration to addWebSearch(String, String, String, String).

    • addWebSearch

      protected void addWebSearch(String type, String city, String country, String region)
      Registers a provider-specific web-search tool.

      This is an optional capability hook intended to be overridden by subclasses whose underlying models natively support real-time web-search tools.

      Parameters:
      type - provider-specific web-search tool type/version
      city - optional user city
      country - optional user country
      region - optional user region

    • normalize

      protected String normalize(String value)
      Normalizes a string for case-insensitive comparisons.
      Parameters:
      value - source value
      Returns:
      lower-cased value, or an empty string when the input is null

    • safelyInvokeTool

      protected Object safelyInvokeTool(String name, ToolFunction tool, com.fasterxml.jackson.databind.JsonNode params, File projectDir)
      Safely invokes a tool function and converts IOExceptions into a textual error payload suitable for the model conversation.
      Parameters:
      name - tool name
      tool - tool handler
      params - parsed tool parameters
      projectDir - working directory passed to the tool
      Returns:
      tool output or a formatted error message string
      Throws:
      SpecialException - if a non-recoverable error occurs or when error-handling is disabled

    • instructions

      public void instructions(String instructions)
      Sets system-level instructions applied to subsequent requests.
      Specified by:
      instructions in interface Genai
      Parameters:
      instructions - instruction text, or null to clear

    • getTimeout

      public long getTimeout()
      Returns the configured request timeout.
      Returns:
      timeout in seconds; 0 indicates the SDK default

    • setTimeout

      public void setTimeout(long timeout, OpenAIProvider openAIProvider)
      Sets the timeout value used by provider client creation.

      The second parameter is unused and retained only for API compatibility.

      Parameters:
      timeout - timeout in seconds; use 0 to use SDK defaults
      openAIProvider - ignored compatibility parameter

    • addTool

      protected abstract void addTool(String name, String description, ToolFunction function, ParamDescriptor... paramsDesc)
      Adds a tool to the provider.

      Implemented by concrete subclasses to register the functional tool definition with the provider's specific API schemas (such as OpenAI's Tool schema or Claude's Tool definition).

      Parameters:
      name - the tool name
      description - the tool description
      function - the tool function implementation callback
      paramsDesc - descriptors for the tool parameters

    • addTools

      public void addTools(FunctionTools tools)
      Registers all annotated tool methods from the given FunctionTools instance.

      This method inspects the public methods of the provided FunctionTools class. For any method annotated with Tool, it extracts its name and description (falling back to the method's Java name if no explicit name is defined in the annotation) and registers it as an active tool.

      Specified by:
      addTools in interface Genai
      Parameters:
      tools - the FunctionTools instance containing the annotated methods to register

    • interpolateDescription

      private String interpolateDescription(String description)
      Interpolates system metadata variables (e.g., OS Name) inside the annotation's tool description text before registering it with the LLM.
      Parameters:
      description - the raw tool description from the annotation
      Returns:
      the interpolated description string

    • addPrompts

      public void addPrompts(FunctionTools tools)
      Registers all annotated prompt methods from the given FunctionTools instance.

      This method inspects the public methods of the provided FunctionTools class. For any method annotated with Prompt, it extracts its configured metadata—such as the name, description, and target Role. If no explicit name is defined in the annotation, it falls back to using the method's Java name, before registering it as an active prompt.

      Specified by:
      addPrompts in interface Genai
      Parameters:
      tools - the FunctionTools instance containing the annotated prompt methods to register

    • addResources

      public void addResources(FunctionTools tools)
      Scans the provided FunctionTools instance for methods annotated with Resource, and registers each resource for use during a run.
      Specified by:
      addResources in interface Genai
      Parameters:
      tools - the FunctionTools instance whose methods will be scanned for Resource annotations

    • addResource

      private void addResource(FunctionTools tools, Method method, String[] uris, String description, String mimeType)
      Resolves resource endpoints from declared arrays and binds them to the implementation context.
      Parameters:
      tools - target instance container
      method - reflective execution handle
      uris - URIs declared in the annotation config
      description - resource description text
      mimeType - the mime type associated with the resource
      Throws:
      IllegalArgumentException - if any URIs have incorrect syntax or execution fails

    • addResource

      protected void addResource(URI uri, String description, String mimeType, ToolFunction function, ParamDescriptor... paramsDesc)
      Registers a resource callback for providers that support resource management tools.

      Intended to be implemented by concrete subclasses to natively expose local/remote resources to the LLM model context.

      Parameters:
      uri - resource URI
      description - a description of the resource tool
      mimeType - the mime type format (e.g. application/json)
      function - the callback execution handler
      paramsDesc - variable-arity array of parameter descriptors

    • addPrompt

      private void addPrompt(FunctionTools tools, Method method, String name, String description, Role role)
      Configures and registers a single prompt method.
      Parameters:
      tools - instance container
      method - reflection handle
      name - the prompt name
      description - descriptive purpose
      role - role level instructions

    • addPrompt

      protected void addPrompt(String name, String description, ToolFunction function, Role role, ParamDescriptor... paramsDesc)
      Registers a prompt callback for providers that support prompt tools.

      Intended to be implemented by concrete subclasses to natively expose dynamic prompt templates to the underlying model execution context.

      Parameters:
      name - prompt name exposed to the provider
      description - prompt description used by the provider
      function - callback used to resolve the prompt content
      role - role associated with the generated prompt
      paramsDesc - descriptors for prompt input parameters

    • addTool

      private void addTool(FunctionTools tools, Method method, String name, String description)
      Configures and registers a single tool method.
      Parameters:
      tools - instance container
      method - reflection handle
      name - the tool name
      description - tool capabilities description

    • fillParamDesc

      private ParamDescriptor[] fillParamDesc(Method method)
      Analyzes method signature annotations to build an array of parameter descriptions.
      Parameters:
      method - the method to inspect
      Returns:
      an array of ParamDescriptor instances detailing parameters

    • invoke

      private Object invoke(FunctionTools tools, Method method, com.fasterxml.jackson.databind.JsonNode props, Object... paramsByType) throws ReflectiveOperationException
      Dynamically invokes the specified method on the given tools instance, matching arguments dynamically.
      Parameters:
      tools - target instance
      method - method handle
      props - the incoming JSON attributes
      paramsByType - variable array of parameter context constraints
      Returns:
      execution output
      Throws:
      ReflectiveOperationException - if the invoked target throws an exception

    • getParamByType

      private <T> T getParamByType(Class<T> type, Object[] paramsByType)
      Filters parameter arrays to find the first assignment-compatible instance of the specified type.
      Type Parameters:
      T - the generic class type to filter for
      Parameters:
      type - the class definition type representing the constraint
      paramsByType - variable array containing contextual params
      Returns:
      the mapped parameter matching the target class, or null if not found

    • getParamValue

      protected String getParamValue(com.fasterxml.jackson.databind.JsonNode props, String paramName, String defaultValue)
      Retrieves the value for a parameter from the given JSON node, or returns the default value if not present.
      Parameters:
      props - the JSON node containing parameters
      paramName - the parameter name
      defaultValue - the default value to use if not present
      Returns:
      the parameter value as a string

    • getProjectDir

      public File getProjectDir()
      Returns the current project directory.
      Returns:
      the active projectDir File context

    • setProjectDir

      public void setProjectDir(File projectDir)
      Sets the project directory.
      Specified by:
      setProjectDir in interface Genai
      Parameters:
      projectDir - the projectDir to set

    • prompt

      public void prompt(String text)
      Sets the prompt text for the provider.
      Specified by:
      prompt in interface Genai
      Parameters:
      text - the prompt text

    • clear

      public void clear()
      Clears the provider state.
      Specified by:
      clear in interface Genai

    • isErrorHandling

      public boolean isErrorHandling()
      Returns whether runtime tool errors are handled conversationally.
      Returns:
      true if errors are returned as text payload to the model; false if exceptions propagate and fail immediately.

    • setErrorHandling

      public void setErrorHandling(boolean errorHandling)
      Configures how runtime tool errors are handled by the invocation logic.

      Use this setter to toggle between conversational error recovery and strict, fail-fast exception reporting.

      Behavior Summary:

      • setErrorHandling(true) (Default): Captures all standard runtime tool exceptions and returns them in a text payload (e.g. "Error: The functional tool call failed..."). This permits conversational LLM agents to review the failure description and attempt self-correction.
      • setErrorHandling(false): Re-throws all invocation exceptions as a wrapped SpecialException up the current thread execution. Use this setting to debug and fail execution immediately upon the first unhandled exception.
      Specified by:
      setErrorHandling in interface Genai
      Parameters:
      errorHandling - true to enable conversational intercept and recovery; false to disable intercept and trigger strict stack propagation.

    • getConfigurator

      public Configurator getConfigurator()
      Returns the configurator context source.
      Returns:
      the config configuration source

    • setEnabledTools

      public void setEnabledTools(String[] tools)
      Configures the list of tool names that are enabled and allowed to be used by the AI provider.
      Specified by:
      setEnabledTools in interface Genai
      Parameters:
      tools - the array of unique tool names to enable; if null or empty, all tools are enabled

    • getEnabledTools

      public String[] getEnabledTools()
      Returns the array of currently active tool names.
      Returns:
      the array of enabled tool identifiers, or null if no filter is applied