{ "$schema": "https://raw.githubusercontent.com/machanism-org/machai/refs/heads/main/bindex-core/src/main/resources/schema/bindex-schema-v2.json", "id": "org.machanism.machai:genai-client:1.2.0-SNAPSHOT", "name": "org.machanism.machai:genai-client", "version": "1.2.0-SNAPSHOT", "description": "GenAI Client is a Java library for provider-agnostic integration with generative AI services in Machai applications. It provides prompt management, system instruction handling, file and URL input support, embedding requests, host-side function tools, provider lifecycle management, dynamic provider resolution, and token usage accounting. The API centers on the org.machanism.machai.ai.provider.Genai contract, shared provider abstractions, concrete OpenAI, Anthropic Claude, and EPAM CodeMie provider implementations, and a manager layer that resolves model identifiers such as OpenAI:gpt-4o-mini or Claude:claude-3-5-sonnet into initialized providers. It is intended for request-scoped workflows where applications configure credentials, endpoints, models, limits, and optional tools, execute model requests, consume generated text or embeddings, and aggregate immutable usage metrics for logging and monitoring. The library supports semantic search, automated content generation, intelligent project assembly, controlled tool calling through Java ServiceLoader-discovered FunctionTools, and integration with OpenAI-compatible, Anthropic-compatible, and CodeMie-hosted AI endpoints.", "authors": [ { "name": "Viktor Tovstyi", "email": "viktor.tovstyi@gmail.com", "website": "https://machanism.org" } ], "license": "Apache License, Version 2.0", "classification": { "type": "library", "domains": [ "Generative AI", "Large Language Model Integration", "Prompt Management", "Embeddings", "Semantic Search", "AI Tool Calling", "Provider Abstraction", "Token Usage Monitoring" ], "languages": [ { "name": "Java", "version": "8" } ], "layers": [ "Adapters", "Infrastructure", "Utils" ], "usageContext": [ "Java applications that need provider-neutral access to large language models", "Machai modules that execute prompts, collect instructions, request embeddings, and report usage", "Applications that expose controlled local Java methods as AI-accessible function tools", "Request-scoped AI workflows requiring configurable credentials, base URLs, model names, output limits, and tool-call limits" ], "targetEnvironment": [ "Java" ], "integrations": [ "OpenAI", "Anthropic Claude", "EPAM CodeMie" ] }, "location": { "repositoryType": "Maven", "repositoryUrl": "https://repo1.maven.org/maven2/", "coordinates": { "group": "org.machanism.machai", "artifactId": "genai-client", "version": "1.2.0-SNAPSHOT", "extension": "jar" } }, "constructors": [ { "package": "org.machanism.machai.ai.manager", "signature": "static org.machanism.machai.ai.provider.Genai getProvider(java.lang.String model, org.machanism.macha.core.commons.config.Configurator conf)", "description": "Creates and initializes a concrete generative AI provider from a model identifier or fully qualified provider class name. The manager resolves identifiers such as OpenAI:gpt-4o-mini, Claude:claude-3-5-sonnet, CodeMie:, or a provider class name, applies the selected model to runtime configuration, and returns the request-scoped Genai implementation.", "examples": [ { "snippet": "org.machanism.macha.core.commons.config.Configurator conf = null;\norg.machanism.machai.ai.provider.Genai provider = org.machanism.machai.ai.manager.GenaiProviderManager.getProvider(\"OpenAI:gpt-4o-mini\", conf);\nprovider.instructions(\"You are a helpful assistant.\");\nprovider.prompt(\"Summarize this repository.\");\njava.lang.String answer = provider.perform();\norg.machanism.machai.ai.manager.GenaiProviderManager.addUsage(provider.usage());", "description": "Resolves an OpenAI-backed provider for a single request, supplies instructions and a prompt, runs the model, and records token usage. Replace the null Configurator with the application configuration that provides credentials, endpoints, limits, and model settings." } ] }, { "package": "org.machanism.machai.ai.tools", "signature": "static org.machanism.machai.ai.tools.FunctionToolsLoader getInstance()", "description": "Obtains the singleton loader that discovers FunctionTools implementations through Java ServiceLoader and applies configured host capabilities to providers that support function or tool calling.", "examples": [ { "snippet": "org.machanism.machai.ai.tools.FunctionToolsLoader loader = org.machanism.machai.ai.tools.FunctionToolsLoader.getInstance();\norg.machanism.macha.core.commons.config.Configurator conf = null;\nloader.setConfiguration(conf);\norg.machanism.machai.ai.provider.Genai provider = org.machanism.machai.ai.manager.GenaiProviderManager.getProvider(\"Claude:claude-3-5-sonnet\", conf);\nloader.applyTools(provider);", "description": "Discovers service-loaded tool contributors, configures the loader, creates a Claude provider, and installs available tools before prompts are executed." } ] } ], "features": [ { "package": "org.machanism.machai.ai.provider", "name": "Genai.perform", "signature": "java.lang.String perform() throws java.io.IOException", "description": "Executes the accumulated request for a provider after instructions, prompts, files, URLs, logged inputs, and optional function tools have been registered. Concrete providers map this common call to their backend execution model and return the generated response text.", "examples": [ { "snippet": "org.machanism.macha.core.commons.config.Configurator conf = null;\norg.machanism.machai.ai.provider.Genai provider = org.machanism.machai.ai.manager.GenaiProviderManager.getProvider(\"OpenAI:gpt-4o-mini\", conf);\nprovider.instructions(\"Answer concisely.\");\nprovider.prompt(\"Explain the purpose of provider abstraction in one paragraph.\");\njava.lang.String result = provider.perform();", "description": "Shows the standard request-scoped workflow: resolve a provider, add instructions and a prompt, and invoke perform to obtain generated text." } ] }, { "package": "org.machanism.machai.ai.provider", "name": "EmbeddingProvider.embedding", "signature": "java.util.List embedding(java.lang.String input)", "description": "Requests vector embeddings from an AI embedding provider. The embedding contract supports semantic search and embedding-powered workflows when the selected backend supports embedding generation.", "examples": [ { "snippet": "org.machanism.macha.core.commons.config.Configurator conf = null;\norg.machanism.machai.ai.provider.EmbeddingProvider embeddings = org.machanism.machai.ai.manager.GenaiProviderManager.getEmbeddingProvider(\"OpenAI:text-embedding-3-small\", conf);\njava.util.List vector = embeddings.embedding(\"GenAI Client provider-neutral prompt execution\");", "description": "Creates an embedding provider with application configuration and generates a vector suitable for semantic search or similarity matching." } ] }, { "package": "org.machanism.machai.ai.manager", "name": "GenaiProviderManager.usage accounting", "signature": "static void addUsage(org.machanism.machai.ai.manager.Usage usage)", "description": "Adds immutable token usage metrics from a provider interaction to the manager-level aggregate registry. Usage reporting helps track total input, cached input, and output token consumption across multiple requests.", "examples": [ { "snippet": "org.machanism.machai.ai.provider.Genai provider = null;\norg.machanism.machai.ai.manager.GenaiProviderManager.addUsage(provider.usage());\norg.machanism.machai.ai.manager.GenaiProviderManager.logUsage();", "description": "After a provider request completes, capture the provider usage object and log aggregate token statistics for monitoring." } ] }, { "package": "org.machanism.machai.ai.tools", "name": "FunctionToolsLoader.applyTools", "signature": "void applyTools(org.machanism.machai.ai.provider.Genai provider)", "description": "Applies discovered FunctionTools implementations to a provider. Tool registration is separate from provider creation so applications can expose local capabilities only for requests that need them and only for providers that support tool execution.", "examples": [ { "snippet": "org.machanism.machai.ai.tools.FunctionToolsLoader tools = org.machanism.machai.ai.tools.FunctionToolsLoader.getInstance();\norg.machanism.macha.core.commons.config.Configurator conf = null;\ntools.setConfiguration(conf);\norg.machanism.machai.ai.provider.Genai provider = org.machanism.machai.ai.manager.GenaiProviderManager.getProvider(\"OpenAI:gpt-4o-mini\", conf);\ntools.applyTools(provider);\nprovider.prompt(\"Use available tools only when necessary.\");\njava.lang.String answer = provider.perform();", "description": "Configures the FunctionToolsLoader, installs host tools into an OpenAI provider, and executes a prompt that may invoke those tools." } ] } ], "customizations": [ { "name": "FunctionTools", "package": "org.machanism.machai.ai.tools", "description": "Service-provider interface for installing host-provided function tools. Implementations are discovered with Java ServiceLoader and can expose controlled host capabilities to compatible AI providers.", "type": "interface", "examples": [ { "snippet": "// 1. Add dependency:\n// org.machanism.machaigenai-client1.2.0-SNAPSHOT\n// 2. Implement org.machanism.machai.ai.tools.FunctionTools in your application.\n// 3. Register the implementation in META-INF/services/org.machanism.machai.ai.tools.FunctionTools.\n// 4. Load and apply it:\norg.machanism.machai.ai.tools.FunctionToolsLoader loader = org.machanism.machai.ai.tools.FunctionToolsLoader.getInstance();\nloader.applyTools(provider);", "description": "Step-by-step ServiceLoader scenario for adding host-defined tools to model requests." } ] }, { "name": "Tool and Prompt annotations", "package": "org.machanism.machai.ai.tools", "description": "Annotations used to mark Java methods and parameters as AI-accessible tool functions or prompt-producing methods. Param, ParamDescriptor, Tool, Prompt, SupportedFor, and Role provide metadata used during tool and prompt exposure.", "type": "annotation model" } ], "studs": [ { "name": "org.machanism.machai.ai.provider.Genai", "package": "org.machanism.machai.ai.provider", "type": "interface", "description": "Contract for a generative-AI provider integration. It defines initialization, instruction and prompt accumulation, file and URL handling, embedding-related operations where supported, tool registration, execution, usage inspection, and cleanup operations.", "implement": "org.machanism.machai.ai.provider.AbstractAIProvider" }, { "name": "org.machanism.machai.ai.provider.EmbeddingProvider", "package": "org.machanism.machai.ai.provider", "type": "interface", "description": "Contract for AI embedding providers that produce vector representations for input text and support semantic search or similarity workflows." }, { "name": "org.machanism.machai.ai.tools.FunctionTools", "package": "org.machanism.machai.ai.tools", "type": "interface", "description": "SPI for host-provided function tool contributors discovered through Java ServiceLoader and applied to compatible Genai providers." }, { "name": "org.machanism.machai.ai.tools.ToolFunction", "package": "org.machanism.machai.ai.tools", "type": "interface", "description": "Functional interface representing a tool callable by a provider during a run." }, { "name": "org.machanism.machai.ai.provider.AbstractAIProvider", "package": "org.machanism.machai.ai.provider", "type": "abstract class", "description": "Base implementation of the Genai contract shared by concrete provider integrations, providing reusable behavior for provider implementations.", "implement": "org.machanism.machai.ai.provider.impl.OpenAIProvider" } ], "examples": [ { "title": "Install and execute a prompt with an OpenAI-compatible provider", "steps": [ "Add the Maven dependency org.machanism.machai:genai-client:1.2.0-SNAPSHOT to the application.", "Provide runtime configuration values such as OPENAI_API_KEY, OPENAI_BASE_URL when needed, selected chat model, request timeout, output-token limit, and tool-call limit.", "Resolve a provider using org.machanism.machai.ai.manager.GenaiProviderManager.getProvider with a model identifier such as OpenAI:gpt-4o-mini.", "Add system instructions and a prompt, invoke perform, then collect usage metrics." ], "snippet": "org.machanism.macha.core.commons.config.Configurator conf = null;\norg.machanism.machai.ai.provider.Genai provider = org.machanism.machai.ai.manager.GenaiProviderManager.getProvider(\"OpenAI:gpt-4o-mini\", conf);\nprovider.instructions(\"You are a helpful assistant for repository analysis.\");\nprovider.prompt(\"Summarize the public API of this project.\");\njava.lang.String answer = provider.perform();\norg.machanism.machai.ai.manager.GenaiProviderManager.addUsage(provider.usage());\norg.machanism.machai.ai.manager.GenaiProviderManager.logUsage();", "description": "Practical end-to-end prompt execution scenario for a request-scoped OpenAI provider." }, { "title": "Use ServiceLoader-discovered function tools in a request", "steps": [ "Implement org.machanism.machai.ai.tools.FunctionTools in the host application.", "Register the implementation in META-INF/services/org.machanism.machai.ai.tools.FunctionTools.", "Create a provider with GenaiProviderManager.", "Configure FunctionToolsLoader and apply tools to the provider before calling perform." ], "snippet": "org.machanism.macha.core.commons.config.Configurator conf = null;\norg.machanism.machai.ai.provider.Genai provider = org.machanism.machai.ai.manager.GenaiProviderManager.getProvider(\"Claude:claude-3-5-sonnet\", conf);\norg.machanism.machai.ai.tools.FunctionToolsLoader tools = org.machanism.machai.ai.tools.FunctionToolsLoader.getInstance();\ntools.setConfiguration(conf);\ntools.applyTools(provider);\nprovider.instructions(\"Use host tools only when they are relevant.\");\nprovider.prompt(\"Inspect the configured project context and propose next actions.\");\njava.lang.String response = provider.perform();", "description": "Demonstrates how to configure and run a provider with host-side function tools available to the AI interaction." } ], "dependencies": [ "org.machanism.macha.core.commons:configurator:0.0.12-SNAPSHOT", "com.openai:openai-java:4.19.0", "com.anthropic:anthropic-java:2.32.0", "com.github.victools:jsonschema-generator:4.38.0", "org.apache.commons:commons-lang3:3.20.0", "org.apache.commons:commons-text:1.15.0", "org.slf4j:slf4j-api:2.0.17" ] }