Package org.machanism.machai.bindex

Class Picker

java.lang.Object
org.machanism.machai.bindex.Picker
public class Picker extends Object
Performs Bindex registration, lookup, and semantic retrieval using embeddings and MongoDB.

This type supports two primary workflows:

  1. Registration: serialize and persist a Bindex into MongoDB, including a classification embedding vector used for semantic search.
  2. Retrieval: classify a free-text query into one or more Classification objects using an LLM, then run vector search queries to retrieve relevant Bindexes and expand results using transitive dependencies.

Example


 Configurator config = ...;
 try (Picker picker = new Picker("openai", null, config)) {
     List<Bindex> results = picker.pick("Find libraries for server-side logging");
 }
Since:
0.0.2
Author:
Viktor Tovstyi

  • Field Details

  • Constructor Details

    • Picker

      public Picker(String genai, String uri, Configurator config)
      Constructs a Picker for registration and semantic search.
      Parameters:
      genai - GenAI provider identifier used for embedding and classification prompts
      uri - MongoDB connection URI; when null, a default URI is constructed using BINDEX_REG_PASSWORD when available
      config - configurator used to initialize the provider
      Throws:
      IllegalArgumentException - if genai or config is null

    • Picker

      Picker(com.mongodb.client.MongoCollection<org.bson.Document> collection, org.machanism.machai.ai.manager.Genai provider)

  • Method Details

    • create

      public String create(Bindex bindex) throws com.fasterxml.jackson.core.JsonProcessingException
      Registers (inserts or updates) a Bindex document for the supplied Bindex.

      Registration deletes any existing document with the same Bindex.getId() and inserts a fresh document containing:

      • Core identity fields: id, name, version
      • Classification facets: domains, layers, normalized languages, integrations
      • A vector embedding under "classification_embedding"
      Parameters:
      bindex - Bindex instance to register
      Returns:
      generated database ID string
      Throws:
      IllegalArgumentException - if bindex is null
      com.fasterxml.jackson.core.JsonProcessingException - if conversion to JSON fails
      com.mongodb.MongoCommandException - on MongoDB insert or connection errors

    • getEmbeddingBson

      org.bson.BsonArray getEmbeddingBson(Classification classification, int dimensions) throws com.fasterxml.jackson.core.JsonProcessingException
      Generates a BSON array representing the embedding of a classification for semantic search.
      Parameters:
      classification - classification instance
      dimensions - number of vector dimensions
      Returns:
      BSON array of vector values
      Throws:
      IllegalArgumentException - if classification is null or dimensions is not positive
      com.fasterxml.jackson.core.JsonProcessingException - on embedding or serialization errors

    • getRegistredId

      public String getRegistredId(Bindex bindex)
      Looks up the registered database ID for a Bindex (if it exists).
      Parameters:
      bindex - Bindex instance
      Returns:
      MongoDB object id as string, or null if not present
      Throws:
      IllegalArgumentException - if bindex is null

    • pick

      public List<Bindex> pick(String query) throws IOException
      Performs a semantic pick/search with a query string, retrieving Bindex results and transitive dependencies.
      Parameters:
      query - query string
      Returns:
      list of Bindex results related to the query (and their dependencies)
      Throws:
      IllegalArgumentException - if query is null
      IOException - if classification or database retrieval fails

    • addDependencies

      void addDependencies(Set<String> dependencies, String bindexId)
      Adds all transitive dependencies of a Bindex into the provided set.
      Parameters:
      dependencies - set of dependency IDs to accumulate
      bindexId - Bindex ID to explore

    • getBindex

      protected Bindex getBindex(String id)
      Retrieves a Bindex instance from the database by its Bindex id.
      Parameters:
      id - Bindex id (the id field in the stored document)
      Returns:
      parsed Bindex, or null if not present
      Throws:
      IllegalArgumentException - if id is null or the stored JSON cannot be parsed

    • getNormalizedLanguageName

      static String getNormalizedLanguageName(Language language)
      Normalizes a Language name for semantic aggregation queries.
      Parameters:
      language - language object
      Returns:
      normalized language name string

    • setScore

      public void setScore(Double minScore)
      Sets the minimum similarity score for semantic vector search queries.
      Parameters:
      minScore - minimum similarity value

    • getScore

      public Double getScore(String id)
      Retrieves the similarity score for a Bindex result by its ID.
      Parameters:
      id - Bindex identifier
      Returns:
      score value for semantic result, or null if not present