hashub-vector
Version:
Official TypeScript/JavaScript SDK for Hashub Vector API - High-quality multilingual text embeddings with Turkish excellence
427 lines (423 loc) • 11.6 kB
TypeScript
/**
* API Configuration for Hashub Vector client
*/
interface HashubVectorConfig {
/** API key for authentication */
apiKey: string;
/** Base URL for the API (optional) */
baseUrl?: string;
/** Request timeout in milliseconds (default: 30000) */
timeout?: number;
/** Maximum number of retry attempts (default: 3) */
maxRetries?: number;
/** Custom headers to include in requests */
headers?: Record<string, string>;
}
/**
* Available embedding models
*/
type EmbeddingModel = 'gte_base' | 'nomic_base' | 'e5_base' | 'mpnet_base' | 'e5_small' | 'minilm_base';
/**
* Single vectorization request
*/
interface VectorizeRequest {
/** Text to vectorize */
text: string;
/** Model to use for embedding */
model?: EmbeddingModel;
/** Maximum chunk size for long texts */
chunkSize?: number;
/** Overlap ratio between chunks (0-1) */
chunkOverlap?: number;
}
/**
* Batch vectorization request
*/
interface VectorizeBatchRequest {
/** Array of texts to vectorize */
texts: string[];
/** Model to use for embedding */
model?: EmbeddingModel;
/** Maximum chunk size for long texts */
chunkSize?: number;
/** Overlap ratio between chunks (0-1) */
chunkOverlap?: number;
}
/**
* Single vectorization response
*/
interface VectorizeResponse {
/** Generated embedding vector */
vector: number[];
/** Dimension of the vector */
dimension: number;
/** Model used for embedding */
model: string;
/** Number of tokens processed */
tokens: number;
/** Number of chunks (for long texts) */
chunkCount?: number;
}
/**
* Batch vectorization response
*/
interface VectorizeBatchResponse {
/** Array of embedding vectors */
vectors: number[][];
/** Dimension of vectors */
dimension: number;
/** Model used for embedding */
model: string;
/** Total number of texts processed */
count: number;
/** Total number of tokens processed */
totalTokens: number;
}
/**
* Model information
*/
interface ModelInfo {
/** Model identifier */
alias: string;
/** Human-readable name */
name: string;
/** Model description */
description: string;
/** Vector dimension */
dimension: number;
/** Maximum tokens per request */
maxTokens: number;
/** Price per 1M tokens in USD */
pricePerMTokens: number;
/** Turkish language support level (1-5) */
turkishSupport: number;
}
/**
* Usage statistics
*/
interface UsageStats {
/** Total tokens used */
tokensUsed: number;
/** Token limit */
tokensLimit: number;
/** Usage percentage */
tokensPercentageUsed: number;
/** Remaining tokens */
tokensRemaining: number;
}
/**
* Daily usage breakdown
*/
interface DailyUsage {
/** Date in YYYY-MM-DD format */
date: string;
/** Tokens used on this date */
tokensUsed: number;
/** Number of requests */
requestCount: number;
/** Models used with token counts */
modelUsage: Record<string, number>;
}
/**
* Detailed usage response
*/
interface UsageResponse {
/** Current usage statistics */
usage: UsageStats;
/** Daily usage breakdown */
dailyUsage: DailyUsage[];
/** Date range of the report */
period: {
from: string;
to: string;
};
}
/**
* API Error response
*/
interface ApiError {
/** Error message */
message: string;
/** Error code */
code?: string;
/** HTTP status code */
status?: number;
/** Additional error details */
details?: Record<string, unknown>;
}
/**
* Similarity calculation request
*/
interface SimilarityRequest {
/** First text */
text1: string;
/** Second text */
text2: string;
/** Model to use for embeddings */
model?: EmbeddingModel;
}
/**
* Similarity calculation response
*/
interface SimilarityResponse {
/** Cosine similarity score (0-1) */
similarity: number;
/** Model used */
model: string;
}
/**
* OpenAI-compatible embedding request
*/
interface OpenAIEmbeddingRequest {
/** Input text(s) */
input: string | string[];
/** Model to use */
model: EmbeddingModel;
/** User identifier (optional) */
user?: string;
}
/**
* OpenAI-compatible embedding response
*/
interface OpenAIEmbeddingResponse {
/** Response object type */
object: 'list';
/** Embedding data */
data: Array<{
object: 'embedding';
embedding: number[];
index: number;
}>;
/** Model used */
model: string;
/** Usage statistics */
usage: {
prompt_tokens: number;
total_tokens: number;
};
}
/**
* Hashub Vector SDK Client for TypeScript/JavaScript
*
* Provides high-quality multilingual text embeddings with exceptional Turkish language support.
*
* @example
* ```typescript
* import { HashubVector } from 'hashub-vector';
*
* const client = new HashubVector({
* apiKey: 'your-api-key'
* });
*
* // Single embedding
* const response = await client.vectorize({
* text: 'Merhaba dünya!',
* model: 'gte_base'
* });
*
* console.log(response.vector); // [0.1, -0.2, ...]
* ```
*/
declare class HashubVector {
private readonly client;
private readonly config;
/**
* Create a new Hashub Vector client
*
* @param config - Configuration options
*/
constructor(config: HashubVectorConfig);
/**
* Generate embedding for a single text
*
* @param request - Vectorization request
* @returns Promise<VectorizeResponse>
*
* @example
* ```typescript
* const response = await client.vectorize({
* text: 'Artificial intelligence is transforming the world',
* model: 'gte_base'
* });
*
* console.log(`Vector dimension: ${response.dimension}`);
* console.log(`Tokens used: ${response.tokens}`);
* ```
*/
vectorize(request: VectorizeRequest): Promise<VectorizeResponse>;
/**
* Generate embeddings for multiple texts (batch processing)
*
* @param request - Batch vectorization request
* @returns Promise<VectorizeBatchResponse>
*
* @example
* ```typescript
* const response = await client.vectorizeBatch({
* texts: [
* 'Hello world',
* 'Merhaba dünya',
* 'Bonjour monde'
* ],
* model: 'gte_base'
* });
*
* console.log(`Processed ${response.count} texts`);
* console.log(`Total tokens: ${response.totalTokens}`);
* ```
*/
vectorizeBatch(request: VectorizeBatchRequest): Promise<VectorizeBatchResponse>;
/**
* Calculate cosine similarity between two texts
*
* @param request - Similarity calculation request
* @returns Promise<SimilarityResponse>
*
* @example
* ```typescript
* const response = await client.similarity({
* text1: 'Machine learning',
* text2: 'Makine öğrenmesi',
* model: 'gte_base'
* });
*
* console.log(`Similarity: ${response.similarity.toFixed(3)}`);
* ```
*/
similarity(request: SimilarityRequest): Promise<SimilarityResponse>;
/**
* Get information about available models
*
* @returns Promise<ModelInfo[]>
*
* @example
* ```typescript
* const models = await client.getModels();
*
* for (const model of models) {
* console.log(`${model.alias}: ${model.description}`);
* console.log(` Dimension: ${model.dimension}`);
* console.log(` Max tokens: ${model.maxTokens}`);
* console.log(` Turkish support: ${model.turkishSupport}/5`);
* }
* ```
*/
getModels(): Promise<ModelInfo[]>;
/**
* Get current usage statistics
*
* @returns Promise<UsageStats>
*
* @example
* ```typescript
* const usage = await client.getUsage();
*
* console.log(`Tokens used: ${usage.tokensUsed.toLocaleString()}`);
* console.log(`Usage: ${usage.tokensPercentageUsed.toFixed(1)}%`);
* console.log(`Remaining: ${usage.tokensRemaining.toLocaleString()}`);
* ```
*/
getUsage(): Promise<UsageStats>;
/**
* Get detailed usage statistics with daily breakdown
*
* @param from - Start date (YYYY-MM-DD format, optional)
* @param to - End date (YYYY-MM-DD format, optional)
* @returns Promise<UsageResponse>
*
* @example
* ```typescript
* // Get last 7 days usage
* const usage = await client.getDetailedUsage('2025-08-01', '2025-08-07');
*
* console.log(`Period: ${usage.period.from} to ${usage.period.to}`);
* console.log(`Total tokens: ${usage.usage.tokensUsed}`);
*
* for (const day of usage.dailyUsage) {
* console.log(`${day.date}: ${day.tokensUsed} tokens, ${day.requestCount} requests`);
* }
* ```
*/
getDetailedUsage(from?: string, to?: string): Promise<UsageResponse>;
/**
* OpenAI-compatible embedding endpoint
*
* @param request - OpenAI-style embedding request
* @returns Promise<OpenAIEmbeddingResponse>
*
* @example
* ```typescript
* // Drop-in replacement for OpenAI
* const response = await client.createEmbedding({
* input: 'Your text here',
* model: 'e5_base'
* });
*
* const embedding = response.data[0].embedding;
* console.log(`Generated ${embedding.length}D embedding`);
* ```
*/
createEmbedding(request: OpenAIEmbeddingRequest): Promise<OpenAIEmbeddingResponse>;
/**
* Make HTTP request with error handling and retries
*/
private makeRequest;
/**
* Handle axios errors and convert to appropriate SDK errors
*/
private handleError;
}
/**
* Base error class for Hashub Vector SDK
*/
declare class HashubVectorError extends Error {
readonly code?: string | undefined;
readonly status?: number | undefined;
readonly details?: Record<string, unknown> | undefined;
constructor(message: string, code?: string, status?: number, details?: Record<string, unknown>);
}
/**
* Authentication error (401)
*/
declare class AuthenticationError extends HashubVectorError {
constructor(message?: string);
}
/**
* Rate limit error (429)
*/
declare class RateLimitError extends HashubVectorError {
readonly retryAfter?: number | undefined;
constructor(message?: string, retryAfter?: number);
}
/**
* Quota exceeded error (402)
*/
declare class QuotaExceededError extends HashubVectorError {
constructor(message?: string);
}
/**
* Validation error (400)
*/
declare class ValidationError extends HashubVectorError {
constructor(message?: string);
}
/**
* Server error (500)
*/
declare class ServerError extends HashubVectorError {
constructor(message?: string);
}
/**
* Network error (connection issues)
*/
declare class NetworkError extends HashubVectorError {
constructor(message?: string);
}
/**
* Timeout error
*/
declare class TimeoutError extends HashubVectorError {
constructor(message?: string);
}
export { AuthenticationError, HashubVector, HashubVectorError, NetworkError, QuotaExceededError, RateLimitError, ServerError, TimeoutError, ValidationError, HashubVector as default };
export type { ApiError, DailyUsage, EmbeddingModel, HashubVectorConfig, ModelInfo, OpenAIEmbeddingRequest, OpenAIEmbeddingResponse, SimilarityRequest, SimilarityResponse, UsageResponse, UsageStats, VectorizeBatchRequest, VectorizeBatchResponse, VectorizeRequest, VectorizeResponse };