Package Exports

@hivellm/vectorizer-client
@hivellm/vectorizer-client/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@hivellm/vectorizer-client) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Hive Vectorizer TypeScript Client SDK

High-performance TypeScript client for the Hive Vectorizer vector database.

Features

✅ Complete TypeScript Support: Full type safety and IntelliSense
✅ Async/Await: Modern async programming patterns
✅ Multiple Transport Protocols: HTTP/HTTPS and UMICP support
✅ HTTP Client: Native fetch-based HTTP client with robust error handling
✅ UMICP Protocol: High-performance protocol with compression and encryption
✅ Comprehensive Validation: Input validation and error handling
✅ 12 Custom Exceptions: Robust error management
✅ Logging: Configurable logging system
✅ Collection Management: CRUD operations for collections
✅ Vector Operations: Insert, search, update, delete vectors
✅ Semantic Search: Text and vector similarity search
✅ Embedding Generation: Text embedding support

Installation

npm install @hivellm/vectorizer-client

Quick Start

import { VectorizerClient } from '@hivellm/vectorizer-client';

// Create client
const client = new VectorizerClient({
  baseURL: 'http://localhost:15001',
  apiKey: 'your-api-key-here'
});

// Health check
const health = await client.healthCheck();
console.log('Server status:', health.status);

// Create collection
const collection = await client.createCollection({
  name: 'documents',
  dimension: 768,
  similarity_metric: 'cosine'
});

// Insert vectors
const vectors = [{
  data: [0.1, 0.2, 0.3, /* ... 768 dimensions */],
  metadata: { source: 'document1.pdf' }
}];

await client.insertVectors('documents', vectors);

// Search vectors
const results = await client.searchVectors('documents', {
  query_vector: [0.1, 0.2, 0.3, /* ... 768 dimensions */],
  limit: 5
});

// Text search
const textResults = await client.searchText('documents', {
  query: 'machine learning algorithms',
  limit: 5
});

// Generate embeddings
const embedding = await client.embedText({
  text: 'machine learning algorithms'
});

Configuration

HTTP Configuration (Default)

const client = new VectorizerClient({
  baseURL: 'http://localhost:15002',     // API base URL
  apiKey: 'your-api-key',                // API key for authentication
  timeout: 30000,                        // Request timeout in ms
  headers: {                             // Custom headers
    'User-Agent': 'MyApp/1.0'
  },
  logger: {                              // Logger configuration
    level: 'info',                       // debug, info, warn, error
    enabled: true
  }
});

UMICP Configuration (High Performance)

UMICP (Universal Messaging and Inter-process Communication Protocol) provides significant performance benefits:

Automatic Compression: GZIP, DEFLATE, or LZ4 compression for large payloads
Built-in Encryption: Optional encryption for secure communication
Lower Latency: Optimized binary protocol with checksums
Request Validation: Automatic request/response validation

Using Connection String

const client = new VectorizerClient({
  connectionString: 'umicp://localhost:15003',
  apiKey: 'your-api-key'
});

Using Explicit Configuration

const client = new VectorizerClient({
  protocol: 'umicp',
  apiKey: 'your-api-key',
  umicp: {
    host: 'localhost',
    port: 15003,
    compression: 'gzip',     // 'gzip', 'deflate', 'lz4', or 'none'
    encryption: true,         // Enable encryption
    priority: 'normal'        // 'low', 'normal', 'high'
  }
});

When to Use UMICP

Use UMICP when:

Large Payloads: Inserting or searching large batches of vectors
High Throughput: Need maximum performance for production workloads
Secure Communication: Require encryption without TLS overhead
Low Latency: Need minimal protocol overhead

Use HTTP when:

Development: Quick testing and debugging
Firewall Restrictions: Only HTTP/HTTPS allowed
Simple Deployments: No need for custom protocol setup

Protocol Comparison

Feature	HTTP/HTTPS	UMICP
Compression	Manual (gzip header)	Automatic (GZIP/DEFLATE/LZ4)
Encryption	TLS required	Built-in optional
Latency	Standard	Lower
Firewall	Widely supported	May require configuration
Debugging	Easy (browser tools)	Requires UMICP tools

API Reference

Collection Management

// List collections
const collections = await client.listCollections();

// Get collection info
const info = await client.getCollection('documents');

// Create collection
const collection = await client.createCollection({
  name: 'documents',
  dimension: 768,
  similarity_metric: 'cosine',
  description: 'Document embeddings'
});

// Update collection
const updated = await client.updateCollection('documents', {
  description: 'Updated description'
});

// Delete collection
await client.deleteCollection('documents');

Vector Operations

// Insert vectors
const vectors = [{
  data: [0.1, 0.2, 0.3],
  metadata: { source: 'doc1.pdf' }
}];
await client.insertVectors('documents', vectors);

// Get vector
const vector = await client.getVector('documents', 'vector-id');

// Update vector
const updated = await client.updateVector('documents', 'vector-id', {
  metadata: { updated: true }
});

// Delete vector
await client.deleteVector('documents', 'vector-id');

// Delete multiple vectors
await client.deleteVectors('documents', ['id1', 'id2', 'id3']);

Search Operations

// Vector similarity search
const results = await client.searchVectors('documents', {
  query_vector: [0.1, 0.2, 0.3],
  limit: 10,
  threshold: 0.8,
  include_metadata: true
});

// Text semantic search
const textResults = await client.searchText('documents', {
  query: 'machine learning',
  limit: 10,
  threshold: 0.8,
  include_metadata: true,
  model: 'bert-base'
});

Embedding Operations

// Generate embeddings
const embedding = await client.embedText({
  text: 'machine learning algorithms',
  model: 'bert-base',
  parameters: {
    max_length: 512,
    normalize: true
  }
});

Error Handling

import {
  VectorizerError,
  AuthenticationError,
  CollectionNotFoundError,
  ValidationError,
  NetworkError,
  ServerError
} from '@hivellm/vectorizer-client';

try {
  await client.createCollection({
    name: 'documents',
    dimension: 768
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Authentication failed:', error.message);
  } else if (error instanceof ValidationError) {
    console.error('Validation error:', error.message);
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
  } else {
    console.error('Unknown error:', error.message);
  }
}

Types

// Vector types
interface Vector {
  id: string;
  data: number[];
  metadata?: Record<string, unknown>;
}

// Collection types
interface Collection {
  name: string;
  dimension: number;
  similarity_metric: 'cosine' | 'euclidean' | 'dot_product';
  description?: string;
  created_at?: Date;
  updated_at?: Date;
}

// Search result types
interface SearchResult {
  id: string;
  score: number;
  data: number[];
  metadata?: Record<string, unknown>;
}

// Client configuration
interface VectorizerClientConfig {
  baseURL?: string;
  wsURL?: string;
  apiKey?: string;
  timeout?: number;
  headers?: Record<string, string>;
  logger?: LoggerConfig;
}

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run build:watch

# Test
npm test

# Test with coverage
npm run test:coverage

# Lint
npm run lint

# Lint and fix
npm run lint:fix

License

MIT License - see LICENSE for details.