Package org.machanism.machai.ai.tools

package org.machanism.machai.ai.tools

Contracts and runtime metadata for exposing Java capabilities as AI tools, prompts, and resources.

Types in this package are deliberately provider-neutral. An application implements the marker interface FunctionTools to group capabilities and declares those capabilities on methods with runtime-retained annotations, while a provider-specific integration discovers the annotations, describes the callable operations, validates arguments, and invokes the methods.

Declaring capabilities

• Tool marks a method as an invokable tool and requires a human-readable description; Tool.name() optionally supplies its exposed name.
• Prompt marks a method as a prompt definition and associates it with a Role; its parameters may be described with Param.
• Resource marks a method that supplies content identified by one or more URIs, such as schemas, configuration, or instruction documents.
• Param supplies runtime parameter metadata, including a name, description, and optional default value.

Provider integration

FunctionTools is the service-provider interface used to group related capabilities. FunctionToolsLoader discovers implementations with ServiceLoader, optionally filters them with SupportedFor, and registers compatible implementations with a provider. ToolFunction provides a functional abstraction for executing a tool with structured JsonNode parameters and runtime context.

Supporting types

• ParamDescriptor represents parameter metadata programmatically when an annotation is not sufficient.
• Role identifies the assistant and user conversation roles.
• ErrorResultException carries a structured, JSON-serializable tool error.
• SpecialException signals a framework-level special condition, such as the completion of a task without shutting down the host application.

Typical usage

 public final class ProjectTools implements FunctionTools {

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.
ToolFunction	Functional interface representing a tool callable by a provider during a run.