@xanots/vector

A complete, production-grade vector embedding, document ingestion, chunking, and semantic similarity search module for XanoTS. Built around Google Gemini Multimodal Embeddings 2 (gemini-embedding-2) at 768 dimensions with native PostgreSQL pgvector indexing and AI agent search tools.

Features

• Gemini Embeddings 2: Native multimodal embeddings across text, images (PNG, JPEG, WebP), audio (WAV, MP3), and video (MP4) scaled to 768 dimensions via Matryoshka Representation Learning (MRL).
• Cross-Modal Vector Search: Seamlessly search text-to-text, text-to-image, image-to-image, or visual queries using cosine similarity (vector_cosine_ops).
• Configurable Chunking: Multi-strategy text segmentation (paragraph, sentence, markdown, fixed, custom) with configurable chunk size and character overlap.
• Document Management: Complete lifecycle tracking (pending, indexing, indexed, failed), multi-chunk storage, and atomic reindexing.
• AI Agent & MCP Tool: Ready-to-use vector_search tool definition for Xano LLM agents and MCP toolsets.
• Typed Client Interfaces: End-to-end type safety for request payloads and responses with zero runtime overhead.

Installation

npm install @xanots/vector @xanots/sdk

Quickstart

import { workspace, workspaceConfig } from "@xanots/sdk";
import { registerVector } from "@xanots/vector";

const ws = workspace("my-app").registerWorkspace(
  workspaceConfig({
    name: "my-app",
    env: {
      GEMINI_API_KEY: process.env.GEMINI_API_KEY!,
    },
  }),
);

export const vector = registerVector(ws, {
  apiKeyEnv: "GEMINI_API_KEY",
  defaultStrategy: "markdown",
});

export default vector.xano;

Configuration Options

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | apiKeyEnv | string | "GEMINI_API_KEY" | Environment variable name storing the Google Gemini API key. | | model | string | "gemini-embedding-2" | Embedding model identifier (gemini-embedding-2). | | defaultStrategy | ChunkStrategy | "paragraph" | Default chunking strategy: fixed, paragraph, sentence, markdown, custom. | | defaultChunkSize | number | 500 | Target character count per chunk (20 to 10000). | | defaultChunkOverlap | number | 50 | Overlap character count between consecutive chunks (>= 0 and < size). | | searchLimit | number | 10 | Default top-k results returned by vector search (1 to 100). | | searchThreshold | number | 0.0 | Default cosine similarity threshold (0.0 to 1.0). | | authTable | TableDef \| string | undefined | User authentication table for multi-tenant ownership scoping. | | authenticated | boolean | false | When true, scopes documents and endpoints to $auth.id. | | routePrefix | string | "vector" | URL route prefix for generated API endpoints. | | canonical | string | undefined | Canonical URL slug for the API group. |

API Endpoints

All endpoints are registered under the configured API Group (default route: /api:vector/vector/*):

| Verb | Path | Description | | :--- | :--- | :--- | | POST | /documents/create | Ingest and index a new text document or multimodal media asset. | | GET | /documents | List uploaded documents with pagination. | | GET | /documents/{id} | Retrieve a document and all of its vector chunks. | | DELETE | /documents/{id}/delete | Delete a document and cascade-delete its chunks. | | POST | /documents/{id}/reindex | Re-chunk and re-embed an existing document. | | POST | /search | Perform cosine similarity search (text, image, or raw vector). | | POST | /embed | Directly generate a 768-dim vector embedding for text or media. |

Examples

1. Ingesting Text Documents

await fetch("https://your-instance.xano.io/api:vector/vector/documents/create", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "System Architecture Guide",
    content: "# System Architecture\nOur service runs on Kubernetes with PostgreSQL...",
    mime_type: "text/markdown",
    strategy: "markdown",
    chunk_size: 400,
    chunk_overlap: 40,
  }),
});

2. Ingesting Multimodal Assets (Images, Audio, Video)

await fetch("https://your-instance.xano.io/api:vector/vector/documents/create", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "Product Diagram",
    content: "Diagram illustrating cloud sync architecture.",
    media_data: "<base64_image_data>",
    mime_type: "image/png",
    metadata: { category: "diagrams", width: 1024, height: 768 },
  }),
});

3. Cross-Modal Semantic Search

// Search using a natural language query
const res = await fetch("https://your-instance.xano.io/api:vector/vector/search", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    query: "Find architecture diagrams explaining cloud sync",
    limit: 5,
  }),
});
const { results, count } = await res.json();

AI Agent Search Tool

Include the vector_search tool directly in your LLM agent or MCP toolset definitions:

import { agent } from "@xanots/sdk";
import { vector } from "./vector-setup.js";

export const ragAgent = agent({
  name: "support_agent",
  instructions: "Answer user inquiries using the vector search tool to retrieve knowledge.",
  tools: [vector.searchTool],
});

License

MIT