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

    • LOG_LINE_LENG

      public static final int LOG_LINE_LENG
      Maximum length for log lines.
      See Also:

    • LOG_INPUTS_PROP_NAME

      public static final String LOG_INPUTS_PROP_NAME
      Configuration property name indicating whether provider inputs should be logged.
      See Also:

    • SERVERID_PROP_NAME

      public static final String SERVERID_PROP_NAME
      Configuration property name for the target GenAI server identifier.
      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:

    • 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:

    • LOG_SECTION_SEPARATOR

      public static final String LOG_SECTION_SEPARATOR
      Separator for log sections.
      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.

  • 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.
      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.
      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 String 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

    • logInputs

      protected void logInputs()
      Writes the current request inputs to inputsLog when logging is enabled.

    • logInputsSpec

      protected void logInputsSpec(Writer streamWriter) throws IOException
      Writes provider-specific input items to the supplied log writer.
      Parameters:
      streamWriter - destination writer
      Throws:
      IOException - when writing fails

    • 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

    • inputsLog

      public void inputsLog(File inputsLog)
      Enables request input logging to the given file.
      Specified by:
      inputsLog in interface Genai
      Parameters:
      inputsLog - file for input logging, or null to disable

    • 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.
      Parameters:
      name - the tool name
      description - the tool description
      function - the tool function implementation
      paramsDesc - descriptors for the tool parameters

    • addTools

      public void addTools(FunctionTools tools)
      Registers all annotated tool methods from the given FunctionTools instance.
      Specified by:
      addTools in interface Genai
      Parameters:
      tools - the tools instance containing annotated methods

    • addPrompts

      public void addPrompts(FunctionTools tools)
      Scans the provided FunctionTools instance for methods annotated with Prompt, and registers each prompt using its name, description, and role.

      For each method in the tools class, if a Prompt annotation is present, the method extracts the prompt's description, name (using the method name if not defined in the annotation), and role, then calls addPrompt(FunctionTools, Method, String, String, Role) to register the prompt.

      Specified by:
      addPrompts in interface Genai
      Parameters:
      tools - The FunctionTools instance whose methods will be scanned for Prompt annotations.

    • addPrompt

      protected void addPrompt(String name, String description, ToolFunction function, Role role, ParamDescriptor... paramsDesc)
      Registers a prompt callback for providers that support prompt tools.
      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

    • 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 projectDir

    • 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:
      the errorHandling

    • 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 config