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 annotated Tool, Prompt, Resource, and Param capabilities for AI agents to interact with Bindex repositories. Its functional AI tools are get_bindex, which retrieves metadata; pick_libraries, which recommends libraries; register_bindex, which registers a descriptor from a file or URL; and register_bindex_json, which registers a supplied descriptor. It also provides the generate-bindex prompt template and the file:///schema/bindex-schema-v2.json contextual JSON Schema resource. 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 id parameter accepts standard Bindex coordinates, a direct http:// or https:// URL for a remote descriptor, or a file:// path for local JSON parsing and validation. Relative file paths are resolved against projectDir; all other identifiers are resolved through the configured repository.

      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 (for example, groupId:artifactId:version), a direct http:// or https:// Bindex JSON URL, or a file:// path; 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 } }").
      projectDir - The base directory used to resolve a relative file:// descriptor path; required for relative file paths and otherwise may be null.
      configurator - The repository configuration used when id is a Bindex identifier.
      Returns:
      The complete Bindex, or a deserialized projection when query is supplied.
      Throws:
      IOException - If the remote descriptor cannot be read or serialized.
      IllegalArgumentException - If no Bindex is found for an identifier.

    • 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 the supplied configuration. The same instance is returned on subsequent calls.

      Parameters:
      configurator - the configuration used when a repository must be initialized
      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 are included; the tool metadata defaults it to 0.85.
      vectorSearchLimits - The maximum number of recommendations to retrieve from vector search. The value is passed to the configured picker as the result limit; the tool metadata defaults it to 25.
      configurator - The configuration used to create the repository and picker.
      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 JSON object from a file in the project directory or a direct http:// or https:// URL. On success it returns the Bindex ID and adds or updates the metadata available to library search and integration.
      Parameters:
      path - The Bindex file path, which must exist within the project directory, or a direct HTTP(S) URL. The tool metadata defaults it to bindex.json.
      projectDir - The project directory; required for file registration.
      configurator - The configuration used to create the repository and picker.
      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.
      IllegalArgumentException - If projectDir is absent for a file-based registration, or an absolute path lies outside that directory.

    • resolveProjectFile

      File resolveProjectFile(String path, File projectDir) throws IOException
      Resolves a descriptor and ensures that it remains within the project tree.
      Parameters:
      path - the user-provided descriptor path
      projectDir - the trusted project base directory
      Returns:
      the canonical descriptor file
      Throws:
      IOException - if a path cannot be canonicalized
      IllegalArgumentException - if the base directory is absent or the descriptor is outside it

    • registerBindexJson

      public String registerBindexJson(org.machanism.machai.schema.Bindex bindex, Configurator configurator)
      Functional AI Tool that registers a Bindex JSON object and returns its Bindex ID on successful registration.
      Parameters:
      bindex - The Bindex JSON object to register; must not be null.
      configurator - The configuration used to create the repository and picker.
      Returns:
      The unique Bindex ID assigned to the registered entry.
      Throws:
      NullPointerException - If bindex is null.

    • 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 file:///schema/bindex-schema-v2.json resource from the classpath and returns its content as a UTF-8 encoded application/json string. The supplied URI is the contextual resource URI provided by the tool framework.

      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 read
      NullPointerException - if the configured schema resource is absent from the classpath

    • bindexGenerationPrompts

      public String bindexGenerationPrompts() throws IOException
      Prompt Template named generate-bindex that loads and returns the Markdown instructions and contextual prompts required for Bindex file generation.

      This method reads the prompt template from the classpath resource /prompts/generate_bindex.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 read
      NullPointerException - if the prompt template resource is absent from the classpath