Vector Database

Create indexes, upsert vectors, and query by similarity. Indexes use HNSW for approximate-nearest-neighbor search.

Create an index

Provide a dimension + metric for raw vectors, or an embed model for integrated embedding (the server embeds your text):

import { createIndexClient } from "@unispec-ai/sdk";
const vectors = createIndexClient({ apiKey: process.env.UNISPEC_API_KEY });

// Raw vectors
await vectors.createIndex({ name: "products", dimension: 384, metric: "cosine" });

// Integrated embedding (no client-side embeddings needed)
await vectors.createIndex({
  name: "docs",
  embed: { model: "bge-small-en-v1.5", field_map: { text: "text" } },
});

Upsert & query

const idx = vectors.index("docs");
await idx.upsertText([{ _id: "d1", text: "The Eiffel Tower is in Paris." }]);

const res = await idx.query({ text: "Where is the Eiffel Tower?", topK: 3, includeMetadata: true });

For raw-vector indexes, upsert { id, values, metadata } and query by vector.

Hybrid search

Dense embeddings miss exact tokens (SKUs, error codes, names); keyword search misses paraphrase. A hybrid index owns both a dense vector space and a sparse full-text space, and text queries fuse the two rankings with Reciprocal Rank Fusion:

await vectors.createIndex({
  name: "support",
  vectorType: "hybrid",
  embed: { model: "bge-small-en-v1.5" },
});

const idx = vectors.index("support");
await idx.upsertText([{ _id: "t1", text: "Error ERR-4012: payment gateway timeout" }]);

// mode defaults to "hybrid" on hybrid indexes when text is given
const res = await idx.query({ text: "ERR-4012", topK: 3 });

Details:

• mode: "dense" | "sparse" | "hybrid" — force one leg or the fusion. Vector-only queries always run dense, so existing callers never change behavior. The fused score is an RRF score, not a cosine similarity.
• The sparse space reads text from the index's text field by default; override at creation with sparse: { source: "metadata:<field>" }. Raw upsert on hybrid indexes must include that text field in metadata.
• Namespaces and metadata filters apply to both legs. One hybrid query counts as one vector read.
• The sparse encoder is Postgres full-text (simple config) in v1 — exact-term oriented; learned sparse (SPLADE) can replace it later without API changes.

Capabilities

• Metrics: cosine, euclidean, dotproduct.
• Namespaces, metadata filters, fetch/list, and describe_index_stats.