Package org.machanism.machai.ai.provider

Interface Genai

All Known Implementing Classes:
ClaudeProvider, CodeMieProvider, GeminiProvider, GenaiAdapter, NoneProvider, OpenAIProvider
public interface Genai
Contract for a generative-AI provider integration.

A Genai 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,
  • computing embedding vectors,
  • 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 = ...;
 Genai provider = GenaiProviderManager.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

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    LINE_SEPARATOR
    Line separator used when composing prompts.
    static final String
    LOG_INPUTS_PROP_NAME
    Configuration property name indicating whether provider inputs should be logged.
    static final String
    PARAGRAPH_SEPARATOR
    Paragraph separator used when composing prompts.
    static final String
    PASSWORD_PROP_NAME
    Environment variable name for authenticating with the GenAI provider.
    static final String
    SERVERID_PROP_NAME
    Configuration property name for the target GenAI server identifier.
    static final String
    USERNAME_PROP_NAME
    Environment variable name for authenticating with the GenAI provider.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addTool(String name, String description, ToolFunction function, String... paramsDesc)
    Registers a custom tool function that the provider may invoke at runtime.
    void
    clear()
    Clears any stored files and session/provider state.
    List<Double>
    embedding(String text, long dimensions)
    Computes an embedding vector for the provided text.
    void
    init(Configurator conf)
    Initializes the provider with application configuration.
    void
    inputsLog(File bindexTempDir)
    Enables logging of provider inputs to the given directory.
    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 and state.
    void
    prompt(String text)
    Adds a user prompt to the current session.
    void
    setWorkingDir(File workingDir)
    Configures the working directory used for file and tool operations.
    Usage
    usage()
    Returns token usage metrics for the most recent perform() invocation.

  • Field Details

    • LOG_INPUTS_PROP_NAME

      static final String LOG_INPUTS_PROP_NAME
      Configuration property name indicating whether provider inputs should be logged.
      See Also:

    • SERVERID_PROP_NAME

      static final String SERVERID_PROP_NAME
      Configuration property name for the target GenAI server identifier.
      See Also:

    • USERNAME_PROP_NAME

      static final String USERNAME_PROP_NAME
      Environment variable name for authenticating with the GenAI provider.
      See Also:

    • PASSWORD_PROP_NAME

      static final String PASSWORD_PROP_NAME
      Environment variable name for authenticating with the GenAI provider.
      See Also:

    • LINE_SEPARATOR

      static final String LINE_SEPARATOR
      Line separator used when composing prompts.
      See Also:

    • PARAGRAPH_SEPARATOR

      static final String PARAGRAPH_SEPARATOR
      Paragraph separator used when composing prompts.
      See Also:

  • Method Details

    • init

      void init(Configurator conf)
      Initializes the provider with application configuration.
      Parameters:
      conf - configuration source

    • prompt

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

    • embedding

      List<Double> embedding(String text, long dimensions)
      Computes an embedding vector for the provided text.
      Parameters:
      text - the input text
      dimensions - desired embedding dimensionality (provider-specific)
      Returns:
      the embedding vector

    • clear

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

    • addTool

      void addTool(String name, String description, ToolFunction function, String... paramsDesc)
      Registers a custom tool function that the provider may invoke at runtime.

      The expected argument structure passed to function is provider-specific.

      Parameters:
      name - tool name (unique per provider instance)
      description - human-readable description of the tool
      function - function implementation; receives an argument array and returns a result
      paramsDesc - parameter descriptors (format is provider-specific)

    • instructions

      void instructions(String instructions)
      Sets system/session instructions for the current conversation.
      Parameters:
      instructions - instruction text

    • perform

      String perform()
      Executes the provider to produce a response based on the accumulated prompts and state.
      Returns:
      the provider response

    • inputsLog

      void inputsLog(File bindexTempDir)
      Enables logging of provider inputs to the given directory.
      Parameters:
      bindexTempDir - directory used for writing log files

    • setWorkingDir

      void setWorkingDir(File workingDir)
      Configures the working directory used for file and tool operations.
      Parameters:
      workingDir - the working directory

    • usage

      Usage usage()
      Returns token usage metrics for the most recent perform() invocation.
      Returns:
      usage metrics; implementations may return zero values if not supported