GenAI Client
Overview
GenAI Client is a Java library for integrating Machai applications with generative AI platforms through a consistent provider abstraction. It provides prompt and instruction handling, provider resolution, runtime configuration, embedding support, usage tracking, and Java function-tool registration for AI-powered workflows.
The library is organized around the common Genai lifecycle contract and shared provider infrastructure. Applications can resolve a configured provider from model identifiers such as OpenAI:gpt-4o-mini, attach prompts, system instructions, files, tools, web-search support, or MCP servers, and execute requests without depending directly on vendor-specific SDK details. Token usage is captured in immutable usage records and can be aggregated per model for reporting and diagnostics.
GenAI Client also includes a lightweight tool metadata layer. Java methods annotated as tools or prompts can be discovered through ServiceLoader, described with parameter metadata, filtered for supported application classes, and registered with providers as AI-callable functions. This enables advanced use cases such as semantic search, automated content generation, intelligent project assembly, structured tool execution, local tool orchestration, and provider-independent prompt workflows.
The main package areas are:
org.machanism.machai.ai.managerresolves configured provider identifiers, initializes provider instances, and records token usage by model.org.machanism.machai.ai.providerdefines the common provider contracts and reusable base behavior for conversational, embedding, tool-enabled, web-search-enabled, and MCP-enabled AI integrations.org.machanism.machai.ai.provider.implcontains concrete provider implementations for OpenAI-compatible APIs, Anthropic Claude, CodeMie, and direct host-side tool execution.org.machanism.machai.ai.toolsdefines annotations, descriptors, loading utilities, prompt roles, and callback contracts used to expose Java methods as AI-accessible tools and reusable prompts.
Supported AI providers
OpenAI
The OpenAI provider adapts the Machai Genai API to the OpenAI Java SDK Responses API and Embeddings API. It supports conversational text generation, file-based inputs, iterative function-tool calling, optional OpenAI web search, MCP server tools, embeddings, request input logging, and OpenAI usage conversion.
Typical configuration includes an OpenAI API key, a chat or embedding model name, and optional values such as a custom OpenAI-compatible base URL, timeout, maximum output tokens, and tool-call limits. It can also be used with OpenAI-compatible endpoints by overriding the base URL.
Anthropic
The Anthropic provider adapts the Machai Genai API to Anthropic Claude models through the Anthropic Java SDK Messages API. It supports prompt execution, system instructions, custom function tools, automatic tool-use loops, optional web search, MCP server forwarding, Anthropic-specific prompt caching for large tool results, and token-usage capture.
Typical configuration includes an Anthropic API key or authorization token, a Claude model identifier, and optional values such as a custom base URL, timeout, output-token limits, tool-call limits, and prompt-cache thresholds.
CodeMie
The CodeMie provider integrates with EPAM CodeMie Code Assistant endpoints. It authenticates with a CodeMie OpenID Connect token endpoint, obtains OAuth 2.0 bearer tokens, configures the delegated AI provider with the CodeMie API base URL, and routes supported model families to the appropriate implementation.
OpenAI-compatible, Gemini-compatible, and embedding model identifiers are delegated to the OpenAI provider configured for CodeMie endpoints. Claude-compatible model identifiers are delegated to the Anthropic provider. The provider supports password-grant and client-credentials authentication flows based on the supplied username, client identifier, password, or client secret.
Tools provider
The Tools provider exposes registered application functions for structured invocation. It collects prompts, registers ToolFunction callbacks, and executes those callbacks from YAML-based tool-call descriptions containing a tool name and parameter payload. This provider is useful for internal orchestration when host-defined tools need to be invoked through the same lifecycle as other AI providers without sending the request to an external model service.
Common configuration parameters
| Parameter | Description | Default value |
|---|---|---|
chatModel |
Model identifier used by the selected provider. Provider resolution commonly uses identifiers in the Provider:Model form, such as OpenAI:gpt-4o-mini. |
Required |
OPENAI_API_KEY |
API key for OpenAI or OpenAI-compatible endpoints. CodeMie sets this to the retrieved OAuth 2.0 bearer token for delegated OpenAI-compatible requests. | Required for OpenAI-compatible providers |
OPENAI_BASE_URL |
Optional base URL override for OpenAI-compatible APIs. | OpenAI SDK default |
ANTHROPIC_API_KEY |
API key or authorization token for Anthropic Claude requests. | Required for Anthropic |
ANTHROPIC_BASE_URL |
Optional base URL override for Anthropic-compatible APIs. | Anthropic SDK default |
GENAI_TIMEOUT |
Request timeout in seconds. A value of 0 or an absent value leaves SDK defaults in effect. |
0 |
MAX_OUTPUT_TOKENS |
Maximum number of tokens the model may generate. | 18000 |
MAX_TOOL_CALLS |
Maximum number of tool calls the model may issue in a response loop. A value of 0 leaves the provider limit unset. |
0 |
logInputs |
Enables logging of provider request inputs when an input log file is configured by the caller. | Not enabled |
WebSearchTool.type |
Enables provider-specific web search when present. The value default maps to the provider default web-search tool type where supported. |
Not set |
WebSearchTool.city |
Optional city hint for web-search user location. | Not set |
WebSearchTool.country |
Optional country hint for web-search user location. | Not set |
WebSearchTool.region |
Optional region hint for web-search user location. | Not set |
MCP.url |
URL for the first MCP server tool. Additional servers can be configured with numbered groups such as MCP_1.url, MCP_2.url, and so on. |
Not set |
MCP.name |
Provider-visible MCP server name. Additional servers can use MCP_1.name, MCP_2.name, and so on. |
Not set |
MCP.authorization |
Optional authorization value for the MCP server. Additional servers can use numbered variants. | Not set |
MCP.description |
Optional MCP server description. Additional servers can use numbered variants. | Not set |
cacheThreshold |
Anthropic-specific threshold for applying ephemeral prompt caching to large tool results. | Provider default |
GENAI_USERNAME |
Generic username used by provider authentication flows. CodeMie can use it for password-grant authentication. | Provider-specific |
GENAI_PASSWORD |
Generic password or secret used by provider authentication flows. CodeMie can use it as a password or client secret. | Provider-specific |
genai.serverId |
Optional GenAI server identifier used by shared provider configuration. | Not set |