Package org.machanism.machai.process.provider

Interface ProcessProvider

All Known Implementing Classes:
AbstractAIProvider, AbstractAIProvider, AnthropicProvider, CodeMieProvider, CodeMieProvider.ClaudeProviderExtension, CodeMieProvider.OpenAIProviderExtension, NoneProvider, OpenAIProvider, ProcessProviderAdapter, ToolsProvider
public interface ProcessProvider
Contract for a generative-AI provider integration.

A ProcessProvider represents a concrete implementation (for example OpenAI, Gemini, a local model, etc.) capable of:

  • Collecting prompts and system instructions for a conversation,
  • Attaching local or remote files for provider-side processing,
  • Registering tool functions that may be invoked during a run.

Implementations may keep session state between calls. Use clear() to reset conversation state.

Typical usage

 Configurator conf = ...;
 ProcessProvider provider = ProcessProviderManager.getProvider("OpenAI:gpt-4o-mini", conf);

 provider.instructions("You are a helpful assistant.");
 provider.prompt("Hello!");
 String response = provider.perform();

 provider.clear();
Author:
Viktor Tovstyi

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addPrompts(FunctionTools tools)
    Scans the provided FunctionTools instance for methods annotated with Prompt and registers each prompt for use during a run.
    void
    addResources(FunctionTools tools)
    Scans the provided FunctionTools instance for methods annotated with Resource, and registers each resource for use during a run.
    void
    addTools(FunctionTools tools, String[] enabledTools)
    Registers the tools exposed by the given FunctionTools implementation, optionally restricting registration to a filtered subset of tools.
    void
    clear()
    Clears any stored files and session/provider state.
    List<String>
    getToolNames()
    Returns the names of tools currently registered with the provider.
    void
    init(String model, Configurator conf)
    Initializes the provider with application configuration.
    void
    instructions(String instructions)
    Sets system/session instructions for the current conversation.
    String
    perform()
    Executes the provider to produce a response based on the accumulated prompts, instructions, files, and registered capabilities.
    void
    prompt(String text)
    Adds a user prompt to the current session.
    void
    setErrorHandling(boolean errorHandling)
    Configures whether tool invocation errors should be returned to the model for conversational recovery or propagated as exceptions.
    void
    setProjectDir(File projectDir)
    Sets the working directory for the provider, which may be supplied to tool, prompt, and resource handlers.

  • Method Details

    • init

      void init(String model, Configurator conf)
      Initializes the provider with application configuration.
      Parameters:
      model - the model identifier or name to use
      conf - configuration source used to initialize the provider
      Throws:
      IllegalArgumentException - if the model or configuration is invalid

    • prompt

      void prompt(String text)
      Adds a user prompt to the current session.

      Prompts are accumulated until perform() or clear() is called. The exact message format sent to the provider is implementation specific.

      Parameters:
      text - the prompt text

    • clear

      void clear()
      Clears any stored files and session/provider state.

      This resets the conversation and any accumulated context.

    • instructions

      void instructions(String instructions)
      Sets system/session instructions for the current conversation.

      Calling this method replaces any previously configured instructions. A null value may be used to clear them when supported by the implementation.

      Parameters:
      instructions - instruction text

    • perform

      String perform()
      Executes the provider to produce a response based on the accumulated prompts, instructions, files, and registered capabilities.

      Whether the accumulated session is retained after execution is provider specific. Call clear() when a new independent conversation is required.

      Returns:
      the provider response as a string

    • addTools

      void addTools(FunctionTools tools, String[] enabledTools)
      Registers the tools exposed by the given FunctionTools implementation, optionally restricting registration to a filtered subset of tools.

      Implementations are expected to discover tool definitions on the provided tools instance (typically via annotated methods) and make them available for use, applying the enablement filter described below.

      Parameters:
      tools - the FunctionTools implementation containing the tool definitions to register; must not be null.
      enabledTools - an optional array of regular expression patterns controlling which tools are registered.

      Each tool is identified internally by a fully qualified name built in the format <ClassName>:<toolName>, where:

      • <ClassName> is the fully qualified class name of the tools implementation, and
      • <toolName> is the tool's declared name (or the method name if no explicit name is provided).
      A tool is registered only if its fully qualified name matches at least one of the given patterns. If enabledTools is null, all available tools are registered without filtering.

    • getToolNames

      List<String> getToolNames()
      Returns the names of tools currently registered with the provider.

      The returned names may be used for diagnostics, filtering, request construction, or tool-invocation processing. The ordering and mutability of the returned list are provider-specific.

      Returns:
      the names of registered tools, or an empty list when no tools are registered

    • addPrompts

      void addPrompts(FunctionTools tools)
      Scans the provided FunctionTools instance for methods annotated with Prompt and registers each prompt for use during a run.

      The prompt name, description, role, and parameters are obtained from the annotation and the method signature.

      Parameters:
      tools - the FunctionTools instance whose methods will be scanned for Prompt annotations

    • addResources

      void addResources(FunctionTools tools)
      Scans the provided FunctionTools instance for methods annotated with Resource, and registers each resource for use during a run.

      This method inspects the given class instance to register resource utilities that can be dynamically called by the AI model during generation processes.

      Parameters:
      tools - the FunctionTools instance whose methods will be scanned for resource annotations

    • setProjectDir

      void setProjectDir(File projectDir)
      Sets the working directory for the provider, which may be supplied to tool, prompt, and resource handlers.
      Parameters:
      projectDir - the project directory, or null to clear the current directory

    • setErrorHandling

      void setErrorHandling(boolean errorHandling)
      Configures whether tool invocation errors should be returned to the model for conversational recovery or propagated as exceptions. This setting does not suppress provider or configuration errors unrelated to tool invocation.
      Parameters:
      errorHandling - true to return tool errors as response text; false to propagate them immediately