GenAI Client 1.2.1-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. The library simplifies interactions with AI services, supporting advanced use cases such as semantic search, automated content generation, and intelligent project assembly.

Purpose and scope

GenAI Client provides the provider-agnostic 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 model. It centralizes provider resolution, model selection, prompt and instruction collection, optional host-side function tools, embedding requests, and token-usage reporting.

The library is designed for request-scoped workflows. Applications resolve a concrete provider from a model identifier, initialize it with runtime configuration, add instructions, prompts, files, or URLs, optionally register controlled local tools, execute the request, and then aggregate usage metrics for logging and monitoring.

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, with shared base behavior supplied through org.machanism.machai.ai.provider.AbstractAIProvider and org.machanism.machai.ai.provider.GenaiAdapter.

Concrete providers live below org.machanism.machai.ai.provider. The OpenAI provider builds response and embedding requests for OpenAI-compatible services, including tool-calling and optional built-in integrations. The Claude provider adapts Anthropic message APIs for prompt execution, tool support, and usage tracking. 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-neutral 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-mini into concrete provider classes.
  • Applies the selected model to runtime configuration and aggregates immutable usage records for reporting.
• 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 reusable base implementations and adapters for concrete backend integrations.
• org.machanism.machai.ai.client.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, MCP integration, embedding generation, and usage mapping.
• org.machanism.machai.ai.client.anthropic - Anthropic Claude integration.
  • Uses the Anthropic Java SDK to execute message-based requests with configured Claude models.
  • Supports prompt accumulation, tool execution, and provider usage capture.
• org.machanism.machai.ai.client.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 ServiceLoader discovery 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

1. 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.
2. Initialize the provider with application configuration so credentials, endpoints, limits, and model settings are available.
3. Optionally apply service-loaded host tools through FunctionToolsLoader.
4. Supply system instructions, prompts, and optional file, URL, or logged-input data.
5. Execute the request, consume the generated response or embeddings, and record usage metrics.

Example API usage: 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.

Packages

Package	Description
org.machanism.machai.ai	Provides Machai's AI integration layer, including provider abstractions, provider implementations, provider lifecycle management, usage accounting, and function-tool metadata used during model-assisted workflows.
org.machanism.machai.ai.manager	Provides management utilities and data structures for working with generative AI providers and their token-usage metrics.
org.machanism.machai.ai.provider	Defines the provider abstraction layer used by Machai to integrate with concrete generative AI platforms through a consistent application-facing API.
org.machanism.machai.ai.provider.impl	Provides concrete implementations of the Machai generative AI provider abstraction.
org.machanism.machai.ai.tools	Defines the annotation model and runtime contracts used to expose Java methods and service-provider implementations as AI-accessible tools and prompts.