Package org.machanism.machai.process.tools

package org.machanism.machai.process.tools

Declares the provider-neutral metadata and execution contracts used to expose application methods as tools, prompts, and resources.

This package separates capability declaration from provider-specific integration. Runtime-retained annotations describe reflective methods and parameters, while the interfaces and exceptions support programmatic registration and invocation. A provider is responsible for interpreting the metadata, validating and converting arguments, invoking methods, and serializing results.

Capability declarations

• Tool marks a method as an invokable operation. Its required description documents the operation; its optional name defaults to Tool.NOT_DEFINED.
• Prompt marks a method that produces a prompt and supplies its name, description, and Role. The default role is Role.USER.
• Resource marks a method that supplies content under one or more URI identifiers. Its description and optional MIME type help a provider decide how to publish and interpret that content.
• Param adds a name, description, and optional default value to a method parameter. ParamDescriptor provides equivalent metadata for programmatic registration and translates the Param.NULL and Param.NOT_DEFINED string sentinels to null where applicable.

Annotation metadata is available at runtime for provider integrations. The NOT_DEFINED constants in Tool, Prompt, Resource, and Param represent omitted metadata; integrations should apply their own schema rules instead of presenting those sentinel values as user-facing names, descriptions, or MIME types.

Discovery and registration

FunctionTools is a marker service-provider interface for a class that groups related tools, prompts, and resources. Publish an implementation's fully qualified class name in META-INF/services/org.machanism.machai.process.tools.FunctionTools for discovery through ServiceLoader. FunctionToolsLoader also reads the legacy descriptor name used by earlier releases. When FunctionToolsLoader.applyTools(org.machanism.machai.process.provider.ProcessProvider, String[], Class) is called, each discovered compatible implementation is passed to the provider for tool, prompt, and resource registration in discovery order. Implementations are not deduplicated.

SupportedFor controls compatibility with the requested application class. An absent annotation, or an annotation whose included-class list is empty, permits every class. Otherwise, the application class must be assignable to at least one included class. A matching class in SupportedFor.excludes() always vetoes the match.

Execution and failure handling

ToolFunction is the functional callback for programmatic tool execution. Its ToolFunction.apply(com.fasterxml.jackson.databind.JsonNode, Object[]) method receives a JSON parameter tree and optional context objects, such as a working-directory File or a Configurator, and may throw an exception. ErrorResultException carries a structured payload in its message and serializes non-string payloads as JSON when possible. ToolExecutionException represents a checked tool failure, whereas SpecialException signals completion of the current task without requiring the host application to terminate. Providers remain responsible for catching, presenting, and mapping these failures to their own protocols.

Example

 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 loadProjectResource(path);
     }
 }
 

Keep published tool names, resource URI identifiers, and descriptions stable when consumers depend on them. Document the context object types that each ToolFunction callback expects, and ensure service descriptors are packaged with their implementations.

Class	Description
ErrorResultException	A runtime exception used to signal a tool or processing error, with a structured error payload that is serialized to JSON and included in the exception message.
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.
Resource	Annotation used to declare a method as an executable resource provider within the generative-AI tools system.
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.
ToolExecutionException	Indicates that a tool callback could not complete its requested operation.
ToolFunction	Functional interface representing a tool callable by a provider during a run.