Package org.machanism.machai.ai.provider

package 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.

This package contains the core contracts, shared infrastructure, and utility types for AI providers, including request initialization, prompt and instruction handling, tool registration, resource registration, embedding generation, usage tracking, input logging, and working-directory propagation. It establishes the common behavior that allows higher-level application code to interact with different model vendors without depending on provider-specific SDK details.

Core contracts

  • Genai defines the primary lifecycle and execution contract for conversational and tool-enabled AI providers, covering initialization, prompting, instruction setting, tool and resource registration, error handling configuration, and response generation.
  • EmbeddingProvider defines the contract for providers that can generate embedding vectors for semantic and similarity-based workflows.

Base and adapter implementations

  • AbstractAIProvider supplies reusable base behavior for configuration-driven providers, including 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.
  • GenaiAdapter provides a delegating implementation for the Genai lifecycle and request operations. It enables wrapper, adapter, and decorator patterns such as cross-cutting logging, metrics, retries, or request shaping around a concrete Genai instance.

Support utilities

  • TypeConverter provides conversion between Java types and their simplified schema-compatible string representations (e.g., "string", "integer", "array", "object"), and performs runtime conversion of string inputs to typed Java objects—including collections, maps, primitives, and arbitrary types with single-argument string constructors.

Concrete provider implementations

The org.machanism.machai.ai.provider.impl sub-package contains concrete provider adapters that connect Machai's common AI interfaces to specific runtime backends:

  • OpenAIProvider adapts the OpenAI Responses API and embedding API, supporting conversational prompting, function tools, MCP tools, web search, usage tracking, and embedding generation for OpenAI-compatible endpoints.
  • AnthropicProvider adapts the Anthropic Claude Beta Messages API, supporting function tools, optional web search, MCP server forwarding, prompt-cache control, and usage tracking.
  • CodeMieProvider integrates with EPAM CodeMie authentication and delegates to the appropriate downstream provider (OpenAIProvider or AnthropicProvider) based on the configured model prefix.
  • ToolsProvider executes locally registered function tools directly from structured YAML prompts, useful for tool-only workflows and deterministic host-side execution.
  • NoneProvider provides a disabled implementation for configurations that intentionally perform no AI work. It discards submitted input and returns null; initializing it with the "log" model enables INFO-level diagnostic logging.

Typical usage

Application code typically resolves a concrete provider, initializes it with runtime configuration and a model identifier, optionally adds instructions, prompts, tools, resources, and file context, and then invokes the common API to perform generation or embedding operations. Providers are stateful during a request-building session: call Genai.clear() before starting an independent conversation on a reusable instance. Provider-specific configuration, credentials, endpoints, timeouts, and feature flags are read from the supplied Configurator; usage information, when supported by the backend, is maintained by the concrete provider implementation.

 Configurator conf = ...;
 Genai provider = new OpenAIProvider();
 provider.init("gpt-4.1", conf);
 provider.instructions("You are a helpful assistant.");
 provider.prompt("Summarize the project architecture.");
 String answer = provider.perform();
 provider.clear();
  • Class
    Description
    AbstractAIProvider
    Base implementation of the Genai contract shared by concrete provider integrations.
    EmbeddingProvider
    EmbeddingProvider defines the contract for AI embedding providers.
    Genai
    Contract for a generative-AI provider integration.
    GenaiAdapter
    Delegating Genai implementation.
    ToolLogger
    Internal logging utility for tool inputs, results, and execution errors.
    ToolLogger.Type
    Defines the types of operations whose activity can be logged.
    TypeConverter
    Utility class for converting between Java types and their string representations, as well as mapping Java types to simplified type names (e.g., "string", "integer", "array").