GenAI Client 1.3.3-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.

GenAI Client supports all types of project files—including source code, documentation, project site content, and other relevant files—so Machai workflows can provide requests with the context appropriate to the task.

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.

The package-level documentation follows the same separation of responsibilities: the manager package covers provider lookup and usage statistics; the provider package defines the common contracts, shared base behavior, and conversion utilities; the provider implementation package connects those contracts to remote and local backends; and the tools package defines annotations and service-provider contracts for host capabilities. Consult those package descriptions and the linked class diagram when navigating the API or designing an integration.

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. Token-usage aggregation is managed by org.machanism.machai.ai.manager.UsageStatistics with individual usage records captured via org.machanism.machai.ai.manager.Usage. 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 in org.machanism.machai.ai.provider.impl. The OpenAI provider builds response and embedding requests for OpenAI-compatible services, including tool-calling and optional built-in integrations. The Anthropic provider adapts Anthropic Beta Messages API for prompt execution, tool support, MCP server forwarding, prompt-cache control, and usage tracking. The CodeMie provider authenticates with EPAM CodeMie via OAuth 2.0 and delegates requests to OpenAIProvider or AnthropicProvider based on the configured model prefix. The ToolsProvider executes locally registered function tools directly from structured YAML prompts. 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.
  • Groups the manager, provider, and tool infrastructure used throughout the module.
  • Serves as the stable entry point that insulates calling code from provider-specific client implementations.
  • Higher-level code can resolve and configure providers, submit prompts or instructions, register callable tools and resources, request embeddings, and inspect usage statistics through stable contracts.
• org.machanism.machai.ai.manager - provider resolution and token-usage aggregation.
  • Resolves identifiers such as OpenAI:gpt-4o-mini into concrete provider classes via GenaiProviderManager, using a conventional package pattern (org.machanism.machai.ai.provider.impl.{Provider}Provider) or a fully qualified class name when the provider segment contains a dot.
  • Captures immutable per-request token counts in Usage (input, cached input, and output tokens).
  • Aggregates and logs usage totals grouped by model identifier via UsageStatistics.
• org.machanism.machai.ai.provider - common provider contracts and shared abstractions.
  • Defines the primary lifecycle and execution contract through Genai, covering initialization, prompting, instruction setting, tool and resource registration, error handling, and response generation.
  • Defines the embedding contract through EmbeddingProvider for semantic and similarity-based workflows.
  • Provides reusable base implementations (AbstractAIProvider) with shared infrastructure for timeout handling, request input logging, optional web-search support, MCP server registration, annotation-driven tool and prompt discovery, guarded tool invocation with configurable error handling, and reflective method invocation for tool and prompt callbacks.
  • Provides a delegating adapter (GenaiAdapter) for wrapper, decorator, and cross-cutting patterns such as logging, metrics, retries, or request shaping around a concrete Genai instance.
  • Includes TypeConverter for schema-compatible Java type mapping (e.g., "string", "integer", "array", "object") and runtime string conversion including collections, maps, primitives, and types with single-argument string constructors.
• org.machanism.machai.ai.provider.impl - concrete provider integrations.
  • OpenAIProvider: adapts the OpenAI Java SDK Responses API and embedding API; supports conversational prompting, function tools, MCP tools, web search, usage tracking, and embedding generation for OpenAI-compatible endpoints.
  • AnthropicProvider: adapts the Anthropic Java SDK Beta Messages API; supports message construction, local function tools, optional web search (versions 20250305 and 20260209), MCP server forwarding, prompt-cache control for the last registered tool, and usage tracking.
  • CodeMieProvider: integrates with EPAM CodeMie authentication via OAuth 2.0 (password-grant or client-credentials flow) and delegates to OpenAIProvider or AnthropicProvider based on the configured model prefix — gpt-*, gemini-*, text-embedding-*, codemie-text-embedding-*, and amazon.titan-embed-text-* prefixes route to OpenAIProvider; claude-* prefixes route to AnthropicProvider.
  • ToolsProvider: executes locally registered function tools directly from structured YAML prompts, useful for tool-only workflows and deterministic host-side execution. Operates in a fail-fast mode: exceptions from tool execution are propagated immediately rather than being returned as model text.
  • NoneProvider: supplies a disabled provider for configurations that intentionally perform no AI work; it discards submitted input and returns null, with an optional log model mode for recording activity at INFO level.
• org.machanism.machai.ai.tools - service-provider infrastructure for function tools.
  • Defines FunctionTools SPI and ToolFunction functional interface as the core tool registration contracts.
  • Provides annotations (@Tool, @Prompt, @Resource, @Param, @SupportedFor) for exposing Java methods as AI-callable tools, prompts, and resources, all retained at runtime for provider discovery, descriptor building, argument validation, and model presentation.
  • Uses Java ServiceLoader discovery via FunctionToolsLoader (through META-INF/services provider configuration) to apply configured host capabilities to compatible providers, filtered by application class via the @SupportedFor annotation.
  • Includes Role enum (ASSISTANT and USER), ParamDescriptor for programmatic parameter metadata (name, data type, required flag, description, default value), ErrorResultException for propagating a structured tool execution error, and SpecialException for framework-level control flow that signals task completion without terminating the application.

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. Anthropic 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. Configuration values may contain placeholders such as ${...}; those placeholders must remain available for runtime substitution.

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, passing the provider and the application class for compatibility filtering.
4. Supply system instructions, prompts, and optional file, URL, or logged-input data.
5. Execute the request and consume the generated response or embeddings. Usage is automatically recorded in UsageStatistics by the provider after each successful perform() call.
6. Optionally call UsageStatistics.logUsage() to log aggregated token totals grouped by model identifier.

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.
• Usage is automatically tracked in UsageStatistics by each provider implementation after a successful perform() call. Aggregated totals can be queried or logged at any time via UsageStatistics.logUsage().
• Configuration values may contain placeholders such as ${...}; those placeholders must remain available for runtime substitution.
• Use provider.clear() to reset accumulated conversation input between requests when reusing a provider instance.
• Tool implementations discovered via ServiceLoader are filtered by application class using the @SupportedFor annotation; only matching tool sets are registered with a given provider.

Packages

Package	Description
org.machanism.machai.ai.manager	Coordinates provider construction and token-usage collection for the application's generative-AI integrations.
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	Contracts and runtime metadata for exposing Java capabilities as AI tools, prompts, and resources.