@vectorai-sdk/sdk

Official TypeScript/JavaScript SDK for VectorAI — The Universal Vector Engine & Zero-Trust Knowledge Gateway by AcadmyAI.

Features

• Universal Vector Gateway: Connect your apps, autonomous agents, and bots to PostgreSQL (pgvector), Qdrant, or In-Memory RAM vector stores via a single unified API.
• Zero-Trust Security: Built-in wire-speed Presidio PII tokenization (Aadhaar, PAN, SSN, emails, credit cards) and prompt-injection firewalls.
• BYOK Multi-Model Embedding: Route embeddings seamlessly across Gemini, OpenAI, Cohere, Voyage AI, and HuggingFace.
• Agent & Bot Memory: Effortlessly store episodic agent memory, sales battlecards (e.g. LaunchAI SDRs), customer support context, and Discord/Telegram bot data.
• Full TypeScript Definitions: Strongly typed parameters, hits, collections, and configurations.
• Zero Heavy Dependencies: Native fetch support for Node.js 18+, Bun, Deno, Next.js Server Actions, and modern browsers.

Installation

# npm
npm install @vectorai-sdk/sdk

# pnpm
pnpm add @vectorai-sdk/sdk

# yarn
yarn add @vectorai-sdk/sdk

# bun
bun add @vectorai-sdk/sdk

Client Initialization

import { VectorAIClient } from "@vectorai-sdk/sdk";

// Initialize client with your profile-scoped API key
const client = new VectorAIClient({
  apiKey: process.env.VECTORAI_API_KEY || "vec_live_YOUR_API_KEY",
  baseUrl: "https://vector.acadmyai.com", // Optional, defaults to production
  timeout: 30000,                         // Optional, default 30s
});

Configuration Options

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | apiKey | string | (Required) | Profile API key starting with vec_live_ or sk-lvl1- | | baseUrl | string | "https://vector.acadmyai.com" | Gateway API endpoint | | timeout | number | 30000 | Request timeout in milliseconds | | fetch | typeof fetch | globalThis.fetch | Custom fetch polyfill for Node < 18 or proxies |

API Reference & Methods

1. Ingest Documents (client.ingest)

Extracts, chunks, masks PII with Presidio, embeds, and indexes text or documents into your collection.

const result = await client.ingest({
  text: "Enterprise SSO supports Okta, Google Workspace, and Azure AD with SCIM provisioning.",
  collection_name: "launch_sales_vault",
  metadata: {
    category: "security_compliance",
    doc_type: "sales_battlecard",
    agent_id: "launch_sdr_01",
  },
  pii_redaction: true,               // Automatically masks sensitive PII entities
  threat_action: "sanitize",         // "block" | "sanitize" | "monitor"
  chunk_size: 512,                   // Optional chunk size in characters/tokens
  chunk_overlap: 64,                 // Optional chunk overlap
});

console.log(`Stored ${result.chunks_stored} chunks in collection: ${result.collection_name}`);

2. Semantic Search (client.search)

Performs high-dimensional cosine similarity search with optional metadata filtering, dynamic clearance level filtering, and prompt injection defense.

const response = await client.search({
  query: "How do we configure SAML SSO with Okta?",
  collection_name: "launch_sales_vault",
  top_k: 3,
  filter: {
    category: { $eq: "security_compliance" },
  },
  threat_action: "sanitize",         // Sanitizes prompt injections in queries
  min_score: 0.65,                   // Optional similarity score floor (0.0 to 1.0)
});

for (const hit of response.results) {
  console.log(`[Score: ${hit.score.toFixed(4)}] ID: ${hit.id}`);
  console.log(`Content:`, hit.payload.text);
  console.log(`Metadata:`, hit.payload);
}
console.log(`Search Latency: ${response.latency_ms}ms`);

3. Collection Management

List Collections

const collections = await client.listCollections();
// Returns: [{ name: "launch_sales_vault", vectors_count: 142, status: "ready", dimension: 768 }]

Create Collection

await client.createCollection({
  collection_name: "financial_reports",
  dimension: 1536,                   // Match target embedding model dimension
  distance: "Cosine",                // "Cosine" | "Euclidean" | "Dot"
});

Delete Collection

await client.deleteCollection("financial_reports");

4. Vector Deletion (client.delete)

Remove specific vector records by ID from a collection:

await client.delete({
  collection_name: "launch_sales_vault",
  vector_ids: ["chunk_01", "chunk_02"],
});

5. Health & Connectivity Check (client.health)

const health = await client.health();
console.log(`VectorAI Gateway Status: ${health.status}`);

Universal Metadata Filter Syntax

VectorAI supports standard MongoDB-style JSON filter operators across pgvector, Qdrant, and memory backends:

const searchResults = await client.search({
  query: "Enterprise tier features",
  collection_name: "pricing_docs",
  filter: {
    // Exact equality / Inequality
    status: { $eq: "published" },
    archived: { $ne: true },
    // Array containment
    department: { $in: ["sales", "product", "security"] },
    // Numeric comparison
    year: { $gte: 2025, $lte: 2026 },
  },
});

Agent & Framework Integration Examples

1. LaunchAI SDR Objection Grounding (Node.js / Next.js)

import { VectorAIClient } from "@vectorai-sdk/sdk";

const vectorai = new VectorAIClient({ apiKey: process.env.VECTORAI_API_KEY! });

export async function groundSalesObjection(prospectObjection: string) {
  const result = await vectorai.search({
    query: prospectObjection,
    collection_name: "sales_battlecards",
    top_k: 2,
    threat_action: "sanitize", // Neutralize adversarial jailbreaks
  });

  if (result.results.length === 0) {
    return "No verified battlecard found. Defer to solutions architect.";
  }

  return result.results.map((hit) => hit.payload.text).join("\n\n");
}

2. Next.js 14 Server Action / Vercel AI SDK Tool

"use server";

import { VectorAIClient } from "@vectorai-sdk/sdk";

const client = new VectorAIClient({ apiKey: process.env.VECTORAI_API_KEY! });

export async function searchCorporateVault(query: string) {
  const response = await client.search({
    query,
    collection_name: "corporate_vault",
    top_k: 4,
  });

  return response.results.map((r) => ({
    id: r.id,
    content: r.payload.text,
    source: r.payload.source_url,
    score: r.score,
  }));
}

3. Error Handling Pattern

try {
  const hits = await client.search({
    query: "Q3 revenue guidance",
    collection_name: "finance_vault",
  });
} catch (err: any) {
  if (err.message.includes("(401)")) {
    console.error("Authentication failed: Check vec_live_ API key.");
  } else if (err.message.includes("(429)")) {
    console.warn("Rate limit exceeded: Standard tier 120 req/min.");
  } else {
    console.error("VectorAI Request failed:", err.message);
  }
}

License

Apache-2.0. Copyright (c) 2026 AcadmyAI.