KB Client

Simple, clean Knowledge Base client for adding and retrieving data from vector database

A lightweight wrapper around ChromaDB (local & cloud) and Pinecone (cloud) with OpenAI that makes it dead simple to:

• ✅ Add data to your knowledge base
• ✅ Search/retrieve data semantically
• ✅ Isolate data per user/workspace using collections/namespaces
• ✅ Automatic deduplication
• ✅ Configurable - supports both ChromaDB and Pinecone

Installation

npm install @quickcontent/kb-client
# or
bun add @quickcontent/kb-client

Quick Start

Using ChromaDB (Local)

import { KBClient } from '@quickcontent/kb-client';

// Initialize with ChromaDB
const kb = new KBClient({
  provider: 'chromadb',
  chromaUrl: 'http://localhost:8000',
  collectionName: 'my-collection',
  openaiApiKey: process.env.OPENAI_API_KEY!,
});

// Add data
await kb.addData({
  text: 'Our brand sells eco-friendly water bottles made from recycled materials',
  metadata: {
    type: 'brand-info',
    category: 'products'
  }
});

// Get data
const results = await kb.getData({
  query: 'What products does the brand sell?',
  topK: 5
});

console.log(results.items[0].text);
// "Our brand sells eco-friendly water bottles..."

Using Pinecone (Cloud)

import { KBClient } from '@quickcontent/kb-client';

// Initialize with Pinecone
const kb = new KBClient({
  provider: 'pinecone',
  pineconeApiKey: process.env.PINECONE_API_KEY!,
  pineconeIndexName: 'my-index',
  openaiApiKey: process.env.OPENAI_API_KEY!,
  namespace: 'user-123', // Isolate per user/workspace
});

// Same API for both providers
await kb.addData({ text: 'Data...' });
const results = await kb.getData({ query: 'query' });

API Reference

Constructor

new KBClient(config: KBConfig)

ChromaDB Config:

• provider: 'chromadb' - Use ChromaDB (required)
• chromaUrl - ChromaDB server URL (default: "http://localhost:8000")
• collectionName - Collection name for data isolation (required)
• openaiApiKey - OpenAI API key (required)
• embeddingModel - OpenAI embedding model (default: "text-embedding-3-large")
• embeddingDimensions - Embedding dimensions (default: 3072)

Pinecone Config:

• provider: 'pinecone' - Use Pinecone (required)
• pineconeApiKey - Pinecone API key (required)
• pineconeIndexName - Pinecone index name (required)
• openaiApiKey - OpenAI API key (required)
• namespace - Namespace for data isolation (default: "default")
• embeddingModel - OpenAI embedding model (default: "text-embedding-3-large")
• embeddingDimensions - Embedding dimensions (default: 3072)

addData()

Add a single piece of data to the knowledge base.

await kb.addData({
  text: string,
  metadata?: Record<string, any>,
  externalId?: string
});

Returns: { id, success, message }

addDataBatch()

Add multiple items at once.

await kb.addDataBatch([
  { text: 'First item', metadata: { type: 'info' } },
  { text: 'Second item', metadata: { type: 'description' } }
]);

Returns: Array of { id, success, message }

getData()

Search for data using semantic similarity.

await kb.getData({
  query: string,
  topK?: number,        // Number of results (default: 10)
  filter?: object,      // Metadata filter
  namespace?: string    // Override default namespace
});

Returns: { items: KBDataItem[], total: number }

Each item contains:

• id - Unique identifier
• score - Similarity score (0-1)
• text - Original text
• metadata - Associated metadata

deleteData()

Delete a specific item by ID.

await kb.deleteData(id, namespace?);

deleteAll()

Delete all data in a namespace.

await kb.deleteAll(namespace?);

getStats()

Get statistics about the namespace.

const stats = await kb.getStats();
console.log(stats.vectorCount); // Number of items

Usage Examples

Workspace-Specific Data

// Workspace A
const kbA = new KBClient({
  pineconeApiKey: process.env.PINECONE_API_KEY!,
  pineconeIndexName: 'quickcontent',
  openaiApiKey: process.env.OPENAI_API_KEY!,
  namespace: 'workspace-aaa',
});

await kbA.addData({ text: 'Workspace A data' });

// Workspace B
const kbB = new KBClient({
  pineconeApiKey: process.env.PINECONE_API_KEY!,
  pineconeIndexName: 'quickcontent',
  openaiApiKey: process.env.OPENAI_API_KEY!,
  namespace: 'workspace-bbb',
});

await kbB.addData({ text: 'Workspace B data' });

// Searches are isolated
const resultsA = await kbA.getData({ query: 'data' });
// Only returns Workspace A data

Brand Information

// Add brand info
await kb.addData({
  text: 'We are a sustainable fashion brand focused on ethical manufacturing',
  metadata: {
    type: 'brand-description',
    source: 'manual',
  }
});

await kb.addData({
  text: 'Website: https://example.com, Instagram: @example',
  metadata: {
    type: 'social-links',
  }
});

// Search
const results = await kb.getData({
  query: 'What is the brand about?',
  topK: 3
});

Metadata Filtering

// Add with categories
await kb.addData({
  text: 'Product info...',
  metadata: { category: 'products', verified: true }
});

// Search only verified products
const results = await kb.getData({
  query: 'product',
  filter: {
    category: 'products',
    verified: true
  }
});

Environment Variables

For ChromaDB

CHROMA_URL=http://localhost:8000  # or cloud URL
OPENAI_API_KEY=your-openai-key

For Pinecone

PINECONE_API_KEY=your-pinecone-key
PINECONE_INDEX_NAME=your-index-name
OPENAI_API_KEY=your-openai-key

Features

• 🚀 Simple API - Just addData() and getData()
• 🔄 Multi-Provider - Switch between ChromaDB (local/cloud) and Pinecone (cloud)
• 🔒 Isolation - Separate data per user/workspace via collections/namespaces
• 🎯 Semantic Search - Find relevant data using natural language queries
• ♻️ Deduplication - Automatic content hashing prevents duplicates
• 📦 Batch Operations - Add multiple items efficiently
• 🏷️ Metadata Support - Tag and filter your data flexibly
• 📊 Stats - Monitor your knowledge base usage
• 🔐 Type-Safe - Full TypeScript support with exported types
• 🌐 RAG-Ready - Perfect for RAG (Retrieval Augmented Generation) applications

Use Cases

• 🤖 AI Chatbots - Store and retrieve company knowledge for context-aware responses
• 📝 Content Generation - Feed brand information to AI for personalized content
• 🔍 Semantic Search - Build powerful search features for documents and data
• 💬 RAG Applications - Retrieval Augmented Generation for accurate AI responses
• 📚 Knowledge Bases - Organize and search through large document collections
• 🏢 Multi-Tenant Apps - Isolated data per user/workspace/organization
• 🎯 Recommendation Systems - Find similar content based on embeddings

TypeScript Support

Full TypeScript support with exported types:

import type {
  KBConfig,
  AddDataParams,
  AddDataResult,
  GetDataParams,
  GetDataResult,
  KBDataItem
} from '@quickcontent/kb-client';

Why KB Client?

• Universal - One API for both ChromaDB and Pinecone
• Production-Ready - Used in production apps serving thousands of users
• Developer-Friendly - Clean, intuitive API that just works
• Flexible - Start local with ChromaDB, scale to cloud with Pinecone
• Type-Safe - Full TypeScript support with detailed type definitions

License

MIT