Package org.machanism.machai.bindex.ai.tools

Class BindexFunctionTools

java.lang.Object
org.machanism.machai.bindex.ai.tools.BindexFunctionTools
All Implemented Interfaces:
FunctionTools
public class BindexFunctionTools extends Object implements FunctionTools
An AI tool set implementation of FunctionTools that provides discovery, resolution, and registration actions for Bindex components to large language models (LLMs).

This class exposes a suite of annotated capabilities with Tool and Param metadata, enabling AI agents to seamlessly interact with Bindex repositories. Key capabilities include:

  • Discovery & Recommendation: Finding relevant libraries based on natural language project descriptions.
  • Metadata Extraction: Querying comprehensive library descriptions and schemas via specific IDs.
  • Descriptor Registration: Adding or updating library declarations from direct JSON objects, local project files, or remote URLs.
See Also:

  • Field Details

    • BINDEX_SCHEMA

      private static final String BINDEX_SCHEMA
      URL to the official Bindex JSON schema definition. Used for validating Bindex files and ensuring schema compliance.
      See Also:

    • VECTOR_SEARCH_LIMITS

      private static final String VECTOR_SEARCH_LIMITS
      Default limit for the number of results returned by vector search operations.
      See Also:

    • DEFAULT_SCORE_VALUE

      private static final String DEFAULT_SCORE_VALUE
      The default similarity score threshold used to filter out low-confidence search results during vector search queries. Only results with a cosine similarity score greater than or equal to this value will be returned.

      Range: [0.0, 1.0] where 1.0 is an exact semantic match. Default: 0.85

      See Also:

    • BINDEX_JSON_FILE_NAME

      private static final String BINDEX_JSON_FILE_NAME
      Default file name for the Bindex JSON metadata file.
      See Also:

    • MODEL_PROP_NAME

      public static final String MODEL_PROP_NAME
      Property name for specifying the model to use in configuration.
      See Also:

    • bindexRepository

      private BindexRepository bindexRepository
      Repository instance for accessing and managing Bindex records.

  • Constructor Details

    • BindexFunctionTools

      public BindexFunctionTools()
      Creates a new Bindex function tool set.

  • Method Details

    • getBindex

      public org.machanism.machai.schema.Bindex getBindex(String id, String query, File projectDir, Configurator configurator) throws IOException
      Functional AI Tool that retrieves Bindex metadata for a given project or library.

      The identifier can be either a standard Bindex ID coordinates string or a remote URL pointing directly to a Bindex JSON descriptor file.

      If a GraphQL query is provided via the graphql_query parameter, the resulting Bindex object's JSON representation will be filtered to include only the requested fields before being returned.

      Parameters:
      id - The unique Bindex identifier (e.g., 'groupId:artifactId:version') or a remote HTTP/HTTPS URL location pointing to a Bindex JSON file; must not be null.
      query - An optional GraphQL-style query to filter the response payload fields and minimize token consumption (e.g., "{ name version classification { languages } }").
      configurator - The configuration object.
      Returns:
      The filtered or complete Bindex object if found.
      Throws:
      IOException - If the remote descriptor cannot be read or serialized.
      IllegalArgumentException - If the bindex cannot be found, or if reading from the provided URL fails.

    • getBindexRepository

      private BindexRepository getBindexRepository(Configurator configurator)
      Returns the current BindexRepository instance, initializing it if necessary.

      If the repository has not yet been created, this method instantiates a new MongoBindexRepository using a default PropertiesConfigurator. The same instance is returned on subsequent calls.

      Parameters:
      configurator - the configuration object (currently unused in this method)
      Returns:
      the BindexRepository instance

    • getRecommendedLibraries

      public Collection<BindexInfo> getRecommendedLibraries(String prompt, double score, int vectorSearchLimits, Configurator configurator) throws IOException
      Functional AI Tool that recommends libraries based on the user's prompt or project requirements.
      Parameters:
      prompt - A description of your project needs or requirements. For example, specify the functionality, technology stack, or features you want to implement.
      score - The minimum relevance score threshold for recommended libraries. Only libraries with a score equal to or higher than this value will be included. If not specified, a default value is used.
      vectorSearchLimits - The maximum number of recommendations to retrieve from vector search. The value is passed to the configured picker as the result limit.
      configurator - The configuration object.
      Returns:
      A collection of BindexInfo objects representing recommended libraries.
      Throws:
      IOException - If there is an error during recommendation.

    • registerBindex

      public String registerBindex(String path, File projectDir, Configurator configurator) throws IOException
      Functional AI Tool that registers a Bindex record from a file in the project directory or from a remote URL.
      Parameters:
      path - The path of the Bindex file to register (must exist in the project directory). Default: "bindex.json".
      projectDir - The project directory.
      configurator - The configuration object.
      Returns:
      The unique record ID assigned by the configured picker.
      Throws:
      FileNotFoundException - If the specified file does not exist.
      IOException - If there is an error reading the file.

    • registerBindexJson

      public String registerBindexJson(org.machanism.machai.schema.Bindex bindex, Configurator configurator)
      Functional AI Tool that registers a Bindex record from a JSON object.
      Parameters:
      bindex - The Bindex JSON object.
      configurator - The configuration object.
      Returns:
      The unique Bindex ID assigned to the registered entry.

    • getBindexSchema

      public String getBindexSchema(URI uri) throws IOException
      Contextual Resource that retrieves the JSON Schema definition for Bindex (bundle index) validation.

      This method loads the schema resource located at /schema/bindex-schema-v2.json from the classpath and returns its content as a UTF-8 encoded string.

      Parameters:
      uri - the resource URI supplied by the tool framework; its path is used to locate the schema on the classpath
      Returns:
      the JSON Schema content for Bindex v2
      Throws:
      IOException - if the schema resource cannot be found or read

    • bindexGenerationPrompts

      public String bindexGenerationPrompts() throws IOException
      Prompt Template that loads and returns the system instructions and prompts required for Bindex generation.

      This method reads the prompt template from the classpath resource /prompts/bindex-generation.md and returns it as a UTF-8 encoded string.

      Returns:
      the content of the Bindex generation prompt template
      Throws:
      IOException - if the prompt template resource cannot be found or read