Package org.machanism.machai.ai.provider.impl

Class OpenAIProvider

java.lang.Object

org.machanism.machai.ai.provider.AbstractAIProvider

org.machanism.machai.ai.provider.impl.OpenAIProvider

All Implemented Interfaces:

EmbeddingProvider, Genai

public class OpenAIProvider
extends AbstractAIProvider
implements EmbeddingProvider

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

Configuration values are read from the Configurator passed to AbstractAIProvider.init(String, 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.
• 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.
• 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.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	OPENAI_API_KEY	Configuration/environment key used by OpenAI-compatible clients to provide the API key.
static final String	OPENAI_BASE_URL_NAME	Configuration/environment key used to override the OpenAI-compatible base URL.

Fields inherited from class org.machanism.machai.ai.provider.AbstractAIProvider

chatModel, DEFAULT_WEBSEARCH_TYPE_NAME, instructions, LINE_SEPARATOR, LOG_INPUTS_PROP_NAME, LOG_LINE_LENG, LOG_SECTION_SEPARATOR, MAX_OUTPUT_TOKENS, maxOutputTokens, maxToolCalls, MCP_PROP_NAME_PREFIX, PARAGRAPH_SEPARATOR, PASSWORD_PROP_NAME, PROJECT_DIR_PARAM_NAME, projectDir, SERVERID_PROP_NAME, timeoutSec, USERNAME_PROP_NAME

Constructor Summary

Constructors

Constructor	Description
OpenAIProvider()	Creates an OpenAI provider instance.

Method Summary

Modifier and Type	Method	Description
protected void	addMcpServer(String name, String url, String authorization, String description)	Adds one or more MCP server tools from configuration.
protected void	addTool(String name, String description, ToolFunction function, ParamDescriptor... paramsDesc)	Registers a function tool for the current provider instance.
protected void	addWebSearch(String type, String city, String country, String region)	Adds the built-in OpenAI web search tool when configured.
protected void	captureUsage(Optional<com.openai.models.responses.ResponseUsage> usage)	Captures and records usage statistics from an optional ResponseUsage instance.
void	clear()	Clears all accumulated inputs for the next request.
List<Double>	embedding(String text, long dimensions)	Requests an embedding vector for the given input text.
com.openai.client.OpenAIClient	getClient()	Returns the underlying OpenAI client.
protected void	logInputsSpec(Writer streamWriter)	Writes provider-specific input items to the supplied log writer.
String	perform()	Executes a request using the currently configured model, inputs, and tools.
void	prompt(String text)	Adds a text prompt to the current request input.

Methods inherited from class org.machanism.machai.ai.provider.AbstractAIProvider

addMcpServers, addPrompt, addPrompts, addTools, addWebSearch, getConfigurator, getParamValue, getProjectDir, getTimeout, init, inputsLog, instructions, isErrorHandling, logInputs, normalize, safelyInvokeTool, setErrorHandling, setProjectDir, setTimeout

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.machanism.machai.ai.provider.EmbeddingProvider

init

Field Details

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:

• Constant Field Values

OPENAI_BASE_URL_NAME

public static final String OPENAI_BASE_URL_NAME

Configuration/environment key used to override the OpenAI-compatible base URL.

See Also:

• Constant Field Values

Constructor Details

OpenAIProvider

public OpenAIProvider()

Creates an OpenAI provider instance.

Method Details

addWebSearch

protected void addWebSearch(String type,
 String city,
 String country,
 String region)

Adds the built-in OpenAI web search tool when configured.

Overrides:

addWebSearch in class AbstractAIProvider

Parameters:

type - provider-specific web-search tool type/version

city - optional user city

country - optional user country

region - optional user region

addMcpServer

protected void addMcpServer(String name,
 String url,
 String authorization,
 String description)

Adds one or more MCP server tools from configuration.

Overrides:

addMcpServer in class AbstractAIProvider

Parameters:

name - provider-visible MCP server label

url - server endpoint URL

authorization - optional authorization token/value

description - optional human-readable description

addTool

protected void addTool(String name,
 String description,
 ToolFunction function,
 ParamDescriptor... 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 class AbstractAIProvider

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.

Specified by:

prompt in interface Genai

Overrides:

prompt in class AbstractAIProvider

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, or null if no text was produced

clear

public void clear()

Clears all accumulated inputs for the next request.

Specified by:

clear in interface Genai

Overrides:

clear in class AbstractAIProvider

getClient

public com.openai.client.OpenAIClient getClient()

Returns the underlying OpenAI client.

Returns:

OpenAI client

captureUsage

protected void captureUsage(Optional<com.openai.models.responses.ResponseUsage> usage)

Captures and records usage statistics from an optional ResponseUsage instance.

If the provided usage is present, this method extracts input tokens, cached input tokens, and output tokens from the ResponseUsage object, constructs a new Usage record, and adds it to the UsageStatistics for the current chat model.

Parameters:

usage - an Optional containing the ResponseUsage details to record; if not present, no action is taken

logInputsSpec

protected void logInputsSpec(Writer streamWriter)
                      throws IOException

Description copied from class: AbstractAIProvider

Writes provider-specific input items to the supplied log writer.

Overrides:

logInputsSpec in class AbstractAIProvider

Parameters:

streamWriter - destination writer

Throws:

IOException - when writing fails

embedding

public List<Double> embedding(String text,
 long dimensions)

Requests an embedding vector for the given input text.

Specified by:

embedding in interface EmbeddingProvider

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