Vector Store Development

This section covers how to develop custom vector store plugins to integrate new vector databases into Astrsomn.

Overview

Astrsomn's vector store extension involves three core interfaces:

Interface	Responsibility
VecDriver	Vector driver entry point — manages data source connections and metadata
VecSource	Vector data source — manages connection lifecycle and Store creation
VecStore	Vector store — provides document CRUD operations

Extend AbstractVecDriver for VecDriver, then implement VecSource and VecStore separately.

Development Steps

1. Create Maven Module

<project>
    <groupId>com.astrsomn</groupId>
    <artifactId>astrsomn-vector-custom</artifactId>
    <version>0.2.0-SNAPSHOT</version>

    <dependencies>
        <dependency>
            <groupId>com.astrsomn</groupId>
            <artifactId>astrsomn-api-runtime</artifactId>
            <version>0.2.0-SNAPSHOT</version>
        </dependency>

        <!-- Vector database client SDK -->
    </dependencies>
</project>

2. Implement VecDriver

Extend AbstractVecDriver:

package com.astrsomn.vector.custom;

import com.astrsomn.api.runtime.common.langchain.extension.vector.AbstractVecDriver;
import com.astrsomn.api.runtime.common.langchain.extension.vector.VecSource;
import com.astrsomn.api.vector.entity.AiVecDriverEntity;
import com.astrsomn.api.vector.entity.AiVecSourceEntity;

public class CustomVecDriver extends AbstractVecDriver {

    @Override
    public String getExtensionKey() {
        return "CUSTOM";  // Unique driver identifier
    }

    @Override
    public VecSource bindSource(AiVecSourceEntity source) {
        // Bind source entity to a concrete VecSource implementation
        return new CustomVecSource(source);
    }

    @Override
    public AiVecDriverEntity getDriverEntity() {
        // Return driver metadata: name, parameter definitions (HOST, PORT, TOKEN)
        AiVecDriverEntity entity = new AiVecDriverEntity();
        entity.setName("Custom Vector Store");
        entity.setProvider("CUSTOM");
        entity.setParams(defineDriverParams());
        return entity;
    }
}

3. Implement VecSource

VecSource manages the connection to the vector database:

package com.astrsomn.vector.custom;

import com.astrsomn.api.runtime.common.langchain.extension.vector.VecSource;
import com.astrsomn.api.runtime.common.langchain.extension.vector.VecStore;
import com.astrsomn.api.vector.entity.AiVecSourceEntity;
import com.astrsomn.api.vector.entity.AiVecStoreEntity;

public class CustomVecSource implements VecSource {

    private final AiVecSourceEntity sourceEntity;
    private CustomClient client;

    public CustomVecSource(AiVecSourceEntity sourceEntity) {
        this.sourceEntity = sourceEntity;
    }

    @Override
    public AiVecSourceEntity getEntity() {
        return sourceEntity;
    }

    @Override
    public boolean testConnection() {
        try {
            client.ping();
            return true;
        } catch (Exception e) {
            return false;
        }
    }

    @Override
    public void shutdown() {
        if (client != null) {
            client.close();
        }
    }

    @Override
    public VecStore openStore(AiVecStoreEntity store) {
        return new CustomVecStore(this, store);
    }
}

4. Implement VecStore

VecStore provides actual document storage operations:

package com.astrsomn.vector.custom;

import com.astrsomn.api.runtime.common.langchain.extension.vector.VecSource;
import com.astrsomn.api.runtime.common.langchain.extension.vector.VecStore;
import com.astrsomn.api.vector.entity.AiVecStoreEntity;
import dev.langchain4j.data.segment.TextSegment;
import dev.langchain4j.store.embedding.EmbeddingStore;

public class CustomVecStore implements VecStore {

    private final CustomVecSource source;
    private final AiVecStoreEntity storeEntity;

    public CustomVecStore(CustomVecSource source, AiVecStoreEntity storeEntity) {
        this.source = source;
        this.storeEntity = storeEntity;
    }

