Package org.machanism.machai.bindex.core

Class MongoBindexRepository

java.lang.Object
org.machanism.machai.bindex.core.MongoBindexRepository
All Implemented Interfaces:
BindexRepository
public class MongoBindexRepository extends Object implements BindexRepository
MongoDB-backed repository for persisting and retrieving Bindex documents.

The repository stores the serialized Bindex JSON in a dedicated field (see BINDEX_PROPERTY_NAME) and provides helper operations commonly needed by higher-level components such as Picker and tool integrations.

Connection details are resolved from configuration/environment:

  • When BINDEX_REPO_URL is configured, it is used as the MongoDB connection URI.
  • Otherwise a default cluster URI is used, with credentials optionally sourced from BINDEX_REG_PASSWORD.
Since:
1.2.0
Author:
Viktor Tovstyi

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    BINDEX_PASSWORD_PROP_NAME
    Configuration property name for the MongoDB password.
    private static final String
    BINDEX_PROP_NAME
    MongoDB field containing the serialized Bindex payload.
    static final String
    BINDEX_PROPERTY_NAME
    MongoDB field name used to store the serialized Bindex JSON payload.
    private static final String
    BINDEX_REPO_URL_PROP_NAME
    Configuration property containing the MongoDB connection URL.
    private static final String
    BINDEX_USER_PROP_NAME
    Configuration property containing a MongoDB username.
    private static final String
    CLASSIFICATION_EMBEDDING_PROP_NAME
    MongoDB field containing the classification embedding vector.
    private final com.mongodb.client.MongoCollection<org.bson.Document>
    collection
    MongoDB collection containing the persisted Bindex documents.
    private Configurator
    config
    Configuration used to resolve MongoDB connection properties.
    private static final String
    CONNECTION
    MongoDB collection name.
    static final String
    DB_URL
    Default MongoDB connection URL used when no repository URL is configured.
    private static final String
    DESCRIPTION_FIELD_NAME
    MongoDB field containing the Bindex description.
    private static final String
    DOMAINS_PROP_NAME
    MongoDB field containing Bindex domains.
    private static final String
    ID_FIELD_NAME
    MongoDB field containing the Bindex identifier.
    private static final String
    INDEXNAME
    Name of the MongoDB vector-search index.
    private static final String
    INSTANCENAME
    MongoDB database name.
    private static final String
    INTEGRATIONS_PROP_NAME
    MongoDB field containing normalized integrations.
    private static final String
    LANGUAGES_PROP_NAME
    MongoDB field containing normalized programming languages.
    private static final String
    LAYERS_PROP_NAME
    MongoDB field containing Bindex architectural layers.
    private final org.slf4j.Logger
    logger
    Logger used for repository diagnostics and registration warnings.
    private com.mongodb.client.MongoClient
    mongoClient
    MongoDB client owned by this repository instance.
    private static final String
    NAME_FIELD_NAME
    MongoDB field containing the Bindex name.
    private static final String
    PUBLILC_USER_NAME
    Default username used for the public database connection.
    private static final String
    REGISTER_USER_NAME
    Username used for the registration database connection.
    private static final String
    SCORE_FIELD_NAME
    Aggregation field containing the vector-search relevance score.
    private static final String
    VERSION_FIELD_NAME
    MongoDB field containing the Bindex version.

  • Constructor Summary

    Constructors
    Constructor
    Description
    MongoBindexRepository(Configurator config)
    Creates a repository instance backed by a MongoDB collection.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Closes the underlying MongoClient if this repository created it.
    private void
    createMongoClient()
    Initializes the internal MongoClient instance.
    String
    deleteBindex(org.machanism.machai.schema.Bindex bindex)
    Deletes a Bindex document from the database.
    Collection<BindexInfo>
    find(org.machanism.machai.schema.Classification[] classifications, List<Double> embedding, long vectorSearchLimits, double score, Configurator config)
    Picks matching Bindex entries for a natural-language query.
    (package private) org.bson.Document
    findFirst(org.bson.conversions.Bson filter)
    Querying the first matching document based on a Bson filter.
    (package private) org.bson.Document
    findFirst(org.bson.Document filter)
    Querying the first matching document based on a raw Document filter.
    org.machanism.machai.schema.Bindex
    getBindex(String id)
    Retrieves a Bindex instance from the database by its Bindex id.
    com.mongodb.client.MongoCollection<org.bson.Document>
    getCollection()
    Provides direct access to the underlying MongoDB collection.
    String
    getRegistredId(org.machanism.machai.schema.Bindex bindex)
    Finds the MongoDB registration identifier for the supplied Bindex.
    private Map<String,BindexInfo>
    getResults(List<Double> embedding, Double score, long vectorSearchLimits, org.bson.conversions.Bson... bsons)
    Executes a vector search and returns matching library coordinates in mapped structure.
    String
    save(org.machanism.machai.schema.Bindex bindex, List<Double> embedding)
    Registers or replaces a Bindex entry in the repository.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • logger

      private final org.slf4j.Logger logger
      Logger used for repository diagnostics and registration warnings.

    • mongoClient

      private com.mongodb.client.MongoClient mongoClient
      MongoDB client owned by this repository instance.

    • BINDEX_PROPERTY_NAME

      public static final String BINDEX_PROPERTY_NAME
      MongoDB field name used to store the serialized Bindex JSON payload.
      See Also:

    • CLASSIFICATION_EMBEDDING_PROP_NAME

      private static final String CLASSIFICATION_EMBEDDING_PROP_NAME
      MongoDB field containing the classification embedding vector.
      See Also:

    • LANGUAGES_PROP_NAME

      private static final String LANGUAGES_PROP_NAME
      MongoDB field containing normalized programming languages.
      See Also:

    • DOMAINS_PROP_NAME

      private static final String DOMAINS_PROP_NAME
      MongoDB field containing Bindex domains.
      See Also:

    • LAYERS_PROP_NAME

      private static final String LAYERS_PROP_NAME
      MongoDB field containing Bindex architectural layers.
      See Also:

    • INTEGRATIONS_PROP_NAME

      private static final String INTEGRATIONS_PROP_NAME
      MongoDB field containing normalized integrations.
      See Also:

    • BINDEX_PROP_NAME

      private static final String BINDEX_PROP_NAME
      MongoDB field containing the serialized Bindex payload.
      See Also:

    • ID_FIELD_NAME

      private static final String ID_FIELD_NAME
      MongoDB field containing the Bindex identifier.
      See Also:

    • NAME_FIELD_NAME

      private static final String NAME_FIELD_NAME
      MongoDB field containing the Bindex name.
      See Also:

    • VERSION_FIELD_NAME

      private static final String VERSION_FIELD_NAME
      MongoDB field containing the Bindex version.
      See Also:

    • DESCRIPTION_FIELD_NAME

      private static final String DESCRIPTION_FIELD_NAME
      MongoDB field containing the Bindex description.
      See Also:

    • SCORE_FIELD_NAME

      private static final String SCORE_FIELD_NAME
      Aggregation field containing the vector-search relevance score.
      See Also:

    • INDEXNAME

      private static final String INDEXNAME
      Name of the MongoDB vector-search index.
      See Also:

    • DB_URL

      public static final String DB_URL
      Default MongoDB connection URL used when no repository URL is configured.
      See Also:

    • PUBLILC_USER_NAME

      private static final String PUBLILC_USER_NAME
      Default username used for the public database connection.
      See Also:

    • REGISTER_USER_NAME

      private static final String REGISTER_USER_NAME
      Username used for the registration database connection.
      See Also:

    • INSTANCENAME

      private static final String INSTANCENAME
      MongoDB database name.
      See Also:

    • CONNECTION

      private static final String CONNECTION
      MongoDB collection name.
      See Also:

    • BINDEX_USER_PROP_NAME

      private static final String BINDEX_USER_PROP_NAME
      Configuration property containing a MongoDB username.
      See Also:

    • BINDEX_PASSWORD_PROP_NAME

      public static final String BINDEX_PASSWORD_PROP_NAME
      Configuration property name for the MongoDB password.
      See Also:

    • BINDEX_REPO_URL_PROP_NAME

      private static final String BINDEX_REPO_URL_PROP_NAME
      Configuration property containing the MongoDB connection URL.
      See Also:

    • config

      private Configurator config
      Configuration used to resolve MongoDB connection properties.

    • collection

      private final com.mongodb.client.MongoCollection<org.bson.Document> collection
      MongoDB collection containing the persisted Bindex documents.

  • Constructor Details

    • MongoBindexRepository

      public MongoBindexRepository(Configurator config)
      Creates a repository instance backed by a MongoDB collection.
      Parameters:
      config - configurator used to resolve BINDEX_REPO_URL
      Throws:
      IllegalArgumentException - if config is null

  • Method Details

    • createMongoClient

      private void createMongoClient()
      Initializes the internal MongoClient instance.

      Resolves connection details from the provided Configurator, building a authenticated or public URL to connect to the MongoDB instance.

    • getCollection

      public com.mongodb.client.MongoCollection<org.bson.Document> getCollection()
      Provides direct access to the underlying MongoDB collection.

      Used by components such as Picker which operate on aggregation pipelines and need the raw MongoCollection.

      Returns:
      the MongoDB collection handle

    • close

      public void close()
      Closes the underlying MongoClient if this repository created it.

      This allows callers to use try-with-resources: 

       try (MongoBindexRepository repo = new MongoBindexRepository(config)) { ... }

    • getBindex

      public org.machanism.machai.schema.Bindex getBindex(String id)
      Retrieves a Bindex instance from the database by its Bindex id.
      Specified by:
      getBindex in interface BindexRepository
      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

    • deleteBindex

      public String deleteBindex(org.machanism.machai.schema.Bindex bindex)
      Deletes a Bindex document from the database.
      Parameters:
      bindex - Bindex to delete (by Bindex.getId())
      Returns:
      the deleted Bindex id
      Throws:
      IllegalArgumentException - if bindex is null

    • findFirst

      org.bson.Document findFirst(org.bson.conversions.Bson filter)
      Querying the first matching document based on a Bson filter.
      Parameters:
      filter - the Bson filter to match
      Returns:
      the first matching Document, or null if none match

    • findFirst

      org.bson.Document findFirst(org.bson.Document filter)
      Querying the first matching document based on a raw Document filter.
      Parameters:
      filter - the Document filter to match
      Returns:
      the first matching Document, or null if none match

    • save

      public String save(org.machanism.machai.schema.Bindex bindex, List<Double> embedding)
      Registers or replaces a Bindex entry in the repository.
      Specified by:
      save in interface BindexRepository
      Parameters:
      bindex - the Bindex definition to persist
      embedding - the embedding vector associated with the Bindex entry
      Returns:
      the inserted MongoDB identifier as a string
      Throws:
      IllegalArgumentException - if the Bindex or its classification cannot be serialized

    • getRegistredId

      public String getRegistredId(org.machanism.machai.schema.Bindex bindex)
      Finds the MongoDB registration identifier for the supplied Bindex.
      Parameters:
      bindex - the Bindex to look up
      Returns:
      the MongoDB object identifier string, or null if not found
      Throws:
      IllegalArgumentException - if bindex is null

    • find

      public Collection<BindexInfo> find(org.machanism.machai.schema.Classification[] classifications, List<Double> embedding, long vectorSearchLimits, double score, Configurator config)
      Picks matching Bindex entries for a natural-language query.
      Specified by:
      find in interface BindexRepository
      Parameters:
      classifications - an array of Classification filters to restrict search scope
      embedding - the embedding vector for semantic search
      vectorSearchLimits - the maximum number of results to return from vector search
      score - the minimum relevance score threshold for recommended entries
      config - the configuration object
      Returns:
      the list of matching Bindex entries

    • getResults

      private Map<String,BindexInfo> getResults(List<Double> embedding, Double score, long vectorSearchLimits, org.bson.conversions.Bson... bsons)
      Executes a vector search and returns matching library coordinates in mapped structure.
      Parameters:
      embedding - the query vector embedding to match against
      score - the minimum vector search score to filter results
      vectorSearchLimits - the maximum size limit of matching elements
      bsons - optional aggregation stages appended after vector search
      Returns:
      a map of unique library coordinates using the preferred version