Package org.machanism.machai.ai.tools

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

This package provides lightweight metadata annotations for describing callable capabilities, including tool methods, prompts, and their parameters. The metadata is retained at runtime so provider implementations can discover annotated methods, build tool or prompt descriptors, validate invocation arguments, and present clear descriptions to an AI model or orchestration layer.

Tool installation is centered on the FunctionTools service-provider interface and FunctionToolsLoader. Implementations can be discovered through Java's ServiceLoader mechanism and registered with a provider. The optional SupportedFor annotation limits a tool set to specific application classes when a capability should only be available in selected runtime contexts.

Direct executable tool callbacks can be represented by ToolFunction, which receives structured JSON invocation parameters, the current project directory, and configuration data. Parameter metadata may also be represented programmatically with ParamDescriptor. Conversation prompt roles are modeled by Role, and SpecialException is available for framework-level control flow that should end a task without stopping the hosting application.

Typical usage

 public final class ProjectTools implements FunctionTools {
     @Tool(description = "Reads a project resource by relative path.")
     public String readResource(
             @Param(description = "Path relative to the project root.") String path) {
         return "resource content";
     }

     @Prompt(description = "Creates a short project summary.", role = Role.ASSISTANT)
     public String summarizeProject() {
         return "Summarize the current project structure and key files.";
     }
 }
 

Classes in this package are intentionally small and framework-oriented. They define stable contracts and descriptive metadata while leaving provider-specific discovery, serialization, validation, and invocation behavior to higher-level components.

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

Class	Description
FunctionTools	Service-provider interface (SPI) for installing host-provided function tools.
FunctionToolsLoader	Discovers and applies FunctionTools implementations using Java's ServiceLoader mechanism.
Param	Annotation to mark a method parameter marked as a Tool or Prompt parameter within the AI provider framework.
ParamDescriptor	Descriptor for a parameter used in tool or prompt definitions within the AI provider framework.
Prompt	Annotation to mark a method as a prompt within the AI provider framework.
Role	Enumeration representing participant roles in an AI interaction context.
SpecialException	Exception used to signal the end of a task without terminating the application.
SupportedFor	Indicates which application classes a FunctionTools implementation supports.
Tool	Annotation to mark a method as a tool function within the AI provider framework.
ToolFunction	Functional interface representing a tool callable by a provider during a run.