GenAI Client 1.1.0 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 a provider-agnostic API for composing prompts, supplying system instructions, optionally attaching files, and executing requests against multiple GenAI backends. Consumers can select a backend by configuration (typically using a Provider:Model identifier) rather than binding directly to a vendor SDK.

Architecture overview

The central provider contract is defined by org.machanism.machai.ai.provider.Genai. Provider resolution, instantiation, and usage aggregation are handled by org.machanism.machai.ai.manager.GenaiProviderManager. Concrete provider implementations adapt the shared contract to specific backends (for example OpenAI, Google Gemini, Anthropic Claude, EPAM CodeMie, and an offline no-op provider).

Providers that support tool/function calling can be augmented with host-side tools (file system, command execution, and web/REST access). Tool installers are typically discovered via java.util.ServiceLoader and applied using org.machanism.machai.ai.tools.FunctionToolsLoader.

Package structure

• org.machanism.machai.ai – provider-agnostic client API.
  • Public abstractions used by consumers to remain decoupled from provider-specific SDKs and transport/auth details.
• org.machanism.machai.ai.manager – provider contract and provider resolution.
  • Defines the Genai contract, provider selection via GenaiProviderManager, a delegating adapter, and token usage reporting via Usage.
  • Supports resolving providers via a short provider name (used in the Provider:Model format) or by fully-qualified class name.
• org.machanism.machai.ai.provider.openai – OpenAI provider implementation.
  • Builds OpenAI requests from prompts/instructions, optional file inputs, and registered tools; maps results into the common contract and usage metrics.
• org.machanism.machai.ai.provider.gemini – Google Gemini provider integration.
  • Adapts the common request model to Gemini APIs (note: some operations may be scaffolded depending on provider implementation status).
• org.machanism.machai.ai.provider.claude – Anthropic Claude provider integration.
  • Adapts the common contract to Claude models.
• org.machanism.machai.ai.provider.codemie – EPAM CodeMie provider integration.
  • Authenticates against an OpenID Connect (OIDC) token endpoint to obtain an access token, configures an OpenAI-compatible client, and delegates calls based on the configured model prefix.
• org.machanism.machai.ai.provider.none – offline/no-op provider.
  • Never calls an external model; accumulates prompts and can optionally persist them to local log files.
  • Unsupported capabilities (for example embeddings) throw UnsupportedOperationException.
• org.machanism.machai.ai.tools – host-integrated function tools.
  • Provides controlled host capabilities (file system, HTTP/REST, and command execution) to providers that support tool/function calling.
  • Tools are typically discovered via ServiceLoader and applied via FunctionToolsLoader.

Typical workflow

1. Resolve a provider for a model identifier (for example OpenAI:gpt-4o-mini).
2. Optionally apply host-side tools (file/web/command helpers) when tool calling is enabled.
3. Supply system instructions and one or more prompts (and optionally files/URLs).
4. Execute the request and record token usage.

Configurator conf = ...;

// Resolve Provider:Model (for example: "OpenAI:gpt-4o-mini").
Genai provider = GenaiProviderManager.getProvider("OpenAI:gpt-4o-mini", conf);

// Optional: expose host-side tools.
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();
Usage usage = provider.usage();
GenaiProviderManager.addUsage(usage);
GenaiProviderManager.logUsage();

Operational notes

• Provider instances are mutable and typically hold per-request state (instructions, prompts/messages, tool registrations). Prefer one provider instance per request.
• Function tools execute inside the host process. Apply them selectively and configure allow/deny checks (for example, allowed commands and allowed paths) according to your deployment environment.
• Token usage can be aggregated across invocations via GenaiProviderManager to support logging and basic cost analysis.

Packages

Package	Description
org.machanism.machai.ai	Provider-agnostic generative AI client API for MachAI.
org.machanism.machai.ai.manager	Provider-resolution and usage-tracking infrastructure for generative-AI integrations.
org.machanism.machai.ai.provider	Defines the provider abstraction layer used by MachAI to integrate with concrete generative AI services.
org.machanism.machai.ai.provider.claude	Provides Anthropic Claude integration for the MachAI generative AI abstraction layer.
org.machanism.machai.ai.provider.codemie	Provides integration with the EPAM CodeMie Code Assistant platform.
org.machanism.machai.ai.provider.gemini	Provides the Gemini-specific implementation of MachAI's provider abstraction.
org.machanism.machai.ai.provider.none	Provides a no-op Genai implementation for offline, disabled, or test-only execution paths.
org.machanism.machai.ai.provider.openai	OpenAI provider integration for MachAI.
org.machanism.machai.ai.tools	Host-side function tooling for integrating controlled local capabilities with a Genai provider.