{
  "$schema": "https://raw.githubusercontent.com/machanism-org/machai/refs/heads/main/bindex-core/src/main/resources/schema/bindex-schema-v2.json",
  "id": "org.machanism.machai:bindex-core:1.2.0-SNAPSHOT",
  "name": "org.machanism.machai:bindex-core",
  "version": "1.2.0-SNAPSHOT",
  "description": "Bindex Core provides core functionality for bindex metadata management, including generation, registration, library selection, and project assembly. It manages org.machanism.machai.schema.Bindex records that describe reusable projects, libraries, integrations, and their classifications. The module stores Bindex records in MongoDB as serialized JSON together with searchable fields such as logical id, name, version, languages, domains, layers, integrations, and classification embeddings. It generates classification embeddings through configured GenAI providers and retrieves matching libraries by combining metadata filters with MongoDB vector search. The public API includes org.machanism.machai.bindex.core.BindexRepository for saving, retrieving, deleting, and recommending Bindex records; org.machanism.machai.bindex.core.MongoBindexRepository for MongoDB-backed persistence and vector-search result loading; org.machanism.machai.bindex.core.Picker for registration, prompt classification, embedding generation, semantic recommendation, lookup, and recursive dependency resolution; and org.machanism.machai.bindex.ai.tools.BindexFunctionTools for exposing get_bindex, pick_libraries, register_bindex, and register_bindex_json operations as AI function tools. It is intended for applications, build automation, and AI-assisted development workflows that need a searchable registry of project and library metadata, especially when components must be selected from descriptive requirements rather than exact coordinates or when tool-calling agents need structured access to reusable project knowledge. Runtime behavior uses BINDEX_REPO_URL, BINDEX_USER, and BINDEX_PASSWORD for MongoDB access, embedding.model for embedding generation, pick.model or gw.model for prompt classification, and pick.score for default tool-based recommendation scoring.",
  "authors": [
    {
      "name": "Viktor Tovstyi",
      "email": "viktor.tovstyi@gmail.com",
      "website": "https://machanism.org"
    }
  ],
  "license": "Apache License, Version 2.0",
  "classification": {
    "type": "library",
    "domains": [
      "Bindex metadata management",
      "Library discovery",
      "Semantic search",
      "AI-assisted development workflows",
      "Project assembly",
      "MongoDB-backed metadata registry",
      "GenAI tool integration",
      "Embedding-based recommendation"
    ],
    "languages": [
      {
        "name": "Java",
        "version": "17"
      }
    ],
    "layers": [
      "Interactors",
      "Adapters",
      "Infrastructure",
      "Entities"
    ],
    "usageContext": [
      "Registering bindex.json metadata descriptors for reusable projects and libraries",
      "Persisting Bindex JSON records and searchable classification fields in MongoDB",
      "Generating vector embeddings for Bindex classifications with configured GenAI providers",
      "Recommending libraries from natural-language requirements using semantic vector search",
      "Providing AI function tools for Bindex retrieval, recommendation, and registration",
      "Filtering returned Bindex JSON payloads with GraphQL-style selection expressions"
    ],
    "targetEnvironment": [
      "Java",
      "Maven",
      "MongoDB",
      "MachAI GenAI provider runtime"
    ],
    "integrations": [
      "MongoDB",
      "GenAI providers",
      "MachAI tool invocation infrastructure"
    ]
  },
  "location": {
    "repositoryType": "Maven",
    "repositoryUrl": "https://repo1.maven.org/maven2/",
    "coordinates": {
      "group": "org.machanism.machai",
      "artifactId": "bindex-core",
      "version": "1.2.0-SNAPSHOT",
      "extension": "jar"
    }
  },
  "constructors": [
    {
      "package": "org.machanism.machai.bindex.core",
      "signature": "org.machanism.machai.bindex.core.Picker(org.machanism.machai.bindex.core.BindexRepository bindexRepository, org.machanism.macha.core.commons.configurator.Configurator configurator)",
      "description": "Creates a Picker backed by the configured Bindex repository and a named GenAI provider. The Picker performs Bindex registration, lookup, semantic retrieval, prompt classification, embedding generation, dependency resolution, and language normalization.",
      "examples": [
        {
          "snippet": "org.machanism.macha.core.commons.configurator.Configurator configurator = ...;\norg.machanism.machai.bindex.core.BindexRepository repository = ...;\norg.machanism.machai.bindex.core.Picker picker = new org.machanism.machai.bindex.core.Picker(repository, configurator);",
          "description": "Creates a Picker with a repository implementation and configuration object so the application can save Bindex records and recommend matching entries from natural-language prompts. Configure MongoDB access with BINDEX_REPO_URL, BINDEX_USER, and BINDEX_PASSWORD, and configure embedding.model plus pick.model or gw.model before invoking semantic operations."
        }
      ]
    },
    {
      "package": "org.machanism.machai.bindex.ai.tools",
      "signature": "org.machanism.machai.bindex.ai.tools.BindexFunctionTools()",
      "description": "Creates an AI-facing FunctionTools implementation that exposes discovery, resolution, and registration actions for Bindex components to large language models. The tool set supports recommending relevant libraries, querying complete or filtered Bindex metadata, and registering descriptors from JSON objects, local project files, or remote URLs.",
      "examples": [
        {
          "snippet": "org.machanism.machai.bindex.ai.tools.BindexFunctionTools tools = new org.machanism.machai.bindex.ai.tools.BindexFunctionTools();",
          "description": "Instantiates the tool adapter for use by the MachAI tool invocation infrastructure. Make the instance available to a GenAI provider as function tools so an agent can call getBindex, getRecommendedLibraries, registerBindex, and registerBindexJson."
        }
      ]
    }
  ],
  "features": [
    {
      "package": "org.machanism.machai.bindex.core",
      "name": "save",
      "signature": "java.lang.String save(org.machanism.machai.schema.Bindex bindex)",
      "description": "Saves a Bindex entry to the repository, generating and storing its embedding vector. The method returns the unique identifier assigned to the saved Bindex entry and throws java.lang.IllegalArgumentException if the embedding cannot be generated.",
      "examples": [
        {
          "snippet": "org.machanism.macha.core.commons.configurator.Configurator configurator = ...;\norg.machanism.machai.bindex.core.BindexRepository repository = ...;\norg.machanism.machai.bindex.core.Picker picker = new org.machanism.machai.bindex.core.Picker(repository, configurator);\norg.machanism.machai.schema.Bindex bindex = ...;\njava.lang.String recordId = picker.save(bindex);",
          "description": "Registers or updates a Bindex descriptor. Before calling save, configure embedding.model so the Picker can generate the classification embedding that will be stored with the serialized Bindex JSON in MongoDB."
        }
      ]
    },
    {
      "package": "org.machanism.machai.bindex.core",
      "name": "pick",
      "signature": "java.util.Collection<org.machanism.machai.bindex.core.BindexInfo> pick(java.lang.String prompt, long vectorSearchLimits, java.lang.Double score, org.machanism.macha.core.commons.configurator.Configurator configurator) throws java.io.IOException",
      "description": "Recommends Bindex entries based on a natural-language prompt and a minimum score. The method uses a GenAI provider to classify the prompt, generates an embedding from that classification, and queries the Bindex repository for matching entries with MongoDB vector search.",
      "examples": [
        {
          "snippet": "org.machanism.macha.core.commons.configurator.Configurator configurator = ...;\norg.machanism.machai.bindex.core.BindexRepository repository = ...;\norg.machanism.machai.bindex.core.Picker picker = new org.machanism.machai.bindex.core.Picker(repository, configurator);\njava.util.Collection<org.machanism.machai.bindex.core.BindexInfo> matches = picker.pick(\"Java service that stores metadata in MongoDB and needs AI-assisted library selection\", 250L, java.lang.Double.valueOf(0.85D), configurator);",
          "description": "Uses semantic search to find registered Bindex records that match a project requirement. Configure pick.model when a dedicated classification model is desired, otherwise the Picker uses gw.model; configure embedding.model for vector generation and pick.score for default recommendation scoring in tool-based workflows."
        }
      ]
    },
    {
      "package": "org.machanism.machai.bindex.ai.tools",
      "name": "getBindex",
      "signature": "org.machanism.machai.schema.Bindex getBindex(java.lang.String id, java.lang.String query, org.machanism.macha.core.commons.configurator.Configurator configurator) throws java.io.IOException",
      "description": "Retrieves Bindex metadata for a project or library. The identifier can be a standard Bindex coordinates string or a remote URL pointing directly to a Bindex JSON descriptor. When a GraphQL-style query is supplied, the returned Bindex JSON representation is filtered to include only requested fields before being returned.",
      "examples": [
        {
          "snippet": "org.machanism.machai.bindex.ai.tools.BindexFunctionTools tools = new org.machanism.machai.bindex.ai.tools.BindexFunctionTools();\norg.machanism.macha.core.commons.configurator.Configurator configurator = ...;\norg.machanism.machai.schema.Bindex bindex = tools.getBindex(\"org.machanism.machai:bindex-core:1.2.0-SNAPSHOT\", \"{ name version classification { languages } }\", configurator);",
          "description": "Loads Bindex metadata by repository identifier and limits the returned payload to selected fields with a GraphQL-style selection expression. Use a remote HTTP or HTTPS URL instead of coordinates when retrieving a descriptor directly from a published bindex.json location."
        }
      ]
    },
    {
      "package": "org.machanism.machai.bindex.ai.tools",
      "name": "getRecommendedLibraries",
      "signature": "java.util.Collection<org.machanism.machai.bindex.core.BindexInfo> getRecommendedLibraries(java.lang.String prompt, java.lang.Double score, int vectorSearchLimits, org.machanism.macha.core.commons.configurator.Configurator configurator) throws java.io.IOException",
      "description": "Recommends libraries based on a prompt that describes project needs, required functionality, technology stack, or desired features. Only libraries with a score equal to or higher than the supplied minimum relevance score are included; if the score is not specified, a configured default can be used.",
      "examples": [
        {
          "snippet": "org.machanism.machai.bindex.ai.tools.BindexFunctionTools tools = new org.machanism.machai.bindex.ai.tools.BindexFunctionTools();\norg.machanism.macha.core.commons.configurator.Configurator configurator = ...;\njava.util.Collection<org.machanism.machai.bindex.core.BindexInfo> recommended = tools.getRecommendedLibraries(\"Need a Java library for MongoDB-backed metadata registration and semantic library discovery\", java.lang.Double.valueOf(0.80D), 100, configurator);",
          "description": "Exposes Bindex semantic recommendation as an AI-callable operation. The caller provides a natural-language requirement, an optional minimum score, and the maximum vector-search result count."
        }
      ]
    },
    {
      "package": "org.machanism.machai.bindex.ai.tools",
      "name": "registerBindex",
      "signature": "java.lang.String registerBindex(java.lang.String path, java.io.File projectDir, org.machanism.macha.core.commons.configurator.Configurator configurator) throws java.io.IOException",
      "description": "Registers a Bindex record from a file in the project directory. The path parameter names the Bindex file to register and defaults to bindex.json. The method returns the record identifier when registration succeeds and throws java.io.FileNotFoundException when the file does not exist.",
      "examples": [
        {
          "snippet": "org.machanism.machai.bindex.ai.tools.BindexFunctionTools tools = new org.machanism.machai.bindex.ai.tools.BindexFunctionTools();\norg.machanism.macha.core.commons.configurator.Configurator configurator = ...;\njava.io.File projectDir = new java.io.File(\".\");\njava.lang.String recordId = tools.registerBindex(\"bindex.json\", projectDir, configurator);",
          "description": "Registers a local bindex.json file from a project directory. This is a practical workflow for build automation: install the Maven dependency, create bindex.json in the project root, configure MongoDB and embedding provider settings, then invoke registerBindex to persist the descriptor and searchable embedding."
        }
      ]
    },
    {
      "package": "org.machanism.machai.bindex.ai.tools",
      "name": "registerBindexJson",
      "signature": "java.util.Map<java.lang.String, java.lang.String> registerBindexJson(org.machanism.machai.schema.Bindex bindex, org.machanism.macha.core.commons.configurator.Configurator configurator)",
      "description": "Registers a Bindex record from an in-memory JSON object represented by org.machanism.machai.schema.Bindex and returns a map containing the record ID after successful registration.",
      "examples": [
        {
          "snippet": "org.machanism.machai.bindex.ai.tools.BindexFunctionTools tools = new org.machanism.machai.bindex.ai.tools.BindexFunctionTools();\norg.machanism.macha.core.commons.configurator.Configurator configurator = ...;\norg.machanism.machai.schema.Bindex bindex = ...;\njava.util.Map<java.lang.String, java.lang.String> result = tools.registerBindexJson(bindex, configurator);",
          "description": "Registers a descriptor that has already been built or deserialized in memory. This is useful for AI agents or services that generate structured Bindex objects directly instead of writing them to disk first."
        }
      ]
    }
  ],
  "customizations": [
    {
      "name": "BINDEX_REPO_URL",
      "description": "Runtime configuration for MongoDB access used by the Bindex repository. The repository stores serialized Bindex JSON plus metadata fields and classification embeddings in MongoDB.",
      "type": "configuration property"
    },
    {
      "name": "BINDEX_USER",
      "description": "Runtime configuration for the MongoDB user used when accessing the Bindex repository.",
      "type": "configuration property"
    },
    {
      "name": "BINDEX_PASSWORD",
      "description": "Runtime configuration for the MongoDB password used when accessing the Bindex repository.",
      "type": "configuration property"
    },
    {
      "name": "embedding.model",
      "description": "Configuration key for the embedding model provider used to convert Bindex classifications and classified user requests into vector representations for semantic search.",
      "type": "configuration property"
    },
    {
      "name": "pick.model",
      "description": "Optional configuration key for the GenAI model used to classify natural-language library selection prompts. If absent, the gateway model configured by gw.model is used.",
      "type": "configuration property"
    },
    {
      "name": "pick.score",
      "description": "Configuration key for the default picker score used for tool-based library recommendations when a score is not provided by the caller.",
      "type": "configuration property"
    }
  ],
  "studs": [
    {
      "name": "org.machanism.machai.bindex.core.BindexRepository",
      "package": "org.machanism.machai.bindex.core",
      "type": "interface",
      "description": "Repository interface for managing Bindex records. It defines the storage and search contract for saving Bindex records, retrieving them by id, deleting records, and finding recommended entries from classification text and embeddings.",
      "implement": "org.machanism.machai.bindex.core.MongoBindexRepository",
      "examples": [
        {
          "snippet": "org.machanism.machai.bindex.core.BindexRepository repository = ...;\norg.machanism.machai.schema.Bindex stored = repository.getBindex(\"org.example:library:1.0.0\");",
          "description": "Uses the repository abstraction to load a stored Bindex by identifier without binding application code directly to MongoDB-specific implementation details."
        }
      ]
    }
  ],
  "examples": [
    {
      "title": "Install Bindex Core in a Maven project",
      "description": "Add the Maven dependency to a Java application that needs Bindex registration, retrieval, and semantic recommendation services.",
      "steps": [
        "Configure a Maven repository that can resolve org.machanism.machai:bindex-core:1.2.0-SNAPSHOT.",
        "Add the dependency with groupId org.machanism.machai, artifactId bindex-core, and version 1.2.0-SNAPSHOT.",
        "Configure MongoDB connection settings with BINDEX_REPO_URL, BINDEX_USER, and BINDEX_PASSWORD.",
        "Configure embedding.model for vector generation and pick.model or gw.model for prompt classification."
      ],
      "snippet": "<dependency>\n  <groupId>org.machanism.machai</groupId>\n  <artifactId>bindex-core</artifactId>\n  <version>1.2.0-SNAPSHOT</version>\n</dependency>"
    },
    {
      "title": "Register a bindex.json descriptor from a project directory",
      "description": "Use BindexFunctionTools as an AI-facing or automation-facing adapter to register a project descriptor stored in the project root.",
      "steps": [
        "Create or update bindex.json in the project root.",
        "Ensure MongoDB and GenAI embedding configuration is available through the Configurator.",
        "Instantiate org.machanism.machai.bindex.ai.tools.BindexFunctionTools.",
        "Call registerBindex with path bindex.json and the project directory."
      ],
      "snippet": "org.machanism.machai.bindex.ai.tools.BindexFunctionTools tools = new org.machanism.machai.bindex.ai.tools.BindexFunctionTools();\norg.machanism.macha.core.commons.configurator.Configurator configurator = ...;\njava.io.File projectDir = new java.io.File(\".\");\njava.lang.String recordId = tools.registerBindex(\"bindex.json\", projectDir, configurator);"
    },
    {
      "title": "Pick libraries from natural-language requirements",
      "description": "Use Picker to classify a requirement, generate an embedding, and query MongoDB vector search for matching registered Bindex entries.",
      "steps": [
        "Create or obtain an org.machanism.machai.bindex.core.BindexRepository implementation backed by MongoDB.",
        "Create org.machanism.machai.bindex.core.Picker with the repository and Configurator.",
        "Pass a natural-language prompt, vector search limit, minimum score, and configuration to pick.",
        "Use the returned org.machanism.machai.bindex.core.BindexInfo collection to inspect identifiers, versions, descriptions, and relevance scores."
      ],
      "snippet": "org.machanism.macha.core.commons.configurator.Configurator configurator = ...;\norg.machanism.machai.bindex.core.BindexRepository repository = ...;\norg.machanism.machai.bindex.core.Picker picker = new org.machanism.machai.bindex.core.Picker(repository, configurator);\njava.util.Collection<org.machanism.machai.bindex.core.BindexInfo> matches = picker.pick(\"Java module for Bindex metadata registration, MongoDB persistence, and GenAI vector recommendations\", 250L, java.lang.Double.valueOf(0.85D), configurator);"
    },
    {
      "title": "Retrieve selected Bindex fields with a GraphQL-style query",
      "description": "Use BindexFunctionTools to fetch a descriptor by coordinates or URL and reduce the returned JSON payload to only the fields needed by an AI caller.",
      "steps": [
        "Instantiate org.machanism.machai.bindex.ai.tools.BindexFunctionTools.",
        "Choose a Bindex id such as groupId:artifactId:version or a remote URL to bindex.json.",
        "Provide a GraphQL-style selection expression such as { name version classification { languages } }.",
        "Call getBindex and pass the configured runtime object."
      ],
      "snippet": "org.machanism.machai.bindex.ai.tools.BindexFunctionTools tools = new org.machanism.machai.bindex.ai.tools.BindexFunctionTools();\norg.machanism.macha.core.commons.configurator.Configurator configurator = ...;\norg.machanism.machai.schema.Bindex selected = tools.getBindex(\"org.machanism.machai:bindex-core:1.2.0-SNAPSHOT\", \"{ name version classification { languages } }\", configurator);"
    }
  ],
  "dependencies": [
    "org.machanism.machai:genai-client:1.2.0-SNAPSHOT",
    "org.tomlj:tomlj:1.1.1",
    "com.graphql-java:graphql-java:22.3",
    "org.apache.maven:maven-core:3.8.1",
    "org.mongodb:mongodb-driver-sync:5.6.4",
    "org.slf4j:slf4j-api:2.0.17"
  ]
}