Package org.machanism.machai.ai.provider.openai

Class OpenAIProvider

java.lang.Object
org.machanism.machai.ai.provider.openai.OpenAIProvider
All Implemented Interfaces:
Genai
public class OpenAIProvider extends Object implements Genai
OpenAI-backed Genai implementation.

This provider adapts the MachAI provider abstraction to the OpenAI Java SDK Responses API. It supports prompting, file inputs, tool/function calling, and embedding generation.

Configuration

Configuration values are read from the Configurator passed to init(Configurator).

  • chatModel (required): model identifier passed to the OpenAI Responses API (for example, gpt-4.1 or gpt-4o).
  • OPENAI_API_KEY (required): API key used to authenticate with the OpenAI API.
  • OPENAI_BASE_URL (optional): base URL for OpenAI-compatible endpoints. If unset, the SDK default base URL is used.
  • GENAI_TIMEOUT (optional): request timeout in seconds. If missing, 0, or negative, the SDK default timeouts are used. Defaults to 600L seconds.
  • MAX_OUTPUT_TOKENS (optional): maximum number of output tokens. Defaults to 18000L.
  • MAX_TOOL_CALLS (optional): maximum number of tool calls allowed in a single response. Defaults to 200L.
  • embedding.model (optional): embedding model identifier used by embedding(String, long). If unset, embedding generation may fail due to missing model selection.

  • Field Details

    • MAX_TOOL_CALLS

      public static final long MAX_TOOL_CALLS
      Default maximum number of tool calls allowed per response.
      See Also:

    • MAX_OUTPUT_TOKENS

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

  • Constructor Details

    • OpenAIProvider

      public OpenAIProvider()

  • Method Details

    • init

      public void init(Configurator config)
      Initializes the provider from the given configuration.
      Specified by:
      init in interface Genai
      Parameters:
      config - provider configuration (must contain OPENAI_API_KEY and chatModel)

    • prompt

      public void prompt(String text)
      Adds a text prompt to the current request input.
      Specified by:
      prompt in interface Genai
      Parameters:
      text - the prompt string

    • perform

      public String perform()
      Executes a request using the currently configured model, inputs, and tools.

      If the response contains tool calls, the provider executes the matching tool handlers and continues the conversation until a final text response is produced.

      Specified by:
      perform in interface Genai
      Returns:
      the final model response text (may be null if no text was produced)

    • embedding

      public List<Double> embedding(String text, long dimensions)
      Requests an embedding vector for the given input text.
      Specified by:
      embedding in interface Genai
      Parameters:
      text - input to embed
      dimensions - number of dimensions requested from the embedding model
      Returns:
      embedding as a list of double values, or null when text is null

    • logInputs

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

    • clear

      public void clear()
      Clears all accumulated inputs for the next request.
      Specified by:
      clear in interface Genai

    • addTool

      public void addTool(String name, String description, ToolFunction function, String... paramsDesc)
      Registers a function tool for the current provider instance.

      The paramsDesc entries must follow the format name:type:required:description. The parameter schema passed to OpenAI is a JSON Schema object of type object.

      Specified by:
      addTool in interface Genai
      Parameters:
      name - tool function name
      description - tool description
      function - handler callback for tool execution
      paramsDesc - parameter descriptors in the format name:type:required:description

    • instructions

      public void instructions(String instructions)
      Sets system-level instructions applied to subsequent requests.
      Specified by:
      instructions in interface Genai
      Parameters:
      instructions - instruction text (may be 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 (may be null to disable)

    • setWorkingDir

      public void setWorkingDir(File workingDir)
      Sets the working directory passed to tool handlers.
      Specified by:
      setWorkingDir in interface Genai
      Parameters:
      workingDir - working directory (may be null)

    • usage

      public Usage usage()
      Returns token usage metrics captured from the most recent perform() call.
      Specified by:
      usage in interface Genai
      Returns:
      usage metrics; never null

    • getClient

      protected com.openai.client.OpenAIClient getClient()
      Returns the underlying OpenAI client.
      Returns:
      OpenAI client

    • getTimeout

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

    • setTimeout

      public void setTimeout(long timeout)
      Sets a request timeout (in seconds) for new clients created by this provider.
      Parameters:
      timeout - timeout in seconds; use 0 to use SDK defaults