    @Override
    public VecSource getSource() { return source; }

    @Override
    public AiVecStoreEntity getEntity() { return storeEntity; }

    @Override
    public void createCollection() {
        // Create vector collection
    }

    @Override
    public void dropCollection() {
        // Drop vector collection
    }

    @Override
    public boolean exists() {
        return false;
    }

    @Override
    public long count() {
        return 0;
    }

    @Override
    public EmbeddingStore<TextSegment> getEmbeddingStore() {
        // Core method — returns LangChain4j EmbeddingStore implementation
        // All document add/search/delete operations flow through this
        return embeddingStore;
    }
}

Core Method: getEmbeddingStore()

getEmbeddingStore() returns a LangChain4j EmbeddingStore<TextSegment> implementation. This is the key bridge between the framework and the vector database — all document addition, search, and deletion goes through this interface. If your database already has a LangChain4j integration (Qdrant, Milvus, Chroma), you can use it directly.

5. Create Extension Descriptor

package com.astrsomn.vector.custom;

import com.astrsomn.starter.system.AstroExtensionDescriptor;
import com.astrsomn.api.system.entity.SystemExtensionEnum;

public class CustomVecExtensionDescriptor extends AstroExtensionDescriptor {

    @Override
    public String getExtensionKey() { return "CUSTOM"; }

    @Override
    public String getExtensionCode() { return "CUSTOM"; }

    @Override
    public SystemExtensionEnum.ExtensionTypeEnum getExtensionType() {
        return SystemExtensionEnum.ExtensionTypeEnum.VECTOR_STORE;
    }
}

6. Register SPI

Create two files under src/main/resources/META-INF/services/:

File 1: com.astrsomn.api.runtime.common.langchain.extension.vector.VecDriver

com.astrsomn.vector.custom.CustomVecDriver

File 2: com.astrsomn.api.runtime.common.langchain.extension.AstroExtensionDescriptor

com.astrsomn.vector.custom.CustomVecExtensionDescriptor

Interface Reference

VecDriver

Package: com.astrsomn.api.runtime.common.langchain.extension.vector

Method	Return Type	Description
getExtensionKey()	String	Unique driver identifier
bindSource(AiVecSourceEntity)	VecSource	Binds source entity to a VecSource
getDriverEntity()	AiVecDriverEntity	Driver metadata (name, parameter definitions)
getVersion()	String	Version (default: "1.0.0")
getAuthor()	String	Author (default: "Astrsomn")

VecSource

Package: com.astrsomn.api.runtime.common.langchain.extension.vector

Method	Return Type	Description
getEntity()	AiVecSourceEntity	Source entity
testConnection()	boolean	Test connection health
shutdown()	void	Close connection, release resources
openStore(AiVecStoreEntity)	VecStore	Open or create a store

VecStore

Package: com.astrsomn.api.runtime.common.langchain.extension.vector

Method	Return Type	Description
getSource()	VecSource	Parent data source
getEntity()	AiVecStoreEntity	Store entity
createCollection()	void	Create collection
dropCollection()	void	Drop collection
exists()	boolean	Check if collection exists
count()	long	Document count
getEmbeddingStore()	EmbeddingStore<TextSegment>	Core — returns LangChain4j store

Build & Deploy

mvn clean package -DskipTests

cp target/astrsomn-vector-custom-0.2.0-SNAPSHOT.jar /path/to/astrsomn/plugins/

Reference Implementations

• Qdrant — astrsomn-plugins/astrsomn-vector/astrsomn-vector-qdrant/
• Milvus — astrsomn-plugins/astrsomn-vector/astrsomn-vector-milvus/
• Chroma — astrsomn-plugins/astrsomn-vector/astrsomn-vector-chroma/
• Redis — astrsomn-plugins/astrsomn-vector/astrsomn-vector-redis/

Related Documentation

• Interface Guide — Detailed API specifications
• Examples — Complete end-to-end examples
• Provider Development — Model provider plugin guide
• MCP Development — MCP protocol plugin guide