VectorSearch: bounded exact cosine retrieval

Given the same vector space, filter documents first and then rank by cosine similarity.

Constructing a VectorSearchSpace requires identity and dimensions (1–16384). upsert({document,vector}) copies the document and normalizes the vector; mismatched dimensions, non-finite numbers, and zero vectors are rejected. search({vector,limit,filter,minScore?,groupBy?}) returns SearchHit[]. filter/groupBy are synchronous, limit is 1–1000, and minScore, when given, must be within [-1,1].

With groupBy configured, each group keeps only its highest score, with ties broken by id; the final order is score descending and then id. remove/clear only change the current in-memory index. It does not generate embeddings, query a database, or mix vectors from different models/dimensions; space version, authorization, index size, and persistence are decided by the App.

Progressive examples for the same business case

First retrieve documentation fragments in the same space

Beginner · Node.js

Two-dimensional vectors are used to show the contract; they do not represent real text embeddings or retrieval quality.

TypeScript

import { VectorSearch } from '@jangts/agent-core/kits/vector-search';
const index = new VectorSearch<{ id: string; text: string }>({ identity: 'demo-direction-v1', dimensions: 2 });
index.upsert({ document: { id: 'workflow', text: '工作流说明' }, vector: [1, 0] });
index.upsert({ document: { id: 'model', text: '模型说明' }, vector: [0, 1] });
console.log(index.search({ vector: [0.9, 0.1], limit: 2, filter: () => true }));

JavaScript

import { VectorSearch } from '@jangts/agent-core/kits/vector-search';
const index = new VectorSearch({ identity: 'demo-direction-v1', dimensions: 2 });
index.upsert({ document: { id: 'workflow', text: '工作流说明' }, vector: [1, 0] });
index.upsert({ document: { id: 'model', text: '模型说明' }, vector: [0, 1] });
console.log(index.search({ vector: [0.9, 0.1], limit: 2, filter: () => true }));

Add permissions, a threshold, and document grouping to the same search

Configuration · Node.js

TypeScript

import { VectorSearch } from '@jangts/agent-core/kits/vector-search';
type Chunk = { id: string; documentId: string; audience: string; text: string };
const index = new VectorSearch<Chunk>({ identity: 'demo-direction-v1', dimensions: 2 });
index.upsert({ document: { id: 'manual-1', documentId: 'manual', audience: 'public', text: '工作流定义' }, vector: [1, 0] });
index.upsert({ document: { id: 'manual-2', documentId: 'manual', audience: 'public', text: '工作流调用' }, vector: [0.95, 0.05] });
index.upsert({ document: { id: 'private-1', documentId: 'private', audience: 'owner', text: '内部说明' }, vector: [1, 0] });
console.log(index.search({ vector: [1, 0], limit: 5, minScore: 0.5, filter: row => row.audience === 'public', groupBy: row => row.documentId }));

JavaScript

import { VectorSearch } from '@jangts/agent-core/kits/vector-search';
const index = new VectorSearch({ identity: 'demo-direction-v1', dimensions: 2 });
index.upsert({ document: { id: 'manual-1', documentId: 'manual', audience: 'public', text: '工作流定义' }, vector: [1, 0] });
index.upsert({ document: { id: 'manual-2', documentId: 'manual', audience: 'public', text: '工作流调用' }, vector: [0.95, 0.05] });
index.upsert({ document: { id: 'private-1', documentId: 'private', audience: 'owner', text: '内部说明' }, vector: [1, 0] });
console.log(index.search({ vector: [1, 0], limit: 5, minScore: 0.5, filter: row => row.audience === 'public', groupBy: row => row.documentId }));

Policies & implementations

• Vector validation, normalization, filtering, and grouped ordering