GenAI Client 1.1.13-SNAPSHOT API
GenAI Client
GenAI Client is a Java library designed for seamless integration with Generative AI providers. It offers foundational prompt management and embedding capabilities, enabling AI-powered features across Machai modules. The library simplifies interactions with AI services, supporting advanced use cases such as semantic search, automated content generation, and intelligent project assembly within the Machanism ecosystem.
Purpose and scope
GenAI Client provides the provider-neutral integration layer used by MachAI applications to interact with large language models and related AI services without coupling application code to a specific vendor SDK, authentication flow, endpoint format, or execution strategy. It centralizes provider resolution, model selection, prompt and instruction collection, optional host-side function tools, embedding requests, and token-usage reporting.
The library is intended for request-oriented workflows. Callers resolve a concrete provider from a model identifier, initialize it with runtime configuration, add instructions, prompts, files, URLs, or logged inputs, optionally register controlled local tools, execute the request, and then aggregate the returned usage metrics.
Architecture overview
The root package org.machanism.machai.ai defines the high-level API and groups the manager, provider,
and tool infrastructure used throughout the module. Provider resolution and cross-request token accounting are handled
by org.machanism.machai.ai.manager, whose main entry point is
org.machanism.machai.ai.manager.GenaiProviderManager. The common provider contract is
org.machanism.machai.ai.provider.Genai, and shared base behavior is supplied through
AbstractAIProvider and GenaiAdapter.
Concrete providers live below org.machanism.machai.ai.provider. The OpenAI provider integrates with the
OpenAI Responses API for prompts, tools, files, and embeddings. The Claude provider adapts Anthropic message APIs for
prompt execution, web search support, and tool-call handling. The CodeMie provider authenticates with EPAM CodeMie
and delegates requests to compatible downstream providers. Tool infrastructure in
org.machanism.machai.ai.tools discovers service-loaded contributors and registers executable callbacks
with providers that support tool or function calling.
Package structure
-
org.machanism.machai.ai– root package for the provider-agnostic generative AI client API.- Defines the main integration surface for prompt execution, embedding requests, tool exposure, and usage monitoring.
- Serves as the stable entry point that insulates calling code from provider-specific client implementations.
-
org.machanism.machai.ai.manager– provider resolution and token-usage aggregation.- Resolves identifiers such as
OpenAI:gpt-4o-miniinto concrete provider classes. - Supports fully qualified provider class names, configures the selected
chatModel, and aggregates immutable usage records.
- Resolves identifiers such as
-
org.machanism.machai.ai.provider– common provider contracts and shared abstractions.- Defines initialization, instructions, prompts, files, embeddings, tool registration, execution, usage inspection, and cleanup operations.
- Provides shared base implementations and adapters for concrete backend integrations.
-
org.machanism.machai.ai.provider.openai– OpenAI integration.- Builds OpenAI Responses API requests from instructions, prompts, file references, and registered tools.
- Supports iterative tool-call execution, optional built-in tools, embedding generation, and provider usage mapping.
-
org.machanism.machai.ai.provider.claude– Anthropic Claude integration.- Uses the Anthropic Java SDK to execute message-based requests with configured Claude models.
- Supports prompt accumulation, web-search tool configuration, host-side tool execution, and usage capture.
-
org.machanism.machai.ai.provider.codemie– EPAM CodeMie integration.- Obtains OAuth 2.0 access tokens using password or client-credentials authentication.
- Configures CodeMie-hosted endpoints as downstream OpenAI-compatible or Anthropic-compatible providers.
-
org.machanism.machai.ai.tools– service-provider infrastructure for function tools.- Defines tool contributor and executable callback contracts.
- Uses Java
ServiceLoaderdiscovery to apply configured host capabilities to compatible providers.
Configuration and runtime behavior
Providers are initialized from application configuration. Common settings include the selected chatModel,
provider credentials, base URLs, request timeouts, output-token limits, tool-call limits, embedding model names,
and input-log destinations. OpenAI uses properties such as OPENAI_API_KEY and
OPENAI_BASE_URL. Claude uses ANTHROPIC_API_KEY and an optional
ANTHROPIC_BASE_URL. CodeMie uses credentials such as GENAI_USERNAME,
GENAI_PASSWORD, and an optional AUTH_URL before delegating to its downstream endpoint.
Tool registration is separate from provider creation. This allows applications to expose local capabilities only for the requests that need them and only for providers that support tool execution. Tool implementations may access host resources, call remote endpoints, or perform domain-specific operations, so production deployments should configure and restrict them deliberately.
Typical workflow
- Resolve a provider using a model identifier such as
OpenAI:gpt-4o-mini,Claude:claude-3-5-sonnet, or a fully qualified provider class name. - Initialize the provider with application configuration so credentials, endpoints, limits, and model settings are available.
- Optionally apply service-loaded host tools through
FunctionToolsLoader. - Supply system instructions, prompts, and optional file, URL, or logged-input data.
- Execute the request, consume the generated response or embeddings, and record usage metrics.
Configurator conf = ...;
Genai provider = GenaiProviderManager.getProvider("OpenAI:gpt-4o-mini", conf);
FunctionToolsLoader tools = FunctionToolsLoader.getInstance();
tools.setConfiguration(conf);
tools.applyTools(provider);
provider.instructions("You are a helpful assistant.");
provider.prompt("Summarize this repository.");
String answer = provider.perform();
GenaiProviderManager.addUsage(provider.usage());
GenaiProviderManager.logUsage();
Usage notes
- Provider instances are mutable and should generally be treated as request-scoped objects rather than shared singletons.
- Capability support varies by provider; embeddings, built-in tools, and tool-calling semantics depend on the selected backend.
- Aggregated usage reporting in the manager layer helps track total input, cached input, and output token consumption across multiple requests.
- Configuration values may contain placeholders such as ${...}; those placeholders must remain available for runtime substitution.