{ "$schema": "https://raw.githubusercontent.com/machanism-org/bindex-core/refs/heads/main/src/main/resources/schema/bindex-schema-v2.json", "id": "org.machanism.machai:genai-client:1.4.3", "name": "org.machanism.machai:genai-client", "version": "1.4.3", "description": "GenAI Client is a Java library in the Machanism ecosystem that provides a provider-neutral API for generative AI and embedding workflows. It resolves provider/model identifiers such as OpenAI:gpt-4o-mini, initializes provider implementations, manages prompts and instructions, executes model requests, and records token usage. Supported integrations include OpenAI-compatible services, Anthropic Claude, EPAM CodeMie, local host-managed Tools, and a no-op None provider. The library supports Java functional tools through ServiceLoader and annotations, optional OpenAI web search and MCP server tools, embedding providers, configuration-driven endpoints and credentials, project-directory context, and usage statistics. It is useful for Java applications implementing AI-assisted workflows, tool orchestration, semantic search, and content generation. The artifact is built for Java 8 bytecode and is published as a Maven library.", "authors": [ { "name": "Machanism" } ], "license": "Apache License, Version 2.0", "classification": { "type": "Java library", "domains": [ "Generative AI", "Large Language Models", "AI provider integration", "Embedding generation", "Semantic search", "Function calling and tool orchestration", "Prompt management", "Application integration" ], "languages": [ { "name": "Java", "version": "8" } ], "layers": [ "Utils", "Adapters", "Infrastructure" ], "usageContext": [ "Java applications", "Maven projects", "AI-powered workflows", "Conversational AI", "Provider-independent model access", "Local function-tool orchestration", "Embedding-based retrieval and semantic search", "Applications integrating OpenAI, Anthropic, or CodeMie" ], "targetEnvironment": [ "Java" ], "integrations": [ "OpenAI", "Anthropic Claude", "EPAM CodeMie" ] }, "constructors": [ { "package": "org.machanism.machai.process.manager", "signature": "public org.machanism.machai.process.manager.ProcessProviderManager()", "description": "Utility manager for resolving and initializing ProcessProvider and EmbeddingProvider implementations dynamically from a provider/model identifier and a Configurator. It is a static utility API; applications normally call its static methods rather than instantiate it.", "examples": [ { "snippet": "org.machanism.machai.process.provider.ProcessProvider provider = org.machanism.machai.process.manager.ProcessProviderManager.getProvider(\"OpenAI:gpt-4o-mini\", configurator);", "description": "Resolve and initialize a chat provider using a Provider:Model identifier and the application's configured credentials and settings." } ] } ], "features": [ { "name": "Resolve and initialize a chat provider", "package": "org.machanism.machai.process.manager", "signature": "public static org.machanism.machai.process.provider.ProcessProvider getProvider(java.lang.String chatModel, org.machanism.macha.core.commons.configurator.Configurator conf)", "description": "Dynamically loads the provider implementation corresponding to the provider identifier in a Provider:Model string, initializes it with the model and configuration, and returns the ProcessProvider. A blank provider name returns null; an invalid or unavailable provider results in IllegalArgumentException.", "examples": [ { "snippet": "org.machanism.machai.process.provider.ProcessProvider provider = org.machanism.machai.process.manager.ProcessProviderManager.getProvider(\"OpenAI:gpt-4o-mini\", configurator);", "description": "Select the OpenAI provider and initialize it for gpt-4o-mini using a Configurator containing OPENAI_API_KEY and any optional provider settings." } ] }, { "name": "Resolve and initialize an embedding provider", "package": "org.machanism.machai.process.manager", "signature": "public static org.machanism.machai.process.provider.EmbeddingProvider getEmbeddingProvider(java.lang.String embeddingModel, org.machanism.macha.core.commons.configurator.Configurator conf)", "description": "Dynamically loads and initializes an EmbeddingProvider using a Provider:Model identifier or a fully qualified embedding implementation class name. Returns null for a blank provider name and throws IllegalArgumentException when the implementation cannot be resolved or initialized.", "examples": [ { "snippet": "org.machanism.machai.process.provider.EmbeddingProvider embeddings = org.machanism.machai.process.manager.ProcessProviderManager.getEmbeddingProvider(\"OpenAI:text-embedding-3-small\", configurator);", "description": "Initialize an embedding provider for text-embedding-3-small to generate vectors for indexing or semantic retrieval." } ] }, { "name": "Register and execute Java functional tools", "package": "org.machanism.machai.process.tools", "signature": "public void applyTools(org.machanism.machai.process.provider.ProcessProvider provider, java.lang.String[] tools, java.lang.Class appClass)", "description": "FunctionToolsLoader discovers FunctionTools implementations with Java ServiceLoader, filters by SupportedFor compatibility and optional regular-expression tool-name filters, then registers tool, prompt, and resource declarations with the provider. Implementations can expose public methods using Tool, Param, Prompt, and Resource annotations.", "examples": [ { "snippet": "org.machanism.machai.process.tools.FunctionToolsLoader loader = new org.machanism.machai.process.tools.FunctionToolsLoader();\nloader.applyTools(provider, null, com.example.application.MyProcessor.class);", "description": "After initializing a provider and registering a FunctionTools implementation in META-INF/services/org.machanism.machai.process.tools.FunctionTools, apply all compatible tools to a real application processor. Use a regular-expression array instead of null to restrict registered callable tools." } ] }, { "name": "Record and report model token usage", "package": "org.machanism.machai.process.manager", "signature": "public void addUsage(java.lang.String model, org.machanism.machai.process.manager.Usage usage)", "description": "UsageStatistics stores usage records by model identifier and supports model-specific and aggregate reporting for input, cached input, and output token counts. This supports application diagnostics and consumption reporting.", "examples": [ { "snippet": "org.machanism.machai.process.manager.UsageStatistics statistics = new org.machanism.machai.process.manager.UsageStatistics();\nstatistics.addUsage(\"gpt-4o-mini\", usage);", "description": "Record a provider usage result under its model identifier, then query the statistics object for model-level or aggregate usage reports." } ] } ], "customizations": [ { "name": "org.machanism.machai.process.tools.FunctionTools", "package": "org.machanism.machai.process.tools", "description": "Implement this service-provider interface to package custom Java capabilities for discovery and registration with compatible AI providers. Public methods can be marked with Tool, Prompt, and Resource annotations; use SupportedFor to limit a bundle to selected application classes.", "type": "interface", "examples": [ { "snippet": "public final class com.example.tools.ProjectTools implements org.machanism.machai.process.tools.FunctionTools {\n @org.machanism.machai.process.tools.Tool(name = \"project_summary\", description = \"Summarize the current project.\")\n public java.lang.String summarize(@org.machanism.machai.process.tools.Param(name = \"topic\", description = \"Project topic to summarize\") java.lang.String topic) {\n return \"Summary for: \" + topic;\n }\n}", "description": "Create a public tool bundle, provide clear model-facing parameter descriptions, and publish its fully qualified class name in the Java ServiceLoader descriptor. Validate inputs and constrain file, network, or command access in the implementation." } ] }, { "name": "org.machanism.machai.process.provider.ProcessProviderAdapter", "package": "org.machanism.machai.process.provider", "description": "Decorate a provider delegate to add application-level behavior such as logging or metrics while preserving the provider lifecycle. The adapter itself does not provide retry behavior.", "type": "class" } ], "studs": [ { "name": "org.machanism.machai.process.provider.ProcessProvider", "package": "org.machanism.machai.process.provider", "type": "interface", "description": "Provider-neutral conversational AI contract for initialization, instructions and prompt handling, tools, and model execution. Concrete implementations adapt supported AI services or provide local/no-op behavior." }, { "name": "org.machanism.machai.process.provider.EmbeddingProvider", "package": "org.machanism.machai.process.provider", "type": "interface", "description": "Provider contract for creating embedding representations from input content. Concrete provider implementations connect the common API to embedding services." }, { "name": "org.machanism.machai.process.tools.FunctionTools", "package": "org.machanism.machai.process.tools", "type": "interface", "description": "Service-provider interface that application developers implement to contribute discoverable Java tool, prompt, and resource bundles to the provider lifecycle." }, { "name": "org.machanism.machai.process.tools.ToolFunction", "package": "org.machanism.machai.process.tools", "type": "interface", "description": "Callback contract for invoking a registered tool with Jackson JSON parameters and optional runtime context objects." } ], "examples": [ { "title": "Install, configure, and run OpenAI chat with a custom Java tool", "description": "Add the library to a Maven application, provide the API credential in application configuration, publish a ServiceLoader tool bundle, resolve a provider, and apply the registered capability before executing the application workflow.", "steps": [ { "step": 1, "action": "Add the dependency", "content": "Declare org.machanism.machai:genai-client:1.4.3 as a dependency in the application's pom.xml. The library is compiled for Java 8 and also depends on provider SDKs and the Machanism Configurator artifact." }, { "step": 2, "action": "Configure credentials and optional settings", "content": "Create a Configurator populated with OPENAI_API_KEY from a securely managed environment or secret store. Optionally configure OPENAI_BASE_URL for a compatible endpoint, GENAI_TIMEOUT, MAX_OUTPUT_TOKENS, and WebSearchTool.type. Do not commit credentials to source control." }, { "step": 3, "action": "Implement and register a tool", "content": "Implement org.machanism.machai.process.tools.FunctionTools, add public methods annotated with @Tool and @Param, and list the implementation class in src/main/resources/META-INF/services/org.machanism.machai.process.tools.FunctionTools." }, { "step": 4, "action": "Initialize and apply capabilities", "content": "Call ProcessProviderManager.getProvider with OpenAI:gpt-4o-mini and the configured Configurator, then call FunctionToolsLoader.applyTools(provider, null, YourApplication.class). Set project-directory context where required and apply input validation and authorization in each tool." }, { "step": 5, "action": "Execute a real workflow", "content": "Attach the user's prompt or instructions using the provider API, invoke the provider's perform workflow, and process its response. When the model requests the registered project_summary function, the provider invokes the local method and continues the model interaction with its result." } ], "mavenDependency": { "groupId": "org.machanism.machai", "artifactId": "genai-client", "version": "1.4.3" }, "providerIdentifier": "OpenAI:gpt-4o-mini" }, { "title": "Configure OpenAI web search and MCP tools", "description": "For an OpenAI provider, optionally configure built-in web search and one or more MCP servers in the same Configurator passed to provider initialization. Set WebSearchTool.type to enable web search; configure sequential MCP groups with a name and valid URL. Store authorization secrets outside source control.", "configurationKeys": [ "WebSearchTool.type", "WebSearchTool.city", "WebSearchTool.country", "WebSearchTool.region", "MCP.url", "MCP.name", "MCP.description", "MCP.authorization", "MCP_1.url", "MCP_1.name" ] }, { "title": "Initialize an embedding provider for semantic retrieval", "description": "Resolve OpenAI:text-embedding-3-small with ProcessProviderManager.getEmbeddingProvider, submit application text through the embedding provider API, and store the resulting vectors in the application's chosen retrieval index for later similarity search." } ], "dependencies": [ "org.machanism.macha.core.commons:configurator:0.0.14", "com.openai:openai-java:4.105.0", "com.anthropic:anthropic-java:2.75.0", "com.github.victools:jsonschema-generator:4.38.0", "org.apache.commons:commons-lang3", "org.apache.commons:commons-text:1.15.0", "org.slf4j:slf4j-api", "org.slf4j:slf4j-simple" ], "location": { "repositoryType": "Maven", "repositoryUrl": "https://central.sonatype.com/artifact/org.machanism.machai/genai-client", "coordinates": { "group": "org.machanism.machai", "artifactId": "genai-client", "version": "1.4.3", "extension": "jar" } } }