{ "$schema": "https://raw.githubusercontent.com/machanism-org/bindex-core/refs/heads/main/src/main/resources/schema/bindex-schema-v2.json", "id": "org.machanism.machai:bindex-core:1.4.3", "name": "org.machanism.machai:bindex-core", "version": "1.4.3", "description": "Bindex Core is a Java library-indexing and library-discovery component for the Machai platform. It represents reusable libraries and integrations as structured Bindex v2 metadata, offers descriptor retrieval and registration, and recommends components for natural-language requirements using GenAI classification, embeddings, and MongoDB vector search. Its Java API combines the BindexRepository persistence boundary, MongoBindexRepository storage adapter, Picker coordination and recommendation service, and AI-facing Functional Tools for lookup, recommendation, registration, schema access, and descriptor-generation prompts. Descriptors contain artifact identity, purpose, dependencies, technical classification, API guidance, practical examples, integration and configuration instructions, and license metadata. Use it to create a searchable software-component catalog, integrate Bindex functions into applications or MCP hosts, and support AI-assisted dependency selection and project assembly. Java 17 or later is required. Descriptor JSON parsing and model mapping do not replace independent validation against the Bindex v2 JSON Schema.", "authors": [ { "name": "Viktor Tovstyi", "email": "viktor.tovstyi@gmail.com", "website": "https://machanism.org" } ], "license": "Apache License, Version 2.0", "classification": { "type": "Java library", "domains": [ "Software component cataloging and library indexing", "Natural-language software library discovery and recommendation", "Semantic search and vector retrieval", "Bindex metadata generation, validation, and registration", "Generative AI and MCP tool integration", "Maven-based project assembly and dependency selection" ], "languages": [ { "name": "Java", "version": "17" } ], "layers": [ "Interactors", "Adapters", "Infrastructure" ], "usageContext": [ "Java applications that manage a searchable catalog of reusable libraries", "MCP-compatible AI host integrations exposing Bindex tools", "Natural-language dependency and component discovery workflows", "Metadata registration from project-local JSON files, remote URLs, or in-memory objects", "Maven builds and AI-assisted software assembly", "Local development and testing against MongoDB Atlas Local" ], "targetEnvironment": [ "Java 17 or later" ], "integrations": [ "MongoDB Atlas Search and Vector Search", "Model Context Protocol" ] }, "location": { "repositoryType": "Maven", "repositoryUrl": "https://central.sonatype.com/artifact/org.machanism.machai/bindex-core", "coordinates": { "group": "org.machanism.machai", "artifactId": "bindex-core", "version": "1.4.3", "extension": "jar" } }, "constructors": [ { "package": "org.machanism.machai.bindex.core", "signature": "public org.machanism.machai.bindex.core.Picker(org.machanism.machai.bindex.core.BindexRepository, org.machanism.macha.core.commons.configurator.Configurator)", "description": "Creates the service coordinating Bindex metadata registration, semantic search, natural-language request classification, embedding generation, and recommendation through a supplied repository and runtime configuration.", "examples": [ { "snippet": "org.machanism.machai.bindex.core.BindexRepository repository = new org.machanism.machai.bindex.core.MongoBindexRepository(configurator);\norg.machanism.machai.bindex.core.Picker picker = new org.machanism.machai.bindex.core.Picker(configurator, repository);", "description": "Configure GenAI, embedding, and MongoDB settings with the host Configurator, create the repository adapter, and pass both dependencies to the Picker for subsequent library searches. Close the MongoDB repository when finished." } ] }, { "package": "org.machanism.machai.bindex.core", "signature": "public org.machanism.machai.bindex.core.MongoBindexRepository(org.machanism.macha.core.commons.configurator.Configurator)", "description": "Creates a MongoDB-backed implementation of the BindexRepository persistence contract using the provided application configuration. It stores Bindex descriptors and embeddings and supports retrieval and vector-based candidate searches.", "examples": [ { "snippet": "org.machanism.machai.bindex.core.MongoBindexRepository repository = new org.machanism.machai.bindex.core.MongoBindexRepository(configurator);", "description": "Instantiate the MongoDB adapter after configuring the repository connection and credentials; call close after use to release MongoDB client resources." } ] }, { "package": "org.machanism.machai.bindex.ai.tools", "signature": "public org.machanism.machai.bindex.ai.tools.BindexFunctionTools()", "description": "Creates the AI function-tool provider exposing Bindex descriptor lookup, library recommendations, descriptor registration, schema resources, and generation prompts to a compatible host.", "examples": [ { "snippet": "org.machanism.machai.bindex.ai.tools.BindexFunctionTools tools = new org.machanism.machai.bindex.ai.tools.BindexFunctionTools();", "description": "Register or expose this provider with a compatible Function Tools host so the host can discover its annotated operations, resource, and prompt template." } ] } ], "features": [ { "name": "find", "package": "org.machanism.machai.bindex.core", "signature": "java.util.Collection find(org.machanism.machai.schema.Classification[] classifications, java.util.List embedding, long vectorSearchLimits, double score, org.machanism.macha.core.commons.configurator.Configurator config)", "description": "BindexRepository search contract for retrieving candidate descriptors through semantic vector similarity and optional classification filters. Applies a similarity threshold and candidate limit and returns compact BindexInfo results, typically ordered by score.", "examples": [ { "snippet": "java.util.Collection matches = repository.find(classifications, queryEmbedding, 25L, 0.85d, configurator);", "description": "Search for relevant registered components using an embedding generated for the user's requirement; pass classification constraints when the search should be limited by technical category." } ] }, { "name": "getRecommendedLibraries", "package": "org.machanism.machai.bindex.core", "signature": "java.util.Collection pick(java.lang.String prompt, long vectorSearchLimits, double score, org.machanism.macha.core.commons.configurator.Configurator configurator) throws java.io.IOException", "description": "Classifies a natural-language development request, obtains its embedding, searches the configured repository, and returns relevant library summaries according to the requested candidate limit and minimum semantic score.", "examples": [ { "snippet": "java.util.Collection matches = picker.pick(\"Find Java components for semantic software library discovery\", 25L, 0.85d, configurator);", "description": "Use the Picker during application planning to obtain candidate artifacts matching a real implementation need, then inspect full metadata before selecting dependencies." } ] }, { "name": "getBindex", "package": "org.machanism.machai.bindex.ai.tools", "signature": "org.machanism.machai.schema.Bindex getBindex(java.lang.String id, java.lang.String graphqlQuery, java.io.File projectDir, org.machanism.macha.core.commons.configurator.Configurator configurator)", "description": "Loads a Bindex descriptor by registered identifier, HTTP(S) URL, or project-contained local file and optionally projects requested top-level fields using a GraphQL-style selection. Nested objects are returned whole rather than recursively projected.", "examples": [ { "snippet": "org.machanism.machai.schema.Bindex descriptor = tools.getBindex(\"org.machanism.machai:bindex-core:1.4.3\", \"{ name version classification { languages } }\", new java.io.File(\".\"), configurator);", "description": "Retrieve a registered descriptor while requesting only identity and classification fields needed by an agent." } ] }, { "name": "registerBindex", "package": "org.machanism.machai.bindex.ai.tools", "signature": "java.lang.String registerBindex(java.lang.String file, java.io.File projectDir, org.machanism.macha.core.commons.configurator.Configurator configurator)", "description": "Reads a Bindex descriptor from a project-contained file or HTTP(S) URL and registers it with the configured repository, returning the saved identifier. File-based paths must remain within the supplied project directory.", "examples": [ { "snippet": "java.lang.String id = tools.registerBindex(\"bindex.json\", new java.io.File(\".\"), configurator);", "description": "Register a reviewed descriptor from the root of the current project for subsequent recommendation and discovery." } ] }, { "name": "registerBindexJson", "package": "org.machanism.machai.bindex.ai.tools", "signature": "java.lang.String registerBindexJson(org.machanism.machai.schema.Bindex bindex, org.machanism.macha.core.commons.configurator.Configurator configurator)", "description": "Registers a Bindex schema-model object already in memory and returns its assigned identifier, avoiding an intermediate local file or remote download.", "examples": [ { "snippet": "java.lang.String id = tools.registerBindexJson(descriptor, configurator);", "description": "Submit an already prepared org.machanism.machai.schema.Bindex object directly from an AI integration or Java workflow." } ] } ], "customizations": [ { "name": "BindexRepository", "package": "org.machanism.machai.bindex.core", "description": "Persistence and semantic-search boundary for storing Bindex descriptors, retrieving entries by identifier, and finding candidates based on embedding vectors and classification constraints. Applications can provide another implementation when a storage backend other than MongoDB is required.", "type": "interface", "examples": [ { "snippet": "public final class InMemoryBindexRepository implements org.machanism.machai.bindex.core.BindexRepository {\n public java.util.Collection find(org.machanism.machai.schema.Classification[] classifications, java.util.List embedding, long vectorSearchLimits, double score, org.machanism.macha.core.commons.configurator.Configurator config) { return java.util.List.of(); }\n public org.machanism.machai.schema.Bindex getBindex(java.lang.String id) { return null; }\n public java.lang.String save(org.machanism.machai.schema.Bindex bindex, java.util.List embedding) { return bindex.getId(); }\n}", "description": "Implement the public repository contract to substitute test, in-memory, or application-specific persistence; replace the illustrative method bodies with actual storage and retrieval behavior." } ] }, { "name": "BINDEX_REPO_URL, BINDEX_USER, and BINDEX_PASSWORD", "description": "Environment configuration for the MongoDB repository URI and optional authentication credentials. A local MongoDB Atlas Local setup can use mongodb://localhost:27017/?appName=machanism with user and pass credentials.", "type": "environment configuration", "examples": [ { "snippet": "$env:BINDEX_REPO_URL = \"mongodb://localhost:27017/?appName=machanism\"\n$env:BINDEX_USER = \"user\"\n$env:BINDEX_PASSWORD = \"pass\"", "description": "PowerShell example configuring application connection settings for a local development repository before launching the Java process." } ] } ], "studs": [ { "name": "org.machanism.machai.bindex.core.BindexRepository", "package": "org.machanism.machai.bindex.core", "type": "interface", "description": "Storage gateway contract defining Bindex descriptor retrieval and saving, as well as embedding-based recommendations with classification and score filtering. Implement this interface to connect Picker workflows to a persistence implementation.", "implement": "org.machanism.machai.bindex.core.MongoBindexRepository" } ], "examples": [ { "title": "Install and use Bindex Core in a Maven Java application", "steps": [ "Add org.machanism.machai:bindex-core:1.4.3 as a dependency in the consuming project's pom.xml.", "Configure the host Configurator with GenAI and embedding provider credentials and model settings, plus the MongoDB repository URI and credentials.", "Create org.machanism.machai.bindex.core.MongoBindexRepository and org.machanism.machai.bindex.core.Picker using the configured runtime settings.", "Call Picker.pick with a specific natural-language requirement, candidate limit, minimum score, and Configurator; inspect returned BindexInfo records and retrieve complete descriptors as needed.", "Close MongoBindexRepository when the application is done so its MongoDB client resources are released." ], "dependency": "\n org.machanism.machai\n bindex-core\n 1.4.3\n", "configuration": "Set BINDEX_REPO_URL, BINDEX_USER, and BINDEX_PASSWORD for MongoDB; configure the host's GenAI and embedding services through org.machanism.macha.core.commons.configurator.Configurator.", "scenario": "A Java application planning a new feature queries its organization's Bindex catalog for relevant reusable components before choosing dependencies." }, { "title": "Run Bindex tools via the Machai MCP server on Windows", "steps": [ "Install a Java 17 or later runtime and download machai-mcp-server.jar and bindex-core.jar into a working directory.", "Configure GENAI_USERNAME, GENAI_PASSWORD, embedding.model, gw.model, BINDEX_REPO_URL, BINDEX_USER, and BINDEX_PASSWORD for the target environment; keep secrets outside committed configuration.", "Start the MCP server from PowerShell with the downloaded artifacts on a semicolon-separated classpath and choose an available TCP port.", "Connect an MCP-compatible client and invoke get_bindex to inspect metadata, pick_libraries to discover relevant artifacts, or register_bindex to publish a reviewed descriptor." ], "command": "java -DGENAI_PASSWORD= -DGENAI_USERNAME= -cp \"machai-mcp-server.jar;bindex-core.jar\" -Dembedding.model=CodeMie:text-embedding-005 -Dgw.model=CodeMie:gpt-5.4-2026-03-05 org.machanism.machai.mcp.server.McpServer -p 45000", "configuration": "Supply model and database settings as JVM properties or environment variables supported by the Machai host, and configure MCP clients to connect to the selected server transport and port.", "scenario": "A development team offers a single controlled MCP endpoint that lets multiple IDE assistants search and inspect the shared component catalog." }, { "title": "Run a local MongoDB Bindex repository for development", "steps": [ "Install Docker Desktop with Docker Compose support and ensure the Docker engine is running.", "From the project root, start the Atlas Local service with docker compose -f src/docker/mongodb/docker-compose.yml up -d.", "Configure the Java process with BINDEX_REPO_URL=mongodb://localhost:27017/?appName=machanism, BINDEX_USER=user, and BINDEX_PASSWORD=pass, together with valid GenAI provider settings.", "Run the Java application or MCP host using Bindex Core; inspect service health with docker compose -f src/docker/mongodb/docker-compose.yml ps and stop the service with docker compose -f src/docker/mongodb/docker-compose.yml down." ], "scenario": "A developer validates descriptor registration and semantic searches locally against the documented Atlas Local database without using a remote MongoDB deployment." } ], "dependencies": [ "org.machanism.machai:genai-client:1.4.3", "org.tomlj:tomlj:2.1.1", "com.graphql-java:graphql-java:22.3", "org.apache.maven:maven-core:3.9.6", "org.mongodb:mongodb-driver-sync:5.6.4" ] }