@sisu-ai/vector-core

Provider‑agnostic vector types and math helpers for Sisu. Keep vector tools and middleware portable across providers.

Setup

npm i @sisu-ai/vector-core

What It Provides

• Types used by vector tools/middleware:
  • Embedding — number[]
  • VectorRecord — { id, embedding, metadata?, namespace? }
  • QueryRequest — { embedding, topK, filter?, namespace? }
  • QueryResult — { matches: Array<{ id, score, metadata? }> }
• Math helpers for local operations:
  • dot(a,b), l2Norm(v), normalize(v), cosineSimilarity(a,b)

Typical Usage

• With vector tools (e.g., @sisu-ai/tool-vec-chroma) and RAG middleware (@sisu-ai/mw-rag).

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' } },
  ]
};

Integration With RAG Middleware

Used by @sisu-ai/mw-rag:

• ragIngest() expects ctx.state.rag.records: VectorRecord[]
• ragRetrieve() expects ctx.state.rag.queryEmbedding: Embedding
• Stores retrieval at ctx.state.rag.retrieval: QueryResult

See examples in examples/openai-rag-chroma.

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.

• Code of Conduct
• Contributing Guide
• License
• Report a Bug
• Request a Feature