Package org.machanism.machai.process.tools


package org.machanism.machai.process.tools
Defines the provider-neutral API for declaring, discovering, registering, and executing application capabilities as tools, prompts, and resources.

The package is intentionally divided into three cooperating layers:

Declaring capabilities

Annotate public or otherwise discoverable methods with Tool for invokable operations, Prompt for prompt-producing methods, or Resource for content identified by one or more URIs. Each annotation requires a description. Names and MIME types use a package-defined NOT_DEFINED sentinel when omitted; integrations should interpret that sentinel according to their own naming and schema rules rather than exposing it to consumers. A Prompt also declares a Role, defaulting to Role.USER. Annotate method parameters with Param when their names, descriptions, or default values must be published as input metadata.

ParamDescriptor is the programmatic counterpart to Param. Its ParamDescriptor.getDescription() and ParamDescriptor.getDefaultValue() methods translate the Param.NULL and Param.NOT_DEFINED string sentinels to null where applicable. Providers remain responsible for validating declarations, converting input values, invoking methods, and serializing returned values.

Discovery and compatibility

Implement FunctionTools in a class that groups related annotated methods, then publish the implementation's fully qualified class name in META-INF/services/org.machanism.machai.process.tools.FunctionTools. FunctionToolsLoader also accepts the legacy descriptor name used by earlier releases. When FunctionToolsLoader.applyTools(org.machanism.machai.process.provider.ProcessProvider, String[], Class) is called, compatible implementations are passed to the provider for tool, prompt, and resource registration in discovery order. The loader does not deduplicate implementations.

SupportedFor narrows registration to application classes. With no annotation, or with an empty SupportedFor.value() array, an implementation is compatible with every application class. Otherwise, the requested application class must be assignable to at least one included class. A class assignable from the requested application class in SupportedFor.excludes() vetoes an otherwise valid match. The value and excludes arrays therefore allow both positive and negative compatibility rules.

Executing tools and handling outcomes

Use ToolFunction when a provider needs a programmatic callback rather than reflective method invocation. 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. ToolFunction.SESSION_ID_PARAM_NAME defines the standard session identifier key.

Throw ErrorResultException when a structured payload should be returned through an exception message; non-string payloads are serialized as JSON when possible. Use ToolExecutionException for a checked failure from tool execution. Use SpecialException when the current task should finish while the host application remains running. The provider integration is responsible for catching these exceptions and mapping them to its protocol.

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 clients depend on them. Document the context object types expected by each ToolFunction, and package every service descriptor with its implementation.

  • Class
    Description
     
    Signals that the current task has ended without terminating the application.
    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.
    Service-provider interface (SPI) for installing host-provided function tools.
    Discovers and applies FunctionTools implementations using Java's ServiceLoader mechanism.
    Annotation to mark a method parameter marked as a Tool or Prompt parameter within the AI provider framework.
    Descriptor for a parameter used in tool or prompt definitions within the AI provider framework.
    Annotation to mark a method as a prompt within the AI provider framework.
    Annotation used to declare a method as an executable resource provider within the generative-AI tools system.
    Enumeration representing participant roles in an AI interaction context.
    Exception used to signal the end of a task without terminating the application.
    Indicates which application classes a FunctionTools implementation supports.
    Annotation to mark a method as a tool function within the AI provider framework.
     
    Indicates that a tool callback could not complete its requested operation.
    Functional interface representing a tool callable by a provider during a run.