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

Class OpenAIProvider

java.lang.Object
org.machanism.machai.ai.provider.AbstractAIProvider
org.machanism.machai.ai.provider.openai.OpenAIProvider
All Implemented Interfaces:
Genai
public class OpenAIProvider extends AbstractAIProvider
OpenAI-backed Genai implementation. <p>This provider adapts the MachAI provider abstraction to the OpenAI Java SDK Responses API. It supports prompting, file inputs, tool/function calling, optional web search and MCP tools, and embedding generation. </p>

Configuration

<p>Configuration values are read from the Configurator passed to AbstractAIProvider.init(Configurator). </p><ul>
  • 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.
  • MAX_OUTPUT_TOKENS (optional): maximum number of output tokens. Defaults to 18000L.
  • MAX_TOOL_CALLS (optional): maximum number of tool calls the model may issue in a single response loop. A value of 0 leaves the limit unset.
  • embedding.model (optional): embedding model identifier used by embedding(String, long).
  • WebSearchTool.type (optional): enables the built-in web search tool when present.
  • WebSearchTool.city (optional): city value for the web search user location.
  • WebSearchTool.country (optional): country value for the web search user location.
  • WebSearchTool.region (optional): region value for the web search user location.
  • MCP.url, MCP.label, MCP.description, MCP.authorization (optional): registers an MCP server tool.
  • MCP_1.url, MCP_1.label, MCP_1.description, MCP_1.authorization and similarly numbered groups (optional): registers additional MCP server tools.
    • </ul>

    • Field Details

      • logger

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

      • OPENAI_API_KEY

        public static final String OPENAI_API_KEY
        Configuration/environment key used by OpenAI-compatible clients to provide the API key.

        For CodeMie this value is set to the retrieved OAuth 2.0 access token.

        See Also:

      • OPENAI_BASE_URL_NAME

        public static final String OPENAI_BASE_URL_NAME
        See Also:

      • toolMap

        final Map<com.openai.models.responses.Tool,ToolFunction> toolMap
        Maps tools to handler functions.

      • inputs

        final List<com.openai.models.responses.ResponseInputItem> inputs
        Accumulated request input items for the current conversation.

    • Constructor Details

      • OpenAIProvider

        public OpenAIProvider()

    • Method Details

      • addWebSearch

        public void addWebSearch()
        Adds the built-in OpenAI web search tool when configured.
        Specified by:
        addWebSearch in class AbstractAIProvider

      • addMcpServer

        public void addMcpServer()
        Adds one or more MCP server tools from configuration.
        Specified by:
        addMcpServer in class AbstractAIProvider

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

        Parameters:
        name - tool function name
        description - tool description
        function - handler callback for tool execution
        paramsDesc - parameter descriptors in the format name:type:required:description

      • prompt

        public void prompt(String text)
        Adds a text prompt to the current request input.
        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.

        Returns:
        the final model response text, or null if no text was produced

      • embedding

        public List<Double> embedding(String text, long dimensions)
        Requests an embedding vector for the given input text.
        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

      • clear

        public void clear()
        Clears all accumulated inputs for the next request.

      • getClient

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

      • captureUsage

        protected void captureUsage(Optional<com.openai.models.responses.ResponseUsage> usage)
        Extracts token usage from the response and stores it as AbstractAIProvider.usage().
        Parameters:
        usage - optional usage information from the OpenAI response

      • logInputsSpec

        protected void logInputsSpec(Writer streamWriter) throws IOException
        Specified by:
        logInputsSpec in class AbstractAIProvider
        Throws:
        IOException