{"_id":"@anisirji/kb-client","name":"@anisirji/kb-client","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@anisirji/kb-client","version":"1.0.0","description":"Universal vector database client for ChromaDB and Pinecone with OpenAI embeddings. Simple addData() and getData() API for semantic search, RAG applications, and knowledge base management.","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","dev":"tsc --watch","prepublishOnly":"bun run build"},"keywords":["vector-database","chromadb","pinecone","openai","embeddings","semantic-search","rag","knowledge-base","ai","machine-learning","retrieval","similarity-search","vector-search","typescript"],"author":"","license":"MIT","repository":{"type":"git","url":"git+https://github.com/anisirji/kb-client-db.git"},"dependencies":{"@pinecone-database/pinecone":"^3.0.3","chromadb":"^1.8.1","openai":"^4.77.3","zod":"^3.23.8"},"devDependencies":{"@types/node":"^20.10.0","typescript":"^5.3.3"},"_id":"@anisirji/kb-client@1.0.0","gitHead":"583f35a07f17a8577ac37965c74579bd5cf74662","bugs":{"url":"https://github.com/anisirji/kb-client-db/issues"},"homepage":"https://github.com/anisirji/kb-client-db#readme","_nodeVersion":"22.17.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-XJcMCCAUWtAAerpIZJxXj7eFCItCUz84BiHiWCXLSLDG6wMbNBMIDHKUrvf0CYnFLIGd2cF5cnsJHLcIxQQFwg==","shasum":"776068703eae5608a5d854a668e5d4ceda5b9063","tarball":"https://registry.npmjs.org/@anisirji/kb-client/-/kb-client-1.0.0.tgz","fileCount":10,"unpackedSize":31104,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCu9V6BnjI23Fg3ZMRWXc6i7ceEYXlu+hLH+Nf3On7hAgIgR3pP2T5MftXgI+Mdqb/fn9FpbO6b5wd+HP1Hs6Ls1w0="}]},"_npmUser":{"name":"anisirji","email":"www.allinoneforyouhere@gmail.com"},"directories":{},"maintainers":[{"name":"anisirji","email":"www.allinoneforyouhere@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/kb-client_1.0.0_1763313059568_0.26578791356683507"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-16T17:10:59.396Z","1.0.0":"2025-11-16T17:10:59.773Z","modified":"2025-11-16T17:11:00.062Z"},"maintainers":[{"name":"anisirji","email":"www.allinoneforyouhere@gmail.com"}],"description":"Universal vector database client for ChromaDB and Pinecone with OpenAI embeddings. Simple addData() and getData() API for semantic search, RAG applications, and knowledge base management.","homepage":"https://github.com/anisirji/kb-client-db#readme","keywords":["vector-database","chromadb","pinecone","openai","embeddings","semantic-search","rag","knowledge-base","ai","machine-learning","retrieval","similarity-search","vector-search","typescript"],"repository":{"type":"git","url":"git+https://github.com/anisirji/kb-client-db.git"},"bugs":{"url":"https://github.com/anisirji/kb-client-db/issues"},"license":"MIT","readme":"# KB Client\n\n> Simple, clean Knowledge Base client for adding and retrieving data from vector database\n\nA lightweight wrapper around **ChromaDB** (local & cloud) and **Pinecone** (cloud) with OpenAI that makes it dead simple to:\n- ✅ Add data to your knowledge base\n- ✅ Search/retrieve data semantically\n- ✅ Isolate data per user/workspace using collections/namespaces\n- ✅ Automatic deduplication\n- ✅ Configurable - supports both ChromaDB and Pinecone\n\n## Installation\n\n```bash\nnpm install @quickcontent/kb-client\n# or\nbun add @quickcontent/kb-client\n```\n\n## Quick Start\n\n### Using ChromaDB (Local)\n\n```typescript\nimport { KBClient } from '@quickcontent/kb-client';\n\n// Initialize with ChromaDB\nconst kb = new KBClient({\n  provider: 'chromadb',\n  chromaUrl: 'http://localhost:8000',\n  collectionName: 'my-collection',\n  openaiApiKey: process.env.OPENAI_API_KEY!,\n});\n\n// Add data\nawait kb.addData({\n  text: 'Our brand sells eco-friendly water bottles made from recycled materials',\n  metadata: {\n    type: 'brand-info',\n    category: 'products'\n  }\n});\n\n// Get data\nconst results = await kb.getData({\n  query: 'What products does the brand sell?',\n  topK: 5\n});\n\nconsole.log(results.items[0].text);\n// \"Our brand sells eco-friendly water bottles...\"\n```\n\n### Using Pinecone (Cloud)\n\n```typescript\nimport { KBClient } from '@quickcontent/kb-client';\n\n// Initialize with Pinecone\nconst kb = new KBClient({\n  provider: 'pinecone',\n  pineconeApiKey: process.env.PINECONE_API_KEY!,\n  pineconeIndexName: 'my-index',\n  openaiApiKey: process.env.OPENAI_API_KEY!,\n  namespace: 'user-123', // Isolate per user/workspace\n});\n\n// Same API for both providers\nawait kb.addData({ text: 'Data...' });\nconst results = await kb.getData({ query: 'query' });\n```\n\n## API Reference\n\n### Constructor\n\n```typescript\nnew KBClient(config: KBConfig)\n```\n\n**ChromaDB Config:**\n- `provider: 'chromadb'` - Use ChromaDB (required)\n- `chromaUrl` - ChromaDB server URL (default: \"http://localhost:8000\")\n- `collectionName` - Collection name for data isolation (required)\n- `openaiApiKey` - OpenAI API key (required)\n- `embeddingModel` - OpenAI embedding model (default: \"text-embedding-3-large\")\n- `embeddingDimensions` - Embedding dimensions (default: 3072)\n\n**Pinecone Config:**\n- `provider: 'pinecone'` - Use Pinecone (required)\n- `pineconeApiKey` - Pinecone API key (required)\n- `pineconeIndexName` - Pinecone index name (required)\n- `openaiApiKey` - OpenAI API key (required)\n- `namespace` - Namespace for data isolation (default: \"default\")\n- `embeddingModel` - OpenAI embedding model (default: \"text-embedding-3-large\")\n- `embeddingDimensions` - Embedding dimensions (default: 3072)\n\n### addData()\n\nAdd a single piece of data to the knowledge base.\n\n```typescript\nawait kb.addData({\n  text: string,\n  metadata?: Record<string, any>,\n  externalId?: string\n});\n```\n\n**Returns:** `{ id, success, message }`\n\n### addDataBatch()\n\nAdd multiple items at once.\n\n```typescript\nawait kb.addDataBatch([\n  { text: 'First item', metadata: { type: 'info' } },\n  { text: 'Second item', metadata: { type: 'description' } }\n]);\n```\n\n**Returns:** Array of `{ id, success, message }`\n\n### getData()\n\nSearch for data using semantic similarity.\n\n```typescript\nawait kb.getData({\n  query: string,\n  topK?: number,        // Number of results (default: 10)\n  filter?: object,      // Metadata filter\n  namespace?: string    // Override default namespace\n});\n```\n\n**Returns:** `{ items: KBDataItem[], total: number }`\n\nEach item contains:\n- `id` - Unique identifier\n- `score` - Similarity score (0-1)\n- `text` - Original text\n- `metadata` - Associated metadata\n\n### deleteData()\n\nDelete a specific item by ID.\n\n```typescript\nawait kb.deleteData(id, namespace?);\n```\n\n### deleteAll()\n\nDelete all data in a namespace.\n\n```typescript\nawait kb.deleteAll(namespace?);\n```\n\n### getStats()\n\nGet statistics about the namespace.\n\n```typescript\nconst stats = await kb.getStats();\nconsole.log(stats.vectorCount); // Number of items\n```\n\n## Usage Examples\n\n### Workspace-Specific Data\n\n```typescript\n// Workspace A\nconst kbA = new KBClient({\n  pineconeApiKey: process.env.PINECONE_API_KEY!,\n  pineconeIndexName: 'quickcontent',\n  openaiApiKey: process.env.OPENAI_API_KEY!,\n  namespace: 'workspace-aaa',\n});\n\nawait kbA.addData({ text: 'Workspace A data' });\n\n// Workspace B\nconst kbB = new KBClient({\n  pineconeApiKey: process.env.PINECONE_API_KEY!,\n  pineconeIndexName: 'quickcontent',\n  openaiApiKey: process.env.OPENAI_API_KEY!,\n  namespace: 'workspace-bbb',\n});\n\nawait kbB.addData({ text: 'Workspace B data' });\n\n// Searches are isolated\nconst resultsA = await kbA.getData({ query: 'data' });\n// Only returns Workspace A data\n```\n\n### Brand Information\n\n```typescript\n// Add brand info\nawait kb.addData({\n  text: 'We are a sustainable fashion brand focused on ethical manufacturing',\n  metadata: {\n    type: 'brand-description',\n    source: 'manual',\n  }\n});\n\nawait kb.addData({\n  text: 'Website: https://example.com, Instagram: @example',\n  metadata: {\n    type: 'social-links',\n  }\n});\n\n// Search\nconst results = await kb.getData({\n  query: 'What is the brand about?',\n  topK: 3\n});\n```\n\n### Metadata Filtering\n\n```typescript\n// Add with categories\nawait kb.addData({\n  text: 'Product info...',\n  metadata: { category: 'products', verified: true }\n});\n\n// Search only verified products\nconst results = await kb.getData({\n  query: 'product',\n  filter: {\n    category: 'products',\n    verified: true\n  }\n});\n```\n\n## Environment Variables\n\n### For ChromaDB\n\n```env\nCHROMA_URL=http://localhost:8000  # or cloud URL\nOPENAI_API_KEY=your-openai-key\n```\n\n### For Pinecone\n\n```env\nPINECONE_API_KEY=your-pinecone-key\nPINECONE_INDEX_NAME=your-index-name\nOPENAI_API_KEY=your-openai-key\n```\n\n## Features\n\n- 🚀 **Simple API** - Just `addData()` and `getData()`\n- 🔄 **Multi-Provider** - Switch between ChromaDB (local/cloud) and Pinecone (cloud)\n- 🔒 **Isolation** - Separate data per user/workspace via collections/namespaces\n- 🎯 **Semantic Search** - Find relevant data using natural language queries\n- ♻️ **Deduplication** - Automatic content hashing prevents duplicates\n- 📦 **Batch Operations** - Add multiple items efficiently\n- 🏷️ **Metadata Support** - Tag and filter your data flexibly\n- 📊 **Stats** - Monitor your knowledge base usage\n- 🔐 **Type-Safe** - Full TypeScript support with exported types\n- 🌐 **RAG-Ready** - Perfect for RAG (Retrieval Augmented Generation) applications\n\n## Use Cases\n\n- 🤖 **AI Chatbots** - Store and retrieve company knowledge for context-aware responses\n- 📝 **Content Generation** - Feed brand information to AI for personalized content\n- 🔍 **Semantic Search** - Build powerful search features for documents and data\n- 💬 **RAG Applications** - Retrieval Augmented Generation for accurate AI responses\n- 📚 **Knowledge Bases** - Organize and search through large document collections\n- 🏢 **Multi-Tenant Apps** - Isolated data per user/workspace/organization\n- 🎯 **Recommendation Systems** - Find similar content based on embeddings\n\n## TypeScript Support\n\nFull TypeScript support with exported types:\n\n```typescript\nimport type {\n  KBConfig,\n  AddDataParams,\n  AddDataResult,\n  GetDataParams,\n  GetDataResult,\n  KBDataItem\n} from '@quickcontent/kb-client';\n```\n\n## Why KB Client?\n\n- **Universal** - One API for both ChromaDB and Pinecone\n- **Production-Ready** - Used in production apps serving thousands of users\n- **Developer-Friendly** - Clean, intuitive API that just works\n- **Flexible** - Start local with ChromaDB, scale to cloud with Pinecone\n- **Type-Safe** - Full TypeScript support with detailed type definitions\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-a339cbbb6c51d2705331b47700849a2c"}