@sisu-ai/vector-core

v1.1.0

Published

7 days ago

Share provider-agnostic vector types and math utilities across Sisu vector tools and middleware.

Downloads

416

0High
0Medium
0Low

lejahmie

sisu ai ai-agent agentic vector core

@sisu-ai/vector-core

Share provider-agnostic vector types and math utilities across Sisu vector tools and middleware.

Setup

npm i @sisu-ai/vector-core

Philosophy

@sisu-ai/vector-core is the storage-contract layer for Sisu.

It defines the minimal types and interfaces needed to talk to a vector backend.
It does not know about chunking, embeddings orchestration, prompt building, or model-facing tools.
It gives backend adapters and higher-level RAG packages a small, explicit contract to share.

This keeps Sisu’s boundaries clean:

@sisu-ai/vector-core defines the contract
@sisu-ai/vector-chroma implements the contract for Chroma
@sisu-ai/vector-vectra implements the contract for local file-backed Vectra indexes
@sisu-ai/rag-core builds reusable RAG mechanics on top of the contract
@sisu-ai/tool-rag exposes model-facing tools on top of @sisu-ai/rag-core
@sisu-ai/mw-rag composes deterministic middleware flows on top of a VectorStore

What It Provides

Contracts

Embedding — number[]
VectorRecord — { id, embedding, metadata?, namespace? }
QueryRequest — { embedding, topK, filter?, namespace? }
QueryResult — { matches: Array<{ id, score, metadata? }> }
VectorStore — { upsert(...), query(...), delete?(...) }

Math helpers

dot(a, b)
l2Norm(v)
normalize(v)
cosineSimilarity(a, b)

How The Stack Fits Together

The usual stack looks like this:

App code or a tool gets embeddings from a provider
A VectorStore implementation writes or queries vectors
@sisu-ai/rag-core handles chunking, record preparation, and retrieval shaping
@sisu-ai/tool-rag or @sisu-ai/mw-rag turns that into agent behavior

Example composition:

import { openAIEmbeddings } from '@sisu-ai/adapter-openai';
import { createVectraVectorStore } from '@sisu-ai/vector-vectra';
import { storeRagContent } from '@sisu-ai/rag-core';
import { createRagTools } from '@sisu-ai/tool-rag';

const embeddings = openAIEmbeddings({ model: 'text-embedding-3-small' });
const vectorStore = createVectraVectorStore({ folderPath: '.vectra', namespace: 'docs' });

await storeRagContent({
  content: 'Sisu keeps packages small and composable.',
  embeddings,
  vectorStore,
});

const ragTools = createRagTools({ embeddings, vectorStore });

Example shape of ingestion records:

import type { VectorRecord } from '@sisu-ai/vector-core';

const records: VectorRecord[] = [
  { id: 'doc-1', embedding: [/* numbers */], metadata: { text: 'hello' }, namespace: 'myspace' },
  { id: 'doc-2', embedding: [/* numbers */], metadata: { text: 'world' }, namespace: 'myspace' },
];

Example query result:

import type { QueryResult } from '@sisu-ai/vector-core';

const res: QueryResult = {
  matches: [
    { id: 'doc-1', score: 0.92, metadata: { text: 'hello' } },
    { id: 'doc-2', score: 0.87, metadata: { text: 'world' } },
  ]
};

Building a New Vector Provider

To add a new backend, implement VectorStore in a vector-* package.

Example skeleton:

import type { VectorStore } from '@sisu-ai/vector-core';

export function createExampleVectorStore(): VectorStore {
  return {
    async upsert({ records, namespace, signal }) {
      return { count: records.length };
    },
    async query({ embedding, topK, filter, namespace, signal }) {
      return { matches: [] };
    },
    async delete({ ids, namespace, signal }) {
      return { count: ids.length };
    },
  };
}

That adapter can then be used by:

@sisu-ai/rag-core
@sisu-ai/tool-rag
@sisu-ai/mw-rag

@sisu-ai/vector-chroma and @sisu-ai/vector-vectra are the concrete maintained examples to follow.

What Does Not Belong Here

These concerns live elsewhere on purpose:

chunking and content preparation → @sisu-ai/rag-core
model-facing tools → @sisu-ai/tool-rag
middleware prompt composition → @sisu-ai/mw-rag
backend SDK implementation details → vector-* adapter packages

See examples/openai-rag-chroma and examples/openai-rag-vectra for full composition paths.

Notes

Namespaces: optional per‑provider routing. If you don’t need them, omit.
Filters: QueryRequest.filter is an open object passed through to the tool/provider; shape depends on the adapter.
Dimensions: math helpers require same‑dimensional vectors and guard against zero vectors for normalization/cosine.

Community & Support

Discover what you can do through examples or documentation. Check it out at https://github.com/finger-gun/sisu. Example projects live under examples/ in the repo.