@inferedge/moss-clustering

TypeScript SDK for asynchronous topic clustering with Moss

Installation

npm install @inferedge/moss-clustering

Quick Start

import { MossClusteringClient } from '@inferedge/moss-clustering';
import * as dotenv from 'dotenv';

dotenv.config();

const clustering = new MossClusteringClient({
  projectId: process.env.MOSS_PROJECT_ID!,
  projectKey: process.env.MOSS_PROJECT_KEY!
});

const jobResponse = await clustering.startClusterGeneration(5, {
  indexNames: ['support-tickets', 'billing-2024']
});

console.log('Job started:', jobResponse.jobId);

const { job } = await clustering.getJobStatus(jobResponse.jobId);
if (job.status === 'completed' && job.result) {
  console.log('Processed indexes:', job.result.processedIndexes);
  console.log('Cluster count:', job.result.clusters.length);
}

Job Lifecycle

1. startClusterGeneration(k, { indexNames })
2. getJobStatus(jobId) to poll progress (phases include fetching documents, preprocessing, embeddings, k-means clustering, saving results).
3. waitForJobCompletion(jobId) or generateClusters() for a blocking helper.

Job status values: queued, processing, completed, failed.

Document Clustering Within an Index

Use the synchronous helpers to cluster individual documents stored in a single Moss index and retrieve cached results later on.

const documentClusters = await clustering.clusterIndexDocuments('support-tickets', 4, {
  maxDocuments: 500,
  sampleStrategy: 'random',
  representativeDocumentCount: 3
});

console.log(documentClusters.documentsProcessed);
console.log(documentClusters.progress.map(step => `${step.phase}: ${step.progress}%`));

const latestSnapshot = await clustering.getIndexDocumentClusters('support-tickets');

if (!latestSnapshot) {
  console.log('Run clusterIndexDocuments first to generate document clusters.');
} else {
  console.log(latestSnapshot.clusters[0]?.label);
}

clusterIndexDocuments invokes the synchronous API and returns end-to-end progress updates. getIndexDocumentClusters returns the most recent clustering snapshot or null if the index has not been processed yet.

📄 Try the dedicated walkthrough in examples/document-cluster-example.ts for a complete runnable script.

Types (excerpt)

interface ClusteringResult {
  clusters: ClusterInfo[];
  totalIndexes: number;
  processedIndexes: string[];
  indexNames?: string[];
  createdAt: string;
  k: number;
}

interface ClusterInfo {
  clusterId: number;
  label: string;
  description: string;
  indexCount: number;
  indexes: string[];
}

interface GenerateClusterJobResponse {
  jobId: string;
  status: 'queued' | 'processing' | 'completed' | 'failed';
  message: string;
  indexNames?: string[];
}

Error Handling

import { isClusteringError } from '@inferedge/moss-clustering';

try {
  await clustering.generateClusters(5);
} catch (error) {
  if (isClusteringError(error)) {
    console.error('Clustering error code:', error.code);
  }
}

Health Checks

const health = await clustering.getServiceHealth();
console.log('Service status:', health.status);

License

PolyForm Shield License 1.0.0 © InferEdge Inc. See LICENSE for details.