Class Picker

java.lang.Object
org.machanism.machai.bindex.core.Picker

public class Picker extends Object
Performs Bindex registration, lookup, and semantic retrieval through a BindexRepository using GenAI-derived classifications and embeddings.

The Picker class provides methods for:

  • Recommending libraries (Bindex entries) based on a natural language prompt and score threshold
  • Registering and retrieving Bindex entries
  • Building and executing classification prompts using a GenAI provider
  • Recursively resolving dependencies for a Bindex entry
  • Normalizing language names for repository matching

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    Classpath resource path for the Bindex JSON schema.
    Repository used for Bindex persistence and semantic search.
    private static final String
    Configuration property overriding the classification prompt template.
    private static String
    Lazily initialized cache holding the extracted classification JSON schema fragment to avoid repeated resource reads.
    private Configurator
    Configuration used to select AI and embedding providers.
    private static final String
    Default prompt template used when no classification instruction is configured.
    private int
    Number of dimensions requested from the embedding provider.
    private final org.slf4j.Logger
    Logger used to report registration and recommendation diagnostics.
    private static final String
    Configuration property selecting the GenAI model used for classification.
    private static final com.fasterxml.jackson.databind.ObjectMapper
    Shared JSON mapper used to read the schema and serialize schema nodes.
  • Constructor Summary

    Constructors
    Constructor
    Description
    Picker(BindexRepository bindexRepository, Configurator configurator)
    Creates a Picker backed by the configured Bindex repository and a named GenAI provider.
  • Method Summary

    Modifier and Type
    Method
    Description
    (package private) void
    addDependencies(Set<String> dependencies, String bindexId)
    Recursively adds the dependencies of the given Bindex to the provided set.
    private String
    getClassification(String query, Configurator configurator)
    Builds a classification prompt for a user query and obtains the provider's response.
    private String
    getClassificationText(org.machanism.machai.schema.Classification classification)
    Serializes a classification into JSON text for prompt and embedding generation.
    private List<Double>
    getEmbedding(org.machanism.machai.schema.Classification classification)
    Generates the embedding vector for a classification.
    (package private) static String
    getNormalizedLanguageName(org.machanism.machai.schema.Language language)
    Normalizes a language name for repository matching.
    private static String
    Loads and caches the classification portion of the Bindex JSON schema.
    pick(String prompt, long vectorSearchLimits, double score, Configurator configurator)
    Recommends a list of Bindex entries based on the provided prompt and minimum score.
    private static String
    readResource(Class<?> owner, String path)
    Reads a UTF-8 classpath resource without using the URL connection cache.
    save(org.machanism.machai.schema.Bindex bindex)
    Saves a Bindex entry to the repository, generating and storing its embedding vector.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • logger

      private final org.slf4j.Logger logger
      Logger used to report registration and recommendation diagnostics.
    • BINDEX_SCHEMA_RESOURCE

      public static final String BINDEX_SCHEMA_RESOURCE
      Classpath resource path for the Bindex JSON schema.
      See Also:
    • CLASSIFICATION_INSTRUCTION_PROP_NAME

      private static final String CLASSIFICATION_INSTRUCTION_PROP_NAME
      Configuration property overriding the classification prompt template.
      See Also:
    • OBJECT_MAPPER

      private static final com.fasterxml.jackson.databind.ObjectMapper OBJECT_MAPPER
      Shared JSON mapper used to read the schema and serialize schema nodes.
    • classificationSchemaCache

      private static volatile String classificationSchemaCache
      Lazily initialized cache holding the extracted classification JSON schema fragment to avoid repeated resource reads.
    • DEFAULT_CLASSIFICATION_INSTRUCTION

      private static final String DEFAULT_CLASSIFICATION_INSTRUCTION
      Default prompt template used when no classification instruction is configured.
      See Also:
    • MODEL_PROP_NAME

      private static final String MODEL_PROP_NAME
      Configuration property selecting the GenAI model used for classification.
      See Also:
    • configurator

      private Configurator configurator
      Configuration used to select AI and embedding providers.
    • bindexRepository

      private BindexRepository bindexRepository
      Repository used for Bindex persistence and semantic search.
    • dimensions

      private int dimensions
      Number of dimensions requested from the embedding provider.
  • Constructor Details

    • Picker

      public Picker(BindexRepository bindexRepository, Configurator configurator)
      Creates a Picker backed by the configured Bindex repository and a named GenAI provider.
      Parameters:
      bindexRepository - the repository used to save and retrieve Bindex data
      configurator - the project configuration used for repository and prompt settings
  • Method Details

    • save

      public String save(org.machanism.machai.schema.Bindex bindex)
      Saves a Bindex entry to the repository, generating and storing its embedding vector.
      Parameters:
      bindex - the Bindex object to save
      Returns:
      the unique identifier of the saved Bindex entry
      Throws:
      IllegalArgumentException - if the embedding vector generation or JSON serialization fails due to a syntax issue
    • pick

      public Collection<BindexInfo> pick(String prompt, long vectorSearchLimits, double score, Configurator configurator) throws IOException
      Recommends a list of Bindex entries based on the provided prompt and minimum score.

      This method uses a GenAI provider to classify the prompt, generates an embedding, and queries the Bindex repository for matching entries.

      Parameters:
      prompt - the natural language description of project requirements
      vectorSearchLimits - the maximum number of results to return from vector search
      score - the minimum relevance score threshold for recommended entries
      configurator - the configuration object
      Returns:
      a list of recommended Bindex entries matching the criteria
      Throws:
      IOException - if there is an error during classification or repository access
    • getEmbedding

      private List<Double> getEmbedding(org.machanism.machai.schema.Classification classification) throws com.fasterxml.jackson.core.JsonProcessingException
      Generates the embedding vector for a classification.
      Parameters:
      classification - the classification to embed
      Returns:
      the embedding encoded as a list of doubles
      Throws:
      com.fasterxml.jackson.core.JsonProcessingException - if the classification cannot be serialized
      IllegalArgumentException - if the classification is null
    • getClassificationText

      private String getClassificationText(org.machanism.machai.schema.Classification classification) throws com.fasterxml.jackson.core.JsonProcessingException
      Serializes a classification into JSON text for prompt and embedding generation.
      Parameters:
      classification - the classification to serialize
      Returns:
      the serialized JSON representation
      Throws:
      com.fasterxml.jackson.core.JsonProcessingException - if serialization fails
    • readResource

      private static String readResource(Class<?> owner, String path) throws IOException
      Reads a UTF-8 classpath resource without using the URL connection cache.
      Parameters:
      owner - the class used to resolve the resource path
      path - the classpath resource path to read
      Returns:
      the resource contents as a UTF-8 string
      Throws:
      IOException - if the resource cannot be found or read
    • loadClassificationSchema

      private static String loadClassificationSchema() throws IOException
      Loads and caches the classification portion of the Bindex JSON schema.
      Returns:
      the classification schema serialized as JSON
      Throws:
      IOException - if the schema resource cannot be read or does not contain the expected classification property
    • getClassification

      private String getClassification(String query, Configurator configurator) throws IOException
      Builds a classification prompt for a user query and obtains the provider's response.
      Parameters:
      query - the natural-language request to classify
      configurator - the configuration used to resolve the prompt template and GenAI provider
      Returns:
      the provider-generated classification response
      Throws:
      IOException - if the classification schema cannot be loaded
      IllegalArgumentException - if the configured prompt template is invalid or no GenAI model is configured
    • addDependencies

      void addDependencies(Set<String> dependencies, String bindexId)
      Recursively adds the dependencies of the given Bindex to the provided set.
      Parameters:
      dependencies - the target set that accumulates dependency identifiers
      bindexId - the root Bindex identifier whose dependency graph is traversed
    • getNormalizedLanguageName

      static String getNormalizedLanguageName(org.machanism.machai.schema.Language language)
      Normalizes a language name for repository matching.
      Parameters:
      language - the language to normalize
      Returns:
      the normalized lowercase language name without any parenthetical suffix